@flowstack-ui/brick 0.1.6 → 0.1.11

package/dist/agents/combobox.json

@@ -0,0 +1,95 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "combobox",
+  "name": "Combobox",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished editable filtering and single-value selection while Atom owns committed value, input text, open state, listbox focus, positioning, dismissal, validation, and form participation.",
+  "useWhen": [
+    "A predefined option set benefits from editable filtering, including search-and-navigate interfaces whose selected result triggers an application-owned effect."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Any text is valid without options, one predefined value needs no filtering, several values must be selected, or the popup contains commands.",
+      "useInstead": "Input, Select or RadioGroup, MultiSelect, or DropdownMenu"
+    }
+  ],
+  "composition": [
+    "Compose a persistent Field.Label, then Combobox.Root with the complete options -> Combobox.Control with Input and optional Clear and Trigger -> optional Portal -> Content -> Listbox -> one Item per available option, plus Empty, Loading, groups, and labels when required.",
+    "Keep committed value, inputValue, and open as independent state axes. Keep rendered Items aligned with Root options and put noninteractive complete labels inside each Item."
+  ],
+  "rules": [
+    {
+      "id": "combobox-three-states",
+      "level": "must",
+      "statement": "Keep committed value, editable input text, and popup open state independent and pair each controlled prop with its matching callback."
+    },
+    {
+      "id": "combobox-one-collection",
+      "level": "must",
+      "statement": "Keep Root options, rendered Items, stable values, labels, disabled state, grouping, and custom filtering aligned as one authoritative collection."
+    },
+    {
+      "id": "combobox-semantic-owners",
+      "level": "must",
+      "statement": "Keep Input as the named editable combobox focus owner, Content as positioning and dismissal owner, and Listbox as semantic option owner; never hand-position a Surface or put listbox role on Content."
+    },
+    {
+      "id": "combobox-keyboard-form",
+      "level": "must",
+      "statement": "Preserve active-descendant focus, Arrow/Home/End, Enter, Escape close-then-clear, Tab, openOnFocus, pointer selection, disabled skipping, required committed-value validity, named hidden submission, external form, and reset."
+    },
+    {
+      "id": "combobox-free-solo",
+      "level": "must",
+      "statement": "Enable freeSolo only when values outside the predefined collection are valid; display text alone must not satisfy required validity for a closed vocabulary."
+    },
+    {
+      "id": "combobox-application-effect",
+      "level": "must",
+      "statement": "Keep routing, remote loading, analytics, persistence, and destination policy in application callbacks while Empty and Loading accurately reflect the current collection state."
+    },
+    {
+      "id": "combobox-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus combobox.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Conflating input text with committed value, enabling freeSolo for closed vocabulary, omitting rendered Items, or putting listbox role on Content.",
+      "correction": "Manage all three states, restrict freeSolo, align options with Items, and preserve Atom's compound semantic owners."
+    },
+    {
+      "mistake": "Putting Link, Button, or other controls inside Item or closing a hand-positioned result Surface with custom document listeners.",
+      "correction": "Use noninteractive option labels and perform the selected value's application effect from onValueChange inside the complete Combobox popup anatomy."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled committed value, input text, and open state; default label initialization; filtering and grouping; disabled options; typing; Arrow/Home/End; Enter option and freeSolo commits; Escape; Tab; openOnFocus; Empty; Loading; Clear; Trigger; pointer selection; and clearOnSelect.",
+    "Verify visible Field naming, required committed-value validity, inline/native validation focus, hidden named value, external form, reset, Control-sized collision positioning, Portal, outside dismissal and cancellation, and highlighted-item scrolling.",
+    "Verify recipes and sizes, long labels, narrow widths, zoom, RTL, mobile focus, light and dark appearance, forced colors, and application-owned search-and-navigate effects."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "combobox",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "listbox",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "input",
+    "select",
+    "radio-group",
+    "multi-select",
+    "dropdown-menu",
+    "popover"
+  ]
+}

package/dist/agents/combobox.md

@@ -0,0 +1,51 @@
+# Combobox agent guide
+
+## Purpose
+
+Present finished editable filtering and single-value selection while Atom owns committed value, input text, open state, listbox focus, positioning, dismissal, validation, and form participation.
+
+## Use when
+
+- A predefined option set benefits from editable filtering, including search-and-navigate interfaces whose selected result triggers an application-owned effect.
+
+## Choose something else when
+
+- Any text is valid without options, one predefined value needs no filtering, several values must be selected, or the popup contains commands. Use Input, Select or RadioGroup, MultiSelect, or DropdownMenu.
+
+## Required composition
+
+- Compose a persistent Field.Label, then Combobox.Root with the complete options -> Combobox.Control with Input and optional Clear and Trigger -> optional Portal -> Content -> Listbox -> one Item per available option, plus Empty, Loading, groups, and labels when required.
+- Keep committed value, inputValue, and open as independent state axes. Keep rendered Items aligned with Root options and put noninteractive complete labels inside each Item.
+
+## Rules
+
+- **MUST:** Keep committed value, editable input text, and popup open state independent and pair each controlled prop with its matching callback.
+- **MUST:** Keep Root options, rendered Items, stable values, labels, disabled state, grouping, and custom filtering aligned as one authoritative collection.
+- **MUST:** Keep Input as the named editable combobox focus owner, Content as positioning and dismissal owner, and Listbox as semantic option owner; never hand-position a Surface or put listbox role on Content.
+- **MUST:** Preserve active-descendant focus, Arrow/Home/End, Enter, Escape close-then-clear, Tab, openOnFocus, pointer selection, disabled skipping, required committed-value validity, named hidden submission, external form, and reset.
+- **MUST:** Enable freeSolo only when values outside the predefined collection are valid; display text alone must not satisfy required validity for a closed vocabulary.
+- **MUST:** Keep routing, remote loading, analytics, persistence, and destination policy in application callbacks while Empty and Loading accurately reflect the current collection state.
+- **MUST:** Load styles.css or core.css plus combobox.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Conflating input text with committed value, enabling freeSolo for closed vocabulary, omitting rendered Items, or putting listbox role on Content. **Instead:** Manage all three states, restrict freeSolo, align options with Items, and preserve Atom's compound semantic owners.
+- **Avoid:** Putting Link, Button, or other controls inside Item or closing a hand-positioned result Surface with custom document listeners. **Instead:** Use noninteractive option labels and perform the selected value's application effect from onValueChange inside the complete Combobox popup anatomy.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled committed value, input text, and open state; default label initialization; filtering and grouping; disabled options; typing; Arrow/Home/End; Enter option and freeSolo commits; Escape; Tab; openOnFocus; Empty; Loading; Clear; Trigger; pointer selection; and clearOnSelect.
+- Verify visible Field naming, required committed-value validity, inline/native validation focus, hidden named value, external form, reset, Control-sized collision positioning, Portal, outside dismissal and cancellation, and highlighted-item scrolling.
+- Verify recipes and sizes, long labels, narrow widths, zoom, RTL, mobile focus, light and dark appearance, forced colors, and application-owned search-and-navigate effects.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/combobox`
+- `@flowstack-ui/atom/agents/listbox`
+- `field`
+- `input`
+- `select`
+- `radio-group`
+- `multi-select`
+- `dropdown-menu`
+- `popover`

package/dist/agents/context-menu.json

@@ -0,0 +1,109 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "context-menu",
+  "name": "ContextMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished target-specific commands at a secondary-click, keyboard context-menu invocation, or cancel-safe touch and pen long press while Atom owns invocation, menu semantics, focus, dismissal, and positioning.",
+  "useWhen": [
+    "Commands belong to the exact file, row, canvas object, or region invoked contextually and every important command also has a visible or keyboard-discoverable route."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar.",
+      "useInstead": "DropdownMenu, visible Brick controls, or Menubar"
+    },
+    {
+      "condition": "The content is site navigation or form-value selection.",
+      "useInstead": "NavigationMenu or NavList, or Select"
+    }
+  ],
+  "composition": [
+    "Compose ContextMenu.Root with ContextMenu.Trigger around the owned target and ContextMenu.Portal with ContextMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.",
+    "Keep Trigger paintless and preserve the target's native semantics through asChild or render. Give Content ariaLabel when the target cannot supply an appropriate menu label, and reproduce any local Appearance scope on the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "context-menu-supplemental",
+      "level": "must",
+      "statement": "Provide another visible or keyboard-discoverable route to every important command; ContextMenu is an enhancement, never the only access path."
+    },
+    {
+      "id": "context-menu-trigger-semantics",
+      "level": "must",
+      "statement": "Keep Trigger as a paintless behavior wrapper and preserve the target's native role, name, action, handlers, and composition instead of inventing button semantics or target paint."
+    },
+    {
+      "id": "context-menu-input-contract",
+      "level": "must",
+      "statement": "Rely on Atom for secondary-click coordinates, Shift+F10 and Context Menu key anchoring, cross-target handoff, and the fixed cancel-safe 700 ms touch and pen long press; do not add gesture timers or positioning listeners."
+    },
+    {
+      "id": "context-menu-content-name",
+      "level": "must",
+      "statement": "Give Content an explicit ariaLabel when the contextual target cannot generate an appropriate accessible menu name."
+    },
+    {
+      "id": "context-menu-item-model",
+      "level": "must",
+      "statement": "Use uniquely valued command, checkbox, and radio item roles, provide textValue when rendered content is not searchable text, and preserve disabled-item navigation, typeahead, closeOnSelect, and paired submenu behavior."
+    },
+    {
+      "id": "context-menu-row-anatomy",
+      "level": "must",
+      "statement": "Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding row columns, selection glyphs, or destructive emphasis."
+    },
+    {
+      "id": "context-menu-responsive",
+      "level": "should",
+      "statement": "Keep Content collision-aware and internally scrollable at its available height; verify repeated invocation points, edge collision, zoom, narrow viewports, long labels, and LTR and RTL submenus without changing it into a mobile tray."
+    },
+    {
+      "id": "context-menu-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it."
+    },
+    {
+      "id": "context-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus context-menu.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making right-click the only route to an action, styling Trigger as a control, or implementing another long-press and point-positioning system.",
+      "correction": "Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation contract."
+    },
+    {
+      "mistake": "Using ContextMenu for navigation or form selection, hand-building row columns, or closing the menu tree with document listeners.",
+      "correction": "Choose the semantic owner, compose the public item anatomy, and rely on Atom's Menu focus and dismissal behavior."
+    }
+  ],
+  "validation": [
+    "Verify the visible alternative, secondary click at changing coordinates, Shift+F10 and Context Menu key opening, repeated and cross-target invocation, disabled state, and touch and pen hold cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.",
+    "Verify Content naming, real item focus, Home/End and typeahead, disabled navigation without activation, checkbox mixed and radio state, selection close policy, submenu keys and whole-tree dismissal, Tab, Escape, outside activation, and focus return.",
+    "Verify three densities, row anatomy and danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "context-menu",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menu",
+      "versionPolicy": "installed-exact"
+    },
+    "dropdown-menu",
+    "menubar",
+    "navigation-menu",
+    "nav-list",
+    "select",
+    "button",
+    "appearance"
+  ]
+}

package/dist/agents/context-menu.md

@@ -0,0 +1,54 @@
+# ContextMenu agent guide
+
+## Purpose
+
+Present finished target-specific commands at a secondary-click, keyboard context-menu invocation, or cancel-safe touch and pen long press while Atom owns invocation, menu semantics, focus, dismissal, and positioning.
+
+## Use when
+
+- Commands belong to the exact file, row, canvas object, or region invoked contextually and every important command also has a visible or keyboard-discoverable route.
+
+## Choose something else when
+
+- The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar. Use DropdownMenu, visible Brick controls, or Menubar.
+- The content is site navigation or form-value selection. Use NavigationMenu or NavList, or Select.
+
+## Required composition
+
+- Compose ContextMenu.Root with ContextMenu.Trigger around the owned target and ContextMenu.Portal with ContextMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.
+- Keep Trigger paintless and preserve the target's native semantics through asChild or render. Give Content ariaLabel when the target cannot supply an appropriate menu label, and reproduce any local Appearance scope on the portalled visual root.
+
+## Rules
+
+- **MUST:** Provide another visible or keyboard-discoverable route to every important command; ContextMenu is an enhancement, never the only access path.
+- **MUST:** Keep Trigger as a paintless behavior wrapper and preserve the target's native role, name, action, handlers, and composition instead of inventing button semantics or target paint.
+- **MUST:** Rely on Atom for secondary-click coordinates, Shift+F10 and Context Menu key anchoring, cross-target handoff, and the fixed cancel-safe 700 ms touch and pen long press; do not add gesture timers or positioning listeners.
+- **MUST:** Give Content an explicit ariaLabel when the contextual target cannot generate an appropriate accessible menu name.
+- **MUST:** Use uniquely valued command, checkbox, and radio item roles, provide textValue when rendered content is not searchable text, and preserve disabled-item navigation, typeahead, closeOnSelect, and paired submenu behavior.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding row columns, selection glyphs, or destructive emphasis.
+- **SHOULD:** Keep Content collision-aware and internally scrollable at its available height; verify repeated invocation points, edge collision, zoom, narrow viewports, long labels, and LTR and RTL submenus without changing it into a mobile tray.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus context-menu.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Making right-click the only route to an action, styling Trigger as a control, or implementing another long-press and point-positioning system. **Instead:** Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation contract.
+- **Avoid:** Using ContextMenu for navigation or form selection, hand-building row columns, or closing the menu tree with document listeners. **Instead:** Choose the semantic owner, compose the public item anatomy, and rely on Atom's Menu focus and dismissal behavior.
+
+## Validation checklist
+
+- Verify the visible alternative, secondary click at changing coordinates, Shift+F10 and Context Menu key opening, repeated and cross-target invocation, disabled state, and touch and pen hold cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.
+- Verify Content naming, real item focus, Home/End and typeahead, disabled navigation without activation, checkbox mixed and radio state, selection close policy, submenu keys and whole-tree dismissal, Tab, Escape, outside activation, and focus return.
+- Verify three densities, row anatomy and danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/context-menu`
+- `@flowstack-ui/atom/agents/menu`
+- `dropdown-menu`
+- `menubar`
+- `navigation-menu`
+- `nav-list`
+- `select`
+- `button`
+- `appearance`