@fusion.dev/helix-docs 0.148.0 → 0.149.1

package/content/color.mdx

@@ -67,6 +67,23 @@ The eight syntax roles for code are `callable`, `comment`, `constant`,
 `invalid`, `keyword`, `name`, `string`, and `tag`. A full editor theme has more
 roles. Helix has fewer because code in documentation only needs to be read.
 
+### Scrollbars
+
+`Scroll Area`, `Chat`, and `Virtual List` color their scrollbars with three
+tokens:
+
+- `--helix-scrollbar-thumb-color` is the thumb at rest. It is a mid gray that
+  measures at least 3:1 against the page and every surface, in both modes.
+- `--helix-scrollbar-thumb-hover-color` is the thumb while the pointer is over
+  its scroller. It is `foreground-subtle`.
+- `--helix-scrollbar-track-color` is the track behind the thumb. It is
+  `transparent`, so the scroller's own ground shows through.
+
+Each of the three reads its own hook first, such as `--scroll-area-thumb-color`
+or `--chat-scrollbar-thumb-color`, so you can recolor one scroller and leave
+the rest. Set the tokens to recolor all three. Other families that scroll keep
+the browser's own scrollbar.
+
 ## Why colors use OKLCH
 
 Every Helix color is written in OKLCH. In sRGB, equal numeric steps do not look

package/content/composition.mdx

@@ -65,6 +65,12 @@ A property that holds content, such as a tooltip's text, is the fallback content
 for a slot of the same name. Helix never renders both.
 
 ```html
+<!-- The trigger, which names the tooltip in aria-describedby -->
+<helix-button
+  aria-describedby="save-tip"
+  id="save"
+>Save</helix-button>
+
 <!-- The property -->
 <helix-tooltip
   content="Save"

package/content/graphs.mdx

@@ -431,9 +431,40 @@ leaves removing it to your framework.
 - In the search field, Down moves into the list, and Escape empties the search.
   With `no-panel`, Escape on an empty search closes the list.
 - Screen readers read the selected note first, then how each other note links
-  to it, such as "Linked from Roadmap", and the count as a search narrows it.
+  to it, such as "Linked from Roadmap". They hear the count when a search or
+  the legend changes it.
+- After the arrow keys, plus, minus, or the buttons move the drawing, screen
+  readers hear which way it went, such as "Moved right" or "Zoomed in".
+  `connectGraph` tells the frame once the drawing has moved. If you answer
+  `helix-graph-pan` and `helix-graph-zoom` yourself, call `frame.moved()` once
+  your view has moved.
+- When you change `nodes` or `links`, the list keeps the note the keys are on.
+  When that note is removed, the keys move to the note that took its row.
 - Change the words with `search-label`, `count-label`, `selected-label`,
-  `links-to-label`, `linked-from-label`, and `linked-both-label`.
+  `links-to-label`, `linked-from-label`, `linked-both-label`,
+  `moved-up-label`, `moved-down-label`, `moved-left-label`,
+  `moved-right-label`, `zoomed-in-label`, and `zoomed-out-label`, or register
+  them for a language with `registerWords` (see
+  [Localization](./localization)).
+
+## Events
+
+The frame sends these events. Their names follow Map's: `helix-graph-pan`,
+`helix-graph-zoom`, `helix-graph-ready`, and `helix-graph-part-change` match
+`helix-map-pan`, `helix-map-zoom`, `helix-map-ready`, and
+`helix-map-part-change`. These are the names Graph keeps.
+
+| Event | Sent when | Cancelable | Who listens |
+|---|---|---|---|
+| `helix-before-activate` | A note is about to be selected | Yes | You, to keep the selection in your own state |
+| `helix-activate` | A note was selected, in the list or the drawing | No | You |
+| `helix-graph-filter` | A group in the legend was pressed, before its notes are shown or hidden | Yes | You, to set `hiddenGroups` yourself |
+| `helix-graph-layout` | A layout settled, with where it put each note | No | You, to keep the positions |
+| `helix-graph-ready` | The graph has been drawn whole | No | You, to show the graph once it is finished |
+| `helix-graph-pan` | An arrow key or a pan button asked the drawing to move | No | `connectGraph`, or your own renderer |
+| `helix-graph-zoom` | Plus, minus, or a zoom button asked the drawing to zoom | No | `connectGraph`, or your own renderer |
+| `helix-graph-part-change` | The notes, links, selection, depth, or gestures changed | No | `connectGraph` only. It stays on the frame. |
+| `helix-graph-signal` | `signal()` was called | No | `connectGraph` only. It stays on the frame. |
 
 ## Write a driver
 

package/content/iconography.mdx

@@ -10,7 +10,7 @@ title: Iconography
 <helix-icon name="trash"></helix-icon>
 ```
 
-Helix has 125 glyphs, 120 of them from Phosphor, drawn on a 256 box at
+Helix has 126 glyphs, 121 of them 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
@@ -90,7 +90,7 @@ both are set, `icon` wins.
 
 `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: 17 kB gzipped for 125 glyphs. With `icon`, you
+`name`, you ship the whole set: 17 kB gzipped for 126 glyphs. With `icon`, you
 ship only the glyph you import.
 
 `icon` also draws glyphs from outside this set. Anything that exports the same

package/content/localization.mdx

@@ -1,5 +1,5 @@
 ---
-description: Set the locale of date, time, and number controls, translate component strings, and lay out pages right to left.
+description: Set the locale of date, time, and number controls, translate the built-in words, and lay out pages right to left.
 section: Essentials
 title: Localization and RTL
 ---
@@ -104,27 +104,175 @@ Six families format numbers or dates and take a `locale`:
 ></helix-pagination>
 ```
 
-If you do not set `locale`, these controls use the browser's locale, which is
-usually correct. Set `locale` when your users choose your application's
+If you do not set `locale`, these controls use the nearest `lang` attribute,
+then the browser's locale, which is usually correct. Set `locale` when your users choose your application's
 language separately from the language of their operating system.
 
 The first day of the week comes from `Intl.Locale`'s week information, which
 Firefox does not provide. There, and where you set no `locale`, the week starts
 on Sunday. Set `first-day-of-week` to choose the day yourself.
 
-`locale` formats dates, times, and numbers. It does not translate the words a
-control speaks, such as "Previous month" on a calendar. Set those through their
-properties, such as `previous-label` and `next-label` on Date Picker and Date
-Input. A time wheel's name, such as "Hour", comes from the locale.
+`locale` formats dates, times, and numbers. On a family that reads the words
+registry, it also picks the words. On the others, set the words a control
+speaks through their properties, such as `previous-label` and `next-label` on
+Date Picker and Date Input. See
+[Translate the built-in words](#translate-the-built-in-words). A time wheel's
+name, such as "Hour", comes from the locale.
 
 Formatting uses `Intl`, so Helix bundles no locale data, and you have nothing to
 keep up to date.
 
-## Translate component strings
+## Calendars
 
-More than a hundred properties in the headless tier set text that your users
-see. Examples include `pan-up-label` on a map and `remove-label` on a combobox's
-selected tags. Properties that combine values are format templates:
+Date Picker, Date Input, and Format Date write dates in five calendars. Each
+has the Gregorian months, so the days in a Date Picker are the same in all
+five:
+
+| Calendar | October 6, 2026 | The locale's own calendar for |
+|---|---|---|
+| `gregory` | October 6, 2026 | Most locales |
+| `buddhist` | 6 ตุลาคม 2569 | `th-TH` |
+| `japanese` | 令和8年10月6日 | `ja-JP-u-ca-japanese` |
+| `roc` | 民國115年10月6日 | `zh-TW-u-ca-roc` |
+| `iso8601` | 2026 October 6 | A locale written with `-u-ca-iso8601` |
+
+If you do not set `calendar`, these components use the locale's own calendar
+when it is one of the five. Set `calendar` to choose one yourself:
+
+```html
+<helix-date-picker
+  calendar="buddhist"
+  locale="en-US"
+></helix-date-picker>
+```
+
+**Every other calendar is written as Gregorian**, in the locale's language and
+digits. This includes the Persian, Islamic, Hebrew, Ethiopic, Indian, Coptic,
+Chinese, and Dangi calendars, whose months are not the Gregorian months. A page
+in `fa-IR`, whose own calendar is Persian, shows October 2026 as "اکتبر ۲۰۲۶".
+
+The value is `YYYY-MM-DD` in every calendar. In a `segmented` Date Input, the
+segments hold the Gregorian day, month, and year, so a Buddhist date is typed
+with the year 2026.
+
+## Translate the built-in words
+
+Components have English words built in: the names a screen reader hears, the
+sentences a live region says, and the text on buttons such as "Load more".
+Register the words for a language once, and every element in that language
+speaks them:
+
+```js
+import { registerWords } from '@fusion.dev/helix'
+
+registerWords('pl', {
+  'helix-combobox': {
+    emptyText: 'Brak wyników',
+    resultsLabel:
+      '{count, plural, one {# wynik} few {# wyniki} many {# wyników} other {# wyniku}}',
+  },
+  'helix-data-table': {
+    nextLabel: 'Następna strona',
+    previousLabel: 'Poprzednia strona',
+  },
+})
+```
+
+Each family's words are keyed by its tag, such as `helix-combobox`, and then
+by the property name. The headless and styled tiers share one key. To type the
+keys, import the generated types once:
+
+```ts
+import type {} from '@fusion.dev/helix/words'
+```
+
+Every family reads the registry for the words it declares, the words several
+families share included. Register a shared word under each family's key: the
+name of a dismiss button, `dismissLabel`, under `helix-callout`; a collection's
+`emptyText` and `loadingText` under `helix-tree`; and the sentence a field
+reports when a required value is missing, `valueMissingMessage`, under
+`helix-checkbox`. A family that has its own English for a shared word, such as
+Tag's `Remove {label}`, keeps it until you register another.
+
+The name a family gives itself where nothing else names it is `fallbackLabel`
+in every family, such as `{ 'helix-table': { fallbackLabel: 'Tabelle' } }`.
+
+### Which words an element uses
+
+1. **A value you set on the element**, as an attribute or a property. The
+   English counts as a value, so `empty-text="No matches"` keeps the English
+   on every page.
+2. The words registered for the element's locale.
+3. The English.
+
+Set the property to `null`, or remove the attribute, to return to the
+registered words. Reading the property gives the word the element uses, in its
+locale.
+
+### Which locale an element speaks
+
+1. The element's `locale` property.
+2. The nearest `lang` attribute, read through shadow roots, such as
+   `<html lang="pl">`.
+3. The browser's language.
+
+The same locale picks the words, the plural forms, and the way numbers are
+written, so one sentence never mixes two languages.
+
+A word that a language does not have falls back one key at a time, through
+the regional, script, and language forms of the tag and then to English. A
+`de-CH` page uses a `de-CH` word, then a `de` word, then the English. Hong Kong
+(`zh-HK`) reaches a `zh-Hant` word before a `zh` word. Name a set of words by
+its full tag where a language has regional forms, such as `pt-BR`, `pt-PT`, and
+`es-419`.
+
+When you register words, or change the `lang` of the `<html>` element, every
+element on the page updates once. When you change the `lang` of another
+element, call `refreshWords()`.
+
+### Write a message
+
+Words are messages in a small part of the ICU MessageFormat syntax, which
+translation tools read:
+
+| Syntax | What it does |
+|---|---|
+| `{name}` | Puts in a value. A number is written in the locale, such as `1.200` in German. |
+| `{p, number, percent}` | Writes a number as a percentage, with the sign where the locale puts it. `{n, number, integer}` rounds. |
+| `{count, plural, one {# wynik} few {# wyniki} other {# wyniku}}` | Picks a form by the language's plural rules. `#` is the number. `=0 {...}` matches one exact number, and `offset:1` counts from one. |
+| `{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}` | Picks a form for a position. |
+| `{direction, select, ascending {...} descending {...} other {...}}` | Picks a whole sentence by a value, so a language can phrase each one its own way. |
+| `''` and `'{'` | Write one apostrophe, and a brace as text. A single apostrophe is text, so `L'élément` needs no escaping. |
+
+Each property's reference entry names its placeholders. A message that does
+not parse shows as written, so a typo appears on the page where you can see it.
+
+`formatMessage(message, values, locale)` formats a message for your own
+elements, and `wordsLocale(element)` gives the locale an element speaks.
+
+### Server rendering
+
+A server knows the element's own attributes and the words your server code
+registered. It does not know the page around the element. So on a server, and
+in the first render while an element hydrates, a word uses the element's
+`locale`, then its own `lang`, then the locale you set with
+`setDefaultWordsLocale`, then English. After hydration, the element reads the
+nearest `lang` and updates once if its words change.
+
+- Register the same words on the server and in the browser, before the
+  elements are defined, so the two renders agree.
+- A server that renders one language calls `setDefaultWordsLocale('pl')` once.
+- A server that renders several languages sets `lang` or `locale` on the
+  elements.
+
+The registry holds no current language, so two requests in two languages in
+one process do not affect each other.
+
+### Set the words of other families
+
+A value set on the element always wins, so any family takes its words as
+properties too, such as `empty-text` on a listbox. Properties that combine
+values are format templates:
 
 ```html
 <helix-pagination-summary
@@ -156,7 +304,8 @@ or `disable-times` rules out.
 A message appears in the browser's own validation bubble and on the line under
 the field. `feedback` does not reach the bubble. If you do not set a message, a
 text field shows the browser's own message, which is already in your user's
-language. Every other control shows its English sentence.
+language. Every other control shows its English sentence. An empty message
+counts as not set.
 
 ```html
 <helix-number-input
@@ -178,9 +327,8 @@ Aria's `@react-stately/color` translates, so you can reuse that table.
 ></helix-color-picker>
 ```
 
-**Pass these strings from your own translation system.** Helix ships English
-defaults and no translation tools. If Helix had its own string catalog, you
-would have to keep two catalogs in step.
+Helix ships English words and no translations. Pass the words from your own
+translation system, either to `registerWords` or to the properties.
 
 ## What to check when you add a language
 
@@ -212,9 +360,9 @@ would have to keep two catalogs in step.
 
 Helix does not include:
 
-- a message catalog
-- a pluralization helper
+- translations of its words into other languages
+- a message catalog for your own application's text
 - a date-range formatter, beyond what the controls format themselves
 
-These belong to your application's i18n layer. You can set every translatable
-property from that layer.
+These belong to your application's i18n layer. You can register every word,
+and set every translatable property, from that layer.

package/content/maps.mdx

@@ -327,7 +327,8 @@ frame with the marker's `name`, or its `label` if it has no name.
 
 To show that a place has been visited, add `passed`. The marker is drawn in a
 muted color, and screen readers hear its name followed by "passed". Use
-`passed-label` to change that word.
+`passed-label` to change that sentence, where `{label}` is the place's name,
+such as `{label} (visited)`.
 
 ### Clusters