@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.
Files changed (239) hide show
  1. package/.codex-plugin/plugin.json +37 -0
  2. package/CHANGELOG.md +21 -0
  3. package/LICENSE +21 -0
  4. package/README.md +125 -0
  5. package/docs/architecture.md +77 -0
  6. package/docs/releasing.md +26 -0
  7. package/docs/testing.md +32 -0
  8. package/package.json +63 -0
  9. package/public/index.json +2073 -0
  10. package/public/llms.txt +19 -0
  11. package/public/packages/atom/0.24.0/components/accordion.txt +131 -0
  12. package/public/packages/atom/0.24.0/components/alert-dialog.txt +112 -0
  13. package/public/packages/atom/0.24.0/components/app-bar.txt +96 -0
  14. package/public/packages/atom/0.24.0/components/aspect-ratio.txt +111 -0
  15. package/public/packages/atom/0.24.0/components/avatar.txt +119 -0
  16. package/public/packages/atom/0.24.0/components/badge.txt +123 -0
  17. package/public/packages/atom/0.24.0/components/bottom-navigation.txt +96 -0
  18. package/public/packages/atom/0.24.0/components/breadcrumb.txt +96 -0
  19. package/public/packages/atom/0.24.0/components/button.txt +98 -0
  20. package/public/packages/atom/0.24.0/components/carousel.txt +128 -0
  21. package/public/packages/atom/0.24.0/components/checkbox-group.txt +118 -0
  22. package/public/packages/atom/0.24.0/components/checkbox.txt +100 -0
  23. package/public/packages/atom/0.24.0/components/clipboard.txt +112 -0
  24. package/public/packages/atom/0.24.0/components/collapsible.txt +112 -0
  25. package/public/packages/atom/0.24.0/components/color-picker.txt +117 -0
  26. package/public/packages/atom/0.24.0/components/combobox.txt +126 -0
  27. package/public/packages/atom/0.24.0/components/context-menu.txt +114 -0
  28. package/public/packages/atom/0.24.0/components/data-grid.txt +136 -0
  29. package/public/packages/atom/0.24.0/components/dialog.txt +116 -0
  30. package/public/packages/atom/0.24.0/components/direction.txt +132 -0
  31. package/public/packages/atom/0.24.0/components/divider.txt +94 -0
  32. package/public/packages/atom/0.24.0/components/drag-drop.txt +141 -0
  33. package/public/packages/atom/0.24.0/components/drawer.txt +96 -0
  34. package/public/packages/atom/0.24.0/components/dropdown-menu.txt +112 -0
  35. package/public/packages/atom/0.24.0/components/feed.txt +132 -0
  36. package/public/packages/atom/0.24.0/components/field.txt +108 -0
  37. package/public/packages/atom/0.24.0/components/fieldset.txt +96 -0
  38. package/public/packages/atom/0.24.0/components/file-upload.txt +120 -0
  39. package/public/packages/atom/0.24.0/components/form.txt +98 -0
  40. package/public/packages/atom/0.24.0/components/hover-card.txt +114 -0
  41. package/public/packages/atom/0.24.0/components/image.txt +94 -0
  42. package/public/packages/atom/0.24.0/components/input.txt +96 -0
  43. package/public/packages/atom/0.24.0/components/label.txt +121 -0
  44. package/public/packages/atom/0.24.0/components/link.txt +100 -0
  45. package/public/packages/atom/0.24.0/components/list.txt +131 -0
  46. package/public/packages/atom/0.24.0/components/listbox.txt +120 -0
  47. package/public/packages/atom/0.24.0/components/menu.txt +126 -0
  48. package/public/packages/atom/0.24.0/components/menubar.txt +120 -0
  49. package/public/packages/atom/0.24.0/components/modal.txt +118 -0
  50. package/public/packages/atom/0.24.0/components/multi-select.txt +120 -0
  51. package/public/packages/atom/0.24.0/components/nav-list.txt +104 -0
  52. package/public/packages/atom/0.24.0/components/navigation-menu.txt +104 -0
  53. package/public/packages/atom/0.24.0/components/number-input.txt +124 -0
  54. package/public/packages/atom/0.24.0/components/otp-field.txt +122 -0
  55. package/public/packages/atom/0.24.0/components/pagination.txt +111 -0
  56. package/public/packages/atom/0.24.0/components/password-toggle-field.txt +116 -0
  57. package/public/packages/atom/0.24.0/components/popover.txt +122 -0
  58. package/public/packages/atom/0.24.0/components/pressable.txt +94 -0
  59. package/public/packages/atom/0.24.0/components/progress.txt +130 -0
  60. package/public/packages/atom/0.24.0/components/radio-group.txt +118 -0
  61. package/public/packages/atom/0.24.0/components/rating.txt +122 -0
  62. package/public/packages/atom/0.24.0/components/reorder.txt +141 -0
  63. package/public/packages/atom/0.24.0/components/scroll-area.txt +96 -0
  64. package/public/packages/atom/0.24.0/components/select.txt +126 -0
  65. package/public/packages/atom/0.24.0/components/sidebar.txt +96 -0
  66. package/public/packages/atom/0.24.0/components/skip-link.txt +96 -0
  67. package/public/packages/atom/0.24.0/components/slider.txt +124 -0
  68. package/public/packages/atom/0.24.0/components/swipeable-item.txt +118 -0
  69. package/public/packages/atom/0.24.0/components/switch.txt +116 -0
  70. package/public/packages/atom/0.24.0/components/table.txt +128 -0
  71. package/public/packages/atom/0.24.0/components/tabs.txt +96 -0
  72. package/public/packages/atom/0.24.0/components/textarea.txt +96 -0
  73. package/public/packages/atom/0.24.0/components/toast.txt +124 -0
  74. package/public/packages/atom/0.24.0/components/toggle-group.txt +118 -0
  75. package/public/packages/atom/0.24.0/components/toggle.txt +110 -0
  76. package/public/packages/atom/0.24.0/components/toolbar.txt +98 -0
  77. package/public/packages/atom/0.24.0/components/tooltip.txt +112 -0
  78. package/public/packages/atom/0.24.0/components/tree-grid.txt +138 -0
  79. package/public/packages/atom/0.24.0/components/tree.txt +138 -0
  80. package/public/packages/atom/0.24.0/components/visually-hidden.txt +119 -0
  81. package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt +55 -0
  82. package/public/packages/atom/0.24.0/docs/guides/getting-started.txt +65 -0
  83. package/public/packages/atom/0.24.0/docs/guides/imports.txt +26 -0
  84. package/public/packages/atom/0.24.0/docs/guides/public-api.txt +100 -0
  85. package/public/packages/atom/0.24.0/guides/behavior-composition.txt +277 -0
  86. package/public/packages/atom/0.24.0/guides/layer-selection.txt +807 -0
  87. package/public/packages/atom/0.24.0/index.txt +89 -0
  88. package/public/packages/brick/0.1.11/components/accordion.txt +158 -0
  89. package/public/packages/brick/0.1.11/components/alert-dialog.txt +175 -0
  90. package/public/packages/brick/0.1.11/components/app-bar.txt +134 -0
  91. package/public/packages/brick/0.1.11/components/appearance.txt +143 -0
  92. package/public/packages/brick/0.1.11/components/aspect-ratio.txt +136 -0
  93. package/public/packages/brick/0.1.11/components/avatar.txt +152 -0
  94. package/public/packages/brick/0.1.11/components/badge.txt +139 -0
  95. package/public/packages/brick/0.1.11/components/bleed.txt +104 -0
  96. package/public/packages/brick/0.1.11/components/bottom-navigation.txt +106 -0
  97. package/public/packages/brick/0.1.11/components/breadcrumb.txt +96 -0
  98. package/public/packages/brick/0.1.11/components/button.txt +103 -0
  99. package/public/packages/brick/0.1.11/components/card.txt +132 -0
  100. package/public/packages/brick/0.1.11/components/carousel.txt +206 -0
  101. package/public/packages/brick/0.1.11/components/checkbox-group.txt +175 -0
  102. package/public/packages/brick/0.1.11/components/checkbox.txt +103 -0
  103. package/public/packages/brick/0.1.11/components/chip.txt +128 -0
  104. package/public/packages/brick/0.1.11/components/code-block.txt +134 -0
  105. package/public/packages/brick/0.1.11/components/code.txt +120 -0
  106. package/public/packages/brick/0.1.11/components/collapsible.txt +179 -0
  107. package/public/packages/brick/0.1.11/components/color-picker.txt +135 -0
  108. package/public/packages/brick/0.1.11/components/color-swatch.txt +98 -0
  109. package/public/packages/brick/0.1.11/components/combobox.txt +157 -0
  110. package/public/packages/brick/0.1.11/components/container.txt +112 -0
  111. package/public/packages/brick/0.1.11/components/context-menu.txt +174 -0
  112. package/public/packages/brick/0.1.11/components/data-grid.txt +199 -0
  113. package/public/packages/brick/0.1.11/components/data-list.txt +115 -0
  114. package/public/packages/brick/0.1.11/components/dialog.txt +176 -0
  115. package/public/packages/brick/0.1.11/components/divider.txt +104 -0
  116. package/public/packages/brick/0.1.11/components/drawer.txt +146 -0
  117. package/public/packages/brick/0.1.11/components/dropdown-menu.txt +179 -0
  118. package/public/packages/brick/0.1.11/components/feed.txt +143 -0
  119. package/public/packages/brick/0.1.11/components/field.txt +115 -0
  120. package/public/packages/brick/0.1.11/components/fieldset.txt +103 -0
  121. package/public/packages/brick/0.1.11/components/file-upload.txt +154 -0
  122. package/public/packages/brick/0.1.11/components/form.txt +108 -0
  123. package/public/packages/brick/0.1.11/components/frame.txt +132 -0
  124. package/public/packages/brick/0.1.11/components/grid.txt +141 -0
  125. package/public/packages/brick/0.1.11/components/group.txt +136 -0
  126. package/public/packages/brick/0.1.11/components/hide.txt +121 -0
  127. package/public/packages/brick/0.1.11/components/hover-card.txt +156 -0
  128. package/public/packages/brick/0.1.11/components/icon-button.txt +119 -0
  129. package/public/packages/brick/0.1.11/components/icon.txt +160 -0
  130. package/public/packages/brick/0.1.11/components/image.txt +163 -0
  131. package/public/packages/brick/0.1.11/components/input.txt +101 -0
  132. package/public/packages/brick/0.1.11/components/link-box.txt +161 -0
  133. package/public/packages/brick/0.1.11/components/link.txt +133 -0
  134. package/public/packages/brick/0.1.11/components/list.txt +139 -0
  135. package/public/packages/brick/0.1.11/components/menubar.txt +174 -0
  136. package/public/packages/brick/0.1.11/components/multi-select.txt +153 -0
  137. package/public/packages/brick/0.1.11/components/nav-list.txt +130 -0
  138. package/public/packages/brick/0.1.11/components/navigation-menu.txt +150 -0
  139. package/public/packages/brick/0.1.11/components/notification-badge.txt +148 -0
  140. package/public/packages/brick/0.1.11/components/number-input.txt +150 -0
  141. package/public/packages/brick/0.1.11/components/otp-field.txt +146 -0
  142. package/public/packages/brick/0.1.11/components/pagination.txt +124 -0
  143. package/public/packages/brick/0.1.11/components/password-toggle-field.txt +146 -0
  144. package/public/packages/brick/0.1.11/components/popover.txt +181 -0
  145. package/public/packages/brick/0.1.11/components/progress-circle.txt +142 -0
  146. package/public/packages/brick/0.1.11/components/progress.txt +150 -0
  147. package/public/packages/brick/0.1.11/components/radio-group.txt +152 -0
  148. package/public/packages/brick/0.1.11/components/rating.txt +151 -0
  149. package/public/packages/brick/0.1.11/components/reorderable-list.txt +130 -0
  150. package/public/packages/brick/0.1.11/components/scroll-area.txt +110 -0
  151. package/public/packages/brick/0.1.11/components/section.txt +118 -0
  152. package/public/packages/brick/0.1.11/components/segment-group.txt +116 -0
  153. package/public/packages/brick/0.1.11/components/select.txt +157 -0
  154. package/public/packages/brick/0.1.11/components/show.txt +121 -0
  155. package/public/packages/brick/0.1.11/components/sidebar.txt +126 -0
  156. package/public/packages/brick/0.1.11/components/skeleton.txt +127 -0
  157. package/public/packages/brick/0.1.11/components/skip-link.txt +102 -0
  158. package/public/packages/brick/0.1.11/components/slider.txt +147 -0
  159. package/public/packages/brick/0.1.11/components/stack.txt +155 -0
  160. package/public/packages/brick/0.1.11/components/status.txt +110 -0
  161. package/public/packages/brick/0.1.11/components/surface.txt +194 -0
  162. package/public/packages/brick/0.1.11/components/swipeable-item.txt +154 -0
  163. package/public/packages/brick/0.1.11/components/switch.txt +152 -0
  164. package/public/packages/brick/0.1.11/components/table.txt +183 -0
  165. package/public/packages/brick/0.1.11/components/tabs.txt +136 -0
  166. package/public/packages/brick/0.1.11/components/text.txt +148 -0
  167. package/public/packages/brick/0.1.11/components/textarea.txt +101 -0
  168. package/public/packages/brick/0.1.11/components/toast.txt +150 -0
  169. package/public/packages/brick/0.1.11/components/toggle-group.txt +149 -0
  170. package/public/packages/brick/0.1.11/components/toggle.txt +140 -0
  171. package/public/packages/brick/0.1.11/components/toolbar.txt +118 -0
  172. package/public/packages/brick/0.1.11/components/tooltip.txt +156 -0
  173. package/public/packages/brick/0.1.11/components/tree-grid.txt +160 -0
  174. package/public/packages/brick/0.1.11/components/tree.txt +156 -0
  175. package/public/packages/brick/0.1.11/components/visually-hidden.txt +123 -0
  176. package/public/packages/brick/0.1.11/components/z-stack.txt +143 -0
  177. package/public/packages/brick/0.1.11/docs/guides/agent-knowledge.txt +67 -0
  178. package/public/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt +179 -0
  179. package/public/packages/brick/0.1.11/docs/guides/browser-support.txt +25 -0
  180. package/public/packages/brick/0.1.11/docs/guides/control-sizing.txt +59 -0
  181. package/public/packages/brick/0.1.11/docs/guides/installation.txt +79 -0
  182. package/public/packages/brick/0.1.11/docs/guides/theme-contract.txt +90 -0
  183. package/public/packages/brick/0.1.11/guides/interface-composition.txt +665 -0
  184. package/public/packages/brick/0.1.11/guides/layer-selection.txt +1437 -0
  185. package/public/packages/brick/0.1.11/index.txt +110 -0
  186. package/public/packages/colors/0.1.1/docs/agent-knowledge.txt +63 -0
  187. package/public/packages/colors/0.1.1/docs/architecture.txt +74 -0
  188. package/public/packages/colors/0.1.1/docs/color-foundations.txt +128 -0
  189. package/public/packages/colors/0.1.1/docs/compatibility.txt +75 -0
  190. package/public/packages/colors/0.1.1/docs/dependency-qualification.txt +117 -0
  191. package/public/packages/colors/0.1.1/docs/installation.txt +48 -0
  192. package/public/packages/colors/0.1.1/docs/palette-generation.txt +151 -0
  193. package/public/packages/colors/0.1.1/docs/releasing.txt +34 -0
  194. package/public/packages/colors/0.1.1/docs/testing.txt +51 -0
  195. package/public/packages/colors/0.1.1/guides/colors-system.txt +282 -0
  196. package/public/packages/colors/0.1.1/index.txt +29 -0
  197. package/public/packages/colors/0.1.1/operations/color-conversion.txt +14 -0
  198. package/public/packages/colors/0.1.1/operations/color-inspection.txt +23 -0
  199. package/public/packages/colors/0.1.1/operations/color-measurement.txt +18 -0
  200. package/public/packages/colors/0.1.1/operations/color-provenance.txt +14 -0
  201. package/public/packages/colors/0.1.1/operations/named-palette-reference.txt +15 -0
  202. package/public/packages/colors/0.1.1/operations/palette-candidate.txt +37 -0
  203. package/public/packages/theme/0.1.1/docs/agent-knowledge.txt +44 -0
  204. package/public/packages/theme/0.1.1/docs/appearances-and-portals.txt +41 -0
  205. package/public/packages/theme/0.1.1/docs/architecture.txt +121 -0
  206. package/public/packages/theme/0.1.1/docs/authoring.txt +141 -0
  207. package/public/packages/theme/0.1.1/docs/colors-interchange.txt +82 -0
  208. package/public/packages/theme/0.1.1/docs/fonts.txt +40 -0
  209. package/public/packages/theme/0.1.1/docs/installation.txt +45 -0
  210. package/public/packages/theme/0.1.1/docs/migration.txt +40 -0
  211. package/public/packages/theme/0.1.1/docs/testing.txt +64 -0
  212. package/public/packages/theme/0.1.1/docs/troubleshooting.txt +53 -0
  213. package/public/packages/theme/0.1.1/guides/theme-system.txt +340 -0
  214. package/public/packages/theme/0.1.1/index.txt +31 -0
  215. package/public/packages/theme/0.1.1/operations/brick-contract-compatibility.txt +35 -0
  216. package/public/packages/theme/0.1.1/operations/colors-interchange.txt +35 -0
  217. package/public/packages/theme/0.1.1/operations/theme-artifacts.txt +19 -0
  218. package/public/packages/theme/0.1.1/operations/theme-cli.txt +10 -0
  219. package/public/packages/theme/0.1.1/operations/theme-compilation.txt +23 -0
  220. package/public/packages/theme/0.1.1/operations/theme-definition.txt +36 -0
  221. package/public/packages/theme/0.1.1/operations/theme-validation.txt +19 -0
  222. package/public/tasks/data.txt +39 -0
  223. package/public/tasks/forms.txt +65 -0
  224. package/public/tasks/layout.txt +37 -0
  225. package/public/tasks/navigation.txt +51 -0
  226. package/public/tasks/overlays.txt +39 -0
  227. package/public/tasks/theming.txt +37 -0
  228. package/skills/flowstack-ui-builder/SKILL.md +35 -0
  229. package/skills/flowstack-ui-builder/agents/openai.yaml +4 -0
  230. package/skills/flowstack-ui-builder/scripts/resolve-agent-knowledge.mjs +399 -0
  231. package/skills/flowstack-ui-compose/SKILL.md +32 -0
  232. package/skills/flowstack-ui-compose/agents/openai.yaml +4 -0
  233. package/skills/flowstack-ui-compose/scripts/resolve-agent-knowledge.mjs +399 -0
  234. package/skills/flowstack-ui-maintainer/SKILL.md +40 -0
  235. package/skills/flowstack-ui-maintainer/agents/openai.yaml +4 -0
  236. package/skills/flowstack-ui-maintainer/scripts/resolve-agent-knowledge.mjs +399 -0
  237. package/skills/flowstack-ui-review/SKILL.md +29 -0
  238. package/skills/flowstack-ui-review/agents/openai.yaml +4 -0
  239. 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
+ ```