@hussmartinez/ui 0.3.0 → 0.5.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 CHANGED
@@ -163,6 +163,7 @@ Every component follows one contract ([ADR 0003](https://github.com/ie-huss-mart
163
163
  | `NumberField` | A number typed as text, exposed as a spin button. Typing is committed on blur or Enter and kept within `min` and `max`; text that isn't a number goes back to the last value, so `onValueChange` never receives `NaN`. Arrow Up and Down step by `step`, Page Up and Down by `largeStep`, and Escape throws the typing away. `parse` and `format` default to the `locale`, or `UiMessagesProvider`'s, digits and separators included; replace them for units or a timecode. With `name`, forms receive the number |
164
164
  | `Slider` | A value in a range, such as volume or zoom, on the native `<input type="range">`: `value` or `defaultValue`, `onValueChange`, `min`, `max`, `step` and `largeStep`. `formatValue` gives screen readers the value as text, such as "−6 dB". Arrow keys, Page Up and Down, Home and End work the same in every browser, mirrored in right-to-left text. In a `Toolbar`, it keeps the arrow keys, so put it last |
165
165
  | `AnnouncerProvider`, `useAnnounce` | Announcements for screen readers, such as "Saved 1.3 MB": `announce(message, { politeness })`. The provider renders the live regions once, on the server too |
166
+ | `usePlatform` | The platform for keyboard shortcuts: `"apple"` on macOS, iOS and iPadOS, where `Mod` is ⌘, otherwise `"other"`. It's `"other"` on the server and during hydration, then Apple devices switch right after, so hydration never mismatches. Pass it to sdk-core's `createShortcutRegistry({ platform })`, and never read `navigator` during render for this |
166
167
 
167
168
  ```tsx
168
169
  import { Button, DownloadIcon, IconButton, RotateLeftIcon } from "@hussmartinez/ui/react";
@@ -221,10 +222,20 @@ The `@hussmartinez` SDKs build their editors from ui's components, so an applica
221
222
 
222
223
  - **One stylesheet, required.** Import `@hussmartinez/ui/styles.css` once, before the SDKs' stylesheets. The SDKs' stylesheets never include it, so it loads once however many SDKs you use. Don't leave it out: the focus rings and target sizes of the components inside an SDK live there.
223
224
  - **One copy of ui.** Each `ui` copy has its own providers, so `UiMessagesProvider`, `ThemeProvider` and `AnnouncerProvider` from one copy don't reach components from another: their text falls back to English, and announcements are lost. If your application uses ui itself, depend on the same minor version as your SDKs; `npm ls @hussmartinez/ui` should list one version. In development, ui warns when a second copy is in use, and names the versions it found.
224
- - **Providers once, at the root.** One `UiMessagesProvider`, `ThemeProvider` and `AnnouncerProvider` around your application reach ui's components inside every SDK too.
225
- - **Headless use.** An SDK's `.` entry never loads ui or React. ui is still installed with the SDK, but its `react` and `react-dom` peers are optional, so there are no peer warnings.
225
+ - **Providers once, at the root.** One `ThemeProvider` and `AnnouncerProvider` around your application reach ui's components inside every SDK too.
226
+ - **Text through the SDK's `messages`.** Inside an SDK, ui's own strings, such as `FileDropZone`'s "Choose a file" or `Dialog`'s "Close", come from the SDK's messages ([ADR 0046](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0046-ui-text-through-the-sdk.md)). Override or translate them through the SDK's `messages` prop, next to the SDK's own text: `{ "fileDropZone.choose": "Datei auswählen" }`. Your own `UiMessagesProvider` reaches only the ui components you render yourself.
227
+ - **Headless use.** An SDK's `.` entry never loads React or ui's React components; it may use ui's server-safe root entry, such as the `IconName` type. ui is installed with the SDK, but its `react` and `react-dom` peers are optional, so there are no peer warnings.
226
228
 
227
- **For SDK authors:** list ui in `dependencies` with a caret range on the current minor, such as `^0.2.0`, and import it only from `features/`, `react/` and `element/`. `sdk-config`'s dependency-cruiser preset fails the build when the core, an adapter, a worker or anything the `.` entry reaches imports it.
229
+ **For SDK authors:**
230
+
231
+ - **The dependency:** list ui in `dependencies` with a caret range on the current minor, such as `^0.4.0`, and import its components only from `features/`, `react/` and `element/`. `sdk-config`'s dependency-cruiser preset fails the build when the core, an adapter or a worker imports ui, or when anything the `.` entry reaches imports React or ui's React entry.
232
+ - **The catalogue:** spread `uiMessages` into your catalogue, next to `sdkCoreMessages`, and pass the one `Messages` object you create with the host's locale and overrides to `UiMessagesProvider` around everything you render. Don't create a second, ui-only object, or hosts can't translate ui's strings.
233
+
234
+ ```ts
235
+ export const myMessages = defineMessages({ ...sdkCoreMessages, ...uiMessages, ...ownMessages });
236
+ ```
237
+
238
+ - **Key collisions:** keep a test that your own keys don't overlap `sdkCoreMessages` or `uiMessages`, so a later release can't silently replace your text. ui's keys use component names as prefixes, such as `dialog.` and `fileDropZone.`.
228
239
 
229
240
  ## Errors and messages
230
241
 
package/dist/index.d.ts CHANGED
@@ -200,7 +200,7 @@ export declare interface ExtendingThemeInput extends ThemeInputBase {
200
200
  *
201
201
  * @public
202
202
  */
203
- export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "delete" | "download" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "split" | "stop" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
203
+ export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "crop" | "delete" | "download" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "snap" | "split" | "stop" | "trim-end" | "trim-start" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
204
204
 
205
205
  /**
206
206
  * The built-in light theme.
package/dist/react.d.ts CHANGED
@@ -15,6 +15,7 @@ import { ForwardRefExoticComponent } from 'react';
15
15
  import { HTMLAttributes } from 'react';
16
16
  import { InputHTMLAttributes } from 'react';
17
17
  import { Messages } from '@hussmartinez/sdk-core';
18
+ import { Platform } from '@hussmartinez/sdk-core';
18
19
  import { ProgressHTMLAttributes } from 'react';
19
20
  import { ReactElement } from 'react';
20
21
  import { ReactNode } from 'react';
@@ -174,6 +175,13 @@ export declare function CloseIcon(props: IconProps): ReactElement;
174
175
  */
175
176
  export declare type ColorMode = "light" | "dark" | "system";
176
177
 
178
+ /**
179
+ * The `crop` icon: Lucide's `crop`.
180
+ *
181
+ * @public
182
+ */
183
+ export declare function CropIcon(props: IconProps): ReactElement;
184
+
177
185
  /**
178
186
  * The `delete` icon: Lucide's `trash`.
179
187
  *
@@ -260,6 +268,20 @@ export declare interface DialogProps extends Omit<DialogHTMLAttributes<HTMLDialo
260
268
  */
261
269
  export declare function DownloadIcon(props: IconProps): ReactElement;
262
270
 
271
+ /**
272
+ * The `fade-in` icon: Lucide's `chart-no-axes-column-increasing`.
273
+ *
274
+ * @public
275
+ */
276
+ export declare function FadeInIcon(props: IconProps): ReactElement;
277
+
278
+ /**
279
+ * The `fade-out` icon: Lucide's `chart-no-axes-column-decreasing`.
280
+ *
281
+ * @public
282
+ */
283
+ export declare function FadeOutIcon(props: IconProps): ReactElement;
284
+
263
285
  /**
264
286
  * A label, an optional description and an optional error, wired to one
265
287
  * control: the label names it, and the description and error describe it.
@@ -431,6 +453,27 @@ export declare interface FileRejection {
431
453
  readonly reason: "type" | "count" | "directory";
432
454
  }
433
455
 
456
+ /**
457
+ * The `fit` icon: Lucide's `scan`.
458
+ *
459
+ * @public
460
+ */
461
+ export declare function FitIcon(props: IconProps): ReactElement;
462
+
463
+ /**
464
+ * The `flip-horizontal` icon: Lucide's `triangles-centerline-dashed-vertical`.
465
+ *
466
+ * @public
467
+ */
468
+ export declare function FlipHorizontalIcon(props: IconProps): ReactElement;
469
+
470
+ /**
471
+ * The `flip-vertical` icon: Lucide's `triangles-centerline-dashed-horizontal`.
472
+ *
473
+ * @public
474
+ */
475
+ export declare function FlipVerticalIcon(props: IconProps): ReactElement;
476
+
434
477
  /**
435
478
  * The `highlighter` icon: Lucide's `highlighter`.
436
479
  *
@@ -479,7 +522,7 @@ export declare type IconComponent = (props: IconProps) => ReactElement;
479
522
  *
480
523
  * @public
481
524
  */
482
- export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "delete" | "download" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "split" | "stop" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
525
+ export declare type IconName = "add" | "check" | "chevron-down" | "chevron-left" | "chevron-right" | "close" | "crop" | "delete" | "download" | "fade-in" | "fade-out" | "fit" | "flip-horizontal" | "flip-vertical" | "highlighter" | "info" | "loop" | "menu" | "more" | "muted" | "open" | "page-grid" | "page-single" | "pan" | "pause" | "pen" | "play" | "redo" | "remove" | "rotate-left" | "rotate-right" | "search" | "select" | "skip-back" | "skip-forward" | "snap" | "split" | "stop" | "trim-end" | "trim-start" | "undo" | "upload" | "volume" | "warning" | "zoom-in" | "zoom-out";
483
526
 
484
527
  /**
485
528
  * Props of every icon. SVG attributes are passed through.
@@ -886,6 +929,13 @@ export declare interface SliderProps extends Omit<InputHTMLAttributes<HTMLInputE
886
929
  readonly label?: string | undefined;
887
930
  }
888
931
 
932
+ /**
933
+ * The `snap` icon: Lucide's `magnet`.
934
+ *
935
+ * @public
936
+ */
937
+ export declare function SnapIcon(props: IconProps): ReactElement;
938
+
889
939
  /**
890
940
  * Shows that something is loading, for an unknown time. It's an
891
941
  * indeterminate progress bar to assistive technology, named by `label`.
@@ -1203,6 +1253,20 @@ export declare const ToolbarSeparator: ForwardRefExoticComponent<ToolbarSeparato
1203
1253
  */
1204
1254
  export declare type ToolbarSeparatorProps = Omit<HTMLAttributes<HTMLHRElement>, "children">;
1205
1255
 
1256
+ /**
1257
+ * The `trim-end` icon: Lucide's `arrow-left-from-line`.
1258
+ *
1259
+ * @public
1260
+ */
1261
+ export declare function TrimEndIcon(props: IconProps): ReactElement;
1262
+
1263
+ /**
1264
+ * The `trim-start` icon: Lucide's `arrow-right-from-line`.
1265
+ *
1266
+ * @public
1267
+ */
1268
+ export declare function TrimStartIcon(props: IconProps): ReactElement;
1269
+
1206
1270
  /**
1207
1271
  * Messages that include `ui`'s text: any sdk-core `Messages` object whose
1208
1272
  * catalogue spreads `uiMessages`.
@@ -1290,6 +1354,27 @@ export declare function UploadIcon(props: IconProps): ReactElement;
1290
1354
  */
1291
1355
  export declare function useAnnounce(): Announce;
1292
1356
 
1357
+ /**
1358
+ * The platform whose keyboard conventions apply, for shortcut labels and for
1359
+ * sdk-core's `createShortcutRegistry({ platform })`: `"apple"` on macOS, iOS
1360
+ * and iPadOS, where `Mod` is `Meta` (⌘), and `"other"` elsewhere, where it's
1361
+ * `Control`.
1362
+ *
1363
+ * A server can't know the platform, so the server render and hydration both
1364
+ * use `"other"`, and Apple devices switch to their keys in the render right
1365
+ * after hydration. That keeps hydration free of mismatches. Never read
1366
+ * `navigator` during render for this.
1367
+ *
1368
+ * @example
1369
+ * ```tsx
1370
+ * const platform = usePlatform();
1371
+ * const shortcuts = useMemo(() => createShortcutRegistry({ platform, tools }), [platform, tools]);
1372
+ * ```
1373
+ *
1374
+ * @public
1375
+ */
1376
+ export declare function usePlatform(): Platform;
1377
+
1293
1378
  /**
1294
1379
  * The messages from the closest {@link UiMessagesProvider}, or English.
1295
1380
  *
package/dist/react.js CHANGED
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
  import { a as uiMessages, i as warnInDevelopment, n as cssWriterOf, o as UiError, t as isThemePair } from "./shared/pair-DLVFV6vU.js";
3
- import { createMessages, sdkCoreMessages } from "@hussmartinez/sdk-core";
4
- import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
3
+ import { createMessages, platformOf, sdkCoreMessages } from "@hussmartinez/sdk-core";
4
+ import { createContext, forwardRef, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
5
5
  import { Fragment, jsx, jsxs } from "react/jsx-runtime";
6
6
  import { flushSync } from "react-dom";
7
7
  // src/internal/single-copy.ts
@@ -9,7 +9,7 @@ var REGISTRY = /* @__PURE__ */ Symbol.for("@hussmartinez/ui");
9
9
  var THIS_COPY = {};
10
10
  var checked = false;
11
11
  function ownVersion() {
12
- return "0.3.0";
12
+ return "0.5.0";
13
13
  }
14
14
  function checkSingleCopy() {
15
15
  if (checked || !(typeof process !== "undefined" && process.env.NODE_ENV !== "production")) return;
@@ -999,6 +999,9 @@ function ChevronRightIcon(props) {
999
999
  function CloseIcon(props) {
1000
1000
  return renderIcon("close", [["path", { d: "M18 6 6 18" }], ["path", { d: "m6 6 12 12" }]], false, props);
1001
1001
  }
1002
+ function CropIcon(props) {
1003
+ return renderIcon("crop", [["path", { d: "M6 2v14a2 2 0 0 0 2 2h14" }], ["path", { d: "M18 22V8a2 2 0 0 0-2-2H2" }]], false, props);
1004
+ }
1002
1005
  function DeleteIcon(props) {
1003
1006
  return renderIcon("delete", [
1004
1007
  ["path", { d: "M10 11v6" }],
@@ -1015,6 +1018,48 @@ function DownloadIcon(props) {
1015
1018
  ["path", { d: "m7 10 5 5 5-5" }]
1016
1019
  ], false, props);
1017
1020
  }
1021
+ function FadeInIcon(props) {
1022
+ return renderIcon("fade-in", [
1023
+ ["path", { d: "M5 21v-6" }],
1024
+ ["path", { d: "M12 21V9" }],
1025
+ ["path", { d: "M19 21V3" }]
1026
+ ], false, props);
1027
+ }
1028
+ function FadeOutIcon(props) {
1029
+ return renderIcon("fade-out", [
1030
+ ["path", { d: "M5 21V3" }],
1031
+ ["path", { d: "M12 21V9" }],
1032
+ ["path", { d: "M19 21v-6" }]
1033
+ ], false, props);
1034
+ }
1035
+ function FitIcon(props) {
1036
+ return renderIcon("fit", [
1037
+ ["path", { d: "M3 7V5a2 2 0 0 1 2-2h2" }],
1038
+ ["path", { d: "M17 3h2a2 2 0 0 1 2 2v2" }],
1039
+ ["path", { d: "M21 17v2a2 2 0 0 1-2 2h-2" }],
1040
+ ["path", { d: "M7 21H5a2 2 0 0 1-2-2v-2" }]
1041
+ ], false, props);
1042
+ }
1043
+ function FlipHorizontalIcon(props) {
1044
+ return renderIcon("flip-horizontal", [
1045
+ ["path", { d: "M12 14v2" }],
1046
+ ["path", { d: "M12 20v2" }],
1047
+ ["path", { d: "M12 2v2" }],
1048
+ ["path", { d: "M12 8v2" }],
1049
+ ["path", { d: "M20.288 16.703A1 1 0 0022 16V8a1 1 0 00-1.712-.703l-3.99 3.991a1 1 0 00-.001 1.424z" }],
1050
+ ["path", { d: "M3.712 16.703A1 1 0 012 16V8a1 1 0 011.712-.703l3.99 3.991a1 1 0 01.001 1.424z" }]
1051
+ ], false, props);
1052
+ }
1053
+ function FlipVerticalIcon(props) {
1054
+ return renderIcon("flip-vertical", [
1055
+ ["path", { d: "M10 12H8" }],
1056
+ ["path", { d: "M16 12h-2" }],
1057
+ ["path", { d: "M22 12h-2" }],
1058
+ ["path", { d: "M4 12H2" }],
1059
+ ["path", { d: "M7.298 20.288A1 1 0 008 22h8a1 1 0 00.703-1.712l-3.991-3.99a1 1 0 00-1.424-.001z" }],
1060
+ ["path", { d: "M7.298 3.712A1 1 0 018 2h8a1 1 0 01.703 1.712l-3.991 3.99a1 1 0 01-1.424.001z" }]
1061
+ ], false, props);
1062
+ }
1018
1063
  function HighlighterIcon(props) {
1019
1064
  return renderIcon("highlighter", [["path", { d: "m9 11-6 6v3h9l3-3" }], ["path", { d: "m22 12-4.6 4.6a2 2 0 0 1-2.8 0l-5.2-5.2a2 2 0 0 1 0-2.8L14 4" }]], false, props);
1020
1065
  }
@@ -1146,6 +1191,13 @@ function SkipBackIcon(props) {
1146
1191
  function SkipForwardIcon(props) {
1147
1192
  return renderIcon("skip-forward", [["path", { d: "M21 4v16" }], ["path", { d: "M6.029 4.285A2 2 0 0 0 3 6v12a2 2 0 0 0 3.029 1.715l9.997-5.998a2 2 0 0 0 .003-3.432z" }]], false, props);
1148
1193
  }
1194
+ function SnapIcon(props) {
1195
+ return renderIcon("snap", [
1196
+ ["path", { d: "m12 15 4 4" }],
1197
+ ["path", { d: "M2.352 10.648a1.205 1.205 0 0 0 0 1.704l2.296 2.296a1.205 1.205 0 0 0 1.704 0l6.029-6.029a1 1 0 1 1 3 3l-6.029 6.029a1.205 1.205 0 0 0 0 1.704l2.296 2.296a1.205 1.205 0 0 0 1.704 0l6.365-6.367A1 1 0 0 0 8.716 4.282z" }],
1198
+ ["path", { d: "m5 8 4 4" }]
1199
+ ], false, props);
1200
+ }
1149
1201
  function SplitIcon(props) {
1150
1202
  return renderIcon("split", [
1151
1203
  ["circle", {
@@ -1172,6 +1224,20 @@ function StopIcon(props) {
1172
1224
  rx: "2"
1173
1225
  }]], false, props);
1174
1226
  }
1227
+ function TrimEndIcon(props) {
1228
+ return renderIcon("trim-end", [
1229
+ ["path", { d: "m9 6-6 6 6 6" }],
1230
+ ["path", { d: "M3 12h14" }],
1231
+ ["path", { d: "M21 19V5" }]
1232
+ ], false, props);
1233
+ }
1234
+ function TrimStartIcon(props) {
1235
+ return renderIcon("trim-start", [
1236
+ ["path", { d: "M3 5v14" }],
1237
+ ["path", { d: "M21 12H7" }],
1238
+ ["path", { d: "m15 18 6-6-6-6" }]
1239
+ ], false, props);
1240
+ }
1175
1241
  function UndoIcon(props) {
1176
1242
  return renderIcon("undo", [["path", { d: "M9 14 4 9l5-5" }], ["path", { d: "M4 9h10.5a5.5 5.5 0 0 1 5.5 5.5a5.5 5.5 0 0 1-5.5 5.5H11" }]], true, props);
1177
1243
  }
@@ -1282,6 +1348,13 @@ function ThemeProvider(props) {
1282
1348
  }), children]
1283
1349
  });
1284
1350
  }
1285
- export { AddIcon, AnnouncerProvider, Button, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, CloseIcon, DeleteIcon, Dialog, DownloadIcon, Field, FileDropZone, HighlighterIcon, IconButton, InfoIcon, LoopIcon, MenuIcon, MoreIcon, MutedIcon, NumberField, OpenIcon, PageGridIcon, PageSingleIcon, PanIcon, PauseIcon, PenIcon, PlayIcon, ProgressBar, RedoIcon, RemoveIcon, RotateLeftIcon, RotateRightIcon, SearchIcon, SegmentedControl, SelectIcon, SkipBackIcon, SkipForwardIcon, Slider, Spinner, SplitIcon, StopIcon, ThemeProvider, ToggleButton, Toolbar, ToolbarGroup, ToolbarSeparator, UiMessagesProvider, UndoIcon, UploadIcon, VisuallyHidden, VolumeIcon, WarningIcon, ZoomInIcon, ZoomOutIcon, uiMessages, useAnnounce, useUiMessages };
1351
+ // src/react/use-platform.ts
1352
+ var subscribe = () => () => void 0;
1353
+ var onClient = () => platformOf(globalThis.navigator);
1354
+ var onServer = () => "other";
1355
+ function usePlatform() {
1356
+ return useSyncExternalStore(subscribe, onClient, onServer);
1357
+ }
1358
+ export { AddIcon, AnnouncerProvider, Button, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, CloseIcon, CropIcon, DeleteIcon, Dialog, DownloadIcon, FadeInIcon, FadeOutIcon, Field, FileDropZone, FitIcon, FlipHorizontalIcon, FlipVerticalIcon, HighlighterIcon, IconButton, InfoIcon, LoopIcon, MenuIcon, MoreIcon, MutedIcon, NumberField, OpenIcon, PageGridIcon, PageSingleIcon, PanIcon, PauseIcon, PenIcon, PlayIcon, ProgressBar, RedoIcon, RemoveIcon, RotateLeftIcon, RotateRightIcon, SearchIcon, SegmentedControl, SelectIcon, SkipBackIcon, SkipForwardIcon, Slider, SnapIcon, Spinner, SplitIcon, StopIcon, ThemeProvider, ToggleButton, Toolbar, ToolbarGroup, ToolbarSeparator, TrimEndIcon, TrimStartIcon, UiMessagesProvider, UndoIcon, UploadIcon, VisuallyHidden, VolumeIcon, WarningIcon, ZoomInIcon, ZoomOutIcon, uiMessages, useAnnounce, usePlatform, useUiMessages };
1286
1359
 
1287
1360
  //# sourceMappingURL=react.js.map