@pieai/swimmer-ui-kit 2.12.0 → 2.14.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
 ## Unreleased
 
+## 2.14.0 — 2026-10-01
+
+- Fix the stair-stepped top edge on every glossy liquid body: the gloss pass
+  added its light's alpha to the body's, so a half-covered edge pixel turned
+  opaque wherever the highlight was bright. The light is now clipped to the
+  body eroded by a pixel and feathered; the highlight itself is unchanged.
+- Add `LiquidFill`: `LiquidGroup` and `LiquidSurface` take `fill={{ top,
+  bottom?, sheen? }}` for the coloured-liquid light (a narrow brighter band at
+  the top, a deeper foot). Colours may be tokens; bands are CSS `color-mix`.
+- `LiquidSurface` takes `gloss` and `outline={{ amplitude, lobes? }}` to
+  override its form's light and rest lobing.
+- 涟 (`LiquidPresence`, `LiquidReveal` material surface): the face carries its
+  light in the fill (top to foot) and casts a soft contact shadow along its
+  own outline through the new `--game-ui-liquid-presence-shadow` token; the
+  material panel drops its raised rim and stroke. The dark surface is unchanged.
+- Compatibility: additive API; visual change to glossy edges and to 涟's
+  material face. Owner approved publication on 2026-10-01 (University
+  session, "品牌UI包要发布成新版"), with the repository kept to one main line.
+
+## 2.13.0 — 2026-09-29
+
+- Add opt-in `surface="plaque"` to `GameButton`, `GameIconButton` and
+  `GameAvatar`, with opaque light/night copper token pairs derived from
+  Directing's reviewed D1-03 cabinet material. Default controls stay unchanged.
+- Add controlled `GameOtpInput`: numeric slots, paste/autofill, keyboard and
+  backspace, localized descriptions and input-method composition handling.
+  Only changed user input completes a code; verification stays in the host.
+- Add vertical `GameTabs` with Up/Down navigation and an accessible name.
+- Add `GameListRow` with thumbnail, text, current indicator and independent
+  selection/actions; no nested buttons.
+- Add browser regressions, six stories and contrast guards. Redirect fresh
+  modal-test screenshots to `.devspace-visual/`, preserving retained scratch
+  evidence and all existing assertions.
+- Compatibility: additive only; no new dependency or React peer change.
+  Published through the existing npm Trusted Publishing workflow after
+  Owner clarified public publication (AuthKit remains private).
+
 ## 2.12.0 — 2026-09-29
 
 - Add optional `useGameCardOrientation` and the bounded `GameCardTilt` input

package/README.md

@@ -2,8 +2,9 @@
 
 Self-contained clay game UI kit for PieAI web, game, and wrapped
 (mobile/desktop WebView) surfaces. React 19 + TypeScript strict.
-**Zero runtime dependencies, 100% standard CSS** — consumers need no
-Tailwind, no PostCSS, no CSS processor of any kind.
+**100% standard CSS** — consumers need no Tailwind, no PostCSS, no CSS
+processor of any kind. The optional `GameHelpTip` uses the existing Floating UI
+dependency; ordinary controls remain native.
 
 Source is publicly readable. Use is governed by the
 [PieAI Limited Use License](./LICENSE), not an open-source license. The visual
@@ -56,6 +57,13 @@ import '@pieai/swimmer-ui-kit/tailwind.css';
 
 ## What's inside
 
+- **Account primitives (2.13.0)**:
+  opt-in copper `surface="plaque"`, `GameOtpInput`, vertical `GameTabs`,
+  and `GameListRow` with independent actions. See the
+  [account-controls contract](docs/reference/design-system-guide.md#账号界面原件)
+  and Storybook `Clay / Account / AccountControls`. Account requests and
+  business state stay in the host.
+
 - **Ready-to-use components** across: core controls (`GameButton`,
   `LiquidMetalButton`, `GameTabs`,
   `GameSlider`, `GameToggle`, `GameForms` inputs…), panels and windows

package/dist/index.d.ts

@@ -1259,9 +1259,11 @@ export declare type GameAssetSource = 'starter' | 'generated' | 'imported';
 
 export declare type GameAssetStatus = 'ready' | 'generating' | 'missing' | 'placed' | 'selected' | 'error';
 
-export declare function GameAvatar({ className, name, size, src, status, }: GameAvatarProps): ReactNode;
+export declare function GameAvatar({ className, name, size, src, status, surface, }: GameAvatarProps): ReactNode;
 
 export declare interface GameAvatarProps {
+    /** Optional copper frame; omitted keeps the existing avatar surface. */
+    surface?: 'flat' | 'plaque';
     /** Display name — used as image alt text and for the initials fallback. */
     name: string;
     /** Optional image URL; when missing, initials are shown instead. */
@@ -1397,7 +1399,7 @@ export declare interface GameButtonProps extends ButtonHTMLAttributes<HTMLButton
     variant?: GameButtonVariant;
 }
 
-export declare type GameButtonSurface = 'flat' | 'liquid';
+export declare type GameButtonSurface = 'flat' | 'liquid' | 'plaque';
 
 export declare type GameButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'success';
 
@@ -1892,6 +1894,22 @@ export declare interface GameLanguageMenuProps {
     onSelect?: (id: string) => void;
 }
 
+/** A quiet list surface, with sibling controls rather than buttons inside a button. */
+export declare function GameListRow({ title, description, thumbnail, current, selected, disabled, onSelect, selectLabel, actions, className, ...props }: GameListRowProps): ReactNode;
+
+export declare interface GameListRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'onSelect' | 'children'> {
+    title: string;
+    description?: ReactNode;
+    thumbnail?: ReactNode;
+    current?: boolean;
+    selected?: boolean;
+    disabled?: boolean;
+    onSelect?: () => void;
+    /** Optional name for the row's selection control, independent of its actions. */
+    selectLabel?: string;
+    actions?: ReactNode;
+}
+
 export declare function GameLoadingState({ label, tone }: GameLoadingStateProps): ReactNode;
 
 export declare interface GameLoadingStateProps {
@@ -1978,6 +1996,24 @@ export declare interface GameOrientationGateProps {
     title: string;
 }
 
+/** Numeric entry only. Sending, expiry, validation and retries belong to the host. */
+export declare function GameOtpInput({ length, value, onChange, onComplete, invalid, disabled, readOnly, getSlotLabel, getSlotDescription, className, 'aria-describedby': describedBy, ...props }: GameOtpInputProps): ReactNode;
+
+export declare interface GameOtpInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'children'> {
+    /** Number of numeric slots; defaults to six. */
+    length?: number;
+    value: string;
+    onChange: (value: string) => void;
+    /** Only user input completes a code; mounting or changing props never submits. */
+    onComplete?: (value: string) => void;
+    invalid?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Zero-based slot index, followed by the configured length. */
+    getSlotLabel?: (index: number, length: number) => string;
+    getSlotDescription?: (index: number, length: number) => string;
+}
+
 export declare function GamePanel({ children, className, title, tone, ...props }: GamePanelProps): ReactNode;
 
 export declare interface GamePanelProps extends HTMLAttributes<HTMLElement> {
@@ -2009,7 +2045,7 @@ export declare function GameProgress({ className, label, max, showValue, tone, v
 
 export declare interface GameProgressProps {
     /** Defaults to the existing liquid leading edge. Flat adds no SVG filter. */
-    surface?: GameButtonSurface;
+    surface?: Exclude<GameButtonSurface, 'plaque'>;
     liquidFinish?: LiquidFinish;
     /** Current value, between 0 and `max`. */
     value: number;
@@ -2084,7 +2120,7 @@ export declare interface GameSegmentedControlProps {
     onSelect?: (id: string) => void;
     options: readonly GameSegmentedOption[];
     /** Existing default is liquid. Flat provides a quiet, filter-free option. */
-    surface?: GameButtonSurface;
+    surface?: Exclude<GameButtonSurface, 'plaque'>;
     liquidFinish?: LiquidFinish;
     disabled?: boolean;
 }
@@ -2104,7 +2140,7 @@ export declare const GameSelect: ForwardRefExoticComponent<GameSelectProps & Ref
 
 export declare interface GameSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
     invalid?: boolean;
-    surface?: GameButtonSurface;
+    surface?: Exclude<GameButtonSurface, 'plaque'>;
     liquidFinish?: LiquidFinish;
 }
 
@@ -2213,9 +2249,12 @@ export declare interface GameTabItem {
     panelId?: string;
 }
 
-export declare function GameTabs({ activeId, id, onSelect, tabs }: GameTabsProps): ReactNode;
+export declare function GameTabs({ activeId, id, onSelect, tabs, orientation, 'aria-label': label, 'aria-labelledby': labelledBy, }: GameTabsProps): ReactNode;
 
 export declare interface GameTabsProps {
+    orientation?: 'horizontal' | 'vertical';
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
     activeId: string;
     /**
      * Base id for this tabs instance (defaults to a generated one). Each tab
@@ -2366,7 +2405,7 @@ export declare function GameToggle({ checked, disabled, label, onClick, surface,
 export declare interface GameToggleProps extends Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled' | 'onClick'> {
     checked: boolean;
     label: string;
-    surface?: GameButtonSurface;
+    surface?: Exclude<GameButtonSurface, 'plaque'>;
     liquidFinish?: LiquidFinish;
 }
 
@@ -2517,6 +2556,45 @@ export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
  */
 export declare const LIQUID_GOOEY_WAVINESS_MAX_FRACTION = 0.3;
 
+/**
+ * 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.
+ */
+export declare type LiquidFill = string | {
+    readonly top: string;
+    readonly bottom?: string;
+    readonly sheen?: number;
+};
+
 /** Material is independent of a widget's meaning and a form's motion. */
 export declare type LiquidFinish = 'matte' | 'glossy';
 
@@ -2664,29 +2742,6 @@ export declare const LiquidGroup: ForwardRefExoticComponent<LiquidGroupProps & R
     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 |
- * | **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.
- */
 export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     children: ReactNode;
     /** Goo blur sigma in px. Larger values bridge larger gaps. */
@@ -2700,8 +2755,11 @@ export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivEle
     gloss?: number;
     /** Optional named finish. An explicit raw gloss wins; omitted preserves the old rendering. */
     liquidFinish?: LiquidFinish;
-    /** Surface fill. Defaults to the kit's theme surface token. */
-    fill?: string;
+    /**
+     * 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. */
@@ -2792,7 +2850,7 @@ export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTM
 
 export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
 
-export declare function LiquidSurface({ children, liquidFinish, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
+export declare function LiquidSurface({ children, liquidFinish, form, active, fill, stroke, shadow: shadowOverride, gloss: glossOverride, outline, radius, className, style, }: LiquidSurfaceProps): ReactNode;
 
 export declare interface LiquidSurfaceProps {
     children: ReactNode;
@@ -2806,7 +2864,20 @@ export declare interface LiquidSurfaceProps {
      */
     active?: boolean;
     /** Silhouette paint. Defaults to the kit's raised surface token. */
-    fill?: string;
+    fill?: LiquidFill;
+    /**
+     * The body's light, overriding the form's own. The coloured liquid theme
+     * uses a low value; with `liquidFinish="matte"` omitted, 0 means flat.
+     */
+    gloss?: number;
+    /**
+     * The rest outline's lobing, overriding the form's own: `amplitude` in px
+     * swells outward, `lobes` is how many go round (2 lazy, 5 busy).
+     */
+    outline?: {
+        readonly amplitude: number;
+        readonly lobes?: number;
+    };
     stroke?: string;
     /** Overrides the form's own cast shadow. `none` removes it. */
     shadow?: string;