@astryxdesign/core 0.1.7-canary.04cd8f7 → 0.1.7-canary.1055df2

package/README.md

@@ -13,14 +13,16 @@ Core UI components, theme system, and utilities for the Astryx design system. Fo
 
 ## Component Docs
 
-Look up any component's full API (props, types, best practices, and theming):
+Look up any component's full API (props, variants, examples, best practices, and theming) via the Astryx CLI:
 
 ```bash
-node node_modules/@astryxdesign/core/docs.mjs Button        # full docs for a component
-node node_modules/@astryxdesign/core/docs.mjs --list         # list all components
-node node_modules/@astryxdesign/core/docs.mjs --list --brief  # brief summaries
+npx @astryxdesign/cli init                   # one-time: writes the component guide into AGENTS.md / CLAUDE.md
+npx @astryxdesign/cli component Button        # full docs for a component
+npx @astryxdesign/cli component --list        # list all components
 ```
 
+> Use the scoped `@astryxdesign/cli` to run without installing; bare `npx astryx` only resolves once the CLI is a dependency.
+
 ## Page Layouts
 
 Building a full page? Start with a template rather than composing from scratch.

package/dist/Avatar/Avatar.d.ts

@@ -13,9 +13,13 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
-type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
+type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 /**
  * Numeric size options (in pixels)
  */
@@ -52,8 +56,9 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
      */
     name?: string;
     /**
-     * The size of the avatar.
-     * @default 'small'
+     * The size of the avatar. A named size (`xsm` 20px, `sm` 24px, `md` 36px,
+     * `lg` 48px, `xl` 128px) or a specific pixel value.
+     * @default 'md'
      */
     size?: AvatarSize;
     /**
@@ -75,7 +80,7 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */

package/dist/Avatar/Avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsC5C;;GAEG;AACH,KAAK,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExE;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAqFD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAc,EACd,GAAG,EACH,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwFb;yBArGe,MAAM"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../src/Avatar/Avatar.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsC5C;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,KAAK,iBAAiB,GACpB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAgBpD;AAqFD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAsCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EACrB,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,WAAW,EACX,IAAI,EACJ,IAAW,EACX,GAAG,EACH,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,+BAwFb;yBArGe,MAAM"}

package/dist/Avatar/Avatar.js

@@ -50,7 +50,11 @@ const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 const INITIALS_FONT_SIZE_RATIO = 0.4;
 
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
 
 /**
@@ -69,15 +73,15 @@ export function resolveSize(size) {
     return size;
   }
   switch (size) {
-    case 'tiny':
+    case 'xsm':
       return 20;
-    case 'xsmall':
+    case 'sm':
       return 24;
-    case 'small':
+    case 'md':
       return 36;
-    case 'medium':
+    case 'lg':
       return 48;
-    case 'large':
+    case 'xl':
       return 128;
   }
 }
@@ -223,7 +227,7 @@ function DefaultIcon({
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */
@@ -232,7 +236,7 @@ export function Avatar({
   'data-testid': testId,
   fallbackSrc,
   name,
-  size = 'small',
+  size = 'md',
   src,
   status,
   xstyle,

package/dist/Avatar/AvatarSizeContext.d.ts

@@ -2,7 +2,7 @@
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export declare const AvatarSizeContext: import("react").Context<number>;
 //# sourceMappingURL=AvatarSizeContext.d.ts.map

package/dist/Avatar/AvatarSizeContext.js

@@ -17,7 +17,7 @@ import { createContext } from 'react';
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export const AvatarSizeContext = /*#__PURE__*/createContext(36);
 AvatarSizeContext.displayName = 'AvatarSizeContext';

package/dist/Avatar/AvatarStatusDot.d.ts

@@ -76,12 +76,12 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/dist/Avatar/AvatarStatusDot.js

@@ -148,12 +148,12 @@ const variantStyleMap = {
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/dist/AvatarGroup/AvatarGroup.d.ts

@@ -27,7 +27,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
     children: ReactNode;
     /**
      * Size applied to all avatars via context.
-     * @default 'small'
+     * @default 'md'
      */
     size?: AvatarSize;
     /**
@@ -45,7 +45,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/AvatarGroup/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AASvD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAc,EACd,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA6B9B;yBAvCe,WAAW"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroup.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAc,KAAK,UAAU,EAAC,MAAM,WAAW,CAAC;AASvD,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjE,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,gBAAgB,GAAG,SAAS,CA6B9B;yBAvCe,WAAW"}

package/dist/AvatarGroup/AvatarGroup.js

@@ -44,7 +44,7 @@ const styles = {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}
@@ -54,7 +54,7 @@ const styles = {
  */
 export function AvatarGroup({
   children,
-  size = 'small',
+  size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   xstyle,

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts

@@ -33,7 +33,7 @@ export interface AvatarGroupOverflowProps extends Omit<BaseProps<HTMLElement>, '
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA6DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}
+{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAW5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA4ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}

package/dist/AvatarGroup/AvatarGroupOverflow.js

@@ -15,7 +15,7 @@
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { colorVars, typographyVars, fontWeightVars, radiusVars } from "../theme/tokens.stylex.js";
+import { colorVars, typographyVars, fontWeightVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { useAvatarGroup } from "./AvatarGroupContext.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -37,13 +37,14 @@ const styles = {
     kMzoRj: "xdh2fpr",
     ksu8eU: "x1y0btm7",
     kVAM5u: "x1touxvs",
-    kB7OPa: "x1afcbsf",
+    kB7OPa: "x9f619",
+    kg3NbH: "xf314gf",
     kKwaWg: "x14bno8m",
     $$css: true
   },
   button: {
     kkrTdU: "x1ypdohk",
-    kmVPX3: "x1717udv",
+    k8WAf4: "xt970qd",
     kKwaWg: "x14bno8m xbfmc0r x1nocapi",
     kI3sdo: "x1a2a7pz x17nn4n9",
     kInvED: "x7s97pk",
@@ -55,26 +56,27 @@ const styles = {
   }
 };
 const _temp = {
-  kGuDYH: "xdmh292",
+  k7Eaqz: "xkj4a21",
+  kZKoxP: "x16ye13r",
   "$$css": true
 };
 const _temp2 = {
+  kGuDYH: "xdmh292",
+  "$$css": true
+};
+const _temp3 = {
   "--_avatar-group-overlap": "xlz5hwt",
   "$$css": true
 };
 const dynamicStyles = {
-  size: s => [{
-    kzqmXN: s != null ? "x5lhr3w" : s,
-    kZKoxP: s != null ? "x16ye13r" : s,
-    $$css: true
-  }, {
-    "--x-width": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s),
-    "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s)
+  size: s => [_temp, {
+    "--x-minWidth": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s + BORDER_WIDTH * 2),
+    "--x-height": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s + BORDER_WIDTH * 2)
   }],
-  fontSize: s => [_temp, {
+  fontSize: s => [_temp2, {
     "--x-fontSize": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(s * OVERFLOW_FONT_RATIO)
   }],
-  overlap: offset => [_temp2, {
+  overlap: offset => [_temp3, {
     "--x---_avatar-group-overlap": `${offset}px` != null ? `${offset}px` : undefined
   }]
 };
@@ -85,7 +87,7 @@ const dynamicStyles = {
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/dist/Carousel/Carousel.d.ts

@@ -3,8 +3,9 @@
  * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
  * @output Exports Carousel component
  * @position Horizontal scroll container with fade-edge overflow indication,
- *   optional prev/next buttons on the top layer, scroll-snap, and a 1px
- *   visual bleed allowance for child selection indicators.
+ *   optional prev/next buttons on the top layer, scroll-snap, a 1px
+ *   visual bleed allowance for child selection indicators, and Shift + wheel
+ *   mapping so mouse users can scroll horizontally.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA2C,MAAM,OAAO,CAAC;AAc/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAmJf;yBAjKe,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAC,KAAK,SAAS,EAA2C,MAAM,OAAO,CAAC;AAc/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BA6Kf;yBA3Le,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -7,8 +7,9 @@
  * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
  * @output Exports Carousel component
  * @position Horizontal scroll container with fade-edge overflow indication,
- *   optional prev/next buttons on the top layer, scroll-snap, and a 1px
- *   visual bleed allowance for child selection indicators.
+ *   optional prev/next buttons on the top layer, scroll-snap, a 1px
+ *   visual bleed allowance for child selection indicators, and Shift + wheel
+ *   mapping so mouse users can scroll horizontally.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Carousel/index.ts (exports)
@@ -234,6 +235,34 @@ export function Carousel({
     scrollElRef.current = el;
     scrollRef(el);
   }, [scrollRef]);
+
+  // Map Shift + vertical wheel to horizontal scroll. Trackpads emit
+  // horizontal deltas natively, but a standard mouse only produces deltaY —
+  // so mouse users can't wheel-scroll a horizontal container. Shift + wheel
+  // is the long-established convention for horizontal scroll containers; we
+  // honor it by translating the vertical delta into a horizontal scroll.
+  //
+  // Only kicks in when Shift is held and the wheel is purely vertical
+  // (deltaX === 0), so native trackpad horizontal scrolling is untouched.
+  const handleWheel = useCallback(event => {
+    if (!event.shiftKey || event.deltaY === 0 || event.deltaX !== 0) {
+      return;
+    }
+    const el = scrollElRef.current;
+    if (!el) {
+      return;
+    }
+    // Nothing to scroll horizontally — let the event fall through so the page
+    // can scroll as it normally would.
+    if (el.scrollWidth <= el.clientWidth) {
+      return;
+    }
+    event.preventDefault();
+    el.scrollBy({
+      left: event.deltaY,
+      behavior: 'auto'
+    });
+  }, []);
   const scrollBy = useCallback(direction => {
     const el = scrollElRef.current;
     if (!el) {
@@ -271,6 +300,7 @@ export function Carousel({
     children: [/*#__PURE__*/_jsx("div", {
       ref: composedRef,
       tabIndex: 0,
+      onWheel: handleWheel,
       ...stylex.props(styles.scroller, gapStyles[gap], padding != null && paddingStyles[padding], hasSnap && styles.snap, fadeStyle),
       children: Children.map(children, child => /*#__PURE__*/_jsx("div", {
         ...{

package/dist/Chat/ChatMessage.d.ts

@@ -46,7 +46,7 @@ export interface ChatMessageProps extends BaseProps<HTMLElement> {
  *
  * @example
  * ```
- * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="small" />}>
+ * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="md" />}>
  *   <ChatMessageBubble>Hello!</ChatMessageBubble>
  *   <ChatMessageMetadata timestamp="2:30 PM" />
  * </ChatMessage>

package/dist/Chat/ChatMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BAyFlB;yBAtGe,WAAW"}
+{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BA2FlB;yBAxGe,WAAW"}

package/dist/Chat/ChatMessage.js

@@ -122,7 +122,7 @@ const styles = {
  *
  * @example
  * ```
- * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="small" />}>
+ * <ChatMessage sender="assistant" name="Navi" avatar={<Avatar name="Navi" size="md" />}>
  *   <ChatMessageBubble>Hello!</ChatMessageBubble>
  *   <ChatMessageMetadata timestamp="2:30 PM" />
  * </ChatMessage>

package/dist/Icon/Icon.d.ts

@@ -140,6 +140,31 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
      * @default 'md'
      */
     size?: IconSize;
+    /**
+     * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
+     * its own — a standalone status glyph or an icon-only indicator with no
+     * adjacent text conveying the same information. Providing it exposes the icon
+     * to assistive tech as `role="img"` with this string as the accessible name
+     * (via `aria-label`) and drops the default `aria-hidden="true"`.
+     *
+     * Omit it (the default) for decorative icons — the common case, e.g. an icon
+     * beside a text label — and the icon stays hidden from assistive tech
+     * (`aria-hidden="true"`). An empty string (`''`) is treated the same as
+     * omitting it (decorative), since an empty accessible name is meaningless.
+     *
+     * Don't set `label` when an interactive parent (Button, IconButton, link)
+     * already names the control — that produces a duplicate announcement.
+     *
+     * @example
+     * ```
+     * // Meaningful, standalone icon
+     * <Icon icon="success" label="Completed" />
+     *
+     * // Decorative icon (default) — omit label
+     * <Icon icon="search" />
+     * ```
+     */
+    label?: string;
 }
 /**
  * Renders an icon from the icon registry or a custom SVG component.
@@ -149,7 +174,7 @@ export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'
  * <Icon icon="close" size="md" color="primary" />
  * ```
  */
-export declare function Icon({ icon, color, size, ref, ...props }: IconProps): React.JSX.Element;
+export declare function Icon({ icon, color, size, label, ref, ...props }: IconProps): React.JSX.Element;
 export declare namespace Icon {
     var displayName: string;
 }

package/dist/Icon/Icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAyCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBA0BX;yBAhCe,IAAI;;;AAiFpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}
+{"version":3,"file":"Icon.d.ts","sourceRoot":"","sources":["../../src/Icon/Icon.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,OAAO,CAAC;AAC/D,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAqBnD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2Df,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;EAiBd,CAAC;AAyCH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,WAAW,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,IAAI,CACrC,QAAQ,CAAC,aAAa,CAAC,EACvB,KAAK,GAAG,OAAO,CAChB;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,EACnB,IAAI,EACJ,KAAiB,EACjB,IAAW,EACX,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,SAAS,qBAkCX;yBAzCe,IAAI;;;AA4FpB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,QAAQ,EAChC,KAAK,CAAC,EAAE;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAC,GAC3C,KAAK,CAAC,SAAS,CAYjB"}

package/dist/Icon/Icon.js

@@ -205,6 +205,26 @@ const spanSizeStyles = {
  * Extends SVGProps to allow passing additional SVG attributes (used when icon is a component).
  */
 
+/**
+ * Derives the ARIA attributes for an icon from its `label` prop.
+ *
+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
+ *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
+ *   tree, so its accessible name would be ignored).
+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
+ *
+ * The result is spread BEFORE `{...props}` in both render modes so an explicit
+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
+ */
+function getIconA11yProps(label) {
+  return label != null && label !== '' ? {
+    role: 'img',
+    'aria-label': label
+  } : {
+    'aria-hidden': 'true'
+  };
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -221,15 +241,21 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }) {
+  // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
+  // meaningful image (role="img" + aria-label) when `label` is non-empty.
+  const a11yProps = getIconA11yProps(label);
+
   // String mode: resolve from icon registry, wrap in styled span
   if (typeof icon === 'string') {
     return /*#__PURE__*/_jsx(IconFromRegistry, {
       name: icon,
       color: color,
       size: size,
+      a11yProps: a11yProps,
       spanProps: props
     });
   }
@@ -237,8 +263,12 @@ export function Icon({
   // Component mode: render SVG component directly with ref forwarding
   const IconComponent = icon;
   return /*#__PURE__*/_jsx(IconComponent, {
-    ref: ref,
-    "aria-hidden": "true",
+    ref: ref
+    // Derived a11y (decorative default or meaningful `label`) is spread
+    // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
+    // consumer still wins as an escape hatch.
+    ,
+    ...a11yProps,
     ...mergeProps(themeProps('icon', {
       size,
       color
@@ -263,6 +293,7 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps
 }) {
   const resolvedIcon = getIcon(name);
@@ -270,11 +301,7 @@ function IconFromRegistry({
     return null;
   }
   return /*#__PURE__*/_jsx("span", {
-    // Decorative by default, but placed BEFORE the prop spread so consumers
-    // can override it (e.g. `aria-hidden={false}` + `role="img"` +
-    // `aria-label`) to expose a meaningful standalone icon. This matches
-    // component-mode Icon, which already sets aria-hidden before its spread.
-    "aria-hidden": "true",
+    ...a11yProps,
     ...spanProps,
     ...mergeProps(themeProps('icon', {
       size,

package/dist/Outline/Outline.d.ts

@@ -19,6 +19,50 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
      * @default 'default'
      */
     density?: 'default' | 'compact';
+    /**
+     * Called when navigation to an item begins, before the scroll starts.
+     * Receives the item `id`. Pair with `onNavigateEnd` to drive an arrival
+     * effect (flash, ring, pulse) on the target heading.
+     */
+    onNavigateStart?: (id: string) => void;
+    /**
+     * Called once when navigation to an item resolves — when the smooth scroll
+     * settles, or immediately-ish when reduced motion turns it into a jump.
+     *
+     * Fires exactly once for every `onNavigateStart`, including when the user
+     * interrupts the scroll by scrolling manually, so a "navigating" state can
+     * never leak. It does not fire if the Outline unmounts mid-scroll.
+     */
+    onNavigateEnd?: (id: string) => void;
+    /**
+     * Height in px of a fixed header overlaying the top of the scroll root.
+     *
+     * Shifts both the activation line *and* the scroll landing by the same
+     * amount, so a heading activates exactly where navigating to it puts it —
+     * below the header rather than hidden underneath it.
+     *
+     * It composes with each heading's own `scroll-margin-top` (the header, then
+     * the breathing room below it) rather than replacing it. When nothing
+     * overlays the content, leave this at 0 and let `scroll-margin-top` do the
+     * work — the browser already honors it.
+     *
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Scroll container to track, instead of auto-detecting the nearest scrollable
+     * ancestor. Use this when the content scrolls inside a split pane, modal, or
+     * dashboard panel rather than the viewport.
+     */
+    scrollContainerRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Whether activating an item smooth-scrolls to it. Set to false to own the
+     * scrolling yourself (virtualized content, a router) — the Outline still
+     * updates the active item, the hash, and the navigate callbacks, but performs
+     * no scroll and suppresses the anchor's default jump.
+     * @default true
+     */
+    hasScrollOnClick?: boolean;
     /** Test ID for testing frameworks. */
     'data-testid'?: string;
 }
@@ -30,8 +74,15 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
  * track that animates to the active item.
  *
  * When `activeId` is omitted, it tracks scroll position and marks the last
- * heading whose top has passed its activation line (its scroll-margin-top)
- * active — defaulting to the first item at the top and the last at the bottom.
+ * heading whose top has passed its activation line — which is exactly where
+ * navigating to that heading lands it: `offset` (a fixed header overlaying the
+ * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
+ * first item at the top and the last at the bottom.
+ *
+ * Keyboard: the list is a single tab stop (roving tabindex), seated on the
+ * active heading. Arrow keys move between headings, Home/End jump to the ends,
+ * and Enter/Space activate — so a long table of contents costs one Tab press,
+ * not one per heading.
  *
  * @example
  * ```
@@ -43,8 +94,23 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
  *   ]}
  * />
  * ```
+ *
+ * Scoped to a custom scroll container, under a fixed header:
+ *
+ * @example
+ * ```
+ * const scrollContainerRef = useRef<HTMLDivElement>(null);
+ *
+ * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
+ * <Outline
+ *   items={items}
+ *   scrollContainerRef={scrollContainerRef}
+ *   offset={64}
+ *   onNavigateEnd={id => flashHeading(id)}
+ * />
+ * ```
  */
-export declare function Outline({ items, activeId, onActiveIdChange, label: labelFromProps, density, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
+export declare function Outline({ items, activeId, onActiveIdChange, label: labelFromProps, density, onNavigateStart, onNavigateEnd, offset, scrollContainerRef, hasScrollOnClick, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
 export declare namespace Outline {
     var displayName: string;
 }

package/dist/Outline/Outline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Outline.d.ts","sourceRoot":"","sources":["../../src/Outline/Outline.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,YAAY,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,6CAA6C;IAC7C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+CAA+C;IAC/C,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAEhC,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgJD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,KAAK,EAAE,cAAc,EACrB,OAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BA2Gd;yBAvHe,OAAO"}
+{"version":3,"file":"Outline.d.ts","sourceRoot":"","sources":["../../src/Outline/Outline.tsx"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,YAAY,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,6CAA6C;IAC7C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+CAA+C;IAC/C,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAErC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEzD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,KAAK,EAAE,cAAc,EACrB,OAAmB,EACnB,eAAe,EACf,aAAa,EACb,MAAU,EACV,kBAAkB,EAClB,gBAAuB,EACvB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BAiLd;yBAlMe,OAAO"}