@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/TopNav/TopNavItem.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TopNav/TopNav.test.tsx
  * - /packages/core/src/TopNav/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
@@ -131,6 +131,8 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   isSelected?: boolean;
   /**
    * Whether the nav item is disabled.
+   * A disabled item renders as a plain anchor without an href (and without
+   * target), so it cannot navigate and is removed from the tab order.
    * @default false
    */
   isDisabled?: boolean;
@@ -157,6 +159,15 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   size?: NavItemSize;
 }
 
+/**
+ * Click handler for disabled items. The disabled anchor renders without an
+ * href, so there is no navigation to block in practice; preventDefault is a
+ * defensive guard against synthetic/programmatic clicks.
+ */
+function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
+  event.preventDefault();
+}
+
 /**
  * A navigation item for use within TopNav startContent.
  *
@@ -178,6 +189,9 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
  */
 export function TopNavItem({
   as,
+  href,
+  target,
+  onClick,
   label,
   isSelected = false,
   isDisabled = false,
@@ -195,22 +209,34 @@ export function TopNavItem({
   const renderMode = useTopNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
 
+  // A disabled item renders as a plain <a> with no href: an href-less anchor
+  // is not focusable and exposes no link affordance, so programmatic focus +
+  // Enter, AT activation commands, and middle-click cannot navigate or fire
+  // the consumer onClick. The router LinkComponent is deliberately skipped —
+  // a disabled item performs no navigation, and custom router links may
+  // require a live href. target is omitted with the href. (Mirrors the
+  // disabled paths of Link and SideNavItem.)
+  const Root = isDisabled ? 'a' : LinkComponent;
+
   // =========================================================================
   // Drawer mode — render as a SideNavItem-style vertical list element
   // =========================================================================
   if (renderMode === 'drawer') {
-    const handleDrawerClick = (e: React.MouseEvent) => {
+    const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       if (isDisabled) {
+        preventDefaultClick(e);
         return;
       }
       // Forward the original onClick if present
-      (props as {onClick?: (e: React.MouseEvent) => void}).onClick?.(e);
+      onClick?.(e);
       closeMobileNav();
     };
 
     return (
-      <LinkComponent
+      <Root
         ref={ref}
+        href={isDisabled ? undefined : href}
+        target={isDisabled ? undefined : target}
         aria-label={isIconOnly ? label : undefined}
         aria-current={isSelected ? 'page' : undefined}
         aria-disabled={isDisabled || undefined}
@@ -235,7 +261,7 @@ export function TopNavItem({
         onClick={handleDrawerClick}>
         {icon}
         {!isIconOnly && (children ?? label)}
-      </LinkComponent>
+      </Root>
     );
   }
 
@@ -244,8 +270,11 @@ export function TopNavItem({
   // =========================================================================
 
   return (
-    <LinkComponent
+    <Root
       ref={ref}
+      href={isDisabled ? undefined : href}
+      target={isDisabled ? undefined : target}
+      onClick={isDisabled ? preventDefaultClick : onClick}
       aria-label={isIconOnly ? label : undefined}
       aria-current={isSelected ? 'page' : undefined}
       aria-disabled={isDisabled || undefined}
@@ -267,7 +296,7 @@ export function TopNavItem({
       {...props}>
       {icon}
       {!isIconOnly && (children ?? label)}
-    </LinkComponent>
+    </Root>
   );
 }
 

package/src/TopNav/TopNavMegaMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenu',

package/src/TopNav/TopNavMegaMenu.tsx

@@ -20,7 +20,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {
@@ -123,6 +123,18 @@ const styles = stylex.create({
       transform: 'translateY(-4px)',
     },
   },
+  // Clamp the anchored layer to the space available below the nav so a tall
+  // menu never runs off the bottom of the viewport. The layer is positioned
+  // with position-area: self-block-end, so its containing block spans from
+  // the nav's block-end to the viewport edge — 100% is exactly that space.
+  // The layer is a flex column so panelContainer can shrink and scroll its
+  // own content, keeping the surface radius/shadow static at the edges.
+  // Internal scroll is a stopgap until the mobile bottom-sheet lands.
+  panelViewportFit: {
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
+  },
   // Visual styles for the panel content container.
   panelContainer: {
     backgroundColor: colorVars['--color-background-popover'],
@@ -132,6 +144,11 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-low'],
     overflow: 'hidden',
+    // Allow the container to shrink inside the height-clamped layer so its
+    // content (panelContent) can scroll rather than overflow the viewport.
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
   },
   panelContent: {
     display: 'flex',
@@ -139,7 +156,14 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-6'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-3'],
-    maxWidth: 960,
+    // Clamp to the viewport (minus a gutter) so the anchored panel never
+    // overflows the screen edge on narrow viewports; caps at 960px otherwise.
+    maxWidth: `min(960px, calc(100dvw - ${spacingVars['--spacing-4']}))`,
+    boxSizing: 'border-box',
+    // Scroll internally when the menu is taller than the available space
+    // below the nav (paired with panelViewportFit on the layer).
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
   },
   menuWrapper: {
     flexGrow: 2,
@@ -484,7 +508,7 @@ function DefaultMegaMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.panelAnimation,
+          xstyle: [styles.panelAnimation, styles.panelViewportFit],
         },
       )}
     </>

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenuFeaturedCard',
@@ -27,7 +27,7 @@ export const docs = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) — usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden), usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
     },
     {
       name: 'linkLabel',

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -15,7 +15,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {type ReactNode} from 'react';

package/src/TopNav/TopNavMegaMenuItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenuItem',

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {type ReactNode} from 'react';

package/src/TopNav/TopNavMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMenu',

package/src/TopNav/TopNavMenu.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/TopNavMenu.test.tsx
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {

package/src/TreeList/TreeList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TreeList',
@@ -30,6 +30,9 @@ export const docs = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {
@@ -91,7 +94,7 @@ export const docs = {
 // See .context/decisions/dense-compression-protocol.md
 // -------------------------------------------------------
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'TreeList',
   displayName: 'Tree List',
@@ -104,6 +107,9 @@ export const docsZh = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {
@@ -159,7 +165,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 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.',

package/src/TreeList/TreeList.test.tsx

@@ -431,26 +431,29 @@ describe('TreeList', () => {
     });
 
     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.
+      // Indentation lives on the row's margin-inline-start (not the guide
+      // element), so it must survive when the connectors are suppressed. The
+      // per-row distance is published as the `--_tree-indent` custom property
+      // (not an inline longhand — see #4308), so the theme layer can override
+      // the `margin-inline-start` declaration. A deeper row is indented more
+      // than a shallower one.
       const {container} = render(
         <TreeList items={deepItems} variant="noGuides" />,
       );
-      const marginOf = (text: string): string => {
+      const indentOf = (text: string): string => {
         const li = screen.getByText(text).closest('li')!;
-        const styled = li.querySelector('[style*="margin-left"]');
+        const styled = li.querySelector('[style*="--_tree-indent"]');
         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
+      // …but each level still publishes an indent distance, 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');
+      expect(indentOf('Root')).toContain('--_tree-indent');
+      expect(indentOf('Mid')).toContain('--_tree-indent');
+      expect(indentOf('Leaf')).toContain('--_tree-indent');
       const level = (text: string): number => {
-        const m = /calc\((\d+)/.exec(marginOf(text));
+        const m = /calc\((\d+)/.exec(indentOf(text));
         return m ? Number(m[1]) : NaN;
       };
       expect(level('Mid')).toBeGreaterThan(level('Root'));
@@ -504,6 +507,43 @@ describe('TreeList', () => {
     });
   });
 
+  // ===========================================================================
+  // Indent lever (--tree-list-indent)
+  // ===========================================================================
+
+  describe('indent lever', () => {
+    it('lets a theme retune the indent step via the tree-list target', () => {
+      // The per-level step is a public, themeable var (default --spacing-4) set
+      // on the tree-list root, so a theme can retune the indent metric (e.g. to
+      // --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
+      // so the generated CSS is what proves the override reaches the lever.
+      const theme = defineTheme({
+        name: 'tree-list-indent-test',
+        components: {
+          'tree-list': {
+            base: {'--tree-list-indent': 'var(--spacing-5)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list {');
+      expect(css).toContain('--tree-list-indent: var(--spacing-5)');
+    });
+
+    it('rows consume the indent step in their published indent distance', () => {
+      // Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
+      // so retuning the step scales every level uniformly.
+      render(<TreeList items={deepItems} variant="noGuides" />);
+      const indentOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="--_tree-indent"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
+      expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
+    });
+  });
+
   // ===========================================================================
   // xds class name
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/TreeList/TreeList.doc.mjs
  * - /packages/core/src/TreeList/index.ts
  * - /apps/storybook/stories/TreeList.stories.tsx
- * - /packages/cli/templates/blocks/components/TreeList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TreeList/ (showcase blocks)
  */
 
 import {useId, useState, useMemo, useCallback, type ReactNode} from 'react';
@@ -83,6 +83,11 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
 const styles = stylex.create({
   root: {
     position: 'relative',
+    // Per-level indentation step. Public, themeable lever: a theme can retune
+    // the tree's indent metric (e.g. to `var(--spacing-5)`) via `defineTheme`
+    // on the `tree-list` target, and both the row margins (TreeListItem) and
+    // the guide-line offsets (TreeListBranches) read it so they stay aligned.
+    '--tree-list-indent': spacingVars['--spacing-4'],
   },
   list: {
     margin: 0,

package/src/TreeList/TreeListBranches.tsx

@@ -10,7 +10,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TreeList/TreeListItem.tsx
- * - /packages/cli/templates/blocks/components/TreeList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TreeList/ (showcase blocks)
  */
 
 import * as stylex from '@stylexjs/stylex';
@@ -26,8 +26,10 @@ const LINE_WIDTH = 1;
  */
 const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-0-5']})`;
 
-/** Per-level indent width, matching --spacing-4 (16px). */
-const LEVEL_INDENT = spacingVars['--spacing-4'];
+/** Per-level indent width. Reads the public, themeable `--tree-list-indent`
+ * lever set on the tree-list root (default `--spacing-4`, 16px), so the guide
+ * lines stay aligned with the row indent when a theme retunes the step. */
+const LEVEL_INDENT = 'var(--tree-list-indent)';
 
 const styles = stylex.create({
   container: {
@@ -37,10 +39,10 @@ const styles = stylex.create({
   },
   verticalLine: {
     borderRadius: 1,
-    left: 0,
+    insetInlineStart: 0,
     margin: 'auto',
     position: 'absolute',
-    right: 0,
+    insetInlineEnd: 0,
     width: LINE_WIDTH,
     backgroundColor: colorVars['--color-border-emphasized'],
   },
@@ -92,7 +94,7 @@ export function TreeListBranches({
               key={level}
               {...mergeProps(stylex.props(styles.container), {
                 style: {
-                  left: branchOffset,
+                  insetInlineStart: branchOffset,
                 },
               })}>
               <div
@@ -109,7 +111,7 @@ export function TreeListBranches({
         <div
           {...mergeProps(stylex.props(styles.container), {
             style: {
-              left: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
+              insetInlineStart: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
             },
           })}>
           <div

package/src/TreeList/TreeListItem.tsx

@@ -11,7 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TreeList/TreeList.doc.mjs
  * - /packages/core/src/TreeList/TreeList.tsx
- * - /packages/cli/templates/blocks/components/TreeList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TreeList/ (showcase blocks)
  */
 
 import {useId, useMemo, type ReactNode} from 'react';
@@ -25,7 +25,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {getIcon} from '../Icon/globalIconRegistry';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
@@ -82,6 +82,12 @@ const styles = stylex.create({
     position: 'relative',
     boxSizing: 'border-box',
     textAlign: 'start',
+    // Per-level indent. Declared here (not inline) so it lives in
+    // `@layer astryx-base` and the theme layer can override it in normal
+    // cascade order — an inline longhand would outrank every layer. The row
+    // publishes only the computed distance as `--_tree-indent`; the per-level
+    // step is the public `--tree-list-indent` lever (see TreeList `root`).
+    marginInlineStart: 'var(--_tree-indent, 0px)',
   },
   interactive: {
     cursor: 'pointer',
@@ -246,6 +252,11 @@ const descriptionSizeStyles = stylex.create({
   },
 });
 
+// `CSSProperties` has no index signature for custom properties, so the row's
+// inline style — which publishes the computed indent distance as the private
+// `--_tree-indent` — needs this augmentation to typecheck.
+type IndentStyle = React.CSSProperties & Record<'--_tree-indent', string>;
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -353,9 +364,18 @@ export function TreeListItem({
     return undefined;
   }, [onClick, hasChildren, onToggle, id, isDisabled]);
 
-  const computedMarginLeft = hasChildren
-    ? `calc(${nestedLevel} * ${spacingVars['--spacing-4']})`
-    : `calc(${nestedLevel} * ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  // Per-level indent distance. The per-level step is the public, themeable
+  // `--tree-list-indent` lever (default `--spacing-4`, set on the tree-list
+  // root). Leaves add a fixed chevron-column offset (chevron width + gap) so
+  // their labels line up with sibling parents' labels; that offset is tied to
+  // the chevron's own dimensions, not the indent step, so it does not scale
+  // with the lever. Published as the private `--_tree-indent` and consumed by
+  // `contentWrapper`'s stylesheet `margin-inline-start` (kept out of the inline
+  // style so the theme layer can override it — see #4308).
+  const indentDistance = hasChildren
+    ? `calc(${nestedLevel} * var(--tree-list-indent))`
+    : `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  const indentStyle: IndentStyle = {'--_tree-indent': indentDistance};
 
   const labelAndDescription = (
     <>
@@ -386,12 +406,14 @@ export function TreeListItem({
   );
 
   const chevronIcon = (
-    <span
-      {...stylex.props(
-        styles.chevronSvg,
-        isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
-      )}>
-      {getIcon('chevronRight')}
+    <span {...stylex.props(rtlStyles.mirror)}>
+      <span
+        {...stylex.props(
+          styles.chevronSvg,
+          isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
+        )}>
+        {getIcon('chevronRight')}
+      </span>
     </span>
   );
 
@@ -527,7 +549,7 @@ export function TreeListItem({
               isSelected && styles.selected,
             ),
           )}
-          style={{marginLeft: computedMarginLeft}}
+          style={indentStyle}
           onClick={handleClick}>
           {innerContent}
         </div>

package/src/TreeList/TreeListTypes.ts

@@ -12,28 +12,11 @@
  */
 
 import type {ReactNode} from 'react';
+import type {TreeListVariantMap} from './index';
 
 /** 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.

package/src/TreeList/index.ts

@@ -11,6 +11,24 @@
  * SYNC: When modified, update /packages/core/src/TreeList/TreeList.doc.mjs
  */
 
+/**
+ * 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;
+}
+
 export {TreeList} from './TreeList';
 export type {TreeListProps, TreeListDensity, TreeListVariant} from './TreeList';
-export type {TreeListItemData, TreeListVariantMap} from './TreeListTypes';
+export type {TreeListItemData} from './TreeListTypes';

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'BaseTypeahead',