@svgrid/grid 2.2.16 → 2.2.18

package/src/SvGrid.types.ts

@@ -9,6 +9,8 @@ import type {
   TableFeatures,
 } from "./index";
 import type { ConditionalFormat } from "./conditional-formatting";
+import type { GridMessages } from "./grid-messages";
+import type { GridPivotConfig } from "./pivot-view.svelte";
 import type { MenuItem } from "./SvMenuList.svelte";
 import type { RecurrenceRule } from "./recurrence";
 
@@ -65,6 +67,7 @@ import type {
   ChartSpec,
   ChartAnnotation,
   ChartReferenceLine,
+  ChartValueFormat,
 } from "./chart";
 
 /** One aggregated bucket returned by a server-side `getAggregate`. */
@@ -196,7 +199,9 @@ export type ContextMenuTarget<TData extends RowData = RowData> = {
 /**
  * A context-menu entry. Either a built-in action key, the `"separator"`
  * divider, or a custom item. Built-in keys: `"copy" | "cut" | "paste" |
- * "clear" | "row_above" | "row_below" | "remove_row" | "remove_col"`.
+ * "clear" | "row_above" | "row_below" | "remove_row" | "remove_col" |
+ * "chart"`. The `"chart"` item (chart the selected range) is only shown when
+ * `charting` is enabled; it is appended to the default menu automatically.
  */
 export type ContextMenuItem<TData extends RowData = RowData> =
   | string
@@ -301,6 +306,58 @@ export type BoardCardMoveEvent<TData extends RowData = RowData> = {
  * of a table. Dragging a card between lanes fires {@link BoardConfig.onCardMove}
  * where you reassign the `groupBy` field on your own data.
  */
+/**
+ * Chart view of the grid. Setting the `chart` prop on `<SvGrid>` swaps the table
+ * for a chart driven by the grid's FILTERED + SORTED rows - so the search box,
+ * column filters and sort all flow through to the chart. Unlike the board and
+ * scheduler views, the renderer is free: the grid lazy-loads a built-in
+ * `SvChart` view unless a host overrides it via `registerChartView`.
+ *
+ * The config maps directly onto `rowsToChartSpec` - one row field for the
+ * category axis, one or more for the value series (or a `series` field to pivot
+ * one series per distinct value).
+ *
+ * ```svelte
+ * <SvGrid {data} {columns}
+ *   chart={{ type: 'bar', category: 'month', value: 'revenue', reduce: 'sum' }} />
+ * ```
+ */
+export type ChartViewConfig<
+  TFeatures extends TableFeatures = TableFeatures,
+  TData extends RowData = RowData,
+> = {
+  /** Chart type. Default `'bar'`. */
+  type?: ChartType;
+  /** Row field for the category (x) axis. */
+  category: keyof TData & string;
+  /** Row field(s) for the value (y) series. */
+  value: (keyof TData & string) | Array<keyof TData & string>;
+  /** Pivot dimension: one series per distinct value of this field. */
+  series?: keyof TData & string;
+  /** Aggregation when several rows share a category. Default `'sum'`. */
+  reduce?: "sum" | "avg" | "count";
+  /** Stack bar / area series instead of grouping them. */
+  stacked?: boolean;
+  /** Stack to 100% (implies `stacked`). */
+  stacked100?: boolean;
+  /** Order categories. Default: insertion order (value-desc when `topN` is set). */
+  sort?: "value-desc" | "value-asc" | "category" | "none";
+  /** Keep only the top N categories; bucket the rest into "Other". */
+  topN?: number;
+  /** Palette for series without an explicit colour. */
+  palette?: string[];
+  /** Number format for the value axis, tooltips and data labels. */
+  valueFormat?: ChartValueFormat;
+  /** Show the clickable legend. Default `true`. */
+  legend?: boolean;
+  /** Draw the value on each bar / point / slice. Default `false`. */
+  dataLabels?: boolean;
+  /** Show the search box above the chart (filters rows first). Default `true`. */
+  searchable?: boolean;
+  /** Placeholder for the search box. */
+  searchPlaceholder?: string;
+};
+
 export type BoardConfig<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = {
   /** Field whose value buckets each row into a lane. */
   groupBy: keyof TData & string;
@@ -581,6 +638,12 @@ export type SchedulerException = {
   end?: string | number | Date;
   title?: string;
   allDay?: boolean;
+  /**
+   * Per-occurrence overrides for ANY other field (e.g. attendees, calendar,
+   * color, resource). Merged over the row for just this occurrence, so "This
+   * event" can change fields beyond start / end / title / all-day.
+   */
+  fields?: Record<string, unknown>;
 };
 
 /** How a change to a recurring event should apply. */
@@ -907,6 +970,30 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * {@link SchedulerConfig}.
    */
   scheduler?: SchedulerConfig<TFeatures, TData>;
+  /**
+   * Chart view. When set, the grid renders its FILTERED + SORTED rows as a chart
+   * instead of a table (search / filters / sort flow through). Unlike board and
+   * scheduler, the renderer is free - the grid lazy-loads a built-in `SvChart`
+   * view, overridable via `registerChartView`. See {@link ChartViewConfig}.
+   */
+  chart?: ChartViewConfig<TFeatures, TData>;
+  /**
+   * Pivot mode. When set (and `pivotMode` is on), the grid renders its rows as a
+   * pivot table in place - the same grid, aggregated across `pivot.rows` /
+   * `pivot.cols` with nested column headers - instead of the flat table. The
+   * pivot ENGINE ships in `@svgrid/enterprise`; call `enablePivot()` (or
+   * `installEnterprise(api)`) to register it, otherwise an upsell note shows.
+   * See {@link GridPivotConfig}.
+   */
+  pivot?: GridPivotConfig<TData>;
+  /**
+   * Whether pivot mode is currently active. Defaults to `true` when `pivot` is
+   * set. Bindable so a toolbar toggle can flip between the pivot and the flat
+   * table over the same data.
+   */
+  pivotMode?: boolean;
+  /** Fired when the in-grid Pivot toggle flips `pivotMode`. */
+  onPivotModeChange?: (on: boolean) => void;
   /**
    * Right-click context menu. `true` shows the default item set (copy, cut,
    * paste, clear, insert row above/below, remove row, remove column). Pass an
@@ -957,6 +1044,24 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   loadingSkeletonRows?: number;
   error?: string | null;
   emptyMessage?: string;
+  /**
+   * The single place to localize the grid. One object with two fields:
+   *
+   * - `locale` - BCP-47 tag(s) for the DATA: accent/case-insensitive filter
+   *   matching AND every column's number / currency / percent / date formatting
+   *   (when the column's own `format.locales` is unset). The default for
+   *   `filterLocale` and per-column format locales.
+   * - `text` - overrides for the grid's own UI STRINGS (empty state, tool panel,
+   *   pager, status bar, filter operator labels, context-menu items, upsell
+   *   notes). Any subset overrides the English defaults; unset keys stay English.
+   *
+   * ```svelte
+   * <SvGrid localization={{ locale: 'fr-FR', text: { noRows: 'Aucune ligne' } }} />
+   * ```
+   *
+   * Omitting it (or any field) is a no-op. See {@link GridMessages}.
+   */
+  localization?: GridLocalization;
   showGlobalFilter?: boolean;
   showColumnFilters?: boolean;
   /**
@@ -1177,6 +1282,13 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
    * consumer wants to own the row ordering.
    */
   onSortingChange?: (sorting: Array<{ id: string; desc: boolean }>) => void;
+  /**
+   * The sort state to start in - `{ id, desc }` entries. Use with `externalSort`
+   * when the initial ordering is decided server-side (e.g. a URL `?sort=` param
+   * read in a SvelteKit `load`), so the header sort indicators match the already-
+   * sorted data on first render. Applied once at mount; user sorting takes over.
+   */
+  initialSorting?: Array<{ id: string; desc: boolean }>;
   /**
    * When `true`, the grid still records column-filter / global-filter /
    * facet state (so the menu UI works and indicators light up) but does
@@ -1455,6 +1567,18 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   filterLocale?: string | ReadonlyArray<string>;
 };
 
+/**
+ * The grid's single localization surface (see {@link Props.localization}):
+ * `locale` handles the data (filter matching + number/date formatting) and
+ * `text` handles the UI strings.
+ */
+export type GridLocalization = {
+  /** BCP-47 tag(s) for filter matching + number / date formatting. */
+  locale?: string | ReadonlyArray<string>;
+  /** Overrides for the grid's own UI strings. */
+  text?: Partial<GridMessages>;
+};
+
 export type SelectionPoint = { rowIndex: number; colIndex: number };
 export type SelectionRange = {
   anchor: SelectionPoint | null;

package/src/SvGridChartView.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  /**
+   * SvGridChartView - the built-in renderer for the grid's `chart` view. It is a
+   * thin adapter: take the grid's filtered + sorted rows, map the ChartViewConfig
+   * onto `rowsToChartSpec`, and render the standalone SvChart (SvGridChart) sized
+   * to fill the container. This is the piece that makes "chart" a view of the
+   * grid, and it stays a thin wrapper precisely because the chart primitive is
+   * reusable on its own (unlike the board / scheduler renderers).
+   *
+   * The grid lazy-loads this by default; a host can replace it via
+   * `registerChartView` when it needs a richer renderer.
+   */
+  import SvGridChart from "./SvGridChart.svelte";
+  import { rowsToChartSpec, type ChartSpec } from "./chart";
+  import type { ChartViewConfig } from "./SvGrid.types";
+
+  let {
+    data,
+    chart,
+  }: {
+    data: ReadonlyArray<Record<string, unknown>>;
+    /** Present for parity with board/scheduler renderers; unused here. */
+    columns?: unknown;
+    getRowId?: unknown;
+    chart: ChartViewConfig;
+  } = $props();
+
+  // Container size -> chart viewBox, so the chart fills the grid area and
+  // re-lays out on resize (the same responsive behaviour a table view has).
+  let w = $state(0);
+  let h = $state(0);
+
+  const spec = $derived.by<ChartSpec>(() => {
+    const s = rowsToChartSpec((data ?? []) as ReadonlyArray<Record<string, unknown>>, {
+      type: chart.type ?? "bar",
+      category: chart.category,
+      value: chart.value,
+      series: chart.series,
+      reduce: chart.reduce,
+      stacked: chart.stacked,
+      stacked100: chart.stacked100,
+      sort: chart.sort,
+      topN: chart.topN,
+      palette: chart.palette,
+    });
+    if (chart.valueFormat) s.valueFormat = chart.valueFormat;
+    return s;
+  });
+</script>
+
+<div class="sv-grid-chart-view" bind:clientWidth={w} bind:clientHeight={h}>
+  {#if w > 0 && h > 0}
+    <SvGridChart
+      {spec}
+      width={w}
+      height={h}
+      legend={chart.legend ?? true}
+      dataLabels={chart.dataLabels ?? false}
+    />
+  {/if}
+</div>
+
+<style>
+  .sv-grid-chart-view {
+    width: 100%;
+    height: 100%;
+    min-height: 0;
+    box-sizing: border-box;
+  }
+</style>

package/src/SvGridDropdown.svelte

@@ -64,6 +64,13 @@
     return index >= 0 && index < visibleOptions.length ? `${instanceId}-opt-${index}` : undefined
   }
 
+  // Options that carry a `color` render as full pills (see the option list
+  // below), which are taller than a plain text row. The panel-sizing math must
+  // reserve that height, otherwise the panel is capped to the plain-row estimate
+  // and clips the last option (e.g. a 3-item coloured list). ~40px per chip row
+  // vs ~32px for plain text.
+  const optionRowHeight = $derived(options.some((o) => o.color) ? 40 : 32)
+
   let searchQuery = $state('')
   const visibleOptions = $derived(
     !searchable || !searchQuery.trim()
@@ -153,7 +160,7 @@
     // 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 estimatedHeight = visibleCount * optionRowHeight + (multiple ? 40 : 0) + 8
     panelRect = anchoredRect(triggerEl.getBoundingClientRect(), {
       estimatedHeight,
       // Preserve the original behavior: anchor to the trigger, no clamping.
@@ -381,7 +388,7 @@
     <!-- Cap to the comfortable 10-row height AND the room the viewport allows,
          so a panel near the bottom edge scrolls instead of overflowing. -->
     {@const panelMax = Math.min(
-      needsScroll ? 10 * 32 + (multiple ? 40 : 0) + 8 : Number.POSITIVE_INFINITY,
+      needsScroll ? 10 * optionRowHeight + (multiple ? 40 : 0) + 8 : Number.POSITIVE_INFINITY,
       panelRect.maxHeight,
     )}
     <div

package/src/SvGridSelect.svelte

@@ -21,7 +21,7 @@
 
   type Props = Pick<
     SvEditorProps,
-    'disabled' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel'
+    'disabled' | 'readonly' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel' | 'loading'
   > & {
     columns: ReadonlyArray<GridSelectColumn>
     options: ReadonlyArray<Row>
@@ -55,6 +55,7 @@
     debounceMs = 250,
     loadingText = 'Loading…',
     disabled = false,
+    readonly = false,
     label,
     hint,
     error,
@@ -65,6 +66,7 @@
     name,
     dir,
     ariaLabel,
+    loading: loadingProp = false,
   }: Props = $props()
 
   const autoId = nextEditorId('sv-gs')
@@ -106,6 +108,7 @@
 
   const gs = createPopoverSelect({
     itemCount: () => filtered.length,
+    readonly: () => readonly,
     onSelect: (i) => {
       const r = filtered[i]
       if (r) { value = r[idField] as string | number; onChange?.(r[idField] as string | number, r) }
@@ -122,7 +125,7 @@
   })
 </script>
 
-<SvField id={uid} {label} {hint} {error} {required} {dir}>
+<SvField id={uid} {label} {hint} {error} {required} {dir} loading={loadingProp || loading}>
   <div class="sv-gs sv-gs--{size}" class:is-disabled={disabled}>
     <button
       bind:this={triggerEl}

package/src/SvGroup.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  /**
+   * SvGroup - a horizontal flex layout primitive: lays children in a row with a
+   * consistent `gap`, alignment, and optional wrapping. The row counterpart to
+   * SvStack - toolbars, button clusters, inline label + control.
+   *
+   * ```svelte
+   * <SvGroup gap={8} justify="between"><Title /><Actions /></SvGroup>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+
+  type Props = {
+    /** Gap between children (px, or any CSS length). Default 8. */
+    gap?: number | string
+    /** Cross-axis alignment. Default `center`. */
+    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline'
+    /** Main-axis distribution. */
+    justify?: 'start' | 'center' | 'end' | 'between' | 'around'
+    /** Allow wrapping to multiple rows. */
+    wrap?: boolean
+    /** Give every child `flex: 1` so they share the width evenly. */
+    grow?: boolean
+    as?: string
+    children?: Snippet
+  }
+
+  let { gap = 8, align = 'center', justify = 'start', wrap = false, grow = false, as = 'div', children }: Props = $props()
+  const g = $derived(typeof gap === 'number' ? `${gap}px` : gap)
+  const alignMap = { start: 'flex-start', center: 'center', end: 'flex-end', stretch: 'stretch', baseline: 'baseline' } as const
+  const justifyMap = { start: 'flex-start', center: 'center', end: 'flex-end', between: 'space-between', around: 'space-around' } as const
+</script>
+
+<svelte:element this={as} class="sv-group" class:is-grow={grow} style:gap={g} style:flex-wrap={wrap ? 'wrap' : 'nowrap'} style:align-items={alignMap[align]} style:justify-content={justifyMap[justify]}>
+  {@render children?.()}
+</svelte:element>
+
+<style>
+  .sv-group { display: flex; flex-direction: row; min-width: 0; }
+  .sv-group.is-grow > :global(*) { flex: 1 1 0; min-width: 0; }
+</style>

package/src/SvHoverCard.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  /**
+   * SvHoverCard - a rich preview card that opens when the pointer rests on its
+   * anchor (a user chip, a link) and closes shortly after it leaves. Built on the
+   * shared positioning engine via SvPopover, so it takes any `placement`, flips
+   * and shifts to stay in view, and the card itself is hoverable (you can move the
+   * pointer onto it). For keyboard/touch users, prefer SvPopover with a click
+   * trigger - a hover card is a pointer affordance.
+   *
+   * ```svelte
+   * <SvHoverCard>
+   *   {#snippet anchor()}<a href="/u/ada">@ada</a>{/snippet}
+   *   <strong>Ada Lovelace</strong>
+   *   <p>Analyst, first programmer.</p>
+   * </SvHoverCard>
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+  import SvPopover from './SvPopover.svelte'
+  import type { Placement } from './positioning'
+
+  type Props = {
+    /** Controlled open state (bindable). */
+    open?: boolean
+    onOpenChange?: (open: boolean) => void
+    /** Preferred placement; flips when there is no room. Default `bottom-start`. */
+    placement?: Placement
+    /** Delay (ms) before the card opens on hover. Default 250. */
+    openDelay?: number
+    /** Delay (ms) before it closes after the pointer leaves. Default 180. */
+    closeDelay?: number
+    /** Show a pointer arrow. Default false (cards usually read cleaner without). */
+    arrow?: boolean
+    /** Force a minimum card width. */
+    minWidth?: number
+    ariaLabel?: string
+    /** The element the card previews. */
+    anchor?: Snippet
+    /** Card content. */
+    children?: Snippet
+  }
+
+  let {
+    open = $bindable(false),
+    onOpenChange,
+    placement = 'bottom-start',
+    openDelay = 250,
+    closeDelay = 180,
+    arrow = false,
+    minWidth = 240,
+    ariaLabel,
+    anchor,
+    children,
+  }: Props = $props()
+</script>
+
+<SvPopover
+  bind:open
+  {onOpenChange}
+  trigger="hover"
+  {placement}
+  {openDelay}
+  {closeDelay}
+  {arrow}
+  {minWidth}
+  {ariaLabel}
+  {anchor}
+>
+  {@render children?.()}
+</SvPopover>

package/src/SvKbd.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  /**
+   * SvKbd - a keyboard-key hint. Pass `keys` for a combo (joined with the OS
+   * separator), or a single `children` label.
+   *
+   * <SvKbd keys={['Ctrl', 'K']} /> · <SvKbd>Esc</SvKbd>
+   */
+  import type { Snippet } from 'svelte'
+
+  type Props = {
+    /** Key sequence, rendered as separate caps. */
+    keys?: string[]
+    /** Separator between keys. */
+    separator?: string
+    size?: 'sm' | 'md'
+    children?: Snippet
+  }
+
+  let { keys, separator = '+', size = 'md', children }: Props = $props()
+</script>
+
+{#if keys}
+  <span class="sv-kbd-group sv-kbd--{size}">
+    {#each keys as k, i}
+      {#if i > 0}<span class="sv-kbd__sep" aria-hidden="true">{separator}</span>{/if}
+      <kbd class="sv-kbd">{k}</kbd>
+    {/each}
+  </span>
+{:else}
+  <kbd class="sv-kbd sv-kbd--{size}">{@render children?.()}</kbd>
+{/if}
+
+<style>
+  .sv-kbd-group { display: inline-flex; align-items: center; gap: 3px; }
+  .sv-kbd {
+    display: inline-block;
+    min-width: 1.4em;
+    padding: 1px 6px;
+    font-family: var(--sg-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+    font-size: 12px;
+    line-height: 1.5;
+    text-align: center;
+    color: var(--sg-fg, #0f172a);
+    background: var(--sg-muted-bg, color-mix(in srgb, var(--sg-fg, #0f172a) 7%, var(--sg-bg, #fff)));
+    border: 1px solid var(--sg-border, #e2e8f0);
+    border-bottom-width: 2px;
+    border-radius: 5px;
+  }
+  .sv-kbd--sm { font-size: 11px; padding: 0 4px; }
+  .sv-kbd__sep { color: var(--sg-muted, #64748b); font-size: 11px; }
+</style>

package/src/SvList.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+  /**
+   * SvList - a themed ordered / unordered / unstyled list. Pass `items` for the
+   * simple case, or a `children` snippet for full control over each `<li>`.
+   *
+   * <SvList items={['One', 'Two', 'Three']} />
+   * <SvList type="ordered" spacing="lg" items={steps} />
+   */
+  import type { Snippet } from 'svelte'
+
+  type Props = {
+    /** Marker style. `none` drops markers + indentation. */
+    type?: 'unordered' | 'ordered' | 'none'
+    /** Simple string items (skip the snippet). */
+    items?: string[]
+    /** Vertical gap between items. */
+    spacing?: 'sm' | 'md' | 'lg'
+    /** Font size step. */
+    size?: 'sm' | 'md' | 'lg'
+    /** Custom list content (`<li>` elements). Overrides `items`. */
+    children?: Snippet
+  }
+
+  let { type = 'unordered', items, spacing = 'md', size = 'md', children }: Props = $props()
+
+  const gapMap = { sm: '2px', md: '6px', lg: '10px' } as const
+  const sizeMap = { sm: '13px', md: '14px', lg: '16px' } as const
+  const tag = $derived(type === 'ordered' ? 'ol' : 'ul')
+</script>
+
+<svelte:element
+  this={tag}
+  class="sv-list sv-list--{type}"
+  style:--sv-list-gap={gapMap[spacing]}
+  style:font-size={sizeMap[size]}
+>
+  {#if children}
+    {@render children()}
+  {:else if items}
+    {#each items as item}<li>{item}</li>{/each}
+  {/if}
+</svelte:element>
+
+<style>
+  .sv-list {
+    margin: 0;
+    font-family: var(--sg-font, inherit);
+    color: var(--sg-fg, #0f172a);
+    line-height: 1.5;
+  }
+  .sv-list--unordered, .sv-list--ordered { padding-left: 1.4em; }
+  .sv-list--none { padding-left: 0; list-style: none; }
+  .sv-list :global(li) { margin-top: var(--sv-list-gap, 6px); }
+  .sv-list :global(li:first-child) { margin-top: 0; }
+</style>