@jcsoftdev/ui 0.3.0 → 0.4.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.
Files changed (268) hide show
  1. package/CHANGELOG.md +103 -1
  2. package/README.md +55 -2
  3. package/bin/ui-theme.mjs +13 -2
  4. package/dist/atoms/checkbox/checkbox.js +3 -1
  5. package/dist/atoms/chip/chip.d.ts +11 -3
  6. package/dist/atoms/chip/chip.js +8 -1
  7. package/dist/atoms/chip/index.d.ts +1 -1
  8. package/dist/atoms/chip/index.js +2 -0
  9. package/dist/atoms/due-chip/due-chip.d.ts +31 -0
  10. package/dist/atoms/due-chip/due-chip.js +41 -0
  11. package/dist/atoms/due-chip/index.d.ts +2 -0
  12. package/dist/atoms/due-chip/index.js +6 -0
  13. package/dist/atoms/due-chip/model.d.ts +25 -0
  14. package/dist/atoms/due-chip/model.js +44 -0
  15. package/dist/atoms/icon-button/icon-button.d.ts +22 -0
  16. package/dist/atoms/icon-button/icon-button.js +38 -0
  17. package/dist/atoms/icon-button/index.d.ts +1 -0
  18. package/dist/atoms/icon-button/index.js +8 -0
  19. package/dist/atoms/index.d.ts +5 -0
  20. package/dist/atoms/index.js +5 -0
  21. package/dist/atoms/internal/hit-area.d.ts +6 -0
  22. package/dist/atoms/internal/hit-area.js +4 -0
  23. package/dist/atoms/kbd/index.d.ts +1 -0
  24. package/dist/atoms/kbd/index.js +4 -0
  25. package/dist/atoms/kbd/kbd.d.ts +7 -0
  26. package/dist/atoms/kbd/kbd.js +17 -0
  27. package/dist/atoms/radio-group/radio-group.js +6 -2
  28. package/dist/atoms/seal/index.d.ts +1 -0
  29. package/dist/atoms/seal/index.js +4 -0
  30. package/dist/atoms/seal/seal.d.ts +30 -0
  31. package/dist/atoms/seal/seal.js +71 -0
  32. package/dist/atoms/spinner/index.d.ts +1 -0
  33. package/dist/atoms/spinner/index.js +5 -0
  34. package/dist/atoms/spinner/spinner.d.ts +19 -0
  35. package/dist/atoms/spinner/spinner.js +31 -0
  36. package/dist/atoms/switch/switch.js +3 -1
  37. package/dist/calendar/date-calendar/date-calendar.d.ts +32 -0
  38. package/dist/calendar/date-calendar/date-calendar.js +189 -0
  39. package/dist/calendar/date-calendar/index.d.ts +1 -0
  40. package/dist/calendar/date-calendar/index.js +6 -0
  41. package/dist/calendar/index.d.ts +1 -0
  42. package/dist/calendar/index.js +1 -0
  43. package/dist/calendar/internal/date-utils.d.ts +26 -0
  44. package/dist/calendar/internal/date-utils.js +95 -1
  45. package/dist/containers/aside/aside.d.ts +14 -0
  46. package/dist/containers/aside/aside.js +25 -0
  47. package/dist/containers/aside/index.d.ts +1 -0
  48. package/dist/containers/aside/index.js +5 -0
  49. package/dist/containers/banner/banner.d.ts +4 -1
  50. package/dist/containers/banner/banner.js +9 -1
  51. package/dist/containers/description-list/description-list.d.ts +29 -6
  52. package/dist/containers/description-list/description-list.js +47 -6
  53. package/dist/containers/feed/feed.d.ts +23 -0
  54. package/dist/containers/feed/feed.js +77 -0
  55. package/dist/containers/feed/index.d.ts +2 -0
  56. package/dist/containers/feed/index.js +10 -0
  57. package/dist/containers/feed/model.d.ts +19 -0
  58. package/dist/containers/feed/model.js +38 -0
  59. package/dist/containers/index.d.ts +6 -0
  60. package/dist/containers/index.js +6 -0
  61. package/dist/containers/kpi/kpi.d.ts +50 -8
  62. package/dist/containers/kpi/kpi.js +91 -39
  63. package/dist/containers/list-detail/index.d.ts +1 -0
  64. package/dist/containers/list-detail/index.js +20 -0
  65. package/dist/containers/list-detail/list-detail.d.ts +55 -0
  66. package/dist/containers/list-detail/list-detail.js +221 -0
  67. package/dist/containers/note/index.d.ts +1 -0
  68. package/dist/containers/note/index.js +4 -0
  69. package/dist/containers/note/note.d.ts +13 -0
  70. package/dist/containers/note/note.js +27 -0
  71. package/dist/containers/section/index.d.ts +1 -0
  72. package/dist/containers/section/index.js +6 -0
  73. package/dist/containers/section/section.d.ts +68 -0
  74. package/dist/containers/section/section.js +198 -0
  75. package/dist/containers/shortcuts/index.d.ts +1 -0
  76. package/dist/containers/shortcuts/index.js +8 -0
  77. package/dist/containers/shortcuts/shortcuts.d.ts +18 -0
  78. package/dist/containers/shortcuts/shortcuts.js +50 -0
  79. package/dist/containers/table/selection.d.ts +9 -0
  80. package/dist/containers/table/selection.js +20 -0
  81. package/dist/containers/table/table.d.ts +66 -4
  82. package/dist/containers/table/table.js +128 -7
  83. package/dist/containers/timeline/index.d.ts +1 -1
  84. package/dist/containers/timeline/index.js +4 -2
  85. package/dist/containers/timeline/timeline.d.ts +32 -5
  86. package/dist/containers/timeline/timeline.js +154 -90
  87. package/dist/forms/chip-group/chip-group.d.ts +54 -0
  88. package/dist/forms/chip-group/chip-group.js +114 -0
  89. package/dist/forms/chip-group/index.d.ts +1 -0
  90. package/dist/forms/chip-group/index.js +6 -0
  91. package/dist/forms/combobox/combobox.d.ts +60 -0
  92. package/dist/forms/combobox/combobox.js +281 -0
  93. package/dist/forms/combobox/index.d.ts +1 -0
  94. package/dist/forms/combobox/index.js +6 -0
  95. package/dist/forms/date-picker/date-picker.d.ts +40 -0
  96. package/dist/forms/date-picker/date-picker.js +183 -0
  97. package/dist/forms/date-picker/date-time-picker.d.ts +43 -0
  98. package/dist/forms/date-picker/date-time-picker.js +121 -0
  99. package/dist/forms/date-picker/index.d.ts +2 -0
  100. package/dist/forms/date-picker/index.js +10 -0
  101. package/dist/forms/date-picker/model.d.ts +35 -0
  102. package/dist/forms/date-picker/model.js +83 -0
  103. package/dist/forms/dropzone/dropzone.d.ts +30 -2
  104. package/dist/forms/dropzone/dropzone.js +153 -23
  105. package/dist/forms/field/field.d.ts +16 -10
  106. package/dist/forms/field/field.js +41 -5
  107. package/dist/forms/index.d.ts +4 -0
  108. package/dist/forms/index.js +4 -0
  109. package/dist/forms/input/index.d.ts +1 -1
  110. package/dist/forms/input/index.js +4 -1
  111. package/dist/forms/input/input.d.ts +21 -5
  112. package/dist/forms/input/input.js +74 -9
  113. package/dist/forms/input-icon/input-icon.d.ts +1 -1
  114. package/dist/forms/internal/listbox-items.d.ts +18 -0
  115. package/dist/forms/internal/listbox-items.js +88 -0
  116. package/dist/forms/internal/listbox.d.ts +44 -0
  117. package/dist/forms/internal/listbox.js +74 -0
  118. package/dist/forms/number-stepper/model.d.ts +16 -0
  119. package/dist/forms/number-stepper/model.js +23 -0
  120. package/dist/forms/number-stepper/number-stepper.d.ts +36 -6
  121. package/dist/forms/number-stepper/number-stepper.js +86 -37
  122. package/dist/forms/select-menu/index.d.ts +1 -0
  123. package/dist/forms/select-menu/index.js +6 -0
  124. package/dist/forms/select-menu/select-menu.d.ts +35 -0
  125. package/dist/forms/select-menu/select-menu.js +230 -0
  126. package/dist/i18n/strings.d.ts +89 -0
  127. package/dist/i18n/strings.js +54 -2
  128. package/dist/i18n/ui-strings-provider.d.ts +1 -1
  129. package/dist/i18n/ui-strings-provider.js +6 -2
  130. package/dist/navigation/index.d.ts +1 -0
  131. package/dist/navigation/index.js +1 -0
  132. package/dist/navigation/stepper/index.d.ts +1 -1
  133. package/dist/navigation/stepper/index.js +3 -1
  134. package/dist/navigation/stepper/stepper.d.ts +8 -0
  135. package/dist/navigation/stepper/stepper.js +68 -45
  136. package/dist/navigation/tabs/index.d.ts +1 -0
  137. package/dist/navigation/tabs/index.js +6 -0
  138. package/dist/navigation/tabs/tabs-nav.d.ts +37 -0
  139. package/dist/navigation/tabs/tabs-nav.js +57 -0
  140. package/dist/navigation/wizard/index.d.ts +1 -0
  141. package/dist/navigation/wizard/index.js +6 -0
  142. package/dist/navigation/wizard/model.d.ts +33 -0
  143. package/dist/navigation/wizard/model.js +34 -0
  144. package/dist/navigation/wizard/wizard.d.ts +45 -0
  145. package/dist/navigation/wizard/wizard.js +169 -0
  146. package/dist/overlays/alert-dialog/alert-dialog.d.ts +103 -0
  147. package/dist/overlays/alert-dialog/alert-dialog.js +342 -0
  148. package/dist/overlays/alert-dialog/index.d.ts +1 -0
  149. package/dist/overlays/alert-dialog/index.js +26 -0
  150. package/dist/overlays/dropdown-menu/dropdown-menu.d.ts +17 -1
  151. package/dist/overlays/dropdown-menu/dropdown-menu.js +12 -4
  152. package/dist/overlays/dropdown-menu/index.d.ts +1 -1
  153. package/dist/overlays/dropdown-menu/index.js +8 -2
  154. package/dist/overlays/index.d.ts +2 -0
  155. package/dist/overlays/index.js +2 -0
  156. package/dist/overlays/testing/index.d.ts +5 -0
  157. package/dist/overlays/testing/index.js +4 -0
  158. package/dist/overlays/toaster/index.d.ts +2 -1
  159. package/dist/overlays/toaster/index.js +4 -2
  160. package/dist/overlays/toaster/toast-store.d.ts +6 -2
  161. package/dist/overlays/toaster/toast.d.ts +3 -0
  162. package/dist/overlays/toaster/toast.js +3 -0
  163. package/dist/overlays/toaster/toaster.d.ts +3 -0
  164. package/dist/overlays/toaster/toaster.js +36 -3
  165. package/dist/overlays/tooltip/index.d.ts +1 -0
  166. package/dist/overlays/tooltip/index.js +4 -0
  167. package/dist/overlays/tooltip/model.d.ts +10 -0
  168. package/dist/overlays/tooltip/model.js +13 -0
  169. package/dist/overlays/tooltip/tooltip.d.ts +41 -0
  170. package/dist/overlays/tooltip/tooltip.js +116 -0
  171. package/dist/primitives/use-dismissable-layer.js +1 -1
  172. package/dist/states/error-state/error-state.d.ts +6 -1
  173. package/dist/states/error-state/error-state.js +13 -9
  174. package/dist/states/skeleton/skeleton.d.ts +8 -2
  175. package/dist/states/skeleton/skeleton.js +44 -2
  176. package/package.json +2 -2
  177. package/scripts/build-theme.mjs +12 -1
  178. package/src/atoms/checkbox/checkbox.tsx +3 -1
  179. package/src/atoms/chip/chip.tsx +18 -3
  180. package/src/atoms/chip/index.ts +2 -0
  181. package/src/atoms/due-chip/due-chip.tsx +75 -0
  182. package/src/atoms/due-chip/index.ts +2 -0
  183. package/src/atoms/due-chip/model.ts +67 -0
  184. package/src/atoms/icon-button/icon-button.tsx +58 -0
  185. package/src/atoms/icon-button/index.ts +6 -0
  186. package/src/atoms/index.ts +5 -0
  187. package/src/atoms/internal/hit-area.ts +7 -0
  188. package/src/atoms/kbd/index.ts +1 -0
  189. package/src/atoms/kbd/kbd.tsx +20 -0
  190. package/src/atoms/radio-group/radio-group.tsx +8 -2
  191. package/src/atoms/seal/index.ts +1 -0
  192. package/src/atoms/seal/seal.tsx +107 -0
  193. package/src/atoms/spinner/index.ts +1 -0
  194. package/src/atoms/spinner/spinner.tsx +49 -0
  195. package/src/atoms/switch/switch.tsx +3 -1
  196. package/src/calendar/date-calendar/date-calendar.tsx +230 -0
  197. package/src/calendar/date-calendar/index.ts +5 -0
  198. package/src/calendar/index.ts +1 -0
  199. package/src/calendar/internal/date-utils.ts +115 -0
  200. package/src/containers/aside/aside.tsx +40 -0
  201. package/src/containers/aside/index.ts +1 -0
  202. package/src/containers/banner/banner.tsx +18 -1
  203. package/src/containers/description-list/description-list.tsx +85 -9
  204. package/src/containers/feed/feed.tsx +99 -0
  205. package/src/containers/feed/index.ts +8 -0
  206. package/src/containers/feed/model.ts +54 -0
  207. package/src/containers/index.ts +6 -0
  208. package/src/containers/kpi/kpi.tsx +161 -62
  209. package/src/containers/list-detail/index.ts +15 -0
  210. package/src/containers/list-detail/list-detail.tsx +293 -0
  211. package/src/containers/note/index.ts +1 -0
  212. package/src/containers/note/note.tsx +38 -0
  213. package/src/containers/section/index.ts +11 -0
  214. package/src/containers/section/section.tsx +281 -0
  215. package/src/containers/shortcuts/index.ts +6 -0
  216. package/src/containers/shortcuts/shortcuts.tsx +92 -0
  217. package/src/containers/table/selection.ts +26 -0
  218. package/src/containers/table/table.tsx +215 -13
  219. package/src/containers/timeline/index.ts +3 -0
  220. package/src/containers/timeline/timeline.tsx +204 -93
  221. package/src/forms/chip-group/chip-group.tsx +184 -0
  222. package/src/forms/chip-group/index.ts +8 -0
  223. package/src/forms/combobox/combobox.tsx +359 -0
  224. package/src/forms/combobox/index.ts +7 -0
  225. package/src/forms/date-picker/date-picker.tsx +239 -0
  226. package/src/forms/date-picker/date-time-picker.tsx +178 -0
  227. package/src/forms/date-picker/index.ts +10 -0
  228. package/src/forms/date-picker/model.ts +108 -0
  229. package/src/forms/dropzone/dropzone.tsx +217 -35
  230. package/src/forms/field/field.tsx +72 -7
  231. package/src/forms/index.ts +4 -0
  232. package/src/forms/input/index.ts +8 -1
  233. package/src/forms/input/input.tsx +97 -12
  234. package/src/forms/input-icon/input-icon.tsx +1 -1
  235. package/src/forms/internal/listbox-items.tsx +103 -0
  236. package/src/forms/internal/listbox.ts +124 -0
  237. package/src/forms/number-stepper/model.ts +35 -0
  238. package/src/forms/number-stepper/number-stepper.tsx +132 -42
  239. package/src/forms/select-menu/index.ts +7 -0
  240. package/src/forms/select-menu/select-menu.tsx +280 -0
  241. package/src/i18n/strings.ts +89 -0
  242. package/src/i18n/ui-strings-provider.tsx +15 -4
  243. package/src/navigation/index.ts +1 -0
  244. package/src/navigation/stepper/index.ts +7 -1
  245. package/src/navigation/stepper/stepper.tsx +41 -5
  246. package/src/navigation/tabs/index.ts +7 -0
  247. package/src/navigation/tabs/tabs-nav.tsx +131 -0
  248. package/src/navigation/wizard/index.ts +7 -0
  249. package/src/navigation/wizard/model.ts +61 -0
  250. package/src/navigation/wizard/wizard.tsx +222 -0
  251. package/src/overlays/alert-dialog/alert-dialog.tsx +486 -0
  252. package/src/overlays/alert-dialog/index.ts +19 -0
  253. package/src/overlays/dropdown-menu/dropdown-menu.tsx +29 -4
  254. package/src/overlays/dropdown-menu/index.ts +3 -0
  255. package/src/overlays/index.ts +2 -0
  256. package/src/overlays/testing/index.ts +5 -0
  257. package/src/overlays/toaster/index.ts +2 -0
  258. package/src/overlays/toaster/toast-store.ts +6 -2
  259. package/src/overlays/toaster/toast.ts +6 -0
  260. package/src/overlays/toaster/toaster.tsx +44 -2
  261. package/src/overlays/tooltip/index.ts +1 -0
  262. package/src/overlays/tooltip/model.ts +18 -0
  263. package/src/overlays/tooltip/tooltip.tsx +166 -0
  264. package/src/primitives/use-dismissable-layer.ts +7 -2
  265. package/src/states/error-state/error-state.tsx +19 -8
  266. package/src/states/skeleton/skeleton.tsx +68 -2
  267. package/styles/tailwind.css +33 -30
  268. package/styles/theme.css +33 -30
@@ -0,0 +1,184 @@
1
+ "use client";
2
+
3
+ import { type ReactNode, useEffect, useId, useRef, useState } from "react";
4
+ import { Check } from "../../icons/index.js";
5
+ import type { ClassNames } from "../../utils/class-names.js";
6
+ import { cn } from "../../utils/cn.js";
7
+ import { useComposedRefs } from "../../utils/compose.js";
8
+ import { useRovingFocus } from "../../utils/roving-focus.js";
9
+ import { useControllableState } from "../../utils/use-controllable-state.js";
10
+
11
+ export interface ChipGroupOption {
12
+ value: string;
13
+ label: ReactNode;
14
+ /** Small count after the label. */
15
+ count?: ReactNode;
16
+ /** Decorative glyph before the label (replaced by a check while selected in a multiple group). */
17
+ icon?: ReactNode;
18
+ disabled?: boolean;
19
+ }
20
+
21
+ export type ChipGroupPart = "root" | "chip" | "label" | "count" | "check";
22
+
23
+ interface ChipGroupCommon {
24
+ options: readonly ChipGroupOption[];
25
+ disabled?: boolean | undefined;
26
+ /** Form field name: a hidden input per selected value. */
27
+ name?: string | undefined;
28
+ /** Marks the group invalid (also set by `Field` through `aria-invalid`). */
29
+ invalid?: boolean | undefined;
30
+ /** Set by `Field`; the group is named from the field's label. */
31
+ id?: string | undefined;
32
+ "aria-label"?: string | undefined;
33
+ "aria-labelledby"?: string | undefined;
34
+ "aria-describedby"?: string | undefined;
35
+ "aria-invalid"?: boolean | "true" | "false" | undefined;
36
+ className?: string | undefined;
37
+ /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root. */
38
+ classNames?: ClassNames<ChipGroupPart>;
39
+ }
40
+
41
+ export interface ChipGroupMultipleProps extends ChipGroupCommon {
42
+ /** Any number of chips can be on. This is the default. */
43
+ type?: "multiple";
44
+ value?: string[] | undefined;
45
+ defaultValue?: string[] | undefined;
46
+ onValueChange?: ((value: string[]) => void) | undefined;
47
+ }
48
+
49
+ export interface ChipGroupSingleProps extends ChipGroupCommon {
50
+ /** At most one chip is on. */
51
+ type: "single";
52
+ value?: string | undefined;
53
+ defaultValue?: string | undefined;
54
+ onValueChange?: ((value: string) => void) | undefined;
55
+ /** Lets the pressed chip be pressed again to clear the choice (`""`). Off by default: a filter keeps one on. */
56
+ allowDeselect?: boolean | undefined;
57
+ }
58
+
59
+ export type ChipGroupProps = ChipGroupMultipleProps | ChipGroupSingleProps;
60
+
61
+ /**
62
+ * A set of chips that act as toggle buttons (`aria-pressed`) in a `fieldset` (a named group): pick several
63
+ * (`type="multiple"`, default) or one (`type="single"`). Arrow keys, Home and End move between
64
+ * chips and Space or Enter toggles; the group works inside `Field` (named from its label,
65
+ * described by its hint and error) and submits one hidden input per selected value when named.
66
+ */
67
+ export function ChipGroup(props: ChipGroupProps) {
68
+ const {
69
+ options,
70
+ disabled,
71
+ name,
72
+ invalid,
73
+ id,
74
+ className,
75
+ classNames,
76
+ "aria-label": ariaLabel,
77
+ "aria-labelledby": ariaLabelledBy,
78
+ "aria-describedby": ariaDescribedBy,
79
+ "aria-invalid": ariaInvalid,
80
+ } = props;
81
+ const single = props.type === "single";
82
+ const generated = useId();
83
+ const baseId = id ?? generated;
84
+
85
+ const [multiValue, setMultiValue] = useControllableState<string[]>({
86
+ prop: props.type === "single" ? undefined : props.value,
87
+ defaultProp: (props.type === "single" ? undefined : props.defaultValue) ?? [],
88
+ onChange: props.type === "single" ? undefined : props.onValueChange,
89
+ });
90
+ const [singleValue, setSingleValue] = useControllableState<string>({
91
+ prop: props.type === "single" ? props.value : undefined,
92
+ defaultProp: (props.type === "single" ? props.defaultValue : undefined) ?? "",
93
+ onChange: props.type === "single" ? props.onValueChange : undefined,
94
+ });
95
+
96
+ const selected = single ? (singleValue ? [singleValue] : []) : multiValue;
97
+ const toggle = (value: string) => {
98
+ if (props.type === "single") {
99
+ if (singleValue === value) {
100
+ if (props.allowDeselect) setSingleValue("");
101
+ } else setSingleValue(value);
102
+ return;
103
+ }
104
+ setMultiValue(
105
+ multiValue.includes(value) ? multiValue.filter((v) => v !== value) : [...multiValue, value],
106
+ );
107
+ };
108
+
109
+ const roving = useRovingFocus({
110
+ activeId: selected.find((v) => options.some((o) => o.value === v && !o.disabled)) ?? null,
111
+ });
112
+ const { ref: rovingRef, onFocus: rovingOnFocus, tabIndex } = roving.rootProps;
113
+ const localRef = useRef<HTMLFieldSetElement | null>(null);
114
+ const composedRef = useComposedRefs<HTMLFieldSetElement>(rovingRef, localRef);
115
+
116
+ // A group is not a labelable element, so `Field`'s <label for> cannot name it: read its text.
117
+ const [fieldLabel, setFieldLabel] = useState<string | undefined>();
118
+ useEffect(() => {
119
+ if (ariaLabel || ariaLabelledBy || !id) return;
120
+ const label = Array.from(
121
+ localRef.current?.ownerDocument.querySelectorAll<HTMLLabelElement>("label[for]") ?? [],
122
+ ).find((candidate) => candidate.htmlFor === id);
123
+ setFieldLabel(label?.textContent?.trim() || undefined);
124
+ }, [id, ariaLabel, ariaLabelledBy]);
125
+
126
+ const isInvalid = invalid || ariaInvalid === true || ariaInvalid === "true";
127
+
128
+ return (
129
+ <fieldset
130
+ ref={composedRef}
131
+ id={baseId}
132
+ tabIndex={tabIndex}
133
+ aria-label={ariaLabel ?? (ariaLabelledBy ? undefined : fieldLabel)}
134
+ aria-labelledby={ariaLabelledBy}
135
+ aria-describedby={ariaDescribedBy}
136
+ data-type={single ? "single" : "multiple"}
137
+ data-invalid={isInvalid ? "" : undefined}
138
+ data-disabled={disabled ? "" : undefined}
139
+ onFocus={rovingOnFocus}
140
+ className={cn(
141
+ "group/chips m-0 flex min-w-0 flex-wrap gap-1.5 border-0 p-0 outline-none",
142
+ classNames?.root,
143
+ className,
144
+ )}
145
+ >
146
+ {options.map((option) => {
147
+ const pressed = selected.includes(option.value);
148
+ const off = disabled || option.disabled;
149
+ const item = roving.getItemProps<HTMLButtonElement>(option.value, { disabled: off });
150
+ return (
151
+ <button
152
+ key={option.value}
153
+ type="button"
154
+ aria-pressed={pressed}
155
+ disabled={off}
156
+ {...item}
157
+ onClick={() => toggle(option.value)}
158
+ className={cn(
159
+ "inline-flex min-h-7 cursor-pointer items-center gap-1.5 rounded-badge border-control bg-surface-control px-3 font-medium text-fs-130 text-ink-2 hover:bg-surface-2 focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-50 aria-pressed:border-accent aria-pressed:bg-accent-soft aria-pressed:text-accent-ink group-data-[invalid]/chips:border-danger in-data-[density=touch]:min-h-11 [&_svg]:size-3",
160
+ classNames?.chip,
161
+ )}
162
+ >
163
+ {pressed && !single ? (
164
+ <Check aria-hidden="true" className={classNames?.check} />
165
+ ) : option.icon ? (
166
+ <span aria-hidden="true" className="inline-flex shrink-0">
167
+ {option.icon}
168
+ </span>
169
+ ) : null}
170
+ <span className={cn("min-w-0", classNames?.label)}>{option.label}</span>
171
+ {option.count !== undefined ? (
172
+ <span className={cn("text-count tabular-nums", classNames?.count)}>
173
+ {option.count}
174
+ </span>
175
+ ) : null}
176
+ </button>
177
+ );
178
+ })}
179
+ {name
180
+ ? selected.map((value) => <input key={value} type="hidden" name={name} value={value} />)
181
+ : null}
182
+ </fieldset>
183
+ );
184
+ }
@@ -0,0 +1,8 @@
1
+ export {
2
+ ChipGroup,
3
+ type ChipGroupMultipleProps,
4
+ type ChipGroupOption,
5
+ type ChipGroupPart,
6
+ type ChipGroupProps,
7
+ type ChipGroupSingleProps,
8
+ } from "./chip-group.js";
@@ -0,0 +1,359 @@
1
+ "use client";
2
+
3
+ import {
4
+ type ComponentProps,
5
+ type KeyboardEvent,
6
+ useEffect,
7
+ useId,
8
+ useMemo,
9
+ useRef,
10
+ useState,
11
+ } from "react";
12
+ import { useUiStrings } from "../../i18n/index.js";
13
+ import { X } from "../../icons/index.js";
14
+ import * as PopoverPrimitive from "../../primitives/popover/popover.js";
15
+ import type { ClassNames } from "../../utils/class-names.js";
16
+ import { cn } from "../../utils/cn.js";
17
+ import { useComposedRefs } from "../../utils/compose.js";
18
+ import { type Material, materialClass } from "../../utils/material.js";
19
+ import { useControllableState } from "../../utils/use-controllable-state.js";
20
+ import {
21
+ filterItems,
22
+ flattenItems,
23
+ type ListboxGroup,
24
+ type ListboxOption,
25
+ matchesQuery,
26
+ moveActive,
27
+ } from "../internal/listbox.js";
28
+ import { LISTBOX_SURFACE, ListboxItems, optionDomId } from "../internal/listbox-items.js";
29
+
30
+ export type ComboboxOption = ListboxOption;
31
+ export type ComboboxGroup = ListboxGroup<ComboboxOption>;
32
+
33
+ export type ComboboxPart = "root" | "input" | "clear" | "content" | "option" | "group" | "status";
34
+
35
+ export interface ComboboxProps
36
+ extends Omit<
37
+ ComponentProps<"input">,
38
+ "value" | "defaultValue" | "onChange" | "type" | "role" | "size"
39
+ > {
40
+ /** Options, optionally nested in labelled groups. For async search, pass the current results. */
41
+ options: readonly (ComboboxOption | ComboboxGroup)[];
42
+ /** Selected option value (controlled). `""` means nothing is selected. */
43
+ value?: string;
44
+ defaultValue?: string;
45
+ onValueChange?: (value: string, option: ComboboxOption | null) => void;
46
+ /**
47
+ * Called on every keystroke with the text typed, and with `""` when the search resets. Debounce
48
+ * in the caller before fetching; the component never delays or cancels requests.
49
+ */
50
+ onSearchChange?: (query: string) => void;
51
+ /**
52
+ * Local filtering. `true` (default) matches label, description and keywords ignoring case and
53
+ * accents; `false` shows `options` as given (server-side search); a function decides per option.
54
+ */
55
+ filter?: boolean | ((option: ComboboxOption, query: string) => boolean);
56
+ /** Most options rendered at once. Default 50. */
57
+ maxVisible?: number;
58
+ /** Shows the loading status, e.g. while an async search is in flight. */
59
+ loading?: boolean;
60
+ loadingText?: string;
61
+ /** Shown when nothing matches. Defaults to the localized "No results". */
62
+ emptyText?: string;
63
+ /** Shows a button that clears the selection. Default `true`. */
64
+ clearable?: boolean;
65
+ clearLabel?: string;
66
+ /** Label to show for `value` while it is not (yet) among `options`, e.g. after an async search moved on. */
67
+ valueLabel?: string;
68
+ /** Submits the value (not the typed text) with a surrounding `<form>` through a hidden input. */
69
+ name?: string;
70
+ invalid?: boolean;
71
+ /**
72
+ * `required` always sets `aria-required`. The native attribute, which blocks form submission
73
+ * with the browser's own bubble before your validation can render, is added only when this is
74
+ * `true`. Default `false`.
75
+ */
76
+ nativeRequired?: boolean;
77
+ size?: "sm" | "md";
78
+ /** Portal target for the popup. Defaults to `document.body`; pass an element to keep a scoped `data-style`. */
79
+ container?: HTMLElement | null;
80
+ /** Popup surface material; see `PopoverContent`. */
81
+ material?: Material;
82
+ /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
83
+ classNames?: ClassNames<ComboboxPart>;
84
+ }
85
+
86
+ /**
87
+ * Searchable single select (WAI-ARIA combobox with a listbox popup). The input shows the typed
88
+ * text while editing and the selected label otherwise; focus never leaves the input and the
89
+ * highlighted option is announced through `aria-activedescendant`. Works with local options or
90
+ * with results the caller loads from `onSearchChange`.
91
+ */
92
+ export function Combobox({
93
+ options,
94
+ value: valueProp,
95
+ defaultValue = "",
96
+ onValueChange,
97
+ onSearchChange,
98
+ filter = true,
99
+ maxVisible = 50,
100
+ loading = false,
101
+ loadingText,
102
+ emptyText,
103
+ clearable = true,
104
+ clearLabel,
105
+ valueLabel,
106
+ name,
107
+ invalid,
108
+ required,
109
+ nativeRequired = false,
110
+ size = "md",
111
+ container,
112
+ material,
113
+ disabled,
114
+ className,
115
+ classNames,
116
+ ref,
117
+ id,
118
+ onFocus,
119
+ onClick,
120
+ onBlur,
121
+ onKeyDown,
122
+ "aria-label": ariaLabel,
123
+ "aria-labelledby": ariaLabelledBy,
124
+ "aria-invalid": ariaInvalid,
125
+ ...props
126
+ }: ComboboxProps) {
127
+ const strings = useUiStrings();
128
+ const autoId = useId();
129
+ const inputId = id ?? autoId;
130
+ const listId = `${inputId}-listbox`;
131
+ const rootRef = useRef<HTMLDivElement | null>(null);
132
+ const inputRef = useRef<HTMLInputElement | null>(null);
133
+ const composedRef = useComposedRefs<HTMLInputElement>(ref, inputRef);
134
+ const allOptions = useMemo(() => flattenItems(options), [options]);
135
+ const [value, setValue] = useControllableState<string>({
136
+ prop: valueProp,
137
+ defaultProp: defaultValue,
138
+ onChange: (next) =>
139
+ onValueChange?.(next, allOptions.find((option) => option.value === next) ?? null),
140
+ });
141
+ const [query, setQuery] = useState<string | null>(null);
142
+ const [open, setOpen] = useState(false);
143
+ const [active, setActive] = useState(0);
144
+
145
+ const text = query ?? "";
146
+ const items = useMemo(() => {
147
+ const predicate =
148
+ filter === false
149
+ ? () => true
150
+ : typeof filter === "function"
151
+ ? (option: ComboboxOption) => filter(option, text)
152
+ : (option: ComboboxOption) => matchesQuery(option, text);
153
+ return filterItems(options, predicate, maxVisible);
154
+ }, [options, filter, text, maxVisible]);
155
+ const flat = useMemo(() => flattenItems(items), [items]);
156
+
157
+ const selected = value === "" ? undefined : allOptions.find((option) => option.value === value);
158
+ const selectedLabel = selected?.label ?? (value === "" ? "" : (valueLabel ?? ""));
159
+ const isOpen = open && !disabled;
160
+ const showList = isOpen && flat.length > 0;
161
+ const showEmpty = isOpen && !loading && flat.length === 0;
162
+ const activeIndex =
163
+ flat[active] && !flat[active]?.disabled ? active : moveActive(flat, -1, "first");
164
+ // biome-ignore lint/correctness/useExhaustiveDependencies: the highlight restarts when the text or the open state changes, not on every new results array.
165
+ useEffect(() => setActive(0), [query, isOpen]);
166
+ useEffect(() => {
167
+ if (!showList || activeIndex < 0) return;
168
+ document
169
+ .getElementById(optionDomId(listId, activeIndex))
170
+ ?.scrollIntoView?.({ block: "nearest" });
171
+ }, [showList, activeIndex, listId]);
172
+
173
+ const resetSearch = () => {
174
+ if (query !== null) onSearchChange?.("");
175
+ setQuery(null);
176
+ };
177
+
178
+ const pick = (option: ComboboxOption | undefined) => {
179
+ if (!option || option.disabled) return;
180
+ setValue(option.value);
181
+ resetSearch();
182
+ setOpen(false);
183
+ };
184
+
185
+ const clear = () => {
186
+ setValue("");
187
+ resetSearch();
188
+ setOpen(false);
189
+ inputRef.current?.focus();
190
+ };
191
+
192
+ const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
193
+ onKeyDown?.(event);
194
+ if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
195
+ const { key } = event;
196
+ if (key === "ArrowDown") {
197
+ event.preventDefault();
198
+ if (!isOpen) setOpen(true);
199
+ else setActive(moveActive(flat, activeIndex, "next"));
200
+ } else if (key === "ArrowUp") {
201
+ event.preventDefault();
202
+ if (!isOpen) setOpen(true);
203
+ else setActive(moveActive(flat, activeIndex, "prev"));
204
+ } else if (key === "Enter") {
205
+ if (showList && flat[activeIndex]) {
206
+ event.preventDefault();
207
+ pick(flat[activeIndex]);
208
+ }
209
+ } else if (key === "Escape") {
210
+ if (isOpen) {
211
+ event.preventDefault();
212
+ setOpen(false);
213
+ } else if (query !== null) {
214
+ event.preventDefault();
215
+ resetSearch();
216
+ }
217
+ } else if (key === "Backspace" && clearable && text === "" && query !== null && selected) {
218
+ clear();
219
+ }
220
+ };
221
+
222
+ const hasClear = clearable && !disabled && value !== "";
223
+
224
+ return (
225
+ <PopoverPrimitive.Root open={isOpen} onOpenChange={setOpen}>
226
+ <PopoverPrimitive.Anchor asChild>
227
+ <div
228
+ ref={rootRef}
229
+ className={cn("relative flex w-full min-w-0", classNames?.root, className)}
230
+ >
231
+ <input
232
+ {...props}
233
+ ref={composedRef}
234
+ id={inputId}
235
+ type="text"
236
+ role="combobox"
237
+ data-ui-layer=""
238
+ autoComplete="off"
239
+ aria-expanded={isOpen}
240
+ aria-controls={isOpen ? listId : undefined}
241
+ aria-autocomplete="list"
242
+ aria-activedescendant={
243
+ showList && activeIndex >= 0 ? optionDomId(listId, activeIndex) : undefined
244
+ }
245
+ aria-label={ariaLabel}
246
+ aria-labelledby={ariaLabelledBy}
247
+ aria-invalid={ariaInvalid ?? (invalid || undefined)}
248
+ aria-required={required || undefined}
249
+ required={nativeRequired ? required : undefined}
250
+ disabled={disabled}
251
+ value={query ?? selectedLabel}
252
+ onFocus={(event) => {
253
+ onFocus?.(event);
254
+ event.currentTarget.select();
255
+ setOpen(true);
256
+ }}
257
+ onClick={(event) => {
258
+ onClick?.(event);
259
+ setOpen(true);
260
+ }}
261
+ onChange={(event) => {
262
+ setQuery(event.target.value);
263
+ onSearchChange?.(event.target.value);
264
+ setOpen(true);
265
+ }}
266
+ onBlur={(event) => {
267
+ onBlur?.(event);
268
+ setOpen(false);
269
+ resetSearch();
270
+ }}
271
+ onKeyDown={handleKeyDown}
272
+ className={cn(
273
+ "w-full min-w-0 rounded-input border-control bg-surface-control pl-3 text-control text-ink placeholder:text-ink-3 focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1 disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-danger",
274
+ size === "sm" ? "h-control-sm" : "h-input min-h-(--touch-target)",
275
+ hasClear ? "pr-8" : "pr-3",
276
+ classNames?.input,
277
+ )}
278
+ />
279
+ {hasClear ? (
280
+ <button
281
+ type="button"
282
+ aria-label={clearLabel ?? strings.clear}
283
+ onPointerDown={(event) => event.preventDefault()}
284
+ onMouseDown={(event) => event.preventDefault()}
285
+ onClick={clear}
286
+ className={cn(
287
+ "absolute inset-y-0 right-0 flex w-8 items-center justify-center rounded-input text-ink-3 outline-none hover:text-ink focus-visible:focus-ring",
288
+ classNames?.clear,
289
+ )}
290
+ >
291
+ <X aria-hidden="true" className="size-3.5" />
292
+ </button>
293
+ ) : null}
294
+ {name ? <input type="hidden" name={name} value={value} disabled={disabled} /> : null}
295
+ </div>
296
+ </PopoverPrimitive.Anchor>
297
+ <PopoverPrimitive.Portal container={container}>
298
+ <PopoverPrimitive.Content
299
+ role="presentation"
300
+ sideOffset={4}
301
+ collisionPadding={8}
302
+ align="start"
303
+ // Focus stays in the input, going in and out.
304
+ onOpenAutoFocus={(event) => event.preventDefault()}
305
+ onCloseAutoFocus={(event) => event.preventDefault()}
306
+ onInteractOutside={(event) => {
307
+ if (rootRef.current?.contains(event.detail.originalEvent.target as Node)) {
308
+ event.preventDefault();
309
+ }
310
+ }}
311
+ className={cn(
312
+ LISTBOX_SURFACE,
313
+ materialClass(material, "surface-solid"),
314
+ classNames?.content,
315
+ )}
316
+ >
317
+ {loading ? (
318
+ <p
319
+ role="status"
320
+ className={cn("px-2.5 py-1.5 text-ink-3 text-meta", classNames?.status)}
321
+ >
322
+ {loadingText ?? strings.loading}
323
+ </p>
324
+ ) : null}
325
+ {showEmpty ? (
326
+ <p
327
+ role="status"
328
+ className={cn("px-2.5 py-1.5 text-ink-3 text-meta", classNames?.status)}
329
+ >
330
+ {emptyText ?? strings.noResults}
331
+ </p>
332
+ ) : null}
333
+ <div
334
+ id={listId}
335
+ role="listbox"
336
+ data-ui-layer=""
337
+ hidden={!showList}
338
+ aria-label={ariaLabelledBy ? undefined : ariaLabel}
339
+ aria-labelledby={ariaLabelledBy}
340
+ >
341
+ {showList ? (
342
+ <ListboxItems
343
+ items={items}
344
+ flat={flat}
345
+ idBase={listId}
346
+ isSelected={(option) => option.value === value}
347
+ activeIndex={activeIndex}
348
+ onActivate={setActive}
349
+ onPick={pick}
350
+ optionClassName={classNames?.option}
351
+ groupClassName={classNames?.group}
352
+ />
353
+ ) : null}
354
+ </div>
355
+ </PopoverPrimitive.Content>
356
+ </PopoverPrimitive.Portal>
357
+ </PopoverPrimitive.Root>
358
+ );
359
+ }
@@ -0,0 +1,7 @@
1
+ export {
2
+ Combobox,
3
+ type ComboboxGroup,
4
+ type ComboboxOption,
5
+ type ComboboxPart,
6
+ type ComboboxProps,
7
+ } from "./combobox.js";