@fusion.dev/helix-docs 0.104.0 → 0.105.0

package/content/forms.mdx

@@ -1,14 +1,20 @@
 ---
-description: Real form participation, labels that resolve across a shadow root, and the disabled trap.
+description: How Helix controls take part in forms, render their own labels, and handle disabled fieldsets.
 section: Essentials
 title: Forms and validation
 ---
 
 # Forms and validation
 
-Twenty-two families are form-associated custom elements, so a `<form>` collects
-them, resets them, restores them on back-navigation and validates them the way it
-does a native control. Nothing about that is simulated.
+Twenty-two component families are form-associated custom elements. A `<form>`
+treats them as it treats native controls:
+
+- It collects their values.
+- It resets them.
+- It restores them when you navigate back.
+- It validates them.
+
+None of this is simulated.
 
 ```html
 <form>
@@ -28,10 +34,10 @@ does a native control. Nothing about that is simulated.
 </form>
 ```
 
-`new FormData(form)` has `name` and `plan` in it. So does a server reading the
-POST body.
+`new FormData(form)` contains `name` and `plan`, and so does the POST body a
+server receives.
 
-## Every control carries its own label
+## Every control renders its own label
 
 ```html
 <helix-input
@@ -42,27 +48,30 @@ POST body.
 ></helix-input>
 ```
 
-There is no wrapping `Field` component, and that is not a style preference. **A
-wrapper cannot name what it wraps.** Its label would live in one shadow root and
-the control in another, and measured in Chrome 148: an `aria-labelledby` IDREF
-cannot see across a shadow boundary, and `control.ariaLabelledByElements =
-[labelInTheWrapper]` reads back as zero elements, the reference silently
-dropped. The same assignment with a label in the control's own tree is kept.
+Helix has no wrapping `Field` component, because **a wrapper cannot name the
+control inside it.** The wrapper's label would be in one shadow root and the
+control in another. We measured this in Chrome 148:
+
+- An `aria-labelledby` IDREF cannot see across a shadow boundary.
+- `control.ariaLabelledByElements = [labelInTheWrapper]` reads back as zero
+  elements, because the reference is silently dropped.
+- The same assignment with a label in the control's own tree is kept.
 
-That pattern works in React component libraries because they have no shadow
-boundary. Bringing it here brings the ergonomics and none of the conditions that
-made it work.
+The wrapper pattern works in React component libraries because they have no
+shadow boundary. Copying it into Helix would copy the API without the condition
+that makes it work.
 
-So every control that wants a label has the same three properties and renders
-its own nodes:
+Every control that takes a label has the same three properties, and it renders
+their content itself:
 
 | Property | For |
 |---|---|
 | `label` | The accessible name, and the fallback for the `label` slot |
 | `hint` | Help under the control, while there is nothing wrong |
-| `feedback` | What is wrong, in your words rather than the browser's |
+| `feedback` | What is wrong, in your own words. It replaces the browser's message |
 
-Each is a slot fallback, so anything richer than a string replaces it:
+Each property is the fallback for a slot of the same name. To use more than
+plain text, put content in the slot:
 
 ```html
 <helix-input name="email">
@@ -70,16 +79,18 @@ Each is a slot fallback, so anything richer than a string replaces it:
 </helix-input>
 ```
 
-**A whitespace-only text node defeats a default slot's fallback**, which costs a
-label and gives no warning. Measured in Chrome 148: a newline between the tags
-is enough, so `<helix-checkbox label="Accept">` closed on the next line renders
-no label at all. Named slots do not have this problem, because `slot="label"` is
-an attribute and a text node has none. It is the platform's behavior rather
-than ours, and it is true of every slot fallback in the library.
+A text node that holds only whitespace replaces a default slot's fallback. You
+lose the label, and nothing warns you. We measured this in Chrome 148. A newline
+between the tags is enough, so `<helix-checkbox label="Accept">` with its
+closing tag on the next line renders no label at all. Named slots do not have
+this problem, because `slot="label"` is an attribute and a text node cannot
+carry one. This is how the platform behaves, and it applies to every slot
+fallback in Helix.
 
 ## Validation
 
-The platform's own validation works, because these are real form participants:
+The platform's own validation works, because these controls are real form
+participants:
 
 ```html
 <helix-input
@@ -90,12 +101,13 @@ The platform's own validation works, because these are real form participants:
 ></helix-input>
 ```
 
-Submitting an empty form blocks and points at the control. `checkValidity()`,
-`reportValidity()` and `:invalid` behave.
+Submitting an empty form is blocked, and the browser points to the control.
+`checkValidity()`, `reportValidity()`, and `:invalid` work as they do for native
+controls.
 
-**`feedback` overrides the message.** Left empty, the browser's own is shown,
-which is localized and familiar; set, it says what you want in the words your
-product uses:
+`feedback` replaces the browser's message. When `feedback` is empty, the
+browser shows its own message, which is localized and familiar. When you set it,
+the control shows the message in the words your product uses:
 
 ```html
 <helix-input
@@ -106,13 +118,13 @@ product uses:
 ></helix-input>
 ```
 
-**A group is the participant, not its members.** `Radio.Group` and
-`Toggle.Group` own the `name`, the `value` and the validity: a lone radio is not
-a control at all, it is an answer to one. `Checkbox.Group` is the exception in
-the other direction, since each box in it submits itself already, so the group
-deliberately reports no value of its own.
+`Radio.Group` and `Toggle.Group` take part in the form for their members. Each
+group owns the `name`, the `value`, and the validity. A single radio is an
+answer, and the group is the control it answers. `Checkbox.Group` works the
+other way. Each checkbox in it already submits itself, so the group reports no
+value of its own.
 
-## The disabled trap
+## Disabled controls and fieldsets
 
 ```html
 <fieldset disabled>
@@ -123,13 +135,13 @@ deliberately reports no value of its own.
 </fieldset>
 ```
 
-That works. The platform tells a form-associated element it has been disabled by
-an ancestor through `formDisabledCallback`, and every Helix control implements
-it, so a control inside a disabled fieldset refuses input and announces itself
-as off rather than staying typeable and unsubmittable.
+A Helix control inside a disabled fieldset is disabled too. The platform calls
+`formDisabledCallback` to tell a form-associated element that an ancestor
+disabled it, and every Helix control implements that callback. A control inside
+a disabled fieldset does not accept input, and it announces itself as turned
+off.
 
-**For your own CSS this means one rule.** Style disabled controls with
-`:disabled`, never `[disabled]`:
+**Style disabled controls with `:disabled`.** Do not use `[disabled]`:
 
 ```css
 /* Right: matches the attribute and the ancestor fieldset. */
@@ -139,23 +151,22 @@ helix-input:disabled { … }
 helix-input[disabled] { … }
 ```
 
-The pseudo-class is true for a control carrying the attribute *and* for one
-inside a disabled fieldset, which sets no attribute on anything. A component
-styled with the attribute selector refuses interaction from the fieldset,
-because the platform disables it either way, and paints itself as live. That
-reads as a control that is simply broken, and it is invisible in every example
-that does not happen to use a fieldset. The library holds itself to this, and
-the same reasoning applies to yours.
+`:disabled` matches a control that has the attribute. It also matches a control
+inside a disabled fieldset, which sets no attribute on anything. With the
+attribute selector, the platform still disables a control inside a disabled
+fieldset, but the control is drawn as if it were active. It looks broken, and
+you will not see the problem in any example without a fieldset. Helix components
+follow this rule, and the same reasoning applies to your styles.
 
-`disabled` is mirrored to `aria-disabled` rather than removing the control from
-the accessibility tree, so a screen reader can still announce that the control
-exists and is currently off.
+`disabled` is mirrored to `aria-disabled`, and the control stays in the
+accessibility tree. A screen reader can still announce that the control exists
+and is turned off.
 
-## Seeding a form
+## Set starting values in a form
 
-A declared `value` or `checked` is a seed and the control goes on managing
-itself, so a form needs nothing wired to work. `default-value` is what a reset
-returns to, which is usually what a seed in a form means:
+A `value` or `checked` you set is a starting value, and the control then manages
+itself, so a form works without any wiring. `default-value` is the value a reset
+returns to. In a form, that is usually what you mean by a starting value:
 
 ```html
 <helix-input

package/content/iconography.mdx

@@ -1,5 +1,5 @@
 ---
-description: 105 glyphs, one geometry, and how to draw one that is not in the set.
+description: Draw icons from the Helix set, import glyphs directly, and build a set of your own.
 section: Foundations
 title: Iconography
 ---
@@ -10,14 +10,14 @@ title: Iconography
 <helix-icon name="trash"></helix-icon>
 ```
 
-108 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
-Phosphor's own geometry and it is kept rather than rescaled: normalizing to a 24
-box would change the optical weight of every glyph and stop the set matching
-anything upstream. Bold rather than regular, because Phosphor's regular is a
-hairline beside the medium weight this library sets its text in, and an icon
-that reads lighter than the words next to it is the opposite of a mark.
+Helix has 108 glyphs from Phosphor, drawn on a 256 box at Phosphor's bold
+weight. We keep Phosphor's own geometry. Rescaling to a 24 box would change the
+optical weight of every glyph, and the set would stop matching Phosphor. We use
+the bold weight because Phosphor's regular weight is a hairline beside the
+medium weight of Helix text. An icon that looks lighter than the words next to
+it does not work as a mark.
 
-## Size and color come from the context
+## Size and color come from the surrounding text
 
 An icon has no `size` and no `color` property. It is `1em` square and
 `currentColor`, so it takes the size and color of the text it sits in:
@@ -28,11 +28,10 @@ An icon has no `size` and no `color` property. It is `1em` square and
 </span>
 ```
 
-Inside a control, `--helix-size-icon` is what decides, and it follows the
-region's density along with everything else. That is why an icon in a small
-button is smaller without anybody saying so.
+Inside a control, `--helix-size-icon` sets the size, and it follows the region's
+density. So an icon in a small button is smaller without any extra setting.
 
-## Decorative or named
+## Decorative and named icons
 
 ```html
 <!-- Decorative: the text beside it already says what this is. -->
@@ -48,11 +47,11 @@ button is smaller without anybody saying so.
 ></helix-icon-button>
 ```
 
-An icon with no `label` is hidden from assistive technology, which is right when
-the words are beside it and wrong when they are not. `Icon.Button` takes a
-`label` because it never has words beside it.
+An icon with no `label` is hidden from assistive technology. Leave out `label`
+when text beside the icon says what it is. Add a `label` when there is no text.
+`Icon.Button` takes a `label` because it never has text beside it.
 
-## One that points along the line
+## Mirror an icon on right-to-left pages
 
 ```html
 <helix-icon
@@ -61,23 +60,23 @@ the words are beside it and wrong when they are not. `Icon.Button` takes a
 ></helix-icon>
 ```
 
-The names are physical, so `arrow-right` points right on every page. An arrow
-that means forward or back asks with `mirror` to turn round on a right-to-left
-page, which every caret the library draws already does.
+Icon names describe physical directions, so `arrow-right` points right on every
+page. When an arrow means forward or back, add `mirror` to flip it on a
+right-to-left page. Every caret Helix draws already flips.
 [Localization](./localization) has the rest.
 
-## Importing a glyph directly
+## Import a glyph
 
 ```ts
 import { trash } from '@fusion.dev/helix-icons'
 ```
 
-Each glyph is data, `{ content, name, viewBox }`, so you can put one in your own
-markup, in a canvas, or anywhere an element is not what you want. Every `name`
-the library uses is held to the set of glyphs that actually exist, so a typo is a
-build failure rather than an empty box.
+Each glyph is data in the form `{ content, name, viewBox }`. You can put one in
+your own markup, in a canvas, or anywhere you do not want an element. Every
+`name` Helix uses is checked against the glyphs that exist, so a typo fails the
+build.
 
-**Hand one to the element and it draws it**, whatever set it came from:
+**Pass a glyph to the `icon` property to draw it**, from any set:
 
 ```tsx
 import { trash } from '@fusion.dev/helix-icons'
@@ -85,44 +84,49 @@ import { trash } from '@fusion.dev/helix-icons'
 <helix-icon icon={trash} />
 ```
 
-A property rather than an attribute, because an object is not a string: the
-frameworks set properties and plain HTML cannot, which is what `name` is for.
-Both set, the value wins.
+`icon` is a property because a glyph is an object, and an attribute holds only a
+string. Frameworks can set properties. Plain HTML cannot, so it uses `name`. If
+both are set, `icon` wins.
 
-**This is the door that scales.** `name` resolves through an index of the whole
-set, which no bundler can shake, so a consumer who renders one named icon ships
-all of it: 15 kB gzipped for 108 glyphs. A value ships the one glyph you
-imported. It is also the door out of this set entirely, since anything exporting
-that shape works, whether it is Phosphor at another weight, another library, or
-your own drawings:
+`icon` also keeps your bundle small. `name` looks up glyphs in an index of the
+whole set, and no bundler can tree-shake that index. If you render one icon by
+`name`, you ship the whole set: 15 kB gzipped for 108 glyphs. With `icon`, you
+ship only the glyph you import.
+
+`icon` also draws glyphs from outside this set. Anything that exports the same
+shape works:
+
+- Phosphor at another weight
+- another icon library
+- your own drawings
 
 ```ts
 const dot = { content: '<circle cx="12" cy="12" r="10" fill="currentColor" />', name: 'dot', viewBox: '0 0 24 24' }
 ```
 
-## Weight is a subpath
+## Choose a weight with a subpath
 
 ```ts
 import { caretDown } from '@fusion.dev/helix-icons/regular'
 import { trash } from '@fusion.dev/helix-icons/bold'
 ```
 
-The default is bold, and `/bold` is the same set under a name that says so.
+The default is bold. `/bold` is the same set, with the weight in its path.
 
-**A subpath rather than an attribute, because a weight is data rather than a
-dial.** Phosphor's weights are outlined filled paths: `caret-down` is `a12,12`
-at bold and `a8,8` at regular, so there is nothing for CSS to turn and every
-weight offered is bytes shipped. A subpath is shaken per import site; a `weight`
-attribute would put every weight into the index that `name` reads, taking one
-consumer's 15 kB to about 90.
+**Each weight is a separate set of drawings, so each weight is a subpath.**
+Phosphor's weights are outlined, filled paths. `caret-down` is `a12,12` at bold
+and `a8,8` at regular, so CSS cannot turn one weight into another, and every
+weight offered adds bytes. Bundlers tree-shake a subpath at each import site. A
+`weight` attribute would put every weight into the index that `name` reads, and
+raise your bundle from 15 kB to about 90.
 
-Only the default weight carries that index, so `name` draws bold. A consumer who
-wants the set in another weight imports the values and hands them over.
+Only the default weight has that index, so `name` always draws bold. To use the
+set in another weight, import the glyphs and pass them to `icon`.
 
-## A set of your own
+## Build your own icon set
 
-The generator that builds this set is the package's own command, so you are not
-waiting on us to carry a glyph:
+The package includes the command that builds this set, so you can add any glyph
+yourself:
 
 ```sh
 npx helix-icons build --source ./brand-icons --out src/icons.ts
@@ -134,9 +138,9 @@ import { peak } from './icons'
 <helix-icon icon={peak} />
 ```
 
-It reads a directory of SVG files and writes the module the element draws from,
-which is the same job whether the drawings are yours, another library's, or the
-1,404 Phosphor glyphs this set does not carry:
+The command reads a directory of SVG files and writes the module that
+`helix-icon` draws from. It works the same way for your own drawings, another
+library's, or the 1,404 Phosphor glyphs this set does not include:
 
 ```sh
 npx helix-icons build \
@@ -144,30 +148,30 @@ npx helix-icons build \
   --list mine.txt --out src/icons.ts
 ```
 
-`--suffix` is for a set that spells the weight into the file name, Phosphor's
-bold being `caret-down-bold.svg`. `--index` also writes the record `name` reads,
-which you want if your own elements take a name in markup and do not want
-otherwise, since it is the part nothing can drop.
+Use `--suffix` for a set that puts the weight in the file name, such as
+Phosphor's bold `caret-down-bold.svg`. `--index` also writes the record that
+`name` reads. Use it only if your own elements take a name in markup, because no
+bundler can remove that record.
 
-**A name in two sources is refused rather than decided.** A precedence decides
-silently, and the glyph on the page would be whichever directory sat higher with
-nothing looking wrong afterwards.
+**The command stops with an error when a name appears in two sources.** With
+an order of precedence, the glyph on the page would come from whichever
+directory ranked higher, and nothing would look wrong.
 
-## Adding one to this set
+## Add a glyph to the Helix set
 
-Add the name to `helix/icons/icons.txt` and run `turbo run icons`. Phosphor names
-resolve from `@phosphor-icons/core` at build time, so adding a glyph is adding a
-line rather than hand-transcribing a path into a TypeScript object.
+Add the name to `helix/icons/icons.txt` and run `turbo run icons`. Phosphor
+names resolve from `@phosphor-icons/core` at build time, so adding a glyph takes
+one line. You do not copy a path into a TypeScript object by hand.
 
-A mark Phosphor does not draw goes into `helix/icons/raw` as an SVG under the
-same name, and is read from there when the package has no match. Keep it to the
-same geometry, a 256 box at the bold weight: a glyph drawn at a different weight
-is visible immediately when it sits beside one that was not.
+For a mark Phosphor does not draw, add an SVG with the same name to
+`helix/icons/raw`. The build reads it from there when Phosphor has no match.
+Draw it with the same geometry, a 256 box at the bold weight. A glyph drawn at a
+different weight stands out next to the others.
 
-## Icons this set does not have
+## Product marks
 
-Product marks. Helix and Cortex have marks and they live in the icon package,
-but a mark is not an icon: it identifies a product and does not mean an action.
-**A mark is one rounded body with material removed**, never a pictogram of a
-metaphor, because the parent it stands beside is a geometric monogram. If you
-are reaching for the icon set to draw a logo, that is the wrong drawer.
+Helix and Cortex have product marks. They are in the icon package, and they are
+not part of the icon set. A mark identifies a product. An icon stands for an
+action. **A mark is one rounded body with material removed.** It is never a
+pictogram of a metaphor, because it stands beside the parent brand's mark, a
+geometric monogram. Do not use the icon set to draw a logo.