@pieai/swimmer-ui-kit 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 2.6.0 — 2026-09-12
+
+Minor: new optional material selection and native controls. Existing root
+exports and export-map paths remain; omitted options retain prior defaults.
+
+### Added
+
+- `LiquidFinish` and optional `liquidFinish="matte" | "glossy"` across
+  LiquidGroup/LiquidSurface, GameButton, GameIconButton, GameToggle,
+  GameSegmentedControl, GameProgress and GameSelect. Both finishes reuse the
+  existing renderer; matte removes the specular pass, not motion or shadows.
+  Explicit LiquidGroup `gloss` remains the advanced override.
+- Liquid icon buttons and switch thumbs; GameSelect uses a real native select
+  with optional liquid closed-field decoration, form/reset/ref/optgroup support,
+  invalid semantics and ordinary disabled/multiple/list modes. The popup remains
+  platform-native; this is not a searchable combobox or custom liquid listbox.
+- Optional flat, filter-free progress and segmented surfaces. Slider forwards
+  native step, disabled, name and id.
+- A beginner catalog at the site root: 12 shared recipe groups, 6 liquid control
+  categories, matte/glossy comparison, theme/state selection, actual interaction,
+  complete copyable/typechecked React examples and shareable configuration URLs.
+  Storybook uses the same recipes. The old reference remains at `/?view=reference`
+  and old `#game-ui-preview-*` links still open it.
+
+### Fixed and intentionally changed
+
+- Press decoration ignores secondary pointer buttons and key repeat, clears on
+  lost capture/cancellation/blur, resets through disabled, and honors `static`.
+  Native content and hit targets never inherit the squash transform.
+- The liquid button's native element no longer picks up the ordinary button's
+  independent CSS `scale` on press or hover lift; only the silhouette moves.
+- Pointer feedback survives macOS WebKit's native pointerdown-then-blur ordering;
+  a true window deactivation still cancels the gesture. No focus is forced onto
+  the native control to hide this platform difference.
+- Progress ARIA values now agree with the clamped visible value, including invalid
+  maxima and non-finite input. Forced-colors decoration falls back to system UI.
+- `GameInput` and `GameTextArea` now expose `invalid` through `aria-invalid`,
+  like the new select; an explicit ARIA value still wins.
+- Select decoration is a sibling of the persistent native field. Disabling,
+  changing material or switching single/list presentation must not remount the
+  select and lose an uncontrolled choice or replace its forwarded DOM ref.
+  Catalog material/state adjustments likewise preserve the current example's
+  entered values instead of silently resetting the recipe.
+- Disabled icon buttons, switches and segmented options now have a quiet,
+  non-hovering treatment. Disabled segmented controls retain the selected option
+  on a flat surface instead of reserving animated liquid groups.
+  Inherited native fieldset disabling also hides button/icon/switch/select decoration.
+- The liquid form page selects experiments instead of mounting every form, size,
+  tone and state simultaneously. At most two liquid groups are mounted; the shared
+  budget was not increased and the twelve forms were not removed or retuned.
+
+### Consumer action
+
+Pin the new version and run your own product gates. New materials/controls are
+opt-in; University was not modified. Do not remove its destination/route transition
+when adopting kit buttons. See the upgrade playbook for adoption and rollback.
+No new runtime dependency, ambient clock, donor observer, image optimization or
+commercial donor preset is introduced by this release.
+
 ## 2.5.0 — 2026-09-12
 
 ### Find the right component before reading the whole API

package/README.md

@@ -17,14 +17,18 @@ assets may not be extracted, modified, or redistributed as a standalone pack.
   [Usage and upgrade playbook](docs/reference/usage-and-upgrade-playbook.md)
 - Exhaustive reference (not the starting point):
   [Generated public API inventory](docs/reference/public-api-inventory.md)
-- Live catalog: `pnpm dev` (preview page) and `pnpm storybook`
+- [Interactive catalog](https://swimmer-ui-kit.pieaistudio.com/): real controls,
+  matte/glossy comparison, theme/state selectors and copyable React examples.
+- [Full reference](https://swimmer-ui-kit.pieaistudio.com/?view=reference) and
+  [liquid form laboratory](https://swimmer-ui-kit.pieaistudio.com/liquid.html).
+  Local: `pnpm dev` and `pnpm storybook`.
 
 ## Install
 
 ```json
 {
   "dependencies": {
-    "@pieai/swimmer-ui-kit": "2.5.0"
+    "@pieai/swimmer-ui-kit": "2.6.0"
   }
 }
 ```

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { SelectHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
 /** Opt in to placeholders on purpose, and stop being told about it. */
@@ -1376,12 +1377,14 @@ export declare interface GameBuildLibraryProps {
     'data-testid'?: string | undefined;
 }
 
-export declare function GameButton({ children, className, fullWidth, onClick, sound, static: isStatic, surface, type, variant, ...props }: GameButtonProps): ReactNode;
+export declare function GameButton({ children, className, fullWidth, liquidFinish, onClick, sound, static: isStatic, surface, type, variant, ...props }: GameButtonProps): ReactNode;
 
 export declare interface GameButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     children: ReactNode;
     /** Fill the available row, including the liquid silhouette and hit target. */
     fullWidth?: boolean;
+    /** Named liquid material. Only used with surface="liquid"; omitted keeps the current look. */
+    liquidFinish?: LiquidFinish;
     sound?: GameInteractionSoundOptions | false;
     /** Disable the scale-on-press feedback where the motion would distract. */
     static?: boolean;
@@ -1727,11 +1730,13 @@ export declare interface GameHudProps {
     label: string;
 }
 
-export declare function GameIconButton({ children, className, label, type, ...props }: GameIconButtonProps): ReactNode;
+export declare function GameIconButton({ children, className, label, surface, liquidFinish, type, ...props }: GameIconButtonProps): ReactNode;
 
 export declare interface GameIconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     children: ReactNode;
     label: string;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
 }
 
 export declare const GameInput: ForwardRefExoticComponent<GameInputProps & RefAttributes<HTMLInputElement>>;
@@ -1912,9 +1917,12 @@ export declare interface GamePlacementToolbarProps {
     title: string;
 }
 
-export declare function GameProgress({ className, label, max, showValue, tone, value, valueLabel, }: GameProgressProps): ReactNode;
+export declare function GameProgress({ className, label, max, showValue, tone, value, valueLabel, surface, liquidFinish, }: GameProgressProps): ReactNode;
 
 export declare interface GameProgressProps {
+    /** Defaults to the existing liquid leading edge. Flat adds no SVG filter. */
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
     /** Current value, between 0 and `max`. */
     value: number;
     max?: number;
@@ -1980,13 +1988,17 @@ 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, surface, liquidFinish, disabled, }: GameSegmentedControlProps): ReactNode;
 
 export declare interface GameSegmentedControlProps {
     activeId: string;
     label: string;
     onSelect?: (id: string) => void;
     options: readonly GameSegmentedOption[];
+    /** Existing default is liquid. Flat provides a quiet, filter-free option. */
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
+    disabled?: boolean;
 }
 
 declare interface GameSegmentedOption {
@@ -1994,6 +2006,20 @@ declare interface GameSegmentedOption {
     label: string;
 }
 
+/**
+ * Native select, not a custom listbox state machine. Options/optgroups, form
+ * submission, reset, keyboard and the mobile picker remain browser-owned.
+ * Liquid paints only the closed single-select field. Disabled/multiple/list
+ * modes use the ordinary surface; we do not pretend to animate an OS popup.
+ */
+export declare const GameSelect: ForwardRefExoticComponent<GameSelectProps & RefAttributes<HTMLSelectElement>>;
+
+export declare interface GameSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    invalid?: boolean;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
+}
+
 export declare function GameShell({ assetLibrary, bottomBar, children, className, density, hud, layout, movementPad, overlay, sidePanel, title, }: GameShellProps): ReactNode;
 
 export declare interface GameShellProps {
@@ -2018,9 +2044,9 @@ export declare interface GameShellProps {
     title: string;
 }
 
-export declare function GameSlider({ label, max, min, onChange, value }: GameSliderProps): ReactNode;
+export declare function GameSlider({ label, max, min, step, disabled, name, id, onChange, value, }: GameSliderProps): ReactNode;
 
-export declare interface GameSliderProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'max' | 'min' | 'value'> {
+export declare interface GameSliderProps extends Pick<InputHTMLAttributes<HTMLInputElement>, 'max' | 'min' | 'value' | 'step' | 'disabled' | 'name' | 'id'> {
     label: string;
     onChange?: (value: number) => void;
 }
@@ -2200,11 +2226,13 @@ export declare interface GameToastProps {
     tone?: 'info' | 'success' | 'danger';
 }
 
-export declare function GameToggle({ checked, disabled, label, onClick }: GameToggleProps): ReactNode;
+export declare function GameToggle({ checked, disabled, label, onClick, surface, liquidFinish, }: GameToggleProps): ReactNode;
 
 export declare interface GameToggleProps extends Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled' | 'onClick'> {
     checked: boolean;
     label: string;
+    surface?: GameButtonSurface;
+    liquidFinish?: LiquidFinish;
 }
 
 export declare function GameTooltip({ children, label }: GameTooltipProps): ReactNode;
@@ -2354,6 +2382,9 @@ export declare const LIQUID_FORMS: Readonly<Record<LiquidForm, LiquidFormSpec>>;
  */
 export declare const LIQUID_GOOEY_WAVINESS_MAX_FRACTION = 0.3;
 
+/** Material is independent of a widget's meaning and a form's motion. */
+export declare type LiquidFinish = 'matte' | 'glossy';
+
 /**
  * The named looks.
  *
@@ -2532,6 +2563,8 @@ export declare interface LiquidGroupProps extends Omit<HTMLAttributes<HTMLDivEle
      * curved surface so it reads as a material rather than as a silhouette.
      */
     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;
     /** Extra filter-region slack in px for the silhouette's painted edges. */
@@ -2624,10 +2657,12 @@ export declare interface LiquidMetalButtonProps extends ButtonHTMLAttributes<HTM
 
 export declare type LiquidMetalRendererMode = 'auto' | 'css' | 'webgl';
 
-export declare function LiquidSurface({ children, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
+export declare function LiquidSurface({ children, liquidFinish, form, active, fill, stroke, shadow: shadowOverride, radius, className, style, }: LiquidSurfaceProps): ReactNode;
 
 export declare interface LiquidSurfaceProps {
     children: ReactNode;
+    /** Omitted keeps the form's existing lighting; matte and glossy share the same motion. */
+    liquidFinish?: LiquidFinish;
     /** Which named look. Defaults to the press form, the one a control wants. */
     form?: LiquidForm;
     /**