TreeView

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: TreeView  tag: wyrd-tree-view  package: wyrd.component.tree-view  title: TreeView  summary: Single-select hierarchical tree derived from flat ordered item data.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: navigation  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: label      type:        kind: string      required: true      serializable: true      summary: Accessible name for the tree.    - name: items      type:        kind: array        item:          kind: object          fields:            label:              kind: string            value:              kind: string            href:              kind: string            parent-value:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Flat ordered tree item data. Items without parent-value are roots; parent records must appear before child records.    - name: expanded-values      type:        kind: array        item:          kind: string      required: false      controlled: true      serializable: true      summary: Controlled expanded parent values.    - name: default-expanded-values      type:        kind: array        item:          kind: string      required: false      default: []      serializable: true      summary: Initial uncontrolled expanded parent values.    - name: selected-value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled selected item value.    - name: default-selected-value      type:        kind: string      required: false      serializable: true      summary: Initial uncontrolled selected item value.  slots: []  events:    - name: expanded-change      payload:        expanded-values:          kind: array          item:            kind: string      bubbles: true      composed: true      cancelable: false      summary: Emitted with the full new expanded value set after expansion state changes.    - name: selection-change      payload:        value:          kind: string      bubbles: true      composed: true      cancelable: false      summary: Emitted when the user selects an enabled tree item.    - name: navigation-request      payload:        value:          kind: string        href:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Emitted when the user activates a tree item with a navigation destination.  states:    - name: default      source: platform      summary: Tree collection is visible.    - name: expanded      source: property      summary: One or more parent items are expanded.    - name: selected      source: property      summary: One tree item is selected.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state on a tree item.    - name: disabled      source: property      summary: Disabled item state.  parts:    - name: root      summary: Tree root.    - name: item      summary: Repeated tree item row.    - name: chevron      summary: Parent item expansion affordance.    - name: label      summary: Tree item label text.    - name: group      summary: Child item group.  tokens:    item:      foreground: color.on-surface      background: color.surface      selected-background: color.primary      selected-foreground: color.on-primary      hover-background: color.secondary      indent: spacing.lg    chevron:      color: color.on-surfacemessages: []obligations:  accessibility:    role: tree    name: Label property provides the required accessible name.    keyboard:      - ArrowDown moves focus to the next visible enabled item.      - ArrowUp moves focus to the previous visible enabled item.      - ArrowRight expands a focused collapsed parent, or moves to its first visible child when already expanded.      - ArrowLeft collapses a focused expanded parent, or moves focus to its parent.      - Home and End move focus to the first and last visible enabled item.      - Enter and Space select the focused enabled item.    semantics:      - Web projections use ul/li tree structure with role=tree, role=treeitem, group containers, aria-level, aria-setsize, aria-posinset, aria-selected, and aria-expanded only on parent items.      - Disabled items render but are skipped by roving tabindex and cannot be selected.      - Navigable web items expose native anchors so standard link actions remain available.      - Selection does not auto-expand ancestors in v1.      - Flutter exposes expanded and selected flags through Semantics and renders visible rows as an indented flattened list.  behavior:    model: collection    interactions:      - Hierarchy is derived at runtime from flat item data.      - Source item order defines sibling order.      - Parent records must appear before their children; dangling children are rendered as roots and reported with console.warn on web targets.      - expanded-values ?? default-expanded-values determines the effective expanded set.      - selected-value ?? default-selected-value determines the effective single selection.      - Arrow-key focus movement uses only visible enabled items.      - Expanding or collapsing does not change selection.    hostEffects:      - Dispatch expanded-change with the full expanded value set.      - Dispatch selection-change with the selected item value.      - Dispatch navigation-request when an item with href is activated; canceling it prevents native navigation.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - label      - items      - expanded-values      - default-expanded-values      - selected-value      - default-selected-value    serializableSlots: []    eventBindings:      - expanded-change      - selection-change      - navigation-request    notes: TreeView serializes a flat ordered item array. Hosts derive the hierarchy at runtime, preserve sibling order, and treat dangling parent references as root items.examples:  - name: file-explorer    state: expanded    properties:      label: Project files      default-expanded-values:        - src        - components      default-selected-value: button      items:        - label: src          value: src        - label: components          value: components          parent-value: src        - label: Button.tsx          value: button          parent-value: components          href: /docs/components/button        - label: Dialog.tsx          value: dialog          parent-value: components        - label: package.json          value: package    slots: {}  - name: disabled-item    state: disabled    properties:      label: Project files      default-expanded-values:        - src      items:        - label: src          value: src        - label: generated          value: generated          parent-value: src          disabled: true        - label: index.ts          value: index          parent-value: src    slots: {}