@umriss-ui/schedule 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -15,6 +15,67 @@ moves from here under the rule above.
 
 ---
 
+## 0.5.0 – Declared through useSchedule, with a view of its own (Oct. 2026)
+
+Released together with `@umriss-ui/charts` and `@umriss-ui/table`, which
+break in the same release. A schedule is declared through `useSchedule`, as a
+table is through `useTable` and a chart through `useChart` (ADR-0048), and it
+holds its own **view** - the span in view and the folded lane groups -, taken
+as a start and reported whole (ADR-0047). The free components and the
+controlled pairs are removed, not deprecated.
+
+### Changed
+
+**Moving over.** Every export and prop that went, and what stands in its
+place:
+
+| Was | Is |
+|---|---|
+| `import { Schedule, Lane, LaneGroup, Subtasks, Dependencies, BlockedTimes }` | `const { Schedule, Lane, … } = useSchedule()` - one `Schedule` per call; a ref on it still gives the `ScheduleHandle` |
+| `Schedule initialDomain` (required) | `useSchedule({ initialView: { domain } })`; without a span the schedule shows the extent of its subtasks |
+| `Schedule collapsedGroups` (controlled) | `view.folded`, and `toggleGroup`, `foldAll`, `unfoldAll` from `useSchedule`; or a new `initialView: { folded }` |
+| `Schedule defaultCollapsedGroups` | `useSchedule({ initialView: { folded } })` |
+| `Schedule onCollapsedGroupsChange` | `useSchedule({ onViewChange })`, `view.folded` |
+| `Schedule onDomainChange` | `useSchedule({ onViewChange })`, `view.domain` |
+
+- **`Schedule` and its parts are no exports of their own.** `useSchedule()`
+  hands them out; they keep their identity over every render. Their props
+  stay public types.
+- **A span is optional.** `initialDomain` was required; without a `domain`
+  in the view the schedule shows the extent of its subtasks, lead-in and
+  lead-out included, widened or narrowed around its middle into
+  `zoomLimits` - fitted once, not after every change of the data, so a
+  dragged bar does not make the plan jump; without subtasks the local day of
+  today.
+- **A view handed in applies by its content.** `initialDomain` went back to
+  a new pair of values; `initialView` applies whenever it differs in content
+  from the last one handed in - the folded groups compared as a set -, the
+  same view again changes nothing, and what it leaves out is reset. A group
+  id no group carries falls out. **A known limit:** a view handed in that
+  equals one the schedule reported less than a second ago, and that has not
+  come back yet, is taken for the schedule's own report coming back late and
+  is not applied - so that linked schedules do not jump back mid-pan. An
+  application that restores a just-reported view within that second sees no
+  change.
+- **One report for both.** `onViewChange(view)` replaces
+  `onDomainChange` and `onCollapsedGroupsChange`: every change once, always
+  the whole view, a pan or zoom at most once per frame, not the view the
+  schedule starts with. `selectedTask` and `onSelectedTaskChange` are a
+  selection, not the view, and stay as they are; so does `zoomLimits`.
+
+### Added
+
+- **`useSchedule({ initialView, onViewChange })`** with `view`,
+  `setDomain(span | null)` (`null` = the subtasks' extent), `toggleGroup(id)`,
+  `foldAll()` and `unfoldAll()` on what it hands back.
+- **Types**: `ScheduleParts`, `ScheduleOptions`, `ScheduleView`.
+- **The demo** has a page 'View' (keep a view across a reload and restore
+  it); 'Linked schedules' keep in step through a shared view, and Lane
+  groups' "Fold groups from outside" folds through the setters, at the
+  anchor `#fold-from-outside` - the old `#controlled` lands there.
+
+---
+
 ## 0.4.0 – Every export explained, and lane counts in every language (Oct. 2026)
 
 The package explains itself where it is used: every export carries a comment,

package/README.md

@@ -24,7 +24,7 @@ the working calendar, the canvas colour resolution — from charts. React 18 or
 ## The smallest schedule that runs
 
 ```tsx
-import { Lane, Schedule, Subtasks, Dependencies } from "@umriss-ui/schedule";
+import { useSchedule } from "@umriss-ui/schedule";
 import type { Subtask, Task, Dependency } from "@umriss-ui/schedule";
 
 const at = (h: number, m = 0) => new Date(2026, 2, 17, h, m).getTime();
@@ -37,8 +37,9 @@ const subtasks: Subtask[] = [
 const dependencies: Dependency[] = [{ id: "move", from: "cut", to: "mill", lag: 15 * 60_000 }];
 
 export function Plan() {
+  const { Schedule, Lane, Subtasks, Dependencies } = useSchedule({ initialView: { domain: [at(5), at(12)] } });
   return (
-    <Schedule ariaLabel="Plan of Tuesday" initialDomain={[at(5), at(12)]}>
+    <Schedule ariaLabel="Plan of Tuesday">
       <Lane id="saw" label="Saw" />
       <Lane id="mill" label="Mill" />
       <Dependencies data={dependencies} />
@@ -115,9 +116,8 @@ reported for it, and no intent names it (ADR-0025).
 Folded, a group becomes one row showing a **miniature** — every lane in it as a
 thin strip, the real work smaller. Dependencies 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.
+folding costs a planner detail and never access. Which groups are folded is
+part of the schedule's view, never an intent.
 
 ## Reading and moving
 
@@ -127,9 +127,18 @@ off. `now` draws the present across the lanes. The wheel over the schedule,
 lane headers included, scrolls the lanes and releases the page at their end,
 Ctrl or ⌘ and a pinch zoom, Shift pans; on a touch screen one finger pans and a
 tap selects. The lane headers take at most 40 % of the width, so that on a
-phone the plot keeps the larger part;
-`onDomainChange` reports the visible span, and a ref handle turns a client
-point into a time and a lane and back.
+phone the plot keeps the larger part; a ref handle turns a client point into a
+time and a lane and back.
+
+## The view
+
+The schedule holds its own view (ADR-0047): the span in view and the folded
+groups. `useSchedule({ initialView, onViewChange })` takes a start and reports
+every change, always the whole view; a view handed in that differs from the
+last one applies at once, so two schedules keep in step by handing each other
+what they report. Without a span the schedule shows the extent of its subtasks.
+`view`, `setDomain`, `toggleGroup`, `foldAll` and `unfoldAll` stand on what the
+hook hands back.
 
 ## Blocked time
 

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export declare interface BlockedTime {
 
 /** A layer of blocked time. Wherever it is declared, it is drawn behind every
  subtask and dependency: it is a property of the lane, not something on it. */
-export declare function BlockedTimes({ data }: BlockedTimesProps): null;
+declare function BlockedTimes({ data }: BlockedTimesProps): null;
 
 /** The props of `BlockedTimes`. */
 export declare interface BlockedTimesProps {
@@ -49,7 +49,7 @@ export declare function departure(dependency: Dependency, from: Subtask): number
 
 /** A layer of dependencies. Declared before `Subtasks`, the lines run beneath the
  bars; after them, above. */
-export declare function Dependencies({ data }: DependenciesProps): null;
+declare function Dependencies({ data }: DependenciesProps): null;
 
 /** The props of `Dependencies`. */
 export declare interface DependenciesProps {
@@ -148,20 +148,20 @@ export declare type IntentKind = Intent["kind"];
 
 /** One lane: a person, a vehicle, a room. The lanes run top to bottom in the order
  they are declared - whichever group they are declared in. */
-export declare function Lane({ id, label }: LaneProps): null;
+declare function Lane({ id, label }: LaneProps): null;
 
 /** A group of lanes: structure over them, and never a lane itself.
 
  It gives its id to its children through context, so a lane never names its
  group and a group reads in JSX as it reads in the organisation. Folded, it becomes
  one row showing a **Miniature** of everything in it; open, it shows a slim
- head above its lanes. Which groups are folded is `collapsedGroups` on
- `Schedule` - a view state, never an **Intent**. */
-export declare function LaneGroup({ id, label, children }: LaneGroupProps): ReactNode;
+ head above its lanes. Which groups are folded is part of the schedule's
+ view (`useSchedule`) - never an **Intent**. */
+declare function LaneGroup({ id, label, children }: LaneGroupProps): ReactNode;
 
 /** The props of `LaneGroup`. */
 export declare interface LaneGroupProps {
-    /** The group's identity - what `collapsedGroups` names. It is never a lane:
+    /** The group's identity - what the view's `folded` names. It is never a lane:
      no subtask sits on it, no finding is reported for it, and no intent names
      it (ADR-0025). */
     id: string;
@@ -319,14 +319,6 @@ export declare interface ResolvedAppearance {
  bounded number of pushes instead of running on. */
 export declare function ripple(subtasks: readonly Subtask[], dependencies: readonly Dependency[], intent: Intent): MoveIntent[];
 
-/** A plan of subtasks on lanes over time - people, vehicles, rooms - with
- dependencies between them. The contents are declared as children (`Lane`,
- `LaneGroup`, `Subtasks`, `Dependencies`, `BlockedTimes`); the planner pans,
- zooms and drags, and every drag ends as an **Intent** through `onIntent`.
- The data changes only where the caller applies it; without `intents` the
- schedule is read-only. A ref gives the `ScheduleHandle`. */
-export declare const Schedule: ForwardRefExoticComponent<ScheduleProps & RefAttributes<ScheduleHandle>>;
-
 /** What a schedule offers a caller imperatively: the arithmetic between a
  point on the screen and a time on a lane. Everything else is props. */
 export declare interface ScheduleHandle {
@@ -377,13 +369,49 @@ export declare interface ScheduleInteraction {
     readonly lane: string | null;
 }
 
+/** What `useSchedule` takes: the view to start from and the handler that
+ hears every change of it. */
+export declare interface ScheduleOptions {
+    /** The view to start from, and to go to whenever one differing in content
+     from the last is handed in - the same view again changes nothing, and
+     what it leaves out is reset; one the schedule reported itself, handed
+     back late, is its own state coming back and not gone to. The schedule
+     remembers none: where a view is kept is the application's decision. */
+    initialView?: ScheduleView;
+    /** Every change of the view, once, always the whole view - the one to keep,
+     or to hand another schedule as its `initialView`. A pan or zoom is
+     reported at most once per frame. Not called for the view the schedule
+     starts with. */
+    onViewChange?: (view: ScheduleView) => void;
+}
+
+/** What `useSchedule` hands back: the schedule and what is declared inside
+ it, its view and the setters that change it. */
+export declare interface ScheduleParts {
+    /** The schedule. One per `useSchedule`: a second schedule is a second call. */
+    Schedule: ForwardRefExoticComponent<ScheduleProps & RefAttributes<ScheduleHandle>>;
+    Lane: typeof Lane;
+    LaneGroup: typeof LaneGroup;
+    Subtasks: typeof Subtasks;
+    Dependencies: typeof Dependencies;
+    BlockedTimes: typeof BlockedTimes;
+    /** How the planner is looking at the plan: the span and the folded groups. */
+    view: ScheduleView;
+    /** Puts a span of two wall-clock instants in view; `null` shows the
+     subtasks' extent. */
+    setDomain: (span: readonly [number, number] | null) => void;
+    /** Folds or unfolds one **Lane group**. */
+    toggleGroup: (id: string) => void;
+    /** Folds every group. */
+    foldAll: () => void;
+    /** Unfolds every group. */
+    unfoldAll: () => void;
+}
+
 /** The props of `Schedule`. */
 export declare interface ScheduleProps {
     /** What the schedule shows, for a screen reader: "Plan of week 38". */
     ariaLabel: string;
-    /** The time in view when the schedule mounts, as two wall-clock instants.
-     Pan and zoom take it from there; a new pair of values puts it back. */
-    initialDomain: readonly [number, number];
     /** Height in CSS pixels, both bands included. The width is the host's.
      @default 400 */
     height?: number;
@@ -440,24 +468,6 @@ export declare interface ScheduleProps {
      nothing. It is called again when another subtask of the same task is
      clicked. */
     onSelectedTaskChange?: (task: string | null, subtask: string | null) => void;
-    /** The **Lane group**s that are folded, controlled. Leave it out and the
-     schedule keeps them itself, starting from `defaultCollapsedGroups`.
-
-     Folding changes the view and not the plan, which is why it is no intent:
-     a caller that applies every intent it receives must never find a fold
-     among them (ADR-0025). A folded outer group hides the inner ones without
-     their entries leaving the list, so unfolding it gives back the view that
-     was there. */
-    collapsedGroups?: readonly string[];
-    /** Which groups are folded when the schedule mounts, where the schedule
-     keeps the state itself. Ignored while `collapsedGroups` is given. */
-    defaultCollapsedGroups?: readonly string[];
-    /** Called with the whole list when the planner folds or unfolds a group. */
-    onCollapsedGroupsChange?: (groups: readonly string[]) => void;
-    /** The visible time span after the planner panned or zoomed, as two
-     wall-clock instants - for keeping a second schedule or a chart in step. A
-     span handed in through `initialDomain` is not reported back. */
-    onDomainChange?: (domain: readonly [number, number]) => void;
     /** What the application is dragging in from outside while it drags it - its
      key, task, the length of its main time, its lead-in and lead-out. The
      browser hands the dragged data over only on the drop, so the ghost before
@@ -536,6 +546,17 @@ export declare type ScheduleTooltipTarget = {
     readonly violated: ViolatedDependency | undefined;
 };
 
+/** How a planner is looking at the plan. Whatever is at its default is absent. */
+export declare interface ScheduleView {
+    /** The span in view, as two wall-clock instants. Absent, the schedule shows
+     the extent of its subtasks, within `zoomLimits`. */
+    domain?: readonly [number, number];
+    /** The **Lane group**s that are folded, by id. An id no group carries falls
+     out. A folded outer group hides the inner ones without their ids leaving
+     the list, so unfolding it gives back the view that was there. */
+    folded?: readonly string[];
+}
+
 /** The moves that carry a whole task in time - every subtask of it by the same
  amount, so that its lengths and the distances between its stops stay as
  they were. The schedule never runs it: apply the moves like any other
@@ -608,7 +629,7 @@ export declare type SubtaskAppearance = "provisional" | "fixed" | "muted" | "ope
 export declare function subtaskFromPlace(intent: PlaceIntent, id: string): Subtask;
 
 /** A layer of subtasks. Several layers draw in the order they are declared. */
-export declare function Subtasks({ data, tasks }: SubtasksProps): null;
+declare function Subtasks({ data, tasks }: SubtasksProps): null;
 
 /** The props of `Subtasks`. */
 export declare interface SubtasksProps {
@@ -631,6 +652,12 @@ export declare interface Task {
     readonly name?: string;
 }
 
+/** Declares a schedule: hands back `Schedule` and the parts declared inside it
+ - `Lane`, `LaneGroup`, `Subtasks`, `Dependencies`, `BlockedTimes` -, its
+ `view` and the setters `setDomain`, `toggleGroup`, `foldAll` and
+ `unfoldAll`. A ref on `Schedule` still gives the `ScheduleHandle`. */
+export declare function useSchedule(options?: ScheduleOptions): ScheduleParts;
+
 /** Every dependency whose successor is to be reached before the predecessor's
  departure plus the dependency's lag. A dependency naming a subtask that
  is not in the data is passed over: there is nothing to judge. */