# Docs & Arch
Author: [@Levi Thomason](@JZxLrdJcRC6aCO9R4VkcwA)

This file will turn into various public docs and contributor guidance.

# Customization asks
- Theming - tweak or replace
- State (not necessarily with props)
- A11y features (no hard coding props / key nav / etc)
- Render template

# Constraints to customization

- React tree needed to stay shallow
- Can't bloat component bundle with many props / deps
- When customzing components, allow customizing any aspect of the component (state, style, a11y, template)
- When customizing, the customized component should remain "a fluent" component: theme still works, all non-customized parts remain in tact

***

## Concepts

### Definitions

#### Slot
A location in a component's render template, such as an icon in a button or the text in a menu item.

#### Component
A named encapsulation of state, style, accessibility behavior, and anatomy intended to serve a specialized UI pattern.

#### The UI Problem™
The web platform does not have ready made components for building product applications, forcing every web product team to first build these missing components before building their product.

#### Product Component
The web has elements that were designed and intended to author text based documents. The web is now also a primary delivery platform for product applications. The web platform has never been updated to support the needs of these product applications. Think of any custom UI component you have had to develop for your product because there was not a suffient HTML element available. Fluent UI thinks of this class of UI components as distinct from HTML elemnts and "missing" in the web platform.

### Component Design Phliosophy
This is an explainer on Fluent UI thinks about and structures UI components.

<div class="why">
<h3>Problem statement</h3>

All patterns in Fluent UI were born from problem statements at Microsoft and the web at large. Microsoft's internal ecosystem is a minature representation of the larger web ecosystem. There are many organizations, products, and teams at Microsoft using a wide range of technologies to serve market needs. These technologies and products increasingly have the need to interop with each other as time goes on.

The web as a UI industry itself is made of many products built on various technologies as well. When any product team sets out to build a product, they first need to build a system to build [product components](#product-component). This separate design system, build system, and component library team is required since the web itself is lacking a system sufficient for building products. Product teams find themselves solving [The UI Problem™](#the-ui-problem) itself before they can tackle their product's market problem.

It is the identification of this gap in web technology (missing product components and design systems) that shapes Fluent UI's decisions in how components should be built. In the ideal web, any product team on the planet should be able to leverage an existing set of [product components](#product-component) to serve their market. They cannot, because that does not exist.

The core issue with [The UI Problem™](#the-ui-problem) is that one product is unable to use the components from another product. This is because the component authors did not create components with "platform thinking" and patterns, but hard-coded proprietary patterns.
</div>
<div class="why">
<h3>Solution Proposal</h3>
The solution to this problem is not to build another proprietary design system and component library, but it is to build the missing web platform components that products need.

In short, this means low-level APIs and customization. This should be obvious as product needs vary greatly. Think of the utility of the HTML div and span elements or CSS selectors. These technologies are sufficiently low level enough to support all web products.

Similarly, product components need to be comprised of sufficiently low-level APIs and patterns to be flexible enough to meet the needs of all common scenarios. Components, however, represent higher-level abtractions of these low-level APIs and must necessarily make many assumptions to be useful at this level.

The goal is to create these high-level abstractions (e.g. assumptions) from decomposable and reusable low-level APIs and patterns. This will allow the abstractions to be restructured for proprietary purposes with minimal work and maximum reuse of problem solving between product teams.

The restructuring of a component must not be overly complex for basic restructuring needs. The amount of work required to restructure a component should be proportional to the degree that the consumer wants to deviate from the UI pattern that the component is serving. Every layer that is restructured should keep in tact the problems that were solved in the next layer down. For instance, tweaking minimal state behavior of a component should not require rewriting the template or markup.

A "dropdown" that is "open" is encapsulating many complex concepts and patterns that are useful, however, it is critical that this abstraction can be decomposed if necessary to allow the consumer to re-compose the component in a modified way to suit their usecase. For example, changing the glyph used in a dropdown to represent open and closed states should require little work. Changing the focus model and narration for the items in the dropdown's menu should require more work. In both cases, the styling solutions provided by the component should not be invalidated.
</div>

### Composition

#### State

<div class="basic">
Declare what it is.
</div>
<div class="why">
Problem statement (customization)
</div>
<div class="why">
Solution (how is it customizable without being overbearing)
</div>

Button

<div class="why">
Conclusion
</div>

#### Style

Button

#### Accessibilty

Button

#### Template
- slots, link to deeper slots info

Button

### Render Templates

Fluent UI uses render templates to render components. A render template is a function that takes in component state and returns JSX.

[[
Image showing low fidelity version of state entering function and being used conditionaly to 1) create markup and 2) add props.
]]

Separating computation of component state from the construction of the JSX markup is critical ini Fluent UI for two reasons:
1) It allows you to intercept and update a component's state without needing to rewrite the markup.
2) Conversely, it also allows you to make changes to the structure of a component while taking full advantage of reusing computed state.

1. Allows you to make changes to the state of a comp

### Component Slots

Shorthand slots

#### Passing content to slots

#### Adding props to slots

#### Replacing a slot component

#### Replacing an entire slot

#### Replacing the entire render template

***

### Component Boundaries
Explain layer alignment for determining new components

Props vs new components