@pieai/swimmer-ui-kit 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -55,7 +55,7 @@ export declare const CLAY_ASSETS: {
 
 export declare const CLAY_COLOR_TOKENS: {
     readonly ink: "#3b2d23";
-    readonly inkMuted: "#7b6652";
+    readonly inkMuted: "#786250";
     readonly parchment: "#fff8ec";
     readonly parchmentDeep: "#f4e2c6";
     readonly cream: "#f3e8d8";
@@ -72,6 +72,9 @@ export declare const CLAY_COLOR_TOKENS: {
     readonly shadow: "rgba(76, 52, 28, 0.24)";
     readonly glass: "rgba(255, 248, 236, 0.82)";
     readonly nightGlass: "rgba(31, 24, 18, 0.76)";
+    /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
+    readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
+    readonly overlayGlassText: "#fff6ee";
 };
 
 export declare const CLAY_ELEVATION_TOKENS: {
@@ -268,6 +271,26 @@ export declare const CLAY_MOTION_TOKENS: {
     readonly reducedMotion: "var(--game-ui-reduced-motion-policy)";
 };
 
+/**
+ * Semantic CSS vars for the official overlay-glass HUD tone
+ * (`data-game-ui-tone="glass"` / `.game-ui-overlay-scope`).
+ */
+declare const CLAY_OVERLAY_GLASS_TOKENS: {
+    readonly bg: "var(--game-ui-overlay-glass-bg)";
+    readonly bgHover: "var(--game-ui-overlay-glass-bg-hover)";
+    readonly bgStrong: "var(--game-ui-overlay-glass-bg-strong)";
+    readonly bgPanel: "var(--game-ui-overlay-glass-bg-panel)";
+    readonly border: "var(--game-ui-overlay-glass-border)";
+    readonly borderHover: "var(--game-ui-overlay-glass-border-hover)";
+    readonly text: "var(--game-ui-overlay-glass-text)";
+    readonly textMuted: "var(--game-ui-overlay-glass-text-muted)";
+    readonly blur: "var(--game-ui-overlay-glass-blur)";
+    readonly focusRing: "var(--game-ui-overlay-glass-focus-ring)";
+    readonly primaryFill: "var(--game-ui-overlay-glass-primary-fill)";
+};
+export { CLAY_OVERLAY_GLASS_TOKENS }
+export { CLAY_OVERLAY_GLASS_TOKENS as GAME_UI_OVERLAY_GLASS_TOKENS }
+
 export declare const CLAY_RADIUS_TOKENS: {
     readonly bead: "var(--game-ui-radius-bead)";
     readonly control: "var(--game-ui-radius-control)";
@@ -346,7 +369,7 @@ export declare const CLAY_TYPE_TOKENS: {
 export declare const CLAY_UI_TOKENS: {
     readonly colors: {
         readonly ink: "#3b2d23";
-        readonly inkMuted: "#7b6652";
+        readonly inkMuted: "#786250";
         readonly parchment: "#fff8ec";
         readonly parchmentDeep: "#f4e2c6";
         readonly cream: "#f3e8d8";
@@ -363,6 +386,9 @@ export declare const CLAY_UI_TOKENS: {
         readonly shadow: "rgba(76, 52, 28, 0.24)";
         readonly glass: "rgba(255, 248, 236, 0.82)";
         readonly nightGlass: "rgba(31, 24, 18, 0.76)";
+        /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
+        readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
+        readonly overlayGlassText: "#fff6ee";
     };
     readonly semantic: {
         readonly background: "var(--game-ui-bg)";
@@ -470,6 +496,19 @@ export declare const CLAY_UI_TOKENS: {
         readonly buildRailCardSize: "var(--game-ui-build-rail-card-size)";
         readonly brushNumberWidth: "var(--game-ui-brush-number-width)";
     };
+    readonly overlayGlass: {
+        readonly bg: "var(--game-ui-overlay-glass-bg)";
+        readonly bgHover: "var(--game-ui-overlay-glass-bg-hover)";
+        readonly bgStrong: "var(--game-ui-overlay-glass-bg-strong)";
+        readonly bgPanel: "var(--game-ui-overlay-glass-bg-panel)";
+        readonly border: "var(--game-ui-overlay-glass-border)";
+        readonly borderHover: "var(--game-ui-overlay-glass-border-hover)";
+        readonly text: "var(--game-ui-overlay-glass-text)";
+        readonly textMuted: "var(--game-ui-overlay-glass-text-muted)";
+        readonly blur: "var(--game-ui-overlay-glass-blur)";
+        readonly focusRing: "var(--game-ui-overlay-glass-focus-ring)";
+        readonly primaryFill: "var(--game-ui-overlay-glass-primary-fill)";
+    };
 };
 
 export declare type ClayAssetGroup = keyof typeof CLAY_ASSETS;
@@ -507,7 +546,7 @@ export declare type ClayIconStyle = 'game' | 'line';
 
 export declare type ClayTokenCategory = keyof typeof CLAY_UI_TOKENS;
 
-export declare function FirstSessionHud({ authenticated, batteryCount, className, dailyStreak, iconSlots, labels, onHistory, onSettings, onWardrobe, playerName }: FirstSessionHudProps): ReactNode;
+export declare function FirstSessionHud({ authenticated, batteryCount, className, dailyStreak, iconSlots, labels, onHistory, onSettings, onWardrobe, playerName, }: FirstSessionHudProps): ReactNode;
 
 export declare interface FirstSessionHudIconSlots {
     history?: ReactNode;
@@ -556,7 +595,7 @@ export declare interface FirstSessionHudProps {
     playerName: string;
 }
 
-export declare function FirstSessionOnboarding({ labels, onDismiss, open }: FirstSessionOnboardingProps): ReactNode;
+export declare function FirstSessionOnboarding({ labels, onDismiss, open, }: FirstSessionOnboardingProps): ReactNode;
 
 export declare interface FirstSessionOnboardingLabels {
     badge: string;
@@ -578,6 +617,15 @@ export declare interface FirstSessionOnboardingStep {
     title: string;
 }
 
+/** Opt-in attribute values for the official overlay-glass HUD scope. */
+export declare const GAME_UI_OVERLAY: {
+    readonly toneAttr: "data-game-ui-tone";
+    readonly toneGlass: "glass";
+    readonly densityAttr: "data-game-ui-density";
+    readonly densityCompact: "compact";
+    readonly scopeClass: "game-ui-overlay-scope";
+};
+
 export declare const GAME_UI_PREVIEW_MESSAGES: readonly GameUiHistoryEntry[];
 
 export declare const GAME_UI_TARGETS: {
@@ -593,6 +641,17 @@ export declare const GAME_UI_TARGETS: {
     readonly mobileLandscapeProofHeightPx: 390;
 };
 
+/**
+ * The semantic `--game-ui-*` custom properties a *complete* theme must
+ * override for full fidelity — this is the same list the official
+ * `[data-game-ui-theme='night']` block in theme.css satisfies, enforced by
+ * a guard test in src/tokens.test.ts. A downstream product building its own
+ * full theme (e.g. `[data-game-ui-theme='abyss']`) can reuse this constant
+ * to check its own CSS for the same completeness instead of eyeballing it —
+ * see "自定义第三主题" in design-system-guide.md for a usage example.
+ */
+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"];
+
 export declare const GAME_UI_TOKENS: {
     readonly iconSm: "var(--game-ui-asset-icon-sm)";
     readonly iconMd: "var(--game-ui-asset-icon-md)";
@@ -670,7 +729,7 @@ export declare const GAME_UI_TOKENS: {
     readonly disabled: "var(--game-ui-disabled)";
 };
 
-export declare function GameActionGrid({ actions, className, density, iconLabelMode, label, style }: GameActionGridProps): ReactNode;
+export declare function GameActionGrid({ actions, className, density, iconLabelMode, label, style, }: GameActionGridProps): ReactNode;
 
 export declare interface GameActionGridProps {
     actions: readonly GameUiAction[];
@@ -725,7 +784,7 @@ export declare interface GameAssetGroup {
     source?: GameAssetSource;
 }
 
-export declare function GameAssetIcon({ className, icon, label, size, style, useSourceAsset }: GameAssetIconProps): ReactNode;
+export declare function GameAssetIcon({ className, icon, label, size, style, useSourceAsset, }: GameAssetIconProps): ReactNode;
 
 export declare interface GameAssetIconProps {
     className?: string;
@@ -762,7 +821,7 @@ 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, }: GameAvatarProps): ReactNode;
 
 export declare interface GameAvatarProps {
     /** Display name — used as image alt text and for the initials fallback. */
@@ -1144,7 +1203,7 @@ export declare interface GameDialogProps {
     title: string;
 }
 
-export declare function GameEmptyState({ action, className, description, icon, title }: GameEmptyStateProps): ReactNode;
+export declare function GameEmptyState({ action, className, description, icon, title, }: GameEmptyStateProps): ReactNode;
 
 export declare interface GameEmptyStateProps {
     /** Optional clay icon shown above the title. */
@@ -1165,7 +1224,7 @@ export declare interface GameFactItem {
     value: ReactNode;
 }
 
-export declare function GameFactList({ className, density, facts, label, variant }: GameFactListProps): ReactNode;
+export declare function GameFactList({ className, density, facts, label, variant, }: GameFactListProps): ReactNode;
 
 export declare interface GameFactListProps {
     className?: string;
@@ -1175,7 +1234,7 @@ export declare interface GameFactListProps {
     variant?: 'facts' | 'stats';
 }
 
-export declare function GameField({ children, className, error, hint, label, required }: GameFieldProps): ReactNode;
+export declare function GameField({ children, className, error, hint, label, required, }: GameFieldProps): ReactNode;
 
 export declare interface GameFieldProps {
     /** The input/textarea this field labels. Rendered inside the <label>. */
@@ -1275,7 +1334,7 @@ export declare interface GameInteractionSoundOptions {
     sfxVolume?: number;
 }
 
-export declare function GameLanguageMenu({ className, currentLabel, label, options, value, defaultValue, onSelect }: GameLanguageMenuProps): ReactNode;
+export declare function GameLanguageMenu({ className, currentLabel, label, options, value, defaultValue, onSelect, }: GameLanguageMenuProps): ReactNode;
 
 export declare interface GameLanguageMenuProps {
     className?: string;
@@ -1315,7 +1374,7 @@ export declare interface GameMaterialSwatchesProps {
     'data-testid'?: string | undefined;
 }
 
-export declare function GameModal({ children, className, closeLabel, closeOnBackdrop, footer, onClose, open, size, title, }: GameModalProps): ReactNode;
+export declare function GameModal({ children, className, closeLabel, closeOnBackdrop, footer, onClose, open, position, size, title, }: GameModalProps): ReactNode;
 
 export declare interface GameModalProps {
     children: ReactNode;
@@ -1327,6 +1386,13 @@ export declare interface GameModalProps {
     /** Called for every close intent: Esc, backdrop click, and close button. */
     onClose: () => void;
     open: boolean;
+    /**
+     * `'bottom'` anchors the frame to the viewport's bottom edge (rounded top
+     * corners only, safe-area-aware padding, slide-up entrance) for mobile
+     * action sheets — same native <dialog> underneath, so focus trap/Esc/
+     * backdrop/top-layer come free either way. Defaults to `'center'`.
+     */
+    position?: 'center' | 'bottom';
     size?: 'sm' | 'md' | 'lg';
     title: string;
 }
@@ -1359,7 +1425,7 @@ export declare const GameObjectToolbar: typeof GamePlacementToolbar;
 
 export declare type GameObjectToolbarProps = GamePlacementToolbarProps;
 
-export declare function GameOrientationGate({ body, cta, badgeLabel, manualHint, preview, title }: GameOrientationGateProps): ReactNode;
+export declare function GameOrientationGate({ body, cta, badgeLabel, manualHint, preview, title, }: GameOrientationGateProps): ReactNode;
 
 export declare interface GameOrientationGateProps {
     body: string;
@@ -1399,7 +1465,7 @@ export declare interface GamePlacementToolbarProps {
     title: string;
 }
 
-export declare function GameProgress({ className, label, max, showValue, tone, value }: GameProgressProps): ReactNode;
+export declare function GameProgress({ className, label, max, showValue, tone, value, }: GameProgressProps): ReactNode;
 
 export declare interface GameProgressProps {
     /** Current value, between 0 and `max`. */
@@ -1421,7 +1487,7 @@ export declare interface GamePromptProps {
     title: string;
 }
 
-export declare function GameRadialMenu({ items, label }: GameRadialMenuProps): ReactNode;
+export declare function GameRadialMenu({ items, label, onSelect }: GameRadialMenuProps): ReactNode;
 
 declare interface GameRadialMenuItem {
     id: string;
@@ -1431,6 +1497,7 @@ declare interface GameRadialMenuItem {
 export declare interface GameRadialMenuProps {
     items: readonly GameRadialMenuItem[];
     label: string;
+    onSelect?: (id: string) => void;
 }
 
 export declare interface GameRobotCrewMember {
@@ -1461,7 +1528,7 @@ export declare const GameSceneHudLayout: typeof GameShell;
 
 export declare type GameSceneHudLayoutProps = GameShellProps;
 
-export declare function GameSegmentedControl({ activeId, label, onSelect, options }: GameSegmentedControlProps): ReactNode;
+export declare function GameSegmentedControl({ activeId, label, onSelect, options, }: GameSegmentedControlProps): ReactNode;
 
 export declare interface GameSegmentedControlProps {
     activeId: string;
@@ -1529,12 +1596,21 @@ export declare type GameSurfaceLayout = 'auto' | 'desktop' | 'mobile';
 export declare interface GameTabItem {
     id: string;
     label: string;
+    /** id of the tabpanel this tab controls; wires aria-controls when set. */
+    panelId?: string;
 }
 
-export declare function GameTabs({ activeId, onSelect, tabs }: GameTabsProps): ReactNode;
+export declare function GameTabs({ activeId, id, onSelect, tabs }: GameTabsProps): ReactNode;
 
 export declare interface GameTabsProps {
     activeId: string;
+    /**
+     * Base id for this tabs instance (defaults to a generated one). Each tab
+     * button's DOM id is `${id}-${tab.id}` — pass an explicit id so your own
+     * `role="tabpanel"` elements can reference it via aria-labelledby (and set
+     * GameTabItem.panelId so the tab points back via aria-controls).
+     */
+    id?: string;
     onSelect?: (id: string) => void;
     tabs: readonly GameTabItem[];
 }
@@ -1682,6 +1758,7 @@ export declare interface GameToggleProps extends Pick<ButtonHTMLAttributes<HTMLB
 export declare function GameTooltip({ children, label }: GameTooltipProps): ReactNode;
 
 export declare interface GameTooltipProps {
+    /** A single focusable trigger element (e.g. GameIconButton). */
     children: ReactNode;
     label: string;
 }