@xaui/native 0.9.1-alpha.2 → 0.9.1-alpha.21

package/dist/system/index.d.cts

@@ -1,86 +1,123 @@
-import { g as XAUITheme, X as XAUIColors } from '../theme.type-B3ODSLbB.cjs';
-import { ViewStyle, TextStyle } from 'react-native';
 import * as react from 'react';
 import { ReactNode, Provider, Ref, RefCallback } from 'react';
+import { b as IconProps, a as IconContextValue } from '../icon.type-Cs1tMX0W.cjs';
+export { I as IconComponentProps } from '../icon.type-Cs1tMX0W.cjs';
+import { V as ViewStyleProps } from '../style-props.type-B1BG5TCm.cjs';
+export { D as DirectionalStyleKey, I as ImageStyleProps, S as StyleProps, T as TextStyleProps } from '../style-props.type-B1BG5TCm.cjs';
+import { S as SlotAnimation, F as FeedbackContext, a as AnimationProp, b as ResolvedAnimation } from '../pressable-feedback.type-wfeiJz5m.cjs';
+export { A as AnimationConfig, P as PressableFeedbackProps, R as RadiusStyle, c as RippleWave } from '../pressable-feedback.type-wfeiJz5m.cjs';
+import * as react_native from 'react-native';
+import { StyleProp, ViewStyle } from 'react-native';
+export { A as Axes, C as CompoundVariant, R as Recipe, b as RecipeConfig, a as ResolveArgs, d as ResolvedSelection, e as ResolvedStyles, S as Selection, f as SlotStyle, g as SlotStyles, h as StateName, i as States, j as StyleFn, T as TintArgs, V as VariantColors, k as VariantRole, l as VariantTokens, c as createRecipe } from '../create-recipe-CPBFg7ym.cjs';
+import 'react-native-reanimated';
+import '../theme.type-C2gNHpEx.cjs';
 
 /**
- * A slot is a view or a text node, and a recipe writes one object per slot, so the two
- * RN style shapes are merged rather than discriminated per slot.
- */
-type SlotStyle = ViewStyle & TextStyle;
-type SlotStyles<Slot extends string> = Partial<Record<Slot, SlotStyle>>;
-/** The roles a variant consumes. The variant names tokens; `paint` says where they land. */
-type VariantRole = 'bg' | 'bgPressed' | 'fg' | 'border';
-/** Token names per role — no colour value ever appears in a recipe. */
-type VariantTokens = Partial<Record<VariantRole, keyof XAUIColors>>;
-/** The same roles resolved: theme colours, or the slices of a raw `color`. */
-type VariantColors = Partial<Record<VariantRole, string>>;
-/**
- * `disabled` is applied last of the three: a control that is both pressed and disabled
- * has to read disabled.
- */
-type StateName = 'focused' | 'pressed' | 'disabled';
-type States = Partial<Record<StateName, boolean>>;
-/** Reads the theme and the variant's resolved colours; returns one style per slot. */
-type StyleFn<Slot extends string> = (theme: XAUITheme, colors: VariantColors) => SlotStyles<Slot>;
-/** Named axes of finite token values — `{ size: { sm: fn, md: fn } }`. */
-type Axes<Slot extends string> = Record<string, Record<string, StyleFn<Slot>>>;
-/** One value per axis, plus the variant. Missing keys fall back to `defaultVariants`. */
-type Selection<Variant extends string, A extends Axes<string>> = {
-    variant?: Variant;
-} & {
-    [Axis in keyof A]?: Extract<keyof A[Axis], string>;
-};
-type CompoundVariant<Slot extends string, Variant extends string, A extends Axes<Slot>> = {
-    when: Selection<Variant, A>;
-    style: StyleFn<Slot>;
-};
-type RecipeConfig<Slot extends string, Variant extends string, A extends Axes<Slot>> = {
-    /** Every slot the component publishes. Slots a recipe never styles resolve to `{}`. */
-    slots: readonly Slot[];
-    base?: StyleFn<Slot>;
-    variantTokens?: Record<Variant, VariantTokens>;
-    /** Where the variant's colours land — written once, and it holds for every variant. */
-    paint?: StyleFn<Slot>;
-    variants?: A;
-    compoundVariants?: ReadonlyArray<CompoundVariant<Slot, Variant, A>>;
-    states?: Partial<Record<StateName, StyleFn<Slot>>>;
-    defaultVariants?: Selection<Variant, A>;
-};
-/** Stable references: the same object for the same tokens, for the app's lifetime. */
-type ResolvedStyles<Slot extends string> = Readonly<Record<Slot, SlotStyle>>;
-/** A selection with `defaultVariants` already folded in, keyed by axis name. */
-type ResolvedSelection = Readonly<Record<string, string | undefined>>;
-
-type ResolveArgs<Variant extends string, A extends Axes<string>> = {
-    theme: XAUITheme;
-    selection?: Selection<Variant, A>;
-    states?: States;
+ * The runtime half of R14. The type half lives in `system/style-props/`, and the two are
+ * pinned to each other by a compile-time check there: a React Native upgrade that adds or
+ * removes a style key fails `type-check` with the key's name rather than drifting.
+ *
+ * One set for the three style types rather than one per node. A caller cannot write
+ * `fontSize` on a view slot — that slot's props are typed `ViewStyleProps` — so the split
+ * never has to know which node it runs for, and every component shares one table.
+ */
+declare const STYLE_PROP_KEYS: readonly ["alignContent", "alignItems", "alignSelf", "aspectRatio", "boxSizing", "columnGap", "direction", "display", "flex", "flexBasis", "flexDirection", "flexGrow", "flexShrink", "flexWrap", "gap", "justifyContent", "overflow", "rowGap", "bottom", "end", "inset", "insetBlock", "insetBlockEnd", "insetBlockStart", "insetInline", "insetInlineEnd", "insetInlineStart", "position", "start", "top", "zIndex", "margin", "marginBlock", "marginBlockEnd", "marginBlockStart", "marginBottom", "marginEnd", "marginHorizontal", "marginInline", "marginInlineEnd", "marginInlineStart", "marginStart", "marginTop", "marginVertical", "padding", "paddingBlock", "paddingBlockEnd", "paddingBlockStart", "paddingBottom", "paddingEnd", "paddingHorizontal", "paddingInline", "paddingInlineEnd", "paddingInlineStart", "paddingStart", "paddingTop", "paddingVertical", "height", "maxHeight", "maxWidth", "minHeight", "minWidth", "width", "borderBlockColor", "borderBlockEndColor", "borderBlockStartColor", "borderBottomColor", "borderBottomEndRadius", "borderBottomStartRadius", "borderBottomWidth", "borderColor", "borderCurve", "borderEndColor", "borderEndEndRadius", "borderEndStartRadius", "borderEndWidth", "borderRadius", "borderStartColor", "borderStartEndRadius", "borderStartStartRadius", "borderStartWidth", "borderStyle", "borderTopColor", "borderTopEndRadius", "borderTopStartRadius", "borderTopWidth", "borderWidth", "backfaceVisibility", "backgroundColor", "boxShadow", "cursor", "elevation", "experimental_backgroundImage", "filter", "isolation", "mixBlendMode", "opacity", "outlineColor", "outlineOffset", "outlineStyle", "outlineWidth", "shadowColor", "shadowOffset", "shadowOpacity", "shadowRadius", "rotation", "scaleX", "scaleY", "transform", "transformMatrix", "transformOrigin", "translateX", "translateY", "color", "fontFamily", "fontSize", "fontStyle", "fontVariant", "fontWeight", "includeFontPadding", "letterSpacing", "lineHeight", "textAlign", "textAlignVertical", "textDecorationColor", "textDecorationLine", "textDecorationStyle", "textShadowColor", "textShadowOffset", "textShadowRadius", "textTransform", "userSelect", "verticalAlign", "writingDirection", "objectFit", "overlayColor", "resizeMode", "tintColor"];
+type StylePropKey = (typeof STYLE_PROP_KEYS)[number];
+/** What `splitStyleProps` takes out of a props object. */
+type StylePropsOf<P> = Pick<P, Extract<keyof P, StylePropKey>>;
+/** What it leaves in it. */
+type RestPropsOf<P> = Omit<P, StylePropKey>;
+
+/**
+ * `splitStyleProps`, memoized on the values (R14). A component calls it on what is left
+ * after destructuring its own props, applies the style half between the tint and its
+ * `style`, and forwards the rest:
+ *
+ * ```tsx
+ * const [styleProps, rest] = useStyleProps(props)
+ * <Pressable style={[styles.root, tint, styleProps, style]} {...rest} />
+ * ```
+ *
+ * The identity is stable while the values are, which is what a memoized child or an
+ * animated style depends on. It is keyed on a hash rather than on the object, because the
+ * object is a fresh rest-spread on every render and would never hit.
+ */
+declare function useStyleProps<P extends object>(props: P): [StylePropsOf<P>, RestPropsOf<P>];
+
+/**
+ * The gap nobody else closes: an icon is a third-party component, so a slot context does
+ * not reach it and every call site ends up computing the colour by hand.
+ *
+ * ```tsx
+ * <Button variant="danger">
+ *   <Button.Icon as={TrashIcon} />   {/* colour and size inherited, nothing to pass *\/}
+ *   <Button.Label>Supprimer</Button.Label>
+ * </Button>
+ * ```
+ *
+ * Three accepted forms — a component through `as`, a raw SVG as children, or an image
+ * through `source` — and the resolution is the same for all three: an explicit prop, else
+ * what the surrounding slot published, else the theme.
+ *
+ * The props are taken whole rather than destructured, because they are a union: which
+ * keys exist depends on the form, and narrowing is what lets `style` be reachable in the
+ * one branch that renders a node and unwritable in the two that do not.
+ */
+declare function Icon(props: IconProps): react.JSX.Element;
+declare namespace Icon {
+    var displayName: string;
+}
+
+/**
+ * Not a `createSlotContext`: that one throws outside its parent, and an `Icon` has to
+ * work on its own as much as inside a `Button`. An empty context is the honest default —
+ * nothing inherited, so the theme decides.
+ */
+declare const IconContext: react.Context<IconContextValue>;
+declare function useIconContext(): IconContextValue;
+
+type PortalProps = {
+    children: ReactNode;
 };
-type TintArgs<Variant extends string, A extends Axes<string>> = ResolveArgs<Variant, A> & {
-    color: string;
+/**
+ * Renders its children into the nearest `PortalHost` instead of where it sits. What
+ * `Dialog`, `Sheet`, `Drawer` and `Snackbar` are built on: an overlay has to escape the
+ * clipping and stacking of whatever container happened to hold the trigger.
+ *
+ * Both halves run in layout effects rather than effects, which is deliberate: the content
+ * lands in the same commit as the trigger's, so an overlay neither shows one frame late
+ * nor survives one frame past the unmount that closed it. The unpublish sits in its own
+ * effect so that it does not depend on `children` — a re-publish then keeps the portal's
+ * place in the host's order instead of dropping it and re-adding it at the end.
+ */
+declare function Portal({ children }: PortalProps): null;
+declare namespace Portal {
+    var displayName: string;
+}
+
+type PortalMethods = {
+    addPortal: (key: string, element: ReactNode) => void;
+    removePortal: (key: string) => void;
 };
-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>;
+/**
+ * `null` outside a host, and `Portal` treats that as "render nothing" rather than
+ * throwing: an app that forgot `PortalHost` should lose its overlays, not crash on the
+ * first `Dialog`.
+ */
+declare const PortalContext: react.Context<PortalMethods | null>;
+
+/** R14 — it renders a view of its own, so it takes that view's style keys as props. */
+type PortalHostProps = ViewStyleProps & {
+    children: ReactNode;
 };
 /**
- * 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]} />
+ * Where every `Portal` in the tree below renders. Mounted once, at the root of the app,
+ * above navigation — an overlay that renders inside a screen is clipped by it.
  */
-declare function createRecipe<Slot extends string, Variant extends string, const A extends Axes<Slot>>(config: RecipeConfig<Slot, Variant, A>): Recipe<Slot, Variant, A>;
+declare function PortalHost({ children, ...props }: PortalHostProps): react.JSX.Element;
+declare namespace PortalHost {
+    var displayName: string;
+}
 
 /**
  * R3: the string a root should wrap in its default text slot, or `null` when it should
@@ -171,4 +208,193 @@ type SlotProps = MergeableProps & {
  */
 declare const Slot: react.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & react.RefAttributes<unknown>>;
 
-export { type AsChildProps, type Axes, type CompoundVariant, type MergeableProps, type PossibleRef, type Recipe, type RecipeConfig, type ResolveArgs, type ResolvedSelection, type ResolvedStyles, type Selection, Slot, type SlotProps, type SlotStyle, type SlotStyles, type StateName, type States, type StyleFn, type TintArgs, type VariantColors, type VariantRole, type VariantTokens, childrenToString, createRecipe, createSlotContext, mergeProps, mergeRefs };
+type PressableFeedbackHighlightProps = ViewStyleProps & {
+    style?: StyleProp<ViewStyle>;
+    animation?: SlotAnimation;
+    /**
+     * The content the wash sits under. Optional: `<Highlight />` on its own is an overlay
+     * among the root's other children, and the root hoists it so order does not matter.
+     */
+    children?: ReactNode;
+};
+/**
+ * The press wash: one flat overlay fading in under the finger.
+ *
+ * It is a **neutral** wash, not the variant's pressed colour. A component picks one or
+ * the other — this overlay, or a `pressed` state in its recipe swapping `bg` for
+ * `bgPressed` — never both, or a pressed button darkens twice.
+ *
+ * **Wrapping is the readable form**, and it costs nothing:
+ *
+ * ```tsx
+ * <PressableFeedback style={{ flexDirection: 'row', gap: 8 }}>
+ *   <PressableFeedback.Highlight>
+ *     <Icon />
+ *     <Label />
+ *   </PressableFeedback.Highlight>
+ * </PressableFeedback>
+ * ```
+ *
+ * The children are **not** put inside a box. They are returned as siblings of the wash in
+ * a fragment, which has no presence in the host tree — so the root's `flexDirection`,
+ * `gap` and `alignItems` still reach the icon and the label directly, and the rendered
+ * tree is identical to writing the wash as a bare sibling. A real wrapping `View` would
+ * have made the root's layout apply to the wrapper instead, and would have added the depth
+ * §8 removed.
+ */
+declare function PressableFeedbackHighlight({ style, animation: override, children, ...props }: PressableFeedbackHighlightProps): react.JSX.Element;
+declare namespace PressableFeedbackHighlight {
+    var displayName: string;
+}
+
+type PressableFeedbackRippleProps = ViewStyleProps & {
+    /** Applies to the wave itself, not to the container that clips it. */
+    style?: StyleProp<ViewStyle>;
+    animation?: SlotAnimation;
+    /**
+     * The content the wave washes under. Optional: `<Ripple />` on its own is an overlay
+     * among the root's other children, and the root hoists it so order does not matter.
+     */
+    children?: ReactNode;
+};
+/**
+ * A circle washing outwards from where the finger landed.
+ *
+ * **The root drives it, this only draws it.** The root is the touch surface: touches on a
+ * component's own children — a button's label — bubble up to the `Pressable`, and never to
+ * this overlay, which is their sibling rather than their parent. An overlay owning the
+ * handlers works on the padding and does nothing on the text, which is the kind of bug that
+ * looks like a rendering problem.
+ *
+ * Its ink and its corners come from the root, which reads both off its own style — only
+ * the root knows what the wave sits on, or what shape it has to stay inside.
+ *
+ * **Wrapping is the readable form**, and it costs nothing:
+ *
+ * ```tsx
+ * <PressableFeedback style={{ flexDirection: 'row', gap: 8 }}>
+ *   <PressableFeedback.Ripple>
+ *     <Icon />
+ *     <Label />
+ *   </PressableFeedback.Ripple>
+ * </PressableFeedback>
+ * ```
+ *
+ * The children are **not** put inside a box. They come back as siblings of the wave's
+ * container in a fragment, which has no presence in the host tree — so the root's
+ * `flexDirection`, `gap` and `alignItems` still reach the icon and the label directly, and
+ * the rendered tree is identical to writing the wave as a bare sibling. Written on its own,
+ * `<Ripple />` is that bare sibling, and the root hoists it so order does not matter.
+ *
+ * The motion is Material's `InkRipple`, and the parts that matter are the ones that are not
+ * obvious: the ink is **independent of the expansion**, the circle **starts at 30%** of its
+ * target rather than at a point, the target is **half the diagonal**, and the centre
+ * **travels** from the finger to the middle of the control. The constants carry the why.
+ */
+declare function PressableFeedbackRipple({ style, animation: override, children, ...props }: PressableFeedbackRippleProps): react.JSX.Element;
+declare namespace PressableFeedbackRipple {
+    var displayName: string;
+}
+
+declare const useFeedback: () => FeedbackContext;
+
+/**
+ * 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.
+ */
+declare const FEEDBACK_OVERLAY: unique symbol;
+/** Tags a component so `PressableFeedback` paints it under its content. */
+declare function markOverlay<T extends object>(component: T): T;
+
+/**
+ * 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.
+ */
+declare const PRESS_SCALE = 0.985;
+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.
+ */
+declare const SCALE_REFERENCE_WIDTH = 300;
+/** The scale a control of `width` should reach when pressed. */
+declare function pressScaleFor(width: number): number;
+/** How far the wash goes at full press, and how long it takes to get there. */
+declare const HIGHLIGHT_OPACITY = 0.1;
+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.
+ */
+declare const RIPPLE_OPACITY = 0.1;
+declare const RIPPLE_START_SCALE = 0.3;
+declare const RIPPLE_EXPAND_DURATION = 1000;
+declare const RIPPLE_CONFIRM_DURATION = 225;
+declare const RIPPLE_FADE_IN = 75;
+declare const RIPPLE_FADE_OUT_DELAY = 225;
+declare const RIPPLE_FADE_OUT = 150;
+/** Half the diagonal covers the box from its centre; the 5 is Material's own overshoot. */
+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.
+ */
+declare function resolveAnimation(animation: AnimationProp | undefined, inheritedDisableAll?: boolean): ResolvedAnimation;
+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.
+ */
+declare function resolveSlotAnimation(override: SlotAnimation | undefined, enabledByRoot: boolean, defaultOpacity: number, defaultDuration?: number): ResolvedSlotAnimation;
+
+/**
+ * The root scales; what else happens under the finger is **composed**, not named by a
+ * prop. An overlay a caller can reach is an overlay a caller can place, style and switch
+ * off — and it is the only shape that survives `asChild`, where the caller's own element
+ * is the pressable and there is no sibling for the primitive to inject.
+ */
+declare const PressableFeedback: react.ForwardRefExoticComponent<Omit<react_native.PressableProps, "style" | "children" | "disabled"> & ViewStyleProps & {
+    isPressed?: boolean;
+    isDisabled?: boolean;
+    asChild?: boolean;
+    animation?: AnimationProp;
+    style?: react_native.StyleProp<react_native.ViewStyle>;
+    children?: react.ReactNode;
+} & react.RefAttributes<react_native.View>> & {
+    Highlight: typeof PressableFeedbackHighlight;
+    Ripple: typeof PressableFeedbackRipple;
+};
+
+export { AnimationProp, type AsChildProps, FEEDBACK_OVERLAY, FeedbackContext, HIGHLIGHT_DURATION, HIGHLIGHT_OPACITY, Icon, IconContext, IconContextValue, IconProps, type MergeableProps, PRESS_DURATION, PRESS_SCALE, Portal, PortalContext, PortalHost, type PortalHostProps, type PortalMethods, type PortalProps, type PossibleRef, PressableFeedback, type PressableFeedbackHighlightProps, type PressableFeedbackRippleProps, RIPPLE_CONFIRM_DURATION, RIPPLE_EXPAND_DURATION, RIPPLE_FADE_IN, RIPPLE_FADE_OUT, RIPPLE_FADE_OUT_DELAY, RIPPLE_OPACITY, RIPPLE_START_SCALE, ResolvedAnimation, SCALE_REFERENCE_WIDTH, Slot, SlotAnimation, type SlotProps, ViewStyleProps, childrenToString, createSlotContext, markOverlay, mergeProps, mergeRefs, pressScaleFor, resolveAnimation, resolveSlotAnimation, rippleRadiusFor, useFeedback, useIconContext, useStyleProps };