@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (190) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +30 -19
  3. package/dist/Avatar/Avatar.d.ts +10 -5
  4. package/dist/Avatar/Avatar.d.ts.map +1 -1
  5. package/dist/Avatar/Avatar.js +12 -8
  6. package/dist/Avatar/AvatarSizeContext.d.ts +1 -1
  7. package/dist/Avatar/AvatarSizeContext.js +1 -1
  8. package/dist/Avatar/AvatarStatusDot.d.ts +2 -2
  9. package/dist/Avatar/AvatarStatusDot.js +2 -2
  10. package/dist/AvatarGroup/AvatarGroup.d.ts +2 -2
  11. package/dist/AvatarGroup/AvatarGroup.d.ts.map +1 -1
  12. package/dist/AvatarGroup/AvatarGroup.js +2 -2
  13. package/dist/AvatarGroup/AvatarGroupOverflow.d.ts +1 -1
  14. package/dist/AvatarGroup/AvatarGroupOverflow.d.ts.map +1 -1
  15. package/dist/AvatarGroup/AvatarGroupOverflow.js +16 -14
  16. package/dist/Carousel/Carousel.d.ts +3 -2
  17. package/dist/Carousel/Carousel.d.ts.map +1 -1
  18. package/dist/Carousel/Carousel.js +32 -2
  19. package/dist/Chat/ChatMessage.d.ts +1 -1
  20. package/dist/Chat/ChatMessage.d.ts.map +1 -1
  21. package/dist/Chat/ChatMessage.js +1 -1
  22. package/dist/Citation/Citation.d.ts.map +1 -1
  23. package/dist/Citation/Citation.js +10 -4
  24. package/dist/Collapsible/Collapsible.d.ts +11 -1
  25. package/dist/Collapsible/Collapsible.d.ts.map +1 -1
  26. package/dist/Collapsible/Collapsible.js +36 -4
  27. package/dist/ContextMenu/ContextMenu.d.ts.map +1 -1
  28. package/dist/ContextMenu/ContextMenu.js +4 -3
  29. package/dist/ContextMenu/index.d.ts +3 -0
  30. package/dist/ContextMenu/index.d.ts.map +1 -1
  31. package/dist/ContextMenu/index.js +7 -1
  32. package/dist/DropdownMenu/DropdownMenu.d.ts.map +1 -1
  33. package/dist/DropdownMenu/DropdownMenu.js +8 -4
  34. package/dist/DropdownMenu/DropdownMenuCheckboxItem.d.ts +89 -0
  35. package/dist/DropdownMenu/DropdownMenuCheckboxItem.d.ts.map +1 -0
  36. package/dist/DropdownMenu/DropdownMenuCheckboxItem.js +170 -0
  37. package/dist/DropdownMenu/DropdownMenuContext.d.ts +17 -1
  38. package/dist/DropdownMenu/DropdownMenuContext.d.ts.map +1 -1
  39. package/dist/DropdownMenu/DropdownMenuContext.js +18 -0
  40. package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts +69 -0
  41. package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts.map +1 -0
  42. package/dist/DropdownMenu/DropdownMenuRadioGroup.js +70 -0
  43. package/dist/DropdownMenu/DropdownMenuRadioItem.d.ts +69 -0
  44. package/dist/DropdownMenu/DropdownMenuRadioItem.d.ts.map +1 -0
  45. package/dist/DropdownMenu/DropdownMenuRadioItem.js +178 -0
  46. package/dist/DropdownMenu/index.d.ts +5 -1
  47. package/dist/DropdownMenu/index.d.ts.map +1 -1
  48. package/dist/DropdownMenu/index.js +10 -1
  49. package/dist/DropdownMenu/menuItemRoles.d.ts +13 -0
  50. package/dist/DropdownMenu/menuItemRoles.d.ts.map +1 -0
  51. package/dist/DropdownMenu/menuItemRoles.js +15 -0
  52. package/dist/Icon/Icon.d.ts +43 -13
  53. package/dist/Icon/Icon.d.ts.map +1 -1
  54. package/dist/Icon/Icon.js +62 -27
  55. package/dist/Outline/Outline.d.ts +69 -3
  56. package/dist/Outline/Outline.d.ts.map +1 -1
  57. package/dist/Outline/Outline.js +129 -26
  58. package/dist/Outline/useScrollSpy.d.ts +27 -7
  59. package/dist/Outline/useScrollSpy.d.ts.map +1 -1
  60. package/dist/Outline/useScrollSpy.js +202 -70
  61. package/dist/TabList/Tab.d.ts.map +1 -1
  62. package/dist/TabList/Tab.js +2 -2
  63. package/dist/TabList/TabList.d.ts.map +1 -1
  64. package/dist/TabList/TabList.js +2 -0
  65. package/dist/TabList/TabMenu.d.ts.map +1 -1
  66. package/dist/TabList/TabMenu.js +1 -1
  67. package/dist/Table/Table.d.ts +1 -1
  68. package/dist/Table/Table.js +1 -1
  69. package/dist/Table/index.d.ts +2 -0
  70. package/dist/Table/index.d.ts.map +1 -1
  71. package/dist/Table/index.js +1 -0
  72. package/dist/Table/plugins/rowExpansion/useTableRowExpansion.d.ts.map +1 -1
  73. package/dist/Table/plugins/rowExpansion/useTableRowExpansion.js +24 -2
  74. package/dist/Table/plugins/sortable/useTableSortable.d.ts.map +1 -1
  75. package/dist/Table/plugins/sortable/useTableSortable.js +18 -7
  76. package/dist/Table/plugins/tree/index.d.ts +5 -0
  77. package/dist/Table/plugins/tree/index.d.ts.map +1 -0
  78. package/dist/Table/plugins/tree/index.js +4 -0
  79. package/dist/Table/plugins/tree/useTableTreeData.d.ts +38 -0
  80. package/dist/Table/plugins/tree/useTableTreeData.d.ts.map +1 -0
  81. package/dist/Table/plugins/tree/useTableTreeData.js +358 -0
  82. package/dist/Table/plugins/tree/useTableTreeState.d.ts +51 -0
  83. package/dist/Table/plugins/tree/useTableTreeState.d.ts.map +1 -0
  84. package/dist/Table/plugins/tree/useTableTreeState.js +175 -0
  85. package/dist/Table/useBaseTablePlugins.d.ts.map +1 -1
  86. package/dist/Table/useBaseTablePlugins.js +6 -3
  87. package/dist/Toolbar/Toolbar.d.ts.map +1 -1
  88. package/dist/Toolbar/Toolbar.js +8 -1
  89. package/dist/TreeList/TreeListItem.d.ts.map +1 -1
  90. package/dist/TreeList/TreeListItem.js +5 -14
  91. package/dist/astryx.css +24 -4
  92. package/dist/astryx.umd.js +54 -54
  93. package/dist/astryx.umd.js.map +4 -4
  94. package/dist/theme/Theme.js +1 -1
  95. package/dist/theme/defineTheme.d.ts +1 -1
  96. package/dist/theme/defineTheme.js +1 -1
  97. package/dist/theme/hct.d.ts +0 -1
  98. package/dist/theme/hct.d.ts.map +1 -1
  99. package/dist/theme/hct.js +0 -3
  100. package/docs.mjs +32 -461
  101. package/locales/en.json +200 -172
  102. package/locales/pseudo.json +21 -0
  103. package/package.json +3 -1
  104. package/scripts/postinstall.mjs +93 -0
  105. package/src/Avatar/Avatar.doc.mjs +6 -6
  106. package/src/Avatar/Avatar.tsx +16 -11
  107. package/src/Avatar/AvatarSizeContext.ts +1 -1
  108. package/src/Avatar/AvatarStatusDot.tsx +2 -2
  109. package/src/AvatarGroup/AvatarGroup.doc.mjs +1 -1
  110. package/src/AvatarGroup/AvatarGroup.test.tsx +17 -3
  111. package/src/AvatarGroup/AvatarGroup.tsx +3 -3
  112. package/src/AvatarGroup/AvatarGroupOverflow.doc.mjs +4 -4
  113. package/src/AvatarGroup/AvatarGroupOverflow.tsx +21 -5
  114. package/src/Carousel/Carousel.doc.mjs +1 -0
  115. package/src/Carousel/Carousel.test.tsx +96 -1
  116. package/src/Carousel/Carousel.tsx +29 -2
  117. package/src/Chat/Chat.doc.mjs +1 -1
  118. package/src/Chat/ChatMessage.tsx +4 -2
  119. package/src/CheckboxInput/CheckboxInput.doc.mjs +1 -1
  120. package/src/Citation/Citation.test.tsx +51 -0
  121. package/src/Citation/Citation.tsx +8 -2
  122. package/src/Collapsible/Collapsible.doc.mjs +7 -0
  123. package/src/Collapsible/Collapsible.test.tsx +80 -0
  124. package/src/Collapsible/Collapsible.tsx +58 -5
  125. package/src/ContextMenu/ContextMenu.test.tsx +75 -1
  126. package/src/ContextMenu/ContextMenu.tsx +10 -5
  127. package/src/ContextMenu/index.ts +15 -0
  128. package/src/DropdownMenu/DropdownMenu.doc.mjs +23 -0
  129. package/src/DropdownMenu/DropdownMenu.tsx +11 -6
  130. package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs +95 -0
  131. package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx +237 -0
  132. package/src/DropdownMenu/DropdownMenuContext.tsx +29 -1
  133. package/src/DropdownMenu/DropdownMenuItem.doc.mjs +7 -1
  134. package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs +80 -0
  135. package/src/DropdownMenu/DropdownMenuRadioGroup.tsx +119 -0
  136. package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs +80 -0
  137. package/src/DropdownMenu/DropdownMenuRadioItem.tsx +232 -0
  138. package/src/DropdownMenu/DropdownMenuSelectable.test.tsx +163 -0
  139. package/src/DropdownMenu/index.ts +23 -3
  140. package/src/DropdownMenu/menuItemRoles.ts +22 -0
  141. package/src/Field/Field.doc.mjs +1 -1
  142. package/src/Field/FieldLabel.doc.mjs +1 -1
  143. package/src/Icon/Icon.doc.mjs +12 -0
  144. package/src/Icon/Icon.test.tsx +142 -0
  145. package/src/Icon/Icon.tsx +98 -30
  146. package/src/Item/Item.doc.mjs +1 -1
  147. package/src/NumberInput/NumberInput.doc.mjs +2 -2
  148. package/src/Outline/Outline.doc.mjs +123 -3
  149. package/src/Outline/Outline.test.tsx +735 -0
  150. package/src/Outline/Outline.tsx +184 -33
  151. package/src/Outline/useScrollSpy.ts +248 -72
  152. package/src/Selector/SelectorOption.doc.mjs +1 -1
  153. package/src/SideNav/SideNavItem.doc.mjs +2 -2
  154. package/src/Switch/Switch.doc.mjs +1 -1
  155. package/src/TabList/Tab.tsx +5 -1
  156. package/src/TabList/TabList.doc.mjs +3 -3
  157. package/src/TabList/TabList.test.tsx +66 -0
  158. package/src/TabList/TabList.tsx +8 -0
  159. package/src/TabList/TabMenu.tsx +4 -1
  160. package/src/Table/Table.doc.mjs +2 -0
  161. package/src/Table/Table.tsx +1 -1
  162. package/src/Table/index.ts +7 -0
  163. package/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx +90 -1
  164. package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx +37 -5
  165. package/src/Table/plugins/sortable/useTableSortable.test.tsx +95 -9
  166. package/src/Table/plugins/sortable/useTableSortable.tsx +23 -7
  167. package/src/Table/plugins/tree/index.ts +12 -0
  168. package/src/Table/plugins/tree/useTableTreeData-perf.test.tsx +163 -0
  169. package/src/Table/plugins/tree/useTableTreeData.test.tsx +594 -0
  170. package/src/Table/plugins/tree/useTableTreeData.tsx +495 -0
  171. package/src/Table/plugins/tree/useTableTreeState.test.tsx +636 -0
  172. package/src/Table/plugins/tree/useTableTreeState.tsx +253 -0
  173. package/src/Table/useBaseTablePlugins.ts +6 -2
  174. package/src/Table/useTableTreeData.doc.mjs +75 -0
  175. package/src/Table/useTableTreeState.doc.mjs +98 -0
  176. package/src/TextArea/TextArea.doc.mjs +1 -1
  177. package/src/TextInput/TextInput.doc.mjs +1 -1
  178. package/src/Toolbar/Toolbar.tsx +10 -3
  179. package/src/TreeList/TreeList.test.tsx +32 -1
  180. package/src/TreeList/TreeListItem.tsx +19 -10
  181. package/src/docs-script.test.mjs +18 -13
  182. package/src/postinstall.test.mjs +71 -0
  183. package/src/theme/Theme.doc.mjs +4 -4
  184. package/src/theme/Theme.tsx +1 -1
  185. package/src/theme/defineTheme.ts +1 -1
  186. package/src/theme/hct.ts +0 -4
  187. package/dist/TreeList/treeListItem.markers.stylex.d.ts +0 -16
  188. package/dist/TreeList/treeListItem.markers.stylex.d.ts.map +0 -1
  189. package/dist/TreeList/treeListItem.markers.stylex.js +0 -22
  190. package/src/TreeList/treeListItem.markers.stylex.ts +0 -20
@@ -19,6 +19,50 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
19
19
  * @default 'default'
20
20
  */
21
21
  density?: 'default' | 'compact';
22
+ /**
23
+ * Called when navigation to an item begins, before the scroll starts.
24
+ * Receives the item `id`. Pair with `onNavigateEnd` to drive an arrival
25
+ * effect (flash, ring, pulse) on the target heading.
26
+ */
27
+ onNavigateStart?: (id: string) => void;
28
+ /**
29
+ * Called once when navigation to an item resolves — when the smooth scroll
30
+ * settles, or immediately-ish when reduced motion turns it into a jump.
31
+ *
32
+ * Fires exactly once for every `onNavigateStart`, including when the user
33
+ * interrupts the scroll by scrolling manually, so a "navigating" state can
34
+ * never leak. It does not fire if the Outline unmounts mid-scroll.
35
+ */
36
+ onNavigateEnd?: (id: string) => void;
37
+ /**
38
+ * Height in px of a fixed header overlaying the top of the scroll root.
39
+ *
40
+ * Shifts both the activation line *and* the scroll landing by the same
41
+ * amount, so a heading activates exactly where navigating to it puts it —
42
+ * below the header rather than hidden underneath it.
43
+ *
44
+ * It composes with each heading's own `scroll-margin-top` (the header, then
45
+ * the breathing room below it) rather than replacing it. When nothing
46
+ * overlays the content, leave this at 0 and let `scroll-margin-top` do the
47
+ * work — the browser already honors it.
48
+ *
49
+ * @default 0
50
+ */
51
+ offset?: number;
52
+ /**
53
+ * Scroll container to track, instead of auto-detecting the nearest scrollable
54
+ * ancestor. Use this when the content scrolls inside a split pane, modal, or
55
+ * dashboard panel rather than the viewport.
56
+ */
57
+ scrollContainerRef?: React.RefObject<HTMLElement | null>;
58
+ /**
59
+ * Whether activating an item smooth-scrolls to it. Set to false to own the
60
+ * scrolling yourself (virtualized content, a router) — the Outline still
61
+ * updates the active item, the hash, and the navigate callbacks, but performs
62
+ * no scroll and suppresses the anchor's default jump.
63
+ * @default true
64
+ */
65
+ hasScrollOnClick?: boolean;
22
66
  /** Test ID for testing frameworks. */
23
67
  'data-testid'?: string;
24
68
  }
@@ -30,8 +74,15 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
30
74
  * track that animates to the active item.
31
75
  *
32
76
  * When `activeId` is omitted, it tracks scroll position and marks the last
33
- * heading whose top has passed its activation line (its scroll-margin-top)
34
- * active — defaulting to the first item at the top and the last at the bottom.
77
+ * heading whose top has passed its activation line — which is exactly where
78
+ * navigating to that heading lands it: `offset` (a fixed header overlaying the
79
+ * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
80
+ * first item at the top and the last at the bottom.
81
+ *
82
+ * Keyboard: the list is a single tab stop (roving tabindex), seated on the
83
+ * active heading. Arrow keys move between headings, Home/End jump to the ends,
84
+ * and Enter/Space activate — so a long table of contents costs one Tab press,
85
+ * not one per heading.
35
86
  *
36
87
  * @example
37
88
  * ```
@@ -43,8 +94,23 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
43
94
  * ]}
44
95
  * />
45
96
  * ```
97
+ *
98
+ * Scoped to a custom scroll container, under a fixed header:
99
+ *
100
+ * @example
101
+ * ```
102
+ * const scrollContainerRef = useRef<HTMLDivElement>(null);
103
+ *
104
+ * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
105
+ * <Outline
106
+ * items={items}
107
+ * scrollContainerRef={scrollContainerRef}
108
+ * offset={64}
109
+ * onNavigateEnd={id => flashHeading(id)}
110
+ * />
111
+ * ```
46
112
  */
47
- export declare function Outline({ items, activeId, onActiveIdChange, label: labelFromProps, density, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
113
+ 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;
48
114
  export declare namespace Outline {
49
115
  var displayName: string;
50
116
  }
@@ -1 +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"}
1
+ {"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"}
@@ -4,7 +4,7 @@
4
4
 
5
5
  /**
6
6
  * @file Outline.tsx
7
- * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types
7
+ * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types, useListFocus
8
8
  * @output Exports Outline component and OutlineProps type
9
9
  * @position Core implementation; consumed by index.ts
10
10
  *
@@ -12,6 +12,9 @@
12
12
  * - Sliding indicator track (vertical divider + animated active bar)
13
13
  * - Density variant (default/compact)
14
14
  * - Scroll-spy active state when uncontrolled
15
+ * - Roving-tabindex keyboard navigation (Arrow/Home/End, Enter/Space activate)
16
+ * - onNavigateStart / onNavigateEnd callbacks around the smooth scroll
17
+ * - Scroll scoping (offset, scrollContainerRef, hasScrollOnClick)
15
18
  *
16
19
  * SYNC: When modified, update these files to stay in sync:
17
20
  * - /packages/core/src/Outline/Outline.doc.mjs
@@ -24,6 +27,8 @@ import * as stylex from '@stylexjs/stylex';
24
27
  import "../theme/tokens.stylex.js";
25
28
  import { colorVars, durationVars, easeVars, radiusVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
26
29
  import { useLinkComponent } from "../Link/useLinkComponent.js";
30
+ import { useListFocus } from "../hooks/useListFocus.js";
31
+ import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
27
32
  import { mergeProps, mergeRefs } from "../utils/index.js";
28
33
  import { useScrollSpy } from "./useScrollSpy.js";
29
34
  import { themeProps } from "../utils/themeProps.js";
@@ -135,8 +140,15 @@ function getIndentStyle(level) {
135
140
  * track that animates to the active item.
136
141
  *
137
142
  * When `activeId` is omitted, it tracks scroll position and marks the last
138
- * heading whose top has passed its activation line (its scroll-margin-top)
139
- * active — defaulting to the first item at the top and the last at the bottom.
143
+ * heading whose top has passed its activation line — which is exactly where
144
+ * navigating to that heading lands it: `offset` (a fixed header overlaying the
145
+ * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
146
+ * first item at the top and the last at the bottom.
147
+ *
148
+ * Keyboard: the list is a single tab stop (roving tabindex), seated on the
149
+ * active heading. Arrow keys move between headings, Home/End jump to the ends,
150
+ * and Enter/Space activate — so a long table of contents costs one Tab press,
151
+ * not one per heading.
140
152
  *
141
153
  * @example
142
154
  * ```
@@ -148,6 +160,21 @@ function getIndentStyle(level) {
148
160
  * ]}
149
161
  * />
150
162
  * ```
163
+ *
164
+ * Scoped to a custom scroll container, under a fixed header:
165
+ *
166
+ * @example
167
+ * ```
168
+ * const scrollContainerRef = useRef<HTMLDivElement>(null);
169
+ *
170
+ * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
171
+ * <Outline
172
+ * items={items}
173
+ * scrollContainerRef={scrollContainerRef}
174
+ * offset={64}
175
+ * onNavigateEnd={id => flashHeading(id)}
176
+ * />
177
+ * ```
151
178
  */
152
179
  export function Outline({
153
180
  items,
@@ -155,6 +182,11 @@ export function Outline({
155
182
  onActiveIdChange,
156
183
  label: labelFromProps,
157
184
  density = 'default',
185
+ onNavigateStart,
186
+ onNavigateEnd,
187
+ offset = 0,
188
+ scrollContainerRef,
189
+ hasScrollOnClick = true,
158
190
  xstyle,
159
191
  className,
160
192
  style,
@@ -166,42 +198,109 @@ export function Outline({
166
198
  const label = labelFromProps ?? t('@astryx.outline.label');
167
199
  const rootRef = useRef(null);
168
200
  const LinkComponent = useLinkComponent();
169
- const isControlled = activeId !== undefined;
170
201
  const {
171
202
  activeId: resolvedActiveId,
172
- setActiveId,
173
- lockActiveId
203
+ scrollTo
174
204
  } = useScrollSpy({
175
205
  activeId,
176
206
  items,
177
207
  onActiveIdChange,
178
- rootRef
208
+ rootRef,
209
+ offset,
210
+ scrollContainerRef,
211
+ hasScrollOnClick,
212
+ onNavigateStart,
213
+ onNavigateEnd
179
214
  });
215
+
216
+ // Roving tabindex over the links: the whole outline is one tab stop, and
217
+ // arrows move between headings. The hook owns `tabindex` on the items.
218
+ const {
219
+ listRef,
220
+ handleKeyDown: handleListKeyDown,
221
+ handleFocus
222
+ } = useListFocus({
223
+ itemSelector: 'a[href]',
224
+ orientation: 'vertical',
225
+ hasRovingTabIndex: true
226
+ });
227
+
228
+ // Seat the tab stop on the *active* heading. WAI-ARIA puts the single tab
229
+ // stop on the current item, so tabbing into a table of contents while
230
+ // reading section 7 lands on section 7 — not back at section 1, which is
231
+ // where useListFocus would otherwise leave it (it promotes the first item on
232
+ // mount and then keeps whichever item already holds the stop).
233
+ //
234
+ // Only while focus is outside the list: once the reader has arrowed to an
235
+ // item, the stop is theirs and scroll-spy must not yank it away. Sets
236
+ // `tabindex` only — it never steals focus. Registered after useListFocus so
237
+ // it runs after the hook's own layout effect and wins; on later commits the
238
+ // hook then finds this item already holding the stop and keeps it.
239
+ useIsomorphicLayoutEffect(() => {
240
+ const list = listRef.current;
241
+ if (list == null || list.contains(document.activeElement)) {
242
+ return;
243
+ }
244
+ const links = Array.from(list.querySelectorAll('a[href]'));
245
+ const active = links.find(link => link.getAttribute('aria-current') === 'true');
246
+ if (active == null) {
247
+ return;
248
+ }
249
+ for (const link of links) {
250
+ const tabIndex = link === active ? '0' : '-1';
251
+ if (link.getAttribute('tabindex') !== tabIndex) {
252
+ link.setAttribute('tabindex', tabIndex);
253
+ }
254
+ }
255
+ });
256
+
257
+ /**
258
+ * The single navigation path, shared by click and keyboard activation:
259
+ * push the hash, then hand off to the scroll-spy's `scrollTo`, which fires
260
+ * the navigate callbacks and moves the indicator when the scroll settles.
261
+ */
262
+ const navigate = id => {
263
+ if (scrollTo(id)) {
264
+ window.history.pushState(null, '', `#${id}`);
265
+ }
266
+ };
267
+
268
+ /** Whether an event carries a modifier chord we must leave to the browser. */
269
+ const hasModifier = event => event.metaKey || event.altKey || event.ctrlKey || event.shiftKey;
180
270
  const handleClick = id => event => {
181
- const target = document.getElementById(id);
271
+ // Let the browser handle modified clicks (open in new tab, etc.) without
272
+ // touching the active state.
273
+ if (event.defaultPrevented || hasModifier(event)) {
274
+ return;
275
+ }
182
276
 
183
- // Let the browser handle modified clicks (open in new tab, etc.) and
184
- // missing targets without touching the active state.
185
- if (target == null || event.defaultPrevented || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) {
277
+ // With no target in the DOM — lazily-rendered or virtualized content —
278
+ // there is nothing to scroll to and nothing to make active. Leave the
279
+ // anchor to the browser's native fragment navigation (which still
280
+ // updates the URL) rather than swallowing the click into a dead link.
281
+ if (document.getElementById(id) == null) {
186
282
  return;
187
283
  }
188
- event.preventDefault();
189
- window.history.pushState(null, '', `#${id}`);
190
284
 
191
- // Move the indicator to the clicked item in a single step. Controlled
192
- // consumers own the active state (notify only); uncontrolled mode pins
193
- // the active id and suppresses scroll-spy until the next manual scroll,
194
- // so the click is honored — even for short/last sections — and the
195
- // indicator doesn't chase the smooth scroll through other sections.
196
- if (isControlled) {
197
- setActiveId(id);
198
- } else {
199
- lockActiveId(id);
285
+ // Suppress the anchor's default jump: we own the scroll (or, with
286
+ // `hasScrollOnClick={false}`, deliberately leave it to the consumer).
287
+ event.preventDefault();
288
+ navigate(id);
289
+ };
290
+ const handleKeyDown = id => event => {
291
+ // Enter is a link's native activation and already produces a click.
292
+ // Space is not, so wire it up here to match the button-like affordance.
293
+ if (event.key !== ' ' && event.key !== 'Spacebar') {
294
+ return;
200
295
  }
201
- target.scrollIntoView({
202
- behavior: 'smooth',
203
- block: 'start'
204
- });
296
+ if (event.defaultPrevented || hasModifier(event)) {
297
+ return;
298
+ }
299
+
300
+ // preventDefault does double duty: it stops the page from scrolling, and
301
+ // it tells useScrollSpy this Space is an activation, not a manual scroll.
302
+ event.preventDefault();
303
+ navigate(id);
205
304
  };
206
305
  return /*#__PURE__*/_jsxs("nav", {
207
306
  ...props,
@@ -215,7 +314,10 @@ export function Outline({
215
314
  ...{
216
315
  className: "x78zum5 xdt5ytf x1lsbc85 x1ghz6dp x1717udv xe8uvvx x98rzlu xeuugli"
217
316
  },
317
+ ref: listRef,
218
318
  role: "list",
319
+ onKeyDown: handleListKeyDown,
320
+ onFocus: handleFocus,
219
321
  children: items.map(item => {
220
322
  const isActive = item.id === resolvedActiveId;
221
323
  return /*#__PURE__*/_jsx("li", {
@@ -227,6 +329,7 @@ export function Outline({
227
329
  href: `#${item.id}`,
228
330
  "aria-current": isActive ? 'true' : undefined,
229
331
  onClick: handleClick(item.id),
332
+ onKeyDown: handleKeyDown(item.id),
230
333
  ...mergeProps(themeProps('outline-item', {
231
334
  active: isActive ? 'active' : null,
232
335
  level: item.level
@@ -4,20 +4,40 @@ interface UseScrollSpyOptions {
4
4
  items: OutlineItem[];
5
5
  onActiveIdChange?: (id: string) => void;
6
6
  rootRef: React.RefObject<HTMLElement | null>;
7
+ /**
8
+ * Height in px of a fixed header overlaying the top of the scroll root.
9
+ * Shifts both the activation line and the scroll landing by the same amount,
10
+ * on top of each heading's own `scroll-margin-top`.
11
+ */
12
+ offset?: number;
13
+ /** Scroll container to track, instead of the nearest scrollable ancestor. */
14
+ scrollContainerRef?: React.RefObject<HTMLElement | null>;
15
+ /** Whether {@link UseScrollSpyResult.scrollTo} performs the smooth scroll. */
16
+ hasScrollOnClick?: boolean;
17
+ /** Called when a navigation begins, before the scroll starts. */
18
+ onNavigateStart?: (id: string) => void;
19
+ /** Called once per navigation, when the scroll settles or is interrupted. */
20
+ onNavigateEnd?: (id: string) => void;
7
21
  }
8
22
  interface UseScrollSpyResult {
9
23
  activeId: string | undefined;
10
24
  /** Set the active id (notifies onActiveIdChange). For controlled consumers. */
11
25
  setActiveId: (id: string) => void;
12
26
  /**
13
- * Handle a click on the outline item with id `id`. Delays moving the
14
- * indicator: scroll-spy is suppressed during the programmatic smooth scroll
15
- * so the indicator doesn't chase it, then the indicator moves once to the
16
- * clicked item when the scroll settles. If the user scrolls manually mid-way,
17
- * scroll-position tracking resumes immediately instead.
27
+ * Navigate to the item with id `id` — the single path shared by click and
28
+ * keyboard activation.
29
+ *
30
+ * Fires `onNavigateStart(id)`, scrolls (unless `hasScrollOnClick` is false),
31
+ * and fires `onNavigateEnd(id)` exactly once when the scroll settles or the
32
+ * user interrupts it. While uncontrolled, scroll-spy is suppressed for the
33
+ * duration so the indicator doesn't chase the scroll through intervening
34
+ * sections; it lands on the target once the scroll settles, or resumes
35
+ * position tracking if the user scrolls away mid-flight.
36
+ *
37
+ * Returns false (and does nothing) when no element with `id` exists.
18
38
  */
19
- lockActiveId: (id: string) => void;
39
+ scrollTo: (id: string) => boolean;
20
40
  }
21
- export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, }: UseScrollSpyOptions): UseScrollSpyResult;
41
+ export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, offset, scrollContainerRef, hasScrollOnClick, onNavigateStart, onNavigateEnd, }: UseScrollSpyOptions): UseScrollSpyResult;
22
42
  export {};
23
43
  //# sourceMappingURL=useScrollSpy.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useScrollSpy.d.ts","sourceRoot":"","sources":["../../src/Outline/useScrollSpy.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAuFzC,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,OAAO,GACR,EAAE,mBAAmB,GAAG,kBAAkB,CA2I1C"}
1
+ {"version":3,"file":"useScrollSpy.d.ts","sourceRoot":"","sources":["../../src/Outline/useScrollSpy.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAsJzC,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACzD,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iEAAiE;IACjE,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAED,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,OAAO,EACP,MAAU,EACV,kBAAkB,EAClB,gBAAuB,EACvB,eAAe,EACf,aAAa,GACd,EAAE,mBAAmB,GAAG,kBAAkB,CAoN1C"}