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

package/public/packages/atom/0.24.0/components/switch.txt

@@ -0,0 +1,116 @@
+# Switch
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: switch
+
+# Switch agent guide
+
+## Purpose
+
+Represent an immediately applied on/off setting with switch semantics, controlled or uncontrolled state, field integration, and optional native form participation.
+
+## Use when
+
+- A setting becomes active or inactive immediately when the user operates it.
+
+## Choose something else when
+
+- The choice is a form answer applied later or a command whose pressed state remains active. Use Checkbox or Toggle.
+
+## Required composition
+
+- Give Root visible text or a native accessible name and add Thumb only when the styled layer needs a decorative movable part. Use name, value, and form when checked state must submit.
+
+## Rules
+
+- **MUST:** Give Root a complete accessible name with visible text, aria-label, aria-labelledby, or Field labeling; Thumb remains decorative and aria-hidden.
+- **MUST:** Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state, and preserve role=switch with aria-checked.
+- **MUST:** Use Switch only for an immediately applied on/off setting; do not substitute it for a deferred checkbox answer or pressed command.
+- **MUST:** Keep read-only Switch focusable while preventing Enter, Space, pointer, and custom-element activation from changing state.
+- **MUST:** Preserve aligned native submission and required-validity proxies, Field state and descriptions, validation focus, and uncontrolled form reset when form behavior applies.
+
+## Common mistakes
+
+- **Avoid:** Using Switch for a submit-later checkbox, relying on Thumb as the accessible control, or using disabled when the value should remain focusable and read-only. **Instead:** Choose by timing and semantics, name Root, keep Thumb decorative, and use readOnly for discoverable locked state.
+
+## Validation checklist
+
+- Verify accessible name, role and checked state, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native and custom asChild/render semantics.
+- Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, inline/native validation focus, form association, and uncontrolled reset.
+
+## Related guidance
+
+- `checkbox`
+- `toggle`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "switch",
+  "name": "Switch",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Represent an immediately applied on/off setting with switch semantics, controlled or uncontrolled state, field integration, and optional native form participation.",
+  "useWhen": [
+    "A setting becomes active or inactive immediately when the user operates it."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The choice is a form answer applied later or a command whose pressed state remains active.",
+      "useInstead": "Checkbox or Toggle"
+    }
+  ],
+  "composition": [
+    "Give Root visible text or a native accessible name and add Thumb only when the styled layer needs a decorative movable part. Use name, value, and form when checked state must submit."
+  ],
+  "rules": [
+    {
+      "id": "switch-name",
+      "level": "must",
+      "statement": "Give Root a complete accessible name with visible text, aria-label, aria-labelledby, or Field labeling; Thumb remains decorative and aria-hidden."
+    },
+    {
+      "id": "switch-state",
+      "level": "must",
+      "statement": "Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state, and preserve role=switch with aria-checked."
+    },
+    {
+      "id": "switch-immediate-setting",
+      "level": "must",
+      "statement": "Use Switch only for an immediately applied on/off setting; do not substitute it for a deferred checkbox answer or pressed command."
+    },
+    {
+      "id": "switch-readonly",
+      "level": "must",
+      "statement": "Keep read-only Switch focusable while preventing Enter, Space, pointer, and custom-element activation from changing state."
+    },
+    {
+      "id": "switch-form",
+      "level": "must",
+      "statement": "Preserve aligned native submission and required-validity proxies, Field state and descriptions, validation focus, and uncontrolled form reset when form behavior applies."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Switch for a submit-later checkbox, relying on Thumb as the accessible control, or using disabled when the value should remain focusable and read-only.",
+      "correction": "Choose by timing and semantics, name Root, keep Thumb decorative, and use readOnly for discoverable locked state."
+    }
+  ],
+  "validation": [
+    "Verify accessible name, role and checked state, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native and custom asChild/render semantics.",
+    "Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, inline/native validation focus, form association, and uncontrolled reset."
+  ],
+  "related": [
+    "checkbox",
+    "toggle",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/table.txt

@@ -0,0 +1,128 @@
+# Table
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: table
+
+# Table agent guide
+
+## Purpose
+
+Render native tabular structure for read-oriented row and column relationships, with caption, section, header, cell, and sort metadata anatomy.
+
+## Use when
+
+- People primarily read and compare values whose row and column relationships are meaningful, without composite grid navigation or row selection.
+
+## Choose something else when
+
+- Cells need two-dimensional keyboard navigation or rows need composite selection. Use DataGrid.
+- Rows are hierarchical and expand into nested rows with several columns, or the content has no meaningful column relationships. Use TreeGrid or List.
+
+## Required composition
+
+- Compose Root with a naming Caption or equivalent accessible name, Header and Body section groups, Row, correctly scoped Head cells, and Cell parts; add Footer only for genuine summary rows and put an interactive control inside Head only when sorting is application-controlled.
+
+## Rules
+
+- **MUST:** Preserve native table, caption, section, row, th, and td semantics and valid table nesting; do not add an ARIA grid interaction model to read-only data.
+- **MUST:** Give the table an accessible name or useful caption when surrounding context does not already identify it.
+- **MUST:** Use Head for actual headers and choose scope or explicit native header relationships that accurately associate headers with data cells.
+- **MUST:** Treat sortDirection as metadata only; place a labelled interactive control inside a sortable Head and keep sorting, data order, and state application-owned.
+- **MUST:** Do not invent table-level keyboard navigation or Tab stops; only genuine interactive descendants participate in keyboard focus.
+
+## Common mistakes
+
+- **Avoid:** Using Table because data looks rectangular even though users must navigate cells or select rows as one composite widget. **Instead:** Use DataGrid for a flat interactive grid or TreeGrid for a hierarchical interactive grid.
+- **Avoid:** Setting sortDirection on Head without a keyboard-operable sorting control or expecting Atom to reorder data. **Instead:** Nest a labelled Button or Pressable, update application sorting, and keep sortDirection synchronized with the result.
+
+## Validation checklist
+
+- Inspect the final DOM for valid native table nesting, an appropriate accessible name, correct header scope or associations, and meaningful caption and footer content.
+- Verify sortable headers expose accurate aria-sort, provide equivalent keyboard and pointer activation through a real control, and update application-owned data without adding table-level focus behavior.
+- Verify server-safe rendering and asChild or render overrides preserve the required native semantics, props, and refs.
+
+## Related guidance
+
+- `data-grid`
+- `tree-grid`
+- `list`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "table",
+  "name": "Table",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Render native tabular structure for read-oriented row and column relationships, with caption, section, header, cell, and sort metadata anatomy.",
+  "useWhen": [
+    "People primarily read and compare values whose row and column relationships are meaningful, without composite grid navigation or row selection."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Cells need two-dimensional keyboard navigation or rows need composite selection.",
+      "useInstead": "DataGrid"
+    },
+    {
+      "condition": "Rows are hierarchical and expand into nested rows with several columns, or the content has no meaningful column relationships.",
+      "useInstead": "TreeGrid or List"
+    }
+  ],
+  "composition": [
+    "Compose Root with a naming Caption or equivalent accessible name, Header and Body section groups, Row, correctly scoped Head cells, and Cell parts; add Footer only for genuine summary rows and put an interactive control inside Head only when sorting is application-controlled."
+  ],
+  "rules": [
+    {
+      "id": "table-native-semantics",
+      "level": "must",
+      "statement": "Preserve native table, caption, section, row, th, and td semantics and valid table nesting; do not add an ARIA grid interaction model to read-only data."
+    },
+    {
+      "id": "table-name",
+      "level": "must",
+      "statement": "Give the table an accessible name or useful caption when surrounding context does not already identify it."
+    },
+    {
+      "id": "table-header-association",
+      "level": "must",
+      "statement": "Use Head for actual headers and choose scope or explicit native header relationships that accurately associate headers with data cells."
+    },
+    {
+      "id": "table-sort-boundary",
+      "level": "must",
+      "statement": "Treat sortDirection as metadata only; place a labelled interactive control inside a sortable Head and keep sorting, data order, and state application-owned."
+    },
+    {
+      "id": "table-keyboard",
+      "level": "must",
+      "statement": "Do not invent table-level keyboard navigation or Tab stops; only genuine interactive descendants participate in keyboard focus."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Table because data looks rectangular even though users must navigate cells or select rows as one composite widget.",
+      "correction": "Use DataGrid for a flat interactive grid or TreeGrid for a hierarchical interactive grid."
+    },
+    {
+      "mistake": "Setting sortDirection on Head without a keyboard-operable sorting control or expecting Atom to reorder data.",
+      "correction": "Nest a labelled Button or Pressable, update application sorting, and keep sortDirection synchronized with the result."
+    }
+  ],
+  "validation": [
+    "Inspect the final DOM for valid native table nesting, an appropriate accessible name, correct header scope or associations, and meaningful caption and footer content.",
+    "Verify sortable headers expose accurate aria-sort, provide equivalent keyboard and pointer activation through a real control, and update application-owned data without adding table-level focus behavior.",
+    "Verify server-safe rendering and asChild or render overrides preserve the required native semantics, props, and refs."
+  ],
+  "related": [
+    "data-grid",
+    "tree-grid",
+    "list",
+    "button"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/tabs.txt

@@ -0,0 +1,96 @@
+# Tabs
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: tabs
+
+# Tabs agent guide
+
+## Purpose
+
+Switch among related panels in one page with linked tab semantics, selection state, and roving keyboard focus.
+
+## Use when
+
+- A small set of related views shares one page and only one panel is normally active.
+
+## Choose something else when
+
+- Choices navigate to destinations or multiple sections may remain open. Use Link or Accordion.
+
+## Required composition
+
+- Compose Trigger and optional Indicator inside List, with one matching Content value for each Trigger inside Root.
+
+## Rules
+
+- **MUST:** Give every Trigger a unique value and matching Content relationship.
+- **SHOULD:** Use manual activation when changing panels is expensive or selection should require explicit confirmation.
+
+## Common mistakes
+
+- **Avoid:** Using Tabs as route navigation or placing unmatched panels outside Root. **Instead:** Use links for routes and keep paired Trigger and Content parts in one Tabs context.
+
+## Validation checklist
+
+- Test arrow, Home, End, Enter, Space, Tab, disabled items, controlled state, orientation, and RTL.
+- Confirm tab/tabpanel IDs and aria relationships remain valid.
+
+## Related guidance
+
+- `accordion`
+- `bottom-navigation`
+- `navigation-menu`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "tabs",
+  "name": "Tabs",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Switch among related panels in one page with linked tab semantics, selection state, and roving keyboard focus.",
+  "useWhen": [
+    "A small set of related views shares one page and only one panel is normally active."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Choices navigate to destinations or multiple sections may remain open.",
+      "useInstead": "Link or Accordion"
+    }
+  ],
+  "composition": [
+    "Compose Trigger and optional Indicator inside List, with one matching Content value for each Trigger inside Root."
+  ],
+  "rules": [
+    {
+      "id": "tabs-value-pairs",
+      "level": "must",
+      "statement": "Give every Trigger a unique value and matching Content relationship."
+    },
+    {
+      "id": "tabs-activation",
+      "level": "should",
+      "statement": "Use manual activation when changing panels is expensive or selection should require explicit confirmation."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Tabs as route navigation or placing unmatched panels outside Root.",
+      "correction": "Use links for routes and keep paired Trigger and Content parts in one Tabs context."
+    }
+  ],
+  "validation": [
+    "Test arrow, Home, End, Enter, Space, Tab, disabled items, controlled state, orientation, and RTL.",
+    "Confirm tab/tabpanel IDs and aria relationships remain valid."
+  ],
+  "related": [
+    "accordion",
+    "bottom-navigation",
+    "navigation-menu"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/textarea.txt

@@ -0,0 +1,96 @@
+# Textarea
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: textarea
+
+# Textarea agent guide
+
+## Purpose
+
+Provide headless native multi-line text entry with Field relationships and controlled or uncontrolled value handling.
+
+## Use when
+
+- The user may enter sentences, paragraphs, notes, or other multi-line text.
+
+## Choose something else when
+
+- The expected value is short and single-line. Use Input.
+
+## Required composition
+
+- Place Textarea.Root inside one Field.Root with Field.Label and an optional description or character guidance.
+
+## Rules
+
+- **MUST:** Give every Textarea an accessible name, normally through Field.Label.
+- **MUST:** Provide a stable name when the value participates in submission.
+
+## Common mistakes
+
+- **Avoid:** Replacing Textarea with a contenteditable div for ordinary text entry. **Instead:** Use native Textarea unless rich-text behavior is genuinely required.
+
+## Validation checklist
+
+- Inspect the label and description relationships.
+- Test multi-line keyboard entry, resizing policy, and submitted value.
+
+## Related guidance
+
+- `field`
+- `form`
+- `input`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "textarea",
+  "name": "Textarea",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide headless native multi-line text entry with Field relationships and controlled or uncontrolled value handling.",
+  "useWhen": [
+    "The user may enter sentences, paragraphs, notes, or other multi-line text."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The expected value is short and single-line.",
+      "useInstead": "Input"
+    }
+  ],
+  "composition": [
+    "Place Textarea.Root inside one Field.Root with Field.Label and an optional description or character guidance."
+  ],
+  "rules": [
+    {
+      "id": "textarea-labeled",
+      "level": "must",
+      "statement": "Give every Textarea an accessible name, normally through Field.Label."
+    },
+    {
+      "id": "textarea-name",
+      "level": "must",
+      "statement": "Provide a stable name when the value participates in submission."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Replacing Textarea with a contenteditable div for ordinary text entry.",
+      "correction": "Use native Textarea unless rich-text behavior is genuinely required."
+    }
+  ],
+  "validation": [
+    "Inspect the label and description relationships.",
+    "Test multi-line keyboard entry, resizing policy, and submitted value."
+  ],
+  "related": [
+    "field",
+    "form",
+    "input"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/toast.txt

@@ -0,0 +1,124 @@
+# Toast
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: toast
+
+# Toast agent guide
+
+## Purpose
+
+Queue, display, announce, pause, act on, and dismiss short non-blocking updates through declarative or imperative toast state and a persistent accessible notification viewport.
+
+## Use when
+
+- A short status update is useful but must not interrupt the current task or require a response before work continues.
+
+## Choose something else when
+
+- Feedback belongs beside a field, is essential or durable, or the user must respond before continuing. Use inline feedback, persistent application content, or AlertDialog.
+
+## Required composition
+
+- Place one Viewport under Provider for queued and announced toasts. Create imperative toasts with toast helpers or compose declarative Root with concise Title and optional Description; add Action, Cancel, or Close only when the toast needs those dismissing controls.
+
+## Rules
+
+- **MUST:** Do not place essential, sole, or response-required information only in Toast because it is transient and never moves focus on appearance.
+- **MUST:** Keep Viewport's persistent polite and assertive announcers as the sole live path; do not add role=status, role=alert, or aria-live to visible store-rendered Root cards.
+- **MUST:** Choose toast type by announcement priority, keep Title and Description concise, and update content only when a meaningful new announcement is intended.
+- **MUST:** Preserve finite duration normalization, hover/focus/page-focus pause policies, labelled hotkey access, focused Escape dismissal, and focus restoration; never move focus merely because a toast appeared.
+- **MUST:** Use Action and Cancel only when running their callbacks should then dismiss; move async interactions that must remain open into separate persistent UI.
+- **MUST:** Keep Close, Escape, timeout, or another obvious dismissal path available; directional swipe is optional enhancement and never the only mechanism.
+- **SHOULD:** Keep safe-area, persistent chrome, software-keyboard, and viewport positioning decisions in the styled or application layer while consuming Atom's logical position and state.
+
+## Common mistakes
+
+- **Avoid:** Using Toast for validation or confirmation, adding a second live region to visible cards, making swipe the only dismissal, or expecting an action to remain open during async work. **Instead:** Use inline or blocking UI for those jobs, preserve the single announcer path and equivalent dismissal, and move persistent async interaction out of the toast.
+
+## Validation checklist
+
+- Verify imperative create/update/dismiss and declarative Root, stable IDs, type role priority, duration and maxVisible normalization, queue order and stack anchoring, close inheritance, entry/exit lifecycle, forceMount, auto-close, hover/focus/page pause, and meaningful update announcements exactly once.
+- Verify labelled Viewport and hotkey, polite/assertive persistent announcers, no visible-card live region, focus-within pause, focused and viewport Escape, focus restoration, Action/Cancel/Close callbacks and dismissal, pointer swipe threshold/direction/cancel, non-swipe dismissal, custom renderToast, asChild viewport insertion, portal container, and logical positions.
+
+## Related guidance
+
+- `alert-dialog`
+- `field`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toast",
+  "name": "Toast",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Queue, display, announce, pause, act on, and dismiss short non-blocking updates through declarative or imperative toast state and a persistent accessible notification viewport.",
+  "useWhen": [
+    "A short status update is useful but must not interrupt the current task or require a response before work continues."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Feedback belongs beside a field, is essential or durable, or the user must respond before continuing.",
+      "useInstead": "inline feedback, persistent application content, or AlertDialog"
+    }
+  ],
+  "composition": [
+    "Place one Viewport under Provider for queued and announced toasts. Create imperative toasts with toast helpers or compose declarative Root with concise Title and optional Description; add Action, Cancel, or Close only when the toast needs those dismissing controls."
+  ],
+  "rules": [
+    {
+      "id": "toast-nonessential",
+      "level": "must",
+      "statement": "Do not place essential, sole, or response-required information only in Toast because it is transient and never moves focus on appearance."
+    },
+    {
+      "id": "toast-single-live-path",
+      "level": "must",
+      "statement": "Keep Viewport's persistent polite and assertive announcers as the sole live path; do not add role=status, role=alert, or aria-live to visible store-rendered Root cards."
+    },
+    {
+      "id": "toast-priority-content",
+      "level": "must",
+      "statement": "Choose toast type by announcement priority, keep Title and Description concise, and update content only when a meaningful new announcement is intended."
+    },
+    {
+      "id": "toast-timing-focus",
+      "level": "must",
+      "statement": "Preserve finite duration normalization, hover/focus/page-focus pause policies, labelled hotkey access, focused Escape dismissal, and focus restoration; never move focus merely because a toast appeared."
+    },
+    {
+      "id": "toast-actions-dismiss",
+      "level": "must",
+      "statement": "Use Action and Cancel only when running their callbacks should then dismiss; move async interactions that must remain open into separate persistent UI."
+    },
+    {
+      "id": "toast-dismissal-alternative",
+      "level": "must",
+      "statement": "Keep Close, Escape, timeout, or another obvious dismissal path available; directional swipe is optional enhancement and never the only mechanism."
+    },
+    {
+      "id": "toast-placement-owner",
+      "level": "should",
+      "statement": "Keep safe-area, persistent chrome, software-keyboard, and viewport positioning decisions in the styled or application layer while consuming Atom's logical position and state."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Toast for validation or confirmation, adding a second live region to visible cards, making swipe the only dismissal, or expecting an action to remain open during async work.",
+      "correction": "Use inline or blocking UI for those jobs, preserve the single announcer path and equivalent dismissal, and move persistent async interaction out of the toast."
+    }
+  ],
+  "validation": [
+    "Verify imperative create/update/dismiss and declarative Root, stable IDs, type role priority, duration and maxVisible normalization, queue order and stack anchoring, close inheritance, entry/exit lifecycle, forceMount, auto-close, hover/focus/page pause, and meaningful update announcements exactly once.",
+    "Verify labelled Viewport and hotkey, polite/assertive persistent announcers, no visible-card live region, focus-within pause, focused and viewport Escape, focus restoration, Action/Cancel/Close callbacks and dismissal, pointer swipe threshold/direction/cancel, non-swipe dismissal, custom renderToast, asChild viewport insertion, portal container, and logical positions."
+  ],
+  "related": [
+    "alert-dialog",
+    "field"
+  ]
+}
+```