@barqjs/aria 0.2.0-next.0 → 0.2.0-next.1

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.
Files changed (78) hide show
  1. package/README.md +24 -13
  2. package/package.json +127 -37
  3. package/src/autocomplete.tsx +581 -0
  4. package/src/breadcrumbs.tsx +21 -20
  5. package/src/button.tsx +151 -25
  6. package/src/calendar.tsx +1019 -92
  7. package/src/checkbox.tsx +214 -52
  8. package/src/collections.ts +88 -5
  9. package/src/color.ts +1580 -23
  10. package/src/colorpicker.tsx +698 -153
  11. package/src/colorswatchpicker.tsx +240 -0
  12. package/src/combobox.tsx +635 -113
  13. package/src/command.tsx +78 -59
  14. package/src/date.ts +31 -9
  15. package/src/datefield.tsx +1451 -336
  16. package/src/datepicker.tsx +465 -114
  17. package/src/dialog.tsx +302 -115
  18. package/src/disclosure.tsx +81 -29
  19. package/src/dnd/clipboard.ts +125 -0
  20. package/src/dnd/collection.ts +1265 -0
  21. package/src/dnd/data.ts +409 -0
  22. package/src/dnd/drag-drop.ts +801 -0
  23. package/src/dnd/index.ts +133 -0
  24. package/src/dnd/manager.ts +639 -0
  25. package/src/dnd/strings.ts +1279 -0
  26. package/src/dnd/targets.ts +726 -0
  27. package/src/dnd/types.ts +212 -0
  28. package/src/dom.ts +3 -6
  29. package/src/drag-and-drop.tsx +669 -0
  30. package/src/dropzone.tsx +208 -0
  31. package/src/file-trigger.tsx +103 -0
  32. package/src/form.tsx +18 -18
  33. package/src/gridlist.tsx +912 -121
  34. package/src/group.tsx +146 -0
  35. package/src/index.ts +402 -0
  36. package/src/interactions/focus-events.ts +13 -5
  37. package/src/interactions/keyboard.ts +195 -2
  38. package/src/interactions/modality.ts +18 -6
  39. package/src/interactions/open-link.ts +46 -13
  40. package/src/interactions/press.ts +35 -18
  41. package/src/label.ts +18 -6
  42. package/src/link.tsx +146 -50
  43. package/src/listbox.tsx +615 -89
  44. package/src/live.ts +4 -0
  45. package/src/menu.tsx +182 -89
  46. package/src/menubar.tsx +21 -17
  47. package/src/navigation-tree.tsx +357 -0
  48. package/src/numberfield.tsx +164 -60
  49. package/src/overlay-arrow.tsx +157 -0
  50. package/src/overlays.ts +364 -62
  51. package/src/platform.ts +2 -1
  52. package/src/preview-trigger.tsx +582 -0
  53. package/src/progress-bar-context.ts +15 -0
  54. package/src/questionnaire.tsx +109 -104
  55. package/src/radio.tsx +101 -27
  56. package/src/select.tsx +225 -145
  57. package/src/selection-indicator.tsx +74 -0
  58. package/src/selection.ts +73 -16
  59. package/src/shared-element-transition.tsx +316 -0
  60. package/src/sheet.tsx +1461 -0
  61. package/src/slider.tsx +139 -44
  62. package/src/switch.tsx +47 -21
  63. package/src/table.tsx +0 -0
  64. package/src/tabs.tsx +198 -89
  65. package/src/tag.tsx +217 -32
  66. package/src/textarea.tsx +186 -0
  67. package/src/textfield.tsx +103 -37
  68. package/src/toast-components.tsx +589 -0
  69. package/src/toggle-button-group.tsx +175 -0
  70. package/src/toggle-input.tsx +38 -0
  71. package/src/toggle.ts +68 -5
  72. package/src/tokenfield.tsx +1673 -0
  73. package/src/toolbar.tsx +15 -10
  74. package/src/tooltip.tsx +46 -29
  75. package/src/tree.tsx +2075 -0
  76. package/src/utils.ts +30 -1
  77. package/src/validation.ts +79 -22
  78. package/src/virtualizer.tsx +186 -23
@@ -21,13 +21,13 @@
21
21
  */
22
22
 
23
23
  import {
24
+ cells,
24
25
  type Accessor,
25
26
  type Child,
26
27
  createMemo,
27
28
  createContext,
28
29
  getContext,
29
30
  getOwner,
30
- type Incoming,
31
31
  install,
32
32
  createSignal,
33
33
  } from "@barqjs/core";
@@ -41,14 +41,19 @@ import {
41
41
  type ColorFormat,
42
42
  type ColorSpace,
43
43
  } from "./color.ts";
44
+ import { useColorSwatchPickerItem } from "./colorswatchpicker.tsx";
44
45
  import { focusWithoutScrolling } from "./dom.ts";
45
46
  import { focusRing } from "./focus.ts";
47
+ import { numberFormatter, StringDictionary, stringFormatter, useLocale } from "./i18n.ts";
48
+ import { focusWithin } from "./interactions/focus-events.ts";
46
49
  import { hover } from "./interactions/hover.ts";
47
50
  import { globalListeners } from "./interactions/listeners.ts";
48
51
  import { move, type MoveMoveEvent } from "./interactions/move.ts";
49
52
  import type { ElementRef } from "./interactions/press.ts";
53
+ import { scrollWheel } from "./interactions/scroll-wheel.ts";
50
54
  import { label as useLabelHook } from "./label.ts";
51
55
  import { visuallyHidden } from "./live.ts";
56
+ import { spinButton } from "./numberfield.tsx";
52
57
  import { formReset, HIDDEN_INPUT_STYLE } from "./toggle.ts";
53
58
  import { textField, type TextFieldOptions } from "./textfield.tsx";
54
59
  import {
@@ -90,6 +95,29 @@ function asColor(value: Color | string | null | undefined): Color | undefined {
90
95
  return typeof value === "string" ? parseColor(value) : value;
91
96
  }
92
97
 
98
+ /** A channel as words read it, in the locale in scope: "Hue 212", "Alpha 50%". */
99
+ function channelWords(): (color: Color, channel: ColorChannel) => string {
100
+ const locale = useLocale();
101
+ const decimal = numberFormatter();
102
+ const percent = numberFormatter({ style: "percent", maximumFractionDigits: 0 });
103
+ return (color, channel) => {
104
+ const amount = color.getChannelValue(channel);
105
+ const value =
106
+ channel === "alpha" ? percent().format(amount) : decimal().format(Math.round(amount));
107
+ return `${color.getChannelName(channel, locale().locale)} ${value}`;
108
+ };
109
+ }
110
+
111
+ function message(
112
+ format: Accessor<{ format(key: PickerStringKey): string }>,
113
+ key: PickerStringKey,
114
+ variables: Record<string, string> = {},
115
+ ): string {
116
+ return format()
117
+ .format(key)
118
+ .replace(/\{(\w+)\}/g, (whole, name: string) => variables[name] ?? whole);
119
+ }
120
+
93
121
  // ---------------------------------------------------------------------------
94
122
  // A single channel: the slider and the wheel
95
123
  // ---------------------------------------------------------------------------
@@ -130,10 +158,15 @@ export function colorSliderState(options: ColorSliderStateOptions): ColorSliderS
130
158
  const [dragging, writeDragging] = createSignal(false);
131
159
  const channel = (): ColorChannel => access(options.channel);
132
160
  const isDisabled = (): boolean => access(options.isDisabled) === true;
161
+ const locale = useLocale();
162
+ const words = channelWords();
133
163
 
134
164
  // What the LAST write produced, so a drag reads its own change back rather
135
- // than the value a controlled owner has not caught up with yet.
165
+ // than the value a controlled owner has not caught up with yet. The drag
166
+ // flag is kept the same way: a key press starts and ends a drag in one
167
+ // tick, before the signal's write is published.
136
168
  let live = value();
169
+ let isDragging = false;
137
170
 
138
171
  const setValue = (next: Color): void => {
139
172
  live = next;
@@ -169,7 +202,8 @@ export function colorSliderState(options: ColorSliderStateOptions): ColorSliderS
169
202
  setChannelValue(Math.round(raw / limits.step) * limits.step);
170
203
  },
171
204
  setDragging: (next) => {
172
- const was = dragging();
205
+ const was = isDragging;
206
+ isDragging = next;
173
207
  writeDragging(next);
174
208
  if (was && !next) options.onChangeEnd?.(live);
175
209
  },
@@ -177,9 +211,10 @@ export function colorSliderState(options: ColorSliderStateOptions): ColorSliderS
177
211
  decrement: (step) => setChannelValue(live.getChannelValue(channel()) - (step ?? range().step)),
178
212
  valueText: () => {
179
213
  const current = value();
180
- const name = current.getChannelName(channel());
181
- const amount = current.getChannelValue(channel());
182
- return `${name} ${channel() === "alpha" ? `${Math.round(amount * 100)}%` : Math.round(amount)}`;
214
+ const text = words(current, channel());
215
+ if (channel() === "hue" || channel() === "alpha") return text;
216
+ // The channel's number alone does not say what colour it made.
217
+ return `${text}, ${current.withChannelValue("alpha", 1).getColorName(locale().locale)}`;
183
218
  },
184
219
  };
185
220
  }
@@ -227,8 +262,10 @@ export function colorAreaState(options: ColorAreaStateOptions): ColorAreaState {
227
262
 
228
263
  const [dragging, writeDragging] = createSignal(false);
229
264
  const isDisabled = (): boolean => access(options.isDisabled) === true;
265
+ const words = channelWords();
230
266
 
231
267
  let live = value();
268
+ let isDragging = false;
232
269
  const setValue = (next: Color): void => {
233
270
  live = next;
234
271
  setValueRaw(next);
@@ -286,7 +323,8 @@ export function colorAreaState(options: ColorAreaStateOptions): ColorAreaState {
286
323
  );
287
324
  },
288
325
  setDragging: (next) => {
289
- const was = dragging();
326
+ const was = isDragging;
327
+ isDragging = next;
290
328
  writeDragging(next);
291
329
  if (was && !next) options.onChangeEnd?.(live);
292
330
  },
@@ -296,9 +334,7 @@ export function colorAreaState(options: ColorAreaStateOptions): ColorAreaState {
296
334
  decrementY: (by) => step(yChannel(), -(by ?? live.getChannelRange(yChannel()).step)),
297
335
  valueText: () => {
298
336
  const current = value();
299
- return `${current.getChannelName(xChannel())} ${Math.round(
300
- current.getChannelValue(xChannel()),
301
- )}, ${current.getChannelName(yChannel())} ${Math.round(current.getChannelValue(yChannel()))}`;
337
+ return `${words(current, xChannel())}, ${words(current, yChannel())}`;
302
338
  },
303
339
  };
304
340
  }
@@ -311,6 +347,8 @@ export interface ColorSliderOptions {
311
347
  trackRef: ElementRef;
312
348
  inputRef: ElementRef<HTMLInputElement>;
313
349
  label?: MaybeAccessor<Child>;
350
+ name?: MaybeAccessor<string | undefined>;
351
+ form?: MaybeAccessor<string | undefined>;
314
352
  "aria-label"?: MaybeAccessor<string | undefined>;
315
353
  "aria-labelledby"?: MaybeAccessor<string | undefined>;
316
354
  }
@@ -342,15 +380,50 @@ export function colorSlider(
342
380
  labelElementType: "label",
343
381
  });
344
382
 
383
+ const locale = useLocale();
384
+ const listeners = globalListeners();
345
385
  const isVertical = (): boolean => state.orientation() === "vertical";
386
+ // Right to left, the minimum of a horizontal track is on the right.
387
+ const isMirrored = (): boolean => !isVertical() && locale().direction === "rtl";
346
388
  let position: number | null = null;
347
389
 
390
+ const range = (): ReturnType<Color["getChannelRange"]> =>
391
+ state.value().getChannelRange(state.channel());
392
+
393
+ // A press that never moves is still a change, and the release ends it.
394
+ const endOnRelease = (element: Element): void => {
395
+ if (isServer) return;
396
+ listeners.add(element.ownerDocument.defaultView ?? window, "pointerup", () => {
397
+ state.setDragging(false);
398
+ listeners.removeAll();
399
+ });
400
+ };
401
+
402
+ // A key press is a drag that starts and ends at once, so it ends the change.
403
+ const byKeyboard = (change: () => void): void => {
404
+ if (state.isDisabled()) return;
405
+ state.setDragging(true);
406
+ change();
407
+ state.setDragging(false);
408
+ };
409
+
348
410
  const { moveProps } = move({
349
411
  onMoveStart: () => {
350
412
  position = null;
351
413
  state.setDragging(true);
352
414
  },
353
415
  onMove: (event) => {
416
+ if (event.pointerType === "keyboard") {
417
+ const by = event.shiftKey ? range().pageSize : range().step;
418
+ const lower =
419
+ (event.deltaX > 0 && isMirrored()) ||
420
+ (event.deltaX < 0 && !isMirrored()) ||
421
+ event.deltaY > 0;
422
+ if (lower) state.decrement(by);
423
+ else state.increment(by);
424
+ return;
425
+ }
426
+
354
427
  const track = access(options.trackRef) as Element | null;
355
428
  if (track === null) return;
356
429
  const box = track.getBoundingClientRect();
@@ -359,7 +432,8 @@ export function colorSlider(
359
432
 
360
433
  if (position === null) position = state.percent() * size;
361
434
  // Up is MORE on a vertical track, and the y axis counts down.
362
- position += isVertical() ? -event.deltaY : event.deltaX;
435
+ if (isVertical()) position -= event.deltaY;
436
+ else position += isMirrored() ? -event.deltaX : event.deltaX;
363
437
  state.setPercent(position / size);
364
438
  },
365
439
  onMoveEnd: () => state.setDragging(false),
@@ -373,12 +447,13 @@ export function colorSlider(
373
447
  if (size === 0) return;
374
448
  const offset = (isVertical() ? clientY : clientX) - (isVertical() ? box.top : box.left);
375
449
  state.setDragging(true);
376
- state.setPercent(isVertical() ? 1 - offset / size : offset / size);
450
+ state.setPercent(isVertical() || isMirrored() ? 1 - offset / size : offset / size);
377
451
  (access(options.inputRef) as HTMLInputElement | null)?.focus();
452
+ endOnRelease(track);
378
453
  };
379
454
 
380
- const range = (): ReturnType<Color["getChannelRange"]> =>
381
- state.value().getChannelRange(state.channel());
455
+ const initial = state.channelValue();
456
+ formReset(options.inputRef, initial, (next: number) => state.setChannelValue(next));
382
457
 
383
458
  return {
384
459
  labelProps,
@@ -393,7 +468,7 @@ export function colorSlider(
393
468
  style: () => ({
394
469
  position: "absolute",
395
470
  [isVertical() ? "top" : "left"]:
396
- `${(isVertical() ? 1 - state.percent() : state.percent()) * 100}%`,
471
+ `${(isVertical() || isMirrored() ? 1 - state.percent() : state.percent()) * 100}%`,
397
472
  transform: "translate(-50%, -50%)",
398
473
  "touch-action": "none",
399
474
  }),
@@ -406,6 +481,8 @@ export function colorSlider(
406
481
  step: () => range().step,
407
482
  value: state.channelValue,
408
483
  disabled: state.isDisabled,
484
+ name: () => access(options.name),
485
+ form: () => access(options.form),
409
486
  "aria-orientation": state.orientation,
410
487
  // The number MEANS something: "212" is not a colour, "Hue 212" is.
411
488
  "aria-valuetext": state.valueText,
@@ -416,13 +493,24 @@ export function colorSlider(
416
493
  state.setChannelValue(Number.parseFloat((event.target as HTMLInputElement).value));
417
494
  },
418
495
  onKeyDown: (event: KeyboardEvent) => {
419
- // Page Up and Page Down, which a range input has no notion of.
420
- if (event.key !== "PageUp" && event.key !== "PageDown") return;
496
+ // Keys a range input either lacks or handles without ending the change.
497
+ switch (event.key) {
498
+ case "PageUp":
499
+ byKeyboard(() => state.increment(range().pageSize));
500
+ break;
501
+ case "PageDown":
502
+ byKeyboard(() => state.decrement(range().pageSize));
503
+ break;
504
+ case "Home":
505
+ byKeyboard(() => state.setChannelValue(range().minValue));
506
+ break;
507
+ case "End":
508
+ byKeyboard(() => state.setChannelValue(range().maxValue));
509
+ break;
510
+ default:
511
+ return;
512
+ }
421
513
  event.preventDefault();
422
- state.setDragging(true);
423
- if (event.key === "PageUp") state.increment(range().pageSize);
424
- else state.decrement(range().pageSize);
425
- state.setDragging(false);
426
514
  },
427
515
  }),
428
516
  outputProps: { "aria-live": "off", for: inputId },
@@ -433,6 +521,10 @@ export interface ColorAreaOptions {
433
521
  containerRef: ElementRef;
434
522
  xInputRef: ElementRef<HTMLInputElement>;
435
523
  yInputRef: ElementRef<HTMLInputElement>;
524
+ /** The form names the two channels are submitted under. */
525
+ xName?: MaybeAccessor<string | undefined>;
526
+ yName?: MaybeAccessor<string | undefined>;
527
+ form?: MaybeAccessor<string | undefined>;
436
528
  "aria-label"?: MaybeAccessor<string | undefined>;
437
529
  "aria-labelledby"?: MaybeAccessor<string | undefined>;
438
530
  }
@@ -454,8 +546,13 @@ export interface ColorAreaResult {
454
546
  */
455
547
  export function colorArea(options: ColorAreaOptions, state: ColorAreaState): ColorAreaResult {
456
548
  const listeners = globalListeners();
549
+ const locale = useLocale();
550
+ const strings = stringFormatter(PICKER_STRINGS);
457
551
  let position: { x: number; y: number } | null = null;
458
552
 
553
+ // Right to left, X grows leftwards, as the text does.
554
+ const isMirrored = (): boolean => locale().direction === "rtl";
555
+
459
556
  /**
460
557
  * Which axis the keyboard last moved, so a drag ends on the input that was
461
558
  * driving it.
@@ -472,12 +569,39 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
472
569
  (access(ref) as HTMLInputElement | null)?.focus();
473
570
  };
474
571
 
572
+ const pageOf = (channel: ColorChannel): number => {
573
+ const range = state.value().getChannelRange(channel);
574
+ return Math.max(range.pageSize, range.step);
575
+ };
576
+
577
+ // A key press is a drag that starts and ends at once, so it ends the change.
578
+ const byKeyboard = (moved: "x" | "y", change: () => void): void => {
579
+ if (state.isDisabled()) return;
580
+ state.setDragging(true);
581
+ change();
582
+ state.setDragging(false);
583
+ axis = moved;
584
+ focusAxis();
585
+ };
586
+
475
587
  const { moveProps } = move({
476
588
  onMoveStart: () => {
477
589
  position = null;
478
590
  state.setDragging(true);
479
591
  },
480
592
  onMove: (event) => {
593
+ if (event.pointerType === "keyboard") {
594
+ const xStep = event.shiftKey ? pageOf(state.xChannel()) : undefined;
595
+ const yStep = event.shiftKey ? pageOf(state.yChannel()) : undefined;
596
+ const right = isMirrored() ? -event.deltaX : event.deltaX;
597
+ if (right > 0) state.incrementX(xStep);
598
+ else if (right < 0) state.decrementX(xStep);
599
+ else if (event.deltaY > 0) state.decrementY(yStep);
600
+ else if (event.deltaY < 0) state.incrementY(yStep);
601
+ axis = Math.abs(event.deltaY) > Math.abs(event.deltaX) ? "y" : "x";
602
+ return;
603
+ }
604
+
481
605
  const container = access(options.containerRef) as Element | null;
482
606
  if (container === null) return;
483
607
  const box = container.getBoundingClientRect();
@@ -486,7 +610,7 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
486
610
  if (position === null) {
487
611
  position = { x: state.xPercent() * box.width, y: (1 - state.yPercent()) * box.height };
488
612
  }
489
- position.x += event.deltaX;
613
+ position.x += isMirrored() ? -event.deltaX : event.deltaX;
490
614
  position.y += event.deltaY;
491
615
  // The y axis counts DOWN the screen and UP the value.
492
616
  state.setPercents(position.x / box.width, 1 - position.y / box.height);
@@ -502,8 +626,9 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
502
626
  if (container === null || state.isDisabled()) return;
503
627
  const box = container.getBoundingClientRect();
504
628
  if (box.width === 0 || box.height === 0) return;
629
+ const x = (clientX - box.left) / box.width;
505
630
  state.setDragging(true);
506
- state.setPercents((clientX - box.left) / box.width, 1 - (clientY - box.top) / box.height);
631
+ state.setPercents(isMirrored() ? 1 - x : x, 1 - (clientY - box.top) / box.height);
507
632
  // A pointer drives both channels at once, so it lands on X — which is what
508
633
  // a reader then announces, and what the arrows move next.
509
634
  axis = "x";
@@ -516,6 +641,8 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
516
641
  });
517
642
  };
518
643
 
644
+ formReset(options.xInputRef, state.value(), (next: Color) => state.setValue(next));
645
+
519
646
  const inputFor = (axisName: "x" | "y"): DOMProps => {
520
647
  const channel = axisName === "x" ? state.xChannel : state.yChannel;
521
648
  const read = axisName === "x" ? state.xValue : state.yValue;
@@ -530,7 +657,9 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
530
657
  step: () => range().step,
531
658
  value: read,
532
659
  disabled: state.isDisabled,
533
- "aria-label": () => state.value().getChannelName(channel()),
660
+ name: () => access(axisName === "x" ? options.xName : options.yName),
661
+ form: () => access(options.form),
662
+ "aria-label": () => state.value().getChannelName(channel(), locale().locale),
534
663
  "aria-orientation": axisName === "x" ? "horizontal" : "vertical",
535
664
  // Both axes, on both inputs: a screen reader user moving one has to hear
536
665
  // what the other is, or the colour is half a description.
@@ -553,20 +682,45 @@ export function colorArea(options: ColorAreaOptions, state: ColorAreaState): Col
553
682
  colorAreaProps: mergeProps(moveProps, {
554
683
  // The arrows belong to the thumb, not to the reading cursor.
555
684
  role: "application",
556
- "aria-label": () => access(options["aria-label"]) ?? "Color area",
685
+ "aria-label": () => access(options["aria-label"]) ?? message(strings, "colorPicker"),
557
686
  "aria-labelledby": () => access(options["aria-labelledby"]),
558
- "aria-roledescription": "2D slider",
687
+ "aria-roledescription": () => message(strings, "twoDimensionalSlider"),
559
688
  "aria-disabled": () => state.isDisabled() || undefined,
560
689
  onPointerDown: (event: PointerEvent) => {
561
690
  if (event.button !== 0) return;
562
691
  onDown(event.clientX, event.clientY);
563
692
  },
693
+ onKeyDown: (event: KeyboardEvent) => {
694
+ // Page Up and Down page Y; Home and End page X, towards the start and
695
+ // the end of the line as the text runs.
696
+ const toEnd = (by: number): void =>
697
+ isMirrored() ? state.decrementX(by) : state.incrementX(by);
698
+ const toStart = (by: number): void =>
699
+ isMirrored() ? state.incrementX(by) : state.decrementX(by);
700
+ switch (event.key) {
701
+ case "PageUp":
702
+ byKeyboard("y", () => state.incrementY(pageOf(state.yChannel())));
703
+ break;
704
+ case "PageDown":
705
+ byKeyboard("y", () => state.decrementY(pageOf(state.yChannel())));
706
+ break;
707
+ case "Home":
708
+ byKeyboard("x", () => toStart(pageOf(state.xChannel())));
709
+ break;
710
+ case "End":
711
+ byKeyboard("x", () => toEnd(pageOf(state.xChannel())));
712
+ break;
713
+ default:
714
+ return;
715
+ }
716
+ event.preventDefault();
717
+ },
564
718
  style: { position: "relative", "touch-action": "none" },
565
719
  }),
566
720
  thumbProps: {
567
721
  style: () => ({
568
722
  position: "absolute",
569
- left: `${state.xPercent() * 100}%`,
723
+ left: `${(isMirrored() ? 1 - state.xPercent() : state.xPercent()) * 100}%`,
570
724
  top: `${(1 - state.yPercent()) * 100}%`,
571
725
  transform: "translate(-50%, -50%)",
572
726
  "touch-action": "none",
@@ -652,6 +806,7 @@ export function colorWheelState(options: ColorWheelStateOptions = {}): ColorWhee
652
806
  // What the LAST write produced, so a drag reads its own change back rather
653
807
  // than the value a controlled owner has not caught up with yet.
654
808
  let live = value();
809
+ let isDragging = false;
655
810
 
656
811
  const setValue = (next: Color): void => {
657
812
  live = next;
@@ -687,7 +842,8 @@ export function colorWheelState(options: ColorWheelStateOptions = {}): ColorWhee
687
842
  isDragging: dragging,
688
843
  isDisabled,
689
844
  setDragging: (next) => {
690
- const was = dragging();
845
+ const was = isDragging;
846
+ isDragging = next;
691
847
  writeDragging(next);
692
848
  if (was && !next) options.onChangeEnd?.(live);
693
849
  },
@@ -748,6 +904,9 @@ export interface ColorWheelResult {
748
904
  */
749
905
  export function colorWheel(options: ColorWheelOptions, state: ColorWheelState): ColorWheelResult {
750
906
  const inputId = id();
907
+ const locale = useLocale();
908
+ const words = channelWords();
909
+ const listeners = globalListeners();
751
910
  const thumbRadius = (): number => (access(options.innerRadius) + access(options.outerRadius)) / 2;
752
911
 
753
912
  const focusInput = (): void => {
@@ -828,6 +987,13 @@ export function colorWheel(options: ColorWheelOptions, state: ColorWheelState):
828
987
  state.setHueFromPoint(x, y, radius);
829
988
  focusInput();
830
989
  state.setDragging(true);
990
+ if (isServer) return;
991
+ // A press that never moves is still a change, and the release ends it.
992
+ listeners.add(track.ownerDocument.defaultView ?? window, "pointerup", () => {
993
+ onTrack = false;
994
+ state.setDragging(false);
995
+ listeners.removeAll();
996
+ });
831
997
  };
832
998
 
833
999
  return {
@@ -864,10 +1030,11 @@ export function colorWheel(options: ColorWheelOptions, state: ColorWheelState):
864
1030
  disabled: state.isDisabled,
865
1031
  name: () => access(options.name),
866
1032
  form: () => access(options.form),
867
- "aria-label": () => access(options["aria-label"]) ?? "Hue",
1033
+ "aria-label": () =>
1034
+ access(options["aria-label"]) ?? state.value().getChannelName("hue", locale().locale),
868
1035
  "aria-labelledby": () => access(options["aria-labelledby"]),
869
1036
  // The number MEANS something: "212" is not a colour, "Hue 212" is.
870
- "aria-valuetext": () => `Hue ${Math.round(state.hue())}`,
1037
+ "aria-valuetext": () => words(state.value(), "hue"),
871
1038
  style: HIDDEN_INPUT_STYLE,
872
1039
  onInput: (event: Event) => {
873
1040
  state.setHue(Number.parseFloat((event.target as HTMLInputElement).value));
@@ -898,9 +1065,12 @@ export interface ColorFieldOptions extends Omit<
898
1065
  * What the page thinks of the COLOUR, checked as it is committed.
899
1066
  *
900
1067
  * The colour rather than the typed text: "#ff" is a prefix, not a colour,
901
- * and a validator handed one has nothing to say about it.
1068
+ * and a validator handed one has nothing to say about it. An empty field has
1069
+ * no colour, and is not handed over.
902
1070
  */
903
1071
  validate?: ValidateFunction<Color>;
1072
+ /** Stop the scroll wheel stepping the colour. @default false */
1073
+ isWheelDisabled?: MaybeAccessor<boolean | undefined>;
904
1074
  }
905
1075
 
906
1076
  export interface ColorFieldResult {
@@ -914,51 +1084,91 @@ export interface ColorFieldResult {
914
1084
  isInvalid: Accessor<boolean>;
915
1085
  }
916
1086
 
1087
+ const BLACK = 0x000000;
1088
+ const WHITE = 0xffffff;
1089
+
1090
+ function fromHexInt(value: number): Color {
1091
+ return parseColor(`#${value.toString(16).padStart(6, "0")}`);
1092
+ }
1093
+
1094
+ /** What was typed, as a colour, or null. Hex may be typed without its `#`. */
1095
+ function readColor(text: string): Color | null {
1096
+ const trimmed = text.trim();
1097
+ for (const candidate of [trimmed, `#${trimmed}`]) {
1098
+ try {
1099
+ return parseColor(candidate);
1100
+ } catch {
1101
+ // Not this reading; the next, or none.
1102
+ }
1103
+ }
1104
+ return null;
1105
+ }
1106
+
917
1107
  /**
918
1108
  * A colour as text.
919
1109
  *
920
1110
  * Committed on blur and on Enter, never as you type: "#ff" is not a colour,
921
1111
  * and a field that reported one on every keystroke would flash the page
922
- * through every prefix of what was typed.
1112
+ * through every prefix of what was typed. The arrows, Page Up and Down, and the
1113
+ * wheel step it through the 24-bit colours one at a time; Home and End go to
1114
+ * black and to white. Emptied and committed, it holds no colour at all.
923
1115
  */
924
1116
  export function colorField(
925
1117
  options: ColorFieldOptions,
926
- state: { value: Accessor<Color>; setValue(value: Color): void; isDisabled: Accessor<boolean> },
1118
+ state: {
1119
+ value: Accessor<Color | null>;
1120
+ setValue(value: Color | null): void;
1121
+ isDisabled: Accessor<boolean>;
1122
+ },
927
1123
  ref: ElementRef<HTMLInputElement>,
928
1124
  ): ColorFieldResult {
929
1125
  const format = (): ColorFormat => access(options.format) ?? "hex";
930
- const [text, writeText] = createSignal(state.value().toString(format()));
1126
+ const show = (color: Color | null): string => color?.toString(format()) ?? "";
1127
+ // Bumped on every commit, so the text is re-seeded from the colour even when
1128
+ // the colour did not move: a controlled field refusing the edit, or text
1129
+ // that was not a colour, both go back to what the field holds.
1130
+ const [commits, setCommits] = createSignal(0);
1131
+ const [text, writeText] = createSignal(() => {
1132
+ commits();
1133
+ return show(state.value());
1134
+ });
931
1135
 
932
- let live = state.value().toString(format());
933
- // What the field SHOWS. Enter commits in the same tick as the keystroke that
934
- // produced the text, and a signal write is not published until the flush, so
935
- // `text()` would hand the parser the value the typing replaced.
936
- let typed = live;
1136
+ // What was typed since the last commit. Enter commits in the same tick as
1137
+ // the keystroke that produced the text, and a signal write is not published
1138
+ // until the flush, so `text()` would hand the parser the value the typing
1139
+ // replaced.
1140
+ let typed: string | null = null;
937
1141
  const setText = (next: string): void => {
938
1142
  typed = next;
939
1143
  writeText(next);
940
1144
  };
941
-
942
- const sync = (): void => {
943
- const formatted = state.value().toString(format());
944
- if (formatted === live) return;
945
- live = formatted;
946
- setText(formatted);
1145
+ const current = (): string => typed ?? text();
1146
+
1147
+ const put = (next: Color | null): void => {
1148
+ typed = null;
1149
+ setCommits((count) => count + 1);
1150
+ const held = state.value();
1151
+ const same = next === null ? held === null : held !== null && next.isEqual(held);
1152
+ if (!same) state.setValue(next);
947
1153
  };
948
1154
 
949
1155
  const commit = (): void => {
950
- try {
951
- const parsed = parseColor(typed);
952
- live = parsed.toString(format());
953
- setText(live);
954
- state.setValue(parsed);
955
- } catch {
956
- // Not a colour: the field goes back to what it holds rather than
957
- // keeping text that means nothing.
958
- setText(state.value().toString(format()));
1156
+ const entered = current();
1157
+ if (entered.trim() === "") {
1158
+ put(null);
1159
+ return;
959
1160
  }
1161
+ put(readColor(entered) ?? state.value());
960
1162
  };
961
1163
 
1164
+ const stepTo = (target: (from: number) => number): void => {
1165
+ const from = (readColor(current()) ?? fromHexInt(BLACK)).toHexInt();
1166
+ put(fromHexInt(Math.min(Math.max(target(from), BLACK), WHITE)));
1167
+ validation.commitValidation();
1168
+ };
1169
+
1170
+ const isReadOnly = (): boolean => access(options.isReadOnly) === true;
1171
+
962
1172
  const {
963
1173
  labelProps,
964
1174
  inputProps,
@@ -971,22 +1181,52 @@ export function colorField(
971
1181
  {
972
1182
  ...options,
973
1183
  type: "text",
974
- value: () => {
975
- sync();
976
- return text();
977
- },
1184
+ value: text,
978
1185
  // The caller validates the COLOUR; `textField` validates a string, so
979
1186
  // the typed text is ignored and the committed value is handed over.
980
1187
  validate:
981
1188
  options.validate === undefined
982
1189
  ? undefined
983
- : () => (options.validate as ValidateFunction<Color>)(state.value()),
1190
+ : () => {
1191
+ const held = state.value();
1192
+ return held === null ? null : (options.validate as ValidateFunction<Color>)(held);
1193
+ },
984
1194
  onChange: setText,
985
1195
  autoComplete: "off",
986
1196
  },
987
1197
  ref,
988
1198
  );
989
1199
 
1200
+ const { spinButtonProps } = spinButton({
1201
+ isDisabled: state.isDisabled,
1202
+ isReadOnly,
1203
+ minValue: BLACK,
1204
+ maxValue: WHITE,
1205
+ value: () => state.value()?.toHexInt(),
1206
+ textValue: () => state.value()?.toString("hex"),
1207
+ onIncrement: () => stepTo((from) => from + 1),
1208
+ onDecrement: () => stepTo((from) => from - 1),
1209
+ onIncrementToMax: () => stepTo(() => WHITE),
1210
+ onDecrementToMin: () => stepTo(() => BLACK),
1211
+ });
1212
+
1213
+ const { focusWithinProps, isFocusWithin } = focusWithin({ isDisabled: state.isDisabled });
1214
+
1215
+ scrollWheel({
1216
+ ref,
1217
+ isDisabled: () =>
1218
+ access(options.isWheelDisabled) === true ||
1219
+ state.isDisabled() ||
1220
+ isReadOnly() ||
1221
+ !isFocusWithin(),
1222
+ onScroll: (delta) => {
1223
+ // Mostly sideways is a trackpad scrolling the page, not this field.
1224
+ if (Math.abs(delta.deltaY) <= Math.abs(delta.deltaX)) return;
1225
+ if (delta.deltaY > 0) stepTo((from) => from + 1);
1226
+ else stepTo((from) => from - 1);
1227
+ },
1228
+ });
1229
+
990
1230
  return {
991
1231
  labelProps,
992
1232
  descriptionProps,
@@ -994,7 +1234,7 @@ export function colorField(
994
1234
  validation,
995
1235
  errors,
996
1236
  isInvalid,
997
- inputProps: mergeProps(inputProps, {
1237
+ inputProps: mergeProps(inputProps, spinButtonProps, focusWithinProps, {
998
1238
  autocorrect: "off",
999
1239
  spellcheck: "false",
1000
1240
  onBlur: () => {
@@ -1027,12 +1267,23 @@ export function colorSwatch(options: ColorSwatchOptions): ColorSwatchResult {
1027
1267
  return typeof given === "string" ? parseColor(given) : given;
1028
1268
  });
1029
1269
 
1270
+ const locale = useLocale();
1271
+ const strings = stringFormatter(PICKER_STRINGS);
1272
+ const degrees = numberFormatter({ style: "unit", unit: "degree", unitDisplay: "long" });
1273
+ const percent = numberFormatter({ style: "percent" });
1274
+
1030
1275
  const description = (): string => {
1031
1276
  const current = color();
1277
+ if (current.alpha === 0) return message(strings, "transparent");
1032
1278
  const hsl = current.toFormat("hsl");
1033
- return `${Math.round(hsl.getChannelValue("hue"))} degrees, ${Math.round(
1034
- hsl.getChannelValue("saturation"),
1035
- )}% saturation, ${Math.round(hsl.getChannelValue("lightness"))}% lightness`;
1279
+ const share = (channel: ColorChannel): string =>
1280
+ percent().format(Math.round(hsl.getChannelValue(channel)) / 100);
1281
+ return message(strings, "colorSwatchDescription", {
1282
+ hue: degrees().format(Math.round(hsl.getChannelValue("hue"))),
1283
+ saturation: share("saturation"),
1284
+ lightness: share("lightness"),
1285
+ name: current.getColorName(locale().locale),
1286
+ });
1036
1287
  };
1037
1288
 
1038
1289
  return {
@@ -1040,6 +1291,7 @@ export function colorSwatch(options: ColorSwatchOptions): ColorSwatchResult {
1040
1291
  swatchProps: {
1041
1292
  // An image, not a button: it SHOWS a colour and does nothing.
1042
1293
  role: "img",
1294
+ "aria-roledescription": () => message(strings, "colorSwatch"),
1043
1295
  "aria-label": () => access(options["aria-label"]) ?? description(),
1044
1296
  style: () => ({ "background-color": color().toString("css") }),
1045
1297
  },
@@ -1083,11 +1335,11 @@ export interface ColorPickerComponentProps extends StyleProps {
1083
1335
  * </ColorPicker>
1084
1336
  * ```
1085
1337
  */
1086
- export function ColorPicker(props: Incoming<ColorPickerComponentProps>) {
1338
+ export function ColorPicker(props: ColorPickerComponentProps) {
1087
1339
  const [value, setValue] = controllable<Color>(
1088
- () => asColor(props.value?.()),
1089
- () => asColor(props.defaultValue?.()) ?? defaultColor(),
1090
- (next) => props.onChange?.()?.(next),
1340
+ () => asColor(props.value),
1341
+ () => asColor(props.defaultValue) ?? defaultColor(),
1342
+ (next) => props.onChange?.(next),
1091
1343
  );
1092
1344
 
1093
1345
  const owner = getOwner();
@@ -1095,15 +1347,15 @@ export function ColorPicker(props: Incoming<ColorPickerComponentProps>) {
1095
1347
  install(owner, ColorPickerContext, () => ({
1096
1348
  value,
1097
1349
  setValue,
1098
- isDisabled: () => props.isDisabled?.() === true,
1350
+ isDisabled: () => props.isDisabled === true,
1099
1351
  }));
1100
1352
  }
1101
1353
 
1102
1354
  const elementProps = mergeProps(
1103
- filterDOMProps(fromProps(props), { global: true }),
1104
- styleProps(props),
1355
+ filterDOMProps(fromProps(cells(props)), { global: true }),
1356
+ styleProps(cells(props)),
1105
1357
  {
1106
- "data-testid": () => props["data-testid"]?.(),
1358
+ "data-testid": () => props["data-testid"],
1107
1359
  },
1108
1360
  );
1109
1361
 
@@ -1118,6 +1370,9 @@ export interface ColorSliderComponentProps extends StyleProps {
1118
1370
  /** @default "horizontal" */
1119
1371
  orientation?: Orientation;
1120
1372
  isDisabled?: boolean;
1373
+ /** The form name the channel's value is submitted under. */
1374
+ name?: string;
1375
+ form?: string;
1121
1376
  "aria-label"?: string;
1122
1377
  ref?: RefTarget<HTMLDivElement>;
1123
1378
  onChange?: (value: Color) => void;
@@ -1125,62 +1380,70 @@ export interface ColorSliderComponentProps extends StyleProps {
1125
1380
  }
1126
1381
 
1127
1382
  /** One channel on a track: a hue, an alpha, a red. */
1128
- export function ColorSlider(props: Incoming<ColorSliderComponentProps>) {
1383
+ export function ColorSlider(props: ColorSliderComponentProps) {
1129
1384
  const trackRef = makeRef<HTMLDivElement>();
1130
1385
  const inputRef = makeRef<HTMLInputElement>();
1131
1386
  const picker = useColorPicker();
1387
+ const locale = useLocale();
1132
1388
 
1133
1389
  const state = colorSliderState({
1134
- channel: () => props.channel(),
1135
- orientation: () => props.orientation?.(),
1136
- value: () => props.value?.() ?? picker?.value(),
1137
- defaultValue: () => props.defaultValue?.(),
1138
- isDisabled: () => props.isDisabled?.() ?? picker?.isDisabled(),
1390
+ channel: () => props.channel,
1391
+ orientation: () => props.orientation,
1392
+ value: () => props.value ?? picker?.value(),
1393
+ defaultValue: () => props.defaultValue,
1394
+ isDisabled: () => props.isDisabled ?? picker?.isDisabled(),
1139
1395
  onChange: (value) => {
1140
1396
  picker?.setValue(value);
1141
- props.onChange?.()?.(value);
1397
+ props.onChange?.(value);
1142
1398
  },
1143
- onChangeEnd: (value) => props.onChangeEnd?.()?.(value),
1399
+ onChangeEnd: (value) => props.onChangeEnd?.(value),
1144
1400
  });
1145
1401
 
1146
1402
  const { labelProps, trackProps, thumbProps, inputProps, outputProps } = colorSlider(
1147
1403
  {
1148
1404
  trackRef,
1149
1405
  inputRef,
1150
- label: () => props.label?.(),
1406
+ label: () => props.label,
1407
+ name: () => props.name,
1408
+ form: () => props.form,
1151
1409
  "aria-label": () =>
1152
- props["aria-label"]?.() ??
1153
- (props.label?.() === undefined ? state.value().getChannelName(props.channel()) : undefined),
1410
+ props["aria-label"] ??
1411
+ (props.label === undefined
1412
+ ? state.value().getChannelName(props.channel, locale().locale)
1413
+ : undefined),
1154
1414
  },
1155
1415
  state,
1156
1416
  );
1157
1417
 
1158
1418
  const { visuallyHiddenProps } = visuallyHidden();
1159
- const { focusProps, isFocusVisible } = focusRing();
1419
+ const { focusProps, isFocused, isFocusVisible } = focusRing();
1160
1420
  const { hoverProps, isHovered } = hover({ isDisabled: state.isDisabled });
1161
1421
 
1162
1422
  const elementProps = mergeProps(
1163
1423
  trackProps,
1164
1424
  hoverProps,
1165
- filterDOMProps(fromProps(props), { global: true }),
1166
- styleProps(props),
1425
+ filterDOMProps(fromProps(cells(props)), { global: true }),
1426
+ styleProps(cells(props)),
1167
1427
  {
1168
1428
  "data-orientation": state.orientation,
1169
1429
  "data-dragging": state.isDragging,
1170
1430
  "data-disabled": state.isDisabled,
1171
- "data-testid": () => props["data-testid"]?.(),
1431
+ "data-testid": () => props["data-testid"],
1172
1432
  },
1173
1433
  );
1174
1434
 
1175
1435
  return (
1176
1436
  <>
1177
- {() => (props.label?.() === undefined ? null : <label {...labelProps}>{props.label}</label>)}
1437
+ {() => (props.label === undefined ? null : <label {...labelProps}>{props.label}</label>)}
1178
1438
  <output {...outputProps}>{() => state.valueText()}</output>
1179
- <div {...elementProps} ref={mergeRefs(trackRef.set, props.ref?.())}>
1439
+ <div {...elementProps} ref={mergeRefs(trackRef.set, props.ref)}>
1180
1440
  <div
1181
1441
  {...mergeProps(thumbProps, {
1442
+ "data-focused": isFocused,
1182
1443
  "data-focus-visible": isFocusVisible,
1183
1444
  "data-hovered": isHovered,
1445
+ "data-dragging": state.isDragging,
1446
+ "data-disabled": state.isDisabled,
1184
1447
  })}
1185
1448
  >
1186
1449
  <input
@@ -1199,6 +1462,10 @@ export interface ColorAreaComponentProps extends StyleProps {
1199
1462
  xChannel?: ColorChannel;
1200
1463
  yChannel?: ColorChannel;
1201
1464
  isDisabled?: boolean;
1465
+ /** The form names the two channels are submitted under. */
1466
+ xName?: string;
1467
+ yName?: string;
1468
+ form?: string;
1202
1469
  "aria-label"?: string;
1203
1470
  ref?: RefTarget<HTMLDivElement>;
1204
1471
  onChange?: (value: Color) => void;
@@ -1206,23 +1473,23 @@ export interface ColorAreaComponentProps extends StyleProps {
1206
1473
  }
1207
1474
 
1208
1475
  /** Two channels in a square: saturation across, brightness up. */
1209
- export function ColorArea(props: Incoming<ColorAreaComponentProps>) {
1476
+ export function ColorArea(props: ColorAreaComponentProps) {
1210
1477
  const containerRef = makeRef<HTMLDivElement>();
1211
1478
  const xInputRef = makeRef<HTMLInputElement>();
1212
1479
  const yInputRef = makeRef<HTMLInputElement>();
1213
1480
  const picker = useColorPicker();
1214
1481
 
1215
1482
  const state = colorAreaState({
1216
- value: () => props.value?.() ?? picker?.value(),
1217
- defaultValue: () => props.defaultValue?.(),
1218
- xChannel: () => props.xChannel?.(),
1219
- yChannel: () => props.yChannel?.(),
1220
- isDisabled: () => props.isDisabled?.() ?? picker?.isDisabled(),
1483
+ value: () => props.value ?? picker?.value(),
1484
+ defaultValue: () => props.defaultValue,
1485
+ xChannel: () => props.xChannel,
1486
+ yChannel: () => props.yChannel,
1487
+ isDisabled: () => props.isDisabled ?? picker?.isDisabled(),
1221
1488
  onChange: (value) => {
1222
1489
  picker?.setValue(value);
1223
- props.onChange?.()?.(value);
1490
+ props.onChange?.(value);
1224
1491
  },
1225
- onChangeEnd: (value) => props.onChangeEnd?.()?.(value),
1492
+ onChangeEnd: (value) => props.onChangeEnd?.(value),
1226
1493
  });
1227
1494
 
1228
1495
  const { colorAreaProps, thumbProps, xInputProps, yInputProps } = colorArea(
@@ -1230,34 +1497,45 @@ export function ColorArea(props: Incoming<ColorAreaComponentProps>) {
1230
1497
  containerRef,
1231
1498
  xInputRef,
1232
1499
  yInputRef,
1233
- "aria-label": () => props["aria-label"]?.(),
1500
+ xName: () => props.xName,
1501
+ yName: () => props.yName,
1502
+ form: () => props.form,
1503
+ "aria-label": () => props["aria-label"],
1234
1504
  },
1235
1505
  state,
1236
1506
  );
1237
1507
 
1238
1508
  const { visuallyHiddenProps } = visuallyHidden();
1239
- const { focusProps, isFocusVisible } = focusRing();
1509
+ // One ring for both inputs: the thumb is one thing, whichever axis has focus.
1510
+ const { focusProps, isFocused, isFocusVisible } = focusRing();
1240
1511
 
1241
1512
  const elementProps = mergeProps(
1242
1513
  colorAreaProps,
1243
- filterDOMProps(fromProps(props), { global: true }),
1244
- styleProps(props),
1514
+ filterDOMProps(fromProps(cells(props)), { global: true }),
1515
+ styleProps(cells(props)),
1245
1516
  {
1246
1517
  "data-dragging": state.isDragging,
1247
1518
  "data-disabled": state.isDisabled,
1248
- "data-testid": () => props["data-testid"]?.(),
1519
+ "data-testid": () => props["data-testid"],
1249
1520
  },
1250
1521
  );
1251
1522
 
1252
1523
  return (
1253
- <div {...elementProps} ref={mergeRefs(containerRef.set, props.ref?.())}>
1254
- <div {...mergeProps(thumbProps, { "data-focus-visible": isFocusVisible })}>
1524
+ <div {...elementProps} ref={mergeRefs(containerRef.set, props.ref)}>
1525
+ <div
1526
+ {...mergeProps(thumbProps, {
1527
+ "data-focused": isFocused,
1528
+ "data-focus-visible": isFocusVisible,
1529
+ "data-dragging": state.isDragging,
1530
+ "data-disabled": state.isDisabled,
1531
+ })}
1532
+ >
1255
1533
  <input
1256
1534
  {...mergeProps(xInputProps, focusProps, { style: visuallyHiddenProps.style })}
1257
1535
  ref={xInputRef.set}
1258
1536
  />
1259
1537
  <input
1260
- {...mergeProps(yInputProps, { style: visuallyHiddenProps.style })}
1538
+ {...mergeProps(yInputProps, focusProps, { style: visuallyHiddenProps.style })}
1261
1539
  ref={yInputRef.set}
1262
1540
  />
1263
1541
  </div>
@@ -1291,24 +1569,24 @@ export interface ColorWheelComponentProps extends StyleProps {
1291
1569
  * the caller's to style; what is here is the geometry, the keyboard and the
1292
1570
  * hidden `<input type="range">` a screen reader announces.
1293
1571
  */
1294
- export function ColorWheel(props: Incoming<ColorWheelComponentProps>) {
1572
+ export function ColorWheel(props: ColorWheelComponentProps) {
1295
1573
  const trackRef = makeRef<HTMLDivElement>();
1296
1574
  const inputRef = makeRef<HTMLInputElement>();
1297
1575
  const picker = useColorPicker();
1298
1576
 
1299
1577
  const state = colorWheelState({
1300
- value: () => props.value?.() ?? picker?.value(),
1301
- defaultValue: () => props.defaultValue?.(),
1302
- isDisabled: () => props.isDisabled?.() ?? picker?.isDisabled(),
1578
+ value: () => props.value ?? picker?.value(),
1579
+ defaultValue: () => props.defaultValue,
1580
+ isDisabled: () => props.isDisabled ?? picker?.isDisabled(),
1303
1581
  onChange: (value) => {
1304
1582
  picker?.setValue(value);
1305
- props.onChange?.()?.(value);
1583
+ props.onChange?.(value);
1306
1584
  },
1307
- onChangeEnd: (value) => props.onChangeEnd?.()?.(value),
1585
+ onChangeEnd: (value) => props.onChangeEnd?.(value),
1308
1586
  });
1309
1587
 
1310
- const outerRadius = (): number => props.outerRadius?.() ?? 80;
1311
- const innerRadius = (): number => props.innerRadius?.() ?? 64;
1588
+ const outerRadius = (): number => props.outerRadius ?? 80;
1589
+ const innerRadius = (): number => props.innerRadius ?? 64;
1312
1590
 
1313
1591
  const { trackProps, thumbProps, inputProps } = colorWheel(
1314
1592
  {
@@ -1316,26 +1594,26 @@ export function ColorWheel(props: Incoming<ColorWheelComponentProps>) {
1316
1594
  inputRef,
1317
1595
  innerRadius,
1318
1596
  outerRadius,
1319
- name: () => props.name?.(),
1320
- form: () => props.form?.(),
1321
- "aria-label": () => props["aria-label"]?.(),
1322
- "aria-labelledby": () => props["aria-labelledby"]?.(),
1597
+ name: () => props.name,
1598
+ form: () => props.form,
1599
+ "aria-label": () => props["aria-label"],
1600
+ "aria-labelledby": () => props["aria-labelledby"],
1323
1601
  },
1324
1602
  state,
1325
1603
  );
1326
1604
 
1327
- const { focusProps, isFocusVisible } = focusRing();
1605
+ const { focusProps, isFocused, isFocusVisible } = focusRing();
1328
1606
  const { hoverProps, isHovered } = hover({ isDisabled: state.isDisabled });
1329
1607
 
1330
1608
  const elementProps = mergeProps(
1331
1609
  trackProps,
1332
1610
  hoverProps,
1333
- filterDOMProps(fromProps(props), { global: true }),
1334
- styleProps(props),
1611
+ filterDOMProps(fromProps(cells(props)), { global: true }),
1612
+ styleProps(cells(props)),
1335
1613
  {
1336
1614
  "data-dragging": state.isDragging,
1337
1615
  "data-disabled": state.isDisabled,
1338
- "data-testid": () => props["data-testid"]?.(),
1616
+ "data-testid": () => props["data-testid"],
1339
1617
  style: () => ({
1340
1618
  position: "relative",
1341
1619
  "touch-action": "none",
@@ -1346,11 +1624,14 @@ export function ColorWheel(props: Incoming<ColorWheelComponentProps>) {
1346
1624
  );
1347
1625
 
1348
1626
  return (
1349
- <div {...elementProps} ref={mergeRefs(trackRef.set, props.ref?.())}>
1627
+ <div {...elementProps} ref={mergeRefs(trackRef.set, props.ref)}>
1350
1628
  <div
1351
1629
  {...mergeProps(thumbProps, {
1630
+ "data-focused": isFocused,
1352
1631
  "data-focus-visible": isFocusVisible,
1353
1632
  "data-hovered": isHovered,
1633
+ "data-dragging": state.isDragging,
1634
+ "data-disabled": state.isDisabled,
1354
1635
  })}
1355
1636
  >
1356
1637
  <input {...mergeProps(inputProps, focusProps)} ref={inputRef.set} />
@@ -1363,8 +1644,9 @@ export interface ColorFieldComponentProps extends StyleProps {
1363
1644
  label?: Child;
1364
1645
  description?: Child;
1365
1646
  errorMessage?: Child;
1366
- value?: Color | string;
1367
- defaultValue?: Color | string;
1647
+ /** Null is an empty field: no colour at all. */
1648
+ value?: Color | string | null;
1649
+ defaultValue?: Color | string | null;
1368
1650
  /** @default "hex" */
1369
1651
  format?: ColorFormat;
1370
1652
  isDisabled?: boolean;
@@ -1375,47 +1657,55 @@ export interface ColorFieldComponentProps extends StyleProps {
1375
1657
  validate?: ValidateFunction<Color>;
1376
1658
  /** @default "aria" */
1377
1659
  validationBehavior?: ValidationBehavior;
1660
+ /** Stop the scroll wheel stepping the colour. @default false */
1661
+ isWheelDisabled?: boolean;
1378
1662
  name?: string;
1379
1663
  "aria-label"?: string;
1380
1664
  ref?: RefTarget<HTMLInputElement>;
1381
- onChange?: (value: Color) => void;
1665
+ /** Called with null when the field is emptied. */
1666
+ onChange?: (value: Color | null) => void;
1382
1667
  }
1383
1668
 
1384
1669
  /** A colour as text: `#7f00ff`, committed on blur and on Enter. */
1385
- export function ColorField(props: Incoming<ColorFieldComponentProps>) {
1670
+ export function ColorField(props: ColorFieldComponentProps) {
1386
1671
  const domRef = makeRef<HTMLInputElement>();
1387
1672
  const picker = useColorPicker();
1388
1673
 
1389
- const [value, setValue] = controllable<Color>(
1390
- () => asColor(props.value?.()) ?? picker?.value(),
1391
- () => asColor(props.defaultValue?.()) ?? defaultColor(),
1674
+ const [value, setValue] = controllable<Color | null>(
1675
+ () => (props.value === null ? null : (asColor(props.value) ?? picker?.value())),
1676
+ () => asColor(props.defaultValue) ?? null,
1392
1677
  (next) => {
1393
- picker?.setValue(next);
1394
- props.onChange?.()?.(next);
1678
+ // A picker always holds a colour, so emptying a field inside one leaves
1679
+ // the picker's colour where it was and the field goes back to it.
1680
+ if (next !== null) picker?.setValue(next);
1681
+ props.onChange?.(next);
1395
1682
  },
1396
1683
  );
1397
1684
 
1398
1685
  const state = {
1399
1686
  value,
1400
1687
  setValue,
1401
- isDisabled: (): boolean => props.isDisabled?.() ?? picker?.isDisabled() ?? false,
1688
+ isDisabled: (): boolean => props.isDisabled ?? picker?.isDisabled() ?? false,
1402
1689
  };
1403
1690
 
1404
1691
  const { labelProps, inputProps, descriptionProps, errorMessageProps, errors, isInvalid } =
1405
1692
  colorField(
1406
1693
  {
1407
- label: () => props.label?.(),
1408
- description: () => props.description?.(),
1409
- errorMessage: () => props.errorMessage?.(),
1410
- format: () => props.format?.(),
1694
+ label: () => props.label,
1695
+ description: () => props.description,
1696
+ errorMessage: () => props.errorMessage,
1697
+ format: () => props.format,
1411
1698
  isDisabled: state.isDisabled,
1412
- isReadOnly: () => props.isReadOnly?.(),
1413
- isRequired: () => props.isRequired?.(),
1414
- isInvalid: () => props.isInvalid?.(),
1415
- validate: callback<[Color], string | string[] | true | null | undefined>(props.validate),
1416
- validationBehavior: () => props.validationBehavior?.(),
1417
- name: () => props.name?.(),
1418
- "aria-label": () => props["aria-label"]?.(),
1699
+ isReadOnly: () => props.isReadOnly,
1700
+ isRequired: () => props.isRequired,
1701
+ isInvalid: () => props.isInvalid,
1702
+ validate: callback<[Color], string | string[] | true | null | undefined>(
1703
+ cells(props).validate,
1704
+ ),
1705
+ validationBehavior: () => props.validationBehavior,
1706
+ isWheelDisabled: () => props.isWheelDisabled,
1707
+ name: () => props.name,
1708
+ "aria-label": () => props["aria-label"],
1419
1709
  },
1420
1710
  state,
1421
1711
  domRef,
@@ -1426,23 +1716,23 @@ export function ColorField(props: Incoming<ColorFieldComponentProps>) {
1426
1716
  const elementProps = mergeProps(
1427
1717
  inputProps,
1428
1718
  focusProps,
1429
- filterDOMProps(fromProps(props), { global: true }),
1430
- styleProps(props),
1719
+ filterDOMProps(fromProps(cells(props)), { global: true }),
1720
+ styleProps(cells(props)),
1431
1721
  {
1432
1722
  "data-focus-visible": isFocusVisible,
1433
1723
  "data-invalid": isInvalid,
1434
- "data-testid": () => props["data-testid"]?.(),
1724
+ "data-testid": () => props["data-testid"],
1435
1725
  },
1436
1726
  );
1437
1727
 
1438
1728
  return (
1439
1729
  <>
1440
1730
  <label {...labelProps}>{props.label}</label>
1441
- <input {...elementProps} ref={mergeRefs(domRef.set, props.ref?.())} />
1731
+ <input {...elementProps} ref={mergeRefs(domRef.set, props.ref)} />
1442
1732
  <span {...descriptionProps}>{props.description}</span>
1443
1733
  <span {...errorMessageProps}>
1444
1734
  {() => {
1445
- const given = props.errorMessage?.();
1735
+ const given = props.errorMessage;
1446
1736
  if (given !== undefined && given !== null && given !== "") return given;
1447
1737
  const found = errors();
1448
1738
  return found.length === 0 ? null : found.join(" ");
@@ -1459,20 +1749,275 @@ export interface ColorSwatchComponentProps extends StyleProps {
1459
1749
  }
1460
1750
 
1461
1751
  /** A square showing a colour, named with what it is. */
1462
- export function ColorSwatch(props: Incoming<ColorSwatchComponentProps>) {
1752
+ export function ColorSwatch(props: ColorSwatchComponentProps) {
1463
1753
  const picker = useColorPicker();
1754
+ const item = useColorSwatchPickerItem();
1464
1755
 
1465
1756
  const { swatchProps } = colorSwatch({
1466
- color: () => props.color?.() ?? picker?.value() ?? defaultColor(),
1467
- "aria-label": () => props["aria-label"]?.(),
1757
+ color: () => props.color ?? item?.() ?? picker?.value() ?? defaultColor(),
1758
+ "aria-label": () => props["aria-label"],
1468
1759
  });
1469
1760
 
1470
1761
  const elementProps = mergeProps(swatchProps, {
1471
- class: () => props.class?.() ?? props.className?.(),
1472
- "data-testid": () => props["data-testid"]?.(),
1762
+ class: () => props.class ?? props.className,
1763
+ "data-testid": () => props["data-testid"],
1473
1764
  });
1474
1765
 
1475
- return <div {...elementProps} ref={mergeRefs(props.ref?.())} />;
1766
+ return <div {...elementProps} ref={mergeRefs(props.ref)} />;
1476
1767
  }
1477
1768
 
1478
1769
  export { parseColor, type Color, type ColorChannel, type ColorFormat, type ColorSpace };
1770
+
1771
+ // ---------------------------------------------------------------------------
1772
+ // Strings
1773
+ // ---------------------------------------------------------------------------
1774
+
1775
+ type PickerStringKey =
1776
+ | "colorPicker"
1777
+ | "twoDimensionalSlider"
1778
+ | "colorSwatch"
1779
+ | "transparent"
1780
+ | "colorSwatchDescription";
1781
+
1782
+ // English describes a swatch by its numbers. No other locale has a translation
1783
+ // of that, so every other one names the colour, in its own words.
1784
+ const PICKER_STRINGS = new StringDictionary<PickerStringKey>({
1785
+ "ar-AE": {
1786
+ colorPicker: "أداة انتقاء اللون",
1787
+ twoDimensionalSlider: "مُنزلق 2D",
1788
+ colorSwatch: "تغيير الألوان",
1789
+ transparent: "شفاف",
1790
+ colorSwatchDescription: "{name}",
1791
+ },
1792
+ "bg-BG": {
1793
+ colorPicker: "Средство за избиране на цвят",
1794
+ twoDimensionalSlider: "2D плъзгач",
1795
+ colorSwatch: "цветна мостра",
1796
+ transparent: "прозрачен",
1797
+ colorSwatchDescription: "{name}",
1798
+ },
1799
+ "cs-CZ": {
1800
+ colorPicker: "Výběr barvy",
1801
+ twoDimensionalSlider: "2D posuvník",
1802
+ colorSwatch: "barevný vzorek",
1803
+ transparent: "průhledný",
1804
+ colorSwatchDescription: "{name}",
1805
+ },
1806
+ "da-DK": {
1807
+ colorPicker: "Farvevælger",
1808
+ twoDimensionalSlider: "2D-skyder",
1809
+ colorSwatch: "farveprøve",
1810
+ transparent: "gennemsigtig",
1811
+ colorSwatchDescription: "{name}",
1812
+ },
1813
+ "de-DE": {
1814
+ colorPicker: "Farbwähler",
1815
+ twoDimensionalSlider: "2D-Schieberegler",
1816
+ colorSwatch: "Farbfeld",
1817
+ transparent: "transparent",
1818
+ colorSwatchDescription: "{name}",
1819
+ },
1820
+ "el-GR": {
1821
+ colorPicker: "Επιλογέας χρωμάτων",
1822
+ twoDimensionalSlider: "Ρυθμιστικό 2D",
1823
+ colorSwatch: "χρωματικό δείγμα",
1824
+ transparent: "διαφανές",
1825
+ colorSwatchDescription: "{name}",
1826
+ },
1827
+ "en-US": {
1828
+ colorPicker: "Color picker",
1829
+ twoDimensionalSlider: "2D slider",
1830
+ colorSwatch: "color swatch",
1831
+ transparent: "transparent",
1832
+ colorSwatchDescription: "{hue}, {saturation} saturation, {lightness} lightness",
1833
+ },
1834
+ "es-ES": {
1835
+ colorPicker: "Selector de color",
1836
+ twoDimensionalSlider: "Regulador 2D",
1837
+ colorSwatch: "muestra de color",
1838
+ transparent: "transparente",
1839
+ colorSwatchDescription: "{name}",
1840
+ },
1841
+ "et-EE": {
1842
+ colorPicker: "Värvivalija",
1843
+ twoDimensionalSlider: "2D-liugur",
1844
+ colorSwatch: "värvinäidis",
1845
+ transparent: "läbipaistev",
1846
+ colorSwatchDescription: "{name}",
1847
+ },
1848
+ "fi-FI": {
1849
+ colorPicker: "Värimuokkain",
1850
+ twoDimensionalSlider: "2D-liukusäädin",
1851
+ colorSwatch: "värimalli",
1852
+ transparent: "läpinäkyvä",
1853
+ colorSwatchDescription: "{name}",
1854
+ },
1855
+ "fr-FR": {
1856
+ colorPicker: "Sélecteur de couleurs",
1857
+ twoDimensionalSlider: "Curseur 2D",
1858
+ colorSwatch: "Échantillon de couleurs",
1859
+ transparent: "Transparent",
1860
+ colorSwatchDescription: "{name}",
1861
+ },
1862
+ "he-IL": {
1863
+ colorPicker: "בוחר הצבעים",
1864
+ twoDimensionalSlider: "מחוון דו מימדי",
1865
+ colorSwatch: "דוגמית צבע",
1866
+ transparent: "שקוף",
1867
+ colorSwatchDescription: "{name}",
1868
+ },
1869
+ "hr-HR": {
1870
+ colorPicker: "Odabir boje",
1871
+ twoDimensionalSlider: "2D klizač",
1872
+ colorSwatch: "uzorak boje",
1873
+ transparent: "transparentno",
1874
+ colorSwatchDescription: "{name}",
1875
+ },
1876
+ "hu-HU": {
1877
+ colorPicker: "Színválasztó",
1878
+ twoDimensionalSlider: "2D-csúszka",
1879
+ colorSwatch: "színtár",
1880
+ transparent: "átlátszó",
1881
+ colorSwatchDescription: "{name}",
1882
+ },
1883
+ "it-IT": {
1884
+ colorPicker: "Selettore colore",
1885
+ twoDimensionalSlider: "Cursore 2D",
1886
+ colorSwatch: "campione di colore",
1887
+ transparent: "trasparente",
1888
+ colorSwatchDescription: "{name}",
1889
+ },
1890
+ "ja-JP": {
1891
+ colorPicker: "カラーピッカー",
1892
+ twoDimensionalSlider: "2D スライダー",
1893
+ colorSwatch: "カラースウォッチ",
1894
+ transparent: "透明",
1895
+ colorSwatchDescription: "{name}",
1896
+ },
1897
+ "ko-KR": {
1898
+ colorPicker: "색상 피커",
1899
+ twoDimensionalSlider: "2D 슬라이더",
1900
+ colorSwatch: "색상 견본",
1901
+ transparent: "투명도",
1902
+ colorSwatchDescription: "{name}",
1903
+ },
1904
+ "lt-LT": {
1905
+ colorPicker: "Spalvų parinkiklis",
1906
+ twoDimensionalSlider: "2D slankiklis",
1907
+ colorSwatch: "spalvų pavyzdys",
1908
+ transparent: "skaidrus",
1909
+ colorSwatchDescription: "{name}",
1910
+ },
1911
+ "lv-LV": {
1912
+ colorPicker: "Krāsu atlasītājs",
1913
+ twoDimensionalSlider: "2D slīdnis",
1914
+ colorSwatch: "krāsu paraugs",
1915
+ transparent: "caurspīdīgs",
1916
+ colorSwatchDescription: "{name}",
1917
+ },
1918
+ "nb-NO": {
1919
+ colorPicker: "Fargevelger",
1920
+ twoDimensionalSlider: "2D-glidebryter",
1921
+ colorSwatch: "fargekart",
1922
+ transparent: "gjennomsiktig",
1923
+ colorSwatchDescription: "{name}",
1924
+ },
1925
+ "nl-NL": {
1926
+ colorPicker: "Kleurkiezer",
1927
+ twoDimensionalSlider: "2D-schuifregelaar",
1928
+ colorSwatch: "kleurstaal",
1929
+ transparent: "transparant",
1930
+ colorSwatchDescription: "{name}",
1931
+ },
1932
+ "pl-PL": {
1933
+ colorPicker: "Próbnik kolorów",
1934
+ twoDimensionalSlider: "Suwak 2D",
1935
+ colorSwatch: "próbka koloru",
1936
+ transparent: "przezroczysty",
1937
+ colorSwatchDescription: "{name}",
1938
+ },
1939
+ "pt-BR": {
1940
+ colorPicker: "Seletor de cores",
1941
+ twoDimensionalSlider: "Controle deslizante 2D",
1942
+ colorSwatch: "amostra de cores",
1943
+ transparent: "transparente",
1944
+ colorSwatchDescription: "{name}",
1945
+ },
1946
+ "pt-PT": {
1947
+ colorPicker: "Seletor de cores",
1948
+ twoDimensionalSlider: "Controle deslizante 2D",
1949
+ colorSwatch: "amostra de cor",
1950
+ transparent: "transparente",
1951
+ colorSwatchDescription: "{name}",
1952
+ },
1953
+ "ro-RO": {
1954
+ colorPicker: "Selector de culori",
1955
+ twoDimensionalSlider: "Glisor 2D",
1956
+ colorSwatch: "specimen de culoare",
1957
+ transparent: "transparent",
1958
+ colorSwatchDescription: "{name}",
1959
+ },
1960
+ "ru-RU": {
1961
+ colorPicker: "Палитра цветов",
1962
+ twoDimensionalSlider: "Ползунок 2D",
1963
+ colorSwatch: "цветовой образец",
1964
+ transparent: "прозрачный",
1965
+ colorSwatchDescription: "{name}",
1966
+ },
1967
+ "sk-SK": {
1968
+ colorPicker: "Výber farieb",
1969
+ twoDimensionalSlider: "2D jazdec",
1970
+ colorSwatch: "vzorkovník farieb",
1971
+ transparent: "transparentný",
1972
+ colorSwatchDescription: "{name}",
1973
+ },
1974
+ "sl-SI": {
1975
+ colorPicker: "Izbirnik barv",
1976
+ twoDimensionalSlider: "2D drsnik",
1977
+ colorSwatch: "barvna paleta",
1978
+ transparent: "prozorno",
1979
+ colorSwatchDescription: "{name}",
1980
+ },
1981
+ "sr-SP": {
1982
+ colorPicker: "Birač boja",
1983
+ twoDimensionalSlider: "2D klizač",
1984
+ colorSwatch: "Uzorak boje",
1985
+ transparent: "providno",
1986
+ colorSwatchDescription: "{name}",
1987
+ },
1988
+ "sv-SE": {
1989
+ colorPicker: "Färgväljaren",
1990
+ twoDimensionalSlider: "2D-reglage",
1991
+ colorSwatch: "färgruta",
1992
+ transparent: "genomskinlig",
1993
+ colorSwatchDescription: "{name}",
1994
+ },
1995
+ "tr-TR": {
1996
+ colorPicker: "Renk Seçici",
1997
+ twoDimensionalSlider: "2D sürgü",
1998
+ colorSwatch: "renk örneği",
1999
+ transparent: "saydam",
2000
+ colorSwatchDescription: "{name}",
2001
+ },
2002
+ "uk-UA": {
2003
+ colorPicker: "Палітра кольорів",
2004
+ twoDimensionalSlider: "Повзунок 2D",
2005
+ colorSwatch: "зразок кольору",
2006
+ transparent: "прозорий",
2007
+ colorSwatchDescription: "{name}",
2008
+ },
2009
+ "zh-CN": {
2010
+ colorPicker: "拾色器",
2011
+ twoDimensionalSlider: "2D 滑块",
2012
+ colorSwatch: "颜色色板",
2013
+ transparent: "透明",
2014
+ colorSwatchDescription: "{name}",
2015
+ },
2016
+ "zh-TW": {
2017
+ colorPicker: "檢色器",
2018
+ twoDimensionalSlider: "2D 滑桿",
2019
+ colorSwatch: "色票",
2020
+ transparent: "透明",
2021
+ colorSwatchDescription: "{name}",
2022
+ },
2023
+ });