diff --git a/docs/react-wiki-archive/API-Documentation.md b/docs/react-wiki-archive/API-Documentation.md new file mode 100644 index 0000000000000..fe46abdd2a406 --- /dev/null +++ b/docs/react-wiki-archive/API-Documentation.md @@ -0,0 +1,136 @@ +# Documenting Fluent UI + +This content only applies to [documentation site](https://developer.microsoft.com/en-us/fluentui) for `@fluentui/react` version 7/8 (formerly `office-ui-fabric-react`) and Fluent UI Android/iOS/etc. (`@fluentui/react-northstar` and `@fluentui/web-components` currently have separate documentation sites.) + +- [Documenting components](#documenting-components) +- [Writing Markdown documentation for the website](#writing-markdown-documentation-for-the-website) + +## API documentation + +`@fluentui/react` 7/8 uses [API Extractor](API-Extractor) and the custom [`@fluentui/api-docs` package](https://github.com/microsoft/fluentui/tree/master/packages/api-docs) (formerly `@uifabric/api-docs`) to generate documentation which shows up in the [Controls section](https://developer.microsoft.com/en-us/fluentui#/controls/web) of our website as well as in the legacy demo app at [aka.ms/fluentdemo](http://aka.ms/fluentdemo). + +Note that all the API documentation features described below will only work on doc comments `/** like this */` (multiline is fine). + +### Top-level doc comments + +For types or components which should be included on the website, be sure to include a `{@docCategory PageName}` tag in the top-level doc comment for each type which should be documented. + +If the type is related to a specific component, `PageName` should be the name of the component. Otherwise, you can use either the name of the type or a general category that it falls under, such as `MergeStyles`. If the `PageName` doesn't match any of the known component page names, it will be put under the References section in the website sidebar. + +For example, if you wanted `ISliderProps` to show up on the 'Slider' page, it would look like the following ([see it live here](https://developer.microsoft.com/en-us/fabric#/controls/web/slider#ISliderProps)): + +```tsx +/** + * {@docCategory Slider} + */ +export interface ISliderProps { +``` + +This should work automatically for `@fluentui/react` and the packages it consumes. If the API is in a newer package, you should check [this file](https://github.com/microsoft/fluentui/blob/master/packages/api-docs/config/api-docs.js) to verify that the package is included (and add it if not). + +Note that top-level doc comments will be rendered as markdown on the website. If it's an especially long/detailed comment which includes headings, **headings must start at level 4** to appropriately nest within the website. + +### Limitations + +Documenting the following API types on the website is **supported**: + +- Interfaces +- Type aliases +- Classes +- Enums + +These API types are **not supported** currently: + +- Functions (including function components) +- Constants + +### Prop comments + +Individual props in interfaces and types have limited support for markdown rendering, due to performance concerns. Currently just inline code blocks (backticks) are supported. + +API Extractor has a particular format required for certain types of doc comments and will fail at build time if this format is not followed. There are also a few suggested best practices. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GoodBad
@param tags must include a dash and not contain type information
+/**
+ * @param myParam - Description here
+ */
+
+/**
+ * @param myParam Description here
+ * @param {number} myParam Description here
+ */
+
Special characters which have meaning in TSDoc (e.g. @ > { } etc.) must be escaped with backslashes or backticks
+/**
+ * Comment about `>` and `{`.
+ * As of version \>= 1.0.0.
+ */
+
+/**
+ * Comment about '>' and '{'.
+ * As of version >= 1.0.0.
+ */
+
@deprecated tags must include a deprecation message
+/**
+ * @deprecated Use `foo` instead.
+ */
+
+/**
+ * Deprecated. Use `foo` instead.
+ * @deprecated
+ */
+
Default values should be indicated by @defaultvalue tags (@default and @defaultValue also work)
+/**
+ * @defaultvalue 'hello world'
+ */
+
+/**
+ * Default is 'hello world'
+ */
+
+ +### More details about the `@fluentui/api-docs` package + +The `@fluentui/api-docs` (previously `@uifabric/api-docs`) package takes the api.json files generated by [API Extractor](API-Extractor) and splits them up into individual page.json files to populate both component pages and (new) references pages. These page.json files live in `@fluentui/api-docs`. + +Generally, this tool is used on `@fluentui/react` and its dependencies (`@fluentui/react-northstar` uses a different approach). You can see or update the full list of included packages in [this file](https://github.com/microsoft/fluentui/blob/master/packages/api-docs/config/api-docs.js). + +## Writing Markdown documentation for the website + +See the [Markdown documentation](Markdown-documentation) page for tips on authoring markdown files such as component overviews/best practices and other website content. diff --git a/docs/react-wiki-archive/API-Extractor.md b/docs/react-wiki-archive/API-Extractor.md new file mode 100644 index 0000000000000..58814b52b88b2 --- /dev/null +++ b/docs/react-wiki-archive/API-Extractor.md @@ -0,0 +1,17 @@ +### What is API Extractor? + +[API Extractor](https://api-extractor.com/) generates an api.md file containing the public API for a package. `@fluentui/react` and related packages as well as `@fluentui/web-components` use API Extractor to ensure that API changes must be reviewed before being merged into master. (`@fluentui/react-northstar` and related packages do not use API Extractor as of writing.) + +### Build Tasks + +As part of a package's build process, the api-extractor task checks the package's public API with the package's auto-generated .api.md file. + +If building locally, the API file will be updated automatically (in `7.0` and `master`). Be sure to commit the updates with your other changes! + +In PR builds, the task will fail if it detects missing API file updates. + +(Previously it was necessary to run a separate command `yarn update-api` to update the API files, but we decided to streamline this and do the update automatically as part of the build instead.) + +### API Extractor code requirements + +See the [API Documentation page](API-Documentation#prop-comment-requirements). diff --git a/docs/react-wiki-archive/Advanced-auto-merge.md b/docs/react-wiki-archive/Advanced-auto-merge.md new file mode 100644 index 0000000000000..1b0073a7253fd --- /dev/null +++ b/docs/react-wiki-archive/Advanced-auto-merge.md @@ -0,0 +1,58 @@ +You can give the bot commands to customize how the bot assists you with merging your pull request when all merge policies pass. + +To customize the auto-merge parameters, @ mention the bot **(e.g. `@msft-fluent-ui-bot`, `@msft-github-bot` or `@msftbot` depending on the bot identity providing auto-merge capabilities)** and provide your instruction in English. Note that for all scenarios below, pre-configured merge policies at the GitHub level must still be satisfied (i.e. the bot will never bypass merge policies for you). Note that you must be a contributor - the bot will ignore all commands given by non-contributors. + +--- + +At this time, the bot supports the following scenarios: + +### Requiring a specific, minimum number of approvals + +Examples of what to say (illustrative, not prescriptive nor exhaustive): + +- > Only merge this pull request if it has 2 approvals. +- > require 3 sign offs. +- > Please make sure there are at least two approving reviews. + +### Requiring an approval from a specific person + +Examples of what to say (illustrative, not prescriptive nor exhaustive): + +- > make sure @cliffkoh has a chance to review before you merge +- > do not merge unless @cliffkoh approves. + +### Requiring approvals from multiple people + +Examples of what to say (illustrative, not prescriptive nor exhaustive): + +- > require sign-offs from @kkjeer and @JasonGore +- > hold this pr until all of the following approve: @kkjeer, @JasonGore, @dzearing + +### Requiring approvals from one of several people + +Examples of what to say (illustrative, not prescriptive nor exhaustive): + +- > make sure @kkjeer, @dzearing or @JasonGore gets to approve +- > require approvals from any one of the following: @kkjeer, @JasonGore, @dzearing + +### Changing the time the pull-request is held open before the bot merges the pull request on your behalf + +Examples of what to say (illustrative, not prescriptive nor exhaustive): + +- > hold this pr for the next 2 hours +- > please wait 1 more day before merging this +- > delay merging this pull request for 2 hours 30 mins + +--- + +Note that the examples above of what to say are only meant to be illustrative and not definitive. + +Additionally, if the bot has misinterpreted you or you have changed your mind, you can express such an intent with a phrase like "nevermind" or "forget what I just told you". + +### Enforcement of policies + +on April 18th 2023 `auto-merge.config.enforce` started to block all PR's (it never ran/finish). + +As we use github automerge funcionatity anyways we removed it from required status checks to unblock contributors and use github build-in features. + +~Enforcement of auto-merge comments is handled by the `auto-merge.config.enforce` status check. It's intended to run for each PR and automatically succeed if no AutoMerge policies apply. If this stops working, contact the bot team (check internal wiki for contact info).~ diff --git a/docs/react-wiki-archive/BETA-Release.md b/docs/react-wiki-archive/BETA-Release.md new file mode 100644 index 0000000000000..9553582e9dd27 --- /dev/null +++ b/docs/react-wiki-archive/BETA-Release.md @@ -0,0 +1,81 @@ +# React Components for Beta + +### Beta quality controls required (in @fluentui/react-components) + +_(Phase 1 & 2)_ + +- Accordion +- Avatar +- Badge +- Button (and variants MenuButton , ToggleButton`) +- Icon +- Link +- Divider +- FluentProvider +- Menu +- Popover +- Text +- Tooltip + +**Additional to include in the beta release if ready before release.** + +_(Phase 3 - Control candidates to be considered by the team as extra)_ + +- Label +- Checkbox + +## Browser support matrix for beta + +Fluent UI React supports many commonly used web browsers such as Internet Explorer, Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge. For browsers outside of this matrix, proper behavior of the components may be good but is not guaranteed. + +| Browser | Supported | Not supported | +| ----------------------------------- | --------- | ------------- | +| Microsoft Edge Chromium | X |   | +| Microsoft Edge Legacy |   | X | +| Internet Explorer 11 |   | X | +| Internet Explorer 10 |   | X | +| Internet Explorer 9 |   | X | +| Google Chrome (latest 2 versions) | X |   | +| Mozilla Firefox (latest 2 versions) | X |   | +| Apple Safari (latest 2 versions) | X |   | +| **Mobile** | +| Edge Chromium on Mobile | X |   | +| Google Chrome on Mobile | X | +| iOS Safari (latest version) | X |   | +| Android Safari (latest version) | X |   | + +Beta packages are the first official version available. This means that the API has not been examined beyond initial implementation. Beta packages may or may not have documentation, however they have had a basic level of testing across a number of different devices. + +We will not be fixing bugs in beta unless there is a high priority partner escalation that will cause a legal problem. Follow-up work that include (fixes, tests) is scheduled After Beta. + +## Definition of Done for Beta + +1. **Design Spec:** + - [x] a) Signed Off. +2. Engineering Spec: + - [x] a) Signed Off +3. **Individual component package is tagged:** + - [x] a) Has the "beta" tag on it (or the correct semver thing on it) +4. **Component must be in the suite package:** + - [x] a) i.e. @fluentui/react-components +5. **Component must have a Storybook story that includes at least the following:** + - [x] a) Component name and description + - [x] b) At least one code example - Code example should include all a11y/aria props if needed. In the past, our fluent examples didn't set things like aria-label etc. So, if there are a11y patterns, we would want folks to copy and paste from our examples that should be in. + - [x] c) Output of the API - Should be easily done with the Control Add-in + - [x] b) [Optional] A link that points to known issues or bugs with the component on GitHub. +6. **Passes all conformance tests:** + - [x] a) Passes all the current/required testing: i.e. Regression, bundling, unit tests.. +7. Component has been tested. against our Browser Matrix: + - [x] a) See above +8. **Supports a11y:** + - [x] a) High Contrast Mode + - [x] b) Narrator - As defined by our AT/Browser Matrix (see above) + - [x] c) Keyboarding +9. **Supports Design Tokens/Theming:** + - [x] a) Light Mode + - [x] b) Dark Mode + - [x] c) Supports all current out of the box Themes +10. **Supports Build-time CSS optimizations:** + - [x] a) Supports the current CSS optimizations we have in place. +11. **Supports SSR:** + - [x] a) Supports the current SSR test we have in place. diff --git a/docs/react-wiki-archive/BestPractices/Accessibility.md b/docs/react-wiki-archive/BestPractices/Accessibility.md new file mode 100644 index 0000000000000..180e5cc4a6a7f --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Accessibility.md @@ -0,0 +1,29 @@ +This document describes our policies and methods for supporting accessibility. + +## Colors + +Default color choices should conform to contrast requirements as laid out in [WCAG 2.0](https://www.w3.org/TR/WCAG20/) level AA recommendations as laid out in section 1.4.3. + +## High Contrast + +We best support high contrast in Microsoft Edge and Internet Explorer 11. Mozilla Firefox is also supported to the extent possible barring technical constraints. Read on for more details. + +The recommended approach is to use the semantically correct elements to match your scenario. For example, use a `; + } + + private _onClick(ev: React.MouseEvent) {} +} +``` + +Instead we can use an arrow function property as it will always be bound to the component. + +GOOD: + +```tsx +class Foo extends React.Component { + public render() { + return ; + } + + private _onClick = (ev: React.MouseEvent) => {}; +} +``` + +## For gathering refs, use `React.createRef` + +String refs are deprecated. Don't use them. Also don't use inline-created functions. + +Bad: + +```tsx +class Foo extends React.Component { + public render() { + return
; + } +} +``` + +Bad: + +```tsx +class Foo extends React.Component { + public render() { + return
(this._root = el)} />; + } +} +``` + +Good: + +`React.createRef` creates a reference object that has the following type `{ current: T | null }`, where T is the element to reference (either a dom node or a react component). You set the reference by passing the reference object as the `ref` prop. You can then subsequently access the reference through the `.current` property on the reference object elsewhere in your code. + +```tsx +class Foo extends React.Component { + // Create the reference object that will be used for setting and accessing the reference + private _root = React.createRef(); + + public render(): JSX.Element { + // Set the reference by passing the reference object as the ref prop + return +
+``` + +If you want to get the button but you do `cy.contains('a')`, it will give you the label instead! + +One way around this is to use more informative, specific text, but there's also `cy.contains(selector, text)` which allows narrowing by a CSS selector before looking for text: for example, `cy.contains('button', 'a')`. + +### Be careful with local variables and asynchronous code + +Since Cypress commands are enqueued synchronously but run asynchronously, be very careful about how you access things that you've saved in local variables within the test (or consider using a different pattern). + +A common example is wrapping local variable access in `cy.then()` or `cy.should()` to ensure you get the latest value at runtime (not at the time the test's commands were enqueued). + +
click to expand example + +```tsx +it('focuses a button incorrectly', () => { + let focusButton = () => undefined; + + const TestCase = () => { + // In the actual instance where this happened, the code needed to call a component's custom + // imperative API. (If the goal is really just to focus a button, there are better ways to do it.) + const buttonRef = React.useRef(); + React.useEffect(() => { + focusButton = () => buttonRef.current?.focus(); + }, []); + + return ; + }; + + mount(); + + // ❌ this will NOT be set to the correct value yet, because the component hasn't rendered! + focusButton(); + // ❌ fails + cy.focused().should('have.text', 'hello'); + + cy.contains('hello').then(() => { + // ✅ button has rendered + focusButton(); + }); + // ✅ succeeds + cy.focused().should('have.text', 'hello'); +}); +``` + +
+ +### Testing that nothing is focused + +Use `cy.focused().should('not.exist')`, NOT an assertion about `body`. Even though `document.activeElement` is probably `body` in that case, Cypress gets the focused element using `:focus`, which never goes to `body`. + +### Waiting + +Cypress does provide a `cy.wait(ms)` method, but it's best if you can think of an actual UI condition to wait for instead. diff --git a/docs/react-wiki-archive/BestPractices/Testing-with-Jest.md b/docs/react-wiki-archive/BestPractices/Testing-with-Jest.md new file mode 100644 index 0000000000000..e3027c9c205f8 --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Testing-with-Jest.md @@ -0,0 +1,234 @@ +> 🚨🚨 **This page is primarily about `@fluentui/react-components` ("v9") and `@fluentui/react` ("v8") and related packages.** 🚨🚨  [See this page for `@fluentui/react-northstar` ("v0").](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/test-a-feature.md) + +## Overview + +Fluent UI's unit, functional, and snapshot tests are built using [Jest](https://jestjs.io/). This allows us to run tests in a Node environment but simulates the browser using [jsdom](https://github.com/jsdom/jsdom). ([See this page for other types of tests.](Testing)) + +We use various libraries on top of Jest for rendering and interacting with React components: + +- New tests should use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) +- Legacy tests may also use: + - [Enzyme](https://enzymejs.github.io/enzyme/) -- **not allowed in new tests** + - [react-test-renderer](https://reactjs.org/docs/test-renderer.html), primarily for snapshot testing _(snapshots are discouraged in new tests)_ + +## Running tests + +Our Jest setup generally require that packages be built before testing, so before running tests the first time, you should run `yarn build --to my-package` from the repo root. + +To run the tests for one package, `cd` to that package and then run `yarn test`. + +To run an individual test (or technically any tests with a path matching this substring), `cd` to the relevant package and run `yarn jest MyTestName`. + +(You can also run tests for the whole repo by running `yarn test` at the repo root. This will build beforehand if needed.) + +## Running tests in watch mode + +When you are developing tests, use the watch mode to run the tests as you write them! + +1. Go to the package folder where you want to run the tests. +2. The start command varies by library: for v8, `yarn start-test`, or for v9, `yarn test --watch` +3. Edit and saving tests should now cause the console to re-run the tests you have added/modified. + +### Debugging + +The repo includes launch configurations for debugging tests using Visual Studio Code. (You could also configure debugging in another editor of your choice.) + +1. Set breakpoints in the test file (`*.test.ts` or `*.test.tsx`) +2. Open the **Run** (debugger) pane in the sidebar and choose the configuration you want: usually **Debug current open test** to run only the current open test, or **Debug test** to run all tests for the package the current file is in +3. Start debugging + +## Jest basics + +Tests in Jest are written similarly to Mocha tests, though Jest includes a number of assertions that work similarly to Chai. (If you've never used either of those, don't worry about it!) + +- If you're new to Jest, start with the [introduction and guides](https://jestjs.io/docs/using-matchers) +- [Jest API reference](https://jestjs.io/docs/api) + - [Available `expect` matchers](https://jestjs.io/docs/expect) + - [Mock functions](https://jestjs.io/docs/mock-function-api) + - [The `jest` object](https://jestjs.io/docs/jest-object) including fake timer APIs ([more info](https://jestjs.io/docs/timer-mocks)) + +Note that you do not need to import the assertions or the Jest APIs; they should be available automatically through the included typings. + +A basic test example: + +```ts +describe('thing', () => { + it('does something', () => { + expect(thing()).toEqual(aValue); + }); +}); +``` + +## Testing components + +In cases where you need to automate a component and validate it performs correctly, you can use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) to mount components, evaluate DOM structure, and simulate events. + +Here's a very basic example of what a test might look like (we'll go over this in more detail later): + +```tsx +const onClick = jest.fn(); +const { getByRole } = render(); + +userEvent.click(getByRole('button')); +expect(onClick).toHaveBeenCalled(); +``` + +### Philosophy + +The [guide on migrating from Enzyme](https://testing-library.com/docs/react-testing-library/migrate-from-enzyme/) nicely sums up Testing Library's philosophy, and how it differs from the way tests tended to be written with Enzyme: + +> The primary purpose of React Testing Library is to increase confidence in your tests by **testing your components in the way a user would use them.** Users don't care what happens behind the scenes, they just see and interact with the output. Instead of accessing the components' internal APIs or evaluating their state, you'll get more confidence by writing your tests based on the component output. + +Some examples of this philosophy: + +- Prefer [finding elements like a user would](https://testing-library.com/docs/queries/about/#priority) (by role, label, or text) rather than relying on `className`, `id`, or DOM structure. This approach helps encourage writing UI that's accessible to all users. +- Prefer interact with elements the way the user would, by clicking or using the keyboard, rather than using imperative APIs. + - [`@testing-library/user-event`](https://testing-library.com/docs/ecosystem-user-event/) more realistically simulates the full sequence of events that occur during user interaction. + +Testing Library's APIs also make it _easier_ to write realistic, user-focused tests compared to Enzyme. + +### Recommended reading + +This page will only go into basics of using Testing Library (and some [common pitfalls](#tips-and-faq)). + +For a more detailed run-through of how to write tests, check out this [tutorial](https://www.robinwieruch.de/react-testing-library/) recommended in Testing Library's docs. (One difference: we typically use the queries returned by `render()`, rather than the global queries from `screen` like the tutorial uses.) + +It's highly recommended that you check out Testing Library's docs as well! + +- Basics + - [Intro and philosophy](https://testing-library.com/docs/react-testing-library/intro) + - [Guide on migrating from Enzyme](https://testing-library.com/docs/react-testing-library/migrate-from-enzyme/) +- APIs and strategies + - [Queries](https://testing-library.com/docs/queries/about) and how to think about querying elements (also read about the individual queries) + - [Waiting for appearance/disappearance](https://testing-library.com/docs/guide-disappearance) + - [API cheatsheet](https://testing-library.com/docs/react-testing-library/cheatsheet/) + - [`render()` API details](https://testing-library.com/docs/react-testing-library/api) + - Also check out other pages in the "Core API" section of the Testing Library docs (not repeating it all here) +- Events + - [`fireEvent`](https://testing-library.com/docs/dom-testing-library/api-events) for firing raw events, and [considerations for `fireEvent`](https://testing-library.com/docs/guide-events/) + - [`userEvent`](https://testing-library.com/docs/ecosystem-user-event/) (`@testing-library/user-event`) for simulating interaction event sequences + - If you're having trouble getting an interaction test working, see [My event isn't working properly](#my-event-isnt-working-properly) below + +### Examples + +```tsx +import * as React from 'react'; +import { render } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { Button } from './Button'; + +describe('Button', () => { + it('calls a function on click', () => { + const onClick = jest.fn(); + // render() returns a variety of get/query methods + const { getByRole } = render(); + + // getByRole will throw if it doesn't find anything + const button = getByRole('button'); + userEvent.click(button); + expect(onClick).toHaveBeenCalled(); + + // 🧹 Unlike with Enzyme or react-test-renderer, cleanup is automatic! + }); +}); +``` + +## Snapshot testing + +> 🚨 **Prefer specific unit/functional tests over snapshot tests.** For example, if you want to verify that an attribute is applied in a particular place, it's much better to test that directly rather than using a snapshot. + +Jest allows creating [snapshot tests](https://jestjs.io/docs/snapshot-testing) that compare an object or text with expected output. + +- `expect.toMatchSnapshot(...)` abstracts loading a .snap file for the test to compare, or will create one if none exists +- `expect.toMatchInlineSnapshot()` saves the snapshot within the test file itself + - **Prefer inline snapshots**: they're more obvious to read and harder to ignore. If the snapshot seems too long to save in the file, that's often a good reason to consider ways to test the desired outcome directly. + +Snapshots in v8 will include style information from `@fluentui/merge-styles` CSS classes. Snapshots in v9 do not include style information. + +
+Expand for example snapshot test + +```tsx +// Foo.test.tsx +import * as React from 'react'; +import { render } from '@testing-library/react'; + +const Foo = () =>
hello world
; + +describe('Foo', () => { + it('renders correctly', () => { + const { container } = render(); + // This saves the snapshot in a file ./__snapshots__/Foo.test.tsx.snap + expect(container).toMatchSnapshot(); + }); + + it('renders correctly (inline snapshot)', () => { + const { container } = render(); + // Inline snapshots are good for basic cases + expect(container.firstElementChild).toMatchInlineSnapshot(` +
+ hello world +
+ `); + }); +}); +``` + +
+ +If you ever break a snapshot, you can update it by running one of the following in the package folder: + +- for v8: `yarn update-snapshots` +- for v9: `yarn test -u` + +## Tips and FAQ + +See also [Tips for interaction testing](#tips-for-interaction-testing) above. + +### Be careful with `.toBeDefined()` and `.not.toBeNull()` + +The matcher `expect(value).toBeDefined()` checks that `value` is _**specifically**_ `undefined`. This can be a problem when `null` is also a possible return value (such as with many DOM APIs) because `null` is not `undefined`. + +```ts +// ❌ querySelector and queryBy____ return null if not found, null !== undefined, matcher passes +expect(queryByRole('button')).toBeDefined(); +expect(element.querySelector('.foo')).toBeDefined(); +``` + +Similarly, `expect(value).not.toBeNull()` will succeed if `value` is `undefined`. + +Instead, consider either checking for a specific value if possible, or using `expect(value).toBeTruthy()`. This works unless `0`, `''`, or `false` is a possible "success" return value (in which case you should check specifically for that value instead). + +```ts +// ✅ return value is always an object (matcher passes) or null (matcher fails) +expect(queryByRole('button')).toBeTruthy(); +expect(element.querySelector('.foo')).toBeTruthy(); +// also okay if you're CERTAIN that the method will never return undefined on failure +// (you can assume this from DOM or testing-library APIs if documented as such) +expect(queryByRole('button')).not.toBeNull(); +expect(element.querySelector('.foo')).not.toBeNull(); +``` + +### Browser methods aren't working + +Using browser methods like `getBoundingClientRect` won't work when using enzyme to render a document fragment. It's possible to mock this method out if needed; see the `FocusZone` unit tests as an example. + +If the test is using `userEvent.type(element)` and throws an error since `getBoundingClientRect` is missing, you can provide the option `userEvent.click(element, { skipClick: true })` to skip the step of clicking on the element (if its actual size/position is irrelevant to the rest of the test). + +### My event isn't working properly + +There are a few possibilities here: + +- Make sure to use [`@testing-library/user-event`](https://www.npmjs.com/package/@testing-library/user-event) to more realistically simulate the sequence of user events that would occur in a real interaction. +- Try using [fake timers](https://jestjs.io/docs/timer-mocks) and manually advancing them to ensure the event and related updates are triggered. +- In some cases, jsdom does not provide realistic event simulation (this is especially an issue for tests involving focus), so try [testing the scenario with Cypress](E2E-testing-with-Cypress) instead. + +### `getByRole` can't find an element or says it's hidden + +testing-library's `getByRole` will only return elements that would be included in the accessibility tree (per its heuristics). Some possible reasons why an element would register as hidden: + +- A few components have an initial off-screen render for measurement purposes (example: v8 CommandBar). In this case, use fake timers and advance the timers past the initial render before running other tests. +- Maybe the component (or the part you're trying to test) is actually not accessible--try it with a screen reader to check +- Some rare edge case where testing-library is wrong (or you want to use `getByRole` for convenience when it doesn't quite apply) + +If you need to override this, you can pass [`{ hidden: true }`](https://testing-library.com/docs/queries/byrole/#hidden) as a second argument to `getByRole` to include the hidden elements. Example: `getByRole('button', { hidden: true })` diff --git a/docs/react-wiki-archive/BestPractices/Testing.md b/docs/react-wiki-archive/BestPractices/Testing.md new file mode 100644 index 0000000000000..059a6c68b4132 --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Testing.md @@ -0,0 +1,30 @@ +Fluent UI's React-based packages use various frameworks for different types of testing. + +## Unit and functional tests + +Most of Fluent UI's tests are built using **[Jest](https://jestjs.io/)**. This allows us to run tests in a Node environment but simulates the browser using [jsdom](https://github.com/jsdom/jsdom). + +On top of Jest, we use **[React Testing Library](https://testing-library.com/docs/react-testing-library/intro)** for rendering and interacting with React components. (Some legacy tests still use Enzyme and/or react-test-renderer.) + +For more details: + +- [Jest testing in `@fluentui/react-components` ("v9") and `@fluentui/react` ("v8")](Testing-with-Jest) +- [Testing in `@fluentui/react-northstar` ("v0")](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/test-a-feature.md) + +## End-to-end (in-browser) tests + +Some scenarios, particularly those relating to focus management, cannot be realistically/reliably tested with jsdom. In these cases we use **[Cypress](https://docs.cypress.io/)** for testing with a real browser. + +For more details: + +- [E2E testing in `@fluentui/react-components` ("v9") and `@fluentui/react` ("v8")](E2E-testing-with-Cypress) +- [E2E testing in `@fluentui/react-northstar` ("v0")](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/e2e/README.md) + +## Visual regression tests + +We use **[Screener](https://screener.io/)** with [Storybook](https://storybook.js.org/basics/introduction/) to document and test various UI states of our components. + +For more details: + +- [Visual testing in `@fluentui/react-components` ("v9") and `@fluentui/react` ("v8")](Visual-regression-testing-with-Screener) +- [Visual testing in `@fluentui/react-northstar` ("v0")](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/test-a-feature.md#screener-tests) diff --git a/docs/react-wiki-archive/BestPractices/Using-icons.md b/docs/react-wiki-archive/BestPractices/Using-icons.md new file mode 100644 index 0000000000000..9823360afbf67 --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Using-icons.md @@ -0,0 +1,115 @@ +- [Font-based icons](#font-based-icons) + - [Alternative CDN options](#alternative-cdn-options) + - [Creating an icon subset](#creating-an-icon-subset) + - [What does `initializeIcons` do?](#what-does-initializeicons-do) + - [Registering custom icons](#registering-custom-icons) + - [Disabling warnings](#disabling-warnings) + - [Test scenarios](#test-scenarios) + - [Library icon registration](#library-icon-registration) + +## Font-based icons + +By default, the font-based Fluent UI icons are not added to your bundle or loaded on the page, in order to save bytes for scenarios where you don't care about icons, or you only care about a subset. + +To make the icons available, you may initialize them as follows. Note that `initializeIcons()` should only be called **once per app** and must be called **before** rendering any components. This is typically done in the app's top-level file just before the main `ReactDOM.render()` call. + +```tsx +// Also available from @uifabric/icons (7 and earlier) and @fluentui/font-icons-mdl2 (8+) +import { initializeIcons } from '@fluentui/react/lib/Icons'; + +initializeIcons(/* optional base url */); +``` + +### Alternative CDN options + +By default, the icon fonts for the default set of icons will be pulled from the SharePoint CDN. The default endpoint is `spoprod-a.akamaihd.net`, but if you run into access/security issues from the Akamai domain, you can also pass in `https://static2.sharepointonline.com/files/fabric/assets/icons/` as the `baseUrl`. + +If you would like the icons to be served from your own CDN, simply copy the files from `@uifabric/icons/fonts` (or `@fluentui/font-icons-mdl2/fonts` in version 8+) to your CDN. A build step is recommended to automate this. Then, in `initializeIcons`, provide the base URL to access those fonts. Note that it will require a trailing slash. + +(If you're using custom icons as described under "Registering custom icons" below, you don't need to modify the CDN setting.) + +### Creating an icon subset + +The Fabric Icons tool, https://aka.ms/uifabric-icons, lets you search and browse all of Fabric/Fluent UI's MDL2 icons. You can also use it to create and maintain subsets of the icon font to use in your web apps, which are drop-in replacements for the default Fabric Core and Fluent UI React icon sets. In addition, the Fabric Icons tool is updated with new icons several times a month, whereas the default Fluent UI React set is updated only occasionally. You can see detailed docs for the tool at https://aka.ms/uifabric-icons?help. + +Note that if you use the Fabric icons tool to create your own icon subset, you will also need to host those assets on your own CDN. + +### What does `initializeIcons` do? + +It registers a map of icon names, which define how to render icons. Icons can be rendered either through JSX components, or as a font character. The icon code will register the font-face definition only when a given icon from a subset is referenced. + +What we're trying to optimize here is download size. We define a map of icon codes which map to a font-face. When the `Icon` component renders the `Upload` icon, we determine if the font-face has yet been registered, an if not, we add it to the page, causing the subset containing the `Upload` icon to be downloaded. + +The `@uifabric/icons` package (or `@fluentui/font-icons-mdl2` in version 8+) can resolve over 1000 different icons, and will download from the 10+ font partitions, minimizing download overhead. We also include the most common icons in the first partition, optimizing for the basic scenarios. If there are commonly used icons missing in there, please file an issue so that we can evaluate adjusting the primary partition. + +### Registering custom icons + +If you want to use a different icon font or SVG icons, you can use `registerIcons` to add custom icons. + +#### Custom SVG icons + +SVG icons, such as the ones from `@fluentui/react-icons-mdl2`, can be registered as follows: + +```tsx +import { registerIcons } from '@fluentui/react/lib/Styling'; +import { ChevronDownIcon } from '@fluentui/react-icons-mdl2'; + +registerIcons({ + icons: { + ChevronDown: , + }, +}); +``` + +You can then use those icons anywhere you'd normally use icons, such as the `Icon` component or in `iconProps`: + +```tsx +import { Icon } from '@fluentui/react/lib/Icon'; + +const IconTest = () => ; +``` + +#### Custom font family + +You can also use this with custom font families: + +```tsx +import { registerIcons } from '@fluentui/react/lib/Styling'; + +registerIcons({ + fontFace: { + fontFamily: `"CustomFontFamily"`, + }, + icons: { + Up: '\uE417', + Down: '\uE416', + }, +}); +``` + +### Disabling warnings + +When icons are rendered using the `Icon` component, but have not yet been registered, you will see console errors indicating so. In most cases, this can be addressed by registering the icons. But there are 2 cases, where this isn't desirable: + +#### Test scenarios + +In test scenarios, you may want to simply disable the warnings and avoid registering icons. To do this: + +```tsx +import { setIconOptions } from '@fluentui/react/lib/Styling'; + +// Suppress icon warnings. +setIconOptions({ + disableWarnings: true, +}); +``` + +#### Library icon registration + +If your code is running in an environment where icons may have already been registered, you may need to disable the warnings. (By default, registering the same icon twice will ignore subsequent registrations.) To initialize icons and avoid duplication warnings, pass options into `initializeIcons`: + +```tsx +import { initializeIcons } from '@fluentui/react/lib/Icons'; + +initializeIcons(undefined, { disableWarnings: true }); +``` diff --git a/docs/react-wiki-archive/BestPractices/Using-markdown-for-Fabric-documentation.md b/docs/react-wiki-archive/BestPractices/Using-markdown-for-Fabric-documentation.md new file mode 100644 index 0000000000000..0d8e7fb35d123 --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Using-markdown-for-Fabric-documentation.md @@ -0,0 +1 @@ +Content moved to [Markdown documentation](Markdown-documentation). diff --git a/docs/react-wiki-archive/BestPractices/Visual-regression-testing-with-Screener.md b/docs/react-wiki-archive/BestPractices/Visual-regression-testing-with-Screener.md new file mode 100644 index 0000000000000..ee1a28f9941ca --- /dev/null +++ b/docs/react-wiki-archive/BestPractices/Visual-regression-testing-with-Screener.md @@ -0,0 +1,142 @@ +> 🚨🚨 **This page is primarily about `@fluentui/react-components` ("v9") and `@fluentui/react` ("v8") and related packages.** 🚨🚨  [See this page for `@fluentui/react-northstar` ("v0").](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/test-a-feature.md#screener-tests) + +## Overview + +We use [Screener](https://screener.io/) with [Storybook](https://storybook.js.org/basics/introduction/) to document and test "stories" containing various UI states of our components. ([See this page for other types of tests.](Testing)) + +With every pull request, Screener renders the stories for each library, checks for visual changes, and updates a GitHub status check for that library. If changes are found, the status will fail until the regressions are fixed or an admin approves the changes. + +The Screener stories for our components are found in different locations for each React library: + +- `@fluentui/react` version 8: [`apps/vr-tests/src/stories`](https://github.com/microsoft/fluentui/tree/master/apps/vr-tests/src/stories) +- `@fluentui/react-components` version 9: [`apps/vr-tests-react-components/src/stories`](https://github.com/microsoft/fluentui/tree/master/apps/vr-tests-react-components/src/stories) +- [See this page for `@fluentui/react-northstar` version 0](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/test-a-feature.md#screener-tests) + +## Writing stories + +Currently, our stories are written with Storybook's [legacy `storiesOf` API](https://github.com/storybookjs/storybook/blob/next/lib/core/docs/storiesOf.md) (this will change in the future, see [#21779](https://github.com/microsoft/fluentui/issues/21779)). + +Here's an example of a story file. See after the code for explanations of its different parts. + +```tsx +import * as React from 'react'; +import Screener, { Steps } from 'screener-storybook/src/screener'; +import { storiesOf } from '@storybook/react'; +import { TestWrapperDecorator } from '../utilities'; +import { Link, ILinkProps } from '@fluentui/react'; + +storiesOf('Link', module) + .addDecorator(TestWrapperDecorator) + .addDecorator(story => ( + + {story()} + + )) + .addStory('Root', () => I'm a link, /* optional */ { rtl: true }) + .addStory('Disabled', () => ( + + I'm a disabled link + + )); +``` + +### `addDecorator(...)` + +Decorators specified with `addDecorator` are rendered around each story. We use decorators to define screener steps and optionally visual wrappers. + +Most stories use `TestWrapperDecorator` or a variant to wrap the component with consistent padding and possibly a set width, and to provide a `.testWrapper` class which can be used to crop snapshots to a smaller area. + +```ts + .addDecorator(TestWrapperDecorator) +``` + +[A `` element with `Steps`](https://github.com/screener-io/screener-storybook) is added as a decorator to define interaction and snapshot steps. + +```tsx + .addDecorator(story => ( + // an actual test would usually have more steps + + {story()} + + )) + +``` + +To make visual states easier to compare, most snapshots should crop to a specific selector: `{ cropTo: '.someSelector' }`. (If you use `TestWrapperDecorator`, you can crop to the `.testWrapper` class.) Otherwise it will capture the whole screen, which includes a lot of extra white space. + +Certain components may be written with a custom decorator/wrapper, and you may crop to a different CSS class or omit the `cropTo` option altogether. Components that render outside their container, require specific styles on their parent, or render on a different layer, such as Callout, are cases where you would customize the decorators. + +```tsx +storiesOf('Slider', module) + .addDecorator(story => ( + // Vertical slider requires its parent to have a height specified +
+ {story() /* Render story (component) inside this container */} +
+ )) + .addDecorator(TestWrapperDecorator) + .addDecorator(story => ( + + {story()} + + )) + .addStory(); +``` + +### `addStory(...)` + +Individual stories are added with the `addStory()` method, which is a custom wrapper for Storybook's `add()` method. It's defined in `apps/vr-tests/.storybook/preview.js` and allows adding stories with additional configuration options, such as an `rtl` flag which allows the story to run twice: once in left-to-right mode and once in right-to-left mode. + +```tsx +storiesOf('Panel', module) + .addDecorator(TestWrapperDecorator) + .addDecorator(story => {story()}) + .addStory( + 'Small left w/ close button', + () => , + { rtl: true }, + ); +``` + +## Testing stories + +It's not possible to do a full Screener run locally, but you can locally build and serve the storybook to at least see what your stories will look like. + +From the repo root, run `yarn start` and choose either `@fluentui/vr-tests` for v8, or `@fluentui/vr-tests-react-components` for v9. + +## GitHub integration + +In the past, we used the official [`screener-runner`](https://www.npmjs.com/package/screener-runner) test runner to handle queueing screener runs and updating GitHub PR statuses. However, this has some issues: + +- Only supports one screener "project" per repo (we need 3 for v8, v9, v0) +- Serves the VR test storybook live and runs the tests via an `ngrok` tunnel, which causes several issues: + - `ngrok` service is not entirely reliable + - `screener-runner` hardcodes a 30-minute timeout (which we hit more often as we added more stories) + - Keeps a build machine busy until the run finishes + +To work around these issues, we wrote a custom screener proxy with the following new features: + +- Multiple projects/statuses per repo +- Can mark a project's screener status as "skipped" if that project's tests aren't relevant to the PR +- "Fire and forget": the proxy service queues a screener run against a version of the VR test storybook which has been uploaded to blob storage (increasing reliability compared to an `ngrok` tunnel and allowing the build machine to be released), then waits for a screener webhook notifying completion and updates the github status + +See the `screener-proxy` repo in the internal UI Fabric project for more details. diff --git a/docs/react-wiki-archive/Broken-NPM-Publishes.md b/docs/react-wiki-archive/Broken-NPM-Publishes.md new file mode 100644 index 0000000000000..e2c6939522ce2 --- /dev/null +++ b/docs/react-wiki-archive/Broken-NPM-Publishes.md @@ -0,0 +1,6 @@ +## What to do? + +In the event that we publish a package version that's broken, follow the steps below to mediate: + +1. Deprecate the broken version for each package that were recently published and affected. +2. Update `latest` tag to point to the last known good version published. You may need to do this not just for the direct package affected but for the whole dependency tree of that package (i.e. `fluentui/react` v8 publishes a broken version, all its v8 dependencies and the v8 dependencies of its dependencies and so on) due to caret dependencies. diff --git a/docs/react-wiki-archive/Build-Command-Changes.md b/docs/react-wiki-archive/Build-Command-Changes.md new file mode 100644 index 0000000000000..61ca6c81c2e95 --- /dev/null +++ b/docs/react-wiki-archive/Build-Command-Changes.md @@ -0,0 +1,13 @@ +[A PR in early 2020](https://github.com/microsoft/fluentui/pull/11574) introduced some important changes to Fabric's build commands which are detailed below. [The Build Command documentation](Build-Commands) has been updated to reflect these changes. + +| Monorepo Build Command | Prereqs | Important Notes | Description | +| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `yarn build` | | Now TypeScript only. No longer runs bundle, lint or test. No longer production build by default. | Generates output using TypeScript. | +| `yarn buildci` | | No change. **This command approximates PR build steps and is useful for validating your build locally.** | Reproduction of PR build steps: build, lint, test, bundle. | +| `yarn buildto` | | Now TypeScript only. No longer runs bundle, lint or test. No longer production build by default. | Builds to specified target package. | +| `yarn buildfast` | | Removed (redundant with `yarn build` and `yarn buildto`) | | +| `yarn bundle` | build | New | Runs webpack. Webpack configs use lib output as entry point, requiring build as prereq. | +| `yarn clean` | | New | Cleans package output. | +| `yarn lint` | build | New | Runs lint and lint-imports tasks. lint-imports requires build artifacts to detect that physical file exist for imports from 'lib'. | +| `yarn test` | build | New (replaces `yarn validate`) | Runs jest. Build artifacts required for dependencies of packages under test. | +| `yarn validate` | | Removed (replaced by `yarn test`) | | diff --git a/docs/react-wiki-archive/Build-Commands-5.0,-6.0-Branches.md b/docs/react-wiki-archive/Build-Commands-5.0,-6.0-Branches.md new file mode 100644 index 0000000000000..4bd2d5fc9ed83 --- /dev/null +++ b/docs/react-wiki-archive/Build-Commands-5.0,-6.0-Branches.md @@ -0,0 +1,188 @@ +This page outlines the major commands used for development in the Fluent UI (Fabric) repo's **5.0 and 6.0 branches.** + +For the **master** or **7.0** branches, [see this page](Build-Commands). + +🚨🚨🚨  **WARNING** 🚨🚨🚨  You **MUST** use **Node 8 or 10** for development in the `5.0` and `6.0` branches. It's recommended to set this up using `nvm`--see instructions on the [nvm setup page](nvm-setup). + +- Quick references + - [Repo-wide commands](#quick-reference-repo-wide-commands) + - [Package-specific commands](#quick-reference-package-specific-commands) +- [Repo-wide commands](#repo-wide-commands) + - [Install and build](#install-and-build) + - [Before check-in](#before-check-in) + - [Troubleshooting](#troubleshooting) + - [Advanced: modifying dependencies, adding packages/components](#advanced-modifying-dependencies-adding-packagescomponents) +- [Package-specific commands](#package-specific-commands) + +### Quick reference: repo-wide commands + +These commands should be run from the root of the Fluent UI (Fabric) Git repo. + + +| Command | Explanation | +|------------|------------| +|[`npm install`](#npm-install)|Install dependencies and build most code| +|[`npm start`](#npm-start-repo)|Start demo site and inner development loop for `office-ui-fabric-react`| +|[`npm run build`](#npm-run-build-and-npm-run-buildfast)|Run a full production build| +|[`npm run buildfast`](#npm-run-build-and-npm-run-buildfast)|Rebuild only projects that have changed| +|[`npm run codepen`](#npm-run-codepen)|Use a local build in codepen| +|[`npm run change`](#npm-run-change)|Create change files| +|[`npm run update-snapshots`](#npm-run-update-snapshots-repo)|Update Jest snapshots for `office-ui-fabric-react`| +|[`npm run update-a11y`](#npm-run-update-a11y)|Update accessibility test snapshots| +|[`npm run update-api`](#npm-run-update-api-repo)|Update API review file for `office-ui-fabric-react`| +|[`npm run scrub`](#npm-run-scrub)|Revert the repo to a clean state *(commit or stash your changes first)*| +|[`npm run rush-update`](#npm-run-rush-update)|Use when adding/modifying dependencies| +|[`npm run create-component`](#npm-run-create-component)|Create a new experimental component| +|[`npm run create-package`](#npm-run-create-package)|Create a new package| + + +### Quick reference: package-specific commands + +These commands can be used in an individual package during development. You must `cd` to the package's folder before running the commands. + + +| Command | Explanation | +|------------|------------| +|[`npm start`](#npm-start-package)|Start inner development loop for current package| +|[`npm run build`](#npm-run-build-package)|Build and run tests for current package| +|[`npm run clean`](#npm-run-clean)|Clean up build output for current package| +|[`npm run update-snapshots`](#npm-run-update-snapshots-package)|Update Jest snapshots for current package| +|[`npm run update-api`](#npm-run-update-api-package)|Update API review file for current package| +|[`npm run start-test`](#npm-run-start-test)|Start inner development loop for Jest tests| +|[`npm run just `](#npm-run-just)|Run an individual task| + + +# Repo-wide commands + +In general, we abstract away the tooling behind `npm run` scripts. This way, we can avoid forcing developers to have global tools to be installed, other than what was already available from node.js. + +## Install and build + +### `npm install` + +`npm install` installs dependencies and builds most code. It should be run immediately after each `git pull` or `git merge` to get your repo back into a consistent state that allows for development. + +Since most of our development work is on `office-ui-fabric-react` (OUFR), this command will build **up to OUFR**: packages it depends on, OUFR itself, and `fabric-website-resources` which powers `npm start`. + +If `npm install` reports that your Node version is too new (or fails with an error like `TypeError: cb.apply is not a function`), [see these instructions](Legacy-Branches#node-version-setup) for how to install Node 8 or 10 alongside your current main Node version. + +### `npm start` (repo) + +To see a demo app with the OUFR components, simply run `npm start`. Note this starts `webpack-dev-server` only on OUFR. This command relies on certain other projects having been built. If it fails to find some files, stop the command, run `npm install`, and try `npm start` again. + +Note that `npm` recognizes `start` as a command, so `npm start` means the same as `npm run start`. + +### `npm run build` and `npm run buildfast` + +`npm run build` does a full rebuild in production mode (abstracting `rush rebuild`). + +`npm run buildfast` builds only projects that changed (abstracting `rush build`). + +#### Common options + +These options work with either `build` or `buildfast`, and can be combined together. Note that since these are `npm run` scripts, you must include a `--` after the script name but before any options: e.g. `npm run buildfast -- --min --to some-project`. + +- `--to `: Build only up to the given project, e.g. `npm run buildfast -- --to experiments` + +- `--from `: Build starting from the given project, e.g. `npm run buildfast -- --from office-ui-fabric-react` + +- `--min`: Build but don't run tests, e.g. `npm run buildfast -- --min` + +- `--production`: Do a production-mode build, e.g. `npm run buildfast -- --production` + +### `npm run codepen` + +In our bug templates, we encourage bug reporters to submit codepen examples. It is sometimes helpful to directly run those examples against in-development code. Run `npm run codepen` to generate several ` +``` + +You can also set it from your app's root JS file, but **it MUST run before anything is imported from Fluent UI React!** For example: + +```ts +window.FabricConfig = { fontBaseUrl: 'https://your-url-here' }; +// Fabric imports must go AFTER this ^^^ +import { Button } from '@fluentui/react'; +``` + +### Caveats + +- Again: this global must be set **BEFORE** any Fluent UI React code is imported or executed. +- The alternative CDN is assumed to follow the same file structure (relative to `fontBaseUrl`) as the default CDN. +- [#3881](https://github.com/microsoft/fluentui/issues/3881) tracks adding a way to change the CDN without a global. diff --git a/docs/react-wiki-archive/Development-Workflow.md b/docs/react-wiki-archive/Development-Workflow.md new file mode 100644 index 0000000000000..2fb18516c4924 --- /dev/null +++ b/docs/react-wiki-archive/Development-Workflow.md @@ -0,0 +1,257 @@ +Please use the following steps to contribute bug fixes or other changes. + +- [Set up your development environment](#set-up-your-development-environment) + +- Code and test the change. + + - [Update your master branch](#update-your-master-branch) + - [Open the repo](#open-the-repo) + - [Create a branch](#create-a-branch) + - [Clean up the repo](#optional-clean-up-the-repo) + - [Install and build](#install-and-build) + - [Make the change](#make-the-change) + - [Verify your changes](#verify-your-changes) (running and debugging unit tests) + - [Commit your changes](#commit-your-changes) + - [Create change files](#create-change-files) + - [Push changes](#push-changes) + +- [Create a pull request.](#creating-a-pull-request) + +- Make sure the build and all the tests are passing. + +## Set up your development environment + +[Follow the steps on the Setup page.](Setup) This includes instructions for installing development tools, setting up your own fork, and setting up your local clone. + +If you're developing against a previous major version branch, it's recommended to set up a separate local copy of the repo for that branch. + +- For `7.0`, see [Contributing to the `7.0` branch](Contributing-to-the-7.0-branch) +- For `6.0` or `5.0`, see [Legacy Branches](Legacy-Branches) + +### Optional: Extra VS Code setup + +These are some VS Code extensions and settings that can be helpful for Fluent UI React development. + +Some of the setup steps including updating VS Code settings. To open the settings page, press `ctrl+shift+P` (`cmd+shift+P`) and type **user settings**. + +- Prettier + - [Install extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + - It's recommended to enable the "Prettier: Require Config" setting (in VS Code settings) to prevent Prettier from enforcing obnoxious defaults (such as line length 80) everywhere. +- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + +## Update your master branch + +Skip this if you just cloned the repo. Otherwise, run the following to ensure that your branch is up to date. (Replace `master` with `7.0` or `6.0` if applicable.) + +**Note: these steps assume you have your `origin` and `upstream` remotes configured as described on the [setup page](Setup#setting-the-upstream-remote).** + +``` +git checkout master +git pull upstream master +git push +``` + +## Detailed instructions for making a change + +If this is your first change, below are some more detailed steps for getting your branch set up and submitting a PR. You can either do this with the command prompt or with a combination of the command prompt and Sourcetree or VS Code. + +Some of steps below include instructions specific to VS Code. It's fine to use another editor/IDE if you prefer, but we're providing instructions for VS Code because its automatic TypeScript integration and other features make it very convenient for Fluent UI React development. + +### Open the repo + +To start, open the root folder of the repo in VS Code. You can do this by either `cd`ing to the folder and running `code .`, or opening VS Code and going to File > Open Folder. (You can also use another IDE or editor if you prefer.) + +To open files in VS Code, use the navigation sidebar or press `ctrl+P` (Mac: `cmd+P`) and type part of the filename. + +VS Code also has a built-in terminal. Press `` ctrl+` `` (Windows or Mac) to open it. (Using the built-in terminal isn't required, just convenient.) + +### Create a branch + +It's recommended to start with a fresh branch for each bug or task. If you have any lingering changes in your current branch that you want to save, go ahead and commit them. If you are just beginning, then you are good to go. + +If you're familiar with Git/GitHub and have a preferred way to create branches, go ahead and use that. Otherwise, choose one of the options below. + +#### Option 1: Command line + +1. Open a command prompt and `cd` to the root of your local copy of the repository +2. Follow the instructions under ["Update your master branch"](#update-your-master-branch) +3. Choose a name for your branch and run `git checkout -b your-branch-name` (in the name, don't use spaces, and limit special characters to `-` `_` `/`) + +#### Option 2: Sourcetree + +1. Open your local copy of the repository in Sourcetree +2. In the sidebar under **Branches**, double-click the **master** branch to check it out. +3. Click the **Branch** button in the top bar +4. Choose to create a new branch, and give it a name. (Don't use spaces, and limit special characters to `-` `_` `/`.) Click the button to create the branch. + +### Optional: Clean up the repo + +If you haven't made any Fluent UI React changes in awhile or you're switching between major release branches (`master`/`7.0`/`6.0`/`5.0`), it's recommended to use the `scrub` script to clean up the repo. (This shouldn't be needed if you've been making Fluent UI React changes regularly and haven't switched major release branches.) + +`scrub` permanently removes all node_modules, build output, and other untracked files or uncommitted changes, which reduces the possibility of strange install/build issues. + +_**Commit or stash any changes you want to keep**_, then run `yarn scrub` (in `master`) or `npm run scrub` (in `6.0`). + +### Install and build + +**Every time you update from master, you should install dependencies and do a basic build** (to pick up any changes others made). + +If working in a branch based on `master` or `7.0`: + +1. Run `yarn` to install dependencies +2. Depending on which package(s) you're working in and the type of change, you may need to run a build. You can either do `yarn build` to build everything, `yarn build:min` to build common packages, or `yarn buildto your-package-name`. + +If working on a branch based on `6.0`: + +1. Run `npm install` to install dependencies and build up to office-ui-fabric-react +2. The next step depends on where your change will be: + - office-ui-fabric-react (or a package it depends on): all done! + - Some other package such as experiments or charting: `npm run buildfast -- --to your-package-name` + +### Make the change + +Now it's time to start making your change. In most cases, if your change is in a single package, the easiest way to build and verify your change is with the local demo app. + +If working in a branch based on `master` or `7.0`: + +1. Run `yarn start` (and choose your package name) to start the local demo app, backed by [Storybook](https://storybook.js.org/) +2. When you make changes and save the file, it will re-compile + +If working on a branch based on `6.0`: + +1. `cd` to the folder for your package (optional for changes in the office-ui-fabric-react package) +2. Run `npm start` to start the local demo app, backed by `webpack-dev-server` +3. When you make changes and save the file, it will re-compile + +Alternatively, if you prefer not to re-compile on change, you can run `yarn build` from the package folder. + +If you're making changes across multiple packages, you can either: + +- `yarn start` and choose the "leaf" package (the one consuming the other packages) and `yarn build` in the other packages, OR +- From the root, `yarn buildto leaf-package-name` + +### Verify your changes + +#### Run package unit tests + +To verify your changes, start by running unit tests in the package where your change is. **Start by `cd`ing to the package's folder**, then choose one of the following: + +- To run tests once: `yarn test` (in 6: `npm run build`) +- To start the tests and re-run when a file changes: `yarn start-test` (in 6: `npm run start-test`) +- (`6.0` only) To run tests once, without a full package build: `npm run just jest` + - Note: this should still pick up the latest changes to TS files + +Some of the tests take "snapshots" of the rendered controls. If you get a snapshot failure, and the change is expected, run `yarn update-snapshots` (in 6: `npm run update-snapshots`) and commit the changed files. + +If you get an error about the API file being out of date, run `yarn update-api` from that package's folder. + +#### Debugging unit tests + +If you're having a lot of trouble with a test, or are writing a new test and would like to run a continuous loop as you develop (with just that test), the easiest way to do this is using VS Code. + +1. Open the root folder of the repo in VS Code +2. Click the **Debug** button in the sidebar +3. In the dropdown at the top of the debug panel, choose **Debug current open test** +4. Open your test file +5. Press the **green play button** in the panel (or press **F5**) + +The test will re-run as you make and save changes. You can also set breakpoints and debug into the test or component code. + +#### Run all tests and lint + +Once the tests in the package you've modified are passing, it's time to run a full build. + +Go to the root folder of the repo and run the following, then address any failures that come up. + +- For `master` or `7.0`: run `yarn buildci` to run tests and lint + - You can optionally follow this with `yarn bundle` but this is less likely to fail in most scenarios. + - If any API files (`*.api.md`) change, you should check them in. +- For `6.0`: run `npm run buildfast` + - If you get a message in a package about the API file being out of date, `cd` to that package and run `yarn update-api`. + +### Commit your changes + +Once you've made your change, or a subset of the change, you need to **commit** it to Git. A commit is a list of changes and a message describing them, plus other metadata. (Other terminology: In Git, files must be **staged** before committing, which just means telling Git which changes you'd like to commit now or leave for later.) + +You can commit multiple times until you are ready to make a pull request. You should keep the message short since it will not be used in the release notes and is just for keeping track of the multiple commits in one pull request. + +To commit files, choose one of the options below. (As usual, if you already have a different way you like to commit changes, that's fine too.) + +#### Option 1: VS Code + +1. Open the root folder of the repo in VS Code +2. Click the **Source Control** button in the sidebar. This will show a list of changed files. +3. Click the **+** next to files you'd like to stage (or the **+** at the top to stage all files) +4. In the text box at the top, type your commit message and then press `ctrl+enter` (Windows) or `cmd+enter` (Mac) + +#### Option 2: Git command line + +1. `cd` to the root folder of the repo +2. Run `git status` to see the list of changed files +3. If you'd like to commit all the files, run `git add -A`. Otherwise, run `git add path/to/file-or-folder` to stage files individually. +4. Run `git commit -m "your message here"` + +#### Option 3: Sourcetree + +In Sourcetree, click on commit in the top left. This won't actually do anything to your files, it will just change to show the commit UI. In the bottom container, stage all of the files you want to submit by selecting them and clicking "Stage". Add a short message in the textbox at the bottom on what is included in your change. This will not show as your entire submission text, just for this commit. + +### Create change files + +Fluent UI React uses "change files" to figure out what type of release to make based on your changes (none, patch, minor, major) and generate a list of changes included in each release. + +From the root of the repo, run `yarn change` (in 6: `npm run change`). This will prompt you to write a change description for each package. + +The change description will be used in the release notes, so it should include the name of the component (or utility etc) that you modified and a high-level summary of what you did. + +See the [Change Files](Change-Files) page for more information about change files, including how to choose the appropriate change type. + +### Push changes + +Before making a pull request, you must push your branch to your fork on GitHub. Choose one of the methods below (or some other method you prefer). + +**Note: these steps assume you have your `origin` and `upstream` remotes configured as described on the [setup page](Setup#setting-the-upstream-remote).** + +#### Option 1: VS Code + +Towards the bottom left corner of the window, look for an icon showing a cloud with an up arrow. Click that, and choose **origin**. (Alternatively, press `ctrl+P` or `cmd+P` and type **Git: Push**.) + +If you need to push more changes later, you can use the same button, but it will have a sync icon (circles/arrows). Click that to push your new changes, as well as pulling down any changes made on the remote copy of the branch. (Alternatively, press `ctrl+P` or `cmd+P` and type **Git: Sync**.) + +#### Option 2: Git command line + +Run `git push -u origin` to push your branch to your fork (`origin`). + +To push additional changes later, you can just run `git push`. + +#### Option 3: Sourcetree + +In Sourcetree click Push. + +## Creating a pull request + +Go to the [main Fluent UI React repo on GitHub](https://github.com/microsoft/fluentui). You should see a yellow bar at the top with your branch name and a button that says **Compare & Pull Request**. Click that button. + +> **NOTE:** If your change is based on the `7.0` or `6.0` branch, be sure to select that branch for the **base:** option instead of `master`. Otherwise your PR will have conflicts and lots of extra changes. + +Fill out the fields with full description of your change, areas to test, and make sure you fill out the checklist when you have completed each item (add an `x` in between the `[]` at the top and make sure there are no spaces). If you are modifying the UI, this is also a good location to add screenshots of the before and after. + +Click **Create Pull Request**, then watch it go through the process of running build checks and wait for reviews. + +### Addressing check/build failures + +The most common check failure is the PR build (**Fluent UI React - PR and CI** or similar). To see why the build (or another step) failed: + +1. Scroll down to the bottom of the PR page and click **Details** next to the check name. +2. On the next page, click the text **1 errors / 0 warnings** (or similar) or **View more details on Azure Pipelines**. +3. Click the name of the build step that failed to see the log +4. Scroll to the bottom of the log (usually) to see the error + +The most common errors are: + +- Missing change files: run `yarn change` and push again +- Missing snapshot updates: if the updates seem reasonable, run `yarn update-snapshots`, commit, and push. Run this command from the root to update all snapshots, or within a package to update only that package's snapshots. +- _(Now applicable to `6.0` only--`7.0` and `master` handle this automatically)_ Missing API file updates: if the updates seem reasonable, run `yarn update-api` from the relevant package, commit, and push + +### Pull request reviews + +Someone will review your change before the change is allowed to be merged in. They may ask questions for more information or ask you to change things. Be sure to respond to their comments and push additional changes to the branch if they ask you to modify things before they sign off. If no one has looked at it in a few days, you can ping whomever is on shield and ask them to take a look. diff --git a/docs/react-wiki-archive/Experimental-Component-Checklist.md b/docs/react-wiki-archive/Experimental-Component-Checklist.md new file mode 100644 index 0000000000000..17bce0dfdb0ee --- /dev/null +++ b/docs/react-wiki-archive/Experimental-Component-Checklist.md @@ -0,0 +1,31 @@ +**WARNING: As of Fluent UI React version 7/8, the ideas on this page are generally correct, but we're in the process of developing new detailed guidance. Until we have a chance to fully update this page, please reach out to the team for current guidance.** + +## Checklist before creating PR to experiments + +- Validate file/package structure +- Validating the atomic-ness of the component + - Is the component unique (is it already implemented elsewhere) + - Can it be broken down further +- Validating the api surface + - Does it have the basic expected props? + - Are there naming or typing inconsistencies? + - Is it hard to use or understand? +- Is the documentation complete and clear? + - Are the prop descriptions consistent with other prop descriptions? +- Are the examples inspiring, delightful, useful, straightforward? + - Can you copy paste into a codepen? +- Are the features robust enough to delight? (are we missing basic fundamentals?) + +## Checklist before graduating out of experiments + +- Hackathon to use/create/tinker/toy +- Refine accessibility (another hackathon?) + - Screen Reader + - High Contrast + - Themable + - RTL/Localization + - Keyboarding +- Example affect on bundle size +- Fill out Questionnaire + - What are the target apps these are built for +- Who will be the CODEOWNERS diff --git a/docs/react-wiki-archive/FAQ---Fabric-and-Stardust-to-Fluent-UI.md b/docs/react-wiki-archive/FAQ---Fabric-and-Stardust-to-Fluent-UI.md new file mode 100644 index 0000000000000..e6ac99f912af7 --- /dev/null +++ b/docs/react-wiki-archive/FAQ---Fabric-and-Stardust-to-Fluent-UI.md @@ -0,0 +1,63 @@ +# FAQ - Fabric and Stardust to Fluent UI + +Fabric and Stardust are evolving into Fluent UI. Here are some common questions and answers. + +### Fabric to Fluent UI...why the name change? + +It's a consolidation of names and concepts. + +Fluent UI represents our UX building approach. It encapsulates Microsoft's concerted effort to unify design and code across platforms and technologies while following the Fluent Design System. + +This extends beyond Fabric's original roots in web and React, hence the rename. We want one umbrella to fold our component and theming efforts under. + +### How am I affected by Fluent UI? + +If you're a Fabric customer: + +Nothing at this time. If you have references to `office-ui-fabric-react` in your app, rest assured that whether you're still on v5, v6, or v7, we will still take PRs and apply fixes as needed. + +Our primary package was renamed to `@fluentui/react`, but this package simply exports bits from the `office-ui-fabric-react` package. This ensures no partners are broken, they still receives fixes, but you can upgrade your package name at your leisure. + +Our plan is that the upcoming v8 package will start publishing only under the `@fluentui/react` name. To make the transition easier, we will be offering an upgrade script you can run on your project to upgrade to v8. This will fix your package names, but also make sure that any components which have major breaking improvements are patched to reference compat imports so that you can adjust to consume improvments when you're ready. + +### What package should I use to build a new application? + +#### `@fluentui/react` - Best for building Office apps\* + +- Used by Outlook, SharePoint, Office (Word/PowerPoint/Excel), and more. +- Consolidating with `@fluentui/react-northstar` over time +- Default look and feel: **Fluent** +- Follows semantic versioning: **Yes** +- Release frequency: **~2 major release per year** +- Break frequency: **On major releases** +- Use: **For building experiences aligned with Office UX.** + +#### `@fluentui/react-northstar` - Best for building Teams apps\* + +- Used by Microsoft Teams, Teams Apps. +- Consolidating with `@fluentui/react` over time +- Default Look and Feel: **Fluent - Teams** +- Follows SemVer: **Yes, but pre-release (only major releases)** +- Release Frequency: **As needed: ~Monthly** +- Break Frequency: **No more frequent than Monthly** +- Use: **Fast moving package for building experiences aligned with Teams UX.** + +**\* Both libraries are converging over time. Review the docs for each and choose the best starting point for you today.** + +There also is a `@fluentui/react-next` package that acts as a staging ground for components. This package should only be used for early testing and validation. It should not be used for production. + +### Why Stardust? Why the merge? Why 2 libraries in one repo? + +Microsoft is a large organization with many efforts. Customers were running into issues working on M365 code which needed to integrate with Teams, which was building out Stardust separately from Fabric. This diversion led to fragmentation, causing partners to build their apps twice. + +We recognize that as a huge issue. As a result, we have decided to converge the two libraries to provide one solution. It can't happen overnight, so we're moving along to pull the best of Stardust concepts and Fabric concepts and ship them iteratively in installments. + +Fabric customers should rest assured, we have not dropped support for you. + +Stardust customers should also rest assured; we won't drop support for you either. + +Our end goal is to unify these things. One styling solution, one theming solution, one set of utilities, one set of component authoring patterns, one set of components, one documentation site. + +### Are the different release channel packages compatible with each other? + +They can live side by side. They currently use different theming and css approaches, which is something we're addressing over the next future updates. diff --git a/docs/react-wiki-archive/FAQ.md b/docs/react-wiki-archive/FAQ.md new file mode 100644 index 0000000000000..1a662cd42e92a --- /dev/null +++ b/docs/react-wiki-archive/FAQ.md @@ -0,0 +1,86 @@ +# Fluent UI React FAQ + +## _Q. What is Fluent UI React?_ + +Fluent UI React (formerly Fabric React) is a responsive, mobile-first, open-source collection of robust components designed to make it quick and simple for you to create web experiences using the Fluent design language. + +## _Q. Who uses Fluent UI React?_ + +React components from Fluent UI React are used by many teams across O365 and Microsoft for building their experiences. Some examples are SharePoint, OneDrive, Outlook, VisualStudio team services, ... + +These components are also used by third-party developers, in particular those building components using the SharePoint Framework. + +## _Q. How do I get started with Fluent UI React?_ + +Start from our [wiki homepage](Home) or the ["Get started" section](https://developer.microsoft.com/en-us/fluentui#/get-started/web) on our website. + +## _Q. Where is the official website located?_ + +https://developer.microsoft.com/fluentui + +## _Q. I am seeing a bug. Where can I open an issue?_ + +Please open all issues at our [GitHub issues](https://github.com/microsoft/fluentui/issues) location. + +Things to remember while opening an issue: + +- Please fill out as many details as you can. +- We **highly encourage** you to submit PRs for issues. + +## _Q. Can I contribute to Fluent UI React?_ + +Fluent UI React is an open-source distributed project. Lots of developers from inside and outside Microsoft contribute to this project. We highly encourage contributions. There is a core team that works hard to stay on top of the issues and pull requests. + +## _Q. Why should I contribute?_ + +Fluent UI React is an open-source distributed project. If you are building a new app inside O365 or Microsoft, this project will potentially save you lots of time, resources and headaches. We encourage all developers who use Fluent UI React to return a small amount to the community. If you notice bugs, we encourage you to not only open an issue on it but also help fix it. If you have a component that you believe others should use, feel motivated and encouraged to contribute that component back to the community. Sharing is caring. Many developers contribute outside their primary job responsibilities. Additionally, there is plenty to learn. We use a lot of cutting edge best practices used in the industry. Learning those can help you in your career. + +## _Q. How do I communicate with a Fluent UI React core team member?_ + +We have a very active community both outside and inside Microsoft. Please use the Microsoft [Teams channel]() for communication from within Microsoft. And a [GitHub issue](https://github.com/microsoft/fluentui/issues) from outside Microsoft. We triage these issues at least once a week. + +## _Q. How do I contribute to Fluent UI React?_ + +Start by reading our [Contributing](Contributing) document. Please point out any missing or incorrect details. + +## _Q. Can I become a part of the Fluent UI core team?_ + +Yes, you totally can. You will need to help out with reviewing pull requests and triaging and fixing issues. For now, only Microsoft employees can be a part of the core team. We are looking into changing that policy to allow non-Microsoft folks to be a part of the core team. + +## _Q. My pull request has been hanging for a long time. What do I do?_ + +We are very proactive and work hard to keep the outstanding pull request count low. But if your pull request is non-trivial and stuck for a long time, please feel free to tag the owners or contact them internally for help. + +## _Q. Where do I read about specific best practices?_ + +Please refer to the following documents. + +- [**Contributing fixes and new components**](Contributing) +- [**Accessibility**](Accessibility) +- [**Component Design**](Component-Design) +- [**Styling**](Component-Styling) +- [**Theming**](Theming) +- [**Testing**](Testing) +- [**Advanced**](Advanced-Usage) +- [**Browse Support**](Browser-Support) + +## _Q. When and how does the issue Triage work?_ + +The Fluent UI React core team works hard to stay on top of the open issues. We have a team member assigned to "shield" each week to triage new issues as they come in. + +### Following issues will qualify as high priority + +We try to fix high priority bugs ASAP. + +- Is this issue blocking the consumer? +- Is this a regression? If yes, how and when did it get in?\* Is this a very serious bug? + +Other bugs will qualify as Normal or lower priority and will get fixed as a part of the normal release cadence. + +From time to time we do plan to close issues that are very old and have no activity. + +## _Q. Will there a Fluent UI for Angular?_ + +A Fluent UI project for Angular is not currently on our roadmap. However, we do have a new [web components package](https://aka.ms/fluentui-web-components) (`@fluentui/web-components`) in progress which can interoperate with Angular. + +You can also use the [UI Fabric Core](https://github.com/OfficeDev/office-ui-fabric-core) CSS classes and SCSS variables/mixins for access to our palette, typography and iconography within any framework. diff --git a/docs/react-wiki-archive/Fabric-6-Release-Notes.md b/docs/react-wiki-archive/Fabric-6-Release-Notes.md new file mode 100644 index 0000000000000..902efba5847ae --- /dev/null +++ b/docs/react-wiki-archive/Fabric-6-Release-Notes.md @@ -0,0 +1,157 @@ +Welcome to the 6.0 release of Office UI Fabric React. Version 6.0 is a mostly +incremental release, but still has a few breaking changes that we wanted to +get out as soon as possible. Primarily this release takes a min-bar dependency +on React 16, which will enable us to more easily clean up the API surface to +be compatible with React 16+ strict mode. + +In addition we've adjusted a number of things to take full advantage of +Webpack 4 tree shaking. This will definitely help with our never ending quest +to keep bundle sizes managable. + +In this release we've tried to minimize the number of changes to keep it +straightforward for upgrading. There are a lot of things we would like to +include in the release, such as gutting out legacy deprecated props. We will +be focused on a full overhaul of the api surface in 7.0 to remove deprecated +props and to overall increase consistency, predictability, and robustness in +the components. + +...and now some details about the new 6.0 features: + +## Webpack tree shaking! + +We are excited to announce officially supporting tree shaking. This means that +assuming you use Webpack 4 or above, you can now import things directly from +the `office-ui-fabric-react` package without memorizing top level imports. +Webpack will tree shake out everything you don't use, which creates much +smaller bundles! + +In order to make tree shaking work, webpack must consume ES6 modules. And +since current Fabric consumers use `/lib/` imports, we needed to adjust the +output folders within the repo: + +#### `/lib/` + +ES6 modules (was commonjs). The `/lib-es2015` folder no longer +exists, so make sure to clean up aliases if you were using them. + +#### `/lib-commonjs/` + +If you refer to fabric components in unit tests via Jest, +you may need to alias the `/lib/` imports to to `/lib-commonjs`. Or use Babel. + +Note: To resolve commonjs modules in Jest, you can use this config blurb in +your `jest.config.js`: + +```js + moduleNameMapper: { + "office-ui-fabric-react/lib/(.*)$": "office-ui-fabric-react/lib-commonjs/$1" + }, +``` + +#### `/lib-amd/` + +AMD modules. If you still need AMD, it is important to note another subtlety: +when we import one package from another, we must import from package based +imports (e.g. `import {...} from '@uifabric/utilities'`) rather than file +based imports (`import {...} from '@uifabric/utilities/lib/index'`.) This +allows Webpack to consume the `module` entry in package.json, and node.js to +consume the `main` entry for resolving where the corresponding consumable +modules are. + +### Caveats + +Note that the consuming app must be using Webpack 4 AND having app code use +ES6 modules in order to benefit from tree-shaking. In addition, other libraries +that are not ES6 modules based (such as React and ReactDOM) should be externalized. + +## React 16 + +A number of changes were introduced in 16.3+ that we'd like to take full advantage +of: + +1. Portals. We have updated the 5.0 release to use portals, but it has added a + large batch of duplicated code. We can remove that code. + +2. createRef. We love the new createRef API so much, we polyfilled it in 5.0. + We can now remove that, reducing bundle size. + +3. forwardRef. This has been a painpoint in React for a long long time, and + has caused us to do unnatural things in the API such as introducing + `componentRef`, and adding utilities in our `BaseDecorator` base class for + hoisting memebers. All of this can now be updated. + +4. Official context api! We use context in a number of places today, mostly + for pushing the theme through the API surface. Now with a formal context + api surface, we should be using it where it makes sense. + +5. New lifetime methods. Right now we are using a number of deprecated methods + in places. We want to clean these up, but also take advantage of the new + React methods like `getDerivedStateFromProps` and + `getSnapshotBeforeUpdates`. + +If we were still supporting older versions of React, it would create a lot of +friction and bloat for all partners for us to try and work around these new +ways of doing things, especially for things that are difficult to polyfill. + +## Rewritten CommandBar + +The CommandBar component is one of the most popular components in Fabric but +has long suffered from bloat and rigidity. The complex resizing logic used to +move surplus items into the overflow menu was customized to the component +making it impossible to reuse, and overriding the styles and functionality of +the menu items was difficult and cumbersome. + +Therefore, CommandBar has been completely rewritten from top to bottom using +newer, modular components like OverflowSet, ResizeGroup and CommandBarButton. +This makes it easier to customize and theme with only minor breaking interface +changes. + +## Breaking changes + +### Components + +- All: Components with `getStyles` property had the property renamed to `styles` + which now either takes in a style object or a function. (#4844) +- Checkbox: Replaced optional properties of the `ICheckboxStyles` interface, + removed `getClassNames` from the `ICheckboxProps` interface, in favor of `styles`. + (#4748) +- ChoiceGroup: All props are now input only. +- CommandBar: Moved experimental Command Bar into release. +- ContextualMenu: Removed deprecated (back in v0.69.0 of OUFR) `icon` prop + from `IContextualMenuItem`. Use `iconProps: { iconName: 'SomeIcon' }` + instead. (#4779) +- Label: Interface improvements. (#4745) +- Toggle: Interface improvements. (#4745) + +### Utilities + +- Selection utility: getSelectedIndices is now a mandatory member of the + `ISelection` interface. (#4558) +- Positioning utility: Remove all deprecated props of the positioning utility + and usages of these props. (#4790) + +## Other fixes and changes + +### Components + +- BaseButton: Make adjustment so that custom class names has precedence. [4073361] +- Checkbox: Checkmark is visible on hover, supports high contrast styles. (#4748) +- ChoiceGroup: Supports custom styling. +- CommandBar: Supports custom styling and button aliasing. +- CommandBar: Add aria label and change to single tab stop. +- CommandBarButton: Fixed high contrast hover state. (#4738) +- ContextualMenu: Deprecate 'name' prop in favor of more consistent 'text' prop. (#4862) +- DetailsList: `fieldName` is now an optional field of `IColumn`. [32bc5dc] +- Label: Supports custom styling and aliased root. (#4745) +- Toggle: Supports custom styling and aliased root. (#4745) + +### Utilities + +- Positioning utility: correctly position callout without beak. (#4841) + +## Breaking changes since the 6.0 release + +### Components + +- ResizeGroup: Remove classNamesFunction to reduce bundle size when using the component alone (#6389) +- Dropdown: directionHintFixed now defaults to false to better mirror standard HTML behavior (#5771) diff --git a/docs/react-wiki-archive/Fabric-7.md b/docs/react-wiki-archive/Fabric-7.md new file mode 100644 index 0000000000000..90fe5f8b804e3 --- /dev/null +++ b/docs/react-wiki-archive/Fabric-7.md @@ -0,0 +1,148 @@ +Fabric 7 introduces Microsoft's new Fluent design language by default. There are a variety of adjustments, described below. We've also taken a dependency on **React 16.8.1**, which will allow for future bundle size improvements as we can move much of our redundant state management over to hooks. + +We've also taken a minbar dependency on **TypeScript 3.5**, which includes improved type safety features we need to avoid breaking partners. + +## What about Fabric 6? (or 5?) + +We will continue to support both Fabric 5 and 6. These versions will live within the `5.0` and `6.0` branches respectively. Please make sure to target the appropriate branch if make PRs for those versions. + +We do not plan on cherrypicking all Fabric 7 fixes into 6.0. We will certainly cherrypick any severe bugs or impactful low-risk performance improvements. The same release pipeline running for 6.0 today (releasing each day if changes have been made) will still continue. + +## Upgrade Path (Migrations and Breaking Changes) + +Fabric 7 is shipping the package `@uifabric/migration` which will ease the transition from Fabric 6 to Fabric 7. + +Before upgrading to Fabric 7 run the command below in your source code directory to identify changes that need to be made before upgrading. Run the command with the `-w` option to have the script automatically update your code with these suggestions. Beware that the `-w` option will modify files in-place, so ensure that files are committed to source control beforehand. + +```bash +# note to use 7.0.0, not the current release number +npx @uifabric/migration 7.0.0 +``` + +_For a complete list of breaking changes, see [@uifabric-migration](@uifabric-migration)._ + +## Changes related to the Fluent theme + +To learn more about Microsoft's Fluent design language, visit our [Fluent design website](https://www.microsoft.com/design/fluent/#/). + +### Font size and weight changes + +As part of the Fluent by default strategy, we have a new type ramp. The change will affect text content on a page that was styled using `FontSizes` from `@uifabric.styling` package or `theme.fonts` object provided by the default theme. All font sizes except the largest one will shift by at most a single pixel. Many font weights change as well, with the most significant changes in the larger half of the ramp, changing from `light` to `semibold`. These changes are backwards compatible. + +Below is a comparison table between Fabric 6 and 7: + +| Variable name | Current (pre-Fluent) font size/weight | Fluent font size/weight | +| :---------------------- | :------------------------------------ | :---------------------- | +| `tiny` | 10px / **semibold** | 10px / **regular** | +| `xSmall` | **11px** / regular | **10px** / regular | +| `small` | 12px / regular | 12px / regular | +| `smallPlus` | **13px** / regular | **12px** / regular | +| `medium` | 14px / regular | 14px / regular | +| `mediumPlus` | **15px** / regular | **16px** / regular | +| `large` | **17px** / **semilight** | **18px** / **regular** | +| `xLarge` | **21px** / **light** | **20px** / **semibold** | +| `xLargePlus` **\*new** | **21px** / **light** (back-ported) | **24px** / **semibold** | +| `xxLarge` | 28px / **light** | 28px / **semibold** | +| `xxLargePlus` **\*new** | **28px** / **light** (back-ported) | **32px** / **semibold** | +| `superLarge` | 42px / **light** | 42px / **semibold** | +| `mega` | **72px** / **light** | **68px** / **semibold** | + +# Changelog + +## office-ui-fabric-react + +### Breaking changes + +- ComboBox: _Breaking Change_ deprecated props `value` and `onChanged` removed ([`ff16255`](https://github.com/OfficeDev/office-ui-fabric-react/commit/ff162559fc3d8e8a7eedc3101ae6f9f2eb283b68)) [migration provided](https://github.com/OfficeDev/office-ui-fabric-react/blob/fabric-7/packages/migration/src/mods/7.0.0/comboboxValuePropChange.ts) +- DetailsList, DetailsRow, DetailsRowFields: remove deprecated props, logic and styles related to `Shimmer`. ([`e3080da`](https://github.com/OfficeDev/office-ui-fabric-react/commit/e3980da346f82e29100462934bfc0cee25600d42)) +- Dropdown: className should be applied to the root +- Rating: _Breaking change_ is `rating` prop is passed, control will reflect value always. ([`2ffdd29`](https://github.com/OfficeDev/office-ui-fabric-react/commit/2ffdd290a40c70017cb23cea55818c266720c2ec)) +- Remove use of deprecated @autobind decorator ([`d7dd099`](https://github.com/OfficeDev/office-ui-fabric-react/commit/d7dd09998172855cfd005aa2ec901a575b838619)) [migration provided](https://github.com/OfficeDev/office-ui-fabric-react/blob/fabric-7/packages/migration/src/mods/7.0.0/warnAutobindRemoved.ts) +- SearchBox: pass event to onChange ([`a41bd00`](https://github.com/OfficeDev/office-ui-fabric-react/commit/a41bd0018eb07f1713a2a533ef16f8219cba00ed)) [migration provided](https://github.com/OfficeDev/office-ui-fabric-react/blob/fabric-7/packages/migration/src/mods/7.0.0/searchBoxPropsArgs.ts) +- ShimmerDetailsList: remove deprecated props and style props. ([`baa1060`](https://github.com/OfficeDev/office-ui-fabric-react/commit/baa1060c5d3579d3bb51fcd77a00126ce51629e8)) +- TextField: Strict controlled/uncontrolled behavior ([`04983f3`](https://github.com/OfficeDev/office-ui-fabric-react/commit/04983f31fedbf04c33f7cfd2395e58b5a9a7d03a)) +- Moved Router utility to `@uifabric/example-app-base`. Please consider a different routing solution for production applications. + +### Minor changes + +- Changes to support slots API refactoring. ([`14b1d77`](https://github.com/OfficeDev/office-ui-fabric-react/commit/14b1d77fc97fffb1c333a3601d62c3e30c4cf3b0)) +- Do not export Foundation package. ([`5cfbccb`](https://github.com/OfficeDev/office-ui-fabric-react/commit/5cfbccb1d6a8f130b4c40c5ceeb20d2e7490a201)) +- Stack: Adding relevant Stack and StackItem tokens. ([`77a9195`](https://github.com/OfficeDev/office-ui-fabric-react/commit/77a91958ee5e37fb6c2991fd22275ec379f4c914)) +- Support slots API changes. ([`37a5246`](https://github.com/OfficeDev/office-ui-fabric-react/commit/37a52465422d2622d52b7339ac2f9b2f234300da)) + +## @uifabric/experiments + +### Breaking changes + +- Remove `Shimmer` control. ([`615c8a6`](https://github.com/OfficeDev/office-ui-fabric-react/commit/615c8a68a2ce6cb866974aca07b06f808f2e5798)) + +### Minor changes + +- Add FloatingSuggestions (FloatingPeoplePicker without inheritence) ([`4717372`](https://github.com/OfficeDev/office-ui-fabric-react/commit/47173727698850e1a13820d3ad14a0ac40203f20)) +- Button: Adding allowDisabledFocus prop and adding @docCategory tags on exports. ([`44be390`](https://github.com/OfficeDev/office-ui-fabric-react/commit/44be390505c024b84f6031eb9f564102736b9fa0)) +- Button: Adding keytips to new Button. ([`c4507e4`](https://github.com/OfficeDev/office-ui-fabric-react/commit/c4507e4bfb50076f51febafb4c6d238465b4c8b6)) +- Button: Adding toggle/checked functionality to Button. ([`65d3dec`](https://github.com/OfficeDev/office-ui-fabric-react/commit/65d3dece099cf1ae247de1d761992f8265e23294)) +- Button: Adding uniqueId prop. ([`8815262`](https://github.com/OfficeDev/office-ui-fabric-react/commit/88152626b21e2f8c5ebf3f1c0750fbc6ac6917b8)) +- Button: Changing style of all variants to be Fluent by default and removing use of palette in favor of semantic slots. ([`2faffcc`](https://github.com/OfficeDev/office-ui-fabric-react/commit/2faffcc51ec77341b3f1d796ea8d9e7440ecf0f7)) +- Button: Making all MenuButton props optional. ([`8d6c7c4`](https://github.com/OfficeDev/office-ui-fabric-react/commit/8d6c7c460cf9f9fa5e7985205fc9b602a678dd7f)) +- Changes to support slots API refactoring. ([`14b1d77`](https://github.com/OfficeDev/office-ui-fabric-react/commit/14b1d77fc97fffb1c333a3601d62c3e30c4cf3b0)) +- Convert foundation components that have state to hooks. ([`5f4051f`](https://github.com/OfficeDev/office-ui-fabric-react/commit/5f4051fd8cad5ebd5f5b88c418093b879efbec9a)) +- SelectedItemsList: Add reworked Selected Items (no inheritence + hooks) ([`69ea4ba`](https://github.com/OfficeDev/office-ui-fabric-react/commit/69ea4ba3a0a3f50ad54e3b187be4dbc7014d7353)) +- SplitButton: Adding ability to use Alt+Down key combination from first focus stop and cleaning up API. ([`3e3bc89`](https://github.com/OfficeDev/office-ui-fabric-react/commit/3e3bc89d8de0580dce51dc285c54010635ba1710)) +- SplitButton: Improving screenreader narration for secondary action and fixing styling in fabric 7 branch. ([`f815723`](https://github.com/OfficeDev/office-ui-fabric-react/commit/f81572376bc29b57a53a34f359b799e1be519844)) +- Support slots API changes. ([`37a5246`](https://github.com/OfficeDev/office-ui-fabric-react/commit/37a52465422d2622d52b7339ac2f9b2f234300da)) + +## @uifabric/fabric-website + +### Minor changes + +- Changes to support slots API refactoring ([`14b1d77`](https://github.com/OfficeDev/office-ui-fabric-react/commit/14b1d77fc97fffb1c333a3601d62c3e30c4cf3b0)) + +## @uifabric/file-type-icons + +### Breaking changes + +- Update file type icons to use new Fluent assets by default ([`5e46b40`](https://github.com/OfficeDev/office-ui-fabric-react/commit/5e46b402ec5ecc8326451b06cf07a0ab95246f45))n/a + +## @uifabric/foundation + +### Minor changes + +- Enable API verification and export legacy styled. ([`5cfbccb`](https://github.com/OfficeDev/office-ui-fabric-react/commit/5cfbccb1d6a8f130b4c40c5ceeb20d2e7490a201)) +- Evolve create component API to separate out view and make options bag optional. ([`20b09cc`](https://github.com/OfficeDev/office-ui-fabric-react/commit/20b09cc417500b205e6007538cb6f04ffee208eb)) +- Foundation: Convert state components to hooks. ([`5f4051f`](https://github.com/OfficeDev/office-ui-fabric-react/commit/5f4051fd8cad5ebd5f5b88c418093b879efbec9a)) +- Slots: Move slot options from individual props to new slots prop object. ([`37a5246`](https://github.com/OfficeDev/office-ui-fabric-react/commit/37a52465422d2622d52b7339ac2f9b2f234300da)) +- Slots: Refactor API and add slot options object. ([`14b1d77`](https://github.com/OfficeDev/office-ui-fabric-react/commit/14b1d77fc97fffb1c333a3601d62c3e30c4cf3b0)) +- Updating IComponent typings for ease of use in tests. ([`f97b56f`](https://github.com/OfficeDev/office-ui-fabric-react/commit/f97b56f0a62e4c99e4ed26b8df588e5fc8d5e9bb)) + +## @uifabric/merge-styles + +### Minor changes + +- Changin borderBottomLeftRadius, borderBottomRightRadius, borderTopLeftRadius and borderTopRightRadius to be of type ICSSPixelUnitRule, like borderRadius, instead of type string. ([`2faffcc`](https://github.com/OfficeDev/office-ui-fabric-react/commit/2faffcc51ec77341b3f1d796ea8d9e7440ecf0f7)) + +## @uifabric/migration + +### Minor changes + +- Non-destructive run by default, show affected files. ([`9dd16b5`](https://github.com/OfficeDev/office-ui-fabric-react/commit/9dd16b5d5317ca28df279ef7c5fbfa0392370291)) + +## @uifabric/react-cards + +### Minor changes + +- Card: Improving CardItem and adding CardSection to allow Card children to fill the Card's margins. ([`77a9195`](https://github.com/OfficeDev/office-ui-fabric-react/commit/77a91958ee5e37fb6c2991fd22275ec379f4c914)) + +## @uifabric/styling + +### Minor changes + +- Extend `getFocusStyle` to include named parameters. ([`73f2ff2`](https://github.com/OfficeDev/office-ui-fabric-react/commit/73f2ff26c052d1833fe49590660edf78a4cdf634)) +- Remap existing font variables and add new ones. ([`31d3fd9`](https://github.com/OfficeDev/office-ui-fabric-react/commit/31d3fd9455c8ba205ef775461463175a78ff6f92)) + +## @uifabric/utilities + +### Breaking changes + +- Remove deprecated `autobind` decorator. ([`d7dd099`](https://github.com/OfficeDev/office-ui-fabric-react/commit/d7dd09998172855cfd005aa2ec901a575b838619)) [migration provided](https://github.com/OfficeDev/office-ui-fabric-react/blob/fabric-7/packages/migration/src/mods/7.0.0/warnAutobindRemoved.ts) +- createRef: removed (use React.createRef instead) ([`d7dff28`](https://github.com/OfficeDev/office-ui-fabric-react/commit/d7dff286902cc947fceba7048150e76927143fdb)) [migration provided](https://github.com/OfficeDev/office-ui-fabric-react/blob/fabric-7/packages/migration/src/mods/7.0.0/createRefFromReact.ts) diff --git a/docs/react-wiki-archive/Fluent-UI-Dev-Process.md b/docs/react-wiki-archive/Fluent-UI-Dev-Process.md new file mode 100644 index 0000000000000..376bbe4729e11 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-Dev-Process.md @@ -0,0 +1,85 @@ +## Objectives and Key Results (OKRs) + +Quarterly, we plan using OKRs + +- Use [OKRs](Fluent-UI-Objectives) to set our goals and measurable results +- Update our [Roadmap](Fluent-UI-React-Roadmap) with our goals for the quarter + +## Project cycle + +Monthly, we execute on a project cycle. + +- Leading up to and during the first week of the cycle we identify work to be done in the next cycle GitHub Issues (Projects or Bugs) are added to the [Milestone](https://github.com/microsoft/fluentui/milestones) corresponding to the cycle (example: [November Project Cycle](https://github.com/microsoft/fluentui/milestone/19)). +- Update project issues with project proposals for the work (example: [vNext bundle size requirements and tooling support #17678](https://github.com/microsoft/fluentui/issues/17678)). +- A project cycle by weeks + - **Week 1:** + - Proposals are reviewed and work starts + - **Weeks 2,3+:** Work proceeds according to proposal + - **Last week:** + - Work wraps up, close out issues + - Work for next cycle identified + - Proposals for next cycle are written + - In the rare case work should continue to the next milestone, move it +- Each week the whole team syncs on high level progress + +## Starting a project cycle: + +At the beginning of the month we: + +- Review proposals from the last month + - Close out the ones that are complete + - Review whether or not we hit our goals we set for the month +- Determine the projects we'll work in upcoming month + - If the project will span months, set the goal for this month +- Add any bugs that we plan to fix to the milestone + +## Weekly project updates + +Every week we: + +- Go through each project in the current [Milestone](https://github.com/microsoft/fluentui/milestones) +- Discuss and enter updates in a comment for each open Project + - Bonus points for entering your updates in the issue comment ahead of time! +- Briefly cover bugs tracked in the Milestone + +## What is a project proposal? + +Properties of well shaped projects: +From: [Principles of Shaping](https://basecamp.com/shapeup/1.1-chapter-02#property-1-its-rough) + +1. Rough + - Unfinished, not too much detail + - Room for real contributions from others +2. Solved + - Despite unfinished, it is thought through + - All the pieces at the macro level are there and fit together + - Clear direction showing the approach + - Obvious holes and risks have been removed + - Call out how we expect to resolve anticipated problems +3. Bounded + - Also indicates what _not_ to do + - There is a specific amount of time to spend on the project + - Scope has been limited to fit the appetite for investment + +> Taken together, the **roughness** leaves room for the team to resolve all the details, while the **solution** and **boundaries** act like guard rails. They reduce risk and channel the team’s efforts, making sure they don’t build too much, wander around, or get stuck. + +### Steps to shaping + +From: [Steps to shaping](https://basecamp.com/shapeup/1.1-chapter-02#steps-to-shaping) + +1. [Set boundaries](https://basecamp.com/shapeup/1.2-chapter-03) + - Figure out how much time the idea is worth (Appetite) + - Narrow down the the problem +2. Rough out the solution (or "elements") + Iterate quickly, likely alone or with a partner to produce: - An idea that solves the problem within the appetite, but without all the fine details worked out +3. Address [risks and "rabbit holes"](https://basecamp.com/shapeup/1.4-chapter-05) + This step is critical and what allows us to execute predictably - Find holes and issues that could trip up the team implementing the solution - Add details or reduce scope to prevent the team from getting stuck or wasting time +4. [Write the pitch](https://basecamp.com/shapeup/1.4-chapter-05) + - Once we shaped the project enough to bet on it write it up + - The pitch summarizes the problem, constraints, solution, rabbit holes, and limitations + - Used to kick off the project and explain it to the team that will build it + +### Project template + +- Full [Project template](Fluent-UI-Project-Template) - with extra info +- [Create a new Project Proposal](https://github.com/microsoft/fluentui/issues/new?body=%23%20Project%20Proposal%0A%0A%23%23%20Problem%0A%23%23%20Appetite%0A%23%23%20Solution%0A%23%23%20Risks%20%28Rabbit%20holes%29%0A%23%23%20Out%20of%20scope%20%28No-gos%29&labels=Type:%20Feature) - Don't forget to pick a Milestone! diff --git a/docs/react-wiki-archive/Fluent-UI-Objectives.md b/docs/react-wiki-archive/Fluent-UI-Objectives.md new file mode 100644 index 0000000000000..61737c4dbbbf5 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-Objectives.md @@ -0,0 +1,7 @@ +We use Objectives & Key Results (OKRs) as a quarterly planning tool. These help our team focus on a few core outcomes each quarter and identify measurable results (or sometimes deliverables) that we believe will move us closer to our Objectives. + +The following outlines current and past OKRs for the Fluent UI projects + +## Fluent UI React + +- [Q2 2021](Fluent-UI-React-OKRs-Q2-2021) diff --git a/docs/react-wiki-archive/Fluent-UI-Project-Cycles.md b/docs/react-wiki-archive/Fluent-UI-Project-Cycles.md new file mode 100644 index 0000000000000..898df596a7c41 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-Project-Cycles.md @@ -0,0 +1,11 @@ +We use Monthly Project Cycles to execute on work. These help our team focus on specific work each month, stay on top of who is working on what, and generally make progress towards shared goals. + +The following outlines current and past Project Cycles for the Fluent UI projects + +## Fluent UI React + +- [Create a new Proposal](https://github.com/microsoft/fluentui/issues/new?body=%23%20Project%20Proposal%0A%0A%23%23%20Problem%0A%23%23%20Appetite%0A%23%23%20Solution%0A%23%23%20Risks%20%28Rabbit%20holes%29%0A%23%23%20Out%20of%20scope%20%28No-gos%29&labels=Type:%20Feature) + +Milestones tracking each project cycle + +- https://github.com/microsoft/fluentui/milestones diff --git a/docs/react-wiki-archive/Fluent-UI-Project-Retrospective-Template.md b/docs/react-wiki-archive/Fluent-UI-Project-Retrospective-Template.md new file mode 100644 index 0000000000000..016793ed77508 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-Project-Retrospective-Template.md @@ -0,0 +1,25 @@ +## End of month retrospective + +Add this as a comment in your [project pitch](https://github.com/microsoft/fluentui/wiki/Fluent-UI-Project-Template) at the end of the cycle before closing the project. + +```md +### What was achieved? + +_Write your response here_ + +### What did we miss? + +_Write your response here_ + +### What went well? + +_Write your response here_ + +### What could have gone better? + +_Write your response here_ + +### What changed from initial expectations? + +_Write your response here_ +``` diff --git a/docs/react-wiki-archive/Fluent-UI-Project-Template.md b/docs/react-wiki-archive/Fluent-UI-Project-Template.md new file mode 100644 index 0000000000000..8f67a2a0a32a1 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-Project-Template.md @@ -0,0 +1,29 @@ +For instructions on shaping a project see here: [Shaping a Project](Fluent-UI-Dev-Process#what-is-a-project-proposal) + +# Project template + +_Below are the key ingredients for a project (pitch in shape up terms). Feel free to use them as a template, or go free form. Like when baking a delcious cake :cake: make sure to include all 5 ingredients. If using this as a template, simply delete all the text in italics, and provide your own._ + +### Problem + +_From: [Problem guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-1-problem)_ +_The best problem definition consists of a single specific story that shows why the status quo doesn’t work._ + +### Appetite + +_From: [Appetite guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-2-appetite)_ +_Think of this as another part of the problem definition. We want to solve this problem, but we also need to do it in a way that will leave time to solve other problems. Here we depart from Shape Up, and allow for timeframes or appetites of 1-3 weeks._ + +### Solution + +_The solution is what makes this Project "Shaped". Without a specific solution defined we leave too much ambiguity and risk for the Project team to figure out while coding. This is not, however, a detailed spec or list of task. It is good to leave details open for the team to decide on while building the solution_ + +### Risks (Rabbit holes) + +_From: [Rabbit hole guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-4-rabbit-holes)_ +_Another key aspect of shaping is de-risking. This involves identifying potential issues and complications in the solution. These may be non-obvious cases where the solution doesn't work. These could be constraints from other parts of the system (dependencies or dependent code). This aspect of shaping is what typically requires the most experience and understanding of the domain. This is likely somethign we will all collectively get better at with practice._ + +### Out of scope (No-gos) + +_From: [No-gos guidance](https://basecamp.com/shapeup/1.5-chapter-06#ingredient-5-no-gos)_ +_A key way to deal with complicated risks or issues with the solution, is to decide a particular funcionatliy is out of scope. If reducing the scope to remove a risk or issue does not prevent us from fulfilling the original problem, then it is fine. Reducing scope may require reaching out to the original customer that had the problem we are solving, or working with a representive of the customer on our team._ diff --git a/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q2-2021.md b/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q2-2021.md new file mode 100644 index 0000000000000..b2f4ed1c3f37b --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q2-2021.md @@ -0,0 +1,28 @@ +### Enable AppBar and MeControl + +- Deliver production ready Icon, Divider, Flex, Tooltip, Button, Badge +- Deliver Avatar, Menu, MenuButton, Popup, Text, Focus[Trap]Zone +- Deliver Popup, Accordion, Header +- Deliver Input + +### Enable Partners to be successfully implemented with vNext components + +- Deliver foundational features [Stabilize react-components](https://github.com/microsoft/fluentui/projects/42) + - All Pri 1 issues addressed by end of quarter + +### Improve developer productivity and satisfaction for vNext components + +- Reduce build failure rate (goal TBD) e.g. Fluent UI React - CI 14 day pass rate 81% -> 95% +- Reduce build time (goal TBD) can we get 5 or 10 min CI build for vNext? +- CI errors reproducible locally (goal TBD) as close to 100% as we can get + +### Accessibility: @fluentui/react improvements by End of April  + +- Meet High Impact MAS bugs targets +- Meet Medium Impact MAS bugs targets +- Maintain targets + +### Set clear expectations and timelines with our core 1st party partners + +- Deliver a plan for testing value with partners: Performance, Bundle Size, Accessibility, API Surface +- Establish Fluent UI vNext component roll out plan jointly with partners diff --git a/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q4-2020.md b/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q4-2020.md new file mode 100644 index 0000000000000..53e2e526d8186 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-OKRs-Q4-2020.md @@ -0,0 +1,144 @@ +- **Vette Fluent UI in Product​** + - Ship hooks component model and design tokens in Ribbon (dogfood) + - Ship open source subset of MDL2 icons + - OWA integrates new ThemeProvider​ + - Use of converged utilities in newly build react-northstar components​ +- **Prove out our new styling and component model​** + - Deliver ThemeProvider to consume the same converged primitives in both Office and Teams + - Deliver refreshed primitives for Card Scenario to Office.com and Teams + - Deliver refreshed primitives and update existing Me control for Teams + - Release a guide covering how to build components​ with new hooks based model + - Identify next set of converged primitives and roll out plan​ + - Prototype and close on converged Accessibility approach​ +- **Upgrades of @fluentui/react-northstar and @fluentui/react@8 are easy and less time consuming** + - Reduce the engineering cost it takes Teams to consume an update of @fluentui/react-northstar to 1eng/month + - Move Tier 1 partners on to @fluentui/react@8 by end of the quarter​ +- **Customers and Partners find the answers they need when reaching out to our team through broad channels** + - Responses on React Teams channel increase by 50%​ + - Increase Github Issues that are either fixed or closed by 35%​ +- **The microsoft/fluentui repo fosters community and contribution with fast builds, good testing, and great documentation​** + - Improve PR/CI pipeline duration (30 day) 24m to 17m (30% improvement) + - Improve PR/CI build reliability by 30% (measurement TBD) + +# OKR Work Breakdown + +Below is a repetition of the OKRs above, but with proposed work mapped to the OKRs. This is the master list of potential work that will help move our OKRs forward. Not all of this work will be completed this quarter, but should be considered our backlog. Look to [Monthly Project Cycles](Fluent-UI-Project-Cycles) for committed work. + +## **Reflect Fluent UI in Product** + +- [ ] [Open question Aneesha/Mak] Cards in Office.com +- [x] OWA integrating Theme Provider - Xu + - Gather feedback +- [ ] Ship hooks model and design tokens in Ribbon (dogfood) - David - [#15757](https://github.com/microsoft/fluentui/issues/15757) +- [ ] Ship Open source MDL2 icons - Tomi + - 1 pager for engineering plan + - Build tooling to construct from icon truth + - [x] Produce open source subset of MDL2 svg icons + - [ ] Produce set of new Fluent UI icons (svg) - [#15758](https://github.com/microsoft/fluentui/issues/15758) +- [ ] Use of converged utilities in newly built react northstar components + - [TODO - what is in plan for Q2/Q4 what is on backlog] + - validate v8 hooks in northstar + - children as slot VS. as replacement of all slots (investigate size of breaking change in TMP) + - Finish converging FocusZone/FocusTrapZone [Mak] + - Unify click outside and ESC to close scenarios between v7/v8/northstar so that components can be integrated (v7/v8 Files experience in Teams) [Task] + - style overrides hook - document, migrate TMP style overrides to it + +## **Prove out our new styling and component model** + +- [ ] Prototype and close on converged Accessibility approach + - Marat's ability helpers - pair Marat with somebody from convergence to propose integration for javascript based focus zone, trap zone, delooser and others\* + - focus, aria, and key handlers should be implemented in hooks going forward + - new approach to testing and documenting accessibility is available, use it v8 and in more northstar components + - Improve accessibility support and validations in UI builder + - Consider https://react-spectrum.adobe.com/react-aria/index.html +- [ ] Deliver Theme provider to consume the same converged primitives in both Office and Teams - Xu [#15749](https://github.com/microsoft/fluentui/issues/15749) +- [ ] [Epic] Deliver primitives for Card Scenario to Office.com and enable buidling Me control for Teams – Mak [TODO wording] + - Full details here: [Component Refresh + Convergence Schedule](/coming soon) + - Build: + - [ ] Card - Mak/Josche + - [ ] Link - Mak/Josche + - [ ] Icon - Mak/Josche + - [ ] Menu - Ben/Tomi + - [ ] Separator - Josche/Mak + - Finish: + - [ ] Text + - [ ] Image + - [ ] Avatar - Ben/Tomi + - [ ] Badge/Status - Ben/Tomi + - Start: + - [ ] Tooltip/Callout - Josche/Mak + - [ ] Release a guide covering how to build converged components – David + - Start this quarter, gather decisions, and our approachs + - Write the guide, publish review, get feedback + - [ ] Identify next set of converged primitives and roll out plan + - Build scorecard, publish roadmap, publish this + - [ ] [Need Assignment] Investigate Configurator API that allows us to modify default props + +## **Make upgrades to @fluentui/react-northstar and @fluentui/react@8 easier and less time consuming** + +- [ ] Reduce the time it takes Teams to consume an update of @fluentui/react-northstar + - Investigate applying codemods to react-northstar + - Goal: 1 engineer cost to continually consume Fluent UI Updates within release cycle + - Goal: regular smaller releases of v0 quickly consumable by TMP without breaking changes +- [ ] Move Tier 1 partners on to @fluentui/react@8 by end of the quarter - Jon + - Engage through Tier 1 partner relationships + - (Azure: David, OWA: Xu, SharePoint: Jon, Office.com: David (Mak?), WAC: David, Teams?: Levi) + +## **Audit/improve external channels (Teams channels, GitHub, Discord/GitHub Discussions?, etc.)** + +- [ ] Responses on React Teams channel increase by 50% + - Measure current response time + - Dedicate Shield attention to replying or connecting right contact +- [ ] Increase Github Issues that are either fixed or closed by 35% + - Measure current fix rate and median response time + - Improve investigation flow of issues enabling better fix opportunity + - Dedicate engineer resources to fix issues +- [ ] Proper domain for v0 docs + +## **The microsoft/fluentui repo fosters community and contribution with fast builds, good testing, and great documentation** + +- For ideas, not committed yet: [Build wish list](https://hackmd.io/mjciSB_aTqGUU_ox3o7eCQ) (feel free to add things) +- Improve test coverage through screener, leak detection, testing-library work + - [ ] integrate Teams' leak detection in CI + - [ ] use testing-library (Enzyme renders differently than ReactDOM.render() & it continues to loose community, adapter for React 17RC was not released yet.) +- Improve build performance by X + - [ ] react-icons build perf concerns + - [ ] Split size auditor bundling into parallel jobs (1-2 days, decreases build time by at least 1/3) + - [ ] Upgrade to TS 4.0+ (helps unblock project references) + - Must ensure that .d.ts files remain backwards-compatible with TS 3.7 (at least for anything used by `@fluentui/react` v8). [downlevel-dts](https://www.npmjs.com/package/downlevel-dts) could help. + - [ ] Continued work on build perf +- Improve build reliability by X + - [ ] ability to run screener and CI for branches/patch releases + - [ ] switch v7 screener to webhooks + - Should we move the webhooks solution for running screener to some kind of azure infra? + - [ ] Continued work on build reliability +- Contributors find contributing easy due to consistent package scaffolding, conformance tests, and documentation + - [ ] consistent package structure (v0, v8) + - [ ] Conformance tests + - [ ] [versioned docs site (v0)](https://hackmd.io/roW27OhISDmCcQnOm2hviA) + - [ ] [Docs site arch changes](https://hackmd.io/aPUhJqFnS2O9WisQ-g7pmg) + +## **Unmapped work** + +- [ ] Replace dotted (Menu.Item) components with one word (MenuItem) in v0 + +## Menu [Project]\* + +- depends on focusing, see Architecture / base utilities part above +- in northstar, refactor or restructuring is needed - split Menu to Nav (?), Tabs and ContextualMenu because contextual menu does not have concept of `active` which makes tracking hover and focus state difficult - Charles has a prototype, can this be used as base for converged ContextualMenu? +- decide if we need rendering of the menu popup inline + +## Cards Scenario [Project] + +- compare API between v8 and northstar, resolve differences +- accessibility - define variants and scenarios +- tokens - compare v8 and northstar, resolve differences +- make progress on required components (Button, Text, Image, Avatar...) + +## Me control [Project] + +- Accessibility spec needed to understand which components they will use + +## UI Builder [Project] + +- create separate package / docs diff --git a/docs/react-wiki-archive/Fluent-UI-React-Repo-Structure.md b/docs/react-wiki-archive/Fluent-UI-React-Repo-Structure.md new file mode 100644 index 0000000000000..e99d0d7fc3602 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-Repo-Structure.md @@ -0,0 +1 @@ +Content moved to [Repo structure page](Repo-structure). diff --git a/docs/react-wiki-archive/Fluent-UI-React-Roadmap-Q2-2021.md b/docs/react-wiki-archive/Fluent-UI-React-Roadmap-Q2-2021.md new file mode 100644 index 0000000000000..f1293d7d40d71 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-Roadmap-Q2-2021.md @@ -0,0 +1,76 @@ +This roadmap represents the currently planned work for Fluent UI React for the next Quarter (April - June). + +As an open source project, features not tracked on this roadmap may be submitted by the community. If you have a feature you would like to add to Fluent UI React, [file an issue](https://github.com/microsoft/fluentui/issues/new/choose) or an [RFC](https://github.com/microsoft/fluentui/tree/master/rfcs) to start the discussion! + +| ⚠️ Subject to Change +|:-----------------------------------------| +|Our roadmap provides insight into our current planning and is subject to change based on new priorities, feature requests, or learnings. While we will do our best to maintain a stable roadmap, this document does not represent a firm commitment.| + +| ❓ Got questions | +| :--------------- | + +|Post any questions or feedback on our Roadmap over on the [Q&A Discussions](https://github.com/microsoft/fluentui/discussions/categories/q-a) + +### Fluent UI vNext components (formerly Component Convergence) + +- Next round of Fluent UI baseline components in experimental phase (rough priority) + - [ ] Icon + - [ ] Divider + - [ ] Flex + - [ ] Tooltip + - [x] Button + - [x] Badge + - [x] Avatar + - [ ] Menu + - [ ] MenuButton + - [ ] Popup + - [ ] Text + - [ ] FocusZone + - [ ] FocusTrapZone + - [ ] Accordion + - [ ] Header + - [ ] Input + +### Fluent UI vNext foundation + +- Deliver Pri 1 issues tracked here [Project: Stabilize react-components + ](https://github.com/microsoft/fluentui/projects/42) +- Write up component model, share broadly for feedback +- Write up theming/tokens approach, share broadly for feedback +- Write up component styling approach, share broadly for feedback + +### Accessibility push for @fluentui/react + +- Fix several outstanding a11y issues + +### Establish Fluent UI vNext roll out w/ internal partners + +- Build plan jointly with partners + +### Establish Monitoring and gates for key vNext benefits + +There are a few key benefits customers will see when upgrading to Fluent UI vNext components. We need to establish regular measurements and monitoring for these scenarios. This is to back up our claims with real data, as well as ensure we do not accidentally regress these as we build out components. + +- Performance \ + Performance benefits primarily come from our optimized approach to CSS-in-JSS (make-styles). \ + Areas to measure include: + - Scenarios for real world CSS-in-JS overhead + - CSS Size (savings from Atomic CSS) + - Initial render cost + - Re-render cost +- Bundle Size \ + We need to measure our bundle size, understand where we are at and develop and opinion for what the incremental cost of adopting Fluent UI vNext components will be. Doing so will allow us to vette this with partners and get feedback. + - Bundle Size of utilities + - Bundle Size of incremental scenarios (Import FluentProvider + Button) + - Bundle Size of each component in isolation (we have this already) + - Bundle Size of common component scenarios +- Accessibility \ + Our a11y first approach to design and implementation of Fluent UI vNext components will lead to a much more accessible set of components. As part of this we are also planning to do a11y specific usability testing for our components. Ensuring they are not only designed following best practices, but also work great for all types of users. + - Write up key Accessibility benefits and implement measurements +- API Surface \ + One key issue with the existing Fluent UI React component library is the large surface exported from the library. With Fluent UI vNext we intend to trim this down to core component exports needed in common use cases. We are also exploring the idea of allowing advanced exports to be access through individual packages. + - Write up key API surface benefits and implement measurements + +### Improve developer productivity in the Fluent UI repo + +- Reduce false build failure rate diff --git a/docs/react-wiki-archive/Fluent-UI-React-Roadmap.md b/docs/react-wiki-archive/Fluent-UI-React-Roadmap.md new file mode 100644 index 0000000000000..a12c40255408f --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-Roadmap.md @@ -0,0 +1,68 @@ +This roadmap represents the currently planned work for Fluent UI React + +As an open source project, features not tracked on this roadmap may be submitted by the community. To make a request for a feature to be added to this roadmap, please submit an [issue on github](https://github.com/microsoft/fluentui/issues/new/choose). + +| ⚠️ Subject to Change +|:-----------------------------------------| +|Our roadmap provides insight into our current planning and is subject to change at any time based on new priorities, feature requests, or learnings. While we will do our best to maintain a stable roadmap, this document does not represent a firm commitment.| + +| ❓ Got questions | +| :--------------- | + +|Post any questions or feedback on our Roadmap over on the [Q&A Discussions](https://github.com/microsoft/fluentui/discussions/categories/q-a) + +## Q4 (Oct-Dec) 2021 + +### Deliver a ~public~ preview of @fluentui/react-components + +_[Update] we're not announcing @fluentui/react-components publicly until later. Our focus right now is on internal partners and getting their feedback._ + +This quarter our goal is to finish all known breaking changes for the core component architecture and release an RC. We also will deliver more components for close internal partners to pick up and use in their applications. We will continue to gather internal partner feedback and validate the architecture and components in large scale web applications. + +- Ship a RC component architecture and theme shape + - Progress: [@fluentui/react-components v9.0.0 Project](https://github.com/orgs/microsoft/projects/182/views/4) + - Deliverable: @fluentui/react-components@RC +- Ship Phase 1 and 2 components at Stable Quality (in @fluentui/react-components) + - Avatar Button (and variants), Icon, Link, Divider, FluentProvider, Menu, Popover, Text, Tooltip, Accordion, Badge + - Progress: [Fluent UI React vNext Component Roadmap](vNext-Component-Roadmap) +- Deliver Phase 3 and 4 components converged and released as Alpha & Beta Quality: + - Alpha: Input, Dropdown + - Beta: Image, Checkbox, Label, Radio, Slider, Switch + - Progress: [Fluent UI React vNext Component Roadmap](vNext-Component-Roadmap) + +### Deliver beta quality developer documentation  + +- Author and publish a set of guides + - Theme compatibility guide + - Migration guide for library concepts + - Getting started guide +- 100% coverage of @fluentui/react-components with docs /examples + +### Initial partners are excited and enthusiastic to integrate vNext components + +- Working primarily with internal partners at this point for tight feedback loops + +## Q1 (Jan-Mar) 2022 + +### Deliver an initial release of @fluentui/react-components (with missing components) + +This quarter our goal is to have a stable component architecture that close partners can depend on without fear of breaking changes. We are also targeting to have Phase 1 through 5 stable as well, which will enable close internal partners to incrementally upgrade to vNext components. This is important to bring benefit to our partners now, as well as getting real production use feedback on these components early. + +- Ship a stable (v9.0) component architecture and theme shape + - Progress: [@fluentui/react-components v9.0.0 Project](https://github.com/orgs/microsoft/projects/182/views/4) + - Deliverable: @fluentui/react-components@9.0 +- Phase 1 - 5 components at Stable Quality (in @fluentui/react-components) + - Progress: [Fluent UI React vNext Component Roadmap](vNext-Component-Roadmap) (Phasing coming soon to component roadmap) + +## Q2 (Apr-Jun) 2022 + +### Deliver a complete first version of @fluentui/react-components + +This quarter we are targeting having a broadly React component library that folks building new applications could pick up and use. +We won't have all 70+ components that exist in @fluentui/react and @fluentui/react-northstar, but the library should be valuable for many new applications. + +- Ship a stable (v9.0) component architecture and theme shape + - Progress: [@fluentui/react-components v9.0.0 Project](https://github.com/orgs/microsoft/projects/182/views/4) + - Deliverable: @fluentui/react-components@9.0 +- Phase 1 - 8 components at Stable Quality (in @fluentui/react-components) + - Progress: [Fluent UI React vNext Component Roadmap](vNext-Component-Roadmap) (Phasing coming soon to component roadmap) diff --git a/docs/react-wiki-archive/Fluent-UI-React-v9-Component-Roadmap.md b/docs/react-wiki-archive/Fluent-UI-React-v9-Component-Roadmap.md new file mode 100644 index 0000000000000..07dab78d1aa12 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-v9-Component-Roadmap.md @@ -0,0 +1,53 @@ +Below you will find the last updated roadmap for the build out of Fluent UI React components. + +for our overall roadmap see the [Fluent UI React Roadmap](Fluent-UI-React-Roadmap) + +Note: These dates are approximate targets for a component and are subject to change as we iterate through the development process. + +## What does the status mean? + +For the general component lifecycle please read: [Component Lifecycle](https://dev.to/paulgildea/fluent-ui-react-component-lifecycle-29n5) + +### ❓TBD + +This is on the roadmap, but the team is not actively working on the component yet. + +### 🔍 Reseach + +1. A scaffolded/prototyped component within the defined feature scope +2. Relative high confidence estimation on when the component will reach the next phase on a quarter boundary + +### ⚠️ Preview/Unstable + +The main criteria for moving from Research to an Unstable component is: + +1. Component publicly available via granular package with `*-preview` suffix ( example `@fluentui/react-one-preview@0.1.0` ) + +- > NOTES 💡: + > + > - these packages use zero major semver `0.x.y`, where `x` bumps mean "major(breaking changes)/feature" releases and `y` is for fixes + > - initially we used for **`@fluentui/react-components/unstable` deep import** from for exposing unstable packages, which **is now deprecated** and no longer applies for new controls. + +2. Component has a majority of the feature set complete, but may still be added or removed +3. Relative high confidence estimation on when the component will reach the next phase on a quarter boundary + +### 🎉 Stable + +The main criteria for moving from Unstable to Stable phase is: + +1. Component exported from the top level of the UI library +2. Component is design and feature complete +3. Future API changes will occur according to semver +4. Component can be used in Production +5. The component has gone through a long list of testing + +Essentially the component is ready to be used. + +### Timelines and Estimates + +The team tends to estimate component completion from start to finish for roughly 2 quarters. This is highly dependent on the complexity of the component, but that gives partner teams enough time to plan and set expectations on timelines. We also check in mid-quarter to notify of any changes to the schedule, as that should give runway to adapt to any changes. Quarters are based on the Financial Year. + +## Component Rollout + +- [Fluent UI React Component Build-out Roadmap](https://github.com/orgs/microsoft/projects/786) +- [Fluent UI React Components in StoryBook](https://react.fluentui.dev/) diff --git a/docs/react-wiki-archive/Fluent-UI-React-v9-Release.md b/docs/react-wiki-archive/Fluent-UI-React-v9-Release.md new file mode 100644 index 0000000000000..d7c7503ecd576 --- /dev/null +++ b/docs/react-wiki-archive/Fluent-UI-React-v9-Release.md @@ -0,0 +1,39 @@ +## Fluent UI React v9 is released! 🎉 + +We have released our first stable release of Fluent UI React v9 - [find it on npm](https://www.npmjs.com/package/@fluentui/react-components). This a stable foundation for our new component model bringing drastic improvements in Performance, Accessibility, Customization, and Design to Code. We will continue to improve upon this release and add more components over time, see our Component Roadmap linked below for upcoming components. + +## Component Roadmap + +We've updated the spot of our [Component Roadmap](Fluent-UI-React-v9-Component-Roadmap). Here you'll get a sense of our upcoming component build out schedule. What's stable in the coming relase as well as what's to follow fast, and proposed in the future. + +## Documentation + +You can find the latest documentation of Fluent UI React v9 at https://react.fluentui.dev + +## Migration from `v0/v8` to `v9` + +Migration is unique to each project and there is a dedicated section focusing on migration in our documentation. It's recommended to start there to understand what's changing, how to use the two libraries side-by-side, and strategies on how to approach migration for your project. + +1. [Upgrading from v8 to v9](https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-components-checkbox-migration--page) +2. [Upgrading from v0 to v9](https://react.fluentui.dev/?path=/docs/concepts-migration-from-v0-components-checkbox-migration--page) +3. Example app of [upgrading from v8 to v9](https://github.com/GeoffCox/fluentui-app-v8-v9) + +## Questions + +If you have questions regarding the Fluent UI React v9 release, feel free to contact us on the [Fluent UI React v9 Discussion](https://github.com/microsoft/fluentui/discussions/23183) + +## Release Planning + +The Fluent UI React team is getting ready to release our first stable release, we've gathering up our [final list breaking changes](https://github.com/microsoft/fluentui/issues/22130#issuecomment-1069566852) and we'll have a few more RC releases to help teams plan and migrate to the final stable release. This wiki will help provide some pointers around the recent RC builds, links to breaking changes, and a release target for the stable release. + +## Key Dates and Releases + +1. ✅ 5/23 - Pre-breaking change RC Release - `9.0.0-rc.11` - [link to npm](https://www.npmjs.com/package/@fluentui/react-components/v/9.0.0-rc.11) +1. ✅ 5/23 - Post-breaking change RC Release - `9.0.0-rc.12` - [link to npm](https://www.npmjs.com/package/@fluentui/react-components/v/9.0.0-rc.12) + - [Includes the list of breaking changes](https://github.com/microsoft/fluentui/issues/22130#issuecomment-1069566852) +1. ✅ 5/26 - RC Release - `9.0.0-rc.13` - [link to npm](https://www.npmjs.com/package/@fluentui/react-components/v/9.0.0-rc.13) + - rc.13 will include bug fixes from internal bug tests +1. ✅ 5/31 - Final\* RC Release - `9.0.0-rc.14` - [link to npm](https://www.npmjs.com/package/@fluentui/react-components/v/9.0.0-rc.14) + - _\*If blocking bugs are found additional RC versions may be released_ +1. ✅ June 2022 - Community and Partner testing and feedback +1. ✅ End of June 2022 - Final Stable Release - `9.0.0` - [link to npm](https://www.npmjs.com/package/@fluentui/react-components) diff --git a/docs/react-wiki-archive/Fluent-theme-in-Fabric-6.md b/docs/react-wiki-archive/Fluent-theme-in-Fabric-6.md new file mode 100644 index 0000000000000..834a41791b65c --- /dev/null +++ b/docs/react-wiki-archive/Fluent-theme-in-Fabric-6.md @@ -0,0 +1,19 @@ +Components in Fluent UI React (Fabric) 7+ use the Fluent theme by default, but you can also use the Fluent theme in Fabric 6. + +The Fluent theme and component updates are included in the Fluent theme package: + +``` +npm install @uifabric/fluent-theme +``` + +Once the theme is installed, the Customizer component can be used to wrap portions of your app to apply the Fluent styles. You can even wrap your entire app: + +```jsx +import { Customizer } from 'office-ui-fabric-react'; +import { FluentCustomizations } from '@uifabric/fluent-theme'; +import { AppCode } from 'myApp/AppCode'; + + + +; +``` diff --git a/docs/react-wiki-archive/Getting-Started-with-Fluent-UI-React.md b/docs/react-wiki-archive/Getting-Started-with-Fluent-UI-React.md new file mode 100644 index 0000000000000..5c2aedbe13877 --- /dev/null +++ b/docs/react-wiki-archive/Getting-Started-with-Fluent-UI-React.md @@ -0,0 +1,5 @@ +**Note: This page is about _consuming_ the Fluent UI React library. If you're interested in _contributing_, start from the [Contributing page](Contributing).** + +--- + +[Please see the "Get started" section on our website.](https://developer.microsoft.com/en-us/fluentui#/get-started/web) diff --git a/docs/react-wiki-archive/Getting-Started-with-UI-Fabric.md b/docs/react-wiki-archive/Getting-Started-with-UI-Fabric.md new file mode 100644 index 0000000000000..5c2aedbe13877 --- /dev/null +++ b/docs/react-wiki-archive/Getting-Started-with-UI-Fabric.md @@ -0,0 +1,5 @@ +**Note: This page is about _consuming_ the Fluent UI React library. If you're interested in _contributing_, start from the [Contributing page](Contributing).** + +--- + +[Please see the "Get started" section on our website.](https://developer.microsoft.com/en-us/fluentui#/get-started/web) diff --git a/docs/react-wiki-archive/Guidelines/Coding-Style.md b/docs/react-wiki-archive/Guidelines/Coding-Style.md new file mode 100644 index 0000000000000..8951f44758625 --- /dev/null +++ b/docs/react-wiki-archive/Guidelines/Coding-Style.md @@ -0,0 +1,110 @@ +## Auto formatting + +We use [Prettier](https://prettier.io) to keep our code style consistent. You do not have to worry about formatting your source code as Prettier will take care of it for you. We ensure the code stays consistent by running Prettier as a pre-commit hook. + +> If you use VS Code, you can use [this plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to help you run the formatter on save. Be sure to set `"prettier.requireConfig": true` in your user settings to only use Prettier in projects with a prettier config (to prevent its default settings from being applied to all code). + +Prettier handles elements of formatting including: + +- Single quotes (usually). Exceptions which use double quotes: + - JSX attributes + - Strings with single quotes inside +- 2 spaces for indentation +- Semicolons +- Curly braces around conditionals and loops +- Open curly braces don't go on a separate line + +In addition, we use TSLint rules to enforce certain other formatting guidelines. TSLint is run while building and as a pre-commit hook. + +## Other guidelines + +**See the [TypeScript guidelines page](TypeScript-Guidelines) for more about recommended patterns.** + +Some of these guidelines are enforced by TSLint rules, while others are just considered good practice. + +### JSDoc + +Use [JSDoc](http://usejsdoc.org/about-getting-started.html) comments for function, interfaces, enums, and classes. Be sure to include comments describing the item's functionality. + +In TS files, **do not** include annotations in your doc comments which TS could infer from the context. These include: + +- Type annotations (example: `{string}` in `@param {string} foo`) +- Class-related tags: `@class`, `@member`, `@abstract`, `@extends`, `@constructor`, `@implements`, `@member`, `@memberof`, `@static`, `@protected` +- `@export`, `@exports`, `@async`, `@constant`, `@enum`, `@function`, `@interface`, `@readonly`, `@typedef` +- `@private` (using `@internal` is okay to indicate something which is exported from its file is not meant as a public API; not necessary to use on private class members) +- `@this`: outside a class, include `this: sometype` as the first parameter in the function signature (it won't be included at runtime but tells TS the type of `this`) + +(Exception: If the file is in JS, please DO use the extra type annotations to help with maintainability! This mostly just applies to build scripts.) + +### Use camelCase when naming objects, functions, and instances. + +This applies regardless of whether the function is internal or exported. + +**Good** + +```ts +const thisIsMyObject = {}; +function thisIsMyFunction() {} +``` + +For utility files exporting a single function, the filename should be identical to the function's name (casing and all). + +### Use PascalCase for classes / components / interfaces + +**Good** + +```tsx +class User { + constructor(options) { + this.name = options.name; + } +} + +// React component +const MyComponent = props =>
{props.name}
; + +interface ISampleInterface { + name: string; +} +``` + +**Bad** + +```ts +class user { + constructor(options) { + this.name = options.name; + } +} + +// React component +const myComponent = props =>
{props.name}
; + +interface sampleInterface { + name: string; +} +``` + +### Use prefixed underscores to identify private consts, methods, and functions + +```ts +const _privateConst = 1; + +class Foo { + private _member = 1; +} + +function _privateFunction() { + // ... +} +``` + +### Interface prefixing + +Historically we've prefixed all interface names (and sometimes type names) with `I`, for example `IPerson`. In newer code, we're dropping this prefix. + +Until all code is updated, please follow the convention for the package you're working in. This is enforced by lint rules. + +### Avoid including the words Core, Utility, Common, or Helper in names + +These words are generic and don't convey any meaning; use more descriptive words. diff --git a/docs/react-wiki-archive/Guidelines/React-Guidelines.md b/docs/react-wiki-archive/Guidelines/React-Guidelines.md new file mode 100644 index 0000000000000..a46b26ee7683d --- /dev/null +++ b/docs/react-wiki-archive/Guidelines/React-Guidelines.md @@ -0,0 +1,120 @@ +## Favor composition over inheritance + +Even as the ES6 Javascript standard is giving us the "class" keyword, we should stay away from inheritance as a model for extending functionality. Inheritance forces a single linear path within which to extend functionality. Functionality from different aspects or domains are added in arbitrary nodes along this path. Eventually, the functionality of the subclasses is muddied with multiple responsibilities. Rather, given a composition model, each composed type can focus on its own purpose without compromising on flexibility. Further, it is easier to test each of these composed units rather than subclasses that are mixed in purpose. + +Inheritance also doesn't work with the new hooks-based function components. + +## Prefer function components in new code + +React 16.8 added support for [hooks in function components](https://reactjs.org/docs/hooks-intro.html). Hooks allow using state and most other React features without writing a class. They allow for much greater reusability and composability of behavior. Therefore, we recommend using function components in new code (but using classes is still allowed as well). + +## Ref usage + +React exposes a special [`ref` prop](https://reactjs.org/docs/refs-and-the-dom.html) for components. Its behavior is different between intrinsic elements, class components, and function components: + +- For **intrinsic/native elements** such as `
` or ``, it returns a reference to the underlying HTML/DOM element object, allowing you access to its API. +- For **class components**, it exposes the class instance and its public API. +- For **function components**, it returns nothing by default, but Fluent UI components use [`React.forwardRef`](https://reactjs.org/docs/react-api.html#reactforwardref) to expose a reference to the component's root DOM element. + +Although it's possible to access a class component's public API using `ref`, we don't recommend this: + +1. It will stop working if the component is converted to a function component +2. It's more error-prone: + - If the component wraps itself in a higher order component or decorator, the `ref` will return the wrapper component rather than what you intended to access. + - Accessing the full component's public methods is probably not desirable. It isn't exactly intended to access `public render` or to allow the consumer to call `componentWillUnmount`, despite these being publicly exposed to React. + +### Consuming a component's public API + +There ARE limited cases where a component should expose a public API contract. It's recommended to do things declaratively in React, but there are some scenarios which are perhaps easier to do imperatively: + +1. Exposing a `focus` method (or similar) +2. Accessing current values of uncontrolled prop values (such as the current value of a `TextField`) + +In Fluent UI React, we do the following for components which expose an imperative API surface: + +1. Define an `I{ComponentName}` interface which only exposes the methods intended to be supported. +2. Add a prop `componentRef?: IRefObject` + +In the consuming code, you can create a ref with `React.createRef` (class components) or `React.useRef` (function components) and pass it as the `componentRef` prop. + +Example usage of `componentRef` to access the `ITextField` interface: + +```tsx +const FooFunc: React.FunctionComponent = () => { + const textField = React.useRef(null); + + React.useEffect(() => { + textField.current?.focus(); + console.log(textField.current?.value); + }, []); + + return ; +}; + +class FooClass extends React.Component { + private _textField = React.createRef(null); + + public render() { + return ; + } + + public componentDidMount() { + this._textField.current?.focus(); + console.log(this._textField.current?.value); + } +} +``` + +### Setting up the componentRef + +This section is about how to set up `componentRef` for a new component, not how to use it. + +For function component, use `useImperativeHandle`. (As a bonus, this example also shows how to use `forwardRef`.) For class components, use `initializeComponentRef`. + +```tsx +import { IRefObject } from '@fluentui/react/lib/Utilities'; + +interface IFoo { + focus(): void; + otherMethod(): number; + readonly someValue: string; +} + +interface IFooProps extends React.RefAttributes { + componentRef?: IRefObject; +} + +const FooFunc: React.FunctionComponent = React.forwardRef => { + React.useImperativeHandle(props.componentRef, () => ({ + focus: () => /* do stuff to focus */, + otherMethod: () => /* do stuff */, + someValue: /* value here */ + })); + + return
...
; +} + +import { initializeComponentRef } from '@fluentui/react/lib/Utilities'; + +class FooClass extends React.Component { + constructor(props) { + super(props); + // must be inside the constructor + initializeComponentRef(this); + } + + public get someValue() { + // return value here + } + + public focus() { + // do stuff to focus + } + + public otherMethod() { + // do stuff + } +} +``` + +**We no longer recommend using BaseComponent due to its negative performance and bundle size implications.** diff --git a/docs/react-wiki-archive/Guidelines/TypeScript-Guidelines.md b/docs/react-wiki-archive/Guidelines/TypeScript-Guidelines.md new file mode 100644 index 0000000000000..8fda43b9a16fd --- /dev/null +++ b/docs/react-wiki-archive/Guidelines/TypeScript-Guidelines.md @@ -0,0 +1,252 @@ +(Note: not all these guidelines are specific to TypeScript, but keeping the page name to avoid breaking links.) + +## General principles + +### Single responsibility + +Module and classes should only have a single purpose. It is a code smell when we have modules with a lot of code in it. + +Having a single purpose makes the code more easily testable. Often complex classes which do many things will retain internal state that makes things difficult to mock or to cover every permutation. + +### Be wary of your browser matrix (Fluent UI React must support IE 11) + +IE11 does not support most ES6+ features natively. The unsupported features fall into two categories: **APIs** which require polyfills and **must not** be used in published Fluent UI React code, and **syntax** which TypeScript can transpile out. + +(Exception: code which runs in a Node environment, primarily tests and build scripts, can use ES6+ features.) + +#### APIs + +Published Fluent UI React code **must not** use ES6+ APIs which IE11 doesn't support, including (but not limited to) `[].find`, `WeakMap`, `IntersectionObserver`, `Promise`, `Object.assign`, and some features in `Map`. We do not provide polyfills and can't assume our consumers will do so. + +Some of these can fail type checking if you set your `lib` in `tsconfig.json` to `["es5", "dom"]` only. + +[caniuse.com](https://caniuse.com) and [these comprehensive compatibility tables](http://kangax.github.io/compat-table/es6/) are good resources for determining browser support. + +#### Syntax + +IE11 also doesn't support certain ES6+ syntax, such as classes and async functions. However, these are **safe to use** in published Fluent UI React code because TypeScript transpiles them down into ES5-compatible constructs. + +## React guidelines + +See [React guidelines page](react-guidelines). + +## Formatting and naming + +See [code style page](code-style). + +## JavaScript/TypeScript guidelines + +### Use `undefined` instead of `null` + +JavaScript has 2 bottom values: `null` and `undefined`. While they do have different semantic meanings, in most cases we recommend using undefined to represent the absence of a value. The exception to this rule is when a third party API, like the return value of React's `render` method, expects null. + +### Use `let` or `const` instead of `var` + +Historically, the only way to create a variable in JavaScript was using the `var` keyword. The `var` keyword is function-scoped, which means the following code is valid JavaScript. + +```ts +function foo() { + if (true) { + var x = 3; + } + console.log(x); // '3'; +} +``` + +ES6 introduced `let` and `const`, which are block-scoped instead of function-scoped, so the code below produces an error: + +```ts +function foo() { + if (true) { + let x = 3; + } + console.log(x); // 'x is not defined' +} +``` + +(TypeScript adds support for `let` and `const` when targeting ES5 through a combination of compile-time checking, and defining unique names for each declaration when needed.) + +### Prefer functions over classes + +ES6 and TypeScript both introduce the `class` keyword which allows for developers to use more familiar OO paradigms. However, JavaScript supports functions as first class citizens, so you often don't need to use classes. Instead, you can often just create a file (effectively, a module) that exports a bunch of functions. We feel this encourages developers to favor composition over inheritance. State can still be stored as a file-scoped variable if necessary. `class` is also unavailable in ES5, so TypeScript will actually generate a fair bit of boilerplate code to provide support for classes in older browsers. + +The main difference between classes and files/modules is that classes can be instantiated. As a general guideline, if you are planning to have multiple instances of something with state associated with each instance (and/or planning to leverage inheritance), classes should be favored. However, if you are grouping logically-connected sets of stateless functions together or just need a singleton, a module is more appropiate. + +The exception to this rule is React components, which can be defined as either classes or functions. See the [React guidelines page](react-guidelines) for more info about choosing between them. + +### Use JavaScript plain objects instead of classes + +It is often convenient to store state inside of a JavaScript object. Those coming from a C# background might be tempted to use a class for this purpose, but one can instead use JavaScript objects directly to achieve this purpose. In TypeScript, you can still achieve type safety by creating an `interface` or a `type` which describes the shape of your object. Note that TypeScript interfaces are very different from interfaces in C# since TypeScript uses "[duck typing](https://en.wikipedia.org/wiki/Duck_typing)". An example of using plain objects can be seen below: + +```ts +interface IPerson { + name: string; + age: number; +} + +let myPerson: Person = { name: 'David', age: 70 }; +``` + +### Use arrow functions instead of `bind` + +The `this` keyword in JavaScript has commonly been the source of [many developer frustrations](https://github.com/Microsoft/TypeScript/wiki/'this'-in-TypeScript), particularly when trying to call functions within a class from a callback. To make sure that you are bound to the right `this`, developers have typically written code like this: + +```tsx +var onClick = this._handleClick.bind(this); +; + } + + private _handleClick = e => { + // code + }; +} +``` + +### Avoid using `any` + +Strive to provide type safety to your code by avoiding the use of the `any` keyword. + +### Use `[]` instead of `Array` + +TypeScript has two mechanisms for declaring an array, which are shown below. We prefer the `[]` notation over the `Array` keyword since this aligns with the open source JavaScript community. + +```ts +// good +let list: number[] = [1, 2, 3]; +// not so good +let list: Array = [1, 2, 3]; +``` + +### Use `for` or `for of` loops, especially in performance-sensitive code + +Loops using `forEach` add function / closure allocation and add stack entries, which especially in legacy browsers can add overhead. Using `for of` will transpile into a transitional `for` loop which is proven to be slightly faster. Performance issues are death by a thousand paper cuts, so be aware to adopt best practices and in bulk it makes a difference. + +[Performance comparison of for vs forEach](https://hackernoon.com/javascript-performance-test-for-vs-for-each-vs-map-reduce-filter-find-32c1113f19d7) + +### Use [`map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [`filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), and [`reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) instead of loops when appropriate + +JavaScript has some great built in functions for common operations that happen in a loop. + +Use `map` when the loop is transforming each item in an array and pushing it into a new array. + +Use `filter` when building a new array which contains a subset of an old array. You can also use it prior to a `map` call to only apply the mapping to a subset of the array items. + +### Use `===` and `!==` over `==` and `!=` + +Use the type safe versions of the equality checks whenever possible. Remember, `8 == '8'` is true, but `8 === '8'` is false. + +#### Don't use `===` with `NaN` + +`NaN` will never `===` anything (including `NaN`). Use `isNaN(value)` instead. + +### Use shortcuts for booleans, but be careful with strings and numbers + +```ts +// bad +if (isValid === true) { + // ... +} + +// good +if (isValid) { + // ... +} +``` + +JavaScript treats all values as [truthy or falsy](https://www.sitepoint.com/javascript-truthy-falsy/). Everything is truthy, except the following six values which are falsy: `false`, `0`, `''` (empty string), `null`, `undefined`, `NaN`. + +_With some caveats_, this allows a simpler conditional check syntax: `if (foo) { ... }`). This is okay to use if `foo` is an object and you'd like to check whether it's defined. However, **be careful with strings and numbers** if `0` or `''` is a valid value! + +Checking if a string is defined: + +```ts +// bad if '' is a valid value for text +if (text) { + // ... +} + +// good +if (typeof text === 'string') { + // ... +} +``` + +Checking if a number is defined: + +```ts +// bad if 0 is a valid value +if (value) { + // ... +} + +// good (note that NaN is a number) +if (typeof value === 'number' && !isNaN(value)) { + // ... +} +``` + +### Don't use `Boolean()` + +Use `!!value` instead of `Boolean(value)`, or `!value` instead of `!Boolean(value)`. + +### Use spread `...` instead of `Object.assign` to combine objects + +`Object.assign` isn't supported in IE 11, but you can achieve similar results using the spread operator `...`, which TypeScript transpiles into something that works in all browsers. + +```tsx +const foo = { a: 1 }; +const bar = { b: 2 }; + +// Bad +const baz = Object.assign({}, foo, bar); + +// Good +const baz = { ...foo, ...bar }; +``` + +The one case not covered by spread is if you wanted to copy all of an object's properties into another _existing_ object (not a new one). In that case, you'd have to use a for loop. + +```ts +// Bad +Object.assign(foo, bar); + +// Good +for (let key of Object.keys(bar)) { + foo[key] = bar[key]; +} +``` + +### Avoid default exports + +We typically don't use default exports in Fluent UI React. If you do want to export something as default, you should also export it as a named entity. + +```js +// Good +export function foo() { ... } + +// Acceptable +export default foo; +``` + +```js +// Bad +export default function foo() {} +``` + +## Acknowledgements + +Many of these rules were inspired by the guidelines of Outlook Web, [Typescript](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines), [Pillar Studio](https://github.com/pillarstudio/standards/blob/master/reactjs-guidelines.md) and [AirBnb](https://github.com/airbnb/javascript) diff --git a/docs/react-wiki-archive/Home.md b/docs/react-wiki-archive/Home.md new file mode 100644 index 0000000000000..2d2d90aa07af3 --- /dev/null +++ b/docs/react-wiki-archive/Home.md @@ -0,0 +1,21 @@ +Fluent UI is a collection of robust components designed to make it simple for you to create consistent web experiences using the Fluent Design Language. + +## Using Fluent UI + +For information about basics of using Fluent UI, and details of the different projects located in this repo, see the [README](https://github.com/microsoft/fluentui/blob/master/README.md). + +## Contributing + +[Setting up your development environment](https://github.com/microsoft/fluentui/wiki/Setup#basic-setup) + +[Contributing to `@fluentui/react` and related packages](Contributing/Contributing) + +[Contributing to `@fluentui/react-northstar` and related packages](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/CONTRIBUTING.md) + +## `fluentui/react` Version 9 is released 🎉 + +See the [documentation website](https://react.fluentui.dev) for more information. + +## `@fluentui/react` Version 8 + +See the [release notes](Version-8-release-notes) for more information. diff --git a/docs/react-wiki-archive/How-to-apply-theme-to-Fluent-UI-React-components.md b/docs/react-wiki-archive/How-to-apply-theme-to-Fluent-UI-React-components.md new file mode 100644 index 0000000000000..7e94d1a96c458 --- /dev/null +++ b/docs/react-wiki-archive/How-to-apply-theme-to-Fluent-UI-React-components.md @@ -0,0 +1,102 @@ +Once you have defined the [`theme`](https://github.com/microsoft/fluentui/wiki/Theming) for your app, you need to apply the theme. Fluent UI React currently supports multiple ways of applying theme. Below is detailed guidance on the recommended and possible approaches. + +- [ThemeProvider (in preview)](#themeprovider-in-preview) +- [loadTheme](#loadtheme) +- [Customizer (deprecated/legacy)](#customizer-deprecatedlegacy) + +## ThemeProvider (in preview) + +Starting in `@fluentui/react@8`, we've introduced a new component called `ThemeProvider`. It's designed to provide a contextual theme down to its child components. By default, it provides the Fluent theme. You can pass a partial or full theme you have created using `theme` prop. `ThemeProvider` will then merge it with the default (Fluent) theme and provide down to its children. + +**NOTE:** `ThemeProvider` was previously published under `@fluentui/react-theme-provider`. For various reasons, it was moved from that package into `@fluentui/react` itself in version 8, so **do not use `@fluentui/react-theme-provider` in version 8.** + +Here is a basic example of using `ThemeProvider`: + +```tsx +import { ThemeProvider, PartialTheme } from '@fluentui/react'; + +const appTheme: PartialTheme = { + palette: { + themePrimary: 'red' + ... + } +}; + +export const App = () => ( + + App content ... + +); +``` + +You can also nest `ThemeProvider`s: + +```tsx +import { ThemeProvider, PartialTheme } from '@fluentui/react'; + +const appTheme: PartialTheme = { + palette: { + themePrimary: 'red' + ... + } +}; + +const headerTheme: PartialTheme = { + palette: { + themePrimary: 'orange' + ... + } +}; + +export const App = () => ( + + + + + + App content ... + +); +``` + +You can find more examples and supported props of `ThemeProvider` [here](https://fabricweb.z5.web.core.windows.net/oufr/8.0.0-beta.2/#/examples/themeprovider). + +`ThemeProvider` is supported with version 8 of Fluent UI React. Note that we don't plan to re-export `ThemeProvider` from version 7. If really needed, you can still use `ThemeProvider` on version 7 by importing it from `@fluentui/react-theme-provider@0` package (see this example [here](https://codesandbox.io/s/themeprovider-for-v7-28ihm?file=/src/App.tsx)). However we recommend you start to adopt `ThemeProvider` after your application is upgraded to version 8. + +## loadTheme + +`loadTheme` is a way to provide a theme in global (and only global) scope, which will affect your entire application. + +If you are `loadTheme` today, it's recommended to replace it with `ThemeProvider`. That way, your application consistently has one way of providing a theme. + +One caveat here is that if you app has styles which is authored in raw CSS which uses theming tokens and relies on `@microsoft/load-themed-styles`, `ThemeProvider` won't be able to replace `loadTheme` in this case without the need to re-write the styles. Only `loadTheme` calls `loadTheme` from `@microsoft/load-themed-styles` internally. + +Here is a basic example of using `loadTheme`: + +```tsx +import { loadTheme, createTheme, Theme } from '@fluentui/react'; + +// Note: +// `loadTheme` does not support passing partial theme. +// You must create a full theme (using `createTheme`). +const appTheme: Theme = createTheme({ + palette: { + themePrimary: 'red' + ... + } +}); + +loadTheme(appTheme); + +export const App = () => ( + <> + App content ... + +); +``` + +## Customizer (deprecated/legacy) + +Starting from `@fluentui/react` version 8, `Customizer` is deprecated in favor of `ThemeProvider`. Compared to `ThemeProvider`, `Customizer` is not type-safe and does not support partial themes. For the sole purpose of providing and consuming a theme in your app, `ThemeProvider` is able to do everything `Customizer` can do today. You can learn more about how to replace `Customizer` with `ThemeProvider` [here](https://github.com/microsoft/fluentui/blob/master/packages/react/src/utilities/ThemeProvider/README.md#customizer). + +(If you're using `Customizer` for purposes besides theming, please let us know.) diff --git a/docs/react-wiki-archive/Implementation-Best-Practices.md b/docs/react-wiki-archive/Implementation-Best-Practices.md new file mode 100644 index 0000000000000..5b7d6adb794a4 --- /dev/null +++ b/docs/react-wiki-archive/Implementation-Best-Practices.md @@ -0,0 +1,97 @@ +**These best practices apply primarily to v9+ components (`@fluentui/react-components`).** + +## Component Props + +### Prefer property names consistent with other components + +Consistent property names across the component library help developers understand how to use your component more quickly because the names are familiar. When there aren't good examples, check out [open-ui.org](https://open-ui.org/) to see what names are commonly used across UI component libraries and frameworks. + +For example, a property that controls the overall layout and style of a component is most commonly named `appearance`. Avoid naming your property `display`, `look`, etc. + +This is true for discriminated union values too. For example, sizes is most commonly `'extra-small' | 'small' | 'medium' | 'large' | 'extra-large'`. There are two common outlier sizes `tiny` and `jumbo`. Avoid naming sizes `ex-s` or `hugely`. + +### Prefer to minimally distinguish property names + +If a property applies to the component or to the logical element of the component choose an unadorned name. Avoid prefixing the component name (e.g. prefer `icon` over `buttonIcon`) or unnecessary adjectives (e.g. prefer `shape` over `overallShape`). + +If a property applies to a part or slot of a component, prefix/suffix with the part name (e.g. prefer `iconPosition` over `position`). Prefer to prefix the part name except where the property is acting as a verb (e.g. `alignContent` over `contentAlign`). + +Avoid any hungarian notation of properties. While they can appear helpful when writing the props in Typescript, they are not idiomatic when calling from TSX. + +### List properties in alphabetical order + +Trying to logically group properties is too sensitive to each developers preferences. Listing alphabetically allows developers to easily scan for a property. It also matches with how the API and storybook documentation will list properties. + +### Avoid re-declaring properties from native element attributes + +If your component provides a `forwardRef` to a native element (e.g. Button => + + + ); +}; +``` + +#### Bad + +_New styles object will be passed every time `getCheckboxStyles` is called :(_ + +```tsx +const getCheckboxStyles = background => ({ root: { background } }); + +const App = () => { + const [color, setColor] = React.useState('red'); + const toggleColor = () => setColor(color === 'red' ? 'blue' : 'red'); + return ( + <> + + + + ); +}; +``` + +_Do not use `React.useMemo` for memoizing styles creation, because it resets the cache every time component unmounts. It will help in case of re-renders, but not if the same component gets mounted multiple times._ + +```tsx +const App = () => { + const [color, setColor] = React.useState('red'); + const toggleColor = () => setColor(color === 'red' ? 'blue' : 'red'); + const checkboxStyles = React.useMemo(() => ({ root: { background: color } }), [color]); + + return ( + <> + + + + ); +}; +``` + +--- diff --git a/docs/react-wiki-archive/Pull-request-reviewing-guidance.md b/docs/react-wiki-archive/Pull-request-reviewing-guidance.md new file mode 100644 index 0000000000000..2f476e0d62878 --- /dev/null +++ b/docs/react-wiki-archive/Pull-request-reviewing-guidance.md @@ -0,0 +1,49 @@ +This document represents a living list of things we look for in PRs to maintain a uniform, high standard across our code. + +Give yourself enough time to review. The general wisdom is that it will take 1-2 hours per 200 lines of code. + +## General areas to consider + +- **Breaking changes, especially subtle ones.** We certainly do not want to break customers, and API changes can certainly create chaos for their upgrade experience. API changes should be caught by API extractor, so pay special attention to API change snapshots. Sometimes DOM changes, classname changes, or even css changes can also cause "breaks" for partners. Use caution in these scenarios and try and err on the side of avoiding breaks, unless a behavior is clearly broken. + +- **Missing tests.** If the PR is about a bug, would it have been possible to write tests that could have caught the bug? If so, we should encourage authors to write tests. + +- **Length of PR.** Is the PR huge? Large reviews often overlook problems as it takes a lot more effort to get reviewed in depth. Ask people to split PRs up if they're more than 20 files, or for large rename PRs or sweeping changes, make sure they focus on one type of change and don't sneak in a "few extra things" to keep from things being overlooked. + +- **Missing comments you'd like to see.** Without comments explaining the thoughts/goals, "fixes" might appear as short-sighted code that should be removed. Use comments to explain to the future reader what the thinking was. + +## Specific mistakes to consider (NOTE: please do not list things caught by linting or prettier, as these will fail the build. Let the robots do their work.) + +- Using `any` without comments. Make sure that opting out of typing is commented. + +- Using commenting formats other than JSDoc for props/methods/classes (or using JSDoc annotations which are unnecessary with typescript). + +- Poorly named variables/methods that don't describe purpose (e.g. `isFlag1`) + +- Inconsistent patterns, e.g. `onChange` (good) vs `onChanged` (bad) + +- Inefficient approaches. This might be runtime cost, but also concerning bundle size. + +- Possible nullref scenarios. Look for periods (e.g. `foo.bar`); can the value to the left (`foo`) be null? (TypeScript strict null checking can catch this sometimes but not always.) + +- Repeat code. Consider consolidating into a single source (const, function, new component.) + +- Violations of coding standards not enforced by lint rules or prettier. (Note: consider if automate systems can be updated to catch things automatically to reduce this list.) + +- Event handling methods inside of classes which don't use lambda syntax to preserve the `this` reference. If lamdas are not used, then the code _might_ work, until later someone references `this` and finds an unexpected result. + +- Avoid using boolean params in method definitions. Boolean params usually mean a conditional `if` statement will be used which means the caller probably knows too much about the implementation of the method it's calling. It also makes it hard to change the method later. Make 2 methods that do different things instead. + +## Browser concerns + +- Calling any browser force-layout api synchronously. Typically this would be calling `element.focus` in synchronous (mount) scenarios. Use an async patterns, like `requestAnimationFrame` to enqueue layout-forcing calls to be done after layout has been resolved. See https://gist.github.com/paulirish/5d52fb081b3570c81e3a + +- Browser-specific code should be avoided unless absolutely necessary. Make sure it has comments explaining why. + +## React component specific concerns + +- Accessing `window` or `document` directly, rather than `getWindow`/`getDocument` and passing in a reference element. This is important because when executing code from a host within a child window, the `window` object will be the host rather than the child, causing side effects to happen (such as not executing `requestAnimationFrame` callbacks if the host is minimized or in a non-active tab.) + +- Accessing `getWindow` or `getDocument` too early before component mounts (e.g. in render function.) Breaks server side rendering. + +- Introducing new class components, rather than using functional components with hooks. diff --git a/docs/react-wiki-archive/README.md b/docs/react-wiki-archive/README.md new file mode 100644 index 0000000000000..46022d7c90de8 --- /dev/null +++ b/docs/react-wiki-archive/README.md @@ -0,0 +1,5 @@ +This folder serves as the archive for the Git Hub Wiki content as of June 2024 for historical purposes if anyone needs reference to v5-8. + +Some files have been renamed to remove special characters. + +Many links are likely broken. diff --git a/docs/react-wiki-archive/RFC-review-process.md b/docs/react-wiki-archive/RFC-review-process.md new file mode 100644 index 0000000000000..a11833130779e --- /dev/null +++ b/docs/react-wiki-archive/RFC-review-process.md @@ -0,0 +1,24 @@ +_This document explains RFC review process for `@fluentui/react-components`_ + +The goal of this process is to ensure that RFCs and specs have the required attention and that authors receive meaningful feedback. + +Currently we have the following teams that work on the library (each team has a CREW LEAD): + +- @microsoft/cxe-coastal +- @microsoft/cxe-prg +- @microsoft/cxe-red +- @microsoft/teams-prg + +RFCs and specs that don't have REVIEWERS are announced at the beginning of offline Tech Syncs that happen weekly on Wednesdays. The goal of a CREW LEAD is to assign a REVIEWER from their team and provide an estimation for an initial review. A TEAM may also skip a review, but that decision should be recorded on a PR through a comment. A CREW LEAD should comment on a PR by Friday EOD. + +Examples of a comment: + +> @gh-handle will review on behalf @microsoft/TEAM by 30 Apr. + +> Our team will not review this PR, we kindly request that you use your best judgement in determining the next steps for this pull request 🐱 + +## Notes + +- A comment from a CREW LEAD provides clarity on when and who will participate in reviews +- RFCs/specs can still be reviewed by anyone +- Estimation date is only for providing an initial review, this does not mean that RFC/spec will be merged that day diff --git a/docs/react-wiki-archive/References/Browser-Support.md b/docs/react-wiki-archive/References/Browser-Support.md new file mode 100644 index 0000000000000..e0d223714631f --- /dev/null +++ b/docs/react-wiki-archive/References/Browser-Support.md @@ -0,0 +1,52 @@ +# Browser support + +Fluent UI React supports many commonly used web browsers such as Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge. For browsers outside of this matrix, proper behavior of the components may be good but is not guaranteed. + +| Browser | `@fluentui/react` version 8 | `office-ui-fabric-react` version 7 | `@fluentui/react-northstar` | `@fluentui/react-components` version 9 | +| :---------------------------------- | :-------------------------- | :--------------------------------- | --------------------------- | -------------------------------------- | +| Microsoft Edge Chromium | ✅ | ✅ | ✅ | ✅ >= 84 | +| Google Chrome (latest 2 versions) | ✅ | ✅ | ✅ | ✅ >= 84 | +| Mozilla Firefox (latest 2 versions) | ✅ | ✅ | ✅ | ✅ >= 75 | +| Apple Safari (latest 2 versions) | ✅ | ✅ | ✅ | ✅ >= 14.1 | +| Microsoft Edge Legacy | See below | ✅ | | | +| Internet Explorer 11 | See below | ✅ | | | +| Internet Explorer 9, 10 | | | | | + +## @fluentui/react-components version 9: + +- For the full breakdown of the `@fluentui/react-components` browser support matrix and other browser related philosophies we're following, see docsite [here](https://react.fluentui.dev/?path=/docs/concepts-developer-browser-support-matrix--page). + +## Internet Explorer 11 and Microsoft Edge Legacy + +[As of June 15th, 2022 Internet Explorer has been sunset](https://github.com/microsoft/fluentui/wiki/Internet-Explorer-11-Sunset). [Microsoft Edge Legacy support ended on March 9th, 2021](https://support.microsoft.com/en-us/microsoft-edge/what-is-microsoft-edge-legacy-3e779e55-4c55-08e6-ecc8-2333768c0fb0). While Fluent may continue to work in IE and Edge Legacy bug fixes and enhancements after this date may affect IE and Edge Legacy compatibility. + +As of June 15th, 2022, we will only fix IE 11 and Edge Legacy bugs in `@fluentui/react` if: + +1. They block major functionality +2. There is a major accessibility bug + +## Mobile Browser support for `@fluentui/react` version 8 + +Mobile browser support for `@fluentui/react` version 8 is done on a best effort basis. In many cases the controls work and are used. We will strive to fix major functionality that is broken across the board on mobile without workarounds. However, for issues impacting specific browsers, we likely won't be able to prioritize fixing it, but we will welcome PRs that do no regress other browsers. + +## Testing `@fluentui/react` version 8 in IE 11 + +### Doc/demo sites + +The public doc site (https://developer.microsoft.com/fluentui) and legacy demo site (https://aka.ms/fluentdemo) should both work in IE 11. + +### Testing local changes + +To test local changes in IE 11, you must use the legacy demo app (`yarn start:legacy`) due to lack of IE 11 support in storybook. You'll also need to edit a registry setting [as detailed here](https://github.com/microsoft/fluentui/issues/19222#issuecomment-892886588). + +### CodePen + +CodePen's main UI doesn't support IE 11, but you can view a pen in IE 11 using debug mode. + +1. Open the pen in another browser +2. If it's not your pen, create a fork (you can only create debug mode links for your own pens) +3. In the view menu, choose "Debug mode", copy the URL of the tab that opens, and paste that into IE 11 + + ![debug mode setting](images/debug-mode.png) + +Once generated, a debug mode link can be viewed by anyone, but they expire after a certain period of time and have to be re-generated (so it's not very useful putting them in issue descriptions/comments). diff --git a/docs/react-wiki-archive/References/The-Fabric-Component.md b/docs/react-wiki-archive/References/The-Fabric-Component.md new file mode 100644 index 0000000000000..4007bee1dbde2 --- /dev/null +++ b/docs/react-wiki-archive/References/The-Fabric-Component.md @@ -0,0 +1,34 @@ +**The `Fabric` component has been deprecated in favor of `ThemeProvider` starting in version 8 (`ThemeProvider` will also be available in version 7 soon). Please see [this page](How-to-apply-theme-to-Fluent-UI-React-components) for more details.** + +**The content below is preserved for reference purposes for those still on earlier versions.** + +--- + +Consumers using Fabric components should be wrapping their content within the `Fabric` component. + +```tsx +import { Fabric } from 'office-ui-fabric-react/lib/Fabric'; +import * as React from 'react'; +import * as ReactDOM from 'react-dom'; + +ReactDOM.render( + + + , + element, +); +``` + +- Note: The `Fabric` component will render a div, and will mix in div properties. You may use it as a replacement for a root div. + +The `Fabric` component is a root wrapper component which solves 2 problems: + +1. The default fontFamily css style is defined at this layer, allowing components within to inherit the default fontFamily. The class `ms-Fabric` defines this. + +2. The focus rectangle visibility is managed through the `is-focusVisible` css class. + +## Focus rectangle notes + +Focus rectangles around components should only be shown when the user presses tab or directional keys. When they press mouse buttons, focus rectangles should not be shown. The `Fabric` component that will conditionally add/remove an `is-focusVisible` class, and components rendering focus rectangles should conditionalize their visibility based on the `.ms-Fabric.is-focusVisible` parent selector. + +This is abstracted in the scss include `focus-border()`. diff --git a/docs/react-wiki-archive/Releases/Fabric5.md b/docs/react-wiki-archive/Releases/Fabric5.md new file mode 100644 index 0000000000000..945d1e52a3259 --- /dev/null +++ b/docs/react-wiki-archive/Releases/Fabric5.md @@ -0,0 +1,112 @@ +The changes from 4.x to 5.x are focused around bundle size, icon management, and css performance. Major list of changes: + +- Icons have been moved to a separate `@uifabric/icons` package. +- Glamor has been replaced with `@uifabric/merge-styles` package. +- Deprecated `Button` component and `ButtonTypes` enum have been removed. + +To give an idea of the bundle size impact of these change, bundling all dependencies (minus react) up to the Fabric component (one of the simplest components) has been reduced from Fabric 4 size of 34.229 KB to Fabric 5's 20.339 KB bytes gzipped. This includes all utilities, styling, and merge-styles logic, which is the foundation required for rendering Fabric components. + +This 40% reduction in foundation code is a good start, but we still can do better and will continue to slice and dice the contents to reduce further in future updates. + +# Migration guide from Fabric 4.x to Fabric 5.x + +# Before updating to 5 + +It would be a good idea to update some deprecated things in your application code before the update: + +1. Remove all references to Button and ButtonType. Replace with variants (PrimaryButton, DefaultButton, IconButton, CommandButton, CompoundButton.) + +2. Remove all references to the `ms-Icon` and `ms-Icon-*` class names. Use the `Icon` component to render icons, rather than using Fabric Core icon class names. This will make the icon transition easier. + +## Notes on Icons + +Icons definitions have been a part of the bundle size problem. 5k gzipped is dedicated to the `IconCodes` code map. Most partners do not need these. Additionally, using the icons downloads the Fabric Icon font, which adds a whopping 80k font download. This is a bad practice that no partner should be burdened with. But this has been an awkward issue to address, since we also want icons to just work out of the box. + +Another problem customers have faced is that the hardcoded SharePoint CDN urls to those icon fonts are not always ideal. In on-premise solutions, those urls can't be accessed and partners tend to have to redefine those rules. We want it to be easy to solve the on-premise scenario as well. + +In Fabric 5, we did this: + +1. We removed the IconCodes enum. + +2. We added a method `registerIcons` to the `@uifabric/styling` package which enables the partner to register a subset definition (including which font to use for what codes.) + +3. We updated the [Icon subset tool](https://aka.ms/uifabric-icons) to generate a package, including TypeScript code which would call `registerIcons` with multiple subsets. + +4. The tool can now allow a partner to choose the icons that are important to them, and then for remaining ones, can optionally split them into chunks. That means rendering the common icons would always download the first chunk but all other icons would only download the subset containing them when actually used. + +The `@uifabric/icons` package is the output of that tool, and will be the official, always updated, single source of truth package for our icons. If there is an icon on the Fabric icons page, it will be registered through. + +To use it, you need to npm install it and save it as a dependency. Then in your root code, initialize the icons through the imported `initializeIcons` function: + +```tsx +import { initializeIcons } from '@uifabric/icons'; + +initializeIcons('//mycdn.com/path/to/icons/' /* optional base url, defaults to sharepoint cdn */); +``` + +The package has a `fonts` folder which contains the fonts which you can optionally copy to your cdn. This enables the on-prem scenario. + +So, your options for supporting icons in your project are: + +1. Don't use Fabric icons. 0 byte performance penalty, yay! + +2. Use the `@uifabric/icons` package. 5k gzip penalty for registering all icons + used font subset download. + +3. Import directly from `@uifabric/icons/lib/fabric-icons-0` to register only the first subset (which includes just the icons that Fabric components use, plus common commanding icons.) Less than 1k gzip penalty for registering just the core icons + 4k core only font subset. + +4. Custom icons! Use the [icon subset tool](https://aka.ms/uifabric-icons) to choose the exact set of icons to register and build your own icon registration code. You can even choose to use inlined icons and include them with your JavaScript bundle. + +# Glamor replacement + +In Fabric 4, we introduced the library Glamor into our project as an initial step towards better control of css generation. It enabled a number of features such as contextual theming, better on demand class registration, and sharing of variables defined in javascript. Perhaps most importantly, it allows us to take `styles` in as props to components which is a much more robust and error-free way to style components compared to the fragile css class name approach which suffers from specificity and no build time validation. + +In the initial set of components we converted, we saw a lot of room for improvement in Glamor: + +- Bundle size penalty is ~11k total (glamor + dependencies) +- Edge performance is very poor (registering 1000 simple rules takes 350ms, and moves exponentially upwards beyond that.) +- TypeScript type safety is missing +- Numerous console warnings emitted with no way to disable them other than to use webpack with DefinePlugin defining the 'production' NODE_ENV value. + +In order to address these issues, and to have tighter control over the iteration and management of this very important core service of creating controls, we are replacing it with our own library `@uifabric/merge-styles`. This allows us to address the issues: + +- Bundle size reduced down to 2.6k. (~8k improvement) +- Edge performance is significantly better. (registering 1000 rules takes <45ms and stays static as you register more.) +- Registering styles is completely type safe now, so doing things like registering `background: 42` will red squiggly. +- No more console warnings +- Tighter control over the release process, we can fix things quickly +- Everything unit tested with 100% code coverage. + +If you were using `mergeStyles` from the `@uifabric/styling` package before, there is a minor modification to the styles you pass into it. For selector rules such as `:hover` or `:before`, these must now be encapsulated within a `selectors` collection. This was done to keep type-safety working (once you add a string indexer, you lose type-safety benefits in catching typos like `bakcground: 'red'`.) + +Before: + +```tsx +mergeStyles({ + ':hover': { + background: 'red', + }, +}); +``` + +After: + +```tsx +mergeStyles({ + selectors: { + ':hover': { + background: 'red', + }, + }, +}); +``` + +Some helpers that were from glamor, such as `parent()` and `before()` have been removed, since you can express these using these selectors. If your selector statement has an ampersand in it, it will translate that into the exact rule replacing the ampersand with the generated className: + +| selector | becomes | +| ----------- | -------------------------- | +| `.parent &` | `.parent .css-123` | +| `& .child` | `.css-123 .child` | +| `&:before` | `.css-123:before` | +| `:hover` | `.css-123:hover` | +| `BUTTON.&` | `BUTTON.css-123` | +| `&&&` | `.css-123.css-123.css-123` | diff --git a/docs/react-wiki-archive/Repo-structure.md b/docs/react-wiki-archive/Repo-structure.md new file mode 100644 index 0000000000000..208d9a76da9aa --- /dev/null +++ b/docs/react-wiki-archive/Repo-structure.md @@ -0,0 +1,43 @@ +Our repository structure is an important topic to touch on as it is the gateway into contributing to our codebase. + +## Folders + +At the root level, there are general configuration files for the repository (such as package.json, prettier.config.js, tsconfig.json, yarn.lock, etc.) as well as a number of different folders, including: + +- `apps`: Contains a number of non-published packages used for internal purposes, such as tests and the website. +- `packages`: Contains our published packages that cover everything from styling, theming and utilities to the components that make the Fluent UI React library. +- `packages/fluentui`: Contains packages, utilities, and tests specific to `@fluentui/react-northstar` +- `scripts`: Contains most of the scripts used for the inner loop build system and for the monorepo management. +- `specs`: Contains technical specs that lay the foundation on which a number of different components are built, although it is not being frequently updated as of now. +- `typings`: Contains custom type definitions for custom global types and packages which don't have `@types` or included declaration files. + +## Relevant published packages + +**NOTE: The info below DOES NOT currently cover `@fluentui/react-components` and related packages from the latest convergence work!** + +Below is some information about some of the most relevant published packages, as they are where most of the work we do happens. + +Note: The repo structure and packages will change over time as we converge existing libraries. This is the reason for the current complexity with these packages. + +First we have the packages that directly deal with the set of components we provide for consumption: + +- `@fluentui/react`: Exports the official finished components which we plan to support long-term or which we plan to provide good migration paths if major changes are made. This is a suite package that mostly re-exports components in other packages, but a few components live here right now to avoid circular dependencies. +- `@fluentui/react-northstar` (under `packages/fluentui/react-northstar`): This package contains the set of components that is mainly consumed by the Teams web application. The set of packages under `packages/fluentui` contains utilities associated with these components. +- `@fluentui/react-{component}`: This set of packages (with some exceptions outlined below) contains work on versions of the components that are expected to use our new composition and styling approaches, which should address the needs of both `react` and `react-northstar` variants in their design (used in v9+, we call these components "converged"). These packages are in varying states of active work and completeness. + - `@fluentui/react-cards`: This package exports the non-converged version of Card. The converged-WIP version is `@fluentui/react-card` (singular). + - `@fluentui/react-focus`: Contains the `FocusZone` component which is re-exported by the suite package. + - Other old packages (see below): `@fluentui/react-charting`, `@fluentui/react-date-time`, `@fluentui/react-experiments` + +Then we have those packages that, while not having components in them, are supporting on how we build them: + +- `@fluentui/merge-styles`: This package includes the inner workings of our existing styling solution used in most of the components in the suite package. +- `@fluentui/make-styles`: This package contains explorations on newer styling solutions that are being experimented with to solve the problems that exist with today's styling solution. +- `@fluentui/style-utilities`: This package includes a number of styling helpers required by most Fluent UI React components. +- `@fluentui/utilities`: This package includes a number of basic utility functions required by most Fluent UI React components. +- `@fluentui/theme`: This package includes all the building blocks to create a theme to be consumed by Fluent UI React components. + +The below packages are worth knowing about but are mostly not actively worked on by our team: + +- `@fluentui/react-charting`: This package has ongoing work but is owned and developed by a separate team. It does not follow most of the patterns that exist in the rest of the repo and we should consider splitting it out in the future. +- `@fluentui/react-date-time`: Previously contained Calendar and DatePicker. As of version 8, these have moved to the suite and this package just re-exports them. +- `@fluentui/react-experiments`: This is a legacy package that was used for developing experimental components and proving out ideas. Some things in there are actively worked on or used by other teams while others have been abandoned. More discussion about this package [can be found here](https://github.com/microsoft/fluentui/issues/16452). diff --git a/docs/react-wiki-archive/Rush-5-Change-Notes.md b/docs/react-wiki-archive/Rush-5-Change-Notes.md new file mode 100644 index 0000000000000..3683c3ecc1270 --- /dev/null +++ b/docs/react-wiki-archive/Rush-5-Change-Notes.md @@ -0,0 +1,22 @@ +Office UI Fabric React 5.x and 6.x branches use Rush 5. + +## rush update + +`rush generate` and `rush install` are merged into a simplified command `rush update`. `rush install` still exists in Rush 5 and is still the read-only operation. Developers can continue to use it in their everyday workflow if they like the distinction. The semantic differences are: + +1. `rush generate` forced you to run `rush install` if nothing had changed, whereas `rush update` will simply succeed and do nothing. +2. `rush update` now by default does an incremental update (whereas `rush generate` rebuilt the entire shrinkwrap file by default). + +#### npm run generate vs. npm run rush-update + +`npm run generate` runs `rush update --full`. `npm run rush-update` runs `rush update` without `--full`. + +## rush install --purge + +`rush install --clean` and `--full-clean` have been replaced with `rush install --purge`. + +## NPM/PNPM + +The new workflow works with both NPM and PNPM. + +#### Check out the official https://rushjs.io/ docs for more detailed information and developer tutorials. diff --git a/docs/react-wiki-archive/Sample-App.md b/docs/react-wiki-archive/Sample-App.md new file mode 100644 index 0000000000000..a30b1262c1644 --- /dev/null +++ b/docs/react-wiki-archive/Sample-App.md @@ -0,0 +1 @@ +[Please see the "Get started" section on our website.](https://developer.microsoft.com/en-us/fluentui#/get-started/web) diff --git a/docs/react-wiki-archive/Server-side-rendering-and-browserless-testing.md b/docs/react-wiki-archive/Server-side-rendering-and-browserless-testing.md new file mode 100644 index 0000000000000..5d476751861ea --- /dev/null +++ b/docs/react-wiki-archive/Server-side-rendering-and-browserless-testing.md @@ -0,0 +1,200 @@ +## Server-side rendering + +## Next.js setup + +For basic instructions on getting Next.js set up, see https://nextjs.org/ + +1. Get a basic next.js setup running, rendering a page from the `pages` folder, as guided by the tutorial. +2. Add a dependency on `@fluentui/react` + +```bash +yarn add @fluentui/react +``` + +1. Create a `_document.js` file under your `pages` folder with the following content: + +```tsx +import * as React from 'react'; +import Document, { Head, Html, Main, NextScript } from 'next/document'; +import { Stylesheet, resetIds } from '@fluentui/react'; +// Fluent UI React (Fabric) 7 or earlier +// import { Stylesheet, resetIds } from 'office-ui-fabric-react'; + +const stylesheet = Stylesheet.getInstance(); + +// Now set up the document, and just reset the stylesheet. +export default class MyDocument extends Document { + static getInitialProps({ renderPage }) { + resetIds(); + + const page = renderPage(App => props => ); + + return { ...page, styleTags: stylesheet.getRules(true), serializedStylesheet: stylesheet.serialize() }; + } + + render() { + return ( + + + + + + ${body} + + + `, +); +``` diff --git a/docs/react-wiki-archive/Sidebar.md b/docs/react-wiki-archive/Sidebar.md new file mode 100644 index 0000000000000..1c7f9207cd7ed --- /dev/null +++ b/docs/react-wiki-archive/Sidebar.md @@ -0,0 +1,107 @@ +### What's new + +- [FAQ - Fabric and Stardust to Fluent UI](FAQ---Fabric-and-Stardust-to-Fluent-UI) +- `@fluentui/react` Version 9 + - [Release Schedule](Fluent-UI-React-v9-Release) + - [Component Roadmap](Fluent-UI-React-v9-Component-Roadmap) +- `@fluentui/react` Version 8 + - [Release notes](Version-8-release-notes) + - [Migration guide](Version-8-migration-guide) + - [Internet Explorer 11 Sunset](Internet-Explorer-11-Sunset) +- [Contributing to the `7.0` branch](Contributing-to-the-7.0-branch) +- [How to apply themes (version 7/8)](How-to-apply-theme-to-Fluent-UI-React-components) + +### Planning + +- [Fluent UI React roadmap](Fluent-UI-React-Roadmap) +- [Monthly project cycles](Fluent-UI-Project-Cycles) + +### Process + +- [Planning and development process](Fluent-UI-Dev-Process) (for work by the core team) + - [Project template](Fluent-UI-Project-Template) + - [Project retrospective template](Fluent-UI-Project-Retrospective-Template) +- [Conducting meetings Style guide](Conducting-Meetings-Style-Guide) +- [Keeping up with review requests](Keeping-up-with-review-requests) +- [RFC review process](RFC-review-process) + +### Usage + +- [Setup (configuring your environment)](Setup) +- Fluent UI React version 7/8 + - [Getting started](Getting-Started-with-Fluent-UI-React) + - [Applying themes](How-to-apply-theme-to-Fluent-UI-React-components) + - [Using icons](Using-icons) + - [Customizing fonts](Customizing-fonts) + - [Server-side rendering and browserless testing](Server-side-rendering-and-browserless-testing) + +### Reporting issues + +- [Known External Issues](Known-External-Issues) +- [Overview](Reporting-Issues) +- [Accessibility Troubleshooting](Accessibility-Troubleshooting) + +### Contributing + +- [CLA](CLA) +- [Overview](Contributing) +- [Repo structure](Repo-structure) +- Development process + - [Setup](Setup) (and development basics) + - [Development workflow](Development-Workflow) + - [Using local (unpublished) version of the lib with a local React app]() + - [Build commands (master, 7.0)](Build-Commands) + - [Change files](Change-Files) +- Contributing to previous versions + - [Contributing to the `7.0` branch](Contributing-to-the-7.0-branch) + - [Legacy branches (5.0, 6.0)](Legacy-Branches) + - [Cherry-picking to 6.0](Cherry-Picking-fixes-from-Fabric-7.0-to-6.0) + - [Build commands (5.0, 6.0 branches)]() +- [API Extractor](API-Extractor) +- [Build command changes](Build-Command-Changes) made in early 2020 + +### Component creation and convergence + +- [Component implementation guide](Component-Implementation-Guide) +- [Creating a component](New-Components) +- [Implementation Best Practices](Implementation-Best-Practices) +- [Theming](Theming) +- [Documenting](API-Documentation) +- [Styling (old approach)](Component-Styling) + +### Testing + +- [Overview](Testing) +- [Testing with Jest](Testing-with-Jest) +- [E2E testing (Cypress)](E2E-testing-with-Cypress) +- [Visual testing (Screener)](Visual-regression-testing-with-Screener) +- [Accessibility review checklist](Manual-Accessibility-Review-Checklist) + +### Coding guidelines + +- [Coding style](Coding-Style) +- [React guidelines](React-Guidelines) +- [TypeScript guidelines](TypeScript-Guidelines) + +### Best practices + +- [Performance](Performance) +- [Accessibility](Accessibility) +- [Advanced usage](Advanced-Usage) +- [Component design](Component-Design) +- [Component usage](Component-Usage) +- [Deprecation guidelines](Deprecation-Guidelines) + +### References + +- [FAQ](FAQ) +- [Browser support](Browser-Support) +- [mergeStyles reference](https://github.com/microsoft/fluentui/blob/master/packages/merge-styles/README.md) +- [Perf testing](Perf-Testing) +- [Layer & portals](Layer-&-Portals) +- [Migration from 4.x to 5.x](Fabric5) +- [Fabric 7.0 release notes](Fabric-7) + +### Useful tools + +- [Advanced auto-merge commands](Advanced-auto-merge) diff --git a/docs/react-wiki-archive/Slots-Tokens.md b/docs/react-wiki-archive/Slots-Tokens.md new file mode 100644 index 0000000000000..dc01dd8fefe3a --- /dev/null +++ b/docs/react-wiki-archive/Slots-Tokens.md @@ -0,0 +1 @@ +The slots and tokens API from `@uifabric/foundation` (previously documented on this page) has been deprecated, and as of spring 2021 we're still finalizing the new approach that will be used in converged components. diff --git a/docs/react-wiki-archive/Spec-Template.md b/docs/react-wiki-archive/Spec-Template.md new file mode 100644 index 0000000000000..0b3058d4f8812 --- /dev/null +++ b/docs/react-wiki-archive/Spec-Template.md @@ -0,0 +1,63 @@ +# Spec Template + +## Background + +_Description and use cases of this component_ + +## Prior Art + +_Include background research done for this component_ + +- _Link to Open UI research_ +- _Link to comparison of v7 and v0_ +- _Link to GitHub epic issue for the converged component_ + +## Sample Code + +_Provide some representative example code that uses the proposed API for the component_ + +## Variants + +_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._ + +## API + +_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_ + +## Structure + +- _**Public**_ +- _**Internal**_ +- _**DOM** - how the component will be rendered as HTML elements_ + +## Migration + +_Describe what will need to be done to upgrade from the existing implementations:_ + +- _Migration from v8_ +- _Migration from v0_ + +## Behaviors + +_Explain how the component will behave in use, including:_ + +- _Component States_ +- _Interaction_ + - _Keyboard_ + - _Cursor_ + - _Touch_ + - _Screen readers_ + +## Accessibility + +Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document. + +- Decide whether to use **native element** or follow **ARIA** and provide reasons +- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible. +- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props. +- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used +- Specify texts for **state change announcements** - [ARIA live regions + ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...) +- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them +- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation) +- List cases when **focus** needs to be **moved programmatically** (if parts of the UI are appearing/disappearing or other cases) diff --git a/docs/react-wiki-archive/Theming.md b/docs/react-wiki-archive/Theming.md new file mode 100644 index 0000000000000..f62535d4dde59 --- /dev/null +++ b/docs/react-wiki-archive/Theming.md @@ -0,0 +1,55 @@ +This document describes theming at a high level. For low level technical details, follow the links. + +**Note that the information on this page currently applies only to `@fluentui/react` version 7/8 (and `office-ui-fabric-react`)**, not `@fluentui/react-northstar` or `@fluentui/web-components`. + +## What is theming? + +Theming is a mechanism by which a consistent look and feel can be applied to all the components on a page. For now, this means sharing a color scheme across the entire page. + +## What's in a theme? + +A theme is defined by a simple collection of variables (which we call slots) with string values. +For example, `themePrimary` by default is `"#0078d4"`, but it could easily be `"rgba(0, 120, 212)"`. + +## What are theme slots? + +There are two kinds of theme slots: palette slots and semantic slots. + +Palette slots are documented in [IPalette.ts](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/IPalette.ts). These are **descriptive** slots: it gives you an idea of what the color is, but you decide how to use it. Most slots with color names (besides `white` and `black`), such as `yellow` and `yellowLight`, will remain a shade of yellow in all themes, useful in cases where color has meaning (such as for errors and warnings). Customizing palette slots allows broad-stroke changes to the overall color scheme. + +Semantic slots are documented in [ISemanticColors.ts](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/ISemanticColors.ts). These are **prescriptive** slots: each one has an intended use. This allows more targeted customizations. For example, you could change the light gray color of a disabled checkbox without affecting the light gray background used by list item hover/selection state, even though they share the same color, because they use different slots. This wouldn't be possible with palette slots. + +We highly recommend using semantic slots wherever possible. + + + +> **NOTE:** The semantic slot list is fairly comprehensive, and should satisfy the vast majority of theming needs. Fluent UI React's policy is that semantic slots may NEVER be removed from the list, so any additions are permanent. _Adding new slots should be a rare event that requires ample justification._ +> +> If a designer can make a case that a new semantic slot is needed, **a new slot can be added to Fluent UI React with the following process:** +> +> 1. The new slot must be approved by the Fluent UI React theming feature crew +> 2. Add the slot definition to the [interface](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/ISemanticColors.ts), with a description on how it can be used +> - Follow the naming convention at the top, and try to fit it in a category +> 3. Add the slot's default palette color in the default blue theme in [`makeSemanticColors()`](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/utilities/makeSemanticColors.ts) +> 4. Add the variant-specific logic to the [variants package](https://github.com/microsoft/fluentui/blob/master/packages/variants/src/variants.ts) +> 5. For backwards-compatibility with SASS, run the script to add the semantic slot and raw default color to the [fallback scss file](https://github.com/microsoft/fluentui/blob/master/packages/common-styles/src/_semanticSlots.scss): from within `packages/common-styles`, run `yarn update-sass-theme-files`. + +## How do I make a theme? + +Check out the [Theme Designer](https://aka.ms/themedesigner) tool to quickly create a custom theme. + +You can define just the subset of slots you want to customize. +For instance, you could overwrite all the `neutral*`s with shades of red. +Anything using one of those palette slots will become reddish. + +Semantic slots usually "inherit" from a palette slot. For example, the `bodyText` semantic slot, if uncustomized, will always pick up the color from the palette slot `neutralPrimary`. You can see these default assignments in [`makeSemanticColors()`](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/utilities/makeSemanticColors.ts). + +## What happens when you theme? + +At a high level, there is a theme definition, which defines the desired color scheme. The theming module, which does the actual work, parses this theme definition, then updates any registered CSS to match the given color scheme. + +Inside the registered CSS are theme tokens that the theming module keeps track of. These theme tokens are basically variables, whose values the theming module changes based on the provided theme definition. + +## How to apply the theme? + +Once you have defined the theme for your app, you need to apply the theme to the components. Fluent UI React currently supports multiple ways of applying themes. You can read [this wiki page](https://github.com/microsoft/fluentui/wiki/How-to-apply-theme-to-Fluent-UI-React-components) for more details. diff --git a/docs/react-wiki-archive/Using-local-unpublished-version-of-the-lib-with-a-local-React-app.md b/docs/react-wiki-archive/Using-local-unpublished-version-of-the-lib-with-a-local-React-app.md new file mode 100644 index 0000000000000..e6d7b0eda524a --- /dev/null +++ b/docs/react-wiki-archive/Using-local-unpublished-version-of-the-lib-with-a-local-React-app.md @@ -0,0 +1,111 @@ +In addition to the standard [development practice](https://github.com/microsoft/fluentui/wiki/Development-Workflow), it is sometimes useful to run a local app against the introduced changes within the library, for instance, when trying to repro a bug locally, etc. In this case, `yarn link` tool comes in real handy, and this short guide will take you through the full setup to get you up and running. + +## The scenario + +Suppose you've just done some changes to how the `PrimaryButton` component behaves, and you'd like to test it in your custom local React app, in addition to running suitable `fluentui` tests, etc. For the sake of argument, let's pretend the projects are laid out as follows: + +``` +common_root + \ + | -- fluentui (this repo with your changes) + | + | -- app (React TS app) +``` + +The app can be any React app. For simplicity, we'll assume you've used the standard bootstrap tooling such `create-react-app` like so: + +``` +$ npx create-react-app app --template typescript +``` + +and in `src/index.tsx` you've something along the lines of: + +```typescript +import { render } from 'react-dom'; +import { PrimaryButton } from '@fluentui/react'; + +// ... + +render(, document.getElementById('content')); +``` + +Normally, you'd add `@fluentui/react` to your project using `yarn add `. However, since we want to test our local changes to the `fluentui` package, this will not be sufficient. This is where `yarn link` saves the day. `yarn link` creates a symlink to your local package inside the `node_modules` directory, however, at the same time, it doesn't add the dependency to the `package.json` file. Having said that, you can still import the linked package as you'd normally do when adding a package from the npm registry. So no difference there. The trick is with the actual linking. We discuss this next. + +## The solution + +We want to link `@fluentui/react` as a dependency of the `app` package. To do this, we first of all need to add our local copy of `@fluentui/react` into `yarn`'s link registry. This can be done by navigating to the `fluentui` project and then into the appropriate package source directory, in this case, `react`, and invoking `yarn link`: + +``` +$ cd fluentui/packages/react +$ yarn link +yarn link v1.22.10 +success Registered "@fluentui/react". +info You can now run `yarn link "@fluentui/react"` in the projects where you want to use this package and it will be used instead. +✨ Done in 0.04s. +``` + +OK, so we're halfway there. Now, from within the `app`'s root directory, we execute the hint given to us by `yarn link`, that is: + +``` +$ cd app +$ yarn link @fluentui/react +yarn link v1.22.10 +success Using linked package for "@fluentui/react". +✨ Done in 0.04s. +``` + +After this is done, if you navigate into your `app`'s `node_modules` dir, you'll see that `@fluentui/react` is a symlink: + +``` +$ cd app/node_modules/@fluentui +$ ls -la react +lrwxr-xr-x 1 username group 45 Jan 11 13:03 node_modules/@fluentui/react -> ../../../../.config/yarn/link/@fluentui/react +``` + +This symlink points to `yarn`'s local link-registry, which in turn dereferences to the `fluentui/packages/react` directory: + +``` +$ ls -la ~/.config/yarn/link/@fluentui/react +lrwxr-xr-x 1 username group 39 Jan 11 11:56 ~/.config/yarn/link/@fluentui/react -> ../../../../common_root/fluentui/packages/react +``` + +In effect, you can think of it as: + +``` +common_root + \ + | -- fluentui + | \ + | | -- packages/react <---------| + | | + | -- app | + \ | + | -- node_modules/@fluentui/react +``` + +If you try running your app however, you will get greeted by a nasty looking [React error scolding you for violating the "Rules of Hooks"](https://reactjs.org/warnings/invalid-hook-call-warning.html). The good news is, we've not violated anything. The bad news is, the app will refuse to launch. It turns out, in addition to violating the "Rules of Hooks", this problem also surfaces when the two projects you want to link locally via symlink both add `react` and `react-dom` as dependencies. In such case, as prescribed by React, it is necessary to manually link in the same version of `react` and `react-dom` between the linked packages using `npm link `, and is best done in the lib's `node_modules`: + +``` +$ cd fluentui +$ rm -rf fluentui/node_modules/react # please, be extremely careful when invoking rm with -rf flags! +$ rm -rf fluentui/node_modules/react-dom +$ npm link ../app/node_modules/react +$ npm link ../app/node_modules/react-dom +``` + +With this done, you should be able to successfully run the app: + +``` +$ yarn start +``` + +## Development workflow + +Now, whenever you make tweaks to the `fluentui` lib, you simply need to rebuild it via: + +``` +$ cd fluentui +$ yarn buildto react +``` + +And the changes should be automatically picked up by the `app`. diff --git a/docs/react-wiki-archive/Version-8-migration-guide.md b/docs/react-wiki-archive/Version-8-migration-guide.md new file mode 100644 index 0000000000000..0848d25421b41 --- /dev/null +++ b/docs/react-wiki-archive/Version-8-migration-guide.md @@ -0,0 +1,549 @@ +This page provides a detailed list of changes and migration guide for Fluent UI React version 8. [See the release notes for a higher-level overview.](Version-8-release-notes) + + + +- [Easier migration](#easier-migration) +- [Using codemods](#using-codemods) +- [Supported dependency versions](#supported-dependency-versions) +- [Package renames](#package-renames) + - [`office-ui-fabric-react` to `@fluentui/react`](#office-ui-fabric-react-to-fluentuireact) + - [`@uifabric` package renames](#uifabric-package-renames) +- [Function component conversions](#function-component-conversions) + - [Converted components](#converted-components) + - [Potentially breaking changes](#potentially-breaking-changes) +- [Theming changes](#theming-changes) +- [Individual components: new features](#individual-components-new-features) +- [Individual components: breaking changes](#individual-components-breaking-changes) +- [Keytips](#keytips) +- [Child window support](#child-window-support) +- [Other changes](#other-changes) + - [Removed experimental components](#removed-experimental-components) + - [Removed internal paths](#removed-internal-paths) +- [Known issues](#known-issues) + +--- + +## Easier migration + +As of 2022-09-05, Fluent UI React v7 has been updated to ease migration from `@uifabric` and `office-ui-fabric-react` to `@fluentui` packages and imports. + +If you first update your package references and imports to the `@fluentui` name while remaining on v7, moving to v8 will require fewer changes. You will be able to focus on the few breaking changes between v7 and v8. + +### @fluentui Stub Packages + +The following packages were added to v7 that publish the `@uifabric` exports as equivalent `@fluentui` exports. + +> Important! v8 removed implicit exports which removed deep imports beyond the lib level. The stub packages only re-export top-level and lib level exports. For example, `office-ui-fabric-react/lib/components/Button/CommandBarButton/CommandBarButton` should become `@fluentui/react/lib/Button` if you are still doing lib level imports or `@fluent/react` if moving to package-level imports. + +| @uifabric package | @fluentui stub package | +| ----------------- | ---------------------- | +| charting | react-charting | +| experiments | react-experiments | +| file-type-icons | react-file-type-icons | +| icons | font-icons-mdl2 | +| merge-styles | merge-style | +| react-cards | react-cards | +| react-hooks | react-hooks | +| styling | style-utilities | +| utilities | utilities | +| variants | scheme-utilities | + +### v7 and v8 fixes + +Fixes and additions were made to both v7 and v8 to make migration easier. Many were ensuring that the getStyles methods for various components were exported under unique names at the top level. Others included exporting types and methods that were previously implicit exports. + +v8: + +- [Added roundedCorners missing from common-styles](https://github.com/microsoft/fluentui/pull/24091) + +- [Expanded ChoiceGroup callbacks to remove breaking change](https://github.com/microsoft/fluentui/pull/24242) +- [Exported ActivityItem getStyles](https://github.com/microsoft/fluentui/pull/24475) +- [Exported CommandBar getStyles](https://github.com/microsoft/fluentui/pull/24478) +- [Exported DetailsList getStyles](https://github.com/microsoft/fluentui/pull/22990) +- [Exported ContextualMenu getItemStyles](https://github.com/microsoft/fluentui/pull/24484) +- [Exported Layer getStyles and notifications](https://github.com/microsoft/fluentui/pull/24485) +- [Exported Picker getStyles](https://github.com/microsoft/fluentui/pull/24509) +- [Exported TextField getStyles](https://github.com/microsoft/fluentui/pull/24511) +- [Exported GroupedListUtilities](https://github.com/microsoft/fluentui/pull/24515) + +v7: + +- [Exported lib/Decorators](https://github.com/microsoft/fluentui/pull/24192) +- [Exported ActivityItem getStyles](https://github.com/microsoft/fluentui/pull/24473) +- [Exported CommandBar getStyles](https://github.com/microsoft/fluentui/pull/24476) +- [Exported DetailsList getStyles](https://github.com/microsoft/fluentui/pull/24483) +- [Exported ContextualMenu getItemStyles](https://github.com/microsoft/fluentui/pull/24493) +- [Exported Layer getStyles and notifications](https://github.com/microsoft/fluentui/pull/24495) +- [Exported Picker getStyles](https://github.com/microsoft/fluentui/pull/24508) +- [Exported TextField getStyles](https://github.com/microsoft/fluentui/pull/24510) +- [Exported GroupedListUtilities](https://github.com/microsoft/fluentui/pull/24514) + +--- + +## Using codemods + +We've provided a number of codemods to help make picking up name and API changes easier. + +Run `npx @fluentui/codemods` to automatically upgrade your repo! This will result in changes being made to files so be sure to run it separate from an other active changes that you have. + +More documentation [here](https://github.com/microsoft/fluentui/wiki/Codemods). + +--- + +## Supported dependency versions + +The minimum supported **React** version remains at **16.8**. React 17 is also supported but has not yet been thoroughly tested due to tooling issues, so if you encounter any problems, please file an issue and we'll fix it. + +The minimum supported **TypeScript** version has increased to **3.9**. Later versions should also work. Our `tslib` dependency has been updated to version 2, as required by TS 3.9. + +React 16.8 and TypeScript 3.9 will continue to be our minimum supported versions for the duration of `@fluentui/react` version 8. + +(We've updated our tooling within the repo to TypeScript 4.1, but we'll ensure that this _does not_ affect our public APIs.) + +--- + +## Package renames + +As the Fabric brand has evolved to Fluent UI, we've renamed our main package from `office-ui-fabric-react` to `@fluentui/react`. The `@uifabric` sub-packages have also been moved to the `@fluentui` scope and in some cases renamed. + +### `office-ui-fabric-react` to `@fluentui/react` + +As of version 8, the `office-ui-fabric-react` package has been discontinued in favor of `@fluentui/react`. + +#### Deep imports: what are they, why are they bad? + +> Update: Although deep imports won't create as much of an immediate issue now that we've reverted the `@fluentui/react-internal` addition from the original beta and moved most files back to their original locations ([details here](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207)), we still **highly recommend** removing deep imports! This should be easier now since recent versions of 7 and 8-beta fixed the majority of exports that were missing from the package root. + +Some partners have deep imports into the current Fabric package; for example: + +```tsx +import { ICalloutProps } from 'office-ui-fabric-react/lib/components/Callout/Callout.types'; +``` + +This has never been supported officially, as we've always recommended to use either the package import or a "top-level import," meaning a file directly under the `/lib/` path. + +```tsx +import { ICalloutProps } from '@fluentui/react'; // Good +import { ICalloutProps } from '@fluentui/react/lib/Callout'; // Also good +``` + +We cannot guarantee any deep import will continue working across major releases. They will break any time any given file is moved, renamed, or even when the casing is changed. This would create a massive surface contract that we are not able to support. + +If you have deep imports in your product, please update them now to only use package or top-level imports. (And please, let us know if you depend on something that is not exported. We can fix that.) + +### `@uifabric` package renames + +The `@uifabric` sub-packages have been moved to the `@fluentui` scope and in some cases renamed to reflect our current naming conventions. + +These renames can automatically be picked up in TypeScript code by [running codemods](#using-codemods), though references in `package.json` and other configuration files will need to be updated manually. + +The following table shows the new package names. For more details and history, [see this issue](https://github.com/microsoft/fluentui/issues/13384). (The UMD global name is probably only relevant for codepen examples or prototypes, not apps which use a bundler.) + +| Old name (under `@uifabric`) | New name (under `@fluentui`) | New UMD global name | +| ------------------------------ | ---------------------------------------------------------------------------- | --------------------------- | +| `azure-themes` | same | `FluentUIAzureThemes` | +| `charting` | `react-charting` | `FluentUIReactCharting` | +| `date-time` | `react-date-time` | `FluentUIReactDateTime` | +| `example-app-base` | `react-docsite-components` | | +| `example-data` | same | `FluentUIExampleData` | +| `experiments` | `react-experiments` | `FluentUIReactExperiments` | +| `file-type-icons` | `react-file-type-icons` | | +| `foundation` | `foundation-legacy` | `FluentUIFoundationLegacy` | +| `icons` | `font-icons-mdl2` | | +| `jest-serializer-merge-styles` | same | | +| `merge-styles` | same | `MergeStyles` | +| `monaco-editor` | same | `FluentUIReactMonacoEditor` | +| `office-ui-fabric-react` | `@fluentui/react` | `FluentUIReact` | +| `react-cards` | same ([reintroduced here](https://github.com/microsoft/fluentui/pull/18965)) | `FluentUIReactCards` | +| `react-hooks` | same | `FluentUIReactHooks` | +| `set-version` | same | | +| `styling` | `style-utilities` | | +| `test-utilities` | same | | +| `theme-samples` | same | `FluentUIThemeSamples` | +| `tsx-editor` | `react-monaco-editor` | | +| `utilities` | same | | +| `variants` | `scheme-utilities` | `FluentUISchemeUtilities` | +| `webpack-utils` | `webpack-utilities` | | + +#### Discontinued packages + +The following packages have been discontinued: + +- `@uifabric/fluent-theme`: Constants have been moved to `@fluentui/theme`. Styles are now the default. +- `@uifabric/mdl2-theme`: This styling is deprecated (though you can continue to use version 7 of the package if needed). + +#### ThemeProvider location changes + +A preview of `ThemeProvider` was published with version 7 under `@fluentui/react-theme-provider`. For various reasons, it was moved from that package into `@fluentui/react` itself in version 8, so **do not use `@fluentui/react-theme-provider` in version 8.** + +--- + +## Function component conversions + +As part of the work to support [React strict mode](https://reactjs.org/docs/strict-mode.html) and unblock adoption of [React concurrent mode](https://reactjs.org/docs/concurrent-mode-intro.html) once it's released, some components were converted from class components to function components. This results in some API surface changes and may also require updates to tests. + +While the function component conversions may require a bit of extra work to pick up in the short term, they also unblock future changes to more easily share state and interaction logic between components, which will help reduce bundle sizes and make behavior more consistent across components. + +### Converted components + +The following components have been converted. (Any component not on this list remains the same component type, class or function, as it was in version 7.) + +- Breadcrumb +- Calendar +- Callout +- Checkbox +- ChoiceGroup (and ChoiceGroupOption) +- Coachmark (and Beak, PositioningContainer) +- ComboBox +- ContextualMenu +- DatePicker +- Dropdown +- Fabric +- Grid (renamed to ButtonGrid) +- Image +- Layer +- Link +- MaskedTextField +- MessageBar +- Modal +- OverflowSet +- Persona (and PersonaCoin, PersonaPresence) +- Pivot +- Popup +- Rating +- ResizeGroup +- SearchBox +- Shimmer +- Slider +- SpinButton +- SwatchColorPicker +- TeachingBubble +- Toggle + +### Potentially breaking changes + +There are a few breaking behavior and API changes for the converted components. Most of these are inherent differences between the behavior of class and function components in React, not specific to Fluent UI React. + +#### `ref` returns a DOM element, not class instance + +The `ref` prop no longer refers to a component class instance; instead, the ref is forwarded to the underlying DOM. All our function components should correctly return a reference to the root DOM element. + +For components with an imperative API (example: `IDropdown.focus()`), you can still access that via `componentRef`. + +See React's docs for [`useRef`](https://reactjs.org/docs/hooks-reference.html#useref) and [`forwardRef`](https://reactjs.org/docs/react-api.html#reactforwardref) for more on using refs with function components. + +#### `ReactDOM.findDOMNode` will not work on function components + +The [deprecated `ReactDOM.findDOMNode` API](https://reactjs.org/docs/react-dom.html#finddomnode) can't be used to find root elements of function components (this is a React limitation). Instead, use `ref` as described above. + +#### Accessing `state` is no longer supported + +Since function component state is handled with hooks rather than a `state` member, it can no longer be accessed from outside the component. + +Most important state properties should be accessible via `componentRef` on the `IComponentName` "imperative handle" interface. + +If you need a former state property which is not included in the relevant `IComponentName` interface, please file an issue and we can consider adding it. + +#### Class extension of components is no longer supported + +If you were using class extension on a component that was converted, it will no longer work. We recommend using composition instead: wrap the Fluent UI component inside another component which handles the prop or callback customizations which were previously done in the child class. + +Even for components which were not converted, class extension is **not recommended** since we'll be converting the remaining components to function components in the future, possibly within a minor release. (Exception: Class extension of Pickers will continue to be supported for now since the current architecture relies on it. We'd like to change this in the future, but not within v8.) + +#### Some test operations may need to be wrapped in `act()` + +If you have components which use our converted function components, certain test operations may need to be wrapped in `act()` (from `react-dom/test-utils`). This is a new requirement from React itself when testing function components that use hooks, and React will log console warnings if the wrapper is missing. [More details here.](https://reactjs.org/docs/test-utils.html#act) + +--- + +## Theming changes + +We know that the number of possible theming approaches and lack of clear guidance has been confusing to Fabric/Fluent UI React users in the past, so for version 8 we've added `ThemeProvider` as a unified approach to applying and accessing themes. + +Please see [this wiki page](https://github.com/microsoft/fluentui/wiki/How-to-apply-theme-to-Fluent-UI-React-components) and the [ThemeProvider README](https://github.com/microsoft/fluentui/blob/master/packages/react/src/utilities/ThemeProvider/README.md) for details about usage and migration. + +The `Fabric` and `Customizer` components have been deprecated in favor of `ThemeProvider`. (If you're using `Customizer` for purposes besides theming, please let us know.) + +**NOTE:** `ThemeProvider` was previously published under `@fluentui/react-theme-provider`. For various reasons, it was moved from that package into `@fluentui/react` itself in version 8, so **do not use `@fluentui/react-theme-provider` in version 8.** + +--- + +## Individual components: new features + +#### ~~`[IN PREVIEW]` Button~~ + +This has moved back to dev status--see [this comment](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207) for details. + +_(Note: when the beta was announced, we planned to officially release the new buttons with version 8 and export them by default from `@fluentui/react`. However, it became apparent that a bit more time was needed to ensure that we're using the right patterns to provide a good foundation for building components moving forward.)_ + +#### Calendar/DatePicker + +`Calendar` and `DatePicker` have been replaced with the versions from the `@fluentui/react-date-time` package (formerly `@uifabric/date-time`). These versions contain various bug fixes and have been converted from SCSS to CSS-in-JS. They should be almost identical in visuals and functionality, though there are some changes to how to customize styles. See under "Breaking changes" below for details. + +#### Pivot + +`Pivot` supports displaying an overflow menu when there is not enough room to display all of the tabs. This can be enabled by setting `overflowBehavior="menu"` on the `Pivot`. + +#### Rating + +It's now possible to use `Rating` as an uncontrolled component by setting `IRatingProps.defaultRating`. + +For either controlled or uncontrolled `Rating`s, the current value is now accessible via `componentRef` as `IRating.rating`. (Use this instead if you were previously accessing `Rating.state.rating`.) + +#### SpinButton + +`SpinButton` (finally) has a standard `onChange` prop. This means you can easily use it as a controlled component without having to re-implement the default increment/decrement/validate handlers. + +#### SwatchColorPicker + +`SwatchColorPicker` now has a standard `onChange` prop. `onColorChanged` is still available but has been deprecated. + +Also added support for the standard controlled/uncontrolled pattern: provide `selectedId` for controlled behavior and `defaultSelectedId` for uncontrolled behavior. + +--- + +## Individual components: breaking changes + +#### ~~Button~~ + +Due to a change of plans, there are **no breaking changes** to Button in v8. The old version of Button remains exported by default from `@fluentui/react` for this release, and the previously proposed "compat" import path for the old Button (`@fluentui/react/lib/compat/Button`) has been removed. + +#### Calendar + +`Calendar` has been replaced with the version from the `@fluentui/react-date-time` package (formerly `@uifabric/date-time`). + +- Converted styling from legacy SCSS to CSS-in-JS. Styling can now be customized using `ICalendarProps.styles` or sub-component props, such as `ICalendarProps.calendarDayProps.styles`. + - [See here](https://github.com/microsoft/fluentui/issues/15646) for details of how to override sub-components' style props and related outstanding issues. +- The DOM structure has changed, and most global classNames are no longer available. We may add some of the classNames back if needed ([see details here](https://github.com/microsoft/fluentui/issues/15646)) but haven't implemented this yet. +- Removed the following props: + - `autoNavigateOnSelection`: Now the default behavior. + - `selectDateOnClick`: Now the default behavior. + - `shouldFocusOnMount`: Use `ICalendar.focus()` instead (via `componentRef`) + - `yearPickerHidden`: Moved to `ICalendarMonthProps` (settable via `ICalendarProps.calendarMonthProps`) + +#### Callout + +- Prop `onDismiss?: (ev?: any) => void;` is now `onDismiss?: (ev?: Event | React.MouseEvent | React.KeyboardEvent) => void;` + +#### Checkbox + +`Checkbox` no longer accepts arbitrary native props at the root (`ICheckboxProps` no longer extends `React.ButtonHTMLAttributes`). This actually is _not a behavior change_: any native props or `data-*` props previously being passed through were ignored, and now the types accurately reflect the behavior. + +To apply arbitrary native props to the hidden checkbox input element (used for accessibility and forms), use `ICheckboxProps.inputProps` instead. Note that `data-*` props are supported in `ICheckboxProps.inputProps` but will require casting since TS < 4.1 doesn't provide a way to express this. This should be adequate for most scenarios, but please comment on [this issue](https://github.com/microsoft/fluentui/issues/16307) if you have a scenario where you need native props on the root element. + +#### ChoiceGroup + +- Setting `checked` on individual options to indicate their checked state is no longer supported. Instead, use `defaultSelectedKey` or `selectedKey`. +- Moved `root` style to the actual root element and removed `applicationRole` style. +- Removed deprecated props and types: + - `onChanged` from `IChoiceGroupProps` (use `onChange`) + - `checked` from `IChoiceGroupOption` (see above for alternative) + - Note that this is still available via `IChoiceGroupOptionProps` for custom rendering purposes only, and will be set correctly by the parent `ChoiceGroup`. + - Type aliases `OnFocusCallback` and `OnChangeCallback`: use `IChoiceGroupOptionProps['onFocus']` and `IChoiceGroupOptionProps['onChange']` +- Only if manually rendering the `ChoiceGroupOption` component, the new prop `itemKey` is now required. (You can still use `key` when passing options via `IChoiceGroupProps.options`, which is by far the most common.) + +#### Coachmark + +- Removed deprecated `isBeaconAnimating` and `isMeasured` style props + +#### ComboBox + +- The return type of `IComboBox.focus()` has changed from `boolean` to `void` to reflect its actual behavior (the implementation does not return a value and can't easily be modified to do so). + +#### DatePicker + +`DatePicker` has been replaced with the version from the `@fluentui/react-date-time` package (formerly `@uifabric/date-time`), which also uses the `Calendar` from that package. See the notes on `Calendar` above for details and potential breaking changes. + +#### Dropdown + +Dropdown options no longer infer `title` values from their `text` prop as it was redundant. + +#### Grid + +`Grid` has been renamed to `ButtonGrid` to better reflect what it is, and to free up the more generic name for a possible future abstraction of CSS grid. (The new name is also available in version 7.) Exported `IGridStyles` are now `IButtonGridStyles`. + +#### OverflowSet + +- Contents of the `OverflowSet` are no longer wrapped in a `FocusZone`. +- Removed deprecated `focusZoneProps` and `doNotContainWithinFocusZone` from types. + +#### Pickers + +- The picker input and selected tags are no longer wrapped in a `FocusZone`. +- The text of selected tags is no longer focusable; only the remove button is in the tab order. + +#### Pivot + +- Removed deprecated and redundant props from v7, including `initialSelectedKey` and `defaultSelectedIndex`. Use `selectedKey` or `defaultSelectedKey` to define the selected tab, and provide `itemKey` on pivot item children. +- `IPivotStyleProps` changes + - Replaced `rootIsLarge` with `linkSize`. + - Replaced `rootIsTabs` and `linkFormat`. + - Removed deprecated prop `linkIsSelected`. +- Updated enums to string union type: `PivotLinkFormat`, `PivotLinkSize`. (#13370) + +#### Popup + +- Updated signature of `onDismiss` to include the native `KeyboardEvent` as a possible type of the `ev` parameter: `onDismiss?: (ev?: React.MouseEvent | React.KeyboardEvent | KeyboardEvent) => any` + +#### Rating + +- Removed deprecated props: + - `onChanged` (use `onChange`) + - `ariaLabelId` (use `getAriaLabel`) +- Passing `null` for `IRatingProps.rating` is no longer supported. To determine whether the user has interacted with the rating yet, set `allowZeroStars: true` and check whether the rating is 0. +- Minor typing corrections: + - `IRatingProps` now extends `React.HTMLAttributes` rather than `React.AllHTMLAttributes`. The old interface included some props which don't actually apply to a `div`. + - Corrected type of `IRatingProp.onChange`'s `event` parameter to reflect how it's used internally. It should be `React.FormEvent`, not `React.FocusEvent`. + +#### SearchBox + +- If `value` is provided, the `SearchBox` will now use strict controlled behavior (the displayed value won't update until the `value` prop changes). Use `defaultValue` for uncontrolled behavior. + +#### SpinButton + +- Removed default values of `min` and `max` (formerly 0 and 100). +- If `value` is provided, the `SpinButton` will now use strict controlled behavior (the displayed value won't update until the `value` prop changes). Use `defaultValue` for uncontrolled behavior. +- `onChange` now has custom handling and is only called when the SpinButton's value is "committed" (blur, enter, or spin). If you were previously using the native `onChange` prop (applied to the component's root `div`) to be notified of every keystroke, use `onInput` instead. +- Simplified props to `ISpinButtonStyles` to include only the parts of the component to bring in line with other components. As a result, the following props have been removed (see below for migration tips): + - `arrowButtonsContainerDisabled` + - `inputDisabled` + - `inputTextSelected` + - `labelDisabled` + - `labelWrapperStart` + - `labelWrapperEnd` + - `spinButtonWrapperDisabled` + - `spinButtonWrapperFocused` + - `spinButtonWrapperHovered` + - `spinButtonWrapperTopBottom` +- Replaced `getClassNames` legacy prop with `styles` prop to bring component consistent to other components and improve cacheability of internal styles. + +If you're using a removed `ISpinButtonStyles` prop, you can instead pass a style function which returns appropriate styles based on the current state of the component. The following code snippet shows how to do this for each removed prop. + +```tsx + { + const { disabled, isFocused, labelPosition, theme } = props; + return { + spinButtonWrapper: [ + disabled && { /* spinButtonWrapperDisabled styles */ }, + isFocused && { /* spinButtonWrapperFocused styles */ }, + !disabled && { ':hover': { /* spinButtonWrapperHovered styles */ } } + ], + input: [ + disabled && { /* inputDisabled styles */ }, + !disabled && { '::selection': { /* inputTextSelected styles */ } } + ], + label: [ + disabled && { /* labelDisabled styles */ } + ], + labelWrapper: [ + (labelPosition === Position.top || labelPosition === Position.bottom) + && { /* spinButtonWrapperTopBottom styles */ }, + labelPosition === Position.left && { /* labelWrapperStart styles */ }, + labelPosition === Position.right && { /* labelWrapperEnd styles */ }, + ], + arrowButtonsContainer: [ + disabled && { /* arrowButtonsContainerDisabled styles */ } + ] + } +}}> +``` + +#### Shimmer + +- Removed unused `componentRef` prop from `Shimmer` types as it doesn't use any public methods. + +#### SwatchColorPicker + +- Selection state is now tracked internally based on `IColorCellProps.id`, not item index. Ensure that all color cells have a unique `id` property. +- Removed deprecated props: + - `positionInSet`: use `ariaPosInSet` + - `setSize`: use `ariaSetSize` +- Deprecated `isControlled`. Provide `selectedId` for controlled behavior and `defaultSelectedId` for uncontrolled behavior. +- Added an `onChange` prop and deprecated `onColorChanged`. + +#### TeachingBubble + +- Removed `rootElementRef` from public API. + +#### Text + +`Text` now uses either the selected font variant's color, or `theme.semanticColors.bodyText` as its color by default. This will only cause problems if you were previously relying on `Text` inheriting color from its parent. + +#### TextField/MaskedTextField + +- Added separate interfaces for `MaskedTextField`: `IMaskedTextFieldProps` and `IMaskedTextField` +- Moved `MaskedTextField`-specific props `mask`, `maskChar`, and `maskCharData` from the general `ITextFieldProps` to `IMaskedTextFieldProps` +- `onChange` is now called synchronously in the change event handler, _before_ updating state (previously it was called asynchronously after the state update). This more closely matches other components and React itself, but may cause issues if anyone was depending on the old behavior. + +--- + +## Keytips + +Previously, `KeytipData` was built into different components which needed Keytip support. This added extra bundle size to our components. In version 8, we have removed `KeytipData` and `keytipProps` props from `Link`, `Toggle`, `Checkbox`, `ComboBox`, `Dropdown`, and `SpinButton`. + +Here is an example on how to migrate from this change: + +Before: + +```jsx + +``` + +After: + +```jsx +import { useKeytipRef } from '@fluentui/react/lib/Keytips'; + +const checkboxRef = useKeytipRef({ keytipProps: checkboxKeytips }); + +; +``` + +You can find more code examples on the public documentation site [here](https://developer.microsoft.com/en-us/fluentui#/controls/web/keytips). + +#### Other call-outs + +- If the component is disabled and you don't want to enable keytips in that case, make sure you are passing `disabled: true` to `keytipProps`. It's possible you weren't setting `disabled` previously and still worked because the value was populated within the component which uses `KeytipData`. +- If you have another `ref` that needs to be passed to a component apart from the `ref` returned by `useKeytipRef`, you can use `useMergedRefs` from `@fluentui/react-hooks` to merge multiple refs into one then pass it to the component. + +--- + +## Child window support + +`WindowProvider` is required for child windows/embeds. This can be imported from `@fluentui/react/lib/WindowProvider` or the `@fluentui/react-window-provider` package. + +--- + +## Other changes + +### Removed experimental components + +The following components have been removed or deprecated from `@fluentui/react-experiments` (formerly `@uifabric/experiments`): + +- Removed `Button`: didn't provide desired performance gains, and is superseded by convergence work. + - `MicroFeedback` now uses the button from `@fluentui/react`; this will affect valid slot prop overrides. +- Deprecated `Slider`: we kept this one for now since it provides some functionality not currently implemented by the `@fluentui/react` `Slider`, but it will also be superseded by convergence work in the future. +- Removed `Toggle`: superseded by convergence work. + +~~The previous implementation of `Card` (which was never officially released) has been entirely removed.~~ As of [this PR](https://github.com/microsoft/fluentui/pull/18965), the deprecated experimental Card has been re-introduced under `@fluentui/react-cards`. Please don't use it in new code. + +### Removed internal paths + +- `FluentStyles` is removed from `@fluentui/react-experiments` since it re-exported `FluentStyles` from `@uifabric/fluent-theme`. Leverage `@fluentui/theme` if you want to replicate the original behavior inside your project, although this should not be needed since the `FluentStyles` are the default ones. +- Removed various files which were originally in `office-ui-fabric-react` and not intended to be part of the public API: + - `office-ui-fabric-react/src/components/Theme/defaultTheme.ts` (use `@fluentui/theme`) + - `office-ui-fabric-react/src/customizations/TeamsTheme.ts` (use `@fluentui/theme-samples`) + - `office-ui-fabric-react/src/utilities/exampleData.ts` (use `@fluentui/example-data`) +- _(list may be incomplete)_ + +### Something missing? Let us know! + +If you encounter any breaking changes which were not mentioned here, feel free to file an issue or let us know internally. + +--- + +## Known issues + +- Although we've added React 17 to our peer dependency range, the library has not been fully tested with React 17. Please file an issue if you encounter problems. + +- Azure theme styling for DatePicker and Calendar may not fully work - [#17156](https://github.com/microsoft/fluentui/issues/17156) diff --git a/docs/react-wiki-archive/Version-8-release-notes.md b/docs/react-wiki-archive/Version-8-release-notes.md new file mode 100644 index 0000000000000..712a9055b719d --- /dev/null +++ b/docs/react-wiki-archive/Version-8-release-notes.md @@ -0,0 +1,92 @@ +## Summary + +Fluent UI React version 8 (v8) is a little different than previous releases: we view it as an incremental release that starts setting up customers, partners, and contributors for the team's collective vision of improving the baseline components used in all Microsoft 365 experiences. + +To install from npm: `npm install @fluentui/react@^8.0.0` + +For a more detailed list of changes and features included in this release, see the [migration guide](Version-8-migration-guide). + +Highlights: + +- **No major visual changes** +- **[Package restructuring](#package-restructuring)** paves the way for smoother updates in the future +- **[React strict mode support](#react-strict-mode-support)** + - Most components converted to function components with hooks + - Unblocks use of [React strict mode](https://reactjs.org/docs/strict-mode.html) while developing applications + - Unblocks adoption of [React concurrent mode](https://reactjs.org/docs/concurrent-mode-intro.html) once it's released +- **[Theming improvements](#theming-changes)**: providing a unified way to apply and access themes +- Enhancements and smaller breaking changes to individual components, including deprecated API surface removal -- see [migration guide](Version-8-migration-guide#individual-components-new-features) for details +- ~~**Previews** of what's up next~~: (moved back to dev status--see [this comment](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207)) + - ~~Improved Button with smaller bundle size and better performance~~ + - ~~Composition utilities~~ + +> **NOTES**: +> +> - Version 8 docs are now live on https://developer.microsoft.com/fluentui +> - **Some details of the release have changed since the original announcement.** For a summary of major changes, see [this comment](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207). The overall impact is actually that **`@fluentui/react` version 8 is more similar to version 7.** + +## What's in v8 + +_Note: "v8" here refers to "version 8," not the v8 JavaScript engine._ + +### Package restructuring + +As part of this release, we're starting to restructure our packages to pave the way for future updates. + +#### `[Breaking]` Package renaming `office-ui-fabric-react` to `@fluentui/react` + +Starting in v8, the `office-ui-fabric-react` name has been discontinued and you will need to install `@fluentui/react` instead. Note that as a consequence of some related changes, **deep imports are no longer supported.** [More details and migration tips here.](Version-8-migration-guide#package-renames) + +#### `[Breaking]` `@uifabric` to `@fluentui` package renames + +The `@uifabric` packages have been moved to the `@fluentui` scope, and in some cases renamed to better align with current conventions. [More details and migration tips here.](Version-8-migration-guide#uifabric-package-renames) + +We plan to provide a codemod (not yet implemented) to help with picking up the renames, but in the meantime you can find the mapping between old and new names in the link above. + +### React strict mode support + +#### Full [strict mode](https://reactjs.org/docs/strict-mode.html) support for all suite components + +In components exported by the main `@fluentui/react` suite package, we've removed usage of all features that are unsupported in strict mode, such as legacy React lifecycle APIs (`UNSAFE_*`) and `ReactDOM.findDOMNode`. This should unblock testing with strict mode, as well as adoption of [concurrent mode](https://reactjs.org/docs/concurrent-mode-intro.html) once it's released. + +There may still be some more subtle strict/concurrent mode issues with components which can't be found just in a search for deprecated APIs (such as unsafe side effects in render lifecycles). If you encounter one of these, please file an issue. + +(Exception: There are still a few components in `@fluentui/react-experiments` which use `UNSAFE_` methods or other features not supported in strict mode. These were lower priority to fix due to their experimental or deprecated status. If you have a dependency on an experimental component and need strict/concurrent mode, please file an issue.) + +#### `[Breaking]` Function component conversion + +Some components have been converted from class components to function components (and the remaining components may be converted in a minor version). In general this will not result in a significant change to the component API surface. However, there are a few important implications, [outlined in detail here](Version-8-migration-guide#function-component-conversions). + +Main points: + +- Class extension of components is no longer supported (exception: Picker components, BaseComponent) +- The `ref` prop now consistently returns the root element of the component (or for portaled components, returns the root element within the portal) +- `ReactDOM.findDOMNode` is not supported for function components +- Directly accessing components' `state` is no longer supported +- More components properly implement controlled/uncontrolled behavior and standard onChange signatures + +### Theming changes + +We know that the number of possible theming approaches and lack of clear guidance has been confusing to Fabric/Fluent UI React users in the past, so for version 8 we've added `ThemeProvider` as a unified approach to applying and accessing themes. + +Please see [this wiki page](How-to-apply-theme-to-Fluent-UI-React-components) and/or the [ThemeProvider README](https://github.com/microsoft/fluentui/blob/master/packages/react/src/utilities/ThemeProvider/README.md) for details about usage and migration. + +The `Fabric` and `Customizer` components have been deprecated in favor of `ThemeProvider`. (If you're using `Customizer` for purposes besides theming, please let us know.) + +### Individual components: new features and breaking changes + +In addition to the larger features outlined above, we've made some smaller features additions and breaking changes in individual components. [See the migration guide for details.](Version-8-migration-guide#individual-components-new-features) + +## ~~What's in preview~~ + +### ~~`[IN PREVIEW]` Improved Button~~ + +This has moved back to dev status--see [this comment](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207) for details. + +### ~~`[IN PREVIEW]` Composition utilities~~ + +This has moved back to dev status--see [this comment](https://github.com/microsoft/fluentui/issues/12770#issuecomment-776389207) for details. + +## Migration guide + +[See this page](Version-8-migration-guide) for details on migrating to version 8, including a full list of breaking changes. diff --git a/docs/react-wiki-archive/What-to-look-for-in-PRs.md b/docs/react-wiki-archive/What-to-look-for-in-PRs.md new file mode 100644 index 0000000000000..d79e3b3dccd9d --- /dev/null +++ b/docs/react-wiki-archive/What-to-look-for-in-PRs.md @@ -0,0 +1,3 @@ +Moved to: + +https://github.com/microsoft/fluentui/wiki/Pull-request-reviewing-guidance diff --git a/docs/react-wiki-archive/images/debug-mode.png b/docs/react-wiki-archive/images/debug-mode.png new file mode 100644 index 0000000000000..b954766d71618 Binary files /dev/null and b/docs/react-wiki-archive/images/debug-mode.png differ diff --git a/docs/react-wiki-archive/new-release-process---v9-packages.md b/docs/react-wiki-archive/new-release-process---v9-packages.md new file mode 100644 index 0000000000000..62c385319b640 --- /dev/null +++ b/docs/react-wiki-archive/new-release-process---v9-packages.md @@ -0,0 +1,167 @@ + + +- [New process/life-cycle flow](#new-processlife-cycle-flow) + - [Major differences with previous unstable/stable flow](#major-differences-with-previous-unstablestable-flow) + - [FAQ](#faq) + - [Is there still a need for `_unstable` suffixes for hooks/utilities?](#is-there-still-a-need-for-_unstable-suffixes-for-hooksutilities) + - [What's the process for updating already existing unstable package](#whats-the-process-for-updating-already-existing-unstable-package) + - [package not released to npm yet (`9.0.0-alpha.x`):](#package-not-released-to-npm-yet-900-alphax) + - [package already released to npm as `9.0.0-(alpha|beta|rc).x`:](#package-already-released-to-npm-as-900-alphabetarcx) +- [Dev Guide](#dev-guide) + - [1. Kick-off phase](#1-kick-off-phase) + - [2. Preview phase](#2-preview-phase) + - [3. Stable phase](#3-stable-phase) + + + +# New process/life-cycle flow + + +unstable-stable-api-new-flow + + +## Major differences with previous unstable/stable flow + +- unstable/preview components don't start with `9.0.0-.0` +- unstable/preview components will never be part of `@fluentui/react-components` suite. They can be used by installing independent package. +- 👉 **`react-components/unstable` is frozen and deprecated - this api cannot be changed in any way** +- both stable and unstable(preview) should always use `^` within package.json dependencies (no more pinned versions for pre-releases needed) +- `*-preview` packages are part of our official storybook public docs right after 1st release + - one can provide public doc-site link right away to designers/partners to test it out **without any hacks** +- unstable/preview packages follow strict semantic versioning via `0.major.(minor|patch)` pattern + - if your changes within preview package are breaking use change-type `minor` + - if you add new features or fixes within preview package use change-type `patch` + +## FAQ + +### Is there still a need for `_unstable` suffixes for hooks/utilities? + +Any utilities that are in a stable package **cannot be broken**. Therefore, the purpose of the `_unstable` suffix has changed. If the owner feels confident that the API of that hook/utility has a sufficient level of extensibility, there is no need for a suffix. However, if there are doubts about the implementation that can be addressed in the future the `_unstable` suffix can communicate that to users. A stable version (i.e. one without the suffix) can be reserved for future use once there is more confidence the use case or functionality. + +Any hooks/utilities with the `_unstable` suffix **cannot be removed and cannot be broken until the next major version**. + +### What's the process for updating already existing unstable package + +#### package not released to npm yet (`9.0.0-alpha.x`): + +> All packages migration PR https://github.com/microsoft/fluentui/pull/28474 + +
+Let's say you have already created `packages/react-components/react-control` package which is in unstable phase. + +Follow these steps: + +1. rename package directory and api.md + +```sh +mv packages/react-components/react-control packages/react-components/react-control-preview +mv packages/react-components/react-control/etc/react-control.api.md packages/react-components/react-control/etc/react-control-preview.api.md +``` + +2. Update `README.md` + +```diff +-# @fluentui/react-control-preview ++# @fluentui/react-control +``` + +3. Update `package.json` + +```diff +{ +- "name": "@fluentui/react-control", ++ "name": "@fluentui/react-control-preview", +- "version": "9.0.0-alpha.0", ++ "version": "0.0.0", + "beachball": { + "disallowedChangeTypes": [ + "major", +- "minor", +- "patch", ++ "prerelease" + ] +}, +} +``` + +4. Update `project.json` + +```diff +{ +- "name": "@fluentui/react-control", ++ "name": "@fluentui/react-control-preview", +} +``` + +5. Update `jest.config.js` + +```diff +module.exports = { +- displayName: 'react-control', ++ displayName: 'react-control-preview', +} +``` + +6. Update `tsconfig.base.json` and `tsconfig.base.all.json` + +```diff +"paths": { +- "@fluentui/react-control": ["packages/react-components/react-control/src/index.ts"] ++ "@fluentui/react-control-preview": ["packages/react-components/react-control-preview/src/index.ts"] +} +``` + +7. Update `/github/CODEOWNERS` + +```diff +-packages/react-components/react-control @microsoft/ ++packages/react-components/react-control-preview @microsoft/ +``` + +8. now when ready to release follow [Unstable phase (first release)](#unstable-phase-first-release) + +
+ +#### package already released to npm as `9.0.0-(alpha|beta|rc).x`: + +> automation PR in progress https://github.com/microsoft/fluentui/pull/28481 + +# Dev Guide + +Following chapters describe required steps for each phase. All of them are generated so it's only a matter of invoking proper generator. + +> Following graph sums those steps as well https://github.com/microsoft/fluentui/blob/master/tools/workspace-plugin/src/generators/prepare-initial-release/README.md#v9-release-process-flow + +## 1. Kick-off phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28474 + +Bootstrap new package, via `yarn create-package` + +```sh +yarn create-package + +# triggers standard prompt + +? Package name (do NOT include @fluentui prefix): react-hello +``` + +This will do the usual scaffolding and adds `-preview` suffix to the package name automatically + +## 2. Preview phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28505 + +```sh +yarn nx g @fluentui/workspace-plugin:prepare-initial-release --project @fluentui/react-one-preview --phase=preview +``` + +## 3. Stable phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28505 + +```sh +yarn nx g @fluentui/workspace-plugin:prepare-initial-release --project @fluentui/react-one-preview --phase=stable +``` + +- TODO: deprecate all released `*-preview` package version on npm on CI during release diff --git a/docs/react-wiki-archive/nvm-setup.md b/docs/react-wiki-archive/nvm-setup.md new file mode 100644 index 0000000000000..641ad88e1ad1a --- /dev/null +++ b/docs/react-wiki-archive/nvm-setup.md @@ -0,0 +1,35 @@ +We recommend using `nvm` (Node Version Manager) to manage and switch Node versions. This is useful if you're developing in multiple repos and/or branches that have different Node version requirements. + +## Setup steps + +First, **uninstall your globally-installed version of Node**. + +The next steps vary by platform. + +### Windows + +1. Install [`nvm-windows`](https://github.com/coreybutler/nvm-windows) +2. Redo setup for normal development: + 1. Install the latest **LTS** Node version. Unfortunately with `nvm-windows` you must manually specify the full version number. + 1. Run `nvm list available` + 2. Take note of the newest version in the `LTS` column -- for demo purposes we'll call it `x.y.z` (you'll need to use the real version number instead) + 3. Install that version: `nvm install x.y.z` + 2. Reinstall yarn: `npm install -g yarn@1` + 3. Optional: reinstall any other npm packages you previously had globally installed +3. _(Only if developing on an old branch)_ Install an old Node version for legacy branch development: + 1. Find the full 10.x or 8.x version number to install. One way is to look at the version number in the filenames on [this page for 10.x](https://nodejs.org/download/release/latest-v10.x/) or [this page for 8.x](https://nodejs.org/download/release/latest-v8.x/). For demo purposes we'll call it `x.y.z` (you'll need to use the real version number instead). + 2. Install that version: `nvm install x.y.z` +4. To switch between the Node versions later, run `nvm use x.y.z` where `x.y.z` is the full version number. + - The selected version will remain the default until you select another version. + - If you forget which versions are installed, run `nvm list installed`. + +### Mac/Linux + +1. Install [`nvm`](https://github.com/nvm-sh/nvm) +2. Redo setup for normal development: + 1. Install the latest **LTS** Node version: `nvm install lts` (or `nvm install 14` if you prefer to stay on 14 for now) + 2. Set that version as your default: `nvm alias default lts` + 3. Reinstall yarn: `npm install -g yarn@1` + 4. Optional: Reinstall any other packages you previously had globally installed +3. _(Only if developing on an old branch)_ Install an old Node version for legacy branch development: either `nvm install 10` or `nvm install 8` +4. When working in the old branch, run `nvm use 10` (or `nvm use 8`) _each time you open a new terminal_ (or you can temporarily change the default by running `nvm alias default 10` then changing it back later) diff --git a/docs/react-wiki-archive/uifabric-migration.md b/docs/react-wiki-archive/uifabric-migration.md new file mode 100644 index 0000000000000..21667370e24a8 --- /dev/null +++ b/docs/react-wiki-archive/uifabric-migration.md @@ -0,0 +1,121 @@ +The `migration` package provides code modifications and notes in order to ease upgrades between fabric versions. **This package is only applicable when upgrading from `office-ui-fabric-react` 6 to 7.** + +Can be run with `npx` inside your project without being an explicit dependency. + +# Usage + +``` +Usage: + migration [-w] VERSION + +Options: + -h --help Display this message + -w --write Write changes directly to files +``` + +## Examples + +**Run in notify-only mode:** + +``` +$ npx @uifabric/migration@7.0.0 7 +``` + +_outputs:_ + +``` +Apply migration steps: +- warn ColorPicker-related onChanged props removed + +- warn ComboBox.onChanged removed + src/tsx/combocontrol.tsx:13:11 - onChanged is removed; please use onChange instead (NOTE: the arguments have changed from onChanged to onChange; please update accordingly) + +- remove use of deprecated ComboBox props + +- createRef should come from React.createRef, not from office-ui-fabric-react + src/tsx/combocontrol.tsx +- rename componentWillReceiveProps with UNSAFE_componentWillReceiveProps + src/tsx/file1.tsx +- warn SearchBox.onChange args changed + +- warn autobind decorator removed + +- Deprecated DetailsRowCheck.isSelected has been removed. Use DetailsRowCheck.selected instead. + +- warn Slider.ValuePosition removed + src/ts/file0.ts:4:9 - ValuePosition no longer available + src/ts/file0.ts:5:9 - ValuePosition no longer available +``` + +**Run in write mode:** + +**Important: Before running with `-w`, ensure all files are backed up or checked in to version control.** + +``` +$ npx @uifabric/migration@7.0.0 -w 7 +``` + +# Supported versions + +The migration package currently supports migrations to the following versions: + +## 7.0.0 + +### ColorPicker - onChanged props removed _(Notify only)_ + +`TODO` + +### ComboBox - onChanged removed _(Notify only)_ + +`TODO` + +### ComboBox - remove use of deprecated props + +`TODO` + +### DetailsRowCheck - isSelected has been removed. Use DetailsRowCheck.selected instead. + +`TODO` + +### React - createRef should come from React.createRef, not from office-ui-fabric-react + +React's implementation of `createRef` has improved to the degree where the office-ui-fabric-react version does not provide additional value. As a result, Fabric 7 no longer provides `createRef`. This migration will import `createRef` from `react` while removing it from `office-ui-fabric-react`'s import statements. + +### React - rename componentWillReceiveProps with UNSAFE_componentWillReceiveProps + +React is removing support for `componentWillReceiveProps` and will only be supporting the method as `UNSAFE_componentWillReceiveProps` in future versions (before removing support entirely). See https://reactjs.org/docs/react-component.html#the-component-lifecycle for more information. This migration renames all instances of this function in a codebase. + +### SearchBox - onChange args changed _(Notify only)_ + +`TODO` + +### Slider - ValuePosition removed _(Notify only)_ + +`TODO` + +### Util - autobind decorator removed _(Notify only)_ + +Fabric 6 and earlier versions shipped a decorator called `autobind`. Autobind takes a function definition and binds it to `this` on class instantiation, such that all calls to the method would have a predicable `this` value regardless of their invocation. + +In practice, a const lambda function provides the same guarantees of binding `this` without the need for annotation support, which is not on by default. + +In practice, these are the practical changes needed: + +```ts +class Foo { + private _val = 0; + + // using autobind - no longer supported directly by fabric + @autobind + bar(): void { + console.log(this._val); // this is always bound correctly + } + + // recommended + bar = (): void => { + console.log(this._val); // this is always bound correctly + }; +} +``` + +If stopping use of `@autobind` represents a large migration burden, consider implementing it in your own codebase or finding an implementation in a pre-existing package, as several exist.