Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/core/src/hooks/ModalAnnounceProvider.tsx b/packages/core/src/hooks/ModalAnnounceProvider.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 selection
if (hasTextSelection(containerEl)) {
return;
}
@@ -230,7 +222,6 @@ export function useClickableContainer({
return;
}
- // If the click landed on or inside a nested interactive element, bail
if (
eventTarget !== event.currentTarget &&
hasInteractiveAncestor(eventTarget, containerEl)
@@ -238,17 +229,15 @@ export function useClickableContainer({
return;
}
- // Fire the click handler
onClickProp?.(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.ts
index 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.ts
diff --git a/packages/core/src/hooks/useEntryAnimation.ts b/packages/core/src/hooks/useEntryAnimation.ts
index 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.ts
index 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.ts
index 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.ts
diff --git a/packages/core/src/hooks/useImageMode.ts b/packages/core/src/hooks/useImageMode.ts
index 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 region
const 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 pixels
let totalR = 0,
totalG = 0,
totalB = 0;
diff --git a/packages/core/src/hooks/useInputStatusIcon.tsx b/packages/core/src/hooks/useInputStatusIcon.tsx
index 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.ts
index 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 → button
if (onClick != null) {
return 'button';
}
@@ -106,6 +91,5 @@ export function useInteractiveRole({
return contextRole;
}
- // 4. Nothing interactive → inert
return 'inert';
}
diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.ts
index 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.ts
index 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.ts
diff --git a/packages/core/src/hooks/useRenamedProp.ts b/packages/core/src/hooks/useRenamedProp.ts
index 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.ts
index 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.ts
index 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.ts
index 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 sync
targetRef.current = targetText;
// Reset when target clears (new message)
@@ -178,7 +163,6 @@ export function useStreamingText(
}
}
- // Snap to full text when streaming ends
const 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 loop
useEffect(() => {
if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
return;
diff --git a/packages/core/src/hooks/useTreeFocus.ts b/packages/core/src/hooks/useTreeFocus.ts
index 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),