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

package/public/packages/atom/0.24.0/components/toggle-group.txt

@@ -0,0 +1,118 @@
+# ToggleGroup
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: toggle-group
+
+# ToggleGroup agent guide
+
+## Purpose
+
+Coordinate related toggle-button commands with single or multiple pressed selection and one orientation-aware roving focus stop.
+
+## Use when
+
+- Several related commands, such as alignment or formatting controls, should expose pressed state and navigate as one keyboard group.
+
+## Choose something else when
+
+- The controls are unrelated, represent form answers, or turn settings on and off immediately. Use individual Toggle controls, RadioGroup or CheckboxGroup, or Switch.
+
+## Required composition
+
+- Give Root an accessible group name, choose type=single or type=multiple, and compose uniquely valued Item parts with visible text or accessible labels.
+
+## Rules
+
+- **MUST:** Give Root a concise accessible name and every icon-only Item its own accessible command name.
+- **MUST:** Choose single when at most one command may be pressed and multiple for independent pressed commands; match controlled value and defaultValue shapes to that type.
+- **MUST:** Provide stable unique Item values and route controlled updates through onValueChange.
+- **MUST:** Preserve one roving Tab stop, disabled-item skipping, DOM-order registration, looping policy, orientation-specific Arrow keys, Home/End, and horizontal RTL mirroring.
+- **MUST:** Preserve each Item's button and aria-pressed behavior and Root's group behavior when using asChild or render.
+
+## Common mistakes
+
+- **Avoid:** Using ToggleGroup for radio form answers, mixing string and array controlled values with the wrong type, or giving every Item a Tab stop. **Instead:** Choose the correct semantic group, keep value shape aligned to type, and retain the owned roving-focus model.
+
+## Validation checklist
+
+- Verify Root and Item names, single and multiple controlled and uncontrolled state, unique values, pressed semantics, disabled Root and Items, pointer, Enter, Space, and selection callbacks.
+- Verify one roving Tab stop when selected and unselected, DOM-order changes, Arrow navigation by orientation, Home/End, loop boundaries, horizontal LTR/RTL, and native, asChild, and render composition.
+
+## Related guidance
+
+- `toggle`
+- `radio-group`
+- `checkbox-group`
+- `switch`
+- `toolbar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toggle-group",
+  "name": "ToggleGroup",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate related toggle-button commands with single or multiple pressed selection and one orientation-aware roving focus stop.",
+  "useWhen": [
+    "Several related commands, such as alignment or formatting controls, should expose pressed state and navigate as one keyboard group."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The controls are unrelated, represent form answers, or turn settings on and off immediately.",
+      "useInstead": "individual Toggle controls, RadioGroup or CheckboxGroup, or Switch"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible group name, choose type=single or type=multiple, and compose uniquely valued Item parts with visible text or accessible labels."
+  ],
+  "rules": [
+    {
+      "id": "toggle-group-name",
+      "level": "must",
+      "statement": "Give Root a concise accessible name and every icon-only Item its own accessible command name."
+    },
+    {
+      "id": "toggle-group-type",
+      "level": "must",
+      "statement": "Choose single when at most one command may be pressed and multiple for independent pressed commands; match controlled value and defaultValue shapes to that type."
+    },
+    {
+      "id": "toggle-group-values",
+      "level": "must",
+      "statement": "Provide stable unique Item values and route controlled updates through onValueChange."
+    },
+    {
+      "id": "toggle-group-roving",
+      "level": "must",
+      "statement": "Preserve one roving Tab stop, disabled-item skipping, DOM-order registration, looping policy, orientation-specific Arrow keys, Home/End, and horizontal RTL mirroring."
+    },
+    {
+      "id": "toggle-group-composition",
+      "level": "must",
+      "statement": "Preserve each Item's button and aria-pressed behavior and Root's group behavior when using asChild or render."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ToggleGroup for radio form answers, mixing string and array controlled values with the wrong type, or giving every Item a Tab stop.",
+      "correction": "Choose the correct semantic group, keep value shape aligned to type, and retain the owned roving-focus model."
+    }
+  ],
+  "validation": [
+    "Verify Root and Item names, single and multiple controlled and uncontrolled state, unique values, pressed semantics, disabled Root and Items, pointer, Enter, Space, and selection callbacks.",
+    "Verify one roving Tab stop when selected and unselected, DOM-order changes, Arrow navigation by orientation, Home/End, loop boundaries, horizontal LTR/RTL, and native, asChild, and render composition."
+  ],
+  "related": [
+    "toggle",
+    "radio-group",
+    "checkbox-group",
+    "switch",
+    "toolbar"
+  ]
+}
+```

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

@@ -0,0 +1,110 @@
+# Toggle
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: toggle
+
+# Toggle agent guide
+
+## Purpose
+
+Represent one command whose pressed state remains on or off with toggle-button semantics and controlled or uncontrolled state.
+
+## Use when
+
+- One command such as bold, pin, or favorite remains pressed until the user operates it again.
+
+## Choose something else when
+
+- The control changes an immediate setting, submits a form choice, or belongs to a related keyboard-navigable set of pressed controls. Use Switch, Checkbox, or ToggleGroup.
+
+## Required composition
+
+- Render Root with visible command text or an accessible label; use asChild or render only when a custom element must preserve the owned button and keyboard contract.
+
+## Rules
+
+- **MUST:** Give Root a complete accessible name, especially when its visible content is only an icon.
+- **MUST:** Use pressed with onPressedChange for controlled state or defaultPressed for uncontrolled state and preserve aria-pressed rather than inventing checkbox or switch semantics.
+- **MUST:** Use Toggle for persistent command state, not for an immediate setting or a form answer.
+- **MUST:** Preserve native button behavior or Atom's role, tab stop, Enter, Space, disabled, props, handlers, and refs when composing a non-native element.
+
+## Common mistakes
+
+- **Avoid:** Using Toggle for a setting or form value, changing its meaning between pressed states, or replacing Atom keyboard handlers in asChild composition. **Instead:** Keep one stable command label and aria-pressed state, choose Switch or Checkbox for other semantics, and merge the owned behavior.
+
+## Validation checklist
+
+- Verify accessible name, controlled and uncontrolled pressed state, aria-pressed and data state, pointer, Enter, and Space activation, disabled behavior, consumer handler prevention, and ref/native-prop forwarding.
+- Verify native button, asChild, and render paths keep one element with correct button semantics, tab order, children, and disabled exposure.
+
+## Related guidance
+
+- `toggle-group`
+- `switch`
+- `checkbox`
+- `button`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toggle",
+  "name": "Toggle",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Represent one command whose pressed state remains on or off with toggle-button semantics and controlled or uncontrolled state.",
+  "useWhen": [
+    "One command such as bold, pin, or favorite remains pressed until the user operates it again."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The control changes an immediate setting, submits a form choice, or belongs to a related keyboard-navigable set of pressed controls.",
+      "useInstead": "Switch, Checkbox, or ToggleGroup"
+    }
+  ],
+  "composition": [
+    "Render Root with visible command text or an accessible label; use asChild or render only when a custom element must preserve the owned button and keyboard contract."
+  ],
+  "rules": [
+    {
+      "id": "toggle-name",
+      "level": "must",
+      "statement": "Give Root a complete accessible name, especially when its visible content is only an icon."
+    },
+    {
+      "id": "toggle-state",
+      "level": "must",
+      "statement": "Use pressed with onPressedChange for controlled state or defaultPressed for uncontrolled state and preserve aria-pressed rather than inventing checkbox or switch semantics."
+    },
+    {
+      "id": "toggle-command",
+      "level": "must",
+      "statement": "Use Toggle for persistent command state, not for an immediate setting or a form answer."
+    },
+    {
+      "id": "toggle-composition",
+      "level": "must",
+      "statement": "Preserve native button behavior or Atom's role, tab stop, Enter, Space, disabled, props, handlers, and refs when composing a non-native element."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Toggle for a setting or form value, changing its meaning between pressed states, or replacing Atom keyboard handlers in asChild composition.",
+      "correction": "Keep one stable command label and aria-pressed state, choose Switch or Checkbox for other semantics, and merge the owned behavior."
+    }
+  ],
+  "validation": [
+    "Verify accessible name, controlled and uncontrolled pressed state, aria-pressed and data state, pointer, Enter, and Space activation, disabled behavior, consumer handler prevention, and ref/native-prop forwarding.",
+    "Verify native button, asChild, and render paths keep one element with correct button semantics, tab order, children, and disabled exposure."
+  ],
+  "related": [
+    "toggle-group",
+    "switch",
+    "checkbox",
+    "button"
+  ]
+}
+```

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

@@ -0,0 +1,98 @@
+# Toolbar
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: toolbar
+
+# Toolbar agent guide
+
+## Purpose
+
+Group related commands in one ARIA toolbar with orientation-aware roving keyboard focus.
+
+## Use when
+
+- A compact row or column of related application controls should behave as one keyboard group.
+
+## Choose something else when
+
+- The items navigate among pages or are unrelated standalone actions. Use NavigationMenu, NavList, or separate Buttons.
+
+## Required composition
+
+- Compose Button, Link, Separator, and ToggleGroup/ToggleItem parts inside a named Root; keep all toolbar items in logical DOM order.
+
+## Rules
+
+- **MUST:** Give the toolbar and icon-only controls useful accessible names.
+- **MUST:** Let Toolbar own item registration and arrow-key focus rather than adding competing tabIndex or key handlers.
+
+## Common mistakes
+
+- **Avoid:** Using AppBar.Toolbar as an ARIA toolbar or nesting a second roving-focus implementation. **Instead:** Compose Toolbar.Root inside AppBar when grouped controls need toolbar behavior.
+
+## Validation checklist
+
+- Test orientation, arrows, Home/End if supported, disabled items, toggle state, links, Tab entry/exit, and RTL.
+- Confirm separators and controls expose correct semantics.
+
+## Related guidance
+
+- `app-bar`
+- `button`
+- `link`
+- `toggle-group`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toolbar",
+  "name": "Toolbar",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Group related commands in one ARIA toolbar with orientation-aware roving keyboard focus.",
+  "useWhen": [
+    "A compact row or column of related application controls should behave as one keyboard group."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The items navigate among pages or are unrelated standalone actions.",
+      "useInstead": "NavigationMenu, NavList, or separate Buttons"
+    }
+  ],
+  "composition": [
+    "Compose Button, Link, Separator, and ToggleGroup/ToggleItem parts inside a named Root; keep all toolbar items in logical DOM order."
+  ],
+  "rules": [
+    {
+      "id": "toolbar-name",
+      "level": "must",
+      "statement": "Give the toolbar and icon-only controls useful accessible names."
+    },
+    {
+      "id": "toolbar-roving-focus",
+      "level": "must",
+      "statement": "Let Toolbar own item registration and arrow-key focus rather than adding competing tabIndex or key handlers."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AppBar.Toolbar as an ARIA toolbar or nesting a second roving-focus implementation.",
+      "correction": "Compose Toolbar.Root inside AppBar when grouped controls need toolbar behavior."
+    }
+  ],
+  "validation": [
+    "Test orientation, arrows, Home/End if supported, disabled items, toggle state, links, Tab entry/exit, and RTL.",
+    "Confirm separators and controls expose correct semantics."
+  ],
+  "related": [
+    "app-bar",
+    "button",
+    "link",
+    "toggle-group"
+  ]
+}
+```

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

@@ -0,0 +1,112 @@
+# Tooltip
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: tooltip
+
+# Tooltip agent guide
+
+## Purpose
+
+Provide a short supplemental text description on hover, focus-visible interaction, and stationary touch long press with an owned aria-describedby relationship.
+
+## Use when
+
+- A control, especially an unfamiliar icon, needs a brief non-interactive hint in addition to its complete accessible name.
+
+## Choose something else when
+
+- The information is important enough to remain visible, is a richer passive preview, or contains links, buttons, inputs, or other interaction. Use visible text, HoverCard, or Popover.
+
+## Required composition
+
+- Compose Root with Trigger and Content; add Provider when descendant tooltips should share timing, Portal only when Content must leave its DOM location, and Arrow only when the styled hint needs a pointer. Plain and rich Content may differ in text structure, but both remain non-interactive tooltips.
+
+## Rules
+
+- **MUST:** Give Trigger a complete accessible name independently; Tooltip supplies only a supplemental aria-describedby description while open.
+- **MUST:** Keep both plain and rich Content free of links, buttons, inputs, and other focusable controls; use Popover for interaction.
+- **SHOULD:** Keep plain Content to a short hint and use rich only for concise non-interactive title and supporting text; render important information visibly.
+- **MUST:** Preserve hover, focus-visible, Escape, shared delay, and stationary 700 ms touch long-press behavior, including movement, scroll, second-touch, cancellation, disabled, unmount, compatibility-event, and finite dismissal handling.
+- **MUST:** When Trigger uses asChild or render, preserve its native semantics, Atom handlers and refs, and the generated description relationship.
+
+## Common mistakes
+
+- **Avoid:** Using Tooltip as the control's accessible name, placing interactive content in the rich variant, hiding essential instructions only on hover, or implementing a second touch long-press timer. **Instead:** Name Trigger independently, keep Content supplemental and non-interactive, show essential information visibly, and rely on Tooltip's owned input contract.
+
+## Validation checklist
+
+- Verify Trigger's independent name, role=tooltip Content, aria-describedby only while open, controlled and disabled state, provider and local delays, pointer hover, focus-visible opening, pointer transfer into Content, focus leave, top-layer Escape, and exit presence.
+- Verify stationary touch long press, early release, movement tolerance, scrolling, outside touch, second touch, touchcancel, compatibility events, disabled changes, unmount cleanup, plain and rich release-time dismissal, portals, direction, collision placement, and optional Arrow geometry.
+
+## Related guidance
+
+- `hover-card`
+- `popover`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "tooltip",
+  "name": "Tooltip",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide a short supplemental text description on hover, focus-visible interaction, and stationary touch long press with an owned aria-describedby relationship.",
+  "useWhen": [
+    "A control, especially an unfamiliar icon, needs a brief non-interactive hint in addition to its complete accessible name."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The information is important enough to remain visible, is a richer passive preview, or contains links, buttons, inputs, or other interaction.",
+      "useInstead": "visible text, HoverCard, or Popover"
+    }
+  ],
+  "composition": [
+    "Compose Root with Trigger and Content; add Provider when descendant tooltips should share timing, Portal only when Content must leave its DOM location, and Arrow only when the styled hint needs a pointer. Plain and rich Content may differ in text structure, but both remain non-interactive tooltips."
+  ],
+  "rules": [
+    {
+      "id": "tooltip-trigger-name",
+      "level": "must",
+      "statement": "Give Trigger a complete accessible name independently; Tooltip supplies only a supplemental aria-describedby description while open."
+    },
+    {
+      "id": "tooltip-noninteractive",
+      "level": "must",
+      "statement": "Keep both plain and rich Content free of links, buttons, inputs, and other focusable controls; use Popover for interaction."
+    },
+    {
+      "id": "tooltip-brief-content",
+      "level": "should",
+      "statement": "Keep plain Content to a short hint and use rich only for concise non-interactive title and supporting text; render important information visibly."
+    },
+    {
+      "id": "tooltip-owned-input",
+      "level": "must",
+      "statement": "Preserve hover, focus-visible, Escape, shared delay, and stationary 700 ms touch long-press behavior, including movement, scroll, second-touch, cancellation, disabled, unmount, compatibility-event, and finite dismissal handling."
+    },
+    {
+      "id": "tooltip-composition",
+      "level": "must",
+      "statement": "When Trigger uses asChild or render, preserve its native semantics, Atom handlers and refs, and the generated description relationship."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Tooltip as the control's accessible name, placing interactive content in the rich variant, hiding essential instructions only on hover, or implementing a second touch long-press timer.",
+      "correction": "Name Trigger independently, keep Content supplemental and non-interactive, show essential information visibly, and rely on Tooltip's owned input contract."
+    }
+  ],
+  "validation": [
+    "Verify Trigger's independent name, role=tooltip Content, aria-describedby only while open, controlled and disabled state, provider and local delays, pointer hover, focus-visible opening, pointer transfer into Content, focus leave, top-layer Escape, and exit presence.",
+    "Verify stationary touch long press, early release, movement tolerance, scrolling, outside touch, second touch, touchcancel, compatibility events, disabled changes, unmount cleanup, plain and rich release-time dismissal, portals, direction, collision placement, and optional Arrow geometry."
+  ],
+  "related": [
+    "hover-card",
+    "popover"
+  ]
+}
+```

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

@@ -0,0 +1,138 @@
+# TreeGrid
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: tree-grid
+
+# TreeGrid agent guide
+
+## Purpose
+
+Combine hierarchical row expansion with ARIA grid cell navigation, active-descendant focus, indexed row and cell relationships, optional row selection, and actionable header boundaries.
+
+## Use when
+
+- Hierarchical parent-child rows expand and each row also exposes several navigable columns, such as a structured file browser.
+
+## Choose something else when
+
+- The hierarchy has one primary item column, rows are flat, or people only read a noninteractive table. Use Tree, DataGrid, or Table.
+- The application expects Atom to own sorting, filtering, editing, resizing, persistence, or virtualization. Use an application composition around TreeGrid and the relevant utility.
+
+## Required composition
+
+- Give Root an accessible name and accurate logical totals, then compose Caption when useful, Header and Body rowgroups, uniquely valued Rows with stable parentValue and level metadata, one RowHeader in the tree column, indexed ColumnHeader and Cell parts, and optional Footer summaries. Configure expansion, active-cell state, and selection deliberately.
+
+## Rules
+
+- **MUST:** Name Root and preserve treegrid, rowgroup, row, rowheader, columnheader, and gridcell relationships with stable row values, parent values, levels, and one-based logical coordinates.
+- **MUST:** Keep DOM focus on Root and preserve active-descendant navigation across visible cells, RTL-aware expand and collapse behavior in the tree column, vertical row movement, Home and End, whole-grid movement, disabled skipping, and loop policy.
+- **MUST:** Mark only real parent Rows expandable, keep descendants hidden from navigation while an ancestor is collapsed, and allow Atom to relocate an active descendant to the collapsed ancestor's tree-column cell.
+- **MUST:** Align scalar, array, or null value with selectionMode, use stable unique Row values, and distinguish selectable=false from disabled for parent, header, and summary rows.
+- **MUST:** Use ColumnHeader onAction for equivalent pointer and Enter activation, keep sortDirection truthful, and keep sorting, editing, filtering, and persistence application-owned.
+- **MUST:** When windowing hierarchical rows, preserve logical totals, indexes, levels, and parent visibility and keep the active cell and collapse destination mounted; Virtualizer owns geometry only.
+
+## Common mistakes
+
+- **Avoid:** Using TreeGrid for a one-column tree or a read-only hierarchical table without composite cell navigation. **Instead:** Use Tree for one-dimensional hierarchy and prefer simpler native structure when interactive grid behavior is absent.
+- **Avoid:** Deriving parentValue, level, rowIndex, or identity from the current visible slice during virtualization. **Instead:** Supply stable logical hierarchy and full-collection coordinates independent of the rendered window.
+
+## Validation checklist
+
+- Verify Root naming and complete treegrid relationships, stable unique Row values, parentValue and level metadata, RowHeader ownership, logical row and column indexes, and full totals.
+- Exercise LTR and RTL tree-column expansion, collapse and parent movement, next-cell arrows, vertical visible-row movement, Home and End, whole-grid movement, loop boundaries, disabled cells, and active relocation after collapse.
+- Verify controlled and uncontrolled expansion and active-cell state, none/single/multiple row selection, nonselectable rows, disabled and read-only behavior, actionable header pointer and Enter parity, and truthful sort metadata.
+- For virtualized hierarchies, verify hidden descendants do not enter navigation and the active descendant always resolves to a mounted visible cell.
+
+## Related guidance
+
+- `tree`
+- `data-grid`
+- `table`
+- `collection`
+- `virtualizer`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "tree-grid",
+  "name": "TreeGrid",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Combine hierarchical row expansion with ARIA grid cell navigation, active-descendant focus, indexed row and cell relationships, optional row selection, and actionable header boundaries.",
+  "useWhen": [
+    "Hierarchical parent-child rows expand and each row also exposes several navigable columns, such as a structured file browser."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The hierarchy has one primary item column, rows are flat, or people only read a noninteractive table.",
+      "useInstead": "Tree, DataGrid, or Table"
+    },
+    {
+      "condition": "The application expects Atom to own sorting, filtering, editing, resizing, persistence, or virtualization.",
+      "useInstead": "an application composition around TreeGrid and the relevant utility"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and accurate logical totals, then compose Caption when useful, Header and Body rowgroups, uniquely valued Rows with stable parentValue and level metadata, one RowHeader in the tree column, indexed ColumnHeader and Cell parts, and optional Footer summaries. Configure expansion, active-cell state, and selection deliberately."
+  ],
+  "rules": [
+    {
+      "id": "tree-grid-name-relationships",
+      "level": "must",
+      "statement": "Name Root and preserve treegrid, rowgroup, row, rowheader, columnheader, and gridcell relationships with stable row values, parent values, levels, and one-based logical coordinates."
+    },
+    {
+      "id": "tree-grid-focus",
+      "level": "must",
+      "statement": "Keep DOM focus on Root and preserve active-descendant navigation across visible cells, RTL-aware expand and collapse behavior in the tree column, vertical row movement, Home and End, whole-grid movement, disabled skipping, and loop policy."
+    },
+    {
+      "id": "tree-grid-expansion",
+      "level": "must",
+      "statement": "Mark only real parent Rows expandable, keep descendants hidden from navigation while an ancestor is collapsed, and allow Atom to relocate an active descendant to the collapsed ancestor's tree-column cell."
+    },
+    {
+      "id": "tree-grid-selection",
+      "level": "must",
+      "statement": "Align scalar, array, or null value with selectionMode, use stable unique Row values, and distinguish selectable=false from disabled for parent, header, and summary rows."
+    },
+    {
+      "id": "tree-grid-actions",
+      "level": "must",
+      "statement": "Use ColumnHeader onAction for equivalent pointer and Enter activation, keep sortDirection truthful, and keep sorting, editing, filtering, and persistence application-owned."
+    },
+    {
+      "id": "tree-grid-virtualization",
+      "level": "must",
+      "statement": "When windowing hierarchical rows, preserve logical totals, indexes, levels, and parent visibility and keep the active cell and collapse destination mounted; Virtualizer owns geometry only."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using TreeGrid for a one-column tree or a read-only hierarchical table without composite cell navigation.",
+      "correction": "Use Tree for one-dimensional hierarchy and prefer simpler native structure when interactive grid behavior is absent."
+    },
+    {
+      "mistake": "Deriving parentValue, level, rowIndex, or identity from the current visible slice during virtualization.",
+      "correction": "Supply stable logical hierarchy and full-collection coordinates independent of the rendered window."
+    }
+  ],
+  "validation": [
+    "Verify Root naming and complete treegrid relationships, stable unique Row values, parentValue and level metadata, RowHeader ownership, logical row and column indexes, and full totals.",
+    "Exercise LTR and RTL tree-column expansion, collapse and parent movement, next-cell arrows, vertical visible-row movement, Home and End, whole-grid movement, loop boundaries, disabled cells, and active relocation after collapse.",
+    "Verify controlled and uncontrolled expansion and active-cell state, none/single/multiple row selection, nonselectable rows, disabled and read-only behavior, actionable header pointer and Enter parity, and truthful sort metadata.",
+    "For virtualized hierarchies, verify hidden descendants do not enter navigation and the active descendant always resolves to a mounted visible cell."
+  ],
+  "related": [
+    "tree",
+    "data-grid",
+    "table",
+    "collection",
+    "virtualizer"
+  ]
+}
+```