@motifx-community/ui 0.1.0-beta.2 → 0.1.0-beta.3

package/docs/tileview.md

@@ -0,0 +1,206 @@
+# TileView
+
+> Display · @motifx-community/ui 0.1.0-beta.3
+
+Tiles of different sizes packed on a grid of base cells: a tile is so many cells wide and tall. They fill the height in columns and scroll sideways, or fill the width in rows; they can be chosen, and put in another order by dragging.
+
+## Import
+
+```tsx
+import { TileView } from '@motifx-community/ui';
+```
+
+## Tiles on a grid
+
+`baseItemWidth` and `baseItemHeight` are one cell; a tile’s `widthRatio` and `heightRatio` say how many it takes. Down the columns (`horizontal`, the default) the view needs a `height` and scrolls sideways; the tiles are packed so no cell stays empty where a later tile fits.
+
+```tsx
+import { TileView } from '@motifx-community/ui';
+
+/** Tiles of one, two and four base cells packed down the columns; the view scrolls sideways when they do not fit. */
+export default function Basic() {
+    return (
+        <TileView
+            class="tv-board"
+            label="Board"
+            height={330}
+            baseItemWidth={120}
+            baseItemHeight={100}
+            items={[
+                { text: 'Sales today', widthRatio: 2 },
+                { text: 'Orders' },
+                { text: 'Returns' },
+                { text: 'Visitors this week', widthRatio: 2, heightRatio: 2 },
+                { text: 'Stock' },
+                { text: 'Staff on duty', heightRatio: 2 },
+                { text: 'Tickets' },
+                { text: 'Deliveries', widthRatio: 2 },
+                { text: 'Reviews' },
+                { text: 'Costs' }
+            ]}
+        />
+    );
+}
+```
+
+## Choosing tiles
+
+`selectionMode` makes the tiles options: `single` keeps one, `multiple` any number (Ctrl and a press, or Space, adds and takes away). `value` is the chosen tile’s `key`, else its index, or a list of them; `x-model` binds it two-way. The arrow keys walk the grid by where the tiles lie.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Stack, TileView } from '@motifx-community/ui';
+
+/** Tiles along the rows, any number of them chosen: a press, Ctrl and a press, Space; the keys walk the grid. */
+export default function Selection() {
+    const s = reactive({ chosen: ['tea'] as string | number | null | readonly (string | number)[] });
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <TileView
+                class="tv-pick"
+                label="Snacks"
+                direction="vertical"
+                selectionMode="multiple"
+                baseItemWidth={110}
+                baseItemHeight={70}
+                x-model={() => s.chosen}
+                items={[
+                    { key: 'tea', text: 'Tea' },
+                    { key: 'coffee', text: 'Coffee' },
+                    { key: 'water', text: 'Water', enabled: false },
+                    { key: 'cake', text: 'Cake', widthRatio: 2 },
+                    { key: 'fruit', text: 'Fruit' },
+                    { key: 'nuts', text: 'Nuts' }
+                ]}
+            />
+            <output class="tv-pick-told">{() => `chosen: ${JSON.stringify(s.chosen)}`}</output>
+        </Stack>
+    );
+}
+```
+
+## Another order
+
+With `allowReorder` a tile is dragged to its new place (a long press on a touch screen) or moved with Ctrl and an arrow key. The tile moves and `onReordered` tells the indexes: reorder your data there, as the example does, so the next draw agrees.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Stack, TileView } from '@motifx-community/ui';
+
+/** Drag a tile to another place, or move it with Ctrl and an arrow key; the data is reordered in `onReordered`. */
+export default function Reorder() {
+    const s = reactive({ tiles: [{ text: 'Plan' }, { text: 'Design', widthRatio: 2 }, { text: 'Build' }, { text: 'Test' }, { text: 'Ship', heightRatio: 2 }, { text: 'Rest' }] });
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <TileView
+                class="tv-order"
+                label="Steps"
+                direction="vertical"
+                allowReorder
+                baseItemWidth={100}
+                baseItemHeight={70}
+                items={() => s.tiles}
+                onReordered={e => s.tiles.splice(e.toIndex, 0, ...s.tiles.splice(e.fromIndex, 1))}
+            />
+            <output class="tv-order-told">{() => s.tiles.map(t => t.text).join(', ')}</output>
+        </Stack>
+    );
+}
+```
+
+## Any content
+
+An item’s `content` makes the tile’s content when the tile is made; what is in it works as anywhere else, and a press on a button inside is that button’s. `onItemClick` tells a press on the tile itself.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, TileView } from '@motifx-community/ui';
+
+const ROOMS = [
+    { name: 'Kitchen', temp: 21 },
+    { name: 'Lounge', temp: 23 },
+    { name: 'Study', temp: 19 },
+    { name: 'Bedroom', temp: 18 }
+];
+
+/** Any content on a tile: a room each, with its own button; a press on the tile itself is told too. */
+export default function Content() {
+    const s = reactive({ told: '' });
+    const room = (r: (typeof ROOMS)[number]) => (
+        <Stack class="tv-room" gap="xs" justify="center" style="block-size: 100%">
+            <strong>{r.name}</strong>
+            <span class="tv-room-temp">{r.temp} °C</span>
+            <Button text="Warmer" variant="outline" size="sm" onclick={() => (s.told = `${r.name}: warmer`)} />
+        </Stack>
+    );
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <TileView class="tv-rooms" label="Rooms" direction="vertical" baseItemWidth={150} baseItemHeight={120} items={ROOMS.map(r => ({ key: r.name, content: () => room(r) }))} onItemClick={e => (s.told = `${(e.item as { key: string }).key} pressed`)} />
+            <output class="tv-rooms-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | One stop: the tile focused last, else the first chosen, else the first. |
+| `Arrow keys` | The nearest tile that way, by where the tiles lie; Home and End the first and the last. |
+| `Space` | Chooses the tile (`single`), or chooses it or lets it go (`multiple`). |
+| `Enter` | A press on the tile: `onItemClick`, and the choice as a press makes it. |
+| `Ctrl + Arrow keys` | With `allowReorder`: moves the tile a place back or on; Ctrl + Home and End to the ends. The move is read out. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Roles` | A `list` of `listitem`s without selection; a `listbox` of `option`s with it (`aria-multiselectable` for `multiple`), each `aria-selected`. |
+| `Disabled tiles` | `aria-disabled`, skipped by the keys, not chosen by a press. |
+| `Dragging` | A copy of the tile follows the pointer; the tile where the drop would land is marked; Escape lets go. On a touch screen a long press lifts the tile. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-tile-view` | The view. `data-direction`, `data-reorder`, `data-dragging` while a tile is dragged. |
+| `.mx-tile-view__tile` | A tile. `aria-selected`, `aria-disabled`, `data-dragging` (left faint in its place), `data-drop="before\|after"` where the drop would land. |
+| `.mx-tile-view__text, .mx-tile-view__ghost` | A tile’s text; the copy after the pointer. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `tile-view.tile, .text, .ghost, .view` | Units: a tile (`hover`, `pressed`, `focus`, `selected`, `disabled`, `dragging`, `target`), its text, the copy after the pointer, the view. |
+| `tile-view.gap` | Between the tiles. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly (TileViewItem \| string)[]>` | `[]` | The tiles in order: `TileViewItem`s (`text`, `widthRatio`, `heightRatio`, `key`, `content`, `enabled`, `data`) or plain texts. |
+| `baseItemWidth, baseItemHeight` | `Bind<number>` | `100` | A base cell in pixels; a tile is `widthRatio` × `heightRatio` of them. |
+| `direction` | `Bind<TileViewDirection>` | `'horizontal'` | `horizontal`: the tiles fill the height in columns and the view scrolls sideways (give it a `height`); `vertical`: they fill the width in rows. |
+| `selectionMode` | `Bind<TileViewSelectionMode>` | `'none'` | `none`, `single` or `multiple`. |
+| `value` | `Bind<string \| number \| null \| (string \| number)[]>` | `null` | The chosen tile (`single`): its `key`, else its index; the chosen tiles (`multiple`) as a list. `x-model` binds it two-way. |
+| `allowReorder` | `Bind<boolean>` | `false` | The tiles can be put in another order by dragging, or with Ctrl and an arrow key. |
+| `height` | `Bind<string \| number \| null>` | `null` | A CSS length or pixels. |
+| `label` | `Bind<string>` | the kit’s “Tiles” | What screen readers call it. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onItemClick` | event | A press on a tile that was not a drag (`index`, `item`, `event`); Enter on a focused tile too. |
+| `onSelectionChanged` | event | The chosen tiles changed (`indexes`, `items`, `byUser`). |
+| `onReordering` | event | A tile is about to be dragged or moved with the keys (`fromIndex`, `toIndex`); `cancel = true` keeps it. |
+| `onReordered` | event | A tile was dropped or moved to a new place (`item`, `fromIndex`, `toIndex`): your data is yours to reorder. |
+| `selectedIndexes` | read-only | The chosen tiles’ indexes, in tile order. |
+| `count` | read-only | How many tiles there are. |
+| `isDragging` | read-only | A tile is being dragged. |
+| `select(index)` | `void` | Chooses a tile programmatically: the only one (`single`), or one more (`multiple`). |
+| `indexOf(value), valueAt(index)` | `number`, `string \| number` | Between a value (a key or an index) and a tile’s index. |
+| `refresh()` | `void` | Reads the items again after they were changed in place. |

package/docs/timeline.md

@@ -0,0 +1,174 @@
+# Timeline
+
+> Display · @motifx-community/ui 0.1.0-beta.3
+
+Events in time order: down the page, each a card beside a line with a dot; or along a line of dates, where a press on a date shows that event’s card under the line. The dates are written in the kit’s language. For hours on a calendar, see the [Scheduler](scheduler.md).
+
+## Import
+
+```tsx
+import { Timeline } from '@motifx-community/ui';
+```
+
+## Down the page
+
+`items` are the events: a `date`, a `title`, a `description`, a `tone` for the dot and a `glyph` in it. `alternate` puts the cards on either side of the line in turn; `collapsible` folds the descriptions until a card is pressed. `onItemClick` tells a press.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, Timeline } from '@motifx-community/ui';
+
+/** A project down the page: a dot per event on the line, coloured by its tone; the cards take turns or fold when told. */
+export default function Vertical() {
+    const s = reactive({ alternate: false, collapsible: false, told: '' });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Take turns" variant="outline" toggle x-model={() => s.alternate} />
+                <Button text="Fold the cards" variant="outline" toggle x-model={() => s.collapsible} />
+                <output class="tl-told">{() => s.told}</output>
+            </Stack>
+            <Timeline
+                class="tl-project"
+                label="The project"
+                alternate={() => s.alternate}
+                collapsible={() => s.collapsible}
+                onItemClick={e => (s.told = `pressed: ${(e.item as { title: string }).title}`)}
+                items={[
+                    { date: '2026-01-12', title: 'Kick-off', description: 'The team met and the scope was agreed.', glyph: 'calendar' },
+                    { date: '2026-02-20', title: 'Design signed off', description: 'Five languages, every state measured.', tone: 'info', glyph: 'pencil' },
+                    { date: '2026-04-03', title: 'Beta', description: 'The first users came in; two slow screens were found.', tone: 'accent', glyph: 'person' },
+                    { date: '2026-05-15', title: 'Slow screens fixed', description: 'The grid draws only what is in view.', tone: 'caution' },
+                    { date: '2026-06-30', title: 'Shipped', description: 'Version one, on time.', tone: 'success', glyph: 'check' }
+                ]}
+            />
+        </Stack>
+    );
+}
+```
+
+## Along a line of dates
+
+`orientation='horizontal'` puts the dates on a line that scrolls with the buttons at its ends; the shown event (`value`, `x-model`) has its card under the line. The arrow keys move along the dates. `dateFormat` takes the options of `Intl.DateTimeFormat`.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Stack, Timeline } from '@motifx-community/ui';
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+
+/** Releases along a line of dates: a press on a date, or the arrow keys, shows that release under the line; the buttons scroll the track. */
+export default function Horizontal() {
+    const s = reactive({ shown: 'r3' as string | number | null });
+    const releases = MONTHS.map((month, i) => ({
+        key: `r${i + 1}`,
+        date: new Date(2026, i, 15),
+        title: `Release ${i + 1}`,
+        description: `What ${month} brought: ${i % 3 === 0 ? 'new components' : i % 3 === 1 ? 'fixes and speed' : 'the docs and the languages'}.`,
+        tone: i % 3 === 0 ? ('accent' as const) : ('default' as const),
+        glyph: i % 3 === 0 ? 'star' : ''
+    }));
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Timeline class="tl-releases" label="Releases" orientation="horizontal" dateFormat={{ month: 'short', year: 'numeric' }} items={releases} x-model={() => s.shown} />
+            <output class="tl-releases-told">{() => `shown: ${s.shown}`}</output>
+        </Stack>
+    );
+}
+```
+
+## Any content
+
+An item’s `content` makes what goes in its card besides the texts; `icon` puts an icon of your own in the dot. A date with a time is written with it when `dateFormat` says so.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, Timeline } from '@motifx-community/ui';
+
+/** Any content in a card: a button to act on the event, an icon of your own in the dot. */
+export default function Content() {
+    const s = reactive({ told: '' });
+    const act = (what: string) => (
+        <Stack orientation="horizontal" gap="sm">
+            <Button text={what} variant="outline" size="sm" onclick={() => (s.told = `${what} pressed`)} />
+        </Stack>
+    );
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Timeline
+                class="tl-orders"
+                label="An order"
+                items={[
+                    { date: '2026-11-02T09:15:00', title: 'Order placed', description: 'Three items, paid by card.', tone: 'info', content: () => act('See the invoice') },
+                    { date: '2026-11-03T14:40:00', title: 'Packed', tone: 'accent', glyph: 'columns' },
+                    { date: '2026-11-04T08:00:00', title: 'On its way', description: 'Handed to the courier.', content: () => act('Track it') },
+                    { date: '2026-11-05T16:25:00', title: 'Delivered', tone: 'success', glyph: 'check', content: () => act('Rate it') }
+                ]}
+                dateFormat={{ dateStyle: 'medium', timeStyle: 'short' }}
+            />
+            <output class="tl-orders-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | Vertical: the cards that fold are stops, one each. Horizontal: the shown date is the one stop; the track’s buttons are stops too. |
+| `Arrow keys` | Horizontal: Left and Right (the other way round in a right-to-left page) show the event before or after; Home and End the first and the last. |
+| `Enter, Space` | On a folding card: unfolds or folds it. On a date: shows it. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Down the page` | A `list` named by `label`, one item per event; a date is a `time` element with its ISO value; a folding card is a button with `aria-expanded` over its description. |
+| `Along the line` | The dates are tabs (`tablist`, `tab`, `aria-selected`) and the card under them the `tabpanel` they control; the buttons at the ends are named “Earlier” and “Later”. |
+| `Dots and glyphs` | Decorative; the tone shows in colour only, so put what matters in the title. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-timeline` | The timeline. `data-orientation`, `data-alternate`. |
+| `.mx-timeline__list, .mx-timeline__item` | The list (the line is its `::before`) and an event (`data-tone`, `data-side`, `data-expanded`, `data-selected`). |
+| `.mx-timeline__dot, .mx-timeline__dot-glyph, .mx-timeline__dot-icon` | The dot and what is in it. |
+| `.mx-timeline__card, .mx-timeline__flag, .mx-timeline__detail` | A card down the page, a date along the line, the card under the line. |
+| `.mx-timeline__date, .mx-timeline__title, .mx-timeline__description, .mx-timeline__content` | The texts and the content of your own. |
+| `.mx-timeline__track, .mx-timeline__nav, .mx-timeline__nav-glyph` | The track that scrolls, its buttons and their arrows. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `timeline.line, .dot, .dot-glyph, .card, .flag, .date, .title, .description, .detail, .nav, .nav-glyph` | Units: the line, a dot and its glyph (by tone), a card (`pressable`, `hover`, `pressed`, `focus`, `expanded`), a flag (`hover`, `pressed`, `focus`, `selected`), the texts, the detail, the track buttons. |
+| `timeline.gap, .dot-gap, .track-gap, .row-gap, .mark-size, .line-thickness` | Between events, between a dot and its card, between flags, between the track and the detail; the dot’s size; the line’s thickness. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly TimelineItem[]>` | `[]` | The events in order: `date` (a `Date`, an ISO text or milliseconds), `title`, `description`, `glyph` or `icon`, `tone`, `content`, `key`, `data`. |
+| `orientation` | `Bind<TimelineOrientation>` | `'vertical'` | `vertical`: down the page, a card per event; `horizontal`: along a line of dates, the shown event’s card under it. |
+| `alternate` | `Bind<boolean>` | `false` | Vertical: the cards take turns on either side of the line. |
+| `collapsible` | `Bind<boolean>` | `false` | Vertical: a card shows its description only when pressed. |
+| `dateFormat` | `Bind<TimelineDateFormat>` | `'medium'` | `short`, `medium`, `long`, or the options of `Intl.DateTimeFormat`; written in the kit’s language. |
+| `value` | `Bind<string \| number \| null>` | `0` | Horizontal: the event whose card is shown, its `key` else its index. `x-model` binds it two-way. |
+| `label` | `Bind<string>` | the kit’s “Timeline” | What screen readers call it. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onItemClick` | event | A press on an event’s card or flag (`index`, `item`). |
+| `onSelectionChanged` | event | Horizontal: the shown event changed (`index`, `item`, `previous`, `byUser`). |
+| `selectedIndex` | read-only | Horizontal: the index of the shown event; -1 when there is none. |
+| `count` | read-only | How many events there are. |
+| `goTo(event)` | `boolean` | Horizontal: shows an event by index or key; vertical: unfolds its card. |
+| `unfold(event, on), isUnfolded(event)` | `void`, `boolean` | Vertical, `collapsible`: unfolds or folds a card; whether it is unfolded. |
+| `formatDate(date)` | `string` | A date as the timeline writes it. |
+| `refresh()` | `void` | Reads the items again after they were changed in place. |

package/docs/toast.md

@@ -1,8 +1,8 @@
 # Toast
 
-> Feedback · @motifx-community/ui 0.1.0-beta.2
+> Feedback · @motifx-community/ui 0.1.0-beta.3
 
-Short notifications at an edge of the window: four tones, an action such as Undo, a time of their own or none, six positions and a limit on how many show at once. Called from code; a region of your own can sit in JSX.
+Short notifications at an edge of the window: four tones, an action such as Undo, a time of their own or none, six positions and a limit on how many show at once. Called programmatically; a region of your own can sit in JSX.
 
 ## Import
 
@@ -10,7 +10,7 @@ Short notifications at an edge of the window: four tones, an action such as Undo
 import { toast, Toast, Toaster, type ToastTone, type ToastPosition } from '@motifx-community/ui';
 ```
 
-## From code and from JSX
+## Programmatic and declarative
 
 `toast.show()` and its tone shortcuts return the `Toast`, an object you can `close()`, `update()` or await. They use `Toaster.default`, made in `document.body` the first time; an app can put a `Toaster` of its own where it wants it in JSX and make it the default.
 
@@ -18,8 +18,8 @@ import { toast, Toast, Toaster, type ToastTone, type ToastPosition } from '@moti
 import { reactive } from '@motifx/core';
 import { Button, toast, type Toast } from '@motifx-community/ui';
 
-/** Toasts shown from code: the Toast that comes back can be closed and awaited. */
-export default function FromCode() {
+/** Toasts shown programmatically: the Toast that comes back can be closed and awaited. */
+export default function Programmatic() {
   const s = reactive({ reason: '' });
 
   const exportFile = () => {