@svgrid/grid 1.2.22 → 1.2.24

package/src/SvDateTimePicker.svelte

@@ -0,0 +1,265 @@
+<script lang="ts" module>
+  export type { DateTimeValue } from './createDateTimePicker.svelte'
+</script>
+
+<script lang="ts">
+  /**
+   * SvDateTimePicker - a text input (formatted via the date-format token engine)
+   * plus a dropdown that composes SvCalendar + SvTimePicker behind DATE / TIME
+   * tabs. Parity target: Smart `smart-date-time-picker`. It is a styled renderer
+   * over the headless `createDateTimePicker` core (value math, parse/format,
+   * clamp, dropdown open/tab state, sub-picker wiring); the component keeps the
+   * render-only concerns - the portalled popover positioning (via popover.ts), DOM
+   * refs, and outside-click / reposition listeners - so the dropdown is never
+   * clipped by the grid's scroll container.
+   */
+  import SvCalendar from './SvCalendar.svelte'
+  import SvTimePicker from './SvTimePicker.svelte'
+  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
+  import { createDateTimePicker, type DateTimeValue, type DropDownDisplayMode } from './createDateTimePicker.svelte'
+  import type { DateLike } from './datetime/date-core'
+
+  type Props = {
+    value?: DateTimeValue
+    onChange?: (value: Date | null) => void
+    /** Fired when the value is finalized (Enter, blur, or a single-date pick).
+     *  Used by the grid to save the cell. */
+    onCommit?: (value: Date | null) => void
+    /** Fired on Escape / dismiss without committing (grid cancels the edit). */
+    onCancel?: () => void
+    /** Display / parse mask (token engine). */
+    formatString?: string
+    min?: DateLike | null
+    max?: DateLike | null
+    nullable?: boolean
+    placeholder?: string
+    disabled?: boolean
+    readonly?: boolean
+    name?: string
+    locale?: string
+    firstDayOfWeek?: number
+    weekNumbers?: boolean
+    hourFormat?: '12-hour' | '24-hour'
+    minuteInterval?: number
+    /** Which tabs the dropdown shows. */
+    dropDownDisplayMode?: DropDownDisplayMode
+    /** Up/down spinner buttons that bump the value by `stepMinutes`. */
+    spinButtons?: boolean
+    stepMinutes?: number
+    /** Open the dropdown as soon as the field is focused (grid in-cell editing). */
+    autoOpen?: boolean
+    /** Animate the calendar's month/drill navigation (honors reduced-motion). */
+    animate?: boolean | 'slide' | 'fade'
+  }
+
+  let {
+    value = null,
+    onChange,
+    onCommit,
+    onCancel,
+    formatString = 'yyyy-MM-dd HH:mm',
+    min = null,
+    max = null,
+    nullable = true,
+    placeholder = 'Select date & time',
+    disabled = false,
+    readonly = false,
+    name,
+    locale = typeof navigator !== 'undefined' ? navigator.language : 'en-US',
+    firstDayOfWeek = 0,
+    weekNumbers = false,
+    hourFormat = '24-hour',
+    minuteInterval = 1,
+    dropDownDisplayMode = 'both',
+    spinButtons = false,
+    stepMinutes = 1,
+    autoOpen = false,
+    animate = false,
+  }: Props = $props()
+
+  // The headless core owns value math, parse/format, clamping, the dropdown
+  // open/tab state and the sub-picker wiring. Reactive inputs are getters;
+  // callbacks are closures.
+  const dtp = createDateTimePicker({
+    value: () => value,
+    onChange: (d) => onChange?.(d),
+    onCommit: (d) => onCommit?.(d),
+    onCancel: () => onCancel?.(),
+    formatString: () => formatString,
+    min: () => min,
+    max: () => max,
+    nullable: () => nullable,
+    locale: () => locale,
+    dropDownDisplayMode: () => dropDownDisplayMode,
+    spinButtons: () => spinButtons,
+    stepMinutes: () => stepMinutes,
+    disabled: () => disabled,
+    readonly: () => readonly,
+  })
+
+  // --- Portalled dropdown positioning (DOM-bound; stays in the component) -----
+  let triggerEl = $state<HTMLDivElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let panelRect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+
+  function updatePos() {
+    if (!triggerEl) return
+    panelRect = anchoredRect(triggerEl.getBoundingClientRect(), { estimatedHeight: 360, minWidth: 300 })
+  }
+
+  // Reposition on open + while open (scroll/resize), and dismiss on outside click.
+  $effect(() => {
+    if (!dtp.open) return
+    updatePos()
+    const reposition = () => updatePos()
+    window.addEventListener('scroll', reposition, true)
+    window.addEventListener('resize', reposition)
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as Node | null
+      if (!t) return
+      if (triggerEl?.contains(t) || panelEl?.contains(t)) return
+      dtp.closePanel()
+    }
+    document.addEventListener('pointerdown', onDown, true)
+    return () => {
+      window.removeEventListener('scroll', reposition, true)
+      window.removeEventListener('resize', reposition)
+      document.removeEventListener('pointerdown', onDown, true)
+    }
+  })
+
+  function focusOpen(node: HTMLInputElement) {
+    if (!autoOpen) return
+    node.focus()
+    dtp.openPanel()
+  }
+
+  function onRootFocusOut(e: FocusEvent) {
+    const next = e.relatedTarget as Node | null
+    // Ignore focus moving within the field or into the portalled panel.
+    if (next && (triggerEl?.contains(next) || panelEl?.contains(next))) return
+    onCommit?.(dtp.current)
+  }
+</script>
+
+<div class="sv-dtp" class:sv-dtp--disabled={disabled} onfocusout={onRootFocusOut}>
+  <div class="sv-dtp__field" bind:this={triggerEl}>
+    {#if spinButtons}
+      <div class="sv-dtp__spin">
+        <button {...dtp.spinProps(1)}>▲</button>
+        <button {...dtp.spinProps(-1)}>▼</button>
+      </div>
+    {/if}
+    <input
+      class="sv-dtp__input"
+      bind:value={dtp.text}
+      {placeholder}
+      {...dtp.inputProps()}
+      use:focusOpen
+    />
+    {#if nullable && dtp.current && dtp.isInteractive}
+      <button class="sv-dtp__clear" {...dtp.clearProps()}>&times;</button>
+    {/if}
+    <button class="sv-dtp__toggle" {...dtp.toggleProps()}>
+      <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2" /><path d="M16 2v4M8 2v4M3 10h18" /></svg>
+    </button>
+  </div>
+
+  {#if dtp.open}
+    <div
+      class="sv-dtp__panel"
+      bind:this={panelEl}
+      use:portalToBody
+      style:position="fixed"
+      style:top={`${panelRect.top}px`}
+      style:left={`${panelRect.left}px`}
+      role="dialog"
+      aria-label="Choose date and time"
+    >
+      {#if dtp.showDateTab && dtp.showTimeTab}
+        <div class="sv-dtp__tabs" role="tablist">
+          <button class:is-active={dtp.tab === 'date'} {...dtp.tabProps('date')}>DATE</button>
+          <button class:is-active={dtp.tab === 'time'} {...dtp.tabProps('time')}>TIME</button>
+        </div>
+      {/if}
+      <div class="sv-dtp__body">
+        {#if dtp.tab === 'date' && dtp.showDateTab}
+          <SvCalendar
+            value={dtp.current}
+            selectionMode="one"
+            min={min}
+            max={max}
+            {firstDayOfWeek}
+            {weekNumbers}
+            {locale}
+            {animate}
+            onChange={dtp.onCalendarChange}
+          />
+        {:else if dtp.showTimeTab}
+          <SvTimePicker
+            value={dtp.current}
+            format={hourFormat}
+            {minuteInterval}
+            footer
+            onChange={dtp.onTimeChange}
+          />
+        {/if}
+      </div>
+    </div>
+  {/if}
+
+  {#if name}<input type="hidden" {name} value={dtp.current ? dtp.current.toISOString() : ''} />{/if}
+</div>
+
+<style>
+  .sv-dtp {
+    --_accent: var(--sg-accent, #2563eb);
+    --_bg: var(--sg-input-bg, var(--sg-bg, #fff));
+    --_fg: var(--sg-fg, #0f172a);
+    --_muted: var(--sg-muted, #64748b);
+    --_border: var(--sg-input-border, var(--sg-border, #cbd5e1));
+    --_radius: var(--sg-radius, 8px);
+    display: inline-block; position: relative; width: 240px; color: var(--_fg);
+  }
+  .sv-dtp--disabled { opacity: 0.6; }
+  .sv-dtp__field {
+    display: flex; align-items: center; gap: 2px;
+    background: var(--_bg); border: 1px solid var(--_border); border-radius: var(--_radius);
+    padding: 0 4px 0 0; height: 34px;
+  }
+  .sv-dtp__field:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-dtp__input {
+    flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit;
+    font: inherit; font-size: 13px; padding: 0 8px; height: 100%;
+  }
+  .sv-dtp__spin { display: flex; flex-direction: column; border-right: 1px solid var(--_border); }
+  .sv-dtp__spin button {
+    flex: 1; width: 20px; border: 0; background: none; color: var(--_muted); cursor: pointer;
+    font-size: 7px; line-height: 1; padding: 0;
+  }
+  .sv-dtp__spin button:hover:not(:disabled) { color: var(--_accent); }
+  .sv-dtp__clear, .sv-dtp__toggle {
+    display: grid; place-items: center; width: 26px; height: 26px; flex: none;
+    background: none; border: 0; color: var(--_muted); cursor: pointer; border-radius: 6px;
+  }
+  .sv-dtp__clear { font-size: 17px; line-height: 1; }
+  .sv-dtp__clear:hover, .sv-dtp__toggle:hover { color: var(--_accent); background: color-mix(in srgb, var(--_accent) 10%, transparent); }
+
+  /* Portalled panel - lives under <body>, styled globally. */
+  :global(.sv-dtp__panel) {
+    z-index: 2147483647;
+    background: var(--sg-bg, #fff);
+    border: 1px solid var(--sg-border, #e2e8f0);
+    border-radius: 12px;
+    box-shadow: 0 16px 48px -12px rgba(15, 23, 42, 0.35);
+    overflow: hidden;
+  }
+  :global(.sv-dtp__tabs) { display: flex; border-bottom: 1px solid var(--sg-border, #e2e8f0); }
+  :global(.sv-dtp__tabs button) {
+    flex: 1; padding: 9px; font: inherit; font-size: 11px; font-weight: 700; letter-spacing: 0.04em;
+    background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer;
+    border-bottom: 2px solid transparent;
+  }
+  :global(.sv-dtp__tabs button.is-active) { color: var(--sg-accent, #2563eb); border-bottom-color: var(--sg-accent, #2563eb); }
+  :global(.sv-dtp__body) { display: grid; place-items: center; padding: 8px; }
+</style>

package/src/SvDateTimePicker.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Component tests for SvDateTimePicker: the masked input round-trips through the
+ * token engine, the dropdown portals to <body> with DATE/TIME tabs, and picking
+ * a day preserves the time (and vice versa).
+ */
+import { describe, expect, it, afterEach } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvDateTimePicker from './SvDateTimePicker.svelte'
+
+function mountDtp(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvDateTimePicker, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+// The panel portals to <body>, so query the document, not the mount target.
+const panel = () => document.querySelector<HTMLElement>('.sv-dtp__panel')
+
+afterEach(() => {
+  document.querySelectorAll('.sv-dtp__panel').forEach((n) => n.remove())
+})
+
+describe('SvDateTimePicker input', () => {
+  it('formats the initial value with the mask', () => {
+    const { target, destroy } = mountDtp({ value: new Date(2026, 5, 7, 9, 4), formatString: 'yyyy-MM-dd HH:mm' })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-dtp__input')!
+      expect(input.value).toBe('2026-06-07 09:04')
+    } finally { destroy() }
+  })
+
+  it('parses typed text on blur and emits a Date', () => {
+    let got: Date | null | undefined
+    const { target, destroy } = mountDtp({
+      value: null, formatString: 'yyyy-MM-dd HH:mm', onChange: (d: Date | null) => (got = d),
+    })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-dtp__input')!
+      input.value = '2026-06-07 14:30'
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+      input.dispatchEvent(new FocusEvent('blur'))
+      flushSync()
+      expect(got).toBeInstanceOf(Date)
+      expect(got!.getFullYear()).toBe(2026)
+      expect(got!.getHours()).toBe(14)
+      expect(got!.getMinutes()).toBe(30)
+    } finally { destroy() }
+  })
+
+  it('reverts invalid text back to the last good value', () => {
+    const { target, destroy } = mountDtp({ value: new Date(2026, 5, 7, 9, 0), formatString: 'yyyy-MM-dd HH:mm' })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-dtp__input')!
+      input.value = 'garbage'
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+      input.dispatchEvent(new FocusEvent('blur'))
+      flushSync()
+      expect(input.value).toBe('2026-06-07 09:00')
+    } finally { destroy() }
+  })
+
+  it('clamps to max', () => {
+    let got: Date | null | undefined
+    const { target, destroy } = mountDtp({
+      value: null, formatString: 'yyyy-MM-dd HH:mm', max: new Date(2026, 5, 10, 0, 0),
+      onChange: (d: Date | null) => (got = d),
+    })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-dtp__input')!
+      input.value = '2026-12-31 23:59'
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+      input.dispatchEvent(new FocusEvent('blur'))
+      flushSync()
+      expect(got!.getTime()).toBe(new Date(2026, 5, 10, 0, 0).getTime())
+    } finally { destroy() }
+  })
+
+  it('clear button nulls a nullable value', () => {
+    let got: Date | null | undefined = new Date()
+    const { target, destroy } = mountDtp({
+      value: new Date(2026, 5, 7), nullable: true, onChange: (d: Date | null) => (got = d),
+    })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-dtp__clear')!.click()
+      flushSync()
+      expect(got).toBeNull()
+    } finally { destroy() }
+  })
+})
+
+describe('SvDateTimePicker dropdown', () => {
+  it('opens a portalled panel with DATE and TIME tabs', () => {
+    const { target, destroy } = mountDtp({ value: new Date(2026, 5, 7, 9, 0) })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-dtp__toggle')!.click()
+      flushSync()
+      expect(panel()).not.toBeNull()
+      const tabs = panel()!.querySelectorAll('[role="tab"]')
+      expect(tabs.length).toBe(2)
+      expect(tabs[0]!.textContent).toBe('DATE')
+      expect(tabs[1]!.textContent).toBe('TIME')
+    } finally { destroy() }
+  })
+
+  it('picking a calendar day preserves the time', () => {
+    let got: Date | null | undefined
+    const { target, destroy } = mountDtp({
+      value: new Date(2026, 5, 7, 9, 45), onChange: (d: Date | null) => (got = d),
+    })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-dtp__toggle')!.click()
+      flushSync()
+      const day20 = Array.from(panel()!.querySelectorAll<HTMLButtonElement>('.sv-cal__day')).find(
+        (b) => b.textContent?.trim() === '20' && !b.classList.contains('is-outside'),
+      )!
+      day20.click()
+      flushSync()
+      expect(got!.getDate()).toBe(20)
+      expect(got!.getHours()).toBe(9) // time preserved
+      expect(got!.getMinutes()).toBe(45)
+    } finally { destroy() }
+  })
+
+  it('honors dropDownDisplayMode=calendar (no tabs, calendar only)', () => {
+    const { target, destroy } = mountDtp({ value: new Date(2026, 5, 7), dropDownDisplayMode: 'calendar' })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-dtp__toggle')!.click()
+      flushSync()
+      expect(panel()!.querySelectorAll('[role="tab"]').length).toBe(0)
+      expect(panel()!.querySelector('.sv-cal')).not.toBeNull()
+      expect(panel()!.querySelector('.sv-tp')).toBeNull()
+    } finally { destroy() }
+  })
+})

package/src/SvDropDownList.svelte

@@ -0,0 +1,120 @@
+<script lang="ts">
+  /**
+   * SvDropDownList - a single-select dropdown (trigger button + portalled list,
+   * no typing). Parity: Smart `smart-drop-down-list`. Controlled via `value` +
+   * `onChange`. Popover escapes scroll clipping via popover.ts.
+   *
+   * One styled renderer over the headless `createDropdownList` core (state +
+   * keyboard + ARIA); only portal/measure/scroll render concerns live here.
+   */
+  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
+  import type { ListOption } from './list-option'
+  import { createDropdownList } from './createDropdownList.svelte'
+
+  type Props = {
+    options: ReadonlyArray<ListOption>
+    value?: string | number | null
+    onChange?: (value: string | number) => void
+    placeholder?: string
+    disabled?: boolean
+    name?: string
+    size?: 'sm' | 'md' | 'lg'
+    ariaLabel?: string
+    autoOpen?: boolean
+  }
+
+  let { options, value = null, onChange, placeholder = 'Select…', disabled = false, name, size = 'md', ariaLabel, autoOpen = false }: Props = $props()
+
+  let triggerEl = $state<HTMLButtonElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+
+  const ddl = createDropdownList({
+    options: () => options,
+    value: () => value,
+    onChange: (v) => onChange?.(v),
+    disabled: () => disabled,
+    ariaLabel: () => ariaLabel,
+    focusTrigger: () => triggerEl?.focus(),
+  })
+
+  const selected = $derived(ddl.selected)
+
+  function updatePos() {
+    if (!triggerEl) return
+    rect = anchoredRect(triggerEl.getBoundingClientRect(), { estimatedHeight: Math.min(options.length, 8) * 34 + 8 })
+  }
+
+  $effect(() => {
+    if (!ddl.open) return
+    updatePos()
+    const rp = () => updatePos()
+    window.addEventListener('scroll', rp, true); window.addEventListener('resize', rp)
+    const od = (e: PointerEvent) => { const t = e.target as Node | null; if (t && (triggerEl?.contains(t) || panelEl?.contains(t))) return; ddl.close() }
+    document.addEventListener('pointerdown', od, true)
+    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); document.removeEventListener('pointerdown', od, true) }
+  })
+  // Keep the active option scrolled into view (render concern).
+  $effect(() => {
+    if (!ddl.open) return
+    const i = ddl.activeIndex
+    queueMicrotask(() => panelEl?.querySelector<HTMLElement>(`[data-idx="${i}"]`)?.scrollIntoView({ block: 'nearest' }))
+  })
+  function focusOpen(node: HTMLButtonElement) { if (autoOpen) { node.focus(); ddl.openPanel() } }
+</script>
+
+<button
+  bind:this={triggerEl}
+  class="sv-ddl sv-ddl--{size}"
+  class:is-open={ddl.open}
+  class:is-disabled={disabled}
+  {...ddl.triggerProps()}
+  use:focusOpen
+>
+  <span class="sv-ddl__value" class:is-placeholder={!selected}>{selected?.label ?? placeholder}</span>
+  <svg class="sv-ddl__chev" viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+</button>
+
+{#if ddl.open}
+  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...ddl.listboxProps()}>
+    {#each options as opt, i (opt.value)}
+      <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+      <div
+        class="sv-ddl__opt"
+        class:is-active={ddl.isActive(i)}
+        class:is-selected={ddl.isSelected(opt)}
+        class:is-disabled={opt.disabled}
+        {...ddl.optionProps(i)}
+      >{opt.label}</div>
+    {/each}
+  </div>
+{/if}
+{#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+
+<style>
+  .sv-ddl {
+    --_accent: var(--sg-accent, #2563eb);
+    display: inline-flex; align-items: center; justify-content: space-between; gap: 8px; width: 200px;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a); font: inherit; text-align: left;
+    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
+    padding: 0 10px; cursor: pointer;
+  }
+  .sv-ddl--sm { height: 28px; font-size: 12px; }
+  .sv-ddl--md { height: 34px; font-size: 13px; }
+  .sv-ddl--lg { height: 40px; font-size: 15px; }
+  .sv-ddl.is-open, .sv-ddl:focus-visible { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); outline: none; }
+  .sv-ddl.is-disabled { opacity: 0.6; cursor: not-allowed; }
+  .sv-ddl__value { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sv-ddl__value.is-placeholder { color: var(--sg-muted, #94a3b8); }
+  .sv-ddl__chev { color: var(--sg-muted, #64748b); flex: none; }
+
+  :global(.sv-ddl__panel) {
+    z-index: 2147483647; max-height: 288px; overflow-y: auto; padding: 4px;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px; box-shadow: 0 16px 48px -12px rgba(15,23,42,0.35);
+  }
+  :global(.sv-ddl__opt) { padding: 7px 10px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+  :global(.sv-ddl__opt.is-active) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  :global(.sv-ddl__opt.is-selected) { color: var(--sg-accent, #2563eb); font-weight: 600; }
+  :global(.sv-ddl__opt.is-disabled) { opacity: 0.4; cursor: not-allowed; }
+</style>

package/src/SvForm.svelte

@@ -0,0 +1,147 @@
+<script lang="ts" module>
+  export type FormFieldType =
+    | 'text' | 'email' | 'tel' | 'textarea' | 'number' | 'password'
+    | 'select' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
+
+  export type FormField = {
+    name: string
+    label: string
+    type?: FormFieldType
+    required?: boolean
+    placeholder?: string
+    options?: Array<{ value: string | number; label: string }>
+    /** Return an error message, or null/undefined when valid. */
+    validate?: (value: any, values: Record<string, any>) => string | null | undefined
+    /** Span full width in the grid. */
+    full?: boolean
+  }
+</script>
+
+<script lang="ts">
+  /**
+   * SvForm - a schema-driven form that renders the SvGrid UI-kit controls with
+   * labels, required + custom validation, and a submit handler. Parity: Smart
+   * `smart-form`. Emits `onSubmit(values)` only when valid; `onChange` on edits.
+   */
+  import SvNumberInput from './SvNumberInput.svelte'
+  import SvPasswordInput from './SvPasswordInput.svelte'
+  import SvDropDownList from './SvDropDownList.svelte'
+  import SvCheckBox from './SvCheckBox.svelte'
+  import SvSwitchButton from './SvSwitchButton.svelte'
+  import SvDateTimePicker from './SvDateTimePicker.svelte'
+  import SvColorInput from './SvColorInput.svelte'
+  import SvRating from './SvRating.svelte'
+  import SvButton from './SvButton.svelte'
+
+  type Props = {
+    fields: ReadonlyArray<FormField>
+    initial?: Record<string, any>
+    onSubmit?: (values: Record<string, any>) => void
+    onChange?: (values: Record<string, any>) => void
+    submitLabel?: string
+    /** Columns in the responsive field grid. */
+    columns?: number
+    disabled?: boolean
+  }
+
+  let { fields, initial = {}, onSubmit, onChange, submitLabel = 'Submit', columns = 1, disabled = false }: Props = $props()
+
+  let values = $state<Record<string, any>>({})
+  let errors = $state<Record<string, string>>({})
+  let touched = $state<Record<string, boolean>>({})
+  let seededForm = false
+  $effect(() => { if (!seededForm) { seededForm = true; values = { ...initial } } })
+
+  function setValue(name: string, v: any) {
+    values = { ...values, [name]: v }
+    onChange?.(values)
+    if (touched[name]) validateField(name)
+  }
+
+  function validateField(name: string): boolean {
+    const field = fields.find((f) => f.name === name)
+    if (!field) return true
+    const v = values[name]
+    let err: string | null | undefined = null
+    if (field.required && (v == null || v === '' || (Array.isArray(v) && !v.length))) err = `${field.label} is required`
+    else if (field.validate) err = field.validate(v, values)
+    const next = { ...errors }
+    if (err) next[name] = err
+    else delete next[name]
+    errors = next
+    return !err
+  }
+
+  function submit(e: Event) {
+    e.preventDefault()
+    let ok = true
+    const t: Record<string, boolean> = {}
+    for (const f of fields) { t[f.name] = true; if (!validateField(f.name)) ok = false }
+    touched = t
+    if (ok) onSubmit?.({ ...values })
+  }
+
+  const dateVal = (v: any): Date | null => (v instanceof Date ? v : v ? new Date(v) : null)
+</script>
+
+<form class="sv-form" style:--cols={columns} onsubmit={submit} novalidate>
+  <div class="sv-form__grid">
+    {#each fields as field (field.name)}
+      {@const type = field.type ?? 'text'}
+      <div class="sv-form__field" class:is-full={field.full || columns === 1} class:has-error={errors[field.name]}>
+        {#if type !== 'checkbox' && type !== 'switch'}
+          <label class="sv-form__label" for={`f-${field.name}`}>
+            {field.label}{#if field.required}<span class="sv-form__req" aria-hidden="true"> *</span>{/if}
+          </label>
+        {/if}
+
+        {#if type === 'textarea'}
+          <textarea id={`f-${field.name}`} class="sv-form__control sv-form__textarea" rows="3" {disabled} placeholder={field.placeholder} value={values[field.name] ?? ''} oninput={(e) => setValue(field.name, e.currentTarget.value)} onblur={() => { touched[field.name] = true; validateField(field.name) }}></textarea>
+        {:else if type === 'number'}
+          <SvNumberInput value={values[field.name] ?? null} {disabled} onChange={(v) => setValue(field.name, v)} />
+        {:else if type === 'password'}
+          <SvPasswordInput value={values[field.name] ?? ''} {disabled} onChange={(v) => setValue(field.name, v)} />
+        {:else if type === 'select'}
+          <SvDropDownList options={field.options ?? []} value={values[field.name] ?? null} {disabled} placeholder={field.placeholder} onChange={(v) => setValue(field.name, v)} />
+        {:else if type === 'checkbox'}
+          <SvCheckBox checked={!!values[field.name]} {disabled} onChange={(v) => setValue(field.name, v)}>{field.label}</SvCheckBox>
+        {:else if type === 'switch'}
+          <div class="sv-form__inline"><SvSwitchButton checked={!!values[field.name]} {disabled} onChange={(v) => setValue(field.name, v)} ariaLabel={field.label} /><span>{field.label}</span></div>
+        {:else if type === 'date'}
+          <SvDateTimePicker value={dateVal(values[field.name])} dropDownDisplayMode="calendar" formatString="yyyy-MM-dd" {disabled} onChange={(v) => setValue(field.name, v)} />
+        {:else if type === 'color'}
+          <SvColorInput value={values[field.name] ?? '#3b82f6'} {disabled} onChange={(v) => setValue(field.name, v)} />
+        {:else if type === 'rating'}
+          <SvRating value={values[field.name] ?? 0} {disabled} onChange={(v) => setValue(field.name, v)} />
+        {:else}
+          <input id={`f-${field.name}`} class="sv-form__control" type={type} {disabled} placeholder={field.placeholder} value={values[field.name] ?? ''} oninput={(e) => setValue(field.name, e.currentTarget.value)} onblur={() => { touched[field.name] = true; validateField(field.name) }} />
+        {/if}
+
+        {#if errors[field.name]}<span class="sv-form__error" role="alert">{errors[field.name]}</span>{/if}
+      </div>
+    {/each}
+  </div>
+  <div class="sv-form__actions">
+    <SvButton type="submit" {disabled}>{submitLabel}</SvButton>
+  </div>
+</form>
+
+<style>
+  .sv-form { --_accent: var(--sg-accent, #2563eb); width: 100%; }
+  .sv-form__grid { display: grid; grid-template-columns: repeat(var(--cols, 1), minmax(0, 1fr)); gap: 14px 18px; }
+  .sv-form__field { display: flex; flex-direction: column; gap: 5px; }
+  .sv-form__field.is-full { grid-column: 1 / -1; }
+  .sv-form__label { font-size: 12.5px; font-weight: 600; color: var(--sg-fg, #0f172a); }
+  .sv-form__req { color: var(--sg-danger, #dc2626); }
+  .sv-form__control {
+    width: 100%; box-sizing: border-box; height: 34px; padding: 0 10px; font: inherit; font-size: 13px;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px); outline: none;
+  }
+  .sv-form__textarea { height: auto; padding: 8px 10px; resize: vertical; }
+  .sv-form__control:focus { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-form__field.has-error .sv-form__control { border-color: var(--sg-danger, #dc2626); }
+  .sv-form__inline { display: flex; align-items: center; gap: 8px; font-size: 13px; }
+  .sv-form__error { font-size: 11.5px; color: var(--sg-danger, #dc2626); }
+  .sv-form__actions { margin-top: 16px; }
+</style>