@svgrid/enterprise 3.0.1 → 3.0.2

package/dist/SvSheet.svelte.d.ts

@@ -0,0 +1,142 @@
+/**
+   * The spreadsheet shell: everything between the ribbon and the sheet tabs.
+   *
+   *   SvSheetRibbon      Home / Insert / Formulas / Data
+   *   SvFormulaBar       Name Box + fx, showing the RAW text of the active cell
+   *   SvGrid             A..Z column headers over the built-in 1..N gutter
+   *   SvSheetTabs        sheet tabs
+   *   status bar         Sum / Average / Count of the selection, as Excel has
+   *
+   * Composition, not a second grid. Every part here already existed and was
+   * being re-assembled by hand in four separate demos; the value of the
+   * component is that the wiring BETWEEN them is done once and correctly -
+   * the formula bar shows the raw text rather than the computed value, the
+   * format store is keyed by row id so sorting cannot strand formatting, the
+   * ribbon and the keyboard run the same actions, and the tab strip is told
+   * when a shortcut moved the active sheet.
+   *
+   *   <SvSheet workbook={wb} />
+   *
+   * That is the whole required API. Everything else is opt-out.
+   */
+import { type SvGridApi, type TableFeatures } from '@svgrid/grid';
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+import type { Workbook, SheetData } from './sheet/workbook.js';
+import { type SheetDocument, type SheetState, type SheetChangeReason } from './sheet/document.js';
+import { type CellFormatEntry } from './sheet/format-store.js';
+import type { RibbonActionId } from './sheet/ribbon.js';
+/**
+ * A grid row carries the RAW text of every cell on it, keyed by column
+ * letter, as well as its position.
+ *
+ * It would be tempting to keep the values only in the workbook and let the
+ * cell snippet read them, since the snippet is what paints. That does not
+ * work, and not only for rendering: the grid's own machinery reads
+ * `row[field]`, so an empty row object means `cmd.getCellValue` returns
+ * undefined for every cell, and then Ctrl+Arrow thinks the sheet is blank,
+ * AutoSum finds no run to total, and the inline editor has nothing to open
+ * on. The workbook stays authoritative; this is its projection.
+ */
+type SheetRow = {
+    id: string;
+    index: number;
+} & Record<string, string | number>;
+type SheetApi = SvGridApi<TableFeatures, SheetRow>;
+type Props = {
+    /**
+     * The document to edit: the workbook plus everything a sheet keeps beside
+     * its cells (formats, sizes, hidden lines, frozen panes, comments). Build
+     * one with `createSheetDocument` to save it, restore it or listen to it
+     * outside the component; without it the shell makes its own from
+     * `workbook` or `data` and hands it back through `onReady`.
+     */
+    document?: SheetDocument;
+    /** The workbook to edit. One is created from `data` when absent. */
+    workbook?: Workbook;
+    /** Seed sheets, when not supplying a workbook. */
+    data?: ReadonlyArray<SheetData>;
+    /** Minimum grid size, so a sparse sheet still looks like a sheet. */
+    rows?: number;
+    columns?: number;
+    /**
+     * Grid viewport height in pixels, or `'100%'` to fill the parent.
+     *
+     * The chrome around the grid - ribbon, formula bar, tabs, status bar -
+     * is about 290px tall, so a fixed grid height is a fixed component
+     * height with that added on. In a flex column that is too tall for the
+     * space, the tab strip is what gets pushed under whatever comes next.
+     * With `'100%'` the component is a flex item that fills its column and
+     * the grid takes whatever the chrome leaves.
+     */
+    height?: number | '100%';
+    /** Default column width. */
+    columnWidth?: number;
+    /** Row height in pixels. Excel's is 20 at 100%; 22 fits the grid's 13px font. */
+    rowHeight?: number;
+    /**
+     * `theme` (the default) paints the shell with the host's `--sg-*`
+     * tokens, so it follows whatever theme the app around it runs, as the
+     * grid does. `excel` pins Excel's own palette and geometry, light or
+     * dark with the page, for an app that wants it to read as Excel
+     * whatever the theme.
+     */
+    look?: 'excel' | 'theme';
+    /**
+     * Per-column overrides, keyed by column letter: `{ A: 150 }`.
+     *
+     * A sheet's first column usually holds labels and the rest hold numbers,
+     * so one width for all of them truncates the only column that needs the
+     * room. Columns stay drag-resizable either way.
+     */
+    columnWidths?: Readonly<Record<string, number>>;
+    /**
+     * Cell formats to start with, keyed by A1 address: `{ B2: { bold: true },
+     * 'E13': { numFmt: '0.0%' } }`.
+     *
+     * A bare address formats the sheet that is active when the shell mounts.
+     * Qualify it to reach another sheet, the way a formula would:
+     * `{ 'Orders!F2': { numFmt: '$#,##0.00' }, "'Price list'!C2": ... }`.
+     * Formats are per sheet, as they are in Excel; a fill on Summary!C5 says
+     * nothing about Orders!C5.
+     *
+     * Without this the sheet can only be formatted by hand after it loads,
+     * which makes it impossible to ship a document that opens looking the way
+     * it was saved. Applied once at mount; after that the stores own it.
+     */
+    formats?: Readonly<Record<string, CellFormatEntry>>;
+    /**
+     * Ribbon buttons the shell has nothing behind: Insert > Table and
+     * Insert > Chart. Left off unless listed here, which says the
+     * application answers them in `onAction`.
+     */
+    extras?: ReadonlyArray<'insert-table' | 'insert-chart'>;
+    /** Hide any part of the chrome. */
+    showRibbon?: boolean;
+    showFormulaBar?: boolean;
+    showTabs?: boolean;
+    showStatusBar?: boolean;
+    /**
+     * Every action the ribbon, the cell menu, the formula bar and the
+     * shortcuts raise. The shell has a dialog of its own for Find and
+     * Replace, Paste Special, Format Cells and Insert Function; a handler
+     * that returns `true` has taken the action over and the shell's dialog
+     * stays closed, so an application can put its own in their place.
+     */
+    onAction?: (action: RibbonActionId, cmd: GridCommandContext) => void | boolean;
+    onReady?: (api: SheetApi, document: SheetDocument) => void;
+    /**
+     * Something the user did landed in the document: a cell, a format, a
+     * size, a hidden line, a frozen pane, a sheet, a comment, or a structural
+     * edit. Called once per tick with every reason since the last call, so a
+     * paste of forty cells is one call; the natural place for an autosave
+     * (`getState()`, debounced). Undo and redo report too.
+     */
+    onChange?: (reasons: ReadonlyArray<SheetChangeReason>) => void;
+};
+declare const SvSheet: import("svelte").Component<Props, {
+    getState: () => SheetState;
+    setState: (state: SheetState) => void;
+    refresh: () => void;
+}, "">;
+type SvSheet = ReturnType<typeof SvSheet>;
+export default SvSheet;

package/dist/SvSheetComment.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+  /**
+   * The comment editor: Excel's note box, opened by New Comment, Edit
+   * Comment, Shift+F2 and the cell menu. A textarea over the text, Save,
+   * and Delete when there is something to delete. As in Excel the text is
+   * kept whatever closes the box: Escape and a click elsewhere save what
+   * was typed, which is why every keystroke is reported through `onDraft`
+   * and the shell saves the draft on dismissal. Ctrl+Enter saves too.
+   * The shell mounts it inside the popover anchored to the cell.
+   */
+  type Props = {
+    /** The comment as it is, empty for a new one. */
+    text: string
+    /** A1 of the cell, for the heading. */
+    address: string
+    /** Every change of the text, so the shell can keep it on dismissal. */
+    onDraft: (text: string) => void
+    onSave: (text: string) => void
+    onDelete: () => void
+  }
+
+  let { text, address, onDraft, onSave, onDelete }: Props = $props()
+
+  let draft = $state('')
+  let box = $state<HTMLTextAreaElement | null>(null)
+
+  $effect(() => {
+    draft = text
+    queueMicrotask(() => {
+      if (!box) return
+      box.focus()
+      box.setSelectionRange(box.value.length, box.value.length)
+    })
+  })
+
+  function onKeyDown(event: KeyboardEvent) {
+    if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) { event.preventDefault(); onSave(draft) }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="sv-sheet-comment" role="dialog" aria-label="Comment on {address}" onkeydown={onKeyDown}>
+  <div class="head">{address}</div>
+  <textarea
+    bind:this={box}
+    bind:value={draft}
+    oninput={() => onDraft(draft)}
+    rows="4"
+    aria-label="Comment"
+    placeholder="Type a comment"
+    spellcheck="false"
+  ></textarea>
+  <div class="sv-sheet-dialog-buttons">
+    <span class="keys">Ctrl+Enter saves</span>
+    <button type="button" class="btn primary" onclick={() => onSave(draft)}>Save</button>
+    {#if text}
+      <button type="button" class="btn" onclick={onDelete}>Delete</button>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .sv-sheet-comment {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    width: 260px;
+    padding: 8px;
+    font-size: 12px;
+    color: var(--sg-fg, #242424);
+  }
+  .head {
+    font-weight: 600;
+    color: var(--sg-muted, #616161);
+  }
+  .keys {
+    margin-right: auto;
+    font-size: 11px;
+    color: var(--sg-muted, #616161);
+  }
+  textarea {
+    width: 100%;
+    box-sizing: border-box;
+    resize: vertical;
+    min-height: 64px;
+    padding: 6px 8px;
+    font: inherit;
+    line-height: 1.4;
+    color: inherit;
+    background: var(--sg-bg, #fff);
+    border: 1px solid var(--sg-border, #d1d1d1);
+    border-radius: 3px;
+  }
+  textarea:focus-visible {
+    outline: 2px solid var(--sg-focus-ring, var(--sg-accent, #107c41));
+    outline-offset: -1px;
+  }
+</style>

package/dist/SvSheetComment.svelte.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The comment editor: Excel's note box, opened by New Comment, Edit
+ * Comment, Shift+F2 and the cell menu. A textarea over the text, Save,
+ * and Delete when there is something to delete. As in Excel the text is
+ * kept whatever closes the box: Escape and a click elsewhere save what
+ * was typed, which is why every keystroke is reported through `onDraft`
+ * and the shell saves the draft on dismissal. Ctrl+Enter saves too.
+ * The shell mounts it inside the popover anchored to the cell.
+ */
+type Props = {
+    /** The comment as it is, empty for a new one. */
+    text: string;
+    /** A1 of the cell, for the heading. */
+    address: string;
+    /** Every change of the text, so the shell can keep it on dismissal. */
+    onDraft: (text: string) => void;
+    onSave: (text: string) => void;
+    onDelete: () => void;
+};
+declare const SvSheetComment: import("svelte").Component<Props, {}, "">;
+type SvSheetComment = ReturnType<typeof SvSheetComment>;
+export default SvSheetComment;

package/dist/SvSheetConditionalFormat.svelte

@@ -0,0 +1,162 @@
+<script lang="ts">
+  /**
+   * Excel's small conditional-formatting dialogs, one component: Greater
+   * Than..., Less Than..., Between..., Equal To..., Text that Contains...,
+   * Duplicate Values..., Top 10 Items..., Bottom 10 Items..., Above Average
+   * and Below Average. Each is a sentence with its inputs and the "with"
+   * picker of Excel's six styles. It opens empty for a new rule from the
+   * ribbon, or on a rule from Manage Rules > Edit, and hands back the rule's
+   * body for the shell to place.
+   */
+  import { SvModal } from '@svgrid/grid'
+  import { CF_PRESET_STYLES, type CfPreset, type CfBody, type CfStyledRule } from './sheet/conditional-formats'
+
+  type Props = {
+    open?: boolean
+    preset: CfPreset
+    /** The rule being edited, for Manage Rules > Edit. */
+    rule?: CfStyledRule | null
+    /** The selection as A1, for the heading. */
+    address: string
+    onApply: (body: CfBody) => void
+    onClose?: () => void
+  }
+
+  let { open = $bindable(false), preset, rule = null, address, onApply, onClose }: Props = $props()
+
+  const TITLES: Record<CfPreset, string> = {
+    greater: 'Greater Than', less: 'Less Than', between: 'Between', equal: 'Equal To',
+    text: 'Text That Contains', duplicates: 'Duplicate Values',
+    top10: 'Top 10 Items', bottom10: 'Bottom 10 Items', aboveAverage: 'Above Average', belowAverage: 'Below Average',
+  }
+  const LEADS: Record<CfPreset, string> = {
+    greater: 'Format cells that are GREATER THAN:', less: 'Format cells that are LESS THAN:',
+    between: 'Format cells that are BETWEEN:', equal: 'Format cells that are EQUAL TO:',
+    text: 'Format cells that contain the text:', duplicates: 'Format cells that contain:',
+    top10: 'Format cells that rank in the TOP:', bottom10: 'Format cells that rank in the BOTTOM:',
+    aboveAverage: 'Format cells that are ABOVE AVERAGE for the selected range:',
+    belowAverage: 'Format cells that are BELOW AVERAGE for the selected range:',
+  }
+
+  let value1 = $state('')
+  let value2 = $state('')
+  let rank = $state('10')
+  let percent = $state(false)
+  let unique = $state(false)
+  let styleId = $state(CF_PRESET_STYLES[0]!.id)
+  let first = $state<HTMLInputElement | HTMLSelectElement | null>(null)
+
+  $effect(() => {
+    if (!open) return
+    value1 = ''
+    value2 = ''
+    rank = '10'
+    percent = false
+    unique = false
+    styleId = CF_PRESET_STYLES[0]!.id
+    const r = rule
+    if (r) {
+      if (r.kind === 'cellIs') { value1 = r.value1; value2 = r.value2 ?? '' }
+      else if (r.kind === 'text') value1 = r.value
+      else if (r.kind === 'duplicates') unique = !!r.unique
+      else if (r.kind === 'topBottom') { rank = String(r.rank); percent = !!r.percent }
+      const match = CF_PRESET_STYLES.find((p) => JSON.stringify(p.style) === JSON.stringify(r.style))
+      if (match) styleId = match.id
+    }
+    queueMicrotask(() => first?.focus())
+  })
+
+  const needsValue = $derived(preset === 'greater' || preset === 'less' || preset === 'between' || preset === 'equal' || preset === 'text')
+  const valid = $derived(
+    (!needsValue || value1.trim() !== '')
+      && (preset !== 'between' || value2.trim() !== '')
+      && ((preset !== 'top10' && preset !== 'bottom10') || (Number.isInteger(Number(rank)) && Number(rank) > 0)),
+  )
+
+  function body(): CfBody {
+    const style = CF_PRESET_STYLES.find((p) => p.id === styleId)?.style ?? CF_PRESET_STYLES[0]!.style
+    switch (preset) {
+      case 'greater': return { kind: 'cellIs', operator: 'greater', value1: value1.trim(), style }
+      case 'less': return { kind: 'cellIs', operator: 'less', value1: value1.trim(), style }
+      case 'between': return { kind: 'cellIs', operator: 'between', value1: value1.trim(), value2: value2.trim(), style }
+      case 'equal': return { kind: 'cellIs', operator: 'equal', value1: value1.trim(), style }
+      case 'text': return { kind: 'text', match: 'contains', value: value1.trim(), style }
+      case 'duplicates': return { kind: 'duplicates', unique, style }
+      case 'top10': return { kind: 'topBottom', top: true, rank: Number(rank), percent, style }
+      case 'bottom10': return { kind: 'topBottom', top: false, rank: Number(rank), percent, style }
+      case 'aboveAverage': return { kind: 'average', above: true, style }
+      case 'belowAverage': return { kind: 'average', above: false, style }
+    }
+  }
+
+  function ok() {
+    if (!valid) return
+    onApply(body())
+    open = false
+    onClose?.()
+  }
+
+  function close() {
+    open = false
+    onClose?.()
+  }
+
+  const sample = $derived(CF_PRESET_STYLES.find((p) => p.id === styleId)?.style ?? {})
+</script>
+
+<SvModal bind:open onClose={onClose} title={TITLES[preset]} size="sm" width={440}>
+  <form class="sv-sheet-dialog cf" onsubmit={(e) => { e.preventDefault(); ok() }}>
+    <div class="where">{address}</div>
+    <div class="lead">{LEADS[preset]}</div>
+    <div class="row">
+      {#if preset === 'between'}
+        <input bind:this={first} type="text" bind:value={value1} aria-label="Lower value" spellcheck="false" />
+        <span>and</span>
+        <input type="text" bind:value={value2} aria-label="Upper value" spellcheck="false" />
+      {:else if needsValue}
+        <input bind:this={first} type="text" bind:value={value1} aria-label="Value" spellcheck="false" placeholder={preset === 'text' ? 'text' : 'value or =formula'} />
+      {:else if preset === 'duplicates'}
+        <select bind:this={first} bind:value={unique} aria-label="Duplicate or unique">
+          <option value={false}>Duplicate</option>
+          <option value={true}>Unique</option>
+        </select>
+        <span>values</span>
+      {:else if preset === 'top10' || preset === 'bottom10'}
+        <input bind:this={first} type="number" min="1" bind:value={rank} aria-label="How many" />
+        <label class="check"><input type="checkbox" bind:checked={percent} /> % of selected range</label>
+      {/if}
+      <span>with</span>
+      <select bind:value={styleId} aria-label="Format style">
+        {#each CF_PRESET_STYLES as p (p.id)}<option value={p.id}>{p.label}</option>{/each}
+      </select>
+    </div>
+    <div class="sample" style:background={sample.fill ?? 'transparent'} style:color={sample.color ?? 'inherit'}>AaBbCcYyZz</div>
+  </form>
+  {#snippet footer()}
+    <div class="sv-sheet-dialog-buttons">
+      <button type="button" class="btn primary" onclick={ok} disabled={!valid}>OK</button>
+      <button type="button" class="btn" onclick={close}>Cancel</button>
+    </div>
+  {/snippet}
+</SvModal>
+
+<style>
+  .where { color: var(--sg-muted, #616161); }
+  .lead { font-weight: 600; }
+  .row {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px;
+  }
+  .row input[type="text"] { flex: 1 1 110px; min-width: 90px; }
+  .row input[type="number"] { width: 64px; }
+  .row select { max-width: 240px; }
+  .sample {
+    width: 120px;
+    padding: 4px 10px;
+    border: 1px solid var(--sg-border, #d1d1d1);
+    border-radius: var(--sg-radius, 3px);
+    text-align: center;
+  }
+</style>

package/dist/SvSheetConditionalFormat.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type CfPreset, type CfBody, type CfStyledRule } from './sheet/conditional-formats.js';
+type Props = {
+    open?: boolean;
+    preset: CfPreset;
+    /** The rule being edited, for Manage Rules > Edit. */
+    rule?: CfStyledRule | null;
+    /** The selection as A1, for the heading. */
+    address: string;
+    onApply: (body: CfBody) => void;
+    onClose?: () => void;
+};
+declare const SvSheetConditionalFormat: import("svelte").Component<Props, {}, "open">;
+type SvSheetConditionalFormat = ReturnType<typeof SvSheetConditionalFormat>;
+export default SvSheetConditionalFormat;