@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/utils/interactionOverlay.stylex.ts

@@ -6,78 +6,12 @@
 
 /**
  * @file Shared hover and pressed overlay states
- * @input Uses StyleX and the semantic interaction-overlay color tokens
- * @output Exports reusable background-color and background-image state styles,
- *   the touch press's registered strength variable (`pressVars`) and its
- *   clocks (`pressConsts`)
+ * @input StyleX and the semantic interaction-overlay color tokens
+ * @output Reusable background-color and background-image state styles, the
+ *   touch press's registered strength variable (`pressVars`) and its clocks
+ *   (`pressConsts`)
  * @position Internal styling utility for interactive core surfaces
  *
- * Every surface that paints a press composes one of these (or carries its own
- * `:active` rule in the same shape), so a change to how the system answers a
- * press is made here once. `pressedBackgroundColor` is the press without the
- * hover, for controls whose hover is a colour or nothing. `pressedAlpha` is the
- * touch press's strength alone, for an owner whose pressed paint lives on a
- * descendant or a pseudo-element.
- *
- * Keep the enabled guard outside the individual states. StyleX assigns an
- * extra priority bucket (and generated selector specificity) to media-nested
- * rules. Repeating `:active` inside the hover-capable branch gives hover and
- * press the same generated specificity; StyleX's native pseudo-state ordering
- * then emits `:active` last.
- *
- * TWO POINTERS, TWO PRESS MODELS. A mouse keeps `:active`. A finger does not:
- * on iOS Safari `:active` paints on the touch itself and can outlive the start
- * of a scroll, so under `@media (pointer: coarse)` the bare `:active` arm is
- * dropped and the press is written by the touch press controller
- * (`utils/pressFeedback.ts`) as `data-astryx-press="on"` once the press is
- * believed (150 ms, no travel, no scroll) and `data-astryx-press="fading"` for the
- * 200 ms release. The query reads the PRIMARY pointer, so on a phone or tablet
- * a mouse, trackpad or Space-key press loses `:active` too; the controller
- * writes the same attribute for those, at once. The two arms paint those
- * through ONE number:
- *
- *  - `--astryx-press-alpha` is the press's strength, 0 to 1. It is a
- *    registered custom property (`@property`, syntax `<number>`, declared once
- *    in the shipped stylesheet by {@link pressVars}), which is what lets it
- *    animate: the overlay itself is a gradient layer, and gradients do not
- *    interpolate, but a registered number does, and every declaration that
- *    reads it is re-resolved on each frame. The touch paint is the pressed
- *    token at that strength — `color-mix(in srgb, pressed calc(alpha * 100%),
- *    transparent)` — declared once here as `--_press-paint` and painted as a
- *    background IMAGE: an image change is discrete, so a composer's colour
- *    transition cannot fade the onset in.
- *  - `[data-astryx-press="on"]` sets the strength to 1 and paints, on the
- *    first frame. Nothing transitions a custom property a composer never named.
- *  - `[data-astryx-press="fading"]` keeps the same paint and runs the release
- *    animation, strength 1 → 0 over {@link PRESS_RELEASE_DURATION} (UIKit's
- *    deselect crossfade; the controller removes the attribute when the same
- *    clock runs out, and by then the paint is gone). It fades to nothing, not
- *    to the hover strength: under a finger there is no hover to land on.
- *
- * WHY AN ANIMATION AND NOT A TRANSITION. Two reasons, both about composers.
- * StyleX is last-wins per property, and composers own their `transition-*`
- * longhands (Button, Item, Tab, Link, ...): the utility can neither append the
- * strength to their transition list nor set one of its own without taking the
- * whole property from them. No composer sets `animation-*` on the element that
- * composes these, so those longhands are free. And a transition needs the
- * declared value to change at the style change, which would make the release
- * arm declare strength 0; every property reading the strength would then
- * change computed value at the lift, and a composer that transitions
- * `background-image` (Button, Token, TreeListItem — Chromium interpolates
- * same-shape gradients) would start its own, shorter fade over this one. With
- * keyframes owning both ends the release arm declares 1 like the on arm, so at
- * the lift nothing a composer transitions changes; only the animation moves.
- *
- * Browser support: Chromium 111+, Safari 16.4+ and Firefox 128+ register the
- * property and interpolate. An engine without `@property` ignores the rule,
- * animates the unregistered value discretely (the paint holds for half the
- * release, then goes) — a step, no worse than the arm before this one.
- *
- * Composers must not set `backgroundImage` of their own on the colour variants
- * (none do): the touch arms own it. Composers must not set `animation-*` on
- * the element that composes any of these (none do): StyleX would drop either
- * the release animation or theirs.
- *
  * SYNC: When modified, update pressFeedback.ts, pressGesture.ts (the fade
  * clock), hooks/usePressFeedback.doc.mjs, the components that paint the touch
  * press off an ancestor scope or a pseudo-element (Switch, Tab,
@@ -85,6 +19,39 @@
  * and scripts/build-css.test.mjs.
  */
 
+// Every surface that paints a press uses one of these styles, so a change to
+// the press is made here once.
+//
+// Keep the enabled guard outside the states. StyleX gives media-nested rules
+// a higher priority. With `:active` repeated in the hover branch, hover and
+// press get the same specificity, and StyleX emits `:active` last.
+//
+// A mouse keeps `:active`. A finger does not: on iOS Safari `:active` paints
+// on the touch and can outlive the start of a scroll. So under
+// `@media (pointer: coarse)` the press controller (pressFeedback.ts) writes
+// `data-astryx-press`: `on` when the press is believed, and `fading` for the
+// release. The query reads the primary pointer, so on a phone a mouse or
+// Space-key press loses `:active` too, and the controller writes the
+// attribute at once.
+//
+// The `on` and `fading` arms paint through `--astryx-press-alpha`, a
+// registered `<number>` from 0 to 1. Gradients do not interpolate, but a registered number does.
+// The touch paint is the pressed token at that strength, painted as a
+// background image, so a composer's color transition cannot fade the onset
+// in. `on` sets the strength to 1 on the first frame. `fading` animates it
+// from 1 to 0, not to the hover strength, because a finger has no hover. The
+// theme's motion tempo scales the release clock (AST-108).
+//
+// The release is an animation, not a transition. Composers own their
+// `transition-*` longhands, and StyleX is last-wins per property. A
+// transition would also make the release arm declare 0, so a composer that
+// transitions `background-image` would start its own fade. With keyframes,
+// both arms declare 1 and only the animation moves. An engine without
+// `@property` steps the paint off at half the release.
+//
+// Composers must not set `backgroundImage` on the color variants, or
+// `animation-*` on the element that composes them. The touch arms own both.
+
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 
@@ -118,8 +85,7 @@ export const pressConsts = stylex.defineConsts({
 
 /**
  * The release's clock as CSS, scaled by the theme's `--_astryx-motion-tempo`
- * (`spec:AST-108` FR4, `component:Button` FR15) up to 1.5, its maximum. The
- * controller's timer reads the same property.
+ * up to 1.5, its maximum. The controller's timer reads the same property.
  */
 const PRESS_RELEASE_DURATION = `calc(${pressConsts.releaseMs}ms * min(var(--_astryx-motion-tempo, 1), 1.5))`;
 /** The same clock under Reduce Motion: a tempo may shorten it, never lengthen it. */
@@ -133,10 +99,14 @@ const COARSE = '@media (pointer: coarse)';
  * attribute is the system's own (`data-astryx-*`, like the pressable marker),
  * outside the namespace a theme's state keys generate into (`[data-<state>]`),
  * so a theme state can never collide with it.
+ *
+ * The press selectors are typed `string`, not as literals. As a computed key,
+ * a `string` gives the object an index signature, and StyleX reads the value
+ * type from it. See {@link ByAttribute}.
  */
-const PRESSED_ON = '[data-astryx-press="on"]';
+const PRESSED_ON: string = '[data-astryx-press="on"]';
 /** Written by the touch press controller for the release's exit. */
-const PRESSED_FADING = '[data-astryx-press="fading"]';
+const PRESSED_FADING: string = '[data-astryx-press="fading"]';
 
 const PRESS_ALPHA = pressVars['--astryx-press-alpha'];
 
@@ -182,21 +152,14 @@ const RELEASE_EASE = 'cubic-bezier(0, 0, 0.2, 1)';
 
 /**
  * The touch press's strength and its release, on the element the controller
- * writes to. Every variant below carries both, as `[PRESS_ALPHA]:
- * pressStrength` and `...pressReleaseAnimation`; `pressedAlpha` is the pair
+ * writes to. Every variant below carries both. `pressedAlpha` is the pair
  * alone.
  *
- * Both objects are written with literal keys, and the strength's own key is
- * spelled inside each variant rather than here, on purpose. StyleX reads a
- * `stylex.create` call from the raw AST, so a computed key written inside
- * the call is still a computed key when it evaluates it. An object hoisted
- * out of the call has been through every other Babel plugin by the time the
- * spread is resolved, and a preset that lowers ES2015 (`next/babel` under
- * the default browserslist: apps/sandbox, and a consumer's source build) has
- * rewritten its computed keys into `_defineProperty` helper calls the
- * evaluator cannot follow, failing the build with "Referenced constant is
- * not defined". Literal keys survive the lowering; `PRESS_ALPHA` cannot be
- * one, since the variable's name is generated, so it stays at each use. The
+ * The keys are literal on purpose. StyleX reads `stylex.create` from the raw
+ * AST. An object hoisted out of the call can first pass through a preset that
+ * lowers ES2015, such as `next/babel`. That preset turns computed keys into
+ * helper calls, and the build fails with "Referenced constant is not
+ * defined". `PRESS_ALPHA` has a generated name, so it stays at each use. The
  * literal keys equal PRESSED_ON and PRESSED_FADING above.
  */
 const pressStrength = {
@@ -204,7 +167,28 @@ const pressStrength = {
   '[data-astryx-press="on"]': 1,
   '[data-astryx-press="fading"]': 1,
 };
-const pressReleaseAnimation = {
+/**
+ * A value that only attribute selectors choose, such as the press arms.
+ *
+ * StyleX infers a value's type from its `default`, its `:` and `@`
+ * conditions, and an index signature. Literal attribute keys are none of
+ * these. For a property whose conditions are all literal attribute keys, it
+ * infers `unknown`, and no component's `xstyle` accepts that. This type gives
+ * the hoisted press arms an index signature.
+ */
+type ByAttribute<Value> = Readonly<{
+  default: null;
+  [attribute: string]: Value | null;
+}>;
+
+const pressReleaseAnimation: Readonly<{
+  animationName: ByAttribute<string>;
+  animationDuration: ByAttribute<
+    Readonly<{default: string; [media: `@media ${string}`]: string}>
+  >;
+  animationTimingFunction: ByAttribute<string>;
+  animationFillMode: ByAttribute<'both'>;
+}> = {
   animationName: {
     default: null,
     '[data-astryx-press="fading"]': pressRelease,

package/src/utils/plainDate.ts

@@ -9,6 +9,8 @@
 
 import type {ISODateString, PlainDate} from './dateTypes';
 import type {Locale} from '../i18n/types';
+import {firstCharacter} from './characters';
+import {standaloneMonthCapitalLanguages} from './standaloneMonthCapitals.generated';
 
 export type {PlainDate} from './dateTypes';
 
@@ -200,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.
@@ -329,6 +331,32 @@ export const DATE_FORMAT_MONTH_YEAR: Intl.DateTimeFormatOptions = {
   month: 'long',
 };
 
+/**
+ * The month and year as a label that stands alone, such as a calendar heading
+ * or a month grid's name. `Intl` formats the month for running text; where
+ * CLDR titlecases a stand-alone month name (its `contextTransforms`), the
+ * label starts with a capital, as Calendar's weekday headers use CLDR's
+ * stand-alone forms (`component:Calendar` FR1). Internal: not re-exported from
+ * `utils/index.ts`.
+ */
+export function plainDateFormatStandaloneMonthYear(
+  pd: PlainDate,
+  locale: Locale,
+): string {
+  const label = plainDateFormat(pd, DATE_FORMAT_MONTH_YEAR, locale);
+  let language: string;
+  try {
+    language = new Intl.Locale(locale).language;
+  } catch {
+    return label;
+  }
+  if (!standaloneMonthCapitalLanguages.has(language)) {
+    return label;
+  }
+  const first = firstCharacter(label);
+  return first.toLocaleUpperCase(locale) + label.slice(first.length);
+}
+
 // e.g. "Sun" (locale-dependent) — the weekday on its own, abbreviated.
 //
 // This is CLDR's `abbreviated` width, which `Intl` reaches natively. Note

package/src/utils/presentation.ts

@@ -4,51 +4,37 @@
 
 /**
  * @file presentation.ts
- * @input A component's `presentation` prop (a caller's value, or omitted),
- *   what the component does when it is omitted, and the touch presentation
- *   (utils/touchPresentation.ts)
- * @output usePresentation and readPresentation (and the pure
- *   resolvePresentation): the surface to render and whether the component's
+ * @input A component's `presentation` prop, what the component does when it
+ *   is omitted, and the touch presentation (utils/touchPresentation.ts)
+ * @output usePresentation, readPresentation, and the pure
+ *   resolvePresentation: the surface to render and whether the component's
  *   touch input modes apply
  * @position Internal resolver for stable components that, under a finger,
- *   present a different surface or switch how an open surface follows input
- *   (architecture:public-component-api INV16)
- *
- * A caller's explicit `presentation` always wins over the touch default:
- *
- * - `'popover'`: the fine-pointer surface AND input modes, on every device;
- * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
- *   finger;
- * - `'adaptive'`: the sheet on a compact touch screen and the popover
- *   elsewhere, with touch input modes under a finger;
- * - omitted: the component's default. `whenOmitted: 'popover'` answers as
- *   `'popover'` (today's components). `whenOmitted: 'touch'` keeps the
- *   popover surface and turns the component's touch input modes on under a
- *   finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`
- *   a released component's default is a functional default change
- *   (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.
- *
- * One touch model on every touch device: the modes depend on the pointer,
- * never on the platform. Touch styling (press paint, the text-size floor)
- * and touch-only behavior that a component's own record defines (a row
- * swipe, a slider's thumb) do not read this: they keep the touch
- * presentation.
- *
- * CSS: a style that implements a touch surface or input mode is applied with
- * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a
- * bare media key on a base style, so a pinned `'popover'` keeps none of it.
- * A rule inside it that needs the touch query uses the touch presentation's
- * touch key; the iOS `@supports` gate is only for the one style iOS WebKit
- * itself requires (the 16px text-size floor), never for a touch mode. On the
- * server and while hydrating, `touchModes` is false and `'adaptive'` is the
- * popover: a touch surface or mode opens only after hydration
- * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens
- * only to the queries a request reads (`architecture:react-component-runtime`
- * INV5): none for a pinned `'popover'`.
+ *   present a different surface or change how an open surface follows input
  *
  * SYNC: When modified, update presentation.test.ts.
  */
 
+// A caller's explicit `presentation` always wins over the touch default:
+// - `'popover'`: the fine-pointer surface and input modes, on every device.
+// - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
+//   finger.
+// - `'adaptive'`: the sheet on a compact touch screen (AST-012), else the
+//   popover, with touch input modes under a finger.
+// - Omitted: `whenOmitted: 'popover'` answers as `'popover'`.
+//   `whenOmitted: 'touch'` keeps the popover surface and turns on touch input
+//   modes under a finger. When a released component changes its default to
+//   `'touch'`, that is a functional default change (AST-017).
+//
+// The modes depend on the pointer, never the platform. Touch styling and
+// touch-only behavior from a component's own record do not read this.
+//
+// Apply a touch-mode style with `touchModes`
+// (`stylex.props(touchModes && styles.touchMode)`), never as a bare media
+// key, so a pinned `'popover'` keeps none of it. On the server and while
+// hydrating, `touchModes` is false and `'adaptive'` is the popover
+// (AST-094). usePresentation listens only to the queries a request reads.
+
 import {useCallback, useMemo, useSyncExternalStore} from 'react';
 import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import type {CompactDefinition} from '../theme/themeAdaptations';
@@ -79,7 +65,7 @@ export interface PresentationOptions {
 
 /**
  * usePresentation's options. There is no server hint: the server and
- * hydrating render never present touch modes (`spec:AST-094` FR13).
+ * hydrating render never present touch modes.
  */
 export type UsePresentationOptions = PresentationOptions;
 
@@ -88,8 +74,7 @@ export interface ReadPresentationOptions extends PresentationOptions {
   readonly view?: Window | null;
   /**
    * The active theme's compact definition (`useCompactDefinition()`, read
-   * while rendering), so a theme that moves `md` moves the sheet too
-   * (`spec:AST-012` FR9).
+   * while rendering), so a theme that moves `md` moves the sheet too.
    */
   readonly compact: CompactDefinition;
 }
@@ -111,13 +96,12 @@ export function resolvePresentation(
 }
 
 const noSubscription = () => () => {};
-/** The server and hydrating render match no query (`spec:AST-094` FR13). */
+/** The server and hydrating render match no query. */
 const matchesNothing = () => false;
 
 /**
- * A media query's match, subscribed only while `query` is given
- * (`architecture:react-component-runtime` INV5); false on the server and
- * while hydrating (`spec:AST-094` FR13).
+ * A media query's match, subscribed only while `query` is given. False on
+ * the server and while hydrating.
  */
 function useMatchWhileRead(query: string | null): boolean {
   const subscribe = useCallback(
@@ -141,7 +125,7 @@ function useMatchWhileRead(query: string | null): boolean {
 /**
  * The presentation now, following the pointer and the size as they change
  * (a tablet docking a trackpad). SSR-safe: renders the server default (not
- * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * touch, not compact) until hydrated. It subscribes
  * only to what the request reads: a pinned `'popover'` to neither query,
  * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
  * `'adaptive'` to the pointer and the compact size.

package/src/utils/pressDisabled.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressDisabled.ts
+ * @input An element
+ * @output `isDisabledControl`: whether an element is a disabled control, so a
+ *   press on it performs no action
+ * @position The one disabled-control check that press feedback
+ *   (../gestures/haptics) and the hover layers' touch trigger
+ *   (../Layer/useTouchTrigger) share, so the two never disagree about a
+ *   control. It lives outside the gesture code, which a public import that
+ *   uses no gesture never carries (architecture:react-component-runtime
+ *   INV13).
+ */
+
+/**
+ * Whether `element` is a disabled control: `aria-disabled="true"`, or a form
+ * control the browser counts as `:disabled` (a disabled fieldset's controls
+ * included). A disabled control performs no action, so it gives no press
+ * feedback (spec:AST-094 FR23), and a tap on it opens its reason instead
+ * (component:Tooltip FR5).
+ */
+export function isDisabledControl(element: Element): boolean {
+  if (element.getAttribute('aria-disabled') === 'true') {
+    return true;
+  }
+  try {
+    return element.matches(':disabled');
+  } catch {
+    return false;
+  }
+}