@svgrid/grid 1.2.22 → 1.2.24

package/dist/SvGrid.svelte

@@ -24,6 +24,8 @@
   } from "./render-component";
   import { buildSparkline, toSparklineValues } from "./sparkline";
   import SvGridDropdown from "./SvGridDropdown.svelte";
+  import SvDateTimePicker from "./SvDateTimePicker.svelte";
+  import { timeStringToDate, dateToTimeString } from "./SvGrid.helpers";
   import type {
     Props,
     SelectionPoint,
@@ -246,6 +248,7 @@
   const computeRowClass = $derived(ctrl.computeRowClass);
   const computeCellClass = $derived(ctrl.computeCellClass);
   const computeCellTooltip = $derived(ctrl.computeCellTooltip);
+  const computeCellValidity = $derived(ctrl.computeCellValidity);
   const computeCellNote = $derived(ctrl.computeCellNote);
   const getCellDisplayValue = $derived(ctrl.getCellDisplayValue);
   const getColumnAlign = $derived(ctrl.getColumnAlign);
@@ -266,6 +269,7 @@
   const getCellRangeEdges = $derived(ctrl.getCellRangeEdges);
   const fillHandleCell = $derived(ctrl.fillHandleCell);
   const isInFillPreview = $derived(ctrl.isInFillPreview);
+  const fillMarqueeEdges = $derived(ctrl.fillMarqueeEdges);
   const startFillDrag = $derived(ctrl.startFillDrag);
   const onCellPointerDown = $derived(ctrl.onCellPointerDown);
   const onCellPointerEnter = $derived(ctrl.onCellPointerEnter);
@@ -306,7 +310,12 @@
   onpointermove={onWindowPointerMove}
 />
 
-{#if props.loading && !props.loadingOverlay}
+{#if props.loading && !props.loadingOverlay && !hasMeasured}
+  <!-- Full-screen loading state only on the *initial* load, before the grid
+       has ever rendered. Once measured, a `loading` flip (from a server-mode
+       sort / filter / page refetch) keeps the table mounted so header inputs
+       and focus survive - the empty-row message + optional `loadingOverlay`
+       cover the in-place refresh. -->
   <div class="sv-grid-state sv-grid-state-loading" role="status">
     Loading grid data...
   </div>
@@ -798,6 +807,49 @@
           </div>
         {/if}
       </div>
+    {:else if ctrl.editingCell?.editorType === "date"}
+      <!-- Rich date editor: SvCalendar popover over a formatted input. Opts
+           out to the native <input type="date"> via editorType 'date-native'. -->
+      <SvDateTimePicker
+        value={ctrl.editingCell?.value as string | number | Date | null}
+        formatString="yyyy-MM-dd"
+        dropDownDisplayMode="calendar"
+        autoOpen
+        onChange={(d) => updateEditingCellValue(d)}
+        onCommit={() => saveEditingCell()}
+        onCancel={() => {
+          ctrl.editingCell = null;
+          ctrl.gridRootEl?.focus({ preventScroll: true });
+        }}
+      />
+    {:else if ctrl.editingCell?.editorType === "datetime"}
+      <SvDateTimePicker
+        value={ctrl.editingCell?.value as string | number | Date | null}
+        formatString="yyyy-MM-dd HH:mm"
+        dropDownDisplayMode="both"
+        autoOpen
+        onChange={(d) => updateEditingCellValue(d)}
+        onCommit={() => saveEditingCell()}
+        onCancel={() => {
+          ctrl.editingCell = null;
+          ctrl.gridRootEl?.focus({ preventScroll: true });
+        }}
+      />
+    {:else if ctrl.editingCell?.editorType === "time"}
+      <!-- Rich time editor: SvTimePicker dial. Stores the 'HH:MM' string the
+           `time` parser expects; opts out via editorType 'time-native'. -->
+      <SvDateTimePicker
+        value={timeStringToDate(ctrl.editingCell?.value)}
+        formatString="HH:mm"
+        dropDownDisplayMode="time"
+        autoOpen
+        onChange={(d) => updateEditingCellValue(dateToTimeString(d))}
+        onCommit={() => saveEditingCell()}
+        onCancel={() => {
+          ctrl.editingCell = null;
+          ctrl.gridRootEl?.focus({ preventScroll: true });
+        }}
+      />
     {:else if ctrl.editingCell?.editorType === "color"}
       <!-- Native <input type="color"> opens its picker in a separate OS
            overlay; once the picker closes, focus stays on the input so
@@ -1179,6 +1231,10 @@
       </div>
     {/if}
 
+    {#if hasMeasured && (props.paginationPosition === "top" || props.paginationPosition === "both")}
+      <GridFooter {ctrl} showStatus={false} top pager pageSizeOptions={props.pageSizeOptions} />
+    {/if}
+
     <div
       class="sv-grid-shell"
       style={`height: ${
@@ -1197,6 +1253,7 @@
         <table
           bind:this={ctrl.gridRootEl}
           class="sv-grid-table"
+          class:sv-grid-no-row-hover={props.enableRowHover !== true}
           {...getGridRootA11yProps({
             activeDescendantId,
             rowCount: allRows.length,
@@ -1795,6 +1852,7 @@
                           rowIndex,
                           colIndex,
                         )}
+                        {@const fillEdges = fillMarqueeEdges(rowIndex, colIndex)}
                         {@const hasFillHandle =
                           fillHandleCell &&
                           fillHandleCell.rowIndex === rowIndex &&
@@ -1807,6 +1865,10 @@
                           row,
                           rendered.column,
                         )}
+                        {@const cellValidity = computeCellValidity(
+                          row,
+                          rendered.column,
+                        )}
                         {@const cellNote = computeCellNote(
                           row,
                           rendered.column,
@@ -1818,7 +1880,9 @@
                             rowIndex && activeCell.colIndex === colIndex}
                           class:sv-grid-cell-has-fill-handle={hasFillHandle}
                           class:sv-grid-cell-cf={hasConditionalFormats}
+                          class:sv-grid-cell-invalid={cellValidity.invalid}
                           class:sv-grid-cell-has-note={cellNote != null}
+                          title={cellValidity.message ?? undefined}
                           data-svgrid-row={rowIndex}
                           data-svgrid-col={colIndex}
                           data-col-id={rendered.column.id}
@@ -1839,6 +1903,10 @@
                           data-fill-preview={isInFillPreview(rowIndex, colIndex)
                             ? "true"
                             : undefined}
+                          data-fill-top={fillEdges?.top ? "true" : undefined}
+                          data-fill-bottom={fillEdges?.bottom ? "true" : undefined}
+                          data-fill-left={fillEdges?.left ? "true" : undefined}
+                          data-fill-right={fillEdges?.right ? "true" : undefined}
                           style={`width: ${rendered.item.size}px; min-width: ${rendered.item.size}px; max-width: ${rendered.item.size}px; ${cellPinStyle(rendered.column.id)}`}
                           onpointerdown={(event) =>
                             onCellPointerDown(rowIndex, colIndex, event)}
@@ -2040,6 +2108,10 @@
                         row,
                         rendered.column,
                       )}
+                      {@const cellValidity = computeCellValidity(
+                        row,
+                        rendered.column,
+                      )}
                       {@const cellNote = computeCellNote(row, rendered.column)}
                       <td
                         class={`sv-grid-cell ${userCellClass}`}
@@ -2047,6 +2119,7 @@
                         class:sv-grid-cell-active={activeCell.rowIndex ===
                           rowIndex && activeCell.colIndex === colIndex}
                         class:sv-grid-cell-cf={hasConditionalFormats}
+                        class:sv-grid-cell-invalid={cellValidity.invalid}
                         class:sv-grid-cell-has-note={cellNote != null}
                         data-svgrid-row={rowIndex}
                         data-svgrid-col={colIndex}
@@ -2070,11 +2143,17 @@
                           // Column tooltip fires on whole-cell hover.
                           // Per-cell notes are gated on the corner hot-
                           // zone below (Excel-style: hover the small
-                          // triangle to read the note).
-                          if (cellTooltip)
+                          // triangle to read the note). A validation
+                          // message (when the cell is invalid) wins over
+                          // the plain column tooltip.
+                          const tip =
+                            cellValidity.invalid && cellValidity.message
+                              ? cellValidity.message
+                              : cellTooltip;
+                          if (tip)
                             showTooltipFor(
                               event.currentTarget as HTMLElement,
-                              cellTooltip,
+                              tip,
                             );
                         }}
                         onpointerleave={hideTooltip}
@@ -2284,7 +2363,7 @@
       {/if}
     </div>
 
-    <GridFooter {ctrl} />
+    <GridFooter {ctrl} pager={(props.paginationPosition ?? "bottom") !== "top"} pageSizeOptions={props.pageSizeOptions} />
 
     {#if ctrl.findOpen}
       <!-- Find-in-grid overlay. Anchored to the TOP of the grid root so

package/dist/SvGrid.types.d.ts

@@ -92,6 +92,35 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     showPagination?: boolean;
     /** Initial page size when pagination is enabled. Defaults to 10. */
     pageSize?: number;
+    /** Page-size choices shown in the footer's selector. Defaults to `[10, 25, 50, 100]`. */
+    pageSizeOptions?: number[];
+    /**
+     * Where the pagination footer sits: `'bottom'` (default), `'top'`, or `'both'`.
+     * The status bar (when enabled) always stays at the bottom.
+     */
+    paginationPosition?: 'top' | 'bottom' | 'both';
+    /**
+     * Server-side pagination. When `true`, the grid renders its native
+     * pagination footer from the `rowCount` / `pageIndex` you provide (rather
+     * than counting the local rows), does NOT slice `data` (the rows you pass are
+     * treated as the current page), and emits `onPaginationChange` when the user
+     * pages or changes page size. Pair with `externalSort` / `externalFilter`
+     * and a server data source. Requires `showPagination` / `pageable` to show
+     * the footer. Controlled: you own `pageIndex` + `pageSize` + `rowCount`.
+     */
+    externalPagination?: boolean;
+    /** Total rows on the server, for the footer's range + page count. Used with `externalPagination`. */
+    rowCount?: number;
+    /** Current 0-based page index. Used with `externalPagination` (controlled). */
+    pageIndex?: number;
+    /**
+     * Fires when the user changes page or page size while `externalPagination`
+     * is on. Fetch that page and update `data` / `rowCount` / `pageIndex`.
+     */
+    onPaginationChange?: (pagination: {
+        pageIndex: number;
+        pageSize: number;
+    }) => void;
     virtualization?: boolean;
     /** Row height in pixels. Pass a function `(rowIndex) => px` for
      *  per-row variable heights (e.g. an interactive row-resize feature).
@@ -137,6 +166,13 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
     showFilterMenu?: boolean;
     showFilterRow?: boolean;
     enableCellSelection?: boolean;
+    /**
+     * Highlight the row under the pointer. Default **false** - the hover tint can
+     * compete with the cell selection / fill marquee. Set `true` to opt in; when
+     * on, the hover no longer paints over selected cells so the selection stays
+     * visible.
+     */
+    enableRowHover?: boolean;
     /**
      * Prepend a header row (the column labels) to copied cell ranges, so pasting
      * into Excel / Sheets includes the headers. Applies per copied range.

package/dist/SvGridDropdown.svelte

@@ -19,6 +19,7 @@
    *   Tab                - commit and let focus escape.
    */
   import type { CellEditorOption } from './editors/cell-editors'
+  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
 
   type Props = {
     options: ReadonlyArray<CellEditorOption>
@@ -30,6 +31,10 @@
     /** Add a typeahead input at the top of the popover that filters the
      *  option list as the user types. Used by the rich-select editor. */
     searchable?: boolean
+    /** Focus the trigger and open the panel on mount. True for in-cell editing
+     *  (you clicked into the cell to edit); set false for form fields, which
+     *  should stay closed and unfocused until the user acts. Default true. */
+    autoOpen?: boolean
     /** Called with the new full value (scalar for single, array for multi). */
     onChange?: (next: unknown) => void
     /** Called when the user finalizes the selection (single pick, Enter, blur with selection). */
@@ -45,6 +50,7 @@
     placeholder = 'Select…',
     renderChipsInTrigger = false,
     searchable = false,
+    autoOpen = true,
     onChange,
     onCommit,
     onCancel,
@@ -69,7 +75,7 @@
   /** Viewport-anchored panel position. We `position: fixed` the panel so it
    *  escapes the grid's overflow:hidden scroll container - otherwise the
    *  bottom of the list gets clipped by the pager or the grid's footer. */
-  let panelRect = $state<{ top: number; left: number; width: number; openUpward: boolean }>({
+  let panelRect = $state<AnchoredRect>({
     top: 0,
     left: 0,
     width: 0,
@@ -134,20 +140,15 @@
    *  flips upward when there isn't enough room below the trigger. */
   function updatePanelPosition() {
     if (!triggerEl) return
-    const r = triggerEl.getBoundingClientRect()
     // Use the smaller of (option count, 10) for the upward-flip math so
     // a 3-option list doesn't think it needs 320px of headroom.
     const visibleCount = Math.min(options.length, 10)
     const estimatedHeight = visibleCount * 32 + (multiple ? 40 : 0) + 8
-    const spaceBelow = window.innerHeight - r.bottom
-    const spaceAbove = r.top
-    const openUpward = spaceBelow < estimatedHeight && spaceAbove > spaceBelow
-    panelRect = {
-      top: openUpward ? r.top - estimatedHeight - 2 : r.bottom + 2,
-      left: r.left,
-      width: r.width,
-      openUpward,
-    }
+    panelRect = anchoredRect(triggerEl.getBoundingClientRect(), {
+      estimatedHeight,
+      // Preserve the original behavior: anchor to the trigger, no clamping.
+      clampHorizontal: false,
+    })
   }
 
   // Keep the panel anchored as the page scrolls or resizes - without this,
@@ -249,28 +250,13 @@
   }
 
   function focusTrigger(node: HTMLButtonElement) {
+    // Form fields (autoOpen=false) stay closed + unfocused until the user acts;
+    // in-cell editing auto-focuses + opens to match clicking into a cell.
+    if (!autoOpen) return
     node.focus()
-    // Auto-open so the user can immediately pick - matches the
-    // expectation set by clicking into an editing cell.
     openPanel()
   }
 
-  /** Svelte action: detach the element on mount and append it to
-   *  document.body, then put it back / remove on destroy. This is how
-   *  we "portal" the panel out of the grid's overflow:hidden scroll
-   *  container so it can never be clipped, no matter how deeply nested
-   *  the editing cell is. */
-  function portalToBody(node: HTMLElement) {
-    document.body.appendChild(node)
-    return {
-      destroy() {
-        if (node.parentNode === document.body) {
-          document.body.removeChild(node)
-        }
-      },
-    }
-  }
-
   /** Close the panel when the user clicks outside both trigger AND
    *  panel - `onfocusout` on the dropdown root no longer catches this
    *  because the portal'd panel is a sibling of body, not a descendant
@@ -388,7 +374,7 @@
       style:left={`${panelRect.left}px`}
       style:width={`${panelRect.width}px`}
       style:max-height={panelMax !== null ? `${panelMax}px` : null}
-      style:z-index="9999"
+      style:z-index="2147483647"
       onpointerdown={(event) => event.stopPropagation()}
       onmousedown={(event) => event.stopPropagation()}
       onclick={(event) => event.stopPropagation()}

package/dist/SvGridDropdown.svelte.d.ts

@@ -28,6 +28,10 @@ type Props = {
     /** Add a typeahead input at the top of the popover that filters the
      *  option list as the user types. Used by the rich-select editor. */
     searchable?: boolean;
+    /** Focus the trigger and open the panel on mount. True for in-cell editing
+     *  (you clicked into the cell to edit); set false for form fields, which
+     *  should stay closed and unfocused until the user acts. Default true. */
+    autoOpen?: boolean;
     /** Called with the new full value (scalar for single, array for multi). */
     onChange?: (next: unknown) => void;
     /** Called when the user finalizes the selection (single pick, Enter, blur with selection). */

package/dist/SvListBox.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+  /**
+   * SvListBox - an inline single/multi-select list (WAI-ARIA listbox) with
+   * roving highlight + full keyboard. Parity: Smart `smart-list-box`. Controlled
+   * via `value` (scalar or array) + `onChange`.
+   */
+  import type { ListOption } from './list-option'
+  import { createListbox } from './createListbox.svelte'
+
+  type Props = {
+    options: ReadonlyArray<ListOption>
+    value?: string | number | Array<string | number> | null
+    onChange?: (value: any) => void
+    multiple?: boolean
+    disabled?: boolean
+    /** Visible height in rows before scrolling. */
+    rows?: number
+    ariaLabel?: string
+    /** Form field name; emits a hidden input per selected value so the listbox
+     *  posts in a native <form> (multiple selection -> repeated name). */
+    name?: string
+  }
+
+  let { options, value = null, onChange, multiple = false, disabled = false, rows = 7, ariaLabel, name }: Props = $props()
+
+  // The styled listbox is just a renderer over the headless core.
+  const lb = createListbox({
+    options: () => options,
+    value: () => value,
+    onChange: (v) => onChange?.(v),
+    multiple: () => multiple,
+    disabled: () => disabled,
+    ariaLabel: () => ariaLabel,
+  })
+  const isSel = (o: ListOption) => lb.isSelected(o.value)
+
+  let listEl: HTMLUListElement | null = null
+  // Scroll-into-view is a render concern, so it lives here (not in the core).
+  $effect(() => {
+    const i = lb.activeIndex
+    queueMicrotask(() => listEl?.querySelector<HTMLElement>(`[data-idx="${i}"]`)?.scrollIntoView({ block: 'nearest' }))
+  })
+</script>
+
+<div style="display: contents">
+<ul
+  bind:this={listEl}
+  class="sv-listbox"
+  style:--sv-rows={rows}
+  {...lb.rootProps()}
+>
+  {#each options as opt, i (opt.value)}
+    <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
+    <li
+      class="sv-listbox__opt"
+      class:is-selected={isSel(opt)}
+      class:is-active={lb.isActive(i)}
+      class:is-disabled={opt.disabled}
+      {...lb.optionProps(i)}
+    >
+      {#if multiple}<span class="sv-listbox__check" aria-hidden="true">{isSel(opt) ? '✓' : ''}</span>{/if}
+      <span class="sv-listbox__label">{opt.label}</span>
+    </li>
+  {/each}
+</ul>
+{#if name}{#each lb.selectedValues as v (v)}<input type="hidden" {name} value={v} />{/each}{/if}
+</div>
+
+<style>
+  .sv-listbox {
+    --_accent: var(--sg-accent, #2563eb);
+    margin: 0; padding: 4px; list-style: none;
+    max-height: calc(var(--sv-rows, 7) * 32px + 8px); overflow-y: auto;
+    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);
+    width: 220px; outline: none;
+  }
+  .sv-listbox:focus-visible { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-listbox__opt {
+    display: flex; align-items: center; gap: 8px; height: 32px; padding: 0 10px;
+    border-radius: 6px; cursor: pointer; font-size: 13px;
+  }
+  .sv-listbox__opt.is-active { background: var(--sg-row-hover-bg, #f1f5f9); }
+  .sv-listbox__opt.is-selected { background: color-mix(in srgb, var(--_accent) 14%, transparent); color: var(--_accent); font-weight: 600; }
+  .sv-listbox__opt.is-selected.is-active { background: color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-listbox__opt.is-disabled { opacity: 0.4; cursor: not-allowed; }
+  .sv-listbox__check { width: 14px; text-align: center; color: var(--_accent); }
+  .sv-listbox__label { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+</style>

package/dist/SvListBox.svelte.d.ts

@@ -0,0 +1,22 @@
+/**
+   * SvListBox - an inline single/multi-select list (WAI-ARIA listbox) with
+   * roving highlight + full keyboard. Parity: Smart `smart-list-box`. Controlled
+   * via `value` (scalar or array) + `onChange`.
+   */
+import type { ListOption } from './list-option';
+type Props = {
+    options: ReadonlyArray<ListOption>;
+    value?: string | number | Array<string | number> | null;
+    onChange?: (value: any) => void;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** Visible height in rows before scrolling. */
+    rows?: number;
+    ariaLabel?: string;
+    /** Form field name; emits a hidden input per selected value so the listbox
+     *  posts in a native <form> (multiple selection -> repeated name). */
+    name?: string;
+};
+declare const SvListBox: import("svelte").Component<Props, {}, "">;
+type SvListBox = ReturnType<typeof SvListBox>;
+export default SvListBox;

package/dist/SvMaskedInput.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+  /**
+   * SvMaskedInput - a pattern-masked text input (#=digit, A=letter, *=alnum;
+   * other chars are literals). Parity: Smart `smart-masked-text-box`. Emits both
+   * the masked display value and the raw (unmasked) value.
+   *
+   * The styled renderer over the headless `createMaskedInput` core; the mask
+   * formatting + state live in the core, spread here via prop-getters.
+   */
+  import { unmask } from './datetime/mask'
+  import { createMaskedInput } from './createMaskedInput.svelte'
+
+  type Props = {
+    value?: string
+    /** Called with (masked, raw, complete). */
+    onChange?: (masked: string, raw: string, complete: boolean) => void
+    mask?: string
+    placeholder?: string
+    disabled?: boolean
+    readonly?: boolean
+    name?: string
+    size?: 'sm' | 'md' | 'lg'
+    ariaLabel?: string
+  }
+
+  let {
+    value = '',
+    onChange,
+    mask = '',
+    placeholder,
+    disabled = false,
+    readonly = false,
+    name,
+    size = 'md',
+    ariaLabel,
+  }: Props = $props()
+
+  const mi = createMaskedInput({
+    value: () => value,
+    onChange: (m, r, c) => onChange?.(m, r, c),
+    mask: () => mask,
+    placeholder: () => placeholder,
+    disabled: () => disabled,
+    readonly: () => readonly,
+    ariaLabel: () => ariaLabel,
+  })
+</script>
+
+<input class="sv-masked sv-masked--{size}" {...mi.inputProps()} />
+{#if name}<input type="hidden" {name} value={mask ? unmask(mi.masked, mask) : mi.masked} />{/if}
+
+<style>
+  .sv-masked {
+    --_accent: var(--sg-accent, #2563eb);
+    box-sizing: border-box; width: 200px;
+    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);
+    font: inherit; padding: 0 10px; outline: none;
+    font-variant-numeric: tabular-nums; letter-spacing: 0.02em;
+  }
+  .sv-masked--sm { height: 28px; font-size: 12px; }
+  .sv-masked--md { height: 34px; font-size: 13px; }
+  .sv-masked--lg { height: 40px; font-size: 15px; }
+  .sv-masked:focus { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-masked:disabled { opacity: 0.6; }
+</style>

package/dist/SvMaskedInput.svelte.d.ts

@@ -0,0 +1,15 @@
+type Props = {
+    value?: string;
+    /** Called with (masked, raw, complete). */
+    onChange?: (masked: string, raw: string, complete: boolean) => void;
+    mask?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    name?: string;
+    size?: 'sm' | 'md' | 'lg';
+    ariaLabel?: string;
+};
+declare const SvMaskedInput: import("svelte").Component<Props, {}, "">;
+type SvMaskedInput = ReturnType<typeof SvMaskedInput>;
+export default SvMaskedInput;

package/dist/SvNumberInput.svelte

@@ -0,0 +1,116 @@
+<script lang="ts">
+  /**
+   * SvNumberInput - a numeric input with min/max/step, spinner buttons, optional
+   * thousands grouping + precision, prefix/suffix. Parity: Smart `smart-number-input`.
+   * Emits number | null. The SvGrid number cell editor, standalone too.
+   *
+   * This is the styled renderer over the headless `createNumberInput` core - the
+   * same split as the grid (`createSvGrid` / `<SvGrid>`): parse/format/clamp,
+   * spinner + keyboard and ARIA all come from the core via prop-getters.
+   */
+  import SvRepeatButton from './SvRepeatButton.svelte'
+  import { editorErrorId, type SvEditorProps } from './editor-contract'
+  import { createNumberInput } from './createNumberInput.svelte'
+
+  type Props = SvEditorProps & {
+    value?: number | null
+    onChange?: (value: number | null) => void
+    min?: number
+    max?: number
+    step?: number
+    precision?: number
+    /** Group thousands (1,234) on display. */
+    grouping?: boolean
+    prefix?: string
+    suffix?: string
+    placeholder?: string
+    spinButtons?: boolean
+  }
+
+  let {
+    value = null,
+    onChange,
+    min = -Infinity,
+    max = Infinity,
+    step = 1,
+    precision,
+    grouping = false,
+    prefix = '',
+    suffix = '',
+    placeholder,
+    disabled = false,
+    readonly = false,
+    spinButtons = true,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    id,
+  }: Props = $props()
+
+  const num = createNumberInput({
+    value: () => value,
+    onChange: (v) => onChange?.(v),
+    min: () => min,
+    max: () => max,
+    step: () => step,
+    precision: () => precision,
+    grouping: () => grouping,
+    prefix: () => prefix,
+    suffix: () => suffix,
+    placeholder: () => placeholder,
+    disabled: () => disabled,
+    readonly: () => readonly,
+    id: () => id,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    ariaLabel: () => ariaLabel,
+  })
+</script>
+
+<div class="sv-field">
+  <div class="sv-num sv-num--{size}" class:is-disabled={disabled} class:is-invalid={invalid}>
+    <input class="sv-num__input" {...num.inputProps()} />
+    {#if spinButtons}
+      <div class="sv-num__spin">
+        <SvRepeatButton size="sm" variant="ghost" ariaLabel="Increment" onclick={num.increment}>
+          <svg viewBox="0 0 24 24" width="11" height="11" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M6 15l6-6 6 6" /></svg>
+        </SvRepeatButton>
+        <SvRepeatButton size="sm" variant="ghost" ariaLabel="Decrement" onclick={num.decrement}>
+          <svg viewBox="0 0 24 24" width="11" height="11" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6" /></svg>
+        </SvRepeatButton>
+      </div>
+    {/if}
+    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+  </div>
+  {#if error}<span class="sv-field__error" id={editorErrorId(id)} role="alert">{error}</span>{/if}
+</div>
+
+<style>
+  /* Shared field wrapper: stacks the control box above an optional error line. */
+  .sv-field { display: inline-flex; flex-direction: column; gap: 3px; }
+  .sv-field__error { font-size: 11.5px; font-weight: 500; color: var(--sg-danger, #dc2626); line-height: 1.35; }
+  .sv-num {
+    --_accent: var(--sg-accent, #2563eb);
+    display: inline-flex; align-items: stretch; width: 150px;
+    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);
+    overflow: hidden;
+  }
+  .sv-num:focus-within { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-num.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-num.is-invalid:focus-within { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
+  .sv-num.is-disabled { opacity: 0.6; }
+  .sv-num__input {
+    flex: 1; min-width: 0; border: 0; background: none; outline: none; color: inherit; font: inherit;
+    text-align: right; padding: 0 8px;
+  }
+  .sv-num--sm { height: 28px; font-size: 12px; }
+  .sv-num--md { height: 34px; font-size: 13px; }
+  .sv-num--lg { height: 40px; font-size: 15px; }
+  .sv-num__spin { display: flex; flex-direction: column; border-left: 1px solid var(--sg-border, #e2e8f0); }
+  .sv-num__spin :global(.sv-repeat) { flex: 1; padding: 0 6px; border-radius: 0; }
+</style>