@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/color-field/color-field.svelte

@@ -0,0 +1,396 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+import { parseColor } from '../../utilities/color-luminance.ts';
+import Input from '../input/input.svelte';
+let { id, class: className, value, defaultValue, alpha = false, formats = ['hex', 'rgb', 'hsl'], disabled = false, required = false, readonly = false, name, placeholder, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, errorMessage, enterBehavior = 'commit-then-submit', onchange, } = $props();
+// Mode is captured once at mount. Runtime mode switches are unsupported.
+// Read untracked: the mode discriminant must not become a reactive dependency.
+const isControlled = untrack(() => value) !== undefined;
+let visibleText = $state('');
+let committedHex = $state('');
+let committedRgba = $state(null);
+let parseError = $state(null);
+let anchorInput = $state(null);
+// Plain (non-reactive) skip guard for the controlled-sync effect — matches
+// color-picker's `lastEmittedHex`. Used to short-circuit reconciliation when
+// the observed value equals the last value we already reconciled.
+let lastReconciledValue = '';
+function toHex2(n) {
+    return Math.max(0, Math.min(255, Math.round(n)))
+        .toString(16)
+        .padStart(2, '0');
+}
+function normalizeHex(parts, emitAlpha) {
+    const base = `#${toHex2(parts.r)}${toHex2(parts.g)}${toHex2(parts.b)}`;
+    if (emitAlpha)
+        return base + toHex2(parts.a * 255);
+    return base;
+}
+// Emit rule: emit `#rrggbbaa` only when `alpha === true` AND parsed `a < 1`.
+function emitFor(parts) {
+    return normalizeHex(parts, alpha && parts.a < 1);
+}
+const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]([0-9a-f]{2})?([0-9a-f]{2})?)?$/i;
+const RGB_RE = /^rgba?\s*\([^)]*\)\s*$/i;
+const HSL_RE = /^hsla?\s*\([^)]*\)\s*$/i;
+const DEFAULT_FORMATS = ['hex', 'rgb', 'hsl'];
+const acceptedFormats = $derived(formats.length === 0 ? DEFAULT_FORMATS : formats);
+function passesFormatGate(text) {
+    if (HEX_RE.test(text))
+        return acceptedFormats.includes('hex');
+    if (RGB_RE.test(text))
+        return acceptedFormats.includes('rgb');
+    if (HSL_RE.test(text))
+        return acceptedFormats.includes('hsl');
+    return false;
+}
+function defaultErrorMessage() {
+    if (errorMessage !== undefined)
+        return errorMessage;
+    const labels = {
+        hex: 'hex',
+        rgb: 'rgb()',
+        hsl: 'hsl()',
+    };
+    const accepted = acceptedFormats.map((format) => labels[format]);
+    if (accepted.length === 1)
+        return `Enter a valid ${accepted[0]} color.`;
+    if (accepted.length === 2)
+        return `Enter a valid ${accepted[0]} or ${accepted[1]} color.`;
+    return `Enter a valid ${accepted.slice(0, -1).join(', ')}, or ${accepted.at(-1)} color.`;
+}
+function seedFromParts(parts) {
+    committedRgba = parts;
+    committedHex = emitFor(parts);
+    visibleText = committedHex;
+}
+function clearAll() {
+    committedRgba = null;
+    committedHex = '';
+    visibleText = '';
+}
+// ── Initialization ──────────────────────────────────────────────────────
+// Snapshot the seed props once. Initialization reads only the mount-time
+// value; the controlled-sync effect (below) handles later prop changes.
+const initialValue = untrack(() => value);
+const initialDefaultValue = untrack(() => defaultValue);
+if (isControlled) {
+    if (initialValue !== undefined && initialValue !== '') {
+        const trimmedInitial = initialValue.trim();
+        if (trimmedInitial !== '' && passesFormatGate(trimmedInitial)) {
+            const parsed = parseColor(trimmedInitial);
+            if (parsed !== null) {
+                seedFromParts(parsed);
+                lastReconciledValue = initialValue;
+            }
+            else {
+                visibleText = initialValue;
+                committedHex = '';
+                committedRgba = null;
+                parseError = defaultErrorMessage();
+            }
+        }
+        else {
+            // Externally-supplied value violates the `formats` gate — preserve the
+            // visible text verbatim and surface a parse error, matching the
+            // documented contract.
+            visibleText = initialValue;
+            committedHex = '';
+            committedRgba = null;
+            parseError = defaultErrorMessage();
+        }
+    }
+}
+else if (initialDefaultValue !== undefined && initialDefaultValue !== '') {
+    const trimmedDefault = initialDefaultValue.trim();
+    if (trimmedDefault !== '' && passesFormatGate(trimmedDefault)) {
+        const parsed = parseColor(trimmedDefault);
+        if (parsed !== null) {
+            seedFromParts(parsed);
+        }
+    }
+}
+// ── Controlled sync ─────────────────────────────────────────────────────
+function reconcileFromValue(next) {
+    const trimmed = next.trim();
+    if (trimmed === '') {
+        clearAll();
+        parseError = null;
+    }
+    else if (!passesFormatGate(trimmed)) {
+        visibleText = next;
+        committedHex = '';
+        committedRgba = null;
+        parseError = defaultErrorMessage();
+    }
+    else {
+        const parsed = parseColor(trimmed);
+        if (parsed === null) {
+            visibleText = next;
+            committedHex = '';
+            committedRgba = null;
+            parseError = defaultErrorMessage();
+        }
+        else {
+            seedFromParts(parsed);
+            parseError = null;
+        }
+    }
+    // Keep native validity in lockstep with parseError through this single
+    // synchronous path — replaces the prior `void parseError` effect that
+    // lagged one microtask behind controlled-sync and alpha-toggle writes.
+    syncCustomValidity();
+}
+$effect(() => {
+    if (!isControlled)
+        return;
+    if (value === undefined) {
+        devWarn('[cinder/ColorField] runtime mode switch ignored (controlled -> undefined)');
+        return;
+    }
+    if (value === lastReconciledValue)
+        return;
+    lastReconciledValue = value;
+    reconcileFromValue(value);
+});
+// ── alpha runtime changes ───────────────────────────────────────────────
+// Re-derive `committedHex` and `visibleText` from `committedRgba` when the
+// alpha mode toggles after mount. In controlled mode the parent's value is
+// canonical — derive from there. Never emit `onchange` on a config change.
+$effect(() => {
+    void alpha;
+    if (isControlled) {
+        // Controlled mode: re-run reconcile against the current controlled value
+        // so the `formats` gate and parse-error surfacing stay in effect.
+        if (value !== undefined)
+            reconcileFromValue(value);
+        return;
+    }
+    // Uncontrolled mode: re-derive from preserved committedRgba.
+    if (committedRgba === null)
+        return;
+    const nextHex = emitFor(committedRgba);
+    if (nextHex === committedHex)
+        return;
+    committedHex = nextHex;
+    visibleText = nextHex;
+});
+// ── formats runtime changes — display-only validation ───────────────────
+// A `formats` change only affects the input-time gate. It must never mutate
+// committed state. If there's a current parse error, re-run the gate on the
+// visible text and clear the error when the value now passes. `passesFormatGate`
+// and `defaultErrorMessage` both read `acceptedFormats` through closure, so the
+// effect re-runs on `formats` changes without an explicit dependency pin.
+$effect(() => {
+    if (parseError === null)
+        return;
+    const text = visibleText.trim();
+    if (text === '') {
+        parseError = null;
+    }
+    else if (!passesFormatGate(text)) {
+        // Refresh the message so its wording reflects the new `formats` set,
+        // not the wording that was current when the error was first raised.
+        parseError = defaultErrorMessage();
+    }
+    else {
+        const parsed = parseColor(text);
+        parseError = parsed === null ? defaultErrorMessage() : null;
+    }
+    syncCustomValidity();
+});
+// ── Commit pipeline (blur + Enter) ──────────────────────────────────────
+function runCommit() {
+    const trimmed = visibleText.trim();
+    if (trimmed === '') {
+        const hadCommitted = committedHex !== '';
+        const hadError = parseError !== null;
+        clearAll();
+        parseError = null;
+        if (hadCommitted) {
+            onchange?.('');
+            return { committed: true, emittedHex: '' };
+        }
+        return { committed: hadError, emittedHex: null };
+    }
+    // Canonical-display bypass: typing the existing committed hex back in is a no-op.
+    if (trimmed === committedHex) {
+        visibleText = committedHex;
+        parseError = null;
+        return { committed: false, emittedHex: null };
+    }
+    if (!passesFormatGate(trimmed)) {
+        parseError = defaultErrorMessage();
+        return { committed: false, emittedHex: null };
+    }
+    const parsed = parseColor(trimmed);
+    if (parsed === null) {
+        parseError = defaultErrorMessage();
+        return { committed: false, emittedHex: null };
+    }
+    const normalized = emitFor(parsed);
+    const previousHex = committedHex;
+    parseError = null;
+    visibleText = normalized;
+    if (!isControlled) {
+        // Uncontrolled — always update all three slots so a later alpha toggle
+        // can reconstruct `#rrggbbaa` even if the strip-on-emit hid it.
+        committedRgba = parsed;
+        committedHex = normalized;
+        if (normalized !== previousHex) {
+            onchange?.(normalized);
+            return { committed: true, emittedHex: normalized };
+        }
+        return { committed: true, emittedHex: null };
+    }
+    // Controlled mode — only mutate committedRgba / committedHex when the
+    // emitted value actually changes. Parent authority is strict: alpha not
+    // present in `value` is not retained.
+    if (normalized !== previousHex) {
+        committedRgba = parsed;
+        committedHex = normalized;
+        onchange?.(normalized);
+        return { committed: true, emittedHex: normalized };
+    }
+    return { committed: false, emittedHex: null };
+}
+// Sync the parse-error state into the native input's customValidity so
+// mouse/touch/programmatic submit paths participate in HTML form validation
+// — the Enter handler's manual guard alone is not enough.
+function syncCustomValidity() {
+    if (anchorInput === null)
+        return;
+    // Walk to the wrapper and find the visible input by class. Avoids
+    // getElementById, which is unreliable when tests reuse ids across mounts.
+    const wrapper = anchorInput.closest('.cinder-color-field');
+    if (wrapper === null)
+        return;
+    const nativeInput = wrapper.querySelector('input.cinder-input');
+    if (nativeInput === null)
+        return;
+    nativeInput.setCustomValidity(parseError ?? '');
+}
+function handleBlur() {
+    runCommit();
+    syncCustomValidity();
+}
+function handleKeydown(event) {
+    if (event.key !== 'Enter')
+        return;
+    event.preventDefault();
+    runCommit();
+    syncCustomValidity();
+    if (anchorInput !== null) {
+        // Imperatively sync the hidden mirror's DOM value so a synchronous
+        // requestSubmit sees the canonical hex (or the empty string after a
+        // clear) even before Svelte's reactive binding flushes.
+        anchorInput.value = committedHex;
+    }
+    // Submit when validation succeeded (no parse error), regardless of whether
+    // the canonical hex actually changed. A controlled field that receives the
+    // same normalized value should still let Enter submit the form.
+    if (parseError !== null)
+        return;
+    if (enterBehavior !== 'commit-then-submit')
+        return;
+    const form = anchorInput?.form ?? null;
+    if (form === null)
+        return;
+    const submitter = form.querySelector('button:not([type]):not([disabled]), button[type="submit"]:not([disabled]), input[type="submit"]:not([disabled])');
+    form.requestSubmit(submitter ?? undefined);
+}
+// ── Form reset wiring ───────────────────────────────────────────────────
+function onFormReset() {
+    if (isControlled)
+        return;
+    parseError = null;
+    if (defaultValue === undefined || defaultValue === '') {
+        clearAll();
+        // Sync after all state changes: the catch-all $effect was removed so every
+        // exit path must explicitly clear the native custom-validity message.
+        syncCustomValidity();
+        return;
+    }
+    const trimmedDefault = defaultValue.trim();
+    if (trimmedDefault === '' || !passesFormatGate(trimmedDefault)) {
+        clearAll();
+        syncCustomValidity();
+        return;
+    }
+    const parsed = parseColor(trimmedDefault);
+    if (parsed === null) {
+        clearAll();
+        syncCustomValidity();
+        return;
+    }
+    seedFromParts(parsed);
+    syncCustomValidity();
+}
+$effect(() => {
+    const input = anchorInput;
+    if (input === null)
+        return;
+    const resolvedInput = input;
+    let currentForm = null;
+    function attach() {
+        const nextForm = resolvedInput.form;
+        if (nextForm === currentForm)
+            return;
+        currentForm?.removeEventListener('reset', onFormReset);
+        currentForm = nextForm;
+        currentForm?.addEventListener('reset', onFormReset);
+    }
+    attach();
+    return () => {
+        currentForm?.removeEventListener('reset', onFormReset);
+    };
+});
+// ── Derived display state ───────────────────────────────────────────────
+const swatchEmpty = $derived(committedHex === '');
+const swatchColor = $derived(committedHex === '' ? 'transparent' : committedHex);
+</script>
+
+{#snippet swatch()}
+  <span
+    class="cinder-color-field__swatch"
+    data-cinder-empty={swatchEmpty ? '' : undefined}
+    data-cinder-alpha={alpha ? '' : undefined}
+    aria-hidden="true"
+    style="--cinder-color-field-swatch: {swatchColor};"
+  ></span>
+{/snippet}
+
+<div
+  class={classNames('cinder-color-field', className)}
+  data-cinder-disabled={disabled ? '' : undefined}
+>
+  <Input
+    {id}
+    bind:value={visibleText}
+    {disabled}
+    {required}
+    {readonly}
+    placeholder={placeholder ?? ''}
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledby}
+    error={parseError ?? ''}
+    onblur={handleBlur}
+    onkeydown={handleKeydown}
+    trailing={swatch}
+  />
+
+  <input
+    type="hidden"
+    {name}
+    disabled={disabled || undefined}
+    value={committedHex}
+    bind:this={anchorInput}
+    aria-hidden="true"
+  />
+</div>

package/src/components/color-field/color-field.types.ts

@@ -0,0 +1,60 @@
+/** Accepted *input* color string formats. Output is always hex. */
+export type ColorFieldFormat = 'hex' | 'rgb' | 'hsl';
+
+/** Props for ColorField. */
+export type ColorFieldProps = {
+  /** Inner `<input>` id. Required (mirrors Input). */
+  id: string;
+  /**
+   * Controlled value as a hex string. One-way: parent sets, child reads.
+   * Not bindable — use `onchange` to observe commits. Accepts any color
+   * string the configured `formats` allow when set externally.
+   */
+  value?: string;
+  /** Initial value when uncontrolled. Accepts any allowed `formats` input. */
+  defaultValue?: string;
+  /**
+   * Accept and emit alpha when the parsed value has partial alpha. When
+   * `false` (default), `#RRGGBBAA` and `rgba()`/`hsla()` inputs are parsed
+   * but alpha is stripped on emit.
+   */
+  alpha?: boolean;
+  /** Accepted *input* formats. Defaults to `['hex', 'rgb', 'hsl']`. Output is always hex. */
+  formats?: readonly ColorFieldFormat[];
+  /** Disable the input. */
+  disabled?: boolean;
+  /** Mark the input as required for form submission and a11y. */
+  required?: boolean;
+  /** Render the inner `<input>` as read-only. */
+  readonly?: boolean;
+  /**
+   * Form field name. When set, the hidden mirror input contributes the current
+   * committed hex value to native form submission.
+   */
+  name?: string;
+  /** Placeholder text for the inner `<input>`. */
+  placeholder?: string;
+  /** Accessible label applied directly to the inner `<input>` when no `FormField` wraps it. */
+  'aria-label'?: string;
+  /** Id of an external element that labels the inner `<input>`. */
+  'aria-labelledby'?: string;
+  /** Additional classes merged onto the **outer wrapper** root (`.cinder-color-field`). */
+  class?: string;
+  /** Override the default parse-failure error message. */
+  errorMessage?: string;
+  /**
+   * Commit-on-Enter behavior. Default `'commit-then-submit'`:
+   *   - `'commit-then-submit'`: Enter commits the value, then lets the form's
+   *     native submission proceed via `requestSubmit`.
+   *   - `'commit-only'`: Enter commits and `preventDefault()`s, suppressing
+   *     form submission (useful in dialogs / multi-field flows where Enter
+   *     must not submit).
+   */
+  enterBehavior?: 'commit-then-submit' | 'commit-only';
+  /**
+   * Fires on successful blur-time commit when the canonical hex actually
+   * changes. Value callback by repo convention — not forwarded to the inner
+   * native `<input>`.
+   */
+  onchange?: (value: string) => void;
+};

package/src/components/color-field/color-field.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/color-field/index.ts

@@ -0,0 +1,6 @@
+import './color-field.css';
+import ColorField from './color-field.svelte';
+
+export default ColorField;
+export type { ColorFieldFormat, ColorFieldProps } from './color-field.types.ts';
+export { ColorField };

package/src/components/color-picker/color-picker.schema.ts

@@ -0,0 +1,62 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description:
+        "Bindable value. Reading the value yields a hex string (`#rrggbb`, or\n`#rrggbbaa` when `alpha` is true). Setting the value accepts hex, `rgb()`,\n`rgba()`, `hsl()`, or `hsla()` input; invalid input is normalized to `''`.",
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Initial color when `value` is not bound. Same input formats as `value`.',
+    },
+    alpha: {
+      type: 'boolean',
+      description: 'Enable the alpha slider and emit `#rrggbbaa`. Default `false`.',
+    },
+    name: {
+      type: 'string',
+      description:
+        'Form field name. When set, a hidden input mirrors the current value for form submission.',
+    },
+    swatches: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      description: 'Optional palette of preset colors rendered below the picker.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable interaction across the picker.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional classes merged onto the root element.',
+    },
+    label: {
+      type: 'string',
+      description: "Accessible label for the picker. Default `'Color picker'`.",
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'onchange',
+        reason: 'function-or-snippet',
+        description: 'Fired on commit (pointer up, swatch click, slider key).',
+      },
+      {
+        name: 'oninput',
+        reason: 'function-or-snippet',
+        description: 'Fired on every intermediate update (drag, slider key, swatch click).',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;