@hussmartinez/ui 0.11.0 → 0.13.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
@@ -915,7 +915,9 @@ export declare function RemoveIcon(props: IconProps): ReactElement;
915
915
  * grid with one column of rows.
916
916
  *
917
917
  * - **↑ and ↓** move between rows and select; with Ctrl or ⌘, they move
918
- * without selecting. **← and →**, Home and End move between a row's
918
+ * without selecting. The selection follows focus however it reaches an
919
+ * item: the keys, Tab, a click, or your own `focus()`. Focus on a control
920
+ * never changes it. **← and →**, Home and End move between a row's
919
921
  * cells. Ctrl or ⌘ with Home or End goes to the first or last row.
920
922
  * Space or Enter on an item selects it.
921
923
  * - **Alt+↑ and Alt+↓** (Option on macOS) move the focused item, through
@@ -1147,6 +1149,11 @@ export declare function SkipForwardIcon(props: IconProps): ReactElement;
1147
1149
  * left and right arrows follow it, in every browser. `formatValue` gives
1148
1150
  * screen readers the value as text.
1149
1151
  *
1152
+ * `onValueChange` follows the value as it moves; `onValueCommit` is called
1153
+ * once when the gesture ends, for what should happen once, such as an undo
1154
+ * step: a drag let go, a key let go after one press or a held repeat, or
1155
+ * focus leaving first.
1156
+ *
1150
1157
  * Inside a `Toolbar`, the slider keeps the arrow keys, Home and End, so
1151
1158
  * they can't move focus past it: put it last in the toolbar. Tab still
1152
1159
  * leaves the toolbar.
@@ -1182,6 +1189,15 @@ export declare interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputE
1182
1189
  readonly defaultValue?: number | undefined;
1183
1190
  /** Called with the new value as it changes, by pointer or keyboard. */
1184
1191
  readonly onValueChange?: ((value: number) => void) | undefined;
1192
+ /**
1193
+ * Called once when a gesture that changed the value ends, with the value
1194
+ * it ended on: when the pointer is let go, when the last key held is let
1195
+ * go, or when the slider loses focus first. Use it for what should happen
1196
+ * once per gesture, such as an undo step, and `onValueChange` for what
1197
+ * follows the value as it moves. A gesture that leaves the value where it
1198
+ * was calls nothing.
1199
+ */
1200
+ readonly onValueCommit?: ((value: number) => void) | undefined;
1185
1201
  /** Defaults to 0. */
1186
1202
  readonly min?: number | undefined;
1187
1203
  /** Defaults to 100. */
@@ -1498,10 +1514,17 @@ export declare interface TimelineClip {
1498
1514
  readonly key: string;
1499
1515
  /** The clip's length, in the timeline's units: a whole number, at least 1. */
1500
1516
  readonly length: number;
1517
+ /**
1518
+ * The unit the clip starts on, for a track with room between its clips.
1519
+ * Give it to every clip of the track, in time order and without overlap,
1520
+ * or to none: without it, each clip starts where the one before ends.
1521
+ */
1522
+ readonly at?: number | undefined;
1501
1523
  /**
1502
1524
  * The clip's accessible name, with its place and range, such as
1503
1525
  * "Clip 2 of 5, 0:04.00 to 0:09.20, muted". Use text from your message
1504
- * catalogue.
1526
+ * catalogue. When `content` shows text, start the name with that text, so
1527
+ * what's seen is in what's heard (WCAG 2.5.3).
1505
1528
  */
1506
1529
  readonly label: string;
1507
1530
  /** What the clip shows, such as its name or a thumbnail. It's cut off where the clip ends. */
@@ -1510,6 +1533,18 @@ export declare interface TimelineClip {
1510
1533
  readonly attributes?: Readonly<Record<`data-${string}`, string | undefined>> | undefined;
1511
1534
  }
1512
1535
 
1536
+ /**
1537
+ * Where a dragged clip was dropped.
1538
+ *
1539
+ * @public
1540
+ */
1541
+ export declare interface TimelineClipDrop {
1542
+ /** How far along time, in units: negative for earlier. */
1543
+ readonly by: number;
1544
+ /** The `id` of the lane it's over, when that isn't the lane it came from. */
1545
+ readonly lane?: string | undefined;
1546
+ }
1547
+
1513
1548
  /**
1514
1549
  * A clip's edge: its start, or its end.
1515
1550
  *
@@ -1523,7 +1558,10 @@ export declare type TimelineClipEdge = "start" | "end";
1523
1558
  * (docs/adr/0011).
1524
1559
  *
1525
1560
  * - **← and →** move between clips, and Home and End go to the first and
1526
- * last. They follow the reading direction. The selection follows focus.
1561
+ * last. They follow the reading direction. With `selectionMode="single"`,
1562
+ * the selection follows focus however it arrives: arrows, Tab, a click, or
1563
+ * your own `focus()` or `focusClip`. Ctrl or ⌘ with an arrow moves focus
1564
+ * without selecting.
1527
1565
  * - **With `selectionMode="multiple"`,** Shift extends the selection from
1528
1566
  * the last clip chosen; Ctrl or ⌘ moves focus without changing it; Space
1529
1567
  * adds or removes the focused clip, and Shift+Space selects up to it;
@@ -1625,6 +1663,116 @@ export declare interface TimelineClipsProps extends StyleProps<TimelineClipsPart
1625
1663
  readonly min?: number;
1626
1664
  readonly max?: number;
1627
1665
  }) | undefined;
1666
+ /**
1667
+ * Called when the user moves clips to the lane above (`-1`) or below
1668
+ * (`1`) with Alt+↑ or Alt+↓ (Option on macOS), with the same keys as
1669
+ * `onMove`. Render them on that lane, at the same time, or leave them when
1670
+ * they can't go there. In a lane, the keys are taken with or without it,
1671
+ * so the page never scrolls instead.
1672
+ */
1673
+ readonly onMoveLane?: ((keys: readonly string[], direction: -1 | 1) => void) | undefined;
1674
+ /**
1675
+ * Called once, when the user lets go of a clip dragged along time or to
1676
+ * another lane, with the keys that moved and where: `by` units, and the
1677
+ * `lane` it's over when that's another one. Render the clips there. With
1678
+ * it, a clip can be dragged, with a mouse or a pen; on a touch screen a
1679
+ * drag scrolls, and clips move with your buttons.
1680
+ */
1681
+ readonly onDrop?: ((keys: readonly string[], drop: TimelineClipDrop) => void) | undefined;
1682
+ /**
1683
+ * Asked as a clip is dragged: whether it may be dropped there. Where it
1684
+ * may not, the clip shows it and letting go reports nothing: a place where
1685
+ * it would overlap another clip, or a lane that doesn't take it.
1686
+ */
1687
+ readonly canDrop?: ((keys: readonly string[], drop: TimelineClipDrop) => boolean) | undefined;
1688
+ /**
1689
+ * What a drag takes hold of: the whole `clip`, the default, or only its
1690
+ * `title`, the strip that shows its `content`. With `title`, a press on
1691
+ * the rest of the clip passes to the layer under it, for an editor where
1692
+ * dragging across a track selects a range of time.
1693
+ */
1694
+ readonly moveHandle?: "clip" | "title" | undefined;
1695
+ }
1696
+
1697
+ /**
1698
+ * A lane of a {@link Timeline}: a track of an editor, with its own layers
1699
+ * and clip track, and a header that stays in view (docs/adr/0011). Lanes
1700
+ * stack downward in the order written, under one playhead.
1701
+ *
1702
+ * - **It's a group,** named by `label`, holding its header and its clips.
1703
+ * - **The header is a toolbar:** one Tab stop a lane, before its clips. The
1704
+ * headers share a column as wide as the widest. Where the timeline is
1705
+ * narrower than 720 pixels, each sits above its lane instead.
1706
+ * - **↑ and ↓ on a clip** go to the clip nearest in time on the next lane
1707
+ * that has clips, so nobody tabs through every lane.
1708
+ * - **You own the lanes' order:** move one by rendering it elsewhere.
1709
+ *
1710
+ * A timeline without lanes is one lane with no header, and needs none.
1711
+ *
1712
+ * @example
1713
+ * ```tsx
1714
+ * <Timeline label={t("timeline.label")} length={frames}>
1715
+ * <TimelinePlayhead … />
1716
+ * {tracks.map((track) => (
1717
+ * <TimelineLane
1718
+ * key={track.key}
1719
+ * id={track.key}
1720
+ * label={t("track.label", track)}
1721
+ * header={<TrackControls track={track} />}
1722
+ * >
1723
+ * <TimelineLayer><Waveform track={track} /></TimelineLayer>
1724
+ * <TimelineClips label={t("track.clips", track)} clips={…} … />
1725
+ * </TimelineLane>
1726
+ * ))}
1727
+ * </Timeline>
1728
+ * ```
1729
+ *
1730
+ * @public
1731
+ */
1732
+ export declare const TimelineLane: ForwardRefExoticComponent<TimelineLaneProps & RefAttributes<HTMLDivElement>>;
1733
+
1734
+ /**
1735
+ * The parts of a timeline's lane that `classNames` can target.
1736
+ *
1737
+ * @public
1738
+ */
1739
+ export declare type TimelineLanePart = "root" | "header";
1740
+
1741
+ /**
1742
+ * Props of {@link TimelineLane}.
1743
+ *
1744
+ * @public
1745
+ */
1746
+ export declare interface TimelineLaneProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role" | "id">, StyleProps<TimelineLanePart> {
1747
+ /** Identifies the lane: in `useTimelineLanes`, and when a clip moves between lanes. Unique in the timeline. */
1748
+ readonly id: string;
1749
+ /**
1750
+ * The lane's accessible name, with what a user needs to tell it from the
1751
+ * others, such as "Track 2, Music, muted". It names the lane's header too.
1752
+ */
1753
+ readonly label: string;
1754
+ /**
1755
+ * The lane's controls, such as its name, Mute and Solo toggles and a gain
1756
+ * slider, last. The lane renders them in a toolbar that stays in view
1757
+ * while the timeline scrolls: one Tab stop, with ← and → between them.
1758
+ */
1759
+ readonly header?: ReactNode;
1760
+ /** The lane's own layers and its clip track, stacked in the order written. */
1761
+ readonly children?: ReactNode;
1762
+ }
1763
+
1764
+ /**
1765
+ * The lanes of the {@link Timeline} around a layer, for one that covers them
1766
+ * all, such as a selected range of time: their ids in the order shown, and
1767
+ * the lane under a pointer.
1768
+ *
1769
+ * @public
1770
+ */
1771
+ export declare interface TimelineLanes {
1772
+ /** The lanes' ids, top to bottom. Empty in a timeline without lanes. */
1773
+ readonly lanes: readonly string[];
1774
+ /** The id of the lane under a pointer, from its `clientY`, if one is. */
1775
+ readonly laneAt: (clientY: number) => string | undefined;
1628
1776
  }
1629
1777
 
1630
1778
  /**
@@ -1726,6 +1874,13 @@ export declare interface TimelineProps extends Omit<HTMLAttributes<HTMLElement>,
1726
1874
  readonly label: string;
1727
1875
  /** The length of what's on the timeline, in whole units, such as frames or samples. */
1728
1876
  readonly length: number;
1877
+ /**
1878
+ * How far to draw the track, in units, when clips run past `length`, such
1879
+ * as audio that outlasts its video. The playhead still ends at `length`,
1880
+ * and a clip that passes it is marked `data-hm-past-end`. Defaults to
1881
+ * `length`, and is never less.
1882
+ */
1883
+ readonly extent?: number | undefined;
1729
1884
  /**
1730
1885
  * The zoom, as a multiple of fitting `length` to the timeline's width.
1731
1886
  * Defaults to 1, which fits; less than 1 fits too.
@@ -1774,8 +1929,13 @@ export declare interface TimelineRange {
1774
1929
  * @public
1775
1930
  */
1776
1931
  export declare interface TimelineScale {
1777
- /** The timeline's length, in units. */
1932
+ /** The timeline's length, in units: as far as the playhead goes. */
1778
1933
  readonly length: number;
1934
+ /**
1935
+ * How far the track is drawn, in units: `length`, or more when clips run
1936
+ * past it.
1937
+ */
1938
+ readonly extent: number;
1779
1939
  /**
1780
1940
  * CSS pixels for one unit at the current zoom. It's 0 until the timeline
1781
1941
  * has measured itself, which is after the first render in a browser, and
@@ -1785,7 +1945,7 @@ export declare interface TimelineScale {
1785
1945
  /** A unit's distance from the start of the track, in CSS pixels. */
1786
1946
  readonly toPixels: (unit: number) => number;
1787
1947
  /**
1788
- * The unit under a pointer, from its `clientX`, within `0…length`. It
1948
+ * The unit under a pointer, from its `clientX`, within `0…extent`. It
1789
1949
  * follows the reading direction. With `snap`, it snaps to the timeline's
1790
1950
  * targets when `snapping` is on.
1791
1951
  */
@@ -2155,6 +2315,13 @@ export declare function useAnnounce(): Announce;
2155
2315
  */
2156
2316
  export declare function usePlatform(): Platform;
2157
2317
 
2318
+ /**
2319
+ * The lanes of the {@link Timeline} around a layer or a part.
2320
+ *
2321
+ * @public
2322
+ */
2323
+ export declare function useTimelineLanes(): TimelineLanes;
2324
+
2158
2325
  /**
2159
2326
  * The scale of the {@link Timeline} around a layer or a part: units to
2160
2327
  * pixels and back, snapping, and the range in view.