From 4291216c007973cdba6bdfbd3a6f52761bf05a14 Mon Sep 17 00:00:00 2001 From: Rob Eisenberg Date: Thu, 26 May 2022 16:13:20 -0400 Subject: [PATCH] docs: update a few readme files (#6035) * docs: update a few readme files * Change files Co-authored-by: EisenbergEffect --- README.md | 45 ++++++++++++------- ...-368645c9-4e93-418a-83a7-73d35dad4c33.json | 7 +++ packages/web-components/README.md | 31 ++++++++----- packages/web-components/fast-router/README.md | 35 ++------------- 4 files changed, 59 insertions(+), 59 deletions(-) create mode 100644 change/@microsoft-fast-router-368645c9-4e93-418a-83a7-73d35dad4c33.json diff --git a/README.md b/README.md index 4ed62a6d48c..6afcb2035d3 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,8 @@ [![Validate PRs](https://github.com/microsoft/fast/actions/workflows/ci-validate-pr.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/ci-validate-pr.yml) [![Validate Platforms/Browsers](https://github.com/microsoft/fast/actions/workflows/ci-validate-platforms.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/ci-validate-platforms.yml) -[![Deploy Documentation (staging)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-staging.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-staging.yml) -[![Deploy Documentation (production)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-production.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-production.yml) +[![Deploy Documentation](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-production.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-www-production.yml) [![Deploy CDN](https://github.com/microsoft/fast/actions/workflows/cd-deploy-cdn.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-cdn.yml) -[![Deploy Component Explorer](https://github.com/microsoft/fast/actions/workflows/cd-deploy-explore-staging.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-explore-staging.yml) -[![Deploy Color Explorer](https://github.com/microsoft/fast/actions/workflows/cd-deploy-color-staging.yml/badge.svg)](https://github.com/microsoft/fast/actions/workflows/cd-deploy-color-staging.yml) [![Discord](https://img.shields.io/badge/chat%20on-discord-7289da.svg)](https://discord.gg/FcSNfg4) [![Twitter](https://img.shields.io/twitter/follow/fast_ui.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=fast_ui) @@ -32,10 +29,12 @@ FAST is a collection of technologies built on Web Components and modern Web Stan **TL;DR** -* Create reusable UI components based on web component standards. -* Use our standard library of pre-built web components in your apps. -* Build your own design system without re-implementing component logic. -* Integrate with any front-end framework or build system. +* Create reusable UI components with `@microsoft/fast-element`, all based on W3C Web Component standards. +* Use our `@microsoft/fast-foundation` library to rapidly build [W3C OpenUI-based](https://open-ui.org/) design systems without re-implementing component logic. +* Leverage modern, W3C standards-based SSR for Web Components by plugging in `@microsoft/fast-ssr`. +* Bring all the pieces together to build SPAs and rich experiences with our Web Components router by installing `@microsoft/fast-router`. +* React users can drop in `@microsoft/fast-react-wrapper` to turn any Web Component into a native React component. +* Integrate FAST Web Components with any library, framework, or build system. You can adopt incrementally without re-writing your existing systems. For an in-depth explanation of FAST [see our docs introduction](https://www.fast.design/docs/introduction/). @@ -57,6 +56,20 @@ The `@microsoft/fast-foundation` package is a library of Web Component classes, This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations. +### `@microsoft/fast-ssr` + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-ssr.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-ssr) + +The `@microsoft/fast-ssr` package contains a NodeJS solution for rendering FAST templates and components. While primarily intended for supporting server-side rendering (SSR) scenarios, it also allows FAST to be used as a general purpose HTML templating solution. + +### `@microsoft/fast-router` + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-router) + +The `@microsoft/fast-router` package contains a history-based navigation and routing solution designed around Web Components. By using `fast-router`, you can create multi-page and full application experiences. The router works with any Web Components, but has special support for Web Components built on FAST. + ### `@fluentui/web-components` [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -64,18 +77,22 @@ This package does not export Web Components registered as [custom elements](http `@fluentui/web-components` is a library of Web Components that *composes* `@microsoft/fast-foundation`. `@fluentui/web-components` makes use of different stylesheets and may include components that specifically support Microsoft's Fluent design language. -The source for `@fluentui/web-components` is hosted in [the Fluent UI monorepo](https://github.com/microsoft/fluentui/tree/master/packages/web-components). +The Fluent UI Web Components are built on `@microsoft/fast-element` and `@microsoft/fast-foundation`. The source for `@fluentui/web-components` is hosted in [the Fluent UI monorepo](https://github.com/microsoft/fluentui/tree/master/packages/web-components). ## Getting Started 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. +* "I just want ready-made components!" + * [Check out the FluentUI Web Components.](https://docs.microsoft.com/en-us/fluent-ui/web-components/) * "I want to build my own design system." * [Jump to the design system docs.](https://fast.design/docs/design-systems/overview) * "I want to build my own components." * [Jump to the fast-element docs.](https://fast.design/docs/fast-element/getting-started) * "I need to integrate FAST with another framework or build system." * [Jump to the integration docs.](https://fast.design/docs/integrations/introduction) +* "I want to look at a quick reference." + * [Jump to the Cheat Sheet](https://fast.design/docs/resources/cheat-sheet) ## Joining the Community @@ -96,15 +113,11 @@ This principle of being unopinionated manifests in several important ways includ * A flat component architecture that lets you compose what you need without struggling with rigid patterns and complex objects. * Separating base components from styles and design systems to support multiple implementations without re-writing or duplicating styles. Use the design system to customize existing styled components, or build your own styles, with your design system, without having to rebuild or duplicate the base components. * Framework agnostic tooling that lets you use our development tools with any view framework. -* The ability to replace almost any FAST package with your package of choice. Get started with our animation package and add more as you need them. Alternatively, use our suite of packages to build your next project from the ground up; it's your call. - -### UI development and style guide tools - -When developing components and views, excellent development tooling can make all the difference. FAST offers development and style guide tools that work with FAST components, components from other frameworks, or your components. +* The ability to replace almost any FAST package with your package of choice. Just use one package or leverage our entire suite of packages to build your next project from the ground up; it's your call. -Try out component properties with an auto-generated property UI, get a live preview of the code based on any property’s configuration, preview localization (RTL/LTR) and themes, and preview component compositing with a transparency grid. +### Tooling -Also, we built FAST development tools from re-usable packages, so if you have special needs, you can build your tools from the same shared libraries. +Leverage our (upcoming!) FAST CLI to accelerate your design or development workflow. You can create new projects from scratch, create design systems, and add or customize from dozens of components in our foundation library. ### Bring your design system diff --git a/change/@microsoft-fast-router-368645c9-4e93-418a-83a7-73d35dad4c33.json b/change/@microsoft-fast-router-368645c9-4e93-418a-83a7-73d35dad4c33.json new file mode 100644 index 00000000000..7a43aa39f75 --- /dev/null +++ b/change/@microsoft-fast-router-368645c9-4e93-418a-83a7-73d35dad4c33.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "docs: update a few readme files", + "packageName": "@microsoft/fast-router", + "email": "roeisenb@microsoft.com", + "dependentChangeType": "none" +} diff --git a/packages/web-components/README.md b/packages/web-components/README.md index baf9b3da1c6..3713906e648 100644 --- a/packages/web-components/README.md +++ b/packages/web-components/README.md @@ -2,32 +2,41 @@ Our web component packages. -## fast-element +## `@microsoft/fast-element` [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-element.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-element) -The `fast-element` library is a lightweight means to easily building 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 `fast-element` see [the Getting Started guide](https://fast.design/docs/fast-element/getting-started). +The `@microsoft/fast-element` 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 `@microsoft/fast-element` see [the Getting Started guide](https://fast.design/docs/fast-element/getting-started). -## fast-foundation +## `@microsoft/fast-foundation` [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-foundation) -The `fast-foundation` package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems (e.g. Fluent Design, Material Design, etc.). The exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior. +The `@microsoft/fast-foundation` package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems (e.g. Fluent Design, Material Design, etc.). The exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior. This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations. -## fast-components +## `@microsoft/fast-ssr` [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components) +[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-ssr.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-ssr) -`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](https://fast.design/docs/components/getting-started) to get started using the components. +The `@microsoft/fast-ssr` package contains a NodeJS solution for rendering FAST templates and components. While primarily intended for supporting server-side rendering (SSR) scenarios, it also allows FAST to be used as a general purpose HTML templating solution. + +## `@microsoft/fast-router` + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-router) + +The `@microsoft/fast-router` package contains a history-based navigation and routing solution designed around Web Components. By using `fast-router`, you can create multi-page and full application experiences. The router works with any Web Components, but has special support for Web Components built on FAST. + +## `@fluentui/web-components` -## fast-components-msft -**This package has been moved to [FluentUI](https://github.com/microsoft/fluentui/) and has been renamed to `@fluentui/web-components`** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft) +[![npm version](https://badge.fury.io/js/%40fluentui%2Fweb-components.svg)](https://badge.fury.io/js/%40fluentui%2Fweb-components) + +`@fluentui/web-components` is a library of Web Components that *composes* `@microsoft/fast-foundation`. `@fluentui/web-components` makes use of different stylesheets and may include components that specifically support Microsoft's Fluent design language. -`@fluentui/web-components` is a library of Web Components that *composes* `fast-foundation`. `@fluentui/web-components` uses the same custom element names as `fast-components`, but makes use of different stylesheets and may include components that specifically support Microsoft's Fluent design language. +The Fluent UI Web Components are built on `@microsoft/fast-element` and `@microsoft/fast-foundation`. The source for `@fluentui/web-components` is hosted in [the Fluent UI monorepo](https://github.com/microsoft/fluentui/tree/master/packages/web-components). \ No newline at end of file diff --git a/packages/web-components/fast-router/README.md b/packages/web-components/fast-router/README.md index 26d38025918..32313357e3f 100644 --- a/packages/web-components/fast-router/README.md +++ b/packages/web-components/fast-router/README.md @@ -1,9 +1,6 @@ # FAST Router -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-router) - -The `fast-router` package contains a history-based navigation and routing solution designed around web components. By using `fast-router`, you can create multi-page and full application experiences. +The `@microsoft/fast-router` package contains a history-based navigation and routing solution designed around Web Components. By using `fast-router`, you can create multi-page and full application experiences. The router works with any Web Components, but has special support for Web Components built on FAST. ## Installation @@ -27,36 +24,10 @@ import { FASTRouter } from '@microsoft/fast-router'; Looking for a setup that integrates with a particular front-end framework or bundler? Check out [our integration docs](https://fast.design/docs/integrations/introduction). -### From CDN - -A pre-bundled script that contains all APIs needed to use FAST Router and 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. - -```html - - - - - - - -``` - -The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that: - -```html - -``` - -:::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. -::: - ## Configuration at a Glance +The router is currently in `alpha` while we address a few bugs, finish up some final polish, and write the full documentation. Below is a quick sample of how to configure the router, to help get you going while we complete the full documentation. + #### A Sample Route Configuration ```ts