@flowstack-ui/brick 0.1.9 → 0.1.11

package/dist/agents/data-grid.json

@@ -0,0 +1,127 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "data-grid",
+  "name": "Data Grid",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present flat interactive tabular data with Atom-owned active-cell navigation and optional row selection while applications own data, sorting, filtering, and pagination.",
+  "useWhen": [
+    "People must navigate tabular cells with arrow keys, select rows, or activate sortable column headers."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "People only need to read and compare static row-and-column data.",
+      "useInstead": "Table"
+    },
+    {
+      "condition": "The content is a visual card collection or ordinary two-dimensional page layout.",
+      "useInstead": "Grid, List, or Card composition"
+    },
+    {
+      "condition": "Cells must contain independent controls, support editing, resize or pin columns, virtualize rows, or expose a schema-driven enterprise data engine.",
+      "useInstead": "An application-owned data tool or a separately qualified future component"
+    }
+  ],
+  "composition": [
+    "Compose explicit Container when wide content needs horizontal overflow, then Root with Caption or another stable accessible name, Header, Body, optional Footer, indexed Rows, indexed ColumnHeaders, and Cells.",
+    "Keep all row and column indexes one-based and provide truthful logical rowCount and columnCount, including when only one page or window is rendered.",
+    "Place external Toolbar, filtering controls, result count, and Pagination around the grid; Data Grid never creates or executes those systems.",
+    "For application-controlled sorting, give the ColumnHeader onAction, update the data and sortDirection outside Data Grid, and keep SortIndicator decorative."
+  ],
+  "rules": [
+    {
+      "id": "data-grid-interactive-boundary",
+      "level": "must",
+      "statement": "Choose Data Grid only when composite keyboard navigation, row selection, or sortable-header activation has real value; use Table for static comparison."
+    },
+    {
+      "id": "data-grid-name-index-count",
+      "level": "must",
+      "statement": "Provide one stable accessible name, one-based row and column indexes, and truthful logical counts for the complete represented data set."
+    },
+    {
+      "id": "data-grid-data-ownership",
+      "level": "must",
+      "statement": "Keep data transformation, filtering, sorting direction changes, fetching, caching, URL state, pagination, stale-request cancellation, and persistence in the application."
+    },
+    {
+      "id": "data-grid-external-controls",
+      "level": "must",
+      "statement": "Compose independently named Brick controls and Pagination outside Root; do not place arbitrary interactive controls inside v1 cells or make the grid itself own surrounding workflow state."
+    },
+    {
+      "id": "data-grid-overflow",
+      "level": "must",
+      "statement": "Author DataGrid.Container explicitly when honest columns need horizontal overflow; Root never inserts containment and narrow layouts must preserve the tabular relationships."
+    },
+    {
+      "id": "data-grid-outline-owner",
+      "level": "must",
+      "statement": "Let the outline Root own its border, radius, and exposed cell corners; do not add a second framed or clipping wrapper to repair the outline recipe."
+    },
+    {
+      "id": "data-grid-selection-identity",
+      "level": "must",
+      "statement": "Use stable row IDs as selection values, keep active cell and row selection as independent states, and do not derive identity from the current visual index."
+    },
+    {
+      "id": "data-grid-sort-composition",
+      "level": "must",
+      "statement": "Give an actionable sortable ColumnHeader pointer and Enter parity, expose sortDirection only on the active sorted header, and treat SortIndicator as decorative."
+    },
+    {
+      "id": "data-grid-virtualization",
+      "level": "must",
+      "statement": "If an application windows rows, preserve full logical one-based indexes and totals and keep the active cell mounted or move active state before it leaves the DOM; geometry utilities do not own grid semantics or focus."
+    },
+    {
+      "id": "data-grid-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus data-grid.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Data Grid because a static table has many rows.",
+      "correction": "Use Table until arrow-key cell navigation, row selection, or sortable-header activation is a genuine task requirement."
+    },
+    {
+      "mistake": "Putting search, filters, pagination, fetches, and data mutation inside Data Grid.",
+      "correction": "Compose those application-owned systems around the public Data Grid anatomy."
+    },
+    {
+      "mistake": "Placing buttons, links, editable fields, or menus in v1 cells without an interaction mode.",
+      "correction": "Keep cells non-editing and use an application-owned data tool when independent cell controls are required."
+    },
+    {
+      "mistake": "Using zero-based or page-local indexes while claiming a larger logical set.",
+      "correction": "Pass one-based logical indexes and truthful counts so active-descendant announcements remain coherent."
+    },
+    {
+      "mistake": "Wrapping an outline Data Grid in another bordered or rounded clipping surface to hide sharp cell corners.",
+      "correction": "Keep Container responsible only for overflow and let the outline Root own one complete rounded boundary."
+    }
+  ],
+  "validation": [
+    "Inspect the accessible name, roles, one-based indexes, logical counts, active descendant, selection metadata, disabled/read-only states, and sort direction.",
+    "Test one Tab entry, arrows, Home and End, PageUp and PageDown, Ctrl or Meta plus Home and End, RTL mapping, disabled skipping, and pointer or Enter sortable-header parity.",
+    "Verify stable selection IDs and focus after application sorting, filtering, page changes, or reordered data.",
+    "Check explicit Container overflow, complete outline corners with and without Header or Footer, 320 CSS pixels, 200% text, 400% zoom, long content, dark appearance, forced colors, and no page-level horizontal overflow.",
+    "Confirm editing, arbitrary cell controls, virtualization, schemas, fetching, filtering, pagination, and persistence remain excluded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "data-grid",
+      "versionPolicy": "installed-exact"
+    },
+    "table",
+    "tree-grid",
+    "toolbar",
+    "pagination",
+    "badge",
+    "scroll-area"
+  ]
+}

package/dist/agents/data-grid.md

@@ -0,0 +1,61 @@
+# Data Grid agent guide
+
+## Purpose
+
+Present flat interactive tabular data with Atom-owned active-cell navigation and optional row selection while applications own data, sorting, filtering, and pagination.
+
+## Use when
+
+- People must navigate tabular cells with arrow keys, select rows, or activate sortable column headers.
+
+## Choose something else when
+
+- People only need to read and compare static row-and-column data. Use Table.
+- The content is a visual card collection or ordinary two-dimensional page layout. Use Grid, List, or Card composition.
+- Cells must contain independent controls, support editing, resize or pin columns, virtualize rows, or expose a schema-driven enterprise data engine. Use An application-owned data tool or a separately qualified future component.
+
+## Required composition
+
+- Compose explicit Container when wide content needs horizontal overflow, then Root with Caption or another stable accessible name, Header, Body, optional Footer, indexed Rows, indexed ColumnHeaders, and Cells.
+- Keep all row and column indexes one-based and provide truthful logical rowCount and columnCount, including when only one page or window is rendered.
+- Place external Toolbar, filtering controls, result count, and Pagination around the grid; Data Grid never creates or executes those systems.
+- For application-controlled sorting, give the ColumnHeader onAction, update the data and sortDirection outside Data Grid, and keep SortIndicator decorative.
+
+## Rules
+
+- **MUST:** Choose Data Grid only when composite keyboard navigation, row selection, or sortable-header activation has real value; use Table for static comparison.
+- **MUST:** Provide one stable accessible name, one-based row and column indexes, and truthful logical counts for the complete represented data set.
+- **MUST:** Keep data transformation, filtering, sorting direction changes, fetching, caching, URL state, pagination, stale-request cancellation, and persistence in the application.
+- **MUST:** Compose independently named Brick controls and Pagination outside Root; do not place arbitrary interactive controls inside v1 cells or make the grid itself own surrounding workflow state.
+- **MUST:** Author DataGrid.Container explicitly when honest columns need horizontal overflow; Root never inserts containment and narrow layouts must preserve the tabular relationships.
+- **MUST:** Let the outline Root own its border, radius, and exposed cell corners; do not add a second framed or clipping wrapper to repair the outline recipe.
+- **MUST:** Use stable row IDs as selection values, keep active cell and row selection as independent states, and do not derive identity from the current visual index.
+- **MUST:** Give an actionable sortable ColumnHeader pointer and Enter parity, expose sortDirection only on the active sorted header, and treat SortIndicator as decorative.
+- **MUST:** If an application windows rows, preserve full logical one-based indexes and totals and keep the active cell mounted or move active state before it leaves the DOM; geometry utilities do not own grid semantics or focus.
+- **MUST:** Load styles.css or core.css plus data-grid.css.
+
+## Common mistakes
+
+- **Avoid:** Using Data Grid because a static table has many rows. **Instead:** Use Table until arrow-key cell navigation, row selection, or sortable-header activation is a genuine task requirement.
+- **Avoid:** Putting search, filters, pagination, fetches, and data mutation inside Data Grid. **Instead:** Compose those application-owned systems around the public Data Grid anatomy.
+- **Avoid:** Placing buttons, links, editable fields, or menus in v1 cells without an interaction mode. **Instead:** Keep cells non-editing and use an application-owned data tool when independent cell controls are required.
+- **Avoid:** Using zero-based or page-local indexes while claiming a larger logical set. **Instead:** Pass one-based logical indexes and truthful counts so active-descendant announcements remain coherent.
+- **Avoid:** Wrapping an outline Data Grid in another bordered or rounded clipping surface to hide sharp cell corners. **Instead:** Keep Container responsible only for overflow and let the outline Root own one complete rounded boundary.
+
+## Validation checklist
+
+- Inspect the accessible name, roles, one-based indexes, logical counts, active descendant, selection metadata, disabled/read-only states, and sort direction.
+- Test one Tab entry, arrows, Home and End, PageUp and PageDown, Ctrl or Meta plus Home and End, RTL mapping, disabled skipping, and pointer or Enter sortable-header parity.
+- Verify stable selection IDs and focus after application sorting, filtering, page changes, or reordered data.
+- Check explicit Container overflow, complete outline corners with and without Header or Footer, 320 CSS pixels, 200% text, 400% zoom, long content, dark appearance, forced colors, and no page-level horizontal overflow.
+- Confirm editing, arbitrary cell controls, virtualization, schemas, fetching, filtering, pagination, and persistence remain excluded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/data-grid`
+- `table`
+- `tree-grid`
+- `toolbar`
+- `pagination`
+- `badge`
+- `scroll-area`

package/dist/agents/data-list.json

@@ -0,0 +1,63 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "data-list",
+  "name": "Data List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present repeated term/value metadata with native description-list semantics and a finished responsive recipe.",
+  "useWhen": [
+    "Several related labels and values describe one record, profile, object, or specification set."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Items are peers rather than terms and descriptions, or the content is a columnar dataset.",
+      "useInstead": "List for peers or Table/Data Grid for columnar data"
+    },
+    {
+      "condition": "The values are editable form controls.",
+      "useInstead": "Field or Fieldset"
+    }
+  ],
+  "composition": [
+    "Compose Root with Item groups; place one or more Label parts before one or more Value parts inside every Item."
+  ],
+  "rules": [
+    {
+      "id": "data-list-native-anatomy",
+      "level": "must",
+      "statement": "Use Root, Item, Label, and Value so the rendered dl/div/dt/dd grammar remains valid; do not recreate the relationship with ul/li or generic Stack children."
+    },
+    {
+      "id": "data-list-responsive-source",
+      "level": "must",
+      "statement": "Keep one label-then-value source order and use responsive orientation rather than duplicating mobile and desktop metadata trees."
+    },
+    {
+      "id": "data-list-labels",
+      "level": "must",
+      "statement": "Write visible meaningful labels; do not add empty Label parts solely to force alignment."
+    },
+    {
+      "id": "data-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus data-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using List for phone/email/title facts or adding ARIA term/definition roles to native Data List parts.",
+      "correction": "Use DataList native anatomy and rely on its native semantics without redundant ARIA."
+    }
+  ],
+  "validation": [
+    "Check dl/div/dt/dd anatomy, complete visible labels, source order, horizontal and vertical orientation, long values, links inside Value, zoom, RTL, forced colors, and CSS loading."
+  ],
+  "related": [
+    "list",
+    "table",
+    "data-grid",
+    "field",
+    "stack"
+  ]
+}

package/dist/agents/data-list.md

@@ -0,0 +1,41 @@
+# Data List agent guide
+
+## Purpose
+
+Present repeated term/value metadata with native description-list semantics and a finished responsive recipe.
+
+## Use when
+
+- Several related labels and values describe one record, profile, object, or specification set.
+
+## Choose something else when
+
+- Items are peers rather than terms and descriptions, or the content is a columnar dataset. Use List for peers or Table/Data Grid for columnar data.
+- The values are editable form controls. Use Field or Fieldset.
+
+## Required composition
+
+- Compose Root with Item groups; place one or more Label parts before one or more Value parts inside every Item.
+
+## Rules
+
+- **MUST:** Use Root, Item, Label, and Value so the rendered dl/div/dt/dd grammar remains valid; do not recreate the relationship with ul/li or generic Stack children.
+- **MUST:** Keep one label-then-value source order and use responsive orientation rather than duplicating mobile and desktop metadata trees.
+- **MUST:** Write visible meaningful labels; do not add empty Label parts solely to force alignment.
+- **MUST:** Load styles.css or core.css plus data-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using List for phone/email/title facts or adding ARIA term/definition roles to native Data List parts. **Instead:** Use DataList native anatomy and rely on its native semantics without redundant ARIA.
+
+## Validation checklist
+
+- Check dl/div/dt/dd anatomy, complete visible labels, source order, horizontal and vertical orientation, long values, links inside Value, zoom, RTL, forced colors, and CSS loading.
+
+## Related guidance
+
+- `list`
+- `table`
+- `data-grid`
+- `field`
+- `stack`

package/dist/agents/dialog.json

@@ -0,0 +1,112 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "dialog",
+  "name": "Dialog",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished modal task, form, settings flow, or focused information surface while Atom owns focus, dismissal, portal, background-isolation, and scroll-lock behavior.",
+  "useWhen": [
+    "A user must focus on a temporary blocking task, form, settings flow, or detailed information surface before returning to the underlying application."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The user must make an urgent consequential choice, the surface belongs at a screen edge, or the panel is compact and anchored to a trigger.",
+      "useInstead": "AlertDialog, Drawer, or Popover"
+    },
+    {
+      "condition": "The content is an in-page disclosure, a command menu, or passive transient feedback.",
+      "useInstead": "Collapsible or Accordion, Menu, or Toast"
+    }
+  ],
+  "composition": [
+    "Compose Dialog.Root with Dialog.Trigger and Dialog.Portal; inside Portal keep Dialog.Overlay and Dialog.Content as siblings. Inside Content, arrange Dialog.Header with Dialog.Title and an optional Dialog.Description, put scrollable task content in Dialog.Body, and place actions and Dialog.Close in Dialog.Footer as the workflow requires.",
+    "Use Dialog.Branch only for an unavoidable consumer-owned third-party portal that cannot mount inside Content. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "dialog-modal-task",
+      "level": "must",
+      "statement": "Use Dialog for an ordinary blocking task or information surface; use AlertDialog for an urgent consequential decision and Popover for compact anchored work."
+    },
+    {
+      "id": "dialog-overlay-content-siblings",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal; never place Content beneath the aria-hidden Overlay."
+    },
+    {
+      "id": "dialog-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description only when it supplies useful context."
+    },
+    {
+      "id": "dialog-atom-behavior",
+      "level": "must",
+      "statement": "Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them."
+    },
+    {
+      "id": "dialog-body-scroll",
+      "level": "must",
+      "statement": "Put long or variable task content in Body so the header and footer remain available while the body owns overflow within the safe viewport bounds."
+    },
+    {
+      "id": "dialog-footer-actions",
+      "level": "must",
+      "statement": "Use Footer justify for simple action distribution and Brick layout components for complex grouping; preserve a clear primary action and a visible close or cancellation path when the workflow requires one."
+    },
+    {
+      "id": "dialog-branch-scope",
+      "level": "must",
+      "statement": "Mount descendant interactive portals inside Content when possible; otherwise wrap only the unavoidable same-document third-party portal owner with Branch."
+    },
+    {
+      "id": "dialog-size-responsive",
+      "level": "should",
+      "statement": "Choose sm, md, or lg from the content measure rather than importance, and verify safe-area bounds, Body overflow, footer reflow, zoom, and narrow or short effective viewports."
+    },
+    {
+      "id": "dialog-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": "dialog-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus dialog.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Nesting Content inside Overlay, hand-building focus or document listeners, or using Dialog for an anchored utility panel.",
+      "correction": "Keep Overlay and Content siblings, rely on Dialog and Atom Modal behavior, and choose Popover for compact anchored work."
+    },
+    {
+      "mistake": "Letting long content scroll the whole surface or assuming an unrelated third-party portal is automatically inside the modal.",
+      "correction": "Put overflow in Body and mount the descendant portal inside Content or register its owner with Branch."
+    }
+  ],
+  "validation": [
+    "Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.",
+    "Verify controlled state, nested dialogs and every Branch, background isolation, document scroll lock, long Body scrolling, footer reflow, exit presence, zoom, reduced motion, forced colors, and narrow and short viewports.",
+    "Check light and dark appearance on the actual portalled Content and confirm Dialog CSS plus every composed child component stylesheet is loaded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "dialog",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "modal",
+      "versionPolicy": "installed-exact"
+    },
+    "alert-dialog",
+    "drawer",
+    "popover",
+    "button",
+    "appearance"
+  ]
+}

package/dist/agents/dialog.md

@@ -0,0 +1,53 @@
+# Dialog agent guide
+
+## Purpose
+
+Present a finished modal task, form, settings flow, or focused information surface while Atom owns focus, dismissal, portal, background-isolation, and scroll-lock behavior.
+
+## Use when
+
+- A user must focus on a temporary blocking task, form, settings flow, or detailed information surface before returning to the underlying application.
+
+## Choose something else when
+
+- The user must make an urgent consequential choice, the surface belongs at a screen edge, or the panel is compact and anchored to a trigger. Use AlertDialog, Drawer, or Popover.
+- The content is an in-page disclosure, a command menu, or passive transient feedback. Use Collapsible or Accordion, Menu, or Toast.
+
+## Required composition
+
+- Compose Dialog.Root with Dialog.Trigger and Dialog.Portal; inside Portal keep Dialog.Overlay and Dialog.Content as siblings. Inside Content, arrange Dialog.Header with Dialog.Title and an optional Dialog.Description, put scrollable task content in Dialog.Body, and place actions and Dialog.Close in Dialog.Footer as the workflow requires.
+- Use Dialog.Branch only for an unavoidable consumer-owned third-party portal that cannot mount inside Content. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root.
+
+## Rules
+
+- **MUST:** Use Dialog for an ordinary blocking task or information surface; use AlertDialog for an urgent consequential decision and Popover for compact anchored work.
+- **MUST:** Render Overlay and Content as siblings inside Portal; never place Content beneath the aria-hidden Overlay.
+- **MUST:** Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description only when it supplies useful context.
+- **MUST:** Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them.
+- **MUST:** Put long or variable task content in Body so the header and footer remain available while the body owns overflow within the safe viewport bounds.
+- **MUST:** Use Footer justify for simple action distribution and Brick layout components for complex grouping; preserve a clear primary action and a visible close or cancellation path when the workflow requires one.
+- **MUST:** Mount descendant interactive portals inside Content when possible; otherwise wrap only the unavoidable same-document third-party portal owner with Branch.
+- **SHOULD:** Choose sm, md, or lg from the content measure rather than importance, and verify safe-area bounds, Body overflow, footer reflow, zoom, and narrow or short effective viewports.
+- **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 dialog.css.
+
+## Common mistakes
+
+- **Avoid:** Nesting Content inside Overlay, hand-building focus or document listeners, or using Dialog for an anchored utility panel. **Instead:** Keep Overlay and Content siblings, rely on Dialog and Atom Modal behavior, and choose Popover for compact anchored work.
+- **Avoid:** Letting long content scroll the whole surface or assuming an unrelated third-party portal is automatically inside the modal. **Instead:** Put overflow in Body and mount the descendant portal inside Content or register its owner with Branch.
+
+## Validation checklist
+
+- Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.
+- Verify controlled state, nested dialogs and every Branch, background isolation, document scroll lock, long Body scrolling, footer reflow, exit presence, zoom, reduced motion, forced colors, and narrow and short viewports.
+- Check light and dark appearance on the actual portalled Content and confirm Dialog CSS plus every composed child component stylesheet is loaded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/dialog`
+- `@flowstack-ui/atom/agents/modal`
+- `alert-dialog`
+- `drawer`
+- `popover`
+- `button`
+- `appearance`

package/dist/agents/dropdown-menu.json

@@ -0,0 +1,112 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "dropdown-menu",
+  "name": "DropdownMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished compact command or settings menu from a visible button while Atom owns menu semantics, real item focus, keyboard navigation, selection, dismissal, portals, and collision-aware placement.",
+  "useWhen": [
+    "A visible named button should reveal a short list of commands, independent settings, exclusive settings, secondary destinations, or nested commands."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Commands belong to a contextual gesture, several persistent application command categories, a form value, or ordinary site navigation.",
+      "useInstead": "ContextMenu, Menubar, Select, or NavigationMenu or NavList"
+    }
+  ],
+  "composition": [
+    "Compose DropdownMenu.Root with DropdownMenu.Trigger asChild around a finished named Button or IconButton, plus DropdownMenu.Portal and DropdownMenu.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.",
+    "For a genuine secondary destination, compose Item asChild around one Brick Link and preserve its href; command rows use onSelect. Reproduce any local Appearance scope on portalled Content and SubContent."
+  ],
+  "rules": [
+    {
+      "id": "dropdown-menu-selection",
+      "level": "must",
+      "statement": "Use DropdownMenu for commands or settings opened by a visible button; use Select for a form value, ContextMenu for contextual invocation, Menubar for persistent command categories, and navigation owners for route lists."
+    },
+    {
+      "id": "dropdown-menu-trigger",
+      "level": "must",
+      "statement": "Compose Trigger around a visible finished Button or IconButton with a complete accessible name and preserve Atom's button, popup, expanded, controls, disabled, and input-aware opening semantics."
+    },
+    {
+      "id": "dropdown-menu-item-model",
+      "level": "must",
+      "statement": "Use uniquely valued Item, CheckboxItem, and RadioItem for their matching roles, provide textValue when rendered children are not searchable text, and preserve real focus, typeahead, and disabled-item navigation without activation."
+    },
+    {
+      "id": "dropdown-menu-selection-close",
+      "level": "must",
+      "statement": "Choose closeOnSelect by job: commands normally close while checkbox and radio settings normally remain open; do not close the tree with competing handlers or document listeners."
+    },
+    {
+      "id": "dropdown-menu-submenu",
+      "level": "must",
+      "statement": "Keep SubTrigger and SubContent inside one Sub and preserve direction-aware cascade keys, hover intent, whole-tree dismissal, and collision-resolved placement instead of inventing responsive drill-in behavior."
+    },
+    {
+      "id": "dropdown-menu-destination",
+      "level": "must",
+      "statement": "Compose a genuine destination Item around one Brick Link so href and menuitem semantics share the same interactive owner; do not attach routing to a command-only div."
+    },
+    {
+      "id": "dropdown-menu-row-anatomy",
+      "level": "must",
+      "statement": "Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding columns, selection glyphs, icon sizing, or destructive emphasis."
+    },
+    {
+      "id": "dropdown-menu-responsive",
+      "level": "should",
+      "statement": "Let Content use its collision-aware available height and native internal scrolling; verify three densities, long labels, zoom, narrow viewports, LTR and RTL, and reachable nested commands without semantic transformation."
+    },
+    {
+      "id": "dropdown-menu-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on Content and SubContent or target a portal container inside it."
+    },
+    {
+      "id": "dropdown-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus dropdown-menu.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using an unlabeled icon trigger, Popover for menu commands, DropdownMenu for form selection or primary navigation, or custom key and document dismissal handlers.",
+      "correction": "Use a named Button or IconButton, choose the semantic owner, and rely on DropdownMenu and shared Menu behavior."
+    },
+    {
+      "mistake": "Nesting a Button inside Item, rebuilding row columns, or treating Shortcut text as registered keyboard behavior.",
+      "correction": "Keep one interactive owner, compose the public row anatomy, and register application shortcuts outside DropdownMenu."
+    }
+  ],
+  "validation": [
+    "Verify Trigger name and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial real item focus, Home/End, typeahead, controlled and disabled state, Tab exit, Escape, outside dismissal, and focus return.",
+    "Verify command, destination-link, checkbox mixed, radio, group, indicator, separator, and submenu behavior; unique values and textValue; close policies; modal and parent-modal ownership; and LTR and RTL cascade keys.",
+    "Verify three densities, Leading geometry, danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, reduced motion, forced colors, light and dark portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "dropdown-menu",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menu",
+      "versionPolicy": "installed-exact"
+    },
+    "context-menu",
+    "menubar",
+    "select",
+    "navigation-menu",
+    "nav-list",
+    "button",
+    "icon-button",
+    "link",
+    "appearance"
+  ]
+}

package/dist/agents/dropdown-menu.md

@@ -0,0 +1,56 @@
+# DropdownMenu agent guide
+
+## Purpose
+
+Present a finished compact command or settings menu from a visible button while Atom owns menu semantics, real item focus, keyboard navigation, selection, dismissal, portals, and collision-aware placement.
+
+## Use when
+
+- A visible named button should reveal a short list of commands, independent settings, exclusive settings, secondary destinations, or nested commands.
+
+## Choose something else when
+
+- Commands belong to a contextual gesture, several persistent application command categories, a form value, or ordinary site navigation. Use ContextMenu, Menubar, Select, or NavigationMenu or NavList.
+
+## Required composition
+
+- Compose DropdownMenu.Root with DropdownMenu.Trigger asChild around a finished named Button or IconButton, plus DropdownMenu.Portal and DropdownMenu.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.
+- For a genuine secondary destination, compose Item asChild around one Brick Link and preserve its href; command rows use onSelect. Reproduce any local Appearance scope on portalled Content and SubContent.
+
+## Rules
+
+- **MUST:** Use DropdownMenu for commands or settings opened by a visible button; use Select for a form value, ContextMenu for contextual invocation, Menubar for persistent command categories, and navigation owners for route lists.
+- **MUST:** Compose Trigger around a visible finished Button or IconButton with a complete accessible name and preserve Atom's button, popup, expanded, controls, disabled, and input-aware opening semantics.
+- **MUST:** Use uniquely valued Item, CheckboxItem, and RadioItem for their matching roles, provide textValue when rendered children are not searchable text, and preserve real focus, typeahead, and disabled-item navigation without activation.
+- **MUST:** Choose closeOnSelect by job: commands normally close while checkbox and radio settings normally remain open; do not close the tree with competing handlers or document listeners.
+- **MUST:** Keep SubTrigger and SubContent inside one Sub and preserve direction-aware cascade keys, hover intent, whole-tree dismissal, and collision-resolved placement instead of inventing responsive drill-in behavior.
+- **MUST:** Compose a genuine destination Item around one Brick Link so href and menuitem semantics share the same interactive owner; do not attach routing to a command-only div.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding columns, selection glyphs, icon sizing, or destructive emphasis.
+- **SHOULD:** Let Content use its collision-aware available height and native internal scrolling; verify three densities, long labels, zoom, narrow viewports, LTR and RTL, and reachable nested commands without semantic transformation.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on Content and SubContent or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus dropdown-menu.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using an unlabeled icon trigger, Popover for menu commands, DropdownMenu for form selection or primary navigation, or custom key and document dismissal handlers. **Instead:** Use a named Button or IconButton, choose the semantic owner, and rely on DropdownMenu and shared Menu behavior.
+- **Avoid:** Nesting a Button inside Item, rebuilding row columns, or treating Shortcut text as registered keyboard behavior. **Instead:** Keep one interactive owner, compose the public row anatomy, and register application shortcuts outside DropdownMenu.
+
+## Validation checklist
+
+- Verify Trigger name and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial real item focus, Home/End, typeahead, controlled and disabled state, Tab exit, Escape, outside dismissal, and focus return.
+- Verify command, destination-link, checkbox mixed, radio, group, indicator, separator, and submenu behavior; unique values and textValue; close policies; modal and parent-modal ownership; and LTR and RTL cascade keys.
+- Verify three densities, Leading geometry, danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, reduced motion, forced colors, light and dark portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/dropdown-menu`
+- `@flowstack-ui/atom/agents/menu`
+- `context-menu`
+- `menubar`
+- `select`
+- `navigation-menu`
+- `nav-list`
+- `button`
+- `icon-button`
+- `link`
+- `appearance`