@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,141 @@
|
|
|
1
|
+
# DragDrop
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: drag-drop
|
|
6
|
+
|
|
7
|
+
# DragDrop agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide headless same-document drag lifecycle, pointer and keyboard input, target resolution, cancellation, and accessible announcements for components that define their own movement rules.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- Building a reusable collection component whose items move between explicit same-document targets and whose product-specific rules cannot be represented by Reorder.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- The user is only arranging a single linear list. Use Reorder.
|
|
20
|
+
- The task is automatic data sorting, native file transfer, freeform canvas placement, or movement between tree parents. Use the relevant collection, file, canvas, or tree-specific behavior.
|
|
21
|
+
|
|
22
|
+
## Required composition
|
|
23
|
+
|
|
24
|
+
- Place Draggable and DropTarget parts within Root; nest Handle inside each Draggable and provide a human label for every source and target.
|
|
25
|
+
- Provide localized Root instructions and message functions, and convert onDragEnd details into application or adapter state only after a valid release.
|
|
26
|
+
- Add a visible simple-pointer alternative appropriate to the surrounding interface; generic dragging alone does not satisfy that requirement.
|
|
27
|
+
|
|
28
|
+
## Rules
|
|
29
|
+
|
|
30
|
+
- **MUST:** Use an explicitly labelled native Handle and preserve its focus across keyed item movement.
|
|
31
|
+
- **MUST:** Commit pointer movement only on release over a valid target; pointer cancellation, Escape, and invalid release must preserve application order.
|
|
32
|
+
- **MUST:** Provide a visible non-dragging simple-pointer operation for every movement job.
|
|
33
|
+
- **MUST:** Use stable application identities for source and target values; never use a changing visual index as identity.
|
|
34
|
+
- **SHOULD:** Prefer a collection-specific adapter such as Reorder, DataGrid, Tree, or Kanban over exposing generic drag events directly in finished application UI.
|
|
35
|
+
|
|
36
|
+
## Common mistakes
|
|
37
|
+
|
|
38
|
+
- **Avoid:** Using DragDrop directly for a normal sortable list or treating data sort order as manual item order. **Instead:** Use Reorder for one-dimensional manual arrangement and keep query sorting separate.
|
|
39
|
+
- **Avoid:** Depending on drag gestures or keyboard movement as the only alternatives. **Instead:** Add visible one-activation movement controls or another contextual simple-pointer alternative.
|
|
40
|
+
- **Avoid:** Mutating application objects during pointer movement. **Instead:** Render transient data attributes during movement and update controlled application state only from a completed drop.
|
|
41
|
+
|
|
42
|
+
## Validation checklist
|
|
43
|
+
|
|
44
|
+
- Verify mouse, pen, touch-delay, keyboard, Escape, pointer cancellation, invalid release, and focus continuity.
|
|
45
|
+
- Verify localized instructions and announcements use human labels and one-based positions.
|
|
46
|
+
- Verify disabled/read-only sources and targets, vertical/horizontal direction, RTL, zoom, and a visible simple-pointer alternative.
|
|
47
|
+
- Verify values remain stable while the surrounding collection reorders or updates.
|
|
48
|
+
|
|
49
|
+
## Related guidance
|
|
50
|
+
|
|
51
|
+
- `reorder`
|
|
52
|
+
- `collection`
|
|
53
|
+
- `data-grid`
|
|
54
|
+
- `tree`
|
|
55
|
+
- `file-upload`
|
|
56
|
+
|
|
57
|
+
## Machine record
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"schema": "flowstack.agent-component.v1",
|
|
62
|
+
"id": "drag-drop",
|
|
63
|
+
"name": "DragDrop",
|
|
64
|
+
"package": "@flowstack-ui/atom",
|
|
65
|
+
"layer": "atom",
|
|
66
|
+
"kind": "component",
|
|
67
|
+
"purpose": "Provide headless same-document drag lifecycle, pointer and keyboard input, target resolution, cancellation, and accessible announcements for components that define their own movement rules.",
|
|
68
|
+
"useWhen": [
|
|
69
|
+
"Building a reusable collection component whose items move between explicit same-document targets and whose product-specific rules cannot be represented by Reorder."
|
|
70
|
+
],
|
|
71
|
+
"avoidWhen": [
|
|
72
|
+
{
|
|
73
|
+
"condition": "The user is only arranging a single linear list.",
|
|
74
|
+
"useInstead": "Reorder"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"condition": "The task is automatic data sorting, native file transfer, freeform canvas placement, or movement between tree parents.",
|
|
78
|
+
"useInstead": "the relevant collection, file, canvas, or tree-specific behavior"
|
|
79
|
+
}
|
|
80
|
+
],
|
|
81
|
+
"composition": [
|
|
82
|
+
"Place Draggable and DropTarget parts within Root; nest Handle inside each Draggable and provide a human label for every source and target.",
|
|
83
|
+
"Provide localized Root instructions and message functions, and convert onDragEnd details into application or adapter state only after a valid release.",
|
|
84
|
+
"Add a visible simple-pointer alternative appropriate to the surrounding interface; generic dragging alone does not satisfy that requirement."
|
|
85
|
+
],
|
|
86
|
+
"rules": [
|
|
87
|
+
{
|
|
88
|
+
"id": "drag-drop-explicit-handle",
|
|
89
|
+
"level": "must",
|
|
90
|
+
"statement": "Use an explicitly labelled native Handle and preserve its focus across keyed item movement."
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"id": "drag-drop-release-cancel",
|
|
94
|
+
"level": "must",
|
|
95
|
+
"statement": "Commit pointer movement only on release over a valid target; pointer cancellation, Escape, and invalid release must preserve application order."
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"id": "drag-drop-alternative",
|
|
99
|
+
"level": "must",
|
|
100
|
+
"statement": "Provide a visible non-dragging simple-pointer operation for every movement job."
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
"id": "drag-drop-stable-identity",
|
|
104
|
+
"level": "must",
|
|
105
|
+
"statement": "Use stable application identities for source and target values; never use a changing visual index as identity."
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
"id": "drag-drop-context-boundary",
|
|
109
|
+
"level": "should",
|
|
110
|
+
"statement": "Prefer a collection-specific adapter such as Reorder, DataGrid, Tree, or Kanban over exposing generic drag events directly in finished application UI."
|
|
111
|
+
}
|
|
112
|
+
],
|
|
113
|
+
"commonMistakes": [
|
|
114
|
+
{
|
|
115
|
+
"mistake": "Using DragDrop directly for a normal sortable list or treating data sort order as manual item order.",
|
|
116
|
+
"correction": "Use Reorder for one-dimensional manual arrangement and keep query sorting separate."
|
|
117
|
+
},
|
|
118
|
+
{
|
|
119
|
+
"mistake": "Depending on drag gestures or keyboard movement as the only alternatives.",
|
|
120
|
+
"correction": "Add visible one-activation movement controls or another contextual simple-pointer alternative."
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
"mistake": "Mutating application objects during pointer movement.",
|
|
124
|
+
"correction": "Render transient data attributes during movement and update controlled application state only from a completed drop."
|
|
125
|
+
}
|
|
126
|
+
],
|
|
127
|
+
"validation": [
|
|
128
|
+
"Verify mouse, pen, touch-delay, keyboard, Escape, pointer cancellation, invalid release, and focus continuity.",
|
|
129
|
+
"Verify localized instructions and announcements use human labels and one-based positions.",
|
|
130
|
+
"Verify disabled/read-only sources and targets, vertical/horizontal direction, RTL, zoom, and a visible simple-pointer alternative.",
|
|
131
|
+
"Verify values remain stable while the surrounding collection reorders or updates."
|
|
132
|
+
],
|
|
133
|
+
"related": [
|
|
134
|
+
"reorder",
|
|
135
|
+
"collection",
|
|
136
|
+
"data-grid",
|
|
137
|
+
"tree",
|
|
138
|
+
"file-upload"
|
|
139
|
+
]
|
|
140
|
+
}
|
|
141
|
+
```
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Drawer
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: drawer
|
|
6
|
+
|
|
7
|
+
# Drawer agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide modal side-sheet behavior, focus management, dismissal, portal composition, and edge-placement metadata.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A modal task or navigation panel enters from an edge and background content must be unavailable while open.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- The panel is centered, non-modal, or permanently part of page layout. Use Dialog or an inline panel.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Trigger and Portal containing Overlay and Content; place Title, Description, and Close inside Content and supply the labeling parts the content requires.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Use Drawer-owned focus trap, focus restoration, scroll lock, Escape, backdrop, and portal behavior instead of rebuilding them.
|
|
28
|
+
- **MUST:** Give Content an accessible name with Title or an explicit labeling relationship.
|
|
29
|
+
|
|
30
|
+
## Common mistakes
|
|
31
|
+
|
|
32
|
+
- **Avoid:** Using Drawer only for its edge appearance while leaving background controls interactive. **Instead:** Use Drawer for modal behavior or use a normal inline region when interaction should remain available.
|
|
33
|
+
|
|
34
|
+
## Validation checklist
|
|
35
|
+
|
|
36
|
+
- Test trigger focus, initial focus, Tab containment, Escape and backdrop dismissal, Close, scroll lock, and focus return.
|
|
37
|
+
- Confirm nested portals remain within the modal contract.
|
|
38
|
+
|
|
39
|
+
## Related guidance
|
|
40
|
+
|
|
41
|
+
- `dialog`
|
|
42
|
+
- `sidebar`
|
|
43
|
+
- `navigation-menu`
|
|
44
|
+
|
|
45
|
+
## Machine record
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"schema": "flowstack.agent-component.v1",
|
|
50
|
+
"id": "drawer",
|
|
51
|
+
"name": "Drawer",
|
|
52
|
+
"package": "@flowstack-ui/atom",
|
|
53
|
+
"layer": "atom",
|
|
54
|
+
"kind": "component",
|
|
55
|
+
"purpose": "Provide modal side-sheet behavior, focus management, dismissal, portal composition, and edge-placement metadata.",
|
|
56
|
+
"useWhen": [
|
|
57
|
+
"A modal task or navigation panel enters from an edge and background content must be unavailable while open."
|
|
58
|
+
],
|
|
59
|
+
"avoidWhen": [
|
|
60
|
+
{
|
|
61
|
+
"condition": "The panel is centered, non-modal, or permanently part of page layout.",
|
|
62
|
+
"useInstead": "Dialog or an inline panel"
|
|
63
|
+
}
|
|
64
|
+
],
|
|
65
|
+
"composition": [
|
|
66
|
+
"Compose Trigger and Portal containing Overlay and Content; place Title, Description, and Close inside Content and supply the labeling parts the content requires."
|
|
67
|
+
],
|
|
68
|
+
"rules": [
|
|
69
|
+
{
|
|
70
|
+
"id": "drawer-modal-contract",
|
|
71
|
+
"level": "must",
|
|
72
|
+
"statement": "Use Drawer-owned focus trap, focus restoration, scroll lock, Escape, backdrop, and portal behavior instead of rebuilding them."
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"id": "drawer-labeling",
|
|
76
|
+
"level": "must",
|
|
77
|
+
"statement": "Give Content an accessible name with Title or an explicit labeling relationship."
|
|
78
|
+
}
|
|
79
|
+
],
|
|
80
|
+
"commonMistakes": [
|
|
81
|
+
{
|
|
82
|
+
"mistake": "Using Drawer only for its edge appearance while leaving background controls interactive.",
|
|
83
|
+
"correction": "Use Drawer for modal behavior or use a normal inline region when interaction should remain available."
|
|
84
|
+
}
|
|
85
|
+
],
|
|
86
|
+
"validation": [
|
|
87
|
+
"Test trigger focus, initial focus, Tab containment, Escape and backdrop dismissal, Close, scroll lock, and focus return.",
|
|
88
|
+
"Confirm nested portals remain within the modal contract."
|
|
89
|
+
],
|
|
90
|
+
"related": [
|
|
91
|
+
"dialog",
|
|
92
|
+
"sidebar",
|
|
93
|
+
"navigation-menu"
|
|
94
|
+
]
|
|
95
|
+
}
|
|
96
|
+
```
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# DropdownMenu
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: dropdown-menu
|
|
6
|
+
|
|
7
|
+
# DropdownMenu agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Open a compact command or settings menu from a visible button with menu popup semantics, input-aware initial focus, and the shared Menu contract.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A visible button should reveal a short list of commands, independent settings, exclusive settings, or nested commands.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- Commands belong to a contextual gesture, several persistent application menu headings, a form value, or ordinary site navigation. Use ContextMenu, Menubar, Select, or NavList.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Root with a visibly named Trigger and Content. Add Portal and Arrow only when needed; fill Content with uniquely valued Item parts and the shared Menu Group, Label, CheckboxItem, RadioGroup with RadioItem, Separator, or paired Sub anatomy as the command model requires.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Use a visible, accessible Trigger that describes the menu; preserve its button, popup, expanded, controls, disabled, and custom-element keyboard semantics.
|
|
28
|
+
- **MUST:** Preserve input-aware opening: pointer or ordinary activation opens through the owned policy, ArrowDown and activation keys enter at the first item, and ArrowUp enters at the last item.
|
|
29
|
+
- **MUST:** Follow Menu's item roles, unique values, real focus, typeahead, disabled navigation, closeOnSelect, submenu, outside-dismissal, modal, portal, and focus-restoration contracts.
|
|
30
|
+
- **MUST:** When Trigger or retained Menu parts use asChild or render, merge Atom props, refs, handlers, ARIA, and children instead of replacing them.
|
|
31
|
+
|
|
32
|
+
## Common mistakes
|
|
33
|
+
|
|
34
|
+
- **Avoid:** Using an unlabeled icon trigger, putting ordinary navigation or a form select into DropdownMenu, or adding custom key and document dismissal handlers. **Instead:** Give Trigger a complete accessible name, select the correct semantic component, and rely on the shared Menu behavior.
|
|
35
|
+
|
|
36
|
+
## Validation checklist
|
|
37
|
+
|
|
38
|
+
- Verify Trigger naming and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial item focus, controlled state, disabled behavior, Tab exit, Escape, outside dismissal, and focus return.
|
|
39
|
+
- Verify command, checkbox, radio, group, indicator, separator, and submenu behavior; typeahead; close policies; modal and parent-modal ownership; LTR and RTL; portals; and collision positioning.
|
|
40
|
+
|
|
41
|
+
## Related guidance
|
|
42
|
+
|
|
43
|
+
- `menu`
|
|
44
|
+
- `context-menu`
|
|
45
|
+
- `menubar`
|
|
46
|
+
- `select`
|
|
47
|
+
- `nav-list`
|
|
48
|
+
|
|
49
|
+
## Machine record
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"schema": "flowstack.agent-component.v1",
|
|
54
|
+
"id": "dropdown-menu",
|
|
55
|
+
"name": "DropdownMenu",
|
|
56
|
+
"package": "@flowstack-ui/atom",
|
|
57
|
+
"layer": "atom",
|
|
58
|
+
"kind": "component",
|
|
59
|
+
"purpose": "Open a compact command or settings menu from a visible button with menu popup semantics, input-aware initial focus, and the shared Menu contract.",
|
|
60
|
+
"useWhen": [
|
|
61
|
+
"A visible button should reveal a short list of commands, independent settings, exclusive settings, or nested commands."
|
|
62
|
+
],
|
|
63
|
+
"avoidWhen": [
|
|
64
|
+
{
|
|
65
|
+
"condition": "Commands belong to a contextual gesture, several persistent application menu headings, a form value, or ordinary site navigation.",
|
|
66
|
+
"useInstead": "ContextMenu, Menubar, Select, or NavList"
|
|
67
|
+
}
|
|
68
|
+
],
|
|
69
|
+
"composition": [
|
|
70
|
+
"Compose Root with a visibly named Trigger and Content. Add Portal and Arrow only when needed; fill Content with uniquely valued Item parts and the shared Menu Group, Label, CheckboxItem, RadioGroup with RadioItem, Separator, or paired Sub anatomy as the command model requires."
|
|
71
|
+
],
|
|
72
|
+
"rules": [
|
|
73
|
+
{
|
|
74
|
+
"id": "dropdown-visible-trigger",
|
|
75
|
+
"level": "must",
|
|
76
|
+
"statement": "Use a visible, accessible Trigger that describes the menu; preserve its button, popup, expanded, controls, disabled, and custom-element keyboard semantics."
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"id": "dropdown-input-focus",
|
|
80
|
+
"level": "must",
|
|
81
|
+
"statement": "Preserve input-aware opening: pointer or ordinary activation opens through the owned policy, ArrowDown and activation keys enter at the first item, and ArrowUp enters at the last item."
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
"id": "dropdown-menu-contract",
|
|
85
|
+
"level": "must",
|
|
86
|
+
"statement": "Follow Menu's item roles, unique values, real focus, typeahead, disabled navigation, closeOnSelect, submenu, outside-dismissal, modal, portal, and focus-restoration contracts."
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"id": "dropdown-composition-merge",
|
|
90
|
+
"level": "must",
|
|
91
|
+
"statement": "When Trigger or retained Menu parts use asChild or render, merge Atom props, refs, handlers, ARIA, and children instead of replacing them."
|
|
92
|
+
}
|
|
93
|
+
],
|
|
94
|
+
"commonMistakes": [
|
|
95
|
+
{
|
|
96
|
+
"mistake": "Using an unlabeled icon trigger, putting ordinary navigation or a form select into DropdownMenu, or adding custom key and document dismissal handlers.",
|
|
97
|
+
"correction": "Give Trigger a complete accessible name, select the correct semantic component, and rely on the shared Menu behavior."
|
|
98
|
+
}
|
|
99
|
+
],
|
|
100
|
+
"validation": [
|
|
101
|
+
"Verify Trigger naming and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial item focus, controlled state, disabled behavior, Tab exit, Escape, outside dismissal, and focus return.",
|
|
102
|
+
"Verify command, checkbox, radio, group, indicator, separator, and submenu behavior; typeahead; close policies; modal and parent-modal ownership; LTR and RTL; portals; and collision positioning."
|
|
103
|
+
],
|
|
104
|
+
"related": [
|
|
105
|
+
"menu",
|
|
106
|
+
"context-menu",
|
|
107
|
+
"menubar",
|
|
108
|
+
"select",
|
|
109
|
+
"nav-list"
|
|
110
|
+
]
|
|
111
|
+
}
|
|
112
|
+
```
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Feed
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: feed
|
|
6
|
+
|
|
7
|
+
# Feed agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Provide a named ARIA feed of focusable articles with article-to-article keyboard movement, loading state, logical position and size metadata, and safe integration with dynamic or virtualized streams.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- A changing, paged, infinite, or virtualized stream of articles needs keyboard movement article by article while people read.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- The content is a static set that needs only ordinary list semantics, or items are selectable options or commands rather than articles. Use List or the matching interactive collection primitive.
|
|
20
|
+
- Only visual infinite scrolling is needed and article keyboard navigation or feed semantics are not appropriate. Use the semantic collection that matches the content, optionally composed with Virtualizer.
|
|
21
|
+
|
|
22
|
+
## Required composition
|
|
23
|
+
|
|
24
|
+
- Give Root an accessible name and truthful busy and setSize state, then render one Item per article with a useful internal heading, stable identity, and accurate one-based position or zero-based index. Compose Virtualizer only when scale justifies windowing and preserve the logical feed contract.
|
|
25
|
+
|
|
26
|
+
## Rules
|
|
27
|
+
|
|
28
|
+
- **MUST:** Give Root an accessible name and preserve feed and direct article relationships; give every Item meaningful article content and a useful heading or accessible name.
|
|
29
|
+
- **MUST:** Expose accurate one-based positions and the total logical set size, using unknown only when the total truly cannot be known and not merely because a rendered window is partial.
|
|
30
|
+
- **MUST:** Set busy while articles are being added or replaced and clear it only after the DOM and position metadata represent the completed update.
|
|
31
|
+
- **MUST:** Preserve PageUp and PageDown article movement, Control or Command Home and End movement outside the feed, focus of the target article, nearest scrolling, and consumer preventDefault cancellation.
|
|
32
|
+
- **MUST:** Keep each Item focusable by default while allowing focusable descendants, and ensure navigation identifies the containing direct article when focus starts inside it.
|
|
33
|
+
- **MUST:** When windowing, keep the current and keyboard target articles mounted or materialize them before focus moves, retain stable keys and logical positions, and remember that Virtualizer supplies measurement rather than feed semantics or loading.
|
|
34
|
+
|
|
35
|
+
## Common mistakes
|
|
36
|
+
|
|
37
|
+
- **Avoid:** Using Feed as a visual synonym for any list or reporting the rendered window length as aria-setsize. **Instead:** Use Feed only for article streams and report the logical full set size or genuinely unknown size.
|
|
38
|
+
- **Avoid:** Unmounting the focused article during virtualization or setting busy for the entire lifetime of an infinite stream. **Instead:** Preserve or deliberately move focus before unmounting and scope busy to each concrete DOM mutation.
|
|
39
|
+
|
|
40
|
+
## Validation checklist
|
|
41
|
+
|
|
42
|
+
- Verify Root naming, direct article roles, meaningful article headings, stable identities, accurate logical positions and known or unknown total size, and busy transitions during mutations.
|
|
43
|
+
- Exercise PageUp and PageDown from Items and their descendants, Control and Command Home and End to outside targets, first and last boundaries, nearest scrolling, and consumer preventDefault cancellation.
|
|
44
|
+
- Verify native prop, tabIndex, asChild, render, ref, and server/client entrypoint behavior without losing feed or article semantics.
|
|
45
|
+
- For paged or virtualized feeds, verify stable keys and full logical metadata and ensure the focused and next navigation target articles exist before focus moves.
|
|
46
|
+
|
|
47
|
+
## Related guidance
|
|
48
|
+
|
|
49
|
+
- `list`
|
|
50
|
+
- `virtualizer`
|
|
51
|
+
|
|
52
|
+
## Machine record
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"schema": "flowstack.agent-component.v1",
|
|
57
|
+
"id": "feed",
|
|
58
|
+
"name": "Feed",
|
|
59
|
+
"package": "@flowstack-ui/atom",
|
|
60
|
+
"layer": "atom",
|
|
61
|
+
"kind": "component",
|
|
62
|
+
"purpose": "Provide a named ARIA feed of focusable articles with article-to-article keyboard movement, loading state, logical position and size metadata, and safe integration with dynamic or virtualized streams.",
|
|
63
|
+
"useWhen": [
|
|
64
|
+
"A changing, paged, infinite, or virtualized stream of articles needs keyboard movement article by article while people read."
|
|
65
|
+
],
|
|
66
|
+
"avoidWhen": [
|
|
67
|
+
{
|
|
68
|
+
"condition": "The content is a static set that needs only ordinary list semantics, or items are selectable options or commands rather than articles.",
|
|
69
|
+
"useInstead": "List or the matching interactive collection primitive"
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"condition": "Only visual infinite scrolling is needed and article keyboard navigation or feed semantics are not appropriate.",
|
|
73
|
+
"useInstead": "the semantic collection that matches the content, optionally composed with Virtualizer"
|
|
74
|
+
}
|
|
75
|
+
],
|
|
76
|
+
"composition": [
|
|
77
|
+
"Give Root an accessible name and truthful busy and setSize state, then render one Item per article with a useful internal heading, stable identity, and accurate one-based position or zero-based index. Compose Virtualizer only when scale justifies windowing and preserve the logical feed contract."
|
|
78
|
+
],
|
|
79
|
+
"rules": [
|
|
80
|
+
{
|
|
81
|
+
"id": "feed-name-articles",
|
|
82
|
+
"level": "must",
|
|
83
|
+
"statement": "Give Root an accessible name and preserve feed and direct article relationships; give every Item meaningful article content and a useful heading or accessible name."
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
"id": "feed-position-size",
|
|
87
|
+
"level": "must",
|
|
88
|
+
"statement": "Expose accurate one-based positions and the total logical set size, using unknown only when the total truly cannot be known and not merely because a rendered window is partial."
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"id": "feed-busy",
|
|
92
|
+
"level": "must",
|
|
93
|
+
"statement": "Set busy while articles are being added or replaced and clear it only after the DOM and position metadata represent the completed update."
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
"id": "feed-keyboard",
|
|
97
|
+
"level": "must",
|
|
98
|
+
"statement": "Preserve PageUp and PageDown article movement, Control or Command Home and End movement outside the feed, focus of the target article, nearest scrolling, and consumer preventDefault cancellation."
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
"id": "feed-focus-content",
|
|
102
|
+
"level": "must",
|
|
103
|
+
"statement": "Keep each Item focusable by default while allowing focusable descendants, and ensure navigation identifies the containing direct article when focus starts inside it."
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"id": "feed-virtualization",
|
|
107
|
+
"level": "must",
|
|
108
|
+
"statement": "When windowing, keep the current and keyboard target articles mounted or materialize them before focus moves, retain stable keys and logical positions, and remember that Virtualizer supplies measurement rather than feed semantics or loading."
|
|
109
|
+
}
|
|
110
|
+
],
|
|
111
|
+
"commonMistakes": [
|
|
112
|
+
{
|
|
113
|
+
"mistake": "Using Feed as a visual synonym for any list or reporting the rendered window length as aria-setsize.",
|
|
114
|
+
"correction": "Use Feed only for article streams and report the logical full set size or genuinely unknown size."
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"mistake": "Unmounting the focused article during virtualization or setting busy for the entire lifetime of an infinite stream.",
|
|
118
|
+
"correction": "Preserve or deliberately move focus before unmounting and scope busy to each concrete DOM mutation."
|
|
119
|
+
}
|
|
120
|
+
],
|
|
121
|
+
"validation": [
|
|
122
|
+
"Verify Root naming, direct article roles, meaningful article headings, stable identities, accurate logical positions and known or unknown total size, and busy transitions during mutations.",
|
|
123
|
+
"Exercise PageUp and PageDown from Items and their descendants, Control and Command Home and End to outside targets, first and last boundaries, nearest scrolling, and consumer preventDefault cancellation.",
|
|
124
|
+
"Verify native prop, tabIndex, asChild, render, ref, and server/client entrypoint behavior without losing feed or article semantics.",
|
|
125
|
+
"For paged or virtualized feeds, verify stable keys and full logical metadata and ensure the focused and next navigation target articles exist before focus moves."
|
|
126
|
+
],
|
|
127
|
+
"related": [
|
|
128
|
+
"list",
|
|
129
|
+
"virtualizer"
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
```
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Field
|
|
2
|
+
|
|
3
|
+
Source: @flowstack-ui/atom@0.24.0
|
|
4
|
+
Kind: component
|
|
5
|
+
ID: field
|
|
6
|
+
|
|
7
|
+
# Field agent guide
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
Wire one form control to its label, description, error, and shared required, disabled, read-only, and invalid state.
|
|
12
|
+
|
|
13
|
+
## Use when
|
|
14
|
+
|
|
15
|
+
- One control needs a visible label and may need help or error text.
|
|
16
|
+
|
|
17
|
+
## Choose something else when
|
|
18
|
+
|
|
19
|
+
- Several related controls share one group label. Use Fieldset containing one Field per control when needed.
|
|
20
|
+
|
|
21
|
+
## Required composition
|
|
22
|
+
|
|
23
|
+
- Compose Field.Root -> Field.Label -> one Field-aware control -> optional Field.Description -> optional Field.Error.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **MUST:** Associate one Field with one owned control.
|
|
28
|
+
- **MUST:** Field.Label already renders the default required marker; do not add Field.RequiredIndicator inside it unless the default indicator is disabled.
|
|
29
|
+
- **SHOULD:** Make error text explain how to correct the value.
|
|
30
|
+
|
|
31
|
+
## Common mistakes
|
|
32
|
+
|
|
33
|
+
- **Avoid:** Adding a manual asterisk or RequiredIndicator beside the default required Label. **Instead:** Set required on Field.Root and let Field.Label render its built-in marker, or disable that marker before composing a separate indicator.
|
|
34
|
+
|
|
35
|
+
## Validation checklist
|
|
36
|
+
|
|
37
|
+
- Inspect label-for and control-id relationships.
|
|
38
|
+
- Confirm description and visible error IDs appear in aria-describedby.
|
|
39
|
+
- Confirm exactly one required indicator is visible.
|
|
40
|
+
|
|
41
|
+
## Related guidance
|
|
42
|
+
|
|
43
|
+
- `form`
|
|
44
|
+
- `fieldset`
|
|
45
|
+
- `input`
|
|
46
|
+
- `textarea`
|
|
47
|
+
- `checkbox`
|
|
48
|
+
|
|
49
|
+
## Machine record
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"schema": "flowstack.agent-component.v1",
|
|
54
|
+
"id": "field",
|
|
55
|
+
"name": "Field",
|
|
56
|
+
"package": "@flowstack-ui/atom",
|
|
57
|
+
"layer": "atom",
|
|
58
|
+
"kind": "component",
|
|
59
|
+
"purpose": "Wire one form control to its label, description, error, and shared required, disabled, read-only, and invalid state.",
|
|
60
|
+
"useWhen": [
|
|
61
|
+
"One control needs a visible label and may need help or error text."
|
|
62
|
+
],
|
|
63
|
+
"avoidWhen": [
|
|
64
|
+
{
|
|
65
|
+
"condition": "Several related controls share one group label.",
|
|
66
|
+
"useInstead": "Fieldset containing one Field per control when needed"
|
|
67
|
+
}
|
|
68
|
+
],
|
|
69
|
+
"composition": [
|
|
70
|
+
"Compose Field.Root -> Field.Label -> one Field-aware control -> optional Field.Description -> optional Field.Error."
|
|
71
|
+
],
|
|
72
|
+
"rules": [
|
|
73
|
+
{
|
|
74
|
+
"id": "field-one-control",
|
|
75
|
+
"level": "must",
|
|
76
|
+
"statement": "Associate one Field with one owned control."
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"id": "field-required-marker",
|
|
80
|
+
"level": "must",
|
|
81
|
+
"statement": "Field.Label already renders the default required marker; do not add Field.RequiredIndicator inside it unless the default indicator is disabled."
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
"id": "field-errors-actionable",
|
|
85
|
+
"level": "should",
|
|
86
|
+
"statement": "Make error text explain how to correct the value."
|
|
87
|
+
}
|
|
88
|
+
],
|
|
89
|
+
"commonMistakes": [
|
|
90
|
+
{
|
|
91
|
+
"mistake": "Adding a manual asterisk or RequiredIndicator beside the default required Label.",
|
|
92
|
+
"correction": "Set required on Field.Root and let Field.Label render its built-in marker, or disable that marker before composing a separate indicator."
|
|
93
|
+
}
|
|
94
|
+
],
|
|
95
|
+
"validation": [
|
|
96
|
+
"Inspect label-for and control-id relationships.",
|
|
97
|
+
"Confirm description and visible error IDs appear in aria-describedby.",
|
|
98
|
+
"Confirm exactly one required indicator is visible."
|
|
99
|
+
],
|
|
100
|
+
"related": [
|
|
101
|
+
"form",
|
|
102
|
+
"fieldset",
|
|
103
|
+
"input",
|
|
104
|
+
"textarea",
|
|
105
|
+
"checkbox"
|
|
106
|
+
]
|
|
107
|
+
}
|
|
108
|
+
```
|