@setsquare/ui 0.9.1 → 0.11.0

package/dist/ui/timeline.d.ts

@@ -0,0 +1,231 @@
+import { type ReactNode } from 'react';
+import { type Key, type TreeProps as RACTreeProps } from 'react-aria-components';
+import { type SnapPoint, type TimeFormat } from '../lib/timeline-scale.js';
+import type { StatusTone } from './badge.js';
+export type { SnapPoint, TimeFormat } from '../lib/timeline-scale.js';
+/** A timeline's words, for the `labels` prop. Times inside them are said in words already ("1 minute, 4 seconds"). */
+export interface TimelineLabels {
+    /** The playhead's name. */
+    playhead: string;
+    /** A count of frames, said after the seconds of a timecode. */
+    frames: string;
+    /** A frame number, said for a `frames` timeline. */
+    frame: string;
+    /** A span's times: "{start} to {end}". */
+    span: string;
+    /** An item's name, its label and its time: "{label}, {time}". */
+    item: string;
+    /** Said when something being moved snaps to a point: "Snapped to {point}". */
+    snapped: string;
+    /** Said and shown when a marker is pressed without being dragged. */
+    picked: string;
+    /** Said and shown when a picked-up marker is put down. */
+    placed: string;
+    /** Said and shown when Escape puts a picked-up marker back. */
+    cancelled: string;
+    /** Every marker's description: the ways to move it. */
+    markerHint: string;
+}
+export declare const timelineLabels: TimelineLabels;
+/** The part of the timeline in view, for a slot to draw: times, and the scale between time and px. */
+export interface TimelineView {
+    /** The timeline's first and last time. */
+    start: number;
+    end: number;
+    /** The first and last time in view (the slot's own band of it). */
+    visibleStart: number;
+    visibleEnd: number;
+    pxPerSecond: number;
+    /** The track's whole width in px: draw `width` wide, or only the visible part. */
+    width: number;
+    /** A time's x in the track, in px. */
+    toX: (time: number) => number;
+}
+type TimelineName = {
+    'aria-label': string;
+} | {
+    'aria-labelledby': string;
+};
+export type TimelineProps = TimelineName & {
+    /** How long the timeline runs, in seconds. */
+    duration: number;
+    /** Its first time, in seconds: 0 for media, the first moment of a schedule (seconds since the epoch) for dates. */
+    start?: number;
+    /** How times are shown and said. Default `seconds`. */
+    format?: TimeFormat;
+    /** Frames per second, for `frames` and `timecode`. Default 25. */
+    fps?: number;
+    /** For `date`: the time zone the schedule is in. Default the reader's. */
+    timeZone?: string;
+    /** The zoom: px per second. Default 100. The ruler's labels and ticks adapt to it. */
+    pxPerSecond?: number;
+    /**
+     * What an arrow key moves the playhead and markers by, and what a pointer rounds to: one frame by default for
+     * `frames` and `timecode`, a tenth of a second for `seconds`, 15 minutes for `date`. Shift moves ten steps.
+     */
+    step?: number;
+    /** The playhead's time. Leave both out for a timeline without one. */
+    time?: number;
+    defaultTime?: number;
+    onTimeChange?: (time: number) => void;
+    /** Points markers snap to: frames are the step, so these are beats, downbeats, cuts. Each says its own name. */
+    snapPoints?: readonly SnapPoint[];
+    /** The id of the selected span or point. */
+    selectedItem?: string | null;
+    defaultSelectedItem?: string | null;
+    onSelectedItemChange?: (id: string | null) => void;
+    /** The label column's width in px. Default 160. Lane labels that don't fit are cut short. */
+    labelWidth?: number;
+    /** The most the timeline is tall, in px or any CSS length: past it, its rows scroll under the ruler. */
+    maxHeight?: number | string;
+    /** Scroll to keep the playhead in view as its time changes. Default true. Instant under reduced motion and at AAA. */
+    followPlayhead?: boolean;
+    labels?: Partial<TimelineLabels>;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Things over time, and the work on them: a ruler whose ticks and labels adapt to the zoom, a playhead to scrub,
+ * lanes of spans and points, markers people move, and slots for a product's own drawing (a waveform, thumbnails).
+ * One scroll container: the ruler stays at the top and the label column at the start while the rest scrolls both
+ * ways, and focus scrolls clear of both. Put `TimeRuler`, `TimelineSlot`, `TimelineMarkers` and `TimelineLanes`
+ * inside, in the order they stack.
+ *
+ * The playhead's line crosses every row. Times are seconds throughout; for `date`, seconds since the epoch. The
+ * axis runs left to right; right-to-left layouts aren't supported yet. Under it, a line says what moving a marker
+ * did (snapped, picked up, put down), and is read out as it changes.
+ */
+export declare function Timeline({ duration, start, format, fps, timeZone, pxPerSecond: pps, step: givenStep, time: givenTime, defaultTime, onTimeChange, snapPoints, selectedItem: givenItem, defaultSelectedItem, onSelectedItemChange, labelWidth, maxHeight, followPlayhead, labels, className, children, ...name }: TimelineProps): import("react").JSX.Element;
+export interface TimeRulerProps {
+    /** What the corner over the label column shows. Default the playhead's time, or nothing. */
+    corner?: ReactNode;
+    className?: string;
+}
+/**
+ * Ticks and labels along the top, which stay as the rows scroll. They adapt to the zoom: labels as close as they
+ * fit and no closer, at steps a reader expects (1, 2, 5, 10, 15, 30 seconds; frames; hours; days), with unlabelled
+ * ticks between. It is where the playhead lives: press anywhere on it to seek, drag to scrub.
+ *
+ * The playhead is a slider named "Playhead", its value said as a time ("1 minute, 4 seconds"), not a number. ← →
+ * move it a step (a frame), Shift ten, Page Up and Page Down a tenth of the timeline, Home and End to the ends.
+ * While a marker is picked up, pressing the ruler puts the marker there instead, and the playhead stays.
+ */
+export declare function TimeRuler({ corner, className }: TimeRulerProps): import("react").JSX.Element;
+export interface TimelineSlotProps {
+    /** Shown in the label column. */
+    label?: ReactNode;
+    /** The band's height in px. Default 48. */
+    height?: number;
+    /**
+     * Names the drawing for a screen reader (`role="img"`). Without it the drawing is hidden from them: a picture
+     * of the signal, which the lanes and the playhead's time already say.
+     */
+    'aria-label'?: string;
+    /** Draws the band, given the part in view. Draw `view.width` wide, or only `visibleStart` to `visibleEnd`. */
+    children: (view: TimelineView) => ReactNode;
+    className?: string;
+}
+/**
+ * A band across the timeline for the product's own drawing: a waveform canvas, a strip of thumbnails, a grid. It
+ * scrolls with the track; the playhead's line crosses it. Not a target: pointers pass through to nothing.
+ */
+export declare function TimelineSlot({ label, height, 'aria-label': named, children, className, }: TimelineSlotProps): import("react").JSX.Element;
+type LanesName = {
+    'aria-label': string;
+} | {
+    'aria-labelledby': string;
+};
+export type TimelineLanesProps = Omit<RACTreeProps<object>, 'className' | 'aria-label' | 'aria-labelledby' | 'children' | 'style'> & LanesName & {
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * The rows: React Aria's Tree, a `treegrid` and one tab stop. ↑ ↓ move between lanes, → opens a group and ← closes
+ * it, and typing jumps to a lane by name. → on a lane moves into its items, in time order; ← → move between them
+ * and back to the lane. Pressing a lane selects it (one at a time by default). Each lane is `--lane-height` tall:
+ * 32px, 24px in compact density, 44px at AAA, so its items are targets at least `--target-min` tall.
+ */
+export declare function TimelineLanes({ className, children, ...props }: TimelineLanesProps): import("react").JSX.Element;
+export interface TimelineLaneProps {
+    id: Key;
+    /** The lane's name, in the label column. Also how typing finds it and what a screen reader says. */
+    label: string;
+    /** Its spans and points, in any order: they're laid out, and reached by keyboard, in time order. */
+    items?: ReactNode;
+    /** The lanes inside this one, for a group that opens. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * One lane: its name in the label column, its items on the track. A lane with lanes inside it is a group, with a
+ * chevron to open it. Selected, it takes the `brand-subtle` ground and, in forced colours, a Highlight bar.
+ */
+export declare function TimelineLane({ id, label, items, children, className }: TimelineLaneProps): import("react").JSX.Element;
+export type TimelineTone = StatusTone;
+interface ItemBase {
+    id: string;
+    /** What it is: shown on a span when it fits, and always in its tooltip and its name. */
+    label: string;
+    tone?: TimelineTone;
+    /** More in its tooltip, under the label and time. */
+    details?: ReactNode;
+    className?: string;
+}
+export interface TimelineSpanProps extends ItemBase {
+    start: number;
+    end: number;
+}
+export interface TimelinePointProps extends ItemBase {
+    at: number;
+}
+/**
+ * Something that lasts, from `start` to `end`: a tween, a booking, a deploy. A bar in its tone; its target is the
+ * whole bar, as tall as the lane. Selecting it (pressing it, or Enter or Space on it) marks it with a ring; its
+ * label, times and `details` show on hover and focus.
+ *
+ * A bar is as wide as its time, however narrow that is: two moments close in time are close on screen. That rests
+ * on 2.5.8's Essential exception for the time axis; keyboard focus reaches every item, in time order, whatever its
+ * width. Items in a lane shouldn't overlap in time: put overlapping things in lanes of their own.
+ */
+export declare function TimelineSpan({ id, label, start, end, tone, details, className, }: TimelineSpanProps): import("react").JSX.Element;
+/**
+ * Something that happens at an instant, `at`: a cue, an error, a release. A diamond in its tone. Its target is
+ * `--target-min` wide, centred on its time, or narrower where a neighbour is closer than that, so targets never
+ * overlap; the narrow case rests on 2.5.8's Essential exception, as a span's does.
+ */
+export declare function TimelinePoint({ id, label, at, tone, details, className, }: TimelinePointProps): import("react").JSX.Element;
+export interface TimelineMarker {
+    id: string;
+    time: number;
+    /** A short name, shown on its flag: "Beat 3", "Chorus", "Cut". */
+    label: string;
+}
+export interface TimelineMarkersProps {
+    /** Shown in the label column, and names the group of markers. */
+    label: string;
+    markers: readonly TimelineMarker[];
+    /**
+     * Called as a marker moves, with where it is now (snapped, unless Alt or Option is held). Leave it out for
+     * markers that can't move: they are still focusable, and say their time.
+     */
+    onMove?: (id: string, time: number) => void;
+    /**
+     * Points to snap to, instead of the Timeline's `snapPoints`. A marker never snaps to a point with its own label
+     * at its own time, so a band's markers can be among its snap points.
+     */
+    snapPoints?: readonly SnapPoint[];
+    className?: string;
+}
+/**
+ * Flags at times, each with a short label, on a band of their own: under the ruler for markers and cue points, or
+ * beside the lanes for beats. Flags that would overlap stack into tiers, each a `--lane-height` row.
+ *
+ * Each flag is a slider (its value said as a time) and its own tab stop. People move one by:
+ * - dragging it, snapping to the snap points within 8px and otherwise to the step (a frame); Alt or Option moves it
+ *   freely. The point it snaps to is said, once each time it snaps.
+ * - the arrow keys: a step, Shift ten, caught by any snap point on the way; Alt or Option without snapping.
+ * - without dragging (2.5.7): click it to pick it up, then click the ruler or this band where it should go. Escape
+ *   puts it back. What happened shows, and is said, in the line under the timeline.
+ */
+export declare function TimelineMarkers({ label, markers, onMove, snapPoints, className, }: TimelineMarkersProps): import("react").JSX.Element;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/ui/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/ui/timeline.tsx"],"names":[],"mappings":"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"}