@flowstack-ui/brick 0.1.3 → 0.1.5

package/dist/agents/navigation-menu.md

@@ -0,0 +1,49 @@
+# NavigationMenu agent guide
+
+## Purpose
+
+Present polished disclosure navigation while Atom owns trigger geometry, viewport positioning, focus, keyboard, pointer, and dismissal behavior.
+
+## Use when
+
+- A top-level site or product navigation combines direct links with disclosure panels of related destinations.
+
+## Choose something else when
+
+- The content is an action menu, persistent route rail, mobile drawer, or tab switcher. Use DropdownMenu, NavList, Drawer, or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item containing Link or Trigger plus Content, with Viewport and optional Indicator/Arrow according to the documented anatomy; lay out content with Brick components.
+
+## Rules
+
+- **MUST:** Keep Indicator and Viewport inside the Root-owned coordinate system and let Atom's measured trigger and viewport geometry position them; use documented NavigationMenu tokens and public parts for visual customization.
+- **MUST:** Let the horizontal Viewport use Atom's active-trigger-centered, collision-aware position; do not re-center it on the full Navigation Menu list or page header.
+- **MUST:** Do not invent overlay props such as side, align, sideOffset, or alignOffset; NavigationMenu does not expose the floating-overlay positioning API.
+- **MUST:** Keep contents focused on navigation destinations rather than commands or unrelated marketing panels.
+- **MUST:** Use Link variant=panel with one direct Surface child when one rich destination should own the complete clickable area; let Surface own inset, radius, border, elevation, and background, and keep all composed children non-interactive and concise.
+- **MUST:** Preserve the panel Link's focus fallback; with a direct Surface the ring follows that Surface, and without one the Link itself must remain visibly focused.
+- **MUST:** In React Server Components, import the component subpath as import * as NavigationMenu from @flowstack-ui/brick/navigation-menu; use the legacy root-package runtime object only inside a client-owned module.
+- **MUST:** Load styles.css or core.css plus navigation-menu.css and every child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Anchoring the panel or arrow to the logo/page, adding custom hover state that fights Atom, or applying Popover-style offset props that NavigationMenu does not own. **Instead:** Keep Viewport and Indicator under Root, let NavigationMenu own geometry and open state, then customize documented recipes, tokens, and public parts.
+- **Avoid:** Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned.
+- **Avoid:** Placing a small link inside a separately clickable-looking Surface, styling NavigationMenu.Link as a duplicate Surface, or nesting a Link or Button inside NavigationMenu.Link. **Instead:** Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry.
+
+## Validation checklist
+
+- Test hover, click, focus, arrow keys, Escape, outside interaction, links, viewport transitions, active-trigger centering, boundary collision, arrow alignment, zoom, narrow widths, and RTL.
+- Confirm destination semantics, Root-relative geometry, panel focus fallback, documented customization hooks, and CSS delivery.
+- In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client.
+
+## Related guidance
+
+- `app-bar`
+- `nav-list`
+- `drawer`
+- `dropdown-menu`
+- `link`
+- `interface-composition`

package/dist/agents/pagination.json

@@ -0,0 +1,48 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "pagination",
+  "name": "Pagination",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present polished movement through ordered result pages with current, boundary, and ellipsis states.",
+  "useWhen": [
+    "A result set or collection is divided into multiple ordered pages."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The controls move between guide articles, ancestors, or local panels.",
+      "useInstead": "Link composition, Breadcrumb, or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root and List with Previous, Page, Ellipsis, and Next parts; use real destinations when each page has a URL."
+  ],
+  "rules": [
+    {
+      "id": "pagination-responsive",
+      "level": "must",
+      "statement": "Adapt visible page ranges at narrow widths without removing previous/next meaning or current-page state."
+    },
+    {
+      "id": "pagination-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus pagination.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Pagination for previous/next documentation guides or allowing controls to wrap into an unreadable grid.",
+      "correction": "Use ordinary guide navigation links and reserve Pagination for numbered collections."
+    }
+  ],
+  "validation": [
+    "Check first, middle, last, current, disabled, ellipsis, long labels, narrow widths, focus, touch targets, and RTL.",
+    "Confirm URL pages are links and CSS is loaded."
+  ],
+  "related": [
+    "breadcrumb",
+    "link",
+    "button"
+  ]
+}

package/dist/agents/pagination.md

@@ -0,0 +1,37 @@
+# Pagination agent guide
+
+## Purpose
+
+Present polished movement through ordered result pages with current, boundary, and ellipsis states.
+
+## Use when
+
+- A result set or collection is divided into multiple ordered pages.
+
+## Choose something else when
+
+- The controls move between guide articles, ancestors, or local panels. Use Link composition, Breadcrumb, or Tabs.
+
+## Required composition
+
+- Compose Root and List with Previous, Page, Ellipsis, and Next parts; use real destinations when each page has a URL.
+
+## Rules
+
+- **MUST:** Adapt visible page ranges at narrow widths without removing previous/next meaning or current-page state.
+- **MUST:** Load styles.css or core.css plus pagination.css.
+
+## Common mistakes
+
+- **Avoid:** Using Pagination for previous/next documentation guides or allowing controls to wrap into an unreadable grid. **Instead:** Use ordinary guide navigation links and reserve Pagination for numbered collections.
+
+## Validation checklist
+
+- Check first, middle, last, current, disabled, ellipsis, long labels, narrow widths, focus, touch targets, and RTL.
+- Confirm URL pages are links and CSS is loaded.
+
+## Related guidance
+
+- `breadcrumb`
+- `link`
+- `button`

package/dist/agents/scroll-area.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "scroll-area",
+  "name": "ScrollArea",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and native input behavior.",
+  "useWhen": [
+    "A rail, code region, table wrapper, or bounded panel needs Brick scrollbar presentation and owned overflow behavior."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Ordinary page or content overflow works with native browser scrolling.",
+      "useInstead": "native overflow"
+    }
+  ],
+  "composition": [
+    "Compose Viewport and the needed Scrollbar/Thumb parts inside Root, adding Corner for two-axis presentation; give the wrapper a real size constraint."
+  ],
+  "rules": [
+    {
+      "id": "scroll-area-bounded",
+      "level": "must",
+      "statement": "Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport."
+    },
+    {
+      "id": "scroll-area-native",
+      "level": "must",
+      "statement": "Preserve wheel, trackpad, touch, keyboard, focus, and nested page scrolling."
+    },
+    {
+      "id": "scroll-area-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus scroll-area.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ScrollArea for every overflow or hiding clipped table content without horizontal scrolling.",
+      "correction": "Use native overflow by default and add ScrollArea with explicit horizontal behavior where it improves the contract."
+    }
+  ],
+  "validation": [
+    "Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.",
+    "Confirm the viewport constraint and CSS are loaded."
+  ],
+  "related": [
+    "table",
+    "data-grid",
+    "code-block",
+    "sidebar"
+  ]
+}

package/dist/agents/scroll-area.md

@@ -0,0 +1,39 @@
+# ScrollArea agent guide
+
+## Purpose
+
+Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and native input behavior.
+
+## Use when
+
+- A rail, code region, table wrapper, or bounded panel needs Brick scrollbar presentation and owned overflow behavior.
+
+## Choose something else when
+
+- Ordinary page or content overflow works with native browser scrolling. Use native overflow.
+
+## Required composition
+
+- Compose Viewport and the needed Scrollbar/Thumb parts inside Root, adding Corner for two-axis presentation; give the wrapper a real size constraint.
+
+## Rules
+
+- **MUST:** Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport.
+- **MUST:** Preserve wheel, trackpad, touch, keyboard, focus, and nested page scrolling.
+- **MUST:** Load styles.css or core.css plus scroll-area.css.
+
+## Common mistakes
+
+- **Avoid:** Using ScrollArea for every overflow or hiding clipped table content without horizontal scrolling. **Instead:** Use native overflow by default and add ScrollArea with explicit horizontal behavior where it improves the contract.
+
+## Validation checklist
+
+- Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.
+- Confirm the viewport constraint and CSS are loaded.
+
+## Related guidance
+
+- `table`
+- `data-grid`
+- `code-block`
+- `sidebar`

package/dist/agents/show.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "show",
+  "name": "Show",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Show content only at selected Brick breakpoints through CSS, avoiding JavaScript viewport state and hydration flicker.",
+  "useWhen": [
+    "A complete region should appear only at selected Brick breakpoints."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content must remain available to assistive technology while visually hidden, or rendering depends on authorization or data.",
+      "useInstead": "VisuallyHidden or application conditional rendering"
+    }
+  ],
+  "composition": [
+    "Wrap the smallest complete composition whose responsive presence changes; combine with Hide only for intentional alternate desktop/mobile structures."
+  ],
+  "rules": [
+    {
+      "id": "show-first-paint",
+      "level": "must",
+      "statement": "Use Show's CSS breakpoint contract rather than client viewport detection for responsive first paint."
+    },
+    {
+      "id": "show-valid-tree",
+      "level": "must",
+      "statement": "Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative."
+    },
+    {
+      "id": "show-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus show.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds.",
+      "correction": "Load the modular CSS and verify exact breakpoint boundaries."
+    }
+  ],
+  "validation": [
+    "Test boundary pixels, zoom, first paint, hydration, focus order, landmarks, and duplicate IDs.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "hide",
+    "visually-hidden",
+    "app-bar",
+    "drawer"
+  ]
+}

package/dist/agents/show.md

@@ -0,0 +1,39 @@
+# Show agent guide
+
+## Purpose
+
+Show content only at selected Brick breakpoints through CSS, avoiding JavaScript viewport state and hydration flicker.
+
+## Use when
+
+- A complete region should appear only at selected Brick breakpoints.
+
+## Choose something else when
+
+- Content must remain available to assistive technology while visually hidden, or rendering depends on authorization or data. Use VisuallyHidden or application conditional rendering.
+
+## Required composition
+
+- Wrap the smallest complete composition whose responsive presence changes; combine with Hide only for intentional alternate desktop/mobile structures.
+
+## Rules
+
+- **MUST:** Use Show's CSS breakpoint contract rather than client viewport detection for responsive first paint.
+- **MUST:** Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative.
+- **MUST:** Load styles.css or core.css plus show.css.
+
+## Common mistakes
+
+- **Avoid:** Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds. **Instead:** Load the modular CSS and verify exact breakpoint boundaries.
+
+## Validation checklist
+
+- Test boundary pixels, zoom, first paint, hydration, focus order, landmarks, and duplicate IDs.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `hide`
+- `visually-hidden`
+- `app-bar`
+- `drawer`

package/dist/agents/sidebar.json

@@ -0,0 +1,56 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "sidebar",
+  "name": "Sidebar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished application-shell side region with expanded, rail, and offcanvas visual states built on Atom Sidebar.",
+  "useWhen": [
+    "An application shell has persistent navigation or tools that collapse to a rail or leave the layout offcanvas."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The side panel is a temporary modal mobile menu or a static content aside.",
+      "useInstead": "Drawer or a semantic page region"
+    }
+  ],
+  "composition": [
+    "Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark."
+  ],
+  "rules": [
+    {
+      "id": "sidebar-layout-owner",
+      "level": "must",
+      "statement": "Use Sidebar state and public layout hooks instead of manually translating a generic aside and overlapping its active items."
+    },
+    {
+      "id": "sidebar-main",
+      "level": "must",
+      "statement": "Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell."
+    },
+    {
+      "id": "sidebar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus sidebar.css and every composed child stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main.",
+      "correction": "Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry."
+    }
+  ],
+  "validation": [
+    "Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.",
+    "Confirm landmark names and CSS delivery."
+  ],
+  "related": [
+    "nav-list",
+    "drawer",
+    "app-bar",
+    "container",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/sidebar.md

@@ -0,0 +1,41 @@
+# Sidebar agent guide
+
+## Purpose
+
+Provide a finished application-shell side region with expanded, rail, and offcanvas visual states built on Atom Sidebar.
+
+## Use when
+
+- An application shell has persistent navigation or tools that collapse to a rail or leave the layout offcanvas.
+
+## Choose something else when
+
+- The side panel is a temporary modal mobile menu or a static content aside. Use Drawer or a semantic page region.
+
+## Required composition
+
+- Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark.
+
+## Rules
+
+- **MUST:** Use Sidebar state and public layout hooks instead of manually translating a generic aside and overlapping its active items.
+- **MUST:** Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell.
+- **MUST:** Load styles.css or core.css plus sidebar.css and every composed child stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main. **Instead:** Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry.
+
+## Validation checklist
+
+- Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.
+- Confirm landmark names and CSS delivery.
+
+## Related guidance
+
+- `nav-list`
+- `drawer`
+- `app-bar`
+- `container`
+- `show`
+- `hide`

package/dist/agents/skip-link.json

@@ -0,0 +1,53 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "skip-link",
+  "name": "SkipLink",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a visibly focused skip-navigation control and matching main-content target using Atom focus behavior.",
+  "useWhen": [
+    "A page repeats header or navigation content before main content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "No repeated content precedes the primary content.",
+      "useInstead": "normal document focus order"
+    }
+  ],
+  "composition": [
+    "Place Root as the first useful focus target and one matching Target at main content; let Target own the main landmark unless custom-rendered."
+  ],
+  "rules": [
+    {
+      "id": "skip-link-visible-focus",
+      "level": "must",
+      "statement": "Keep Root visible and readable when focused in every theme and viewport."
+    },
+    {
+      "id": "skip-link-one-main",
+      "level": "must",
+      "statement": "Do not create duplicate main landmarks around Target."
+    },
+    {
+      "id": "skip-link-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus skip-link.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hiding the link permanently, clipping its focus ring, or targeting a missing id.",
+      "correction": "Use the matching Root/Target pair and test from the browser chrome."
+    }
+  ],
+  "validation": [
+    "Tab to Root, activate it, and confirm Target receives visible focus and scrolls into view.",
+    "Check themes, zoom, sticky headers, one main landmark, and CSS delivery."
+  ],
+  "related": [
+    "app-bar",
+    "sidebar",
+    "link"
+  ]
+}

package/dist/agents/skip-link.md

@@ -0,0 +1,38 @@
+# SkipLink agent guide
+
+## Purpose
+
+Provide a visibly focused skip-navigation control and matching main-content target using Atom focus behavior.
+
+## Use when
+
+- A page repeats header or navigation content before main content.
+
+## Choose something else when
+
+- No repeated content precedes the primary content. Use normal document focus order.
+
+## Required composition
+
+- Place Root as the first useful focus target and one matching Target at main content; let Target own the main landmark unless custom-rendered.
+
+## Rules
+
+- **MUST:** Keep Root visible and readable when focused in every theme and viewport.
+- **MUST:** Do not create duplicate main landmarks around Target.
+- **MUST:** Load styles.css or core.css plus skip-link.css.
+
+## Common mistakes
+
+- **Avoid:** Hiding the link permanently, clipping its focus ring, or targeting a missing id. **Instead:** Use the matching Root/Target pair and test from the browser chrome.
+
+## Validation checklist
+
+- Tab to Root, activate it, and confirm Target receives visible focus and scrolls into view.
+- Check themes, zoom, sticky headers, one main landmark, and CSS delivery.
+
+## Related guidance
+
+- `app-bar`
+- `sidebar`
+- `link`

package/dist/agents/stack.json

@@ -0,0 +1,48 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "stack",
+  "name": "Stack",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Arrange children in one tokenized row or column with logical spacing, alignment, wrapping, and responsive-friendly public props.",
+  "useWhen": [
+    "Content needs one-dimensional vertical or horizontal layout."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Both rows and columns need explicit track control.",
+      "useInstead": "Grid"
+    }
+  ],
+  "composition": [
+    "Choose VStack for vertical flow or HStack for horizontal flow; set gap and alignment from the content relationship."
+  ],
+  "rules": [
+    {
+      "id": "stack-one-dimension",
+      "level": "must",
+      "statement": "Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear."
+    },
+    {
+      "id": "stack-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus stack.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding repeated custom flex utilities for ordinary rows and columns.",
+      "correction": "Use Stack so spacing and logical-direction behavior stay on the Brick contract."
+    }
+  ],
+  "validation": [
+    "Check source and visual order at narrow widths and zoom.",
+    "Check gap, wrapping, alignment, and RTL behavior."
+  ],
+  "related": [
+    "grid",
+    "surface",
+    "card"
+  ]
+}

package/dist/agents/stack.md

@@ -0,0 +1,37 @@
+# Stack agent guide
+
+## Purpose
+
+Arrange children in one tokenized row or column with logical spacing, alignment, wrapping, and responsive-friendly public props.
+
+## Use when
+
+- Content needs one-dimensional vertical or horizontal layout.
+
+## Choose something else when
+
+- Both rows and columns need explicit track control. Use Grid.
+
+## Required composition
+
+- Choose VStack for vertical flow or HStack for horizontal flow; set gap and alignment from the content relationship.
+
+## Rules
+
+- **MUST:** Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear.
+- **MUST:** Load styles.css or core.css plus stack.css.
+
+## Common mistakes
+
+- **Avoid:** Adding repeated custom flex utilities for ordinary rows and columns. **Instead:** Use Stack so spacing and logical-direction behavior stay on the Brick contract.
+
+## Validation checklist
+
+- Check source and visual order at narrow widths and zoom.
+- Check gap, wrapping, alignment, and RTL behavior.
+
+## Related guidance
+
+- `grid`
+- `surface`
+- `card`

package/dist/agents/surface.json

@@ -0,0 +1,48 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "surface",
+  "name": "Surface",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Apply semantic background layers, boundaries, elevation, radius, and inset without implying a specific content object.",
+  "useWhen": [
+    "A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region represents one bounded subject with card anatomy.",
+      "useInstead": "Card"
+    }
+  ],
+  "composition": [
+    "Choose Surface level and boundary by hierarchy, then compose public layout and content components inside."
+  ],
+  "rules": [
+    {
+      "id": "surface-semantic-level",
+      "level": "should",
+      "statement": "Choose surface level by information hierarchy, not decoration alone."
+    },
+    {
+      "id": "surface-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus surface.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using arbitrary background colors to recreate a surface.",
+      "correction": "Use Surface and theme its semantic tokens."
+    }
+  ],
+  "validation": [
+    "Check foreground contrast against the selected surface in every appearance.",
+    "Confirm nested surfaces communicate hierarchy without excessive borders or elevation."
+  ],
+  "related": [
+    "card",
+    "stack",
+    "grid"
+  ]
+}