@scattered-light/loomiere-base-ui 0.6.1 → 0.7.0

package/README.md

@@ -29,13 +29,143 @@ Use Base UI as usual, with the class names the styles target, or the few wrapper
 
 ```tsx
 import {
-  Accordion, AlertDialog, Autocomplete, Avatar, Button, Checkbox, CheckboxGroup, Collapsible,
-  Combobox, ContextMenu, Dialog, Drawer, Field, Form, Input, Menu, Menubar, Meter, NumberField,
-  OTPField, Popover, PreviewCard, Progress, Radio, ScrollArea, Select, Separator, Slider, Switch,
-  Tabs, Toast, Toggle, ToggleGroup, Toolbar, Tooltip,
+  Accordion, AlertDialog, Autocomplete, Avatar, Badge, Button, Calendar, Checkbox, CheckboxGroup, Collapsible,
+  Combobox, ContextMenu, DatePicker, DatePresets, Dialog, Drawer, EmptyState, Field, Form, Input, ListDetail, Menu, Menubar, Meter, MoneyField, NumberField,
+  OTPField, Popover, PreviewCard, Progress, Radio, ScrollArea, Select, Separator, Slider, Splitter, Switch,
+  Tabs, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, useListDetail,
 } from '@scattered-light/loomiere-base-ui';
 ```
 
 ## Base UI version
 
-The styles are written against Base UI `baseUi.target` in [package.json](package.json) (1.9.0), and the peer dependency starts there. Every published CSS file names that release in its first line. `npm run check:base-ui` fails if an older Base UI is installed and warns if a newer minor one is.
+The styles are written against Base UI `baseUi.target` in [package.json](package.json) (1.9.0), and the peer dependency starts there. Every published CSS file names that release in its first line. `npm run check:base-ui` fails if an older Base UI is installed and warns if a newer minor one is. That check, and `baseUi.target`, cover Base UI parts only. Custom components are left out of it. Check MoneyField when Number Field changes: it is built on `NumberField.Root`, and a new root prop should keep working without a change here. Money field's default maximum is `10^15 - 1` minor units. A major amount with more than 15 significant digits is not exact as a float, and Number field counts in floats. `formatMoney` passes the exact decimal string to `Intl.NumberFormat`. Number field 1.9 leaves a controlled input showing the typed text on blur when the number did not change (`12.5` stays `12.5` instead of `1,234.50`). Money field rewrites that text after Number field's layout effect, without remounting. Drop the rewrite when Number field formats this case itself. Check Collection when Checkbox, Tabs, Select or Menu change. Check Collection when the `@tanstack/react-table` major changes.
+
+## Custom components
+
+A custom component is one Base UI does not have. It is built here from concepts and tokens that already exist (emphasis, status, type, space), not as a new package. React lives in `src/custom/`, CSS in `styles/custom/`. Both export from the package root and from `@scattered-light/loomiere-base-ui/custom`. Table is custom too: plain HTML, with no React wrapper. A Badge that is only a number needs an accessible name: `aria-label` (for example "3 unread") or visually hidden text. Collection is the exception to the main export: it lives at `@scattered-light/loomiere-base-ui/custom/collection` so an app that only imports Badge does not have to install TanStack.
+
+### DatePicker
+
+A field that opens a calendar for one date or a period. The developer sets `mode`. The person using it cannot switch. `Calendar` is the month grid on its own. `DatePresets` is the quick-selection list. The preset `today` is the quick selection; `todayDate()` is the local calendar day.
+
+| Prop | What it does |
+| --- | --- |
+| `mode` | `single` or `range`. Defaults to `single`. |
+| `value`, `defaultValue`, `onValueChange` | An ISO date, or `{ start, end }` for a range. `null` clears a single date. |
+| `defaultMonth` | The month to open on when there is no value yet. Any day in that month. |
+| `months` | `1`, `2`, `3`, or `auto` (2 for a range, 1 for a single date). The panel can only show fewer: one month under 32rem, in a drawer, or for a coarse pointer under 48rem; at most two under 40rem. |
+| `min`, `max` | Inclusive ISO dates. Days outside them stay visible and disabled. |
+| `isDateDisabled` | Extra days to disable, such as weekends. |
+| `minLength`, `maxLength` | Inclusive length of a range. |
+| `presets` | `true` (the default list), `false`, or your own. |
+| `weekStartsOn` | `0` Sunday through `6` Saturday. The locale decides when this is omitted. |
+| `locale`, `showOutsideDays`, `showWeekNumbers` | Formatting, trailing days, and ISO week numbers. |
+| `commit` | `immediate` writes as soon as a day is picked. `apply` keeps a draft until Apply or Cancel. The default is immediate for one date and apply for a range. |
+| `clearable`, `placeholder`, `formatValue` | The trigger. |
+| `name`, `nameStart`, `nameEnd`, `required` | Submitted through a visually hidden input so `required` and `Field` validation see the value. |
+| `disabled`, `readOnly` | Disabled leaves the tab order. Read-only stays focusable, announces the value, and does not open. |
+| `open`, `defaultOpen`, `onOpenChange`, `popup` | `popup` is `auto`, `popover`, or `drawer`. |
+| `label` | Names the trigger and the dialog when there is no `Field.Label`. The value is described, not part of the name. |
+
+A range is a start click, then an end click. An end before the start swaps. Clicking the start again makes a one-day range. Hover or focus previews the band until the end is chosen; the preview is not announced as selected. Immediate mode writes `{ start, end: null }` on the first click and leaves the popup open, then writes the finished range and closes on the second click. Apply mode keeps that draft until Apply or Cancel.
+
+Escape on a half-picked range clears the start and stays open. A second Escape closes. Escape in the month or year chooser returns to the days. Clicking outside, or any other close, throws the draft away and shows the committed value again. In immediate mode the half range is already committed, so that close keeps it.
+
+Page Down with two months showing shifts the view by one month, so the focused day lands in the last column. Direction is read when the popup opens. A `dir` change while it is open is not picked up.
+
+When you add one:
+
+- Add `src/custom/<name>.tsx` and `styles/custom/<Name>.css`, and import the CSS from `styles/index.css` in the custom block (after the Base UI imports).
+- Export it from `src/index.ts` and `src/custom/index.ts`.
+- List it in `build/build-design-system.mjs`: `GROUPS`, `WRAPPERS` when it has a React component, and `CUSTOM`.
+- Add it to the brand book in `packages/loomiere/exporters/design-system.mjs`: the wrappers sentence, the "which component for what" list, and the custom-components line.
+- Add `src/stories/components/<Name>.stories.tsx` (`autodocs`, `ds:lib`). The default story is the Design System preview.
+- Mark it included in `src/stories/OverviewChecklist.stories.jsx` and `src/stories/README.md`.
+- If MUI or Chakra already has the component, point that override at the same variables through `exporters/component-styles.mjs`.
+- If it paints with `--sl-e-*`, give its default level a selector in `DEFAULT_LEVELS` (`packages/loomiere/build/build-tokens.mjs`).
+- Add a Figma page script under `packages/loomiere/figma/library/pages/` and a step in `run-order.json`. Leave `check/mojave.json` until that page has been built in Figma.
+
+### Splitter
+
+A window splitter. The handle is a separator you drag or move with the arrow keys. One panel has no size and fills what the others leave. Sizes can mix pixels and percent. `id` is the panel's key in storage and in a controlled `layout`. The DOM id is that key prefixed with the splitter's `useId`, so two splitters can both name a panel `main`, and `aria-controls` points at the element. Pass `layout` to control the sizes: the component renders from it and only reports changes. Children are `Splitter.Panel` and `Splitter.Handle`. A Fragment is flattened (a `.map()` can return one). Any other child throws in development, because a wrapper would hide its panel. Escape during a drag puts the sizes back.
+
+```tsx
+<Splitter.Root orientation="horizontal" storageKey="workstation">
+  <Splitter.Panel id="nav" defaultSize="240px" minSize="180px" maxSize="400px" collapsible />
+  <Splitter.Handle aria-label="Resize navigation" />
+  <Splitter.Panel id="main">…</Splitter.Panel>
+</Splitter.Root>
+```
+
+### ListDetail
+
+The detail of one selected item. Wide, it is a Splitter. Narrow, the detail opens in a Drawer, or replaces the list. The list stays in the first panel the whole time, so its scroll survives opening, closing, and the width change. The app keeps the selected id. `useListDetail()` returns the layout and a `close()`. `headingLevel` is the detail heading in every layout, including the drawer. `listLabel` names the list as a region.
+
+```tsx
+<ListDetail.Root open={!!selectedId} onOpenChange={(open) => !open && setSelectedId(null)} storageKey="register">
+  <ListDetail.List>
+    <table className="Table">…</table>
+  </ListDetail.List>
+  <ListDetail.Detail title="Transaction 1042" closeDisabled={dirty}>…</ListDetail.Detail>
+</ListDetail.Root>
+```
+
+### EmptyState
+
+The block a page, pane, table, list or popup shows when it has nothing to show. `kind` picks the default icon, the media tone and whether a screen reader hears it. The title is required. Everything else is optional, so a title on its own is a valid empty state. It does not choose button emphasis: the first action is the main one (`bold` for `start`, `standard` for the other kinds) and a secondary action is `quiet`. `Media` and `Title` read `kind` and `size` from the root. Their own props override that. The announcement is a visually hidden live region that starts empty and fills one frame later, so the words are a change. `done` stays quiet on the render that mounts it, and is read when the kind becomes `done` after that.
+
+```tsx
+<EmptyState
+  kind="no-results"
+  title="No transactions match"
+  description="Try a different date range, or clear the filters."
+  actions={<Button emphasis="standard" onClick={clearFilters}>Clear filters</Button>}
+/>
+```
+
+A filtered table keeps its header. The empty row does not hover:
+
+```tsx
+<tr>
+  <td data-empty colSpan={4}>
+    <EmptyState size="compact" kind="no-results" title="No transactions match" />
+  </td>
+</tr>
+```
+
+`Combobox.Empty`, `Autocomplete.Empty` and `Menu.Empty` stay the popup's own slots. Put a compact empty state inside one:
+
+```tsx
+<Combobox.Empty>
+  <EmptyState size="compact" kind="no-results" title="No fruits match" />
+</Combobox.Empty>
+```
+
+### Collection
+
+Install the peer, then import the views from their own entry. `EditableList` does not need it, and comes from `./custom` like Badge.
+
+```
+npm install @tanstack/react-table
+```
+
+```tsx
+import { DataList, DataTable, CollectionToolbar, CollectionPagination, defineColumns, useCollection } from '@scattered-light/loomiere-base-ui/custom/collection';
+import { EditableList } from '@scattered-light/loomiere-base-ui/custom';
+```
+
+`useCollection` holds search, sort, filters, selection, grouping, paging, and column order and visibility. DataTable and DataList render that same state. Switch views by changing the component. The plain `<table class="Table">` is unchanged, for static tables and reports.
+
+Columns decide how a value sorts, searches, filters and totals. `rowHeader` names the row. One column may use a tabs filter. Money totals add in minor units. Search is deferred, not debounced.
+
+The toolbar keeps the tabs and the search while rows are selected, and swaps the trailing controls for the selection bar, so the bar does not push the search down. A list sorts from the toolbar. A table sorts from its headers. Sort cycles ascending, descending, then back to the system's default.
+
+Keyboard, on a table or a list, when a row can be activated: the row-header buttons are one tab stop. Up and Down move between rows. Home and End go to the first and last row on the page. Space toggles that row's checkbox. Enter activates the row. Escape clears the search when it has text. Arrow keys do nothing while focus is in a field inside a cell. This is a data table, not a grid.
+
+State attributes on the view: `data-sorted`, `data-filtered`, `data-selecting`, `data-loading`, `data-grouped`, `data-view` (`table` or `list`), `data-size` (`sm` or `md`).
+
+A tree stays a data table. The row header's accessible name carries the level ("Cash, level 2, in Assets"). It is not a treegrid. ArrowRight opens a closed parent and ArrowLeft closes an open one, swapped in right-to-left. Totals add leaf rows only, so a parent's amount is not added again. A click on `[data-no-activate]` does not activate the row.
+
+EditableList can take `defaultValue` with no `value`. `itemLabel` names one row ("Allocation"). Pass `EditableList.useField(column)`'s `id` and `aria-labelledby` to the input, including a Select or MoneyField that draws its own input. `name` writes hidden inputs for primitive fields other than `id`, or for the keys in `fields`. Do not combine `name` with fields the app names itself.
+
+Not built, and the state is ready for the first three: user column show/hide and reorder, row reorder, inline cell editing, virtualization, multi-sort, column resize. EditableList has no move-up or drag yet; those buttons would sit in the row, ahead of any drag handle.