@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/docs/menus.md

@@ -0,0 +1,312 @@
+# MenuBar and ContextMenu
+
+> Buttons · @motifx-community/ui 0.1.0-beta.0
+
+A menu bar of an app (File, Edit, View) and the menu that opens on a right-click. Both show the same menu items: submenus, check and radio items, shortcuts, access keys.
+
+## Import
+
+```tsx
+import { MenuBar, ContextMenu, attachContextMenu, type MenuItem } from '@motifx-community/ui';
+```
+
+## MenuBar
+
+A `MenuBar` takes its top items as `items`; each one's `items` is its menu. `&File` makes Alt+F open File. Left and Right move along the bar and, while a menu is open, to the next menu; Escape goes back to the bar.
+
+```tsx
+import { reactive, type Component } from '@motifx/core';
+import { CheckBox, MenuBar, Stack, type MenuItem } from '@motifx-community/ui';
+
+/** An app's menu bar made with `new`: submenus, check and radio items, shortcuts, access keys, and `onItemClick`. */
+export default function MainMenu() {
+  const s = reactive({
+    log: 'Nothing chosen yet.',
+    chosen: 0,
+    wrap: true,
+    statusBar: false,
+    zoom: '100%',
+    theme: 'light',
+    f10: false,
+    canUndo: true,
+  });
+
+  const did = (what: string) => (s.log = what);
+  const undo = (back: boolean) => {
+    s.canUndo = !back;
+    did(back ? 'Undo' : 'Redo');
+  };
+  const zoom = (value: string): MenuItem => ({ text: value, group: 'zoom', checked: () => s.zoom === value, click: () => (s.zoom = value) });
+  const theme = (value: string, text: string): MenuItem => ({ text, group: 'theme', checked: () => s.theme === value, click: () => (s.theme = value) });
+
+  const menus: MenuItem[] = [
+    {
+      text: '&File',
+      items: [
+        { text: '&New', shortcut: 'Ctrl+N', click: () => did('New') },
+        { text: '&Open…', shortcut: 'Ctrl+O', click: () => did('Open…') },
+        { text: 'Open &recent', items: ['report.docx', 'budget.xlsx', 'notes.md'].map((name) => ({ text: name, click: () => did(`Open ${name}`) })) },
+        { text: '&Save', shortcut: 'Ctrl+S', beginGroup: true, click: () => did('Save') },
+        { text: 'Save &as…', click: () => did('Save as…') },
+        { text: 'E&xit', beginGroup: true, click: () => did('Exit') },
+      ],
+    },
+    {
+      text: '&Edit',
+      items: [
+        { text: '&Undo', shortcut: 'Ctrl+Z', enabled: () => s.canUndo, click: () => undo(true) },
+        { text: '&Redo', shortcut: 'Ctrl+Y', click: () => undo(false) },
+        { text: 'Cu&t', shortcut: 'Ctrl+X', beginGroup: true, click: () => did('Cut') },
+        { text: '&Copy', shortcut: 'Ctrl+C', click: () => did('Copy') },
+        { text: '&Paste', shortcut: 'Ctrl+V', click: () => did('Paste') },
+        { text: 'Paste &special', enabled: false },
+      ],
+    },
+    {
+      text: '&View',
+      items: [
+        { text: '&Word wrap', checked: () => s.wrap, click: () => (s.wrap = !s.wrap) },
+        { text: '&Status bar', checked: () => s.statusBar, click: () => (s.statusBar = !s.statusBar) },
+        { ...zoom('100%'), beginGroup: true },
+        zoom('125%'),
+        zoom('150%'),
+        { text: '&Theme', beginGroup: true, items: [theme('light', 'Light'), theme('dark', 'Dark'), theme('system', 'Same as the system')] },
+      ],
+    },
+    { text: '&Help', items: [{ text: '&About', click: () => did('About') }] },
+  ];
+
+  const bar = new MenuBar({ label: 'Main', items: menus, focusOnF10: () => s.f10 });
+  bar.onItemClick(() => s.chosen++);
+
+  return (
+    <>
+      <div style="inline-size: 100%" ref={(c: Component<HTMLDivElement>) => c.controls.add(bar)} />
+      <Stack orientation="horizontal" wrap align="center">
+        <CheckBox label="F10 focuses the bar" x-model={() => s.f10} />
+        <output class="mb-log">{() => s.log}</output>
+        <output class="mb-count">{() => `onItemClick ran ${s.chosen} times.`}</output>
+      </Stack>
+      <span class="mb-view">{() => `Word wrap ${s.wrap ? 'on' : 'off'} · status bar ${s.statusBar ? 'on' : 'off'} · zoom ${s.zoom} · theme ${s.theme}`}</span>
+    </>
+  );
+}
+```
+
+## Submenus, checks, radios, shortcuts
+
+An item with `items` opens a submenu at its side: Right (Left in a right-to-left page), Enter or Space open it, Left and Escape close it, and the pointer opens it after a short rest. `checked` makes a check item; `checked` with a `group` one choice of several, shown with a dot. `shortcut` is shown at the end of the item; register the key itself with `addShortcut`. The same items work in `Button`’s menu.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `text` | `Bind<string>` | The label; `&Copy` makes C choose it while the menu is open (Alt+C on a menu bar’s top item). |
+| `icon, hint` | `Bind<…>` | An icon at the start, a tooltip. |
+| `shortcut` | `Bind<string>` | A key combination shown at the end (`Ctrl+S`). Only shown: register the key with `addShortcut`. |
+| `description` | `Bind<string>` | A second, dimmer text after the label: what tells the item apart, such as a folder. Part of the item’s name, never a key. |
+| `items` | `Bind<readonly MenuItem[]>` | A submenu, opened at the side. |
+| `checked` | `Bind<boolean>` | A check item (`menuitemcheckbox`). |
+| `group` | `Bind<string>` | With `checked`: one choice of a group (`menuitemradio`), shown with a dot. |
+| `enabled, visible` | `Bind<boolean>` | Dimmed and not chosen, or left out. |
+| `beginGroup` | `Bind<boolean>` | A line before the item. |
+| `tone` | `Bind<'standard' \| 'accent' \| 'success' \| 'caution' \| 'danger'>` | The item in the kit tone color (`danger` for a destructive one); a toolbar button moved into the overflow menu keeps its tone. |
+| `click` | `(e) => void` | Chosen, after the menu closed. `e`: `{ item, source, event }`. |
+| `data` | `unknown` | Your own value. |
+
+## ContextMenu
+
+A `ContextMenu` opens on its target’s right-click at the pointer, and with the Menu key or Shift+F10 at the focused element. `onOpening` gets the element (`e.target`) and builds the items for it, here for the row of a list; `e.cancel = true` leaves the browser its own menu. It closes on Escape and a press outside; when the page scrolls it goes along with the element it opened on, and closes once that element is out of sight.
+
+```tsx
+import { reactive, type Component } from '@motifx/core';
+import { ContextMenu, type MenuItem } from '@motifx-community/ui';
+
+interface FileRow {
+  id: number;
+  name: string;
+  locked: boolean;
+  starred: boolean;
+}
+
+const BOX = 'inline-size: 100%; margin: 0; list-style: none; padding: var(--mx-space-4); background: var(--mx-color-bg-card); border: var(--mx-border-width-1) solid var(--mx-color-stroke-card); border-radius: var(--mx-radius-lg)';
+
+/** A context menu whose items `onOpening` builds for the row of a list it opens on. */
+export default function FileList() {
+  const s = reactive({
+    log: 'Nothing chosen yet.',
+    files: [
+      { id: 1, name: 'report.docx', locked: false, starred: true },
+      { id: 2, name: 'budget.xlsx', locked: true, starred: false },
+      { id: 3, name: 'photo.png', locked: false, starred: false },
+    ] as FileRow[],
+  });
+  let renamed = 0;
+  let list: Component<HTMLUListElement> | null = null;
+
+  const did = (what: string) => (s.log = what);
+  const rename = (row: FileRow) => {
+    row.name = `copy-${++renamed}-${row.name}`;
+    did(`Renamed to ${row.name}`);
+  };
+
+  const rowItems = (row: FileRow): MenuItem[] => [
+    { text: '&Open', click: () => did(`Open ${row.name}`) },
+    { text: '&Rename', enabled: !row.locked, click: () => rename(row) },
+    { text: '&Star', checked: row.starred, click: () => (row.starred = !row.starred) },
+    { text: '&Move to', items: ['Documents', 'Pictures', 'Archive'].map((folder) => ({ text: folder, click: () => did(`Move ${row.name} to ${folder}`) })) },
+    { text: '&Delete', shortcut: 'Del', beginGroup: true, enabled: !row.locked, click: () => (s.files = s.files.filter((f) => f !== row)) },
+  ];
+
+  const rowOf = (el: Element) => {
+    const id = Number(el.closest('[data-id]')?.getAttribute('data-id'));
+    return s.files.find((f) => f.id === id);
+  };
+
+  return (
+    <>
+      <ul class="cm-list" aria-label="Files" ref={(c: Component<HTMLUListElement>) => (list = c)} style={BOX}>
+        {s.files.map((file) => (
+          <li key={file.id} data-id={String(file.id)} tabindex="0" style="padding-block: var(--mx-space-2)">
+            {() => `${file.starred ? '★ ' : ''}${file.name}${file.locked ? ' (locked)' : ''}`}
+          </li>
+        ))}
+      </ul>
+      <ContextMenu
+        target={() => list}
+        label="File"
+        onOpening={(e) => {
+          const row = rowOf(e.target);
+          if (row) e.items = rowItems(row);
+          else e.cancel = true;
+        }}
+      />
+      <output class="cm-log">{() => s.log}</output>
+    </>
+  );
+}
+```
+
+```tsx
+import { reactive, type Component } from '@motifx/core';
+import { attachContextMenu } from '@motifx-community/ui';
+
+const START = 'Right-click here, or focus me and press the Menu key.';
+const BOX = 'padding: var(--mx-space-4); background: var(--mx-color-bg-card); border: var(--mx-border-width-1) solid var(--mx-color-stroke-card); border-radius: var(--mx-radius-lg)';
+
+/** A menu given to an element with `attachContextMenu`, its items built from the opening. */
+export default function AttachedMenu() {
+  const s = reactive({ zone: START });
+
+  const attach = (c: Component<HTMLDivElement>) => {
+    const remove = attachContextMenu(c, (e) => [
+      { text: '&Say where', click: () => (s.zone = `Opened ${e.byKeyboard ? 'from the keyboard' : 'with the pointer'} on <${e.target.tagName.toLowerCase()}>.`) },
+      { text: '&Reset', click: () => (s.zone = START) },
+    ]);
+    c.motif.setDisposable(remove);
+  };
+
+  return (
+    <div class="cm-zone" tabindex="0" style={BOX} onBuilt={attach}>
+      {() => s.zone}
+    </div>
+  );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | Into the menu bar (one stop), and out of it. |
+| `Left / Right` | On the bar: the previous / next top item. In a menu: the neighbour’s menu, or close a submenu (Right opens one). Mirrored right to left. |
+| `Down, Enter, Space` | On the bar: open the menu, first item. Up opens it on the last item. |
+| `Up / Down, Home / End` | In a menu: move between the items, wrapping around. |
+| `A letter` | The next item starting with it; an item’s `&` key chooses it. |
+| `Alt + key` | Opens the top item with that `&` key (Control + Option on Apple platforms). |
+| `Escape` | Closes a submenu, then the menu, back to where it opened. |
+| `F10` | Focuses the menu bar, with `focusOnF10`. |
+| `Menu key, Shift+F10` | Opens a context menu at the focused element. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `MenuBar` | `role="menubar"` named by `label`; top items are `menuitem`s with `aria-haspopup` and `aria-expanded`, one Tab stop (roving tabindex). |
+| `Menus` | `role="menu"`; items are `menuitem`, `menuitemcheckbox` or `menuitemradio` with `aria-checked`; disabled ones `aria-disabled`, still reachable. |
+| `Submenus` | The item has `aria-haspopup="menu"` and `aria-expanded`; the submenu opens next to it, focus goes in and comes back. |
+| `Focus` | A menu opened from the keyboard focuses its first item; from the pointer, the menu itself. Closing gives focus back. |
+| `Shortcuts` | The shortcut text is part of the item’s name; access keys are in `aria-keyshortcuts` on the top items. |
+
+## Localization
+
+Menus write no text of their own: every label, shortcut and name comes from your items, so they follow your own translations (a function in `text` follows a language change at once).
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-menubar, .mx-menubar__bar, .mx-menubar__item` | The menu bar, its row, a top item (`aria-expanded="true"` while open). |
+| `.mx-context-menu, .mx-context-menu__anchor` | The context menu (no box of its own) and the point it opens at. |
+| `.mx-menu, .mx-menu__item, .mx-menu__separator` | A menu (shared with Button), an item, a line. |
+| `.mx-menu__check, .mx-menu__icon, .mx-menu__label, .mx-menu__description, .mx-menu__shortcut, .mx-menu__arrow` | The parts of an item. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `menubar.height, menubar.item-height` | The heights of the bar and of a top item. |
+| `menubar.bar, menubar.item, menubar.icon, menubar.mnemonic` | Units: the bar; a top item with its box per state (`hover`, `pressed`, `open`, `disabled`, `focus`); its icon; its access key’s mark (`shown`). |
+| `menu.item, menu.item-height, menu.item-white-space` | Menu items (shared with Button’s menu): the item unit in each state (`highlight`, `pressed`, `focus`, `checked`, `disabled`, `first`, `last`, each tone and `<tone>-highlight`), the row height, whether a text wraps. |
+| `menu.panel, menu.check, menu.icon, menu.check-mark, menu.radio-mark, menu.separator` | Units: the column of items, the leading mark and icon, the check and radio marks, the line between groups. |
+| `menu.label, menu.description, menu.shortcut, menu.arrow` | Units: an item’s text, its description, the shortcut and the submenu arrow. |
+
+## API reference
+
+### MenuBar props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly MenuItem[]>` | `[]` | The top items; their `items` are the menus they open. A top item without `items` runs its `click`. |
+| `label` | `Bind<string>` | `''` | Names the bar for screen readers. The same property as `text`. |
+| `focusOnF10` | `Bind<boolean>` | `false` | F10 moves focus to the bar from anywhere on the page. Off by default: browsers use F10. |
+| `openOnHover` | `Bind<boolean>` | `true` | While a menu is open, pointing at another top item opens its menu; pointing at an item opens its submenu. |
+| `enabled / disabled, visible, tabStop, tabIndex` | see Control |  | The shared properties of every control. |
+
+### ContextMenu props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly MenuItem[]>` | `[]` | The commands; `onOpening` can give others per element. |
+| `target` | `Bind<Element \| Component \| null>` | its parent | Whose menu it is. Without it, the element the `ContextMenu` is placed in. |
+| `label` | `Bind<string>` | `''` | Names the menu for screen readers. |
+| `keyboard` | `Bind<boolean>` | `true` | The Menu key and Shift+F10 open it at the focused element. |
+| `closeOnScroll` | `Bind<boolean>` | `true` | Scrolling that takes the element it opened on out of sight closes it; until then the menu goes along with that element. |
+| `openOnHover` | `Bind<boolean>` | `true` | Pointing at an item opens its submenu. |
+| `enabled` | `Bind<boolean>` | `true` | `false`: the browser shows its own menu. |
+
+### Properties
+
+| Property | Access | Description |
+| --- | --- | --- |
+| `MenuBar.openItem` | read-only, reactive | The top item whose menu is open. |
+| `ContextMenu.opened` | read-only, reactive | Whether it is open. |
+| `ContextMenu.targetElement` | read-only, reactive | The element it was last opened on. |
+| `ContextMenu.target` | read/write, reactive | The element it listens on. |
+
+### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `MenuBar.open(item \| index)` | `boolean` | Opens a top item’s menu with focus on its first item. |
+| `MenuBar.close()` | `void` | Closes the open menu. |
+| `ContextMenu.open(at, target?)` | `boolean` | Opens it from code, at `{ x, y }` or at an element. |
+| `ContextMenu.close()` | `void` | Closes it. |
+| `MenuBar.refresh(), ContextMenu.refresh()` | `void` | Your items may be plain or reactive; the menu reads them as they are. After changing them in place, call `refresh()`. The bar, the open menu and its submenus follow. |
+| `attachContextMenu(target, items)` | `() => void` | Gives an element or component a menu; `items` can be a function of the opening (`e.target`). Returns the remover. |
+
+### Events
+
+| Event | When |
+| --- | --- |
+| `onItemClick(e)` | Both: an item was chosen, after its own `click`. |
+| `ContextMenu.onOpening(e)` | About to open. `e`: `{ target, items, cancel, byKeyboard, event, source }`; set `e.items` for the element, or `e.cancel = true`. |
+| `ContextMenu.onClosed(reason)` | `escape`, `outside`, `focus` or `code`. |

package/docs/numberbox.md

@@ -0,0 +1,309 @@
+# NumberBox
+
+> Editors · @motifx-community/ui 0.1.0-beta.0
+
+A number field: arrow keys, PageUp / PageDown and spin buttons that repeat while held, bounds, a step without float noise, a format for display (currency, percent) and typing in the locale’s own way.
+
+## Import
+
+```tsx
+import { NumberBox, type NumberBoxProps } from '@motifx-community/ui';
+```
+
+## From JSX and from code
+
+`x-model` binds a number (`null` when empty). Created with `new`, the same properties are set from code.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, NumberBox, Stack } from '@motifx-community/ui';
+
+const show = (value: number | null) => (value === null ? 'null' : String(value));
+
+/** A field bound to a number with x-model, and fields created with `new` and stepped from code. */
+export default function FromCode() {
+  const s = reactive({ quantity: 3 as number | null, log: '' });
+  let added = 0;
+  let host: Stack | null = null;
+
+  const addFromCode = () => {
+    const box = new NumberBox({ label: `Count ${++added}`, min: 0, max: 10, value: 5, locale: 'en' });
+    box.onValueChanged((e) => (s.log = `${box.label}: ${show(e.value)}`));
+    host?.controls.add(box);
+    box.stepUp();
+    box.focus();
+  };
+
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <NumberBox label="&Quantity" min={1} max={99} locale="en" x-model={() => s.quantity} />
+        <output class="nb-quantity">{() => `value: ${show(s.quantity)}`}</output>
+      </Stack>
+      <Stack orientation="horizontal" wrap align="center">
+        <Button text="Add a field from code" variant="outline" onclick={addFromCode} />
+        <output class="nb-log">{() => s.log}</output>
+      </Stack>
+      <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
+    </>
+  );
+}
+```
+
+## Steps and keys
+
+Up / Down add `step`, PageUp / PageDown add `largeStep` (10 × `step` by default), Home / End go to `min` / `max`. Steps are added on the decimal digits, so 0.1 + 0.2 is 0.3. With `wheel`, the mouse wheel steps while the field has focus.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { NumberBox } from '@motifx-community/ui';
+
+const show = (value: number | null) => (value === null ? 'null' : String(value));
+
+/** A step of 0.1 without float noise, and the mouse wheel stepping while the field has focus. */
+export default function Steps() {
+  const s = reactive({ rate: 0.1 as number | null });
+  return (
+    <>
+      <NumberBox label="Rate" step={0.1} min={0} max={5} wheel locale="en" x-model={() => s.rate} />
+      <output class="nb-rate">{() => `value: ${show(s.rate)}`}</output>
+    </>
+  );
+}
+```
+
+## Spin buttons
+
+Pressing a spin button steps once; holding it repeats until it is let go or a bound is reached. They sit on top of each other (`stacked`) or side by side (`inline`), or not at all.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, NumberBox, Stack, type SpinLayout } from '@motifx-community/ui';
+
+const LAYOUTS: SpinLayout[] = ['stacked', 'inline'];
+
+/** Spin buttons on top of each other, side by side, or none. */
+export default function SpinButtons() {
+  const s = reactive({ seats: 2 as number | null, layout: 'stacked' as SpinLayout, spin: true });
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center" role="group" aria-label="Spin buttons">
+        {LAYOUTS.map((layout) => (
+          <Button
+            key={layout}
+            text={layout}
+            size="sm"
+            variant={() => (s.spin && s.layout === layout ? 'solid' : 'ghost')}
+            aria-pressed={() => s.spin && s.layout === layout}
+            onclick={() => {
+              s.layout = layout;
+              s.spin = true;
+            }}
+          />
+        ))}
+        <Button text="none" size="sm" variant={() => (s.spin ? 'ghost' : 'solid')} aria-pressed={() => !s.spin} onclick={() => (s.spin = false)} />
+      </Stack>
+      <NumberBox label="Seats" min={1} max={9} locale="en" spinLayout={() => s.layout} showSpinButtons={() => s.spin} x-model={() => s.seats} />
+    </>
+  );
+}
+```
+
+## Format and locale
+
+Without focus the value shows through `Intl.NumberFormat` with `format` and `locale` (the page `lang` by default); with focus it turns into the plain number to edit. What is typed is read in that locale: `1.234,5` in Turkish, `1,234.5` in English; a `.` also works as the decimal point where it cannot be a group separator. A percent is edited as shown: 12.5 for 0.125.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { NumberBox, Stack } from '@motifx-community/ui';
+
+const show = (value: number | null) => (value === null ? 'null' : String(value));
+
+/** A Turkish lira price, a percent edited as shown, and US dollars. */
+export default function Format() {
+  const s = reactive({ price: 1234.5 as number | null, share: 0.125 as number | null, dollars: 99.99 as number | null });
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <NumberBox label="Price" locale="tr-TR" min={0} format={{ style: 'currency', currency: 'TRY' }} x-model={() => s.price} />
+        <output class="nb-price">{() => `value: ${show(s.price)}`}</output>
+      </Stack>
+      <Stack orientation="horizontal" wrap align="center">
+        <NumberBox label="Share" locale="en" min={0} max={1} step={0.01} format={{ style: 'percent', maximumFractionDigits: 1 }} x-model={() => s.share} />
+        <output class="nb-share">{() => `value: ${show(s.share)}`}</output>
+      </Stack>
+      <Stack orientation="horizontal" wrap align="center">
+        <NumberBox label="Amount" locale="en-US" format={{ style: 'currency', currency: 'USD' }} x-model={() => s.dollars} />
+        <output>{() => `value: ${show(s.dollars)}`}</output>
+      </Stack>
+    </>
+  );
+}
+```
+
+## Min, max and clamp
+
+An entered value outside `min` / `max` is brought inside when the field is left. With `clamp={false}` it stays as typed and the range check reports it.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { NumberBox } from '@motifx-community/ui';
+
+/** A value brought inside its bounds, and one left as typed for the range check to report. */
+export default function MinMaxClamp() {
+  const s = reactive({ score: 50 as number | null, age: null as number | null });
+  return (
+    <>
+      <NumberBox label="Score" min={0} max={100} locale="en" x-model={() => s.score} helpText="Try 250." />
+      <NumberBox label="Age" min={18} max={120} clamp={false} locale="en" x-model={() => s.age} helpText="Try 12." />
+    </>
+  );
+}
+```
+
+## Decimals and empty
+
+`decimals` rounds every value, the one given as well as the one entered, and shows exactly that many digits while the field is not edited (`72.50`); `format` can show them otherwise. An empty field is `null`; with `allowEmpty={false}` it gets `min` (or 0) when the field is left.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { NumberBox, Stack } from '@motifx-community/ui';
+
+const show = (value: number | null) => (value === null ? 'null' : String(value));
+
+/** Rounding to one decimal, and a field that cannot stay empty. */
+export default function DecimalsAndEmpty() {
+  const s = reactive({ weight: 72.456 as number | null });
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center">
+        <NumberBox label="Weight" decimals={1} step={0.1} suffix="kg" locale="en" x-model={() => s.weight} />
+        <output class="nb-weight">{() => `value: ${show(s.weight)}`}</output>
+      </Stack>
+      <NumberBox label="Guests" min={1} allowEmpty={false} locale="en" value={2} />
+    </>
+  );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Up / Down arrow` | Adds / takes away `step`. |
+| `PageUp / PageDown` | Adds / takes away `largeStep`. |
+| `Home / End` | Goes to `min` / `max` when they are set; otherwise moves the caret. |
+| `Enter` | Enters the typed text (rounded, kept in range) and fires `onEnter`. |
+| `Mouse wheel` | With `wheel`, steps while the field has focus. |
+| `Alt + key (`&Name`)` | Focus the field (Control + Option + key on Apple platforms). |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Role` | `spinbutton` on a text `<input inputmode="decimal">`, so phones show a number keyboard and any locale can be typed. |
+| `Value` | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` with the formatted value (`₺1.234,50`). |
+| `Spin buttons` | Named “Increase” / “Decrease” from `uiLocale`; not Tab stops (the arrow keys do their job). |
+| `Errors` | `aria-invalid="true"`; the message line is a polite live region. |
+
+## Localization
+
+The names of the spin buttons and the range messages come from `uiLocale.strings`; numbers follow `locale`.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { kitTexts } from '../../../shared/kit-texts';
+
+/** Switches the names of the spin buttons and the range messages. */
+export default function Localization() {
+  const s = reactive({ lang: 'en' });
+
+  const toggle = () => {
+    s.lang = s.lang === 'en' ? 'tr' : 'en';
+    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+  };
+
+  return (
+    <>
+      <Button text={() => (s.lang === 'en' ? 'Language: English' : 'Dil: Türkçe')} variant="outline" onclick={toggle} />
+      <span>
+        The up button reads <output class="nb-increase">{() => kitTexts.strings.increase}</output>
+      </span>
+    </>
+  );
+}
+```
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-field.mx-number-box` | The field. `data-spin` while the spin buttons show, and the field attributes. |
+| `.mx-number-box__spin` | The spin buttons; `data-layout="stacked" \| "inline"`. |
+| `.mx-number-box__step` | One spin button; `data-step="up" \| "down"`. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `number-box.spin, number-box.step, number-box.glyph` | Units: the spin buttons together (`stacked`, `inline`, `disabled`), each step (`up`, `down`, `next`, `hover`, `pressed`, `disabled`) and its glyph. |
+| `number-box.spin-layout, number-box.spin-order` | Where the steps stand (stacked at the end, or one on each side) and in which order. |
+| `number-box.spin-inset` | The space around the stacked spin buttons. |
+| `field.*` | Everything else, as for TextBox. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<number \| null>` | `null` | The number; `null` when empty. `x-model` binds it two-way. |
+| `min / max` | `Bind<number \| null>` | `null` | Bounds: steps stop there, Home / End go there, entered values are kept inside (see `clamp`), the range is checked. |
+| `step` | `Bind<number>` | `1` | What the arrow keys, the spin buttons and the wheel add. |
+| `largeStep` | `Bind<number>` | 10 × `step` | What PageUp / PageDown add. |
+| `showSpinButtons` | `Bind<boolean>` | `true` | The up and down buttons in the box. |
+| `spinLayout` | `Bind<SpinLayout>` | `'stacked'` | `stacked`: arrows on top of each other; `inline`: − and + side by side. |
+| `wheel` | `Bind<boolean>` | `false` | The mouse wheel changes the value while the field has focus. |
+| `format` | `Bind<Intl.NumberFormatOptions>` | `{}` | How the value shows without focus: `{ style: 'currency', currency: 'TRY' }`, `{ style: 'percent' }`, `{ minimumFractionDigits: 2 }`… |
+| `locale` | `Bind<string>` | the page `lang` | The locale of the format and of what is typed. |
+| `decimals` | `Bind<number \| null>` | `null` | Digits after the point: every value is rounded to them (half away from zero), wherever it comes from, and shown with exactly that many while the field is not edited. |
+| `clamp` | `Bind<boolean>` | `true` | A value outside `min` / `max` is brought inside when entered; `false` leaves it to the range check. |
+| `allowEmpty` | `Bind<boolean>` | `true` | An empty field is `null`; `false` puts `min` (or 0) in its place when the field is left. |
+| `updateOn` | `Bind<'input' \| 'change'>` | `'input'` | `input`: the value changes as soon as the text is a whole number in range; `change`: when the field is left or Enter is pressed. |
+| `placeholder` | `Bind<string>` | `''` | Shown while the field is empty. |
+| `selectOnFocus` | `Bind<boolean>` | `false` | Selects the whole text when the field gets focus. |
+| `align` | `Bind<'start' \| 'center' \| 'end'>` | `'start'` | Text alignment. |
+| `label, labelMode, helpText, hint, prefix, suffix, icon, buttons` | see TextBox |  | The parts every field has. |
+| `readOnly, required, size, variant, stretch` | see TextBox |  | The states and the look every field has. |
+| `rules, error, validateOn, validationGroup` | see TextBox |  | Validation, as for every field. |
+| `name, autocomplete` | `Bind<string>` | —, `'off'` | Passed to the `<input>`. |
+| `enabled / disabled, visible, tabStop, tabIndex` | see Control |  | The shared properties of every control. |
+
+### Properties
+
+| Property | Access | Description |
+| --- | --- | --- |
+| `every prop above` | read/write, reactive | A value or a function, like the prop. `locale` reads back the locale in use. |
+| `formattedValue` | read-only, reactive | The value as it shows without focus, `''` when empty. |
+| `isValid, validationMessage, validating` | read-only, reactive | The outcome of the checks. |
+| `inputElement` | read-only | The native `<input>`. |
+
+### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `stepUp(times = 1)` | `void` | Adds `step` × `times`, kept within `min` / `max`. |
+| `stepDown(times = 1)` | `void` | Takes `step` × `times` away. |
+| `validate()` | `Promise<boolean>` | Checks the value and shows the outcome. |
+| `resetValidation()` | `void` | Hides the outcome of earlier checks. |
+| `focus()` | `boolean` | Focuses the input. |
+| `select()` | `void` | Selects the whole text. |
+
+### Events
+
+| Event | When |
+| --- | --- |
+| `onValueChanged(e)` | The value changed. `e`: `{ value, previousValue, byUser, source, event? }`; a held spin button reports every step. |
+| `onValidated(e)` | A check ended. `e`: `{ valid, message, source }`. |
+| `onEnter(e)` | Enter was pressed. `e`: `{ value, source, event }`. |