@umriss-ui/schedule 0.3.16 → 0.5.0

package/CHANGELOG.md

@@ -15,6 +15,127 @@ 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,
+every default a `@default` tag, and the demo lists all of it in an API index
+(ADR-0044). A group's lane count is fitted anew when the language changes.
+Needs `@umriss-ui/core` 0.25 and `@umriss-ui/charts` 0.10; the peer ranges move
+to `^0.25.0` and `^0.10.0`.
+
+### Added
+
+- **The First schedule page says what a screen reader meets**: a section
+  Accessibility after Keyboard names the plot's role, name and summary, the
+  readout after a key, the label to pass and what forced colours and reduced
+  motion change. Every other page with a schedule in its examples has a
+  Keyboard section linking First schedule's keys; Dependencies and Pan and
+  zoom also list the keys of their own feature there. In the demo, the
+  Markdown twins and `docs/llms-full.md`; the schedule is unchanged.
+- **Every export carries a comment**: what a component, a function or a type is
+  for, and for a function `@param` and `@returns` where its type alone does not
+  say it. The editor shows it on hover, from the package's `.d.ts`. Nothing
+  else changes.
+- **A prop's default stands in a `@default` tag** where its comment used to say
+  it in words: the editor shows it on hover, and the props table in its Default
+  column. Nothing else changes.
+- **`docs/llms-full.md` defines every type a props table names**: a type
+  without a table of its own (`Intent`, the charts' `WorkingCalendar`) stands
+  under "Types on this page" of each page that names it, with its comment and
+  its members or its declaration.
+- **The demo has an API index**: `/schedule/api/`, the last entry of the
+  sidebar, lists every export of `@umriss-ui/schedule`, grouped as components,
+  functions, constants and types, alphabetical - each value with its comment
+  and its declaration, each type with a link to its table or its definition,
+  and the pages that use it. A hook or a function a page names, in its text or
+  its import line, leads to its entry. `docs/llms-full.md` ends with the same
+  index, in place of the appendix "The rest of the API". The library is
+  unchanged.
+- **Every prop of a props table is shown, or named as an exception**: new
+  examples for groups that start folded (`defaultCollapsedGroups`), one
+  handover drawn its own way (a dependency's `attach` and `ends`) and a
+  tooltip that says what a bar covers and a line joins (`subtask`, `blocked`,
+  `dependency`, `from`, `to`); the list of findings now writes `departure`
+  and `arrival`, and "Report the pointer" names the lane, as its lead
+  promised. The two props left without an example, `className` and `style`,
+  are pass-throughs; the demo's list says so. The schedule is unchanged.
+
+### Fixed
+
+- **A group's lane count is measured anew when the language changes**: a
+  wording switched under a mounted schedule (English to German, say) left the
+  counts as the old wording had fitted them, so "2 Bahnen" stood beside a cut
+  name. Now the name wins over the count in every language, as it already did
+  after a reload - measured anew whenever the header column changes size or
+  anything it shows changes, a custom label's content included.
+- **`docs/llms-full.md` names the peers in its install line**:
+  `npm install @umriss-ui/schedule @umriss-ui/core @umriss-ui/charts`, read
+  from the manifest. It had named the schedule alone, and an install after it
+  lacked core and charts.
+
+---
+
 ## 0.3.16 – Core 0.24.0 (Oct. 2026)
 
 Needs `@umriss-ui/core` 0.24; the peer range moves to `^0.24.0`. Nothing else changes for a caller.

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
 
@@ -155,12 +164,16 @@ Done from this list: **blocked time** per lane.
 
 * The demo: <https://romanhaendler.github.io/umriss-ui/schedule/>, or locally
   `pnpm dev:schedule` (port 4176). It is the documentation — every page shows
-  running examples with their source and the props table generated from `src/`.
+  running examples with their source and the props table generated from `src/`,
+  each prop linked to the examples that show it. An API index lists every
+  export, one search finds across all five packages, and the header switches
+  the examples to German.
 * [`CHANGELOG.md`](CHANGELOG.md) — what changes for a caller.
 * **For a coding agent**: `docs/llms-full.md` inside the installed package —
   the demo as one Markdown file, pinned to the installed version: every page
   with its examples' source, its props tables and why it is built as it is,
-  and the declaration of every other export. Online, for the latest version:
+  and an index of every export with its comment and its declaration. Each
+  page also has a Markdown twin online; for the latest version:
   <https://romanhaendler.github.io/umriss-ui/schedule/llms.txt>.
 * The vocabulary — **Task**, **Subtask**, **Lead-in**, **Lead-out**,
   **Dependency**, **Violated dependency**, **Blocked time**, **Lane header**, **Lane group**,

package/dist/index.d.ts

@@ -35,8 +35,9 @@ 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 {
     /** The blocked time of the lanes - leave, maintenance, unavailability -, as
      the caller holds it: one list, each interval naming its lane. */
@@ -48,8 +49,9 @@ 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 {
     /** The dependencies, as the caller holds them. */
     data: readonly Dependency[];
@@ -68,11 +70,12 @@ export declare interface Dependency {
      begin as soon as the predecessor ends. */
     readonly lag: number;
     /** Where it leaves: at the end of the main time, or after the lead-out.
-     Default `"leadOut"` - the predecessor counts as ended once its lead-out is. */
+     The predecessor counts as ended once its lead-out is.
+     @default "leadOut" */
     readonly leaves?: "main" | "leadOut";
     /** Where it arrives: at the start of the main time, or before the lead-in.
-     Default `"leadIn"` - the lag must have run out before the successor's
-     lead-in begins. */
+     The lag must have run out before the successor's lead-in begins.
+     @default "leadIn" */
     readonly arrives?: "main" | "leadIn";
     /** How this one is drawn, where it is not drawn like the rest. It changes
      the picture and never the finding: whether a dependency is violated follows
@@ -145,24 +148,26 @@ 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;
     /** What the group's header says - the team, the depot, the region.
-     Real text, read by a screen reader; without one the header shows the id. */
+     Real text, read by a screen reader.
+     @default id */
     label?: ReactNode;
     /** `Lane`s and further `LaneGroup`s, to any depth. */
     children?: ReactNode;
@@ -177,11 +182,13 @@ export declare interface LaneIntent {
     readonly lane: string;
 }
 
+/** The props of `Lane`. */
 export declare interface LaneProps {
     /** The identity subtasks name in their `lane`. */
     id: string;
     /** What the lane header says - the person, vehicle or room. Real text, read by a
-     screen reader; without one the header shows the id. */
+     screen reader.
+     @default id */
     label?: ReactNode;
 }
 
@@ -278,6 +285,10 @@ export declare interface PlacingItem {
     readonly leadOut?: number;
 }
 
+/** Settles a subtask's appearances into what is drawn. `provisional` and
+ `fixed` contradict each other; the later one in the list wins.
+ @param appearance The subtask's `appearance`, in the order it was given.
+ @returns Which of the four channels are on. */
 export declare function resolveAppearance(appearance: readonly SubtaskAppearance[] | undefined): ResolvedAppearance;
 
 /** What the drawing needs to know, with the contradiction already settled.
@@ -285,8 +296,7 @@ export declare function resolveAppearance(appearance: readonly SubtaskAppearance
  The four names are the ones this module was born with, and they are kept so
  that a caller's code does not change because a picture did. Two of them are
  now named after a drawing they no longer use, and the channel each one
- really owns stands beside it (`sceneDraw.ts`, "ONE CHANNEL PER
- STATEMENT"). */
+ really owns stands beside it. */
 export declare interface ResolvedAppearance {
     /** `provisional`: the FILL - none at all, so the surface shows through, with
      a dashed outline in the task colour. Planned, not released. */
@@ -309,8 +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[];
 
-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 {
@@ -361,35 +369,79 @@ 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. */
+    /** Height in CSS pixels, both bands included. The width is the host's.
+     @default 400 */
     height?: number;
-    /** Height of one lane in pixels. */
+    /** Height of one lane in pixels.
+     @default 44 */
     laneHeight?: number;
     /** Width of the lane headers in pixels - at most 40 % of the schedule, so
-     that on a phone the plot keeps the larger part. */
+     that on a phone the plot keeps the larger part.
+     @default 160 */
     headerWidth?: number;
     /** A working calendar: the intervals in which time counts. Nights and
-     weekends outside them are cut out of the axis. Default: the wall clock. */
+     weekends outside them are cut out of the axis. Without intervals every
+     hour counts, as on the wall clock.
+     @default [] */
     calendar?: CalendarInput;
     /** The narrowest and widest time span zoom may reach, in milliseconds.
-     Default: one hour to 28 days. */
+     @default one hour to 28 days */
     zoomLimits?: ZoomLimits;
     /** The raster a drag lands on: `"ticks"` - the fine band's current step -, a
      step in milliseconds from local midnight, a step with an offset (shifts at
      06:00, 14:00 and 22:00 are eight hours offset by six), or `false` for none.
-     It shapes the ghost and the intent, never the data. */
+     It shapes the ghost and the intent, never the data.
+     @default "ticks" */
     snap?: "ticks" | number | SnapRaster | false;
     /** The intents the caller handles. Each one enables its interaction; none
-     leaves a read-only schedule (ADR-0023). */
+     leaves a read-only schedule (ADR-0023).
+     @default [] */
     intents?: readonly IntentKind[];
-    /** Whether a subtask may go to a lane. Without it every lane is open; it
-     narrows `"lane"`, it does not enable it.
+    /** Whether a subtask may go to a lane. It narrows `"lane"`, it does not
+     enable it.
 
      Asked once per lane when a drag takes hold, and asked again at the drop.
      The lanes it turns down are marked from the first frame of the drag - a
@@ -399,7 +451,8 @@ export declare interface ScheduleProps {
      nothing else: a drop after it still reports the move in time.
 
      It is asked for work dragged in from outside as well, with the key and
-     task the application declared in `placing`. */
+     task the application declared in `placing`.
+     @default every lane is open */
     canMoveTo?: (subtask: Subtask, lane: string) => boolean;
     /** Called once per intent when a drag ends. The data changes only if the
      caller changes it. */
@@ -415,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
@@ -441,19 +476,22 @@ export declare interface ScheduleProps {
     placing?: PlacingItem | null;
     /** How the dependencies are drawn: a `"curve"` that leaves and arrives
      forwards, a `"straight"` line, or `"orthogonal"` segments. A dependency may
-     say otherwise for itself. */
+     say otherwise for itself.
+     @default "curve" */
     route?: DependencyRoute;
     /** Where a dependency's ends sit on their bars: the `"centre"` of both, or the
      `"nearest"` edge - which is the shortest line between two stops. Within
      one lane both mean the middle. A dependency may say otherwise for itself.
 
      It changes the picture and never a finding: whether a dependency is violated
-     follows from its `leaves` and `arrives` alone. */
+     follows from its `leaves` and `arrives` alone.
+     @default "centre" */
     attach?: DependencyAttachment;
-    /** Whether a dependency's two ends carry a dot (`"dot"`, the default) or the
-     line stands alone (`"none"`). The dot says where the line is anchored - a
+    /** Whether a dependency's two ends carry a dot (`"dot"`) or the line
+     stands alone (`"none"`). The dot says where the line is anchored - a
      help while a plan is being read, and noise in a plan full of short moves.
-     A dependency may say otherwise for itself. */
+     A dependency may say otherwise for itself.
+     @default "dot" */
     ends?: DependencyEnds;
     /** What stands written in a bar: a function from a subtask to a line of
      text, or nothing for bars without text. The text is cut off with an
@@ -466,7 +504,8 @@ export declare interface ScheduleProps {
      what the pointer rests on and returns content of the application's own. */
     tooltip?: false | ((target: ScheduleTooltipTarget) => ReactNode);
     /** A line marking the present across the lanes: `true` follows the clock by
-     the minute, an instant fixes it there. Off by default. */
+     the minute, an instant fixes it there.
+     @default false */
     now?: boolean | number;
     /** Goes to the root element. */
     className?: string;
@@ -507,6 +546,26 @@ 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
+ intent, or run `ripple` over them first.
+ @param subtasks All subtasks; only those of `task` are moved.
+ @param task The id of the task, as its subtasks name it in `task`.
+ @param by How far, in milliseconds; negative is earlier.
+ @returns One move intent per subtask of the task - none where `by` is zero
+ or not finite. */
 export declare function shiftTask(subtasks: readonly Subtask[], task: string, by: number): MoveIntent[];
 
 /** A raster: a step, and where it starts after local midnight. */
@@ -570,8 +629,9 @@ 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 {
     /** The subtasks, as the caller holds them. The schedule never changes one. */
     data: readonly Subtask[];
@@ -592,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. */