@theroutingcompany/components 0.0.25 → 0.0.26-alpha.1

package/README.md

@@ -12,8 +12,8 @@ First double check if everything that needs to exported is added to the `compone
 
 ### Public
 
- - Login to NPM with the shared TREX 1pass creds.
- - Execute the ./scripts/release.sh file.
+- Login to NPM with the shared TREX 1pass creds.
+- Execute the ./scripts/release.sh file.
 
 ```
 npm run ready:release
@@ -21,8 +21,8 @@ npm run ready:release
 
 ### Prerelease
 
- - Login to NPM with the shared TREX 1pass creds.
- - Execute the ./scripts/prerelease.sh file.
+- Login to NPM with the shared TREX 1pass creds.
+- Execute the ./scripts/prerelease.sh file.
 
 ```
 npm run ready:prerelease
@@ -43,29 +43,6 @@ It may seem weird at first sight that two component libraries are used but they
 
 Styling is done with [styled-components](https://styled-components.com/), a CSS-in-JS library.
 
-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)`
-
-- 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.
-
-- 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)
-
 ### Start Simple
 
 Or the “Principle of Least Power”.
@@ -106,7 +83,7 @@ Similar to last point. Compound components scale better.
 ```jsx
 <AlertDialog>
   <AlertDialogTrigger asChild>
-    <Button>Open dialog</Button>
+    <Button size='small'>Open dialog</Button>
   </AlertDialogTrigger>
   <AlertDialogContent size={size}>
     <AlertDialogTitle>Header</AlertDialogTitle>
@@ -130,260 +107,3 @@ Similar to last point. Compound components scale better.
   </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.
-
-<figure>
-<blockquote>
-[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.
-</blockquote>
-<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>
-<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>
-  </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:
-
-- [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/)
-
-## Avoid adding margins by default to components
-
-Avoid “leaky margins”. When possible, prefer a flex or grid container to space child items.
-
-There are exceptions, eg a header or footer that is expected to always have some room below or above it.
-
-<figure>
-<blockquote>The trouble with confining styles to objects is that not everything should be considered a property of an object per se. Take margins: margins are something that exist between elements. Simply giving an element a top margin makes no sense, no matter how few or how many times you do it. <em>It’s like applying glue to one side of an object before you’ve determined whether you actually want to stick it to something or what that something might be.</em>
-</blockquote>
-<figcaption>
-  <cite>
-    <a href="https://alistapart.com/article/axiomatic-css-and-lobotomized-owls/#section5">Axiomatic CSS and Lobotomized Owls — Dispensing with margins
-by Heydon Pickering</a>
-  </cite> 
-</figcaption>
-</figure>
-
-## Style variants
-
-> **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 `*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>
-<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>
-<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>
-  </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 an example.
-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><em>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.</em></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>
-  </cite> 
-</figcaption>
-</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).
-
-> 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.
-
-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.
-
-Note, Radix often required spreading on to the underlying DOM node
-
-<figure>
-<blockquote>
-  <em>Your component must spread props</em>.
-  When Radix clones your component, it will pass its own props and event handlers to make it functional and accessible.
-  If your component doesn't support those props, it will break.
-  This is done by spreading all of the props onto the underlying DOM node.
-</blockquote>
-<figcaption>
-  <cite>
-    <a href="https://www.radix-ui.com/docs/primitives/guides/composition#your-component-must-spread-props">Composing with your own React components</a>
-  </cite> 
-</figcaption>
-</figure>
-
-## Configurable Components Should Have Sane Defaults & Not Blow Up Without Props
-
-> **Warning**
-> This is a principle we don't always abide by but should!
-
-Every component should have enough default props to render without exploding and look normal.
-
-- ❌ `<Title>Hi</Title>` without `size` prop raising `Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined`
-- ✅ `<Title>Hi</Hi>` without `size` prop defaults to `size='medium'` and doesn’t blow up.
-
-
-## 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
-
-- [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/)
-- [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/)