@umriss-ui/schedule 0.3.16 → 0.4.0

package/CHANGELOG.md

@@ -15,6 +15,66 @@ moves from here under the rule above.
 
 ---
 
+## 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

@@ -155,12 +155,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

@@ -37,6 +37,7 @@ export declare interface BlockedTime {
  subtask and dependency: it is a property of the lane, not something on it. */
 export 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. */
@@ -50,6 +51,7 @@ export declare function departure(dependency: Dependency, from: Subtask): number
  bars; after them, above. */
 export 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
@@ -156,13 +159,15 @@ export declare function Lane({ id, label }: LaneProps): null;
  `Schedule` - a view state, never an **Intent**. */
 export 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:
      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,6 +319,12 @@ 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
@@ -361,35 +377,43 @@ export declare interface ScheduleInteraction {
     readonly lane: string | null;
 }
 
+/** 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 +423,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. */
@@ -441,19 +466,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 +494,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 +536,15 @@ export declare type ScheduleTooltipTarget = {
     readonly violated: ViolatedDependency | undefined;
 };
 
+/** 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. */
@@ -572,6 +610,7 @@ export declare function subtaskFromPlace(intent: PlaceIntent, id: string): Subta
 /** A layer of subtasks. Several layers draw in the order they are declared. */
 export 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[];