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

package/docs/datebox.md

@@ -1,6 +1,6 @@
 # DateBox
 
-> Editors · @motifx-community/ui 0.1.0-beta.2
+> Editors · @motifx-community/ui 0.1.0-beta.3
 
 A date, a time or both. It is typed in the order of the locale through a mask, or picked from a calendar and a list of times; `min`, `max` and `disabledDates` limit both ways.
 
@@ -10,7 +10,7 @@ A date, a time or both. It is typed in the order of the locale through a mask, o
 import { DateBox } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -18,13 +18,13 @@ import { Button, DateBox, Stack } from '@motifx-community/ui';
 
 const today = new Date();
 
-/** A date box bound with x-model, and date boxes created with `new`, given a value and added from code. */
-export default function FromCode() {
+/** A date box bound with x-model, and date boxes created with `new`, given a value and added programmatically. */
+export default function Programmatic() {
   const order = reactive({ delivery: new Date(today.getFullYear(), today.getMonth(), today.getDate() + 3) as Date | null, result: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const due = new DateBox({ label: `Due ${++added}`, locale: 'tr-TR', clearButton: true });
     due.value = new Date(2026, 9, 25);
     due.onValueChanged((e) => (order.result = `${due.label}: ${e.value ? e.value.toDateString() : '—'}`));
@@ -36,7 +36,7 @@ export default function FromCode() {
     <>
       <DateBox label="&Delivery" x-model={() => order.delivery} clearButton />
       <output class="db-day">{() => (order.delivery ? order.delivery.toDateString() : '—')}</output>
-      <Button text="Add a date box from code" variant="outline" onclick={addFromCode} />
+      <Button text="Add a date box programmatically" variant="outline" onclick={addProgrammatic} />
       <output class="db-made">{() => order.result}</output>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
     </>

package/docs/daterangebox.md

@@ -1,6 +1,6 @@
 # DateRangeBox
 
-> Editors · @motifx-community/ui 0.1.0-beta.2
+> 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.
 
@@ -10,7 +10,7 @@ A start and an end date in one field: typed through two masks, or picked on two
 import { DateRangeBox, type DateRange } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -18,8 +18,8 @@ import { Button, DateRangeBox, Stack, type DateRange } from '@motifx-community/u
 
 const say = (d: Date | null) => (d ? d.toLocaleDateString('en-GB') : '—');
 
-/** A range bound with x-model, and one made from code and read through its properties. */
-export default function FromCode() {
+/** 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])}`) });
 

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.2
+> 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.2
+> 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. */
@@ -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

@@ -1,8 +1,8 @@
 # FileUploader
 
-> Editors · @motifx-community/ui 0.1.0-beta.2
+> 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 from code, with progress, cancel, retry and remove on each. Files outside the limits are listed with the reason.
+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
 
@@ -137,7 +137,7 @@ The uploader posts a form with the file in `uploadField` (`file` by default) to
 | --- | --- |
 | `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 from code. 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). |
+| `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. |
 
@@ -178,7 +178,7 @@ The uploader posts a form with the file in `uploadField` (`file` by default) to
 | `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()` from code. Default `instant` with `uploadUrl` or `upload`, else `manual`. |
+| `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. |

package/docs/filterbuilder.md

@@ -1,6 +1,6 @@
 # FilterBuilder
 
-> Data · @motifx-community/ui 0.1.0-beta.2
+> Data · @motifx-community/ui 0.1.0-beta.3
 
 A filter builder lets people put a filter together by hand: groups joined by And, Or, Not And or Not Or, and conditions of a field, an operation and a value. Its value is the data layer's filter expression, so it goes to rows in memory and to every adapter as it is. The DataGrid opens it from its filter panel; on its own it serves a report screen or a saved search.
 
@@ -57,7 +57,7 @@ export const saleFields: FilterBuilderField[] = [
 ];
 ```
 
-## From code, and the events
+## Programmatic use, and the events
 
 Every change the user makes is also a method (`addCondition`, `addGroup`, `removeItem`, `setField`, `setOperation`, `setConditionValue`, `setGroupOperation`, `clear`), and every change asks first: `onItemAdding`, `onItemRemoving` and `onItemChanging` can change it or cancel it, the `…ed` events and `onValueChanged` follow. Here the last condition of the root cannot be taken out.
 
@@ -372,7 +372,7 @@ export const saleFields: FilterBuilderField[] = [
 | `setField(condition, dataField), setOperation(condition, op), setConditionValue(condition, value)` | `boolean` | An operation or value that no longer fits the new field is reset. |
 | `setGroupOperation(group, op)` | `boolean` |  |
 | `clear()` | `void` | Empties the tree. |
-| `openEditor(condition), closeEditor(keep?)` | `boolean`, `void` | The value editor, from code. |
+| `openEditor(condition), closeEditor(keep?)` | `boolean`, `void` | The value editor, programmatically. |
 | `focusItem(item, part?), focus()` | `boolean` | A row's button (`'remove'`, `'group'`, `'add'`, `'field'`, `'operation'`, `'value'`); the tree's Tab stop. |
 | `getFilterExpression()` | `data.FilterExpression \| null` | The value. |
 | `refresh()` | `void` | Your fields and value may be plain or reactive; the builder reads them as they are. After changing them in place, call `refresh()`. The rows are drawn again; a value changed in place is read into the tree. |
@@ -460,7 +460,7 @@ export const saleFields: FilterBuilderField[] = [
 ];
 ```
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -468,14 +468,14 @@ import { data } from '@motifx-community/data';
 import { Button, FilterBuilder, Stack } from '@motifx-community/ui';
 import { saleFields } from './sales';
 
-/** Made with `new` and driven from code; every change asks first, and a handler may cancel it. */
-export default function FromCode() {
+/** Made with `new` and driven programmatically; every change asks first, and a handler may cancel it. */
+export default function Programmatic() {
   const log = reactive({ lines: [] as { id: number; text: string }[], next: 0 });
   const write = (text: string) => {
     log.lines.unshift({ id: log.next++, text });
     if (log.lines.length > 6) log.lines.pop();
   };
-  const builder = new FilterBuilder({ fields: saleFields, locale: 'en', label: 'Built from code' });
+  const builder = new FilterBuilder({ fields: saleFields, locale: 'en', label: 'Built programmatically' });
   builder.element.classList.add('fb-code');
   builder.onItemAdding((e) => write(`adding a ${e.item.kind}${e.byUser ? ' (user)' : ''}`));
   builder.onItemRemoving((e) => {

package/docs/formlayout.md

@@ -1,6 +1,6 @@
 # FormLayout
 
-> Navigation · @motifx-community/ui 0.1.0-beta.2
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
 Lays out the fields of a data object on a grid. Each field gets an editor — by name, or by the type of its value — bound to the object both ways; groups, spans and buttons arrange them; sending the form checks every field first.