@umriss-ui/schedule 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changes to `@umriss-ui/schedule`
+
+This document describes what changes for **callers** of the package: exports,
+props, behaviour. What was worked on in the repository stands in the
+repository's journal (`docs/journal.md`) and in the specs under `.scratch/`.
+
+**The numbers.** The middle digit rises when something is added; the last one
+when something is repaired. As long as the first digit is `0`, no number
+promises compatibility — which is why whatever changes existing behaviour stands
+under a heading "Changed" of its own, no matter which digit rose.
+
+**Release candidates.** The package started as a release candidate under the
+tag `next`. With `0.1.0` it is released: the tag is gone, and the interface
+moves from here under the rule above.
+
+---
+
+## 0.1.0 – The first release (Sep. 2026)
+
+No longer a release candidate: the tag `next` is gone, `pnpm add
+@umriss-ui/schedule` is the whole install line, and `@umriss-ui/core` and
+`@umriss-ui/charts` are released versions too. What the candidate `0.1.0-rc.0`
+was is still here; three deliveries stand on top of it, newest first, each with
+its own report below.
+
+The numbers keep their meaning from here: the middle digit rises when something
+is added, the last one when something is repaired, and whatever changes
+existing behaviour stands under a heading "Changed" of its own. As long as the
+first digit is `0`, no number promises compatibility.
+
+---
+
+## Lanes that fold, and one language for the bars (Sep. 2026)
+
+Delivery report for `.scratch/schedule-lane-groups/spec.md`, tickets 01–11.
+
+### Added
+
+- **`<LaneGroup id label>`** puts structure over the lanes — halls, lines,
+  machine groups, to any depth. It is declared by composition, so a group reads
+  in JSX as it reads in the plant, and a lane never names its group.
+
+  A group is **never a lane** (ADR-0025). Nothing sits on it: a subtask names a
+  machine, a finding belongs to a machine, `canMoveTo` is asked about a machine
+  and every intent names one. Folding a group changes none of it.
+
+  ```tsx
+  <Schedule …>
+    <LaneGroup id="hall-a" label="Hall A">
+      <LaneGroup id="turning" label="Turning line">
+        <Lane id="lathe-1" label="Lathe 1" />
+        <Lane id="lathe-2" label="Lathe 2" />
+      </LaneGroup>
+      <Lane id="press-1" label="Press 1" />
+    </LaneGroup>
+    <Lane id="paint" label="Paint shop" />
+  </Schedule>
+  ```
+- **`collapsedGroups`, `defaultCollapsedGroups` and `onCollapsedGroupsChange`**
+  say which groups are folded — controlled, with an uncontrolled default: the
+  shape `selectedTask` has. It is **not an intent**. Folding says what is on
+  screen and nothing about the plan, so a caller that applies every intent it
+  receives will never find a fold among them.
+- **A folded group shows a miniature**: every lane in it as a thin strip, at a
+  smaller scale, with its work in the tasks' own colours. Transports arrive at
+  a strip, a finding inside a fold is marked on the strip and on the row, and a
+  strip can be hovered, tooltipped and selected. A strip carries no appearance,
+  no bar label, no progress rail and no grips — that is what unfolding is for.
+- **The header of a group** carries a chevron button with `aria-expanded` and
+  `aria-controls`, the group's label and how many lanes it holds; children
+  indent one step per level. It is the first thing the schedule puts into the
+  tab order, and it has a focus ring of its own. Two wording entries in English
+  and in `@umriss-ui/core/wording/de`, plus the lane count.
+- **A drag held over a folded group opens it** after a moment, so work can be
+  moved into a group without preparing the view first. It closes again when the
+  drag ends, and the caller's list is never written to — the application did
+  not fold anything, and hears nothing.
+
+### Changed
+
+- **Every appearance is drawn differently.** The words a caller writes are
+  unchanged and so is `resolveAppearance`; the picture is not. Each statement
+  now owns exactly one property of the drawing, so that several on one bar stay
+  several statements:
+  - `"provisional"` is **hollow** - no fill at all, the surface shows through,
+    with its dashed outline in the task colour at full weight. It used to be a
+    45-per-cent fill, which read as a setup; empty is not faint.
+  - `"fixed"` carries a **cap at each end** of the main time, three pixels, in
+    the colour the bar's label takes, set just inside the end. The hatch across
+    its face is gone: it lay under the label, and it was the loudest mark in
+    the picture for the calmest statement.
+  - `"muted"` is at **full height** in the task colour mixed half into the
+    surface, opaque and without an outline. It used to be drawn at half height,
+    which read as a different kind of thing and cost it its label.
+  - `"open"` **fades at whichever edge of the view** the bar passes, left as
+    well as right. A bar that began before the view used to say nothing at all.
+- **A `progress` rail** lies within the main time and above the bar's lower
+  edge. It measures the work, so it stops where the main time does.
+- **A hatch now means one thing only**: a lane a drag may not put its work on.
+  It is no longer a mark on any bar.
+- **A refused lane is visible before it is met.** The lanes `canMoveTo` turns
+  down are marked from the first frame of a drag - drawn back and hatched, and
+  their headers with them (`[data-lane][data-refused]`, to style beside the
+  schedule). Over one of them the cursor says no and a hairline ties the ghost
+  to the pointer it is not following.
+- **A refused lane no longer costs the whole gesture.** A drop after one still
+  reports the move in time; only the lane change is dropped. `canMoveTo` is
+  asked once per lane when a drag takes hold, and again at the drop.
+- **`ScheduleHandle` answers for a folded lane** with its strip:
+  `clientPointOf` and `positionAt` read the place a lane is actually drawn, so
+  a caller's own marks keep pointing at the work when a group folds.
+
+---
+
+## A plan one can read (Sep. 2026)
+
+Delivery report for `.scratch/schedule-legibility/spec.md`, tickets 01–06.
+The formats of `@umriss-ui/core` became English in the same delivery
+(ADR-0024), which is what the dates and numbers of a schedule follow.
+
+### Added
+
+- **`label`** writes a line into every bar: the order, the article, whatever a
+  planner reads first. It is real DOM text, cut off with an ellipsis where the
+  bar is too narrow, left out where nothing would be readable, and held at the
+  view's edge for a bar that began before it. Its colour follows the brightness
+  of the bar's.
+- **`route`, `anchor` and `ends`** decide how a transport is drawn: a curve, a
+  straight line or orthogonal segments; from the middle of a bar or from the
+  edge facing the other stop; with or without a dot at each end. All three are
+  options of the schedule and all three are overridable per transport. They
+  change the picture and never a finding - `leaves` and `arrives` alone decide
+  whether a transport is late.
+- **`appearance` and `progress` on a subtask:** `"provisional"` (a dashed
+  outline), `"fixed"` (a hatch), `"muted"` (drawn slim), `"open"` (fading where
+  it continues past the view), and a share of the work that is done, drawn as a
+  rail along the bar. Each is a pattern or an outline and not only a colour, and
+  none of them uses the faint fill that means a setup or a teardown.
+- **`canMoveTo(subtask, lane)`** narrows where a drag may land. The ghost stays
+  on the last lane that was allowed and says "Not this lane"; a refused drop
+  reports nothing. It is asked for work dragged in from outside as well. Two
+  wording entries come with it.
+
+---
+
+## The schedule in daily use (Sep. 2026)
+
+Delivery report for `.scratch/schedule-refinement/spec.md`, tickets 01–09.
+Read **Changed** first: the wheel does something else now.
+
+### Changed
+
+- **The wheel scrolls the lanes** and lets the page scroll on once they are at
+  their end. **Ctrl or ⌘ with the wheel, and a pinch, zoom**; a horizontal
+  wheel or Shift with a vertical one pans through time. Before this, every
+  wheel movement zoomed, which trapped the wheel on a long page and left
+  twenty lanes unreachable by it.
+- **`onSelectedTaskChange` carries the clicked subtask** as a second argument
+  (null for a click on a transport or on nothing), and is called again when
+  another subtask of the same task is clicked. A caller that reads only the
+  first argument is unaffected.
+
+### Added
+
+- **A tooltip** on a hovered subtask or transport: the order, the stop, its
+  times, setup and teardown, the transport's route and duration, and the
+  findings on it. `tooltip={false}` switches it off; a function replaces its
+  content and receives a `ScheduleTooltipTarget` with the findings.
+- **`now`** draws a line across the lanes at the present: `true` follows the
+  clock by the minute, an instant fixes it there. Off by default.
+- **A drag near the edge of the plot pans the plot along**, faster the closer
+  to the edge, so a subtask reaches a time that was not in view in one
+  gesture.
+- **`snap` takes a raster with an offset** (`{ step, offset }`): shifts at
+  06:00, 14:00 and 22:00 are eight hours offset by six. A snapped time that
+  would land in time an operating calendar removes moves on to the seam, so an
+  intent never asks for a time the plant does not run.
+- **`shiftTask(subtasks, task, by)`** returns one move intent per stop of a
+  task - the whole order moved, distances kept.
+- **The place intent and `placing`:** work that is not on the plan can be
+  dragged in from any list, with the platform's drag and drop. The application
+  declares what it is dragging in `placing` while it drags; a drop on a lane
+  reports `{ kind: "place", item, task, lane, from, to, setup, teardown }`.
+  `subtaskFromPlace(intent, id)` builds the subtask, `applyIntent` leaves the
+  data alone for it, and `ripple` pushes nothing until the subtask exists.
+  Without `"place"` in `intents` no drop is accepted.
+- **`onDomainChange`** reports the visible span after the planner pans or
+  zooms - for keeping a second schedule, or a chart's time axis, in step. A
+  span handed in through `initialDomain` is not reported back.
+- **A ref handle** (`ScheduleHandle`): `positionAt(clientX, clientY)`,
+  `clientPointOf(time, lane?)`, `visibleDomain()`.
+
+---
+
+## 0.1.0-rc.0 – The schedule (Sep. 2026)
+
+Delivery report for `.scratch/schedule/spec.md` (ADR-0022, ADR-0023). Not yet
+published.
+
+### Added
+
+- **`Schedule`** with **`Lane`**, **`Subtasks`** and **`Transports`** declared
+  as children. Lane headers at the left as text, a day band above the plot and a
+  time band below it that steps from the day down to the quarter hour with the
+  zoom. Subtasks drawn with main time, setup and teardown in their task's colour;
+  transports as lines from an end to a start, anchored per transport
+  (`leaves`, `arrives`). Canvas colours follow `color-scheme`.
+- **Findings drawn and never resolved:** an overlap on a lane — setup and
+  teardown included — offset and marked; a late transport dashed in the finding
+  colour.
+- **Pan and zoom:** drag the background in both directions, the wheel and a
+  pinch zoom around the pointer, a horizontal wheel pans; `zoomLimits`. An
+  operating calendar (`calendar`) cuts removed time out of the axis.
+- **Interaction:** `onInteraction` reports click, context menu and hover with
+  the hit (subtask and part, transport, lane, nothing), the client point, the
+  time and the lane. A click selects the whole task; `selectedTask` and
+  `onSelectedTaskChange` control it.
+- **Controlled editing:** `intents` and `onIntent` — move, lane, stretch at the
+  edges, setup and teardown grips on the selected subtask — with a ghost that
+  shows its times and findings while the drag is in flight; Escape cancels.
+  `snap`: the tick raster by default, a step, or `false`.
+- **The arithmetic:** `findings`, `overlaps`, `lateTransports`, `ripple`,
+  `applyIntent`, `snapTime`, `occupied`, `departure`, `arrival`, and the types
+  `Task`, `Subtask`, `Transport`, `Intent` and its five kinds.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Roman Händler
+
+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 OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @umriss-ui/schedule
+
+The schedule of a plant: **subtasks** on **lanes** over time. One task runs
+across several machines in a fixed order, each stop has a main time with a
+setup before it and a teardown after it, and between the stops lie
+**transports** with durations of their own. The schedule draws all of it, marks
+what cannot work — two subtasks on one machine at once, a transport that cannot
+arrive in time — and lets a planner move things by hand without ever changing
+the plan underneath them.
+
+## Install
+
+```bash
+pnpm add @umriss-ui/schedule @umriss-ui/core @umriss-ui/charts
+```
+
+Both `@umriss-ui/core` and `@umriss-ui/charts` are **peer dependencies**
+(ADR-0022): the schedule takes its styling regime, provider, formats and
+wording from core, and its time arithmetic — the affine scale, the time steps,
+the operating calendar, the canvas colour resolution — from charts. React 18 or
+19 as a peer as well.
+
+## The smallest schedule that runs
+
+```tsx
+import { Lane, Schedule, Subtasks, Transports } from "@umriss-ui/schedule";
+import type { Subtask, Task, Transport } from "@umriss-ui/schedule";
+
+const at = (h: number, m = 0) => new Date(2026, 2, 17, h, m).getTime();
+
+const tasks: Task[] = [{ id: "a-2041", color: "#2563eb" }];
+const subtasks: Subtask[] = [
+  { id: "cut", task: "a-2041", lane: "saw", from: at(6), to: at(7), teardown: 10 * 60_000 },
+  { id: "mill", task: "a-2041", lane: "mill", from: at(8), to: at(10), setup: 30 * 60_000 },
+];
+const transports: Transport[] = [{ id: "move", from: "cut", to: "mill", duration: 15 * 60_000 }];
+
+export function Plan() {
+  return (
+    <Schedule ariaLabel="Plan of Tuesday" initialDomain={[at(5), at(12)]}>
+      <Lane id="saw" label="Saw" />
+      <Lane id="mill" label="Mill" />
+      <Transports data={transports} />
+      <Subtasks data={subtasks} tasks={tasks} />
+    </Schedule>
+  );
+}
+```
+
+## Editing is controlled
+
+The schedule draws the data it is given and changes none of it (ADR-0023). A
+drag shows a **ghost** with the findings the drop would create, and ends in an
+**intent** — move, lane, stretch, setup, teardown — reported to the caller:
+
+```tsx
+<Schedule
+  intents={["move", "lane"]}
+  onIntent={(intent) => setSubtasks((all) => all.map((s) => applyIntent(s, intent)))}
+  …
+>
+```
+
+`intents` lists what the application handles; without it the schedule is
+read-only. `canMoveTo(subtask, lane)` narrows it: a drag across a lane the
+subtask may not go to leaves the ghost where it was allowed and shows a
+refusal, and a refused drop reports nothing. A drag near the edge of the plot pans the plot along, and `snap`
+takes the tick raster, a step, or a step with an offset - shifts at 06:00,
+14:00 and 22:00 are eight hours offset by six.
+
+Dependent subtasks never move by themselves: `ripple` computes the cascade for
+the application to apply, or not, and `shiftTask` the moves of a whole order.
+`findings`, `overlaps` and `lateTransports` return what the schedule draws as
+data.
+
+Work that is not on the plan is dragged in from any list of the application,
+with the platform's drag and drop: the application says what it is dragging in
+`placing`, the drop reports a `place` intent, and `subtaskFromPlace` builds the
+subtask under the application's own id.
+
+## What a bar says
+
+`label` writes a line into every bar, cut off where the bar is too narrow and
+left out where nothing would be readable. `appearance` adds what a colour
+cannot say - `"provisional"`, `"fixed"`, `"muted"`, `"open"` - and `progress`
+draws the share that is done as a rail along the bar. `route`, `anchor` and
+`ends` decide how a transport is drawn, per schedule or per transport, without
+touching what a finding says.
+
+Each appearance owns exactly **one** property of the drawing, so several on one
+bar stay several statements: `"provisional"` the fill (none at all, the surface
+shows through), `"fixed"` the ends (a cap inside each), `"muted"` the
+saturation (the task colour half mixed into the surface, at full height), and
+`"open"` a fade at whichever edge of the view the bar passes. `progress` owns a
+rail inside the main time. The faint, outlined fill belongs to a setup and a
+teardown and to nothing else.
+
+## Lanes that fold
+
+`<LaneGroup>` puts halls, lines and machine groups over the lanes, to any
+depth. A group is structure and never a lane: nothing sits on it, no finding is
+reported for it, and no intent names it (ADR-0025).
+
+```tsx
+<LaneGroup id="hall-a" label="Hall A">
+  <LaneGroup id="turning" label="Turning line">
+    <Lane id="lathe-1" label="Lathe 1" />
+    <Lane id="lathe-2" label="Lathe 2" />
+  </LaneGroup>
+  <Lane id="press-1" label="Press 1" />
+</LaneGroup>
+```
+
+Folded, a group becomes one row showing a **miniature** — every lane in it as a
+thin strip, the real work smaller. Transports still arrive at the right strip,
+findings are still marked, and a strip can still be hovered and selected:
+folding costs a planner detail and never access. `collapsedGroups`,
+`defaultCollapsedGroups` and `onCollapsedGroupsChange` put the state in the
+application's hands; it is a view state, never an intent.
+
+## Reading and moving
+
+A tooltip on a hovered subtask or transport names the order, the times, setup
+and teardown and the findings; `tooltip` replaces its content or switches it
+off. `now` draws the present across the lanes. The wheel scrolls the lanes and
+releases the page at their end, Ctrl or ⌘ and a pinch zoom, Shift pans;
+`onDomainChange` reports the visible span, and a ref handle turns a client
+point into a time and a lane and back.
+
+## Where to read on
+
+* The demo — `pnpm dev:schedule` (port 4176) — is the documentation: every page
+  shows running examples with their source and the props generated from `src/`.
+* [`CHANGELOG.md`](CHANGELOG.md) — what changes for a caller.
+* The vocabulary — **Task**, **Subtask**, **Setup**, **Teardown**,
+  **Transport**, **Late transport**, **Lane header**, **Lane group**,
+  **Miniature**, **Intent**, **Ghost** — stands in the workspace's
+  `CONTEXT.md`, section "The schedule".