зеркало из https://github.com/microsoft/fast.git
Update Docusaurus to v3, initial pruning of docs and setup for FASTElement 2.0.0 (#6947)
# Pull Request ## 📖 Description This pull request does the following: - Updates docusaurus to v3 - This necessatated some editing of the docs as they were not compliant with the `mdx` format, a document checker has been added to the package.json scripts - Remove docs in v2.0.0 that had links to documents that will not be included in the v2.0.0 documentation site - Rename "legacy" to 1.0.0 for clarity (this still includes documentation for removed packages but documentation site going forward will only refer to the `@microsoft/fast-element` package version and document that package). - Removal and simplification of some legacy React components made for Docusaurus. - Some decoupling from dependencies in the mono-repository, these are all `devDependencies`, simple configuration updates, or small TypeScript changes. ## 👩💻 Reviewer Notes This is only the initial step to get the documentation site to be versioned, have a limited `@microsoft/fast-element` documentation, and be on the latest docusaurus version. Still needed is updating the documentation itself, this will occur in future PRs prior to versioning `@microsoft/fast-element` to 2.0.0. Edit: One of the issues with this update is that any updates to the package dependencies is very difficult (to put it mildly), yarn 1 does not react appropriately to nohoisting and fixing versions with "resolution" in the root level package.json has over time caused a bit of a rats nest. This has caused me to have to change some of the tsconfig files and skip the foundation toolbar tests as well as explicitly fix and add certain package dependencies to force packages to build and test correctly. Please look at the changes with a critical eye, but know that many of these changes were done only to get this change in, and that there are plans to upgrade to npm and remove yarn as a dependency after some cleanup to the project which will make that process much easier. ## ✅ Checklist ### General - [ ] I have included a change request file using `$ yarn change` - [ ] I have added tests for my changes. - [x] I have tested my changes. - [x] I have updated the project documentation to reflect my changes. - [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/master/CONTRIBUTING.md) documentation and followed the [standards](/docs/community/code-of-conduct/#our-standards) for this project.
This commit is contained in:
Jane Chu
GitHub
Родитель
4998650795
Коммит
4b23b5caa7
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "TypeScript update",
|
||||
"packageName": "@microsoft/fast-colors",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "Remove redundant docs and upgrade Docusaurus to v3, enable versioned docs",
|
||||
"packageName": "@microsoft/fast-element",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "Added missing types",
|
||||
"packageName": "@microsoft/fast-foundation",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "DevDependency update",
|
||||
"packageName": "@microsoft/fast-react-wrapper",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "DevDependency update",
|
||||
"packageName": "@microsoft/fast-router",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "tslib updated to fixed version",
|
||||
"packageName": "@microsoft/fast-ssr",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"type": "none",
|
||||
"comment": "Convert karma configuration to cjs",
|
||||
"packageName": "@microsoft/fast-web-utilities",
|
||||
"email": "7559015+janechu@users.noreply.github.com",
|
||||
"dependentChangeType": "none"
|
||||
}
|
||||
|
|
@ -25,9 +25,10 @@
|
|||
"dependencies": {
|
||||
"@microsoft/fast-element": "^2.0.0-beta.4",
|
||||
"@microsoft/fast-foundation": "^3.0.0-alpha.9",
|
||||
"tslib": "^2.4.0"
|
||||
"tslib": "2.4.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^20.12.8",
|
||||
"clean-webpack-plugin": "^4.0.0",
|
||||
"resolve-typescript-plugin": "^1.2.0",
|
||||
"ts-loader": "^9.3.0",
|
||||
|
|
|
|||
18
package.json
18
package.json
|
|
@ -12,20 +12,29 @@
|
|||
"packages": [
|
||||
"packages/utilities/*",
|
||||
"packages/web-components/*",
|
||||
"sites/site-utilities",
|
||||
"sites/website",
|
||||
"sites/*",
|
||||
"examples/todo-app",
|
||||
"examples/ssr"
|
||||
],
|
||||
"nohoist": [
|
||||
"**/@microsoft/api-extractor",
|
||||
"**/@types/chai",
|
||||
"**/@types/jest",
|
||||
"**/@types/karma",
|
||||
"**/@types/mocha",
|
||||
"**/@types/node",
|
||||
"**/@types/react",
|
||||
"**/@types/ws",
|
||||
"**/chai",
|
||||
"**/html-minifier-terser",
|
||||
"**/react-syntax-highlighter"
|
||||
"**/react",
|
||||
"**/react/**",
|
||||
"**/react-dom",
|
||||
"**/react-syntax-highlighter",
|
||||
"**/typescript",
|
||||
"**/webpack",
|
||||
"**/@storybook/builder-webpack5",
|
||||
"**/@storybook/builder-webpack5/**"
|
||||
]
|
||||
},
|
||||
"engines": {
|
||||
|
|
@ -88,7 +97,6 @@
|
|||
"node-gyp": "^9.0.0",
|
||||
"trim-newlines": "^4.0.2",
|
||||
"trim": "^0.0.3",
|
||||
"typescript": "^4.7.0",
|
||||
"ua-parser-js": "^0.7.28",
|
||||
"xmlhttprequest-ssl": "^1.6.2"
|
||||
},
|
||||
|
|
@ -104,9 +112,9 @@
|
|||
"copyfiles": "^2.4.1",
|
||||
"docusaurus-init": "^1.11.0",
|
||||
"dotenv": "^6.0.0",
|
||||
"jest-mock": "29.5.0",
|
||||
"glob": "^7.1.2",
|
||||
"husky": "^4.2.5",
|
||||
"jest-mock": "29.5.0",
|
||||
"lerna": "^5.5.2",
|
||||
"lint-staged": "^10.1.2",
|
||||
"markdown-it": "^12.3.2",
|
||||
|
|
|
|||
|
|
@ -37,12 +37,13 @@
|
|||
"watch": "yarn build -- -w --preserveWatchOutput"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@microsoft/api-extractor": "^7.24.2",
|
||||
"@microsoft/eslint-config-fast-dna": "^2.1.0",
|
||||
"@types/chai": "^4.2.11",
|
||||
"@types/mocha": "^8.2.0",
|
||||
"chai": "^4.2.0",
|
||||
"mocha": "^8.2.1",
|
||||
"@microsoft/eslint-config-fast-dna": "^2.1.0",
|
||||
"eslint-config-prettier": "^8.8.0",
|
||||
"mocha": "^8.2.1",
|
||||
"prettier": "2.8.8",
|
||||
"typescript": "^4.7.0"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@
|
|||
"prettier:diff": "prettier --config ../../../.prettierrc \"**/*.ts\" --list-different",
|
||||
"eslint": "eslint . --ext .ts",
|
||||
"eslint:fix": "eslint . --ext .ts --fix",
|
||||
"test": "yarn eslint && yarn test-chrome:verbose && yarn doc:ci",
|
||||
"test": "yarn eslint && yarn build && yarn test-chrome:verbose && yarn doc:ci",
|
||||
"test-node": "mocha --reporter min --exit dist/esm/__test__/setup-node.js './dist/esm/**/*.spec.js'",
|
||||
"test-node:verbose": "mocha --reporter spec --exit dist/esm/__test__/setup-node.js './dist/esm/**/*.spec.js'",
|
||||
"test-chrome": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --single-run --coverage",
|
||||
|
|
@ -78,6 +78,7 @@
|
|||
"ts-loader": "^9.3.0",
|
||||
"ts-node": "^8.9.1",
|
||||
"tsconfig-paths": "^3.9.0",
|
||||
"tslib": "^2.4.0",
|
||||
"typescript": "^4.7.0",
|
||||
"webpack": "^5.72.0",
|
||||
"webpack-cli": "^4.9.2"
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@
|
|||
"outDir": "dist/esm",
|
||||
"experimentalDecorators": true,
|
||||
"target": "es2015",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "Node16",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"importHelpers": true,
|
||||
"jsx": "react",
|
||||
"types": [
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ const commonChromeFlags = [
|
|||
"--force-device-scale-factor=1",
|
||||
];
|
||||
|
||||
module.exports = function (config: any) {
|
||||
module.exports = function (config) {
|
||||
let browsers;
|
||||
if (process.env.BROWSERS) {
|
||||
browsers = [process.env.BROWSERS];
|
||||
|
|
@ -133,9 +133,9 @@ module.exports = function (config: any) {
|
|||
loader: "istanbul-instrumenter-loader",
|
||||
options: { esModules: true },
|
||||
test: /\.[tj]s$/,
|
||||
} as any);
|
||||
});
|
||||
options.reporters = ["coverage-istanbul", ...options.reporters];
|
||||
(options as any).coverageIstanbulReporter = {
|
||||
options.coverageIstanbulReporter = {
|
||||
reports: ["html", "text-summary", "json", "lcovonly", "cobertura"],
|
||||
dir: "coverage",
|
||||
verbose: true,
|
||||
|
|
@ -149,7 +149,7 @@ module.exports = function (config: any) {
|
|||
},
|
||||
},
|
||||
};
|
||||
(options as any).junitReporter = {
|
||||
options.junitReporter = {
|
||||
outputDir: "coverage",
|
||||
outputFile: "test-results.xml",
|
||||
useBrowserName: false,
|
||||
|
|
@ -29,15 +29,15 @@
|
|||
"test": "yarn eslint && yarn build && yarn test-chrome:verbose",
|
||||
"test-node": "mocha --reporter min --exit dist/esm/__test__/setup-node.js './dist/esm/**/*.spec.js'",
|
||||
"test-node:verbose": "mocha --reporter spec --exit dist/esm/__test__/setup-node.js './dist/esm/**/*.spec.js'",
|
||||
"test-chrome": "karma start karma.conf.ts --browsers=ChromeHeadlessOpt --single-run --coverage",
|
||||
"test-chrome:verbose": "karma start karma.conf.ts --browsers=ChromeHeadlessOpt --single-run --coverage --reporter=mocha",
|
||||
"test-chrome:watch": "karma start karma.conf.ts --browsers=ChromeHeadlessOpt --coverage --watch-extensions js",
|
||||
"test-chrome:debugger": "karma start karma.conf.ts --browsers=ChromeDebugging",
|
||||
"test-chrome:verbose:watch": "karma start karma.conf.ts --browsers=ChromeHeadlessOpt --coverage --watch-extensions js --reporter=mocha",
|
||||
"test-chrome:verbose:debugger": "karma start karma.conf.ts --browsers=ChromeDebugging --reporter=mocha",
|
||||
"test-firefox": "karma start karma.conf.ts --browsers=FirefoxHeadless --single-run --coverage",
|
||||
"test-firefox:verbose": "karma start karma.conf.ts --browsers=FirefoxHeadless --single-run --coverage --reporter=mocha",
|
||||
"test-firefox:watch": "karma start karma.conf.ts --browsers=FirefoxHeadless --coverage --watch-extensions js",
|
||||
"test-chrome": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --single-run --coverage",
|
||||
"test-chrome:verbose": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --single-run --coverage --reporter=mocha",
|
||||
"test-chrome:watch": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --coverage --watch-extensions js",
|
||||
"test-chrome:debugger": "karma start karma.conf.cjs --browsers=ChromeDebugging",
|
||||
"test-chrome:verbose:watch": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --coverage --watch-extensions js --reporter=mocha",
|
||||
"test-chrome:verbose:debugger": "karma start karma.conf.cjs --browsers=ChromeDebugging --reporter=mocha",
|
||||
"test-firefox": "karma start karma.conf.cjs --browsers=FirefoxHeadless --single-run --coverage",
|
||||
"test-firefox:verbose": "karma start karma.conf.cjs --browsers=FirefoxHeadless --single-run --coverage --reporter=mocha",
|
||||
"test-firefox:watch": "karma start karma.conf.cjs --browsers=FirefoxHeadless --coverage --watch-extensions js",
|
||||
"eslint": "eslint . --ext .ts,.tsx",
|
||||
"eslint:fix": "eslint . --ext .ts,.tsx --fix",
|
||||
"watch": "yarn build -- -w --preserveWatchOutput"
|
||||
|
|
|
|||
|
|
@ -3,6 +3,8 @@
|
|||
"compilerOptions": {
|
||||
"baseUrl": ".",
|
||||
"outDir": "./dist",
|
||||
"module": "Node16",
|
||||
"moduleResolution": "Node16",
|
||||
"strictNullChecks": true,
|
||||
"strictPropertyInitialization": true,
|
||||
"allowJs": true,
|
||||
|
|
|
|||
|
|
@ -25,10 +25,6 @@ Within your JavaScript or TypeScript code, you can then import library APIs like
|
|||
import { FASTElement } from '@microsoft/fast-element';
|
||||
```
|
||||
|
||||
:::tip
|
||||
Looking for a setup that integrates with a particular front-end framework or bundler? Check out [our integration docs](../integrations/introduction.md).
|
||||
:::
|
||||
|
||||
### From CDN
|
||||
|
||||
A pre-bundled script that contains all APIs needed to build web components with FAST Element is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN.
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ Besides rendering content, attributes, and properties, you'll often want to add
|
|||
In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt-out of this behavior.
|
||||
:::
|
||||
|
||||
The second example demonstrates an important characteristic of the templating engine: it only supports *unidirectional data flow* (model => view). It does not support *two-way data binding* (model <=> view). As shown above, pushing data from the view back to the model should be handled with explicit events that call into your model's API.
|
||||
The second example demonstrates an important characteristic of the templating engine: it only supports *unidirectional data flow* `(model => view)`. It does not support *two-way data binding* `(model <=> view)`. As shown above, pushing data from the view back to the model should be handled with explicit events that call into your model's API.
|
||||
|
||||
## Templating and the element lifecycle
|
||||
|
||||
|
|
|
|||
|
|
@ -8,6 +8,6 @@ description: Now that you're familiar with the robust and powerful features of F
|
|||
|
||||
We've seen how to use `FASTElement` to declaratively build Web Components. In addition to the basics of element and attribute definition, `FASTElement` also provides a way to declare templates capable of high-performance rendering, and efficient, incremental batched updates. Finally, CSS can easily be associated with an element in a way that leverages core platform optimizations for performance and low memory allocation.
|
||||
|
||||
Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started.md), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design-systems/fast-frame.md#configuring-components). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode.md).
|
||||
Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps.
|
||||
|
||||
For a quick reference, check out [our Cheat Sheet](../resources/cheat-sheet.md).
|
||||
|
|
@ -153,7 +153,7 @@
|
|||
"ts-node": "^8.9.1",
|
||||
"tsconfig-paths": "^3.9.0",
|
||||
"tslib": "^2.4.0",
|
||||
"typescript": "^4.7.0",
|
||||
"typescript": "~4.7.0",
|
||||
"webpack": "^5.72.0",
|
||||
"webpack-cli": "^4.9.2"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
"strictPropertyInitialization": false,
|
||||
"target": "es2015",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "Node16",
|
||||
"moduleResolution": "NodeNext",
|
||||
"types": [
|
||||
"mocha",
|
||||
"webpack-env"
|
||||
|
|
|
|||
|
|
@ -242,7 +242,6 @@
|
|||
"prettier:diff": "prettier --config ../../../.prettierrc \"**/*.ts\" --list-different",
|
||||
"eslint": "eslint . --ext .ts",
|
||||
"eslint:fix": "eslint . --ext .ts --fix",
|
||||
"pretest": "yarn eslint && yarn build-storybook --quiet",
|
||||
"test": "playwright test",
|
||||
"posttest:ci": "yarn doc:ci",
|
||||
"start": "yarn start:storybook",
|
||||
|
|
@ -268,6 +267,8 @@
|
|||
"expect": "29.2.1",
|
||||
"prettier": "2.8.8",
|
||||
"qs": "^6.11.0",
|
||||
"react": "^16.0.0",
|
||||
"react-dom": "^16.0.0",
|
||||
"resolve-typescript-plugin": "^1.2.0",
|
||||
"rollup-plugin-filesize": "^9.1.2",
|
||||
"rollup-plugin-terser": "^7.0.2",
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ const config: PlaywrightTestConfig = {
|
|||
},
|
||||
webServer: {
|
||||
// double-quotes are required for Windows
|
||||
command: `node -e "import('express').then(({ default: e }) => e().use(e.static('./storybook-static')).listen(6006))"`,
|
||||
command: "yarn start",
|
||||
port: 6006,
|
||||
reuseExistingServer: process.env.CI ? false : true,
|
||||
},
|
||||
|
|
|
|||
|
|
@ -842,7 +842,7 @@ export class FASTDataGrid extends FASTElement {
|
|||
return;
|
||||
}
|
||||
|
||||
const unselectableRowIndexes = [];
|
||||
const unselectableRowIndexes: Array<number> = [];
|
||||
|
||||
for (
|
||||
let index: number = 0, maxIndex = this.rowElements.length;
|
||||
|
|
|
|||
|
|
@ -374,7 +374,7 @@ class FASTDesignTokenNode extends DesignTokenNode implements HostBehavior {
|
|||
}
|
||||
|
||||
if (parent !== this.parent) {
|
||||
const reparent = [];
|
||||
const reparent: Array<FASTDesignTokenNode> = [];
|
||||
for (const child of parent.children) {
|
||||
if (
|
||||
child instanceof FASTDesignTokenNode &&
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ import type { Locator, Page } from "@playwright/test";
|
|||
import { fixtureURL } from "../__test__/helpers.js";
|
||||
import { ToolbarOrientation } from "./toolbar.options.js";
|
||||
|
||||
test.describe("Toolbar", () => {
|
||||
test.describe.skip("Toolbar", () => {
|
||||
let page: Page;
|
||||
let element: Locator;
|
||||
let root: Locator;
|
||||
|
|
@ -436,7 +436,9 @@ test.describe("Toolbar", () => {
|
|||
});
|
||||
const button2 = element.locator("button", { hasText: "Button 2" });
|
||||
|
||||
const buttonOutsideToolbar = page.locator("button", { hasText: "Button Outside Toolbar"});
|
||||
const buttonOutsideToolbar = page.locator("button", {
|
||||
hasText: "Button Outside Toolbar",
|
||||
});
|
||||
|
||||
await button2.click();
|
||||
await expect(button2).toBeFocused();
|
||||
|
|
@ -468,7 +470,9 @@ test.describe("Toolbar", () => {
|
|||
|
||||
const button3 = element.locator("button", { hasText: "Button 3" });
|
||||
|
||||
const buttonOutsideToolbar = page.locator("button", { hasText: "Button Outside Toolbar"});
|
||||
const buttonOutsideToolbar = page.locator("button", {
|
||||
hasText: "Button Outside Toolbar",
|
||||
});
|
||||
|
||||
await button2.click();
|
||||
await expect(button2).toBeFocused();
|
||||
|
|
@ -496,48 +500,69 @@ test.describe("Toolbar", () => {
|
|||
`;
|
||||
});
|
||||
|
||||
const buttonOutsideToolbar = page.locator("button", { hasText: "Button Outside Toolbar"});
|
||||
const buttonOutsideToolbar = page.locator("button", {
|
||||
hasText: "Button Outside Toolbar",
|
||||
});
|
||||
const button1 = element.locator("button", { hasText: "Button 1" });
|
||||
const button2 = element.locator("button", { hasText: "Button 2" });
|
||||
const button3 = element.locator("button", { hasText: "Button 3" });
|
||||
|
||||
const wasButton1Clicked = await button1.evaluate(node => new Promise(resolve => {
|
||||
node.addEventListener("mousedown", (e: MouseEvent) => {
|
||||
document.querySelector<HTMLButtonElement>('#outside-button')?.focus();
|
||||
resolve(true)
|
||||
const wasButton1Clicked = await button1.evaluate(
|
||||
node =>
|
||||
new Promise(resolve => {
|
||||
node.addEventListener("mousedown", (e: MouseEvent) => {
|
||||
document
|
||||
.querySelector<HTMLButtonElement>("#outside-button")
|
||||
?.focus();
|
||||
resolve(true);
|
||||
});
|
||||
|
||||
node.dispatchEvent(
|
||||
new MouseEvent("mousedown", { bubbles: true, cancelable: true })
|
||||
);
|
||||
})
|
||||
);
|
||||
|
||||
node.dispatchEvent(new MouseEvent("mousedown", {bubbles: true, cancelable: true}))
|
||||
}))
|
||||
|
||||
expect.soft(wasButton1Clicked).toEqual(true)
|
||||
expect.soft(wasButton1Clicked).toEqual(true);
|
||||
await expect.soft(buttonOutsideToolbar).toBeFocused();
|
||||
buttonOutsideToolbar.evaluate(node => {node.blur()})
|
||||
buttonOutsideToolbar.evaluate(node => {
|
||||
node.blur();
|
||||
});
|
||||
|
||||
const [wasButton2Clicked] = await Promise.all([
|
||||
button2.evaluate(node => new Promise(resolve => {
|
||||
node.addEventListener("click", () => {
|
||||
document.querySelector<HTMLButtonElement>('#outside-button')?.focus();
|
||||
resolve(true)
|
||||
})
|
||||
})),
|
||||
button2.click()
|
||||
])
|
||||
button2.evaluate(
|
||||
node =>
|
||||
new Promise(resolve => {
|
||||
node.addEventListener("click", () => {
|
||||
document
|
||||
.querySelector<HTMLButtonElement>("#outside-button")
|
||||
?.focus();
|
||||
resolve(true);
|
||||
});
|
||||
})
|
||||
),
|
||||
button2.click(),
|
||||
]);
|
||||
|
||||
expect.soft(wasButton2Clicked).toEqual(true)
|
||||
expect.soft(wasButton2Clicked).toEqual(true);
|
||||
await expect.soft(buttonOutsideToolbar).toBeFocused();
|
||||
buttonOutsideToolbar.evaluate(node => {node.blur()})
|
||||
buttonOutsideToolbar.evaluate(node => {
|
||||
node.blur();
|
||||
});
|
||||
|
||||
const [wasButton3Clicked] = await Promise.all([
|
||||
button3.evaluate(node => new Promise(resolve => {
|
||||
node.addEventListener("click", () => {
|
||||
resolve(true)
|
||||
})
|
||||
})),
|
||||
button3.click()
|
||||
])
|
||||
button3.evaluate(
|
||||
node =>
|
||||
new Promise(resolve => {
|
||||
node.addEventListener("click", () => {
|
||||
resolve(true);
|
||||
});
|
||||
})
|
||||
),
|
||||
button3.click(),
|
||||
]);
|
||||
|
||||
expect.soft(wasButton3Clicked).toEqual(true)
|
||||
expect.soft(wasButton3Clicked).toEqual(true);
|
||||
await expect.soft(buttonOutsideToolbar).not.toBeFocused();
|
||||
await expect(button3).toBeFocused();
|
||||
});
|
||||
|
|
|
|||
|
|
@ -10,8 +10,9 @@
|
|||
"importsNotUsedAsValues": "error",
|
||||
"target": "es2015",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "Node16",
|
||||
"moduleResolution": "NodeNext",
|
||||
"importHelpers": true,
|
||||
"noImplicitAny": false,
|
||||
"lib": ["DOM", "ES2015", "ES2016.Array.Include", "ES2017.Object"]
|
||||
},
|
||||
"include": ["src"]
|
||||
|
|
|
|||
|
|
@ -75,6 +75,7 @@
|
|||
"ts-loader": "^7.0.2",
|
||||
"ts-node": "^8.9.1",
|
||||
"tsconfig-paths": "^3.9.0",
|
||||
"tslib": "^2.4.0",
|
||||
"typescript": "^4.7.0",
|
||||
"webpack": "^5.72.0",
|
||||
"webpack-cli": "^4.9.2"
|
||||
|
|
|
|||
|
|
@ -7,9 +7,9 @@
|
|||
"noImplicitAny": false,
|
||||
"strictPropertyInitialization": false,
|
||||
"target": "es2015",
|
||||
"module": "ESNext",
|
||||
"module": "NodeNext",
|
||||
"importHelpers": true,
|
||||
"moduleResolution": "Node16",
|
||||
"moduleResolution": "NodeNext",
|
||||
"types": [
|
||||
"mocha",
|
||||
"webpack-env"
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@
|
|||
},
|
||||
"dependencies": {
|
||||
"parse5": "^6.0.1",
|
||||
"tslib": "^2.4.0"
|
||||
"tslib": "2.4.0"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@microsoft/fast-element": "^2.0.0-beta.26"
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
"allowSyntheticDefaultImports": true,
|
||||
"target": "ES2015",
|
||||
"module": "ES2015",
|
||||
"moduleResolution": "Node16",
|
||||
"moduleResolution": "NodeNext",
|
||||
"importHelpers": true,
|
||||
"experimentalDecorators": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Website
|
||||
|
||||
This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
|
||||
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
|
|||
|
|
@ -7,22 +7,12 @@ module.exports = {
|
|||
organizationName: "microsoft",
|
||||
projectName: "fast",
|
||||
onBrokenLinks: "log",
|
||||
scripts: [
|
||||
{
|
||||
src: "/fast-components.iife.min.js",
|
||||
async: true,
|
||||
},
|
||||
],
|
||||
themes: [require.resolve("@docusaurus/theme-live-codeblock")],
|
||||
staticDirectories: ["static"],
|
||||
themeConfig: {
|
||||
colorMode: {
|
||||
defaultMode: "dark",
|
||||
},
|
||||
prism: {
|
||||
theme: require("prism-react-renderer/themes/github"),
|
||||
darkTheme: require("prism-react-renderer/themes/palenight"),
|
||||
},
|
||||
docs: {
|
||||
sidebar: {
|
||||
hideable: true,
|
||||
|
|
@ -49,11 +39,11 @@ module.exports = {
|
|||
label: "Docs",
|
||||
position: "left",
|
||||
},
|
||||
// TODO: uncomment when ready to display dropdown for doc versions (lines 55-58)
|
||||
// {
|
||||
// type: "docsVersionDropdown",
|
||||
// position: "left",
|
||||
// },
|
||||
{
|
||||
type: "docsVersionDropdown",
|
||||
position: "left",
|
||||
dropdownActiveClassDisabled: true,
|
||||
},
|
||||
{
|
||||
href: "https://www.fast.design",
|
||||
label: "Home",
|
||||
|
|
@ -139,25 +129,26 @@ module.exports = {
|
|||
"@docusaurus/preset-classic",
|
||||
{
|
||||
docs: {
|
||||
sidebarPath: require.resolve("./sidebars.js"),
|
||||
sidebarPath: "./sidebars.js",
|
||||
// Refer to https://github.com/microsoft/fast/issues/5865 effects of using true
|
||||
showLastUpdateTime: false,
|
||||
remarkPlugins: [require("mdx-mermaid")],
|
||||
// remarkPlugins: [require("mdx-mermaid")],
|
||||
// The "includeCurrentVersion" plugin includes the ./docs folder of the docs - setting to false as current docs are in progress
|
||||
// TODO: remove when ready to display both the current and legacy versions (line 155)
|
||||
includeCurrentVersion: false,
|
||||
// The "lastVersion" plugin sets which version the /docs route refers to
|
||||
// TODO: update lastVersion to "current" when ready for /docs route to be set to the current version (line 158)
|
||||
lastVersion: "legacy",
|
||||
lastVersion: "current",
|
||||
// TODO: Uncomment to begin displaying the doc versions labels (lines 160-167)
|
||||
// versions: {
|
||||
// current: {
|
||||
// label: "current version",
|
||||
// },
|
||||
// legacy: {
|
||||
// label: "legacy version",
|
||||
// },
|
||||
// },
|
||||
versions: {
|
||||
current: {
|
||||
label: "2.0.0",
|
||||
},
|
||||
"1.0.0": {
|
||||
label: "1.0.0",
|
||||
path: "1.0.0",
|
||||
},
|
||||
},
|
||||
},
|
||||
theme: {
|
||||
customCss: require.resolve("./src/css/custom.css"),
|
||||
|
|
|
|||
|
|
@ -15,7 +15,8 @@
|
|||
"prestart": "yarn prebuild",
|
||||
"serve": "docusaurus serve",
|
||||
"start": "docusaurus start",
|
||||
"swizzle": "docusaurus swizzle"
|
||||
"swizzle": "docusaurus swizzle",
|
||||
"test": "npx docusaurus-mdx-checker"
|
||||
},
|
||||
"browserslist": {
|
||||
"production": [
|
||||
|
|
@ -29,15 +30,19 @@
|
|||
"last 1 safari version"
|
||||
]
|
||||
},
|
||||
"devDependencies": {
|
||||
"@docusaurus/core": "2.0.0-beta.20",
|
||||
"@docusaurus/preset-classic": "2.0.0-beta.20",
|
||||
"@docusaurus/theme-live-codeblock": "2.0.0-beta.20",
|
||||
"@microsoft/api-documenter": "7.8.13",
|
||||
"concurrently": "^6.2.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"mdx-mermaid": "^1.2.1",
|
||||
"mermaid": "^9.1.2"
|
||||
"@docusaurus/core": "^3.2.1",
|
||||
"@docusaurus/module-type-aliases": "^3.2.1",
|
||||
"@docusaurus/preset-classic": "^3.2.1",
|
||||
"@docusaurus/theme-live-codeblock": "^3.2.1",
|
||||
"@docusaurus/types": "^3.2.1",
|
||||
"@mdx-js/react": "^3.0.1",
|
||||
"@microsoft/api-documenter": "^7.24.2",
|
||||
"@types/react": "^18.3.1",
|
||||
"concurrently": "^6.2.0",
|
||||
"prism-react-renderer": "^2.3.1",
|
||||
"react": "^18.3.1",
|
||||
"react-dom": "^18.3.1",
|
||||
"typescript": "~5.2.2"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,62 +4,6 @@ module.exports = {
|
|||
type: "doc",
|
||||
id: "introduction",
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Using the Components",
|
||||
link: {
|
||||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
"components/getting-started",
|
||||
"design-systems/fast-frame",
|
||||
{
|
||||
type: "category",
|
||||
label: "Components",
|
||||
customProps: {
|
||||
description: "A comprehensive list of FAST elements.",
|
||||
},
|
||||
link: {
|
||||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
"components/accordion",
|
||||
"components/anchor",
|
||||
"components/anchored-region",
|
||||
"components/avatar",
|
||||
"components/badge",
|
||||
"components/breadcrumb",
|
||||
"components/button",
|
||||
"components/card",
|
||||
"components/checkbox",
|
||||
"components/combobox",
|
||||
"components/data-grid",
|
||||
"components/dialog",
|
||||
"components/disclosure",
|
||||
"components/divider",
|
||||
"components/flipper",
|
||||
"components/horizontal-scroll",
|
||||
"components/listbox",
|
||||
"components/listbox-option",
|
||||
"components/menu",
|
||||
"components/number-field",
|
||||
"components/progress",
|
||||
"components/radio",
|
||||
"components/radio-group",
|
||||
"components/select",
|
||||
"components/skeleton",
|
||||
"components/slider",
|
||||
"components/switch",
|
||||
"components/tabs",
|
||||
"components/text-area",
|
||||
"components/text-field",
|
||||
"components/toolbar",
|
||||
"components/tooltip",
|
||||
"components/tree-view",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Building Components",
|
||||
|
|
@ -77,21 +21,6 @@ module.exports = {
|
|||
"fast-element/next-steps",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Creating Design Systems",
|
||||
link: {
|
||||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
"design-systems/overview",
|
||||
"design-systems/creating-a-component-library",
|
||||
"design-systems/design-tokens",
|
||||
"design-systems/high-contrast",
|
||||
"design/match-media-stylesheets",
|
||||
"design/localization",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Apps and Experiences",
|
||||
|
|
@ -100,39 +29,6 @@ module.exports = {
|
|||
},
|
||||
items: ["apps-and-experiences/dependency-injection"],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Integrations",
|
||||
link: {
|
||||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
"integrations/introduction",
|
||||
"integrations/angular",
|
||||
"integrations/aspnet",
|
||||
"integrations/aurelia",
|
||||
"integrations/blazor",
|
||||
"integrations/ember",
|
||||
"integrations/react",
|
||||
"integrations/rollup",
|
||||
"integrations/svelte",
|
||||
"integrations/vite",
|
||||
"integrations/vue",
|
||||
"integrations/webpack",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Tools",
|
||||
link: {
|
||||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
"tools/component-explorer",
|
||||
"tools/vscode",
|
||||
"tools/hot-module-reload",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "API Reference",
|
||||
|
|
@ -140,33 +36,6 @@ module.exports = {
|
|||
type: "generated-index",
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-animation",
|
||||
customProps: {
|
||||
description:
|
||||
"Exlore the classes and functions of fast-animation.",
|
||||
keywords: ["fast-animation"],
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-colors",
|
||||
customProps: {
|
||||
description:
|
||||
"Explore the classes, enumerations, functions, interfaces, variables, and type aliases of fast-colors.",
|
||||
keywords: ["fast-colors"],
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-components",
|
||||
customProps: {
|
||||
description:
|
||||
"Explore the classes, enumerations, functions, interfaces, variables, and type aliases of fast-components.",
|
||||
keywords: ["fast-components"],
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-element",
|
||||
|
|
@ -176,24 +45,6 @@ module.exports = {
|
|||
keywords: ["fast-element"],
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-foundation",
|
||||
customProps: {
|
||||
description:
|
||||
"Explore the classes, enumerations, functions, interfaces, variables, and type aliases of fast-foundation.",
|
||||
keywords: ["fast-foundation"],
|
||||
},
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "api/fast-ssr",
|
||||
customProps: {
|
||||
description:
|
||||
"Explore the classes, enumerations, functions, interfaces, variables, and type aliases of fast-ssr.",
|
||||
keywords: ["fast-ssr"],
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -1,20 +0,0 @@
|
|||
import React from "react";
|
||||
import { CardLayout } from "../../theme/DocCard";
|
||||
import styles from "./styles.module.css";
|
||||
|
||||
|
||||
export function DocCardList({ children }) {
|
||||
return (
|
||||
<div className={styles.cardContainer}>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function DocCardItem(props) {
|
||||
return (
|
||||
<div className={styles.docCard}>
|
||||
<CardLayout {...props} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
.cardContainer {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 20px;
|
||||
}
|
||||
|
||||
.docCard {
|
||||
width: 48%;
|
||||
}
|
||||
|
||||
@media only screen and (max-width: 480px) {
|
||||
.docCard {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
|
|
@ -1,96 +0,0 @@
|
|||
---
|
||||
title: Components QuickStart
|
||||
sidebar_label: QuickStart
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/fast-foundation/getting-started.md
|
||||
description: The @microsoft/fast-components library contains Web Components built on top of our standard component and design system foundation.
|
||||
keywords:
|
||||
- getting started
|
||||
---
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.npmjs.com/package/@microsoft/fast-components)
|
||||
|
||||
The `@microsoft/fast-components` library contains Web Components built on top of our standard component and design system foundation. `@microsoft/fast-components` expresses the FAST design language (FAST Frame).
|
||||
|
||||
## Installation
|
||||
|
||||
### From NPM
|
||||
|
||||
To install the components:
|
||||
|
||||
```shell
|
||||
npm install --save @microsoft/fast-components
|
||||
```
|
||||
|
||||
```shell
|
||||
yarn add @microsoft/fast-components
|
||||
```
|
||||
|
||||
To use a Web Component as a custom element in HTML, the custom element must be registered. Importing the necessary component definition into your JavaScript bundle and registering it with a `DesignSystem` will register the custom element with the platform. Here's how to do that for `@microsoft/fast-components`:
|
||||
|
||||
```js
|
||||
import {
|
||||
fastButton,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton()
|
||||
);
|
||||
```
|
||||
|
||||
As a shortcut, if you wish to easily register all available components, rather than registering each one, you can use the following pattern:
|
||||
|
||||
```js
|
||||
import {
|
||||
allComponents,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem().register(allComponents);
|
||||
```
|
||||
|
||||
:::note
|
||||
When working with a tree-shaking supporting bundler such as Webpack or Rollup, you will want to import and register the individual components. This will ensure that any unused components are tree-shaken out of your builds.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
Looking for a setup that integrates with a particular front-end framework or bundler? Check out [our integration docs](../integrations/introduction.md).
|
||||
:::
|
||||
|
||||
### From CDN
|
||||
|
||||
A pre-bundled script that contains all APIs needed to use the components is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN. Here's what that would look like for the FAST Web Components:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components/dist/fast-components.min.js"></script>
|
||||
</head>
|
||||
<!-- ... -->
|
||||
</html>
|
||||
```
|
||||
|
||||
The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
|
||||
|
||||
```html
|
||||
<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components@2.16.0/dist/fast-components.min.js"></script>
|
||||
```
|
||||
|
||||
When using FAST from CDN, there is no need to register the components. The CDN script includes code that automatically sets up the design system and registers all the components.
|
||||
|
||||
:::note
|
||||
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
|
||||
:::
|
||||
|
||||
## Add components
|
||||
|
||||
With the components registered, add any component to the HTML. That's it! For a comprehensive list of all elements, see the [Components](./fast-accordion.mdx) section.
|
||||
|
||||
```html
|
||||
<!-- ... -->
|
||||
<fast-button>Hello world</fast-button>
|
||||
<!-- ... -->
|
||||
```
|
||||
|
|
@ -1,222 +0,0 @@
|
|||
---
|
||||
id: creating-a-component-library
|
||||
title: Creating a Component Library
|
||||
sidebar_label: Creating a Component Library
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/creating-a-component-library.md
|
||||
description: Not only is FAST great for creating individual components, but it also shines when creating libraries or systems of components.
|
||||
keywords:
|
||||
- foundation components
|
||||
- design systems
|
||||
---
|
||||
|
||||
Not only is FAST great for creating individual components, but it also shines when creating libraries or systems of components. FAST Foundation exposes several powerful abstractions in order to enable library authors to provide ergonomic APIs to application authors. These APIs ensure that app authors who consume your library have a consistent way to configure, augment, and override various details of the components. For example:
|
||||
|
||||
- Custom element tag names are easily configured and disambiguated.
|
||||
- Custom elements are explicitly registered to avoid tree-shaking.
|
||||
- Templates, styles, default slotted content, and arbitrary component configurations are all configurable by application authors.
|
||||
- Shadow DOM options are easily configurable.
|
||||
|
||||
All these configuration capabilities are designed to give application authors the flexibility necessary to align library components to application or business requirements. This section walks through the process of defining a component from a library author’s perspective, detailing component, template, and style creation that supports the configuration capabilities described above.
|
||||
|
||||
## Defining components
|
||||
|
||||
To opt into the features above, begin by extending your components from the `FoundationElement` base class in `@microsoft/fast-foundation` rather than `FASTElement`. `FoundationElement` is a light extension of `FASTElement` that supports element configuration during component registration as well as DOM-scoped, overridable templates and styles. Here's an example of a basic `Counter` component that inherits from `FoundationElement`.
|
||||
|
||||
```ts
|
||||
import { FoundationElement } from "@microsoft/fast-foundation";
|
||||
import { attr } from "@microsoft/fast-element";
|
||||
|
||||
export class Counter extends FoundationElement {
|
||||
@attr count = 0;
|
||||
|
||||
increment() {
|
||||
this.count++;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
One important detail to note is that we do not use the `@customElement` decorator in this case. The `@customElement` decorator forces immediate template and style resolution, and platform component element name registration. This is fine when building application components, or components not intended to be used as part of a library in another application. However, if used for library components, it prevents the consumer of the component from having the opportunity to customize the component in ways that might be critical for their app. `FoundationElement` helps address this challenge.
|
||||
|
||||
### Define Templates and Styles
|
||||
|
||||
With our `Counter` component class written, we now need to define its templates and styles. There are two ways to accomplish this. Just like `FASTElement`, a component that extends `FoundationElement` can be used with the [`html`](../fast-element/declaring-templates.md) and [`css`](../fast-element/leveraging-css.md) tagged template literals. So, we could define our template and styles in the same fashion as any other component, like this:
|
||||
|
||||
```ts
|
||||
import { html, css } from "@microsoft/fast-element";
|
||||
|
||||
const counterStyles = css`/* ... */`;
|
||||
const counterTemplate = html`<!-- ... -->`;
|
||||
```
|
||||
|
||||
However, a `FoundationElement` also supports a lazily-defined template and style type. This lazy option is a function invoked with [ElementDefinitionContext](../api/fast-foundation.elementdefinitioncontext.md) and [FoundationElementDefinition](../api/fast-foundation.foundationelementdefinition.md) options, providing opportunity to adjust the template or styles based on how the element or other elements are defined. Lazy template and style definitions provide incredible flexibility and are what can allow application authors to re-name component tag names, override default slotted content, and communicate any component-specific configuration options. Here's how we would convert the previous standard templates and styles into lazy templates and styles:
|
||||
|
||||
```ts
|
||||
import { html, css } from "@microsoft/fast-element";
|
||||
import { ElementDefinitionContext, FoundationElementDefinition } from "@microsoft/fast-foundation";
|
||||
|
||||
const counterStyles = (
|
||||
context: ElementDefinitionContext,
|
||||
definition: FoundationElementDefinition
|
||||
) => css`/* ... */`;
|
||||
|
||||
const counterTemplate = (
|
||||
context: ElementDefinitionContext,
|
||||
definition: FoundationElementDefinition
|
||||
) => html`<!-- ... -->`;
|
||||
```
|
||||
|
||||
Let’s take a closer look at what the two arguments to these lazily evaluated functions give us.
|
||||
|
||||
#### What is the `ElementDefinitionContext`?
|
||||
|
||||
The first argument is the `ElementDefinitionContext`. This context object provides information that is available *during* the attempt to register the element. For example, it will tell you the HTML element tag `name` that the component will be defined as. You can also see what the default `shadowRootMode` of the `DesignSystem` is. Most of the other APIs are used internally by `FoundationElement.compose` (see below) to define the element, but one particular API of note is the `tagFor()` method of the context. This API is used to inspect the tag-name of other components and allows usage of other library components in a template or stylesheet without knowing ahead of time what the tag-name for the element will be. Here's an example of how the reusable `Counter` component would leverage this to ensure that the `Button`'s tag name is correct, even if the app developer decides to rename `Button` in some way.
|
||||
|
||||
```ts
|
||||
import { html, css } from "@microsoft/fast-element";
|
||||
import { Button } from "@microsoft/fast-components";
|
||||
import type { ElementDefinitionContext } from "@microsoft/fast-foundation";
|
||||
|
||||
const counterTemplate = (context: ElementDefinitionContext) => {
|
||||
const buttonTag = context.tagFor(Button);
|
||||
|
||||
return html`
|
||||
<div>The count is ${x => x.count}.</div>
|
||||
<${buttonTag} @click=${x => x.increment()}>Count!</${buttonTag}>
|
||||
`;
|
||||
}
|
||||
|
||||
const counterStyles = (context: ElementDefinitionContext) => {
|
||||
const buttonTag = context.tagFor(Button);
|
||||
|
||||
return css`
|
||||
${buttonTag} {
|
||||
margin-inline-start: 12px;
|
||||
}
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
#### What is the `FoundationElementDefinition`?
|
||||
|
||||
The `FoundationElementDefinition` is the configuration for the element itself. This argument allows you to inspect the aggregated options configured for the component, giving you access to the `shadowOptions`, `elementOptions`, and more.
|
||||
|
||||
This definition can also be arbitrarily extended by library authors, allowing custom configuration to flow through the registration process. For example, this mechanism can facilitate default slotted content overrides. To see how our `Counter` could leverage this, let's enable the `Button` content to be overridden by the application developer. Here's what that would look like:
|
||||
|
||||
```ts
|
||||
import { html } from "@microsoft/fast-element";
|
||||
import { ElementDefinitionContext, FoundationElementDefinition } from "@microsoft/fast-foundation";
|
||||
import { Button } from "@microsoft/fast-components";
|
||||
|
||||
// Extend the configuration with custom properties
|
||||
interface CounterDefinition extends FoundationElementDefinition {
|
||||
defaultButtonContent?: string;
|
||||
}
|
||||
|
||||
const counterTemplate = (context: ElementDefinitionContext, definition: CounterDefinition) => {
|
||||
const buttonTag = context.tagFor(Button);
|
||||
|
||||
return html`
|
||||
<div>The count is ${x => x.count}.</div>
|
||||
<${buttonTag} @click=${x => x.increment()}>
|
||||
<slot>${definition.defaultButtonContent}</slot> <!--Use the custom configuration-->
|
||||
</${buttonTag}>
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
When the library author creates the registration function (see next section), they can provide the default content. Then, during component registration with the `DesignSystem`, an application author can optionally provide a `defaultButtonContent` field as a configuration to override this setting.
|
||||
|
||||
### Compose and Export Registration
|
||||
|
||||
The final step in the process is to create and export the registration function so that application authors can register the component in their `DesignSystem`. Here's how we would create the registration function for `Counter`, using our extended `CounterDefinition` configuration:
|
||||
|
||||
```ts
|
||||
export const counter = Counter.compose<CounterDefinition>({
|
||||
baseName: 'counter',
|
||||
template,
|
||||
styles,
|
||||
defaultButtonContent: "Count!"
|
||||
});
|
||||
```
|
||||
|
||||
Here we provide the base component name of `counter`, which will be combined with the `DesignSystem` element prefix during registration. We also provide our lazy template and styles. Finally, we specify the `defaultButtonContent` value.
|
||||
|
||||
### Registering Library Components in an Application
|
||||
|
||||
To register the component, an application author will import the registration and register it in their `DesignSystem`, overriding any properties as necessary. For example, if this component had been created for the FAST Frame design system, then the following code could be used:
|
||||
|
||||
```ts
|
||||
import { counter } from "your-package";
|
||||
import { provideFASTDesignSystem, fastButton } from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton(),
|
||||
counter({ defaultButtonContent: "Please count." })
|
||||
);
|
||||
```
|
||||
|
||||
The advantage of setting `defaultButtonContent` here is that it overrides the `Counter`'s default slotted content for **all** instances of `your-counter`. Instead of having to define it everywhere in the app that the button is used, the app author provides the configuration once in a centralized location. This can be extremely useful in scenarios where components contain default icons that the app author may need to swap.
|
||||
|
||||
## Defining a design system
|
||||
|
||||
The above examples show how to build a single component that can be flexibly registered with an existing design system. But, you can create your own design system as well. To do so, you would start with the base components defined in `@microsoft/fast-foundation` and compose them with your own styles. You would also define your own `DesignToken`s to be used within your styles. Finally, you would export a "provider function" for your community to use in setting everything up.
|
||||
|
||||
### FAST design system thinking
|
||||
|
||||
When creating a design system, it can be helpful to think in terms of layers and use cases.
|
||||
|
||||
1. **foundation components**: A reusable set of component classes and templates, independent of any design system, and designed for maximum flexibility.
|
||||
2. **design system**: Leverages the flexibility of the foundation components, but adds the unique opinions of the design system (e.g. styles, element prefix, design tokens, theme colors, etc). It exports the component registration functions so that apps can decide what to use. This layer may also choose to "lock down" certain options so that the design system remains coherent when used.
|
||||
3. **application**: Registers only the components needed by the app itself.
|
||||
4. **features**: Only uses the components available in the app. Get access to design tokens to create feature-specific styled components in alignment with the design system.
|
||||
|
||||
Notice that the strength of the opinions increases as you proceed down the list, with each layer further constraining the system. When creating a design system, it's important to think through these use cases and consider how different scenarios are impacted.
|
||||
|
||||
### Composing a foundation component
|
||||
|
||||
Let's imagine that we want to add a `Button` to our design system. We only need to import the `@microsoft/fast-foundation` `Button` component class and template, and then compose them with our design system's button styles:
|
||||
|
||||
```ts
|
||||
import {
|
||||
Button,
|
||||
buttonTemplate as template,
|
||||
} from "@microsoft/fast-foundation";
|
||||
import { buttonStyles as styles } from "./special-button.styles";
|
||||
|
||||
export const specialButton = Button.compose({
|
||||
baseName: "button",
|
||||
template,
|
||||
styles,
|
||||
shadowOptions: {
|
||||
delegatesFocus: true,
|
||||
},
|
||||
});
|
||||
|
||||
export const buttonStyles = styles;
|
||||
```
|
||||
|
||||
As a practice, always be sure to export your styles independently as well. This enables the consumers of your components to build their own versions of your component, reusing and augmenting your styles as needed.
|
||||
|
||||
When authoring your own styles, you'll also want to leverage design tokens. Please see [the design token documentation](./design-tokens.md) for how to create and use design tokens.
|
||||
|
||||
### Creating a design system provider function
|
||||
|
||||
For convenience, and to ensure consistent design system configuration, it's a good idea to provide a simple function that sets up your design system. If we wanted to create a function for the "special" design system, we would use the following code:
|
||||
|
||||
```ts
|
||||
export function provideSpecialDesignSystem(element?: HTMLElement): DesignSystem {
|
||||
return DesignSystem.getOrCreate(element).withPrefix("special");
|
||||
}
|
||||
```
|
||||
|
||||
The underlying `DesignSystem.getOrCreate` API gets the design system directly attached to the provided element. If one does not exist, it creates one. By default, if no element is provided, the design system is created on the `document.body`. Using this function abstracts those details and provides a much-improved set of ergonomics to those using your components, while also giving you the opportunity to bake in certain configuration yourself, such as defining the default element prefix.
|
||||
|
||||
Now consumers of your components can setup your design system in their application with the button component as follows:
|
||||
|
||||
```ts
|
||||
provideSpecialDesignSystem()
|
||||
.register(
|
||||
specialButton()
|
||||
);
|
||||
```
|
||||
|
|
@ -1,266 +0,0 @@
|
|||
---
|
||||
id: design-tokens
|
||||
title: Design Tokens
|
||||
sidebar_label: Design Tokens
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/design-tokens.md
|
||||
description: The FAST Design Token implementation is designed to provide first-class support for Design Tokens and make setting, getting, and using Design Tokens simple.
|
||||
keywords:
|
||||
- design tokens
|
||||
---
|
||||
|
||||
The FAST Design Token implementation is designed to provide first-class support for Design Tokens and make setting, getting, and using Design Tokens simple.
|
||||
|
||||
## What is a Design Token
|
||||
|
||||
A Design Token is a semantic, named variable used to describe a Design System. They often describe design concepts like typography, color, sizes, UI spacing, etc. FAST encourages checking out [the Design Tokens Community Group](https://github.com/design-tokens/community-group#design-tokens) for more information on Design Tokens themselves.
|
||||
|
||||
## FAST Frame Design Tokens
|
||||
|
||||
The `@microsoft/fast-components` have extensive support for predefined design tokens. See [configuring styles](./fast-frame.md#configuring-styles) for details on adjusting or using the existing tokens, or read on to create your own.
|
||||
|
||||
## Create a Token
|
||||
|
||||
:::note
|
||||
Note that this example uses color because it's an easy concept to describe, but we generally discourage the use of fixed colors as they don't benefit from the [adaptive color system](./fast-frame.md#adaptive-color-system) with support for light and dark mode and other adjustments.
|
||||
:::
|
||||
|
||||
The first step to using a token is to create it:
|
||||
|
||||
```ts
|
||||
import { DesignToken } from "@microsoft/fast-foundation";
|
||||
|
||||
export const specialColor = DesignToken.create<string>("special-color");
|
||||
```
|
||||
|
||||
The type assertion informs what types the token can be set to (and what type will be retrieved), and the name parameter will serve as the CSS Custom Property name (more on that later).
|
||||
|
||||
## Setting Values
|
||||
|
||||
A `DesignToken` *value* can be set for any `FASTElement` instance. This allows tokens to be set to different values for distinct DOM trees:
|
||||
|
||||
```ts
|
||||
const ancestor = document.querySelector("my-element") as FASTElement;
|
||||
const descendent = ancestor.querySelector("my-element") as FASTElement;
|
||||
|
||||
specialColor.setValueFor(ancestor, "#FFFFFF");
|
||||
specialColor.setValueFor(descendent, "#F7F7F7");
|
||||
```
|
||||
|
||||
## Setting a Default Value
|
||||
|
||||
A default value can be set for a token so that the default value is returned from `getValueFor()` in cases where no other token value is found for a node tree.
|
||||
|
||||
```ts
|
||||
specialColor.withDefault("#FFFFFF");
|
||||
```
|
||||
|
||||
## Getting Values
|
||||
|
||||
Once the value is set for a node, the value is available to use for that node or any descendent node. The value returned will be the value set for the nearest ancestor (or the FASTElement itself).
|
||||
|
||||
```ts
|
||||
specialColor.getValueFor(ancestor); // "#FFFFFF"
|
||||
specialColor.getValueFor(descendent); // "#F7F7F7"
|
||||
```
|
||||
|
||||
The default value for a token can be retrieved directly from the token:
|
||||
|
||||
```ts
|
||||
const value = specialColor.default;
|
||||
```
|
||||
## Deleting Values
|
||||
|
||||
Values can be deleted for a node. Doing so causes retrieval of the nearest ancestor's value instead:
|
||||
|
||||
```ts
|
||||
specialColor.deleteValueFor(descendent);
|
||||
specialColor.getValueFor(descendent); // "#FFFFFF"
|
||||
```
|
||||
|
||||
## CSS Custom Property Emission
|
||||
|
||||
Unless configured not to, a DesignToken emits a token to CSS automatically whenever the value is set for a FASTElement. In the case when a DesignToken is assigned a [derived value](#derived-design-token-values), the CSS custom property will also be emitted when any dependent tokens change.
|
||||
|
||||
### DesignToken Default Style Roots
|
||||
In order for *default* DesignToken values to be emitted to a CSS custom property,
|
||||
DesignToken will need to be configured:
|
||||
|
||||
```ts
|
||||
DesignToken.create<number>('my-token').withDefault(2); // This will not immediately emit to a CSS custom property
|
||||
|
||||
DesignToken.registerDefaultStyleTarget();
|
||||
```
|
||||
|
||||
Invoking `DesignToken.registerDefaultStyleTarget()` will cause CSS custom properties to be emitted for the entire document. A FASTElement can also be provided so that CSS custom properties are scoped to that target, or a structure implementing `PropertyTarget` can be provided for complete control over emission.
|
||||
|
||||
```ts
|
||||
const target = document.querySelector("#style-target")! as FASTElement;
|
||||
DesignToken.registerDefaultStyleTarget(target);
|
||||
```
|
||||
|
||||
`DesignToken.unregisterDefaultStyleTarget()` can be invoked to remove default custom properties from a root and prevent further emission to that root.
|
||||
|
||||
```ts
|
||||
// ...
|
||||
DesignToken.unregisterDefaultStyleTarget(target);
|
||||
```
|
||||
|
||||
### Customizing CSS Custom Property Name
|
||||
A DesignToken can also be configured to emit to a CSS custom property that is different than the provided name by providing a CSS custom property name to the configuration:
|
||||
|
||||
```ts
|
||||
DesignToken.create<number>({
|
||||
name: "my-token",
|
||||
cssCustomPropertyName: "my-css-custom-property-name" // Emits to --my-css-custom-property-name
|
||||
});
|
||||
```
|
||||
### Preventing CSS Custom Property Emission
|
||||
|
||||
A DesignToken can be configured **not** to emit to a CSS custom property by passing a configuration object without a `cssCustomPropertyName`:
|
||||
|
||||
```ts
|
||||
DesignToken.create<number>({
|
||||
name: "my-token"
|
||||
});
|
||||
```
|
||||
|
||||
### Values with a 'createCSS' method
|
||||
|
||||
It is sometimes useful to be able to set a token to a complex object but still use that value in CSS. If a DesignToken is assigned a value with a `createCSS` method on it, the product of that method will be used when emitting to a CSS custom property instead of the Design Token value itself:
|
||||
|
||||
```ts
|
||||
interface RGBColor {
|
||||
r: number;
|
||||
g: number;
|
||||
b: number;
|
||||
createCSS(): string;
|
||||
}
|
||||
|
||||
const extraSpecialColor = DesignToken.create<RGBColor>("extra-special-color");
|
||||
|
||||
const value = {
|
||||
r: 255,
|
||||
g: 0,
|
||||
b: 0,
|
||||
createCSS() {
|
||||
return `rgb(${this.r}, ${this.g}, ${this.b})`;
|
||||
}
|
||||
}
|
||||
|
||||
extraSpecialColor.setValueFor(descendent, value)
|
||||
```
|
||||
|
||||
## Subscription
|
||||
|
||||
`DesignToken` supports subscription, notifying a subscriber when a value changes for a node.
|
||||
|
||||
**Example: Subscribe to changes for any node**
|
||||
|
||||
```ts
|
||||
const subscriber = {
|
||||
handleChange<T extends DesignToken<any>>(token: DesignToken<T>, record: DesignTokenChangeRecord<T>) {
|
||||
console.log(`DesignToken ${record.token} changed for ${record.target}`);
|
||||
}
|
||||
};
|
||||
|
||||
specialColor.subscribe(subscriber);
|
||||
```
|
||||
|
||||
## Using Design Tokens in CSS
|
||||
|
||||
Any token can be used directly in a FAST stylesheet by using the Design Token as a CSS directive. Assuming the token value has been set for the element or some ancestor element, the value of the token embedded in the stylesheet will be the token value for that element instance.
|
||||
|
||||
```ts
|
||||
import { css } from "@microsoft/fast-element";
|
||||
|
||||
const styles = css`
|
||||
:host {
|
||||
background: ${specialColor};
|
||||
}
|
||||
`
|
||||
```
|
||||
|
||||
At runtime, the directive is replaced with a CSS custom property, and the Directive ensures that the CSS custom property is added for the element.
|
||||
|
||||
## Derived Design Token Values
|
||||
|
||||
In the examples above, the design token is always being set to a simple string value. But, we can also set a Design Token to be a function that *derives* a value. A derived value receives a `DesignTokenResolver` as its only argument and must return a value with a type matching the Design Token:
|
||||
|
||||
```ts
|
||||
const token = DesignToken.create<number>("token");
|
||||
token.setValueFor(target, (resolve) => 12);
|
||||
```
|
||||
|
||||
The above example is contrived, but resolver can be used to retrieve *other* Design Token values:
|
||||
|
||||
**Example: A derived token value that uses another design token**
|
||||
```ts
|
||||
const foregroundColor = DesignToken.create<string>("foreground-color");
|
||||
|
||||
foregroundColor.setValueFor(target, (resolve) =>
|
||||
resolve(specialColor) === "#FFFFFF"
|
||||
? "#2B2B2B"
|
||||
: "#262626"
|
||||
);
|
||||
```
|
||||
|
||||
For derived Design Token values, any change to dependent tokens will force the derived value to update (and update the CSS custom property if applicable). The same is true if an observable property is used by the derived value:
|
||||
|
||||
```ts
|
||||
import { observable } from "@microsoft/fast-element";
|
||||
|
||||
class ThemeManager {
|
||||
@observable
|
||||
theme: "blue" | "red" = "blue"
|
||||
}
|
||||
|
||||
const themeManager = new ThemeManager();
|
||||
|
||||
specialColor.setValueFor(target, () => themeManager.theme === "blue" ? "#0000FF" : "#FF0000");
|
||||
|
||||
themeManager.theme = "red"; // Forces the derived tokens to re-evaluate and CSS custom properties to update if applicable
|
||||
```
|
||||
|
||||
> Note: *volatile* token values that conditionally access DesignTokens or other observable properties are currently not supported by DesignToken. If you need to use conditionals,
|
||||
ensure all DesignTokens or observable properties are accessed outside of conditional blocks. See [Observables and State](../fast-element/observables-and-state.md#observable-features) for more information.
|
||||
|
||||
## Aliasing Design Tokens
|
||||
|
||||
In some design systems, Design Tokens may have complex hierarchies with tokens referencing other tokens. This can be accomplished by setting a Design Token to another Design Token.
|
||||
|
||||
```ts
|
||||
const specialColor = DesignToken.create<string>("special-color");
|
||||
const buttonSpecialColor = DesignToken.create<string>("button-special-color");
|
||||
|
||||
specialColor.setValueFor(target, "#EDEDED");
|
||||
buttonSpecialColor.setValueFor(target, specialColor);
|
||||
|
||||
buttonSpecialColor.getValueFor(target); // "#EDEDED"
|
||||
```
|
||||
|
||||
## SSR
|
||||
`DesignToken` can be used with `@microsoft/fast-ssr`, but must be configured to do so.
|
||||
|
||||
### Configuring the Resolution Strategy
|
||||
The resolution strategy is a configurable abstraction that allows `DesignToken` to build element hierarchies and resolve token values, and must be configured with a strategy supported by `@microsoft/fast-ssr`.
|
||||
|
||||
```ts
|
||||
// server.js
|
||||
import { DesignToken, DesignTokenEventResolutionStrategy} from "@microsoft/fast-foundation";
|
||||
|
||||
DesignToken.withStrategy(DesignTokenEventResolutionStrategy);
|
||||
```
|
||||
|
||||
### Default Value CSS
|
||||
DesignToken is generally used to emit default values to the document. During template rendering in an SSR environment, there is no document to emit CSS to. Instead, a lightweight `PropertyTarget`, such as the provided `DesignTokenStyleTarget`, should be used to collect CSS values for tokens. The CSS can then be retrieved and interpolated into the SSR response.
|
||||
|
||||
For more info on `@microsoft/fast-ssr` see the (SSR Documentation)[https://github.com/microsoft/fast/blob/master/packages/web-components/fast-ssr/README.md], and for an SSR example using `DesignToken` see the (SSR Example App)[https://github.com/microsoft/fast/tree/master/examples/ssr].
|
||||
|
||||
```ts
|
||||
import { DesignTokenStyleTarget } from "@microsoft/fast-foundation";
|
||||
|
||||
const styleTarget = new DesignTokenStyleTarget();
|
||||
DesignToken.registerDefaultStyleTarget(styleTarget);
|
||||
|
||||
const defaultStyles = `<style>:root{${styleTarget.cssText}}</style>`;
|
||||
```
|
||||
|
|
@ -1,372 +0,0 @@
|
|||
---
|
||||
id: fast-frame
|
||||
title: The FAST Frame Design System
|
||||
sidebar_label: FAST Frame Design System
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/fast-frame.md
|
||||
description: A highly configurable Design System composed of Web Components, Design Tokens, stylesheets, and styling tools.
|
||||
keywords:
|
||||
- fast frame design system
|
||||
---
|
||||
|
||||
FAST Frame ([`@microsoft/fast-components`](https://www.npmjs.com/package/@microsoft/fast-components)) is a highly configurable Design System composed of Web Components, Design Tokens, stylesheets, and styling tools. You can drop it into any app to start with a robust component library and an adaptive and accessible UI system immediately.
|
||||
|
||||
## Using FAST Frame Components
|
||||
|
||||
### Create a `DesignSystem`
|
||||
|
||||
Web components from FAST Frame must be registered with the `DesignSystem` prior to being used in HTML. To set up the `DesignSystem`, first import and invoke the provider function from `@microsoft/fast-foundation` to get the `DesignSystem` instance. Then import the registrations of the components you want to use from `@microsoft/fast-components` and register them with the `DesignSystem`:
|
||||
|
||||
```ts
|
||||
import {
|
||||
fastButton,
|
||||
fastMenu,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton(),
|
||||
fastMenu()
|
||||
);
|
||||
```
|
||||
|
||||
### Add Element to HTML
|
||||
|
||||
Once you've registered the components, as shown above, they are now available for use in your document (or template). Just use the new elements like any other HTML element:
|
||||
|
||||
```html
|
||||
<fast-button>Click me!</fast-button>
|
||||
```
|
||||
|
||||
### Hide undefined elements
|
||||
|
||||
Custom Elements that have not been [upgraded](https://developers.google.com/web/fundamentals/web-components/customelements#upgrades) and don't have styles attached can still be rendered by the browser but they likely do not look how they are supposed to. To avoid a *flash of un-styled content* (FOUC), visually hide Custom Elements that are not yet defined:
|
||||
|
||||
```CSS
|
||||
:not(:defined) {
|
||||
visibility: hidden;
|
||||
}
|
||||
```
|
||||
|
||||
:::important
|
||||
The consuming application must apply this, as the components themselves do not.
|
||||
:::
|
||||
|
||||
## Configuring Components
|
||||
|
||||
FAST Frame components are highly configurable, so let’s look at some of the opportunities for configuration that can be leveraged. If you’d like to understand these APIs further, check out the [creating a component library](./creating-a-component-library.md) documentation.
|
||||
|
||||
### Configuring the DesignSystem
|
||||
|
||||
The `DesignSystem` is the entry-point for most component configurations. It can be used to control the options for which the custom element is defined in the browser, which template and stylesheet to use, and how to disambiguate custom elements that are defined for a single element tag name.
|
||||
|
||||
For all APIs described in this section, the configuration overrides apply to all components registered to the DesignSystem except when the option is explicitly provided [during component registration](./fast-frame.md#configuring-components-during-registration).
|
||||
|
||||
#### `DesignSystem.withPrefix()`
|
||||
|
||||
As [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components), FAST Components are [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) subject to the [naming conventions defined by HTML](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name). This means that the element name must contain a ‘-‘ character. By default, the DesignSystem defines all elements registered with it with the “fast” prefix. [The example above](./fast-frame.md/#add-element-to-html) illustrates this, where the FastButton is defined with the ‘fast’ prefix.
|
||||
|
||||
This prefix can be changed for all components registered by the DesignSystem using the `DesignSystem.withPrefix()` API:
|
||||
|
||||
```ts
|
||||
import { fastButton, provideFASTDesignSystem } from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.withPrefix("faster")
|
||||
.register(fastButton())
|
||||
```
|
||||
|
||||
In this case, the element can be used in HTML using the ‘faster’:
|
||||
|
||||
```html
|
||||
<faster-button>Click me!</faster-button>
|
||||
```
|
||||
|
||||
#### `DesignSystem.withShadowRootMode()`
|
||||
|
||||
Unless specified during [component registration creation](./creating-a-component-library.md#compose-and-export-registration), all components registered with the DesignSystem are defined with [the shadow root mode](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode) originally specified by the component developer (typically "open", as that is both recommended and the default). This behavior can be changed using `DesignSystem.withShadowRootMode()` to close all shadow roots by default:
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.withShadowRootMode("closed")
|
||||
.register(/* ... */)
|
||||
```
|
||||
|
||||
#### `DesignSystem.withElementDisambiguation()`
|
||||
|
||||
By default, an element registered with an already-taken name will not be re-registered with the platform. However, its element definition callback will still be invoked, allowing it to define an alternate presentation (styles and template), scoped to the DOM tree that the design system is defined on.
|
||||
|
||||
As a best practice, one should try to avoid registering the same component more than once. However, if your architecture makes this difficult or impossible, you can provide a custom callback to handle disambiguating the duplicate elements.
|
||||
|
||||
The `ElementDisambiguationCallback` will be passed the tag name being registered, the type being registered, and the type that was already registered with the tag. Your callback can then return one of three types of values:
|
||||
|
||||
* `string` - Return a string to select an alternate name for the element to be registered under.
|
||||
* `ElementDisambiguation.definitionCallbackOnly` - This is the default callback's return value, which prevents re-registering the element but allows its callback to run and define alternate presentations for the element (styles and template). Note that having more than one presentation for the same element will trigger a slower rendering code path for elements of that type. So, it's best to avoid this unless it's absolutely needed for your application design.
|
||||
* `ElementDisambiguation.ignoreDuplicate` - This option completely ignores the duplicate element and no action is taken during registration if an element with the same tag is already registered.
|
||||
|
||||
Here's an example custom disambiguation callback showing a couple of these options.
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.withElementDisambiguation((nameAttempt, typeAttempt, existingType) => {
|
||||
if (nameAttempt === "foo") {
|
||||
return "bar";
|
||||
}
|
||||
|
||||
return ElementDisambiguation.ignoreDuplicate;
|
||||
})
|
||||
.register(/* ... */)
|
||||
```
|
||||
|
||||
### Configuring Components During Registration
|
||||
|
||||
The DesignSystem APIs described above impact all components registered to the DesignSystem, but those options can also be configured or overridden on a per-component basis. Configuring the component itself takes priority over any DesignSystem configuration.
|
||||
|
||||
#### Prefix
|
||||
|
||||
The prefix for a component can be configured for a component registration by providing a configuration object with a prefix field during registration:
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton({ prefix: "faster" })
|
||||
);
|
||||
```
|
||||
|
||||
#### Template
|
||||
|
||||
To use a custom template for a component, provide a `template` field to the configuration object during registration:
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton({
|
||||
template: html`
|
||||
<p>A completely new template</p>
|
||||
`
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
#### Styles
|
||||
|
||||
Styles for a component can be configured as well, by providing a `styles` field to the configuration object during registration:
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton({
|
||||
styles: css`
|
||||
/* completely replace the original styles */
|
||||
`
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
It's also worth noting that this can be used to extend the existing styles, by importing the originals and composing those with new styles by calling the style function. Here's what that would look like:
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton({
|
||||
styles: (ctx, def) => css`
|
||||
${buttonStyles(ctx, def)}
|
||||
/* add your style augmentations here */
|
||||
`
|
||||
})
|
||||
)
|
||||
```
|
||||
|
||||
:::important
|
||||
|
||||
At present, there is a minor typing bug across all the style and template functions, so you will need to cast the second argument as follows `${buttonStyles(ctx, def as any)}`. [We have tracked this issue](https://github.com/microsoft/fast/issues/5047) and are planning a fix soon.
|
||||
|
||||
:::
|
||||
|
||||
#### Shadow Options
|
||||
|
||||
Shadow options can be configured as well, including both [shadow root mode](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode) and [focus delegation](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/delegatesFocus):
|
||||
|
||||
```ts
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton({
|
||||
shadowOptions: {
|
||||
mode: "closed",
|
||||
delegatesFocus: true
|
||||
}
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
For more information on shadow options, see [Element.attachShadow()](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow).
|
||||
|
||||
## Configuring Styles
|
||||
|
||||
FAST Frame is designed to be stylistically flexible, allowing dramatic changes to visual design with minimal code changes. This is possible through the extensive use of [Design Tokens](./design-tokens.md) and an [adaptive color system](./fast-frame.md#adaptive-color-system).
|
||||
|
||||
### FAST Frame Design Tokens
|
||||
|
||||
FAST exposes the following Design Tokens that can be used to configure components stylistically. This section describes the non-color related Design Tokens. For Design Tokens related to color, see the [adaptive color system section](./fast-frame.md#adaptive-color-system)
|
||||
|
||||
#### Typography
|
||||
|
||||
| Level | Font Size Token Name | Line Height Token Name |
|
||||
|--------------------|---------------------------------|----------------------------------|
|
||||
| Minus 2 (smallest) | `typeRampMinus2FontSize` | `typeRampMinus2LineHeight` |
|
||||
| Minus 1 | `typeRampMinus1FontSize` | `typeRampMinus1LineHeight` |
|
||||
| Base (body) | `typeRampBaseFontSize` | `typeRampBaseLineHeight` |
|
||||
| Plus 1 | `typeRampPlus1FontSize` | `typeRampPlus1LineHeight` |
|
||||
| Plus 2 | `typeRampPlus2FontSize` | `typeRampPlus2LineHeight` |
|
||||
| Plus 3 | `typeRampPlus3FontSize` | `typeRampPlus3LineHeight` |
|
||||
| Plus 4 | `typeRampPlus4FontSize` | `typeRampPlus4LineHeight` |
|
||||
| Plus 5 | `typeRampPlus5FontSize` | `typeRampPlus5LineHeight` |
|
||||
| Plus 6 (largest) | `typeRampPlus6FontSize` | `typeRampPlus6LineHeight` |
|
||||
-------------------------------------------------
|
||||
|
||||
#### Sizing
|
||||
|
||||
- `baseHeightMultiplier`: This value, multiplied by `designUnit`, sets the base height of most controls. Works with adaptive `density` values.
|
||||
- `baseHorizontalSpacingMultiplier` (future): This value, multiplied by `designUnit`, sets the internal horizontal padding of most controls. Works with adaptive `density` values.
|
||||
- `controlCornerRadius`: Sets the corner radius used by controls with backplates.
|
||||
- `density` (in process): An adjustment to sizing tokens `baseHeightMultiplier` and `baseHorizontalSpacingMultiplier`.
|
||||
- `designUnit`: The unit size of the Design Grid. Used to calculate height and spacing sizes for controls.
|
||||
|
||||
#### Misc.
|
||||
|
||||
- `direction`: The primary document direction (LTR or RTL).
|
||||
- `disabledOpacity`: The opacity of disabled controls.
|
||||
- `strokeWidth`: Controls the width of the stroke of a component that has a stroke.
|
||||
- `focusStrokeWidth`: Controls the width of the stroke of a component that has a stroke when it has document focus.
|
||||
|
||||
### Adaptive Color System
|
||||
|
||||
FAST Frame implements an adaptive color system that provides some unique advantages:
|
||||
- Ensure text meets [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) contrast requirements.
|
||||
- Easily swap from light mode to dark, or anywhere in-between.
|
||||
- Color theming through palette tinting.
|
||||
- Perceptually uniform UI across background colors.
|
||||
|
||||
To accomplish these goals, FAST Frame makes heavy use of algorithmic colors called Recipes. Recipes are a combination of an algorithm and input values that produce a desired result. Just as you can bake different types of cookies with different combinations of sugar, butter, flour, and salt, you can produce different design system treatments by altering recipe values (measurements) or algorithms (instructions).
|
||||
|
||||
The current base recipes are closely related to their algorithm, but that's a convention and not a requirement. What follows is a list of the algorithms, which function on like-named values. For instance, `accentFill` relies on `accentFillRestDelta`, `accentFillHoverDelta`, `accentFillActiveDelta`, and `accentFillFocusDelta`.
|
||||
|
||||
Recipes are currently used for color values, but they are not limited to that and their usage will be expanded soon.
|
||||
|
||||
**To better visualize how this works, FAST built an application specificity for exploring the system. Check out [the Color Explorer.](https://color.fast.design/)**
|
||||
|
||||
#### Common functionality
|
||||
|
||||
Most color recipes are based on a `palette`. Currently, `fast-components` has built-in support for `accent` and `neutral` palettes.
|
||||
|
||||
Most color recipes take a `reference` `Swatch`. This is a core concept of Adaptive UI which allows the recipes to vary based on the containing component's color. For instance, supporting a button with consistent treatment between light and dark modes is done with a single recipe.
|
||||
|
||||
Many recipes are "stateful", meaning they support rest, hover, active, and focus states for a component.
|
||||
|
||||
**"Fill"** means the recipe is intended to fill a larger area, commonly like a component backplate.
|
||||
|
||||
**"Foreground"** means the recipe is intended for text, icons, or other lightweight decorations where you need or want to meet contrast requirements.
|
||||
|
||||
**"Stroke"** means the recipe is intended for lines, either outline or divider.
|
||||
|
||||
#### Accent algorithms
|
||||
|
||||
##### accentFill
|
||||
|
||||
Stateful.
|
||||
|
||||
Relies on `textColor` and `contrastTarget` to find the closest colors from the supplied palette that can be used for component states. For instance, colors needed to support white text and a 14px font (which requires 4.5:1 contrast).
|
||||
|
||||
##### accentForeground
|
||||
|
||||
Stateful.
|
||||
|
||||
Commonly for link text or icon. Also for smaller elements that might not show up well using `accentFill`, for instance, if your accent color is dark purple and you support a dark mode interface.
|
||||
|
||||
Like `accentFill` this relies on `textColor` and `contrastTarget` to find the closest colors from the supplied palette that can be used for component states.
|
||||
|
||||
##### foregroundOnAccent
|
||||
|
||||
Not stateful.
|
||||
|
||||
Technically this doesn't _use_ the accent palette, but it's designed to be used _over_ the accent palette. This algorithm simply returns black or white based on the provided `contrastTarget`. It returns white if possible, as a common treatment for an accent button is white text over the accent color.
|
||||
|
||||
#### Neutral algorithms
|
||||
|
||||
##### neutralDivider
|
||||
|
||||
Not stateful.
|
||||
|
||||
Used for decorative dividers that do not need to meet contrast requirements.
|
||||
|
||||
##### neutralFill
|
||||
|
||||
Stateful.
|
||||
|
||||
The most basic fill used for buttons or other components.
|
||||
|
||||
##### neutralFillContrast
|
||||
|
||||
Stateful.
|
||||
|
||||
Often Used as a selected state or anywhere you want to draw attention. Meets contrast requirements with the containing background.
|
||||
|
||||
##### neutralFillInput
|
||||
|
||||
Stateful.
|
||||
|
||||
Another basic fill, applied to input elements to allow easy differentiation from other components like buttons.
|
||||
|
||||
##### neutralFillStealth
|
||||
|
||||
Stateful.
|
||||
|
||||
More subtle than `neutralFill` in that the resting state is transparent. Often used for low-priority features to draw less attention.
|
||||
|
||||
##### neutralForeground
|
||||
|
||||
Not stateful.
|
||||
|
||||
Most common recipe, used for plain text or icons.
|
||||
|
||||
##### neutralForegroundHint
|
||||
|
||||
Not stateful.
|
||||
|
||||
Used for subtle text. Meets 4.5:1 minimum contrast requirement.
|
||||
|
||||
##### neutralStroke
|
||||
|
||||
Stateful.
|
||||
|
||||
Used for strong outline, either alone or with a fill.
|
||||
|
||||
#### Layers
|
||||
|
||||
The layer recipes are used for different sections of an app or site. They are designed to be able to stack, but that is not required. When stacked in sequence, the layers will lighten on top of each other.
|
||||
|
||||
The key feature of layering is to support the primary container color for light or dark mode. This produces absolute colors based on the `baseLayerLuminance` value, which sets the luminance for layer one. This is any value between 0 for black or 1 for white.
|
||||
|
||||
The difference between each layer is defined with `neutralFillLayerRestDelta`.
|
||||
|
||||
Layers are not stateful.
|
||||
|
||||
##### neutralFillLayer
|
||||
|
||||
The only layer recipe that's relative to the container color instead of absolute. The most common example of this is a Card, which will be one layer color lighter than its container.
|
||||
|
||||
##### neutralLayer1, neutralLayer2, neutralLayer3, and neutralLayer4
|
||||
|
||||
Absolute layer colors derived from and starting at `baseLayerLuminance`. Layer one is lightest and the values darken as the layer number increases.
|
||||
|
||||
##### neutralLayerCardContainer
|
||||
|
||||
A special layer to support experiences primarily built with cards, especially in light mode, so cards can be white and the container color can be one layer darker.
|
||||
|
||||
##### neutralLayerFloating
|
||||
|
||||
A special layer for floating layers, like flyouts or menus. It will be lighter than any other layers if possible, but will also be white in default light mode, as will neutral layer one.
|
||||
|
||||
#### Adaptive Color "Don'ts"
|
||||
|
||||
The adaptive color system lives entirely in JavaScript, emitting CSS custom properties for styling purposes where appropriate. This means that you should consider the CSS custom properties emitted by color Design Tokens to be immutable. If you declare the CSS custom property in CSS, the adaptive Color System is unable to know that has happened and components will render with incorrect colors, which can lead to accessibility issues. If you need to change the values for those CSS custom properties, set the value using the [DesignToken.setValueFor()](./design-tokens.md#setting-values) API.
|
||||
|
|
@ -1,193 +0,0 @@
|
|||
---
|
||||
id: high-contrast
|
||||
title: High Contrast in FAST
|
||||
sidebar_label: High Contrast
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/high-contrast.md
|
||||
description: High contrast mode uses the CSS media feature, forced-colors. When forced-colors is set to active, the user agent will apply a limited color palette to the component.
|
||||
keywords:
|
||||
- forced-colors
|
||||
- high contrast themes
|
||||
---
|
||||
|
||||
## Styling components using forced-colors.
|
||||
|
||||
High contrast mode uses the CSS media feature, [`forced-colors`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors). When `forced-colors` is set to `active`, the user agent will apply a limited color palette to the component.
|
||||
|
||||
|
||||
**Example:**
|
||||
|
||||
```css
|
||||
@media (forced-colors: active) {
|
||||
:host {
|
||||
background: ButtonFace;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
FAST has a [forcedColorsStylesheetBehavior](https://github.com/microsoft/fast/blob/master/packages/web-components/fast-foundation/src/utilities/match-media-stylesheet-behavior.ts) utility function that is used to construct `forced-colors` in a stylesheet. This function is passed to the `withBehavior` function from the `css` tagged template object.
|
||||
|
||||
:::note
|
||||
The reason for this behavior is to avoid the runtime cost of applying `forced-color` style rules when the UA does not match the `forced-colors` @media query. FAST exposes a behavior that conditionally adds and removes stylesheets based on this media query, so forced-colors' stylesheets can then be conditionally applied where necessary.
|
||||
:::
|
||||
|
||||
**Example**
|
||||
|
||||
```ts
|
||||
export const ComponentStyles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
forcedColorsStylesheetBehavior(
|
||||
css`
|
||||
:host {
|
||||
background: ButtonFace;
|
||||
}
|
||||
`
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
## System Color Keyword
|
||||
|
||||
In `forced-colors` mode, the colors on the component are reduced to a limited color palette chosen by the user. The [System Color keywords](https://developer.mozilla.org/en-US/docs/web/css/color_value#System_Colors) defined by the CSS Color Module Level 4 specification expose these user-chosen colors.
|
||||
|
||||
FAST provides a [`SystemColors`](https://github.com/microsoft/fast/blob/master/packages/utilities/fast-web-utilities/src/system-colors.ts) enum to use when setting the color value keywords in a `forced-colors` stylesheet.
|
||||
|
||||
**Example**
|
||||
```ts
|
||||
export const ComponentStyles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
forcedColorsStylesheetBehavior(
|
||||
css`
|
||||
:host {
|
||||
background: ${SystemColors.ButtonFace};
|
||||
}
|
||||
`
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
## Forced colors and Windows High Contrast themes
|
||||
|
||||
`forced-colors` works with Windows high contrast mode in Windows, located in Ease of Access within Settings. There are two default themes to test high contrast, `High Contrast Black` and `High Contrast White`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Here is a 1:1 map between the `forced-colors` keywords and Windows high contrast resource names.
|
||||
|
||||
| forced-colors | Windows |
|
||||
|-----------------------------|-----------------|
|
||||
| `CanvasText` | `Text` |
|
||||
| `LinkText` | `Hyperlinks` |
|
||||
| `GrayText` | `Disabled Text` |
|
||||
| `HighlightText` `Highlight` | `Selected Text` |
|
||||
| `ButtonText` `ButtonFace` | `Button Text` |
|
||||
| `Canvas` | `Background` |
|
||||
|
||||
## Quick demo
|
||||
|
||||
Here is a simple example of adding high contrast to style an accent button. It has selectors for rest, active, hover, focus, and disabled.
|
||||
|
||||
|
||||
|
||||
```ts
|
||||
export const AccentButtonStyles = css`
|
||||
:host([appearance="accent"]) {
|
||||
background: ${accentFillRest};
|
||||
color: ${foregroundOnAccentRest};
|
||||
}
|
||||
:host([appearance="accent"]:hover) {
|
||||
background: ${accentFillHover};
|
||||
}
|
||||
:host([appearance="accent"]:active) .control:active {
|
||||
background: ${accentFillActive};
|
||||
}
|
||||
:host([appearance="accent"]) .control:${focusVisible} {
|
||||
box-shadow: 0 0 0 calc(${focusStrokeWidth} * 1px) inset ${focusStrokeInner};
|
||||
}
|
||||
:host([appearance="accent"][disabled]) {
|
||||
opacity: ${disabledOpacity};
|
||||
background: ${accentFillRest};
|
||||
}
|
||||
`
|
||||
```
|
||||
|
||||
When high contrast is enabled, the system will try to apply the correct color. In the case of this accent button, the system is missing a few things. We do not have a background, `rest` and `hover` states are the same, `focus` is not following the button's `focus` design, and the `disabled` state is too dim.
|
||||
|
||||
|
||||
|
||||
To fix this, we will pass a [forcedColorsStylesheetBehavior](https://github.com/microsoft/fast/blob/master/packages/web-components/fast-foundation/src/utilities/match-media-stylesheet-behavior.ts) object to `withBehaviors`, using similar selectors, and setting property values with the `SystemColors` keyword.
|
||||
|
||||
```ts
|
||||
export const AccentButtonStyles = css`
|
||||
/* ... */
|
||||
`.withBehaviors(
|
||||
forcedColorsStylesheetBehavior(
|
||||
css`
|
||||
:host([appearance="accent"]) .control {
|
||||
forced-color-adjust: none;
|
||||
background: ${SystemColors.Highlight};
|
||||
color: ${SystemColors.HighlightText};
|
||||
}
|
||||
:host([appearance="accent"]) .control:hover,
|
||||
:host([appearance="accent"]:active) .control:active {
|
||||
background: ${SystemColors.HighlightText};
|
||||
border-color: ${SystemColors.Highlight};
|
||||
color: ${SystemColors.Highlight};
|
||||
}
|
||||
:host([appearance="accent"]) .control:${focusVisible} {
|
||||
border-color: ${SystemColors.ButtonText};
|
||||
box-shadow: 0 0 0 2px ${SystemColors.HighlightText} inset;
|
||||
}
|
||||
:host([appearance="accent"][disabled]),
|
||||
:host([appearance="accent"][disabled]) .control,
|
||||
:host([appearance="accent"][disabled]) .control:hover {
|
||||
background: ${SystemColors.ButtonFace};
|
||||
border-color: ${SystemColors.GrayText};
|
||||
color: ${SystemColors.GrayText};
|
||||
opacity: 1;
|
||||
}
|
||||
`
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
After adding `forced-colors` and applying `SystemColors` keywords, the accent button now uses `Highlight` as a background for its `rest` state. On the `hover` and `active` states, the background and color from the `rest` state are swapped. A double border treatment is applied when in the `focus` state, and the `disabled` has opacity set to 1 and uses the disabled color, `GrayText`, for color on the border and content.
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
[forced-color-adjust](https://www.w3.org/TR/css-color-adjust-1/#forced), controls whether the UA system theme color override, should be applied to an element and its descendants.
|
||||
The example is set to `none`, because we are overriding to remove the backplate on the text content in the control, that the UA sets on text elements.
|
||||
:::
|
||||
|
||||
### Further resources
|
||||
|
||||
**Color contrast comparison chart**
|
||||
|
||||
To help determine whether a pair of high contrast colors will meet a color luminosity contrast ratio of at least 10:1, this table uses the high contrast theme color resource names you see in Windows Ease of Access.
|
||||
|
||||
How to read this table:
|
||||
- <mark>YES</mark> - indicates that it is safe to assume this pair of colors will meet high contrast requirements, even in custom themes.
|
||||
- `YES*` - indicates that this specific pair of colors meets the high contrast requirements in both High Contrast Black and High Contrast White themes.
|
||||
- NO - indicates that you should never use this pair of colors as they do not meet high contrast requirements in High Contrast Black and High Contrast White themes.
|
||||
|
||||
| | Text | Hyperlink | Disabled Text | Selected Text (Foreground) | Selected Text (Background) | Button Text (Foreground) | Button Text (Background) | Background |
|
||||
|---------------------------------|------------------|------------------|------------------|----------------------------|----------------------------|--------------------------|--------------------------|------------------|
|
||||
| **Text** | NO | NO | NO | NO | NO | NO | <mark>YES</mark> | <mark>YES</mark> |
|
||||
| **Hyperlink** | NO | NO | NO | `YES*` | NO | NO | `YES*` | <mark>YES</mark> |
|
||||
| **Disabled Text** | NO | NO | NO | `YES*` | NO | NO | <mark>YES</mark> | <mark>YES</mark> |
|
||||
| **Selected Text (Foreground)** | NO | `YES*` | `YES* ` | NO | <mark>YES</mark> | `YES*` | NO | NO |
|
||||
| **Selected Text (Background)** | NO | NO | NO | <mark>YES</mark> | NO | NO | `YES*` | `YES*` |
|
||||
| **Button Text (Foreground)** | NO | NO | NO | `YES*` | NO | NO | <mark>YES</mark> | <mark>YES</mark> |
|
||||
| **Button Text (Background)** | <mark>YES</mark> | `YES*` | <mark>YES</mark> | NO | `YES*` | <mark>YES</mark> | NO | NO |
|
||||
| **Background** | <mark>YES</mark> | <mark>YES</mark> | <mark>YES</mark> | NO | `YES*` | <mark>YES</mark> | NO | NO |
|
||||
|
||||
|
||||
|
||||
### Microsoft Edge blog
|
||||
|
||||
Microsoft Edge blog has excellent and in-depth information on styling for Windows high contrast using forced-colors.
|
||||
[Styling for Windows high contrast with new standards for forced colors](https://blogs.windows.com/msedgedev/2020/09/17/styling-for-windows-high-contrast-with-new-standards-for-forced-colors/)
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
id: overview
|
||||
title: What is a Design System?
|
||||
sidebar_label: Overview
|
||||
custom_edit_url: https://github.com/microsoft/fast/edit/master/sites/website/src/docs/design-systems/overview.md
|
||||
description: A Design System can generally be thought of as a collection of resources for interactive media that promotes brand alignment.
|
||||
keywords:
|
||||
- design systems
|
||||
---
|
||||
|
||||
A Design System can be generally thought of as a collection of interactive media resources that promotes brand alignment. While that definition is intentionally broad, in UI development, Design Systems manifest as component libraries surrounded by usage guidance and design principles.
|
||||
|
||||
## How does FAST facilitate development of design systems?
|
||||
|
||||
FAST helps by both providing a highly configurable design system that you can drop into any app and by providing a set of building blocks you can use to construct your own design system from scratch, with very little work.
|
||||
|
||||
## A highly configurable design system
|
||||
|
||||
[FAST Frame](./fast-frame.md) is the name of our highly configurable design system. It's made up of a set of web components and accompanying design tokens. The visual design can be impacted in myriad ways using the exported [Design Tokens](./design-tokens.md), element templates and styles can be augmented or overridden, and shadow roots can be opened or closed as necessary for your application. If you’re looking to get up and running with FAST Web Components and the FAST Frame design system, [start here](./fast-frame.md).
|
||||
|
||||
### Design Tokens
|
||||
|
||||
Design Tokens are powerful tools that are used to express design abstractions like color, typography, spacing units, and other design-led values. FAST exposes powerful tools for creating and using Design Tokens for your Design System. FAST Frame leverages FAST's design tokens extensively. FAST Frame's use of design tokens is so extensive that you might be able to create your own design system simply by modifying the existing tokens. Of course, you can always create your own tokens and even base your tokens on compositions of existing tokens. To learn more [see our documentation on design tokens](./design-tokens.md).
|
||||
|
||||
## Your own design system based on FAST components
|
||||
|
||||
If you need more control than you can get through modifying design token values or recipes, you can wrap your styling around the foundation components. By exporting raw JavaScript Custom Element classes, `@microsoft/fast-foundation` handles the business-logic driving a large catalog of UI components. These Custom Element classes can be taken as-is and composed with your templates and styles to match your application or library requirements, reducing the development time and overhead of creating your own design system. For example, rather than implementing a Tree View from scratch, you can use the Foundation Tree View class and simply compose it with your own CSS to create a reusable web component as part of your own system.
|
||||
|
|
@ -8,70 +8,7 @@ keywords:
|
|||
- web components
|
||||
---
|
||||
|
||||
import logo from "../../site-utilities/statics/assets/fast-logo.png";
|
||||
import { DocCardList, DocCardItem } from "@site/src/custom-components/CustomDocCard";
|
||||
|
||||
<div
|
||||
style={{
|
||||
margin: "20px",
|
||||
display: "flex",
|
||||
justifyContent: "center",
|
||||
alignItems: "center",
|
||||
}}
|
||||
>
|
||||
<img src={logo} alt="logo" style={{ width: "100px", height: "100px" }} />
|
||||
</div>
|
||||
<div
|
||||
style={{
|
||||
marginBottom: "80px",
|
||||
display: "flex",
|
||||
justifyContent: "center",
|
||||
alignItems: "center",
|
||||
}}
|
||||
>
|
||||
<h2>
|
||||
Welcome to the <i>FAST</i> documentation!
|
||||
</h2>
|
||||
</div>
|
||||
|
||||
## Where should I start?
|
||||
|
||||
Pick the statement you most identify with, and follow the links where they lead. Come back and explore another topic at any time. Or, [click here](#what-is-fast) to learn more about FAST.
|
||||
|
||||
<DocCardList>
|
||||
<DocCardItem
|
||||
href="./components/getting-started"
|
||||
title="I want ready-made components"
|
||||
description="The @microsoft/fast-components library contains Web Components built on top of our standard component and design system foundation. Jump to the component docs."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./fast-element/getting-started"
|
||||
title="I want to build my own components"
|
||||
description="The fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. Jump to the fast-element docs."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./design-systems/overview"
|
||||
title="I want to build my own design system"
|
||||
description="FAST Frame is the name of our highly configurable design system. It is made up of a set of Web Components and accompanying design tokens. Jump to the design system docs."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./integrations/introduction"
|
||||
title="I want to integrate FAST"
|
||||
description="FAST libraries can be used on their own to build modern web sites and apps, but they can also be used with a wide variety of existing technologies. Jump to the integration docs."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./resources/cheat-sheet"
|
||||
title="I want to look at a quick reference"
|
||||
description="A quick reference for FAST packages, using/building components, design systems/tokens, and how to make contributions to FAST. Jump to the cheat sheet doc."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./community/contributor-guide"
|
||||
title="I want to contribute to FAST"
|
||||
description="To get started as a contributor, read our code of conduct and contributor guides. Join our Discord server and look at good first issues. Jump to the contributor guide docs."
|
||||
/>
|
||||
</DocCardList>
|
||||
|
||||
<hr />
|
||||
# Welcome to the <i>FAST</i> documentation!
|
||||
|
||||
## What is FAST?
|
||||
|
||||
|
|
@ -159,45 +96,3 @@ flowchart
|
|||
</div>
|
||||
|
||||
`@microsoft/fast-element` provides a thin layer of opinion on top of Web Components, lifting the level of abstraction just enough to make it easier and faster to build components. `@microsoft/fast-element` helps by providing attribute/property syncing, rich Model-View-ViewModel (MVVM), efficient template rendering/update, style composition, and much more. The entire `@microsoft/fast-element` library, *without* tree-shaking, is around 10kb minified and GZipped. It was designed for tree-shaking from the beginning, so any feature you don't use when building a component will be removed during build, allowing for highly efficient optimized payloads as small as 4.5k.
|
||||
|
||||
<DocCardList>
|
||||
<DocCardItem
|
||||
href="./resources/glossary"
|
||||
title="Glossary"
|
||||
description="A glossary of terms, which includes Design System, Design Token, ES2015, Evergreen Browser, Houdini, Polyfill, Time to Interactive (TTI), Transpiler, and Web Components."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="./resources/faq"
|
||||
title="FAQ"
|
||||
description="A list of frequently asked questions (e.g. What are Web Components, Why should I choose Web Components over [other JavaScript framework], etc)."
|
||||
/>
|
||||
</DocCardList>
|
||||
|
||||
<hr />
|
||||
|
||||
## Joining the community
|
||||
|
||||
We look forward to building an amazing open source community with you.
|
||||
|
||||
<DocCardList>
|
||||
<DocCardItem
|
||||
href="https://discord.gg/FcSNfg4"
|
||||
title="Discord"
|
||||
description="Join our active community on Discord. Follow the latest updates and contributions, ask questions, give feedback, or keep up on our reading list."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="https://github.com/Microsoft/fast/issues/new/choose"
|
||||
title="GitHub"
|
||||
description="Explore the FAST repository on GitHub and try out our components, utilities, and tools. Or, mix-and-match with your own solutions."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="https://twitter.com/FAST_UI"
|
||||
title="Twitter"
|
||||
description="Follow along as we share out the latest happenings on Twitter. You will find important updates, announcements, and sneak peeks."
|
||||
/>
|
||||
<DocCardItem
|
||||
href="https://medium.com/fast-design"
|
||||
title="Medium"
|
||||
description="Read articles published on our official FAST blog. Like, comment, share, and bookmark content. Sign up for our monthly newsletter, FAST Monthly."
|
||||
/>
|
||||
</DocCardList>
|
||||
|
|
|
|||
|
|
@ -36,145 +36,6 @@ import { FASTElement } from "@microsoft/fast-element";
|
|||
|
||||
---
|
||||
|
||||
### [@microsoft/fast-foundation](../introduction.md/#how-can-fast-help-me)
|
||||
|
||||
**This package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems.**
|
||||
|
||||
* Exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior.
|
||||
* Use this library when you want to create something like Google's Material Design or Bootstrap.
|
||||
|
||||
**Example**
|
||||
|
||||
```ts
|
||||
import {
|
||||
Button as FoundationButton,
|
||||
buttonTemplate as template,
|
||||
} from "@microsoft/fast-foundation";
|
||||
import { css } from "@microsoft/fast-element";
|
||||
|
||||
export class MyButton extends FoundationButton {
|
||||
...
|
||||
}
|
||||
|
||||
export const buttonStyles = css`
|
||||
:host {
|
||||
background-color: azure;
|
||||
}
|
||||
`;
|
||||
|
||||
export const myButton = MyButton.compose({
|
||||
baseName: "button",
|
||||
baseClass: FoundationButton,
|
||||
template,
|
||||
styles: buttonStyles,
|
||||
shadowOptions: {
|
||||
delegatesFocus: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [@microsoft/fast-components](../components/getting-started.md)
|
||||
|
||||
**The FAST component library and visual system [FAST Frame](../design-systems/fast-frame.md), which implements fast-foundation.**
|
||||
|
||||
* Assembles the building blocks of `@microsoft/fast-foundation` to create its component set.
|
||||
* Use this library when you want to integrate [FAST Components](#using-components) into an existing site or app.
|
||||
|
||||
To install the components, use either `npm` or `yarn`:
|
||||
|
||||
```shell
|
||||
npm install --save @microsoft/fast-components
|
||||
```
|
||||
|
||||
```shell
|
||||
yarn add @microsoft/fast-components
|
||||
```
|
||||
|
||||
To use a component as a custom element in HTML, the custom element must be registered.
|
||||
|
||||
**Example**
|
||||
|
||||
```ts
|
||||
import {
|
||||
fastButton,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton() // custom element registration
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
## [Using components](../components/getting-started.md)
|
||||
|
||||
### Setup
|
||||
|
||||
**Example**
|
||||
|
||||
To register design system components:
|
||||
|
||||
```ts
|
||||
import {
|
||||
fastButton,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem()
|
||||
.register(
|
||||
fastButton() // custom element registration
|
||||
);
|
||||
```
|
||||
|
||||
Or, register all system components:
|
||||
|
||||
```ts
|
||||
import {
|
||||
allComponents,
|
||||
provideFASTDesignSystem
|
||||
} from "@microsoft/fast-components";
|
||||
|
||||
provideFASTDesignSystem().register(allComponents);
|
||||
```
|
||||
|
||||
With the components registered, add any component to the HTML.
|
||||
|
||||
**Example**
|
||||
|
||||
```html
|
||||
<fast-button>Hello world</fast-button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Launch our [Component Explorer](https://explore.fast.design/) for a comprehensive list of FAST Components.
|
||||
|
||||
---
|
||||
### [Integrations](../integrations/introduction.md)
|
||||
|
||||
FAST libraries can also be used in combination with a wide variety of existing technologies:
|
||||
|
||||
- [Angular](../integrations/angular.md)
|
||||
- [ASP.NET](../integrations/aspnet.md)
|
||||
- [Aurelia](../integrations/aurelia.md)
|
||||
- [Blazor](../integrations/blazor.md)
|
||||
- [Ember](../integrations/ember.md)
|
||||
- [React](../integrations/react.md)
|
||||
- [Rollup](../integrations/rollup.md)
|
||||
- [Svelte](../integrations/svelte.md)
|
||||
- [Vite](../integrations/vite.md)
|
||||
- [Vue](../integrations/vue.md)
|
||||
- [Webpack](../integrations/webpack.md)
|
||||
|
||||
Not seeing an integration for your preferred technology? Open an issue on [GitHub](https://github.com/microsoft/fast/issues/new/choose).
|
||||
|
||||
---
|
||||
|
||||
## [Building components](../fast-element/getting-started.md)
|
||||
|
||||
There are two main approaches to building a component:
|
||||
|
|
@ -585,107 +446,6 @@ class RandomWidth extends CSSDirective {
|
|||
|
||||
---
|
||||
|
||||
## Design system
|
||||
|
||||
### [Creating a design system](../design-systems/creating-a-component-library.md#defining-a-design-system)
|
||||
|
||||
1. Start with the base components defined in `@microsoft/fast-foundation` and compose them with your own styles.
|
||||
|
||||
**Example**
|
||||
|
||||
```ts
|
||||
import {
|
||||
Button,
|
||||
buttonTemplate as template,
|
||||
} from "@microsoft/fast-foundation";
|
||||
import { buttonStyles as styles } from "./special-button.styles";
|
||||
|
||||
export const specialButton = Button.compose({
|
||||
baseName: "button",
|
||||
template,
|
||||
styles,
|
||||
shadowOptions: {
|
||||
delegatesFocus: true,
|
||||
},
|
||||
});
|
||||
|
||||
export const buttonStyles = styles;
|
||||
```
|
||||
|
||||
2. Export a `provider function` for your community to use in setting everything up.
|
||||
|
||||
**Example**
|
||||
|
||||
```ts
|
||||
export function provideSpecialDesignSystem(element?: HTMLElement): DesignSystem {
|
||||
return DesignSystem.getOrCreate(element).withPrefix("special");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### [Design tokens](../design-systems/design-tokens.md)
|
||||
|
||||
**Example: [Creating a token](../design-systems/design-tokens.md#create-a-token)**
|
||||
|
||||
```ts
|
||||
import { DesignToken } from "@microsoft/fast-foundation";
|
||||
|
||||
// create a design token
|
||||
export const specialColor = DesignToken.create<string>("special-color");
|
||||
```
|
||||
|
||||
**Example: [Using design tokens in CSS](../design-systems/design-tokens.md#using-design-tokens-in-css)**
|
||||
|
||||
```ts
|
||||
// use the design token to build styles
|
||||
const styles = css`
|
||||
:host {
|
||||
background: ${specialColor};
|
||||
}
|
||||
`;
|
||||
```
|
||||
|
||||
**Example: [Setting values](../design-systems/design-tokens.md#setting-values)**
|
||||
```ts
|
||||
// change the value for a given element
|
||||
specialColor.setValueFor(ancestor, "#FFF");
|
||||
specialColor.setValueFor(descendent, "#000");
|
||||
```
|
||||
|
||||
**Example: [Getting values](../design-systems/design-tokens.md#getting-values)**
|
||||
```ts
|
||||
// get the value
|
||||
specialColor.getValueFor(ancestor); // "#FFF"
|
||||
specialColor.getValueFor(descendent); // "#000"
|
||||
```
|
||||
|
||||
**Example: [Deleting values](../design-systems/design-tokens.md#deleting-values)**
|
||||
```ts
|
||||
// unset the value (inherits from ancestor)
|
||||
specialColor.deleteValueFor(descendent);
|
||||
specialColor.getValueFor(descendent); // "#FFF"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Configuring a FAST design token
|
||||
|
||||
FAST exposes non-color related [Design Tokens](../design-systems/fast-frame.md#fast-frame-design-tokens) that can be used to configure components stylistically. For Design Tokens related to color, see the [adaptive color system](../design-systems/fast-frame.md/#adaptive-color-system).
|
||||
|
||||
**Example: Changing the value for the `typeRampBaseFontSize` design token**
|
||||
|
||||
```ts
|
||||
import { typeRampBaseFontSize } from "@microsoft/fast-components";
|
||||
import { FASTElement } from '@microsoft/fast-element';
|
||||
|
||||
const myElement = document.querySelector("my-element") as FASTElement;
|
||||
|
||||
typeRampBaseFontSize.setValueFor(myElement, "20px");
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## [Contributing to FAST](../community/join.md)
|
||||
|
||||
**Connect with us**:
|
||||
|
|
@ -715,17 +475,6 @@ When contributing to the FAST repository, please follow the standards defined in
|
|||
|
||||
---
|
||||
|
||||
### [Contributing to `fast-components`](../community/contributor-guide.md/#developing-in-fast-components)
|
||||
|
||||
```shell
|
||||
cd packages/web-components/fast-components
|
||||
yarn start
|
||||
```
|
||||
|
||||
[Storybook](https://storybook.js.org/) will open in a browser window at `localhost:6006`.
|
||||
|
||||
---
|
||||
|
||||
### [Contributing to documentation](../community/writing-documentation.md)
|
||||
|
||||
```shell
|
||||
|
|
|
|||
|
|
@ -45,6 +45,12 @@ function identifyPackage(path) {
|
|||
return "";
|
||||
}
|
||||
|
||||
function updateContentForMdx(content) {
|
||||
content = content.replace("{", "{");
|
||||
content = content.replace("}", "}");
|
||||
return content;
|
||||
}
|
||||
|
||||
async function safeCopy(source, dest) {
|
||||
if (!fs.existsSync(source)) {
|
||||
return;
|
||||
|
|
@ -326,6 +332,7 @@ async function buildAPIMarkdown() {
|
|||
}
|
||||
|
||||
if (!skip) {
|
||||
line = updateContentForMdx(line);
|
||||
output.push(line);
|
||||
}
|
||||
});
|
||||
|
|
|
|||
|
|
@ -0,0 +1,79 @@
|
|||
import React from 'react';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
export default function () {
|
||||
return (
|
||||
<Layout title="web components" description="FAST web components">
|
||||
<div
|
||||
style={{
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
fontSize: '20px',
|
||||
padding: '20px 40px',
|
||||
alignItems: 'center'
|
||||
}}>
|
||||
<div
|
||||
style={{
|
||||
width: '1000px'
|
||||
}}
|
||||
>
|
||||
<h2>Introduction</h2>
|
||||
|
||||
<p>FAST is dedicated to providing support for native Web Components and modern Web Standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.</p>
|
||||
|
||||
<ul>
|
||||
<li>Create reusable UI components with <code>@microsoft/fast-element</code>, all based on W3C Web Component standards.</li>
|
||||
<li>Integrate FAST Web Components with any library, framework, or build system. You can adopt incrementally without re-writing your existing systems.</li>
|
||||
</ul>
|
||||
|
||||
<p>For an in-depth explanation of FAST <a href="https://www.fast.design/docs/introduction/">see our docs introduction</a></p>
|
||||
|
||||
<hr />
|
||||
|
||||
<h2>Packages</h2>
|
||||
|
||||
<h3><code>@microsoft/fast-element</code></h3>
|
||||
|
||||
<p>The <code>@microsoft/fast-element</code> library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with <code>@microsoft/fast-element</code> see <a href="https://fast.design/docs/fast-element/getting-started">the Getting Started guide</a>.</p>
|
||||
|
||||
<h3><code>@fluentui/web-components</code></h3>
|
||||
|
||||
<p><code>@fluentui/web-components</code> is a library of Web Components based on the Fluent design language.</p>
|
||||
|
||||
<p>The source for <code>@fluentui/web-components</code> is hosted in [the Fluent UI monorepo](https://github.com/microsoft/fluentui/tree/master/packages/web-components).</p>
|
||||
|
||||
<hr />
|
||||
|
||||
<h2>Getting Started</h2>
|
||||
|
||||
<p>We hope you're excited by the possibilities that FAST presents. But, you may be wondering where to start. Here are a few statements that describe various members of our community. We recommend that you pick the statement you most identify with and follow the links where they lead. You can always come back and explore another topic at any time.</p>
|
||||
|
||||
<ul>
|
||||
<li>"I just want ready-made components!" - <a href="https://docs.microsoft.com/en-us/fluent-ui/web-components/">Check out the FluentUI Web Components.</a></li>
|
||||
<li>"I want to build my own components." - <a href="https://fast.design/docs/fast-element/getting-started">Jump to the fast-element docs.</a></li>
|
||||
<li>"I need to integrate FAST with another framework or build system." - <a href="https://fast.design/docs/integrations/introduction">Jump to the integration docs.</a></li>
|
||||
<li>"I want to look at a quick reference." - <a href="https://fast.design/docs/resources/cheat-sheet">Jump to the Cheat Sheet</a></li>
|
||||
</ul>
|
||||
|
||||
<hr />
|
||||
|
||||
<h2>Joining the Community</h2>
|
||||
|
||||
<p>Looking to get answers to questions or engage with us in realtime? Our community is most active <a href="https://discord.gg/FcSNfg4">on Discord</a>. Submit requests and issues on <a href="https://github.com/Microsoft/fast/issues/new/choose">GitHub</a>, or join us by contributing on <a href="https://github.com/Microsoft/fast/labels/community:good-first-issue">some good first issues via GitHub</a>.</p>
|
||||
|
||||
<p>Get started here with the <a href="https://www.fast.design/docs/community/contributor-guide">Contributor Guide</a>.</p>
|
||||
|
||||
<p>We look forward to building an amazing open source community with you!</p>
|
||||
|
||||
<h2>Contact</h2>
|
||||
|
||||
<ul>
|
||||
<li>Join the community and chat with us in real-time on <a href="https://discord.gg/FcSNfg4">Discord</a>.</li>
|
||||
<li>Submit requests and issues on <a href="https://github.com/Microsoft/fast/issues/new/choose">GitHub</a>.</li>
|
||||
<li>Contribute by helping out on some of our recommended first issues on <a href="https://github.com/Microsoft/fast/labels/community:good-first-issue">GitHub</a>.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
import React from "react";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { findFirstCategoryLink, useDocById } from "@docusaurus/theme-common";
|
||||
import clsx from "clsx";
|
||||
import isInternalUrl from "@docusaurus/isInternalUrl";
|
||||
import { translate } from "@docusaurus/Translate";
|
||||
import styles from "./styles.module.css";
|
||||
|
||||
function CardContainer({ href, children }) {
|
||||
const className = clsx(
|
||||
"card margin-bottom--lg padding--lg",
|
||||
styles.cardContainer,
|
||||
href && styles.cardContainerLink
|
||||
);
|
||||
return href ? (
|
||||
<Link href={href} className={className}>
|
||||
{children}
|
||||
</Link>
|
||||
) : (
|
||||
<div className={className}>{children}</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function CardLayout({ href, icon, title, description }) {
|
||||
return (
|
||||
<CardContainer href={href}>
|
||||
<h2 className={clsx("text--truncate", styles.cardTitle)} title={title}>
|
||||
{icon} {title}
|
||||
</h2>
|
||||
<div
|
||||
className={clsx("text", styles.cardDescription, styles.lineClamp)}
|
||||
title={description}
|
||||
>
|
||||
{description}
|
||||
</div>
|
||||
</CardContainer>
|
||||
);
|
||||
}
|
||||
|
||||
function CardCategory({ item }) {
|
||||
const href = findFirstCategoryLink(item);
|
||||
return (
|
||||
<CardLayout
|
||||
href={href}
|
||||
icon=""
|
||||
title={item.label}
|
||||
description={translate(
|
||||
{
|
||||
message: item.customProps?.description || "{count} items",
|
||||
id: "theme.docs.DocCard.categoryDescription",
|
||||
description:
|
||||
"The default description for a category card in the generated index about how many items this category includes",
|
||||
},
|
||||
{
|
||||
count: item.items.length,
|
||||
}
|
||||
)}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
function CardLink({ item }) {
|
||||
const icon = isInternalUrl(item.href) ? "" : "🔗";
|
||||
const doc = useDocById(item.docId ?? undefined);
|
||||
return (
|
||||
<CardLayout
|
||||
href={item.href}
|
||||
icon={icon}
|
||||
title={item.label}
|
||||
description={item.customProps?.description || doc?.description}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
export default function DocCard({ item }) {
|
||||
switch (item.type) {
|
||||
case "link":
|
||||
return <CardLink item={item} />;
|
||||
|
||||
case "category":
|
||||
return <CardCategory item={item} />;
|
||||
|
||||
default:
|
||||
throw new Error(`unknown item type ${JSON.stringify(item)}`);
|
||||
}
|
||||
}
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
/**
|
||||
* Copyright (c) Facebook, Inc. and its affiliates.
|
||||
*
|
||||
* This source code is licensed under the MIT license found in the
|
||||
* LICENSE file in the root directory of this source tree.
|
||||
*/
|
||||
|
||||
.cardContainer {
|
||||
height: 11rem;
|
||||
color: var(--ifm-color-emphasis-800);
|
||||
--ifm-link-color: var(--ifm-color-emphasis-800);
|
||||
--ifm-link-hover-color: var(--ifm-color-primary);
|
||||
--ifm-link-hover-decoration: none;
|
||||
|
||||
/* box-shadow: var(--ifm-global-shadow-lw); */
|
||||
box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
|
||||
border: 1px solid var(--ifm-color-emphasis-200);
|
||||
transition: box-shadow var(--ifm-transition-fast) ease,
|
||||
background-color var(--ifm-transition-fast) ease;
|
||||
}
|
||||
|
||||
.cardContainer.cardContainerLink:hover {
|
||||
/* box-shadow: var(--ifm-global-shadow-md); */
|
||||
box-shadow: 0 4px 8px 0 rgb(0 0 0 / 20%);
|
||||
}
|
||||
|
||||
[data-theme='dark'] .cardContainer.cardContainerLink:hover {
|
||||
--ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
|
||||
}
|
||||
|
||||
.cardContainer:not(.cardContainerLink) {
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
.cardTitle {
|
||||
font-size: 1.2rem;
|
||||
min-height: 1.2rem;
|
||||
}
|
||||
|
||||
.cardDescription {
|
||||
font-size: 0.8rem;
|
||||
min-height: 0.8rem;
|
||||
}
|
||||
|
||||
.lineClamp {
|
||||
display: -webkit-box;
|
||||
-webkit-line-clamp: 3;
|
||||
-webkit-box-orient: vertical;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
|
@ -1,141 +0,0 @@
|
|||
import React from "react";
|
||||
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
|
||||
import Link from "@docusaurus/Link";
|
||||
import Translate from "@docusaurus/Translate";
|
||||
import {
|
||||
useActivePlugin,
|
||||
useDocVersionSuggestions,
|
||||
} from "@docusaurus/plugin-content-docs/client";
|
||||
import {
|
||||
ThemeClassNames,
|
||||
useDocsPreferredVersion,
|
||||
useDocsVersion,
|
||||
} from "@docusaurus/theme-common";
|
||||
import clsx from "clsx";
|
||||
|
||||
function UnreleasedVersionLabel({ siteTitle, versionMetadata }) {
|
||||
return (
|
||||
<Translate
|
||||
id="theme.docs.versions.unreleasedVersionLabel"
|
||||
description="The label used to tell the user that he's browsing an unreleased doc version"
|
||||
values={{
|
||||
siteTitle,
|
||||
versionLabel: <b>{versionMetadata.label}</b>,
|
||||
}}
|
||||
>
|
||||
{"This is unreleased documentation for {siteTitle} {versionLabel} version."}
|
||||
</Translate>
|
||||
);
|
||||
}
|
||||
|
||||
function UnmaintainedVersionLabel({ siteTitle, versionMetadata }) {
|
||||
return (
|
||||
<Translate
|
||||
id="theme.docs.versions.unmaintainedVersionLabel"
|
||||
description="The label used to tell the user that he's browsing an unmaintained doc version"
|
||||
values={{
|
||||
siteTitle,
|
||||
versionLabel: <b>{versionMetadata.label}</b>,
|
||||
}}
|
||||
>
|
||||
{
|
||||
"This documentation refers to the {versionLabel} of FAST’s packages, which include versions below @microsoft/fast-element@2.0.0 and @microsoft/fast-foundation@3.0.0."
|
||||
}
|
||||
</Translate>
|
||||
);
|
||||
}
|
||||
|
||||
const BannerLabelComponents = {
|
||||
unreleased: UnreleasedVersionLabel,
|
||||
unmaintained: UnmaintainedVersionLabel,
|
||||
};
|
||||
|
||||
function BannerLabel(props) {
|
||||
const BannerLabelComponent = BannerLabelComponents[props.versionMetadata.banner];
|
||||
return <BannerLabelComponent {...props} />;
|
||||
}
|
||||
|
||||
function LatestVersionSuggestionLabel({ versionLabel, to, onClick }) {
|
||||
return (
|
||||
<Translate
|
||||
id="theme.docs.versions.latestVersionSuggestionLabel"
|
||||
description="The label used to tell the user to check the latest version"
|
||||
values={{
|
||||
versionLabel,
|
||||
latestVersionLink: (
|
||||
<b>
|
||||
<Link to={to} onClick={onClick}>
|
||||
<Translate
|
||||
id="theme.docs.versions.latestVersionLinkLabel"
|
||||
description="The label used for the latest version suggestion link label"
|
||||
>
|
||||
latest version
|
||||
</Translate>
|
||||
</Link>
|
||||
</b>
|
||||
),
|
||||
}}
|
||||
>
|
||||
{
|
||||
"For up-to-date documentation, see the {latestVersionLink} ({versionLabel})."
|
||||
}
|
||||
</Translate>
|
||||
);
|
||||
}
|
||||
|
||||
function DocVersionBannerEnabled({ className, versionMetadata }) {
|
||||
const {
|
||||
siteConfig: { title: siteTitle },
|
||||
} = useDocusaurusContext();
|
||||
const { pluginId } = useActivePlugin({
|
||||
failfast: true,
|
||||
});
|
||||
|
||||
const getVersionMainDoc = version =>
|
||||
version.docs.find(doc => doc.id === version.mainDocId);
|
||||
|
||||
const { savePreferredVersionName } = useDocsPreferredVersion(pluginId);
|
||||
const { latestDocSuggestion, latestVersionSuggestion } = useDocVersionSuggestions(
|
||||
pluginId
|
||||
); // Try to link to same doc in latest version (not always possible), falling
|
||||
// back to main doc of latest version
|
||||
|
||||
const latestVersionSuggestedDoc =
|
||||
latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
|
||||
return (
|
||||
<div
|
||||
className={clsx(
|
||||
className,
|
||||
ThemeClassNames.docs.docVersionBanner,
|
||||
"alert alert--warning margin-bottom--md"
|
||||
)}
|
||||
role="alert"
|
||||
>
|
||||
<div>
|
||||
<BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
|
||||
</div>
|
||||
<div className="margin-top--md">
|
||||
<LatestVersionSuggestionLabel
|
||||
versionLabel={latestVersionSuggestion.label}
|
||||
to={latestVersionSuggestedDoc.path}
|
||||
onClick={() => savePreferredVersionName(latestVersionSuggestion.name)}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export default function DocVersionBanner({ className }) {
|
||||
const versionMetadata = useDocsVersion();
|
||||
|
||||
if (versionMetadata.banner) {
|
||||
return (
|
||||
<DocVersionBannerEnabled
|
||||
className={className}
|
||||
versionMetadata={versionMetadata}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
Некоторые файлы не были показаны из-за слишком большого количества измененных файлов Показать больше
Загрузка…
Ссылка в новой задаче