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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/core/src/utils/coarsePointer.ts b/packages/core/src/utils/coarsePointer.tsindex 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.tsindex 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.tsdiff --git a/packages/core/src/utils/focusOutline.stylex.ts b/packages/core/src/utils/focusOutline.stylex.tsindex 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.tsindex 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 thediff --git a/packages/core/src/utils/hitArea.ts b/packages/core/src/utils/hitArea.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsdiff --git a/packages/core/src/utils/touchPresentation.stylex.ts b/packages/core/src/utils/touchPresentation.stylex.tsindex 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.tsindex 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(