makersclaw 0.2.0 → 0.3.1

package/registry/blocks/task-model/README.md

@@ -0,0 +1,455 @@
+# Task model
+
+The shared model every view of work reads: one task shape, one context
+(statuses, people, projects, custom fields, today), the arithmetic every
+view repeats (search, filter, group, sort, subtasks, dates, capacity,
+dependencies), the Change a view sends when the founder moves something,
+the small parts every view draws the same way, the toolbar above them, and
+the drag primitives on @dnd-kit. List, board, table, calendar, gantt,
+workload, portfolio and roadmap all run through it, so a task filtered out
+of one is filtered out of all, and one `onChange` saves every view.
+
+```jsx
+import { createTaskContext, applyView, ViewToolbar, useTaskChanges } from "../components/blocks/task-model";   // a Makersclaw app
+import { createTaskContext, applyView, ViewToolbar, useTaskChanges } from "@/components/makersclaw/blocks/task-model";   // a shadcn project
+```
+
+A surface rarely renders it alone: `task-list` (and calendar, gantt,
+workload, work-views…) are built on it. A view built on it `requires`
+task-model and imports @dnd-kit only through it. `model.js` and
+`dates.js` are pure (no React): they run on the server too.
+
+## The data
+
+### A task
+
+```js
+{
+  id: "t1",                       // string (numbers are stringified)
+  title: "Write the launch email",
+  status: "todo",                 // a status id
+  assignees: ["maya"],            // person ids; [] when unassigned
+  start: "2026-09-22",            // optional; a day, or "2026-09-22T09:30"
+  due: "2026-09-24T17:00",        // optional; same forms
+  estimate: 4,                    // optional, hours
+  progress: 40,                   // optional, 0–100 (else from status / subtasks)
+  priority: "high",               // optional: urgent · high · medium · low
+  parentId: "t0",                 // optional: a subtask of t0
+  dependsOn: ["t7"],              // optional: t7 must finish first
+  location: { lat, lng, label },  // optional, for a map view
+  tags: ["copy"],                 // []
+  project: "site",                // optional, a project id
+  order: 2048,                    // optional: the hand-made order (see placeChange)
+  …extra                          // any other key is kept and passed through
+}
+```
+
+`normalizeTask(t)` makes the lists lists and the id a string (it also
+takes `name` for `title` and a single `assignee`); every helper does this
+for you. Dates are wall-calendar strings, never Date objects: they compare
+in order, survive JSON and a `date` column, and mean the same day in every
+timezone. A time is local wall time, no zone.
+
+### The context
+
+```js
+const ctx = useMemo(() => createTaskContext({
+  statuses: [{ id: "todo", label: "To do", tone: "neutral" }, …, { id: "done", label: "Done", tone: "success", done: true }],
+  people:   [{ id: "maya", name: "Maya Chen", src?, capacity?: 6 }],   // capacity: hours a day (default 8)
+  projects: [{ id: "site", name: "Website relaunch", hue?: 1 }],       // hue 1–5 = chart-1…5
+  fields:   [{ key: "channel", label: "Channel", kind: "select", options: ["Email", "Social"] }],
+  today:    "2026-09-23",       // fix it in a demo; default the browser's today
+  weekStartsOn: 1,              // 0 Sunday … 6; default Monday
+  weekend: [0, 6], holidays: ["2026-12-25"],   // for working-day math
+}), [statuses, people, projects]);
+```
+
+A status's `tone` is neutral · info · warning · success · danger · primary
+(or `hue` 1–5 for a category-like status). `done: true` marks the done
+statuses (several may be). Without `statuses` you get `DEFAULT_STATUSES`
+(To do, In progress, In review, Done). Custom field kinds: text · number ·
+select · date · checkbox. Every helper takes `ctx` (or the plain options
+object, built on the fly — build it once instead).
+
+What `ctx` holds: `statuses`, `people`, `projects`, `fields` (built-in +
+custom, see `TASK_FIELDS`), `statusById` / `personById` / `projectById`
+(Maps; a status also has its `index`), `doneIds` (Set), `today`,
+`weekStartsOn`, `weekend`, `holidays`.
+
+### A view
+
+What a view remembers, and what work-views saves per tab:
+
+```js
+DEFAULT_VIEW = { search: "", filters: {}, groupBy: "status", sort: [], fields: ["assignees", "due", "priority"], hideDone: false }
+```
+
+- `filters` — `{ status: ["todo", "doing"], assignees: ["maya", NONE], due: ["overdue", "today"] }`:
+  any value within a field, every field. `NONE` (`"__none"`) is
+  "Unassigned / No date / No project…". Date fields filter by due bucket.
+- `groupBy` — any field key, or `"none"`.
+- `sort` — `[{ key, dir: "asc" | "desc" }]`; `[]` is the manual order
+  (`order`). Keys: any field, or `"manual"`.
+- `fields` — which fields a row shows (the list's "Fields" menu).
+
+### A change — how a view reports what the founder did
+
+A view never edits tasks. It builds a Change and commits it:
+
+```js
+{ type: "create", task }            or { type: "create", tasks: [...] }
+{ type: "update", id, patch }       or { type: "update", ids: [...], patch }
+{ type: "delete", id }              or { type: "delete", ids: [...] }
+{ type: "batch", changes: [...] }   // several at once (a renumber, an undo)
+```
+
+The page answers every change through ONE async callback,
+`onChange(change) → { ok: true } | { ok: false, error }` (a throw counts as
+failed; `{ ok: true, id }` may return a create's database id). In a
+Makersclaw app it is a loop over `changeWrites(change)`:
+
+```js
+const COLUMNS = ["id", "title", "status", "assignees", "due", "priority", "parentId", "order"];   // your table's
+
+async function onChange(change) {
+  for (const w of changeWrites(change, { columns: COLUMNS, keepNewIds: false })) {
+    const r = w.op === "insert" ? await insertRow({ source: "public.tasks", values: w.values })
+            : w.op === "update" ? await updateRow({ source: "public.tasks", id: w.id, patch: w.patch })
+            : await deleteRow({ source: "public.tasks", id: w.id });
+    if (r.ok === false) return r;
+  }
+  return { ok: true };
+}
+```
+
+## Props
+
+task-model has no one component; these are its exports, grouped by what
+a view builder needs. Every one is importable from the block's index.
+
+### Views: search, filter, group, sort
+
+- `applyView(tasks, view, ctx)` → `{ tasks, groups, total }` — the whole
+  pipeline: normalise, hide done (`hideDone`), search, filter, sort, group.
+  Use this and you match every other view.
+- `searchTasks(tasks, query, ctx)` — every word must appear in the
+  title, tags, people's names, project, status label, description or a
+  custom text field. `searchText(task, ctx)` is that haystack.
+- `filterTasks(tasks, filters, ctx)` · `activeFilterCount(view)`.
+- `sortTasks(tasks, sort, ctx)` — stable, blanks last either way; status
+  sorts in the statuses' order, priority urgent → low, people by name,
+  dates by day then time. `sortOptions(ctx)` for a menu.
+- `groupTasks(tasks, by, ctx, { showEmpty? })` →
+  `[{ key, label, tone?, hue?, option, tasks }]` in the field's order,
+  the "none" group last. A task with two assignees (or tags) is in both
+  groups. Empty groups are kept for status and priority (somewhere to
+  drop) or with `showEmpty: true`. `groupOptions(ctx)` for a menu.
+- `valuesOf(task, key, ctx)` — the group keys a task is filed under
+  (`["maya", "leo"]`, `["overdue"]`, `[NONE]`).
+- `optionsOf(key, ctx, tasks?)` → `[{ id, label, tone?, hue?, person?, project?, none? }]`
+  — a field's choices in order; `labelOf(key, value, ctx)` — one's words.
+- `movePatch(task, by, fromKey, toKey, ctx)` — the patch that moves a task
+  between groups of `by`: a new status; one assignee swapped for another
+  (the rest stay); a due date for a due bucket (a start moves with it,
+  the length kept); `null` when the target is not a place to drop
+  (Overdue). Board columns, list groups, workload rows all use it.
+- `fieldOf(key, ctx)` · `TASK_FIELDS` · `PRIORITIES` · `NONE` ·
+  `DEFAULT_STATUSES` · `DEFAULT_VIEW`.
+- `isDone(task, ctx)` · `doneStatusId(ctx)` · `openStatusId(ctx)` ·
+  `toggleDoneChange(task, ctx)` (the completion checkbox's change).
+
+### Manual order
+
+- `orderOf(task)` — its `order`, or null.
+- `rankBetween(a, b)` — a number between two orders (either may be null).
+- `placeChange(list, task, index, patch?)` — the Change that puts `task` at
+  `index` of `list` (the target group's tasks as shown, without the task),
+  with `patch` (its new group) merged in: a midpoint `order` when there is
+  room, else one `batch` that renumbers the list. Drag-to-reorder is this
+  one call.
+- `draftTask(title, ctx, patch?, { after? })` — a new task for a quick-add:
+  a client id (`newTaskId()`), the first open status, an order after
+  `after`, the group's patch.
+
+### Subtasks
+
+- `flattenTree(tasks, { collapsed? })` → `[{ task, depth, childCount, hasChildren, collapsed }]`
+  in reading order; a task whose parent is not in `tasks` is a root.
+- `buildTree(tasks)` → `[{ task, depth, children }]` · `childrenMap(tasks)`.
+- `descendantIds(tasks, id)` · `ancestorIds(tasks, id)`.
+- `subtaskCounts(tasks, ctx)` → Map id → `{ total, done }` (a row's "2/5").
+- `rollup(tasks, id, ctx)` → `{ count, done, estimate, progress }`;
+  `progressOf(task, tasks, ctx)` → 0–100 (its own, else 100 if done, else
+  from its subtasks weighted by estimate).
+- `deleteChange(tasks, ids)` — a delete that takes the subtasks too.
+
+### Dates (dates.js — the calendar, gantt and workload math)
+
+Days are `"YYYY-MM-DD"`, optionally `"…THH:mm"`.
+
+- Reading: `isDay(v)` · `dayOf(v)` (a day, from a datetime or a Date) ·
+  `minutesOf(v)` (minutes after midnight, null for all-day) ·
+  `withTime(day, minutes)` · `todayDay()` · `dayNumber(day)` /
+  `fromDayNumber(n)` (integer days, for pixel math: `x = (dayNumber(d) - dayNumber(start)) * dayWidth`).
+- Arithmetic: `addDays` · `diffDays(a, b)` (b − a) · `addMonths` (clamps
+  to the month's end) · `weekdayOf` (0 Sunday) · `startOfWeek(day, ws)` ·
+  `endOfWeek` · `weekDays(day, ws)` (7 days) · `startOfMonth` ·
+  `endOfMonth` · `daysBetween(a, b)` (inclusive list).
+- Grids: `monthGrid("2026-09", { weekStartsOn, fixedWeeks })` → weeks of
+  7 days (mute the days whose `slice(0, 7)` is not the month) ·
+  `timeScale(from, to, unit, { weekStartsOn, locale })` → columns
+  `{ key, start, end, label }` for unit day · week · month · quarter (a
+  gantt header, workload columns, a roadmap's quarters) ·
+  `rangeOfTasks(tasks, { pad, fallback })` → the window all tasks fit in.
+- Working days: `WEEKEND` · `isWeekend` · `isWorkingDay(day, { weekend, holidays })` ·
+  `workingDaysBetween(a, b, opts)` · `addWorkingDays(day, n, opts)`.
+- Spans: `spanOf(task)` → `{ start, end }` (one date → a one-day span;
+  none → null = unscheduled) · `spansOverlap(a, b)` ·
+  `tasksInRange(tasks, from, to)` · `tasksOnDay(tasks, day)`.
+- Patches a drag saves: `shiftDates(task, n)` (move by n days, keeping
+  length and times) · `spanPatch(task, start, end)` (a resize).
+- Words: `formatDay(day, today)` ("Today", "Tomorrow", "Yesterday", "Fri",
+  "Oct 30", "Jan 3, 2027") · `formatTime(v)` ("2:30 PM") ·
+  `formatDate(day, intlOptions)`.
+- Due buckets: `dueBucket(due, today, { done, weekStartsOn })` → overdue ·
+  today · tomorrow · this-week · next-week · later · past (a done task's
+  old date) · none; `DUE_BUCKETS` (their words and tones) ·
+  `dayForBucket(bucket, today)` (the day a drop into a bucket sets).
+
+The kit's own `addDays` / `startOfMonth` / `formatDate` exist too, with
+the same string dates; import one or the other in a file, not both.
+
+### Capacity
+
+- `workload(tasks, ctx, { from, to, unit: "day" | "week", defaultCapacity: 8, includeDone })`
+  → `{ rows: [{ person, total, capacity, buckets: [{ key, start, end, hours, capacity, over, tasks: [{ task, hours }] }] }], buckets, unassigned, unscheduled }`.
+  A task's estimate is spread evenly over the working days of its span and
+  split between its assignees; a bucket's capacity is the person's hours a
+  day × its working days. `over` is load past capacity.
+- `hoursPerDay(task, ctx)` · `sumOf(tasks, key = "estimate")`.
+
+### Dependencies
+
+- `dependencyEdges(tasks)` → `[{ from, to }]` (`to` waits on `from`).
+- `blockersOf(task, tasks, ctx)` — what it waits on that is not done.
+- `wouldCycle(tasks, fromId, toId)` — refuse a link that loops.
+- `dateConflicts(tasks)` — edges whose `to` starts before `from` ends.
+- `criticalPath(tasks)` → Set of ids on the longest dependent chain.
+
+### Changes
+
+- `useTaskChanges(tasks, onChange)` → `{ tasks, commit, error, clearError, saving }`
+  — the hook every view uses. `commit(change, { label?, undo? })` shows
+  the change at once, calls `onChange`, and on `{ ok: false }` takes it
+  back and sets `error` ("“Write brief” was not saved: … It is back as it
+  was.") — show it in a `Notice`. `undo: "Deleted “Write brief”"` also
+  shows a toast with Undo (it commits the inverse; deleted tasks come back
+  with their ids). It returns the page's answer. Example rows
+  (`useFixture`, `_sample`) change on screen and are never sent. The
+  change stays on screen until the page's `tasks` move on, so nothing
+  flickers back between the save and the re-read.
+- `applyChange(tasks, change)` · `invertChange(tasksBefore, change)` ·
+  `changedIds(change)`.
+- `changeWrites(change, { columns?, keepNewIds? })` — the change as plain
+  `{ op: "insert", values } | { op: "update", id, patch } | { op: "delete", id }`
+  rows. `columns` keeps only your table's keys (a new task carries empty
+  `tags` and `dependsOn` lists your table may not have); `keepNewIds:
+  false` drops a created task's client id (`new-…`, see `isNewId`) so the
+  table makes its own. Keep it (the default) when your id column is text
+  and the client id may stand.
+
+### Adapters for the existing blocks
+
+Drive `board` and `data-table` from tasks without touching them:
+
+```jsx
+const b = toBoard(visibleTasks, { groupBy: "status", ctx });   // or "assignees", "priority", "due"…
+<Board rows={b.rows} groupBy={b.groupBy} columns={b.columns} otherLabel={b.otherLabel}
+  onMove={(row, to, from) => commit(b.moveChange(row, to, from), { label: `“${row.title}”` })}
+  titleOf={(t) => t.title}
+  renderDetails={(t) => <><DueLabel value={t.due} ctx={ctx} /><AssigneeStack ids={t.assignees} ctx={ctx} /></>} />
+
+<DataTable rows={toTableRows(visibleTasks, ctx)}
+  columns={taskColumns(ctx, { keys: ["title", "status", "assignees", "due", "priority"], onChange: commit })}
+  facets={taskFacets(ctx)} noun="task" />
+```
+
+- `toBoard(tasks, { groupBy, ctx })` → `{ rows, groupBy: "__group", columns, otherLabel, moveChange(row, to, from) }`
+  — one card per task, under its first value; `moveChange` is
+  `movePatch` as an update (null when the column refuses it). Overdue is
+  not a column when grouped by due date.
+- `toTableRows(tasks, ctx)` → the tasks plus `statusLabel`, `statusIndex`,
+  `assigneeNames`, `projectName`, `priorityLabel`, `priorityRank`,
+  `dueDay`, `dueBucket`, `parentTitle`, `subtasks` ("2/5"), `done`.
+- `taskColumns(ctx, { keys?, onChange? })` — DataTable columns (title,
+  status, assignees, due, start, priority, project, estimate, progress,
+  tags), sortable, drawn with the parts; with `onChange` the status,
+  people, due and priority cells are pickers that send an update Change.
+- `taskFacets(ctx, { keys? })` — facets for status, assignee, priority,
+  project.
+
+### Parts every view shares
+
+Each is a label; with `onChange` it becomes a picker (a kit Menu or
+Popover) and hands the picked value back — you wrap it in a Change.
+
+- `<StatusPill status ctx onChange?(id) size?="sm"|"md" hideLabel? />` — dot + words.
+- `<CompleteToggle done onToggle label size?="md"|"sm" />` — the round
+  completion check (not the square selection Checkbox).
+- `<AssigneeStack ids ctx onChange?(ids) max?=3 size?="xs" />` — faces,
+  or a dashed "assign" circle; the picker ticks people (stays open).
+- `<PersonLabel id ctx />` — face + name ("Unassigned" for NONE).
+- `<DueLabel value done? ctx onChange?(day|null) quiet?=true placeholder? />`
+  — "Today" / "Fri" / "Oct 30", danger when overdue, warning today; the
+  picker is quick picks (Today, Tomorrow, Next week) + a calendar + Remove.
+  `quiet` hides an empty one's words until its row (`group/row`) is hovered.
+- `<PriorityFlag value onChange?(id|null) showLabel? />` — a flag in the
+  priority's tone.
+- `<TagList tags max?=2 />` · `<SubtaskCount done total />` ·
+  `<ProgressLine value />` (0–100).
+- `<TaskChip task ctx onOpen? showTime? showPeople? dragging? lifted? dragProps? />`
+  — a task on one compact line (status dot, time, title, first face, the
+  project's hue on its leading edge): a calendar day's item, a gantt
+  label, a workload cell.
+- `<GroupLabel group by ctx />` — a group heading's face for any field.
+- `TONE_TEXT` · `HUE_EDGE` · `HUE_BG` — the token classes those use
+  (tone → `text-…`, hue 1–5 → `border-s-chart-N` / `bg-chart-N`).
+
+Rows that host pickers should carry the `group/row` class: the quiet
+parts (an empty due date, an empty priority, a drag handle) appear when
+the row is hovered or focused, and always on touch.
+
+### ViewToolbar
+
+```jsx
+<ViewToolbar view={view} onViewChange={setView} ctx={ctx} tasks={allTasks}
+  count={shown.tasks.length} extra={<Button variant="primary" size="sm" icon="plus">Add task</Button>} />
+```
+
+Search (Escape clears), Filter (a popover of every filterable field with
+counts, and "Hide done tasks"), Group by, Sort (field + direction), Fields
+(which fields rows show), your `extra` at the end; active filters as
+chips underneath, each with ×, and "Clear filters". On a phone the search
+takes the first line and the controls are icons.
+
+- `view` · `onViewChange(nextView)` — controlled; a view object as above.
+- `ctx` · `tasks` (the counts in the filter menu).
+- `controls` — default `["search", "filter", "group", "sort", "fields"]`;
+  a calendar might pass `["search", "filter"]`.
+- `filterFields` · `groupFields` · `showableFields` — limit the choices.
+- `count` — "12 tasks" beside the controls (from 768px).
+- `searchPlaceholder` (default "Search tasks") · `extra` · `className`.
+
+### Drag primitives (@dnd-kit, never imported directly)
+
+One interaction model everywhere: a mouse drags after 5px, a finger after
+a short press (so lists still scroll), the keyboard picks up with Space
+or Enter, moves with the arrows, drops with Space, cancels with Escape;
+screen readers hear what was picked up and where it is.
+
+```jsx
+<TaskDragProvider
+  onDragEnd={({ active, over }) => { /* active.data / over.data are what you attached */ }}
+  overlay={(active) => <div className={LIFTED}><TaskChip task={active.data.task} ctx={ctx} /></div>}
+  collision="list">
+  <SortableGroup ids={ids}>…rows using useSortableTask…</SortableGroup>
+  …cells using useDropTarget, chips using useDraggableTask…
+</TaskDragProvider>
+```
+
+- `<TaskDragProvider onDragStart? onDragOver? onDragEnd? onDragCancel? overlay? collision? describe? place? disabled? />`
+  — callbacks get `{ active: { id, data }, over: { id, data } | null, delta }`.
+  `overlay(active)` draws the lifted copy (tilted 1°, 150ms drop; flat
+  and instant under reduced motion). `collision`: `"list"` (default: the
+  item under the pointer, else the group under it, else — keyboard — the
+  closest) · `"closest"` · `"pointer"` (grids and calendars) · `"rect"` ·
+  a function. `describe(active)` / `place(over)` word the announcements
+  (default `data.task.title`, `data.label`).
+- `<SortableGroup ids layout?="vertical"|"horizontal"|"grid">` — items that
+  reorder among themselves.
+- `useSortableTask(id, data, { disabled })` → `{ setNodeRef, setHandleRef, style, handle, isDragging, isOver }`
+  — `setNodeRef` + `style` on the item, `handle` spread on its grip.
+- `useDraggableTask(id, data)` → `{ setNodeRef, setHandleRef, handle, style, transform, isDragging }`
+  — a free item dropped on targets (a calendar chip, a gantt bar; use
+  `delta` in onDragEnd for a resize or a pixel shift).
+- `useDropTarget(id, data)` → `{ setNodeRef, isOver, active }` — a group,
+  a day cell, a person's week.
+- `<DragHandle handle handleRef? label alwaysVisible? />` — the grip, shown
+  on row hover (always on touch). `<DropLine />` — a landing line.
+- `LIFTED` — the lifted-card classes · `useReducedMotion()` · `arrayMove`.
+
+How a drop becomes a save: read `over.data` (a group key, a day, a
+person), build the patch (`movePatch`, `shiftDates`, `spanPatch`, or
+`placeChange` for an order), `commit` it.
+
+## Example
+
+A minimal view on the model — search, filter and group from the toolbar,
+tasks as chips, drag a chip to another status:
+
+```jsx
+"use client";
+import { useMemo, useState } from "react";
+import { Notice } from "./ui";
+import {
+  DEFAULT_VIEW, TaskChip, TaskDragProvider, ViewToolbar, applyView, createTaskContext,
+  movePatch, useDraggableTask, useDropTarget, useTaskChanges, LIFTED,
+} from "./blocks/task-model";
+
+export default function StatusLanes({ tasks, statuses, people, onChange }) {
+  const ctx = useMemo(() => createTaskContext({ statuses, people }), [statuses, people]);
+  const { tasks: live, commit, error, clearError } = useTaskChanges(tasks, onChange);
+  const [view, setView] = useState({ ...DEFAULT_VIEW, groupBy: "status" });
+  const { groups } = applyView(live, view, ctx);
+  return (
+    <div className="grid gap-3">
+      <ViewToolbar view={view} onViewChange={setView} ctx={ctx} tasks={live} controls={["search", "filter"]} />
+      {error ? <Notice tone="danger" onDismiss={clearError}>{error}</Notice> : null}
+      <TaskDragProvider collision="pointer"
+        overlay={(a) => <div className={LIFTED}><TaskChip task={a.data.task} ctx={ctx} /></div>}
+        onDragEnd={({ active, over }) => {
+          if (!over) return;
+          const patch = movePatch(active.data.task, "status", active.data.group, over.data.group, ctx);
+          if (patch && over.data.group !== active.data.group) commit({ type: "update", id: active.data.task.id, patch });
+        }}>
+        {groups.map((g) => <Lane key={g.key} group={g} ctx={ctx} />)}
+      </TaskDragProvider>
+    </div>
+  );
+}
+
+function Lane({ group, ctx }) {
+  const drop = useDropTarget(`lane-${group.key}`, { group: group.key, label: group.label });
+  return (
+    <section ref={drop.setNodeRef} className={drop.isOver ? "rounded-lg bg-accent p-2" : "rounded-lg p-2"}>
+      <h3 className="text-sm font-semibold">{group.label}</h3>
+      <ul className="mt-2 grid gap-1">{group.tasks.map((t) => <Chip key={t.id} task={t} group={group.key} ctx={ctx} />)}</ul>
+    </section>
+  );
+}
+
+function Chip({ task, group, ctx }) {
+  const d = useDraggableTask(task.id, { task, group });
+  return <li ref={d.setNodeRef}><TaskChip task={task} ctx={ctx} dragging={d.isDragging} dragProps={d.handle} /></li>;
+}
+```
+
+## What it will not do
+
+- Draw a whole view: that is `task-list`, `board` (through `toBoard`),
+  `data-table` (through `toTableRows`), and the calendar / gantt /
+  workload blocks built on this one.
+- Fetch or save: tasks come in as props, changes go out through the
+  page's `onChange`.
+- Recurring tasks, time zones, or time tracking: a date is a wall-calendar
+  day (and time); a repeat is the page's to create.
+- Sync between people live: the page re-reads.
+
+Its files are fixed: `npm run check` refuses a change, and `makersclaw
+add task-model` restores them. A view it cannot be is your own component
+built from these exports.
+
+## Credits
+
+The drag primitives wrap @dnd-kit (MIT, https://dndkit.com): core 6.3.1,
+sortable 10.0.0, utilities 3.2.2.

package/registry/blocks/task-model/block.json

@@ -0,0 +1,167 @@
+{
+  "name": "task-model",
+  "title": "Task model",
+  "description": "The shared work-item model every task view reads: one task shape (status, assignees, start/due, estimate, progress, priority, parent, dependencies, location, tags, project, extra fields) with statuses, people and projects; pure helpers to search, filter, group by any field, sort, nest subtasks, do date math (week and month grids, working days, overlaps, time scales), sum capacity per person, follow dependencies and the critical path, and apply, undo and persist changes; the shared parts (StatusPill, AssigneeStack, DueLabel, PriorityFlag, TaskChip, CompleteToggle), the ViewToolbar (search, filter chips, group by, sort, show fields), drag primitives on @dnd-kit, a hook for optimistic saves with rollback and undo, and adapters that drive the Board and DataTable blocks from tasks.",
+  "useWhen": "You are building a view of work items \u2014 a list, calendar, gantt, workload, roadmap or a switcher between them \u2014 or driving Board / DataTable from tasks. Views import it; a surface rarely renders it alone. Not for records that are not work (use data-table or board directly).",
+  "tags": [
+    "tasks",
+    "task",
+    "work items",
+    "project management",
+    "model",
+    "filter",
+    "group",
+    "sort",
+    "subtasks",
+    "dates",
+    "calendar math",
+    "workload",
+    "capacity",
+    "dependencies",
+    "critical path",
+    "toolbar",
+    "drag",
+    "drop",
+    "dnd-kit",
+    "optimistic",
+    "undo",
+    "clickup",
+    "linear",
+    "asana"
+  ],
+  "exports": [
+    "NONE",
+    "PRIORITIES",
+    "DEFAULT_STATUSES",
+    "TASK_FIELDS",
+    "DEFAULT_VIEW",
+    "normalizeTask",
+    "normalizeTasks",
+    "createTaskContext",
+    "fieldOf",
+    "isDone",
+    "doneStatusId",
+    "openStatusId",
+    "toggleDoneChange",
+    "newTaskId",
+    "draftTask",
+    "valuesOf",
+    "optionsOf",
+    "labelOf",
+    "searchText",
+    "searchTasks",
+    "filterTasks",
+    "orderOf",
+    "sortTasks",
+    "sortOptions",
+    "groupTasks",
+    "groupOptions",
+    "movePatch",
+    "applyView",
+    "activeFilterCount",
+    "rankBetween",
+    "placeChange",
+    "childrenMap",
+    "buildTree",
+    "flattenTree",
+    "descendantIds",
+    "ancestorIds",
+    "subtaskCounts",
+    "rollup",
+    "progressOf",
+    "dependencyEdges",
+    "blockersOf",
+    "wouldCycle",
+    "dateConflicts",
+    "criticalPath",
+    "hoursPerDay",
+    "workload",
+    "sumOf",
+    "applyChange",
+    "invertChange",
+    "changeWrites",
+    "changedIds",
+    "deleteChange",
+    "toBoard",
+    "toTableRows",
+    "taskFacets",
+    "StatusPill",
+    "CompleteToggle",
+    "AssigneeStack",
+    "PersonLabel",
+    "DueLabel",
+    "PriorityFlag",
+    "TagList",
+    "SubtaskCount",
+    "ProgressLine",
+    "TaskChip",
+    "GroupLabel",
+    "taskColumns",
+    "TONE_TEXT",
+    "HUE_EDGE",
+    "HUE_BG",
+    "TaskDragProvider",
+    "SortableGroup",
+    "useSortableTask",
+    "useDraggableTask",
+    "useDropTarget",
+    "DragHandle",
+    "DropLine",
+    "LIFTED",
+    "useReducedMotion",
+    "arrayMove",
+    "isDay",
+    "dayNumber",
+    "fromDayNumber",
+    "dayOf",
+    "minutesOf",
+    "withTime",
+    "todayDay",
+    "addDays",
+    "diffDays",
+    "weekdayOf",
+    "startOfWeek",
+    "endOfWeek",
+    "weekDays",
+    "startOfMonth",
+    "endOfMonth",
+    "addMonths",
+    "daysBetween",
+    "monthGrid",
+    "WEEKEND",
+    "isWeekend",
+    "isWorkingDay",
+    "workingDaysBetween",
+    "addWorkingDays",
+    "spanOf",
+    "spansOverlap",
+    "tasksInRange",
+    "tasksOnDay",
+    "shiftDates",
+    "spanPatch",
+    "dueBucket",
+    "DUE_BUCKETS",
+    "dayForBucket",
+    "formatDay",
+    "formatTime",
+    "formatDate",
+    "timeScale",
+    "rangeOfTasks",
+    "isNewId"
+  ],
+  "files": [
+    "index.js",
+    "model.js",
+    "dates.js",
+    "changes.js",
+    "parts.jsx",
+    "toolbar.jsx",
+    "dnd.jsx"
+  ],
+  "requires": [],
+  "dependencies": {
+    "@dnd-kit/core": "6.3.1",
+    "@dnd-kit/sortable": "10.0.0",
+    "@dnd-kit/utilities": "3.2.2"
+  }
+}