@hussmartinez/ui 0.9.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/README.md +12 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +21 -1
- package/dist/index.js.map +1 -1
- package/dist/react.d.ts +493 -1
- package/dist/react.js +849 -68
- package/dist/react.js.map +1 -1
- package/dist/shared/{pair-pt-vUVwu.js → pair-MeX064R6.js} +2 -1
- package/dist/shared/pair-MeX064R6.js.map +1 -0
- package/dist/styles.css +262 -0
- package/dist/ui.d.ts +493 -1
- package/package.json +1 -1
- package/dist/shared/pair-pt-vUVwu.js.map +0 -1
package/dist/ui.d.ts
CHANGED
|
@@ -626,7 +626,7 @@ export declare type IconComponent = (props: IconProps) => ReactElement;
|
|
|
626
626
|
*
|
|
627
627
|
* @public
|
|
628
628
|
*/
|
|
629
|
-
export declare type IconName = "add" | "arrow" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "crop" | "delete" | "download" | "duplicate" | "ellipse" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "hidden" | "highlighter" | "info" | "layers" | "loop" | "menu" | "more" | "move-down" | "move-up" | "muted" | "open" | "page-add" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "rectangle" | "redact" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "snap" | "split" | "stop" | "text" | "trim-end" | "trim-start" | "undo" | "upload" | "visible" | "volume" | "warning" | "zoom-in" | "zoom-out";
|
|
629
|
+
export declare type IconName = "add" | "arrow" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "crop" | "delete" | "download" | "duplicate" | "ellipse" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "hidden" | "highlighter" | "image" | "info" | "layers" | "loop" | "menu" | "more" | "move-down" | "move-up" | "muted" | "open" | "page-add" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "rectangle" | "redact" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "snap" | "split" | "stop" | "text" | "trim-end" | "trim-start" | "undo" | "upload" | "visible" | "volume" | "warning" | "zoom-in" | "zoom-out";
|
|
630
630
|
|
|
631
631
|
/**
|
|
632
632
|
* Props of every icon. SVG attributes are passed through.
|
|
@@ -642,6 +642,13 @@ export declare interface IconProps extends Omit<SVGProps<SVGSVGElement>, "childr
|
|
|
642
642
|
readonly label?: string | undefined;
|
|
643
643
|
}
|
|
644
644
|
|
|
645
|
+
/**
|
|
646
|
+
* The `image` icon: Lucide's `image`.
|
|
647
|
+
*
|
|
648
|
+
* @public
|
|
649
|
+
*/
|
|
650
|
+
export declare function ImageIcon(props: IconProps): ReactElement;
|
|
651
|
+
|
|
645
652
|
/**
|
|
646
653
|
* The `info` icon: Lucide's `info`.
|
|
647
654
|
*
|
|
@@ -902,6 +909,131 @@ export declare function RedoIcon(props: IconProps): ReactElement;
|
|
|
902
909
|
*/
|
|
903
910
|
export declare function RemoveIcon(props: IconProps): ReactElement;
|
|
904
911
|
|
|
912
|
+
/**
|
|
913
|
+
* A list whose items the user selects, reorders and removes, with one Tab
|
|
914
|
+
* stop and room for controls in each row (docs/adr/0009). It's a WAI-ARIA
|
|
915
|
+
* grid with one column of rows.
|
|
916
|
+
*
|
|
917
|
+
* - **↑ and ↓** move between rows and select; with Ctrl or ⌘, they move
|
|
918
|
+
* without selecting. **← and →**, Home and End move between a row's
|
|
919
|
+
* cells. Ctrl or ⌘ with Home or End goes to the first or last row.
|
|
920
|
+
* Space or Enter on an item selects it.
|
|
921
|
+
* - **Alt+↑ and Alt+↓** (Option on macOS) move the focused item, through
|
|
922
|
+
* `onMove`. **Delete and Backspace** remove it, through `onRemove`.
|
|
923
|
+
* - **You own the order.** The list calls `onMove` and `onRemove`, and you
|
|
924
|
+
* render the result. Focus stays with a moved item, and goes to the next
|
|
925
|
+
* one after a removal.
|
|
926
|
+
* - **Offer buttons too.** The keys are an addition: also render buttons
|
|
927
|
+
* that move the selected item, for touch and for people who don't know
|
|
928
|
+
* the keys, and name the keys on them with `aria-keyshortcuts`.
|
|
929
|
+
*
|
|
930
|
+
* @example
|
|
931
|
+
* ```tsx
|
|
932
|
+
* <ReorderableList
|
|
933
|
+
* label={t("layers.label")}
|
|
934
|
+
* selectedId={selected}
|
|
935
|
+
* onSelectedChange={setSelected}
|
|
936
|
+
* onMove={(id, toIndex) => session.moveLayer(id, toIndex)}
|
|
937
|
+
* onRemove={(id) => session.deleteLayer(id)}
|
|
938
|
+
* >
|
|
939
|
+
* {layers.map((layer) => (
|
|
940
|
+
* <ReorderableListItem
|
|
941
|
+
* key={layer.id}
|
|
942
|
+
* id={layer.id}
|
|
943
|
+
* label={layer.name}
|
|
944
|
+
* controls={[
|
|
945
|
+
* <ToggleButton
|
|
946
|
+
* key="visible"
|
|
947
|
+
* variant="quiet"
|
|
948
|
+
* label={t("layers.visible")}
|
|
949
|
+
* icon={<VisibleIcon />}
|
|
950
|
+
* pressed={layer.visible}
|
|
951
|
+
* onPressedChange={(visible) => session.showLayer(layer.id, visible)}
|
|
952
|
+
* />,
|
|
953
|
+
* ]}
|
|
954
|
+
* >
|
|
955
|
+
* {layer.name}
|
|
956
|
+
* </ReorderableListItem>
|
|
957
|
+
* ))}
|
|
958
|
+
* </ReorderableList>
|
|
959
|
+
* ```
|
|
960
|
+
*
|
|
961
|
+
* @public
|
|
962
|
+
*/
|
|
963
|
+
export declare const ReorderableList: ForwardRefExoticComponent<ReorderableListProps & RefAttributes<HTMLDivElement>>;
|
|
964
|
+
|
|
965
|
+
/**
|
|
966
|
+
* An item of a {@link ReorderableList}: a row with the item's content, and a
|
|
967
|
+
* cell for each of its `controls`.
|
|
968
|
+
*
|
|
969
|
+
* @public
|
|
970
|
+
*/
|
|
971
|
+
export declare const ReorderableListItem: ForwardRefExoticComponent<ReorderableListItemProps & RefAttributes<HTMLDivElement>>;
|
|
972
|
+
|
|
973
|
+
/**
|
|
974
|
+
* The parts of a reorderable list's item that `classNames` can target.
|
|
975
|
+
*
|
|
976
|
+
* @public
|
|
977
|
+
*/
|
|
978
|
+
export declare type ReorderableListItemPart = "root" | "item" | "control";
|
|
979
|
+
|
|
980
|
+
/**
|
|
981
|
+
* Props of {@link ReorderableListItem}.
|
|
982
|
+
*
|
|
983
|
+
* @public
|
|
984
|
+
*/
|
|
985
|
+
export declare interface ReorderableListItemProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role" | "id">, StyleProps<ReorderableListItemPart> {
|
|
986
|
+
/** Identifies the item in `selectedId`, `onMove` and `onRemove`. Unique in the list. */
|
|
987
|
+
readonly id: string;
|
|
988
|
+
/**
|
|
989
|
+
* The item's accessible name, such as a layer's name. Start it with the
|
|
990
|
+
* text the item shows, if it shows any.
|
|
991
|
+
*/
|
|
992
|
+
readonly label: string;
|
|
993
|
+
/**
|
|
994
|
+
* The item's controls, such as a visibility toggle: one focusable control
|
|
995
|
+
* each, in its own cell. A control that can't act should stay focusable,
|
|
996
|
+
* as `focusableWhenDisabled` makes a button.
|
|
997
|
+
*/
|
|
998
|
+
readonly controls?: readonly ReactNode[] | undefined;
|
|
999
|
+
/** What the item shows. */
|
|
1000
|
+
readonly children?: ReactNode;
|
|
1001
|
+
}
|
|
1002
|
+
|
|
1003
|
+
/**
|
|
1004
|
+
* Props of {@link ReorderableList}.
|
|
1005
|
+
*
|
|
1006
|
+
* @public
|
|
1007
|
+
*/
|
|
1008
|
+
export declare interface ReorderableListProps extends Omit<HTMLAttributes<HTMLDivElement>, "className" | "role">, StyleProps<"root"> {
|
|
1009
|
+
/** The list's accessible name, such as "Layers". Required. */
|
|
1010
|
+
readonly label: string;
|
|
1011
|
+
/** The selected item's `id`, or `null` for none. */
|
|
1012
|
+
readonly selectedId?: string | null | undefined;
|
|
1013
|
+
/** Called with an item's `id` when the user selects it. */
|
|
1014
|
+
readonly onSelectedChange?: ((id: string) => void) | undefined;
|
|
1015
|
+
/**
|
|
1016
|
+
* Called when the user moves an item with Alt+↑ or Alt+↓ (Option on
|
|
1017
|
+
* macOS), with its `id` and the position it should have, counted from 0.
|
|
1018
|
+
* Render the items in the new order, or leave them when the move isn't
|
|
1019
|
+
* allowed. Without it, the list doesn't reorder.
|
|
1020
|
+
*/
|
|
1021
|
+
readonly onMove?: ((id: string, toIndex: number) => void) | undefined;
|
|
1022
|
+
/**
|
|
1023
|
+
* Called when the user presses Delete or Backspace on an item, with its
|
|
1024
|
+
* `id`. Render the items without it. Without it, the keys do nothing.
|
|
1025
|
+
*/
|
|
1026
|
+
readonly onRemove?: ((id: string) => void) | undefined;
|
|
1027
|
+
/**
|
|
1028
|
+
* Whether the list announces a move to screen readers, through the
|
|
1029
|
+
* closest `AnnouncerProvider`. Defaults to `true`; pass `false` when you
|
|
1030
|
+
* announce it in your own words.
|
|
1031
|
+
*/
|
|
1032
|
+
readonly announceMoves?: boolean | undefined;
|
|
1033
|
+
/** The items: {@link ReorderableListItem} elements, in the order shown. */
|
|
1034
|
+
readonly children?: ReactNode;
|
|
1035
|
+
}
|
|
1036
|
+
|
|
905
1037
|
/**
|
|
906
1038
|
* The `rotate-left` icon: Lucide's `rotate-ccw`.
|
|
907
1039
|
*
|
|
@@ -1323,6 +1455,349 @@ export declare interface ThemeProviderSingleProps extends ThemeProviderBaseProps
|
|
|
1323
1455
|
readonly mode?: undefined;
|
|
1324
1456
|
}
|
|
1325
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
|
+
|
|
1326
1801
|
/**
|
|
1327
1802
|
* A button that turns something on or off, such as loop playback or the
|
|
1328
1803
|
* active tool, exposed as `aria-pressed`. Controlled with `pressed` and
|
|
@@ -1599,6 +2074,7 @@ export declare const uiMessages: {
|
|
|
1599
2074
|
readonly "fileDropZone.hint": "or drop it here";
|
|
1600
2075
|
readonly "fileDropZone.hintMultiple": "or drop them here";
|
|
1601
2076
|
readonly "progress.label": "Progress";
|
|
2077
|
+
readonly "reorderableList.moved": "{label} moved to position {position} of {count}";
|
|
1602
2078
|
readonly "spinner.label": "Loading";
|
|
1603
2079
|
readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
|
|
1604
2080
|
readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
|
|
@@ -1679,6 +2155,22 @@ export declare function useAnnounce(): Announce;
|
|
|
1679
2155
|
*/
|
|
1680
2156
|
export declare function usePlatform(): Platform;
|
|
1681
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
|
+
|
|
1682
2174
|
/**
|
|
1683
2175
|
* The messages from the closest {@link UiMessagesProvider}, or English.
|
|
1684
2176
|
*
|
package/package.json
CHANGED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"pair-pt-vUVwu.js","names":[],"sources":["../../src/errors/ui-error.ts","../../src/messages/en.ts","../../src/internal/development.ts","../../src/theme/registry.ts","../../src/theme/pair.ts"],"sourcesContent":["import { SdkError } from \"@hussmartinez/sdk-core\";\n\n/**\n * Error codes of `@hussmartinez/ui`. They never change once released.\n *\n * - `INVALID_THEME_TOKEN`: a theme token has an unknown name, or a value that\n * isn't allowed for its type. `details` has `token`, `value` and `reason`.\n * - `INVALID_THEME_SELECTOR`: the selector passed to `themeToCss` isn't a\n * plain CSS selector. `details` has `selector` and `reason`.\n *\n * @public\n */\nexport type UiErrorCode = \"INVALID_THEME_TOKEN\" | \"INVALID_THEME_SELECTOR\";\n\n/**\n * The error `@hussmartinez/ui` throws, with a stable `code` and structured\n * `details`. Show users the text for its code from {@link uiMessages}, never\n * its `message`.\n *\n * @example\n * ```ts\n * try {\n * createTheme({ extends: \"light\", tokens: { \"color-accent\": brandColour } });\n * } catch (error) {\n * if (isSdkError(error, \"INVALID_THEME_TOKEN\")) {\n * // Ask for another colour.\n * }\n * }\n * ```\n *\n * @public\n */\nexport class UiError extends SdkError<UiErrorCode> {\n override readonly name = \"UiError\";\n}\n","import { defineMessages } from \"@hussmartinez/sdk-core\";\n\n/**\n * English text for `@hussmartinez/ui`'s error codes. Applications and SDKs\n * spread it into their catalogue, next to `sdkCoreMessages`, so\n * `messages.error()` can describe a `UiError`. Components add their\n * text here as they arrive.\n *\n * @example\n * ```ts\n * export const en = defineMessages({ ...sdkCoreMessages, ...uiMessages });\n * ```\n *\n * @public\n */\nexport const uiMessages = /* @__PURE__ */ defineMessages({\n \"colorField.swatches\": \"swatches\",\n \"dialog.close\": \"Close\",\n \"fileDropZone.choose\": \"Choose a file\",\n \"fileDropZone.chooseMultiple\": \"Choose files\",\n \"fileDropZone.hint\": \"or drop it here\",\n \"fileDropZone.hintMultiple\": \"or drop them here\",\n \"progress.label\": \"Progress\",\n \"spinner.label\": \"Loading\",\n \"errors.INVALID_THEME_TOKEN\": \"The theme setting {token} has a value that can't be used.\",\n \"errors.INVALID_THEME_SELECTOR\": \"The theme can't be applied to the selector {selector}.\",\n});\n","declare const process: { readonly env: { readonly NODE_ENV?: string } };\n\n/**\n * Whether development-only checks and warnings are on, as a runtime check.\n * The same pattern as sdk-core's.\n *\n * It keeps a forgotten guard from warning in production, but it can't make a\n * bundle smaller: a bundler can't see through a function call, so the\n * message passed to {@link warnInDevelopment} would still ship. Every call\n * site therefore also guards itself inline, with exactly this expression,\n * which bundlers fold away when they replace `process.env.NODE_ENV`:\n *\n * ```ts\n * if (typeof process !== \"undefined\" && process.env.NODE_ENV !== \"production\") {\n * warnInDevelopment(`…`);\n * }\n * ```\n *\n * `development.test.ts` checks every call site, and `build.test.ts` checks\n * that a production bundle drops the messages. Where nothing defines\n * `process`, such as a page loading the module directly, warnings are off.\n */\nexport function isDevelopment(): boolean {\n try {\n return process.env.NODE_ENV !== \"production\";\n } catch {\n return false;\n }\n}\n\n/**\n * Logs a development-only warning. Call it only inside the inline guard\n * shown on {@link isDevelopment}.\n *\n * @param message - What's wrong and how to fix it.\n */\nexport function warnInDevelopment(message: string): void {\n if (isDevelopment()) {\n // biome-ignore lint/suspicious/noConsole: development-only diagnostics are the purpose of this helper.\n console.warn(`[@hussmartinez/ui] ${message}`);\n }\n}\n","import type { Theme } from \"./types.js\";\n\n/** Writes validated themes as CSS. Lives in css-writer.ts. */\nexport type CssWriter = (light: Theme, dark: Theme | undefined, selector: string) => string;\n\n/**\n * Themes from `createTheme`, with the function that writes them as CSS.\n *\n * Kept apart from `createTheme` so `ThemeProvider` can apply themes without\n * importing the validator, the colour parser or the token data: an\n * application that only uses the built-in themes doesn't ship them.\n */\nconst writers = /* @__PURE__ */ new WeakMap<Theme, CssWriter>();\n\n/** Records a validated theme, and how to write it as CSS. */\nexport function registerTheme(theme: Theme, writer: CssWriter): void {\n writers.set(theme, writer);\n}\n\n/**\n * The CSS writer of a theme from `createTheme`, or `undefined` for anything\n * else, such as a theme parsed from JSON.\n */\nexport function cssWriterOf(theme: unknown): CssWriter | undefined {\n return typeof theme === \"object\" && theme !== null ? writers.get(theme as Theme) : undefined;\n}\n","import type { Theme, ThemePair } from \"./types.js\";\n\n/** Whether a value is a light and dark pair rather than a single theme. */\nexport function isThemePair(value: Theme | ThemePair): value is ThemePair {\n return typeof value === \"object\" && value !== null && \"light\" in value && \"dark\" in value;\n}\n"],"mappings":";;AAgCA,IAAa,UAAb,cAA6B,SAAsB;CACjD,OAAyB;AAC3B;;ACnBA,IAAa,aAA6B,+BAAe;CACvD,uBAAuB;CACvB,gBAAgB;CAChB,uBAAuB;CACvB,+BAA+B;CAC/B,qBAAqB;CACrB,6BAA6B;CAC7B,kBAAkB;CAClB,iBAAiB;CACjB,8BAA8B;CAC9B,iCAAiC;AACnC,CAAC;;ACJD,SAAgB,gBAAyB;CACvC,IAAI;EACF,OAAA,QAAA,IAAA,aAAgC;CAClC,QAAQ;EACN,OAAO;CACT;AACF;AAQA,SAAgB,kBAAkB,SAAuB;CACvD,IAAI,cAAc,GAEhB,QAAQ,KAAK,sBAAsB,SAAS;AAEhD;;AC7BA,IAAM,0BAA0B,IAAI,QAA0B;AAG9D,SAAgB,cAAc,OAAc,QAAyB;CACnE,QAAQ,IAAI,OAAO,MAAM;AAC3B;AAMA,SAAgB,YAAY,OAAuC;CACjE,OAAO,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ,IAAI,KAAc,IAAI,KAAA;AACrF;;ACtBA,SAAgB,YAAY,OAA8C;CACxE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW,SAAS,UAAU;AACtF"}
|