@hussmartinez/ui 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/react.d.ts CHANGED
@@ -1455,6 +1455,349 @@ export declare interface ThemeProviderSingleProps extends ThemeProviderBaseProps
1455
1455
  readonly mode?: undefined;
1456
1456
  }
1457
1457
 
1458
+ /**
1459
+ * A timeline over whole units, such as frames or samples: a scrolling track
1460
+ * as wide as `length` at the current zoom, for a playhead, clips and an
1461
+ * editor's own layers (docs/adr/0011). It formats no time and has no text
1462
+ * of its own: names and values come from you.
1463
+ *
1464
+ * - **Zoom** is yours: `zoom` is a multiple of fitting `length` to the
1465
+ * width, and `onMaxZoomChange` says where it stops.
1466
+ * - **Snapping** pulls a pointer to the playhead, the clips' boundaries and
1467
+ * your `snapTargets`, within 8 CSS pixels at any zoom.
1468
+ * - **Layers** are your own drawing, such as a waveform, sized to the
1469
+ * track. `useTimelineScale()` gives them the same mapping the parts use.
1470
+ *
1471
+ * @example
1472
+ * ```tsx
1473
+ * <Timeline label={t("timeline.label")} length={frames} zoom={zoom} onMaxZoomChange={setMaxZoom}>
1474
+ * <TimelineLayer>
1475
+ * <Waveform />
1476
+ * </TimelineLayer>
1477
+ * <TimelinePlayhead
1478
+ * label={t("timeline.playhead")}
1479
+ * position={playhead}
1480
+ * onPositionChange={seek}
1481
+ * largeStep={framesPerSecond}
1482
+ * formatValue={formatTime}
1483
+ * />
1484
+ * </Timeline>
1485
+ * ```
1486
+ *
1487
+ * @public
1488
+ */
1489
+ export declare const Timeline: ForwardRefExoticComponent<TimelineProps & RefAttributes<HTMLElement>>;
1490
+
1491
+ /**
1492
+ * A clip on a {@link TimelineClips} track.
1493
+ *
1494
+ * @public
1495
+ */
1496
+ export declare interface TimelineClip {
1497
+ /** Identifies the clip in `selectedKeys`. Unique on the track. */
1498
+ readonly key: string;
1499
+ /** The clip's length, in the timeline's units: a whole number, at least 1. */
1500
+ readonly length: number;
1501
+ /**
1502
+ * The clip's accessible name, with its place and range, such as
1503
+ * "Clip 2 of 5, 0:04.00 to 0:09.20, muted". Use text from your message
1504
+ * catalogue.
1505
+ */
1506
+ readonly label: string;
1507
+ /** What the clip shows, such as its name or a thumbnail. It's cut off where the clip ends. */
1508
+ readonly content?: ReactNode;
1509
+ /** `data-*` attributes for the clip, for your own states, such as `data-muted`. */
1510
+ readonly attributes?: Readonly<Record<`data-${string}`, string | undefined>> | undefined;
1511
+ }
1512
+
1513
+ /**
1514
+ * A clip's edge: its start, or its end.
1515
+ *
1516
+ * @public
1517
+ */
1518
+ export declare type TimelineClipEdge = "start" | "end";
1519
+
1520
+ /**
1521
+ * The clip track of a {@link Timeline}: a horizontal listbox with one Tab
1522
+ * stop, each clip as wide as its length at the timeline's zoom
1523
+ * (docs/adr/0011).
1524
+ *
1525
+ * - **← and →** move between clips, and Home and End go to the first and
1526
+ * last. They follow the reading direction. The selection follows focus.
1527
+ * - **With `selectionMode="multiple"`,** Shift extends the selection from
1528
+ * the last clip chosen; Ctrl or ⌘ moves focus without changing it; Space
1529
+ * adds or removes the focused clip, and Shift+Space selects up to it;
1530
+ * Ctrl or ⌘+A selects every clip. A click selects, a Shift-click
1531
+ * extends, and a Ctrl- or ⌘-click adds or removes.
1532
+ * - **Clips are data.** Give each a `label` that says its place and range,
1533
+ * since a screen reader can't see where it is on the track.
1534
+ * - **When the focused clip goes,** focus moves to the clip that took its
1535
+ * place, or the one before, or the playhead, if focus was on the track.
1536
+ *
1537
+ * The clips' boundaries are snap targets for the rest of the timeline.
1538
+ *
1539
+ * @example
1540
+ * ```tsx
1541
+ * <TimelineClips
1542
+ * label={t("timeline.clips")}
1543
+ * selectionMode="multiple"
1544
+ * clips={plan.clips.map((clip, index) => ({
1545
+ * key: clip.key,
1546
+ * length: framesOf(clip),
1547
+ * label: t("timeline.clip", { index: index + 1, count: plan.clips.length, … }),
1548
+ * content: clip.name,
1549
+ * }))}
1550
+ * selectedKeys={selected}
1551
+ * onSelectedKeysChange={setSelected}
1552
+ * />
1553
+ * ```
1554
+ *
1555
+ * @public
1556
+ */
1557
+ export declare const TimelineClips: ForwardRefExoticComponent<TimelineClipsProps & RefAttributes<TimelineClipsHandle>>;
1558
+
1559
+ /**
1560
+ * What a {@link TimelineClips} ref gives.
1561
+ *
1562
+ * @public
1563
+ */
1564
+ export declare interface TimelineClipsHandle {
1565
+ /** Moves focus to a clip, and scrolls it into view. Returns whether it's on the track. */
1566
+ focusClip(key: string): boolean;
1567
+ }
1568
+
1569
+ /**
1570
+ * The parts of a clip track that `classNames` can target.
1571
+ *
1572
+ * @public
1573
+ */
1574
+ export declare type TimelineClipsPart = "root" | "clip" | "content";
1575
+
1576
+ /**
1577
+ * Props of {@link TimelineClips}.
1578
+ *
1579
+ * @public
1580
+ */
1581
+ export declare interface TimelineClipsProps extends StyleProps<TimelineClipsPart> {
1582
+ /** The track's accessible name, such as "Clips". Required. */
1583
+ readonly label: string;
1584
+ /** The clips, in the order they play. */
1585
+ readonly clips: readonly TimelineClip[];
1586
+ /**
1587
+ * `single`, the default, keeps one clip selected: the focused one.
1588
+ * `multiple` adds Shift to extend the selection, Ctrl or ⌘ to move
1589
+ * without changing it, and Space to add or remove the focused clip.
1590
+ */
1591
+ readonly selectionMode?: "single" | "multiple" | undefined;
1592
+ /** The selected clips' keys. */
1593
+ readonly selectedKeys: readonly string[];
1594
+ /** Called with the new selection, in the clips' order. */
1595
+ readonly onSelectedKeysChange: (keys: readonly string[]) => void;
1596
+ /**
1597
+ * Called when the user moves clips with Alt+← or Alt+→ (Option on macOS),
1598
+ * with the keys to move, in order, and `-1` for earlier or `1` for later.
1599
+ * They're the selected clips when the focused one is selected, and the
1600
+ * focused clip otherwise. Render the clips in the new order, or leave them
1601
+ * when the move isn't allowed. The keys are taken at the first and last
1602
+ * clips too, and without `onMove`, so the browser never goes back instead.
1603
+ */
1604
+ readonly onMove?: ((keys: readonly string[], direction: -1 | 1) => void) | undefined;
1605
+ /**
1606
+ * Called when the user changes a clip's length at one edge, by dragging
1607
+ * the edge or with Alt+`[` and Alt+`]`, with the change in units:
1608
+ * positive makes the clip longer at that edge, negative shorter. A drag
1609
+ * calls it once, when it ends. With it, each clip has edges to drag.
1610
+ */
1611
+ readonly onTrim?: ((key: string, edge: TimelineClipEdge, delta: number) => void) | undefined;
1612
+ /**
1613
+ * Called for `[` and `]` on a focused clip: set its start or its end to
1614
+ * the playhead. You know where the playhead is.
1615
+ */
1616
+ readonly onTrimToPlayhead?: ((key: string, edge: TimelineClipEdge) => void) | undefined;
1617
+ /** What Alt+`[` and Alt+`]` change an edge by, in units. Defaults to 1. */
1618
+ readonly trimStep?: number | undefined;
1619
+ /**
1620
+ * How far an edge can go, as `onTrim`'s `delta`, such as up to its
1621
+ * source's end. A drag stops there. Without it, a clip can shrink to one
1622
+ * unit and grow without limit.
1623
+ */
1624
+ readonly trimLimits?: ((key: string, edge: TimelineClipEdge) => {
1625
+ readonly min?: number;
1626
+ readonly max?: number;
1627
+ }) | undefined;
1628
+ }
1629
+
1630
+ /**
1631
+ * A layer of a {@link Timeline} for an editor's own drawing, such as a
1632
+ * waveform or a selected range: a box the size of the track. Layers and
1633
+ * parts stack in the order written. A layer is as tall as its content, and
1634
+ * at least `--hm-timeline-lane-height`.
1635
+ *
1636
+ * What a layer draws is invisible to assistive technology unless you say
1637
+ * otherwise, so give a text equivalent elsewhere, and mark a canvas
1638
+ * `aria-hidden`.
1639
+ *
1640
+ * @public
1641
+ */
1642
+ export declare const TimelineLayer: ForwardRefExoticComponent<TimelineLayerProps & RefAttributes<HTMLDivElement>>;
1643
+
1644
+ /**
1645
+ * Props of {@link TimelineLayer}.
1646
+ *
1647
+ * @public
1648
+ */
1649
+ export declare interface TimelineLayerProps extends HTMLAttributes<HTMLDivElement> {
1650
+ /** Your drawing: a canvas, markers, a selection. Size it to the layer. */
1651
+ readonly children?: ReactNode;
1652
+ }
1653
+
1654
+ /**
1655
+ * The parts of a timeline that `classNames` can target.
1656
+ *
1657
+ * @public
1658
+ */
1659
+ export declare type TimelinePart = "root" | "viewport" | "track";
1660
+
1661
+ /**
1662
+ * The playhead of a {@link Timeline}: a slider over the timeline's units,
1663
+ * and a line on the track at its position.
1664
+ *
1665
+ * - **The slider** is a `ui` `Slider` as wide as the track, so its thumb is
1666
+ * the playhead's handle. Arrow keys move by `step`, Page Up and Page Down
1667
+ * by `largeStep`, and Home and End go to the start and the end.
1668
+ * - **A press on the track** moves the playhead there, snapping to the
1669
+ * timeline's targets unless Alt is held.
1670
+ * - **It's the only part that renders as the playhead moves.** Give it the
1671
+ * position from a component of its own, and nothing else in the timeline
1672
+ * re-renders while playing.
1673
+ *
1674
+ * @public
1675
+ */
1676
+ export declare const TimelinePlayhead: ForwardRefExoticComponent<TimelinePlayheadProps & RefAttributes<HTMLInputElement>>;
1677
+
1678
+ /**
1679
+ * The parts of a timeline's playhead that `classNames` can target.
1680
+ *
1681
+ * @public
1682
+ */
1683
+ export declare type TimelinePlayheadPart = "root" | "slider" | "line";
1684
+
1685
+ /**
1686
+ * Props of {@link TimelinePlayhead}.
1687
+ *
1688
+ * @public
1689
+ */
1690
+ export declare interface TimelinePlayheadProps extends StyleProps<TimelinePlayheadPart> {
1691
+ /** The slider's accessible name, such as "Playhead". Required. */
1692
+ readonly label: string;
1693
+ /** Where the playhead is, in the timeline's units. */
1694
+ readonly position: number;
1695
+ /** Called with the unit the user moved the playhead to. */
1696
+ readonly onPositionChange: (position: number) => void;
1697
+ /** The arrow keys' step, in units. Defaults to 1. */
1698
+ readonly step?: number | undefined;
1699
+ /** The Page Up and Page Down step, in units, such as one second. */
1700
+ readonly largeStep?: number | undefined;
1701
+ /**
1702
+ * Writes a position as text for screen readers, such as "0:12.40",
1703
+ * exposed as `aria-valuetext`. Without it, they read the number of units.
1704
+ */
1705
+ readonly formatValue?: ((position: number) => string) | undefined;
1706
+ /**
1707
+ * Whether a press on the track, outside the clips and controls, moves the
1708
+ * playhead there. Defaults to `true`. Turn it off when a layer of yours
1709
+ * handles presses itself, such as one that selects a range by dragging.
1710
+ */
1711
+ readonly seekOnPress?: boolean | undefined;
1712
+ /**
1713
+ * Keeps the playhead in view by scrolling, as while playing. Without it,
1714
+ * the timeline scrolls only after a zoom.
1715
+ */
1716
+ readonly following?: boolean | undefined;
1717
+ }
1718
+
1719
+ /**
1720
+ * Props of {@link Timeline}.
1721
+ *
1722
+ * @public
1723
+ */
1724
+ export declare interface TimelineProps extends Omit<HTMLAttributes<HTMLElement>, "className">, StyleProps<TimelinePart> {
1725
+ /** The timeline's accessible name, such as "Timeline". Required. */
1726
+ readonly label: string;
1727
+ /** The length of what's on the timeline, in whole units, such as frames or samples. */
1728
+ readonly length: number;
1729
+ /**
1730
+ * The zoom, as a multiple of fitting `length` to the timeline's width.
1731
+ * Defaults to 1, which fits; less than 1 fits too.
1732
+ */
1733
+ readonly zoom?: number | undefined;
1734
+ /** The closest zoom, in CSS pixels for one unit. Defaults to 48. */
1735
+ readonly maxPixelsPerUnit?: number | undefined;
1736
+ /**
1737
+ * Called with the largest `zoom` that has an effect, when it changes with
1738
+ * the timeline's width or `length`, so zoom controls know when to stop.
1739
+ */
1740
+ readonly onMaxZoomChange?: ((maxZoom: number) => void) | undefined;
1741
+ /**
1742
+ * Whether pointers snap to targets, within 8 CSS pixels. Defaults to
1743
+ * `true`. Holding Alt turns it off for one gesture.
1744
+ */
1745
+ readonly snapping?: boolean | undefined;
1746
+ /** More units to snap to, such as markers. The playhead and the clips' boundaries always are. */
1747
+ readonly snapTargets?: readonly number[] | undefined;
1748
+ /**
1749
+ * Called with the units in view when they change, by scrolling, zooming
1750
+ * or resizing: for a layer that draws only what's visible, such as a
1751
+ * waveform on a canvas.
1752
+ */
1753
+ readonly onVisibleRangeChange?: ((range: TimelineRange) => void) | undefined;
1754
+ /** The timeline's parts and layers, in the order they stack. */
1755
+ readonly children?: ReactNode;
1756
+ }
1757
+
1758
+ /**
1759
+ * A range of a timeline, in whole units: `start` is the first unit in it,
1760
+ * and `end` is the one after its last.
1761
+ *
1762
+ * @public
1763
+ */
1764
+ export declare interface TimelineRange {
1765
+ readonly start: number;
1766
+ readonly end: number;
1767
+ }
1768
+
1769
+ /**
1770
+ * How a {@link Timeline} maps its units to pixels, for the parts and layers
1771
+ * inside it. Units are whole numbers, such as frames or samples
1772
+ * (sdk-core ADR 0042).
1773
+ *
1774
+ * @public
1775
+ */
1776
+ export declare interface TimelineScale {
1777
+ /** The timeline's length, in units. */
1778
+ readonly length: number;
1779
+ /**
1780
+ * CSS pixels for one unit at the current zoom. It's 0 until the timeline
1781
+ * has measured itself, which is after the first render in a browser, and
1782
+ * always on a server.
1783
+ */
1784
+ readonly pixelsPerUnit: number;
1785
+ /** A unit's distance from the start of the track, in CSS pixels. */
1786
+ readonly toPixels: (unit: number) => number;
1787
+ /**
1788
+ * The unit under a pointer, from its `clientX`, within `0…length`. It
1789
+ * follows the reading direction. With `snap`, it snaps to the timeline's
1790
+ * targets when `snapping` is on.
1791
+ */
1792
+ readonly unitAt: (clientX: number, options?: {
1793
+ readonly snap?: boolean;
1794
+ }) => number;
1795
+ /** A unit snapped to the nearest target within reach, or itself. */
1796
+ readonly snap: (unit: number) => number;
1797
+ /** The units in view now. Read it when you draw; it isn't state. */
1798
+ readonly visibleRange: () => TimelineRange;
1799
+ }
1800
+
1458
1801
  /**
1459
1802
  * A button that turns something on or off, such as loop playback or the
1460
1803
  * active tool, exposed as `aria-pressed`. Controlled with `pressed` and
@@ -1812,6 +2155,22 @@ export declare function useAnnounce(): Announce;
1812
2155
  */
1813
2156
  export declare function usePlatform(): Platform;
1814
2157
 
2158
+ /**
2159
+ * The scale of the {@link Timeline} around a layer or a part: units to
2160
+ * pixels and back, snapping, and the range in view.
2161
+ *
2162
+ * @example
2163
+ * ```tsx
2164
+ * function Markers({ at }: { at: readonly number[] }) {
2165
+ * const scale = useTimelineScale();
2166
+ * // Draw each marker at scale.toPixels(unit); hit-test with scale.unitAt(event.clientX).
2167
+ * }
2168
+ * ```
2169
+ *
2170
+ * @public
2171
+ */
2172
+ export declare function useTimelineScale(): TimelineScale;
2173
+
1815
2174
  /**
1816
2175
  * The messages from the closest {@link UiMessagesProvider}, or English.
1817
2176
  *