@astryxdesign/core 0.5.2-canary.2da7a39 → 0.5.2-canary.2e51213

package/src/Tooltip/useTooltip.tsx

@@ -5,7 +5,7 @@
 /**
  * @file useTooltip.tsx
  * @input Uses useLayer, useTouchTrigger, React hooks
- * @output Exports useTooltip hook for hover/focus/tap triggered tooltips
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
  * SYNC: When modified, update:
@@ -284,6 +284,15 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     onShow,
     onHide,
   });
+  const {
+    ref: layerRef,
+    anchorId: layerAnchorId,
+    show: showLayer,
+    hide: hideLayer,
+    isOpen: isLayerOpen,
+    id: layerId,
+    render: renderLayer,
+  } = layer;
 
   const popoverXstyle = styles.container;
 
@@ -307,20 +316,26 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // passing across the trigger, and a tap is never that.
   const showNow = useCallback(() => {
     clearTimeouts();
-    layer.show();
-  }, [clearTimeouts, layer]);
+    showLayer();
+  }, [clearTimeouts, showLayer]);
 
   const hideNow = useCallback(() => {
     clearTimeouts();
-    layer.hide();
-  }, [clearTimeouts, layer]);
+    hideLayer();
+  }, [clearTimeouts, hideLayer]);
 
-  const touch = useTouchTrigger({
+  const {
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown: handleTouchPointerDown,
+    clearTapOpen,
+  } = useTouchTrigger({
     touchTrigger,
     isEnabled,
     isControlled: isOpen !== undefined,
-    isOpen: layer.isOpen,
-    layerId: layer.id,
+    isOpen: isLayerOpen,
+    layerId: layerId,
     triggerRef,
     show: showNow,
     hide: hideNow,
@@ -333,9 +348,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }
     clearTimeouts();
     showTimeoutRef.current = setTimeout(() => {
-      layer.show();
+      showLayer();
     }, delay);
-  }, [isEnabled, isOpen, clearTimeouts, layer, delay]);
+  }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
@@ -348,9 +363,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     clearTimeouts();
     const effectiveHideDelay = hideDelay > 0 ? hideDelay : HOVER_BRIDGE_DELAY;
     hideTimeoutRef.current = setTimeout(() => {
-      layer.hide();
+      hideLayer();
     }, effectiveHideDelay);
-  }, [isOpen, clearTimeouts, layer, hideDelay]);
+  }, [isOpen, clearTimeouts, hideLayer, hideDelay]);
 
   // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
   const cancelHide = useCallback(() => {
@@ -365,21 +380,21 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     // A tap synthesizes mouseenter. On touch the tap path owns the decision,
     // so hover must not also fire — including the tap that just opened the
     // tooltip, which would otherwise be double-handled.
-    if (touch.isTouchPointerRef.current) {
+    if (isTouchPointerRef.current) {
       return;
     }
     scheduleShow();
-  }, [touch, scheduleShow]);
+  }, [isTouchPointerRef, scheduleShow]);
 
   const handleMouseLeave = useCallback(() => {
     // On touch the synthesized mouseleave arrives with the next tap elsewhere,
     // which the outside-tap dismissal already handles — and handling it here
     // too would close the tooltip behind the tap-open bookkeeping's back.
-    if (touch.isTouchPointerRef.current) {
+    if (isTouchPointerRef.current) {
       return;
     }
     scheduleHide();
-  }, [touch, scheduleHide]);
+  }, [isTouchPointerRef, scheduleHide]);
 
   const handleFocusIn = useCallback(
     (e: Event) => {
@@ -391,7 +406,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       // matches it. Those are exactly the action triggers `auto` just decided
       // to keep shut, so without this the focus reopens what the tap
       // suppressed, over the field the user is trying to type into.
-      if (touch.isTouchInteraction()) {
+      if (isTouchInteraction()) {
         return;
       }
       // Only show tooltip for keyboard focus (:focus-visible),
@@ -401,9 +416,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         return;
       }
       clearTimeouts();
-      layer.show();
+      showLayer();
     },
-    [isEnabled, touch, clearTimeouts, layer],
+    [isEnabled, isTouchInteraction, clearTimeouts, showLayer],
   );
 
   const handleFocusOut = useCallback(() => {
@@ -414,25 +429,24 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // the hint has served its purpose, and a tooltip lingering over a
   // just-pressed control reads as stale. Fires on pointerdown so it feels
   // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
-  // is owned by the consumer. `layer.hide()` self-guards when already closed.
+  // is owned by the consumer. `hideLayer()` self-guards when already closed.
   // A touch press is a different gesture (it may be the only way to open the
   // tooltip at all), so the touch path answers it first.
   const handlePointerDown = useCallback(
     (event: PointerEvent) => {
-      if (touch.handlePointerDown(event)) {
+      if (handleTouchPointerDown(event)) {
         return;
       }
       if (isOpen !== undefined) {
         return;
       }
       clearTimeouts();
-      layer.hide();
+      hideLayer();
     },
-    [touch, isOpen, clearTimeouts, layer],
+    [handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
   );
 
   // Interaction ref that handles event listeners only
-  const {handlePointerEnter, clearTapOpen} = touch;
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
       // Cleanup previous element
@@ -488,10 +502,10 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // Combined ref - shorthand for calling both positionRef and interactionRef
   const ref: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
-      layer.ref(el);
+      layerRef(el);
       interactionRef(el);
     },
-    [layer, interactionRef],
+    [layerRef, interactionRef],
   );
 
   // Cleanup on unmount
@@ -504,7 +518,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // Show on mount when isDefaultOpen is true
   useEffect(() => {
     if (isDefaultOpen) {
-      layer.show();
+      showLayer();
     }
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
   }, []);
@@ -516,12 +530,12 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }
     if (isOpen) {
       clearTimeouts();
-      layer.show();
+      showLayer();
     } else {
       clearTimeouts();
-      layer.hide();
+      hideLayer();
     }
-  }, [isOpen, clearTimeouts, layer]);
+  }, [isOpen, clearTimeouts, showLayer, hideLayer]);
 
   // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
   // stack. A visible tip is the top-most layer, so it takes the press and
@@ -536,7 +550,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // consumer's value, so only their update may change it. Same contract as a
   // controlled Dialog.
   useLayerDismissal({
-    // Registered for the hook's lifetime rather than gated on `layer.isOpen`:
+    // Registered for the hook's lifetime rather than gated on `isLayerOpen`:
     // that state can lag a frame behind the DOM, so a press arriving right after
     // the layer appears would find nothing registered. Because this layer
     // CONSUMES the press, a stale registration would be worse than a missed one
@@ -547,7 +561,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       const el =
         typeof document === 'undefined'
           ? null
-          : document.getElementById(layer.id);
+          : document.getElementById(layerId);
       if (el == null) {
         return false;
       }
@@ -556,7 +570,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       } catch {
         // Browsers without the Popover API (and some test environments) cannot
         // answer the selector; fall back to the hook's own state.
-        return layer.isOpen;
+        return isLayerOpen;
       }
     },
     onDismiss: () => {
@@ -566,7 +580,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         onHide?.();
         return;
       }
-      layer.hide();
+      hideLayer();
     },
   });
 
@@ -592,20 +606,27 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         onMouseLeave: scheduleHide,
       };
 
-      return layer.render(
+      return renderLayer(
         <div {...stylex.props(styles.content)}>{children}</div>,
         renderProps,
       );
     },
-    [layer, placement, alignment, popoverXstyle, cancelHide, scheduleHide],
+    [
+      renderLayer,
+      placement,
+      alignment,
+      popoverXstyle,
+      cancelHide,
+      scheduleHide,
+    ],
   );
 
   return {
     ref,
-    positionRef: layer.ref,
+    positionRef: layerRef,
     interactionRef,
-    anchorId: layer.anchorId,
-    describedBy: layer.id,
+    anchorId: layerAnchorId,
+    describedBy: layerId,
     renderTooltip,
   };
 }

package/src/TreeList/TreeList.doc.mjs

@@ -1,5 +1,60 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Tree list',
+    required: true,
+    description: 'Container that presents the hierarchical tree.',
+  },
+  {
+    name: 'Header',
+    required: false,
+    description: 'Caller-provided content that visibly names the tree.',
+  },
+  {
+    name: 'Item',
+    required: true,
+    description: 'Painted row for one node in the hierarchy.',
+  },
+  {
+    name: 'Chevron',
+    required: false,
+    description:
+      'Expand and collapse control rendered for an Item with children.',
+  },
+  {
+    name: 'Chevron glyph',
+    required: false,
+    description: 'Directional symbol rendered by Icon inside a Chevron.',
+  },
+  {
+    name: 'Item label',
+    required: true,
+    description: 'Primary content that identifies an Item.',
+  },
+  {
+    name: 'Item description',
+    required: false,
+    description: 'Secondary text rendered below an Item label.',
+  },
+  {
+    name: 'Start content',
+    required: false,
+    description: 'Caller-provided content rendered before an Item label.',
+  },
+  {
+    name: 'End content',
+    required: false,
+    description: 'Caller-provided content rendered after an Item label.',
+  },
+  {
+    name: 'Guide',
+    required: false,
+    description: 'Connector line that shows parent-child relationships.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -79,6 +134,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [
@@ -158,6 +214,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [
@@ -175,6 +232,7 @@ export const docsDense = {
   description:
     'Data-driven tree list for hierarchical data w/ expand/collapse, branch lines, interactive items. Flat items array w/ recursive children, no composition, no cloneElement.',
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [

package/src/TreeList/TreeList.spec.md

@@ -0,0 +1,224 @@
+---
+schema_version: 3
+template_version: 3
+kind: component
+id: component:TreeList
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/TreeList/TreeList.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-005/DEC-1]
+---
+
+# TreeList component contract
+
+## Intent
+
+TreeList presents hierarchical data as expandable tree rows. This draft records
+its current consumer anatomy, target ownership, delegated Icon glyph, and
+unreached stable parts without changing runtime behavior, styling, targets, or
+public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Tree list, Item, Chevron, Item label, and Guide parts and their five current
+  targets.
+- The stable Item description rendered below an Item label.
+- Hierarchical placement, indentation, expansion, selection, and tree semantics.
+
+**Does not own / non-goals**
+
+- The Chevron glyph artwork and Icon target — owned by `component:Icon`.
+- Header, Start content, and End content supplied through consumer slots — owned
+  by the product callsite.
+- New targets for Item description or caller-provided slots — unresolved by this
+  factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer data, props, slots, and usage
+remain documented in `TreeList.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                          | Basis                             | Draft review state                                                        |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                | Current source and target docs    | Verified current inventory; focused placement coverage is partial         |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                      | Current source and component docs | Verified current ownership; no target change                              |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.  | Current source and target docs    | Verified current reachability; long-term theming intent remains unsettled |
+
+### Allowed variation
+
+- **AV1 — Hierarchy.** Item count, depth, expansion, selection, density, and guide
+  visibility may vary without changing the anatomy ownership recorded here.
+- **AV2 — Consumer content.** Header, Start content, End content, Item label
+  values, and descriptions may vary without making caller-owned slot content a
+  TreeList target.
+- **AV3 — Delegated glyph.** Icon may change the Chevron glyph's internal element
+  shape while preserving its own public contract.
+
+### Representative states
+
+| State                    | Required invariant                                    | Allowed variation                             |
+| ------------------------ | ----------------------------------------------------- | --------------------------------------------- |
+| Empty tree               | Tree list remains; no Item instances render.          | Optional Header content.                      |
+| Flat items               | Each Item contains an Item label.                     | Description and consumer slots may be absent. |
+| Expandable item          | Item may contain Chevron and delegated Chevron glyph. | Expanded or collapsed state.                  |
+| Nested `lineGuides` tree | Guide instances show parent-child relationships.      | Count and position follow hierarchy.          |
+| `noGuides` tree          | Guide instances are absent; indentation remains.      | All other anatomy remains unchanged.          |
+| Described item           | Item description renders below Item label.            | Caller-provided description text.             |
+
+### Transformation and precedence order
+
+- No new hierarchy, focus, expansion, layout, or styling precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend TreeList's current tree, treeitem, group,
+roving-focus, expansion, selection, disabled, or activation behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                   | Representation authority       | Hierarchy role    | Component contract |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Tree list        | Groups the hierarchical tree and owns its density and guide variant. | Current source and public docs | Supporting        | FR1, FR2           |
+| Header           | Visibly names the tree with caller-provided content.                 | Caller-supplied content        | Prominent         | FR1, FR3           |
+| Item             | Paints one row and reflects density, selection, and disabled state.  | Current source and public docs | Prominent         | FR1, FR2           |
+| Chevron          | Provides the expand and collapse control for an Item with children.  | Current source and public docs | Supporting        | FR1, FR2           |
+| Chevron glyph    | Presents the current directional symbol inside Chevron.              | `component:Icon`               | Supporting        | FR1, FR3           |
+| Item label       | Presents the primary content that identifies an Item.                | Current source and public docs | Prominent         | FR1, FR2           |
+| Item description | Presents stable secondary text below Item label.                     | Current source and public docs | Supporting        | FR1, FR4           |
+| Start content    | Presents caller-provided content before Item label.                  | Caller-supplied content        | Context-dependent | FR1, FR3           |
+| End content      | Presents caller-provided content after Item label.                   | Caller-supplied content        | Context-dependent | FR1, FR3           |
+| Guide            | Paints a connector between related hierarchy levels.                 | Current source and public docs | Supporting        | FR1, FR2           |
+
+Item description is stable TreeList-rendered anatomy, not consumer-owned slot
+structure. Its current lack of a target is observed reachability, not a decision
+that it must remain unthemeable. Header, Start content, and End content remain
+caller-owned even though TreeList positions their slot wrappers.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Tree list": {"target": "tree-list"},
+  "Header": {
+    "none": {
+      "reason": "intentional: Header is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "Item": {"target": "tree-list-item"},
+  "Chevron": {"target": "tree-list-chevron"},
+  "Chevron glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Item label": {"target": "tree-list-item-label"},
+  "Item description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Item description; future exposure still needs an owner decision"
+    }
+  },
+  "Start content": {
+    "none": {
+      "reason": "intentional: Start content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "End content": {
+    "none": {
+      "reason": "intentional: End content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "Guide": {"target": "tree-list-guide"}
+}
+```
+
+The five local targets are current public seams. The Chevron glyph retains Icon
+ownership. Consumer-slot `none` dispositions are ownership boundaries; Item
+description's `none` disposition records a current audit gap and does not
+authorize a new target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, delegation, and factual `none` dispositions.
+- `architecture:public-component-api` owns the stable data, props, and slot
+  surface; this documentation adds no API.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+  TreeList continues to own its existing tree focus and activation behavior.
+- `family:navigation-destinations` owns the shared accept/block result for a
+  TreeListItem `href`; `spec:AST-005/DEC-1` requires native and custom-router
+  item paths to preserve that result.
+- TreeList's current custom-router path inherits the `useLinkComponent` adoption
+  gap recorded by the family until the accepted implementation lands.
+
+## Verification map
+
+| Contract            | Verification                                                                                    | Representative states                              | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section            |
+| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                | Five local targets and their documented states     | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming` |
+| FR3                 | Source inspection plus Icon public target metadata                                              | Expandable rows and caller-provided slots          | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming` |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                            | Item with description                              | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                   | Canonical anatomy and five current local targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                               | `audit:TreeList/theming` |
+
+Focused target-placement assertions cover all five local targets: Tree list,
+Item, Chevron, Item label, and Guide. Existing tests do not assert the Icon
+instance that renders Chevron glyph.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, behavior, or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Item description gain a stable public theming target?**
+  (`human-api`) Its current lack of reachability is an audit gap, not settled
+  intent.
+- **OQ2 — Should a focused test pin the delegated Chevron glyph's Icon
+  instance?** (`checkable`) Its presence is currently source-inspected rather
+  than asserted.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, shared modality
+rules, current audit results, or implementation steps. It links to their owners.