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

package/src/Tokenizer/Tokenizer.tsx

@@ -25,6 +25,12 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {
+  BusyIndicatorLaneProvider,
+  createBusyIndicatorLane,
+  useIsBusy,
+  type BusyIndicatorLane,
+} from '../Typeahead/busyIndicatorLane';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {BaseTypeahead} from '../Typeahead/BaseTypeahead';
@@ -40,6 +46,8 @@ import {
   type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
+import {Spinner} from '../Spinner';
+import {useEndLaneReserve} from './useEndLaneReserve';
 import {renderIconSlot, type IconType} from '../Icon';
 import {OverflowList} from '../OverflowList';
 import {useLayer} from '../Layer/useLayer';
@@ -232,6 +240,10 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
 // Styles
 // =============================================================================
 
+// How far the end lane sits from the field's inline-end border, named once
+// because the input's reserve is derived from the same value.
+const END_LANE_INSET = spacingVars['--spacing-2'];
+
 const styles = stylex.create({
   wrapper: {
     position: 'relative',
@@ -267,7 +279,7 @@ const styles = stylex.create({
     // Match the field's inline padding (inputWrapperStyles.base uses
     // spacing-2) so end content (clear button, resultCount) lines up with
     // the text/start-icon inset instead of hugging the border at ~3px.
-    insetInlineEnd: spacingVars['--spacing-2'],
+    insetInlineEnd: END_LANE_INSET,
     display: 'flex',
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
@@ -387,6 +399,45 @@ const CREATABLE_ID_PREFIX = '__xds_create__';
  * />
  * ```
  */
+/**
+ * The field's inline-end lane: the busy Spinner, then `endContent`, then the
+ * clear button — pinned to the field's first row while tokens wrap below it.
+ *
+ * A separate component so that subscribing to the busy state re-renders THIS
+ * and nothing else. Subscribed from `Tokenizer`, a search transition
+ * re-rendered every selected token twice — twenty tokens meant forty renders
+ * per search for one glyph none of them contain.
+ *
+ * Renders nothing when the lane would be empty, so `useEndLaneReserve` sees no
+ * element, publishes no width, and the input keeps its full content box.
+ */
+function EndLane({
+  lane,
+  laneRef,
+  laneXStyle,
+  loadingLabel,
+  hasStaticContent,
+  children,
+}: {
+  lane: BusyIndicatorLane;
+  laneRef: (node: HTMLElement | null) => void;
+  laneXStyle: stylex.StyleXStyles[];
+  loadingLabel: string;
+  hasStaticContent: boolean;
+  children: ReactNode;
+}) {
+  const isBusy = useIsBusy(lane);
+  if (!isBusy && !hasStaticContent) {
+    return null;
+  }
+  return (
+    <div ref={laneRef} {...stylex.props(laneXStyle)}>
+      {isBusy && <Spinner size="sm" aria-label={loadingLabel} />}
+      {children}
+    </div>
+  );
+}
+
 export function Tokenizer<T extends SearchableItem>({
   label,
   isLabelHidden = false,
@@ -461,6 +512,24 @@ export function Tokenizer<T extends SearchableItem>({
   }));
 
   // Focus-within state for overflow truncation
+  // Reported by BaseTypeahead so the indicator can live in this field's own
+  // end lane, beside endContent and the clear button.
+  // The base owns the busy state; this field only paints it. Held in a store
+  // rather than this component's state — held here, a search transition
+  // re-rendered every selected token twice, for a glyph no token contains.
+  // See busyIndicatorLane.tsx.
+  const busyLane = useMemo(() => createBusyIndicatorLane(), []);
+  // What sits in the end lane varies most here — a spinner, arbitrary
+  // `endContent`, a clear button, or all three — so its width is measured
+  // rather than assumed, and the input reserves it.
+  const [laneRef, laneReserve] = useEndLaneReserve(END_LANE_INSET);
+  // The half of the lane's contents this component knows about. The busy half
+  // is the leaf's own business — folding it in here would mean reading the
+  // busy state during this render, which is exactly the re-render the store
+  // exists to avoid.
+  const hasStaticEndLane = Boolean(
+    endContent || (hasClear && value.length > 0 && !isDisabled),
+  );
   const [isFocusedWithin, setIsFocusedWithin] = useState(false);
   const isTruncated =
     !isFocusedWithin && tokenOverflowBehavior !== 'none' && value.length > 0;
@@ -795,37 +864,48 @@ export function Tokenizer<T extends SearchableItem>({
       ) : (
         tokens
       )}
-      <BaseTypeahead
-        ref={inputRef}
-        searchSource={isAtMax ? emptySource : filteredSource}
-        value={null}
-        onChange={handleAdd}
-        renderItem={renderItem}
-        placeholder={value.length === 0 ? placeholder : ''}
-        hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
-        maxMenuItems={maxMenuItems}
-        menuWidth={menuWidth}
-        minQueryLength={minQueryLength}
-        emptySearchResultsText={emptySearchResultsText}
-        isDisabled={isDisabled}
-        isFocusableDisabled={showsDisabledMessage}
-        hasAutoFocus={hasAutoFocus}
-        inputId={inputId}
-        ariaDescribedBy={ariaDescribedBy}
-        onChangeQuery={onChangeQuery}
-        __queryEntries={createEntries}
-        debounceMs={debounceMs}
-        onKeyDown={handleKeyDown}
-        anchorRef={wrapperRef}
-        size={size}
-        inputXStyle={
-          isAtMax || isTruncated
-            ? styles.inputAtMax
-            : value.length > 0
-              ? styles.inputCompact
-              : undefined
-        }
-      />
+      {/* The base reports its busy state through this lane, so the
+          indicator lands in the end controls below beside the clear
+          button rather than as a second one inside the base. */}
+      <BusyIndicatorLaneProvider value={busyLane}>
+        <BaseTypeahead
+          ref={inputRef}
+          searchSource={isAtMax ? emptySource : filteredSource}
+          value={null}
+          onChange={handleAdd}
+          renderItem={renderItem}
+          placeholder={value.length === 0 ? placeholder : ''}
+          hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
+          maxMenuItems={maxMenuItems}
+          menuWidth={menuWidth}
+          minQueryLength={minQueryLength}
+          emptySearchResultsText={emptySearchResultsText}
+          isDisabled={isDisabled}
+          isFocusableDisabled={showsDisabledMessage}
+          hasAutoFocus={hasAutoFocus}
+          inputId={inputId}
+          ariaDescribedBy={ariaDescribedBy}
+          onChangeQuery={onChangeQuery}
+          __queryEntries={createEntries}
+          debounceMs={debounceMs}
+          onKeyDown={handleKeyDown}
+          anchorRef={wrapperRef}
+          size={size}
+          inputXStyle={[
+            isAtMax || isTruncated
+              ? styles.inputAtMax
+              : value.length > 0
+                ? styles.inputCompact
+                : undefined,
+            // Not for the collapsed states above: those give the input no width
+            // to pad, and `inputAtMax` zeroes its padding outright.
+            // Applied whether or not a lane is up: the reserve resolves to
+            // zero until the lane publishes a width, so this does not need to
+            // know about the busy state.
+            !(isAtMax || isTruncated) && laneReserve,
+          ]}
+        />
+      </BusyIndicatorLaneProvider>
       {htmlName != null &&
         value.map(item => (
           <input
@@ -838,20 +918,23 @@ export function Tokenizer<T extends SearchableItem>({
             disabled={isDisabled}
           />
         ))}
-      {(endContent || (hasClear && value.length > 0 && !isDisabled)) && (
-        <div {...stylex.props(styles.endSection, endSectionSizeStyles[size])}>
-          {endContent}
-          {hasClear && value.length > 0 && !isDisabled && (
-            <InputClearButton
-              label={t('@astryx.tokenizer.clearAll')}
-              onClick={e => {
-                e.stopPropagation();
-                handleClearAll();
-              }}
-            />
-          )}
-        </div>
-      )}
+      <EndLane
+        lane={busyLane}
+        laneRef={laneRef}
+        laneXStyle={[styles.endSection, endSectionSizeStyles[size]]}
+        loadingLabel={t('@astryx.typeahead.loading')}
+        hasStaticContent={hasStaticEndLane}>
+        {endContent}
+        {hasClear && value.length > 0 && !isDisabled && (
+          <InputClearButton
+            label={t('@astryx.tokenizer.clearAll')}
+            onClick={e => {
+              e.stopPropagation();
+              handleClearAll();
+            }}
+          />
+        )}
+      </EndLane>
     </div>
   );
 

package/src/Tokenizer/useEndLaneReserve.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useEndLaneReserve.ts
+ * @input Uses React and the shared ResizeObserver
+ * @output Exports useEndLaneReserve, which keeps a field's input clear of the
+ *   absolutely-positioned lane at its inline end
+ * @position Tokenizer internal. Tokenizer parks its clear button, end content
+ *   and busy indicator in one absolutely-positioned lane at the field's
+ *   inline end, and this keeps the input's text and caret clear of it.
+ *
+ *   It lives here, beside its one caller, rather than in `Field/` with the
+ *   shared field internals — deliberately. A measured reserve is Tokenizer's
+ *   workaround for a constraint only Tokenizer has: its lane must stay pinned
+ *   to the field's first row while tokens wrap below it, so it cannot be in
+ *   flow, and an out-of-flow box reserves nothing. Every other field, this
+ *   one's own Typeahead included, puts its end controls in flow as flex
+ *   siblings the way TextInput does, which needs no measuring at all. Filed
+ *   under `Field/` this read as shared infrastructure and invited the next
+ *   field to reach for it; that is the wrong default.
+ *
+ * SYNC: When modified, update this header and the caller:
+ * - /packages/core/src/Tokenizer/Tokenizer.tsx
+ */
+
+import {useCallback} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {observeResize} from '../utils/sharedResizeObserver';
+
+/**
+ * The measured lane width, published on the field wrapper and read by the
+ * input through inheritance. A custom property is the point of the design: it
+ * carries a measurement into CSS without carrying it through React, so a lane
+ * that grows or shrinks repaints without re-rendering the field.
+ */
+const LANE_RESERVE_VAR = '--_tokenizer-end-lane-reserve';
+
+// Keep the input's text and caret out from under the lane.
+//
+// The input's content box already stops one wrapper padding short of the
+// border, and the lane is inset from that same border — so what is left for
+// the input to clear is the lane's inset plus its width, less the padding it
+// already has, plus a padding's worth of gap so the text does not touch the
+// glyph. The two paddings cancel, which is why this reads as inset + width.
+//
+// The variable carries the WHOLE reserve, not just the width, so its absence
+// means "no lane" rather than "a lane of zero width": with no lane up, the
+// fallback resolves the padding to 0 and the input keeps its full content box.
+// That is what lets the caller apply this style unconditionally, which in turn
+// is what keeps the field from having to know whether a search is running.
+// The rule stays static either way — one class, generated once, never
+// regenerated as the lane changes.
+const reserveStyles = stylex.create({
+  reserve: {
+    paddingInlineEnd: `var(${LANE_RESERVE_VAR}, 0px)`,
+  },
+});
+
+/**
+ * Keep a field's input clear of the lane at its inline end.
+ *
+ * The lane is absolutely positioned — it has to be, because these wrappers
+ * wrap, and an in-flow sibling gets pushed onto a second row by a token — and
+ * an out-of-flow box reserves no space by definition. There is no CSS that
+ * makes one do so: the input cannot see a sibling's width. So the lane is
+ * measured, and the input spends the measurement as padding.
+ *
+ * What the lane holds is not a fixed set: a clear button that comes and goes
+ * with the value, a busy indicator that comes and goes with the search, and
+ * arbitrary `endContent`. Measuring covers all of it, including the
+ * combinations, and needs no constant kept in step with what renders.
+ *
+ * **The measurement never enters React state.** It is written to a custom
+ * property on the field wrapper and inherited by the input. Held in state, it
+ * cost the field a second commit every time the lane changed size — once when
+ * the spinner arrived and again when it left — doubling the field's renders
+ * across a search for a value no JavaScript ever reads. The observation is
+ * shared as well: `observeResize` batches every field on the page into one
+ * callback per frame instead of one observer each.
+ *
+ * Takes the lane's inset from the field's inline-end border, as the CSS
+ * expression that positions it. Returns a ref callback for the lane, and the
+ * style for the input — which the caller applies unconditionally: with no lane
+ * mounted the variable is absent and the padding resolves to zero, so the
+ * caller never has to know whether a search is running.
+ */
+export function useEndLaneReserve(
+  laneInset: string,
+): [(node: HTMLElement | null) => void, stylex.StyleXStyles] {
+  const laneRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (node == null) {
+        return;
+      }
+      // The lane's parent: the field wrapper in both callers, and an ancestor
+      // of the input either way, which is what inheritance needs.
+      const host = node.parentElement;
+
+      const unobserve = observeResize(node, () => {
+        // `offsetWidth`, not `getBoundingClientRect().width`. The rect is in
+        // VIEWPORT space — it carries every CSS transform between this element
+        // and the root — while the padding it feeds is in the element's own
+        // LOCAL space. Under `scale(.5)` the rect reads half the lane's real
+        // width and the input reserves half of what it needs, so the query runs
+        // under the controls again; under `scale(2)` it reads double and the
+        // caret sits in a gap twice the lane's width. Measured in Chromium on a
+        // 123px lane in a 280px field: at `scale(.5)` the rect published 61.48px
+        // and the spinner covered 14px of the input's content box; at `scale(2)`
+        // it published 245.91px, leaving a 125.95px gap and growing the field
+        // from 32px to 55px tall. `offsetWidth` is the untransformed border-box
+        // width, so it reports 123 at every scale — the number this padding is
+        // actually denominated in.
+        //
+        // It is already an integer, which is the rounding the old `Math.ceil`
+        // was there for: a fractional width left as-is reserves a hair too
+        // little and the glyph's last subpixel column lands on the caret.
+        const width = node.offsetWidth;
+        if (width > 0) {
+          host?.style.setProperty(
+            LANE_RESERVE_VAR,
+            `calc(${laneInset} + ${width}px)`,
+          );
+        } else {
+          // A mounted but empty lane (no end content, no clear, not searching)
+          // claims nothing.
+          host?.style.removeProperty(LANE_RESERVE_VAR);
+        }
+      });
+
+      // React 19 runs a ref callback's return value as its cleanup, so the
+      // observer is released exactly when the lane unmounts.
+      return () => {
+        unobserve();
+        // The room the lane claimed goes back to the input. Removing beats
+        // setting 0px: the rule's fallback is already that, and this leaves no
+        // stale property behind on the DOM.
+        host?.style.removeProperty(LANE_RESERVE_VAR);
+      };
+    },
+    [laneInset],
+  );
+
+  return [laneRef, reserveStyles.reserve];
+}

package/src/Toolbar/Toolbar.doc.mjs

@@ -1,5 +1,21 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Outer chrome',
+    required: true,
+    description:
+      'Section-owned container that supplies the toolbar surface, padding, and selected divider edges.',
+  },
+  {
+    name: 'Toolbar',
+    required: true,
+    description:
+      'Named toolbar row that owns toolbar semantics and the start, optional center, and end layout.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -147,6 +163,7 @@ export const docs = {
       ],    },
   ],
   usage: {
+    anatomy,
     description:
       'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
     bestPractices: [
@@ -182,6 +199,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
     bestPractices: [
@@ -200,6 +218,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Horizontal bar w/ left, center, right areas. For contextual actions in content, not page headers. Size cascades to children.',
   usage: {
+    anatomy,
     description:
       'Horizontal bar w/ left, optional center, right. For contextual actions within content (tables, cards, panels), not page-level headers. Size cascades to children.',
     bestPractices: [

package/src/Toolbar/Toolbar.spec.md

@@ -0,0 +1,174 @@
+---
+schema_version: 3
+template_version: 3
+kind: component
+id: component:Toolbar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Toolbar/Toolbar.test.tsx,
+    packages/core/src/Section/Section.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:container-padding,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Toolbar component contract
+
+## Intent
+
+Toolbar presents a named contextual action region with one semantic toolbar row
+inside Section-owned outer chrome. This draft records the current consumer
+anatomy and theming ownership without changing layout, keyboard behavior,
+targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The named toolbar row, toolbar semantics, start/optional-center/end layout,
+  keyboard movement, size cascade, and current `toolbar` target.
+
+**Does not own / non-goals**
+
+- The painted outer chrome, variant, block padding, and selected divider edges —
+  delegated to `component:Section`.
+- Content supplied through the three layout slots — owned by the caller or its
+  rendered components.
+- A general arbitrary-child layout primitive contract.
+- New runtime behavior, targets, props, or target placement.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, and usage remain
+documented in `Toolbar.doc.mjs`; `family:layout-regions` owns the shared
+structural-region boundary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                              | Basis                                      | Draft review state                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------- |
+| FR1 | The current render contains Section-owned Outer chrome around one named Toolbar carrying `role="toolbar"` and the current `toolbar` target.                      | Current source, docs, tests, and family    | Verified current behavior; no new behavior decided |
+| FR2 | The Toolbar uses its current two-lane layout without center content and its current three-lane layout when center content is supplied.                           | Current source and focused structure tests | Verified current behavior; no layout change        |
+| FR3 | Variant, selected divider edges, and outer padding remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout. | Current source, docs, and family contract  | Verified current ownership; no target change       |
+
+### Allowed variation
+
+- Caller content may be absent or supplied in the start, center, and end slots
+  without changing Outer chrome or Toolbar ownership.
+- Size and orientation may change the current row geometry and keyboard axis
+  without creating separate anatomy parts or targets.
+
+### Representative states
+
+| State             | Required invariant                                      | Allowed variation                                   |
+| ----------------- | ------------------------------------------------------- | --------------------------------------------------- |
+| Empty toolbar     | Outer chrome and named Toolbar remain rendered.         | No caller slot content.                             |
+| Two-lane layout   | Start and/or end content use the current flex layout.   | Either lane may be absent.                          |
+| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent.                 |
+| Vertical toolbar  | Toolbar semantics and target remain unchanged.          | Layout and keyboard movement use the vertical axis. |
+
+### Transformation and precedence order
+
+- No new slot, layout, edge-compensation, padding, or event precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Toolbar's current accessible name,
+orientation, roving-tabindex, keyboard-hint, caret-guard, or event-composition
+behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                               | Representation authority                  | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
+| Outer chrome     | Supplies the painted surface, padding, and selected boundaries around the row.   | `component:Section`                       | Supporting     | FR1, FR3           |
+| Toolbar          | Presents the named toolbar semantics and current two- or three-lane arrangement. | Current source, docs, and family contract | Prominent      | FR1, FR2, FR3      |
+
+The slot contents are caller-owned content inside Toolbar's layout. They do not
+become additional Toolbar-owned anatomy or targets.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Outer chrome": {
+    "delegatesTo": {"owner": "component:Section", "target": "section"}
+  },
+  "Toolbar": {"target": "toolbar"}
+}
+```
+
+## Family and system relationships
+
+- `family:layout-regions` owns the structural-region vocabulary and records
+  Toolbar as a Section-backed contextual action region.
+- `architecture:container-padding` owns the inherited inset and edge-compensation
+  geometry used by the composed Section and Toolbar.
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, and component delegation.
+- `architecture:public-component-api` owns the stable prop and slot surface; this
+  documentation adds no API.
+
+## Verification map
+
+| Contract            | Verification                                                    | Representative states                          | Mutation or failure expectation                                                                                      | Audit section           |
+| ------------------- | --------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `Toolbar.test.tsx` role, name, pass-through, and Section suites | Empty and populated Toolbar                    | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence.     | `audit:Toolbar/anatomy` |
+| FR2                 | `Toolbar.test.tsx` slot and child-count suites                  | Start-only, end-only, two-lane, and three-lane | Changing current slot presence or two-/three-lane structure fails focused assertions.                                | `audit:Toolbar/layout`  |
+| FR3                 | Toolbar and Section source plus their focused tests             | Variant, divider, size, and orientation states | Moving outer chrome ownership into Toolbar or moving toolbar semantics onto Section contradicts source and coverage. | `audit:Toolbar/theming` |
+| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                | Toolbar and delegated Section targets          | Runtime and documented target metadata drift fails target validation.                                                | `audit:Toolbar/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                   | Canonical anatomy and current local target     | Missing, extra, prefixed, or stale mappings fail repository validation.                                              | `audit:Toolbar/theming` |
+
+Existing tests assert the semantic row, slot structure, and Section composition.
+They do not prove computed inset or edge-compensation geometry for every parent
+padding state; this documentation does not claim that coverage.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, container-padding mechanics, keyboard algorithms, implementation steps,
+or system rules. It links to their owners.

package/src/Tooltip/Tooltip.doc.mjs

@@ -1,5 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Tooltip surface',
+    required: true,
+    description: 'Painted overlay surface that presents the tooltip.',
+  },
+  {
+    name: 'Tooltip text',
+    required: true,
+    description: 'Tooltip content rendered within the surface.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -110,6 +124,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
@@ -217,6 +232,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
@@ -233,6 +249,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [