@pieai/swimmer-ui-kit 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
 ## Unreleased
 
+### 2.13.0 candidate — WO-UI-1
+
+- 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.
+  This candidate is not published: Owner's private-publication instruction
+  needs clarification before using this repository's public npm workflow.
+
+## 2.12.0 — 2026-09-29
+
+- Add optional `useGameCardOrientation` and the bounded `GameCardTilt` input
+  on `GameCollectibleCard`. One explicitly enabled hook serves the active card
+  in an album. Mounting does not request permission or subscribe to a sensor.
+  Secure context, denial, late permission, page visibility and reduced motion
+  have explicit state and cleanup; no sensor samples or consent are stored.
+- Preserve pointer/keyboard flipping and all omitted-prop behavior. A pointer
+  on the card wins over device tilt; reduced motion zeros both immediately.
+  Drag classification still applies under reduced motion, and a keyboard or
+  assistive click is not suppressed by a stale pointer gesture.
+- Add an opt-in Storybook example and isolated browser sensor-contract tests.
+  Synthetic sensor/permission cases are not physical-device permission evidence.
+
 ## 2.11.0 — 2026-09-28
 
 Minor: University's V7 opening screen and card album, and the liquid fix

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 local candidate, not published)**:
+  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';
 
@@ -1431,6 +1433,14 @@ export declare interface GameCardFanProps {
     label: string;
 }
 
+export declare type GameCardOrientationStatus = 'unavailable' | 'off' | 'requesting' | 'enabled' | 'denied';
+
+/** Normalized card tilt; zero is level, -1 and 1 are the bounded extremes. */
+export declare interface GameCardTilt {
+    readonly x: number;
+    readonly y: number;
+}
+
 export declare function GameCheckbox({ className, label, ...props }: GameCheckboxProps): ReactNode;
 
 export declare interface GameCheckboxProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'checked' | 'defaultChecked' | 'disabled' | 'name' | 'onChange' | 'required' | 'value'> {
@@ -1469,7 +1479,7 @@ export declare interface GameCollapsiblePanelProps extends Omit<HTMLAttributes<H
  * Under reduced motion the card does not tilt, shine or spin its light, and a
  * flip is instant.
  */
-export declare function GameCollectibleCard({ rarity, title, caption, setLabel, rarityLabel, art, pips, sticker, back, label, faceDown, defaultFaceDown, onFlip, spotlight, sound, className, }: GameCollectibleCardProps): ReactNode;
+export declare function GameCollectibleCard({ rarity, title, caption, setLabel, rarityLabel, art, pips, sticker, back, label, faceDown, defaultFaceDown, onFlip, spotlight, sound, tilt: externalTilt, className, }: GameCollectibleCardProps): ReactNode;
 
 export declare interface GameCollectibleCardProps {
     readonly rarity: GameCollectibleCardRarity;
@@ -1503,6 +1513,9 @@ export declare interface GameCollectibleCardProps {
     readonly spotlight?: boolean;
     /** Play a synthesized flip sound; browsers allow it only after the page has been tapped. */
     readonly sound?: boolean;
+    /** Optional normalized tilt from one explicitly enabled sensor owner. A
+     * pointer on this card takes precedence; reduced motion always wins. */
+    readonly tilt?: GameCardTilt | null;
     readonly className?: string;
 }
 
@@ -1881,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 {
@@ -1967,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> {
@@ -1998,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;
@@ -2073,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;
 }
@@ -2093,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;
 }
 
@@ -2202,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
@@ -2355,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;
 }
 
@@ -2893,6 +2943,19 @@ declare type Transition = TransitionPreset | SpringConfig | {
 
 declare type TransitionPreset = 'snappy' | 'smooth' | 'bouncy' | 'wobbly';
 
+/** One optional sensor owner for an album or preview, NOT one per card.
+ * Call enable from a real user action, then pass tilt only to the active card.
+ * No permission, storage, microphone, motion sensor or network request occurs
+ * on mount. Reduced motion cancels consent in flight and requires a new action;
+ * hiding the page pauses samples and recalibrates on return. */
+export declare function useGameCardOrientation(): {
+    status: GameCardOrientationStatus;
+    tilt: GameCardTilt | null;
+    enable: () => Promise<boolean>;
+    disable: () => void;
+    reducedMotion: boolean;
+};
+
 /**
  * Whether a waiting screen should appear yet: only once `waiting` has stayed
  * true for `delayMs` without a break. A scene change that finishes inside the