@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 +132 -2
- package/dist/combobox/combobox.d.ts +13 -0
- package/dist/combobox/style.d.ts +8 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.js +1575 -0
- package/dist/index.js.map +7 -0
- package/dist/multi-select/multi-select.d.ts +19 -0
- package/dist/select/select-options.d.ts +18 -0
- package/dist/select/select.d.ts +13 -0
- package/dist/select/style.d.ts +12 -0
- package/dist/shared/combobox-options.d.ts +20 -0
- package/dist/shared/options.d.ts +9 -0
- package/dist/shared/scroll-option.d.ts +8 -0
- package/dist/shared/selection-actions.d.ts +13 -0
- package/dist/shared/selection-form.d.ts +18 -0
- package/dist/shared/style.d.ts +15 -0
- package/dist/shared/types.d.ts +49 -0
- package/dist/shared/use-search-options.d.ts +20 -0
- package/dist/shared/use-selection-popup.d.ts +24 -0
- package/dist/shared/use-selection-value.d.ts +16 -0
- package/dist/styles.css +264 -0
- package/package.json +54 -3
package/README.md
CHANGED
|
@@ -1,3 +1,133 @@
|
|
|
1
|
-
#
|
|
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;
|
package/dist/index.d.ts
ADDED
|
@@ -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";
|