Add more docs to docsite (#25)

* Add internal docs to docsite

* Update overview doc title

* Update title tags

* Updating case for filename

* Fix parsing errors in the docs

* Fix parsing errors

* Fix parsing errors

* Include release log in docs

---------

Co-authored-by: Atishay Jain (from Dev Box) <[email protected]>

apps/docsite/docusaurus.config.ts

@@ -123,7 +123,7 @@ const config: Config = {
           ],
         },
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} FluentUI React Charting. Built with Docusaurus.`,
+      copyright: `Copyright © ${new Date().getFullYear()} Microsoft`,
     },
     prism: {
       theme: prismThemes.github,

apps/docsite/sidebars.ts

@@ -17,11 +17,18 @@ const sidebars: SidebarsConfig = {
   // But you can create a sidebar manually
 
   tutorialSidebar: [
-    'Fluent-React-Charting',
-    'TechnicalDetails',
+    'Overview',
+    'CHANGELOG',
+    'Start Developing',
+    'Contributor Guide',
+    'Technical Details',
+    'Detailed Implementation Steps',
+    'Debugging',
+    'Implementation Best Practices',
+    'Accessibility',
     'colors',
     'implementing-2-to-1-spacing',
-    'TestingStrategy',
+    'Testing Strategy',
     {
       type:'category',
       label:'Test Plans',
@@ -31,7 +38,8 @@ const sidebars: SidebarsConfig = {
           dirName:'Test Plans',
         }
       ]
-    }
+    },
+    'Testing Unpublished Library Version',
   ],
 
 };

docs/Accessibility.md

@@ -0,0 +1,18 @@
+The react charting library is accessibility MAS C compliant.
+We satisfy accessibility requirements for the following aspects (and more).
+
+- Screen readers and narrators in different browser modes.
+- 400% browser zoom.
+- Color contrast ratios.
+- Keyboard navigation.
+- Voice access.
+- Supporting high contrast mode.
+- Focusable elements
+- ... and more
+
+Browser modes:
+Focus mode
+
+All the colors in our palette meet accessibility requirements. 
+- They satisfy 4.5:1 contrast ratio with the background.
+- They also meet the 3:1 contrast ratio wrt each other.

docs/Contributor Guide.md

@@ -0,0 +1,45 @@
+Fluent charting library is a collection of individual charts like LineChart, AreaChart, Horizontal bar chart, vertical bar chart.
+Charting components are built as production-ready, generalized, documented, and reusable components to be used in Microsoft products. This enables us and our partners to easily build great applications without spending a ton of time implementing the same controls over and over.
+Each component is designed to be RTL-friendly, keyboard accessible, screen reader-friendly, themable, and generalized. TypeScript definition files are also included, so if you use TypeScript (which isn't a requirement), you will get compiler validation and using an editor like VS Code, you'll get intellisense. Each component is exported as a named module that can be easily imported in your code, allowing your external bundler to create small bundles that include just what you need.
+
+**Contribution process**
+We invite members of the community to actively participate in any way - code, documentation, design, publicity, moderation, analytics, explorations, dicussions and more.
+
+Before proceeding into details, we would like to set some contractual guidelines with our contributor community.
+
+**Commitments from the maintaining team** [(charting-team)](https://github.com/orgs/microsoft/teams/charting-team)
+- Responding to queries within a day.
+- Responding to PRs within 2 business days.
+- Publishing day to day design discussions, decisions taken, roadmaps, backlogs and current sprint board. 
+
+**Expectations from contributors**
+**For Issues:**
+Follow the [issue template](https://github.com/microsoft/fluentui/issues/new/choose) to report bugs and feature requests.
+For internal product requests that can contain confidential information, report issues to our internal ADO [here](https://uifabric.visualstudio.com/iss/_workitems/create/User%20Story?templateId=c0a6b2f0-ecaf-4f0e-83a6-a3ea43f30847&ownerId=0c0ad9a8-059c-4697-a4b6-ff1179ca8699).
+Make sure to specify the current and expected behavior along with repro steps so that our team can take appropriate action to the request.
+
+**For Pull Requests:**
+_During planning of the implementation:_
+- Go through the documentation and design decisions for the respective component.
+- Any design and/or behavior changes should be reviewed by the charting core team to validate its consistency, generalization, and visual design alignment with the rest of the charts.
+- If the change is major, the dev design should be reviewed by the charting core team to ensure the changes are aligned to the overall design of the library and does not cause any unexpected behavior.
+
+_After implementation_
+- Follow [Testing Strategy](Testing Strategy.md) to ensure all the changes are tested and relevant scenarios are automated.
+- Test for relevant accessibility scenarios. Refer [Accessibility Guide](Accessibility.md) for more details.
+- The contributor needs to provide a 30 day support to fix any bug arising due to their change. 
+
+**Checklist for a partner feature contribution.**
+- [ ]	Clearly mention the usecase and a video of the functionality that you have implemented.
+- [ ]	Test Plan Item created and corresponding test passed.
+- [ ] Add examples on our demo site for new scenarios. 
+- [ ]	Test for keyboard accessibility
+- [ ]	Test for screen reader accessibility
+- [ ]	Works with light theme, dark theme and high contrast theme.
+- [ ]	Release notes updated with appropriate details.
+- [ ]	30 day support for user reported or accessibility bugs in your feature area.
+- [ ] Works with RTL languages
+
+**Measuring the impact of your contribution**
+The charting team is working to define datapoints to measure the usage of different charts and their functionalities. We will soon publish metrics with quantitative impact of your contribution across the organization.
+

docs/Debugging.md

@@ -0,0 +1,15 @@
+The chart components can be debugged using few techniques.
+
+1. Using browser developer tools.
+    1. Open developer tools (Pressing `F12`).
+    2. Go to sources tab and open search bar (Pressing `Ctrl + Shift + F`).
+    3. Search for the component name and open the sources file from the search results.
+    4. Apply breakpoints and run the scenario to see the breakpoints getting hit.
+
+2. Add console logs with the variables that you want to test. (Make sure to remove these logs while commiting your changes.)
+3. Add a `debugger` statement wherever you want to debug. Open dev tools and run the scenario. The execution will pause once the debugger statement is hit. (Make sure to remove these logs while commiting your changes.)
+4. Debugging using test cases
+    1. Open visual studio code from fluent ui root folder. (Not from `packages\react-charting`)
+    2. Check whether the `Debug current open test` debug option is visible under the run and debug tab.
+    3. Add breakpoints to the relevant test case and start debugging using `Debug current open test` option.
+    Note that this option renders the components under a headless browser. So some actual rendering dependent functions like `getBoundingClientRect` will not work and will need to be mocked.

docs/Detailed Implementation Steps.md

@@ -0,0 +1,60 @@
+If you are planning to contribute a major chart, follow the below steps to align the component with fluent charting design, principles, style and standards.
+
+**Step 1:**
+**_Background research._**
+Is there any existing work that has already happened (either on the dev side or on the design side) or in the backlog. Any planned feature can be found in our roadmap [here](https://github.com/orgs/microsoft/projects/792/views/1) along with high level timelines and current status. Also look for any discussions about the feature in our discord channel.
+If the ask is net new, setup sometime with the charting team. This will help determine the next steps to proceed with designing the control as per fluent charting framework. 
+
+**Step 2:**
+**_Visual design._**
+The design figma should cover specification about the following aspects before the control can be implemented.
+1. **Anatomy:** Describe the components of the chart and how each of them will look.
+2. **Possible sizes:** The control can be supported in different sizes like S, M, L XL. 
+3. **Variations:** The control can have multiple variations for different use cases.
+4. **Handling large dataset or data labels.**
+5. **Theming:** How will the chart look in light mode and dark mode. What about high contrast mode.
+6. **Colors:** What is the supported color palette by this chart. It should either use the default [color palette](colors.md) of react charting or a subset of it.
+7. **Interactive behavior:** Define how the user can interact with points and other visuals in the chart. For eg: hover card when a user hovers over a chart area, selecting particular legend.
+8. **Accessibility:** The charting library is currently MAS C compliant. The chart should meet [accessibility](Accessibility.md) standards to ensure this grade.
+9. **RTL support:** The library supports [RTL](https://en.wikipedia.org/wiki/Right-to-left_script) scripts. Do we need any special design to support them.
+
+Refer to [this](https://www.figma.com/file/oNWKEgIOCSLElvMZPOVMCq/Fluent-Data-Viz-(WIP)?node-id=1776-205538&t=77LXR8DHndlgs3ap-0) figma to see an example.
+
+**Step 3:**
+**_Dev Design._**
+Once the visual design is finalized, prepare a dev design document. You can look at design docs of other charts for reference. [[Example](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/src/components/TreeChart/TreeChart.md)]
+Try to include the following sections in the design document.
+1. External interfaces
+2. Props
+3. React lifecycle state management.
+4. Data structure to store and process the data.
+5. Handling large data sets.
+6. Rerendering and recomputations on user interactions.
+7. Reusable components.
+8. Unit testable and component testable pieces.
+9. Mapping geometrical logic to visual graph.
+10. Limitations.
+11. Alternative design considerations.
+12. Accessibility considerations
+
+These design collaterals will be added to this contributor guide for future references.
+
+**Step 4.**
+**_POC._** - This step will overlap with step 2. This will help understand and align with overall design of fluent charting library.
+The charting team will be more than happy to participate in design discussions to iterate over step 2 and 3.
+Once done get a formal review from the charting team and address any feedbacks.
+
+**Step 5:**
+**_Implementation._**
+
+
+**Step 6:**
+_**Pilot with a customer as an unstable component.**_
+The rollout starts by piloting with a partner assuming the component to have some bugs. 
+This phase includes fixing these bugs and correcting any external interfaces.
+
+**Step 7:**
+**_Stable release._**
+Once the component has been released as stable, it can no longer have any breaking changes before the next major release of the library.
+
+If the proposed changes are bugfixes, minor enhancements or extension then steps 1-4, 5 and 6 can be brief or skipped. But make sure to capture any relevant information in PR description or supporting documents.

docs/Implementation Best Practices.md

@@ -0,0 +1,73 @@
+## 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 => `<button>`) and you intersect `React.HTMLAttributes<>`, avoid re-declaring those attributes within your component props. Doing so can lead to type mismatch problems.
+
+Avoid names that are commonly used in other HTML elements or attributes. They won't cause a compile or runtime error, but they may be confusing to callers.
+
+### Use discriminated union over boolean for mutually exclusive props
+
+Boolean properties are convenient to set in TSX and are appropriate for flag values.
+
+For example, a Tooltip component may have an option to show an arrow pointing at the target. `withArrow: boolean`. Callers can easily set this in TSX `<Tooltip withArrow />`.
+
+If there are properties that are mutually exclusive, then a discriminated union is a better choice. The caller cannot accidentally specify multiple values which could lead to unpredictable behavior.
+
+Going back to the Tooltip component, it might have different options for position relative to the target. If these were boolean values like `before?: boolean`, `after?: boolean`, or `cover?: boolean`, the caller could write `<Tooltip before after cover />`. It is much clearer to specify `<Tooltip position="before" />`.
+
+### Consider a discriminated union for future additional
+
+If you have only a single optional value today and think there could be multiple values in the future, prefer a discriminated union with one value. For example: `border: boolean` would have to be changed to a discriminated union later to support both square, rounded, and circular borders.
+
+### Prefer to inline small & independent discriminated unions
+
+When a property type is a discriminated union, it is tempting to declare and export a type for it.
+
+For example a size, `'small' | 'medium' | 'large'` would be easy to define as `export type Size = 'small' | 'medium' | 'large'` and declare `size: Size;`.
+
+There are few pitfalls with defining and exporting types for every discriminated union:
+
+- Tightly bound cross-component dependencies.
+
+  If a component A uses the Size type from component B and then component B adds a value to the union, it could break component A. Component A is also less portable.
+
+- Extra F12 navigation
+
+  Developers inspecting the props have to follow the union to understand it rather than seeing the union right next to the property. This can lead to duplicate documentation comments on property and type declarations.
+
+- Type explosion/collision in the type declaration files (`.d.ts`).
+
+  While types are compiled away, having many types used only in one place increases declaration file size without much benefit.
+
+  Component authors have to be careful to distinguish their type from other component types (e.g. ButtonSize vs. ImageSize). Otherwise tooling might auto-import the incorrect type.
+
+  Since the practice is to place types in separate `.types.ts` files, these get exported for the component to use and can be inadvertently exported by `index.ts` `export * from ...`
+
+There are scenarios when you should consider defining a type for a discriminated union:
+
+- It is used across multiple components within the same package, or multiple times in the same props declaration.
+- There are many union values that it clutters the props declaration.
+- The type is a union of unions (e.g. `color: 'brand' | 'neutral' | StatusColor`)
+- Callers will need to use the type in TS/JS rather than in just TSX/JSX.
+- Developers authoring variants of your component will need that type in their component props.

docs/Overview.md

@@ -0,0 +1,25 @@
+---
+title: Overview
+---
+Fluent UI React (formerly Office UI Fabric React) charts is a set of modern, accessible, interactive, lightweight and highly customizable visualization library representing the Microsoft design system. The charts are used across 100+ projects inside Microsoft including Microsoft 365 and Azure.
+
+The library is built using D3 (Data Driven Documents) and other fluent UI controls.
+
+## Contact
+
+The charting project is actively funded by a small feature team. The team responds within 1-2 business days for any queries or doubts.
+You can reach out to the charting team by tagging `@microsoft/charting-team` in [discussion](https://github.com/microsoft/fluentui/discussions) items.
+
+You could also create issues under the [charting](https://github.com/microsoft/fluentui/labels/Package:%20charting) tag.
+
+## Demo site
+https://aka.ms/fluentcharting
+
+## Code repository
+https://github.com/microsoft/fluentui/blob/master/packages/react-charting
+
+## DataViz design guidelines
+Coming soon
+
+## Published roadmap
+https://github.com/orgs/microsoft/projects/792/views/1