@gridui/select 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,133 @@
1
- # Temporary Holding Version
1
+ # @gridui/select
2
+
3
+ Core family. Public API: `Combobox`, `ComboboxProps`, `MultiSelect`, `MultiSelectProps`, `Select`, `SelectAction`, `SelectGroup`, `SelectOption`, `SelectProps`.
4
+
5
+ Import components from `@gridui/select` and load `@gridui/select/styles.css` after Theme.
6
+ Load styles for any composed dependency used by this family. Applications own routes, labels, state persistence, and branding.
7
+
8
+ See [component ownership](../../docs/component-ownership.md) and [release history](.changeset/history/).
9
+
10
+ ## Select and Combobox
11
+
12
+ `Select` and `Combobox` share options, actions, selection state, form integration,
13
+ and the dropdown surface, highlight, indicators, typography, and motion.
14
+ Radix Select owns option navigation; Combobox combines Radix Popover with a
15
+ native editable input and an active-descendant listbox.
16
+ Each popup contains an option listbox and a separate action footer; buttons and
17
+ links never masquerade as options. Select defaults to `position="popper"`, opening
18
+ below the trigger and flipping at viewport edges. `position="item-aligned"` places
19
+ the selected item over the trigger when space permits, with a viewport-safe
20
+ fallback. Both modes match the trigger's outer width and limit height to available
21
+ space. The option list scrolls independently of actions. Standard and small
22
+ triggers retain 2.75rem and 2.25rem minimum heights. Option labels and descriptions wrap;
23
+ the editable input displays one line. `portalContainer` can keep popups within an
24
+ enclosing overlay's ownership and focus boundary. Inside a Modal or Drawer,
25
+ use `portalContainer` when the popup must inherit a local theme or custom portal
26
+ location. Radix layers coordinate nested focus and Escape handling. Attach a
27
+ custom container to the panel, not its scrolling body, to avoid clipping menus.
28
+
29
+ `options` accepts `SelectOption` entries or `SelectGroup` entries with `label`
30
+ and `options`. Option values must be unique across groups; group labels must be
31
+ unique. Each option has a string `label`, optional string `description`, decorative
32
+ `icon` React node, and `disabled`. Descriptions wrap below labels. Select shows the label and icon in its trigger;
33
+ Combobox shows the label in its input. Do not put interactive content in icons.
34
+
35
+ Use `value` / `onValueChange` for controlled state or `defaultValue` for local
36
+ state. The default value is empty; no option is implicitly selected. A selected
37
+ value missing from `options` displays its raw value and remains in native form
38
+ submission until its matching option arrives. An explicit
39
+ empty-valued option is supported for filters such as “All statuses”. Otherwise,
40
+ `placeholder` supplies empty-state text. Provide a label through `Label.htmlFor`
41
+ and `id`, or an accessible name on the trigger. Select forwards button props and
42
+ refs; Combobox forwards input props and refs.
43
+ For both components, `name`, `form`, `required`, and `disabled` configure the native hidden
44
+ select used for form submission and constraints. Invalid controls focus the
45
+ visible trigger. Native form reset restores initial values; controlled callers
46
+ receive resets through `onValueChange`, including while disabled. A cancelled reset
47
+ has no effect. Setting `disabled` on an open control closes its popup;
48
+ re-enabling it leaves the popup closed. Combobox also closes and clears its
49
+ search when it becomes read-only; making it editable again does not reopen it. Selections and actions also check inherited
50
+ fieldset availability at activation time, rejecting stale portalled interactions.
51
+
52
+ Supplying a localized `clearLabel` adds a separate clear button. It emits the
53
+ empty string and returns focus to the trigger. Clearing is disabled for required,
54
+ disabled, or already-empty controls.
55
+ Combobox also disables clearing while `readOnly`; external controlled updates and
56
+ native form reset retain their normal behavior.
57
+
58
+ ### Actions
59
+
60
+ Both components accept `actions: readonly SelectAction[]`. Each action has a
61
+ unique `id`, `label`, optional decorative `icon`, and optional `disabled`.
62
+ Provide either `href` (with optional `target` and `rel`) for a native link or
63
+ `onAction` for a button callback. Actions never update the selected value or emit
64
+ `onValueChange`. They remain available when there
65
+ are no matching options. No implicit option creation takes place.
66
+
67
+ Actions close the popup by default; `closeOnAction: false` keeps it open.
68
+ Closing restores trigger focus before the callback runs, allowing a callback
69
+ to open a dialog or focus another control without later focus theft. Links keep
70
+ native navigation and modified-click behavior. Disabled actions are skipped in
71
+ the Tab sequence. Actions are outside the option listbox and cannot be reached
72
+ or selected with option-navigation keys.
73
+
74
+ ### Search and keyboard interaction
75
+
76
+ `Combobox` searches directly in its editable trigger. Supply localized
77
+ `searchLabel` and `emptyLabel` strings. A visible `Label` associated through `id`
78
+ or an explicit accessible name takes precedence over the search-label fallback.
79
+ Search filters labels and descriptions using case-insensitive, NFKC-normalized
80
+ substring matching. Empty groups disappear; disabled matches remain visible.
81
+ Typing does not commit a selection. Selecting commits the label to the input;
82
+ Escape, outside dismissal, or closing actions restore the selected label.
83
+ Actions that keep the popup open preserve the current query.
84
+
85
+ Select opens with Enter, Space, or arrow keys and focuses the selected option.
86
+ Up/Down navigate enabled options; Home/End and timed character-prefix navigation
87
+ are also supported. Enter or Space commits. Combobox preserves native editing
88
+ and IME composition; typing or its arrow button opens the list, Up/Down move the
89
+ active option, and Enter commits enabled options. GridUI allows highlighting
90
+ disabled Combobox options for discovery; activating them never commits.
91
+ Its input retains DOM focus and exposes the
92
+ active option through `aria-activedescendant`. If options change during search,
93
+ the highlight stays on its current result when present, otherwise it falls back
94
+ to the first current result. Enter always uses the current result collection. Escape dismisses without committing
95
+ and returns focus to the trigger, leaving an enclosing owner open. Tab/Shift+Tab
96
+ reach independent actions; disabled actions are skipped. Pointer dismissal leaves
97
+ focus with the outside target.
98
+
99
+ ### Server rendering
100
+
101
+ Selected labels, icons, and native form values are rendered explicitly during
102
+ SSR, including grouped options and `defaultValue`. The editable trigger renders
103
+ its selected label before hydration; a closed popup does not render options or
104
+ execute actions. The client hydrates before popup interaction;
105
+ keep server and client initial values/options identical. Browser verification
106
+ hydrates real Node-rendered HTML and exercises selection, reset, filtering,
107
+ independent actions, focus handoff, and empty results across the viewport matrix.
108
+ Remote search and implicit option creation are not included. Use MultiSelect for multiple selection.
109
+
110
+
111
+ ## Implementation and lifecycle
112
+
113
+ Select uses Radix Select; Combobox composes Radix Popover with a native input, sharing the GridUI
114
+ surface, typography, spacing, and highlights. Select defaults to `position="popper"`;
115
+ `position="item-aligned"` aligns the selected item with the trigger when space permits.
116
+ Both modes use the trigger width, including borders and padding.
117
+
118
+ Within `src/select/`, `select.tsx` and `combobox.tsx` own their trigger and popup
119
+ compositions. Their option renderers stay separate because Select owns item-text
120
+ alignment while Combobox owns a filtered collection. Radix owns positioning and
121
+ dismissal. Select delegates option navigation to Radix; Combobox owns its
122
+ editable input and active-descendant keyboard model. `use-selection-value.ts`
123
+ owns controlled/local selection and initial-value reset. `use-selection-popup.ts`
124
+ owns availability, open/close transitions, and focus handoff. Combobox and
125
+ MultiSelect share query, current-result highlighting, and keyboard movement through
126
+ `use-search-options.ts`; option replacement never leaves an invalid active item. `selection-form.tsx` owns native form association, validation, and cancellable
127
+ reset observation. `selection-actions.tsx` renders independent links and buttons.
128
+
129
+ `types.ts` owns shared option, action, and selection contracts; `options.ts` owns
130
+ pure filtering and flattening; `style.ts` owns shared presentation. Internal parts
131
+ are not package exports. See the selection contract
132
+ for keyboard, form, server-rendering, and focus guarantees protected by browser tests.
2
133
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Select
4
+ * @namespace Combobox
5
+ * @description Combobox
6
+ */
7
+ import type { SelectionProps } from "../shared/types";
8
+ import { type ComponentPropsWithRef, type FC } from "react";
9
+ export type ComboboxProps = Omit<ComponentPropsWithRef<"input">, "children" | "value" | "defaultValue" | "onChange" | "type" | "size"> & SelectionProps & {
10
+ readonly searchLabel: string;
11
+ readonly emptyLabel: string;
12
+ };
13
+ export declare const Combobox: FC<ComboboxProps>;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Select
4
+ * @namespace Combobox
5
+ * @description Style
6
+ */
7
+ export declare const comboboxInputStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
8
+ export declare const comboboxTriggerStyles: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Select
4
+ * @namespace Root
5
+ * @description Index
6
+ */
7
+ export type { ComboboxProps } from "./combobox/combobox";
8
+ export { Combobox } from "./combobox/combobox";
9
+ export type { MultiSelectProps } from "./multi-select/multi-select";
10
+ export { MultiSelect } from "./multi-select/multi-select";
11
+ export type { SelectProps } from "./select/select";
12
+ export { Select } from "./select/select";
13
+ export type { SelectAction } from "./shared/types";
14
+ export type { SelectGroup } from "./shared/types";
15
+ export type { SelectOption } from "./shared/types";