@theroutingcompany/components 0.0.11 → 0.0.13

package/README.md

@@ -20,7 +20,7 @@ Styling is done with [styled-components](https://styled-components.com/), a CSS-
 The approach is roughly:
 
 1. A "base" styled component with shared styles: `ButtonBase`
-2. Each variant in the [Figma designs](https://www.figma.com/file/xfnqeuF8FgoqhJSUs5GTsK/PDS-Components-Desktop?node-id=16%3A7&t=22cWETfRERKj9wkP-0) is a styled component 'extending' the base component: ` const PrimaryButton = styled(ButtonBase)``  `
+2. Each variant in the Figma designs is a styled component 'extending' the base component: ` const PrimaryButton = styled(ButtonBase)``   `
 
 - 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
@@ -29,42 +29,43 @@ The approach is roughly:
 
 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!
+- 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 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
 
 Partly inspired by these
 
-* [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)
+- [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)
 
 ### Start Simple
 
 Or the “Principle of Least Power”.
 
-For example, don’t start building a table component that covers many use-cases. Instead start with just the reusable parts of the table that can be shared between many use-cases.
+For example, don’t start building a table component that covers many use-cases. Instead, start with just the reusable parts of the table that can be shared between many use-cases.
 
 ### For content, prefer composition over props
 
-  - ❌ `<Text variant="body" text="Some text" />`
-  - ✅ `<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
+### 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"
+  title='Header'
+  description='Optional description'
+  cancelButtonText='Close'
   onCancel={() => {}}
-  confirmButtonText="Delete"
-  confirmButtonVariant="primary"
+  confirmButtonText='Delete'
+  confirmButtonVariant='primary'
   onDelete={() => {}}
   // ... and so on
 >
@@ -76,37 +77,43 @@ Similar to last point. Compound components scale better.
 ```
 
 ✅
+
 ```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>
+<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.
+Compound components are components that <q cite="https://kentcdodds.com/blog/compound-components-with-react-hooks">components that work together to accomplish a useful task</q>.
+Radix makes extensive use of compound components.
+
+Also 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.
+
+The context should only be consumed within the library component and not exported.
 
 <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.
@@ -125,13 +132,12 @@ 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>..
-
+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.
+<blockquote> 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.</blockquote>
 <figcaption>
   <cite>
     <a href="https://www.jonambas.com/posts/component-api-standards">React Component API Standards — Native Attributes</a>
@@ -148,47 +154,52 @@ It is unfortunate that react-aria breaks with this principle. Therefore we have
 
 Using design tokens consistently will make it easier to change values at scale in the future.
 
-- ❌  `color: black;`
-- ✅  `color: ${tokens.color_black};`
+- ❌ `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};`
+- ❌ `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%);`
+- ❌ `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);`
+- ❌ `color: hsla(217deg, 90%, 61%, 0.8);`
+- ✅ `color: hsl(217deg 90% 61% / 0.8);`
 
 Some reading material on this:
 
-* [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/)
+- [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/)
 
 ## 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?).
 
+Use CSS variables for the dynamic parts in styled-components using. 
+
 See [The styled-components Happy Path](https://www.joshwcomeau.com/css/styled-components/)
 
+### Merge props
+
+Use the [`mergeProps`](https://react-spectrum.adobe.com/react-aria/mergeProps.html) function from `@react-aria/util` to merge props correctly.
+For example, Radix adds events handlers to buttons inside a `*Trigger` components with an `asChild` prop, `mergeProps` ensures there are chained instead of overwritten which enables functionality to be composed.
+
 ### 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/>`.
+<blockquote>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/>`.</blockquote>
 <figcaption>
   <cite>
     <a href="https://www.jonambas.com/posts/component-api-standards">React Component API Standards — Refs</a>
@@ -199,7 +210,7 @@ See [The styled-components Happy Path](https://www.joshwcomeau.com/css/styled-co
 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.
+<blockquote>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.</blockquote>
 <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>
@@ -218,10 +229,10 @@ 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)). 
+- ❌ `[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:
@@ -241,7 +252,6 @@ There are also a few react-aria hooks to handle these interaction state ([useFoc
 > **Warning**
 > Unfinished
 
-
 Only write TypeScript files.
 The linting config is also quite strict with `@typescript-eslint`.
 
@@ -251,8 +261,12 @@ Correct component types make it easier to use components without having to look
 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.
+<blockquote>
+  <ul>
+    <li>Avoid “stringly typed” code. Prefer more appropriate types where not every string is a possibility.</li>
+    <li>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.</li>
+  </ul>
+</blockquote>
 <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>
@@ -261,16 +275,15 @@ Exact types for props (for editor autocomplete) is a necessity, not a nice-to-ha
 </figure>
 </figure>
 
-
-- ❌  `type Variant = string;`
-- ✅  `type Variant = 'primary' | 'secondary' | 'danger' | 'inverse';`
+- ❌ `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! 
+> 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). 
+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
 
@@ -279,34 +292,27 @@ Two ways we can solve this
 
 > 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
 
 - [the component gallery](https://component.gallery/) "Designed to be a reference for anyone building component-based user interfaces, The Component Gallery is an up-to-date repository of interface components based on examples from the world of design systems."
 - [Storybook showcase](https://storybook.js.org/showcase)
+- [Shopify Polaris](https://polaris.shopify.com/)
 - [Primer: React implementation of GitHub's Primer Design System](https://primer.style/react/)
 - [Paste: The Design System for building Twilio customer experiences](https://paste.twilio.design/)
 - [Spectrum: Adobe’s design system.](https://react-spectrum.adobe.com/react-spectrum/)
 - [Evergreen: Segment’s design system](https://evergreen.segment.com/)
 - [awesome-react-design-systems](https://github.com/jbranchaud/awesome-react-design-systems)
 
-## Reading
+## Misc Reading
 
 - [The styled-components Happy Path](https://www.joshwcomeau.com/css/styled-components/)
+- [Demystifying styled-components](https://www.joshwcomeau.com/react/demystifying-styled-components/)
 - [CSS Variables for React Devs](https://www.joshwcomeau.com/css/css-variables-for-react-devs/)
-
 - [You Don’t Need A UI Framework](https://www.smashingmagazine.com/2022/05/you-dont-need-ui-framework/)
-
-###
-
 - [Vadim Demedes Design system tips](https://twitter.com/i/events/1577907596966641665)
-- [https://www.robinrendle.com/notes/the-difference-between-correct-ness-and-useful-ness-in-a-design-system/](https://www.robinrendle.com/notes/the-difference-between-correct-ness-and-useful-ness-in-a-design-system/)
-
+- [The difference between correct-ness and useful-ness in a design system/](https://www.robinrendle.com/notes/the-difference-between-correct-ness-and-useful-ness-in-a-design-system/)
 - [Apple Developer: Layout - Foundations - Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/foundations/layout/)
 
-
-
 #### TypeScript
 
 - [TypeScript + React: Typing Generic forwardRefs](https://fettblog.eu/typescript-react-generic-forward-refs/)