Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(utils): trim the remaining long utility comments (#9527)

Cindy Zhang2d6154dc5c51
diff --git a/.changeset/utils-comment-cleanup-2.md b/.changeset/utils-comment-cleanup-2.md
new file mode 100644
index 0000000000..a1c0f4aec6
--- /dev/null
+++ b/.changeset/utils-comment-cleanup-2.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] More source comments in the core utilities are shorter and explain only non-obvious reasons. Nothing a consumer imports or renders changes.
+
+@cixzhang
diff --git a/packages/core/src/utils/coarsePointer.ts b/packages/core/src/utils/coarsePointer.ts
index f279922c50..a4fca81351 100644
--- a/packages/core/src/utils/coarsePointer.ts
+++ b/packages/core/src/utils/coarsePointer.ts
@@ -9,13 +9,11 @@
* the press controller (pressFeedback.ts): touch-only work registers only
* while it holds
*
- * Where the primary pointer is coarse, a phone's touch work stays
- * registered: the gesture host's page listeners, the page hold and the
- * finger scroll. Where it is fine, recognizers still attach for every
- * pointer, and the host listens on the page only during a press
- * (`spec:AST-094` FR19, FR24, FR43). The query is TOUCH_QUERY, from
- * touchQueries.ts, which loads without React. The answer can change while
- * the page is open (a tablet docking a mouse), so a holder watches it.
+ * Under a coarse primary pointer, a phone's touch work stays registered: the
+ * gesture host's page listeners, the page hold and the finger scroll. Under a
+ * fine one, recognizers still attach, and the host listens on the page only
+ * during a press (AST-094). The answer can change while the page is open (a
+ * tablet docking a mouse), so a holder watches it.
*
* SYNC: When modified, update coarsePointer.test.ts.
*/
diff --git a/packages/core/src/utils/devWarning.ts b/packages/core/src/utils/devWarning.ts
index 0ce68590cf..cd16aa3503 100644
--- a/packages/core/src/utils/devWarning.ts
+++ b/packages/core/src/utils/devWarning.ts
@@ -6,15 +6,10 @@
* @output Standardized `Component: message` console warnings and errors
* @position Shared dev-logging utility used across components and hooks
*
- * Standardizes how the design system surfaces information to the builder:
- * every message reads `Component: message` (e.g. `Field: isOptional and
- * isRequired are mutually exclusive.`), so the source is always obvious in
- * the console.
- *
- * Prefer the `useDevWarning` hook inside components — it guards against
- * repeating a warning on every render. These imperative helpers exist for
- * the non-render contexts a hook can't cover: plain functions, module
- * initialization, and inside effects.
+ * Every message reads `Component: message`, so the source is clear in the
+ * console. Prefer `useDevWarning` in components, because it does not repeat
+ * a warning on each render. These helpers are for plain functions, module
+ * initialization and effects.
*
* SYNC: When modified, update:
* - /packages/core/src/utils/index.ts
diff --git a/packages/core/src/utils/focusOutline.stylex.ts b/packages/core/src/utils/focusOutline.stylex.ts
index 56c2341eee..e240078cd7 100644
--- a/packages/core/src/utils/focusOutline.stylex.ts
+++ b/packages/core/src/utils/focusOutline.stylex.ts
@@ -5,24 +5,15 @@
* @input Uses StyleX and theme color tokens
* @output Exports shared focus-outline prop builders
* @position Internal utility for consistent keyboard focus outlines across core components
- *
- * Centralizes the standard Astryx focus outline, shown only for keyboard focus.
- * Every focusable surface drew the same 2px accent ring already; writing it per
- * component meant dozens of identical definitions to keep in step, and they did
- * not stay in step — offsets drifted and one ring was a border-width thick.
- *
- * Every ring in core and lab is drawn from here, with one exception recorded in
- * Switch: its condition is a component-scoped ancestor marker, which cannot be
- * shared without leaking focus state between components. A component may still
- * override the OFFSET (a ring that must sit inset, or clear of a field border);
- * width, style and color are not restated anywhere.
- *
- * Every value comes from the `--focus-outline-*` tokens, which is how a theme
- * restyles the ring: one override reaches every component at once. The
- * `:focus-visible` condition is not themeable and stays here, so a theme can
- * change what the ring looks like but cannot show it to pointer users.
*/
+// Every ring in core and lab comes from here, except Switch's: its condition
+// is a component-scoped ancestor marker, which cannot be shared without
+// leaking focus state. A component may override only the offset. The values
+// come from the `--focus-outline-*` tokens, so a theme restyles every ring at
+// once. The `:focus-visible` condition is not themeable, so a theme cannot
+// show the ring to pointer users.
+
import * as stylex from '@stylexjs/stylex';
import {focusVars} from '../theme/tokens.stylex';
@@ -162,10 +153,9 @@ export const focusOutlineStyles = stylex.create({
},
/**
* Like {@link focusOutlineStyles.focusWithin}, but only for a direct child
- * with `role="combobox"` — for a control box that paints the ring for its
+ * with `role="combobox"`: for a control box that paints the ring for its
* combobox trigger while sibling controls inside it (a status info-tip, a
- * clear button) ring themselves. One focus move, one ring
- * (architecture:interaction-modality INV3).
+ * clear button) ring themselves. One focus move shows one ring.
*/
focusWithinCombobox: {
outlineWidth: {
diff --git a/packages/core/src/utils/focusReturn.ts b/packages/core/src/utils/focusReturn.ts
index 7dbf32c7b3..cd7f305801 100644
--- a/packages/core/src/utils/focusReturn.ts
+++ b/packages/core/src/utils/focusReturn.ts
@@ -12,7 +12,7 @@
* that return focus to their control when the overlay closes, but only when
* the dismiss did not already move focus somewhere the user chose, and by
* overlays (Dialog, DropdownMenu) that move focus programmatically, and by
- * disclosures that hide focused content (`component:SideNav` AR3). Only
+ * disclosures that hide focused content. Only
* `isFocusDetached` is exported from the utils entry; the rest is internal.
*/
@@ -104,8 +104,7 @@ export function moveFocusLeftBehind(
}
/**
- * Move focus programmatically so its ring follows the last input
- * (`architecture:interaction-modality` INV1). After pointer input the browser's
+ * Move focus programmatically so its ring follows the last input. After pointer input the browser's
* focus option keeps the element from matching `:focus-visible`, which is the
* one way to reach an element the overlay does not render: the consumer's
* autofocus target, the control that opened a Dialog, or a menu trigger the
diff --git a/packages/core/src/utils/hitArea.ts b/packages/core/src/utils/hitArea.ts
index 7d27556148..42d157a615 100644
--- a/packages/core/src/utils/hitArea.ts
+++ b/packages/core/src/utils/hitArea.ts
@@ -15,18 +15,16 @@
* a standalone control writes `watchHitArea`'s insets to an invisible
* coarse-only hit layer
*
- * A finger needs a 44 × 44 px target, but a control may not grow on a phone,
- * and its hit area must never take a neighbour's taps. Each side grows toward
- * the minimum size and stops at half the gap to the nearest neighbour on that
- * side (0 when they touch), so two neighbours' areas meet in the middle and a
- * tap always goes to the nearer target. CSS cannot see where the neighbours
- * are, so a live control measures: only where the primary pointer is coarse,
- * only while on screen, and every control pending a measurement in one read
- * pass per frame (all reads, then all writes), up to a 4 ms budget, the rest
- * carried to the next frame. Until the first pass the
- * insets are 0, so first paint and server rendering never overlap anything.
*/
+// A finger needs a 44 × 44 px target, but a control may not grow on a phone,
+// and its hit area must never take a neighbor's taps. Each side grows toward
+// the minimum and stops at half the gap to the nearest neighbor on that side,
+// so a tap always goes to the nearer target. CSS cannot see the neighbors, so a
+// live control measures: only under a coarse primary pointer (AST-094), only on
+// screen, and in one read pass per frame within a 4 ms budget. Until the first
+// pass the insets are 0, so first paint never overlaps anything.
+
import {observeContent} from './sharedMutationObserver';
/** A rect in client pixels. */
@@ -459,10 +457,9 @@ function scheduleAll(): void {
* neighbour, and the next tap uses the fresh insets.
*/
function onPress(event: Event): void {
- // One listener for every watched control, on the document: a control, a
- // row or a handle carries none of its own (a list's listeners stay the
- // list's, spec:AST-103 FR5). The innermost watched element the press
- // lands in is the one it is for.
+ // One listener on the document for every watched control, so a control, row
+ // or handle has none of its own (AST-103 FR5). The innermost watched element
+ // that the press lands in is the one it is for.
for (
let node: Element | null =
event.target instanceof Element ? event.target : null;
@@ -579,9 +576,9 @@ function observe(element: Element, entry: Watched): void {
}
/**
- * Everything that watches the page for hit areas: on only while the primary
- * pointer is coarse, so a mouse page runs no observer, timer or listener for
- * them (`spec:AST-094` FR24).
+ * Everything that watches the page for hit areas is on only while the
+ * primary pointer is coarse, so a mouse page runs no observer, timer or
+ * listener for them.
*/
function startObserving(): void {
if (view == null) {
diff --git a/packages/core/src/utils/inputPresentation.ts b/packages/core/src/utils/inputPresentation.ts
index 778c0fbb75..efe2e1f75d 100644
--- a/packages/core/src/utils/inputPresentation.ts
+++ b/packages/core/src/utils/inputPresentation.ts
@@ -4,16 +4,16 @@
* @file inputPresentation.ts
* @input A presentation policy, the deprecated nativePicker value, and pointer type
* @output The resolved picker surface for DateInput, DateTimeInput, and TimeInput
- * @position Shared presentation vocabulary owned by spec:AST-043
+ * @position Shared presentation vocabulary (AST-043)
*
* SYNC: When modified, update these files to stay in sync:
- * - /docs/specs/AST-043-input-presentation/spec.md (FR1–FR3 tables)
+ * - /docs/specs/AST-043-input-presentation/spec.md
* - /packages/core/src/DateInput/DateInput.tsx
* - /packages/core/src/DateTimeInput/DateTimeInput.tsx
* - /packages/core/src/TimeInput/TimeInput.tsx
*/
-/** Picker-surface policy for date/time inputs (`spec:AST-043` FR1). */
+/** Picker-surface policy for date/time inputs. */
export type InputPresentation =
| 'text-input'
| 'popover'
@@ -22,7 +22,7 @@ export type InputPresentation =
| 'adaptive-bottom-sheet'
| 'adaptive-native';
-/** `presentation` for components without a text-only surface: all except `TimeInput` exclude `text-input` (AST-043). */
+/** `presentation` for components without a text-only surface: all except `TimeInput` exclude `text-input`. */
export type PickerPresentation = Exclude<InputPresentation, 'text-input'>;
/** The surface a resolved `InputPresentation` actually renders. */
@@ -35,7 +35,7 @@ export type PickerPresentationSurface = Exclude<
'text-input'
>;
-/** Deprecated picker policy (`spec:AST-043` FR3). */
+/** Deprecated picker policy. */
export type LegacyNativePicker = 'touch' | 'always' | 'never';
/**
diff --git a/packages/core/src/utils/plainDate.ts b/packages/core/src/utils/plainDate.ts
index 138400ccb8..97e7376abb 100644
--- a/packages/core/src/utils/plainDate.ts
+++ b/packages/core/src/utils/plainDate.ts
@@ -202,7 +202,7 @@ export function plainDateToInstant(
// this wall time skipped or repeated.
const offsetBefore = getTimezoneOffsetMS(timezoneID, wallTime - DAY_MS);
const offsetAfter = getTimezoneOffsetMS(timezoneID, wallTime + DAY_MS);
- // AST-067 (Temporal's "compatible" disambiguation): a wall time that happens
+ // Temporal's "compatible" disambiguation (AST-067): a wall time that happens
// twice resolves to its earlier occurrence, and one that never happens is
// read in the offset before the transition, which moves it forward by the
// length of the gap.
diff --git a/packages/core/src/utils/pressGesture.ts b/packages/core/src/utils/pressGesture.ts
index 9798f7c61a..f9520b1ae1 100644
--- a/packages/core/src/utils/pressGesture.ts
+++ b/packages/core/src/utils/pressGesture.ts
@@ -9,31 +9,21 @@
* @position Pure half of the touch press model; driven by pressFeedback.ts,
* tested by pressGesture.test.ts without a browser
*
- * WHAT A FINGER MEANS, AS A STATE MACHINE.
- *
- * A native (UIKit) list delays a press by 0.15 s, cancels it the instant a
- * scroll claims the gesture, never brings it back inside that gesture, and
- * fades it only on release. CSS `:active` on iOS Safari does none of those
- * things: measured on iOS 26.2, it paints within 14 ms of the touch and was
- * still painted 1.6 s into a scroll. So on a coarse pointer the pressed state
- * is owned here, in JavaScript, and `:active` keeps only the mouse.
- *
- * The stylesheet drops `:active` by the PRIMARY pointer, so a mouse, trackpad
- * or Space key on such a device has lost `:active` too. Their presses come
- * here as `buttonDown`: painted at once, held through any travel, faded on
- * release like a finger's.
- *
- * Every constant below was measured against the real Settings and Contacts
- * apps on an iPhone simulator, driven with real HID touches at 60 fps, before
- * it was written down. The machine is deliberately ignorant of the DOM: it
- * takes what happened and answers with what should be painted, so
- * {@link pressGestureStep}'s table of cases IS the state diagram, one arm per
- * requirement.
- *
* SYNC: When modified, update pressFeedback.ts (the controller) and
* pressGesture.test.ts.
*/
+// A native list delays a press by 0.15 s, cancels it when a scroll claims the
+// gesture, never brings it back in that gesture, and fades it only on
+// release. On iOS Safari, CSS `:active` paints at once and stays painted into
+// a scroll. So on a coarse pointer this machine owns the pressed state, and
+// `:active` keeps only the mouse. The stylesheet drops `:active` by the
+// primary pointer, so a mouse, trackpad or Space press on such a device comes
+// here as `buttonDown`: painted at once and faded on release.
+//
+// The constants were measured against native apps. The machine knows nothing
+// of the DOM, so {@link pressGestureStep}'s cases are the state diagram.
+
import {pressConsts} from './interactionOverlay.stylex';
/**
diff --git a/packages/core/src/utils/timeFormat.ts b/packages/core/src/utils/timeFormat.ts
index 0d9cefca8d..1f1bc12d34 100644
--- a/packages/core/src/utils/timeFormat.ts
+++ b/packages/core/src/utils/timeFormat.ts
@@ -7,19 +7,11 @@
* @position Internal shared helper for TimeInput and DateTimeInput; not part
* of the public surface
*
- * Time of day as the locale writes it. The hour cycle, digits, separator, and
- * day-period words all come from Intl rather than a table, so a field reads
- * the same way `Timestamp` does beside it.
- *
- * The hour cycle is the locale's own: `en-US` and `ko-KR` read twelve-hour,
- * `en-GB`, `de-DE`, and `vi-VN` read twenty-four-hour. A `-u-hc-` extension
- * on the provider locale (`en-US-u-hc-h23`) carries an app's per-user
- * preference through the same path, so every Astryx time honors it.
- *
- * The parser reads back what the formatter writes: the locale's digits, its
- * hour-minute separator, and its day-period words, on either side of the time.
- * Whatever is left goes through the shared English-tolerant parser, so "2:30
- * PM" and "14:30" keep working in every locale.
+ * The hour cycle, digits, separator and day-period words come from Intl, so a
+ * field reads like `Timestamp`. A `-u-hc-` extension on the provider locale
+ * carries an app's per-user hour cycle. The parser reads back what the
+ * formatter writes, and the rest goes through the English-tolerant parser,
+ * so "2:30 PM" and "14:30" work in every locale.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/utils/timeFormat.test.ts
diff --git a/packages/core/src/utils/touchPresentation.stylex.ts b/packages/core/src/utils/touchPresentation.stylex.ts
index f571303739..005a8fda2d 100644
--- a/packages/core/src/utils/touchPresentation.stylex.ts
+++ b/packages/core/src/utils/touchPresentation.stylex.ts
@@ -6,30 +6,24 @@
* @output Exports touchKeys: the touch presentation resolver's queries as
* StyleX at-rule keys
* @position The reference spellings of the touch, compact and iOS-gate
- * conditions. Core styles write these as literal keys wherever they need
- * them (`spec:AST-094` FR13, `spec:AST-012` FR9), and a test pins each
- * literal to these values; utils/touchPresentation.ts holds the same
- * queries for script (matchMedia)
- *
- * These are the spellings to match. A style that changes with these
- * conditions writes the same literal key (`'@media (pointer: coarse)'`, the
- * iOS gate as that media key outside `'@supports (-webkit-touch-callout:
- * none)'`), and a test pins every literal in core to these values. Do not use
- * an imported key as a computed StyleX key: it compiles to a different
- * priority than the literal (6000 against 3200) and reorders the cascade.
- * The iOS supports gate is only for a style iOS WebKit itself requires (the
- * 16px input floor), never a behaviour.
+ * conditions. utils/touchPresentation.ts holds the same queries for script.
*
* SYNC: When modified, update touchPresentation.ts and
* touchPresentation.test.ts.
*/
+// Core styles write these as literal keys (AST-012), and a test pins each
+// literal to these values. Do not use an imported key as a computed StyleX key:
+// it gets a different priority than the literal (6000 against 3200) and
+// reorders the cascade. The iOS supports gate is only for a style that iOS
+// WebKit requires (the 16px input floor), never for a behavior (AST-094).
+
import * as stylex from '@stylexjs/stylex';
export const touchKeys = stylex.defineConsts({
/** The primary pointer is coarse (TOUCH_QUERY). */
touch: '@media (pointer: coarse)',
- /** The viewport is compact (COMPACT_QUERY, `spec:AST-012` FR9). */
+ /** The viewport is compact (COMPACT_QUERY). */
compact: '@media (width < 768px), (height < 500px)',
/** Both: a presentation such as a sheet in place of a popover. */
compactTouch:
diff --git a/packages/core/src/utils/typeaheadMatch.ts b/packages/core/src/utils/typeaheadMatch.ts
index a025da3847..9f56314d2e 100644
--- a/packages/core/src/utils/typeaheadMatch.ts
+++ b/packages/core/src/utils/typeaheadMatch.ts
@@ -6,7 +6,7 @@
* @output foldForTypeahead, nextTypeaheadBuffer, typeaheadPrefixMatch,
* findTypeaheadMatch
* @position Shared type-to-select matching for useTypeahead, useTreeFocus and
- * MultiSelector (`architecture:internationalization` INV17)
+ * MultiSelector
*
* Type-to-select is navigation, not sorting, so it folds the same way in every
* locale: case, the combining marks canonical decomposition leaves
@@ -17,8 +17,9 @@
const COMBINING_MARKS = /[\u0300-\u036f]/g;
-// The six stroked or barred Latin letters INV17 folds, in both cases. Turkish
-// dotless ı joins them; dotted İ decomposes to I + U+0307 and needs no entry.
+// The six stroked or barred Latin letters that the fold removes, in both cases.
+// Turkish dotless ı joins them; dotted İ decomposes to I + U+0307 and needs no
+// entry.
const STROKED: Readonly<Record<string, string>> = {
đ: 'd',
Đ: 'd',
@@ -47,8 +48,8 @@ export function foldForTypeahead(text: string): string {
.normalize('NFD')
.replace(COMBINING_MARKS, '')
.replace(STROKED_CHARS, c => STROKED[c] ?? c)
- // Recompose what INV17 keeps (a Japanese voiced mark, an Arabic hamza, a
- // Hangul final consonant), so a one-letter prefix does not skip it.
+ // Recompose what the fold keeps (a Japanese voiced mark, an Arabic hamza,
+ // a Hangul final consonant), so a one-letter prefix does not skip it.
.normalize('NFC')
.toLowerCase()
);
@@ -98,7 +99,7 @@ function hasMark(typed: string): boolean {
}
/**
- * Whether `label` starts with `typed` under INV17's fold. `exact` additionally
+ * Whether `label` starts with `typed` under the fold. `exact` additionally
* requires the unfolded letters to match (Turkish case pairing).
*/
export function typeaheadPrefixMatch(