@flowstack-ui/brick 0.1.3 → 0.1.5

package/dist/agents/container.md

@@ -0,0 +1,39 @@
+# Container agent guide
+
+## Purpose
+
+Own consistent centered content width, logical page gutters, and size variants for sections and application shells.
+
+## Use when
+
+- Page or section content needs a shared maximum inline size and responsive logical gutters.
+
+## Choose something else when
+
+- The region needs a visual boundary or only a local one-axis relationship. Use Surface/Card or Stack.
+
+## Required composition
+
+- Place section content inside Container, then use Stack or Grid for internal relationships; let full-bleed backgrounds live outside it.
+
+## Rules
+
+- **MUST:** Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections.
+- **MUST:** Do not use Container as a visual card or background owner.
+- **MUST:** Load styles.css or core.css plus container.css.
+
+## Common mistakes
+
+- **Avoid:** Applying a separate max-width class to every page section or nesting Containers without a width reason. **Instead:** Use one deliberate Container boundary per aligned content region.
+
+## Validation checklist
+
+- Check gutters and max width at all adopted breakpoints, zoom levels, and RTL.
+- Confirm full-bleed and contained regions align intentionally and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `surface`
+- `card`

package/dist/agents/divider.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "divider",
+  "name": "Divider",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render a finished decorative or semantic content boundary with horizontal or vertical visual recipes.",
+  "useWhen": [
+    "Adjacent content groups need a visible boundary and Atom Divider semantics."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Spacing alone expresses the relationship or the boundary is interactive.",
+      "useInstead": "Stack gap or a dedicated splitter"
+    }
+  ],
+  "composition": [
+    "Use Divider.Root inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning."
+  ],
+  "rules": [
+    {
+      "id": "divider-meaning",
+      "level": "must",
+      "statement": "Choose semantic versus decorative behavior independently from color, thickness, and orientation."
+    },
+    {
+      "id": "divider-group-owner",
+      "level": "must",
+      "statement": "Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls."
+    },
+    {
+      "id": "divider-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus divider.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy.",
+      "correction": "Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner."
+    }
+  ],
+  "validation": [
+    "Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.",
+    "Confirm it is not focusable and CSS is loaded."
+  ],
+  "related": [
+    "stack",
+    "toolbar",
+    "surface",
+    "nav-list"
+  ]
+}

package/dist/agents/divider.md

@@ -0,0 +1,39 @@
+# Divider agent guide
+
+## Purpose
+
+Render a finished decorative or semantic content boundary with horizontal or vertical visual recipes.
+
+## Use when
+
+- Adjacent content groups need a visible boundary and Atom Divider semantics.
+
+## Choose something else when
+
+- Spacing alone expresses the relationship or the boundary is interactive. Use Stack gap or a dedicated splitter.
+
+## Required composition
+
+- Use Divider.Root inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning.
+
+## Rules
+
+- **MUST:** Choose semantic versus decorative behavior independently from color, thickness, and orientation.
+- **MUST:** Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls.
+- **MUST:** Load styles.css or core.css plus divider.css.
+
+## Common mistakes
+
+- **Avoid:** Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy. **Instead:** Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner.
+
+## Validation checklist
+
+- Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.
+- Confirm it is not focusable and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `toolbar`
+- `surface`
+- `nav-list`

package/dist/agents/drawer.json

@@ -0,0 +1,76 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "drawer",
+  "name": "Drawer",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished modal side sheet while Atom owns focus, dismissal, portal, scroll-lock, and labeling behavior.",
+  "useWhen": [
+    "A temporary modal task or navigation panel should enter from a screen edge."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The side region is persistent layout or the overlay has no edge meaning.",
+      "useInstead": "Sidebar or Dialog"
+    }
+  ],
+  "composition": [
+    "Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body."
+  ],
+  "rules": [
+    {
+      "id": "drawer-anatomy",
+      "level": "must",
+      "statement": "Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior."
+    },
+    {
+      "id": "drawer-responsive",
+      "level": "must",
+      "statement": "Choose size and placement from content needs: use xl when content may need the viewport but should shrink when short, and full only when the surface must always fill it."
+    },
+    {
+      "id": "drawer-content-growth",
+      "level": "must",
+      "statement": "Let top and bottom Drawers grow naturally to their selected size cap; keep long overflow in Drawer.Body instead of forcing a fixed application height."
+    },
+    {
+      "id": "drawer-footer-layout",
+      "level": "must",
+      "statement": "Use Footer justify for simple action distribution, a Brick layout component inside Footer for complex grouping, and Button fullWidth only when the action itself should fill the row."
+    },
+    {
+      "id": "drawer-rsc-import",
+      "level": "must",
+      "statement": "In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module."
+    },
+    {
+      "id": "drawer-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus drawer.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy.",
+      "correction": "Use Drawer anatomy and compose the menu content with Brick navigation and layout components."
+    },
+    {
+      "mistake": "Adding use client to an entire Next page only to dereference the legacy Drawer runtime object.",
+      "correction": "Use the RSC-safe module-namespace subpath so only Drawer remains client-owned."
+    }
+  ],
+  "validation": [
+    "Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.",
+    "Confirm CSS and every composed child component stylesheet are loaded.",
+    "In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client."
+  ],
+  "related": [
+    "sidebar",
+    "dialog",
+    "nav-list",
+    "stack",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/drawer.md

@@ -0,0 +1,46 @@
+# Drawer agent guide
+
+## Purpose
+
+Present a finished modal side sheet while Atom owns focus, dismissal, portal, scroll-lock, and labeling behavior.
+
+## Use when
+
+- A temporary modal task or navigation panel should enter from a screen edge.
+
+## Choose something else when
+
+- The side region is persistent layout or the overlay has no edge meaning. Use Sidebar or Dialog.
+
+## Required composition
+
+- Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body.
+
+## Rules
+
+- **MUST:** Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior.
+- **MUST:** Choose size and placement from content needs: use xl when content may need the viewport but should shrink when short, and full only when the surface must always fill it.
+- **MUST:** Let top and bottom Drawers grow naturally to their selected size cap; keep long overflow in Drawer.Body instead of forcing a fixed application height.
+- **MUST:** Use Footer justify for simple action distribution, a Brick layout component inside Footer for complex grouping, and Button fullWidth only when the action itself should fill the row.
+- **MUST:** In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module.
+- **MUST:** Load styles.css or core.css plus drawer.css.
+
+## Common mistakes
+
+- **Avoid:** Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy. **Instead:** Use Drawer anatomy and compose the menu content with Brick navigation and layout components.
+- **Avoid:** Adding use client to an entire Next page only to dereference the legacy Drawer runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only Drawer remains client-owned.
+
+## Validation checklist
+
+- Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.
+- Confirm CSS and every composed child component stylesheet are loaded.
+- In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client.
+
+## Related guidance
+
+- `sidebar`
+- `dialog`
+- `nav-list`
+- `stack`
+- `show`
+- `hide`

package/dist/agents/field.json

@@ -0,0 +1,57 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "field",
+  "name": "Field",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Visually arrange one control with its label, description, error, and inherited Atom field relationships.",
+  "useWhen": [
+    "One finished control needs a visible label and may need help or error text."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Several related controls share one group label.",
+      "useInstead": "Fieldset, with Field inside when individual controls also need labels"
+    }
+  ],
+  "composition": [
+    "Compose Field.Root -> Field.Label -> one control -> optional Field.Description -> optional Field.Error."
+  ],
+  "rules": [
+    {
+      "id": "field-one-control",
+      "level": "must",
+      "statement": "Associate one Field with one control."
+    },
+    {
+      "id": "field-marker",
+      "level": "must",
+      "statement": "Field.Label already renders the default required marker; never add a second asterisk or RequiredIndicator unless the default is disabled."
+    },
+    {
+      "id": "field-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus field.css and the owned control stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding a manual required asterisk beside a required Field.Label.",
+      "correction": "Set required on Field.Root and use the built-in Label marker, or explicitly replace it once."
+    }
+  ],
+  "validation": [
+    "Confirm label, description, and error relationships.",
+    "Confirm exactly one required marker.",
+    "Check vertical and horizontal layouts at narrow widths."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/field",
+    "form",
+    "fieldset",
+    "input",
+    "textarea",
+    "checkbox"
+  ]
+}

package/dist/agents/field.md

@@ -0,0 +1,42 @@
+# Field agent guide
+
+## Purpose
+
+Visually arrange one control with its label, description, error, and inherited Atom field relationships.
+
+## Use when
+
+- One finished control needs a visible label and may need help or error text.
+
+## Choose something else when
+
+- Several related controls share one group label. Use Fieldset, with Field inside when individual controls also need labels.
+
+## Required composition
+
+- Compose Field.Root -> Field.Label -> one control -> optional Field.Description -> optional Field.Error.
+
+## Rules
+
+- **MUST:** Associate one Field with one control.
+- **MUST:** Field.Label already renders the default required marker; never add a second asterisk or RequiredIndicator unless the default is disabled.
+- **MUST:** Load styles.css or core.css plus field.css and the owned control stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Adding a manual required asterisk beside a required Field.Label. **Instead:** Set required on Field.Root and use the built-in Label marker, or explicitly replace it once.
+
+## Validation checklist
+
+- Confirm label, description, and error relationships.
+- Confirm exactly one required marker.
+- Check vertical and horizontal layouts at narrow widths.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/field`
+- `form`
+- `fieldset`
+- `input`
+- `textarea`
+- `checkbox`

package/dist/agents/fieldset.json

@@ -0,0 +1,49 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "fieldset",
+  "name": "Fieldset",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render a finished native group for related controls with a legend, group messaging, and inherited Atom state.",
+  "useWhen": [
+    "Multiple related controls answer one group question."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only one control needs a label.",
+      "useInstead": "Field"
+    }
+  ],
+  "composition": [
+    "Compose Fieldset.Root -> Fieldset.Legend -> optional description/error -> Fields or grouped choices."
+  ],
+  "rules": [
+    {
+      "id": "fieldset-legend",
+      "level": "must",
+      "statement": "Give the related group a meaningful legend."
+    },
+    {
+      "id": "fieldset-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus fieldset.css and child component styles."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using visual heading and div wrappers for a related choice group.",
+      "correction": "Use Fieldset so the group label and state remain semantic."
+    }
+  ],
+  "validation": [
+    "Inspect fieldset and legend semantics.",
+    "Check group messaging, state propagation, spacing, and responsive layout."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/fieldset",
+    "form",
+    "field",
+    "checkbox"
+  ]
+}

package/dist/agents/fieldset.md

@@ -0,0 +1,38 @@
+# Fieldset agent guide
+
+## Purpose
+
+Render a finished native group for related controls with a legend, group messaging, and inherited Atom state.
+
+## Use when
+
+- Multiple related controls answer one group question.
+
+## Choose something else when
+
+- Only one control needs a label. Use Field.
+
+## Required composition
+
+- Compose Fieldset.Root -> Fieldset.Legend -> optional description/error -> Fields or grouped choices.
+
+## Rules
+
+- **MUST:** Give the related group a meaningful legend.
+- **MUST:** Load styles.css or core.css plus fieldset.css and child component styles.
+
+## Common mistakes
+
+- **Avoid:** Using visual heading and div wrappers for a related choice group. **Instead:** Use Fieldset so the group label and state remain semantic.
+
+## Validation checklist
+
+- Inspect fieldset and legend semantics.
+- Check group messaging, state propagation, spacing, and responsive layout.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/fieldset`
+- `form`
+- `field`
+- `checkbox`

package/dist/agents/form.json

@@ -0,0 +1,49 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "form",
+  "name": "Form",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished native submission boundary and consistent form rhythm while Atom owns submission and validation behavior.",
+  "useWhen": [
+    "Related controls submit user input as one operation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Controls are unrelated immediate settings or actions.",
+      "useInstead": "Individual Field and Button compositions"
+    }
+  ],
+  "composition": [
+    "Compose Form -> Fieldset for related groups -> Field for each control -> a named submit Button."
+  ],
+  "rules": [
+    {
+      "id": "form-native",
+      "level": "must",
+      "statement": "Keep native submission available and give submitted controls names."
+    },
+    {
+      "id": "form-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus form.css and every rendered child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Treating Form as a complete login or contact workflow.",
+      "correction": "Keep business workflow in the application or a future Block; Form owns the generic visual boundary."
+    }
+  ],
+  "validation": [
+    "Submit with keyboard and pointer.",
+    "Inspect submitted values, invalid relationships, spacing, and narrow-layout behavior."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/form",
+    "field",
+    "fieldset",
+    "button"
+  ]
+}

package/dist/agents/form.md

@@ -0,0 +1,38 @@
+# Form agent guide
+
+## Purpose
+
+Provide a finished native submission boundary and consistent form rhythm while Atom owns submission and validation behavior.
+
+## Use when
+
+- Related controls submit user input as one operation.
+
+## Choose something else when
+
+- Controls are unrelated immediate settings or actions. Use Individual Field and Button compositions.
+
+## Required composition
+
+- Compose Form -> Fieldset for related groups -> Field for each control -> a named submit Button.
+
+## Rules
+
+- **MUST:** Keep native submission available and give submitted controls names.
+- **MUST:** Load styles.css or core.css plus form.css and every rendered child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Treating Form as a complete login or contact workflow. **Instead:** Keep business workflow in the application or a future Block; Form owns the generic visual boundary.
+
+## Validation checklist
+
+- Submit with keyboard and pointer.
+- Inspect submitted values, invalid relationships, spacing, and narrow-layout behavior.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/form`
+- `field`
+- `fieldset`
+- `button`

package/dist/agents/grid.json

@@ -0,0 +1,57 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "grid",
+  "name": "Grid",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Arrange content on tokenized two-dimensional tracks with public column, row, gap, and item-placement controls.",
+  "useWhen": [
+    "Content needs coordinated rows and columns or responsive card tracks."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The layout has one primary row or column.",
+      "useInstead": "Stack"
+    }
+  ],
+  "composition": [
+    "Choose Grid tracks from the minimum readable child size; use Grid.Item placement only when source order remains meaningful."
+  ],
+  "rules": [
+    {
+      "id": "grid-source-order",
+      "level": "must",
+      "statement": "Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence."
+    },
+    {
+      "id": "grid-item-as-child",
+      "level": "must",
+      "statement": "Use Grid.Item asChild when an existing link, Surface, or component should itself receive placement; provide exactly one element and preserve its native semantics."
+    },
+    {
+      "id": "grid-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus grid.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Keeping too many columns until cards become unreadably narrow.",
+      "correction": "Reduce columns at the content's real minimum width, not at a device-name breakpoint."
+    },
+    {
+      "mistake": "Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item.",
+      "correction": "Compose that one element with Grid.Item asChild."
+    }
+  ],
+  "validation": [
+    "Test intrinsic sizing, overflow, zoom, narrow widths, source order, and RTL.",
+    "Confirm each child remains readable before and after track changes."
+  ],
+  "related": [
+    "stack",
+    "card",
+    "surface"
+  ]
+}

package/dist/agents/grid.md

@@ -0,0 +1,39 @@
+# Grid agent guide
+
+## Purpose
+
+Arrange content on tokenized two-dimensional tracks with public column, row, gap, and item-placement controls.
+
+## Use when
+
+- Content needs coordinated rows and columns or responsive card tracks.
+
+## Choose something else when
+
+- The layout has one primary row or column. Use Stack.
+
+## Required composition
+
+- Choose Grid tracks from the minimum readable child size; use Grid.Item placement only when source order remains meaningful.
+
+## Rules
+
+- **MUST:** Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence.
+- **MUST:** Use Grid.Item asChild when an existing link, Surface, or component should itself receive placement; provide exactly one element and preserve its native semantics.
+- **MUST:** Load styles.css or core.css plus grid.css.
+
+## Common mistakes
+
+- **Avoid:** Keeping too many columns until cards become unreadably narrow. **Instead:** Reduce columns at the content's real minimum width, not at a device-name breakpoint.
+- **Avoid:** Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item. **Instead:** Compose that one element with Grid.Item asChild.
+
+## Validation checklist
+
+- Test intrinsic sizing, overflow, zoom, narrow widths, source order, and RTL.
+- Confirm each child remains readable before and after track changes.
+
+## Related guidance
+
+- `stack`
+- `card`
+- `surface`