@pieai/swimmer-ui-kit 2.14.0 → 3.0.0-rc.1

package/dist/liquid-effects.d.ts

@@ -0,0 +1,350 @@
+import { ForwardRefExoticComponent } from 'react';
+import { HTMLAttributes } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+
+export declare interface BendTuning {
+    /** Vertical bow strength, 0..1. */
+    vertical?: number;
+    /** Horizontal cap deformation, 0..1. */
+    horizontal?: number;
+}
+
+declare interface BlobShape {
+    /** Outward bulge, in px. 0 gives the plain rounded rectangle. */
+    readonly amplitude: number;
+    /** Which shape. Same seed, same silhouette, every render. */
+    readonly seed?: number;
+    /** How many swells go round the outline. 2 is lazy, 5 is busy. */
+    readonly lobes?: number;
+    /** Rotates the swells around the outline; the knob a press animates. */
+    readonly phase?: number;
+}
+
+declare type CornerRadii = [number, number, number, number];
+
+export declare interface DissolveOptions {
+    /** Melt blur in px. */
+    blur?: number;
+    /** Displacement strength of the liquid warp. */
+    warp?: number;
+    /** Magnetic drift toward the contact, in px. */
+    pull?: number;
+    /** Distance at which melting starts. */
+    range?: number;
+    /** Size of the melt zone around the contact, in px. */
+    zone?: number;
+    /** 0..1 two-liquid erosion strength. */
+    mix?: number;
+    /** Px the melt is drawn toward the neighbour's centre. */
+    gravity?: number;
+    /** 0..1 pointiness of the directional flow. */
+    taper?: number;
+    /** Noise frequency multiplier. */
+    warpFreq?: number;
+    /** Px/s the noise field may drift while the item is moving. */
+    flowSpeed?: number;
+    /** Noise style. */
+    warpStyle?: 'fractalNoise' | 'turbulence';
+    /** Noise octaves. */
+    detail?: number;
+    /** Whether the dissolve is currently allowed to grow. */
+    active?: boolean;
+    /** Structural release time in ms. */
+    releaseMs?: number;
+    /** Opacity fade time in ms. */
+    fadeMs?: number;
+    /** 0..1 overall dissolve ceiling. */
+    strength?: number;
+    /** Fraction of the smaller body at which the seam has been swallowed. */
+    sink?: number;
+    /** Plain blur radius for the guaranteed-smooth seam wash. */
+    seamBlur?: number;
+}
+
+declare interface EvolveOptions {
+    /** Spring driving the liquid mass's centre. */
+    massStiffness?: number;
+    massDamping?: number;
+    /** Spring driving width and height. */
+    sizeStiffness?: number;
+    sizeDamping?: number;
+    /** Spring driving the corner radius. */
+    radiusStiffness?: number;
+    radiusDamping?: number;
+    /** Maximum content cross-blur during the morph, in px. */
+    contentBlur?: number;
+    /** 0..1 droplet roundness during a shape transition. */
+    roundness?: number;
+    /** Corner-forming timeline. */
+    cornerDuration?: number;
+    cornerDelay?: number;
+    cornerEase?: string;
+    /** Ramp-in time for the droplet lead, in ms. */
+    anticipation?: number;
+    /** Maximum droplet lead toward the destination, in px. */
+    travel?: number;
+}
+
+export declare interface ImageMeltOptions {
+    /** Goo sigma: how far the bodies reach for each other and how wide colour averaging runs. */
+    blur?: number;
+    /** Alpha-contrast slope of the liquid boundary. */
+    contrast?: number;
+    /** How far each crisp face dissolves back before its neighbour. */
+    reach?: number;
+    /** Softness of the crisp-face dissolve mask. */
+    fade?: number;
+    /** Turbulence displacement of the molten layer, in px. */
+    warp?: number;
+    /** 0..1 two-liquid marbling strength in the touch area. */
+    mix?: number;
+    /** Blur of the marble pass's source colours. */
+    mixBlur?: number;
+    /** How deep the marble zone reaches into each card. */
+    gravity?: number;
+    /** Wavelength control of the warp noise. */
+    waviness?: number;
+}
+
+export declare const LiquidEffectsGroup: ForwardRefExoticComponent< LiquidGroupProps & RefAttributes<HTMLDivElement>> & {
+    Item: ForwardRefExoticComponent< LiquidEffectsItemProps & RefAttributes<HTMLDivElement>>;
+};
+
+export declare type LiquidEffectsGroupProps = LiquidGroupProps_2;
+
+export declare const LiquidEffectsItem: ForwardRefExoticComponent<LiquidEffectsItemProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface LiquidEffectsItemProps extends Omit<LiquidItemProps, 'effect'> {
+    effect?: 'morph' | 'melt' | 'bend';
+    bend?: BendTuning;
+    melt?: ImageMeltOptions & {
+        src?: string;
+    };
+    dissolve?: boolean | number | DissolveOptions;
+}
+
+/**
+ * A shared liquid silhouette behind crisp item content.
+ *
+ * Put the visual treatment on the group: `fill`, `stroke`, and `shadow` are
+ * rebuilt on the merged silhouette. Do NOT add border, outline, or box-shadow
+ * to children directly; those styles live on the content layer and cannot
+ * merge with the liquid shape.
+ *
+ * Its motion vocabulary is intentionally small and semantic:
+ *
+ * | gesture | meaning |
+ * | --- | --- |
+ * | **merge** (Morph) | two things become one: reward settling, collecting, confirming |
+ * | **follow** (Move) | selection, progress, dragging |
+ * | **shape** (Morph shape) | the liquid changes size and corners like jelly |
+ * | **bend** | speed bows the surface while content stays glued to it |
+ * | **dissolve** | replacement, transition |
+ * | **still** | THE DEFAULT |
+ *
+ * Liquid appears only on a state change the user caused. There is no ambient,
+ * idle, or decorative liquid; keep the filter-area budget visible when more
+ * than one group is on a screen.
+ */
+/**
+ * A liquid body's paint.
+ *
+ * A colour paints the body flat. `{ top, bottom }` is the light the coloured
+ * liquid theme settled on (University, 2026-09-30): a narrow brighter band at
+ * the top, the colour falling from `top` to `bottom`, and the foot a touch
+ * deeper, so a body reads as having thickness without a white rim. `sheen` is
+ * how far the top band leans to white (0–1, default 0.3). Colours may be tokens:
+ * the bands are mixed with CSS `color-mix`, not computed here.
+ */
+declare type LiquidFill = string | {
+    readonly top: string;
+    readonly bottom?: string;
+    readonly sheen?: number;
+};
+
+/**
+ * A shared liquid silhouette behind crisp item content.
+ *
+ * Put the visual treatment on the group: `fill`, `stroke`, and `shadow` are
+ * rebuilt on the merged silhouette. Do NOT add border, outline, or box-shadow
+ * to children directly; those styles live on the content layer and cannot
+ * merge with the liquid shape.
+ *
+ * Its motion vocabulary is intentionally small and semantic:
+ *
+ * | gesture | meaning |
+ * | --- | --- |
+ * | **merge** (Morph) | two things become one: reward settling, collecting, confirming |
+ * | **follow** (Move) | selection, progress, dragging |
+ * | **shape** (Morph shape) | the liquid changes size and corners like jelly |
+ * | **bend** | speed bows the surface while content stays glued to it |
+ * | **dissolve** | replacement, transition |
+ * | **still** | THE DEFAULT |
+ *
+ * Liquid appears only on a state change the user caused. There is no ambient,
+ * idle, or decorative liquid; keep the filter-area budget visible when more
+ * than one group is on a screen.
+ */
+/**
+ * A liquid body's paint.
+ *
+ * A colour paints the body flat. `{ top, bottom }` is the light the coloured
+ * liquid theme settled on (University, 2026-09-30): a narrow brighter band at
+ * the top, the colour falling from `top` to `bottom`, and the foot a touch
+ * deeper, so a body reads as having thickness without a white rim. `sheen` is
+ * how far the top band leans to white (0–1, default 0.3). Colours may be tokens:
+ * the bands are mixed with CSS `color-mix`, not computed here.
+ */
+declare type LiquidFill_2 = string | {
+    readonly top: string;
+    readonly bottom?: string;
+    readonly sheen?: number;
+};
+
+declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children: ReactNode;
+    /** Goo blur sigma in px. Larger values bridge larger gaps. */
+    blur?: number;
+    /** Alpha-contrast slope. Larger values make the liquid edge harder. */
+    contrast?: number;
+    /**
+     * Volume. 0 leaves the body a flat colour; higher values light it as a
+     * curved surface so it reads as a material rather than as a silhouette.
+     */
+    gloss?: number;
+    /**
+     * Surface fill. Defaults to the kit's theme surface token. A colour paints
+     * the body flat; `{ top, bottom }` gives it light (see `LiquidFill`).
+     */
+    fill?: LiquidFill;
+    /** Extra filter-region slack in px for the silhouette's painted edges. */
+    filterPadding?: number;
+    /** Optional token-based box-shadow syntax rebuilt on the merged silhouette. */
+    shadow?: string;
+    /** Optional stroke syntax rebuilt on the merged silhouette. Note: Do NOT add border to children directly! */
+    stroke?: string;
+    /** Max px the liquid boundary undulates. Defaults to the CSS token (6). */
+    waviness?: number;
+    /** Noise frequency of the undulation; lower values make longer waves. */
+    wavinessFreq?: number;
+    /**
+     * Max fraction of the group's shorter side allowed for waviness. Defaults
+     * to 0.3; pass `false` to explicitly disable the size clamp.
+     */
+    wavinessClamp?: number | false;
+    /**
+     * `auto` follows the existing component transition clock, `follow` adopts
+     * the Move surface for an explicit user-caused selection/progress gesture,
+     * and `reduced` snaps. Still remains the house default gesture.
+     */
+    motion?: 'auto' | 'follow' | 'reduced';
+}
+
+declare interface LiquidGroupProps_2 extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    children: ReactNode;
+    /** Goo blur sigma in px. Larger values bridge larger gaps. */
+    blur?: number;
+    /** Alpha-contrast slope. Larger values make the liquid edge harder. */
+    contrast?: number;
+    /**
+     * Volume. 0 leaves the body a flat colour; higher values light it as a
+     * curved surface so it reads as a material rather than as a silhouette.
+     */
+    gloss?: number;
+    /**
+     * Surface fill. Defaults to the kit's theme surface token. A colour paints
+     * the body flat; `{ top, bottom }` gives it light (see `LiquidFill`).
+     */
+    fill?: LiquidFill_2;
+    /** Extra filter-region slack in px for the silhouette's painted edges. */
+    filterPadding?: number;
+    /** Optional token-based box-shadow syntax rebuilt on the merged silhouette. */
+    shadow?: string;
+    /** Optional stroke syntax rebuilt on the merged silhouette. Note: Do NOT add border to children directly! */
+    stroke?: string;
+    /** Max px the liquid boundary undulates. Defaults to the CSS token (6). */
+    waviness?: number;
+    /** Noise frequency of the undulation; lower values make longer waves. */
+    wavinessFreq?: number;
+    /**
+     * Max fraction of the group's shorter side allowed for waviness. Defaults
+     * to 0.3; pass `false` to explicitly disable the size clamp.
+     */
+    wavinessClamp?: number | false;
+    /**
+     * `auto` follows the existing component transition clock, `follow` adopts
+     * the Move surface for an explicit user-caused selection/progress gesture,
+     * and `reduced` snaps. Still remains the house default gesture.
+     */
+    motion?: 'auto' | 'follow' | 'reduced';
+}
+
+declare interface LiquidItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Crisp content rendered above the merged silhouette. Do NOT add border,
+     * outline, or box-shadow to children directly; put the shared treatment on
+     * the parent <LiquidGroup> instead.
+     */
+    children: ReactNode;
+    /** Mirrored translation applied to the content wrapper and SVG silhouette. */
+    x?: number;
+    y?: number;
+    scale?: number;
+    /**
+     * Vertical scale, when it should differ from `scale`. A body that squashes
+     * wider as it gets shorter reads as jelly; one that scales uniformly reads
+     * as a thing getting smaller.
+     */
+    scaleY?: number;
+    /** Spring preset/config or an explicit duration/easing pair. */
+    transition?: Transition;
+    /** Delay before this item starts its group-clock transition, in ms. */
+    delay?: number;
+    /** Override the measured content border radius for the silhouette. */
+    radius?: number | CornerRadii;
+    /**
+     * Pour the outline outward into an organic body instead of leaving it a
+     * rounded rectangle. The bulge is outward-only, so the silhouette always
+     * contains the content's own box however bold the amplitude gets.
+     */
+    blob?: BlobShape;
+    /**
+     * Select the core Morph behavior. Optional deformation belongs to liquid-effects.
+     * Move is a group gesture (`motion="follow"`), not an item effect.
+     */
+    effect?: 'morph';
+    /** Morph shape, tempo, bounce, and content cross-blur tuning. */
+    morph?: MorphTuning;
+    /** Follow a child moved by external code. */
+    observe?: boolean;
+}
+
+declare interface MorphTuning {
+    /** Whether shape-change physics is enabled. The kit default is token-on. */
+    shape?: boolean;
+    /** Tempo multiplier. */
+    speed?: number;
+    /** 0..1 overshoot amount. */
+    bounce?: number;
+    /** Maximum content cross-blur, in px. */
+    contentBlur?: number;
+    /** Raw evolve escape hatch. */
+    advanced?: Partial<EvolveOptions>;
+}
+
+/** Small spring-to-easing compiler used by the shared group clock. */
+declare interface SpringConfig {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+}
+
+declare type Transition = TransitionPreset | SpringConfig | {
+    duration: number;
+    ease?: string;
+};
+
+declare type TransitionPreset = 'snappy' | 'smooth' | 'bouncy' | 'wobbly';
+
+export { }