@theroutingcompany/components 0.0.18-alpha.1 → 0.0.18-alpha.10

package/README.md

@@ -182,12 +182,29 @@ 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. 
+Use CSS variables for the dynamic parts in styled-components using.
 
 See [The styled-components Happy Path](https://www.joshwcomeau.com/css/styled-components/)
 
@@ -257,14 +274,14 @@ 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.
+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>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>
+    <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>
@@ -285,12 +302,23 @@ Exact types for props (for editor autocomplete) is a necessity, not a nice-to-ha
 
 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.
 
-> 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.
+## 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