@streamscloud/kit 0.2.42 → 0.9.1

package/dist/ui/usage/cmp.usage.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    title: string;
+    /** Right-aligned secondary text in the header (e.g. plan name). */
+    meta?: string;
+    children: Snippet;
+};
+/**
+ * Usage — card that lists plan / quota usage as a column of icon + label + progress bar + display rows.
+ * Compose with `<UsageRow>` children.
+ *
+ * ### CSS Custom Properties
+ * | Property | Description | Default |
+ * |---|---|---|
+ * | `--sc-kit--usage--background` | Card background | `var(--sc-kit--color--bg--panel)` |
+ * | `--sc-kit--usage--border-color` | Card border | `var(--sc-kit--color--border)` |
+ * | `--sc-kit--usage--padding` | Card padding | `var(--sc-kit--space--6) var(--sc-kit--space--8)` |
+ * | `--sc-kit--usage--title--color` | Header title color | `var(--sc-kit--color--text--primary)` |
+ * | `--sc-kit--usage--meta--color` | Header meta color | `var(--sc-kit--color--text--muted)` |
+ */
+declare const Cmp: import("svelte").Component<Props, {}, "">;
+type Cmp = ReturnType<typeof Cmp>;
+export default Cmp;

package/dist/ui/usage/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Usage } from './cmp.usage.svelte';
+export { default as UsageRow } from './cmp.usage-row.svelte';

package/dist/ui/usage/index.js

@@ -0,0 +1,2 @@
+export { default as Usage } from './cmp.usage.svelte';
+export { default as UsageRow } from './cmp.usage-row.svelte';

package/dist/ui/validatable/cmp.field-error.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">let { error, children } = $props();
+export {};
+</script>
+
+<div class="field-error" class:field-error--errored={!!error}>
+  {@render children()}
+  {#if error}
+    <small class="field-error__message">{error}</small>
+  {/if}
+</div>
+
+<!--
+@component
+Internal helper — wraps a form field and renders its error message in an absolutely-positioned slot
+below, with reserved space so the layout doesn't shift when the error toggles. Used internally by
+`Validatable` / `ValidationError` (and any other field-shaped kit consumer that needs the same
+visual contract).
+
+Not exported from `index.ts` — for kit-internal use only.
+-->
+
+<style>.field-error {
+  position: relative;
+  margin-bottom: 1.1em;
+  display: block;
+}
+.field-error__message {
+  position: absolute;
+  top: calc(100% + 0.1em);
+  left: 0;
+  right: 0;
+  display: block;
+  color: var(--sc-kit--color--danger);
+  font-size: 0.6875rem;
+  font-weight: 400;
+}</style>

package/dist/ui/validatable/cmp.field-error.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    /** Error message to display below the field. Falsy hides the message and the `--errored` flag. */
+    error?: string | null | undefined;
+    children: Snippet;
+};
+/**
+ * Internal helper — wraps a form field and renders its error message in an absolutely-positioned slot
+ * below, with reserved space so the layout doesn't shift when the error toggles. Used internally by
+ * `Validatable` / `ValidationError` (and any other field-shaped kit consumer that needs the same
+ * visual contract).
+ *
+ * Not exported from `index.ts` — for kit-internal use only.
+ */
+declare const Cmp: import("svelte").Component<Props, {}, "">;
+type Cmp = ReturnType<typeof Cmp>;
+export default Cmp;

package/dist/ui/validatable/cmp.validatable.svelte

@@ -1,57 +1,93 @@
-<script lang="ts" generics="T extends Record<string, unknown>">let { name, handler, disableTouchedTracking = false, children } = $props();
-const showErrors = $derived(handler.errors[name] && (disableTouchedTracking || handler.touched[name]));
-export {};
+<script lang="ts" module>export {};
 </script>
 
-<div class="validatable" class:validatable--errored={showErrors}>
-  {@render children()}
-  {#if showErrors}
-    <small class="validatable__error">{handler.errors[name]}</small>
-  {/if}
-</div>
+<script lang="ts" generics="T extends Record<string, unknown>, K extends keyof T & string">import { Utils } from '../../core/utils';
+import { default as FieldError } from './cmp.field-error.svelte';
+let { handler, name, validateOn = ['input', 'change', 'blur'], debounceMs = 0, disableTouchedTracking = false, on, children } = $props();
+// True between a value change and the next completed validation. Hides the stale error in the
+// UI without mutating handler.errors — the model keeps the last known result, the view just
+// doesn't trust it until the validator has caught up.
+let pendingValidation = $state(false);
+// Monotonic counter: each value change and each validation start bumps it. Completing
+// validation clears `pendingValidation` only when the token still matches the latest bump —
+// this discards results from validations that were superseded by further input.
+let activeToken = 0;
+const runValidate = async () => {
+    const myToken = ++activeToken;
+    await handler.validateField(name);
+    if (myToken === activeToken) {
+        pendingValidation = false;
+    }
+};
+const validate = $derived(debounceMs > 0 ? Utils.debounce(runValidate, debounceMs) : runValidate);
+const runs = (mode) => validateOn.includes(mode);
+const showErrors = $derived(!pendingValidation && !!handler.errors[name] && (disableTouchedTracking || !!handler.touched[name]));
+const field = $derived({
+    name,
+    value: handler.form[name],
+    error: showErrors,
+    on: {
+        input: (v) => {
+            handler.updateField(name, v);
+            activeToken++;
+            pendingValidation = true;
+            if (runs('input')) {
+                validate();
+            }
+            on?.input?.(v);
+        },
+        change: (v) => {
+            handler.updateField(name, v);
+            activeToken++;
+            pendingValidation = true;
+            if (runs('change')) {
+                validate();
+            }
+            on?.change?.(v);
+        },
+        blur: () => {
+            handler.updateTouched(name, true);
+            if (runs('blur')) {
+                validate();
+            }
+            else {
+                pendingValidation = false;
+            }
+            on?.blur?.();
+        }
+    }
+});
+</script>
+
+<FieldError error={showErrors ? handler.errors[name] : null}>
+  {@render children(field)}
+</FieldError>
 
 <!--
 @component
-Wraps a form field and displays validation errors from a FormValidationHandler.
+Binds a form field to any kit input via a render-prop snippet. The base inputs stay unchanged;
+`Validatable` is the only place that knows about `FormValidationHandler`. Wraps children in an
+internal `FieldError` frame that reserves space for the error message so toggling doesn't shift
+layout.
 
-### CSS Custom Properties
-| Property | Description | Default |
-|---|---|---|
-| `--sc-kit--validatable--error--color` | Error text and accent color | destructive-500 |
-| `--sc-kit--validatable--error--position` | Error message positioning | `absolute` |
-| `--sc-kit--validatable--error--left` | Error left offset | `0` |
-| `--sc-kit--validatable--error--right` | Error right offset | `0` |
-| `--sc-kit--validatable--margin-bottom` | Bottom margin for spacing | `1.1em` |
-| `--sc-kit--validatable--margin-right` | Right margin for spacing | `0` |
-| `--sc-kit--validatable--display` | Display mode | `block` |
-| `--sc-kit--validatable--width` | Container width | `auto` |
--->
+### Usage
+```svelte
+<Validatable {handler} name="email">
+  {#snippet children(field)}
+    <Input {...field} placeholder="Email" />
+  {/snippet}
+</Validatable>
+```
 
-<style>.validatable {
-  --_validatable--error--color: var(--sc-kit--validatable--error--color, #e71d36);
-  --_validatable--error--position: var(--sc-kit--validatable--error--position, absolute);
-  --_validatable--error--left: var(--sc-kit--validatable--error--left, 0);
-  --_validatable--error--right: var(--sc-kit--validatable--error--right, 0);
-  --_validatable--margin-bottom: var(--sc-kit--validatable--margin-bottom, 1.1em);
-  --_validatable--margin-right: var(--sc-kit--validatable--margin-right, 0);
-  --_validatable--display: var(--sc-kit--validatable--display, block);
-  --_validatable--width: var(--sc-kit--validatable--width, auto);
-  position: relative;
-  margin-bottom: var(--_validatable--margin-bottom);
-  margin-right: var(--_validatable--margin-right);
-  display: var(--_validatable--display);
-  width: var(--_validatable--width);
-}
-.validatable--errored {
-  --_input--explicit-shadow-color: var(--_validatable--error--color);
-}
-.validatable__error {
-  position: var(--_validatable--error--position);
-  top: calc(100% + 0.1em);
-  left: var(--_validatable--error--left);
-  right: var(--_validatable--error--right);
-  display: block;
-  color: var(--_validatable--error--color);
-  font-size: 0.7rem;
-  font-weight: 400;
-}</style>
+The snippet argument has shape `{ name, value, error, on: { input, change, blur } }` — the
+minimal interface every kit input supports. Inputs whose primary value prop is not `value`
+(e.g. `Checkbox` uses `checked`) wire the field explicitly inside the snippet.
+
+### Validation events
+`validateOn` accepts an array. Default `['input', 'change', 'blur']` validates on every event.
+Pass `['blur']` for blur-only validation, `['change', 'blur']` for the classic "validate on commit" pattern.
+
+### Consumer callbacks
+Pass extra callbacks via `Validatable`'s own `on={...}` — they run AFTER the validation wiring
+and cannot override it.
+-->

package/dist/ui/validatable/cmp.validatable.svelte.d.ts

@@ -1,49 +1,93 @@
+export type ValidateOnEvent = 'input' | 'change' | 'blur';
+export type FieldBinding<V> = {
+    name: string;
+    value: V;
+    error: boolean;
+    on: {
+        input: (v: V) => void;
+        change: (v: V) => void;
+        blur: () => void;
+    };
+};
 import type { FormValidationHandler } from '../../core/validation';
 import type { Snippet } from 'svelte';
-declare function $$render<T extends Record<string, unknown>>(): {
+declare function $$render<T extends Record<string, unknown>, K extends keyof T & string>(): {
     props: {
-        /** Field name in the form handler */
-        name: keyof T & string;
-        /** Form validation handler instance */
+        /** Form validation handler instance. */
         handler: FormValidationHandler<T>;
-        /** Show errors even if field was not touched */
+        /** Field name in the form handler. */
+        name: K;
+        /**
+         * Which events trigger validation. Value is always updated synchronously on `input`/`change`
+         * regardless of this option — it only controls when the validator runs.
+         * @default ['input', 'change', 'blur']
+         */
+        validateOn?: ValidateOnEvent[];
+        /**
+         * Debounce validator calls in ms. Value update stays sync; only validation is delayed.
+         * @default 0
+         */
+        debounceMs?: number;
+        /** Show errors even when the field has not been touched. @default false */
         disableTouchedTracking?: boolean;
-        children: Snippet;
+        /**
+         * Extra consumer callbacks. Run AFTER the validation wiring; they cannot override it.
+         * The `children` snippet always receives fully-wired `field.on.*`.
+         */
+        on?: {
+            input?: (value: T[K]) => void;
+            change?: (value: T[K]) => void;
+            blur?: () => void;
+        };
+        /** Receives a wired `FieldBinding<T[K]>` to spread into a kit input. */
+        children: Snippet<[FieldBinding<T[K]>]>;
     };
     exports: {};
     bindings: "";
     slots: {};
     events: {};
 };
-declare class __sveltets_Render<T extends Record<string, unknown>> {
-    props(): ReturnType<typeof $$render<T>>['props'];
-    events(): ReturnType<typeof $$render<T>>['events'];
-    slots(): ReturnType<typeof $$render<T>>['slots'];
+declare class __sveltets_Render<T extends Record<string, unknown>, K extends keyof T & string> {
+    props(): ReturnType<typeof $$render<T, K>>['props'];
+    events(): ReturnType<typeof $$render<T, K>>['events'];
+    slots(): ReturnType<typeof $$render<T, K>>['slots'];
     bindings(): "";
     exports(): {};
 }
 interface $$IsomorphicComponent {
-    new <T extends Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
-        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
-    } & ReturnType<__sveltets_Render<T>['exports']>;
-    <T extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
-    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+    new <T extends Record<string, unknown>, K extends keyof T & string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, K>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, K>['props']>, ReturnType<__sveltets_Render<T, K>['events']>, ReturnType<__sveltets_Render<T, K>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, K>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, K>['exports']>;
+    <T extends Record<string, unknown>, K extends keyof T & string>(internal: unknown, props: ReturnType<__sveltets_Render<T, K>['props']> & {}): ReturnType<__sveltets_Render<T, K>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
 }
 /**
- * Wraps a form field and displays validation errors from a FormValidationHandler.
+ * Binds a form field to any kit input via a render-prop snippet. The base inputs stay unchanged;
+ * `Validatable` is the only place that knows about `FormValidationHandler`. Wraps children in an
+ * internal `FieldError` frame that reserves space for the error message so toggling doesn't shift
+ * layout.
+ *
+ * ### Usage
+ * ```svelte
+ * <Validatable {handler} name="email">
+ * {#snippet children(field)}
+ *   <Input {...field} placeholder="Email" />
+ * {/snippet}
+ * </Validatable>
+ * ```
+ *
+ * The snippet argument has shape `{ name, value, error, on: { input, change, blur } }` — the
+ * minimal interface every kit input supports. Inputs whose primary value prop is not `value`
+ * (e.g. `Checkbox` uses `checked`) wire the field explicitly inside the snippet.
+ *
+ * ### Validation events
+ * `validateOn` accepts an array. Default `['input', 'change', 'blur']` validates on every event.
+ * Pass `['blur']` for blur-only validation, `['change', 'blur']` for the classic "validate on commit" pattern.
  *
- * ### CSS Custom Properties
- * | Property | Description | Default |
- * |---|---|---|
- * | `--sc-kit--validatable--error--color` | Error text and accent color | destructive-500 |
- * | `--sc-kit--validatable--error--position` | Error message positioning | `absolute` |
- * | `--sc-kit--validatable--error--left` | Error left offset | `0` |
- * | `--sc-kit--validatable--error--right` | Error right offset | `0` |
- * | `--sc-kit--validatable--margin-bottom` | Bottom margin for spacing | `1.1em` |
- * | `--sc-kit--validatable--margin-right` | Right margin for spacing | `0` |
- * | `--sc-kit--validatable--display` | Display mode | `block` |
- * | `--sc-kit--validatable--width` | Container width | `auto` |
+ * ### Consumer callbacks
+ * Pass extra callbacks via `Validatable`'s own `on={...}` — they run AFTER the validation wiring
+ * and cannot override it.
  */
 declare const Cmp: $$IsomorphicComponent;
-type Cmp<T extends Record<string, unknown>> = InstanceType<typeof Cmp<T>>;
+type Cmp<T extends Record<string, unknown>, K extends keyof T & string> = InstanceType<typeof Cmp<T, K>>;
 export default Cmp;

package/dist/ui/validatable/cmp.validation-error.svelte

@@ -1,52 +1,15 @@
-<script lang="ts" generics="T extends Record<string, unknown>">let { name, validationResult, children } = $props();
-const showErrors = $derived(validationResult?.errors[name]);
-export {};
+<script lang="ts" generics="T extends Record<string, unknown>">import { default as FieldError } from './cmp.field-error.svelte';
+let { name, validationResult, children } = $props();
+const errorText = $derived(validationResult?.errors[name] ?? null);
 </script>
 
-<div class="validatable" class:validatable--errored={showErrors}>
+<FieldError error={errorText}>
   {@render children()}
-  {#if showErrors}
-    <small class="validatable__error">{validationResult!.errors[name]}</small>
-  {/if}
-</div>
+</FieldError>
 
 <!--
 @component
-Wraps a form field and displays validation errors from a FormValidateResult object.
-
-### CSS Custom Properties
-| Property | Description | Default |
-|---|---|---|
-| `--sc-kit--validatable--error--color` | Error text and accent color | destructive-500 |
-| `--sc-kit--validatable--error--position` | Error message positioning | `absolute` |
-| `--sc-kit--validatable--margin-bottom` | Bottom margin for spacing | `1.1em` |
+Wraps a form field and displays validation errors from a `FormValidateResult` object. Stateless
+sibling of `Validatable` for cases where the consumer already has the validation result in hand
+(e.g. server-validated forms) and does not need a `FormValidationHandler`.
 -->
-
-<style>.validatable {
-  --_validatable--error--color: var(--sc-kit--validatable--error--color, #e71d36);
-  --_validatable--error--position: var(--sc-kit--validatable--error--position, absolute);
-  --_validatable--error--left: var(--sc-kit--validatable--error--left, 0);
-  --_validatable--error--right: var(--sc-kit--validatable--error--right, 0);
-  --_validatable--margin-bottom: var(--sc-kit--validatable--margin-bottom, 1.1em);
-  --_validatable--margin-right: var(--sc-kit--validatable--margin-right, 0);
-  --_validatable--display: var(--sc-kit--validatable--display, block);
-  --_validatable--width: var(--sc-kit--validatable--width, auto);
-  position: relative;
-  margin-bottom: var(--_validatable--margin-bottom);
-  margin-right: var(--_validatable--margin-right);
-  display: var(--_validatable--display);
-  width: var(--_validatable--width);
-}
-.validatable--errored {
-  --_input--explicit-shadow-color: var(--_validatable--error--color);
-}
-.validatable__error {
-  position: var(--_validatable--error--position);
-  top: calc(100% + 0.1em);
-  left: var(--_validatable--error--left);
-  right: var(--_validatable--error--right);
-  display: block;
-  color: var(--_validatable--error--color);
-  font-size: 0.7rem;
-  font-weight: 400;
-}</style>

package/dist/ui/validatable/cmp.validation-error.svelte.d.ts

@@ -28,14 +28,9 @@ interface $$IsomorphicComponent {
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 /**
- * Wraps a form field and displays validation errors from a FormValidateResult object.
- *
- * ### CSS Custom Properties
- * | Property | Description | Default |
- * |---|---|---|
- * | `--sc-kit--validatable--error--color` | Error text and accent color | destructive-500 |
- * | `--sc-kit--validatable--error--position` | Error message positioning | `absolute` |
- * | `--sc-kit--validatable--margin-bottom` | Bottom margin for spacing | `1.1em` |
+ * Wraps a form field and displays validation errors from a `FormValidateResult` object. Stateless
+ * sibling of `Validatable` for cases where the consumer already has the validation result in hand
+ * (e.g. server-validated forms) and does not need a `FormValidationHandler`.
  */
 declare const Cmp: $$IsomorphicComponent;
 type Cmp<T extends Record<string, unknown>> = InstanceType<typeof Cmp<T>>;

package/dist/ui/validatable/index.d.ts

@@ -1,2 +1,3 @@
 export { default as Validatable } from './cmp.validatable.svelte';
+export type { FieldBinding, ValidateOnEvent } from './cmp.validatable.svelte';
 export { default as ValidationError } from './cmp.validation-error.svelte';

package/dist/ui/video/cmp.video.svelte

@@ -261,20 +261,20 @@ const handleSeek = (percent) => {
     role="none">
     {#if isVideoPaused && !hidePlayButton}
       <button type="button" aria-label="play" class="video__playback-button" onclick={togglePlay} onkeydown={() => ({})}>
-        <Icon src={IconPlay} color="white" />
+        <Icon src={IconPlay} color="on-accent" />
       </button>
     {:else if showControlsOnHover && !hidePlayButton}
       <button type="button" aria-label="pause" class="video__playback-button video__playback-button--pause" onclick={togglePlay} onkeydown={() => ({})}>
-        <Icon src={IconPause} color="white" />
+        <Icon src={IconPause} color="on-accent" />
       </button>
     {/if}
 
     {#if (showControlsOnHover || MediaVolumeManager.isMuted) && !hideSpeaker}
       <button type="button" aria-label={MediaVolumeManager.isMuted ? 'mute' : 'unmute'} class="video__mute-button" onclick={toggleMute}>
         {#if MediaVolumeManager.isMuted}
-          <Icon src={IconSpeakerMute} color="white" />
+          <Icon src={IconSpeakerMute} color="on-accent" />
         {:else}
-          <Icon src={IconSpeaker} color="white" />
+          <Icon src={IconSpeaker} color="on-accent" />
         {/if}
       </button>
     {/if}
@@ -316,7 +316,7 @@ A full-featured video player with custom overlay controls, play/pause, mute, see
 -->
 
 <style>.video {
-  --_video--background-color: var(--sc-kit--video--background-color, #000000);
+  --_video--background-color: var(--sc-kit--video--background-color, #000);
   --_video--border-radius: var(--sc-kit--video--border-radius, 0);
   --_video--media-fit: var(--sc-kit--video--media-fit, contain);
   --_video--poster--media-fit: var(--sc-kit--video--poster--media-fit, cover);
@@ -334,7 +334,7 @@ A full-featured video player with custom overlay controls, play/pause, mute, see
 }
 .video__playback-button {
   --sc-kit--icon--size: 2.5rem;
-  --sc-kit--icon--filter: drop-shadow(1px 1px #000000);
+  --sc-kit--icon--filter: drop-shadow(1px 1px #000);
   position: absolute;
   top: 50%;
   left: 50%;
@@ -350,7 +350,7 @@ A full-featured video player with custom overlay controls, play/pause, mute, see
 }
 .video__mute-button {
   --sc-kit--icon--size: 1.25rem;
-  --sc-kit--icon--filter: drop-shadow(1px 1px #000000);
+  --sc-kit--icon--filter: drop-shadow(1px 1px #000);
   position: absolute;
   top: 0.625em;
   right: 0.625em;

package/dist/ui/visual-select/cmp.visual-select.svelte

@@ -0,0 +1,154 @@
+<script lang="ts" generics="T">import { Icon } from '../icon';
+const { options, cols = 3, disabled = false, compare, ...mode } = $props();
+const eq = (a, b) => (compare ? compare(a, b) : a === b);
+const isSelected = (o) => {
+    if (mode.multi) {
+        return mode.value.some((v) => eq(v, o.value));
+    }
+    return mode.value !== null && eq(mode.value, o.value);
+};
+const toggle = (o) => {
+    if (disabled || o.disabled) {
+        return;
+    }
+    if (mode.multi) {
+        const arr = mode.value;
+        const next = arr.some((v) => eq(v, o.value)) ? arr.filter((v) => !eq(v, o.value)) : [...arr, o.value];
+        mode.on?.change?.(next);
+    }
+    else {
+        const next = mode.value !== null && eq(mode.value, o.value) ? null : o.value;
+        mode.on?.change?.(next);
+    }
+};
+</script>
+
+<div class="visual-select" class:visual-select--disabled={disabled} style:--_cols={cols} role={mode.multi ? 'group' : 'radiogroup'}>
+  {#each options as o (o.value)}
+    {@const selected = isSelected(o)}
+    <button
+      type="button"
+      class="visual-select__tile"
+      class:visual-select__tile--selected={selected}
+      class:visual-select__tile--disabled={o.disabled}
+      role={mode.multi ? 'checkbox' : 'radio'}
+      aria-checked={selected}
+      aria-label={o.label}
+      disabled={disabled || o.disabled}
+      onclick={() => toggle(o)}>
+      <span class="visual-select__thumb">
+        {#if typeof o.graphic === 'string'}
+          <Icon src={o.graphic} />
+        {:else}
+          {@render o.graphic()}
+        {/if}
+      </span>
+      <span class="visual-select__label">{o.label}</span>
+    </button>
+  {/each}
+</div>
+
+<!--
+@component
+Card-radio (or card-checkbox via `multi`) group. Each tile shows a small graphic above an
+uppercase label. Graphics render with `fill="currentColor"` so they shift from muted gray to
+accent when the tile becomes selected. Selection state recolors the tile's border + background
+and lifts the thumb to a panel background with an accent foreground.
+
+### CSS Custom Properties
+| Property | Description | Default |
+|---|---|---|
+| `--sc-kit--visual-select--tile-width` | Fixed tile width | `120px` |
+| `--sc-kit--visual-select--gap` | Gap between tiles | `var(--sc-kit--space--2)` |
+| `--sc-kit--visual-select--tile--background` | Tile background (unselected) | `var(--sc-kit--color--bg--panel)` |
+| `--sc-kit--visual-select--tile--background--selected` | Tile background when selected | `var(--sc-kit--color--accent--softer)` |
+| `--sc-kit--visual-select--tile--border-color` | Tile border (unselected) | `var(--sc-kit--color--border--field)` |
+| `--sc-kit--visual-select--tile--border-color--hover` | Tile border on hover | `var(--sc-kit--color--border--strong)` |
+| `--sc-kit--visual-select--tile--border-color--selected` | Tile border when selected | `var(--sc-kit--color--accent)` |
+| `--sc-kit--visual-select--thumb--background` | Thumb background (unselected) | `var(--sc-kit--color--bg--active)` |
+| `--sc-kit--visual-select--thumb--background--selected` | Thumb background when selected | `var(--sc-kit--color--bg--panel)` |
+| `--sc-kit--visual-select--thumb--color` | Graphic color (unselected) | `var(--sc-kit--color--text--muted)` |
+| `--sc-kit--visual-select--thumb--color--selected` | Graphic color when selected | `var(--sc-kit--color--accent)` |
+| `--sc-kit--visual-select--label--color` | Label color (unselected) | `var(--sc-kit--color--text--secondary)` |
+| `--sc-kit--visual-select--label--color--selected` | Label color when selected | `var(--sc-kit--color--text--primary)` |
+-->
+
+<style>.visual-select {
+  --_vs--tile-width: var(--sc-kit--visual-select--tile-width, 7.5rem);
+  --_vs--gap: var(--sc-kit--visual-select--gap, var(--sc-kit--space--2));
+  --_vs--tile-background: var(--sc-kit--visual-select--tile--background, var(--sc-kit--color--bg--panel));
+  --_vs--tile-background-selected: var(--sc-kit--visual-select--tile--background--selected, var(--sc-kit--color--accent--softer));
+  --_vs--tile-border-color: var(--sc-kit--visual-select--tile--border-color, var(--sc-kit--color--border--field));
+  --_vs--tile-border-color-hover: var(--sc-kit--visual-select--tile--border-color--hover, var(--sc-kit--color--border--strong));
+  --_vs--tile-border-color-selected: var(--sc-kit--visual-select--tile--border-color--selected, var(--sc-kit--color--accent));
+  --_vs--thumb-background: var(--sc-kit--visual-select--thumb--background, var(--sc-kit--color--bg--active));
+  --_vs--thumb-background-selected: var(--sc-kit--visual-select--thumb--background--selected, var(--sc-kit--color--bg--panel));
+  --_vs--thumb-color: var(--sc-kit--visual-select--thumb--color, var(--sc-kit--color--text--muted));
+  --_vs--thumb-color-selected: var(--sc-kit--visual-select--thumb--color--selected, var(--sc-kit--color--accent));
+  --_vs--label-color: var(--sc-kit--visual-select--label--color, var(--sc-kit--color--text--secondary));
+  --_vs--label-color-selected: var(--sc-kit--visual-select--label--color--selected, var(--sc-kit--color--text--primary));
+  display: grid;
+  grid-template-columns: repeat(var(--_cols, 3), var(--_vs--tile-width));
+  gap: var(--_vs--gap);
+  width: fit-content;
+  max-width: 100%;
+}
+.visual-select--disabled {
+  opacity: 0.6;
+  pointer-events: none;
+}
+.visual-select__tile {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--sc-kit--space--1);
+  padding: var(--sc-kit--space--2);
+  background: var(--_vs--tile-background);
+  border: 1px solid var(--_vs--tile-border-color);
+  border-radius: var(--sc-kit--radius--md);
+  cursor: pointer;
+  font-family: inherit;
+  transition: border-color var(--sc-kit--duration--base) var(--sc-kit--ease--default), background-color var(--sc-kit--duration--base) var(--sc-kit--ease--default);
+}
+.visual-select__tile:hover:not(:disabled):not(.visual-select__tile--selected) {
+  border-color: var(--_vs--tile-border-color-hover);
+}
+.visual-select__tile:focus-visible {
+  outline: 2px solid var(--sc-kit--color--border--focus);
+  outline-offset: 2px;
+}
+.visual-select__tile--selected {
+  background: var(--_vs--tile-background-selected);
+  border-color: var(--_vs--tile-border-color-selected);
+}
+.visual-select__tile--disabled, .visual-select__tile:disabled {
+  cursor: default;
+}
+.visual-select__thumb {
+  --sc-kit--icon--color: currentColor;
+  width: 100%;
+  height: 2.25rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--_vs--thumb-background);
+  border-radius: var(--sc-kit--radius--sm);
+  color: var(--_vs--thumb-color);
+  transition: background-color var(--sc-kit--duration--base) var(--sc-kit--ease--default), color var(--sc-kit--duration--base) var(--sc-kit--ease--default), box-shadow var(--sc-kit--duration--base) var(--sc-kit--ease--default);
+}
+.visual-select__tile--selected .visual-select__thumb {
+  background: var(--_vs--thumb-background-selected);
+  color: var(--_vs--thumb-color-selected);
+  box-shadow: inset 0 0 0 1px var(--sc-kit--color--border);
+}
+.visual-select__label {
+  font-size: var(--sc-kit--font-size--xs);
+  font-weight: var(--sc-kit--font-weight--medium);
+  letter-spacing: var(--sc-kit--letter-spacing--wide);
+  color: var(--_vs--label-color);
+  text-transform: uppercase;
+  line-height: var(--sc-kit--leading--tight);
+}
+.visual-select__tile--selected .visual-select__label {
+  color: var(--_vs--label-color-selected);
+}</style>