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

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

@@ -0,0 +1,138 @@
+# Tree
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: tree
+
+# Tree agent guide
+
+## Purpose
+
+Provide one-dimensional hierarchical navigation with tree semantics, active-descendant focus, controlled selection and expansion, typeahead, form state, and nested group relationships.
+
+## Use when
+
+- Users navigate and optionally select expandable parent-child items in one primary column, such as a file browser or category picker.
+
+## Choose something else when
+
+- Each hierarchical row has several navigable columns, or the sections contain general disclosure content rather than selectable items. Use TreeGrid or Accordion.
+- Items form a flat option collection without parent-child expansion. Use Listbox.
+
+## Required composition
+
+- Give Root an accessible name and deliberate selection, expansion, orientation, direction, and form state. Compose uniquely valued Item parts with ItemText for reliable naming and typeahead, mark only real parents expandable, and place each nested Group inside its parent Item.
+
+## Rules
+
+- **MUST:** Name Root and preserve tree, treeitem, and group relationships, automatic levels, ItemText labeling, and parent-child nesting.
+- **MUST:** Give every Item a stable unique value; align scalar or array selection with multiple; and keep selection and expandedValue controlled or uncontrolled without mixing ownership.
+- **MUST:** Keep DOM focus on Root and preserve active-descendant focus, visible-item Arrow movement, expand and collapse or parent movement, Home and End, typeahead, disabled skipping, loop policy, and RTL behavior.
+- **MUST:** Mark only actual parent Items expandable, keep collapsed descendants out of visible navigation, and ensure active state relocates to a visible ancestor or resets when controlled expansion hides it.
+- **MUST:** Preserve Field naming and descriptions, disabled, read-only, required, invalid, and named form submission; read-only may navigate but must not change selection or expansion through selection keys.
+- **MUST:** If a large tree is windowed, retain complete parent relationships and logical accessibility metadata and keep the active descendant and expansion target mounted; generic Virtualizer does not reconstruct tree semantics.
+
+## Common mistakes
+
+- **Avoid:** Building arbitrary disclosure sections as treeitems or marking leaf Items expandable merely to show an icon. **Instead:** Use Accordion for content sections and set expandable only when the Item owns a nested Group.
+- **Avoid:** Giving each Item a Tab stop, omitting ItemText for complex labels, or allowing duplicate values. **Instead:** Keep Root as the sole composite focus target, register reliable visible text, and use durable unique identities.
+
+## Validation checklist
+
+- Verify Root naming; tree, treeitem, and group relationships; automatic levels; ItemText naming; unique values; nested visibility; and form submission in the final DOM.
+- Exercise initial focus, LTR and RTL expansion and parent keys, orientation movement, Home and End, loop boundaries, typeahead cycling and prefixes, pointer selection, disabled Items, and scroll-to-nearest behavior.
+- Verify single and multiple controlled and uncontrolled selection, controlled expansion, collapse of the active branch, force-mounted hidden Groups, read-only and Field state, and asChild or render prop merging.
+- For windowed trees, verify every visible level and parent relationship is correct and aria-activedescendant never references an unmounted Item.
+
+## Related guidance
+
+- `tree-grid`
+- `accordion`
+- `listbox`
+- `collection`
+- `virtualizer`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "tree",
+  "name": "Tree",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide one-dimensional hierarchical navigation with tree semantics, active-descendant focus, controlled selection and expansion, typeahead, form state, and nested group relationships.",
+  "useWhen": [
+    "Users navigate and optionally select expandable parent-child items in one primary column, such as a file browser or category picker."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Each hierarchical row has several navigable columns, or the sections contain general disclosure content rather than selectable items.",
+      "useInstead": "TreeGrid or Accordion"
+    },
+    {
+      "condition": "Items form a flat option collection without parent-child expansion.",
+      "useInstead": "Listbox"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and deliberate selection, expansion, orientation, direction, and form state. Compose uniquely valued Item parts with ItemText for reliable naming and typeahead, mark only real parents expandable, and place each nested Group inside its parent Item."
+  ],
+  "rules": [
+    {
+      "id": "tree-name-anatomy",
+      "level": "must",
+      "statement": "Name Root and preserve tree, treeitem, and group relationships, automatic levels, ItemText labeling, and parent-child nesting."
+    },
+    {
+      "id": "tree-identity-state",
+      "level": "must",
+      "statement": "Give every Item a stable unique value; align scalar or array selection with multiple; and keep selection and expandedValue controlled or uncontrolled without mixing ownership."
+    },
+    {
+      "id": "tree-focus-keyboard",
+      "level": "must",
+      "statement": "Keep DOM focus on Root and preserve active-descendant focus, visible-item Arrow movement, expand and collapse or parent movement, Home and End, typeahead, disabled skipping, loop policy, and RTL behavior."
+    },
+    {
+      "id": "tree-visible-state",
+      "level": "must",
+      "statement": "Mark only actual parent Items expandable, keep collapsed descendants out of visible navigation, and ensure active state relocates to a visible ancestor or resets when controlled expansion hides it."
+    },
+    {
+      "id": "tree-form-state",
+      "level": "must",
+      "statement": "Preserve Field naming and descriptions, disabled, read-only, required, invalid, and named form submission; read-only may navigate but must not change selection or expansion through selection keys."
+    },
+    {
+      "id": "tree-virtualization",
+      "level": "must",
+      "statement": "If a large tree is windowed, retain complete parent relationships and logical accessibility metadata and keep the active descendant and expansion target mounted; generic Virtualizer does not reconstruct tree semantics."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building arbitrary disclosure sections as treeitems or marking leaf Items expandable merely to show an icon.",
+      "correction": "Use Accordion for content sections and set expandable only when the Item owns a nested Group."
+    },
+    {
+      "mistake": "Giving each Item a Tab stop, omitting ItemText for complex labels, or allowing duplicate values.",
+      "correction": "Keep Root as the sole composite focus target, register reliable visible text, and use durable unique identities."
+    }
+  ],
+  "validation": [
+    "Verify Root naming; tree, treeitem, and group relationships; automatic levels; ItemText naming; unique values; nested visibility; and form submission in the final DOM.",
+    "Exercise initial focus, LTR and RTL expansion and parent keys, orientation movement, Home and End, loop boundaries, typeahead cycling and prefixes, pointer selection, disabled Items, and scroll-to-nearest behavior.",
+    "Verify single and multiple controlled and uncontrolled selection, controlled expansion, collapse of the active branch, force-mounted hidden Groups, read-only and Field state, and asChild or render prop merging.",
+    "For windowed trees, verify every visible level and parent relationship is correct and aria-activedescendant never references an unmounted Item."
+  ],
+  "related": [
+    "tree-grid",
+    "accordion",
+    "listbox",
+    "collection",
+    "virtualizer"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/visually-hidden.txt

@@ -0,0 +1,119 @@
+# VisuallyHidden
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: visually-hidden
+
+# VisuallyHidden agent guide
+
+## Purpose
+
+Keep authored text or semantic content available to assistive technology while removing it from visual layout through an authoritative hiding contract.
+
+## Use when
+
+- Assistive technology needs words that sighted users already infer from visible context, such as the name of an icon-only control or extra link context.
+
+## Choose something else when
+
+- The explanation benefits everyone, content is decorative and should be hidden from assistive technology, or interactive content would become invisible to sighted keyboard users. Use visible text, aria-hidden, or a visibly focusable interaction.
+
+## Required composition
+
+- Place concise meaningful content inside Root within the element whose accessible name or reading context it should extend. Hide decorative visual siblings with aria-hidden when needed, and keep any focusable control itself visible rather than wrapping it in VisuallyHidden.
+
+## Rules
+
+- **MUST:** Use Root only for content that should remain in the accessibility tree while being visually absent; it does not hide content from assistive technology.
+- **MUST:** Prefer visible text whenever the name, instruction, status, or explanation also benefits sighted users.
+- **MUST:** Do not visually hide an interactive element that can receive keyboard focus unless it has a deliberate visible-on-focus pattern owned elsewhere.
+- **MUST:** Author concise text in the correct naming or reading-order context and verify it does not duplicate an existing accessible name.
+- **MUST:** Do not override Atom's hiding geometry; consumer styles merge first and the exported visuallyHiddenStyle contract remains authoritative.
+
+## Common mistakes
+
+- **Avoid:** Using VisuallyHidden to hide a decorative icon from screen readers or to conceal required instructions from sighted users. **Instead:** Use aria-hidden for decoration and keep broadly useful instructions visible.
+- **Avoid:** Wrapping an icon-only Button itself in VisuallyHidden, creating an invisible focus target. **Instead:** Keep the Button visible and place VisuallyHidden text inside it as its accessible label.
+
+## Validation checklist
+
+- Inspect the accessibility tree and computed accessible name or description to confirm hidden text is present once, in the intended reading order, without duplicate wording.
+- Verify no focusable element becomes visually absent, visible text remains available where broadly useful, and decorative content uses aria-hidden instead.
+- Verify authoritative hiding styles survive consumer style, asChild, and render composition and that the final element adds no unintended role or ARIA attributes.
+
+## Related guidance
+
+- `label`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "visually-hidden",
+  "name": "VisuallyHidden",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Keep authored text or semantic content available to assistive technology while removing it from visual layout through an authoritative hiding contract.",
+  "useWhen": [
+    "Assistive technology needs words that sighted users already infer from visible context, such as the name of an icon-only control or extra link context."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The explanation benefits everyone, content is decorative and should be hidden from assistive technology, or interactive content would become invisible to sighted keyboard users.",
+      "useInstead": "visible text, aria-hidden, or a visibly focusable interaction"
+    }
+  ],
+  "composition": [
+    "Place concise meaningful content inside Root within the element whose accessible name or reading context it should extend. Hide decorative visual siblings with aria-hidden when needed, and keep any focusable control itself visible rather than wrapping it in VisuallyHidden."
+  ],
+  "rules": [
+    {
+      "id": "visually-hidden-at-only",
+      "level": "must",
+      "statement": "Use Root only for content that should remain in the accessibility tree while being visually absent; it does not hide content from assistive technology."
+    },
+    {
+      "id": "visually-hidden-visible-first",
+      "level": "must",
+      "statement": "Prefer visible text whenever the name, instruction, status, or explanation also benefits sighted users."
+    },
+    {
+      "id": "visually-hidden-no-focus-trap",
+      "level": "must",
+      "statement": "Do not visually hide an interactive element that can receive keyboard focus unless it has a deliberate visible-on-focus pattern owned elsewhere."
+    },
+    {
+      "id": "visually-hidden-context",
+      "level": "must",
+      "statement": "Author concise text in the correct naming or reading-order context and verify it does not duplicate an existing accessible name."
+    },
+    {
+      "id": "visually-hidden-style",
+      "level": "must",
+      "statement": "Do not override Atom's hiding geometry; consumer styles merge first and the exported visuallyHiddenStyle contract remains authoritative."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using VisuallyHidden to hide a decorative icon from screen readers or to conceal required instructions from sighted users.",
+      "correction": "Use aria-hidden for decoration and keep broadly useful instructions visible."
+    },
+    {
+      "mistake": "Wrapping an icon-only Button itself in VisuallyHidden, creating an invisible focus target.",
+      "correction": "Keep the Button visible and place VisuallyHidden text inside it as its accessible label."
+    }
+  ],
+  "validation": [
+    "Inspect the accessibility tree and computed accessible name or description to confirm hidden text is present once, in the intended reading order, without duplicate wording.",
+    "Verify no focusable element becomes visually absent, visible text remains available where broadly useful, and decorative content uses aria-hidden instead.",
+    "Verify authoritative hiding styles survive consumer style, asChild, and render composition and that the final element adds no unintended role or ARIA attributes."
+  ],
+  "related": [
+    "label",
+    "button"
+  ]
+}
+```

package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt

@@ -0,0 +1,55 @@
+# Public document: guides/agent-knowledge
+
+Source: @flowstack-ui/atom@0.24.0
+
+# Agent Knowledge
+
+Atom ships public component and cross-component guidance for coding agents
+alongside its runtime artifacts. Component guidance explains local selection,
+required composition, accessibility rules, recurring mistakes, and
+validation. Package guides first explain layer selection and behavior
+composition. Neither artifact adds runtime behavior or a dependency.
+
+Use `@flowstack-ui/atom/agents/manifest.json` to discover guidance. Its
+separate `guides` and `components` collections point to machine-readable JSON
+and human-readable Markdown. Read `layer-selection` and
+`behavior-composition` before choosing individual primitives, for example:
+
+```text
+@flowstack-ui/atom/agents/field.json
+@flowstack-ui/atom/agents/field.md
+@flowstack-ui/atom/agents/layer-selection.json
+@flowstack-ui/atom/agents/behavior-composition.md
+```
+
+The manifest links `@flowstack-ui/atom/agents/coverage.json`, a deterministic
+`flowstack.agent-coverage.v1` report derived from the package exports, public
+TypeScript symbols, documented primitive owners, and the checked-in catalog.
+It distinguishes component owners from compound parts, root aliases,
+utilities, metadata, and intentional native/application destinations. This
+prevents utility subpaths from being mistaken for missing components and
+prevents a new public surface from escaping classification.
+
+The source pair lives beside the primitive it describes. `agent.json` is the
+structured authority and `agent.md` is generated from it. Component source,
+types, public documentation, and tests remain authoritative when a guide is
+incomplete.
+
+Package-level guide sources live under `agents/guides/`. They use
+`flowstack.agent-guide.v1`; component sources continue to use
+`flowstack.agent-component.v1`. Manifest `guides` is additive, so consumers
+that already read only `components` remain compatible.
+
+`npm run agents:build` and `npm run agents:check` are strict closure gates.
+They require every public component owner to have a valid source pair and
+manifest entry, and check mode compares every generated artifact while
+rejecting stale or extra output. Builds, prepublication, packed-package checks,
+and installed-consumer checks all require complete coverage with zero
+failures.
+
+When a finished application has selected `@flowstack-ui/brick`, consume Brick
+instead of importing Atom directly. Atom's guides are behavior authority for
+primitive authors and for diagnosing a genuine Brick-to-Atom gap.
+
+Agent Knowledge is public usage guidance. It does not contain private prompts,
+ranking policy, customer information, or application workflows.

package/public/packages/atom/0.24.0/docs/guides/getting-started.txt

@@ -0,0 +1,65 @@
+# Public document: guides/getting-started
+
+Source: @flowstack-ui/atom@0.24.0
+
+# Getting Started
+
+Atom UI is a headless React primitive package. It provides accessible behavior
+and semantic structure without visual styling.
+
+Install Atom in an existing React application:
+
+```bash
+npm install @flowstack-ui/atom
+```
+
+React and React DOM 18 or newer are peer dependencies and must be provided by
+the consuming application. Atom installs its Floating UI runtime dependency
+automatically.
+
+## Usage
+
+Prefer namespace imports:
+
+```tsx
+import { Dialog, Field, Input } from "@flowstack-ui/atom";
+
+export function Example() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger>Open</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay />
+        <Dialog.Content>
+          <Dialog.Title>Profile</Dialog.Title>
+          <Field.Root id="email" required>
+            <Field.Label>Email</Field.Label>
+            <Input.Root name="email" type="email" />
+          </Field.Root>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+Subpath imports are supported:
+
+```tsx
+import { Dialog } from "@flowstack-ui/atom/dialog";
+import { Input } from "@flowstack-ui/atom/input";
+```
+
+## Styling
+
+Atom does not ship CSS. Style primitives through native selectors,
+`data-slot`, and behavior state attributes.
+
+```css
+[data-slot="button"][data-state="pressed"] {
+  opacity: 0.85;
+}
+```
+
+Styled packages should compose Atom primitives instead of reimplementing ARIA,
+keyboard, focus, and state behavior.

package/public/packages/atom/0.24.0/docs/guides/imports.txt

@@ -0,0 +1,26 @@
+# Public document: guides/imports
+
+Source: @flowstack-ui/atom@0.24.0
+
+# Imports
+
+Use the main namespace import for convenient access to several primitives:
+
+```tsx
+import { Input, Dialog, MultiSelect } from "@flowstack-ui/atom";
+```
+
+Subpath imports are also public and stable:
+
+```tsx
+import { Input } from "@flowstack-ui/atom/input";
+import { Dialog } from "@flowstack-ui/atom/dialog";
+import { Link } from "@flowstack-ui/atom/link";
+import { Clipboard } from "@flowstack-ui/atom/clipboard";
+import { Carousel } from "@flowstack-ui/atom/carousel";
+import { MultiSelect } from "@flowstack-ui/atom/multi-select";
+```
+
+Use the main package import when teaching component anatomy. Use subpaths when a
+project wants explicit package boundaries per primitive or when a bundler policy
+requires focused entrypoints.

package/public/packages/atom/0.24.0/docs/guides/public-api.txt

@@ -0,0 +1,100 @@
+# Public document: guides/public-api
+
+Source: @flowstack-ui/atom@0.24.0
+
+# Public API
+
+Atom UI exposes three public API layers.
+
+## Namespace Exports
+
+Namespace exports are the stable API for application and styled-layer usage.
+
+```tsx
+import { Select } from "@flowstack-ui/atom";
+
+<Select.Root>
+  <Select.Trigger />
+  <Select.Content />
+</Select.Root>;
+```
+
+## Subpath Exports
+
+Subpaths are stable focused entrypoints.
+
+```tsx
+import { Select } from "@flowstack-ui/atom/select";
+import { Link } from "@flowstack-ui/atom/link";
+import { Clipboard } from "@flowstack-ui/atom/clipboard";
+import { Carousel } from "@flowstack-ui/atom/carousel";
+import { Image } from "@flowstack-ui/atom/image";
+import { useControllableState } from "@flowstack-ui/atom/hooks";
+```
+
+Every supported subpath is declared by the package and provides JavaScript plus
+TypeScript declarations.
+
+## Direct Part Exports
+
+Direct exports are available from component subpaths for migration and
+advanced composition.
+
+```tsx
+import { SelectRoot, SelectTrigger } from "@flowstack-ui/atom/select";
+```
+
+Prefer namespace usage for new code unless a direct part export improves local
+readability. Shared primitives retain their shared direct names. For example,
+`Dialog.Root` is directly exported as `ModalRoot` because Dialog composes the
+shared Modal root behavior. Check the component subpath declarations rather
+than assuming every direct export is named by concatenating its namespace and
+part names.
+
+## Non-API Files
+
+The following are not public package API:
+
+- files under `src/primitives/**`
+- files under `src/utils/**`, except `Portal` through `@flowstack-ui/atom/portal`
+- tests
+- internal helper functions that are not exported from a public subpath
+
+These implementation files may change between releases even when the public
+entrypoints remain compatible.
+
+## Composition
+
+Components that document `asChild` clone their only child and merge Atom props
+onto it. Components that document `render` can replace the default element with
+an intrinsic tag, element, or render callback. Both paths preserve forwarded
+refs, native props, and Atom-owned behavior.
+
+Choose a composed element whose native semantics match the interaction. For
+example, a Button link composition should expose its destination through an
+`href` prop so Atom preserves link semantics instead of adding button behavior:
+
+```tsx
+import { Button } from "@flowstack-ui/atom";
+
+<Button.Root asChild>
+  <a href="/settings">Settings</a>
+</Button.Root>;
+```
+
+The same rule applies to custom link adapters and `render` elements: keep
+`href` visible on the element passed to Button. This lets Button identify link
+semantics and replace `href`, `target`, and `rel` with `null` while disabled or
+loading. Native anchors and permissive adapters render without those
+attributes.
+
+A router component that requires `href` to remain a string is not safe for
+direct inactive composition. Use a render adapter that bypasses the router
+component and returns a destination-free anchor when `aria-disabled` is true.
+Atom does not ship router-specific bindings, inspect framework-specific
+navigation props, or retain a live destination on an inactive link.
+
+The generic `Link.Root` is narrower than Button link mode. Its default render
+requires `href`, while `render` or `asChild` may supply a router adapter that
+owns the final destination. Link does not add action, loading, disabled, or
+router-provider behavior and remains server-safe.