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

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

@@ -0,0 +1,150 @@
+# Toast
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: toast
+
+# Toast agent guide
+
+## Purpose
+
+Present queued finished transient updates while Atom owns store identity, timers, announcements, focus, hotkey access, portal, dismissal, swipe, and lifecycle.
+
+## Use when
+
+- A short non-blocking outcome or process update is useful, can be safely ignored, and remains recoverable or visible elsewhere without interrupting the current task.
+
+## Choose something else when
+
+- Feedback belongs beside a field, is essential or durable, represents numeric progress, or requires a response before continuing. Use Field or Form feedback, persistent application content, Progress, or AlertDialog.
+
+## Required composition
+
+- Install one Toaster near the application root. Create imperative updates with toast helpers, or use the public Toast.Root, Icon, Content, Title, Description, Actions, Action, Close, and Viewport parts for advanced rendering while preserving one Atom Provider and Viewport announcement path.
+- Supply concise meaningful title or description, choose type by announcement priority, localize Toaster label and closeLabel, and include an optional action only when it is safe to ignore and may dismiss immediately.
+
+## Rules
+
+- **MUST:** Never make Toast the sole home of essential, response-required, validation, or durable information because it is transient and does not move focus when it appears.
+- **MUST:** Keep Viewport's persistent polite and assertive announcers as the only live path; do not add role=status, role=alert, or aria-live to visible Root cards.
+- **MUST:** Use warning and error assertion only for genuinely important feedback, keep Title and Description concise, include meaning beyond color and glyph, and update content only when a new announcement is intended.
+- **MUST:** Preserve normalized duration, hover/focus/page-focus pause, localized hotkey access, focused Escape dismissal, and focus restoration; never steal focus merely because a toast appeared.
+- **MUST:** Use Brick's single Action only for a callback that may dismiss immediately; Brick has no Cancel part, and async interaction that must stay open belongs in persistent application UI.
+- **MUST:** Keep Close, Escape, timeout, or another obvious path available; directional swipe is optional and never the sole dismissal mechanism.
+- **MUST:** Choose logical position, responsive/compact/full width, and separated/overlap stacking deliberately; keep safe areas, fixed chrome, software keyboards, narrow screens, zoom, RTL, and viewport offsets under styled or application ownership.
+- **MUST:** Load styles.css or core.css plus toast.css.
+
+## Common mistakes
+
+- **Avoid:** Using Toast for validation or confirmation, adding a second live region, choosing assertive type by color preference, or expecting Action to remain open during async work. **Instead:** Use inline or blocking UI for those jobs, preserve one announcement path, choose priority semantically, and move persistent async interaction outside Toast.
+- **Avoid:** Making swipe the only dismissal, mounting multiple Toasters casually, or allowing fixed application chrome to cover the viewport. **Instead:** Provide an obvious non-swipe dismissal, keep one application-level viewport, and set documented logical offsets for measured chrome collisions.
+
+## Validation checklist
+
+- Verify imperative create/update/dismiss and promise flows, declarative Root, stable IDs, type priority, duration and maxVisible normalization, queue and stacking, close inheritance, entry/exit lifecycle, forceMount, auto-close, pause policies, and meaningful updates announced once.
+- Verify localized Viewport label/hotkey, polite/assertive announcers, no visible-card live region, focus-within pause, Escape and restoration, Action and Close callbacks/dismissal, optional swipe threshold/direction/cancel, non-swipe dismissal, custom renderToast, portal container, and logical positions.
+- Verify six types, all width/stacking/position recipes, title-only and description-only geometry, long localized content, safe-area and application offsets, 320px, zoom, RTL, light/dark appearance, forced colors, and reduced motion.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/toast`
+- `alert-dialog`
+- `field`
+- `form`
+- `progress`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toast",
+  "name": "Toast",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present queued finished transient updates while Atom owns store identity, timers, announcements, focus, hotkey access, portal, dismissal, swipe, and lifecycle.",
+  "useWhen": [
+    "A short non-blocking outcome or process update is useful, can be safely ignored, and remains recoverable or visible elsewhere without interrupting the current task."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Feedback belongs beside a field, is essential or durable, represents numeric progress, or requires a response before continuing.",
+      "useInstead": "Field or Form feedback, persistent application content, Progress, or AlertDialog"
+    }
+  ],
+  "composition": [
+    "Install one Toaster near the application root. Create imperative updates with toast helpers, or use the public Toast.Root, Icon, Content, Title, Description, Actions, Action, Close, and Viewport parts for advanced rendering while preserving one Atom Provider and Viewport announcement path.",
+    "Supply concise meaningful title or description, choose type by announcement priority, localize Toaster label and closeLabel, and include an optional action only when it is safe to ignore and may dismiss immediately."
+  ],
+  "rules": [
+    {
+      "id": "toast-nonessential",
+      "level": "must",
+      "statement": "Never make Toast the sole home of essential, response-required, validation, or durable information because it is transient and does not move focus when it appears."
+    },
+    {
+      "id": "toast-single-live-path",
+      "level": "must",
+      "statement": "Keep Viewport's persistent polite and assertive announcers as the only live path; do not add role=status, role=alert, or aria-live to visible Root cards."
+    },
+    {
+      "id": "toast-priority-content",
+      "level": "must",
+      "statement": "Use warning and error assertion only for genuinely important feedback, keep Title and Description concise, include meaning beyond color and glyph, and update content only when a new announcement is intended."
+    },
+    {
+      "id": "toast-timing-focus",
+      "level": "must",
+      "statement": "Preserve normalized duration, hover/focus/page-focus pause, localized hotkey access, focused Escape dismissal, and focus restoration; never steal focus merely because a toast appeared."
+    },
+    {
+      "id": "toast-actions-dismiss",
+      "level": "must",
+      "statement": "Use Brick's single Action only for a callback that may dismiss immediately; Brick has no Cancel part, and async interaction that must stay open belongs in persistent application UI."
+    },
+    {
+      "id": "toast-dismissal",
+      "level": "must",
+      "statement": "Keep Close, Escape, timeout, or another obvious path available; directional swipe is optional and never the sole dismissal mechanism."
+    },
+    {
+      "id": "toast-responsive",
+      "level": "must",
+      "statement": "Choose logical position, responsive/compact/full width, and separated/overlap stacking deliberately; keep safe areas, fixed chrome, software keyboards, narrow screens, zoom, RTL, and viewport offsets under styled or application ownership."
+    },
+    {
+      "id": "toast-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus toast.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Toast for validation or confirmation, adding a second live region, choosing assertive type by color preference, or expecting Action to remain open during async work.",
+      "correction": "Use inline or blocking UI for those jobs, preserve one announcement path, choose priority semantically, and move persistent async interaction outside Toast."
+    },
+    {
+      "mistake": "Making swipe the only dismissal, mounting multiple Toasters casually, or allowing fixed application chrome to cover the viewport.",
+      "correction": "Provide an obvious non-swipe dismissal, keep one application-level viewport, and set documented logical offsets for measured chrome collisions."
+    }
+  ],
+  "validation": [
+    "Verify imperative create/update/dismiss and promise flows, declarative Root, stable IDs, type priority, duration and maxVisible normalization, queue and stacking, close inheritance, entry/exit lifecycle, forceMount, auto-close, pause policies, and meaningful updates announced once.",
+    "Verify localized Viewport label/hotkey, polite/assertive announcers, no visible-card live region, focus-within pause, Escape and restoration, Action and Close callbacks/dismissal, optional swipe threshold/direction/cancel, non-swipe dismissal, custom renderToast, portal container, and logical positions.",
+    "Verify six types, all width/stacking/position recipes, title-only and description-only geometry, long localized content, safe-area and application offsets, 320px, zoom, RTL, light/dark appearance, forced colors, and reduced motion."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "toast",
+      "versionPolicy": "installed-exact"
+    },
+    "alert-dialog",
+    "field",
+    "form",
+    "progress"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/toggle-group.txt

@@ -0,0 +1,149 @@
+# ToggleGroup
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: toggle-group
+
+# ToggleGroup agent guide
+
+## Purpose
+
+Coordinate a related set of single- or multiple-selection pressed commands with shared Brick recipes and Atom keyboard behavior.
+
+## Use when
+
+- Related view, formatting, filter, or presentation commands need a visible pressed state and arrow-key movement.
+
+## Choose something else when
+
+- One independent command toggles, a form submits one required choice, or the selection changes the displayed panel. Use Toggle, RadioGroup, or Tabs according to the user job.
+
+## Required composition
+
+- Compose named Item controls directly inside Root, choose single or multiple value semantics deliberately, and let Root own the shared variant, tone, size, shape, attachment, and width policy.
+- Use iconOnly only when an Item contains an icon with a complete accessible name; keep visible labels when the icon is not universally understood.
+
+## Rules
+
+- **MUST:** Choose single or multiple mode from the command model and keep the value and onValueChange types consistent with that choice.
+- **MUST:** Do not use ToggleGroup for a form choice that requires radio semantics, validation, or ordinary form submission.
+- **MUST:** Give Root an accessible name when surrounding context is insufficient and give every Item a stable complete name.
+- **MUST:** Give every Item a stable unique value, route controlled changes through onValueChange, and keep string values for single mode and string-array values for multiple mode.
+- **MUST:** Preserve one roving Tab stop, DOM-order registration, disabled-item skipping, looping policy, orientation-specific Arrow keys, Home/End, and horizontal RTL mirroring.
+- **MUST:** Use accent or neutral tone for selection emphasis; do not use semantic status colors to imply error, success, warning, or danger.
+- **MUST:** Choose wrapping, orientation, or an alternative narrow layout without changing DOM order or clipping focus; attached groups do not wrap.
+- **MUST:** Load styles.css or core.css plus toggle-group.css.
+
+## Common mistakes
+
+- **Avoid:** Using ToggleGroup as visual tabs, omitting the group name, or styling every Item independently so selected states drift. **Instead:** Use Tabs for panels, name the command group, and configure the shared variant and tone on Root.
+
+## Validation checklist
+
+- Check single and multiple values, pressed state, arrows, Home and End, looping, disabled-item skipping, and controlled behavior.
+- Check wrapping or vertical layout, touch targets, focus visibility, themes, zoom, and RTL.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/toggle-group`
+- `toggle`
+- `radio-group`
+- `checkbox-group`
+- `switch`
+- `tabs`
+- `toolbar`
+- `icon`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toggle-group",
+  "name": "ToggleGroup",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Coordinate a related set of single- or multiple-selection pressed commands with shared Brick recipes and Atom keyboard behavior.",
+  "useWhen": [
+    "Related view, formatting, filter, or presentation commands need a visible pressed state and arrow-key movement."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "One independent command toggles, a form submits one required choice, or the selection changes the displayed panel.",
+      "useInstead": "Toggle, RadioGroup, or Tabs according to the user job"
+    }
+  ],
+  "composition": [
+    "Compose named Item controls directly inside Root, choose single or multiple value semantics deliberately, and let Root own the shared variant, tone, size, shape, attachment, and width policy.",
+    "Use iconOnly only when an Item contains an icon with a complete accessible name; keep visible labels when the icon is not universally understood."
+  ],
+  "rules": [
+    {
+      "id": "toggle-group-selection-model",
+      "level": "must",
+      "statement": "Choose single or multiple mode from the command model and keep the value and onValueChange types consistent with that choice."
+    },
+    {
+      "id": "toggle-group-not-radio",
+      "level": "must",
+      "statement": "Do not use ToggleGroup for a form choice that requires radio semantics, validation, or ordinary form submission."
+    },
+    {
+      "id": "toggle-group-naming",
+      "level": "must",
+      "statement": "Give Root an accessible name when surrounding context is insufficient and give every Item a stable complete name."
+    },
+    {
+      "id": "toggle-group-values",
+      "level": "must",
+      "statement": "Give every Item a stable unique value, route controlled changes through onValueChange, and keep string values for single mode and string-array values for multiple mode."
+    },
+    {
+      "id": "toggle-group-roving",
+      "level": "must",
+      "statement": "Preserve one roving Tab stop, DOM-order registration, disabled-item skipping, looping policy, orientation-specific Arrow keys, Home/End, and horizontal RTL mirroring."
+    },
+    {
+      "id": "toggle-group-tone",
+      "level": "must",
+      "statement": "Use accent or neutral tone for selection emphasis; do not use semantic status colors to imply error, success, warning, or danger."
+    },
+    {
+      "id": "toggle-group-responsive-policy",
+      "level": "must",
+      "statement": "Choose wrapping, orientation, or an alternative narrow layout without changing DOM order or clipping focus; attached groups do not wrap."
+    },
+    {
+      "id": "toggle-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus toggle-group.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ToggleGroup as visual tabs, omitting the group name, or styling every Item independently so selected states drift.",
+      "correction": "Use Tabs for panels, name the command group, and configure the shared variant and tone on Root."
+    }
+  ],
+  "validation": [
+    "Check single and multiple values, pressed state, arrows, Home and End, looping, disabled-item skipping, and controlled behavior.",
+    "Check wrapping or vertical layout, touch targets, focus visibility, themes, zoom, and RTL."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "toggle-group",
+      "versionPolicy": "installed-exact"
+    },
+    "toggle",
+    "radio-group",
+    "checkbox-group",
+    "switch",
+    "tabs",
+    "toolbar",
+    "icon"
+  ]
+}
+```

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

@@ -0,0 +1,140 @@
+# Toggle
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: toggle
+
+# Toggle agent guide
+
+## Purpose
+
+Present one persistent pressed or unpressed command with Brick recipes and Atom-owned button behavior.
+
+## Use when
+
+- One command such as Favorite, Pin, Bold, or Show completed needs a persistent pressed state.
+
+## Choose something else when
+
+- Related pressed commands need shared selection and arrow navigation. Use ToggleGroup.
+- A momentary action, submitted choice, boolean setting, or panel switch is required. Use Button, Checkbox, Switch, or Tabs according to the job.
+
+## Required composition
+
+- Keep one stable visible or accessible name across pressed states; use iconOnly only with a complete accessible name.
+- Choose variant for the selected-state treatment and accent or neutral tone for its emphasis before applying local customization.
+
+## Rules
+
+- **MUST:** Use Toggle only when the same command meaning remains valid in pressed and unpressed states.
+- **MUST:** Use accent or neutral tone for selection emphasis; do not use semantic status colors to imply error, success, warning, or danger.
+- **MUST:** Preserve Atom-owned native button semantics, aria-pressed state, activation, disabled behavior, and composition.
+- **MUST:** Use pressed with onPressedChange for controlled state or defaultPressed for uncontrolled state, and keep one stable command name across both aria-pressed states.
+- **MUST:** When using asChild or render, preserve one element with Atom props, handlers, refs, tab stop, Enter and Space activation, button semantics, and disabled exposure.
+- **MUST:** Load styles.css or core.css plus toggle.css.
+
+## Common mistakes
+
+- **Avoid:** Using Toggle as Checkbox, Switch, Button, or a visual tab, or changing its accessible name with state. **Instead:** Select the component matching the interaction and keep Toggle's command name stable.
+
+## Validation checklist
+
+- Check pointer and keyboard activation, controlled and uncontrolled state, stable naming, disabled state, and complete icon-only names.
+- Check every adopted variant and accent/neutral tone in light, dark, forced colors, narrow layouts, zoom, and RTL.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/toggle`
+- `toggle-group`
+- `toolbar`
+- `button`
+- `checkbox`
+- `switch`
+- `tabs`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toggle",
+  "name": "Toggle",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one persistent pressed or unpressed command with Brick recipes and Atom-owned button behavior.",
+  "useWhen": [
+    "One command such as Favorite, Pin, Bold, or Show completed needs a persistent pressed state."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Related pressed commands need shared selection and arrow navigation.",
+      "useInstead": "ToggleGroup"
+    },
+    {
+      "condition": "A momentary action, submitted choice, boolean setting, or panel switch is required.",
+      "useInstead": "Button, Checkbox, Switch, or Tabs according to the job"
+    }
+  ],
+  "composition": [
+    "Keep one stable visible or accessible name across pressed states; use iconOnly only with a complete accessible name.",
+    "Choose variant for the selected-state treatment and accent or neutral tone for its emphasis before applying local customization."
+  ],
+  "rules": [
+    {
+      "id": "toggle-role",
+      "level": "must",
+      "statement": "Use Toggle only when the same command meaning remains valid in pressed and unpressed states."
+    },
+    {
+      "id": "toggle-tone",
+      "level": "must",
+      "statement": "Use accent or neutral tone for selection emphasis; do not use semantic status colors to imply error, success, warning, or danger."
+    },
+    {
+      "id": "toggle-behavior",
+      "level": "must",
+      "statement": "Preserve Atom-owned native button semantics, aria-pressed state, activation, disabled behavior, and composition."
+    },
+    {
+      "id": "toggle-state",
+      "level": "must",
+      "statement": "Use pressed with onPressedChange for controlled state or defaultPressed for uncontrolled state, and keep one stable command name across both aria-pressed states."
+    },
+    {
+      "id": "toggle-composition",
+      "level": "must",
+      "statement": "When using asChild or render, preserve one element with Atom props, handlers, refs, tab stop, Enter and Space activation, button semantics, and disabled exposure."
+    },
+    {
+      "id": "toggle-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus toggle.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Toggle as Checkbox, Switch, Button, or a visual tab, or changing its accessible name with state.",
+      "correction": "Select the component matching the interaction and keep Toggle's command name stable."
+    }
+  ],
+  "validation": [
+    "Check pointer and keyboard activation, controlled and uncontrolled state, stable naming, disabled state, and complete icon-only names.",
+    "Check every adopted variant and accent/neutral tone in light, dark, forced colors, narrow layouts, zoom, and RTL."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "toggle",
+      "versionPolicy": "installed-exact"
+    },
+    "toggle-group",
+    "toolbar",
+    "button",
+    "checkbox",
+    "switch",
+    "tabs"
+  ]
+}
+```

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

@@ -0,0 +1,118 @@
+# Toolbar
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: toolbar
+
+# Toolbar agent guide
+
+## Purpose
+
+Style one logical group of related commands with Atom toolbar semantics and roving keyboard focus.
+
+## Use when
+
+- Related editor or application controls should behave as one horizontal or vertical keyboard group.
+
+## Choose something else when
+
+- The items are navigation destinations or unrelated standalone actions. Use NavigationMenu/NavList or separate Button and IconButton controls.
+
+## Required composition
+
+- Compose Button, Link, Separator, and ToggleGroup/ToggleItem parts inside a named Root; configure Toggle selection through its shared variant and accent/neutral tone, and use Brick icons with concise visible or accessible labels.
+
+## Rules
+
+- **MUST:** Use Toolbar rather than adding manual arrow-key handlers or role=toolbar to an AppBar row.
+- **MUST:** Define a deliberate narrow-width wrap, scroll, or alternative composition without breaking roving focus order.
+- **MUST:** Configure Toolbar ToggleItems through their ToggleGroup variant and tone; do not replace Toolbar behavior with a standalone ToggleGroup or style Items independently.
+- **MUST:** Treat neutral as non-accent intent and let Toolbar own its layered selected-surface recipe; do not copy a neutral solid Button fill into ToggleItems.
+- **MUST:** Load styles.css or core.css plus toolbar.css and any composed Icon stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using AppBar.Toolbar as the behavior owner or placing unrelated page actions in one roving group. **Instead:** Compose a named Toolbar only around logically related controls.
+
+## Validation checklist
+
+- Test orientation, arrows, disabled items, links, toggles, separators, Tab entry/exit, focus rings, touch targets, overflow, themes, zoom, and RTL.
+- Confirm names and CSS delivery.
+
+## Related guidance
+
+- `app-bar`
+- `button`
+- `icon-button`
+- `toggle-group`
+- `divider`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toolbar",
+  "name": "Toolbar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style one logical group of related commands with Atom toolbar semantics and roving keyboard focus.",
+  "useWhen": [
+    "Related editor or application controls should behave as one horizontal or vertical keyboard group."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The items are navigation destinations or unrelated standalone actions.",
+      "useInstead": "NavigationMenu/NavList or separate Button and IconButton controls"
+    }
+  ],
+  "composition": [
+    "Compose Button, Link, Separator, and ToggleGroup/ToggleItem parts inside a named Root; configure Toggle selection through its shared variant and accent/neutral tone, and use Brick icons with concise visible or accessible labels."
+  ],
+  "rules": [
+    {
+      "id": "toolbar-owner",
+      "level": "must",
+      "statement": "Use Toolbar rather than adding manual arrow-key handlers or role=toolbar to an AppBar row."
+    },
+    {
+      "id": "toolbar-overflow",
+      "level": "must",
+      "statement": "Define a deliberate narrow-width wrap, scroll, or alternative composition without breaking roving focus order."
+    },
+    {
+      "id": "toolbar-toggle-recipes",
+      "level": "must",
+      "statement": "Configure Toolbar ToggleItems through their ToggleGroup variant and tone; do not replace Toolbar behavior with a standalone ToggleGroup or style Items independently."
+    },
+    {
+      "id": "toolbar-neutral-recipe",
+      "level": "must",
+      "statement": "Treat neutral as non-accent intent and let Toolbar own its layered selected-surface recipe; do not copy a neutral solid Button fill into ToggleItems."
+    },
+    {
+      "id": "toolbar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus toolbar.css and any composed Icon stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AppBar.Toolbar as the behavior owner or placing unrelated page actions in one roving group.",
+      "correction": "Compose a named Toolbar only around logically related controls."
+    }
+  ],
+  "validation": [
+    "Test orientation, arrows, disabled items, links, toggles, separators, Tab entry/exit, focus rings, touch targets, overflow, themes, zoom, and RTL.",
+    "Confirm names and CSS delivery."
+  ],
+  "related": [
+    "app-bar",
+    "button",
+    "icon-button",
+    "toggle-group",
+    "divider"
+  ]
+}
+```