@hussmartinez/ui 0.11.0 → 0.12.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/styles.css CHANGED
@@ -1697,9 +1697,15 @@
1697
1697
  * a server, they share the track equally; then TimelineClips.tsx sets each
1698
1698
  * one's inline size.
1699
1699
  */
1700
+ /*
1701
+ * Only the clips take the pointer: between them, and beside a clip's
1702
+ * title when that's its handle, a press reaches what's under the track,
1703
+ * such as a layer that selects a range of time.
1704
+ */
1700
1705
  .hm-timeline-clips {
1701
1706
  box-sizing: border-box;
1702
1707
  display: flex;
1708
+ pointer-events: none;
1703
1709
  }
1704
1710
 
1705
1711
  .hm-timeline-clip {
@@ -1710,6 +1716,7 @@
1710
1716
  flex: 1 1 0;
1711
1717
  min-inline-size: 0;
1712
1718
  overflow: hidden;
1719
+ pointer-events: auto;
1713
1720
  position: relative;
1714
1721
  user-select: none;
1715
1722
  }
@@ -1752,6 +1759,37 @@
1752
1759
  white-space: nowrap;
1753
1760
  }
1754
1761
 
1762
+ /*
1763
+ * Clips that can be dragged. A dragged clip is above the lanes and the
1764
+ * playhead as it follows the pointer; TimelineClips.tsx moves it.
1765
+ */
1766
+ .hm-timeline-clips[data-hm-move-handle="clip"] > .hm-timeline-clip,
1767
+ .hm-timeline-clips[data-hm-move-handle="title"] .hm-timeline-clip-content {
1768
+ cursor: grab;
1769
+ }
1770
+
1771
+ /*
1772
+ * With the title as the handle, the rest of a clip lets a press through
1773
+ * to the layer under it, such as one that selects a range of time.
1774
+ */
1775
+ .hm-timeline-clips[data-hm-move-handle="title"] > .hm-timeline-clip {
1776
+ pointer-events: none;
1777
+ }
1778
+
1779
+ .hm-timeline-clips[data-hm-move-handle="title"] .hm-timeline-clip-content,
1780
+ .hm-timeline-clips[data-hm-move-handle="title"] .hm-timeline-clip-edge {
1781
+ pointer-events: auto;
1782
+ }
1783
+
1784
+ .hm-timeline-clips > .hm-timeline-clip[data-hm-moving] {
1785
+ cursor: grabbing;
1786
+ z-index: var(--hm-z-sticky);
1787
+ }
1788
+
1789
+ .hm-timeline-clips > .hm-timeline-clip[data-hm-moving="refused"] {
1790
+ cursor: not-allowed;
1791
+ }
1792
+
1755
1793
  /* Over both rows, and above the layers; only its slider takes the pointer. */
1756
1794
  .hm-timeline-playhead {
1757
1795
  grid-row: 1 / 3;
@@ -1773,6 +1811,106 @@
1773
1811
  position: absolute;
1774
1812
  }
1775
1813
 
1814
+ /*
1815
+ * Lanes. Each is a row of the track, under the slider's, with its own
1816
+ * layers and clips stacked in it; Timeline.tsx gives each its row. Their
1817
+ * headers share a column before the first unit, in room the timeline adds
1818
+ * to the viewport's padding, and stay there as the track scrolls.
1819
+ */
1820
+ .hm-timeline[data-hm-lanes] .hm-timeline-viewport {
1821
+ overflow: auto;
1822
+ }
1823
+
1824
+ .hm-timeline[data-hm-lanes] .hm-timeline-track {
1825
+ grid-auto-rows: minmax(var(--hm-timeline-lane-height, var(--hm-control-height)), auto);
1826
+ grid-template-rows: max(
1827
+ var(--hm-slider-thumb-size, var(--hm-icon-size)),
1828
+ var(--hm-target-size)
1829
+ );
1830
+ }
1831
+
1832
+ /*
1833
+ * Two columns: the header's, as wide as the header and nothing without
1834
+ * one, then the lane's layers and clips, stacked. TimelineLane.tsx pulls
1835
+ * the lane back over the room kept for the headers, so the header has a
1836
+ * box to stay in.
1837
+ */
1838
+ .hm-timeline-lane {
1839
+ box-sizing: border-box;
1840
+ display: grid;
1841
+ grid-template-columns: auto minmax(0, 1fr);
1842
+ }
1843
+
1844
+ .hm-timeline-lane > * {
1845
+ grid-column: 2;
1846
+ grid-row: 1;
1847
+ min-inline-size: 0;
1848
+ }
1849
+
1850
+ .hm-timeline-lane > .hm-timeline-lane-header {
1851
+ align-items: center;
1852
+ box-sizing: border-box;
1853
+ display: flex;
1854
+ grid-column: 1;
1855
+ inset-inline-start: 0;
1856
+ overflow: hidden;
1857
+ position: sticky;
1858
+ z-index: var(--hm-z-sticky);
1859
+ }
1860
+
1861
+ /* As wide as its controls, so the timeline can tell how wide the column must be. */
1862
+ .hm-timeline-lane-toolbar {
1863
+ flex: none;
1864
+ inline-size: max-content;
1865
+ max-inline-size: var(--hm-timeline-header-max-width, var(--hm-surface-width-small));
1866
+ }
1867
+
1868
+ /* The slider's row stays at the top as the lanes scroll under it. */
1869
+ .hm-timeline-bar {
1870
+ grid-column: 1;
1871
+ grid-row: 1;
1872
+ inset-block-start: 0;
1873
+ position: sticky;
1874
+ z-index: var(--hm-z-raised);
1875
+ }
1876
+
1877
+ .hm-timeline[data-hm-lanes] .hm-timeline-playhead-slider {
1878
+ inset-block-start: 0;
1879
+ position: sticky;
1880
+ }
1881
+
1882
+ /* Only its cover takes the pointer: the rest of the row is the slider's. */
1883
+ .hm-timeline-corner {
1884
+ grid-column: 1;
1885
+ grid-row: 1;
1886
+ inset-block-start: 0;
1887
+ pointer-events: none;
1888
+ position: sticky;
1889
+ z-index: var(--hm-z-sticky);
1890
+ }
1891
+
1892
+ .hm-timeline-corner-cover {
1893
+ block-size: 100%;
1894
+ inset-inline-start: 0;
1895
+ pointer-events: auto;
1896
+ position: sticky;
1897
+ }
1898
+
1899
+ /* Where the timeline is narrow, each header sits above its lane. */
1900
+ .hm-timeline[data-hm-lanes="above"] .hm-timeline-lane {
1901
+ grid-template-rows: auto minmax(var(--hm-timeline-lane-height, var(--hm-control-height)), auto);
1902
+ }
1903
+
1904
+ .hm-timeline[data-hm-lanes="above"] .hm-timeline-lane > * {
1905
+ grid-row: 2;
1906
+ }
1907
+
1908
+ .hm-timeline[data-hm-lanes="above"] .hm-timeline-lane > .hm-timeline-lane-header {
1909
+ grid-column: 1 / -1;
1910
+ grid-row: 1;
1911
+ justify-self: start;
1912
+ }
1913
+
1776
1914
  /* Visual styles, dropped with unstyled. */
1777
1915
  /* On the viewport, so it's behind the slider's ends too, and stays put while the track scrolls. */
1778
1916
  .hm-timeline:not([data-hm-unstyled]) .hm-timeline-viewport {
@@ -1819,4 +1957,27 @@
1819
1957
  .hm-timeline-clips:not([data-hm-unstyled]) > .hm-timeline-clip[data-hm-dragging] {
1820
1958
  border-color: var(--hm-timeline-clip-selected-border-color, var(--hm-color-accent));
1821
1959
  }
1960
+
1961
+ /* Opaque, so clips and the slider's rail pass under them. */
1962
+ .hm-timeline:not([data-hm-unstyled]) .hm-timeline-lane > .hm-timeline-lane-header,
1963
+ .hm-timeline:not([data-hm-unstyled]) .hm-timeline-corner-cover,
1964
+ .hm-timeline:not([data-hm-unstyled]) .hm-timeline-bar {
1965
+ background: var(--hm-timeline-header-bg, var(--hm-color-surface));
1966
+ }
1967
+
1968
+ .hm-timeline:not([data-hm-unstyled]) .hm-timeline-lane {
1969
+ border-block-start: var(--hm-border-width) solid
1970
+ var(--hm-timeline-lane-border-color, var(--hm-color-border));
1971
+ }
1972
+
1973
+ /* A clip being dragged, and one that can't be dropped where it is. */
1974
+ .hm-timeline-clips:not([data-hm-unstyled]) > .hm-timeline-clip[data-hm-moving] {
1975
+ border-color: var(--hm-timeline-clip-selected-border-color, var(--hm-color-accent));
1976
+ box-shadow: var(--hm-timeline-clip-moving-shadow, var(--hm-shadow-raised));
1977
+ }
1978
+
1979
+ .hm-timeline-clips:not([data-hm-unstyled]) > .hm-timeline-clip[data-hm-moving="refused"] {
1980
+ border-color: var(--hm-timeline-clip-refused-border-color, var(--hm-color-danger-text));
1981
+ border-style: dashed;
1982
+ }
1822
1983
  }
package/dist/ui.d.ts CHANGED
@@ -1498,10 +1498,17 @@ export declare interface TimelineClip {
1498
1498
  readonly key: string;
1499
1499
  /** The clip's length, in the timeline's units: a whole number, at least 1. */
1500
1500
  readonly length: number;
1501
+ /**
1502
+ * The unit the clip starts on, for a track with room between its clips.
1503
+ * Give it to every clip of the track, in time order and without overlap,
1504
+ * or to none: without it, each clip starts where the one before ends.
1505
+ */
1506
+ readonly at?: number | undefined;
1501
1507
  /**
1502
1508
  * The clip's accessible name, with its place and range, such as
1503
1509
  * "Clip 2 of 5, 0:04.00 to 0:09.20, muted". Use text from your message
1504
- * catalogue.
1510
+ * catalogue. When `content` shows text, start the name with that text, so
1511
+ * what's seen is in what's heard (WCAG 2.5.3).
1505
1512
  */
1506
1513
  readonly label: string;
1507
1514
  /** What the clip shows, such as its name or a thumbnail. It's cut off where the clip ends. */
@@ -1510,6 +1517,18 @@ export declare interface TimelineClip {
1510
1517
  readonly attributes?: Readonly<Record<`data-${string}`, string | undefined>> | undefined;
1511
1518
  }
1512
1519
 
1520
+ /**
1521
+ * Where a dragged clip was dropped.
1522
+ *
1523
+ * @public
1524
+ */
1525
+ export declare interface TimelineClipDrop {
1526
+ /** How far along time, in units: negative for earlier. */
1527
+ readonly by: number;
1528
+ /** The `id` of the lane it's over, when that isn't the lane it came from. */
1529
+ readonly lane?: string | undefined;
1530
+ }
1531
+
1513
1532
  /**
1514
1533
  * A clip's edge: its start, or its end.
1515
1534
  *
@@ -1625,6 +1644,116 @@ export declare interface TimelineClipsProps extends StyleProps<TimelineClipsPart
1625
1644
  readonly min?: number;
1626
1645
  readonly max?: number;
1627
1646
  }) | undefined;
1647
+ /**
1648
+ * Called when the user moves clips to the lane above (`-1`) or below
1649
+ * (`1`) with Alt+↑ or Alt+↓ (Option on macOS), with the same keys as
1650
+ * `onMove`. Render them on that lane, at the same time, or leave them when
1651
+ * they can't go there. In a lane, the keys are taken with or without it,
1652
+ * so the page never scrolls instead.
1653
+ */
1654
+ readonly onMoveLane?: ((keys: readonly string[], direction: -1 | 1) => void) | undefined;
1655
+ /**
1656
+ * Called once, when the user lets go of a clip dragged along time or to
1657
+ * another lane, with the keys that moved and where: `by` units, and the
1658
+ * `lane` it's over when that's another one. Render the clips there. With
1659
+ * it, a clip can be dragged, with a mouse or a pen; on a touch screen a
1660
+ * drag scrolls, and clips move with your buttons.
1661
+ */
1662
+ readonly onDrop?: ((keys: readonly string[], drop: TimelineClipDrop) => void) | undefined;
1663
+ /**
1664
+ * Asked as a clip is dragged: whether it may be dropped there. Where it
1665
+ * may not, the clip shows it and letting go reports nothing: a place where
1666
+ * it would overlap another clip, or a lane that doesn't take it.
1667
+ */
1668
+ readonly canDrop?: ((keys: readonly string[], drop: TimelineClipDrop) => boolean) | undefined;
1669
+ /**
1670
+ * What a drag takes hold of: the whole `clip`, the default, or only its
1671
+ * `title`, the strip that shows its `content`. With `title`, a press on
1672
+ * the rest of the clip passes to the layer under it, for an editor where
1673
+ * dragging across a track selects a range of time.
1674
+ */
1675
+ readonly moveHandle?: "clip" | "title" | undefined;
1676
+ }
1677
+
1678
+ /**
1679
+ * A lane of a {@link Timeline}: a track of an editor, with its own layers
1680
+ * and clip track, and a header that stays in view (docs/adr/0011). Lanes
1681
+ * stack downward in the order written, under one playhead.
1682
+ *
1683
+ * - **It's a group,** named by `label`, holding its header and its clips.
1684
+ * - **The header is a toolbar:** one Tab stop a lane, before its clips. The
1685
+ * headers share a column as wide as the widest. Where the timeline is
1686
+ * narrower than 720 pixels, each sits above its lane instead.
1687
+ * - **↑ and ↓ on a clip** go to the clip nearest in time on the next lane
1688
+ * that has clips, so nobody tabs through every lane.
1689
+ * - **You own the lanes' order:** move one by rendering it elsewhere.
1690
+ *
1691
+ * A timeline without lanes is one lane with no header, and needs none.
1692
+ *
1693
+ * @example
1694
+ * ```tsx
1695
+ * <Timeline label={t("timeline.label")} length={frames}>
1696
+ * <TimelinePlayhead … />
1697
+ * {tracks.map((track) => (
1698
+ * <TimelineLane
1699
+ * key={track.key}
1700
+ * id={track.key}
1701
+ * label={t("track.label", track)}
1702
+ * header={<TrackControls track={track} />}
1703
+ * >
1704
+ * <TimelineLayer><Waveform track={track} /></TimelineLayer>
1705
+ * <TimelineClips label={t("track.clips", track)} clips={…} … />
1706
+ * </TimelineLane>
1707
+ * ))}
1708
+ * </Timeline>
1709
+ * ```
1710
+ *
1711
+ * @public
1712
+ */
1713
+ export declare const TimelineLane: ForwardRefExoticComponent<TimelineLaneProps & RefAttributes<HTMLDivElement>>;
1714
+
1715
+ /**
1716
+ * The parts of a timeline's lane that `classNames` can target.
1717
+ *
1718
+ * @public
1719
+ */
1720
+ export declare type TimelineLanePart = "root" | "header";
1721
+
1722
+ /**
1723
+ * Props of {@link TimelineLane}.
1724
+ *
1725
+ * @public
1726
+ */
1727
+ export declare interface TimelineLaneProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role" | "id">, StyleProps<TimelineLanePart> {
1728
+ /** Identifies the lane: in `useTimelineLanes`, and when a clip moves between lanes. Unique in the timeline. */
1729
+ readonly id: string;
1730
+ /**
1731
+ * The lane's accessible name, with what a user needs to tell it from the
1732
+ * others, such as "Track 2, Music, muted". It names the lane's header too.
1733
+ */
1734
+ readonly label: string;
1735
+ /**
1736
+ * The lane's controls, such as its name, Mute and Solo toggles and a gain
1737
+ * slider, last. The lane renders them in a toolbar that stays in view
1738
+ * while the timeline scrolls: one Tab stop, with ← and → between them.
1739
+ */
1740
+ readonly header?: ReactNode;
1741
+ /** The lane's own layers and its clip track, stacked in the order written. */
1742
+ readonly children?: ReactNode;
1743
+ }
1744
+
1745
+ /**
1746
+ * The lanes of the {@link Timeline} around a layer, for one that covers them
1747
+ * all, such as a selected range of time: their ids in the order shown, and
1748
+ * the lane under a pointer.
1749
+ *
1750
+ * @public
1751
+ */
1752
+ export declare interface TimelineLanes {
1753
+ /** The lanes' ids, top to bottom. Empty in a timeline without lanes. */
1754
+ readonly lanes: readonly string[];
1755
+ /** The id of the lane under a pointer, from its `clientY`, if one is. */
1756
+ readonly laneAt: (clientY: number) => string | undefined;
1628
1757
  }
1629
1758
 
1630
1759
  /**
@@ -1726,6 +1855,13 @@ export declare interface TimelineProps extends Omit<HTMLAttributes<HTMLElement>,
1726
1855
  readonly label: string;
1727
1856
  /** The length of what's on the timeline, in whole units, such as frames or samples. */
1728
1857
  readonly length: number;
1858
+ /**
1859
+ * How far to draw the track, in units, when clips run past `length`, such
1860
+ * as audio that outlasts its video. The playhead still ends at `length`,
1861
+ * and a clip that passes it is marked `data-hm-past-end`. Defaults to
1862
+ * `length`, and is never less.
1863
+ */
1864
+ readonly extent?: number | undefined;
1729
1865
  /**
1730
1866
  * The zoom, as a multiple of fitting `length` to the timeline's width.
1731
1867
  * Defaults to 1, which fits; less than 1 fits too.
@@ -1774,8 +1910,13 @@ export declare interface TimelineRange {
1774
1910
  * @public
1775
1911
  */
1776
1912
  export declare interface TimelineScale {
1777
- /** The timeline's length, in units. */
1913
+ /** The timeline's length, in units: as far as the playhead goes. */
1778
1914
  readonly length: number;
1915
+ /**
1916
+ * How far the track is drawn, in units: `length`, or more when clips run
1917
+ * past it.
1918
+ */
1919
+ readonly extent: number;
1779
1920
  /**
1780
1921
  * CSS pixels for one unit at the current zoom. It's 0 until the timeline
1781
1922
  * has measured itself, which is after the first render in a browser, and
@@ -1785,7 +1926,7 @@ export declare interface TimelineScale {
1785
1926
  /** A unit's distance from the start of the track, in CSS pixels. */
1786
1927
  readonly toPixels: (unit: number) => number;
1787
1928
  /**
1788
- * The unit under a pointer, from its `clientX`, within `0…length`. It
1929
+ * The unit under a pointer, from its `clientX`, within `0…extent`. It
1789
1930
  * follows the reading direction. With `snap`, it snaps to the timeline's
1790
1931
  * targets when `snapping` is on.
1791
1932
  */
@@ -2155,6 +2296,13 @@ export declare function useAnnounce(): Announce;
2155
2296
  */
2156
2297
  export declare function usePlatform(): Platform;
2157
2298
 
2299
+ /**
2300
+ * The lanes of the {@link Timeline} around a layer or a part.
2301
+ *
2302
+ * @public
2303
+ */
2304
+ export declare function useTimelineLanes(): TimelineLanes;
2305
+
2158
2306
  /**
2159
2307
  * The scale of the {@link Timeline} around a layer or a part: units to
2160
2308
  * pixels and back, snapping, and the range in view.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hussmartinez/ui",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "Design system of the @hussmartinez SDK family: tokens, themes, base styles and accessible React components.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {