@flowstack-ui/brick 0.1.2 → 0.1.4

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"
+  ]
+}

package/dist/agents/surface.md

@@ -0,0 +1,37 @@
+# Surface agent guide
+
+## Purpose
+
+Apply semantic background layers, boundaries, elevation, radius, and inset without implying a specific content object.
+
+## Use when
+
+- A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy.
+
+## Choose something else when
+
+- The region represents one bounded subject with card anatomy. Use Card.
+
+## Required composition
+
+- Choose Surface level and boundary by hierarchy, then compose public layout and content components inside.
+
+## Rules
+
+- **SHOULD:** Choose surface level by information hierarchy, not decoration alone.
+- **MUST:** Load styles.css or core.css plus surface.css.
+
+## Common mistakes
+
+- **Avoid:** Using arbitrary background colors to recreate a surface. **Instead:** Use Surface and theme its semantic tokens.
+
+## Validation checklist
+
+- Check foreground contrast against the selected surface in every appearance.
+- Confirm nested surfaces communicate hierarchy without excessive borders or elevation.
+
+## Related guidance
+
+- `card`
+- `stack`
+- `grid`

package/dist/agents/tabs.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "tabs",
+  "name": "Tabs",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style related in-page panel switching while Atom owns tab semantics, selection, roving focus, and indicator geometry.",
+  "useWhen": [
+    "A small set of related panels shares one page and one panel is normally active."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Choices navigate to routes or multiple sections should remain open.",
+      "useInstead": "Link/NavList or Accordion"
+    }
+  ],
+  "composition": [
+    "Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components."
+  ],
+  "rules": [
+    {
+      "id": "tabs-related-panels",
+      "level": "must",
+      "statement": "Use Tabs only for related in-page panels, not to imitate a site navigation underline."
+    },
+    {
+      "id": "tabs-overflow",
+      "level": "must",
+      "statement": "Define a deliberate narrow-width overflow or wrapping policy without clipping triggers or indicator focus."
+    },
+    {
+      "id": "tabs-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus tabs.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Tabs for routes, clipping focus/indicator edges, or mismatching Trigger and Content values.",
+      "correction": "Use navigation links for routes and keep complete paired tab anatomy."
+    }
+  ],
+  "validation": [
+    "Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, focus rings, themes, zoom, and RTL.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "accordion",
+    "navigation-menu",
+    "bottom-navigation",
+    "scroll-area"
+  ]
+}

package/dist/agents/tabs.md

@@ -0,0 +1,39 @@
+# Tabs agent guide
+
+## Purpose
+
+Style related in-page panel switching while Atom owns tab semantics, selection, roving focus, and indicator geometry.
+
+## Use when
+
+- A small set of related panels shares one page and one panel is normally active.
+
+## Choose something else when
+
+- Choices navigate to routes or multiple sections should remain open. Use Link/NavList or Accordion.
+
+## Required composition
+
+- Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components.
+
+## Rules
+
+- **MUST:** Use Tabs only for related in-page panels, not to imitate a site navigation underline.
+- **MUST:** Define a deliberate narrow-width overflow or wrapping policy without clipping triggers or indicator focus.
+- **MUST:** Load styles.css or core.css plus tabs.css.
+
+## Common mistakes
+
+- **Avoid:** Using Tabs for routes, clipping focus/indicator edges, or mismatching Trigger and Content values. **Instead:** Use navigation links for routes and keep complete paired tab anatomy.
+
+## Validation checklist
+
+- Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, focus rings, themes, zoom, and RTL.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `accordion`
+- `navigation-menu`
+- `bottom-navigation`
+- `scroll-area`