@xaui/native 0.9.1-alpha.9 → 0.9.1-alpha.91

package/dist/system/pressable-feedback/pressable-feedback.animation.d.ts

@@ -0,0 +1,68 @@
+import type { AnimationProp, ResolvedAnimation, SlotAnimation } from './pressable-feedback.type';
+/**
+ * How far a control shrinks under the finger — **before** the width coefficient below.
+ *
+ * The v0 tree shrank everything to a flat `0.975`, which is why a wide button read as
+ * lurching: a ratio applied to a 360pt row moves nine points, and the same ratio on a
+ * 96pt chip moves two. What the eye reads is the displacement, not the ratio.
+ */
+export declare const PRESS_SCALE = 0.985;
+export declare const PRESS_DURATION = 300;
+/**
+ * The width at which `PRESS_SCALE` is applied as written. Wider controls shrink
+ * proportionally less, narrower ones more, so the movement stays roughly constant in
+ * points across a 96pt chip and a full-width button.
+ */
+export declare const SCALE_REFERENCE_WIDTH = 300;
+/** The scale a control of `width` should reach when pressed. */
+export declare function pressScaleFor(width: number): number;
+/** How far the wash goes at full press, and how long it takes to get there. */
+export declare const HIGHLIGHT_OPACITY = 0.1;
+export declare const HIGHLIGHT_DURATION = 200;
+/**
+ * The ripple, taken from Material's reference implementation (`InkRipple`) rather than
+ * approximated. Four of its numbers are load-bearing and none of them is obvious:
+ *
+ * - **The opacity is not tied to the expansion.** It reaches full ink in 75ms and stays
+ *   there while the circle keeps growing. Tying the two — the obvious thing to write —
+ *   means the ink is faintest exactly when the circle is small enough to be read as a
+ *   circle, which is why such a ripple looks like nothing at all.
+ * - **The circle starts at 30% of its target**, not at a point. A wave from a dot spends
+ *   its visible life too small to see.
+ * - **The target radius is half the diagonal**, which is what covers the box. Larger and
+ *   the edge leaves the control before the eye catches it, so the effect reads as the
+ *   surface tinting rather than as something spreading.
+ * - **The centre travels** from the finger to the middle of the control as it opens, which
+ *   is what makes it settle into the control instead of flooding out of a corner.
+ *
+ * The expansion runs a full second while the finger is down, and finishes in 225ms once it
+ * lifts — the wave catches up rather than being cut.
+ */
+export declare const RIPPLE_OPACITY = 0.1;
+export declare const RIPPLE_START_SCALE = 0.3;
+export declare const RIPPLE_EXPAND_DURATION = 1000;
+export declare const RIPPLE_CONFIRM_DURATION = 225;
+export declare const RIPPLE_FADE_IN = 75;
+export declare const RIPPLE_FADE_OUT_DELAY = 225;
+export declare const RIPPLE_FADE_OUT = 150;
+/** Half the diagonal covers the box from its centre; the 5 is Material's own overshoot. */
+export declare function rippleRadiusFor(width: number, height: number): number;
+/**
+ * One shape out of four accepted ones, so the components read a record instead of
+ * re-deciding what `'disable-all'` meant.
+ *
+ * `inheritedDisableAll` comes from an ancestor that asked for it, and it wins: a list
+ * that switched its rows' animations off cannot be overridden by a row.
+ */
+export declare function resolveAnimation(animation: AnimationProp | undefined, inheritedDisableAll?: boolean): ResolvedAnimation;
+export type ResolvedSlotAnimation = {
+    enabled: boolean;
+    duration: number;
+    opacity: number;
+};
+/**
+ * A slot's own `animation` over the root's blanket one, with the root winning when it
+ * switched everything off — `animation="disable-all"` on an ancestor cannot be undone by
+ * an overlay that asks nicely.
+ */
+export declare function resolveSlotAnimation(override: SlotAnimation | undefined, enabledByRoot: boolean, defaultOpacity: number, defaultDuration?: number): ResolvedSlotAnimation;

package/dist/system/pressable-feedback/pressable-feedback.d.cts

@@ -0,0 +1,41 @@
+import { View } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { useFeedback } from './pressable-feedback-context';
+/**
+ * The pressable root every pressable component renders — `Button`, `Chip`, a clickable
+ * `Card`, `ListItem`, `MenuItem`, `SegmentButton`. Touch feedback is identical
+ * everywhere, so it is written once here rather than forty-seven times.
+ *
+ * **Controlled.** The root above owns `isPressed`, because its recipe resolves on it
+ * (R5) and it needs the value before it renders. This applies the value; it does not
+ * decide it.
+ *
+ * **The root scales; overlays are composed.** There is no prop naming what to mount — a
+ * wash or a wave is a child:
+ *
+ * ```tsx
+ * <PressableFeedback isPressed={isPressed} style={styles.root}>
+ *   <PressableFeedback.Ripple />
+ *   <Label />
+ * </PressableFeedback>
+ * ```
+ *
+ * Order does not matter: the root paints its overlays under everything else wherever they
+ * were written. Leaving that to source order would have made a `Ripple` written after the
+ * label sit on top of it — a 10% wash over text, subtle enough to ship by accident.
+ *
+ * What an overlay needs from its surface is published here rather than configured on it:
+ * the root flattens its own `style` and takes the contrasting ink and the corner radii off
+ * it. Only the root knows what an overlay sits on, so only the root can pick an ink that
+ * is visible on it and a shape that matches it.
+ */
+export declare const PressableFeedback: import("react").ForwardRefExoticComponent<Omit<import("react-native").PressableProps, "disabled" | "style" | "children"> & import("..").ViewStyleProps & {
+    isPressed?: boolean;
+    isDisabled?: boolean;
+    asChild?: boolean;
+    animation?: import("./pressable-feedback.type").AnimationProp;
+    layout?: import("react-native-reanimated").AnimatedProps<import("react-native").PressableProps>["layout"];
+    style?: StyleProp<ViewStyle>;
+    children?: import("react").ReactNode;
+} & import("react").RefAttributes<View>>;
+export { useFeedback };

package/dist/system/pressable-feedback/pressable-feedback.d.ts

@@ -0,0 +1,41 @@
+import { View } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { useFeedback } from './pressable-feedback-context';
+/**
+ * The pressable root every pressable component renders — `Button`, `Chip`, a clickable
+ * `Card`, `ListItem`, `MenuItem`, `SegmentButton`. Touch feedback is identical
+ * everywhere, so it is written once here rather than forty-seven times.
+ *
+ * **Controlled.** The root above owns `isPressed`, because its recipe resolves on it
+ * (R5) and it needs the value before it renders. This applies the value; it does not
+ * decide it.
+ *
+ * **The root scales; overlays are composed.** There is no prop naming what to mount — a
+ * wash or a wave is a child:
+ *
+ * ```tsx
+ * <PressableFeedback isPressed={isPressed} style={styles.root}>
+ *   <PressableFeedback.Ripple />
+ *   <Label />
+ * </PressableFeedback>
+ * ```
+ *
+ * Order does not matter: the root paints its overlays under everything else wherever they
+ * were written. Leaving that to source order would have made a `Ripple` written after the
+ * label sit on top of it — a 10% wash over text, subtle enough to ship by accident.
+ *
+ * What an overlay needs from its surface is published here rather than configured on it:
+ * the root flattens its own `style` and takes the contrasting ink and the corner radii off
+ * it. Only the root knows what an overlay sits on, so only the root can pick an ink that
+ * is visible on it and a shape that matches it.
+ */
+export declare const PressableFeedback: import("react").ForwardRefExoticComponent<Omit<import("react-native").PressableProps, "disabled" | "style" | "children"> & import("..").ViewStyleProps & {
+    isPressed?: boolean;
+    isDisabled?: boolean;
+    asChild?: boolean;
+    animation?: import("./pressable-feedback.type").AnimationProp;
+    layout?: import("react-native-reanimated").AnimatedProps<import("react-native").PressableProps>["layout"];
+    style?: StyleProp<ViewStyle>;
+    children?: import("react").ReactNode;
+} & import("react").RefAttributes<View>>;
+export { useFeedback };

package/dist/system/pressable-feedback/pressable-feedback.overlay.d.cts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+/**
+ * What marks a component as a press overlay.
+ *
+ * `Symbol.for` rather than a boolean field or an identity check against our own two
+ * components: the registry is global, so two copies of `@xaui/native` in one tree still
+ * agree on what an overlay is, and a third party writing their own overlay — anything that
+ * reads `useFeedback()` and paints under the content — opts into the same treatment
+ * instead of being a second-class citizen.
+ */
+export declare const FEEDBACK_OVERLAY: unique symbol;
+/** Tags a component so `PressableFeedback` paints it under its content. */
+export declare function markOverlay<T extends object>(component: T): T;
+/**
+ * Splits the root's children into the bare overlays and everything else, so the root can
+ * paint those overlays first **whatever order they were written in**.
+ *
+ * Without this, source order decides the stacking: a `Ripple` written after the label sits
+ * on top of it rather than under it, and a 10% wash over the text is exactly subtle enough
+ * to be shipped by accident. Composition should not carry an invisible ordering rule.
+ *
+ * A wrapping overlay — `<Ripple>{children}</Ripple>` — is left where it is, because it
+ * already puts itself under the content it was given.
+ *
+ * Only direct children are inspected. An overlay wrapped in a `Fragment` keeps source
+ * order: descending would mean re-keying a fragment's children into their parent's list,
+ * where they can collide with a sibling fragment's, and no real call site needs it — an
+ * overlay is written next to the content, and a conditional one (`{isX && <Ripple />}`) is
+ * still a direct child.
+ */
+export declare function partitionOverlays(children: ReactNode): {
+    overlays: ReactNode;
+    content: ReactNode;
+};
+/**
+ * What the root actually renders, as **one** node.
+ *
+ * Written as a single value rather than as `{overlays}{content}` in the JSX, because those
+ * are two expression children and React hands two children to the root as an *array*.
+ * Under `asChild` the root is a `Slot`, which merges into one element and has nothing to
+ * merge into an array — so every pressable's `asChild` threw, whether or not it composed
+ * an overlay: with none, `partitionOverlays` still returns `overlays: null`, and
+ * `[null, content]` is an array all the same.
+ *
+ * `asChild` also skips the partition entirely. The caller's element *is* the pressable, so
+ * there is no sibling slot to hoist an overlay into — an overlay written inside that
+ * element belongs to it, and pulling it out would make it a sibling of the very element it
+ * was composed into. It reads the feedback context, which is published above the root and
+ * descends into it regardless of where it sits.
+ */
+export declare function feedbackChildren(children: ReactNode, asChild: boolean): ReactNode;

package/dist/system/pressable-feedback/pressable-feedback.overlay.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+/**
+ * What marks a component as a press overlay.
+ *
+ * `Symbol.for` rather than a boolean field or an identity check against our own two
+ * components: the registry is global, so two copies of `@xaui/native` in one tree still
+ * agree on what an overlay is, and a third party writing their own overlay — anything that
+ * reads `useFeedback()` and paints under the content — opts into the same treatment
+ * instead of being a second-class citizen.
+ */
+export declare const FEEDBACK_OVERLAY: unique symbol;
+/** Tags a component so `PressableFeedback` paints it under its content. */
+export declare function markOverlay<T extends object>(component: T): T;
+/**
+ * Splits the root's children into the bare overlays and everything else, so the root can
+ * paint those overlays first **whatever order they were written in**.
+ *
+ * Without this, source order decides the stacking: a `Ripple` written after the label sits
+ * on top of it rather than under it, and a 10% wash over the text is exactly subtle enough
+ * to be shipped by accident. Composition should not carry an invisible ordering rule.
+ *
+ * A wrapping overlay — `<Ripple>{children}</Ripple>` — is left where it is, because it
+ * already puts itself under the content it was given.
+ *
+ * Only direct children are inspected. An overlay wrapped in a `Fragment` keeps source
+ * order: descending would mean re-keying a fragment's children into their parent's list,
+ * where they can collide with a sibling fragment's, and no real call site needs it — an
+ * overlay is written next to the content, and a conditional one (`{isX && <Ripple />}`) is
+ * still a direct child.
+ */
+export declare function partitionOverlays(children: ReactNode): {
+    overlays: ReactNode;
+    content: ReactNode;
+};
+/**
+ * What the root actually renders, as **one** node.
+ *
+ * Written as a single value rather than as `{overlays}{content}` in the JSX, because those
+ * are two expression children and React hands two children to the root as an *array*.
+ * Under `asChild` the root is a `Slot`, which merges into one element and has nothing to
+ * merge into an array — so every pressable's `asChild` threw, whether or not it composed
+ * an overlay: with none, `partitionOverlays` still returns `overlays: null`, and
+ * `[null, content]` is an array all the same.
+ *
+ * `asChild` also skips the partition entirely. The caller's element *is* the pressable, so
+ * there is no sibling slot to hoist an overlay into — an overlay written inside that
+ * element belongs to it, and pulling it out would make it a sibling of the very element it
+ * was composed into. It reads the feedback context, which is published above the root and
+ * descends into it regardless of where it sits.
+ */
+export declare function feedbackChildren(children: ReactNode, asChild: boolean): ReactNode;

package/dist/system/pressable-feedback/pressable-feedback.surface.d.cts

@@ -0,0 +1,35 @@
+import type { ColorValue, ViewStyle } from 'react-native';
+import type { RadiusStyle } from './pressable-feedback.type';
+/**
+ * The colours an ink is picked from — the theme's two extremes and its fallback.
+ * Named rather than taking the whole theme, so this stays a pure function with a test.
+ */
+export type InkColors = {
+    snow: string;
+    eclipse: string;
+    foreground: string;
+};
+/**
+ * The ink an overlay needs to be visible on this control.
+ *
+ * A wash or a wave has to contrast with what it sits on, and the root is the only thing
+ * that knows: it can read its own `backgroundColor`. Two cases fall back to the theme's
+ * `foreground`, and both for the same reason — the control is showing what is behind it:
+ *
+ * - **No background at all**, a `ghost` or a transparent row.
+ * - **A translucent one.** Every `…Soft` token is an `rgba()`, and a luminance cannot be
+ *   read off a colour that is partly whatever is underneath. `contrastOn` throws on
+ *   anything that is not hex rather than guessing, so this asks first.
+ */
+export declare function inkFor(background: ColorValue | undefined, colors: InkColors): string;
+/**
+ * The root's corners, for an overlay to round itself to the same shape.
+ *
+ * An absolute fill has square corners; every control here is rounded. Copying is what
+ * keeps the clip on the overlay instead of on the root — a root that clipped would also
+ * cut a badge sitting on its corner, which has nothing to do with the press.
+ *
+ * Undefined keys are dropped rather than passed through as `undefined`, so the returned
+ * object composes into a style array without overriding what an earlier entry set.
+ */
+export declare function radiusFrom(style: ViewStyle | undefined): RadiusStyle;

package/dist/system/pressable-feedback/pressable-feedback.surface.d.ts

@@ -0,0 +1,35 @@
+import type { ColorValue, ViewStyle } from 'react-native';
+import type { RadiusStyle } from './pressable-feedback.type';
+/**
+ * The colours an ink is picked from — the theme's two extremes and its fallback.
+ * Named rather than taking the whole theme, so this stays a pure function with a test.
+ */
+export type InkColors = {
+    snow: string;
+    eclipse: string;
+    foreground: string;
+};
+/**
+ * The ink an overlay needs to be visible on this control.
+ *
+ * A wash or a wave has to contrast with what it sits on, and the root is the only thing
+ * that knows: it can read its own `backgroundColor`. Two cases fall back to the theme's
+ * `foreground`, and both for the same reason — the control is showing what is behind it:
+ *
+ * - **No background at all**, a `ghost` or a transparent row.
+ * - **A translucent one.** Every `…Soft` token is an `rgba()`, and a luminance cannot be
+ *   read off a colour that is partly whatever is underneath. `contrastOn` throws on
+ *   anything that is not hex rather than guessing, so this asks first.
+ */
+export declare function inkFor(background: ColorValue | undefined, colors: InkColors): string;
+/**
+ * The root's corners, for an overlay to round itself to the same shape.
+ *
+ * An absolute fill has square corners; every control here is rounded. Copying is what
+ * keeps the clip on the overlay instead of on the root — a root that clipped would also
+ * cut a badge sitting on its corner, which has nothing to do with the press.
+ *
+ * Undefined keys are dropped rather than passed through as `undefined`, so the returned
+ * object composes into a style array without overriding what an earlier entry set.
+ */
+export declare function radiusFrom(style: ViewStyle | undefined): RadiusStyle;

package/dist/system/pressable-feedback/pressable-feedback.type.d.cts

@@ -0,0 +1,136 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, StyleProp, ViewStyle } from 'react-native';
+import type { AnimatedProps, SharedValue } from 'react-native-reanimated';
+import type { ViewStyleProps } from '../style-props';
+export type AnimationConfig = {
+    scale?: boolean;
+    highlight?: boolean;
+    ripple?: boolean;
+};
+/**
+ * `false` and `'disabled'` turn this component's animations off. `'disable-all'` turns
+ * them off for its descendants too — a long list kills every row's worklets with one
+ * prop instead of threading it down. An object switches them off one at a time.
+ */
+export type AnimationProp = boolean | 'disabled' | 'disable-all' | AnimationConfig;
+/** `animation` once normalised — what the components actually read. */
+export type ResolvedAnimation = {
+    scale: boolean;
+    highlight: boolean;
+    ripple: boolean;
+    /** True when every sub-animation is off: the branch that mounts no worklet at all. */
+    none: boolean;
+    /** Propagated to descendants through context. */
+    disableAll: boolean;
+};
+/**
+ * R14 — it renders a `Pressable`, so it takes that node's style keys as props. The
+ * primitive every pressable component in the library is built on cannot be the one place
+ * where `padding={16}` has to become an object again.
+ */
+export type PressableFeedbackProps = Omit<PressableProps, 'style' | 'children' | 'disabled'> & ViewStyleProps & {
+    /** Controlled: the root owns the state, because its recipe resolves on it (R5). */
+    isPressed?: boolean;
+    /** R8: `disabled` is not part of the public vocabulary, `isX` is. */
+    isDisabled?: boolean;
+    /**
+     * Merge into the single child instead of rendering a pressable (R12) — **keeping the
+     * feedback**. Swapping this component out for a bare `Slot` would silently drop the
+     * touch feedback of every `asChild` control.
+     */
+    asChild?: boolean;
+    animation?: AnimationProp;
+    /**
+     * Reanimated's layout transition, for a control whose **own box** changes size — a
+     * `MorphButton` growing from a pill into a card. It is here rather than in that
+     * component because the box that travels is this node: a transition on a wrapper
+     * animates the wrapper's frame while the pressable inside it is already at its final
+     * size, so the content spills out of the shape halfway through.
+     *
+     * It has no effect on the static branch, which mounts a plain `Pressable` and no
+     * worklet at all: `animation={false}` turns the morph off with everything else, which
+     * is the answer a caller asking for no animation wanted.
+     */
+    layout?: AnimatedProps<PressableProps>['layout'];
+    style?: StyleProp<ViewStyle>;
+    /**
+     * The overlays are children, not a prop — `<PressableFeedback.Highlight />` or
+     * `<PressableFeedback.Ripple />`, in any order: the root paints them under everything
+     * else wherever they sit. The scale is the root's own and needs nothing rendered.
+     *
+     * `Pressable`'s function form is dropped on purpose. It exists to hand the press state
+     * to children; here the root above already owns that state and this publishes it
+     * through context, so the function form would be a second, quieter source of truth.
+     */
+    children?: ReactNode;
+};
+/**
+ * A slot's own animation, overriding the blanket one on the root. `false` switches that
+ * slot off; the object tunes it. Deliberately two knobs rather than a full timing
+ * surface — anything past this is a different animation, and that is a component's job,
+ * not a prop's.
+ */
+export type SlotAnimation = boolean | {
+    /** Milliseconds. Falls back to the shared press timing. */
+    duration?: number;
+    /** How far the overlay goes at full press, 0 to 1. */
+    opacity?: number;
+};
+/** One ripple wave. Two of them, so a rapid double tap does not cut the one in flight. */
+export type RippleWave = {
+    /** `0 → 1` as the circle opens. */
+    expand: SharedValue<number>;
+    /** `0 → 1` as the ink arrives, on its own curve. */
+    alpha: SharedValue<number>;
+    /** Where the finger landed, in the root's coordinates. */
+    origin: SharedValue<{
+        x: number;
+        y: number;
+    }>;
+};
+/**
+ * The corner keys an overlay copies off the root. The `Left`/`Right` forms are absent
+ * rather than forgotten: R13 bans them, because RN mirrors only the logical ones under RTL.
+ */
+export type RadiusStyle = Pick<ViewStyle, 'borderRadius' | 'borderStartStartRadius' | 'borderStartEndRadius' | 'borderEndStartRadius' | 'borderEndEndRadius'>;
+export type FeedbackContext = {
+    /**
+     * The overlay's ink, resolved by the root from its own background.
+     *
+     * A wash or a wave has to contrast with what it sits on, and only the root knows that —
+     * it flattens its own `style` and reads `backgroundColor`, then takes the contrasting
+     * side the same way a tint does. Black ink at 10% on a saturated fill is close to
+     * invisible, which is the one thing a press indicator cannot be.
+     */
+    ink: string;
+    /**
+     * The root's own corners, so an overlay rounds itself to match. `corners` and not
+     * `radius`: the ripple already has a radius, and it is a length in points rather than a
+     * shape.
+     *
+     * An absolute fill has square corners and every control here is rounded, so without this
+     * both the wash and the wave paint outside the surface at each corner. The overlay
+     * carries the clip rather than the root: clipping the root would also cut a child that
+     * legitimately overflows — a badge on a button's corner — and that child has nothing to
+     * do with the press.
+     */
+    corners: RadiusStyle;
+    isPressed: boolean;
+    animation: ResolvedAnimation;
+    /** Absent on the static branch, where nothing animates and no worklet is mounted. */
+    progress?: SharedValue<number>;
+    /** How big the root is — what the scale coefficient is computed from. */
+    size?: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * The two ripple waves, driven by the **root**.
+     *
+     * They belong to the root because the root is the touch surface. An overlay carrying its
+     * own handlers only hears touches that land on *it* — and it is a sibling of the label,
+     * not its parent, so pressing the text of a button would do nothing. Touches bubble to
+     * the `Pressable`, which is why the handlers live there and the waves are published down.
+     */
+    waves?: readonly [RippleWave, RippleWave];
+};

package/dist/system/pressable-feedback/pressable-feedback.type.d.ts

@@ -0,0 +1,136 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, StyleProp, ViewStyle } from 'react-native';
+import type { AnimatedProps, SharedValue } from 'react-native-reanimated';
+import type { ViewStyleProps } from '../style-props';
+export type AnimationConfig = {
+    scale?: boolean;
+    highlight?: boolean;
+    ripple?: boolean;
+};
+/**
+ * `false` and `'disabled'` turn this component's animations off. `'disable-all'` turns
+ * them off for its descendants too — a long list kills every row's worklets with one
+ * prop instead of threading it down. An object switches them off one at a time.
+ */
+export type AnimationProp = boolean | 'disabled' | 'disable-all' | AnimationConfig;
+/** `animation` once normalised — what the components actually read. */
+export type ResolvedAnimation = {
+    scale: boolean;
+    highlight: boolean;
+    ripple: boolean;
+    /** True when every sub-animation is off: the branch that mounts no worklet at all. */
+    none: boolean;
+    /** Propagated to descendants through context. */
+    disableAll: boolean;
+};
+/**
+ * R14 — it renders a `Pressable`, so it takes that node's style keys as props. The
+ * primitive every pressable component in the library is built on cannot be the one place
+ * where `padding={16}` has to become an object again.
+ */
+export type PressableFeedbackProps = Omit<PressableProps, 'style' | 'children' | 'disabled'> & ViewStyleProps & {
+    /** Controlled: the root owns the state, because its recipe resolves on it (R5). */
+    isPressed?: boolean;
+    /** R8: `disabled` is not part of the public vocabulary, `isX` is. */
+    isDisabled?: boolean;
+    /**
+     * Merge into the single child instead of rendering a pressable (R12) — **keeping the
+     * feedback**. Swapping this component out for a bare `Slot` would silently drop the
+     * touch feedback of every `asChild` control.
+     */
+    asChild?: boolean;
+    animation?: AnimationProp;
+    /**
+     * Reanimated's layout transition, for a control whose **own box** changes size — a
+     * `MorphButton` growing from a pill into a card. It is here rather than in that
+     * component because the box that travels is this node: a transition on a wrapper
+     * animates the wrapper's frame while the pressable inside it is already at its final
+     * size, so the content spills out of the shape halfway through.
+     *
+     * It has no effect on the static branch, which mounts a plain `Pressable` and no
+     * worklet at all: `animation={false}` turns the morph off with everything else, which
+     * is the answer a caller asking for no animation wanted.
+     */
+    layout?: AnimatedProps<PressableProps>['layout'];
+    style?: StyleProp<ViewStyle>;
+    /**
+     * The overlays are children, not a prop — `<PressableFeedback.Highlight />` or
+     * `<PressableFeedback.Ripple />`, in any order: the root paints them under everything
+     * else wherever they sit. The scale is the root's own and needs nothing rendered.
+     *
+     * `Pressable`'s function form is dropped on purpose. It exists to hand the press state
+     * to children; here the root above already owns that state and this publishes it
+     * through context, so the function form would be a second, quieter source of truth.
+     */
+    children?: ReactNode;
+};
+/**
+ * A slot's own animation, overriding the blanket one on the root. `false` switches that
+ * slot off; the object tunes it. Deliberately two knobs rather than a full timing
+ * surface — anything past this is a different animation, and that is a component's job,
+ * not a prop's.
+ */
+export type SlotAnimation = boolean | {
+    /** Milliseconds. Falls back to the shared press timing. */
+    duration?: number;
+    /** How far the overlay goes at full press, 0 to 1. */
+    opacity?: number;
+};
+/** One ripple wave. Two of them, so a rapid double tap does not cut the one in flight. */
+export type RippleWave = {
+    /** `0 → 1` as the circle opens. */
+    expand: SharedValue<number>;
+    /** `0 → 1` as the ink arrives, on its own curve. */
+    alpha: SharedValue<number>;
+    /** Where the finger landed, in the root's coordinates. */
+    origin: SharedValue<{
+        x: number;
+        y: number;
+    }>;
+};
+/**
+ * The corner keys an overlay copies off the root. The `Left`/`Right` forms are absent
+ * rather than forgotten: R13 bans them, because RN mirrors only the logical ones under RTL.
+ */
+export type RadiusStyle = Pick<ViewStyle, 'borderRadius' | 'borderStartStartRadius' | 'borderStartEndRadius' | 'borderEndStartRadius' | 'borderEndEndRadius'>;
+export type FeedbackContext = {
+    /**
+     * The overlay's ink, resolved by the root from its own background.
+     *
+     * A wash or a wave has to contrast with what it sits on, and only the root knows that —
+     * it flattens its own `style` and reads `backgroundColor`, then takes the contrasting
+     * side the same way a tint does. Black ink at 10% on a saturated fill is close to
+     * invisible, which is the one thing a press indicator cannot be.
+     */
+    ink: string;
+    /**
+     * The root's own corners, so an overlay rounds itself to match. `corners` and not
+     * `radius`: the ripple already has a radius, and it is a length in points rather than a
+     * shape.
+     *
+     * An absolute fill has square corners and every control here is rounded, so without this
+     * both the wash and the wave paint outside the surface at each corner. The overlay
+     * carries the clip rather than the root: clipping the root would also cut a child that
+     * legitimately overflows — a badge on a button's corner — and that child has nothing to
+     * do with the press.
+     */
+    corners: RadiusStyle;
+    isPressed: boolean;
+    animation: ResolvedAnimation;
+    /** Absent on the static branch, where nothing animates and no worklet is mounted. */
+    progress?: SharedValue<number>;
+    /** How big the root is — what the scale coefficient is computed from. */
+    size?: SharedValue<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * The two ripple waves, driven by the **root**.
+     *
+     * They belong to the root because the root is the touch surface. An overlay carrying its
+     * own handlers only hears touches that land on *it* — and it is a sibling of the label,
+     * not its parent, so pressing the text of a button would do nothing. Touches bubble to
+     * the `Pressable`, which is why the handlers live there and the waves are published down.
+     */
+    waves?: readonly [RippleWave, RippleWave];
+};

package/dist/system/recipe/create-recipe.d.cts

@@ -0,0 +1,31 @@
+import type { XAUITheme } from '../../theme/theme.type';
+import type { Axes, RecipeConfig, ResolvedStyles, Selection, SlotStyles, States } from './recipe.type';
+export type ResolveArgs<Variant extends string, A extends Axes<string>> = {
+    theme: XAUITheme;
+    selection?: Selection<Variant, A>;
+    states?: States;
+};
+export type TintArgs<Variant extends string, A extends Axes<string>> = ResolveArgs<Variant, A> & {
+    color: string;
+};
+export type Recipe<Slot extends string, Variant extends string, A extends Axes<Slot>> = {
+    readonly slots: readonly Slot[];
+    /** The cached pass: stable `StyleSheet` references, keyed by tokens alone. */
+    resolve(args: ResolveArgs<Variant, A>): ResolvedStyles<Slot>;
+    /**
+     * The tint pass: the same functions run again with `color`'s slices in place of the
+     * theme's tokens. Uncached and allocating, and only ever called when `color` is set.
+     */
+    tint(args: TintArgs<Variant, A>): SlotStyles<Slot>;
+};
+/**
+ * A component's style, declared once. Resolution splits in two because the two halves
+ * have different lifetimes: everything keyed by a finite token is cached forever, and
+ * an arbitrary `color` is recomputed per render — which is what keeps the cache bounded
+ * by the number of token combinations rather than by the palette users invent.
+ *
+ *     const styles = buttonRecipe.resolve({ theme, selection: { variant, size }, states })
+ *     const tint = color ? buttonRecipe.tint({ theme, color, selection, states }) : undefined
+ *     <View style={[styles.root, tint?.root, style]} />
+ */
+export declare function createRecipe<Slot extends string, Variant extends string, const A extends Axes<Slot>>(config: RecipeConfig<Slot, Variant, A>): Recipe<Slot, Variant, A>;