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

package/docs/daterangebox.md

@@ -0,0 +1,192 @@
+# DateRangeBox
+
+> Editors · @motifx-community/ui 0.1.0-beta.3
+
+A start and an end date in one field: typed through two masks, or picked on two months side by side, from ready-made ranges, within the dates and the span allowed. The value is a `[start, end]` pair.
+
+## Import
+
+```tsx
+import { DateRangeBox, type DateRange } from '@motifx-community/ui';
+```
+
+## Declarative and programmatic
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, DateRangeBox, Stack, type DateRange } from '@motifx-community/ui';
+
+const say = (d: Date | null) => (d ? d.toLocaleDateString('en-GB') : '—');
+
+/** A range bound with x-model, and one made programmatically and read through its properties. */
+export default function Programmatic() {
+    const s = reactive({ stay: [new Date(2026, 2, 10), new Date(2026, 2, 14)] as DateRange, told: '' });
+    const coded = new DateRangeBox({ label: 'Report period', clearButton: true, onValueChanged: e => (s.told = `${say(e.value[0])} to ${say(e.value[1])}`) });
+
+    return (
+        <Stack gap="md">
+            <Stack orientation="horizontal" wrap align="center">
+                <DateRangeBox label="Stay" x-model={() => s.stay} clearButton />
+                <output class="dr-stay">{() => `${say(s.stay[0])} to ${say(s.stay[1])}`}</output>
+            </Stack>
+            <Stack orientation="horizontal" wrap align="center">
+                <span onConfig={c => c.controls.add(coded)} />
+                <Button text="This week" variant="outline" onclick={() => (coded.value = [new Date(2026, 2, 16), new Date(2026, 2, 22)])} />
+                <output class="dr-told">{() => s.told}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Presets
+
+`presets` puts ready-made ranges beside the calendars: `true` for the kit’s, or your own, each made when it is chosen. `calendars={1}` shows one month.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { DateRangeBox, Stack, type DateRange, type DateRangePreset } from '@motifx-community/ui';
+
+const day = (offset: number) => {
+    const d = new Date();
+    d.setHours(0, 0, 0, 0);
+    d.setDate(d.getDate() + offset);
+    return d;
+};
+
+// Ranges of our own, made when chosen so they are about today.
+const QUARTERS: DateRangePreset[] = [
+    { text: 'Next 3 days', range: () => [day(0), day(2)] },
+    { text: 'Next week', range: () => [day(1), day(7)] },
+    { text: 'Next 90 days', range: () => [day(0), day(89)] }
+];
+
+/** The kit's presets beside the calendars, and presets of your own. */
+export default function Presets() {
+    const s = reactive({ sales: [null, null] as DateRange, plan: [null, null] as DateRange });
+    return (
+        <Stack orientation="horizontal" wrap align="center">
+            <DateRangeBox label="Sales period" presets x-model={() => s.sales} />
+            <DateRangeBox label="Planning" presets={QUARTERS} calendars={1} x-model={() => s.plan} />
+        </Stack>
+    );
+}
+```
+
+## Limits
+
+`min`, `max` and `disabledDates` bound both ends, typed or picked; `minDays` and `maxDays` bound the span, and the calendars offer only the days within while the end is being picked. A failed rule says which.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, DateRangeBox, Stack, type DateRange } from '@motifx-community/ui';
+
+const today = new Date();
+const inMonths = (n: number) => new Date(today.getFullYear(), today.getMonth() + n, today.getDate());
+
+/** A stay of one to fourteen nights, within the next six months, never starting on a Sunday; the message says which rule failed. */
+export default function Limits() {
+    const s = reactive({ stay: [null, null] as DateRange, told: '' });
+    let box!: DateRangeBox;
+    return (
+        <Stack orientation="horizontal" wrap align="center">
+            <DateRangeBox
+                ref={(b: DateRangeBox) => (box = b)}
+                label="Stay"
+                min={today}
+                max={inMonths(6)}
+                minDays={1}
+                maxDays={14}
+                disabledDates={d => d.getDay() === 0}
+                required
+                x-model={() => s.stay}
+            />
+            <Button text="Check" variant="outline" onclick={() => void box.validate().then(ok => (s.told = ok ? 'Fine.' : box.validationMessage))} />
+            <output class="dr-check">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## With a time, and in another locale
+
+```tsx
+import { reactive } from '@motifx/core';
+import { DateRangeBox, Stack, type DateRange } from '@motifx-community/ui';
+
+/** Date and time on both ends: the time is typed after the date, the calendars keep it; one box in Turkish. */
+export default function DateTime() {
+    const s = reactive({ shift: [new Date(2026, 2, 10, 8, 30), new Date(2026, 2, 10, 17, 0)] as DateRange, trip: [null, null] as DateRange });
+    return (
+        <Stack orientation="horizontal" wrap align="center">
+            <DateRangeBox label="Shift" type="datetime" x-model={() => s.shift} displayFormat={{ dateStyle: 'short', timeStyle: 'short' }} />
+            <DateRangeBox label="Seyahat" locale="tr-TR" showWeekNumbers x-model={() => s.trip} startPlaceholder="gidiş" endPlaceholder="dönüş" />
+        </Stack>
+    );
+}
+```
+
+## Behaviour
+
+| Topic | How |
+| --- | --- |
+| `Typing` | Each side is a masked input in the locale’s order (`22.11.2006`); a whole, real date is taken as it is finished, an emptied side becomes `null`. Tab moves from the start to the end. |
+| `Picking` | On the popup the first pick is the start, the second the end: an earlier second pick becomes the start. With both chosen, the next pick starts a new range. While the end is being picked, the pointer shows the range it would make. |
+| `Two months` | The calendars show the start’s month and the next; paging one pages the other with it. |
+| `Presets` | A list beside the calendars; a press takes the range and closes. |
+| `Keyboard` | Alt+Down opens the popup; in it the calendars take the arrow keys, Enter picks; Escape closes, and clears the field when `clearButton` is on and the popup is closed. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Inputs` | Two text boxes named “<label>, Start date” and “<label>, End date” in the kit language; the field’s label marks the start. |
+| `Popup` | A dialog named “Choose date”; the calendars are the kit’s grids, the presets a list box. |
+| `Messages` | The rules speak in the kit language; a rule of your own in yours. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-date-range-box` | The field. `data-type`. |
+| `.mx-date-range-box__start, .mx-date-range-box__end, .mx-date-range-box__separator` | The inputs and the glyph between them. |
+| `.mx-date-range-box__toggle, .mx-date-range-box__clear` | The buttons in the box. |
+| `.mx-date-range-box__popup, .mx-date-range-box__calendar, .mx-date-range-box__presets` | The popup, each calendar, the presets. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `date-range-box.separator, .presets` | Units: the glyph between the inputs (`icon`, `bg`), the list of presets (`focus`, `beside`). |
+| `date-range-box.calendar` | Place: a calendar on the popup. |
+| `date-range-box.popup-gap` | Between the calendars and the presets. |
+| `calendar.cell range-start, range-end, range-single, range-in` | The calendar’s cells in a range: its ends and the days between, drawn by each language. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<DateRange>` | `[null, null]` | The `[start, end]` pair; either `null` while not chosen. `x-model` binds it two-way. |
+| `type` | `Bind<'date' \| 'datetime'>` | `'date'` | With `datetime` the time is typed after the date; the calendars keep it. |
+| `min, max, disabledDates` | `Bind<Date \| null>`, `Bind<(d: Date) => boolean>` | — | The dates allowed, on both ends, typed or picked. |
+| `minDays, maxDays` | `Bind<number \| null>` | `null` | The least and the most days a range may span, the end counted from the start; while the end is picked the calendars offer only days within. |
+| `presets` | `Bind<readonly DateRangePreset[] \| boolean>` | `false` | `true`: the kit’s ready-made ranges beside the calendars (today, yesterday, the last 7 and 30 days, this and last month); your own as `{ text, range: () => DateRange }`. |
+| `calendars` | `Bind<1 \| 2>` | `2` | Months side by side on the popup; two stay a month apart as one is paged. |
+| `closeOnComplete` | `Bind<boolean>` | `true` | The popup closes once both ends are picked. |
+| `locale, displayFormat, firstDayOfWeek, showWeekNumbers, showSeconds` |  |  | As on the `DateBox`. |
+| `startPlaceholder, endPlaceholder` | `Bind<string>` | `''` | Shown in an empty box. |
+| `clearButton, showPickerButton` | `Bind<boolean>` | `false`, `true` | The clear button; the button that opens the calendars. |
+| `label, helpText, required, rules, readOnly, size, variant…` |  |  | The field props, as on every editor. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `startDate, endDate` | `Date \| null` | The ends as properties of their own. |
+| `inputElement, endInputElement` | read-only | The start’s and the end’s inputs. |
+| `open(), close(), opened` | `boolean` / `void` | The popup with the calendars; `onOpened`, `onClosed`. |
+| `clear()` | `void` | Empties both ends. |
+| `validate(), validationMessage, isValid` |  | As on every field: an unfinished date, a date outside `min`, `max` or `disabledDates`, a start after the end, a span under `minDays` or over `maxDays`. |
+| `onValueChanged` | event | The pair changed (`value`, `previousValue`, `byUser`). |

package/docs/draggable.md

@@ -0,0 +1,194 @@
+# Draggable and DropTarget
+
+> Navigation · @motifx-community/ui 0.1.0-beta.3
+
+Anything the user moves with the pointer, a finger or the arrow keys, along an axis or inside a boundary, by a handle or as a copy; and the targets that take it. For items that change places in a list, see [Sortable](sortable.md).
+
+## Import
+
+```tsx
+import { Draggable, DropTarget } from '@motifx-community/ui';
+```
+
+## Moving things
+
+The JSX children are what moves. `boundary` keeps it inside its parent or an element, `axis` keeps it on a line, `handle` names the only part that takes the press and the keys. A drag writes the place to `x-model` and `onDragEnded` tells it; Escape brings it back.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Draggable, Panel, Stack } from '@motifx-community/ui';
+
+/** Three notes in a room: one moves anywhere inside it, one only sideways, one only by its grip; the keys move the focused one. */
+export default function Free() {
+    const s = reactive({ told: '' });
+    const note = (text: string, grip = false) => (
+        <Panel padding="sm" variant="outline" style="inline-size: 150px">
+            {grip && <span class="dg-grip">⋮⋮ </span>}
+            <span>{text}</span>
+        </Panel>
+    );
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <div class="dg-room" style="position: relative; block-size: 220px; outline: 2px dashed var(--mx-color-stroke-control-strong); outline-offset: -2px">
+                <Draggable class="dg-free" boundary="parent" style="position: absolute; left: 16px; top: 16px" onDragEnded={e => (s.told = `free: ${e.x}, ${e.y}`)}>
+                    {note('Anywhere in the room')}
+                </Draggable>
+                <Draggable class="dg-axis" axis="x" boundary="parent" style="position: absolute; left: 16px; top: 100px" onDragEnded={e => (s.told = `sideways: ${e.x}, ${e.y}`)}>
+                    {note('Only sideways')}
+                </Draggable>
+                <Draggable class="dg-handle" handle=".dg-grip" boundary="parent" style="position: absolute; left: 300px; top: 16px" onDragEnded={e => (s.told = `by the grip: ${e.x}, ${e.y}`)}>
+                    {note('Only by the grip', true)}
+                </Draggable>
+            </div>
+            <output class="dg-free-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Drop targets
+
+A `DropTarget` of the same `group` takes a draggable dropped on it and is told in `onDropped` with the draggable’s `data`; `onDragEntering` may refuse. With `clone` a copy follows the pointer and the draggable stays, so one thing can be dropped many times. What a drop does to your data is yours.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Draggable, DropTarget, Stack } from '@motifx-community/ui';
+
+const FRUIT = ['Apple', 'Pear', 'Plum'];
+
+/** Copies of the chips go to the bowls of their group; the small bowl refuses a third, and the data moves in `onDropped`. */
+export default function Targets() {
+    const s = reactive({ big: [] as string[], small: [] as string[], told: '' });
+    const bowl = (name: 'big' | 'small', limit: number) => (
+        <DropTarget
+            class={`dg-bowl dg-bowl-${name}`}
+            group="fruit"
+            grow
+            style="flex-basis: 0; min-block-size: 96px; padding: 12px; border: 1px solid var(--mx-color-stroke-divider); border-radius: var(--mx-radius-md)"
+            onDragEntering={e => (e.cancel = s[name].length >= limit)}
+            onDropped={e => {
+                s[name].push(e.data as string);
+                s.told = `${e.data} went to the ${name} bowl`;
+            }}
+        >
+            <strong>{name === 'big' ? 'Big bowl' : 'Small bowl, two at most'}</strong>
+            <div class="dg-bowl-list">{() => s[name].join(', ') || 'empty'}</div>
+        </DropTarget>
+    );
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Stack orientation="horizontal" gap="sm" wrap>
+                {FRUIT.map(fruit => (
+                    <Draggable class="dg-chip" clone group="fruit" data={fruit} style="padding: 6px 12px; border-radius: var(--mx-radius-full); border: 1px solid var(--mx-color-stroke-control-strong)">
+                        {fruit}
+                    </Draggable>
+                ))}
+            </Stack>
+            <Stack orientation="horizontal" gap="md">
+                {bowl('big', 99)}
+                {bowl('small', 2)}
+            </Stack>
+            <output class="dg-bowls-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Programmatic use
+
+`position` puts it where you say, in pixels from where it was laid out, and `x-model` takes the place back after every drag or key: kept and restored.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Draggable, Panel, Stack } from '@motifx-community/ui';
+
+/** The place goes out to x-model after every drag or key and comes back: moved, kept and restored programmatically. */
+export default function Programmatic() {
+    const s = reactive({ at: { x: 0, y: 0 } as { x: number; y: number } | null, kept: null as { x: number; y: number } | null });
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <div style="position: relative; block-size: 160px">
+                <Draggable class="dg-coded" boundary="parent" step={20} x-model={() => s.at} style="position: absolute; left: 0; top: 0">
+                    <Panel padding="sm" variant="outline" style="inline-size: 140px">
+                        Moved by the model
+                    </Panel>
+                </Draggable>
+            </div>
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Right by 40" variant="outline" onclick={() => (s.at = { x: (s.at?.x ?? 0) + 40, y: s.at?.y ?? 0 })} />
+                <Button text="Keep this place" variant="outline" onclick={() => (s.kept = s.at ? { ...s.at } : null)} />
+                <Button text="Restore it" variant="outline" enabled={() => !!s.kept} onclick={() => (s.at = s.kept ? { ...s.kept } : null)} />
+                <Button text="Back to the start" variant="outline" onclick={() => (s.at = { x: 0, y: 0 })} />
+                <output class="dg-coded-told">{() => `at: ${JSON.stringify(s.at)}`}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | The draggable (or its handle) is one stop. |
+| `Arrow keys` | Move it by `step` pixels along its axis, inside its boundary; the new place is read out. |
+| `Escape` | While dragging: lets go and brings it back where it started. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `The draggable` | A `group` with `aria-roledescription="draggable"` named “Move” in the kit language; with a `handle`, that element is a button of that name instead. |
+| `Dragging` | A long press lifts it on a touch screen. While it is dragged it lets the pointer through, so the target under it is found; the copy of a `clone` follows the pointer. |
+| `Targets` | Marked while a drag of their group is under way, while the draggable is over them, and when they refuse it. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-draggable` | The draggable. `data-dragging`, `data-handle`, `data-clone`, `data-axis`. |
+| `.mx-draggable__handle, .mx-draggable__ghost` | The handle named by `handle`; the copy after the pointer. |
+| `.mx-drop-target` | A target. `data-drop-active` during a drag of its group, `data-drop-over`, `data-drop-refused`. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `draggable.box, .handle, .ghost` | Units: the draggable (`draggable`, `dragging`, `focus`), its handle (`hover`, `focus`), the copy. |
+| `drop-target.target` | Unit: a target (`active`, `over`, `refused`). |
+
+## API reference
+
+### Draggable props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `axis` | `Bind<DragAxis>` | `'both'` | `both`, `x` or `y`. |
+| `boundary` | `Bind<'parent' \| HTMLElement \| null>` | `null` | The draggable stays inside this: its parent, or an element it lies in. |
+| `handle` | `Bind<string \| null>` | `null` | A selector inside the draggable: only a press there drags it, and it takes the Tab stop and the keys. |
+| `clone` | `Bind<boolean>` | `false` | A copy follows the pointer and the draggable stays where it is; for a drop target to take. |
+| `group` | `Bind<string \| null>` | `null` | Drop targets of the same group take it. |
+| `data` | `unknown` | — | Anything of your own, given to the drop target with the drop. |
+| `step` | `Bind<number>` | `10` | Pixels an arrow key moves it by. |
+| `position` | `Bind<DragPosition \| null>` | `null` | Where it stands, in pixels from where it was laid out: given, it is applied; after every drag or key the new place is written to `x-model`. |
+
+### DropTarget props and events
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `group` | `Bind<string \| null>` | `null` | Takes the draggables of this group; `null` takes those without one. |
+| `onDragEntering` | event | A draggable came over it (`draggable`, `data`); `cancel = true` refuses it. |
+| `onDragLeaving` | event | The draggable left it. |
+| `onDropped` | event | A draggable was dropped on it: your data is yours to move. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onDragStarting` | event | A drag is about to begin; `cancel = true` keeps it in place. |
+| `onDragging` | event | It is being dragged (`x`, `y`, the `target` under the pointer). |
+| `onDragEnding` | event | The pointer let go; `cancel = true` brings it back where it started. |
+| `onDragEnded` | event | The drag ended (`x`, `y`, `target`, `dropped`). |
+| `currentPosition` | read-only | Where it stands now. |
+| `isDragging` | read-only | A drag is under way. |
+| `handleElement` | read-only | What takes the press and the keys: the handle, else the draggable itself. |

package/docs/drawer.md

@@ -1,6 +1,6 @@
 # Drawer
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
 A panel that slides in from an edge of the page or of a container, over the content or pushing it aside. A finger swipes it in from the edge and back again; Escape, the scrim and the browser's back close it.
 

package/docs/dropdown.md

@@ -1,6 +1,6 @@
 # DropDown
 
-> Choice · @motifx-community/ui 0.1.0-beta.1
+> Choice · @motifx-community/ui 0.1.0-beta.3
 
 Picks one item from a list. The field shows the chosen item; the list opens below it with the keyboard or a press, can be searched, grouped and drawn your way, and stays fast with thousands of items.
 
@@ -10,9 +10,9 @@ Picks one item from a list. The field shows the chosen item; the list opens belo
 import { DropDown, type DropDownItem } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-`items` can be plain values; `x-model` binds the value. Created with `new`, the same properties are set from code.
+`items` can be plain values; `x-model` binds the value. Created with `new`, the same properties are set programmatically.
 
 ```tsx
 /** The cities the drop-downs of the examples show. */
@@ -156,14 +156,14 @@ The search box, the clear button, the empty list text, the wait (`loading`) and
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, DropDown, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, DropDown, uiLocale } from '@motifx-community/ui';
 
 /** Switches the texts of every drop-down on the page: the search box, the clear button, the empty list. */
 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;
+    void uiLocale.use(s.lang);
   };
   return (
     <>
@@ -249,20 +249,20 @@ The list is a shared part, `OptionList`, exported for combo boxes, list boxes an
 
 ## Example files
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, DropDown, Stack } from '@motifx-community/ui';
 import { cities } from './cities';
 
-/** Drop-downs bound with x-model, and drop-downs created with `new` and added from code. */
-export default function FromCode() {
+/** Drop-downs bound with x-model, and drop-downs created with `new` and added programmatically. */
+export default function Programmatic() {
   const form = reactive({ city: 'İzmir' as string | null, size: null as string | null, result: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const size = new DropDown<string, string>({ label: `Size ${++added}`, items: ['S', 'M', 'L'], placeholder: 'Pick one' });
     size.onValueChanged((e) => (form.result = `${size.label}: ${e.value}`));
     host?.controls.add(size);
@@ -277,7 +277,7 @@ export default function FromCode() {
       </Stack>
       <DropDown label="Size" items={['S', 'M', 'L', 'XL']} placeholder="Pick one" x-model={() => form.size} clearButton />
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a drop-down from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a drop-down programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="dd-made">{() => form.result}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />

package/docs/fileuploader.md

@@ -0,0 +1,201 @@
+# FileUploader
+
+> Editors · @motifx-community/ui 0.1.0-beta.3
+
+Files chosen with a button or dropped on the box, listed with their size and what happens to them: uploaded as they come, on a button or programmatically, with progress, cancel, retry and remove on each. Files outside the limits are listed with the reason.
+
+## Import
+
+```tsx
+import { FileUploader } from '@motifx-community/ui';
+```
+
+## Choosing, dropping, uploading
+
+`upload` is your own way to send a file: report progress, stop on the signal, resolve to the response. With `uploadUrl` instead, the uploader sends the file itself, in one piece or in chunks (`chunkSize`).
+
+```tsx
+import { reactive } from '@motifx/core';
+import { FileUploader, Stack } from '@motifx-community/ui';
+
+// Stands in for a server: takes two seconds per megabyte, reports as it goes, stops on the signal.
+const send = (file: File, report: (fraction: number) => void, signal: AbortSignal) =>
+    new Promise<string>((resolve, reject) => {
+        const steps = 20;
+        const wait = Math.max(600, Math.min(4000, (file.size / 1_000_000) * 2000)) / steps;
+        let step = 0;
+        const timer = setInterval(() => {
+            step++;
+            report(step / steps);
+            if (step === steps) {
+                clearInterval(timer);
+                resolve(`id-${file.name}`);
+            }
+        }, wait);
+        signal.addEventListener('abort', () => {
+            clearInterval(timer);
+            reject(new Error('stopped'));
+        });
+    });
+
+/** Files chosen or dropped go up as they come, through your own upload; each row shows progress, cancel, retry, remove. */
+export default function Basic() {
+    const s = reactive({ files: [] as readonly File[], told: '' });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <FileUploader
+                label="Attachments"
+                helpText="Any files; a stand-in server takes them."
+                upload={send}
+                x-model={() => s.files}
+                onUploaded={e => (s.told = `${e.file.name} is up as ${String(e.item.response)}.`)}
+                onUploadAborted={e => (s.told = `${e.file.name} was stopped.`)}
+            />
+            <output class="fu-told">{() => s.told || `${s.files.length} file(s) taken`}</output>
+        </Stack>
+    );
+}
+```
+
+## Limits
+
+```tsx
+import { reactive } from '@motifx/core';
+import { FileUploader, Stack } from '@motifx-community/ui';
+
+/** Only pictures and PDFs, up to 2 MB each and three in all; a file outside is listed with the reason. */
+export default function Limits() {
+    const s = reactive({ files: [] as readonly File[], refused: '' });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <FileUploader
+                label="Documents"
+                accept=".pdf,image/*"
+                maxFileSize={2_000_000}
+                maxFiles={3}
+                required
+                x-model={() => s.files}
+                onFilesAdded={e => (s.refused = e.refused.length ? e.refused.map(r => r.message).join(' ') : '')}
+            />
+            <output class="fu-refused">{() => s.refused}</output>
+        </Stack>
+    );
+}
+```
+
+## When files go up
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, FileUploader, Stack } from '@motifx-community/ui';
+
+const quick = (file: File, report: (fraction: number) => void) =>
+    new Promise<void>(resolve => {
+        let step = 0;
+        const timer = setInterval(() => {
+            report(++step / 10);
+            if (step === 10) {
+                clearInterval(timer);
+                resolve();
+            }
+        }, 120);
+    });
+
+/** An Upload button sends what was chosen; or nothing goes until code says so. One file only, no dropping. */
+export default function Modes() {
+    const s = reactive({ one: [] as readonly File[] });
+    let manual!: FileUploader;
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <FileUploader label="Photo" multiple={false} allowDrop={false} accept="image/*" upload={quick} uploadMode="button" x-model={() => s.one} />
+            <Stack orientation="horizontal" wrap align="center">
+                <FileUploader ref={(u: FileUploader) => (manual = u)} label="Logs" accept=".log,.txt" upload={quick} uploadMode="manual" />
+                <Button text="Send the logs" variant="outline" onclick={() => void manual.upload()} />
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Sending to a server
+
+The uploader posts a form with the file in `uploadField` (`file` by default) to `uploadUrl`, with `uploadHeaders`; a 2xx answer is the item’s `response`, JSON parsed when it is JSON. With `chunkSize` each piece carries `Content-Range` and the fields `chunkIndex` and `chunkCount`.
+
+```tsx
+<FileUploader
+  label="Attachments"
+  uploadUrl="/api/files"
+  uploadHeaders={{ Authorization: 'Bearer ' + token }}
+  chunkSize={1_000_000}
+  onUploaded={(e) => this.attachments.push(e.item.response as Attachment)}
+/>
+```
+
+## Behaviour
+
+| Topic | How |
+| --- | --- |
+| `Choosing` | The button opens the file dialog; files may be dropped on the box too, which lights up while they are over it. |
+| `Refusing` | A file outside `accept`, the sizes or `maxFiles` is listed as refused with the reason, and is not in the value. |
+| `Uploading` | As chosen, on the Upload button, or programmatically. A row shows the progress and a Cancel button meanwhile; afterwards “Uploaded”, or the failure with Retry. The server’s answer is the item’s `response` (JSON parsed). |
+| `Chunks` | With `chunkSize` the file goes in pieces, each a request with `Content-Range: bytes start-end/total`; progress runs over the whole. |
+| `Removing` | Each row has a remove button; a running upload is stopped first. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Button` | The select button is the field’s control: the label marks it, Space and Enter open the dialog. |
+| `List` | A list of rows: the name, the size and the state as text; the progress bar named after the file; the buttons named “Cancel the upload of …”, “Retry”, “Remove …”. |
+| `Messages` | The reasons a file was refused and the failures speak in the kit language, or in the server’s words. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-file-uploader` | The field. `data-dragover` while files are over it. |
+| `.mx-file-uploader__select, .mx-file-uploader__drop, .mx-file-uploader__upload` | The select button, the hint, the Upload button. |
+| `.mx-file-uploader__list, .mx-file-uploader__item` | The list and each row. `data-status` on the row. |
+| `.mx-file-uploader__icon, __name, __size, __state, __progress, __actions, __action` | The parts of a row. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `file-uploader.over, .select, .upload, .hint, .list, .item, .icon, .name, .size, .state` | Units: the box with files over it, the two buttons (`hover`, `pressed`, `focus`, `disabled`), the hint, the list, a row per status, the file glyph, the texts. |
+| `file-uploader.field, .action` | Places: the field’s box as a drop zone (a dashed frame, its corners, its padding); the row’s buttons. |
+| `file-uploader.box-gap, .button-gap, .item-gap` | The spaces in the box, in a button and in a row. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<readonly File[]>` | `[]` | The files taken (the refused ones are not in it). `x-model` binds it two-way. |
+| `multiple` | `Bind<boolean>` | `true` | Several files at once; `false` keeps one, the newest. |
+| `accept` | `Bind<string>` | `''` | What may be chosen, as for `<input type="file">`: `.png,.jpg`, `image/*`, `application/pdf`. |
+| `maxFileSize, minFileSize` | `Bind<number \| null>` | `null` | Bytes. A file outside is listed as refused, with the reason. |
+| `maxFiles` | `Bind<number \| null>` | `null` | How many files may be taken in all. |
+| `allowDrop` | `Bind<boolean>` | `true` | Files may be dropped on the box. |
+| `uploadMode` | `Bind<UploadMode>` | `instant` / `manual` | `instant`: as chosen; `button`: an Upload button; `manual`: `upload()` programmatically. Default `instant` with `uploadUrl` or `upload`, else `manual`. |
+| `uploadUrl, uploadMethod, uploadHeaders, uploadField` | `Bind<string \| null>`, … | `null`, `POST`, `null`, `file` | Where and how the uploader itself sends a file (XMLHttpRequest, with progress), as a form with the file in `uploadField`. |
+| `chunkSize` | `Bind<number \| null>` | `null` | Bytes per request: the file goes in pieces, each with its `Content-Range` and `chunkIndex` / `chunkCount` fields; the last answer is the response. |
+| `upload` | `(file, report, signal) => Promise<unknown>` | — | Your own upload instead of `uploadUrl`: call `report(0…1)` as it goes, stop on `signal`; what it resolves to is the response. |
+| `selectText, dropText, uploadText` | `Bind<string>` | the kit’s | The button, the hint beside it, the Upload button. |
+| `showFileList` | `Bind<boolean>` | `true` | The list of files under the box. |
+| `label, helpText, required, rules, readOnly, size, variant…` |  |  | The field props, as on every editor. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `items` | read-only | Every file in the list with what happened to it: `file`, `status` (`ready`, `uploading`, `done`, `error`, `aborted`, `invalid`), `progress`, `response`, `message`. |
+| `isUploading` | read-only | An upload is running. |
+| `openDialog()` | `void` | Opens the browser’s file dialog, as the button does. |
+| `addFiles(files)` | `void` | Takes files as if chosen: the limits apply, `onFilesAdded` is asked, uploads start as the mode says. |
+| `upload(item?)` | `Promise<void>` | Uploads the files waiting, or one of them; what `manual` mode calls. |
+| `abort(item?), remove(item), clear()` | `void` | Stops an upload (the file stays, cancelled); takes a file out; takes every file out. |
+| `onFilesAdded` | event | Files were chosen or dropped (`files`, `refused`); `cancel = true` takes none. |
+| `onFileRemoved, onUploadStarted, onProgress, onUploaded, onUploadError, onUploadAborted` | event | One file’s way through: each with `item` and `file`, a failure with `error`. |
+| `onValueChanged` | event | The files taken changed. |