@flowstack-ui/brick 0.1.2 → 0.1.4

package/dist/agents/divider.json

@@ -0,0 +1,48 @@
+{
+  "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 owning Stack, Toolbar, menu, or surface 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-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.",
+      "correction": "Use Divider when there is a boundary and Stack gap when there is only spacing."
+    }
+  ],
+  "validation": [
+    "Check orientation, contrast, forced colors, zoom, and semantics.",
+    "Confirm it is not focusable and CSS is loaded."
+  ],
+  "related": [
+    "stack",
+    "toolbar",
+    "surface"
+  ]
+}

package/dist/agents/divider.md

@@ -0,0 +1,37 @@
+# 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 owning Stack, Toolbar, menu, or surface and choose decorative=false only when the separation has meaning.
+
+## Rules
+
+- **MUST:** Choose semantic versus decorative behavior independently from color, thickness, and orientation.
+- **MUST:** Load styles.css or core.css plus divider.css.
+
+## Common mistakes
+
+- **Avoid:** Using a bordered div or text glyph for every separator. **Instead:** Use Divider when there is a boundary and Stack gap when there is only spacing.
+
+## Validation checklist
+
+- Check orientation, contrast, forced colors, zoom, and semantics.
+- Confirm it is not focusable and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `toolbar`
+- `surface`

package/dist/agents/drawer.json

@@ -0,0 +1,56 @@
+{
+  "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, placement, and full-screen mobile presentation from content needs without duplicating mounted dialog trees."
+    },
+    {
+      "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."
+    }
+  ],
+  "validation": [
+    "Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, touch, reduced motion, narrow screens, and nested portals.",
+    "Confirm CSS and every composed child component stylesheet are loaded."
+  ],
+  "related": [
+    "sidebar",
+    "dialog",
+    "nav-list",
+    "stack",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/drawer.md

@@ -0,0 +1,41 @@
+# 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, placement, and full-screen mobile presentation from content needs without duplicating mounted dialog trees.
+- **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.
+
+## Validation checklist
+
+- Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, touch, reduced motion, narrow screens, and nested portals.
+- Confirm CSS and every composed child component stylesheet are loaded.
+
+## 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,48 @@
+{
+  "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-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."
+    }
+  ],
+  "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,37 @@
+# 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:** 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.
+
+## 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`

package/dist/agents/hide.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "hide",
+  "name": "Hide",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.",
+  "useWhen": [
+    "One composition should be absent at selected Brick breakpoints while remaining present elsewhere."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content should be visually hidden but remain available to assistive technology, or should not render for business reasons.",
+      "useInstead": "VisuallyHidden or application conditional rendering"
+    }
+  ],
+  "composition": [
+    "Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions."
+  ],
+  "rules": [
+    {
+      "id": "hide-css-breakpoint",
+      "level": "must",
+      "statement": "Use Hide instead of JavaScript matchMedia for first-paint responsive visibility."
+    },
+    {
+      "id": "hide-no-semantic-loss",
+      "level": "must",
+      "statement": "Do not hide the only accessible name, error, instruction, or required content at a breakpoint."
+    },
+    {
+      "id": "hide-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus hide.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs.",
+      "correction": "Load hide.css and verify alternate compositions have independent valid relationships."
+    }
+  ],
+  "validation": [
+    "Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "show",
+    "visually-hidden",
+    "app-bar",
+    "drawer"
+  ]
+}

package/dist/agents/hide.md

@@ -0,0 +1,39 @@
+# Hide agent guide
+
+## Purpose
+
+Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.
+
+## Use when
+
+- One composition should be absent at selected Brick breakpoints while remaining present elsewhere.
+
+## Choose something else when
+
+- Content should be visually hidden but remain available to assistive technology, or should not render for business reasons. Use VisuallyHidden or application conditional rendering.
+
+## Required composition
+
+- Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions.
+
+## Rules
+
+- **MUST:** Use Hide instead of JavaScript matchMedia for first-paint responsive visibility.
+- **MUST:** Do not hide the only accessible name, error, instruction, or required content at a breakpoint.
+- **MUST:** Load styles.css or core.css plus hide.css.
+
+## Common mistakes
+
+- **Avoid:** Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs. **Instead:** Load hide.css and verify alternate compositions have independent valid relationships.
+
+## Validation checklist
+
+- Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `show`
+- `visually-hidden`
+- `app-bar`
+- `drawer`