@theroutingcompany/components 0.0.13 → 0.0.14

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 is a styled component 'extending' the base component: ` const PrimaryButton = styled(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)``  `
 
 - 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,43 +29,42 @@ 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 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](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
 
 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
 >
@@ -77,43 +76,37 @@ 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
 
-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.
+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.
@@ -132,12 +125,13 @@ 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>
-<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>
+> 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>
@@ -154,52 +148,47 @@ 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>
-<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>
+> 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>
@@ -210,7 +199,7 @@ For example, Radix adds events handlers to buttons inside a `*Trigger` component
 This is very important for components based on RadixUI and react-aria to work correctly.
 
 <figure>
-<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>
+> 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>
@@ -229,10 +218,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:
@@ -252,6 +241,7 @@ 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`.
 
@@ -261,12 +251,8 @@ 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>
-<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>
+> 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>
@@ -275,15 +261,16 @@ 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
 
@@ -292,27 +279,34 @@ 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)
 
-## Misc Reading
+## 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)
-- [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/)
+- [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/)
+
 - [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/)