@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/press/contactReceipt.js

@@ -0,0 +1,177 @@
+/** Existing release budgets, preserved separately from contact ownership. */
+export const PRESS_CONTACT_CLICK_WINDOW_MS = 1_000;
+export const MENU_CONTACT_CLICK_WINDOW_MS = 750;
+export const TOGGLE_CONTACT_CLICK_WINDOW_MS = 350;
+const states = new WeakMap();
+const fallbackTarget = new EventTarget();
+export function contactTarget() {
+    return typeof document === 'undefined' ? fallbackTarget : document;
+}
+function contactState(target) {
+    const existing = states.get(target);
+    if (existing)
+        return existing;
+    const state = {
+        sequence: 0,
+        active: new Map(),
+        latestByPointer: new Map(),
+        receipts: new Map(),
+        dispose() {
+            for (const [type, handler] of Object.entries(handlers))
+                target.removeEventListener(type, handler, true);
+            states.delete(target);
+        },
+    };
+    const down = (event) => {
+        const pointerId = event.pointerId;
+        const gesture = { pointerId, sequence: ++state.sequence, released: false };
+        state.active.set(pointerId, gesture);
+        state.latestByPointer.set(pointerId, gesture);
+        state.latest = gesture;
+    };
+    const up = (event) => {
+        const pointerId = event.pointerId;
+        const gesture = state.active.get(pointerId);
+        if (gesture) {
+            gesture.released = true;
+            state.latest = gesture;
+            state.active.delete(pointerId);
+            setTimeout(() => {
+                if (state.latestByPointer.get(pointerId) === gesture)
+                    state.latestByPointer.delete(pointerId);
+            }, PRESS_CONTACT_CLICK_WINDOW_MS);
+        }
+    };
+    const click = (event) => {
+        const pointer = event;
+        const receipt = takePhysicalContact(target, performance.now(), pointer.detail, pointer.pointerId);
+        if (!receipt)
+            return;
+        // A switch already committed at UP may keep its trusted label default for the tick.
+        // Retargeted clicks still lose their default, so another control cannot activate.
+        if (!(receipt.nativeLabel &&
+            event.target instanceof Node &&
+            receipt.nativeLabel.contains(event.target)))
+            event.preventDefault();
+        event.stopImmediatePropagation();
+    };
+    const touchEnd = (event) => {
+        const touches = event.changedTouches;
+        // Legacy EventTarget adapters have no touch list. On WebKit, prevent defaults
+        // only while a menu receipt owns an ending contact, never for unrelated roles.
+        const ownsEnd = [...state.receipts.values()].some(receipt => receipt.suppressTouchEnd &&
+            (!touches || (receipt.gesture === state.latest && receipt.gesture.released)));
+        if (ownsEnd)
+            event.preventDefault();
+    };
+    const handlers = {
+        pointerdown: down,
+        pointerup: up,
+        pointercancel: up,
+        click,
+        touchend: touchEnd,
+    };
+    for (const [type, handler] of Object.entries(handlers))
+        target.addEventListener(type, handler, { capture: true, passive: false });
+    states.set(target, state);
+    return state;
+}
+/** A receipt belongs to one pointer and one DOWN sequence. Later contacts cannot
+ * erase it or spend it. Legacy WebKit mouse clicks have no usable pointer id;
+ * those consume released receipts in release order, including after unmount.
+ */
+export function ownPhysicalContact(target, owner, windowMs, options = {}) {
+    const state = contactState(target);
+    const pointerId = options.pointerId ?? state.latest?.pointerId;
+    const previous = [...state.receipts.values()].findLast(receipt => receipt.gesture.pointerId === pointerId && receipt.owner === owner);
+    const gesture = state.active.get(pointerId) ??
+        (state.latest?.pointerId === pointerId ? state.latest : undefined) ??
+        previous?.gesture ?? {
+        pointerId,
+        sequence: ++state.sequence,
+        released: Number.isFinite(windowMs),
+    };
+    state.latest = gesture;
+    if (pointerId !== undefined)
+        state.latestByPointer.set(pointerId, gesture);
+    if (!gesture.released && pointerId !== undefined)
+        state.active.set(pointerId, gesture);
+    state.receipts.get(gesture.sequence)?.clear();
+    let timer;
+    const clear = () => {
+        clearTimeout(timer);
+        state.receipts.delete(gesture.sequence);
+        if (pointerId !== undefined && state.latestByPointer.get(pointerId) === gesture)
+            state.latestByPointer.delete(pointerId);
+    };
+    state.receipts.set(gesture.sequence, {
+        gesture,
+        owner,
+        deadline: (options.now ?? performance.now()) + windowMs,
+        clear,
+        suppressTouchEnd: options.suppressTouchEnd,
+        consumed: options.consumed,
+        nativeLabel: options.nativeLabel,
+    });
+    if (Number.isFinite(windowMs)) {
+        gesture.released = true;
+        if (pointerId !== undefined && state.active.get(pointerId) === gesture)
+            state.active.delete(pointerId);
+        timer = setTimeout(clear, windowMs);
+    }
+}
+/** Adapters can also consume when a development EventTarget does not bubble. */
+function takePhysicalContact(target, now, detail, pointerId) {
+    if (detail === 0)
+        return;
+    const state = states.get(target);
+    const candidates = [...(state?.receipts.values() ?? [])];
+    const knownGesture = pointerId === undefined ? undefined : state?.latestByPointer.get(pointerId);
+    if (knownGesture && !state?.receipts.has(knownGesture.sequence))
+        return;
+    for (const receipt of candidates)
+        if (now > receipt.deadline)
+            receipt.clear();
+    const receipt = candidates.find(receipt => now <= receipt.deadline &&
+        (pointerId !== undefined && pointerId !== 0 && pointerId !== -1
+            ? receipt.gesture.pointerId === pointerId ||
+                receipt.gesture.pointerId === undefined ||
+                !knownGesture
+            : receipt.gesture.released));
+    if (!receipt)
+        return;
+    receipt.clear();
+    receipt.consumed?.();
+    return receipt;
+}
+export function consumePhysicalContact(target, now, detail, pointerId) {
+    return !!takePhysicalContact(target, now, detail, pointerId);
+}
+/** Explicit cancellation affects only this owner, including all its contacts. */
+export function retirePhysicalContact(target, owner) {
+    const state = states.get(target);
+    if (!state)
+        return;
+    for (const receipt of state.receipts.values())
+        if (!owner || receipt.owner === owner)
+            receipt.clear();
+    if (!owner)
+        state.dispose();
+}
+const menuOwner = {};
+export function ownMenuCompatibilityClick(target, pointerId) {
+    ownPhysicalContact(target, menuOwner, MENU_CONTACT_CLICK_WINDOW_MS, {
+        pointerId,
+        suppressTouchEnd: true,
+    });
+}
+const pressOwner = {};
+export function armPointerClickSuppression(now, pointerId) {
+    ownPhysicalContact(contactTarget(), pressOwner, PRESS_CONTACT_CLICK_WINDOW_MS, { now, pointerId });
+}
+export function consumePointerClickSuppression(now, detail = 1) {
+    return consumePhysicalContact(contactTarget(), now, detail);
+}
+export function resetPointerClickSuppression() {
+    retirePhysicalContact(contactTarget());
+}

package/dist/press/gestureArbitration.d.ts

@@ -0,0 +1,13 @@
+/** The gesture that claimed a touch: the navigation back swipe, or any other pan (a scroll, a
+ * sheet's drag, a menu's hold). */
+export type OwnedGesture = 'back-swipe' | 'other';
+export type OwnedTouchHandoff = Readonly<{
+    touchIdentifier: number;
+    retired: AbortSignal;
+}>;
+type CancellationObserver = (owner: OwnedGesture, handoff?: OwnedTouchHandoff) => boolean | void;
+/** Resources prepared by a press share its cancellation without replacing its activation owner. */
+export declare function observePointerPressCancellation(pointerId: number, cancel: CancellationObserver): () => void;
+export declare function registerPointerPressCancellation(pointerId: number, cancel: () => void): () => void;
+export declare function cancelPointerPressForOwnedGesture(pointerId: number, owner?: OwnedGesture, handoff?: OwnedTouchHandoff): boolean;
+export {};

package/dist/press/gestureArbitration.js

@@ -0,0 +1,38 @@
+const pointerPressCancellations = new Map();
+const cancellationObservers = new Map();
+/** Resources prepared by a press share its cancellation without replacing its activation owner. */
+export function observePointerPressCancellation(pointerId, cancel) {
+    const observers = cancellationObservers.get(pointerId) ?? new Set();
+    observers.add(cancel);
+    cancellationObservers.set(pointerId, observers);
+    return () => {
+        observers.delete(cancel);
+        if (!observers.size && cancellationObservers.get(pointerId) === observers)
+            cancellationObservers.delete(pointerId);
+    };
+}
+export function registerPointerPressCancellation(pointerId, cancel) {
+    pointerPressCancellations.set(pointerId, cancel);
+    return () => {
+        if (pointerPressCancellations.get(pointerId) === cancel) {
+            pointerPressCancellations.delete(pointerId);
+        }
+    };
+}
+export function cancelPointerPressForOwnedGesture(pointerId, owner = 'other', handoff) {
+    const cancel = pointerPressCancellations.get(pointerId);
+    const observers = cancellationObservers.get(pointerId);
+    if (!cancel && !observers?.size)
+        return false;
+    pointerPressCancellations.delete(pointerId);
+    cancel?.();
+    // An observer may keep the physical contact after activation has yielded. A later owner must
+    // still reach it. Existing observers remain one-shot unless they explicitly decline.
+    for (const observer of [...(observers ?? [])]) {
+        if (observer(owner, handoff) !== false)
+            observers?.delete(observer);
+    }
+    if (!observers?.size && cancellationObservers.get(pointerId) === observers)
+        cancellationObservers.delete(pointerId);
+    return true;
+}

package/dist/press/stateMachine.d.ts

@@ -0,0 +1,29 @@
+/** Whether a press is idle, held or cancelled. */
+export type PressState = 'idle' | 'pressed' | 'deactivated';
+export interface PressBounds {
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+}
+export interface PointerPressSession {
+    readonly bounds: PressBounds;
+    readonly pointerId: number;
+    readonly state: Exclude<PressState, 'idle'>;
+}
+export interface PressRelease {
+    readonly fire: boolean;
+    readonly state: 'idle';
+}
+export declare function beginPointerPress(pointerId: number, bounds: PressBounds): PointerPressSession;
+export declare function updatePointerPressBounds(session: PointerPressSession, bounds: PressBounds): PointerPressSession;
+export declare function movePointerPress(session: PointerPressSession, point: Readonly<{
+    x: number;
+    y: number;
+}>, retentionOffset: number): PointerPressSession;
+export declare function releasePointerPress(session: PointerPressSession): PressRelease;
+export declare function cancelPointerPress(): PressRelease;
+/** Visual feedback is separate from activation while a scroll still owns the touch. */
+export type RowFeedbackState = 'idle' | 'pending' | 'pressed' | 'releasing';
+export type RowFeedbackEvent = 'down' | 'hold' | 'release' | 'cancel';
+export declare function transitionRowFeedback(state: RowFeedbackState, event: RowFeedbackEvent): RowFeedbackState;

package/dist/press/stateMachine.js

@@ -0,0 +1,39 @@
+export function beginPointerPress(pointerId, bounds) {
+    return { bounds, pointerId, state: 'pressed' };
+}
+export function updatePointerPressBounds(session, bounds) {
+    if (session.bounds.bottom === bounds.bottom &&
+        session.bounds.left === bounds.left &&
+        session.bounds.right === bounds.right &&
+        session.bounds.top === bounds.top) {
+        return session;
+    }
+    return { ...session, bounds };
+}
+export function movePointerPress(session, point, retentionOffset) {
+    const { bounds } = session;
+    const insideRetentionRegion = point.x >= bounds.left - retentionOffset &&
+        point.x <= bounds.right + retentionOffset &&
+        point.y >= bounds.top - retentionOffset &&
+        point.y <= bounds.bottom + retentionOffset;
+    const state = insideRetentionRegion ? 'pressed' : 'deactivated';
+    return state === session.state ? session : { ...session, state };
+}
+export function releasePointerPress(session) {
+    return { fire: session.state === 'pressed', state: 'idle' };
+}
+export function cancelPointerPress() {
+    return { fire: false, state: 'idle' };
+}
+export function transitionRowFeedback(state, event) {
+    if (event === 'down')
+        return 'pending';
+    if (event === 'cancel')
+        return 'idle';
+    if (event === 'hold')
+        return state === 'pending' ? 'pressed' : state;
+    // A release can fade an existing highlight, but must never create one.
+    if (state === 'pending')
+        return 'idle';
+    return state === 'pressed' ? 'releasing' : state;
+}

package/dist/press/tokens.d.ts

@@ -0,0 +1,18 @@
+/** Measured from PressableReference on iPhone 17 Pro / iOS 26.5. */
+export declare const PRESSABLE_PRESSED_OPACITY = 0.75;
+/** The first changed reference frame was already at the pressed plateau. */
+export declare const PRESSABLE_PRESS_IN_DURATION_MS = 0;
+/** native reference release returned to rest in 400-418 ms at 60 Hz. */
+export declare const PRESSABLE_RELEASE_DURATION_MS = 400;
+/** Closest named curve to the measured decelerating release envelope. */
+export declare const PRESSABLE_RELEASE_EASING = "cubic-bezier(0, 0, 0.58, 1)";
+/** Native plain-Button retention measured 69 points beyond the label bounds. */
+export declare const PRESSABLE_RETENTION_OFFSET_PX = 69;
+export declare const pressableTokens: Readonly<{
+    pressedOpacity: 0.75;
+    pressInDurationMs: 0;
+    releaseDurationMs: 400;
+    releaseEasing: "cubic-bezier(0, 0, 0.58, 1)";
+    retentionOffsetPx: 69;
+}>;
+export declare const ROW_HIGHLIGHT_DELAY_MS = 175;

package/dist/press/tokens.js

@@ -0,0 +1,19 @@
+/** Measured from PressableReference on iPhone 17 Pro / iOS 26.5. */
+export const PRESSABLE_PRESSED_OPACITY = 0.75;
+/** The first changed reference frame was already at the pressed plateau. */
+export const PRESSABLE_PRESS_IN_DURATION_MS = 0;
+/** native reference release returned to rest in 400-418 ms at 60 Hz. */
+export const PRESSABLE_RELEASE_DURATION_MS = 400;
+/** Closest named curve to the measured decelerating release envelope. */
+export const PRESSABLE_RELEASE_EASING = 'cubic-bezier(0, 0, 0.58, 1)';
+/** Native plain-Button retention measured 69 points beyond the label bounds. */
+export const PRESSABLE_RETENTION_OFFSET_PX = 69;
+export const pressableTokens = Object.freeze({
+    pressedOpacity: PRESSABLE_PRESSED_OPACITY,
+    pressInDurationMs: PRESSABLE_PRESS_IN_DURATION_MS,
+    releaseDurationMs: PRESSABLE_RELEASE_DURATION_MS,
+    releaseEasing: PRESSABLE_RELEASE_EASING,
+    retentionOffsetPx: PRESSABLE_RETENTION_OFFSET_PX,
+});
+/* Stock Form row scroll-intent deadline. See row-picker-notes.md for the reference. */
+export const ROW_HIGHLIGHT_DELAY_MS = 175;

package/dist/press/usePressInteraction.d.ts

@@ -0,0 +1,30 @@
+import { type KeyboardEvent, type PointerEvent } from 'react';
+import { type RowFeedbackState, type PressState } from './stateMachine.js';
+/** Shared contact feedback. Native inputs keep their own browser activation. */
+export declare function usePressInteraction<T extends HTMLButtonElement | HTMLInputElement>({ disabled, feedback, onPress, onPressStateChange, nativeActivation, }: {
+    disabled?: boolean;
+    feedback?: 'opacity' | 'row';
+    onPress?: () => void;
+    onPressStateChange?: (state: PressState) => void;
+    nativeActivation?: boolean;
+}): {
+    elementRef: import("react").RefObject<T | null>;
+    pressState: PressState;
+    attributes: {
+        'data-satin-press-state': PressState;
+        'data-satin-press-feedback': "opacity" | "row";
+        'data-satin-row-feedback': RowFeedbackState | undefined;
+        'data-satin-press-transition': "cancel" | "instant" | "return";
+    };
+    handlers: {
+        onBlur: () => void;
+        onKeyDown: (event: KeyboardEvent<T>) => void;
+        onKeyUp: (event: KeyboardEvent<T>) => void;
+        onLostPointerCapture: (event: PointerEvent<T>) => void;
+        onPointerCancel: (event: PointerEvent<T>) => void;
+        onPointerDown: (event: PointerEvent<T>) => void;
+        onPointerMove: (event: PointerEvent<T>) => void;
+        onPointerUp: (event: PointerEvent<T>) => void;
+    };
+    onClick: () => void;
+};

package/dist/press/usePressInteraction.js

@@ -0,0 +1,247 @@
+import { useEffect, useRef, useState, startTransition, } from 'react';
+import { armPointerClickSuppression, beginKeyboardActivation, releaseKeyboardActivation, resolveClickActivation, } from './activation.js';
+import { transitionRowFeedback, beginPointerPress, cancelPointerPress, movePointerPress, updatePointerPressBounds, releasePointerPress, } from './stateMachine.js';
+import { ROW_HIGHLIGHT_DELAY_MS, PRESSABLE_RETENTION_OFFSET_PX } from './tokens.js';
+import { registerPointerPressCancellation } from './gestureArbitration.js';
+const PRESS_KEYS = new Set(['Enter', ' ']);
+const CLICK_SESSION_TIMEOUT_MS = 1_000;
+/** Shared contact feedback. Native inputs keep their own browser activation. */
+export function usePressInteraction({ disabled = false, feedback = 'opacity', onPress, onPressStateChange, nativeActivation = false, }) {
+    const [pressState, setRenderedPressState] = useState('idle');
+    const [pressTransition, setPressTransition] = useState('instant');
+    const [rowFeedback, setRowFeedback] = useState('idle');
+    const rowFeedbackRef = useRef('idle');
+    const rowDelayRef = useRef(undefined);
+    const elementRef = useRef(null);
+    const pressStateRef = useRef('idle');
+    const pointerSessionRef = useRef(undefined);
+    const pointerCancellationCleanupRef = useRef(undefined);
+    const keyboardSessionRef = useRef(undefined);
+    const keyboardCleanupRef = useRef(undefined);
+    const onPressRef = useRef(onPress);
+    const onPressStateChangeRef = useRef(onPressStateChange);
+    useEffect(() => {
+        onPressRef.current = onPress;
+        onPressStateChangeRef.current = onPressStateChange;
+    }, [onPress, onPressStateChange]);
+    const renderPressState = (nextState) => {
+        if (pressStateRef.current === nextState)
+            return;
+        const previousState = pressStateRef.current;
+        pressStateRef.current = nextState;
+        setPressTransition(previousState === 'deactivated' && nextState === 'pressed' ? 'return' : 'instant');
+        setRenderedPressState(nextState);
+        // Keep app preparation from suspending live contact feedback.
+        startTransition(() => onPressStateChangeRef.current?.(nextState));
+    };
+    const clearRowDelay = () => {
+        if (rowDelayRef.current === undefined)
+            return;
+        window.clearTimeout(rowDelayRef.current);
+        rowDelayRef.current = undefined;
+    };
+    const updateRowFeedback = (event) => {
+        if (feedback !== 'row')
+            return;
+        clearRowDelay();
+        rowFeedbackRef.current = transitionRowFeedback(rowFeedbackRef.current, event);
+        setRowFeedback(rowFeedbackRef.current);
+        if (event === 'down') {
+            rowDelayRef.current = window.setTimeout(() => updateRowFeedback('hold'), ROW_HIGHLIGHT_DELAY_MS);
+        }
+    };
+    const clearPointerSession = (element = elementRef.current) => {
+        const session = pointerSessionRef.current;
+        // A native input's browser click must retire with its cancelled contact.
+        // Buttons already own activation; leave their receipt path unchanged.
+        if (nativeActivation && session) {
+            armPointerClickSuppression(performance.now(), session.pointerId);
+        }
+        if (session || rowFeedbackRef.current === 'pending' || rowFeedbackRef.current === 'pressed') {
+            updateRowFeedback('cancel');
+        }
+        pointerSessionRef.current = undefined;
+        pointerCancellationCleanupRef.current?.();
+        pointerCancellationCleanupRef.current = undefined;
+        if (session && element?.hasPointerCapture(session.pointerId)) {
+            element.releasePointerCapture(session.pointerId);
+        }
+        renderPressState(cancelPointerPress().state);
+        setPressTransition('cancel');
+    };
+    const clearKeyboardSession = () => {
+        keyboardSessionRef.current = undefined;
+        if (keyboardCleanupRef.current !== undefined) {
+            window.clearTimeout(keyboardCleanupRef.current);
+            keyboardCleanupRef.current = undefined;
+        }
+    };
+    const scheduleKeyboardSessionCleanup = (session) => {
+        if (keyboardCleanupRef.current !== undefined) {
+            window.clearTimeout(keyboardCleanupRef.current);
+        }
+        keyboardCleanupRef.current = window.setTimeout(() => {
+            if (keyboardSessionRef.current === session) {
+                keyboardSessionRef.current = undefined;
+            }
+            keyboardCleanupRef.current = undefined;
+        }, CLICK_SESSION_TIMEOUT_MS);
+    };
+    const handlePointerDown = (event) => {
+        if (disabled || !event.isPrimary || (event.pointerType === 'mouse' && event.button !== 0)) {
+            return;
+        }
+        if (pointerSessionRef.current)
+            return;
+        const element = event.currentTarget;
+        const bounds = element.getBoundingClientRect();
+        pointerSessionRef.current = beginPointerPress(event.pointerId, bounds);
+        pointerCancellationCleanupRef.current = registerPointerPressCancellation(event.pointerId, () => {
+            if (pointerSessionRef.current?.pointerId !== event.pointerId)
+                return;
+            armPointerClickSuppression(performance.now(), event.pointerId);
+            clearPointerSession(element);
+        });
+        // Direct-manipulation pointers receive implicit capture. Asking WebKit
+        // for a second explicit capture can keep a control's recognizer alive
+        // after a ScrollSurface has won the pan; mouse input still needs it.
+        if (event.pointerType === 'mouse')
+            element.setPointerCapture(event.pointerId);
+        updateRowFeedback('down');
+        renderPressState('pressed');
+    };
+    const handlePointerMove = (event) => {
+        const session = pointerSessionRef.current;
+        if (!session || session.pointerId !== event.pointerId)
+            return;
+        const nextSession = movePointerPress(updatePointerPressBounds(session, event.currentTarget.getBoundingClientRect()), { x: event.clientX, y: event.clientY }, feedback === 'row' ? 0 : PRESSABLE_RETENTION_OFFSET_PX);
+        pointerSessionRef.current = nextSession;
+        if (nextSession.state === 'deactivated')
+            updateRowFeedback('cancel');
+        else if (rowFeedbackRef.current === 'idle')
+            updateRowFeedback('down');
+        renderPressState(nextSession.state);
+    };
+    const handlePointerUp = (event) => {
+        const session = pointerSessionRef.current;
+        if (!session || session.pointerId !== event.pointerId) {
+            if (!event.isPrimary)
+                armPointerClickSuppression(performance.now(), event.pointerId);
+            return;
+        }
+        const finalSession = movePointerPress(updatePointerPressBounds(session, event.currentTarget.getBoundingClientRect()), { x: event.clientX, y: event.clientY }, feedback === 'row' ? 0 : PRESSABLE_RETENTION_OFFSET_PX);
+        const release = releasePointerPress(finalSession);
+        pointerSessionRef.current = undefined;
+        pointerCancellationCleanupRef.current?.();
+        pointerCancellationCleanupRef.current = undefined;
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        updateRowFeedback(release.fire ? 'release' : 'cancel');
+        renderPressState(release.state);
+        // Arm the shared receipt for accepted AND rejected releases: WebKit's
+        // synthesized click follows either, and after a navigation unmount it
+        // can retarget to a different Pressable entirely.
+        if (!nativeActivation || !release.fire) {
+            armPointerClickSuppression(performance.now(), event.pointerId);
+        }
+        if (release.fire && !nativeActivation)
+            onPressRef.current?.();
+    };
+    const handlePointerCancel = (event) => {
+        const session = pointerSessionRef.current;
+        if (!session || session.pointerId !== event.pointerId)
+            return;
+        clearPointerSession(event.currentTarget);
+    };
+    const handleLostPointerCapture = (event) => {
+        if (pointerSessionRef.current?.pointerId === event.pointerId) {
+            clearPointerSession();
+        }
+    };
+    const handleKeyDown = (event) => {
+        if (disabled || !PRESS_KEYS.has(event.key))
+            return;
+        const result = beginKeyboardActivation(keyboardSessionRef.current, event.key);
+        keyboardSessionRef.current = result.session;
+        if (!result.started)
+            return;
+        updateRowFeedback('down');
+        updateRowFeedback('hold');
+        renderPressState('pressed');
+        if (result.fire && !nativeActivation)
+            onPressRef.current?.();
+    };
+    const handleKeyUp = (event) => {
+        if (!PRESS_KEYS.has(event.key))
+            return;
+        const result = releaseKeyboardActivation(keyboardSessionRef.current, event.key);
+        if (!result)
+            return;
+        keyboardSessionRef.current = result.session;
+        updateRowFeedback('release');
+        renderPressState('idle');
+        if (result.fire && !nativeActivation)
+            onPressRef.current?.();
+        scheduleKeyboardSessionCleanup(result.session);
+    };
+    const handleClick = () => {
+        if (disabled)
+            return;
+        const keyboardClick = resolveClickActivation(keyboardSessionRef.current);
+        keyboardSessionRef.current = keyboardClick.session;
+        if (!keyboardClick.fire) {
+            if (!keyboardClick.session)
+                clearKeyboardSession();
+            return;
+        }
+        onPressRef.current?.();
+    };
+    const handleBlur = () => {
+        const hadKeyboardSession = !!keyboardSessionRef.current;
+        clearKeyboardSession();
+        if (!pointerSessionRef.current) {
+            // Pointer activation can blur while its release animation is still visible.
+            if (hadKeyboardSession)
+                updateRowFeedback('cancel');
+            renderPressState('idle');
+        }
+    };
+    useEffect(() => {
+        if (!disabled)
+            return;
+        clearKeyboardSession();
+        clearPointerSession();
+    }, [disabled]);
+    useEffect(() => () => {
+        clearKeyboardSession();
+        clearRowDelay();
+        const session = pointerSessionRef.current;
+        pointerCancellationCleanupRef.current?.();
+        pointerCancellationCleanupRef.current = undefined;
+        if (session && elementRef.current?.hasPointerCapture(session.pointerId)) {
+            elementRef.current.releasePointerCapture(session.pointerId);
+        }
+    }, []);
+    return {
+        elementRef,
+        pressState,
+        attributes: {
+            'data-satin-press-state': pressState,
+            'data-satin-press-feedback': feedback,
+            'data-satin-row-feedback': feedback === 'row' ? rowFeedback : undefined,
+            'data-satin-press-transition': pressTransition,
+        },
+        handlers: {
+            onBlur: handleBlur,
+            onKeyDown: handleKeyDown,
+            onKeyUp: handleKeyUp,
+            onLostPointerCapture: handleLostPointerCapture,
+            onPointerCancel: handlePointerCancel,
+            onPointerDown: handlePointerDown,
+            onPointerMove: handlePointerMove,
+            onPointerUp: handlePointerUp,
+        },
+        onClick: handleClick,
+    };
+}

package/dist/public/Label.d.ts

@@ -0,0 +1,16 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SymbolName } from '../symbols/Symbol.js';
+import { type BuiltInLabelStyle, type LabelStyle } from './controlStyle.js';
+/** A label's title (children) and its icon: a `symbol` name or any `icon` node. */
+export type LabelProps = {
+    children: ReactNode;
+    icon?: ReactNode;
+    symbol?: SymbolName;
+    labelStyle?: BuiltInLabelStyle | LabelStyle;
+    style?: CSSProperties;
+};
+/** Combines a semantic title and icon. Hidden titles remain available to assistive technology; toolbar labels with icons show the icon alone. */
+export declare function Label({ children, icon, symbol, labelStyle: requestedStyle, style: cssStyle, }: LabelProps): import("react").JSX.Element;
+/** The accessible name of a toolbar label that draws only an icon: a `Label` with an icon, or a
+ * `SymbolImage`. A toolbar button or menu with such a label is a glass circle. */
+export declare function toolbarIconName(label: ReactNode): string | undefined;