@flowstack-ui/brick 0.1.3 → 0.1.5

package/dist/agents/layer-selection.json

@@ -0,0 +1,107 @@
+{
+  "schema": "flowstack.agent-guide.v1",
+  "id": "layer-selection",
+  "name": "Brick layer selection",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "guide",
+  "purpose": "Choose the correct FLOWSTACK layer and require Brick-first composition when building a finished interface with Brick.",
+  "decisionOrder": [
+    "Describe the interface job and semantic relationship before choosing markup or appearance.",
+    "Search Brick's package guides and component manifest for a component that owns the job.",
+    "Use Brick public components for finished interface structure, controls, navigation, content, media, responsive visibility, and visual surfaces.",
+    "Let Brick consume Atom; do not import Atom directly in an ordinary Brick application.",
+    "Keep purposeful sections in Blocks, page arrangements in Blueprints, theme values in a Theme, and business behavior in the application."
+  ],
+  "selection": [
+    {
+      "intent": "text with Brick typography",
+      "use": "Text",
+      "note": "Choose the semantic rendered element through its public API."
+    },
+    {
+      "intent": "one-dimensional alignment",
+      "use": "Stack, HStack, or VStack",
+      "note": "Use Grid for two-dimensional track relationships."
+    },
+    {
+      "intent": "bounded page width",
+      "use": "Container",
+      "note": "Use Surface or Card when the region also needs a visual boundary."
+    },
+    {
+      "intent": "top application or page bar",
+      "use": "AppBar",
+      "note": "Compose navigation and action components inside its sections."
+    },
+    {
+      "intent": "responsive presence",
+      "use": "Show or Hide",
+      "note": "Use CSS media visibility rather than rendering two JavaScript-controlled trees."
+    },
+    {
+      "intent": "image with resilient loading",
+      "use": "Image",
+      "note": "Use an adapter only when a framework image optimizer provides a measured capability Brick lacks."
+    },
+    {
+      "intent": "navigation destination",
+      "use": "Link or Button with href",
+      "note": "Use Link for ordinary navigation and Button only for an emphasized destination."
+    }
+  ],
+  "rules": [
+    {
+      "id": "brick-first",
+      "level": "must",
+      "statement": "Use an existing Brick component when it owns the interface job instead of recreating it with native elements and application CSS."
+    },
+    {
+      "id": "brick-no-direct-atom",
+      "level": "must",
+      "statement": "Do not import @flowstack-ui/atom directly in an application that has selected Brick; report a Brick gap if the finished component is missing."
+    },
+    {
+      "id": "brick-css-contract",
+      "level": "must",
+      "statement": "Load styles.css once, or core.css once plus every rendered component's modular stylesheet; never mix the two delivery modes."
+    },
+    {
+      "id": "brick-semantic-choice",
+      "level": "must",
+      "statement": "Choose components by semantic and interaction intent rather than by visual resemblance."
+    },
+    {
+      "id": "brick-customization-contract",
+      "level": "must",
+      "statement": "After selecting a Brick owner, follow interface-composition's ordered prop, semantic-token, component-token, public-part, and stable-hook customization contract."
+    },
+    {
+      "id": "brick-report-fallback",
+      "level": "should",
+      "statement": "Record intentional native or framework fallbacks with the searched Brick component and missing capability."
+    }
+  ],
+  "nativeFallback": {
+    "check": "Search the Brick manifest, package guide selection map, component docs, and public exports before writing native markup or replacement CSS.",
+    "use": "Use semantic native HTML only for document or application structure Brick does not own, or through a documented adapter when a framework supplies a required measured capability.",
+    "report": "Record the fallback as a Brick gap, adapter need, higher-layer composition, or intentional application-owned element before continuing."
+  },
+  "validation": [
+    "List every native layout, text, image, navigation, and interactive element and name why Brick does not own it; list every direct Brick stable-hook declaration and its completed customization gap report.",
+    "Confirm there are no direct @flowstack-ui/atom imports.",
+    "Confirm every rendered Brick component has its required modular CSS or the complete stylesheet is loaded once.",
+    "Classify each repeated composition as component, theme, Block, Blueprint, adapter, or application ownership."
+  ],
+  "related": [
+    "interface-composition",
+    "app-bar",
+    "container",
+    "stack",
+    "grid",
+    "text",
+    "image",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/layer-selection.md

@@ -0,0 +1,57 @@
+# Brick layer selection
+
+## Purpose
+
+Choose the correct FLOWSTACK layer and require Brick-first composition when building a finished interface with Brick.
+
+## Decision order
+
+1. Describe the interface job and semantic relationship before choosing markup or appearance.
+2. Search Brick's package guides and component manifest for a component that owns the job.
+3. Use Brick public components for finished interface structure, controls, navigation, content, media, responsive visibility, and visual surfaces.
+4. Let Brick consume Atom; do not import Atom directly in an ordinary Brick application.
+5. Keep purposeful sections in Blocks, page arrangements in Blueprints, theme values in a Theme, and business behavior in the application.
+
+## Selection map
+
+- **text with Brick typography:** use Text. Choose the semantic rendered element through its public API.
+- **one-dimensional alignment:** use Stack, HStack, or VStack. Use Grid for two-dimensional track relationships.
+- **bounded page width:** use Container. Use Surface or Card when the region also needs a visual boundary.
+- **top application or page bar:** use AppBar. Compose navigation and action components inside its sections.
+- **responsive presence:** use Show or Hide. Use CSS media visibility rather than rendering two JavaScript-controlled trees.
+- **image with resilient loading:** use Image. Use an adapter only when a framework image optimizer provides a measured capability Brick lacks.
+- **navigation destination:** use Link or Button with href. Use Link for ordinary navigation and Button only for an emphasized destination.
+
+## Rules
+
+- **MUST:** Use an existing Brick component when it owns the interface job instead of recreating it with native elements and application CSS.
+- **MUST:** Do not import @flowstack-ui/atom directly in an application that has selected Brick; report a Brick gap if the finished component is missing.
+- **MUST:** Load styles.css once, or core.css once plus every rendered component's modular stylesheet; never mix the two delivery modes.
+- **MUST:** Choose components by semantic and interaction intent rather than by visual resemblance.
+- **MUST:** After selecting a Brick owner, follow interface-composition's ordered prop, semantic-token, component-token, public-part, and stable-hook customization contract.
+- **SHOULD:** Record intentional native or framework fallbacks with the searched Brick component and missing capability.
+
+## Native fallback
+
+1. Search the Brick manifest, package guide selection map, component docs, and public exports before writing native markup or replacement CSS.
+2. Use semantic native HTML only for document or application structure Brick does not own, or through a documented adapter when a framework supplies a required measured capability.
+3. Record the fallback as a Brick gap, adapter need, higher-layer composition, or intentional application-owned element before continuing.
+
+## Validation checklist
+
+- List every native layout, text, image, navigation, and interactive element and name why Brick does not own it; list every direct Brick stable-hook declaration and its completed customization gap report.
+- Confirm there are no direct @flowstack-ui/atom imports.
+- Confirm every rendered Brick component has its required modular CSS or the complete stylesheet is loaded once.
+- Classify each repeated composition as component, theme, Block, Blueprint, adapter, or application ownership.
+
+## Related guidance
+
+- `interface-composition`
+- `app-bar`
+- `container`
+- `stack`
+- `grid`
+- `text`
+- `image`
+- `show`
+- `hide`

package/dist/agents/link.json

@@ -0,0 +1,47 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "link",
+  "name": "Link",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render finished native navigation as inline, standalone, or button-like content without changing its link semantics.",
+  "useWhen": [
+    "The user moves to a route, URL, document, download, email address, or telephone destination."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The interaction changes current state without navigating.",
+      "useInstead": "Button"
+    }
+  ],
+  "composition": [
+    "Provide a real href or compose a router-owned anchor, then choose a visual variant independently from navigation semantics."
+  ],
+  "rules": [
+    {
+      "id": "link-destination",
+      "level": "must",
+      "statement": "Preserve anchor semantics and a real destination even when the link looks like a button."
+    },
+    {
+      "id": "link-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus link.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Replacing a destination with Button because the design is prominent.",
+      "correction": "Use Link and select the appropriate Brick variant."
+    }
+  ],
+  "validation": [
+    "Inspect href and accessible name.",
+    "Test focus, Enter navigation, visited/external behavior when relevant, and contrast."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/link",
+    "button"
+  ]
+}

package/dist/agents/link.md

@@ -0,0 +1,36 @@
+# Link agent guide
+
+## Purpose
+
+Render finished native navigation as inline, standalone, or button-like content without changing its link semantics.
+
+## Use when
+
+- The user moves to a route, URL, document, download, email address, or telephone destination.
+
+## Choose something else when
+
+- The interaction changes current state without navigating. Use Button.
+
+## Required composition
+
+- Provide a real href or compose a router-owned anchor, then choose a visual variant independently from navigation semantics.
+
+## Rules
+
+- **MUST:** Preserve anchor semantics and a real destination even when the link looks like a button.
+- **MUST:** Load styles.css or core.css plus link.css.
+
+## Common mistakes
+
+- **Avoid:** Replacing a destination with Button because the design is prominent. **Instead:** Use Link and select the appropriate Brick variant.
+
+## Validation checklist
+
+- Inspect href and accessible name.
+- Test focus, Enter navigation, visited/external behavior when relevant, and contrast.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/link`
+- `button`

package/dist/agents/manifest.json

@@ -0,0 +1,207 @@
+{
+  "schema": "flowstack.agent-manifest.v1",
+  "package": "@flowstack-ui/brick",
+  "packageVersion": "0.1.5",
+  "components": [
+    {
+      "id": "app-bar",
+      "name": "AppBar",
+      "json": "./app-bar.json",
+      "markdown": "./app-bar.md"
+    },
+    {
+      "id": "bottom-navigation",
+      "name": "BottomNavigation",
+      "json": "./bottom-navigation.json",
+      "markdown": "./bottom-navigation.md"
+    },
+    {
+      "id": "breadcrumb",
+      "name": "Breadcrumb",
+      "json": "./breadcrumb.json",
+      "markdown": "./breadcrumb.md"
+    },
+    {
+      "id": "button",
+      "name": "Button",
+      "json": "./button.json",
+      "markdown": "./button.md"
+    },
+    {
+      "id": "card",
+      "name": "Card",
+      "json": "./card.json",
+      "markdown": "./card.md"
+    },
+    {
+      "id": "checkbox",
+      "name": "Checkbox",
+      "json": "./checkbox.json",
+      "markdown": "./checkbox.md"
+    },
+    {
+      "id": "container",
+      "name": "Container",
+      "json": "./container.json",
+      "markdown": "./container.md"
+    },
+    {
+      "id": "divider",
+      "name": "Divider",
+      "json": "./divider.json",
+      "markdown": "./divider.md"
+    },
+    {
+      "id": "drawer",
+      "name": "Drawer",
+      "json": "./drawer.json",
+      "markdown": "./drawer.md"
+    },
+    {
+      "id": "field",
+      "name": "Field",
+      "json": "./field.json",
+      "markdown": "./field.md"
+    },
+    {
+      "id": "fieldset",
+      "name": "Fieldset",
+      "json": "./fieldset.json",
+      "markdown": "./fieldset.md"
+    },
+    {
+      "id": "form",
+      "name": "Form",
+      "json": "./form.json",
+      "markdown": "./form.md"
+    },
+    {
+      "id": "grid",
+      "name": "Grid",
+      "json": "./grid.json",
+      "markdown": "./grid.md"
+    },
+    {
+      "id": "hide",
+      "name": "Hide",
+      "json": "./hide.json",
+      "markdown": "./hide.md"
+    },
+    {
+      "id": "icon-button",
+      "name": "IconButton",
+      "json": "./icon-button.json",
+      "markdown": "./icon-button.md"
+    },
+    {
+      "id": "image",
+      "name": "Image",
+      "json": "./image.json",
+      "markdown": "./image.md"
+    },
+    {
+      "id": "input",
+      "name": "Input",
+      "json": "./input.json",
+      "markdown": "./input.md"
+    },
+    {
+      "id": "link",
+      "name": "Link",
+      "json": "./link.json",
+      "markdown": "./link.md"
+    },
+    {
+      "id": "nav-list",
+      "name": "NavList",
+      "json": "./nav-list.json",
+      "markdown": "./nav-list.md"
+    },
+    {
+      "id": "navigation-menu",
+      "name": "NavigationMenu",
+      "json": "./navigation-menu.json",
+      "markdown": "./navigation-menu.md"
+    },
+    {
+      "id": "pagination",
+      "name": "Pagination",
+      "json": "./pagination.json",
+      "markdown": "./pagination.md"
+    },
+    {
+      "id": "scroll-area",
+      "name": "ScrollArea",
+      "json": "./scroll-area.json",
+      "markdown": "./scroll-area.md"
+    },
+    {
+      "id": "show",
+      "name": "Show",
+      "json": "./show.json",
+      "markdown": "./show.md"
+    },
+    {
+      "id": "sidebar",
+      "name": "Sidebar",
+      "json": "./sidebar.json",
+      "markdown": "./sidebar.md"
+    },
+    {
+      "id": "skip-link",
+      "name": "SkipLink",
+      "json": "./skip-link.json",
+      "markdown": "./skip-link.md"
+    },
+    {
+      "id": "stack",
+      "name": "Stack",
+      "json": "./stack.json",
+      "markdown": "./stack.md"
+    },
+    {
+      "id": "surface",
+      "name": "Surface",
+      "json": "./surface.json",
+      "markdown": "./surface.md"
+    },
+    {
+      "id": "tabs",
+      "name": "Tabs",
+      "json": "./tabs.json",
+      "markdown": "./tabs.md"
+    },
+    {
+      "id": "text",
+      "name": "Text",
+      "json": "./text.json",
+      "markdown": "./text.md"
+    },
+    {
+      "id": "textarea",
+      "name": "Textarea",
+      "json": "./textarea.json",
+      "markdown": "./textarea.md"
+    },
+    {
+      "id": "toolbar",
+      "name": "Toolbar",
+      "json": "./toolbar.json",
+      "markdown": "./toolbar.md"
+    }
+  ],
+  "guides": [
+    {
+      "id": "interface-composition",
+      "name": "Brick interface composition",
+      "json": "./interface-composition.json",
+      "markdown": "./interface-composition.md"
+    },
+    {
+      "id": "layer-selection",
+      "name": "Brick layer selection",
+      "json": "./layer-selection.json",
+      "markdown": "./layer-selection.md"
+    }
+  ]
+}

package/dist/agents/nav-list.json

@@ -0,0 +1,65 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "nav-list",
+  "name": "NavList",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style persistent route navigation with current state, optional section labels, and collapsible grouped content.",
+  "useWhen": [
+    "A sidebar, drawer, rail, or page region contains a persistent list of destinations, optionally grouped."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Navigation uses top-bar disclosure panels or local tab panels.",
+      "useInstead": "NavigationMenu or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary."
+  ],
+  "rules": [
+    {
+      "id": "nav-list-current",
+      "level": "must",
+      "statement": "Set current destination state from the route and keep route items as links."
+    },
+    {
+      "id": "nav-list-layout",
+      "level": "must",
+      "statement": "Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs."
+    },
+    {
+      "id": "nav-list-group-boundary",
+      "level": "must",
+      "statement": "Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner."
+    },
+    {
+      "id": "nav-list-shell-alignment",
+      "level": "must",
+      "statement": "Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms."
+    },
+    {
+      "id": "nav-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus nav-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS.",
+      "correction": "Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment."
+    }
+  ],
+  "validation": [
+    "Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.",
+    "Confirm links and section relationships remain semantic and CSS is loaded."
+  ],
+  "related": [
+    "sidebar",
+    "drawer",
+    "navigation-menu",
+    "link",
+    "divider"
+  ]
+}

package/dist/agents/nav-list.md

@@ -0,0 +1,42 @@
+# NavList agent guide
+
+## Purpose
+
+Style persistent route navigation with current state, optional section labels, and collapsible grouped content.
+
+## Use when
+
+- A sidebar, drawer, rail, or page region contains a persistent list of destinations, optionally grouped.
+
+## Choose something else when
+
+- Navigation uses top-bar disclosure panels or local tab panels. Use NavigationMenu or Tabs.
+
+## Required composition
+
+- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary.
+
+## Rules
+
+- **MUST:** Set current destination state from the route and keep route items as links.
+- **MUST:** Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs.
+- **MUST:** Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner.
+- **MUST:** Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms.
+- **MUST:** Load styles.css or core.css plus nav-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS. **Instead:** Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment.
+
+## Validation checklist
+
+- Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.
+- Confirm links and section relationships remain semantic and CSS is loaded.
+
+## Related guidance
+
+- `sidebar`
+- `drawer`
+- `navigation-menu`
+- `link`
+- `divider`

package/dist/agents/navigation-menu.json

@@ -0,0 +1,90 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "navigation-menu",
+  "name": "NavigationMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present polished disclosure navigation while Atom owns trigger geometry, viewport positioning, focus, keyboard, pointer, and dismissal behavior.",
+  "useWhen": [
+    "A top-level site or product navigation combines direct links with disclosure panels of related destinations."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is an action menu, persistent route rail, mobile drawer, or tab switcher.",
+      "useInstead": "DropdownMenu, NavList, Drawer, or Tabs"
+    }
+  ],
+  "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": [
+    {
+      "id": "navigation-menu-positioning",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "navigation-menu-horizontal-position",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "navigation-menu-public-api",
+      "level": "must",
+      "statement": "Do not invent overlay props such as side, align, sideOffset, or alignOffset; NavigationMenu does not expose the floating-overlay positioning API."
+    },
+    {
+      "id": "navigation-menu-destinations",
+      "level": "must",
+      "statement": "Keep contents focused on navigation destinations rather than commands or unrelated marketing panels."
+    },
+    {
+      "id": "navigation-menu-panel-link",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "navigation-menu-panel-focus",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "navigation-menu-rsc-import",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "navigation-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus navigation-menu.css and every child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "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.",
+      "correction": "Keep Viewport and Indicator under Root, let NavigationMenu own geometry and open state, then customize documented recipes, tokens, and public parts."
+    },
+    {
+      "mistake": "Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object.",
+      "correction": "Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned."
+    },
+    {
+      "mistake": "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.",
+      "correction": "Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry."
+    }
+  ],
+  "validation": [
+    "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": [
+    "app-bar",
+    "nav-list",
+    "drawer",
+    "dropdown-menu",
+    "link",
+    "interface-composition"
+  ]
+}