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

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

@@ -0,0 +1,96 @@
+# Fieldset
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: fieldset
+
+# Fieldset agent guide
+
+## Purpose
+
+Group related form controls under native fieldset and legend semantics while sharing group state and validation behavior.
+
+## Use when
+
+- Multiple related controls need one group question or label, especially radio or checkbox choices.
+
+## Choose something else when
+
+- Only one control needs a label. Use Field.
+
+## Required composition
+
+- Compose Fieldset.Root -> Fieldset.Legend -> optional description/error -> Fields or grouped controls.
+
+## Rules
+
+- **MUST:** Group only controls that answer one related question.
+- **MUST:** Provide a meaningful legend unless an equivalent documented accessible naming strategy is required.
+
+## Common mistakes
+
+- **Avoid:** Using one Field to label a collection of controls. **Instead:** Use Fieldset for the group and Field for each independently labeled control.
+
+## Validation checklist
+
+- Inspect fieldset and legend semantics.
+- Confirm disabled, required, and invalid group state reaches descendants as documented.
+
+## Related guidance
+
+- `form`
+- `field`
+- `checkbox`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "fieldset",
+  "name": "Fieldset",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Group related form controls under native fieldset and legend semantics while sharing group state and validation behavior.",
+  "useWhen": [
+    "Multiple related controls need one group question or label, especially radio or checkbox choices."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only one control needs a label.",
+      "useInstead": "Field"
+    }
+  ],
+  "composition": [
+    "Compose Fieldset.Root -> Fieldset.Legend -> optional description/error -> Fields or grouped controls."
+  ],
+  "rules": [
+    {
+      "id": "fieldset-related-controls",
+      "level": "must",
+      "statement": "Group only controls that answer one related question."
+    },
+    {
+      "id": "fieldset-visible-legend",
+      "level": "must",
+      "statement": "Provide a meaningful legend unless an equivalent documented accessible naming strategy is required."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using one Field to label a collection of controls.",
+      "correction": "Use Fieldset for the group and Field for each independently labeled control."
+    }
+  ],
+  "validation": [
+    "Inspect fieldset and legend semantics.",
+    "Confirm disabled, required, and invalid group state reaches descendants as documented."
+  ],
+  "related": [
+    "form",
+    "field",
+    "checkbox"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/file-upload.txt

@@ -0,0 +1,120 @@
+# FileUpload
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: file-upload
+
+# FileUpload agent guide
+
+## Purpose
+
+Coordinate native file picking, optional drag and drop, client-side acceptance feedback, selected-file state, removal, Field validation, and multipart form participation.
+
+## Use when
+
+- Users choose local files and the experience needs a custom picker action, drop target, selected-file list, removal, or client-side rejection feedback.
+
+## Choose something else when
+
+- The browser's native file input is sufficient or the task only receives an already-hosted URL or remote asset reference. Use a native input type=file or the application-owned remote-source workflow.
+
+## Required composition
+
+- Compose Root with HiddenInput and an accessible Trigger for keyboard, touch, and pointer picker access. Add Dropzone as an enhancement, and use ItemGroup with Item, optional ItemName and ItemSize, and ItemDeleteTrigger when selected files must be reviewed or removed.
+
+## Rules
+
+- **MUST:** Render HiddenInput when Trigger, native picker, required validity, name, form, accept, or multiple file semantics are needed; keep it aligned with the visible Trigger.
+- **MUST:** Always provide a visible accessible Trigger for keyboard, touch, and single-pointer selection; Dropzone alone is not an equivalent accessible picker.
+- **MUST:** Use accept, maxFiles, maxSize, and validateFile only for immediate client feedback and validate file type, size, content, authorization, and storage policy again on the server.
+- **MUST:** Use files with onFilesChange for controlled state or defaultFiles for uncontrolled state, choose appendFiles intentionally in multiple mode, and expose rejected files as visible authored feedback.
+- **MUST:** Preserve file-only drag acceptance, accept/reject preview, nested enter/leave handling, disabled/read-only behavior, and document-drop protection unless the application intentionally owns outside drops.
+- **MUST:** Preserve HiddenInput name, form, multiple, selected FileList synchronization where supported, required validity, validation focus, Field relationships, deletion reset for same-file reselection, and uncontrolled form reset.
+
+## Common mistakes
+
+- **Avoid:** Using Dropzone as the only picker, treating accept or client validation as a security boundary, hiding rejection reasons, or forgetting that selecting the same removed file requires native input reset. **Instead:** Include HiddenInput and Trigger, validate again on the server, present rejection feedback, and use ItemDeleteTrigger or Root behavior to keep native selection synchronized.
+
+## Validation checklist
+
+- Verify picker opening by pointer, touch, Enter, and Space; controlled/uncontrolled files; single replace and multiple append/replace policy; accept extension/MIME/wildcard rules; max count and size; custom rejection; visible rejection feedback; disabled/read-only behavior; and same-file reselection after removal.
+- Verify drag enter/over/leave/drop accept and reject state, non-file drags, nested targets, outside document file-drop protection, HiddenInput name/form/required/multiple/FileList behavior, Field labels and errors, native/inline validation focus, reset, ItemGroup rendering, metadata, delete labels, refs, and asChild/render composition.
+
+## Related guidance
+
+- `input`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "file-upload",
+  "name": "FileUpload",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate native file picking, optional drag and drop, client-side acceptance feedback, selected-file state, removal, Field validation, and multipart form participation.",
+  "useWhen": [
+    "Users choose local files and the experience needs a custom picker action, drop target, selected-file list, removal, or client-side rejection feedback."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The browser's native file input is sufficient or the task only receives an already-hosted URL or remote asset reference.",
+      "useInstead": "a native input type=file or the application-owned remote-source workflow"
+    }
+  ],
+  "composition": [
+    "Compose Root with HiddenInput and an accessible Trigger for keyboard, touch, and pointer picker access. Add Dropzone as an enhancement, and use ItemGroup with Item, optional ItemName and ItemSize, and ItemDeleteTrigger when selected files must be reviewed or removed."
+  ],
+  "rules": [
+    {
+      "id": "file-upload-native-input",
+      "level": "must",
+      "statement": "Render HiddenInput when Trigger, native picker, required validity, name, form, accept, or multiple file semantics are needed; keep it aligned with the visible Trigger."
+    },
+    {
+      "id": "file-upload-access-path",
+      "level": "must",
+      "statement": "Always provide a visible accessible Trigger for keyboard, touch, and single-pointer selection; Dropzone alone is not an equivalent accessible picker."
+    },
+    {
+      "id": "file-upload-validation",
+      "level": "must",
+      "statement": "Use accept, maxFiles, maxSize, and validateFile only for immediate client feedback and validate file type, size, content, authorization, and storage policy again on the server."
+    },
+    {
+      "id": "file-upload-state",
+      "level": "must",
+      "statement": "Use files with onFilesChange for controlled state or defaultFiles for uncontrolled state, choose appendFiles intentionally in multiple mode, and expose rejected files as visible authored feedback."
+    },
+    {
+      "id": "file-upload-drop",
+      "level": "must",
+      "statement": "Preserve file-only drag acceptance, accept/reject preview, nested enter/leave handling, disabled/read-only behavior, and document-drop protection unless the application intentionally owns outside drops."
+    },
+    {
+      "id": "file-upload-form",
+      "level": "must",
+      "statement": "Preserve HiddenInput name, form, multiple, selected FileList synchronization where supported, required validity, validation focus, Field relationships, deletion reset for same-file reselection, and uncontrolled form reset."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Dropzone as the only picker, treating accept or client validation as a security boundary, hiding rejection reasons, or forgetting that selecting the same removed file requires native input reset.",
+      "correction": "Include HiddenInput and Trigger, validate again on the server, present rejection feedback, and use ItemDeleteTrigger or Root behavior to keep native selection synchronized."
+    }
+  ],
+  "validation": [
+    "Verify picker opening by pointer, touch, Enter, and Space; controlled/uncontrolled files; single replace and multiple append/replace policy; accept extension/MIME/wildcard rules; max count and size; custom rejection; visible rejection feedback; disabled/read-only behavior; and same-file reselection after removal.",
+    "Verify drag enter/over/leave/drop accept and reject state, non-file drags, nested targets, outside document file-drop protection, HiddenInput name/form/required/multiple/FileList behavior, Field labels and errors, native/inline validation focus, reset, ItemGroup rendering, metadata, delete labels, refs, and asChild/render composition."
+  ],
+  "related": [
+    "input",
+    "field",
+    "form"
+  ]
+}
+```

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

@@ -0,0 +1,98 @@
+# Form
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: form
+
+# Form agent guide
+
+## Purpose
+
+Provide the native form submission boundary and shared validation behavior for descendant fields and groups.
+
+## Use when
+
+- A set of controls submits related user input.
+
+## Choose something else when
+
+- Controls are unrelated or trigger immediate independent actions. Use Individual Field and Button compositions.
+
+## Required composition
+
+- Compose Form around Fieldset for related groups and Field around each single control; finish with a named submit Button.
+
+## Rules
+
+- **MUST:** Preserve native form submission and do not make click handling the only submit path.
+- **MUST:** Give submitted controls stable names.
+
+## Common mistakes
+
+- **Avoid:** Building a form-shaped div with click-only submission. **Instead:** Use Form and a submit Button so keyboard and platform behavior remain available.
+
+## Validation checklist
+
+- Submit with Enter where appropriate.
+- Inspect submitted names and values.
+- Verify invalid fields expose their relationships.
+
+## Related guidance
+
+- `field`
+- `fieldset`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "form",
+  "name": "Form",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide the native form submission boundary and shared validation behavior for descendant fields and groups.",
+  "useWhen": [
+    "A set of controls submits related user input."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Controls are unrelated or trigger immediate independent actions.",
+      "useInstead": "Individual Field and Button compositions"
+    }
+  ],
+  "composition": [
+    "Compose Form around Fieldset for related groups and Field around each single control; finish with a named submit Button."
+  ],
+  "rules": [
+    {
+      "id": "form-native-submit",
+      "level": "must",
+      "statement": "Preserve native form submission and do not make click handling the only submit path."
+    },
+    {
+      "id": "form-control-names",
+      "level": "must",
+      "statement": "Give submitted controls stable names."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building a form-shaped div with click-only submission.",
+      "correction": "Use Form and a submit Button so keyboard and platform behavior remain available."
+    }
+  ],
+  "validation": [
+    "Submit with Enter where appropriate.",
+    "Inspect submitted names and values.",
+    "Verify invalid fields expose their relationships."
+  ],
+  "related": [
+    "field",
+    "fieldset",
+    "button"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/hover-card.txt

@@ -0,0 +1,114 @@
+# HoverCard
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: hover-card
+
+# HoverCard agent guide
+
+## Purpose
+
+Reveal supplemental, nonessential preview content from mouse-capable hover or focus-visible interaction without creating popup semantics or replacing the trigger's native action.
+
+## Use when
+
+- A link or other focusable subject benefits from a richer passive preview that is supplemental, nonessential, and contains no required actions.
+
+## Choose something else when
+
+- The content is a brief text hint, contains interactive controls, must hold focus, or is essential on touch and other non-hover input. Use Tooltip, Popover, Dialog, or visible inline content.
+
+## Required composition
+
+- Compose Root with Trigger and Content; preserve the Trigger's native semantic element with asChild when it owns an action. Add Portal only when Content must leave its DOM location and Arrow only when the styled preview needs a pointer.
+
+## Rules
+
+- **MUST:** Keep all essential information and required actions available outside Content because touch does not open HoverCard and Content has no popup relationship.
+- **MUST:** Do not put buttons, links, inputs, or required interaction inside Content; use Popover for interactive floating content.
+- **MUST:** Preserve Trigger's native action and tab order through asChild, and do not add aria-expanded, aria-controls, or dialog semantics to this preview pattern.
+- **MUST:** Preserve mouse-capable hover, focus-visible opening, touch and compatibility-event suppression, delays, the safe pointer corridor, and top-layer Escape behavior.
+- **SHOULD:** Style from resolved side and measured available-size data rather than assuming the requested placement remains unchanged after collision handling.
+
+## Common mistakes
+
+- **Avoid:** Putting a profile action or essential fact only in HoverCard, expecting touch to open it, or adding popup ARIA relationships. **Instead:** Keep the preview passive and redundant, preserve the trigger action, and use Popover or visible content when users must interact or access the information.
+
+## Validation checklist
+
+- Verify controlled state, disabled state, mouse hover and focus-visible opening, ordinary focus behavior, delays, Trigger-to-Content pointer corridor, Escape, exit presence, and that touch taps and long presses preserve the native Trigger action without opening.
+- Verify no essential or interactive content is hidden in the preview, no popup ARIA is introduced, asChild semantics, portals, explicit and inherited direction, collision placement, available-size properties, and optional Arrow geometry.
+
+## Related guidance
+
+- `tooltip`
+- `popover`
+- `dialog`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "hover-card",
+  "name": "HoverCard",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Reveal supplemental, nonessential preview content from mouse-capable hover or focus-visible interaction without creating popup semantics or replacing the trigger's native action.",
+  "useWhen": [
+    "A link or other focusable subject benefits from a richer passive preview that is supplemental, nonessential, and contains no required actions."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is a brief text hint, contains interactive controls, must hold focus, or is essential on touch and other non-hover input.",
+      "useInstead": "Tooltip, Popover, Dialog, or visible inline content"
+    }
+  ],
+  "composition": [
+    "Compose Root with Trigger and Content; preserve the Trigger's native semantic element with asChild when it owns an action. Add Portal only when Content must leave its DOM location and Arrow only when the styled preview needs a pointer."
+  ],
+  "rules": [
+    {
+      "id": "hover-card-supplemental",
+      "level": "must",
+      "statement": "Keep all essential information and required actions available outside Content because touch does not open HoverCard and Content has no popup relationship."
+    },
+    {
+      "id": "hover-card-noninteractive",
+      "level": "must",
+      "statement": "Do not put buttons, links, inputs, or required interaction inside Content; use Popover for interactive floating content."
+    },
+    {
+      "id": "hover-card-trigger-native",
+      "level": "must",
+      "statement": "Preserve Trigger's native action and tab order through asChild, and do not add aria-expanded, aria-controls, or dialog semantics to this preview pattern."
+    },
+    {
+      "id": "hover-card-input-policy",
+      "level": "must",
+      "statement": "Preserve mouse-capable hover, focus-visible opening, touch and compatibility-event suppression, delays, the safe pointer corridor, and top-layer Escape behavior."
+    },
+    {
+      "id": "hover-card-positioning",
+      "level": "should",
+      "statement": "Style from resolved side and measured available-size data rather than assuming the requested placement remains unchanged after collision handling."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting a profile action or essential fact only in HoverCard, expecting touch to open it, or adding popup ARIA relationships.",
+      "correction": "Keep the preview passive and redundant, preserve the trigger action, and use Popover or visible content when users must interact or access the information."
+    }
+  ],
+  "validation": [
+    "Verify controlled state, disabled state, mouse hover and focus-visible opening, ordinary focus behavior, delays, Trigger-to-Content pointer corridor, Escape, exit presence, and that touch taps and long presses preserve the native Trigger action without opening.",
+    "Verify no essential or interactive content is hidden in the preview, no popup ARIA is introduced, asChild semantics, portals, explicit and inherited direction, collision placement, available-size properties, and optional Arrow geometry."
+  ],
+  "related": [
+    "tooltip",
+    "popover",
+    "dialog"
+  ]
+}
+```

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

@@ -0,0 +1,94 @@
+# Image
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: image
+
+# Image agent guide
+
+## Purpose
+
+Coordinate image loading, fallback visibility, and accessible native image semantics.
+
+## Use when
+
+- Media needs a fallback or loading-state composition that stays synchronized with the image.
+
+## Choose something else when
+
+- A native image is sufficient or a framework optimizer owns a required measured capability. Use a native img or a documented framework adapter.
+
+## Required composition
+
+- Compose Image.Content and Image.Fallback inside Image.Root; provide meaningful alt text or alt="" for decorative content.
+
+## Rules
+
+- **MUST:** Give every Content a correct alt value based on the image's purpose.
+- **MUST:** Do not let a visual fallback create a duplicate or misleading accessible name.
+
+## Common mistakes
+
+- **Avoid:** Using CSS background images for meaningful content or omitting alt because a fallback exists. **Instead:** Use Content with intentional alt text and treat Fallback as loading or error presentation.
+
+## Validation checklist
+
+- Verify loaded, loading, error, cached, and source-change states.
+- Confirm the accessible name remains correct in every state.
+
+## Related guidance
+
+- `avatar`
+- `aspect-ratio`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "image",
+  "name": "Image",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate image loading, fallback visibility, and accessible native image semantics.",
+  "useWhen": [
+    "Media needs a fallback or loading-state composition that stays synchronized with the image."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A native image is sufficient or a framework optimizer owns a required measured capability.",
+      "useInstead": "a native img or a documented framework adapter"
+    }
+  ],
+  "composition": [
+    "Compose Image.Content and Image.Fallback inside Image.Root; provide meaningful alt text or alt=\"\" for decorative content."
+  ],
+  "rules": [
+    {
+      "id": "image-alt",
+      "level": "must",
+      "statement": "Give every Content a correct alt value based on the image's purpose."
+    },
+    {
+      "id": "image-fallback-name",
+      "level": "must",
+      "statement": "Do not let a visual fallback create a duplicate or misleading accessible name."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using CSS background images for meaningful content or omitting alt because a fallback exists.",
+      "correction": "Use Content with intentional alt text and treat Fallback as loading or error presentation."
+    }
+  ],
+  "validation": [
+    "Verify loaded, loading, error, cached, and source-change states.",
+    "Confirm the accessible name remains correct in every state."
+  ],
+  "related": [
+    "avatar",
+    "aspect-ratio"
+  ]
+}
+```

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

@@ -0,0 +1,96 @@
+# Input
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: input
+
+# Input agent guide
+
+## Purpose
+
+Provide headless native single-line text entry that participates in Field relationships and controlled or uncontrolled value handling.
+
+## Use when
+
+- The user enters one line of text, email, search, URL, telephone, or another supported native input value.
+
+## Choose something else when
+
+- The value needs multiple lines. Use Textarea.
+
+## Required composition
+
+- Place Input.Root inside one Field.Root with Field.Label; add a stable name when it participates in submission.
+
+## Rules
+
+- **MUST:** Give every Input an accessible name, normally through Field.Label.
+- **SHOULD:** Choose the narrowest correct native type and autocomplete value.
+
+## Common mistakes
+
+- **Avoid:** Using placeholder text as the only label. **Instead:** Add a persistent Field.Label and keep placeholder text optional.
+
+## Validation checklist
+
+- Inspect name, type, autocomplete, label, and description relationships.
+- Test keyboard entry and browser autofill where relevant.
+
+## Related guidance
+
+- `field`
+- `form`
+- `textarea`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "input",
+  "name": "Input",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide headless native single-line text entry that participates in Field relationships and controlled or uncontrolled value handling.",
+  "useWhen": [
+    "The user enters one line of text, email, search, URL, telephone, or another supported native input value."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value needs multiple lines.",
+      "useInstead": "Textarea"
+    }
+  ],
+  "composition": [
+    "Place Input.Root inside one Field.Root with Field.Label; add a stable name when it participates in submission."
+  ],
+  "rules": [
+    {
+      "id": "input-labeled",
+      "level": "must",
+      "statement": "Give every Input an accessible name, normally through Field.Label."
+    },
+    {
+      "id": "input-native-type",
+      "level": "should",
+      "statement": "Choose the narrowest correct native type and autocomplete value."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using placeholder text as the only label.",
+      "correction": "Add a persistent Field.Label and keep placeholder text optional."
+    }
+  ],
+  "validation": [
+    "Inspect name, type, autocomplete, label, and description relationships.",
+    "Test keyboard entry and browser autofill where relevant."
+  ],
+  "related": [
+    "field",
+    "form",
+    "textarea"
+  ]
+}
+```