microsoft / fast

The adaptive interface system for modern web experiences.

FAST

This is the FAST monorepo, containing web component packages, tools, examples, and documentation. FAST tech can be used à la carte or as a suite to build enterprise-grade websites, applications, components, design systems, and more.

⭐ We appreciate your star, it helps!

Introduction

FAST is a collection of technologies built on 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.

TL;DR

• 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 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.

Packages

@microsoft/fast-element

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.

@microsoft/fast-foundation

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 - 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

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

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

@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 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.

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.
• "I want to build my own design system."
  • Jump to the design system docs.
• "I want to build my own components."
  • Jump to the fast-element docs.
• "I need to integrate FAST with another framework or build system."
  • Jump to the integration docs.
• "I want to look at a quick reference."
  • Jump to the Cheat Sheet

Joining the Community

Looking to get answers to questions or engage with us in realtime? Our community is most active on Discord. Submit requests and issues on GitHub, or join us by contributing on some good first issues via GitHub.

Get started here with the Contributor Guide.

We look forward to building an amazing open source community with you!

Features & benefits

Unopinionated

There are a million and one great ways to build your next website or application. To support the technologies you choose, creating unopinionated code is at the center of every decision we make in FAST.

This principle of being unopinionated manifests in several important ways including:

• 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. Just use one package or leverage our entire suite of packages to build your next project from the ground up; it's your call.

Tooling

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

Widely available design systems from companies like Microsoft (Fluent), Google (Material), or Salesforce (Lightning) are useful when it is essential to align with a platform or take advantage of a polished system at low cost, but many companies have a design system of their own, and some may have multiple design systems or variations.

Because FAST has abstracted base components from their style, you get a head start on your design system by building on top of tried and true base components and style libraries like our offerings for color, animation, and elevation.

Contact

• Join the community and chat with us in real-time on Discord.
• Submit requests and issues on GitHub.
• Contribute by helping out on some of our recommended first issues on GitHub.

fast's Issues

Evaluate options for visual regression testing

@awentzel commented on Wed Jan 17 2018

We have several files relating to vdiff leftover in the repo. Revisit the story here and what we should do regarding v-diff and whether or not we should update/remove what is currently in the repo

Content copied from duplicate task:
Investigate how we can get consistent vidffing of components. x-platform (windows, OSX).

Investigate the best strategy and architecture to implement UI automation testing based on our requirements.

1. Ability to test across 6 viewports
2. Ability to test across all browsers in our matrix
3. Ability to test the above across platforms (Windows, MacOS)
4. Ability to test on actual devices through automation not manual.

Investigate using Sauce Labs versus Browser Stack for snapshots and image management in the cloud.

Investigate using Applitools to configure different scenarios based on each components requirements.

• Pixel perfection differences
• Regional differences
• Layout differences
• Ignoring parts of a page differences
• When differences are found how do file bugs on our system
• How do we approve or deny the results to allow deployment to production?

Create tasks based on the above for all the work that needs to get done.

• Adds ability to take image snapshots and store in the cloud
• Adds ability to configure snapshots based on individual component requirements
• Adds ability to file bugs when differences are found
• Adds ability to approve or deny automation results to allow release deployment into production

Investigate using Cypress
https://www.cypress.io/pricing/

"Visual regression testing" should be used in documentation instead of visual automation testing to be more specific to what it does.

Testing Notes that can be used for documenting solution for visual automation.
Snapshots on Jest are great for comparing assertion tests against snapshot file.

Kent C. Dodds - Snapshot testing https://blog.kentcdodds.com/effective-snapshot-testing-e0d1a2c28eca use snapshots sparingly and where appropriate. Don’t overdue. Architecture: Make it easier to write tests.

Making tests more resilient. Don’t tie tests to CSS class name. Use a different attribute “data-test-<#unique-id>”

Automating confidence in code base.
Workshops : https://kentcdodds.com/workshops/

Deliverables

1. Evaluate regression testing options (cypress, sauce labs, applitools)
2. define and document testing plan
3. create tasks to implement plan

Update Typography with improvements for accessibility

permutating data takes too long on array

Right now arrays take a very long time to generate permutations, we should be able to cut down this time with better logic.

Mitigated by changing to example data rather than permutating examples for the docsite, this still needs to be addressed in the permutator for data.

feat(fast-development-site): adds new package for testing component libraries

feat(fast-react-jss-manager): adds package for managing css on react

Update permutator for schema simplification

When using other validation methods to check schemas (online validators) schemas with duplicate items in the required array cause an issue with validation. Every string in required should be unique.

Use set to create a unique array of required items when merging.

Update Image with improvements for accessibility

Remove Gulp and replace with Node

@awentzel commented on Thu Jan 11 2018

Remove and/or replace anything gulp related with node / javascript tasks.

Update LCA requirements to gain approval for Green Sock

@awentzel commented on Wed Jan 17 2018

leverage any work already completed from OneNote

Create activity alerts to Slack

@awentzel commented on Wed Jan 17 2018

Setup activity alerts on Azure for Web App Service. This will allow everyone to be notified on Slack #fluent-web-alerts when a change has been made to the server or application running on the server.

Create formatting to the report generation process

@awentzel commented on Wed Jan 17 2018

Reports currently generate as a single string, they should be formatted with proper nesting so that we can easily identify areas in which they change.

This reformats from single line to multi-line readably formatted file.

Would make code reviews and maintaining far easier.

Related: #4

Create packages for react viewer, data permutator and browser extensions

Three packages need to be migrated into this repository from outside:

• react viewer
• data permutator
• browser extensions

Create report generation CI process

@awentzel commented on Wed Jan 17 2018

Generate on a nightly CI process a batch of reports that will generate every data permutation to determine what/where changes occur and if they are acceptable. This will help us account for changes to the API and ensure we are not accidentally introducing errors in the design system.

1. Reports can be completely removed from the development run time.
2. Reports could be in the hundreds of thousands so we want this ran on nightly CI
3. Reports would check for errors and inform us of issues.

Related: #8

Create CLI to easily hook up new components

@awentzel commented on Wed Jan 17 2018

The scope of this task is to create an initial script run by CLI that allows a fluent web component to be easily created.

This script should create files and folders for an initial setup with a working react component in the core framework. This should be a node script written in TypeScript.

The execution of the script should take a parameter for the library (react, angular), the name of the item (eg. foo) and the level of the item (component or module).

For example, user can use the command line to create a component

$ npm run create:component:foo

---

@awentzel commented on Wed Jan 17 2018

related to #18

Create chisel to the VSTS build system

@awentzel commented on Wed Jan 17 2018

implement chisel https://mseng.visualstudio.com/VSOnline/Keros/_packaging?feed=Keros&package=%40mskeros%2Fchisel&version=1.127.1&protocolType=Npm&_a=package

Would be great to be an early adopter of this feature for talking points. Hence why it's a P1.

Update Foundation component with base functionality

Expected behavior

Actual behavior

Steps to reproduce the problem

Specifications (hardware, software, configurations)

• Include device make, model, OS version:
• Include browser and version:
• Include screen orientation:
• Include screen size:
• Include page URL:
• Include localization:

Please attach screenshots or video of the problem for quickest resolution

Update changelog creation and management

@awentzel commented on Wed Jan 17 2018

Compare this with our changelog format and look to remove as much manual operations as possible.

Additionally ensure we're following latest standards and guidelines on how it's been implemented.
https://nodejs.org/en/blog/release/v7.8.0/?utm_source=nodeweekly&utm_medium=email

1. We should have an all up (rolled up) versions in the developer documentation page. as shown here
   http://fluentweb.com/documentation/distribution-deployment/changelog/

2. Each components or module should include a link to it's own changlog history.

3. This component/module level history should have a new section after specifications for "Changelog" and show top 5.

4. There would be a link to view all history beyond top 5.

get this initial stuff functional and then fine tune with Andrew.

Add an app shell and breadcrumbs to the development site

• Create a shell component
• Create a breadcrumb component
• Create a stage for the different datasets of a component to sit in that has configuration options for a minimum width
• Add these to the development site

Update Textfield with improvements for accessibility

Migrate fast-animation into mono repo

Create a new package for fast-animation and copy files into from https://github.com/microsoft/fast-animation

Update Context Menu with improvements for accessibility

Create monitoring for all websites

@awentzel commented on Wed Jan 17 2018

Provide analytics and monitoring on application health that will then fire off alerts on CloudBot -> Slack App.

1. Configure app insights
   https://ms.portal.azure.com/#resource/subscriptions/456b8669-6142-4a7b-b4a6-adf39c80289e/resourceGroups/fluent-web-resource-group/providers/microsoft.insights/components/fluent-web-app-insights/properties
2. Update webpage code with the instrumentation keys
3. Update CloudBot to integration

Update Card with improvements for accessibility

Add documentation to fast-development-site

How would someone use this package?

feat: adds button boilerplate

Update schemas to check for dependencies

if a schema has dependencies, check to see if required exists.

See price component - if a dependency needs the required array, this should be checked, if it does not exist add it

Note: Dependencies have an array which, if it exists should be creating schema variations. These variations should have a modified required array to account for the array of dependencies.

Create state storage and examples to the CLI routine

@awentzel commented on Wed Jan 17 2018

Currently, when a new component or module is created there are multiple places throughout the repo where it needs to be included before the build will succeed. This all could be automated at build time which would improve our workflow, limit merge conflicts, and improve the experience for contributors.

Ideally this would be easily incorporated in our experimentation and prototype repos.

getInitialState, createStore, examples, etc should all be populated dynamically at build time based on an export or config file.

This task would automate the imports for initial state, store and examples which currently have to be manually populated and managed. Automating these will reduce conflicts and ensure that nothing is missed as it is all auto-generated.

#17

Create performance matrix at compile time

@awentzel commented on Wed Jan 17 2018

Evaluate wiring up something like https://www.sitespeed.io for build time analysis of perf

1. Add in a command line argument to run BundleAnalyzer
2. Add in a command line tool that writes out
   -- Total files,
   -- Total css file size (min and non),
   -- Total JS file size (min and non),
   -- Total HTML home page file size (might be nice to actually write this as a code comment on each rendered page in SPA if possible,
   -- Total components
   -- Total layouts
   -- Total example

It might be actually even nicer to add this for the website as part of a commented out section in markup so at any time Jason or myself can view source and see friendly data matrix on code health.

Update Flyout with improvements for accessibility

Update Hyperlink with improvements for accessibility

Migrate fast-tslint-rules project to mono repo

Create a new package for fast-tslint-rules and copy files into from https://github.com/microsoft/fast-tslint-rules

Migrate fast-tutorials from current repo to mono repo

Create a new package for fast-tutorials and copy files into from https://github.com/microsoft/fast-tutorials

Update working group plan to better reflect open source

@awentzel commented on Wed Jan 17 2018

Though it might be better to rename or recreate as fast-wg-a11y@ and fast-wg-security@

• Evaluate the notes below to determine what changes should be made to better align OSS community around security and accessibility
• Update policy documentation
• Update email groups, descriptions, members, owners.

It is recommended that the Steering Committee establish a security working group of collaborators with recognized security experts tasked with reviewing security related pull requests and determining an appropriate review process.

Long-term support working group roadmap

The LTS WG is expected to establish a regular and predictable cadence of LTS Releases. To this end, the LTS WG must maintain and regularly publish a clear roadmap that outlines the priorities and milestones for upcoming LTS releases. The goal of the roadmap is to help guide the project's evolution as opposed to constraining it.

Working groups

Working groups are autonomous groups of collaborators chartered by the SC to oversee specific aspects of the project. Working groups can be formed at any time but require ratification by the TSC.

Every working group has a charter that details its area of responsibility. Once approved by the SC, the working group becomes solely responsible for items detailed in that charter.

When applicable, the charter should indicate the conditions under which the working group's activity can be considered to be complete, and the WG dissolved. A working group can, at any time, request that the SC dissolve the working group by opening an issue requesting dissolution.

The SC may revoke the working groups charter at any time following the decision-making process defined in the SC charter.

Proposals to create a new working group should be made either by opening an issue with the draft charter for the new working group, then putting that on the SC agenda.

Nested JSS classes without any css rules does not export the classname

Expected behavior

One should be able to nest a JSS class without defining root style rules

{
    root: {
        "& $nested: { color: "red" }
   },
   nested: {}
}

Actual behavior

There is no class exposed under the nested key of the classes object.

Update Webpack to the latest version

@awentzel commented on Thu Jan 11 2018

I'd like to ensure that we're using the latest version of webpack on fast-dna.

Creating nested classes and pseudo elements selectors causes typescript compile error

Expected behavior

Actual behavior

Steps to reproduce the problem

Specifications (hardware, software, configurations)

• Include device make, model, OS version:
• Include browser and version:
• Include screen orientation:
• Include screen size:
• Include page URL:
• Include localization:

Please attach screenshots or video of the problem for quickest resolution

Create plan for Azure CD to notify upon ZipDeploy completion

@awentzel commented on Tue Jan 16 2018

Create an Azure notification plugin that will notify users upon completion of Zip Deploy:

Current method is a GitHub project, but, requires code in every repository to accomplish. We should write a plan that can accomplish the same thing in a single Docker file and/or be using Azure Platform. They may already have a plan, so talk with Azure PM team to get an idea.

https://github.com/awentzel/KuduPostDeploymentSlackHook.git

fast-react-jss-manager needs documentation on how to use it's exports

There is currently no documentation for fast-react-jss-manager

Update to fix security vulnerability

https://github.com/microsoft/fast-dna/network/dependencies

A dependency defined in fast-browser-extensions/package-lock.json has known security vulnerabilities and should be updated.

Known vulnerability found
CVE-2018-7651
Moderate severity
index.js in the ssri module before 5.2.2 for Node.js is prone to a regular expression denial of service vulnerability...

package-lock.json update suggested:
ssri ~> 5.2.2
Always verify the validity and compatibility of suggestions with your codebase.

Create a plan around scripting DevOps tasks

@awentzel commented on Wed Jan 17 2018

As requests come in to onboard into Azure or off board this should be done through script to automate the entire process with simple run of a script.

a. Create an Azure script to create and configure new 'Web App' instances with default configuration.
a. windows or linux
b. static or node
	i. docker?
c. custom dns?
	i. script to update dns
d. ssl?
	i. script to edit azure

d.a. configure for custom domain name and ssl
e. configure to run on scripts/server.js
f. configure to add port 4001
g. configure to select the correct docker image

Remove the -beta flag from npm packages

@awentzel commented on Wed Jan 17 2018

Prior to launch we should remove the beta flag

Create security analysis to code base on

@awentzel commented on Wed Jan 17 2018

Configure Microsoft VSTS / PRSS for code signing and malware scanning

Create plan to analyze and visualize real-user data analytics

@awentzel commented on Wed Jan 17 2018

We currently use JSLL, but, now that we're on SPA I'm not sure about support. Let's evaluate the best method of collecting user behavior and click through data.

1. JSLL
2. SOASTA
3. C+E solutions (BI etc)
4. other alternatives?
   RUM => Real User Measurement
   For MSN and Edge pages we have both in-house and external solution
   In house: Currently using OTF events, moving to JSLL, which is more Microsoft wide solution
   External: SOASTA https://www.soasta.com
5. Custom FAST solution that will automatically self-inform and describe at the component level what is happening, who is using it, and how. This will be published to a repository which can be hooked up with GraphQL to visualize. Allowing us to know exactly what is running on the web. (preference)

Requirements:

1. tracking logged in users versus non-logged in behind AD and microsoft accounts
2. implementation as a node module that can easily be inherited by our many websites
3. Lightweight dOM impact

If JSLL turns out to be the best option then update to implement tracking for authenticated users https://osgwiki.com/wiki/JSLLv4

12. Jsll vs soasta vs bi c+e etc? Wtf: https://osgwiki.com/wiki/JSLLv4#Single_Page_Application_.28SPA.29_Properties_Management
    www.soasta.com etc

Update Checkbox with improvements for accessibility

Create a plan to release a VSTS marketplace package

@awentzel commented on Wed Jan 17 2018

1. Create scope of work for all requirements users would want
2. Create tasks from this scope of work to execute the build out
3. Create documentation for installing, configuring, and using this package
4. Create blog post announcing this new package on fluentweb.com
5. Add to existing curriculum to include how to do all of the above.
6. Create video to walk through this entire process.

Create performance matrix at compile time

@awentzel commented on Wed Jan 17 2018

Evaluate wiring up something like https://www.sitespeed.io for build time analysis of perf

1. Add in a command line argument to run BundleAnalyzer
2. Add in a command line tool that writes out
   -- Total files,
   -- Total css file size (min and non),
   -- Total JS file size (min and non),
   -- Total HTML home page file size (might be nice to actually write this as a code comment on each rendered page in SPA if possible,
   -- Total components
   -- Total layouts
   -- Total example

It might be actually even nicer to add this for Fluent Web as part of commented out section in markup so at anytime Jason or myself can view source and see friendly data matrix on code health.

Refactor foundation component to improve typing

Update button component to support either anchor or button

Expected behavior

Actual behavior

Steps to reproduce the problem

Specifications (hardware, software, configurations)

• Include device make, model, OS version:
• Include browser and version:
• Include screen orientation:
• Include screen size:
• Include page URL:
• Include localization:

Please attach screenshots or video of the problem for quickest resolution

feat(fast-react-component-base): adds package for base react components

Update Button with improvements for accessibility