@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/dist/SegmentedControl/useSegmentedSelectionMotion.d.ts

@@ -0,0 +1,357 @@
+/**
+ * @file useSegmentedSelectionMotion.ts
+ * @input The radiogroup, the selected value, the presentation and tracking
+ *   flags; the animator, the UIKit table and the touch tracking
+ * @output Exports `useSegmentedSelectionMotion`, `SegmentedSelectionMotion`,
+ *   the layer custom properties and the segment and title selectors
+ * @position SegmentedControl's touch layer
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/SegmentedControl/SegmentedControl.tsx (the pseudo-elements)
+ * - /packages/core/src/SegmentedControl/SegmentedControlItem.tsx (the title marker)
+ * - /packages/core/src/SegmentedControl/useSegmentedTouchTracking.ts
+ */
+import { type RefCallback, type RefObject } from 'react';
+import { type Animator } from '../motion/animator.js';
+/** The segments, in DOM order. */
+export declare const SEGMENT_SELECTOR = "[role=\"radio\"][data-value]";
+/** The selected surface's paint, copied into a layer's custom properties. */
+export declare const SURFACE_PROPERTIES: ReadonlyArray<string>;
+/**
+ * The radiogroup's two pseudo-element layers: the lens (::before) and the
+ * ::after, which under Reduced Motion shows the surface that fades out where
+ * it is.
+ */
+export type Layer = 'lens' | 'after';
+/** Box and visibility of a layer, besides its paint. */
+export declare const LAYER_GEOMETRY: ReadonlyArray<string>;
+/** The custom property on the radiogroup that sets `property` of `layer`. */
+export declare function layerVariable(layer: Layer, property: string): string;
+/** What the control reads of its selection motion. */
+export interface SegmentedSelection {
+    /**
+     * A press is down on the control (any pointer's), or its tap's click has
+     * not run yet. The press commits through that click, so a focus move it
+     * causes selects nothing.
+     */
+    readonly isPressing: () => boolean;
+    /** A key went down: a focus move it causes is the keyboard's, and selects. */
+    readonly keyPressed: () => void;
+}
+export interface SegmentedSelectionMotionOptions {
+    /** The animator's clock (ms, document timeline); `performance.now()` by default. */
+    readonly now?: () => number;
+    /**
+     * The animator for the radiogroup's ::after (the surface that fades out
+     * under Reduced Motion); one of its own by default.
+     */
+    readonly afterAnimator?: Animator;
+}
+/**
+ * The selection motion of one SegmentedControl, as UIKit's segmented control
+ * moves it. It lives outside React's render cycle. Nothing here sets state,
+ * so a slide never re-renders anything.
+ *
+ * At rest, the selected segment paints its own surface, so themes style it
+ * as before. For a slide, the lens takes over. The lens is the radiogroup's
+ * ::before, painted from custom properties copied from the segment's
+ * computed surface. The segment hides its own surface inline, so a theme
+ * rule cannot keep it painted. The lens moves with `translate` and `scale`
+ * on the compositor animator. Nothing lays out or paints per frame, and the
+ * slide keeps moving while JavaScript is busy. The lens lays out on the
+ * destination's box. It lands at translate 0 and scale 1 and hands the
+ * surface back pixel for pixel. Its position and its size run on separate
+ * springs, as UIKit's do. A change mid-flight starts from the presented
+ * geometry and its velocities. The titles change with the selection, at
+ * once.
+ *
+ * Under a finger:
+ * - A theme role owns a pressed thumb's lift, so a press on the selected
+ *   segment lifts nothing here.
+ * - A drag from the selected segment carries the lens at its resting size.
+ *   Its center chases the finger, at most `dragOvershoot` past the end
+ *   segments.
+ * - The selected title's color follows the lens's center. It moves to a
+ *   neighbor only once the center is a quarter of that segment past the
+ *   boundary. Every title keeps its weight until the lift.
+ * - The lift commits the segment nearest the finger, through that segment's
+ *   click. A lift outside the control commits nothing, and the lens settles
+ *   back.
+ * - A press on another segment leaves the lens in place until the lift.
+ *   Meanwhile that segment shows the shared pressed overlay.
+ * - A click that the item cancels sends the lens back at once. Otherwise the
+ *   lens waits for the new value, which a parent can adopt later. It goes
+ *   back only if the slide settles without the new value.
+ * - A cancelled touch puts the lens back.
+ *
+ * Under a mouse or a pen, the same press commits the same segment, but the
+ * theme owns the timing. A click, a key or a new value slides the lens on the
+ * theme's duration and easing, as the segments' own transition does. A drag
+ * from the selected segment carries the lens on the pointer itself.
+ *
+ * Under Reduced Motion, a held lens still follows the pointer: that is direct
+ * movement, not a transition. Nothing else chases, travels or scales. The lens
+ * fades in at the new segment while ::after, painted with the old surface,
+ * fades out in place. With a fine pointer under Reduce Motion, a change shows
+ * through the theme's transition.
+ */
+export declare class SegmentedSelectionMotion {
+    private readonly animator;
+    private track;
+    private carried;
+    /**
+     * Segments whose surface the lens carried until a change turned it
+     * elsewhere. They keep their surface hidden until the lens lands. A tap's
+     * press paint can still fade on such a segment. That paint would cover the
+     * lens, which sits under the segments' backgrounds, while the lens crosses
+     * it.
+     */
+    private readonly abandoned;
+    /** The segment showing the selected face under a dragging finger. */
+    private facedSegment;
+    /** The frame request that keeps the face on the lens while it is carried. */
+    private lensFrame;
+    /** Titles wearing the other face's color during a drag. */
+    private readonly faceOverrides;
+    /** The motions the hand-back waits for. */
+    private readonly running;
+    /** A finger holds the lens: a drag from the selected segment carries it. */
+    private isHeld;
+    /**
+     * The touch presentation applies (a coarse primary pointer), so every
+     * change slides on UIKit's springs. When it is off, a change slides on the
+     * theme's duration and easing, as the segments' transition does. A drag from
+     * the selected segment carries the lens on the pointer itself.
+     */
+    private isPresenting;
+    /**
+     * Segments whose own transitions are off while a fine pointer's carry is
+     * on screen, with their own inline values to give back.
+     */
+    private readonly stilled;
+    /** The frame request that gives the stilled segments their transitions back. */
+    private thawFrame;
+    private touch;
+    /**
+     * The value a touch already moved the lens to: the selection change that
+     * follows (the controlled value coming back) re-aims the lens.
+     */
+    private committed;
+    /**
+     * The commit's click ran without a veto: the lens waits for the value
+     * until the slide settles.
+     */
+    private isAwaitingValue;
+    /** The motion a release starts once its commit's click has run. */
+    private pending;
+    /** The last release was a finger's (decline and re-aim follow it). */
+    private releasedByFinger;
+    /** The ::after shows the leaving surface (Reduced Motion). */
+    private isLeavingShown;
+    /** Bumped by every leaving fade; a finished fade clears only its own. */
+    private leaving;
+    private readonly now;
+    /** The ::after: the surface fading out under Reduced Motion. */
+    private readonly after;
+    constructor(animator?: Animator, options?: SegmentedSelectionMotionOptions);
+    /** Attaches the radiogroup whose pseudo-elements are the lens (null detaches). */
+    attachTrack(element: HTMLElement | null): void;
+    /** True while the lens carries the selected surface. */
+    get isSliding(): boolean;
+    /** A press (any pointer's) is down on the control, from landing to letting go. */
+    get isPressed(): boolean;
+    /**
+     * Whether the touch presentation applies. Off, under a fine primary
+     * pointer, a change slides on the theme's timing, and a drag from the
+     * selected segment still carries the lens. A change of presentation hands
+     * anything in flight back.
+     */
+    present(isPresenting: boolean): void;
+    /** The segment that commits `value`, if the track has one. */
+    segmentFor(track: HTMLElement, value: string): HTMLElement | null;
+    /** The selection moved from `from` to `to`; the DOM already shows `to`. */
+    select(track: HTMLElement, from: string, to: string): void;
+    /**
+     * Whether a change of value slides the lens. A fine pointer under Reduce
+     * Motion leaves the change to the theme's transition.
+     */
+    private slidesChanges;
+    /**
+     * A press landed on `origin`, the segment the action-group tracker resolved
+     * for it (null: none). It reads the track's geometry and title faces once.
+     * Under Reduced Motion a finger's release cross-fades.
+     */
+    begin(track: HTMLElement, origin: HTMLElement | null, isFinger?: boolean): void;
+    /**
+     * The finger moved to `clientX`. A drag from the selected segment carries
+     * the lens at its resting size. A touch elsewhere leaves the lens alone,
+     * and that segment shows the shared pressed overlay.
+     */
+    drag(clientX: number): void;
+    /**
+     * The first move of a drag from the selected segment binds the lens there,
+     * at its resting size. Under Reduced Motion too: the lens follows the hand,
+     * and only the release cross-fades.
+     */
+    private hold;
+    /**
+     * The selected face follows the held lens: it goes to the segment under the
+     * lens's presented center. Hysteresis around each boundary keeps a finger
+     * that rests on a boundary from flipping it. This runs every frame while
+     * the lens is held, so the face keeps up as the lens settles under a still
+     * finger.
+     */
+    private followLens;
+    /** The held lens's center chases the finger at `clientX`. */
+    private chase;
+    /**
+     * The finger let go on `target`, the segment the tracker resolved for it
+     * (null: none, or a disabled one). Moves the lens there and returns its
+     * value when it is not the selected one (the tracker's lift commits it
+     * through its click), else null.
+     */
+    release(target: HTMLElement | null): string | null;
+    /**
+     * The commit's click for `value` has run. A click that the item's
+     * `onClick` cancels sends the lens back at once. Otherwise the lens waits
+     * for the value, which a parent can adopt later.
+     */
+    clicked(track: HTMLElement, value: string, isCancelled: boolean): void;
+    /**
+     * The value the finger let go on was not adopted. The item's `onClick`
+     * cancelled it, or a controlled parent kept its value. The lens goes back
+     * to the selected segment. The next change to that value slides as any
+     * change does.
+     */
+    decline(track: HTMLElement, value: string): void;
+    /** The touch was taken away (the page scrolled): the lens goes back. */
+    cancel(): void;
+    /** Hands the surface back to its segment now and hides the lens. */
+    settle(): void;
+    /**
+     * The control resized. The lens aims at boxes measured when its motion
+     * began, so it hands the surface back rather than land somewhere stale.
+     * Two cases keep the motion. In the first, the track keeps its measured
+     * size: a new title weight resized a content-sized control before the box
+     * was measured. In the second, a finger holds the lens.
+     */
+    resized(track: HTMLElement): void;
+    /**
+     * Ends everything in flight (unmount). The controller stays usable, so an
+     * effect cleanup followed by a setup (StrictMode's extra mount) loses
+     * nothing.
+     */
+    stop(): void;
+    /**
+     * A fine pointer's carry. The segments' own transitions go off while the
+     * lens is on screen, so the borrowed surface does not fade out and back in.
+     * Under a finger, the touch presentation already turns them off.
+     */
+    private stillTransitions;
+    /**
+     * Gives the stilled segments their transitions back two frames after the
+     * hand-back, once the surfaces it gave back have been on screen.
+     */
+    private thawTransitions;
+    private cancelThaw;
+    private restoreTransitions;
+    /** The selected segment, as the DOM shows it now. */
+    private selectedIn;
+    /**
+     * Starts the motion the release left pending: on `box` (the destination's
+     * box now) or the box measured at landing, showing `paint`'s surface (the
+     * selected segment's).
+     */
+    private startPending;
+    /**
+     * Aims the lens at `destination`'s box as it is now: a value adopted
+     * after its click (mid-flight) moves the segments with its titles' new
+     * weights.
+     */
+    private reaim;
+    /**
+     * Binds the lens for `segment`, with `box` as its layout box and `paint`'s
+     * surface, the selected segment's. It keeps what is on screen. With nothing
+     * carried, it starts from `from`, a segment's resting box. Otherwise it
+     * starts from the presented geometry, re-based onto the new box with its
+     * velocities.
+     */
+    private carry;
+    /** Velocities captured by the last `carry`, in the new box's units. */
+    private velocity;
+    /** A spring transition that keeps the captured velocities of `values`. */
+    private springFrom;
+    /**
+     * The lens settles at its resting place on `segment`. Under a finger it
+     * springs on the slide spring. Under a fine pointer it takes the theme's
+     * duration and easing, as the segments' own transition does.
+     */
+    private settleLens;
+    /** Springs the lens toward `values`. */
+    private springLens;
+    /** The lens's presented center and size, from the animator. */
+    private presented;
+    /**
+     * The lens settles on `segment`, at its resting size. Under Reduced Motion
+     * a finger's release (`touchRelease`) cross-fades on any primary pointer. A
+     * mouse's or a pen's lands at once under a fine one.
+     */
+    private moveLensTo;
+    /**
+     * A tap's slide: from `from` to `segment` on the slide spring. Under Reduced
+     * Motion there is no travel, and a finger's tap (`touchRelease`) fades.
+     */
+    private slideTo;
+    /**
+     * Under Reduced Motion, the lens lands on `segment` and fades in there, as
+     * an animator entrance. The surface on screen fades out in place on the
+     * same clock. That surface is the lens when it was carried, else `from`'s
+     * resting surface. The animator decides whether anything fades. On a fine
+     * pointer, both change at once unless a touch released the change
+     * (`touchRelease`).
+     */
+    private crossFadeTo;
+    /**
+     * Paints the ::after with the surface on screen (the lens's paint, or
+     * `paint`'s resting surface) where it is (`from`, at `opacity`).
+     */
+    private leave;
+    /**
+     * The ::after fades out in place while the lens fades in on `box`. As a
+     * leaving travel, it fades on the animator's Reduce Motion clock. It lands
+     * only once it is invisible.
+     */
+    private fadeLeaving;
+    private endLeaving;
+    /**
+     * Waits for `handle`; the surface goes back when nothing is left. A
+     * touch's value still waiting to come back when the motion settles goes
+     * back instead: the settled slide bounds the wait.
+     */
+    private trackHandle;
+    /**
+     * Gives `segment`'s title the selected face and the selected segment's
+     * title an unselected one (none for null or the selected segment), at once.
+     */
+    private showFaceAt;
+    /**
+     * Mid-drag, the face is the color alone. A weight swap changes the titles'
+     * widths, which moves the segments under the finger and shakes the
+     * boundary. The commit's own styles give the new weight at the lift.
+     */
+    private wearFace;
+    /** Every title back to its own face. */
+    private clearFaces;
+}
+/**
+ * Wires `SegmentedSelectionMotion` to a SegmentedControl. While enabled,
+ * every change of `value` slides the selection in the commit that shows the
+ * new value, so no frame shows it unanimated. A press drives the lens while
+ * `isTracking`.
+ */
+export declare function useSegmentedSelectionMotion(trackRef: RefObject<HTMLElement | null>, value: string, isPresenting: boolean, isTracking: boolean): {
+    readonly selection: SegmentedSelection;
+    /** The radiogroup's callback ref: it attaches the animators to the node. */
+    readonly attachTrack: RefCallback<HTMLElement>;
+};
+//# sourceMappingURL=useSegmentedSelectionMotion.d.ts.map

package/dist/SegmentedControl/useSegmentedSelectionMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSegmentedSelectionMotion.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/useSegmentedSelectionMotion.ts"],"names":[],"mappings":"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"}