@flowstack-ui/brick 0.1.2 → 0.1.4

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.4",
+  "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,54 @@
+{
+  "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."
+  ],
+  "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-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus nav-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using buttons for routes or adding a collapsible trigger that controls no content.",
+      "correction": "Use Link for destinations and SectionLabel alone for static groups."
+    }
+  ],
+  "validation": [
+    "Check current, hover, focus, collapsed, expanded, 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"
+  ]
+}

package/dist/agents/nav-list.md

@@ -0,0 +1,39 @@
+# 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.
+
+## 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:** Load styles.css or core.css plus nav-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using buttons for routes or adding a collapsible trigger that controls no content. **Instead:** Use Link for destinations and SectionLabel alone for static groups.
+
+## Validation checklist
+
+- Check current, hover, focus, collapsed, expanded, 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`

package/dist/agents/navigation-menu.json

@@ -0,0 +1,76 @@
+{
+  "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-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."
+    }
+  ],
+  "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, 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"
+  ]
+}

package/dist/agents/navigation-menu.md

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

package/dist/agents/pagination.json

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

package/dist/agents/pagination.md

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