@pieai/swimmer-ui-kit 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.10.0
+
+### Added
+
+- **`motion="follow"` for selection and progress.** `<LiquidGroup>` now carries
+  the donor's Move surface through the token layer and shared animation and
+  filter-area budgets. It is used only by `GameSegmentedControl`'s selected
+  indicator and `GameProgress`'s leading edge; the shared clock sleeps
+  completely at rest.
+- **Optional static waviness on `<LiquidGroup>`.** The new group-level
+  `waviness` and `wavinessFreq` knobs adapt the pinned liquid-gooey noise
+  displacement so merged silhouettes read as fluid instead of as two rounded
+  rectangles. The displaced `shape` feeds both SVG shadow passes and the final
+  SVG raster shadow, so the shadow follows the same edge. The token default is
+  `0` to preserve existing output; the recommended brand preset is `6px` at
+  `0.018`, with `3px`/`0.022` and `10px`/`0.014` available as conservative and
+  bold points on the same intensity axis. The noise is fixed-seed and static,
+  so it adds no idle animation clock. Its maximum displacement is reserved in
+  the filter region and counted by the 480,000 px² budget.
+
+### Fixed
+
+- **`<LiquidGroup>` drew nothing under React StrictMode.** The effect cleanup
+  marked the memoized engine disposed for good, so StrictMode's second mount
+  acquired its budget, reported an active group, and then returned early from
+  `wake()`. The merged path's `d` stayed empty, which meant every app rendering
+  under StrictMode — that is, every app we ship — got no Morph and no Move at
+  all, with nothing in the console to say so. `register()` now revives a
+  disposed engine and resets the observer and listener state with it, a
+  StrictMode regression test asserts the path is not empty, and the
+  budget-exhausted path warns once in development instead of degrading in
+  silence. Storybook runs with StrictMode on.
+
+## 1.9.0
+
+### Added
+
+- **`<LiquidGroup>`, a budgeted liquid-merge primitive.** Two or more nearby
+  children share one gooey silhouette while their own content stays crisp: an
+  SVG blur-plus-contrast filter builds the merged shape, and the content is
+  drawn unfiltered on top. It is a one-shot primitive for celebrations, merge
+  moments and transitions — not a resident background, not behind body text,
+  and not on navigation. `blur`, `contrast` and `filterPadding` are the shape
+  knobs; `motion="reduced"` snaps instead of springing.
+- **`stroke` on `<LiquidGroup>`.** The border belongs to the merged silhouette,
+  not to the pieces. Passing a CSS border shorthand draws one continuous
+  outline that deforms with the merge, including across the liquid bridge. A
+  child that draws its own `border` will show a static circle that refuses to
+  merge — that is the bug this prop exists to remove, and the story documents
+  it as a rule rather than a preference.
+
+### Fixed
+
+- **The `LiquidGroup` stories now demonstrate the supported composition.** The
+  demo buttons reset their browser border and background so they do not paint
+  hard-edged content-layer circles over the merged silhouette. The stories now
+  show the continuous outline on `LiquidGroup`, with a dedicated
+  `stroke` + `shadow` example that makes the group-owned treatment explicit.
+
 ## 1.8.1
 
 ### Fixed

package/NOTICE

@@ -32,6 +32,61 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+Liquid-gooey morph filter
+-------------------------
+The liquid morph primitive in `src/LiquidGroup.tsx` and its supporting filter,
+geometry, shadow, and spring modules is an original SwimmerUIKit
+implementation informed by the `liquid-gooey` package in the Libraries
+repository (https://github.com/Jakubantalik/Libraries/tree/main/packages/liquid-gooey),
+Copyright (c) 2026 Jakub Antalik, licensed under the MIT License.
+
+The reviewed upstream state is pinned in `donors-individual-lock.json` at commit
+`3862ffa345217443b63696a8c331a0664eea4b04`; the package source lives at
+`packages/liquid-gooey/` in that repository. The combined-workspace review
+checkout is `<portfolio-root>/_donors-individual/for_SwimmerUIKit/` and is not
+packaged or loaded at runtime.
+
+We took the donor's morph-specific ideas and small implementation patterns:
+the SVG silhouette/content split, the Gaussian-blur plus alpha color-matrix
+filter, rounded-rectangle geometry, token-compatible shadow passes, and spring
+to easing compilation. We also adapted its Move center spring, velocity-axis
+stretch, and lagging tail/mid-droplet physics for the selected segmented
+indicator and progress leading edge. This package now directly adapts the
+donor's group-level `waviness` / `wavinessFreq` filter pass: a fixed-seed
+`feTurbulence` field and `feDisplacementMap` move the silhouette before its
+shadow passes consume it, so the shadow follows the same edge. We did not take
+the donor's melt, bend, or dissolve systems, its general observer, or its
+image-melt engine. We changed the implementation for this kit by making fill
+and shadow values token-driven, keeping waviness static with a shipped-off
+token default, adding a process-wide animated-group and filter-area budget
+that includes the displacement slack, and putting the shared
+requestAnimationFrame clock to sleep after stillness. The actual interactive
+content remains outside the filtered SVG layer.
+
+The MIT License text for that material:
+
+MIT License
+
+Copyright (c) 2026 Jakub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 Fonts
 -----
 Baloo 2 and Geist Variable are licensed under the SIL Open Font License.

package/dist/index.d.ts

@@ -268,6 +268,45 @@ export declare const CLAY_LAYER_TOKENS: {
     readonly toast: "var(--game-ui-z-toast)";
 };
 
+/**
+ * Token references for the adopted liquid-gooey Move physics. The values are
+ * deliberately numeric custom properties so a host theme can tune the feel
+ * without putting physics constants in the engine.
+ */
+declare const CLAY_LIQUID_GOOEY_TOKENS: {
+    readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+    readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+    readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+    readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+    readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+    readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+    readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+    readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+    readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+    readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+    readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+    readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+    readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+    readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+    readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+    readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+    readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+    readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+    readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+    readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+    readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+    readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+    readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+    readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+    readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+    readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+    readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+    readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+    readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
+};
+export { CLAY_LIQUID_GOOEY_TOKENS }
+export { CLAY_LIQUID_GOOEY_TOKENS as GAME_UI_LIQUID_GOOEY_TOKENS }
+
 /**
  * Effect knobs for `<LiquidMetalButton>`. Face/ink are real colours (both
  * themes must set them); accent aliases `--game-ui-accent` so a host can
@@ -552,6 +591,37 @@ export declare const CLAY_UI_TOKENS: {
         readonly rest: "var(--game-ui-liquid-metal-rest)";
         readonly bloom: "var(--game-ui-liquid-metal-bloom)";
     };
+    readonly liquidGooey: {
+        readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+        readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+        readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+        readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+        readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+        readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+        readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+        readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+        readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+        readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+        readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+        readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+        readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+        readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+        readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+        readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+        readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+        readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+        readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+        readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+        readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+        readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+        readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+        readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+        readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+        readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+        readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+        readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+        readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
+    };
 };
 
 export declare type ClayAssetGroup = keyof typeof CLAY_ASSETS;
@@ -589,6 +659,20 @@ export declare type ClayIconStyle = 'game' | 'line';
 
 export declare type ClayTokenCategory = keyof typeof CLAY_UI_TOKENS;
 
+declare type CornerRadii = [number, number, number, number];
+
+/**
+ * Process-wide budget for animated liquid-gooey groups.
+ *
+ * SVG filters do not consume WebGL contexts, but they can still be expensive
+ * to repaint. The default allows two animated groups and rejects regions
+ * larger than the configured filter-area ceiling. A rejected group keeps its
+ * SVG filter and snaps its content to each new state without animating.
+ */
+export declare const DEFAULT_LIQUID_GOOEY_ANIMATION_BUDGET = 2;
+
+export declare const DEFAULT_LIQUID_GOOEY_FILTER_AREA_BUDGET = 480000;
+
 /**
  * Process-wide ledger for liquid-metal WebGL2 contexts.
  *
@@ -708,6 +792,35 @@ export declare const GAME_UI_TARGETS: {
 export declare const GAME_UI_THEME_CONTRACT: readonly ["--game-ui-bg", "--game-ui-surface", "--game-ui-surface-raised", "--game-ui-panel", "--game-ui-panel-strong", "--game-ui-panel-deep", "--game-ui-text", "--game-ui-text-muted", "--game-ui-accent", "--game-ui-accent-bright", "--game-ui-secondary", "--game-ui-success", "--game-ui-success-bright", "--game-ui-danger", "--game-ui-danger-bright", "--game-ui-warning", "--game-ui-focus-ring", "--game-ui-border-subtle", "--game-ui-border-strong", "--game-ui-disabled", "--game-ui-ink-deep", "--game-ui-border-ink", "--game-ui-wood", "--game-ui-ink-title", "--game-ui-ink-heading", "--game-ui-liquid-metal-face", "--game-ui-liquid-metal-ink"];
 
 export declare const GAME_UI_TOKENS: {
+    readonly moveStiffness: "var(--game-ui-liquid-gooey-move-stiffness)";
+    readonly moveDamping: "var(--game-ui-liquid-gooey-move-damping)";
+    readonly moveStretch: "var(--game-ui-liquid-gooey-move-stretch)";
+    readonly moveTail: "var(--game-ui-liquid-gooey-move-tail)";
+    readonly moveForce: "var(--game-ui-liquid-gooey-move-force)";
+    readonly moveTailSpringStiffness: "var(--game-ui-liquid-gooey-move-tail-spring-stiffness)";
+    readonly moveTailSpringDamping: "var(--game-ui-liquid-gooey-move-tail-spring-damping)";
+    readonly moveStretchSpeed: "var(--game-ui-liquid-gooey-move-stretch-speed)";
+    readonly moveStretchSquash: "var(--game-ui-liquid-gooey-move-stretch-squash)";
+    readonly moveSpeedThreshold: "var(--game-ui-liquid-gooey-move-speed-threshold)";
+    readonly moveTailOnsetSpeed: "var(--game-ui-liquid-gooey-move-tail-onset-speed)";
+    readonly moveTailOnsetRange: "var(--game-ui-liquid-gooey-move-tail-onset-range)";
+    readonly moveTailRamp: "var(--game-ui-liquid-gooey-move-tail-ramp)";
+    readonly moveTailMinRadius: "var(--game-ui-liquid-gooey-move-tail-min-radius)";
+    readonly moveTailWobble: "var(--game-ui-liquid-gooey-move-tail-wobble)";
+    readonly moveTailPhaseSpeed: "var(--game-ui-liquid-gooey-move-tail-phase-speed)";
+    readonly moveTailMidpointA: "var(--game-ui-liquid-gooey-move-tail-midpoint-a)";
+    readonly moveTailMidpointB: "var(--game-ui-liquid-gooey-move-tail-midpoint-b)";
+    readonly moveTailMidRadiusA: "var(--game-ui-liquid-gooey-move-tail-mid-radius-a)";
+    readonly moveTailMidRadiusB: "var(--game-ui-liquid-gooey-move-tail-mid-radius-b)";
+    readonly moveTailWobblePhase: "var(--game-ui-liquid-gooey-move-tail-wobble-phase)";
+    readonly moveMinPerpendicular: "var(--game-ui-liquid-gooey-move-min-perpendicular)";
+    readonly moveLagBase: "var(--game-ui-liquid-gooey-move-lag-base)";
+    readonly moveLagForce: "var(--game-ui-liquid-gooey-move-lag-force)";
+    readonly moveSettleDistance: "var(--game-ui-liquid-gooey-move-settle-distance)";
+    readonly moveSettleSpeed: "var(--game-ui-liquid-gooey-move-settle-speed)";
+    readonly moveIntegrationRate: "var(--game-ui-liquid-gooey-move-integration-rate)";
+    readonly waviness: "var(--game-ui-liquid-gooey-waviness)";
+    readonly wavinessFreq: "var(--game-ui-liquid-gooey-waviness-freq)";
     readonly iconSm: "var(--game-ui-asset-icon-sm)";
     readonly iconMd: "var(--game-ui-asset-icon-md)";
     readonly iconLg: "var(--game-ui-asset-icon-lg)";
@@ -1924,11 +2037,101 @@ export declare function getClayIconStyles(icon: ClayIconName): ClayIconStyle[];
 
 export declare function getClaySourceAssetPath(icon: ClayIconName, style?: ClayIconStyle): string;
 
+export declare function getLiquidGooeyBudget(): LiquidGooeyBudgetState;
+
 export declare function getLiquidMetalContextBudget(): {
     limit: number;
     used: number;
 };
 
+declare interface LiquidGooeyBudgetOptions {
+    maxAnimatedGroups?: number;
+    maxFilterArea?: number;
+}
+
+declare interface LiquidGooeyBudgetState {
+    maxAnimatedGroups: number;
+    maxFilterArea: number;
+    activeGroups: number;
+}
+
+/**
+ * Merges nearby item silhouettes into one shape while leaving their content
+ * accessible and unfiltered. Do NOT add border, outline, or box-shadow to
+ * children directly; pass the shared treatment to <LiquidGroup>.
+ */
+export declare const LiquidGroup: ForwardRefExoticComponent<LiquidGroupProps & RefAttributes<HTMLDivElement>> & {
+    Item: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
+};
+
+/**
+ * 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 |
+ * | **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.
+ */
+export 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;
+    /** Surface fill. Defaults to the kit's theme surface token. */
+    fill?: string;
+    /** 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 (0). */
+    waviness?: number;
+    /** Noise frequency of the undulation; lower values make longer waves. */
+    wavinessFreq?: number;
+    /**
+     * `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';
+}
+
+export declare const LiquidItem: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
+
+export 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;
+    /** 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;
+}
+
 export declare function LiquidMetalButton({ children, className, onClick, sound, type, renderer, ...props }: LiquidMetalButtonProps): ReactNode;
 
 export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -1970,6 +2173,23 @@ export declare function setClayAssetBasePath(basePath: string): void;
  */
 export declare function setClayAssetMode(mode: ClayAssetMode): void;
 
+/** Update one or both host-side performance limits. */
+export declare function setLiquidGooeyBudget(next: number | LiquidGooeyBudgetOptions): void;
+
 export declare function setLiquidMetalContextBudget(nextLimit: number): void;
 
+/** 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';
+
 export { }