@theroutingcompany/components 0.0.8 → 0.0.10

package/README.md

@@ -1,5 +1,7 @@
 # TRC TREX Component Library
 
+View the [StoryBook](https://6392297e45ccab79e466ee19-iytnzjepcr.chromatic.com/).
+
 ## UI Libraries
 
 The component library is built on the following 'component primitives' UI libraries, low-level unstyled building blocks.
@@ -23,18 +25,255 @@ The approach is roughly:
 - All variant are placed in an object (a map but not a `Map()`)
 - The exported takes a `variant` prop and uses it to get the right styled component from the object map
 
+## Missing
+
+This component library is very much a work in progress and has many gaps.
+
+* A component that exposes the spacing design tokens in an easy-to-use, type-safe way. Usually this is called `Box`.
+* Far from all components in the [Components Figma](https://www.figma.com/file/xfnqeuF8FgoqhJSUs5GTsK/PDS-Components-Desktop) have been implemented
+* For existing component, we need more documentation. Often, design systems include a "Guidelines" or "When to Use" section" on the component doc page.
+* Tests!
+
 ## Guiding Principles
 
-https://www.gabe.pizza/notes-on-component-libraries/
+Partly inspired by these
 
-- For content, prefer composition over props
+* [Notes on maintaining an internal React component library](https://www.gabe.pizza/notes-on-component-libraries/)
+* [Component API Standards](https://jonambas.com/posts/component-api-standards)
+
+### For content, prefer composition over props
 
-  - ✅ `<Text variant="body">Some text</Text>`
   - ❌ `<Text variant="body" text="Some text" />`
+  - ✅ `<Text variant="body">Some text</Text>`
+
+### Prefer `compound components` over one large component with many props
+
+Similar to last point. Compound components scale better.
+
+❌ 
+```jsx
+<AlertDialog
+  title="Header"
+  description="Optional description"
+  cancelButtonText="Close"
+  onCancel={() => {}}
+  confirmButtonText="Delete"
+  confirmButtonVariant="primary"
+  onDelete={() => {}}
+  // ... and so on
+>
+  <Text type='body'>
+    Powering the next generation of transit We help build more sustainable
+    cities with convenient and reliable transit for all
+  </Text>
+</AlertDialog>
+```
+
+✅
+```jsx
+  <AlertDialog>
+    <AlertDialogTrigger asChild>
+      <Button>Open dialog</Button>
+    </AlertDialogTrigger>
+    <AlertDialogContent size={size}>
+      <AlertDialogTitle>Header</AlertDialogTitle>
+      <AlertDialogDescription>Optional description</AlertDialogDescription>
+      <Text type='body'>
+        Powering the next generation of transit We help build more sustainable
+        cities with convenient and reliable transit for all
+      </Text>
+      <AlertDialogFooter>
+        <AlertDialogCancel asChild>
+          <Button size='large' variant='primary' emphasis='medium'>
+            Close
+          </Button>
+        </AlertDialogCancel>
+        <AlertDialogAction asChild>
+          <Button size='large' variant='danger'>
+            Delete
+          </Button>
+        </AlertDialogAction>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+```
+
+### Prefer React Context for components that depend on each other
+
+See [Most of the time, it’s a good idea to use React context for components that depend on each other.](https://www.gabe.pizza/notes-on-component-libraries/#most-of-the-time-its-a-good-idea-to-use-react-context-for-components-that-depend-on-each-other) for an example. This is also how Radix does it.
+
+<figure>
+> [T]he context should be kept internal to the library. Allowing the naked context to be imported and handled by applications creates a brittle coupling that will easily break in future upgrades.
+<figcaption>
+  <cite>
+    <a href="https://www.gabe.pizza/notes-on-component-libraries/#most-of-the-time-its-a-good-idea-to-use-react-context-for-components-that-depend-on-each-other">Notes on maintaining an internal React component library
+ — Most of the time, it’s a good idea to use React context for components that depend on each other.</a>
+  </cite> 
+</figcaption>
+</figure>
+
+### Avoid the `React.Children` API and `React.cloneElement`, prefer React Context
+
+Avoid the Children API and `cloneElement`.
+
+The Children API is a <q>leaky abstraction</q> and in [maintenance mode](https://github.com/reactjs/rfcs/pull/61#issuecomment-431247764).
+<small>At the moment it's only used in the breadcrumbs component.</small>
+
+The [React docs](https://beta.reactjs.org/reference/react/cloneElement#cloneelement) discourages the use of `cloneElement` because <q cite="https://beta.reactjs.org/reference/react/cloneElement#cloneelement">Cloning children makes it hard to tell how the data flows through your app.</q> and <q cite="https://beta.reactjs.org/reference/react/cloneElement#cloneelement">Using cloneElement is uncommon and can lead to fragile code</q>..
+
+
+### Don't rename HTML attributes
+
+<figure>
+> Native attributes or common props, such as `className`, `id` or `onClick`, should not be renamed. Don't force your engineers to learn APIs they already know.
+<figcaption>
+  <cite>
+    <a href="https://www.jonambas.com/posts/component-api-standards">React Component API Standards — Native Attributes</a>
+  </cite> 
+</figcaption>
+</figure>
+
+- ❌ `<TextInput isDisabled />`
+- ✅ `<TextInput disabled />`
+
+It is unfortunate that react-aria breaks with this principle. Therefore we have to rename boolean props before passing them to react-aria's hooks, usually prefix them with `is-`, and the reverse, remove the prefixes from the types.
+
+### Use design tokens where possible
+
+Using design tokens consistently will make it easier to change values at scale in the future.
+
+- ❌  `color: black;`
+- ✅  `color: ${tokens.color_black};`
+
+## Prefer meaningful tokens
+
+For example, if we ever decide to implement dark mode, meaningfully-named tokens will make this switch easier.
+
+- ❌  `color: ${tokens.color_black};`
+- ✅  `color: ${tokens.tokens.color_text_strong};`
+
+### Use HSL colors
+
+[HSL notation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl) is more readable and more intuitive. Prefer it over other color notations like hex codes or `rgb()`
+
+- ❌  `color: #4287f5;`
+- ❌  `color: rgb(66, 135, 245);`
+- ✅  `color: hsl(217deg 90% 61%);`
+
+Prefer modern [`hsl()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl) over `hsla()`. `hsla` is legacy syntax. Add the alpha channel at the end after a `/`.
+
+- ❌  `color: hsla(217deg, 90%, 61%, 0.8);`
+- ✅  `color: hsl(217deg 90% 61% / 0.8);`
+
+Some reading material on this:
 
-- Don't rename
+* [Why you should use HSL over other colour formats in your CSS.](https://sujansundareswaran.com/blog/why-hsl-is-better-than-hex-and-rgb)
+* [Using HSL Colors In CSS](https://www.smashingmagazine.com/2021/07/hsl-colors-css/)
 
-TODO Expand
+## Style variants
+
+Style styled-components usingg CSS variables defined in the component.
+
+> **Warning**
+> This is not settled and this pattern is not followed consistently (yet?).
+
+See [The styled-components Happy Path](https://www.joshwcomeau.com/css/styled-components/)
+
+### Forward refs
+
+<figure>
+> Refs should always be forwarded, either to the outermost DOM element, or to the most applicable element of the component. For example form components should forward refs to `<input/>`.
+<figcaption>
+  <cite>
+    <a href="https://www.jonambas.com/posts/component-api-standards">React Component API Standards — Refs</a>
+  </cite> 
+</figcaption>
+</figure>
+
+This is very important for components based on RadixUI and react-aria to work correctly.
+
+<figure>
+> All component parts that render a DOM element have an `asChild` prop. This is useful when you want a part to attach its accessibility and functional requirements onto your own element instead.
+<figcaption>
+  <cite>
+    <a href="https://www.radix-ui.com/docs/primitives/overview/styling#changing-the-rendered-element">React Component API Standards — Changing the rendered element</a>
+  </cite> 
+</figcaption>
+</figure>
+
+For components based on react-aria that require a DOM ref, use `useObjectRef` hook from `@react-aria/utils` with the forwarded ref. See PR [Add a useObjectRef util](https://github.com/adobe/react-spectrum/pull/2293)
+
+### Prefer attribute selectors to style component states
+
+Don't add classNames to style a component in a certain state (eg invalid, selected, disabled), use attribute selectors instead. Use `aria-` or custom `data-` attributes to add styles for states.
+
+Prefer `~=` over `=`. `~=` matches <q cite="https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors#syntax">whitespace-separated list of words, one of which is exactly value</q>, whereas `=` matches an <q>attr whose value is exactly value</q>.
+For compound states, e.g `date-state='selected on'` the latter will not work.
+
+(I like to think of it like `[...strings.split(" ")].includes(value)`. vs `strings === value`)
+
+- ❌  `[data-state='selected']`.
+- ✅  `[data-state~='selected']`
+ 
+Radix adds a custom attribute with the state automatically. The attribute names and values are listed on each component's doc page ([example](https://www.radix-ui.com/docs/primitives/components/toggle#root)). 
+For component built on react-aria, we need to add `data-` attribute ourselves.
+
+Recommended reads:
+
+- [Building a Button Part 1: Press Events](https://react-spectrum.adobe.com/blog/building-a-button-part-1.html)
+- [Building a Button Part 2: Hover Interactions](https://react-spectrum.adobe.com/blog/building-a-button-part-2.html)
+- [Building a Button Part 3: Keyboard Focus Behavior](https://react-spectrum.adobe.com/blog/building-a-button-part-3.html)
+
+### Prefer `:focus-visible` over `:focus`
+
+Focus state styles should only be shown on keyboard interactions. Basically [`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) is a smarter pseudo-selector that only shows the focus states with (not totally sure about that).
+
+There are also a few react-aria hooks to handle these interaction state ([useFocus](https://react-spectrum.adobe.com/react-aria/useFocus.html), [useHover](https://react-spectrum.adobe.com/react-aria/useHover.html)), it's not totally clear to me yet what the benefit of these hooks are over plain CSS pseudo-selectors.
+
+### TypeScript only
+
+> **Warning**
+> Unfinished
+
+
+Only write TypeScript files.
+The linting config is also quite strict with `@typescript-eslint`.
+
+### Types of component props should be strong
+
+Correct component types make it easier to use components without having to look at the source or example.
+Exact types for props (for editor autocomplete) is a necessity, not a nice-to-have. Be as detailed as possible.
+
+<figure>
+> Avoid “stringly typed” code. Prefer more appropriate types where not every string is a possibility.
+> Prefer a union of string literal types to string if that more accurately describes the domain of a variable. You’ll get stricter type checking and improve the development experience.
+<figcaption>
+  <cite>
+    <a href="https://www.oreilly.com/library/view/effective-typescript/9781492053736/ch04.html#avoid-strings">Effective TypeScript - Prefer More Precise Alternatives to String Types</a>
+  </cite> 
+</figcaption>
+</figure>
+</figure>
+
+
+- ❌  `type Variant = string;`
+- ✅  `type Variant = 'primary' | 'secondary' | 'danger' | 'inverse';`
+
+### Avoid spreads on native JSX elements
+
+> **Warning**
+> This is a principle we don't currently abide by but should! 
+
+See [Avoiding JSX spread on foreign data prevents weird bugs sometimes.](https://www.gabe.pizza/notes-on-component-libraries/#avoiding-jsx-spread-on-foreign-data-prevents-weird-bugs-sometimes). 
+
+Two ways we can solve this
+
+1. Filter spread props. Reject all non-DOM props using a utility. Note react-aria has a util names `filterDOMProps` despite its name it does not filter DOM props (I think it's a legacy util).
+2. Be more explicit. Write out all the props to forward and types explicitly.
+
+> I recommend, whenever possible, to destructure the props object and forward keys as needed. Breaking the props down removes excessive keys, allows setting defaults, and makes grepping the code easier.
+
+One downside I see the #2 is that 
 
 ## Examples
 
@@ -60,8 +299,7 @@ TODO Expand
 
 - [Apple Developer: Layout - Foundations - Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/foundations/layout/)
 
-- https://jonambas.com/posts/lessons-learned
-- [https://jonambas.com/posts/component-api-standards](https://jonambas.com/posts/component-api-standards)
+
 
 #### TypeScript