An open source design system that's fully customizable and agent ready
TypeScript
chore(hooks): source comments explain only non-obvious reasons (2 of 2) (#9520)
Cindy Zhangf8f615574eb0
diff --git a/.changeset/hooks-comment-cleanup-2.md b/.changeset/hooks-comment-cleanup-2.mdnew file mode 100644index 0000000000..b9c9dcf0cc--- /dev/null+++ b/.changeset/hooks-comment-cleanup-2.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] More source comments in the core hooks are shorter and explain only non-obvious reasons. Nothing a consumer imports or renders changes.++@cixzhangdiff --git a/packages/core/src/hooks/ModalAnnounceProvider.tsx b/packages/core/src/hooks/ModalAnnounceProvider.tsxindex 9581633214..dafcdc6c8c 100644--- a/packages/core/src/hooks/ModalAnnounceProvider.tsx+++ b/packages/core/src/hooks/ModalAnnounceProvider.tsx@@ -57,10 +57,9 @@ export function ModalAnnounceProvider({}: {dialogRef: RefObject<HTMLDialogElement | null>;/**- * The owner's intent for this render: open as a modal (or presented as a- * modal step). A non-modal surface — a scrimless Drawer shown with- * `showPopover()`, a scrimless sheet — passes `false`: it is not an FR14- * modal, and callers inside it route as the page does.+ * The owner's intent for this render: open as a modal, or presented as a+ * modal step. A non-modal surface, such as a scrimless Drawer or sheet,+ * passes `false`. Callers inside it route as the page does.*/isOpen: boolean;children: ReactNode;@@ -77,12 +76,10 @@ export function ModalAnnounceProvider({useIsomorphicLayoutEffect(() => {scope.isOpen = isOpen;}, [scope, isOpen]);- // The presentation watch is a session: it starts when the owner intends- // the dialog open (or finds it already open), follows `open`, `inert` and- // `aria-hidden` through the exit, and ends once the dialog has really- // closed, or when the provider unmounts. A closed dialog at rest — a- // preloaded sheet, a Drawer never shown — holds no observer- // (`architecture:react-component-runtime` INV5).+ // The presentation watch is a session. It starts when the owner intends the+ // dialog open, or finds it open. It follows `open`, `inert` and+ // `aria-hidden` through the exit, and it ends when the dialog really closes+ // or the provider unmounts. A closed dialog at rest holds no observer.const sessionRef = useRef<{dialog: HTMLDialogElement;stop: () => void;diff --git a/packages/core/src/hooks/menuPressOnItems.ts b/packages/core/src/hooks/menuPressOnItems.tsindex 4f2bf444d6..b5aff64361 100644--- a/packages/core/src/hooks/menuPressOnItems.ts+++ b/packages/core/src/hooks/menuPressOnItems.ts@@ -3,20 +3,18 @@/*** @file menuPressOnItems.ts* @input useMenuPress's menu `onPointerDown` and the menu's item selector- * @output Exports pressOnItemsOnly: the same handler, run only for a press- * that lands on an item and is not a modified mouse press on a link+ * @output pressOnItemsOnly: the same handler, run only for a press that lands+ * on an item and is not a modified mouse press on a link* @position Internal to core's menus with caller content or link items* (NavHeadingMenu, TopNavMenu, SideNavHeading's and TopNavHeading's menus,* BreadcrumbItem's menu)- *- * A menu that holds caller content beside its items (a button, a link list)- * tracks only presses that land on an item. A press on anything else stays- * the browser's own, so that content's click runs as it always has- * (`architecture:interaction-modality` INV4). A mouse press with Ctrl, Cmd or- * Shift on a link item is the browser's too, so it opens the link in a new- * tab or window as it always has; a middle press never reaches the model.*/+// A press on caller content beside the items stays the browser's, so that+// content's click runs as before. A Ctrl, Cmd or Shift mouse press on a link+// item also stays the browser's, so it opens the link in a new tab or window.+// A middle press never reaches the model.+import type {PointerEvent as ReactPointerEvent} from 'react';export function pressOnItemsOnly<E extends HTMLElement>(diff --git a/packages/core/src/hooks/modalAnnounce.ts b/packages/core/src/hooks/modalAnnounce.tsindex 4f52efc695..12cad6f04b 100644--- a/packages/core/src/hooks/modalAnnounce.ts+++ b/packages/core/src/hooks/modalAnnounce.ts@@ -4,23 +4,11 @@/*** @file modalAnnounce.ts- * @input Uses the live-region internals of useAnnounce and DOM dialog state+ * @input The live-region internals of useAnnounce and DOM dialog state* @output Installs the modal route into useAnnounce as it loads, and exports- * the presentation bookkeeping ModalAnnounceProvider drives- * @position Core a11y internal (spec:AST-086 FR14): where a message from- * inside an Astryx modal is heard. A dialog is exposed when it is open as- * a modal and neither inert nor aria-hidden; the top-layer order is kept- * by `open` alone; a message a dialog holds when it stops being exposed is- * handed to the channel exposed then, or held while an exiting modal still- * covers everything, and released at its real close; a covered modal is- * not written to; a caller inside a modal being presented in this commit- * waits one frame for the route. Words move with their announcers'- * receipts, one delivery per announcer, so an announcer can take back its- * own share while it waits wherever it went: a `hasReplace` instance's- * next message (FR9), a busy start overtaken by its outcome (FR8). Loaded- * only by ModalAnnounceProvider, so- * a component that calls useAnnounce and renders no modal does not carry- * it.+ * the presentation bookkeeping that ModalAnnounceProvider drives+ * @position Core a11y internal (AST-086 FR14) that decides where a message+ * from inside an Astryx modal is heard. Only ModalAnnounceProvider loads it.** SYNC: not exported from /packages/core/src/hooks/index.ts.*/@@ -157,14 +145,11 @@ function isAnyModalOpen(): boolean {return false;}-// Words waiting for an exiting modal's real close: their dialog has left-// the accessibility tree for its exit but is still an open native modal, or-// such a dialog covers the channel they would go to, so nothing is exposed-// yet. They are delivered when a dialog closes (or theirs is exposed again).-// Each text keeps its announcers' receipts, so one taking its share back-// leaves it for the others, and a receipt follows the words when they are-// released; an entry is gone once delivered, so a receipt never reaches-// equal words held later.+// Words that wait for an exiting modal's real close. Their dialog left the+// accessibility tree for its exit but is still an open native modal, or such+// a dialog covers their channel. They are delivered when a dialog closes or+// theirs is exposed again. Each text keeps its announcers' receipts. An entry+// is gone once delivered, so a receipt never reaches equal words held later.interface HeldWords extends WaitingWords {readonly receipts: AnnounceReceipt[];}@@ -285,7 +270,7 @@ function deliverBeyond(* Move whatever `dialog`'s containers hold that assistive technology has not* had yet to the channel exposed now. Called when the dialog stops being* exposed — closed, taken inert or `aria-hidden` for its exit, or unmounted- * while open — so a message sent just before is not lost (FR14).+ * while open — so a message sent just before is not lost.*/export function handOffUnexposed(dialog: HTMLDialogElement): void {for (const politeness of ['polite', 'assertive'] as const) {@@ -352,11 +337,10 @@ function announceInModalRouted(});}-// Messages from callers whose enclosing modal is being presented in this-// commit, waiting one frame for the route; an empty message among them-// withdraws the earlier ones of its urgency, as it would on a channel.-// Each message keeps a receipt per announcer: before the frame, taking it-// back drops that announcer's share; the frame points it at its write.+// Messages from callers whose modal is presented in this commit wait one+// frame for the route. An empty message among them withdraws the earlier+// ones of its urgency. Before the frame, a receipt drops its announcer's+// share. The frame points the receipt at its write.interface Deferred {frame: number;words: Record<AnnouncePoliteness, HeldWords[]>;@@ -462,15 +446,12 @@ function announceFromScope(politeness: AnnouncePoliteness,): WithdrawAnnouncement | null {if (isBeingPresented(scope)) {- // Announced in the commit that opens the enclosing modal — a field error- // inside `{isOpen && <Dialog isOpen>}`, alone or inside an already-open- // Dialog — before the Dialog's own Effect, which runs after its- // content's, has called showModal(). Choose the route a frame later,- // when it has, rather than the modal beneath, which the new one is about- // to cover; an empty message in the same commit withdraws what waits- // (FR9). A caller inside a modal that is meant to be closed (its content- // stays mounted) is not waiting for anything: it takes the route of- // where it is now, joined with the frame's other messages.+ // The message comes in the commit that opens its modal, before the+ // Dialog's Effect calls showModal(), because that Effect runs after its+ // content's. Choose the route a frame later, not the modal beneath that+ // the new one will cover. An empty message in the same commit withdraws+ // what waits. A caller in a modal that is meant to be closed waits for+ // nothing: it takes the route of where it is now.return deferUntilPresented(scope, message, politeness);}const dialog = enclosingOpenModal(scope);diff --git a/packages/core/src/hooks/scrollbarGutter.ts b/packages/core/src/hooks/scrollbarGutter.tsindex 34b0446be6..30f6fa27d4 100644--- a/packages/core/src/hooks/scrollbarGutter.ts+++ b/packages/core/src/hooks/scrollbarGutter.ts@@ -3,26 +3,19 @@/*** @file scrollbarGutter.ts* @input The element a scroll lock pins, plus live layout measurements- * @output Exports holdScrollbarGutter and the ScrollbarGutterHold it returns+ * @output holdScrollbarGutter and the ScrollbarGutterHold it returns* @position Internal hook utility; used by useScrollLock and MobileNav so that* locking background scroll does not resize the layout viewport.- *- * Locking scroll hides the document's scrollbar. Where that scrollbar is a- * classic (space-taking) one — Windows/Linux desktop, and macOS set to- * "Always" show scroll bars — hiding it widens the layout viewport by the- * scrollbar's width and the whole page jumps sideways behind the overlay.- *- * The fix is `scrollbar-gutter: stable`, which holds the gutter open once the- * scrollbar goes away. Being a real layout change it holds `position: fixed`- * chrome (sticky headers, toast viewports) as well as in-flow content, which- * padding fundamentally cannot: fixed elements resolve against the viewport,- * not against the padded element.- *- * Padding is kept only as a fallback for engines without `scrollbar-gutter`- * (Safari shipped it in 18.2), and it is applied by measuring whether the- * element actually moved rather than by assuming it did.*/+// A scroll lock hides the document's scrollbar. A classic, space-taking+// scrollbar then gives its width back, and the page jumps sideways behind the+// overlay. `scrollbar-gutter: stable` keeps the gutter open. It is a layout+// change, so it also holds `position: fixed` chrome, which padding cannot:+// fixed elements resolve against the viewport. Padding is only a fallback for+// engines without `scrollbar-gutter`, and it applies only when a measurement+// shows that the element moved.+const NOOP: ScrollbarGutterHold = {settle() {},release() {},diff --git a/packages/core/src/hooks/useAnimatedLayout.ts b/packages/core/src/hooks/useAnimatedLayout.tsindex 861a5600c0..5fc84e4cb1 100644--- a/packages/core/src/hooks/useAnimatedLayout.ts+++ b/packages/core/src/hooks/useAnimatedLayout.ts@@ -7,8 +7,7 @@* @input React (useMemo), motion/animatedLayout.ts* @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle* type- * @position Public hook (`spec:AST-105`) over the one size-change module- * (`architecture:react-component-runtime` INV12)+ * @position Public hook over the one size-change module** SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts*/@@ -35,7 +34,7 @@ export interface UseAnimatedLayoutOptions {** `containerRef` names the area: an app passes the ref it already gives its* scroll container or panel (a ScrollableArea's ref reaches its native scroll- * viewport). The handle has no public members (`spec:AST-105` FR1).+ * viewport). The handle has no public members.** @example* ```diff --git a/packages/core/src/hooks/useAutoMediaMode.ts b/packages/core/src/hooks/useAutoMediaMode.tsindex d674a3aa06..1db042429b 100644--- a/packages/core/src/hooks/useAutoMediaMode.ts+++ b/packages/core/src/hooks/useAutoMediaMode.ts@@ -6,33 +6,20 @@* @file useAutoMediaMode.ts* @input Ref to the element whose backdrop should be measured* @output 'dark' | 'light' | null (not yet measurable)- * @position INTERNAL — powers `MediaTheme mode="auto"`. Not exported from the- * package: MediaTheme is the supported surface for this behavior.- * Sibling to useImageMode, which answers the same question for images.- *- * Picks the media context a surface wants by measuring what the browser- * actually painted, rather than trusting a token's name.- *- * The bug it exists for: `--color-background-inverted` is not required to be- * inverted. A theme can define it as a pale grey, and a hardcoded- * `mode="dark"` then paints white text on it at 1.25:1. Because the surface- * colour is a runtime value and the mode is a compile-time guess, no amount- * of care in the component can catch that.- *- * The answer can also be `'off'`: when the surface's own ambient text already- * reads on it, the surface is not effectively inverted and does not want a- * media context. Verified in Chromium that this loses nothing on a surface- * that is chromatic but legible — the dark-mode error toast renders- * identically either way, because a dark page already resolves those tokens- * to the values the media context would install.- *- * @example- * ```- * // Inside MediaTheme; see its `mode="auto"`.- * const detected = useAutoMediaMode(ref, mode === 'auto');- * ```+ * @position Internal; powers `MediaTheme mode="auto"`. Not exported from the+ * package. Sibling to useImageMode, which does the same for images.*/+// The hook measures what the browser painted and does not trust a token's+// name. `--color-background-inverted` need not be inverted: a theme can make+// it pale grey, and a fixed `mode="dark"` then paints white text on it at+// 1.25:1. The surface color is a runtime value, so only a measurement can+// catch this.+//+// The answer can be `'off'` when the surface's own text already reads on it.+// A dark page already resolves those tokens to the media context's values,+// so a chromatic but legible surface loses nothing.+import {useRef, useState} from 'react';import type {RefObject} from 'react';import type {RGBA} from '../utils/color';@@ -45,17 +32,11 @@ import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';export type DetectedMediaMode = 'dark' | 'light' | 'off';/**- * Resolve token references to the colors they actually paint, by reading them- * back off a hidden probe.- *- * A custom property cannot simply be read: `getPropertyValue` returns the- * token's *specified* text, and Astryx tokens are `light-dark(a, b)` pairs- * that resolve only once used in a real property. The probe assigns each- * token to `color` and reads the computed value back, which the browser has- * resolved against the host's own color-scheme and any overrides.- *- * `display: none` keeps the probe out of layout — computed color still- * resolves — so this costs a style recalc and no reflow.+ * Resolve token references to the colors they paint, through a hidden probe.+ * `getPropertyValue` returns a token's specified text, and Astryx tokens are+ * `light-dark(a, b)` pairs that resolve only in a real property. The probe+ * sets each token as `color` and reads the computed value. `display: none`+ * keeps the probe out of layout, so this costs a style recalc and no reflow.*/function resolvePaintedColors(host: HTMLElement,@@ -116,14 +97,11 @@ function resolveBackdrop(element: HTMLElement): RGBA | null {}/**- * Contrast at which a surface's own ambient text counts as reading well- * enough that no media context is wanted.- *- * WCAG's non-text / large-text line. It is deliberately low: this decides- * whether a surface is *effectively inverted*, not whether its text meets a- * standard. A pairing that clears 3:1 is one the theme is rendering- * successfully, and swapping in a media context there changes accent,- * overlays and borders for no legibility gain.+ * Contrast at which a surface's own text reads well enough that no media+ * context is wanted. This is WCAG's large-text line. It is low on purpose: it+ * decides if a surface is effectively inverted, not if its text meets a+ * standard. A media context on a 3:1 pairing changes accent, overlays and+ * borders with no legibility gain.*/const AMBIENT_READS_AT = 3;@@ -182,12 +160,10 @@ export function useAutoMediaMode(const {tokens} = useTheme();const lastRef = useRef<{background: string; tokens: unknown} | null>(null);- // Deliberately no dependency array. A surface's color is a painted value:- // it changes when a prop on some ancestor changes, and no dependency this- // hook could name would catch that (an earlier revision took a `watch`- // array and silently went stale whenever a caller forgot an entry). So the- // measurement re-runs whenever anything re-renders, and skips its own- // expensive half when nothing moved — see the early return below.+ // No dependency array. A surface color is a painted value, and it changes+ // when a prop on some ancestor changes. No dependency that this hook can+ // name catches that. So the measurement runs on each render, and it skips+ // its expensive half when nothing moved (see the early return below).useIsomorphicLayoutEffect(() => {const surface = ref.current?.parentElement ?? null;if (!isEnabled || surface === null) {@@ -199,10 +175,9 @@ export function useAutoMediaMode(return;}- // The backdrop walk above is a couple of getComputedStyle reads; the- // probe below appends a node and forces another style resolution. Skip- // it when neither the painted backdrop nor the theme has moved, which is- // the overwhelmingly common render.+ // The probe adds a node and forces another style resolution. Skip it when+ // neither the painted backdrop nor the theme moved, which is the usual+ // case.const backgroundKey = formatColor(background);const last = lastRef.current;if (diff --git a/packages/core/src/hooks/useBusyAnnouncement.ts b/packages/core/src/hooks/useBusyAnnouncement.tsindex eb39a53630..9b98ac171d 100644--- a/packages/core/src/hooks/useBusyAnnouncement.ts+++ b/packages/core/src/hooks/useBusyAnnouncement.ts@@ -8,24 +8,19 @@* to an element inside the control* @output Announces each busy start once, through the shared polite channel* or a persistent region inside the open modal dialog holding the control- * @position Core a11y hook for controls that show a decorative busy Spinner- *- * The busy Spinner inside a control is decorative (hidden, no live role); the- * control announces its busy state instead (`spec:AST-086` FR8), once per busy- * start (FR6): rerenders and StrictMode replay do not repeat it, and settling- * re-arms it. The returned function is called by an owner announcing the- * busy operation's outcome: a busy start not yet announced is dropped, so it- * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not- * exposed, so a control inside it announces through that dialog's polite- * container, the one `useAnnounce` uses for every message from inside the- * modal (FR14), inserted empty and filled a frame later (FR3); the control's- * own element locates the modal, so a busy start inside a native modal an app- * renders without Astryx is heard inside it too.- *- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —- * this is a shared implementation detail of Astryx's busy controls.+ * @position Core a11y hook for controls that show a decorative busy Spinner.+ * It is a shared detail of the busy controls, so it is not in hooks/index.ts.*/+// The busy Spinner is decorative, so the control announces its busy state,+// once for each busy start (AST-086). A re-render or a StrictMode replay does+// not repeat it, and the settle re-arms it. An owner calls the returned function+// when it announces the outcome. A busy start that is not yet announced is+// then dropped, so it never follows its own outcome. While a native modal is+// open, the page-body channel is not exposed. So a control in a modal+// announces through that dialog's polite region, also in a modal that an app+// renders without Astryx.+import {useCallback, useEffect, useRef, type RefObject} from 'react';import {announceInModal,@@ -65,10 +60,8 @@ export function useBusyAnnouncement(const frame = requestAnimationFrame(() => {frameRef.current = null;hasAnnouncedRef.current = true;- // The nearest open native modal around the control's own element,- // Astryx or app-rendered, so a busy start inside a modal an app renders- // without Astryx is still heard inside it (`spec:AST-086` FR14); the- // shared `useAnnounce` route otherwise, which itself follows the+ // The nearest open native modal around the control's element, Astryx or+ // app-rendered. Else the shared `useAnnounce` route, which follows the// nearest Astryx modal around this hook's caller.const dialog = enclosingModalDialog(elementRef.current);if (dialog != null) {diff --git a/packages/core/src/hooks/useClickableContainer.ts b/packages/core/src/hooks/useClickableContainer.tsindex a6781ce57f..03c571b4c4 100644--- a/packages/core/src/hooks/useClickableContainer.ts+++ b/packages/core/src/hooks/useClickableContainer.ts@@ -7,15 +7,9 @@* @input Container ref, interactive element ref, click/href handlers* @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;* hasInteractiveAncestor and the shared innermostInteractive walk- * @position Core hook for clickable containers that safely handle nested interactive elements- *- * Solves the "nested interactive elements" problem: when a card is clickable- * but contains buttons/links, clicking those should NOT trigger the card's action.- *- * Every navigation exit here (window.open, location.href, and the delegated- * click on the interactive ref) runs after the shared navigation-destination- * rule in utils/safeUrl.ts; a blocked href does not navigate by any- * activation method.+ * @position Core hook for clickable containers with nested interactive+ * elements. A click on a nested button or link does not run the card's+ * action. Each navigation passes the rule in utils/safeUrl.ts first.** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts (export)@@ -117,8 +111,7 @@ export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {return innermostInteractive(el, rootEl, belongsToSomethingElse) != null;}-// A press inside an open Tooltip or HoverCard surface belongs to that surface-// (component:Tooltip FR11, component:HoverCard FR11).+// A press inside an open Tooltip or HoverCard surface belongs to that surface.function belongsToSomethingElse(element: Element): boolean {return matchesInteractiveSelectors(element) || isLayerSurface(element);}@@ -220,7 +213,6 @@ export function useClickableContainer({return;}- // Don't trigger on text selectionif (hasTextSelection(containerEl)) {return;}@@ -230,7 +222,6 @@ export function useClickableContainer({return;}- // If the click landed on or inside a nested interactive element, bailif (eventTarget !== event.currentTarget &&hasInteractiveAncestor(eventTarget, containerEl)@@ -238,17 +229,15 @@ export function useClickableContainer({return;}- // Fire the click handleronClickProp?.(event);if (event.defaultPrevented) {return;}- // Navigate if href is provided. React DOM vets the hrefs it writes as- // attributes; nothing below passes through React, so the shared- // navigation rule decides once, before target, modifier key, or the- // delegated anchor can select a sink. A blocked href simply does not- // navigate — the click handler above still ran.+ // React DOM checks the hrefs that it writes, but nothing below passes+ // through React. So the shared navigation rule decides once, before the+ // target, a modifier key, or the delegated anchor picks a sink. A+ // blocked href does not navigate, but the click handler above still ran.if (href != null && isSafeUrl(href)) {const shouldOpenNewTab =target === '_blank' || event.ctrlKey || event.metaKey;diff --git a/packages/core/src/hooks/useDevWarning.ts b/packages/core/src/hooks/useDevWarning.tsindex cc141e2fc7..94553acb1b 100644--- a/packages/core/src/hooks/useDevWarning.ts+++ b/packages/core/src/hooks/useDevWarning.ts@@ -6,14 +6,9 @@* @file useDevWarning.ts* @input A component name, a message, and a boolean condition* @output Fires a dev-only `Component: message` warning once per mount- * @position Core hook; the render-safe way to warn the builder from a component- *- * The right way to surface a dev guardrail from inside a component. A naive- * `if (condition) console.warn(...)` in the render body repeats on every- * render, and reaching for `useState` to gate it adds needless state and- * re-renders. This hook uses a ref + effect: the warning fires once per mount- * when the condition holds, never during render, and never triggers a- * re-render. Messages use the standardized `Component: message` format.+ * @position Core hook; the render-safe way to warn the builder from a component.+ * A ref and an effect fire the warning once per mount, never during+ * render, and without a re-render.** SYNC: When modified, update:* - /packages/core/src/hooks/index.tsdiff --git a/packages/core/src/hooks/useEntryAnimation.ts b/packages/core/src/hooks/useEntryAnimation.tsindex 5bba2676a8..7c37657987 100644--- a/packages/core/src/hooks/useEntryAnimation.ts+++ b/packages/core/src/hooks/useEntryAnimation.ts@@ -7,9 +7,7 @@* @output Exports useEntryAnimation hook for mount-only entry animations* @position Hook utility; consumed by FieldStatus and available to consumers*- * Provides entry animations for conditionally rendered elements.- * Only animates when the element is dynamically mounted after the initial- * page paint — statically rendered elements on page load are not animated.+ * It animates only an element that mounts after the first page paint.* Server-rendered elements hydrate without the entry style and never play it* (spec:AST-013 FR13).*/diff --git a/packages/core/src/hooks/useHighlightedOptionScroll.ts b/packages/core/src/hooks/useHighlightedOptionScroll.tsindex 03f26e8355..4c72733ddd 100644--- a/packages/core/src/hooks/useHighlightedOptionScroll.ts+++ b/packages/core/src/hooks/useHighlightedOptionScroll.ts@@ -22,9 +22,7 @@ interface UseHighlightedOptionScrollOptions {getOptionId: (index: number) => string;/*** Current option count, when the list can change while open (filtered or- * min/max-clamped lists). A count change re-runs the scroll, matching the- * list-length dependency the per-component effects carried before this hook- * existed.+ * min/max-clamped lists). A count change runs the scroll again.*/itemCount?: number;}@@ -33,7 +31,7 @@ interface UseHighlightedOptionScrollOptions {* Keep the highlighted option visible during keyboard navigation — but not for* hover highlights. Hover must highlight only: scrollIntoView moves the next* option under the stationary pointer, whose mouseenter re-highlights and- * scrolls again — a runaway auto-scroll loop with no user input (#6077).+ * scrolls again — a runaway auto-scroll loop with no user input.* Keyboard paths call the raw setter directly and keep their scrolling; hover* paths call the returned callback.*/diff --git a/packages/core/src/hooks/useHotkeys.ts b/packages/core/src/hooks/useHotkeys.tsindex ad8f3e25e6..4ba1f27e00 100644--- a/packages/core/src/hooks/useHotkeys.ts+++ b/packages/core/src/hooks/useHotkeys.ts@@ -4,22 +4,10 @@/*** @file useHotkeys.ts- * @input Uses React useEffect, useRef- * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts- * @position Core hook; used by consumers for app-level keyboard shortcuts- *- * Registers a single window keydown listener per hook instance. Handlers- * are kept in a ref so re-renders never re-subscribe (subscribe once on- * mount, unsubscribe on unmount). SSR-safe — window is only touched- * inside the effect.- *- * Skips events that are already handled (defaultPrevented) or during IME composition,- * and events targeting typing surfaces (input, textarea, select, contenteditable)- * unless a hotkey opts in via `allowInInputs`.- *- * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and- * ctrlKey elsewhere, through the same isApplePlatform util Kbd reads, so- * displayed and handled shortcuts cannot disagree.+ * @input React effects and refs+ * @output useHotkeys hook and Hotkey interface for global keyboard shortcuts+ * @position Core hook for app-level keyboard shortcuts. `mod` uses the same+ * isApplePlatform util as Kbd, so shown and handled shortcuts agree.** SYNC: When modified, update:* - /packages/core/src/hooks/index.tsdiff --git a/packages/core/src/hooks/useImageMode.ts b/packages/core/src/hooks/useImageMode.tsindex 25491f35db..3364cc3b9f 100644--- a/packages/core/src/hooks/useImageMode.ts+++ b/packages/core/src/hooks/useImageMode.ts@@ -7,31 +7,6 @@* @input Image source URL* @output Detected mode luminance: 'dark' | 'light' | null* @position Hook; used alongside MediaTheme for auto-detection- *- * Detects whether an image is predominantly dark or light by sampling- * its pixels via OffscreenCanvas. Runs entirely off the paint path —- * no visible canvas element, no layout thrash.- *- * Uses APCA perceptual lightness (sRGB linearization + power curve)- * which handles saturated colors better than BT.709 gamma-luma or- * WCAG 2 relative luminance.- *- * For regional detection (e.g. "what's the luminance where the text- * overlay sits"), pass a `region` option to sample a specific area.- *- * @example- * ```tsx- * function ImageCard({ src }: { src: string }) {- * const mode = useImageMode(src);- * return (- * <div style={{ backgroundImage: `url(${src})` }}>- * <MediaTheme mode={mode ?? 'dark'}>- * <Text>Auto-detected text color</Text>- * </MediaTheme>- * </div>- * );- * }- * ```*/import {useState, useEffect} from 'react';@@ -72,18 +47,9 @@ export interface UseImageModeOptions {}/**- * APCA perceptual lightness from sRGB values (0-255).- *- * Linearizes sRGB with a 2.4 exponent, computes luminance Y using- * APCA coefficients (slightly refined from BT.709), then applies a- * perceptual power curve (Y^0.56) that maps linear light to a scale- * where 0.5 ≈ perceptual mid-gray.- *- * This outperforms both raw BT.709 gamma-luma and WCAG 2 relative- * luminance for dark/light surface detection — especially on saturated- * colors (reds, blues) where gamma-encoded luma overestimates brightness.- *- * Returns 0–1 where 0 is black, 1 is white.+ * APCA perceptual lightness from sRGB values (0-255), from 0 (black) to 1+ * (white). It handles saturated colors better than BT.709 gamma-luma or WCAG+ * 2 relative luminance, which overestimate the brightness of reds and blues.*/function perceptualLightness(r: number, g: number, b: number): number {const lin = (c: number) => Math.pow(c / 255, 2.4);@@ -117,7 +83,6 @@ export function useImageMode(async function detect() {try {- // Load image as bitmap (async, doesn't block rendering)const response = await fetch(srcUrl, {mode: 'cors'});const blob = await response.blob();const bitmap = await createImageBitmap(blob);@@ -126,7 +91,6 @@ export function useImageMode(return;}- // Determine source regionconst sx = region ? Math.round(region.x * bitmap.width) : 0;const sy = region ? Math.round(region.y * bitmap.height) : 0;const sw = region@@ -136,9 +100,9 @@ export function useImageMode(? Math.round(region.height * bitmap.height): bitmap.height;- // Sample at a small size and average all pixels manually.- // OffscreenCanvas 1×1 drawImage can produce inaccurate results- // depending on the browser's resampling algorithm.+ // Sample at a small size and average the pixels here. A 1×1+ // OffscreenCanvas drawImage can be inaccurate, because browsers+ // resample in different ways.const sampleSize = 10;const canvas = new OffscreenCanvas(sampleSize, sampleSize);const ctx = canvas.getContext('2d');@@ -149,7 +113,6 @@ export function useImageMode(ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, sampleSize, sampleSize);const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize).data;- // Average all sampled pixelslet totalR = 0,totalG = 0,totalB = 0;diff --git a/packages/core/src/hooks/useInputStatusIcon.tsx b/packages/core/src/hooks/useInputStatusIcon.tsxindex 7c6af841b1..f9a3928a4e 100644--- a/packages/core/src/hooks/useInputStatusIcon.tsx+++ b/packages/core/src/hooks/useInputStatusIcon.tsx@@ -10,26 +10,6 @@** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts (exports)- *- * Centralizes the on-field status icon across the bordered inputs (TextInput,- * TextArea, NumberInput, DateInput, DateTimeInput, DateRangeInput, TimeInput,- * FileInput) so the three statusVariants behave consistently:- *- * - `attached` → icon sits inside the control; the message box below carries- * the text.- * - `detached` → the detached message box renders its OWN leading icon, so the- * on-field icon is suppressed here to avoid a duplicate glyph.- * - `tooltip` → no message box renders; the status is surfaced through an- * info-tip on the on-field icon. The icon is a real focusable `<button>` so- * the status is reachable by every user, not just those with hover or a- * screen reader:- * - Keyboard (no AT): the button is in the tab order (WCAG 2.1.1) with a- * visible focus ring (WCAG 2.4.7); focusing it opens the tooltip.- * - Pointer: hover opens it (guarded to fine pointers).- * - Touch: hover is unavailable, so a tap toggles the tooltip open/closed.- * - Assistive tech: the button has an accessible name (its status type,- * WCAG 4.1.2) and is described by the message via `aria-describedby`.- * - Dismissible with Escape and hoverable (WCAG 1.4.13) via useTooltip.*/import {useCallback, useEffect, useState} from 'react';@@ -92,12 +72,9 @@ const styles = stylex.create({default: 'pointer',':is(:disabled,[aria-disabled="true"])': 'default',},- // Own the interactivity so the tooltip opens on hover even when the field- // renders this affordance inside a non-interactive trailing slot. TextArea- // positions its end slot as an absolute overlay with `pointer-events: none`- // (right for the decorative spinner/icon it was built for), which otherwise- // swallows this button's hover — keyboard focus still worked, pointer did- // not.+ // The button owns its pointer events, so hover opens the tooltip in a+ // non-interactive trailing slot. TextArea's end slot has+ // `pointer-events: none`, which would block this button's hover.pointerEvents: 'auto',borderRadius: radiusVars['--radius-full'],// Not the shared offset: this button sits inside the field, and measured at@@ -138,7 +115,15 @@ export interface UseInputStatusIconReturn {/*** Builds the on-field status icon and its accessibility wiring for a bordered- * input. See the file header for the per-variant behavior.+ * input, so every bordered input shows status the same way:+ * - `attached`: the icon is in the control, and the message box below has+ * the text.+ * - `detached`: the message box shows its own leading icon, so this hook+ * shows none.+ * - `tooltip`: no message box. The icon is a focusable `<button>` with an+ * info-tip, so every user can reach the status. Focus or a fine-pointer+ * hover opens it, and a tap toggles it on touch. Its accessible name is the+ * status type, and the message describes it. Escape dismisses it.*/export function useInputStatusIcon({status,@@ -162,9 +147,8 @@ export function useInputStatusIcon({isOpen: tapOpen,});- // Re-hand control back to hover/focus once a tap-opened tooltip is dismissed- // (Escape/outside interaction), so subsequent pointer/keyboard use behaves- // normally.+ // Give control back to hover and focus after a tap-opened tooltip is+ // dismissed.const handleButtonBlur = useCallback(() => {setTapOpen(undefined);}, []);@@ -183,9 +167,8 @@ export function useInputStatusIcon({setTapOpen(prev => (prev === true ? false : true));}, []);- // Dismiss a tap-opened tooltip on Escape and return to the uncontrolled- // state (useTooltip owns Escape for the uncontrolled case, but while we hold- // control via isOpen it does not, so mirror it here).+ // Escape dismisses a tap-opened tooltip and returns to the uncontrolled+ // state. useTooltip handles Escape only when it is uncontrolled.useEffect(() => {if (tapOpen !== true) {return;@@ -213,11 +196,9 @@ export function useInputStatusIcon({icon={STATUS_ICON[status.type]}size={size}color={status.type}- // Stable theme target on the status glyph itself, so a theme can restyle- // just this icon (color, size) — and each status — via `defineTheme`.- // Same-element rules in @layer astryx-theme win over the icon's own base- // width/height/fontSize, which a field-level target could not reach.- // Shared by the attached and tooltip variants across all bordered inputs.+ // A stable theme target on the glyph, so a theme can restyle this icon+ // for each status. Same-element rules in @layer astryx-theme override+ // the icon's base size, which a field-level target cannot reach.{...themeProps('input-status-icon', {size, status: status.type})}/>);diff --git a/packages/core/src/hooks/useInteractiveRole.ts b/packages/core/src/hooks/useInteractiveRole.tsindex be9b1b60ae..827d4fc738 100644--- a/packages/core/src/hooks/useInteractiveRole.ts+++ b/packages/core/src/hooks/useInteractiveRole.ts@@ -4,24 +4,11 @@/*** @file useInteractiveRole.ts- * @input Uses useInteractiveTrigger- * @output Exports useInteractiveRole hook and InteractiveRole type- * @position Hook utility; consumed by Token, Thumbnail, Item, ClickableCard, etc.- *- * Centralizes the "what element should I render as?" decision for- * polymorphic components. The priority order:- *- * 1. href → 'link' (navigation always wins, unless disabled)- * 2. onClick → 'button' (explicit interactivity)- * 3. interactive trigger context → 'button' (implicit via parent)- * 4. else → 'inert' (non-interactive)- *- * A disabled `href` is excluded at step 1 and therefore resolves via the- * remaining steps — 'inert' when no onClick or context applies.- *- * This hook is the single place to add new context-based triggers- * (e.g., Popover, DropdownMenu, Disclosure). Components that consume- * this hook never need updating when new trigger contexts are added.+ * @input useInteractiveTrigger+ * @output useInteractiveRole hook and InteractiveRole type+ * @position Hook utility for polymorphic components such as Token, Thumbnail,+ * Item and ClickableCard. Add new context-based triggers here, so the+ * components that use this hook need no change.** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts (export)@@ -90,13 +77,11 @@ export function useInteractiveRole({}: UseInteractiveRoleOptions): InteractiveRole {const contextRole = useInteractiveRoleContext();- // 1. href → link (unless disabled — a disabled href is skipped here and- // resolved by the checks below, landing on 'inert' if nothing else applies)+ // A disabled href is skipped, so the checks below decide the role.if (href != null && !isDisabled) {return 'link';}- // 2. Explicit onClick → buttonif (onClick != null) {return 'button';}@@ -106,6 +91,5 @@ export function useInteractiveRole({return contextRole;}- // 4. Nothing interactive → inertreturn 'inert';}diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex 880e37261c..aaaacd2169 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -139,11 +139,10 @@ export interface InternalListFocusOptions extends UseListFocusOptions {*/tabStopOrder?: (list: HTMLElement) => ReadonlyArray<HTMLElement>;/**- * Moves focus with the focus the last input calls for- * (`architecture:interaction-modality` INV1): after a pointer press a- * focused item shows no keyboard ring, after a key press it does. For a list- * whose items draw the ring and that opens from a pointer, such as a context- * menu. Unset (the default): a plain `focus()`.+ * Moves focus with the modality of the last input: after a pointer press a+ * focused item shows no keyboard ring, and after a key press it does. Use it+ * for a list whose items draw the ring and that opens from a pointer, such as+ * a context menu. Unset (the default): a plain `focus()`.*/focusFollowsLastInput?: boolean;}diff --git a/packages/core/src/hooks/useOverflow.ts b/packages/core/src/hooks/useOverflow.tsindex 3cc134d6ff..8df30b94d3 100644--- a/packages/core/src/hooks/useOverflow.ts+++ b/packages/core/src/hooks/useOverflow.ts@@ -6,14 +6,9 @@* @file useOverflow.ts* @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect* @output Exports useOverflow hook for measuring and managing horizontal overflow- * @position Core hook; used by OverflowList and consumers for overflow patterns- *- * Measures children rendered in a hidden container to determine how many fit- * in the available width, without flickering. Observes both the visible and- * hidden measurement containers so changes to available width or measured child- * sizes recalculate the result. Supports an optional item cap (`maxVisibleItems`)- * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math- * lives in the pure `computeOverflow` helper.+ * @position Core hook; used by OverflowList and consumers for overflow patterns.+ * Hidden copies of the children are measured, so nothing flickers. The+ * fit, clamp and row math lives in the pure `computeOverflow` helper.** SYNC: When modified, update:* - /packages/core/src/hooks/index.tsdiff --git a/packages/core/src/hooks/useRenamedProp.ts b/packages/core/src/hooks/useRenamedProp.tsindex 9c589bbec4..b95ef7a14f 100644--- a/packages/core/src/hooks/useRenamedProp.ts+++ b/packages/core/src/hooks/useRenamedProp.ts@@ -6,25 +6,16 @@* @file useRenamedProp.ts* @input The component name, the old and new prop names, and both values* @output The value to use, with development warnings for the overlap- * @position Core deprecation utility; the replacement-first half of a prop- * rename- *- * A released prop is a public promise, so a rename ships the replacement- * first and keeps the old name working through the overlap (`spec:AST-017`- * FR28–FR29, `architecture:public-component-api` INV9). This centralizes the- * two things every such overlap owes: the new name wins when both are set,- * and development says so rather than letting a caller wonder which one the- * component read.- *- * Production behavior is unchanged either way — a warning is a builder- * guardrail, never shipped noise (`spec:AST-017` FR29).- *- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —- * that barrel is re-exported wholesale from the package entry point, so- * adding it there would ship a new public hook without `spec:AST-002`- * admission. Import it by path from inside the package.+ * @position Core deprecation utility for the overlap of a prop rename. It is+ * not in hooks/index.ts, because that barrel is public and a new public hook+ * needs admission (AST-002). Import it by path.*/+// A released prop is a public promise. So a rename ships the replacement+// first and keeps the old name working for an overlap (AST-017). The new name+// wins when both are set, and development says so. Production behavior does+// not change.+import {useDevWarning} from './useDevWarning';export interface RenamedPropOptions<T> {diff --git a/packages/core/src/hooks/useScrollOverflow.ts b/packages/core/src/hooks/useScrollOverflow.tsindex 11818a5e47..4ed2a24d59 100644--- a/packages/core/src/hooks/useScrollOverflow.ts+++ b/packages/core/src/hooks/useScrollOverflow.ts@@ -4,28 +4,11 @@/*** @file useScrollOverflow.ts- * @input Uses React useRef, useState, useCallback, useEffect- * @output Exports useScrollOverflow hook for tracking scroll position edges+ * @input React refs, state and effects+ * @output useScrollOverflow, which tracks the overflow at the scroll edges* @position Core hook; used by Carousel and TabList for fade-edge and button* state*- * Observes a scroll container and reports whether content overflows at the- * start, end, or both edges. Updates on every scroll, and while the container- * is rendered on what else changes the overflow with or without the- * container resizing: its own size, a child's size (a slide's content- * growing), a child added or removed, and its class or style (a new gap or- * padding). A layout read on an element the browser is not- * rendering (an ancestor with `display: none`, or a `content-visibility:- * hidden` subtree) either answers zeros or makes the browser lay out that- * whole hidden subtree for the answer, so an observation delivered for a- * hidden container, and the measurement at registration inside one, are- * skipped; the hook keeps its last state until the resize observation that- * follows the reveal (one frame after it paints). A scroll is measured- * whether or not the container is rendered: a scroll of a hidden container- * is script's (a selected tab revealed under a hidden panel), its layout is- * already the scroll's, and a reveal at the same size brings no resize to- * measure it with.- ** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts*/@@ -144,10 +127,10 @@ export function useScrollOverflow() {});}, []);- // Registration, resize and content changes: only a rendered container. A- // hidden one has no edges to report, and reading its layout would make the- // browser render the hidden subtree it sits in; the resize observation that- // follows the reveal measures again.+ // Only a rendered container is measured at registration and on a resize or+ // content change. A layout read on a hidden one makes the browser render+ // its hidden subtree. The resize observation after the reveal measures+ // again.const measure = useCallback(() => {const el = elRef.current;if (el && isRendered(el)) {@@ -155,10 +138,9 @@ export function useScrollOverflow() {}}, [measureNow]);- // A scroll: measured hidden or not. Script scrolled the hidden container- // (its layout is already the scroll's), and a reveal at the same size- // brings no resize observation, so this is the read that keeps the edges- // right for it.+ // A scroll is measured hidden or not. Script scrolled the hidden container,+ // so its layout is already current. A reveal at the same size brings no+ // resize observation, so this read keeps the edges right.const measureOnScroll = useCallback(() => {const el = elRef.current;if (el) {diff --git a/packages/core/src/hooks/useScrollableArea.ts b/packages/core/src/hooks/useScrollableArea.tsindex 8c0f9789d2..afdbf1b66e 100644--- a/packages/core/src/hooks/useScrollableArea.ts+++ b/packages/core/src/hooks/useScrollableArea.ts@@ -8,10 +8,8 @@* @output Safe prop getters, native keyboard entry, and stable per-axis effective scroll state* @position Canonical behavior core for ScrollableArea and structure-owning adopters*- * Geometry and style signals coalesce into one full measurement per frame. A- * scroll only moves the offset, so its event re-derives the logical edges- * from box geometry: no computed-style read and no extra frame while the- * user scrolls.+ * Geometry and style signals cause one full measurement per frame. A scroll+ * moves only the offset, so it reads only box geometry.** SYNC: When modified, update:* - /packages/core/src/hooks/useScrollableArea.doc.mjs@@ -303,15 +301,12 @@ export function useScrollableArea({frame = window.requestAnimationFrame(measure);};- // A scroll moves the offset and nothing else, so it only re-derives the- // logical edges, from box geometry, as the scroll event is dispatched.- // Browsers fire it at most once per frame, before animation-frame- // callbacks, when style and layout are normally still clean from the last- // frame: no computed style is read, no frame is requested, and the edges- // are current in the frame that moved. Anything a scroll cannot explain- // (overflow appearing or going away on a requested axis, or an offset- // whose sign the measured writing direction rules out) schedules the- // full measurement, as every other invalidation does.+ // A scroll moves only the offset, so it derives the logical edges from+ // box geometry when the event fires. Style and layout are usually still+ // clean then, so no computed style is read and no frame is requested.+ // When the scroll cannot explain a change (overflow on a requested axis+ // appears or goes away, or the offset sign does not match the writing+ // direction), it schedules the full measurement.const onScroll = () => {if (!isActive || frame != null) {// A full measurement is already pending for this frame.@@ -427,14 +422,12 @@ export function useScrollableArea({};}, [axis, content, viewport]);- // The first measure reads the viewport before this hook has let an- // overflowing axis scroll (it is `clip` until then), so it finds overflow- // but no scrollable axis yet. Measure again in the same commit once an axis- // has just gained overflow (or the axis mapping changed), so the viewport is- // a tab stop from the first frame it scrolls, not an animation frame later- // (`spec:AST-025` FR12). Only on a gain: content that fits only once a- // scrollbar takes space would otherwise flip overflow back and forth inside- // one commit; a loss waits for the next frame, as before.+ // The first measure runs before an overflowing axis can scroll (it is+ // `clip` until then). So when an axis gains overflow, or the axis mapping+ // changes, measure again in the same commit. Then the viewport is a tab+ // stop from the first frame it scrolls (AST-025). Do this only on a gain:+ // content that fits only when a scrollbar takes space would flip in one+ // commit. A loss waits for the next frame.const previousOverflowRef = useRef<LogicalOverflowGeometry>(INITIAL_OVERFLOW);const previousMappingRef = useRef<LogicalAxisMapping>(INITIAL_MAPPING);useIsomorphicLayoutEffect(() => {diff --git a/packages/core/src/hooks/useStreamingText.ts b/packages/core/src/hooks/useStreamingText.tsindex 55b441e1a2..271073482d 100644--- a/packages/core/src/hooks/useStreamingText.ts+++ b/packages/core/src/hooks/useStreamingText.ts@@ -4,21 +4,10 @@/*** @file useStreamingText.ts- * @input Uses React useState, useEffect, useRef, useMediaQuery, useTheme- * @output Exports useStreamingText hook for smooth text streaming- * @position Core hook; smooths bursty streamed text into steady character reveal- *- * Decouples the arrival rate of streamed chunks from the display rate,- * draining characters at a steady pace using requestAnimationFrame. The- * reveal cadence advances by a fixed number of UTF-16 code units per tick;- * the rendered slice is then snapped back to the nearest grapheme cluster- * boundary (see snapToGraphemeBoundary) so a tick landing inside a- * surrogate pair, flag sequence, or ZWJ emoji doesn't render a lone- * surrogate or a partial glyph for one frame.- *- * Animation timing derives from Astryx motion tokens (via useTheme) when- * an Theme provider is present. Falls back to sensible defaults when- * used outside a theme provider.+ * @input React state, effects and refs; useMediaQuery; useTheme+ * @output useStreamingText hook for smooth text streaming+ * @position Core hook; smooths bursty streamed text into a steady reveal.+ * Timing comes from the motion tokens, with defaults outside a theme.** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts (exports)@@ -71,9 +60,8 @@ const CHARS_PER_TICK = {instant: Infinity,} as const;-// Reuse a single segmenter when the runtime supports Intl.Segmenter.-// Granularity is fixed and locale doesn't affect grapheme-cluster-// boundaries, so one instance is safe to share across calls.+// One shared segmenter. The granularity is fixed, and the locale does not+// change grapheme boundaries.const graphemeSegmenter =typeof Intl.Segmenter === 'function'? new Intl.Segmenter(undefined, {granularity: 'grapheme'})@@ -100,9 +88,8 @@ export function snapToGraphemeBoundary(text: string, offset: number): number {return offset;}if (graphemeSegmenter) {- // `containing` only returns undefined for an out-of-range index; offset- // is already guarded to [1, text.length - 1] above, so this is always- // defined at runtime — the `??` is to satisfy the type, which is wider.+ // The guard above keeps offset in range, so `containing` is defined. The+ // `??` satisfies the wider type.return graphemeSegmenter.segment(text).containing(offset)?.index ?? offset;}return isLowSurrogate(text.charCodeAt(offset)) ? offset - 1 : offset;@@ -141,9 +128,8 @@ export function useStreamingText(const speed = options?.speed ?? 'natural';const charsPerTick = CHARS_PER_TICK[speed];- // Derive tick timing from Astryx motion tokens when available.- // natural → --duration-fast-min (frame-level cadence from the theme)- // fast → half that, floored at 4ms (roughly 2x speed)+ // Tick timing comes from the motion tokens: natural uses+ // --duration-fast-min, and fast uses half of it, at least 4ms.const {token} = useTheme();const tickMs = useMemo(() => {if (speed === 'instant') {@@ -153,8 +139,8 @@ export function useStreamingText(if (base == null) {return speed === 'fast' ? FALLBACK_TICK_MS_FAST : FALLBACK_TICK_MS;}- // Scale: use ~1/10th of the theme's fast-min duration as the per-frame tick.- // This maps a 130ms token to ~13ms tick (natural) or ~6.5ms tick (fast).+ // The per-frame tick is about 1/10 of the fast-min duration, so a 130ms+ // token gives a 13ms tick (natural) or a 6.5ms tick (fast).const tick = speed === 'fast' ? base / 20 : base / 10;return Math.max(4, Math.round(tick));}, [token, speed]);@@ -165,7 +151,6 @@ export function useStreamingText(const lastTickRef = useRef(0);const rafRef = useRef<number | null>(null);- // Keep target ref in synctargetRef.current = targetText;// Reset when target clears (new message)@@ -178,7 +163,6 @@ export function useStreamingText(}}- // Snap to full text when streaming endsconst prevIsStreamingRef = useRef(isStreaming);if (isStreaming !== prevIsStreamingRef.current) {prevIsStreamingRef.current = isStreaming;@@ -188,15 +172,12 @@ export function useStreamingText(}}- // Respect the user's reduced-motion preference — skip the progressive- // reveal and snap straight to the full text. Uses the package's SSR-safe- // useMediaQuery (useMediaQuery.ts) so the read stays in sync if the- // preference changes mid-stream.+ // Reduced motion skips the progressive reveal and shows the full text.+ // useMediaQuery follows a preference change mid-stream.const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)',);- // Animation loopuseEffect(() => {if (!isStreaming || speed === 'instant' || prefersReducedMotion) {return;diff --git a/packages/core/src/hooks/useTreeFocus.ts b/packages/core/src/hooks/useTreeFocus.tsindex 61e169681e..ed70fe1089 100644--- a/packages/core/src/hooks/useTreeFocus.ts+++ b/packages/core/src/hooks/useTreeFocus.ts@@ -268,7 +268,7 @@ export type UseTreeFocusInternalReturn<T extends HTMLElement = HTMLElement> =* With `hasRovingTabIndex`, makes `item` the tree's one Tab stop, by the* same rule the hook's own moves follow: a disabled or hidden row never* takes it, and the stop stays where it is. TreeList calls it when it- * moves focus to a collapsing row (`component:TreeList` AR2).+ * moves focus to a collapsing row.*/takeTabStop: (item: HTMLElement) => void;};@@ -468,8 +468,8 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(...items.slice(0, start + offset),];const enabled = ordered.filter(item => !itemDisabled(item));- // INV17: case, accents, stroked letters and Turkish i fold away, and a- // typed mark prefers the exact match.+ // Case, accents, stroked letters and Turkish i fold away, and a typed+ // mark prefers the exact match.const matchIndex = findTypeaheadMatch(enabled.map((_, i) => i),i => itemLabelText(enabled[i], matchLabelledBy),