@astryxdesign/core 0.1.8 → 0.1.9

package/src/TreeList/TreeList.test.tsx

@@ -14,6 +14,8 @@ import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TreeList} from './TreeList';
 import type {TreeListItemData} from './TreeListTypes';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 const simpleItems: TreeListItemData[] = [
   {id: 'a', label: 'Item A'},
@@ -393,6 +395,115 @@ describe('TreeList', () => {
     expect(screen.getByRole('tree')).toBeInTheDocument();
   });
 
+  // ===========================================================================
+  // Variant (guide lines)
+  // ===========================================================================
+
+  describe('variant', () => {
+    it('renders guide lines by default', () => {
+      const {container} = render(<TreeList items={nestedItemsExpanded} />);
+      expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+    });
+
+    it("variant='lineGuides' renders guide lines (explicit == default)", () => {
+      const {container} = render(
+        <TreeList items={nestedItemsExpanded} variant="lineGuides" />,
+      );
+      expect(container.querySelector('.astryx-tree-list-guide')).not.toBeNull();
+    });
+
+    it("variant='noGuides' renders NO guide lines", () => {
+      const {container} = render(
+        <TreeList items={nestedItemsExpanded} variant="noGuides" />,
+      );
+      expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+    });
+
+    it("variant='noGuides' preserves the tree structure and items", () => {
+      render(<TreeList items={nestedItemsExpanded} variant="noGuides" />);
+      // Rows, roles, and nesting are all intact — only the connectors are gone.
+      expect(screen.getByRole('tree')).toBeInTheDocument();
+      expect(screen.getAllByRole('treeitem')).toHaveLength(4);
+      expect(screen.getByText('Parent')).toBeInTheDocument();
+      expect(screen.getByText('Child 1')).toBeInTheDocument();
+      expect(screen.getByText('Child 2')).toBeInTheDocument();
+      expect(screen.getByText('Sibling')).toBeInTheDocument();
+    });
+
+    it("variant='noGuides' preserves per-level indentation on the rows", () => {
+      // Indentation lives on the row's marginLeft (not the guide element), so
+      // it must survive when the connectors are suppressed. A deeper row is
+      // indented more than a shallower one.
+      const {container} = render(
+        <TreeList items={deepItems} variant="noGuides" />,
+      );
+      const marginOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="margin-left"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      // Guides are gone…
+      expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
+      // …but each level still carries an inline margin-left, and the level
+      // multiplier grows with depth (0, 1, 2).
+      expect(marginOf('Root')).toContain('margin-left');
+      expect(marginOf('Mid')).toContain('margin-left');
+      expect(marginOf('Leaf')).toContain('margin-left');
+      const level = (text: string): number => {
+        const m = /calc\((\d+)/.exec(marginOf(text));
+        return m ? Number(m[1]) : NaN;
+      };
+      expect(level('Mid')).toBeGreaterThan(level('Root'));
+      expect(level('Leaf')).toBeGreaterThan(level('Mid'));
+    });
+  });
+
+  // ===========================================================================
+  // Guide theme target
+  // ===========================================================================
+
+  describe('guide theme target', () => {
+    it('renders the astryx-tree-list-guide target on the connector lines', () => {
+      const {container} = render(<TreeList items={nestedItemsExpanded} />);
+      const guide = container.querySelector('.astryx-tree-list-guide');
+      // A dedicated, stable target so a theme can recolor or hide the guides
+      // without hiding the built-in connectors and reimplementing them.
+      expect(guide).not.toBeNull();
+    });
+
+    it('exposes tree-list-guide as a themeable defineTheme target', () => {
+      // jsdom cannot resolve the @layer cascade, so the generated CSS is what
+      // proves a theme override reaches the guide element.
+      const theme = defineTheme({
+        name: 'tree-list-guide-test',
+        components: {
+          'tree-list-guide': {
+            base: {backgroundColor: 'var(--color-accent)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-guide {');
+      expect(css).toContain('background-color: var(--color-accent)');
+    });
+
+    it('lets a theme hide the guides via display: none on the target', () => {
+      // Hiding the guides is done through the theme target, not a prop — the
+      // theme rule lands in @layer astryx-theme, above StyleX's base layer.
+      const theme = defineTheme({
+        name: 'tree-list-guide-hidden-test',
+        components: {
+          'tree-list-guide': {
+            base: {display: 'none'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-guide {');
+      expect(css).toContain('display: none');
+    });
+  });
+
   // ===========================================================================
   // xds class name
   // ===========================================================================
@@ -403,6 +514,127 @@ describe('TreeList', () => {
     expect(root.className).toContain('astryx-tree-list');
   });
 
+  // ===========================================================================
+  // Chevron theme target
+  // ===========================================================================
+
+  describe('chevron theme target', () => {
+    it('renders the astryx-tree-list-chevron target on the toggle button', () => {
+      render(<TreeList items={nestedItems} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+
+      // Dedicated, stable theme target on the expand/collapse control, so a
+      // theme can restyle the chevron without a fragile [data-tree-toggle] hook.
+      expect(toggle).toHaveClass('astryx-tree-list-chevron');
+      // Open/closed state is reflected so a theme can target each state alone.
+      expect(toggle).toHaveAttribute('data-state', 'collapsed');
+    });
+
+    it('reflects the expanded state on the toggle when open', () => {
+      render(<TreeList items={nestedItemsExpanded} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+
+      expect(toggle).toHaveClass('astryx-tree-list-chevron');
+      expect(toggle).toHaveAttribute('data-state', 'expanded');
+    });
+
+    it('keeps the functional data-tree-toggle hook alongside the new target', () => {
+      // The theme target is additive — the toggle is still a real <button> and
+      // still carries the functional activation attribute TreeList relies on.
+      render(<TreeList items={nestedItems} />);
+      const toggle = screen
+        .getByText('Parent')
+        .closest('li')!
+        .querySelector('[data-tree-toggle]')!;
+      expect(toggle.tagName).toBe('BUTTON');
+      expect(toggle).toHaveAttribute('data-tree-toggle');
+    });
+
+    it('exposes tree-list-chevron as a themeable defineTheme target', () => {
+      // The generated CSS is what proves the target is reachable by a theme:
+      // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+      // above and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'tree-list-chevron-test',
+        components: {
+          'tree-list-chevron': {
+            base: {color: 'var(--color-accent)'},
+            'state:expanded': {color: 'var(--color-text-primary)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-chevron {');
+      expect(css).toContain('color: var(--color-accent)');
+      expect(css).toContain('.astryx-tree-list-chevron.expanded');
+      expect(css).toContain('color: var(--color-text-primary)');
+    });
+  });
+
+  // ===========================================================================
+  // Item label theme target
+  // ===========================================================================
+
+  describe('item label theme target', () => {
+    it('renders the astryx-tree-list-item-label target on the label span', () => {
+      render(<TreeList items={simpleItems} />);
+      const label = screen.getByText('Item A');
+
+      // Dedicated, stable theme target on the label text, so a theme can style
+      // just the label without a fragile `button:not([data-tree-toggle]) > span`
+      // structural selector.
+      expect(label).toHaveClass('astryx-tree-list-item-label');
+      // A non-selected item's label carries no selected reflection.
+      expect(label).not.toHaveAttribute('data-selected');
+    });
+
+    it('reflects the selected state on the selected item label', () => {
+      render(
+        <TreeList items={[{id: 'a', label: 'Item A', isSelected: true}]} />,
+      );
+      const label = screen.getByText('Item A');
+      expect(label).toHaveClass('astryx-tree-list-item-label');
+      expect(label).toHaveAttribute('data-selected', 'selected');
+    });
+
+    it('keeps the label linked to its row via aria-labelledby', () => {
+      // The theme target is additive — the label still owns the id the
+      // interactive row references for its accessible name.
+      render(
+        <TreeList items={[{id: 'a', label: 'Item A', onClick: () => {}}]} />,
+      );
+      const label = screen.getByText('Item A');
+      const action = screen.getByRole('button');
+      expect(action).toHaveAttribute('aria-labelledby', label.id);
+    });
+
+    it('exposes tree-list-item-label as a themeable defineTheme target', () => {
+      // The generated CSS is what proves the target is reachable by a theme:
+      // jsdom cannot resolve the @layer cascade, so the DOM-class assertions
+      // above and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'tree-list-item-label-test',
+        components: {
+          'tree-list-item-label': {
+            base: {color: 'var(--color-text-primary)'},
+            selected: {fontWeight: 'var(--font-weight-bold)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list-item-label {');
+      expect(css).toContain('color: var(--color-text-primary)');
+      expect(css).toContain('.astryx-tree-list-item-label.selected');
+      expect(css).toContain('font-weight: var(--font-weight-bold)');
+    });
+  });
+
   // ===========================================================================
   // APG structural ARIA (aria-level / aria-posinset / aria-setsize)
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -21,7 +21,11 @@ import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {TreeListItem} from './TreeListItem';
-import type {TreeListItemData, TreeListDensity} from './TreeListTypes';
+import type {
+  TreeListItemData,
+  TreeListDensity,
+  TreeListVariant,
+} from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
 import {useTreeFocus} from '../hooks/useTreeFocus';
 
@@ -29,7 +33,7 @@ import {useTreeFocus} from '../hooks/useTreeFocus';
 // Types
 // =============================================================================
 
-export {type TreeListDensity} from './TreeListTypes';
+export {type TreeListDensity, type TreeListVariant} from './TreeListTypes';
 
 export interface TreeListProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
@@ -50,6 +54,16 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
    */
   density?: TreeListDensity;
 
+  /**
+   * Visual treatment of the hierarchy guide (connector) lines.
+   * - `lineGuides`: connector lines between parent and child rows
+   * - `noGuides`: no connector lines; indentation alone conveys nesting
+   *
+   * Orthogonal to `density` (which controls spacing) — the two compose.
+   * @default 'lineGuides'
+   */
+  variant?: TreeListVariant;
+
   /**
    * Header content rendered above the tree list.
    * Semantically associated via aria-labelledby.
@@ -156,6 +170,7 @@ function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
 export function TreeList({
   items,
   density = 'balanced',
+  variant = 'lineGuides',
   header,
   xstyle,
   className,
@@ -275,6 +290,7 @@ export function TreeList({
           isExpanded={isExpanded}
           onToggle={handleToggle}
           density={density}
+          variant={variant}
           renderedChildren={renderedChildren}
           posInSet={index + 1}
           setSize={items.length}

package/src/TreeList/TreeListBranches.tsx

@@ -16,6 +16,7 @@
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
 
 const LINE_WIDTH = 1;
 
@@ -65,6 +66,11 @@ interface TreeListBranchesProps {
 /**
  * Renders vertical lines showing parent-child relationships in the tree.
  * Positioned in a full-height container to span the entire item including children.
+ *
+ * The line element carries the stable `astryx-tree-list-guide` theme target so a
+ * theme can recolor or hide the connectors via `defineTheme` (e.g.
+ * `backgroundColor` or `display: 'none'`) instead of hiding the built-in guides
+ * and reimplementing them.
  */
 export function TreeListBranches({
   ancestorsIsLast,
@@ -90,7 +96,10 @@ export function TreeListBranches({
                 },
               })}>
               <div
-                {...stylex.props(styles.verticalLine, styles.verticalFull)}
+                {...mergeProps(
+                  themeProps('tree-list-guide'),
+                  stylex.props(styles.verticalLine, styles.verticalFull),
+                )}
               />
             </div>
           )
@@ -103,7 +112,12 @@ export function TreeListBranches({
               left: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
             },
           })}>
-          <div {...stylex.props(styles.verticalLine, styles.verticalFull)} />
+          <div
+            {...mergeProps(
+              themeProps('tree-list-guide'),
+              stylex.props(styles.verticalLine, styles.verticalFull),
+            )}
+          />
         </div>
       )}
     </>

package/src/TreeList/TreeListItem.tsx

@@ -28,7 +28,7 @@ import {getIcon} from '../Icon/globalIconRegistry';
 import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
-import type {TreeListDensity} from './TreeListTypes';
+import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
@@ -268,6 +268,12 @@ export interface TreeListItemInternalProps {
   isExpanded: boolean;
   onToggle?: (id: string) => void;
   density: TreeListDensity;
+  /**
+   * Guide-line visual treatment. `noGuides` suppresses the connector lines;
+   * indentation is unaffected (it lives on the row's `marginLeft`, not the
+   * guide element).
+   */
+  variant: TreeListVariant;
   /** Pre-rendered children subtree (rendered by the parent recursion) */
   renderedChildren?: ReactNode;
   /** 1-based position of this item among its siblings (aria-posinset). */
@@ -304,6 +310,7 @@ export function TreeListItem({
   isExpanded,
   onToggle,
   density,
+  variant,
   renderedChildren,
   posInSet,
   setSize,
@@ -352,7 +359,20 @@ export function TreeListItem({
 
   const labelAndDescription = (
     <>
-      <span id={labelId} {...stylex.props(styles.label)}>
+      <span
+        id={labelId}
+        {...mergeProps(
+          // Stable theme target for the item's label text. The label carries no
+          // themeable handle today, so a theme can only reach it through a
+          // fragile structural selector (a content button's first span). This
+          // adds an `astryx-tree-list-item-label` class and reflects the row's
+          // `selected` state so a theme can, e.g., bold just the selected
+          // item's label via `defineTheme`.
+          themeProps('tree-list-item-label', {
+            selected: isSelected ? 'selected' : null,
+          }),
+          stylex.props(styles.label),
+        )}>
         {label}
       </span>
       {description != null && (
@@ -394,12 +414,30 @@ export function TreeListItem({
         // a separate tab stop. Row-level Enter/Space forwards to this button.
         tabIndex={-1}
         onClick={handleToggle}
-        {...stylex.props(styles.chevronButton)}>
+        {...mergeProps(
+          // Stable theme target for the expand/collapse control. `data-tree-toggle`
+          // stays as the functional activation hook; this adds a themeable
+          // `astryx-tree-list-chevron` class and reflects the open/closed state so
+          // a theme can restyle the toggle (and each state) without a fragile
+          // `[data-tree-toggle]` selector.
+          themeProps('tree-list-chevron', {
+            state: isExpanded ? 'expanded' : 'collapsed',
+          }),
+          stylex.props(styles.chevronButton),
+        )}>
         {chevronIcon}
       </button>
     ) : (
       // Non-interactive chevron only when toggling is not wired up at all
-      <span {...stylex.props(styles.chevronContainer)}>{chevronIcon}</span>
+      <span
+        {...mergeProps(
+          themeProps('tree-list-chevron', {
+            state: isExpanded ? 'expanded' : 'collapsed',
+          }),
+          stylex.props(styles.chevronContainer),
+        )}>
+        {chevronIcon}
+      </span>
     )
   ) : null;
 
@@ -461,13 +499,15 @@ export function TreeListItem({
       data-tree-level={nestedLevel + 1}
       data-tree-disabled={isDisabled || undefined}
       {...stylex.props(styles.wrapper)}>
-      <div {...stylex.props(styles.treeBranches)}>
-        <TreeListBranches
-          ancestorsIsLast={ancestorsIsLast}
-          isLast={isLast}
-          nestedLevel={nestedLevel}
-        />
-      </div>
+      {variant !== 'noGuides' && (
+        <div {...stylex.props(styles.treeBranches)}>
+          <TreeListBranches
+            ancestorsIsLast={ancestorsIsLast}
+            isLast={isLast}
+            nestedLevel={nestedLevel}
+          />
+        </div>
+      )}
       <div {...stylex.props(styles.rowWrapper)}>
         <div
           {...mergeProps(

package/src/TreeList/TreeListTypes.ts

@@ -3,7 +3,7 @@
 /**
  * @file TreeListTypes.ts
  * @input Uses React types
- * @output Exports TreeListItemData, TreeListDensity types
+ * @output Exports TreeListItemData, TreeListDensity, TreeListVariant types
  * @position Type definitions; consumed by TreeList.tsx, TreeListItem.tsx, index.ts
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -16,6 +16,32 @@ import type {ReactNode} from 'react';
 /** Spacing density for tree list items. */
 export type TreeListDensity = 'compact' | 'balanced' | 'spacious';
 
+/**
+ * Extensible variant map for TreeList.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/TreeList' {
+ *   interface TreeListVariantMap {
+ *     'dotted': true;
+ *   }
+ * }
+ * ```
+ */
+export interface TreeListVariantMap {
+  lineGuides: true;
+  noGuides: true;
+}
+
+/**
+ * Visual treatment of the hierarchy guide (connector) lines. Extensible via
+ * module augmentation of TreeListVariantMap.
+ * - `lineGuides`: connector lines between parent and child rows (default)
+ * - `noGuides`: no connector lines; indentation alone conveys nesting
+ */
+export type TreeListVariant = keyof TreeListVariantMap;
+
 /** Recursive item configuration for TreeList. */
 export interface TreeListItemData {
   /** Unique identifier for the item. Used as React key and for expansion tracking. */

package/src/TreeList/index.ts

@@ -12,5 +12,5 @@
  */
 
 export {TreeList} from './TreeList';
-export type {TreeListProps, TreeListDensity} from './TreeList';
-export type {TreeListItemData} from './TreeListTypes';
+export type {TreeListProps, TreeListDensity, TreeListVariant} from './TreeList';
+export type {TreeListItemData, TreeListVariantMap} from './TreeListTypes';

package/src/authoring/doc.ts

@@ -130,9 +130,7 @@ export type AstryxGenericDocInput = AstryxBaseDocInput;
  * any code referring to the old name.
  */
 export type AstryxComponentDoc =
-  | AstryxComponentDocInput
-  | AstryxFunctionDocInput
-  | AstryxGenericDocInput;
+  AstryxComponentDocInput | AstryxFunctionDocInput | AstryxGenericDocInput;
 
 /**
  * Author a component doc. Stamp-only: returns the def with `type: 'component'`

package/src/docs-types.ts

@@ -669,6 +669,7 @@ export interface TranslationDoc {
  * @example
  * ```
  * { type: 'prose', text: 'Spacing tokens control gap and padding...' }
+ * { type: 'heading', level: 3, text: 'Examples' }
  * { type: 'code', lang: 'tsx', code: 'padding: spacingVars[...]' }
  * { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
  * { type: 'list', style: 'do', items: ['Use semantic tokens'] }
@@ -677,6 +678,7 @@ export interface TranslationDoc {
  */
 export type ContentBlock =
   | {type: 'prose'; text: string}
+  | {type: 'heading'; level: 3 | 4 | 5 | 6; text: string}
   | {type: 'code'; lang: string; code: string; label?: string}
   | {type: 'table'; headers: string[]; rows: string[][]}
   | {
@@ -729,6 +731,9 @@ export type TokenPreviewType =
 export interface ReferenceSection {
   /** Section title, e.g. "Spacing Tokens", "Light/Dark Mode" */
   title: string;
+  /** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's
+   *  category so sections can be grouped independently in the docsite nav. */
+  category?: string;
   /** Ordered content blocks. Mix prose, code, tables, and lists freely. */
   content: ContentBlock[];
   /** Preview type for token tables in this section. When set, the docsite