@heyramzi/tasks 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,286 @@
-# Temporary Holding Version
+# @heyramzi/tasks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 task views. One array of tasks shows as a drag-and-drop board, a
+grouped list or a gantt timeline, and the same column config drives all three.
+Status badges, dots and icons come from one map too. Live at
+[ui.heyramzi.com/tasks](https://ui.heyramzi.com/tasks).
+
+Every view knows nothing about your data. You pass items and a few accessors,
+and it hands back a change to persist. No runtime dependencies: `svelte` is the
+only peer. This package was `@heyramzi/board` up to 0.2.
+
+```
+pnpm add @heyramzi/tasks
+```
+
+## Board
+
+The board owns the layout, the drag state and the drop logic. Drag and drop is
+native HTML5 (`draggable`, `dragover`, `drop`), so cards can also land on
+elements outside the board if you wire those up. Keyboard users move the
+focused card with Alt plus Left or Right arrow. A column with
+`droppable: false` is display only: it never calls `preventDefault`, so it
+isn't a drop target (an Overdue lane, say).
+
+```svelte
+<script lang="ts">
+  import { KanbanBoard, type KanbanMove } from "@heyramzi/tasks";
+
+  type Task = { id: string; column: string; title: string; order: string };
+
+  let tasks = $state<Task[]>([]);
+
+  const columns = [
+    { id: "todo", label: "To do" },
+    { id: "doing", label: "In progress", hue: "var(--color-info)" },
+    { id: "overdue", label: "Overdue", droppable: false },
+    { id: "done", label: "Done", hue: "var(--color-success)" },
+  ];
+
+  function onMove(id: string, move: KanbanMove) {
+    tasks = tasks.map((task) =>
+      task.id === id
+        ? { ...task, column: move.columnId, order: move.boardOrder ?? task.order }
+        : task,
+    );
+  }
+</script>
+
+<KanbanBoard
+  {columns}
+  items={tasks}
+  getId={(task) => task.id}
+  getColumn={(task) => task.column}
+  boardOrder={(task) => task.order}
+  {onMove}
+>
+  {#snippet renderCard(task)}
+    <article class="rounded-xl border border-border bg-card p-2.5">{task.title}</article>
+  {/snippet}
+</KanbanBoard>
+```
+
+| Prop            | Type                                                    | Notes                                                        |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
+| `columns`       | `KanbanColumn[]`                                        | `{ id, label, hue?, ariaLabel?, droppable? }`. `hue` tints the column while a card is over it. `droppable: false` makes it display only. |
+| `items`         | `T[]`                                                   | Every card.                                                 |
+| `getId`         | `(item: T) => string`                                   | Stable id, used for keys and drag payloads.                 |
+| `getColumn`     | `(item: T) => string`                                   | Which column the card belongs to.                           |
+| `onMove`        | `(id: string, move: KanbanMove) => void \| Promise<void>` | Called on drop. Awaited.                                 |
+| `renderCard`    | `Snippet<[T, { columnId, index }]>`                     | Card markup.                                                |
+| `boardOrder`    | `(item: T) => string \| null \| undefined`               | Manual order key. Required for `sortKey="manual"`.          |
+| `sortKeys`      | `KanbanSortKey<T>[]`                                    | Extra sorts, `{ id, label, compare }`.                     |
+| `sortKey`       | `string`                                                | Active sort. Defaults to `"manual"`.                        |
+| `columnHeader`  | `Snippet<[KanbanColumn, { count, active }]>`            | Optional header. Defaults to label plus count.              |
+| `emptyLabel`    | `string`                                                | Shown in an empty column.                                   |
+| `dropAtTop`     | `(columnId: string) => boolean`                         | Drops on a capped column go to the top. Defaults to "is `limit` hiding its tail".  |
+| `isDroppable`   | `(columnId: string) => boolean`                         | Overrides the per-column `droppable` flag.                  |
+| `manualTiebreak` | `(a: T, b: T) => number`                               | Settles two cards with the same manual key, or none.        |
+| `getLabel`      | `(item: T) => string`                                   | The screen-reader name of a card. Defaults to a keyboard hint. |
+| `onSelect`      | `(id: string) => void`                                  | Enter or Space on a focused card.                           |
+| `columnFooter`  | `Snippet<[Column, KanbanColumnContext]>`                | Under a column's cards: a "Show all" or an add button.      |
+| `wrapColumn`    | `Snippet<[Column, Snippet<[props]>]>`                   | Wraps a whole column, for a context menu. Render the inner snippet once with the props you are handed. |
+| `limit`         | `(columnId: string) => number \| undefined`             | Cards a column shows before the rest fold. `expanded` and `onExpandedChange` lift it per column. |
+| `hidden`        | `string[]`                                              | Columns folded into a rail on the right. Fold and unfold animate, and a card dropped on a rail entry brings the column back. `onHiddenChange`, `hiddenLabel`, `showAllLabel` and `hiddenItem` go with it. |
+
+`columns` can be your own type, as long as it extends `KanbanColumn`: the
+header, footer and wrap snippets get it back as you passed it, so a column can
+carry a status or a stage for your own markup. The header and footer context is
+`{ count, active, shown, capped, hide, expand }`.
+
+`onMove` gives `{ columnId, boardOrder?, beforeId?, afterId? }`. On a manual
+drop `beforeId` and `afterId` name the cards above and below the new slot (null
+at an end), for a backend that orders by neighbour. `boardOrder` is set when you
+pass a `boardOrder` accessor. It's a fractional key that places the card in its
+new slot, so a move writes one row instead of renumbering a column.
+
+## List
+
+`TaskList` takes the board's columns as `groups` and the board's `onMove`, so a
+page can switch between the two without a second code path. Rows sit under a
+header per group that folds open and shut. Drag a row to another group or
+another slot, or focus it and press Alt plus Up or Down to send it to the next
+group. Rows slide into their new place when the order changes.
+
+```svelte
+<TaskList
+  groups={columns}
+  items={tasks}
+  getId={(task) => task.id}
+  getGroup={(task) => task.column}
+  boardOrder={(task) => task.order}
+  {onMove}
+>
+  {#snippet head()}
+    <div class="grid w-full grid-cols-[1fr_6rem] px-3.5"><span>Task</span><span>Due</span></div>
+  {/snippet}
+  {#snippet renderRow(task)}
+    <div class="grid h-10 grid-cols-[1fr_6rem] items-center px-2">{task.title}<span>{task.due}</span></div>
+  {/snippet}
+</TaskList>
+```
+
+Beyond the board's props it takes `head` (a sticky header row), `groupHeader`
+(`Snippet<[group, { count, active, open, depth, hasChildren }]>`), `actions` (controls at the end of
+a group header, shown on hover), `groupFooter` (an add-task row under the rows),
+`collapsible` (default true), `collapsed` (group ids that start folded) and
+`onCollapsedChange`. Pass `flat` to drop the card border, radius and fill so the list sits on the page (the gantt takes it too); group dividers stay. Pass `draggable={false}` for a list that only groups: rows
+lose the drag handlers and the keyboard move, so links and buttons inside them
+keep every key.
+
+Pass `getParent` to nest one group under another, such as a project under its
+client. It takes a group and returns the id of its parent, or nothing for a
+top-level group. A child draws inside its parent's section, indented, with its
+own sticky header under the parent's, and folds when the parent folds. A parent
+takes no drops and its `count` adds up its children. A child whose parent id
+matches no group is drawn at the top level.
+
+```svelte
+<TaskList
+  groups={[
+    { id: "acme", label: "Acme" },
+    { id: "acme-site", label: "Website", parent: "acme" },
+    { id: "acme-audit", label: "Audit", parent: "acme" },
+  ]}
+  getParent={(group) => group.parent}
+  ...
+/>
+```
+
+## Gantt
+
+`TaskGantt` draws each task as a bar from its start to its end date, both
+inclusive ISO dates (`"2026-10-16"`). Drag a bar to move it, drag an edge to
+resize it, and the bar glides from day to day while a tip shows the new range.
+A focused bar moves a day with the arrow keys, and Shift plus an arrow moves
+its end. Leave out `onChange` and the chart is read only.
+
+```svelte
+<TaskGantt
+  items={tasks}
+  getId={(task) => task.id}
+  getTitle={(task) => task.title}
+  getStart={(task) => task.start}
+  getEnd={(task) => task.end}
+  getDependsOn={(task) => task.blockedBy}
+  groups={columns}
+  getGroup={(task) => task.column}
+  onChange={(id, { start, end }) => save(id, start, end)}
+/>
+```
+
+| Prop           | Type                                      | Notes                                                       |
+| -------------- | ----------------------------------------- | ----------------------------------------------------------- |
+| `items`, `getId`, `getTitle` |                             | Required.                                                   |
+| `getStart`, `getEnd` | `(item: T) => string \| null \| undefined` | ISO dates, inclusive. A one-day task has the same start and end. One date alone is a one-day task, none is undated. A parent with no dates draws the span of its children as an outline bar. |
+| `onChange`     | `(id, { start, end }) => void \| Promise<void>` | Called after a drag, a resize or a key nudge.        |
+| `onSelect`     | `(id) => void`                            | A click or Enter that didn't move the bar.                  |
+| `getHue`       | `(item: T) => string \| undefined`         | Bar color. Falls back to the group hue, then `--color-primary`. |
+| `getProgress`  | `(item: T) => number \| undefined`         | 0 to 1, filled from the left.                               |
+| `getDependsOn` | `(item: T) => string[] \| undefined`       | Draws an arrow from each listed task's end to this one's start. |
+| `groups`, `getGroup` |                                     | Optional. Groups rows under a header with a span line.      |
+| `getParent`    | `(item: T) => string \| null \| undefined` | Nests a task under another by id: indented, foldable, depth first. |
+| `collapsed`    | `string[]`                                | Parent ids that start folded.                               |
+| `isMilestone`  | `(item: T) => boolean`                    | Draws a flag at the end date instead of a bar. Not draggable. |
+| `noDatesLabel` | `string`                                  | Shown for a task with no dates. Default "No dates".         |
+| `renderLabel`  | `Snippet<[T, { depth, hasChildren, open }]>` | The left column. Defaults to the title.                  |
+| `from`, `to`   | `string`                                  | The shown range. Defaults to the tasks' span, padded, from a Monday. |
+| `today`        | `string`                                  | Where the today line sits. Defaults to the viewer's today.  |
+| `dayWidth`     | `number`                                  | Default 32. Under 18 the header shows week starts only.     |
+| `rowHeight`, `labelWidth`, `labelHeading`, `locale` |      | Layout and text.                                            |
+
+It opens scrolled to today, a third of the way in. Call `scrollToToday()` on a
+`bind:this` reference to go back there.
+
+## View switch
+
+`TaskViewSwitch` is the segmented control the demo uses to flip between views,
+with a pill that slides to the active option. Pass `views`
+(`{ id, label, icon? }[]`) and `bind:value`. `BoardIcon`, `ListIcon` and
+`GanttIcon` are exported for it.
+
+## Time tracking
+
+Optional. `TimeTracker` logs time against one task: a start and stop timer, quick
+entry that reads `1h30`, `90m`, `1.5h` or `1:30`, a date and a note, entries
+grouped by day with day totals, a per-person split and an optional estimate shown
+as a ring that turns warning at 90% and destructive past 100%. It holds no data
+and fetches nothing. You pass entries in and persist what it hands back.
+
+```svelte
+<TimeTracker
+  entries={entries}
+  getId={(e) => e.id}
+  getMinutes={(e) => e.minutes}
+  getDay={(e) => e.day}
+  getPerson={(e) => e.person}
+  estimate={480}
+  {running}
+  onStart={() => (running = { startedAt: Date.now() })}
+  onStop={(info) => save(info.minutes, info.day)}
+  onLog={(input) => save(input.minutes, input.day, input.note)}
+  onDelete={(entry) => remove(entry.id)}
+/>
+```
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `entries` | `T[]` | Every entry on the task. |
+| `getId`, `getMinutes`, `getDay`, `getPerson` | accessors | `getDay` returns `YYYY-MM-DD`. |
+| `getPersonId`, `getNote` | accessors | Optional. The id keeps two people with one name apart. |
+| `running` | `{ startedAt } \| null` | The host stores it, so it survives a reload. |
+| `estimate` | `number` | Minutes budgeted. Draws the ring. |
+| `onStart` | `() => void` | The host sets `running`. |
+| `onStop` | `(info) => void` | `info` is `{ minutes, startedAt, stoppedAt, day }`. Clear `running` after saving. |
+| `onLog` | `(input) => void \| boolean` | `input` is `{ minutes, day, note? }`. Return `false` to keep the fields. |
+| `onDelete`, `canDelete` | callback | The delete button shows when `onDelete` is set and `canDelete` allows it. |
+| `renderMeta` | `Snippet<[T]>` | Extra text after a row's note. |
+| `flat` | `boolean` | Drops the card (border, radius, background, shadow, padding) for a host that already has a panel. The running state then shows through the dot, readout and button. |
+| `locale`, `labels`, `class` | | `labels` overrides any string in `DEFAULT_TIME_LABELS`. |
+
+Alt+S starts and stops the timer. A screen reader hears the start, one update a
+minute and the stop. Import it alone from `@heyramzi/tasks/time`.
+
+For boards and lists: `TimeChip` (`minutes`, `estimate?`, `running?`) shows the
+logged total, with a pulsing dot while a timer runs and a small ring against an
+estimate. `TimeRing` and `TimeDot` are the pieces under it.
+`parseMinutes`, `formatMinutes`, `formatClock`, `budgetTone` and `localDay` are
+exported helpers.
+
+## Also exported
+
+- `KanbanColumn`: the column shell, if you want to build your own board.
+- `createKanbanDnd`: the drag state and handlers behind the board and the list.
+- `liftDragImage`: gives the browser a tilted, lifted drag snapshot.
+- `boardOrderAt`, `keyBetween`: fractional order keys.
+- `reorderByIds`: move an item to another item's index in a flat list.
+- `addDays`, `dayNumber`, `isoFromDay`, `todayIso`: the date helpers the gantt uses.
+- `StatusBadge`, `StatusDot`, `StatusIcon`: chips, dots and icons from one config.
+  A badge also takes its text as children, for a caller that already has the word.
+- `defineStatuses`: builds a status registry from a plain map.
+- `TONE_CLASS`, `TONE_COLOR`, `TONE_ICON`, `TONE_TEXT`, `insetWellClass`: the severity scale.
+- `salesStatuses`: an example pipeline map.
+
+## Styling
+
+The accent tone reads `--tone-accent` and falls back to `--color-primary`. Set
+`--tone-accent` when your primary is a neutral and your accent is a brand color.
+
+Classes are Tailwind, on shadcn-style tokens (`bg-card`, `border-border`,
+`text-muted-foreground`, `--color-primary`). Point Tailwind at the package with
+`@source` so it generates them. Motion reads the `--duration-*` and `--ease-*`
+tokens from `@heyramzi/ui/animations` when they're there and falls back to the
+same values when they aren't. Everything goes still under
+`prefers-reduced-motion`.
+
+## Demo
+
+`src/demo.svelte` puts one task list behind a Board, List and Gantt switch, with
+sorting, a Days and Weeks scale and a status badge strip.
+
+The fractional ordering in `board-order.ts` is the CC0 algorithm from
+[Implementing Fractional Indexing](https://observablehq.com/@dgreensp/implementing-fractional-indexing).
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@heyramzi/tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "Svelte 5 task views: a drag-and-drop board, a grouped list and a gantt timeline from one config, plus status badges, dots and icons.",
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "kanban",
+    "board",
+    "gantt",
+    "timeline",
+    "tasks",
+    "drag-and-drop"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heyramzi/ui.git",
+    "directory": "packages/tasks"
+  },
+  "homepage": "https://ui.heyramzi.com/tasks",
+  "type": "module",
+  "svelte": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "svelte": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./kanban": {
+      "svelte": "./src/kanban-board.svelte",
+      "types": "./src/kanban-board.svelte",
+      "default": "./src/kanban-board.svelte"
+    },
+    "./list": {
+      "svelte": "./src/task-list.svelte",
+      "types": "./src/task-list.svelte",
+      "default": "./src/task-list.svelte"
+    },
+    "./gantt": {
+      "svelte": "./src/task-gantt.svelte",
+      "types": "./src/task-gantt.svelte",
+      "default": "./src/task-gantt.svelte"
+    },
+    "./status": {
+      "svelte": "./src/status-badge.svelte",
+      "types": "./src/status-badge.svelte",
+      "default": "./src/status-badge.svelte"
+    },
+    "./status-dot": {
+      "svelte": "./src/status-dot.svelte",
+      "types": "./src/status-dot.svelte",
+      "default": "./src/status-dot.svelte"
+    },
+    "./statuses": {
+      "svelte": "./src/define-statuses.ts",
+      "types": "./src/define-statuses.ts",
+      "default": "./src/define-statuses.ts"
+    },
+    "./time": {
+      "svelte": "./src/time/time-tracker.svelte",
+      "types": "./src/time/time-tracker.svelte",
+      "default": "./src/time/time-tracker.svelte"
+    },
+    "./inbox": {
+      "svelte": "./src/inbox/index.ts",
+      "types": "./src/inbox/index.ts",
+      "default": "./src/inbox/index.ts"
+    },
+    "./presets/sales": {
+      "svelte": "./src/presets/sales.ts",
+      "types": "./src/presets/sales.ts",
+      "default": "./src/presets/sales.ts"
+    },
+    "./demo": {
+      "svelte": "./src/demo.svelte",
+      "default": "./src/demo.svelte"
+    },
+    "./demo.svelte": "./src/demo.svelte"
+  },
+  "peerDependencies": {
+    "@heyramzi/ui": "*",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@heyramzi/ui": "7.0.0",
+    "@types/node": "^26.6.4",
+    "svelte-check": "^4.7.6",
+    "typescript": "~7.0.2"
+  },
+  "scripts": {
+    "check": "svelte-check --tsconfig ./tsconfig.json"
+  }
 }

package/src/ambient.d.ts

@@ -0,0 +1,6 @@
+// Vite's ?raw import hands back the file as a string. Declared here so svelte-check passes
+// without pulling in vite/client.
+declare module "*.svg?raw" {
+	const svg: string;
+	export default svg;
+}

package/src/board-order.ts

@@ -0,0 +1,137 @@
+// Fractional indexing: an order key that always sorts between its neighbours,
+// so a move writes one row instead of renumbering a column. The algorithm is
+// the CC0 one from https://observablehq.com/@dgreensp/implementing-fractional-indexing
+// (see the README credit). Kept inline so this package carries no runtime deps.
+const DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const INT_DIGITS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ZERO = DIGITS[0];
+
+function integerLength(head: string): number {
+  const i = INT_DIGITS.indexOf(head);
+  if (i === -1) throw new Error("invalid order key head: " + head);
+  const half = INT_DIGITS.length / 2;
+  return i < half ? half - i + 1 : i - half + 2;
+}
+
+function integerPart(key: string): string {
+  const length = integerLength(key[0]);
+  if (length > key.length) throw new Error("invalid order key: " + key);
+  return key.slice(0, length);
+}
+
+function smallestInteger(): string {
+  return INT_DIGITS[0] + ZERO.repeat(INT_DIGITS.length / 2);
+}
+
+function midpoint(a: string, b: string | null): string {
+  if (b != null && a >= b) throw new Error(a + " >= " + b);
+  if (a.slice(-1) === ZERO || (b && b.slice(-1) === ZERO)) throw new Error("trailing zero");
+
+  if (b) {
+    let n = 0;
+    while ((a[n] ?? ZERO) === b[n]) n++;
+    if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n));
+  }
+
+  const digitA = a ? DIGITS.indexOf(a[0]) : 0;
+  const digitB = b != null ? DIGITS.indexOf(b[0]) : DIGITS.length;
+  if (digitB - digitA > 1) {
+    return DIGITS[Math.round(0.5 * (digitA + digitB))];
+  }
+  if (b && b.length > 1) return b.slice(0, 1);
+  return DIGITS[digitA] + midpoint(a.slice(1), null);
+}
+
+function incrementInteger(x: string): string | null {
+  const head = x[0];
+  let trailing = "";
+  for (let i = x.length - 1; i >= 1; i--) {
+    const d = DIGITS.indexOf(x[i]) + 1;
+    if (d === DIGITS.length) trailing = ZERO + trailing;
+    else return head + x.slice(1, i) + DIGITS[d] + trailing;
+  }
+
+  const headIndex = INT_DIGITS.indexOf(head);
+  if (headIndex === INT_DIGITS.length - 1) return null;
+  const h = INT_DIGITS[headIndex + 1];
+  const delta = integerLength(h) - integerLength(head);
+  return h + (delta > 0 ? trailing + ZERO : delta < 0 ? trailing.slice(1) : trailing);
+}
+
+function decrementInteger(x: string): string | null {
+  const head = x[0];
+  const last = DIGITS[DIGITS.length - 1];
+  let trailing = "";
+  for (let i = x.length - 1; i >= 1; i--) {
+    const d = DIGITS.indexOf(x[i]) - 1;
+    if (d === -1) trailing = last + trailing;
+    else return head + x.slice(1, i) + DIGITS[d] + trailing;
+  }
+
+  const headIndex = INT_DIGITS.indexOf(head);
+  if (headIndex === 0) return null;
+  const h = INT_DIGITS[headIndex - 1];
+  const delta = integerLength(h) - integerLength(head);
+  return h + (delta > 0 ? trailing + last : delta < 0 ? trailing.slice(1) : trailing);
+}
+
+/** An order key that sorts strictly between `a` and `b`. Null means an open end. */
+export function keyBetween(a: string | null, b: string | null): string {
+  if (a != null && b != null && a > b) [a, b] = [b, a];
+
+  if (a == null) {
+    if (b == null) return INT_DIGITS[INT_DIGITS.length / 2] + ZERO;
+    const ib = integerPart(b);
+    const fb = b.slice(ib.length);
+    if (ib === smallestInteger()) return ib + midpoint("", fb);
+    if (ib < b) return ib;
+    const res = decrementInteger(ib);
+    if (res == null) throw new Error("cannot decrement any more");
+    return res;
+  }
+
+  if (b == null) {
+    const ia = integerPart(a);
+    const fa = a.slice(ia.length);
+    const i = incrementInteger(ia);
+    return i == null ? ia + midpoint(fa, null) : i;
+  }
+
+  const ia = integerPart(a);
+  const fa = a.slice(ia.length);
+  const ib = integerPart(b);
+  const fb = b.slice(ib.length);
+  if (ia === ib) return ia + midpoint(fa, fb);
+
+  const i = incrementInteger(ia);
+  if (i == null) throw new Error("cannot increment any more");
+  if (i < b) return i;
+  return ia + midpoint(fa, null);
+}
+
+/**
+ * The key a card should take when dropped at `index`. Rows may share a key or
+ * have none, so the bounds skip both and only compare against real keys.
+ */
+export function boardOrderAt<T>(
+  column: readonly T[],
+  index: number,
+  order: (item: T) => string | null | undefined,
+): string {
+  let lower: string | null = null;
+  for (const item of column.slice(0, index)) {
+    const key = order(item);
+    if (key != null && (lower === null || key > lower)) lower = key;
+  }
+
+  let upper: string | null = null;
+  for (const item of column.slice(index)) {
+    const key = order(item);
+    if (key != null && (lower === null || key > lower)) {
+      upper = key;
+      break;
+    }
+  }
+
+  return keyBetween(lower, upper);
+}

package/src/dates.ts

@@ -0,0 +1,31 @@
+// Dates are plain "YYYY-MM-DD" strings, counted as whole UTC days. A timeline
+// only needs days, and day numbers dodge every timezone and DST edge.
+const DAY_MS = 86_400_000;
+
+/** Days since 1970-01-01 for an ISO date. Anything after the date part is ignored. */
+export function dayNumber(iso: string): number {
+  const [y, m, d] = iso.slice(0, 10).split("-").map(Number);
+  return Math.round(Date.UTC(y, m - 1, d) / DAY_MS);
+}
+
+/** The ISO date for a day number. */
+export function isoFromDay(day: number): string {
+  return new Date(day * DAY_MS).toISOString().slice(0, 10);
+}
+
+/** Shift an ISO date by whole days. */
+export function addDays(iso: string, days: number): string {
+  return isoFromDay(dayNumber(iso) + days);
+}
+
+/** Today in the viewer's own timezone, as an ISO date. */
+export function todayIso(): string {
+  const now = new Date();
+  const local = new Date(now.getTime() - now.getTimezoneOffset() * 60_000);
+  return local.toISOString().slice(0, 10);
+}
+
+/** 0 is Sunday, as in `Date.getUTCDay`. */
+export function weekday(day: number): number {
+  return new Date(day * DAY_MS).getUTCDay();
+}

package/src/define-statuses.ts

@@ -0,0 +1,32 @@
+import type { StatusDef, StatusId, StatusMap, Statuses } from "./status-types.js";
+
+/**
+ * Build a status registry from a plain map. The registry keeps the map's keys as
+ * a union, so `statuses.ids` and lookups stay typed.
+ *
+ * ```ts
+ * const statuses = defineStatuses({
+ *   draft: { label: "Draft", tone: "neutral" },
+ *   sent: { label: "Sent", tone: "info" },
+ * });
+ * ```
+ */
+export function defineStatuses<const M extends StatusMap>(
+	map: M,
+): Statuses & { ids: StatusId<M>[] } {
+	const lookup = map as Record<string, StatusDef | undefined>;
+	const find = (id: string): StatusDef | undefined => lookup[id];
+
+	return {
+		map,
+		ids: Object.keys(map) as StatusId<M>[],
+		has: (id) => find(id) !== undefined,
+		get: find,
+		label: (id) => find(id)?.label ?? id,
+		tone: (id) => find(id)?.tone ?? "neutral",
+		icon: (id) => find(id)?.icon,
+		variant: (id) => find(id)?.variant ?? "open",
+		progress: (id) => find(id)?.progress,
+		color: (id) => find(id)?.color,
+	};
+}