@svgrid/grid 1.2.34 → 2.0.1

package/src/SvDropDownList.svelte

@@ -7,23 +7,57 @@
    * 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 { flushSync } from 'svelte'
+  import { anchoredRect, portalToBody, popIn, type AnchoredRect } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
+  import { groupOptions, hasGroups, type ListOption } from './list-option'
+  import { virtualRange, scrollToIndex } from './virtual'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, type SvEditorProps } from './editor-contract'
   import { createDropdownList } from './createDropdownList.svelte'
 
-  type Props = {
+  type Props = SvEditorProps & {
     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
+    /** Window the option list (render only visible) for large sets. */
+    virtual?: boolean
+    /** Fixed option height in px (must match the CSS). Default 34. */
+    rowHeight?: number
   }
 
-  let { options, value = null, onChange, placeholder = 'Select…', disabled = false, name, size = 'md', ariaLabel, autoOpen = false }: Props = $props()
+  let {
+    options,
+    value = null,
+    onChange,
+    placeholder = 'Select…',
+    disabled = false,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    autoOpen = false,
+    virtual = false,
+    rowHeight = 34,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-ddl')
+  const uid = $derived(id ?? autoId)
+
+  // Virtualization applies to a flat (ungrouped) list.
+  const useVirtual = $derived(virtual && !hasGroups(options))
+  let scrollTop = $state(0)
+  let viewportH = $state(0)
+  const vr = $derived(virtualRange({ scrollTop, viewportHeight: viewportH, rowHeight, count: options.length, overscan: 10 }))
+  const windowed = $derived(useVirtual ? options.slice(vr.start, vr.end).map((o, i) => ({ ...o, index: vr.start + i })) : [])
 
   let triggerEl = $state<HTMLButtonElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
@@ -36,6 +70,11 @@
     disabled: () => disabled,
     ariaLabel: () => ariaLabel,
     focusTrigger: () => triggerEl?.focus(),
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
   })
 
   const selected = $derived(ddl.selected)
@@ -50,43 +89,74 @@
     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) }
+    // Outside-pointer dismissal via the shared layer stack (Escape stays with
+    // the core keyboard handler). Because this layer is pushed ON TOP, a
+    // dropdown opened inside a dialog/drawer closes itself first and never
+    // dismisses the dialog underneath it.
+    const layer = createDismissableLayer({
+      element: () => [triggerEl, panelEl],
+      onDismiss: () => ddl.close(),
+      closeOnEscape: false,
+    })
+    layer.activate()
+    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); layer.release() }
   })
   // 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' }))
+    if (useVirtual) {
+      if (!panelEl) return
+      const next = scrollToIndex(i, panelEl.scrollTop, panelEl.clientHeight, rowHeight)
+      if (next !== panelEl.scrollTop) { panelEl.scrollTop = next; scrollTop = next }
+    } else {
+      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>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <button
+    bind:this={triggerEl}
+    class="sv-ddl sv-ddl--{size}"
+    class:is-open={ddl.open}
+    class:is-disabled={disabled}
+    class:is-invalid={invalid}
+    {...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>
+</SvField>
 
 {#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>
+  <div bind:this={panelEl} class="sv-ddl__panel" class:is-virtual={useVirtual} use:portalToBody use:popIn={{ up: rect.openUpward }} style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} onscroll={(e) => { scrollTop = e.currentTarget.scrollTop; if (useVirtual) flushSync() }} bind:clientHeight={viewportH} {...ddl.listboxProps()}>
+    {#if useVirtual}
+      <div class="sv-ddl__sizer" aria-hidden="true" style:height={`${vr.totalHeight}px`}></div>
+      {#each windowed as opt (opt.value)}
+        <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+        <div class="sv-ddl__opt sv-ddl__opt--abs" style:height={`${rowHeight}px`} style:transform={`translateY(${opt.index * rowHeight}px)`} class:is-active={ddl.isActive(opt.index)} class:is-selected={ddl.isSelected(opt)} class:is-disabled={opt.disabled} {...ddl.optionProps(opt.index)}>{opt.label}</div>
+      {/each}
+    {:else}
+    {#each groupOptions(options) as g (g.group ?? '')}
+      {#if g.group != null}
+        <div class="sv-ddl__group" role="group" aria-label={g.group}>
+          <div class="sv-ddl__group-label" aria-hidden="true">{g.group}</div>
+          {#each g.options as opt (opt.value)}
+            <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+            <div class="sv-ddl__opt" class:is-active={ddl.isActive(opt.index)} class:is-selected={ddl.isSelected(opt)} class:is-disabled={opt.disabled} {...ddl.optionProps(opt.index)}>{opt.label}</div>
+          {/each}
+        </div>
+      {:else}
+        {#each g.options as opt (opt.value)}
+          <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+          <div class="sv-ddl__opt" class:is-active={ddl.isActive(opt.index)} class:is-selected={ddl.isSelected(opt)} class:is-disabled={opt.disabled} {...ddl.optionProps(opt.index)}>{opt.label}</div>
+        {/each}
+      {/if}
     {/each}
+    {/if}
   </div>
 {/if}
 {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
@@ -95,7 +165,7 @@
   .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;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a); font: inherit; text-align: start;
     border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
     padding: 0 10px; cursor: pointer;
   }
@@ -103,6 +173,8 @@
   .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-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-ddl.is-invalid.is-open, .sv-ddl.is-invalid:focus-visible { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
   .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); }
@@ -113,8 +185,15 @@
     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) { box-sizing: border-box; display: flex; align-items: center; padding: 7px 10px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+  :global(.sv-ddl__panel.is-virtual) { position: fixed; will-change: scroll-position; }
+  :global(.sv-ddl__sizer) { padding: 0; margin: 0; pointer-events: none; }
+  :global(.sv-ddl__opt--abs) { position: absolute; inset-inline: 4px; top: 4px; }
   :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; }
+  :global(.sv-ddl__group-label) {
+    padding: 8px 10px 3px; font-size: 10.5px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em;
+    color: var(--sg-muted, #94a3b8);
+  }
 </style>

package/src/SvDurationInput.svelte

@@ -0,0 +1,108 @@
+<script lang="ts">
+  /**
+   * SvDurationInput - a duration editor whose value is a number of MINUTES but
+   * which accepts the human forms people type ("1h 30m", "1:30", "90"). It shows
+   * a formatted value when unfocused and re-parses on blur / Enter. As a grid
+   * cell editor: Enter commits, Escape cancels.
+   */
+  import SvField from './SvField.svelte'
+  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
+  import { parseDuration, formatDuration } from './duration'
+
+  type Props = SvEditorProps & {
+    /** Value in minutes (or null when empty). */
+    value?: number | null
+    onChange?: (minutes: number | null) => void
+    onCommit?: (minutes: number | null) => void
+    onCancel?: () => void
+    /** Display style when unfocused: `1:30` (colon) or `1h 30m` (units). */
+    style?: 'colon' | 'units'
+    placeholder?: string
+    autofocus?: boolean
+  }
+
+  let {
+    value = $bindable<number | null>(null),
+    onChange,
+    onCommit,
+    onCancel,
+    style = 'colon',
+    placeholder = 'e.g. 1h 30m',
+    disabled = false,
+    readonly = false,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    autofocus = false,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-dur')
+  const uid = $derived(id ?? autoId)
+
+  let text = $state('')
+  let focused = $state(false)
+  // Reflect the external value into the field whenever the user isn't typing.
+  $effect(() => {
+    if (!focused) text = value == null ? '' : formatDuration(value, style)
+  })
+
+  function commit(): number | null {
+    const mins = parseDuration(text)
+    value = mins // enables bind:value
+    onChange?.(mins)
+    if (mins != null) text = formatDuration(mins, style)
+    return mins
+  }
+  function mountFocus(node: HTMLInputElement) {
+    if (autofocus) { node.focus(); node.select() }
+  }
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-dur sv-dur--{size}" class:is-disabled={disabled}>
+    <div class="sv-dur__field" class:is-invalid={invalid}>
+      <input
+        use:mountFocus
+        class="sv-dur__input"
+        type="text"
+        inputmode="numeric"
+        value={text}
+        {placeholder}
+        {disabled}
+        {readonly}
+        oninput={(e) => (text = e.currentTarget.value)}
+        onfocus={() => (focused = true)}
+        onblur={() => { focused = false; commit() }}
+        onkeydown={(e) => {
+          if (e.key === 'Enter') { onCommit?.(commit()) }
+          else if (e.key === 'Escape') onCancel?.()
+        }}
+        {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
+      />
+    </div>
+    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+  </div>
+</SvField>
+
+<style>
+  .sv-dur { --_accent: var(--sg-accent, #2563eb); display: inline-flex; flex-direction: column; width: 160px; }
+  .sv-dur.is-disabled { opacity: 0.6; }
+  .sv-dur__field {
+    display: flex; align-items: center;
+    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);
+  }
+  .sv-dur__field:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-dur__field.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-dur__input { flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit; padding: 0 10px; }
+  .sv-dur--sm .sv-dur__field { height: 28px; font-size: 12px; }
+  .sv-dur--md .sv-dur__field { height: 34px; font-size: 13px; }
+  .sv-dur--lg .sv-dur__field { height: 40px; font-size: 15px; }
+</style>

package/src/SvEmptyState.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  /**
+   * SvEmptyState - a centered placeholder for empty lists, no-results, and blank
+   * screens: an icon/illustration, a title, a description, and an action slot.
+   * Theme-driven. Parity: Smart empty / no-data states.
+   *
+   * ```svelte
+   * <SvEmptyState title="No orders yet" description="Create your first order to get going.">
+   *   <SvButton>New order</SvButton>
+   * </SvEmptyState>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+
+  type Props = {
+    title?: string
+    description?: string
+    /** Tighter padding (for empty dropdowns / small panels). */
+    compact?: boolean
+    /** Custom icon / illustration (overrides the default). */
+    icon?: Snippet
+    /** Action buttons / links. */
+    children?: Snippet
+  }
+
+  let { title, description, compact = false, icon, children }: Props = $props()
+</script>
+
+<div class="sv-empty" class:is-compact={compact}>
+  <div class="sv-empty__icon" aria-hidden="true">
+    {#if icon}
+      {@render icon()}
+    {:else}
+      <svg viewBox="0 0 48 48" width="44" height="44" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <rect x="8" y="12" width="32" height="26" rx="3" /><path d="M8 20h32" /><path d="M16 28h10" />
+      </svg>
+    {/if}
+  </div>
+  {#if title}<div class="sv-empty__title">{title}</div>{/if}
+  {#if description}<p class="sv-empty__desc">{description}</p>{/if}
+  {#if children}<div class="sv-empty__actions">{@render children()}</div>{/if}
+</div>
+
+<style>
+  .sv-empty {
+    display: flex; flex-direction: column; align-items: center; text-align: center;
+    gap: 6px; padding: 44px 24px; color: var(--sg-fg, #0f172a);
+  }
+  .sv-empty.is-compact { padding: 22px 16px; }
+  .sv-empty__icon {
+    color: var(--sg-muted, #94a3b8); margin-bottom: 4px;
+    display: grid; place-items: center; width: 66px; height: 66px; border-radius: 16px;
+    background: var(--sg-row-hover-bg, #f1f5f9);
+  }
+  .sv-empty.is-compact .sv-empty__icon { width: 48px; height: 48px; }
+  .sv-empty__title { font-size: 15px; font-weight: 650; }
+  .sv-empty__desc { margin: 0; max-width: 42ch; color: var(--sg-muted, #64748b); font-size: 13px; line-height: 1.55; }
+  .sv-empty__actions { display: flex; gap: 8px; margin-top: 8px; }
+</style>

package/src/SvField.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  /**
+   * SvField - the shared field chrome for every value-bearing editor in the kit.
+   * It renders an optional `label` (wired to the control via `for`/`id`), the
+   * control itself (passed as children), and an optional `hint` / `error` line
+   * whose ids match `editorHintId` / `editorErrorId` for `aria-describedby`.
+   *
+   * Editors wrap their control box in it so label/hint/error/RTL behave
+   * IDENTICALLY across the kit:
+   *
+   * ```svelte
+   * <SvField {id} {label} {hint} {error} {required} {dir}>
+   *   <div class="sv-num">...control...</div>
+   * </SvField>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import { editorErrorId, editorHintId, type EditorDir } from './editor-contract'
+
+  let {
+    id,
+    label,
+    hint,
+    error,
+    required = false,
+    dir,
+    /** Stretch the field (and its control) to the container width. */
+    block = false,
+    children,
+  }: {
+    id?: string
+    label?: string
+    hint?: string
+    error?: string
+    required?: boolean
+    dir?: EditorDir
+    block?: boolean
+    children: Snippet
+  } = $props()
+
+  // 'auto'/undefined -> inherit from the document (no dir attribute).
+  const resolvedDir = $derived(dir === 'ltr' || dir === 'rtl' ? dir : undefined)
+</script>
+
+<div class="sv-field" class:sv-field--block={block} dir={resolvedDir}>
+  {#if label}
+    <label class="sv-field__label" for={id}>
+      {label}{#if required}<span class="sv-field__req" aria-hidden="true">*</span>{/if}
+    </label>
+  {/if}
+  {@render children()}
+  {#if error}
+    <span class="sv-field__error" id={editorErrorId(id)} role="alert">{error}</span>
+  {:else if hint}
+    <span class="sv-field__hint" id={editorHintId(id)}>{hint}</span>
+  {/if}
+</div>
+
+<style>
+  .sv-field {
+    display: inline-flex;
+    flex-direction: column;
+    gap: 3px;
+    text-align: start;
+  }
+  .sv-field--block { display: flex; width: 100%; }
+  .sv-field__label {
+    font-size: 12.5px;
+    font-weight: 550;
+    color: var(--sg-fg, #0f172a);
+    line-height: 1.3;
+  }
+  .sv-field__req { color: var(--sg-danger, #dc2626); margin-inline-start: 2px; }
+  .sv-field__hint {
+    font-size: 11.5px;
+    color: var(--sg-muted, #64748b);
+    line-height: 1.35;
+  }
+  .sv-field__error {
+    font-size: 11.5px;
+    font-weight: 500;
+    color: var(--sg-danger, #dc2626);
+    line-height: 1.35;
+  }
+</style>

package/src/SvFileUpload.svelte

@@ -0,0 +1,169 @@
+<script lang="ts" module>
+  export type { FileRejection, FileRejectReason } from './createFileUpload.svelte'
+</script>
+
+<script lang="ts">
+  /**
+   * SvFileUpload - a drag-and-drop file field with a click-to-browse fallback,
+   * accept / size / count validation and a selected-files list. Parity: Smart
+   * `smart-file-upload`. Controlled via `files` + `onChange`.
+   *
+   * Part of the editor kit: carries the shared contract (label, hint, error
+   * validation, `dir`/RTL and localizable `messages`) via `<SvField>`. The
+   * drag/validation/state live in the headless `createFileUpload` core.
+   */
+  import SvField from './SvField.svelte'
+  import { nextEditorId, resolveMessages, type SvEditorProps } from './editor-contract'
+  import { createFileUpload, type FileRejection } from './createFileUpload.svelte'
+
+  /** User-facing strings (localizable via `messages`). */
+  type FileMessages = { prompt: string; browse: string; remove: string; hintTypes: string }
+  const DEFAULT_MESSAGES: FileMessages = {
+    prompt: 'Drag files here or', browse: 'browse', remove: 'Remove', hintTypes: 'Accepted:',
+  }
+
+  type Props = SvEditorProps & {
+    files?: File[]
+    onChange?: (files: File[]) => void
+    onReject?: (rejections: FileRejection[]) => void
+    accept?: string
+    multiple?: boolean
+    /** Max size per file in bytes. */
+    maxSize?: number
+    maxFiles?: number
+    messages?: Partial<FileMessages>
+  }
+
+  let {
+    files = $bindable([]),
+    onChange,
+    onReject,
+    accept,
+    multiple = false,
+    maxSize,
+    maxFiles,
+    disabled = false,
+    readonly = false,
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+    messages,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-file')
+  const uid = $derived(id ?? autoId)
+  const M = $derived(resolveMessages(DEFAULT_MESSAGES, messages))
+
+  const fu = createFileUpload({
+    files: () => files,
+    onChange: (f) => { files = f; onChange?.(f) },
+    onReject: (r) => onReject?.(r),
+    accept: () => accept,
+    multiple: () => multiple,
+    maxSize: () => maxSize,
+    maxFiles: () => maxFiles,
+    disabled: () => disabled,
+    readonly: () => readonly,
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
+    ariaLabel: () => ariaLabel,
+  })
+
+  let inputEl = $state<HTMLInputElement | null>(null)
+
+  function openPicker() { if (fu.isInteractive) inputEl?.click() }
+  function onDropzoneKey(e: KeyboardEvent) {
+    if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openPicker() }
+  }
+  function onInputChange(e: Event) {
+    const list = (e.currentTarget as HTMLInputElement).files
+    if (list) fu.addFiles([...list])
+    ;(e.currentTarget as HTMLInputElement).value = '' // allow re-selecting the same file
+  }
+  function onDrop(e: DragEvent) {
+    e.preventDefault()
+    fu.setDragging(false)
+    if (e.dataTransfer?.files) fu.addFiles([...e.dataTransfer.files])
+  }
+
+  const fmtSize = (n: number) => (n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(0)} KB` : `${(n / 1048576).toFixed(1)} MB`)
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-file" class:is-disabled={disabled}>
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      class="sv-file__zone"
+      class:is-dragging={fu.dragging}
+      class:is-invalid={invalid}
+      {...fu.dropzoneProps()}
+      onclick={openPicker}
+      onkeydown={onDropzoneKey}
+      ondragenter={(e) => { e.preventDefault(); fu.setDragging(true) }}
+      ondragover={(e) => { e.preventDefault(); fu.setDragging(true) }}
+      ondragleave={() => fu.setDragging(false)}
+      ondrop={onDrop}
+    >
+      <svg class="sv-file__icon" viewBox="0 0 24 24" width="26" height="26" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4M17 8l-5-5-5 5M12 3v12" /></svg>
+      <p class="sv-file__prompt">{M.prompt} <span class="sv-file__browse">{M.browse}</span></p>
+      {#if accept}<p class="sv-file__types">{M.hintTypes} {accept}</p>{/if}
+      <input bind:this={inputEl} class="sv-file__input" {...fu.inputProps()} onchange={onInputChange} />
+    </div>
+
+    {#if files.length}
+      <ul class="sv-file__list">
+        {#each files as file, i (file.name + file.size + i)}
+          <li class="sv-file__item">
+            <span class="sv-file__name" title={file.name}>{file.name}</span>
+            <span class="sv-file__size">{fmtSize(file.size)}</span>
+            {#if fu.isInteractive}
+              <button class="sv-file__remove" aria-label={`${M.remove} ${file.name}`} {...fu.removeProps(i)}>&times;</button>
+            {/if}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </div>
+</SvField>
+
+<style>
+  .sv-file {
+    --_accent: var(--sg-accent, #2563eb);
+    --_border: var(--sg-input-border, var(--sg-border, #cbd5e1));
+    --_radius: var(--sg-radius, 8px);
+    display: flex; flex-direction: column; gap: 8px; width: 320px; color: var(--sg-fg, #0f172a);
+  }
+  .sv-file.is-disabled { opacity: 0.6; }
+  .sv-file__zone {
+    display: flex; flex-direction: column; align-items: center; gap: 4px;
+    padding: 22px 16px; text-align: center; cursor: pointer;
+    background: var(--sg-input-bg, #fff); color: var(--sg-muted, #64748b);
+    border: 1.5px dashed var(--_border); border-radius: var(--_radius); transition: border-color 0.15s, background 0.15s;
+  }
+  .sv-file__zone:hover, .sv-file__zone:focus-visible { border-color: var(--_accent); outline: none; }
+  .sv-file__zone.is-dragging { border-color: var(--_accent); background: color-mix(in srgb, var(--_accent) 8%, transparent); color: var(--_accent); }
+  .sv-file__zone.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-file__icon { color: var(--_accent); }
+  .sv-file__prompt { margin: 0; font-size: 13px; }
+  .sv-file__browse { color: var(--_accent); font-weight: 650; text-decoration: underline; }
+  .sv-file__types { margin: 0; font-size: 11.5px; opacity: 0.8; }
+  .sv-file__input { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); border: 0; }
+
+  .sv-file__list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; }
+  .sv-file__item {
+    display: flex; align-items: center; gap: 8px; padding: 6px 8px; font-size: 12.5px;
+    background: var(--sg-header-bg, #f8fafc); border: 1px solid var(--sg-border, #e2e8f0); border-radius: 6px;
+  }
+  .sv-file__name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 550; }
+  .sv-file__size { color: var(--sg-muted, #64748b); flex: none; font-variant-numeric: tabular-nums; }
+  .sv-file__remove { flex: none; background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; font-size: 16px; line-height: 1; padding: 0 2px; }
+  .sv-file__remove:hover { color: var(--sg-danger, #dc2626); }
+</style>