@pieai/swimmer-ui-kit 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 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.
+
 ## 1.8.1
 
 ### Fixed

package/NOTICE

@@ -32,6 +32,48 @@ 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.
+
+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 did not take its move, 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,
+adding a process-wide animated-group and filter-area budget, 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

@@ -589,6 +589,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.
  *
@@ -1924,11 +1938,62 @@ 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;
+}
+
+export declare const LiquidGroup: ForwardRefExoticComponent<LiquidGroupProps & RefAttributes<HTMLDivElement>> & {
+    Item: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
+};
+
+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;
+    /** Deterministic reduced-motion override for previews; auto follows the OS. */
+    motion?: 'auto' | 'reduced';
+}
+
+export declare const LiquidItem: ForwardRefExoticComponent<LiquidItemProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface LiquidItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    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 +2035,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 { }