@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/brick/0.1.11/components/input.txt

@@ -0,0 +1,101 @@
+# Input
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: input
+
+# Input agent guide
+
+## Purpose
+
+Render finished native single-line text entry with Brick sizing, states, and Atom field integration.
+
+## Use when
+
+- The user enters a single-line text, email, search, URL, telephone, or supported native input value.
+
+## Choose something else when
+
+- The value needs multiple lines. Use Textarea.
+
+## Required composition
+
+- Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data. Use outline when the containing surface should remain visible and soft when Input should own a filled plane.
+
+## Rules
+
+- **MUST:** Use a persistent accessible label; placeholder is not a replacement.
+- **MUST:** Load styles.css or core.css plus input.css and field.css when composed with Field.
+
+## Common mistakes
+
+- **Avoid:** Using placeholder as the only visible label. **Instead:** Compose Input with Field.Label and use placeholder only as optional example text.
+
+## Validation checklist
+
+- Inspect label, name, type, autocomplete, and messaging relationships.
+- Test focus, entry, autofill, invalid/disabled states, zoom, and both appearances.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/input`
+- `field`
+- `textarea`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "input",
+  "name": "Input",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render finished native single-line text entry with Brick sizing, states, and Atom field integration.",
+  "useWhen": [
+    "The user enters a single-line text, email, search, URL, telephone, or supported native input value."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value needs multiple lines.",
+      "useInstead": "Textarea"
+    }
+  ],
+  "composition": [
+    "Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data. Use outline when the containing surface should remain visible and soft when Input should own a filled plane."
+  ],
+  "rules": [
+    {
+      "id": "input-label",
+      "level": "must",
+      "statement": "Use a persistent accessible label; placeholder is not a replacement."
+    },
+    {
+      "id": "input-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus input.css and field.css when composed with Field."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using placeholder as the only visible label.",
+      "correction": "Compose Input with Field.Label and use placeholder only as optional example text."
+    }
+  ],
+  "validation": [
+    "Inspect label, name, type, autocomplete, and messaging relationships.",
+    "Test focus, entry, autofill, invalid/disabled states, zoom, and both appearances."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "input",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "textarea"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/link-box.txt

@@ -0,0 +1,161 @@
+# Link Box
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: link-box
+
+# Link Box agent guide
+
+## Purpose
+
+Expand one real destination across a containing region while keeping secondary controls independent.
+
+## Use when
+
+- A card, result, article, or other bounded item has one primary destination and needs a larger pointer target.
+- The same item may contain a separate save, compare, menu, or other action.
+
+## Choose something else when
+
+- The complete region performs an operation instead of navigating. Use Button or Pressable.
+- Only the visible text should be clickable or pointer text selection is important. Use Link.
+
+## Required composition
+
+- Wrap the complete visual item in LinkBox.Root and put LinkBox.Link around concise destination text, usually the item title.
+- Wrap every independently interactive sibling in LinkBox.Action; never place buttons or additional links inside LinkBox.Link.
+- When an Action overlays media through ZStack, compose ZStack.Item asChild with LinkBox.Action and use ZStack.Root isolation="open" plus ZStack.Item layer="action"; use edgeSpacing when the control needs a theme-space inset.
+- Give Root the semantic host for the item, such as article or li, and keep the inner Card.Root as its default div to avoid duplicate semantic containers.
+
+## Rules
+
+- **MUST:** Provide exactly one primary LinkBox.Link with a real destination and concise accessible name.
+- **MUST:** Keep secondary controls outside the primary anchor and inside LinkBox.Action.
+- **MUST:** For an Action nested in a ZStack overlay, use ZStack's public isolation and named-layer API, then prove the independent action and expanded link both activate correctly in a real browser.
+- **MUST:** Do not add role, tabIndex, click handlers, or Pressable behavior to LinkBox.Root.
+- **MUST:** Load styles.css or core.css plus link-box.css; the modular entry includes Link styling.
+- **SHOULD:** Use Root variant plain for an unbounded editorial preview whose edge media and unpadded copy should not receive a hover boundary; focus-visible remains intact.
+
+## Common mistakes
+
+- **Avoid:** Wrapping the entire Card in Link and then adding favorite or menu buttons inside it. **Instead:** Use LinkBox.Root, keep one title LinkBox.Link, and layer each separate control through LinkBox.Action.
+- **Avoid:** Making Root focusable in addition to Link. **Instead:** Root is only a visual containing region; the real Link owns focus and navigation.
+- **Avoid:** Placing LinkBox.Action inside an isolated overlay layout without checking stacking contexts. **Instead:** Merge ZStack.Item onto LinkBox.Action with asChild, set ZStack.Root isolation="open", set the item layer="action", and verify pointer activation rather than recreating the relationship with inline styles.
+- **Avoid:** Using LinkBox for a card that only performs an operation. **Instead:** Use Button or Pressable so action semantics and keyboard behavior remain truthful.
+
+## Validation checklist
+
+- Inspect the final DOM for one primary a[href] and no nested interactive elements.
+- Click empty visual areas, then keyboard-focus and activate the named link with Enter.
+- Verify secondary controls activate independently with both pointer and keyboard input and do not navigate.
+- Check the whole-region hover and focus ring in light, dark, forced colors, narrow layouts, and zoom.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/link`
+- `link`
+- `card`
+- `button`
+- `icon-button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "link-box",
+  "name": "Link Box",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Expand one real destination across a containing region while keeping secondary controls independent.",
+  "useWhen": [
+    "A card, result, article, or other bounded item has one primary destination and needs a larger pointer target.",
+    "The same item may contain a separate save, compare, menu, or other action."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The complete region performs an operation instead of navigating.",
+      "useInstead": "Button or Pressable"
+    },
+    {
+      "condition": "Only the visible text should be clickable or pointer text selection is important.",
+      "useInstead": "Link"
+    }
+  ],
+  "composition": [
+    "Wrap the complete visual item in LinkBox.Root and put LinkBox.Link around concise destination text, usually the item title.",
+    "Wrap every independently interactive sibling in LinkBox.Action; never place buttons or additional links inside LinkBox.Link.",
+    "When an Action overlays media through ZStack, compose ZStack.Item asChild with LinkBox.Action and use ZStack.Root isolation=\"open\" plus ZStack.Item layer=\"action\"; use edgeSpacing when the control needs a theme-space inset.",
+    "Give Root the semantic host for the item, such as article or li, and keep the inner Card.Root as its default div to avoid duplicate semantic containers."
+  ],
+  "rules": [
+    {
+      "id": "link-box-one-destination",
+      "level": "must",
+      "statement": "Provide exactly one primary LinkBox.Link with a real destination and concise accessible name."
+    },
+    {
+      "id": "link-box-actions",
+      "level": "must",
+      "statement": "Keep secondary controls outside the primary anchor and inside LinkBox.Action."
+    },
+    {
+      "id": "link-box-overlay-actions",
+      "level": "must",
+      "statement": "For an Action nested in a ZStack overlay, use ZStack's public isolation and named-layer API, then prove the independent action and expanded link both activate correctly in a real browser."
+    },
+    {
+      "id": "link-box-no-press",
+      "level": "must",
+      "statement": "Do not add role, tabIndex, click handlers, or Pressable behavior to LinkBox.Root."
+    },
+    {
+      "id": "link-box-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus link-box.css; the modular entry includes Link styling."
+    },
+    {
+      "id": "link-box-plain-editorial",
+      "level": "should",
+      "statement": "Use Root variant plain for an unbounded editorial preview whose edge media and unpadded copy should not receive a hover boundary; focus-visible remains intact."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Wrapping the entire Card in Link and then adding favorite or menu buttons inside it.",
+      "correction": "Use LinkBox.Root, keep one title LinkBox.Link, and layer each separate control through LinkBox.Action."
+    },
+    {
+      "mistake": "Making Root focusable in addition to Link.",
+      "correction": "Root is only a visual containing region; the real Link owns focus and navigation."
+    },
+    {
+      "mistake": "Placing LinkBox.Action inside an isolated overlay layout without checking stacking contexts.",
+      "correction": "Merge ZStack.Item onto LinkBox.Action with asChild, set ZStack.Root isolation=\"open\", set the item layer=\"action\", and verify pointer activation rather than recreating the relationship with inline styles."
+    },
+    {
+      "mistake": "Using LinkBox for a card that only performs an operation.",
+      "correction": "Use Button or Pressable so action semantics and keyboard behavior remain truthful."
+    }
+  ],
+  "validation": [
+    "Inspect the final DOM for one primary a[href] and no nested interactive elements.",
+    "Click empty visual areas, then keyboard-focus and activate the named link with Enter.",
+    "Verify secondary controls activate independently with both pointer and keyboard input and do not navigate.",
+    "Check the whole-region hover and focus ring in light, dark, forced colors, narrow layouts, and zoom."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "link",
+      "versionPolicy": "installed-exact"
+    },
+    "link",
+    "card",
+    "button",
+    "icon-button"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/link.txt

@@ -0,0 +1,133 @@
+# Link
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: link
+
+# 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. Leave the default theme variant to follow the project decoration policy, choose underline for a persistent local affordance, or choose plain only inside unmistakable navigation whose container, current state, hover/pressed treatment, and focus ring preserve the destination affordance without decoration. Neutral navigation stays primary at rest and gains semantic accent emphasis on hover and press.
+- When a Link completes a sentence or paragraph, keep it inside that semantic Text owner and leave its default inherited size so typography and wrapping remain one coherent text flow; use layout components only for independently meaningful peer items.
+
+## Rules
+
+- **MUST:** Preserve anchor semantics and a real destination even when the link looks like a button.
+- **MUST:** Keep a Link that completes surrounding prose inside the owning sentence or paragraph and inherit its typography; do not split one sentence into layout siblings merely to align it.
+- **MUST:** When a theme removes the resting underline, keep accent link text at least 3:1 distinct from adjacent primary text and restore the underline on interaction.
+- **MUST:** Load styles.css or core.css plus link.css.
+
+## Common mistakes
+
+- **Avoid:** Replacing ordinary inline or standalone navigation with Button only to increase emphasis. **Instead:** Use Link for ordinary navigation; use Button with a real href only when the destination intentionally needs a filled, soft, outlined, or ghost action treatment.
+- **Avoid:** Rendering prose and the Link that completes it as separate Stack children, or explicitly restating Link's default inherited size. **Instead:** Render one semantic Text sentence with an inline Link and leave its inherited size implicit; reserve Stack for independent peers.
+- **Avoid:** Removing resting underlines globally without validating links against surrounding text. **Instead:** Use the Theme Link input so compilation validates the required text distinction, or keep underlines.
+
+## Validation checklist
+
+- Inspect href and accessible name.
+- For inline prose links, confirm the Link remains inside the owning sentence or paragraph, inherits its typography, and wraps as one text flow.
+- Test focus, Enter navigation, visited/external behavior when relevant, and contrast.
+- For no-resting-underline themes, verify the compiled 3:1 text-distinction result and the interactive underline.
+- For explicit plain navigation, verify no interaction underline appears, neutral destinations gain semantic accent hover/press emphasis, and container, current, and focus treatments still communicate the destination.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/link`
+- `text`
+- `stack`
+- `button`
+
+## Machine record
+
+```json
+{
+  "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. Leave the default theme variant to follow the project decoration policy, choose underline for a persistent local affordance, or choose plain only inside unmistakable navigation whose container, current state, hover/pressed treatment, and focus ring preserve the destination affordance without decoration. Neutral navigation stays primary at rest and gains semantic accent emphasis on hover and press.",
+    "When a Link completes a sentence or paragraph, keep it inside that semantic Text owner and leave its default inherited size so typography and wrapping remain one coherent text flow; use layout components only for independently meaningful peer items."
+  ],
+  "rules": [
+    {
+      "id": "link-destination",
+      "level": "must",
+      "statement": "Preserve anchor semantics and a real destination even when the link looks like a button."
+    },
+    {
+      "id": "link-inline-sentence",
+      "level": "must",
+      "statement": "Keep a Link that completes surrounding prose inside the owning sentence or paragraph and inherit its typography; do not split one sentence into layout siblings merely to align it."
+    },
+    {
+      "id": "link-plain-distinction",
+      "level": "must",
+      "statement": "When a theme removes the resting underline, keep accent link text at least 3:1 distinct from adjacent primary text and restore the underline on interaction."
+    },
+    {
+      "id": "link-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus link.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Replacing ordinary inline or standalone navigation with Button only to increase emphasis.",
+      "correction": "Use Link for ordinary navigation; use Button with a real href only when the destination intentionally needs a filled, soft, outlined, or ghost action treatment."
+    },
+    {
+      "mistake": "Rendering prose and the Link that completes it as separate Stack children, or explicitly restating Link's default inherited size.",
+      "correction": "Render one semantic Text sentence with an inline Link and leave its inherited size implicit; reserve Stack for independent peers."
+    },
+    {
+      "mistake": "Removing resting underlines globally without validating links against surrounding text.",
+      "correction": "Use the Theme Link input so compilation validates the required text distinction, or keep underlines."
+    }
+  ],
+  "validation": [
+    "Inspect href and accessible name.",
+    "For inline prose links, confirm the Link remains inside the owning sentence or paragraph, inherits its typography, and wraps as one text flow.",
+    "Test focus, Enter navigation, visited/external behavior when relevant, and contrast.",
+    "For no-resting-underline themes, verify the compiled 3:1 text-distinction result and the interactive underline.",
+    "For explicit plain navigation, verify no interaction underline appears, neutral destinations gain semantic accent hover/press emphasis, and container, current, and focus treatments still communicate the destination."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "link",
+      "versionPolicy": "installed-exact"
+    },
+    "text",
+    "stack",
+    "button"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/list.txt

@@ -0,0 +1,139 @@
+# List
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: list
+
+# List agent guide
+
+## Purpose
+
+Render finished ordered or unordered content with native list semantics, optional structured rows, markers, density, and boundaries.
+
+## Use when
+
+- Content is naturally a set of peer items or a sequence and needs Brick's finished list presentation.
+
+## Choose something else when
+
+- Rows are persistent route destinations or need current-route state. Use NavList.
+- Rows form a keyboard-operated choice, action collection, data table, or two-dimensional grid. Use Listbox, Menu, Table, or DataGrid according to the interaction.
+- Content only needs visual spacing and has no list relationship. Use Stack or Grid.
+
+## Required composition
+
+- Compose Root > Item; for structured rows use Leading, Content with Title and Description, then Trailing in that order.
+- Use ordered only when sequence changes meaning and preserve native list hosts when composing with asChild or render.
+- Keep Trailing for compact metadata or controls; when a long action would narrow supporting copy, place the action with the title inside Content using Brick layout instead.
+
+## Rules
+
+- **MUST:** Use List only for a real item or sequence relationship and preserve native list semantics.
+- **MUST:** Keep structured row parts in Leading, Content, Trailing order and use one Content and one Trailing maximum per Item.
+- **MUST:** Keep Trailing compact; move long actions into a Content-owned layout when a fixed trailing column would damage narrow-screen reading.
+- **MUST:** Do not add row selection, activation, focus movement, or navigation behavior to List; choose the component that owns that interaction.
+- **MUST:** Load styles.css or core.css plus list.css.
+
+## Common mistakes
+
+- **Avoid:** Using List as a generic row layout, making an Item itself clickable, or placing a long action in Trailing until supporting text becomes a narrow column. **Instead:** Use Stack or Grid for non-list layout, NavList or another interaction owner for clickable rows, and move long actions into Content's own layout.
+- **Avoid:** Assuming an Item's disabled presentation disables controls inside it. **Instead:** Apply the proper disabled contract to every interactive descendant; List's disabled state is descriptive and visual only.
+
+## Validation checklist
+
+- Inspect ul or ol and li output, ordered meaning, marker behavior, structured-part order, nesting, roles, and CSS delivery.
+- Test long titles and descriptions, compact and comfortable density, all variants and markers, first-line marker alignment in bordered simple and structured rows, 320 CSS px, 200 and 400 percent zoom, RTL, and forced colors.
+- Confirm Trailing content does not squeeze Content, controls have names and touch targets, disabled descendants are handled explicitly, and List adds no keyboard model.
+
+## Related guidance
+
+- `nav-list`
+- `stack`
+- `grid`
+- `text`
+- `divider`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "list",
+  "name": "List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render finished ordered or unordered content with native list semantics, optional structured rows, markers, density, and boundaries.",
+  "useWhen": [
+    "Content is naturally a set of peer items or a sequence and needs Brick's finished list presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Rows are persistent route destinations or need current-route state.",
+      "useInstead": "NavList"
+    },
+    {
+      "condition": "Rows form a keyboard-operated choice, action collection, data table, or two-dimensional grid.",
+      "useInstead": "Listbox, Menu, Table, or DataGrid according to the interaction"
+    },
+    {
+      "condition": "Content only needs visual spacing and has no list relationship.",
+      "useInstead": "Stack or Grid"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item; for structured rows use Leading, Content with Title and Description, then Trailing in that order.",
+    "Use ordered only when sequence changes meaning and preserve native list hosts when composing with asChild or render.",
+    "Keep Trailing for compact metadata or controls; when a long action would narrow supporting copy, place the action with the title inside Content using Brick layout instead."
+  ],
+  "rules": [
+    {
+      "id": "list-native-relationship",
+      "level": "must",
+      "statement": "Use List only for a real item or sequence relationship and preserve native list semantics."
+    },
+    {
+      "id": "list-structured-order",
+      "level": "must",
+      "statement": "Keep structured row parts in Leading, Content, Trailing order and use one Content and one Trailing maximum per Item."
+    },
+    {
+      "id": "list-trailing-width",
+      "level": "must",
+      "statement": "Keep Trailing compact; move long actions into a Content-owned layout when a fixed trailing column would damage narrow-screen reading."
+    },
+    {
+      "id": "list-no-interaction",
+      "level": "must",
+      "statement": "Do not add row selection, activation, focus movement, or navigation behavior to List; choose the component that owns that interaction."
+    },
+    {
+      "id": "list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using List as a generic row layout, making an Item itself clickable, or placing a long action in Trailing until supporting text becomes a narrow column.",
+      "correction": "Use Stack or Grid for non-list layout, NavList or another interaction owner for clickable rows, and move long actions into Content's own layout."
+    },
+    {
+      "mistake": "Assuming an Item's disabled presentation disables controls inside it.",
+      "correction": "Apply the proper disabled contract to every interactive descendant; List's disabled state is descriptive and visual only."
+    }
+  ],
+  "validation": [
+    "Inspect ul or ol and li output, ordered meaning, marker behavior, structured-part order, nesting, roles, and CSS delivery.",
+    "Test long titles and descriptions, compact and comfortable density, all variants and markers, first-line marker alignment in bordered simple and structured rows, 320 CSS px, 200 and 400 percent zoom, RTL, and forced colors.",
+    "Confirm Trailing content does not squeeze Content, controls have names and touch targets, disabled descendants are handled explicitly, and List adds no keyboard model."
+  ],
+  "related": [
+    "nav-list",
+    "stack",
+    "grid",
+    "text",
+    "divider"
+  ]
+}
+```