@flowstack-ui/agent-tools 0.1.0-bootstrap.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/.codex-plugin/plugin.json +37 -0
- package/CHANGELOG.md +21 -0
- package/LICENSE +21 -0
- package/README.md +125 -0
- package/docs/architecture.md +77 -0
- package/docs/releasing.md +26 -0
- package/docs/testing.md +32 -0
- package/package.json +63 -0
- package/public/index.json +2073 -0
- package/public/llms.txt +19 -0
- package/public/packages/atom/0.24.0/components/accordion.txt +131 -0
- package/public/packages/atom/0.24.0/components/alert-dialog.txt +112 -0
- package/public/packages/atom/0.24.0/components/app-bar.txt +96 -0
- package/public/packages/atom/0.24.0/components/aspect-ratio.txt +111 -0
- package/public/packages/atom/0.24.0/components/avatar.txt +119 -0
- package/public/packages/atom/0.24.0/components/badge.txt +123 -0
- package/public/packages/atom/0.24.0/components/bottom-navigation.txt +96 -0
- package/public/packages/atom/0.24.0/components/breadcrumb.txt +96 -0
- package/public/packages/atom/0.24.0/components/button.txt +98 -0
- package/public/packages/atom/0.24.0/components/carousel.txt +128 -0
- package/public/packages/atom/0.24.0/components/checkbox-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/checkbox.txt +100 -0
- package/public/packages/atom/0.24.0/components/clipboard.txt +112 -0
- package/public/packages/atom/0.24.0/components/collapsible.txt +112 -0
- package/public/packages/atom/0.24.0/components/color-picker.txt +117 -0
- package/public/packages/atom/0.24.0/components/combobox.txt +126 -0
- package/public/packages/atom/0.24.0/components/context-menu.txt +114 -0
- package/public/packages/atom/0.24.0/components/data-grid.txt +136 -0
- package/public/packages/atom/0.24.0/components/dialog.txt +116 -0
- package/public/packages/atom/0.24.0/components/direction.txt +132 -0
- package/public/packages/atom/0.24.0/components/divider.txt +94 -0
- package/public/packages/atom/0.24.0/components/drag-drop.txt +141 -0
- package/public/packages/atom/0.24.0/components/drawer.txt +96 -0
- package/public/packages/atom/0.24.0/components/dropdown-menu.txt +112 -0
- package/public/packages/atom/0.24.0/components/feed.txt +132 -0
- package/public/packages/atom/0.24.0/components/field.txt +108 -0
- package/public/packages/atom/0.24.0/components/fieldset.txt +96 -0
- package/public/packages/atom/0.24.0/components/file-upload.txt +120 -0
- package/public/packages/atom/0.24.0/components/form.txt +98 -0
- package/public/packages/atom/0.24.0/components/hover-card.txt +114 -0
- package/public/packages/atom/0.24.0/components/image.txt +94 -0
- package/public/packages/atom/0.24.0/components/input.txt +96 -0
- package/public/packages/atom/0.24.0/components/label.txt +121 -0
- package/public/packages/atom/0.24.0/components/link.txt +100 -0
- package/public/packages/atom/0.24.0/components/list.txt +131 -0
- package/public/packages/atom/0.24.0/components/listbox.txt +120 -0
- package/public/packages/atom/0.24.0/components/menu.txt +126 -0
- package/public/packages/atom/0.24.0/components/menubar.txt +120 -0
- package/public/packages/atom/0.24.0/components/modal.txt +118 -0
- package/public/packages/atom/0.24.0/components/multi-select.txt +120 -0
- package/public/packages/atom/0.24.0/components/nav-list.txt +104 -0
- package/public/packages/atom/0.24.0/components/navigation-menu.txt +104 -0
- package/public/packages/atom/0.24.0/components/number-input.txt +124 -0
- package/public/packages/atom/0.24.0/components/otp-field.txt +122 -0
- package/public/packages/atom/0.24.0/components/pagination.txt +111 -0
- package/public/packages/atom/0.24.0/components/password-toggle-field.txt +116 -0
- package/public/packages/atom/0.24.0/components/popover.txt +122 -0
- package/public/packages/atom/0.24.0/components/pressable.txt +94 -0
- package/public/packages/atom/0.24.0/components/progress.txt +130 -0
- package/public/packages/atom/0.24.0/components/radio-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/rating.txt +122 -0
- package/public/packages/atom/0.24.0/components/reorder.txt +141 -0
- package/public/packages/atom/0.24.0/components/scroll-area.txt +96 -0
- package/public/packages/atom/0.24.0/components/select.txt +126 -0
- package/public/packages/atom/0.24.0/components/sidebar.txt +96 -0
- package/public/packages/atom/0.24.0/components/skip-link.txt +96 -0
- package/public/packages/atom/0.24.0/components/slider.txt +124 -0
- package/public/packages/atom/0.24.0/components/swipeable-item.txt +118 -0
- package/public/packages/atom/0.24.0/components/switch.txt +116 -0
- package/public/packages/atom/0.24.0/components/table.txt +128 -0
- package/public/packages/atom/0.24.0/components/tabs.txt +96 -0
- package/public/packages/atom/0.24.0/components/textarea.txt +96 -0
- package/public/packages/atom/0.24.0/components/toast.txt +124 -0
- package/public/packages/atom/0.24.0/components/toggle-group.txt +118 -0
- package/public/packages/atom/0.24.0/components/toggle.txt +110 -0
- package/public/packages/atom/0.24.0/components/toolbar.txt +98 -0
- package/public/packages/atom/0.24.0/components/tooltip.txt +112 -0
- package/public/packages/atom/0.24.0/components/tree-grid.txt +138 -0
- package/public/packages/atom/0.24.0/components/tree.txt +138 -0
- package/public/packages/atom/0.24.0/components/visually-hidden.txt +119 -0
- package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt +55 -0
- package/public/packages/atom/0.24.0/docs/guides/getting-started.txt +65 -0
- package/public/packages/atom/0.24.0/docs/guides/imports.txt +26 -0
- package/public/packages/atom/0.24.0/docs/guides/public-api.txt +100 -0
- package/public/packages/atom/0.24.0/guides/behavior-composition.txt +277 -0
- package/public/packages/atom/0.24.0/guides/layer-selection.txt +807 -0
- package/public/packages/atom/0.24.0/index.txt +89 -0
- package/public/packages/brick/0.1.11/components/accordion.txt +158 -0
- package/public/packages/brick/0.1.11/components/alert-dialog.txt +175 -0
- package/public/packages/brick/0.1.11/components/app-bar.txt +134 -0
- package/public/packages/brick/0.1.11/components/appearance.txt +143 -0
- package/public/packages/brick/0.1.11/components/aspect-ratio.txt +136 -0
- package/public/packages/brick/0.1.11/components/avatar.txt +152 -0
- package/public/packages/brick/0.1.11/components/badge.txt +139 -0
- package/public/packages/brick/0.1.11/components/bleed.txt +104 -0
- package/public/packages/brick/0.1.11/components/bottom-navigation.txt +106 -0
- package/public/packages/brick/0.1.11/components/breadcrumb.txt +96 -0
- package/public/packages/brick/0.1.11/components/button.txt +103 -0
- package/public/packages/brick/0.1.11/components/card.txt +132 -0
- package/public/packages/brick/0.1.11/components/carousel.txt +206 -0
- package/public/packages/brick/0.1.11/components/checkbox-group.txt +175 -0
- package/public/packages/brick/0.1.11/components/checkbox.txt +103 -0
- package/public/packages/brick/0.1.11/components/chip.txt +128 -0
- package/public/packages/brick/0.1.11/components/code-block.txt +134 -0
- package/public/packages/brick/0.1.11/components/code.txt +120 -0
- package/public/packages/brick/0.1.11/components/collapsible.txt +179 -0
- package/public/packages/brick/0.1.11/components/color-picker.txt +135 -0
- package/public/packages/brick/0.1.11/components/color-swatch.txt +98 -0
- package/public/packages/brick/0.1.11/components/combobox.txt +157 -0
- package/public/packages/brick/0.1.11/components/container.txt +112 -0
- package/public/packages/brick/0.1.11/components/context-menu.txt +174 -0
- package/public/packages/brick/0.1.11/components/data-grid.txt +199 -0
- package/public/packages/brick/0.1.11/components/data-list.txt +115 -0
- package/public/packages/brick/0.1.11/components/dialog.txt +176 -0
- package/public/packages/brick/0.1.11/components/divider.txt +104 -0
- package/public/packages/brick/0.1.11/components/drawer.txt +146 -0
- package/public/packages/brick/0.1.11/components/dropdown-menu.txt +179 -0
- package/public/packages/brick/0.1.11/components/feed.txt +143 -0
- package/public/packages/brick/0.1.11/components/field.txt +115 -0
- package/public/packages/brick/0.1.11/components/fieldset.txt +103 -0
- package/public/packages/brick/0.1.11/components/file-upload.txt +154 -0
- package/public/packages/brick/0.1.11/components/form.txt +108 -0
- package/public/packages/brick/0.1.11/components/frame.txt +132 -0
- package/public/packages/brick/0.1.11/components/grid.txt +141 -0
- package/public/packages/brick/0.1.11/components/group.txt +136 -0
- package/public/packages/brick/0.1.11/components/hide.txt +121 -0
- package/public/packages/brick/0.1.11/components/hover-card.txt +156 -0
- package/public/packages/brick/0.1.11/components/icon-button.txt +119 -0
- package/public/packages/brick/0.1.11/components/icon.txt +160 -0
- package/public/packages/brick/0.1.11/components/image.txt +163 -0
- package/public/packages/brick/0.1.11/components/input.txt +101 -0
- package/public/packages/brick/0.1.11/components/link-box.txt +161 -0
- package/public/packages/brick/0.1.11/components/link.txt +133 -0
- package/public/packages/brick/0.1.11/components/list.txt +139 -0
- package/public/packages/brick/0.1.11/components/menubar.txt +174 -0
- package/public/packages/brick/0.1.11/components/multi-select.txt +153 -0
- package/public/packages/brick/0.1.11/components/nav-list.txt +130 -0
- package/public/packages/brick/0.1.11/components/navigation-menu.txt +150 -0
- package/public/packages/brick/0.1.11/components/notification-badge.txt +148 -0
- package/public/packages/brick/0.1.11/components/number-input.txt +150 -0
- package/public/packages/brick/0.1.11/components/otp-field.txt +146 -0
- package/public/packages/brick/0.1.11/components/pagination.txt +124 -0
- package/public/packages/brick/0.1.11/components/password-toggle-field.txt +146 -0
- package/public/packages/brick/0.1.11/components/popover.txt +181 -0
- package/public/packages/brick/0.1.11/components/progress-circle.txt +142 -0
- package/public/packages/brick/0.1.11/components/progress.txt +150 -0
- package/public/packages/brick/0.1.11/components/radio-group.txt +152 -0
- package/public/packages/brick/0.1.11/components/rating.txt +151 -0
- package/public/packages/brick/0.1.11/components/reorderable-list.txt +130 -0
- package/public/packages/brick/0.1.11/components/scroll-area.txt +110 -0
- package/public/packages/brick/0.1.11/components/section.txt +118 -0
- package/public/packages/brick/0.1.11/components/segment-group.txt +116 -0
- package/public/packages/brick/0.1.11/components/select.txt +157 -0
- package/public/packages/brick/0.1.11/components/show.txt +121 -0
- package/public/packages/brick/0.1.11/components/sidebar.txt +126 -0
- package/public/packages/brick/0.1.11/components/skeleton.txt +127 -0
- package/public/packages/brick/0.1.11/components/skip-link.txt +102 -0
- package/public/packages/brick/0.1.11/components/slider.txt +147 -0
- package/public/packages/brick/0.1.11/components/stack.txt +155 -0
- package/public/packages/brick/0.1.11/components/status.txt +110 -0
- package/public/packages/brick/0.1.11/components/surface.txt +194 -0
- package/public/packages/brick/0.1.11/components/swipeable-item.txt +154 -0
- package/public/packages/brick/0.1.11/components/switch.txt +152 -0
- package/public/packages/brick/0.1.11/components/table.txt +183 -0
- package/public/packages/brick/0.1.11/components/tabs.txt +136 -0
- package/public/packages/brick/0.1.11/components/text.txt +148 -0
- package/public/packages/brick/0.1.11/components/textarea.txt +101 -0
- package/public/packages/brick/0.1.11/components/toast.txt +150 -0
- package/public/packages/brick/0.1.11/components/toggle-group.txt +149 -0
- package/public/packages/brick/0.1.11/components/toggle.txt +140 -0
- package/public/packages/brick/0.1.11/components/toolbar.txt +118 -0
- package/public/packages/brick/0.1.11/components/tooltip.txt +156 -0
- package/public/packages/brick/0.1.11/components/tree-grid.txt +160 -0
- package/public/packages/brick/0.1.11/components/tree.txt +156 -0
- package/public/packages/brick/0.1.11/components/visually-hidden.txt +123 -0
- package/public/packages/brick/0.1.11/components/z-stack.txt +143 -0
- package/public/packages/brick/0.1.11/docs/guides/agent-knowledge.txt +67 -0
- package/public/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt +179 -0
- package/public/packages/brick/0.1.11/docs/guides/browser-support.txt +25 -0
- package/public/packages/brick/0.1.11/docs/guides/control-sizing.txt +59 -0
- package/public/packages/brick/0.1.11/docs/guides/installation.txt +79 -0
- package/public/packages/brick/0.1.11/docs/guides/theme-contract.txt +90 -0
- package/public/packages/brick/0.1.11/guides/interface-composition.txt +665 -0
- package/public/packages/brick/0.1.11/guides/layer-selection.txt +1437 -0
- package/public/packages/brick/0.1.11/index.txt +110 -0
- package/public/packages/colors/0.1.1/docs/agent-knowledge.txt +63 -0
- package/public/packages/colors/0.1.1/docs/architecture.txt +74 -0
- package/public/packages/colors/0.1.1/docs/color-foundations.txt +128 -0
- package/public/packages/colors/0.1.1/docs/compatibility.txt +75 -0
- package/public/packages/colors/0.1.1/docs/dependency-qualification.txt +117 -0
- package/public/packages/colors/0.1.1/docs/installation.txt +48 -0
- package/public/packages/colors/0.1.1/docs/palette-generation.txt +151 -0
- package/public/packages/colors/0.1.1/docs/releasing.txt +34 -0
- package/public/packages/colors/0.1.1/docs/testing.txt +51 -0
- package/public/packages/colors/0.1.1/guides/colors-system.txt +282 -0
- package/public/packages/colors/0.1.1/index.txt +29 -0
- package/public/packages/colors/0.1.1/operations/color-conversion.txt +14 -0
- package/public/packages/colors/0.1.1/operations/color-inspection.txt +23 -0
- package/public/packages/colors/0.1.1/operations/color-measurement.txt +18 -0
- package/public/packages/colors/0.1.1/operations/color-provenance.txt +14 -0
- package/public/packages/colors/0.1.1/operations/named-palette-reference.txt +15 -0
- package/public/packages/colors/0.1.1/operations/palette-candidate.txt +37 -0
- package/public/packages/theme/0.1.1/docs/agent-knowledge.txt +44 -0
- package/public/packages/theme/0.1.1/docs/appearances-and-portals.txt +41 -0
- package/public/packages/theme/0.1.1/docs/architecture.txt +121 -0
- package/public/packages/theme/0.1.1/docs/authoring.txt +141 -0
- package/public/packages/theme/0.1.1/docs/colors-interchange.txt +82 -0
- package/public/packages/theme/0.1.1/docs/fonts.txt +40 -0
- package/public/packages/theme/0.1.1/docs/installation.txt +45 -0
- package/public/packages/theme/0.1.1/docs/migration.txt +40 -0
- package/public/packages/theme/0.1.1/docs/testing.txt +64 -0
- package/public/packages/theme/0.1.1/docs/troubleshooting.txt +53 -0
- package/public/packages/theme/0.1.1/guides/theme-system.txt +340 -0
- package/public/packages/theme/0.1.1/index.txt +31 -0
- package/public/packages/theme/0.1.1/operations/brick-contract-compatibility.txt +35 -0
- package/public/packages/theme/0.1.1/operations/colors-interchange.txt +35 -0
- package/public/packages/theme/0.1.1/operations/theme-artifacts.txt +19 -0
- package/public/packages/theme/0.1.1/operations/theme-cli.txt +10 -0
- package/public/packages/theme/0.1.1/operations/theme-compilation.txt +23 -0
- package/public/packages/theme/0.1.1/operations/theme-definition.txt +36 -0
- package/public/packages/theme/0.1.1/operations/theme-validation.txt +19 -0
- package/public/tasks/data.txt +39 -0
- package/public/tasks/forms.txt +65 -0
- package/public/tasks/layout.txt +37 -0
- package/public/tasks/navigation.txt +51 -0
- package/public/tasks/overlays.txt +39 -0
- package/public/tasks/theming.txt +37 -0
- package/skills/flowstack-ui-builder/SKILL.md +35 -0
- package/skills/flowstack-ui-builder/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-builder/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-compose/SKILL.md +32 -0
- package/skills/flowstack-ui-compose/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-compose/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-maintainer/SKILL.md +40 -0
- package/skills/flowstack-ui-maintainer/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-maintainer/scripts/resolve-agent-knowledge.mjs +399 -0
- package/skills/flowstack-ui-review/SKILL.md +29 -0
- package/skills/flowstack-ui-review/agents/openai.yaml +4 -0
- package/skills/flowstack-ui-review/scripts/resolve-agent-knowledge.mjs +399 -0
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Checkbox
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: checkbox
|
|
6
|
+
|
|
7
|
+
# Checkbox agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide an independent checked, unchecked, or mixed selection with keyboard, pointer, touch, and form behavior.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A user independently turns an option on or off, or an aggregate parent represents mixed child selection.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- Exactly one option must be selected from a set. Use RadioGroup.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Checkbox.Root with Checkbox.Indicator and a visible associated label, usually inside Field.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Provide a visible label for each checkbox unless the visual context is truly redundant and an accessible name remains.
|
|
28
|
+
- **MUST:** Use checkbox semantics only for independently selectable values or a documented aggregate mixed state.
|
|
29
|
+
|
|
30
|
+
## Common mistakes
|
|
31
|
+
|
|
32
|
+
- **Avoid:** Using a checkbox for mutually exclusive choices. **Instead:** Use RadioGroup for a one-of-many decision.
|
|
33
|
+
|
|
34
|
+
## Validation checklist
|
|
35
|
+
|
|
36
|
+
- Toggle with Space and pointer/touch.
|
|
37
|
+
- Inspect checked or mixed state and submitted name/value.
|
|
38
|
+
- Confirm disabled state cannot change.
|
|
39
|
+
|
|
40
|
+
## Related guidance
|
|
41
|
+
|
|
42
|
+
- `field`
|
|
43
|
+
- `fieldset`
|
|
44
|
+
- `form`
|
|
45
|
+
- `radio-group`
|
|
46
|
+
|
|
47
|
+
## Machine record
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"schema": "flowstack.agent-component.v1",
|
|
52
|
+
"id": "checkbox",
|
|
53
|
+
"name": "Checkbox",
|
|
54
|
+
"package": "@flowstack-ui/atom",
|
|
55
|
+
"layer": "atom",
|
|
56
|
+
"kind": "component",
|
|
57
|
+
"purpose": "Provide an independent checked, unchecked, or mixed selection with keyboard, pointer, touch, and form behavior.",
|
|
58
|
+
"useWhen": [
|
|
59
|
+
"A user independently turns an option on or off, or an aggregate parent represents mixed child selection."
|
|
60
|
+
],
|
|
61
|
+
"avoidWhen": [
|
|
62
|
+
{
|
|
63
|
+
"condition": "Exactly one option must be selected from a set.",
|
|
64
|
+
"useInstead": "RadioGroup"
|
|
65
|
+
}
|
|
66
|
+
],
|
|
67
|
+
"composition": [
|
|
68
|
+
"Compose Checkbox.Root with Checkbox.Indicator and a visible associated label, usually inside Field."
|
|
69
|
+
],
|
|
70
|
+
"rules": [
|
|
71
|
+
{
|
|
72
|
+
"id": "checkbox-visible-label",
|
|
73
|
+
"level": "must",
|
|
74
|
+
"statement": "Provide a visible label for each checkbox unless the visual context is truly redundant and an accessible name remains."
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"id": "checkbox-independent-choice",
|
|
78
|
+
"level": "must",
|
|
79
|
+
"statement": "Use checkbox semantics only for independently selectable values or a documented aggregate mixed state."
|
|
80
|
+
}
|
|
81
|
+
],
|
|
82
|
+
"commonMistakes": [
|
|
83
|
+
{
|
|
84
|
+
"mistake": "Using a checkbox for mutually exclusive choices.",
|
|
85
|
+
"correction": "Use RadioGroup for a one-of-many decision."
|
|
86
|
+
}
|
|
87
|
+
],
|
|
88
|
+
"validation": [
|
|
89
|
+
"Toggle with Space and pointer/touch.",
|
|
90
|
+
"Inspect checked or mixed state and submitted name/value.",
|
|
91
|
+
"Confirm disabled state cannot change."
|
|
92
|
+
],
|
|
93
|
+
"related": [
|
|
94
|
+
"field",
|
|
95
|
+
"fieldset",
|
|
96
|
+
"form",
|
|
97
|
+
"radio-group"
|
|
98
|
+
]
|
|
99
|
+
}
|
|
100
|
+
```
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Clipboard
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: clipboard
|
|
6
|
+
|
|
7
|
+
# Clipboard agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Copy a known text value through an explicit user action while coordinating editable or displayed value, truthful asynchronous status, latest-operation ownership, and authored accessible feedback.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A user needs to copy a known command, URL, token, or code sample and the interface must report actual clipboard success or failure.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- The task reads, pastes, cuts, or copies files or binary data, or a normal Button without copy status is sufficient. Use an application-owned Clipboard API workflow or Button.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Root around a stably named Trigger and authored Status feedback. Add Label with Input when the value is editable or exposed as a field, Control for structure, ValueText for read-only display, and state-specific Indicator parts inside Status as needed.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Start copying only from an intentional Trigger activation and preserve consumer preventDefault cancellation, secure-context, permission, and browser Clipboard API requirements.
|
|
28
|
+
- **MUST:** Report copying, copied, and error only from the authoritative write result; never imply success when the API is unavailable or rejects.
|
|
29
|
+
- **MUST:** Keep the newest copy attempt authoritative when earlier asynchronous writes settle later and reset copied or error state only after the configured timeout.
|
|
30
|
+
- **MUST:** Give Trigger a stable accessible action name and put short authored success and failure wording in Status; Atom intentionally supplies no product strings.
|
|
31
|
+
- **MUST:** Use Clipboard for text writes only and do not add deprecated execCommand fallbacks that can misreport behavior.
|
|
32
|
+
|
|
33
|
+
## Common mistakes
|
|
34
|
+
|
|
35
|
+
- **Avoid:** Showing Copied immediately on click, swallowing permission errors, changing Trigger's accessible name unpredictably, or using Clipboard to read or transfer binary data. **Instead:** Wait for the write result, expose error feedback, keep a stable action name, and use an application-owned workflow for unsupported clipboard operations.
|
|
36
|
+
|
|
37
|
+
## Validation checklist
|
|
38
|
+
|
|
39
|
+
- Verify controlled/uncontrolled value editing, Label/Input association, ValueText, disabled behavior, pointer and keyboard Trigger activation, consumer cancellation, custom writeValue adapter, secure-context or unavailable API error, success, rejection, and focus remaining on Trigger.
|
|
40
|
+
- Verify idle/copying/copied/error Indicators, polite atomic Status announcements, timeout reset and cleanup, overlapping writes resolving and rejecting out of order, no stale status changes, native props, refs, and asChild/render semantics.
|
|
41
|
+
|
|
42
|
+
## Related guidance
|
|
43
|
+
|
|
44
|
+
- `button`
|
|
45
|
+
- `input`
|
|
46
|
+
|
|
47
|
+
## Machine record
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"schema": "flowstack.agent-component.v1",
|
|
52
|
+
"id": "clipboard",
|
|
53
|
+
"name": "Clipboard",
|
|
54
|
+
"package": "@flowstack-ui/atom",
|
|
55
|
+
"layer": "atom",
|
|
56
|
+
"kind": "component",
|
|
57
|
+
"purpose": "Copy a known text value through an explicit user action while coordinating editable or displayed value, truthful asynchronous status, latest-operation ownership, and authored accessible feedback.",
|
|
58
|
+
"useWhen": [
|
|
59
|
+
"A user needs to copy a known command, URL, token, or code sample and the interface must report actual clipboard success or failure."
|
|
60
|
+
],
|
|
61
|
+
"avoidWhen": [
|
|
62
|
+
{
|
|
63
|
+
"condition": "The task reads, pastes, cuts, or copies files or binary data, or a normal Button without copy status is sufficient.",
|
|
64
|
+
"useInstead": "an application-owned Clipboard API workflow or Button"
|
|
65
|
+
}
|
|
66
|
+
],
|
|
67
|
+
"composition": [
|
|
68
|
+
"Compose Root around a stably named Trigger and authored Status feedback. Add Label with Input when the value is editable or exposed as a field, Control for structure, ValueText for read-only display, and state-specific Indicator parts inside Status as needed."
|
|
69
|
+
],
|
|
70
|
+
"rules": [
|
|
71
|
+
{
|
|
72
|
+
"id": "clipboard-user-action",
|
|
73
|
+
"level": "must",
|
|
74
|
+
"statement": "Start copying only from an intentional Trigger activation and preserve consumer preventDefault cancellation, secure-context, permission, and browser Clipboard API requirements."
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"id": "clipboard-truthful-status",
|
|
78
|
+
"level": "must",
|
|
79
|
+
"statement": "Report copying, copied, and error only from the authoritative write result; never imply success when the API is unavailable or rejects."
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"id": "clipboard-latest-operation",
|
|
83
|
+
"level": "must",
|
|
84
|
+
"statement": "Keep the newest copy attempt authoritative when earlier asynchronous writes settle later and reset copied or error state only after the configured timeout."
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
"id": "clipboard-feedback",
|
|
88
|
+
"level": "must",
|
|
89
|
+
"statement": "Give Trigger a stable accessible action name and put short authored success and failure wording in Status; Atom intentionally supplies no product strings."
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"id": "clipboard-text-only",
|
|
93
|
+
"level": "must",
|
|
94
|
+
"statement": "Use Clipboard for text writes only and do not add deprecated execCommand fallbacks that can misreport behavior."
|
|
95
|
+
}
|
|
96
|
+
],
|
|
97
|
+
"commonMistakes": [
|
|
98
|
+
{
|
|
99
|
+
"mistake": "Showing Copied immediately on click, swallowing permission errors, changing Trigger's accessible name unpredictably, or using Clipboard to read or transfer binary data.",
|
|
100
|
+
"correction": "Wait for the write result, expose error feedback, keep a stable action name, and use an application-owned workflow for unsupported clipboard operations."
|
|
101
|
+
}
|
|
102
|
+
],
|
|
103
|
+
"validation": [
|
|
104
|
+
"Verify controlled/uncontrolled value editing, Label/Input association, ValueText, disabled behavior, pointer and keyboard Trigger activation, consumer cancellation, custom writeValue adapter, secure-context or unavailable API error, success, rejection, and focus remaining on Trigger.",
|
|
105
|
+
"Verify idle/copying/copied/error Indicators, polite atomic Status announcements, timeout reset and cleanup, overlapping writes resolving and rejecting out of order, no stale status changes, native props, refs, and asChild/render semantics."
|
|
106
|
+
],
|
|
107
|
+
"related": [
|
|
108
|
+
"button",
|
|
109
|
+
"input"
|
|
110
|
+
]
|
|
111
|
+
}
|
|
112
|
+
```
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Collapsible
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: collapsible
|
|
6
|
+
|
|
7
|
+
# Collapsible agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Show or hide one related block with disclosure-button semantics, linked region state, optional retained presence, orientation metadata, and measured intrinsic size.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- One clearly named control reveals one related inline block such as advanced settings, details, or filters.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- Several named disclosure sections form one set or the content must interrupt the page in a modal layer. Use Accordion or Dialog.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Root with one clearly named Trigger and its related Content. Use keepMounted only when retained closed DOM is required for state or exit animation, and choose orientation to describe the intended expansion axis to the styled layer.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Use one Root for one Trigger and related Content; use Accordion when several named sections need shared coordination.
|
|
28
|
+
- **MUST:** Give Trigger clear text or an accessible name describing the content it reveals and preserve its button, aria-expanded, aria-controls, disabled, Enter, and Space behavior.
|
|
29
|
+
- **MUST:** Preserve Content's region role, Trigger label relationship, open/closed visibility, and generated IDs rather than recreating disclosure ARIA.
|
|
30
|
+
- **MUST:** Leave keepMounted false unless retained DOM or exit animation is required; when true, preserve the closed hidden state and do not expose its descendants to interaction.
|
|
31
|
+
- **SHOULD:** Use orientation, data-initial-open, and live content size variables for styled motion while keeping visual animation policy outside Atom.
|
|
32
|
+
|
|
33
|
+
## Common mistakes
|
|
34
|
+
|
|
35
|
+
- **Avoid:** Using Collapsible for a coordinated accordion or modal, omitting a meaningful Trigger name, leaving closed retained content interactive, or hard-coding stale content height. **Instead:** Choose the correct owner, preserve the disclosure relationship and hidden state, and consume Atom's live measured size for optional styling.
|
|
36
|
+
|
|
37
|
+
## Validation checklist
|
|
38
|
+
|
|
39
|
+
- Verify controlled/uncontrolled open state, native and custom Trigger pointer/Enter/Space activation, accessible name, expanded and controls relationships, disabled behavior, Content region label, default unmount, keepMounted hidden state, and asChild/render composition.
|
|
40
|
+
- Verify vertical and horizontal metadata across all parts, initial-open state, measurement before entry paint, live width and height updates after responsive reflow and intrinsic content changes, exit presence, and no unintended page-load entrance motion.
|
|
41
|
+
|
|
42
|
+
## Related guidance
|
|
43
|
+
|
|
44
|
+
- `accordion`
|
|
45
|
+
- `dialog`
|
|
46
|
+
|
|
47
|
+
## Machine record
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"schema": "flowstack.agent-component.v1",
|
|
52
|
+
"id": "collapsible",
|
|
53
|
+
"name": "Collapsible",
|
|
54
|
+
"package": "@flowstack-ui/atom",
|
|
55
|
+
"layer": "atom",
|
|
56
|
+
"kind": "component",
|
|
57
|
+
"purpose": "Show or hide one related block with disclosure-button semantics, linked region state, optional retained presence, orientation metadata, and measured intrinsic size.",
|
|
58
|
+
"useWhen": [
|
|
59
|
+
"One clearly named control reveals one related inline block such as advanced settings, details, or filters."
|
|
60
|
+
],
|
|
61
|
+
"avoidWhen": [
|
|
62
|
+
{
|
|
63
|
+
"condition": "Several named disclosure sections form one set or the content must interrupt the page in a modal layer.",
|
|
64
|
+
"useInstead": "Accordion or Dialog"
|
|
65
|
+
}
|
|
66
|
+
],
|
|
67
|
+
"composition": [
|
|
68
|
+
"Compose Root with one clearly named Trigger and its related Content. Use keepMounted only when retained closed DOM is required for state or exit animation, and choose orientation to describe the intended expansion axis to the styled layer."
|
|
69
|
+
],
|
|
70
|
+
"rules": [
|
|
71
|
+
{
|
|
72
|
+
"id": "collapsible-one-disclosure",
|
|
73
|
+
"level": "must",
|
|
74
|
+
"statement": "Use one Root for one Trigger and related Content; use Accordion when several named sections need shared coordination."
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"id": "collapsible-trigger-name",
|
|
78
|
+
"level": "must",
|
|
79
|
+
"statement": "Give Trigger clear text or an accessible name describing the content it reveals and preserve its button, aria-expanded, aria-controls, disabled, Enter, and Space behavior."
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"id": "collapsible-region",
|
|
83
|
+
"level": "must",
|
|
84
|
+
"statement": "Preserve Content's region role, Trigger label relationship, open/closed visibility, and generated IDs rather than recreating disclosure ARIA."
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
"id": "collapsible-presence",
|
|
88
|
+
"level": "must",
|
|
89
|
+
"statement": "Leave keepMounted false unless retained DOM or exit animation is required; when true, preserve the closed hidden state and do not expose its descendants to interaction."
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"id": "collapsible-motion-metadata",
|
|
93
|
+
"level": "should",
|
|
94
|
+
"statement": "Use orientation, data-initial-open, and live content size variables for styled motion while keeping visual animation policy outside Atom."
|
|
95
|
+
}
|
|
96
|
+
],
|
|
97
|
+
"commonMistakes": [
|
|
98
|
+
{
|
|
99
|
+
"mistake": "Using Collapsible for a coordinated accordion or modal, omitting a meaningful Trigger name, leaving closed retained content interactive, or hard-coding stale content height.",
|
|
100
|
+
"correction": "Choose the correct owner, preserve the disclosure relationship and hidden state, and consume Atom's live measured size for optional styling."
|
|
101
|
+
}
|
|
102
|
+
],
|
|
103
|
+
"validation": [
|
|
104
|
+
"Verify controlled/uncontrolled open state, native and custom Trigger pointer/Enter/Space activation, accessible name, expanded and controls relationships, disabled behavior, Content region label, default unmount, keepMounted hidden state, and asChild/render composition.",
|
|
105
|
+
"Verify vertical and horizontal metadata across all parts, initial-open state, measurement before entry paint, live width and height updates after responsive reflow and intrinsic content changes, exit presence, and no unintended page-load entrance motion."
|
|
106
|
+
],
|
|
107
|
+
"related": [
|
|
108
|
+
"accordion",
|
|
109
|
+
"dialog"
|
|
110
|
+
]
|
|
111
|
+
}
|
|
112
|
+
```
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Color Picker
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: color-picker
|
|
6
|
+
|
|
7
|
+
# Color Picker agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide headless hexadecimal color selection with controlled or uncontrolled state, native picker access, preset selection, popover behavior, and form submission.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A form needs an editable hexadecimal color value, a native color chooser, preset color choices, or a popover that combines those inputs.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- The interface only previews a color and does not select or submit it. Use a styled-layer Color Swatch or a passive application element.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Place ColorPicker.Label and ColorPicker.Control inside ColorPicker.Root; include ColorPicker.HiddenInput when the value participates in form submission.
|
|
24
|
+
- Compose ColorPicker.Trigger with ColorPicker.Content for a floating picker, or omit both for an inline picker.
|
|
25
|
+
|
|
26
|
+
## Rules
|
|
27
|
+
|
|
28
|
+
- **MUST:** Give the editable and native color inputs an accessible name through ColorPicker.Label or an explicit aria-label.
|
|
29
|
+
- **MUST:** Provide name to ColorPicker.Root and render ColorPicker.HiddenInput when the selected value must submit with a form.
|
|
30
|
+
- **MUST:** Use CSS hexadecimal values in #rrggbb or #rgb form; Atom normalizes valid values to lowercase #rrggbb.
|
|
31
|
+
- **SHOULD:** Give preset triggers human-readable aria-label values when the raw color string is not a sufficient name.
|
|
32
|
+
|
|
33
|
+
## Common mistakes
|
|
34
|
+
|
|
35
|
+
- **Avoid:** Adding a visual swatch directly in Atom. **Instead:** Keep Atom headless and render the finished Color Swatch from Brick inside triggers or adjacent content.
|
|
36
|
+
- **Avoid:** Rendering a text input with no persistent label. **Instead:** Use ColorPicker.Label or provide an explicit accessible name.
|
|
37
|
+
|
|
38
|
+
## Validation checklist
|
|
39
|
+
|
|
40
|
+
- Test keyboard editing, native color selection, preset selection, controlled state, disabled and read-only behavior, and form submission.
|
|
41
|
+
- Verify invalid text is not committed and the last valid value is restored on blur.
|
|
42
|
+
|
|
43
|
+
## Related guidance
|
|
44
|
+
|
|
45
|
+
- `field`
|
|
46
|
+
- `form`
|
|
47
|
+
- `input`
|
|
48
|
+
- `popover`
|
|
49
|
+
|
|
50
|
+
## Machine record
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"schema": "flowstack.agent-component.v1",
|
|
55
|
+
"id": "color-picker",
|
|
56
|
+
"name": "Color Picker",
|
|
57
|
+
"package": "@flowstack-ui/atom",
|
|
58
|
+
"layer": "atom",
|
|
59
|
+
"kind": "component",
|
|
60
|
+
"purpose": "Provide headless hexadecimal color selection with controlled or uncontrolled state, native picker access, preset selection, popover behavior, and form submission.",
|
|
61
|
+
"useWhen": [
|
|
62
|
+
"A form needs an editable hexadecimal color value, a native color chooser, preset color choices, or a popover that combines those inputs."
|
|
63
|
+
],
|
|
64
|
+
"avoidWhen": [
|
|
65
|
+
{
|
|
66
|
+
"condition": "The interface only previews a color and does not select or submit it.",
|
|
67
|
+
"useInstead": "a styled-layer Color Swatch or a passive application element"
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
"composition": [
|
|
71
|
+
"Place ColorPicker.Label and ColorPicker.Control inside ColorPicker.Root; include ColorPicker.HiddenInput when the value participates in form submission.",
|
|
72
|
+
"Compose ColorPicker.Trigger with ColorPicker.Content for a floating picker, or omit both for an inline picker."
|
|
73
|
+
],
|
|
74
|
+
"rules": [
|
|
75
|
+
{
|
|
76
|
+
"id": "color-picker-label",
|
|
77
|
+
"level": "must",
|
|
78
|
+
"statement": "Give the editable and native color inputs an accessible name through ColorPicker.Label or an explicit aria-label."
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"id": "color-picker-form",
|
|
82
|
+
"level": "must",
|
|
83
|
+
"statement": "Provide name to ColorPicker.Root and render ColorPicker.HiddenInput when the selected value must submit with a form."
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"id": "color-picker-hex",
|
|
87
|
+
"level": "must",
|
|
88
|
+
"statement": "Use CSS hexadecimal values in #rrggbb or #rgb form; Atom normalizes valid values to lowercase #rrggbb."
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"id": "color-picker-preset-name",
|
|
92
|
+
"level": "should",
|
|
93
|
+
"statement": "Give preset triggers human-readable aria-label values when the raw color string is not a sufficient name."
|
|
94
|
+
}
|
|
95
|
+
],
|
|
96
|
+
"commonMistakes": [
|
|
97
|
+
{
|
|
98
|
+
"mistake": "Adding a visual swatch directly in Atom.",
|
|
99
|
+
"correction": "Keep Atom headless and render the finished Color Swatch from Brick inside triggers or adjacent content."
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"mistake": "Rendering a text input with no persistent label.",
|
|
103
|
+
"correction": "Use ColorPicker.Label or provide an explicit accessible name."
|
|
104
|
+
}
|
|
105
|
+
],
|
|
106
|
+
"validation": [
|
|
107
|
+
"Test keyboard editing, native color selection, preset selection, controlled state, disabled and read-only behavior, and form submission.",
|
|
108
|
+
"Verify invalid text is not committed and the last valid value is restored on blur."
|
|
109
|
+
],
|
|
110
|
+
"related": [
|
|
111
|
+
"field",
|
|
112
|
+
"form",
|
|
113
|
+
"input",
|
|
114
|
+
"popover"
|
|
115
|
+
]
|
|
116
|
+
}
|
|
117
|
+
```
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Combobox
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: combobox
|
|
6
|
+
|
|
7
|
+
# Combobox agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide editable option filtering and single-value selection with independent committed value, input text, and popup state, plus listbox focus, positioning, dismissal, and form validation.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- Users should type to find one option in a longer collection, with optional explicitly allowed free-form entry.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- Typing is unnecessary, choices should remain visible, several values are selected, or arbitrary input is not valid. Use Select, Listbox, MultiSelect, or Combobox without freeSolo.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Provide Root options and an accessible Input, preferably inside Control with optional Clear and Trigger so Content positions from the complete visible control. Inside optional Portal and Content, render exactly one Listbox containing an Item for each available filtered option plus optional Group with Label, Empty, and Loading states.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Treat committed value, editable inputValue, and open state as independent controllable contracts and route each controlled prop through its matching callback.
|
|
28
|
+
- **MUST:** Give Root the complete stable option data and render matching uniquely valued Items for filtered options; mark disabled options and keep labels consistent with filtering and display.
|
|
29
|
+
- **MUST:** Enable freeSolo only when arbitrary typed values are valid domain values, and choose clearOnSelect deliberately for both option and free-form commits.
|
|
30
|
+
- **MUST:** Give Input an accessible Label or native relationship and preserve its combobox, listbox, active-descendant, editable focus, Arrow/Home/End, Enter, Escape, Tab, open-on-focus, and pointer-selection suppression behavior.
|
|
31
|
+
- **MUST:** Treat only the committed logical value as satisfying required validity; display text alone must not satisfy the aligned native value proxy.
|
|
32
|
+
- **MUST:** Keep Content as positioning and dismissal owner and Listbox as the semantic option owner; use preventDefault on onInteractOutside rather than competing document listeners.
|
|
33
|
+
|
|
34
|
+
## Common mistakes
|
|
35
|
+
|
|
36
|
+
- **Avoid:** Conflating input text with committed value, enabling freeSolo for a closed vocabulary, omitting rendered Items for options, or putting listbox role on Content instead of Listbox. **Instead:** Manage the three states explicitly, restrict freeSolo to valid arbitrary values, keep option data and Items aligned, and preserve the compound semantic owners.
|
|
37
|
+
|
|
38
|
+
## Validation checklist
|
|
39
|
+
|
|
40
|
+
- Verify controlled/uncontrolled committed value, input text, and open state; default label initialization; filtering and grouping; disabled options; Input typing; Arrow/Home/End; Enter option and freeSolo commits; Escape close-then-clear; Tab; openOnFocus with Empty; Clear; Trigger mobile focus; pointer selection; and clearOnSelect.
|
|
41
|
+
- Verify Label and Field relationships, required committed-value validity, inline/native validation focus, hidden named value and external form, reset, loading/empty states, Control-sized collision positioning, portals, completed mouse/touch/pen/virtual outside dismissal, cancellation, and highlighted-item scrolling.
|
|
42
|
+
|
|
43
|
+
## Related guidance
|
|
44
|
+
|
|
45
|
+
- `select`
|
|
46
|
+
- `listbox`
|
|
47
|
+
- `multi-select`
|
|
48
|
+
- `input`
|
|
49
|
+
- `field`
|
|
50
|
+
- `form`
|
|
51
|
+
|
|
52
|
+
## Machine record
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"schema": "flowstack.agent-component.v1",
|
|
57
|
+
"id": "combobox",
|
|
58
|
+
"name": "Combobox",
|
|
59
|
+
"package": "@flowstack-ui/atom",
|
|
60
|
+
"layer": "atom",
|
|
61
|
+
"kind": "component",
|
|
62
|
+
"purpose": "Provide editable option filtering and single-value selection with independent committed value, input text, and popup state, plus listbox focus, positioning, dismissal, and form validation.",
|
|
63
|
+
"useWhen": [
|
|
64
|
+
"Users should type to find one option in a longer collection, with optional explicitly allowed free-form entry."
|
|
65
|
+
],
|
|
66
|
+
"avoidWhen": [
|
|
67
|
+
{
|
|
68
|
+
"condition": "Typing is unnecessary, choices should remain visible, several values are selected, or arbitrary input is not valid.",
|
|
69
|
+
"useInstead": "Select, Listbox, MultiSelect, or Combobox without freeSolo"
|
|
70
|
+
}
|
|
71
|
+
],
|
|
72
|
+
"composition": [
|
|
73
|
+
"Provide Root options and an accessible Input, preferably inside Control with optional Clear and Trigger so Content positions from the complete visible control. Inside optional Portal and Content, render exactly one Listbox containing an Item for each available filtered option plus optional Group with Label, Empty, and Loading states."
|
|
74
|
+
],
|
|
75
|
+
"rules": [
|
|
76
|
+
{
|
|
77
|
+
"id": "combobox-three-states",
|
|
78
|
+
"level": "must",
|
|
79
|
+
"statement": "Treat committed value, editable inputValue, and open state as independent controllable contracts and route each controlled prop through its matching callback."
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"id": "combobox-options-items",
|
|
83
|
+
"level": "must",
|
|
84
|
+
"statement": "Give Root the complete stable option data and render matching uniquely valued Items for filtered options; mark disabled options and keep labels consistent with filtering and display."
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
"id": "combobox-free-solo",
|
|
88
|
+
"level": "must",
|
|
89
|
+
"statement": "Enable freeSolo only when arbitrary typed values are valid domain values, and choose clearOnSelect deliberately for both option and free-form commits."
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"id": "combobox-name-focus",
|
|
93
|
+
"level": "must",
|
|
94
|
+
"statement": "Give Input an accessible Label or native relationship and preserve its combobox, listbox, active-descendant, editable focus, Arrow/Home/End, Enter, Escape, Tab, open-on-focus, and pointer-selection suppression behavior."
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"id": "combobox-committed-validity",
|
|
98
|
+
"level": "must",
|
|
99
|
+
"statement": "Treat only the committed logical value as satisfying required validity; display text alone must not satisfy the aligned native value proxy."
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"id": "combobox-popup",
|
|
103
|
+
"level": "must",
|
|
104
|
+
"statement": "Keep Content as positioning and dismissal owner and Listbox as the semantic option owner; use preventDefault on onInteractOutside rather than competing document listeners."
|
|
105
|
+
}
|
|
106
|
+
],
|
|
107
|
+
"commonMistakes": [
|
|
108
|
+
{
|
|
109
|
+
"mistake": "Conflating input text with committed value, enabling freeSolo for a closed vocabulary, omitting rendered Items for options, or putting listbox role on Content instead of Listbox.",
|
|
110
|
+
"correction": "Manage the three states explicitly, restrict freeSolo to valid arbitrary values, keep option data and Items aligned, and preserve the compound semantic owners."
|
|
111
|
+
}
|
|
112
|
+
],
|
|
113
|
+
"validation": [
|
|
114
|
+
"Verify controlled/uncontrolled committed value, input text, and open state; default label initialization; filtering and grouping; disabled options; Input typing; Arrow/Home/End; Enter option and freeSolo commits; Escape close-then-clear; Tab; openOnFocus with Empty; Clear; Trigger mobile focus; pointer selection; and clearOnSelect.",
|
|
115
|
+
"Verify Label and Field relationships, required committed-value validity, inline/native validation focus, hidden named value and external form, reset, loading/empty states, Control-sized collision positioning, portals, completed mouse/touch/pen/virtual outside dismissal, cancellation, and highlighted-item scrolling."
|
|
116
|
+
],
|
|
117
|
+
"related": [
|
|
118
|
+
"select",
|
|
119
|
+
"listbox",
|
|
120
|
+
"multi-select",
|
|
121
|
+
"input",
|
|
122
|
+
"field",
|
|
123
|
+
"form"
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|