@pieai/swimmer-ui-kit 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -3,6 +3,81 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.4.0 — 2026-09-11
+
+Minor: additive. One new token, six new form names, and a cast shadow that
+every liquid body was missing.
+
+### Added
+
+- **A cast shadow on the single-body forms.** `LiquidSurface` accepted a
+  `shadow` and no form set one, so every liquid button floated: the flat button
+  standing next to it carries a solid lip *and* `--game-ui-shadow-button`, and
+  the liquid one carried neither. `press`, `settle`, `drain`, and the new
+  `swell`, `reach`, `ripple` and `set` now carry two layers each — a tight,
+  barely-offset seat that says the body is touching, and a wide low cast that
+  gives it height. Compared at device ratio 1 against the flat control, a seat
+  alone glues the body to the page and a cast alone leaves it hovering.
+
+  Every layer is outer and spreadless, which is the case
+  `compositorDropShadowFilter` lifts onto the compositor: it costs no filter
+  area and it hugs the poured outline rather than a rounded rectangle. A caller
+  that wants its own ground still passes `shadow`, and `shadow="none"` removes
+  it.
+
+- **`--game-ui-shadow-liquid-ink`.** The colour a liquid body casts, per theme.
+  It is a solid colour rather than a finished shadow, so a form states strength
+  and offset without restating the room's light. Deliberately **not** added to
+  `GAME_UI_THEME_CONTRACT`: that list is exported for downstream themes to
+  self-check, and adding an entry would turn a consumer's green check red for a
+  token they have never heard of. A theme that does not define it gets the
+  light theme's warm brown ink.
+
+- **`shadowEngaged` on a form, and a shadow that answers the gesture.** A
+  pressed body is nearer the ground, so its seat hardens and its cast collapses
+  toward it; `settle` rests mid-air with no seat at all and gains one on
+  landing, which is the moment that form exists to mark. The silhouette's
+  filter transitions, so the shadow no longer arrives before the thing casting
+  it.
+
+- **Six more forms: `set`, `swell`, `reach`, `ripple`, `split`, `bead`.** Each
+  says something none of the previous six could. `set` is the only one that
+  stops being liquid — everything else is a degree of wetness — and it snaps
+  rather than tweening, because setting is a discontinuity. `swell` is
+  attention with nothing touching it, so it is the one moving form with no
+  squash. `reach` is the only form with a direction. `ripple` says 「no」 by
+  moving and leaves its shape alone. `split` is `merge` backwards with a harder
+  edge and more recoil. `bead` is the one relationship form that pours, because
+  its bodies are the message rather than the neck between them.
+
+- **`kind` on every form, and `LiquidFormKind`.** A form is one body or a
+  relationship between siblings. `LiquidSurface` can only draw the first;
+  handing it a group form used to render a correct-looking body that silently
+  never moved, and it now warns once, in every build.
+
+- **`groupEngaged` on a form.** Group knobs that change while engaged. Only
+  `set` uses it. `blob` is path data and `gloss` is a filter pass, so neither
+  tweens — they snap, which is right for one form and a flicker for any other.
+
+- **`LIQUID_BLOB_MAX_FRACTION`.** The share of a box's shorter side a poured
+  outline may swell by (0.18). Exported because it is why one `blob` value can
+  be handed to a 44px button and a 14px meter, and a number written in three
+  places drifts in two.
+
+- **A Liquid page on the showcase site, at `/liquid.html`.** Every form live and
+  triggerable, at a control size and a meter size, on any of the four tones, in
+  both themes, with its knobs — including the derived edge width in px — written
+  out beside it.
+
+### Changed
+
+- **`GameUiPreview`'s liquid section is smaller.** It keeps what a component
+  gallery is for — `surface` is a second axis on `GameButton` — and links out to
+  the Liquid page for the vocabulary. Two shelves meant two to update and, in
+  practice, one of them lagging. Hosts that render `<GameUiPreview />` and do
+  not serve `liquid.html` will have a link that does not resolve; the section
+  otherwise stands on its own.
+
 ## 2.3.0 — 2026-09-11
 
 Minor: additive, plus one token value change on the default liquid fill.

package/dist/index.d.ts

@@ -2353,10 +2353,22 @@ export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
 export declare const LIQUID_GOOEY_WAVINESS_MAX_FRACTION = 0.3;
 
 /**
- * The named looks, ordered by how much cohesion the liquid is losing:
- * `press` barely deforms, `drain` stops being a shape at all.
+ * The named looks.
+ *
+ * Bodies first, then the forms that only mean something between siblings, and
+ * within each run they are ordered by how much cohesion the liquid is losing:
+ * `set` stops being liquid at all, `press` barely deforms, `drain` stops being
+ * a shape.
+ *
+ * Six of these were the whole vocabulary until the brand needed more of it,
+ * and six is worth saying out loud as *where it got to* rather than as a
+ * complete set. A form earns its place by having something to say that none of
+ * the others says. That is the only entry requirement — and it is also why a
+ * form existing here is not permission to put it on a screen: the recorded
+ * finding is that gooey on a static solid block reads as damage, and that one
+ * screen wants one liquid element carrying one layer of intent.
  */
-export declare type LiquidForm = 'press' | 'settle' | 'merge' | 'follow' | 'fill' | 'drain';
+export declare type LiquidForm = 'set' | 'press' | 'swell' | 'settle' | 'fill' | 'reach' | 'ripple' | 'drain' | 'follow' | 'merge' | 'split' | 'bead';
 
 /** Filter-level knobs a form fixes on the group. */
 export declare interface LiquidFormGroup {
@@ -2377,6 +2389,32 @@ export declare interface LiquidFormGroup {
      */
     readonly gloss: number;
     readonly filterPadding: number;
+    /**
+     * What the body casts on the ground at rest, in CSS box-shadow syntax.
+     *
+     * Every liquid button floated before this existed: the flat button has a lip
+     * *and* `--game-ui-shadow-button`, and the liquid one had neither, which is
+     * most of why it read flatter than its own flat twin. A form is where this
+     * belongs rather than a call site, because how far a body sits off the
+     * surface is part of what the form means.
+     *
+     * Keep it to outer layers with no spread. `liquidGooeyShadow` compiles those
+     * to a CSS `drop-shadow()` on the silhouette — the compositor does the blur,
+     * the shadow hugs the poured outline rather than a rounded rectangle, and it
+     * is allowed to paint outside the filter region. Inset and spread are legal
+     * but stay inside the SVG filter and are charged against the filter-area
+     * budget, so they are a deliberate purchase, not a default.
+     */
+    readonly shadow?: string;
+    /**
+     * What it casts while the form is engaged, when that differs.
+     *
+     * A body that squashes toward the surface gets *closer* to it, and a real
+     * contact shadow answers by tightening and darkening rather than staying
+     * put. Leaving this out is fine; the rest shadow then holds through the
+     * whole gesture, which is what a form with no vertical travel wants.
+     */
+    readonly shadowEngaged?: string;
 }
 
 /**
@@ -2399,10 +2437,37 @@ export declare interface LiquidFormItem {
 /** Resolve a form into item props, with the same merge-don't-replace rule. */
 export declare function liquidFormItem(form: LiquidForm, overrides?: LiquidFormItem): LiquidFormItem;
 
+/**
+ * Whether a form describes one body or a relationship between siblings.
+ *
+ * `LiquidSurface` draws one silhouette, so it can only honour a `body` form;
+ * a `group` form says something about the space *between* items and needs a
+ * `LiquidGroup` the caller arranges. That distinction used to live in a
+ * parenthetical — `ENGAGED` carried two entries marked 「present for
+ * exhaustiveness」 — which meant picking the wrong one failed silently, by
+ * rendering a body that never moves. Naming it lets a shelf group itself, lets
+ * a caller check, and lets the kit say so out loud in development.
+ */
+export declare type LiquidFormKind = 'body' | 'group';
+
 export declare interface LiquidFormSpec {
     /** One sentence on what a viewer sees, for docs and for picking. */
     readonly summary: string;
+    /** One body, or a relationship between siblings the caller arranges. */
+    readonly kind: LiquidFormKind;
     readonly group: LiquidFormGroup;
+    /**
+     * Group knobs that change while the form is engaged.
+     *
+     * Only `set` uses this, and only because `set` is the one form whose subject
+     * is *stopping* being liquid — without it the vocabulary can say a dozen
+     * degrees of liquid and never say 「solid」. Be careful with it: `blob` is
+     * path data and `gloss` is a filter pass, so neither tweens. They snap. For
+     * `set` that snap is the gesture — a thing clicking into place — and for
+     * anything continuous it would be a flicker, which is why this is not a
+     * general-purpose second bundle.
+     */
+    readonly groupEngaged?: Partial<LiquidFormGroup>;
     readonly item: LiquidFormItem;
 }
 
@@ -2557,7 +2622,7 @@ export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTM
 
 export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
 
-export declare function LiquidSurface({ children, form, active, fill, stroke, shadow, radius, className, style, }: LiquidSurfaceProps): ReactNode;
+export declare function LiquidSurface({ children, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
 
 export declare interface LiquidSurfaceProps {
     children: ReactNode;
@@ -2571,6 +2636,7 @@ export declare interface LiquidSurfaceProps {
     /** Silhouette paint. Defaults to the kit's raised surface token. */
     fill?: string;
     stroke?: string;
+    /** Overrides the form's own cast shadow. `none` removes it. */
     shadow?: string;
     /** Corner radius of the body, in px. 999 gives a pill. */
     radius?: number;