@svgrid/enterprise 1.2.0 → 2.0.0

package/src/license.ts

@@ -1,90 +1,103 @@
-// Polite license gate. Not crypto - anyone with devtools can extract the key
-// from a deployed bundle. The point is to make commercial use require a
-// transaction, not to defeat reverse engineering.
-//
-// Behavior matrix:
-//
-//   currentKey state                  -> result
-//   ────────────────────────────────────────────────────────────────────
-//   null (no key set)                 -> soft-gate: watermark + console.log,
-//                                        feature still runs
-//   does not start with "SVENTERPRISE-"      -> throws (programmer error)
-//   in REVOKED_KEYS                   -> throws (revoked / leaked / expired)
-//   starts with "SVENTERPRISE-DEV" or
-//     "SVENTERPRISE-EVAL"                    -> works; one-time console.info notice
-//   any other "SVENTERPRISE-..."             -> works silently (paid production)
-
-import { REVOKED_KEYS } from './revoked'
-import { emitUnlicensedNudge } from './watermark'
-import { showUpgradePrompt, type EnterpriseFeatureLabel } from './upgrade-prompt'
-
-const VALID_PREFIX = 'SVENTERPRISE-'
-let currentKey: string | null = null
-let noticedDev = false
-
-export function setLicenseKey(key: string): void {
-  if (typeof key !== 'string' || key.length === 0) {
-    throw new Error('@svgrid/enterprise: setLicenseKey() requires a non-empty string')
-  }
-  currentKey = key
-  noticedDev = false
-}
-
-export function clearLicenseKey(): void {
-  currentKey = null
-  noticedDev = false
-}
-
-export function getLicenseKey(): string | null {
-  return currentKey
-}
-
-/** True if a key is set at all (regardless of validity). */
-export function isLicenseKeySet(): boolean {
-  return currentKey != null
-}
-
-/**
- * True if the current key passes every check: present, valid prefix, not
- * revoked. Use this from callers that want to branch on license status
- * (e.g. UI that hides Pro-only options when unlicensed).
- */
-export function hasValidLicense(): boolean {
-  if (currentKey == null) return false
-  if (!currentKey.startsWith(VALID_PREFIX)) return false
-  if (REVOKED_KEYS.has(currentKey)) return false
-  return true
-}
-
-export function assertEnterpriseLicensed(feature?: EnterpriseFeatureLabel): void {
-  if (currentKey == null) {
-    // Soft-gate: the feature still runs, but the user gets a watermark +
-    // a one-time console.log nudge directing them to pricing, plus a
-    // contextual moment-of-intent upgrade card naming the feature they
-    // just reached for.
-    emitUnlicensedNudge()
-    showUpgradePrompt(feature)
-    return
-  }
-  if (!currentKey.startsWith(VALID_PREFIX)) {
-    throw new Error(
-      '@svgrid/enterprise: invalid license key format (expected "SVENTERPRISE-..." prefix).',
-    )
-  }
-  if (REVOKED_KEYS.has(currentKey)) {
-    throw new Error(
-      '@svgrid/enterprise: this license key has been revoked. ' +
-        'Contact sales@jqwidgets.com for a replacement.',
-    )
-  }
-  if (
-    !noticedDev &&
-    (currentKey.startsWith('SVENTERPRISE-DEV') || currentKey.startsWith('SVENTERPRISE-EVAL'))
-  ) {
-    // eslint-disable-next-line no-console
-    console.info(
-      '@svgrid/enterprise: using a development / evaluation license. Not for production use.',
-    )
-    noticedDev = true
-  }
-}
+// Polite license gate. Not crypto - anyone with devtools can extract the key
+// from a deployed bundle. The point is to make commercial use require a
+// transaction, not to defeat reverse engineering.
+//
+// Behavior matrix:
+//
+//   currentKey state                  -> result
+//   ────────────────────────────────────────────────────────────────────
+//   null (no key set)                 -> soft-gate: watermark + console.log,
+//                                        feature still runs
+//   does not start with "SVENTERPRISE-"      -> throws (programmer error)
+//   in REVOKED_KEYS                   -> throws (revoked / leaked / expired)
+//   starts with "SVENTERPRISE-DEV" or
+//     "SVENTERPRISE-EVAL"                    -> works; one-time console.info notice
+//   any other "SVENTERPRISE-..."             -> works silently (paid production)
+
+import { checkLicenseKey, VALID_PREFIX, type LicenseInfo } from './license-core'
+import { emitUnlicensedNudge } from './watermark'
+import { showUpgradePrompt, type EnterpriseFeatureLabel } from './upgrade-prompt'
+
+export { checkLicenseKey, type LicenseInfo, type LicenseStatus } from './license-core'
+
+let currentKey: string | null = null
+let noticedDev = false
+
+export function setLicenseKey(key: string): void {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('@svgrid/enterprise: setLicenseKey() requires a non-empty string')
+  }
+  currentKey = key
+  noticedDev = false
+}
+
+export function clearLicenseKey(): void {
+  currentKey = null
+  noticedDev = false
+}
+
+export function getLicenseKey(): string | null {
+  return currentKey
+}
+
+/** True if a key is set at all (regardless of validity). */
+export function isLicenseKeySet(): boolean {
+  return currentKey != null
+}
+
+/**
+ * True if the current key passes every check: present, valid prefix, not
+ * revoked. Use this from callers that want to branch on license status
+ * (e.g. UI that hides Pro-only options when unlicensed).
+ */
+export function hasValidLicense(): boolean {
+  return checkLicenseKey(currentKey).valid
+}
+
+/**
+ * Soft-gate a Pro surface: if the current key isn't valid, nudge (watermark +
+ * one-time console log + a moment-of-intent upgrade card naming `feature`) and
+ * return. NEVER throws and NEVER blocks - the feature always runs. This is the
+ * gate the Studio uses, and it's safe to call on the server (the nudges no-op
+ * without a DOM). Idempotent/self-throttling, so call it freely at chokepoints.
+ */
+export function nudgeEnterprise(feature?: EnterpriseFeatureLabel): void {
+  if (checkLicenseKey(currentKey).valid) return
+  emitUnlicensedNudge()
+  showUpgradePrompt(feature)
+}
+
+export function assertEnterpriseLicensed(feature?: EnterpriseFeatureLabel): void {
+  const info: LicenseInfo = checkLicenseKey(currentKey)
+  switch (info.status) {
+    case 'unset':
+      // Soft-gate: the feature still runs, but the user gets a watermark +
+      // a one-time console.log nudge directing them to pricing, plus a
+      // contextual moment-of-intent upgrade card naming the feature they
+      // just reached for.
+      emitUnlicensedNudge()
+      showUpgradePrompt(feature)
+      return
+    case 'invalid':
+      throw new Error(
+        `@svgrid/enterprise: invalid license key format (expected "${VALID_PREFIX}..." prefix).`,
+      )
+    case 'revoked':
+      throw new Error(
+        '@svgrid/enterprise: this license key has been revoked. ' +
+          'Contact sales@jqwidgets.com for a replacement.',
+      )
+    case 'dev':
+    case 'eval':
+      if (!noticedDev) {
+        // eslint-disable-next-line no-console
+        console.info(
+          '@svgrid/enterprise: using a development / evaluation license. Not for production use.',
+        )
+        noticedDev = true
+      }
+      return
+    case 'licensed':
+      return
+  }
+}

package/src/master-detail.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { buildDisplayRows, isDetailRow, toggleExpanded } from './master-detail'
+
+type Order = { id: string; customer: string }
+const orders: Order[] = [
+  { id: 'o1', customer: 'Ann' },
+  { id: 'o2', customer: 'Bob' },
+  { id: 'o3', customer: 'Cara' },
+]
+const idOf = (o: Order) => o.id
+
+describe('toggleExpanded', () => {
+  it('adds then removes an id, immutably', () => {
+    const a = toggleExpanded(new Set(), 'o1')
+    expect([...a]).toEqual(['o1'])
+    const b = toggleExpanded(a, 'o1')
+    expect([...b]).toEqual([])
+    expect([...a]).toEqual(['o1']) // original untouched
+  })
+})
+
+describe('isDetailRow', () => {
+  it('distinguishes detail markers from plain rows', () => {
+    expect(isDetailRow({ __svgridDetail: true, parent: {}, parentId: 'x' })).toBe(true)
+    expect(isDetailRow({ id: 'o1' })).toBe(false)
+    expect(isDetailRow(null)).toBe(false)
+  })
+})
+
+describe('buildDisplayRows', () => {
+  it('returns just the parents when nothing is expanded', () => {
+    const rows = buildDisplayRows(orders, new Set(), idOf)
+    expect(rows).toHaveLength(3)
+    expect(rows.every((r) => !isDetailRow(r))).toBe(true)
+  })
+
+  it('inserts a detail row right after each expanded parent, preserving order', () => {
+    const rows = buildDisplayRows(orders, new Set(['o2']), idOf)
+    expect(rows).toHaveLength(4)
+    expect(isDetailRow(rows[2])).toBe(true) // after o2
+    const detail = rows[2]
+    if (isDetailRow(detail)) {
+      expect(detail.parentId).toBe('o2')
+      expect((detail.parent as Order).customer).toBe('Bob')
+    }
+    // surrounding parents intact
+    expect((rows[1] as Order).id).toBe('o2')
+    expect((rows[3] as Order).id).toBe('o3')
+  })
+
+  it('handles multiple expanded parents', () => {
+    const rows = buildDisplayRows(orders, new Set(['o1', 'o3']), idOf)
+    expect(rows.map((r) => (isDetailRow(r) ? 'detail' : (r as Order).id))).toEqual([
+      'o1',
+      'detail',
+      'o2',
+      'o3',
+      'detail',
+    ])
+  })
+})

package/src/master-detail.ts

@@ -0,0 +1,42 @@
+/**
+ * Master-detail logic. The testable core behind `SvGridMasterDetail.svelte`:
+ * track which parent rows are expanded and splice a synthetic "detail" row in
+ * after each expanded parent, so a single `<SvGrid>` renders both the master
+ * rows and a full-width detail region (via the grid's `isDetailRow` /
+ * `renderDetailRow`). Pure - no Svelte, no DOM.
+ */
+
+/** A synthetic row inserted after an expanded parent; carries the parent it belongs to. */
+export type DetailRow<TParent> = { __svgridDetail: true; parent: TParent; parentId: string }
+
+/** True for the synthetic detail rows produced by `buildDisplayRows`. */
+export function isDetailRow(row: unknown): row is DetailRow<unknown> {
+  return !!row && typeof row === 'object' && (row as { __svgridDetail?: unknown }).__svgridDetail === true
+}
+
+/** Toggle a parent id in the expanded set, returning a new set (immutable). */
+export function toggleExpanded(expanded: ReadonlySet<string>, id: string): Set<string> {
+  const next = new Set(expanded)
+  if (next.has(id)) next.delete(id)
+  else next.add(id)
+  return next
+}
+
+/**
+ * Weave detail rows into the master rows: each expanded parent is followed by a
+ * `DetailRow` marker. Order is otherwise preserved, so the grid renders parents
+ * in place with their detail region directly beneath.
+ */
+export function buildDisplayRows<TParent>(
+  parents: ReadonlyArray<TParent>,
+  expanded: ReadonlySet<string>,
+  getRowId: (parent: TParent) => string,
+): Array<TParent | DetailRow<TParent>> {
+  const out: Array<TParent | DetailRow<TParent>> = []
+  for (const parent of parents) {
+    out.push(parent)
+    const id = getRowId(parent)
+    if (expanded.has(id)) out.push({ __svgridDetail: true, parent, parentId: id })
+  }
+  return out
+}

package/src/print.ts

@@ -1,127 +1,107 @@
-import type { RowData, TableFeatures, SvGridApi } from '@svgrid/grid'
-import { assertEnterpriseLicensed } from './license'
-import { installSmartShim } from './smart-shim'
-import type { ExportColumn } from './export'
-
-export type PrintOptions<TData> = {
-  /** Title placed above the printed grid. Defaults to "Grid". */
-  title?: string
-  /** Columns to print. If omitted, every key of the first row is printed. */
-  columns?: ReadonlyArray<ExportColumn>
-  /** Rows to print. If omitted, the api's displayed rows are used. */
-  rows?: ReadonlyArray<TData>
-  /**
-   * Print orientation hint. Browsers honor it via `@page { size: ... }`.
-   * Defaults to "portrait".
-   */
-  orientation?: 'portrait' | 'landscape'
-}
-
-type DataExporterCtor = new (
-  options: Record<string, unknown>,
-) => {
-  exportData(
-    data: ReadonlyArray<Record<string, unknown>>,
-    format: string,
-    filename?: string,
-  ): unknown
-}
-
-let exporterCtorPromise: Promise<DataExporterCtor> | null = null
-
-async function getDataExporter(): Promise<DataExporterCtor> {
-  if (typeof window === 'undefined') {
-    throw new Error('@svgrid/enterprise: print requires a browser environment')
-  }
-  if (!exporterCtorPromise) {
-    exporterCtorPromise = (async () => {
-      installSmartShim()
-      await import('./smart.export.js')
-      const Ctor = window.Smart?.Utilities?.DataExporter as DataExporterCtor | undefined
-      if (!Ctor) {
-        throw new Error('@svgrid/enterprise: failed to load Smart.Utilities.DataExporter')
-      }
-      return Ctor
-    })()
-  }
-  return exporterCtorPromise
-}
-
-export async function printGrid<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(api: SvGridApi<TFeatures, TData>, opts?: PrintOptions<TData>): Promise<void> {
-  assertEnterpriseLicensed('Print')
-  const sourceRows: ReadonlyArray<TData> = opts?.rows ?? api.getDisplayedRows()
-  let cols: ReadonlyArray<ExportColumn>
-  if (opts?.columns && opts.columns.length > 0) {
-    cols = opts.columns
-  } else if (sourceRows.length > 0) {
-    cols = Object.keys(sourceRows[0] as Record<string, unknown>)
-      .filter((k) => !k.startsWith('_'))
-      .map((field) => ({ field }))
-  } else {
-    cols = []
-  }
-  if (sourceRows.length === 0) {
-    throw new Error('@svgrid/enterprise: nothing to print - the grid has no rows')
-  }
-  const header: Record<string, unknown> = {}
-  for (const c of cols) header[c.field] = c.header ?? c.field
-  const projected: Array<Record<string, unknown>> = [header]
-  for (const r of sourceRows) {
-    const out: Record<string, unknown> = {}
-    const src = r as unknown as Record<string, unknown>
-    for (const c of cols) out[c.field] = src[c.field]
-    projected.push(out)
-  }
-
-  const Ctor = await getDataExporter()
-  const exporter = new Ctor({ exportHeader: true })
-  // No filename means exportData returns the HTML string instead of triggering
-  // a download (see downloadFile in smart.export.js: when filename is falsy it
-  // returns the raw content unchanged).
-  const html = exporter.exportData(projected, 'html') as string
-
-  const title = (opts?.title ?? 'Grid').replace(/[<>]/g, '')
-  const orientation = opts?.orientation ?? 'portrait'
-  const wrapped = `<!DOCTYPE html>
-<html><head><meta charset="utf-8"><title>${title}</title>
-<style>
-  @page { size: ${orientation}; margin: 14mm; }
-  @media print { body { -webkit-print-color-adjust: exact; print-color-adjust: exact; } }
-  body { font-family: -apple-system, "Segoe UI", Roboto, sans-serif; color: #111; }
-  h1 { font-size: 16pt; margin: 0 0 8mm 0; }
-  table { border-collapse: collapse; width: 100%; font-size: 9pt; }
-  th, td { border: 1px solid #444; padding: 4px 6px; text-align: left; }
-  thead { background: #eee; }
-</style></head>
-<body>
-  <h1>${title}</h1>
-  ${html.replace(/^[\s\S]*?<body>/i, '').replace(/<\/body>[\s\S]*$/i, '')}
-</body></html>`
-
-  const w = window.open('', '_blank', 'width=900,height=700')
-  if (!w) {
-    throw new Error(
-      '@svgrid/enterprise: print() could not open a window - the browser blocked the popup',
-    )
-  }
-  w.document.open()
-  w.document.write(wrapped)
-  w.document.close()
-  // Give the new window one tick to paint before invoking print.
-  w.focus()
-  w.addEventListener('load', () => {
-    setTimeout(() => w.print(), 50)
-  })
-  // Some browsers fire 'load' before the listener attaches if document was
-  // already complete. Fall back: try a print after a short delay regardless.
-  setTimeout(() => {
-    try {
-      w.print()
-    } catch {
-      // ignore - listener path will have fired
-    }
-  }, 300)
-}
+import type { RowData, TableFeatures, SvGridApi } from '@svgrid/grid'
+import { assertEnterpriseLicensed } from './license'
+import {
+  buildLinkResolver,
+  projectRows,
+  resolveColumns,
+  resolveRowSource,
+  type ExportColumn,
+  type ExportRowSource,
+} from './export'
+import { buildPrintDocument, type PrintDocOptions } from './export-print'
+import { buildConditionalResolver } from './export-conditional'
+import type { ConditionalFormat } from '@svgrid/grid/format'
+
+export type PrintOptions<TData> = {
+  /** Title placed above the printed grid. Defaults to "Grid". */
+  title?: string
+  /** Smaller line under the title. */
+  subtitle?: string
+  /** Logo data URL, shown above the title. */
+  logo?: string
+  /** Columns to print. Defaults to the grid's own visible columns (with their
+   *  header labels + `format`, so values print formatted). */
+  columns?: ReadonlyArray<ExportColumn<TData>>
+  /** Rows to print. Defaults to the current view; accepts the same
+   *  `'displayed' | 'selected' | 'all'` shorthand as `exportData`. */
+  rows?: ExportRowSource<TData>
+  /** Write raw underlying values instead of the formatted display values. */
+  rawValues?: boolean
+  /** Print orientation. Browsers honor it via `@page { size }`. Default "portrait". */
+  orientation?: 'portrait' | 'landscape'
+  /** `@page` size keyword, e.g. 'A4' | 'Letter'. Combined with orientation. */
+  pageSize?: string
+  /** Page margin, e.g. '14mm'. Default '14mm'. */
+  margin?: string
+  /** Zebra-stripe rows. Default true. */
+  zebra?: boolean
+  /** Header row background color. */
+  headerColor?: string
+  /** Conditional formatting rules (same array as `<SvGrid conditionalFormats>`);
+   *  carried into the print view as cell background / color / bold + icons. */
+  conditionalFormats?: ReadonlyArray<ConditionalFormat<TData>>
+}
+
+export async function printGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts?: PrintOptions<TData>): Promise<void> {
+  assertEnterpriseLicensed('Print')
+  if (typeof window === 'undefined') {
+    throw new Error('@svgrid/enterprise: print requires a browser environment')
+  }
+  const sourceRows = resolveRowSource(api, opts?.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to print - the grid has no rows')
+  }
+  const cols = resolveColumns(api, { columns: opts?.columns }, sourceRows)
+  const fields = cols.map((c) => c.field)
+  // Formatted display values (or raw when asked) so the print matches the grid.
+  const projected = await projectRows(sourceRows, cols, { rawValues: opts?.rawValues })
+  const dataRows = projected.slice(1).map((r) => fields.map((f) => String(r[f] ?? '')))
+  const columns = cols.map((c) => ({ header: c.header ?? c.field, align: c.align }))
+
+  const docOpts: PrintDocOptions = {
+    title: opts?.title ?? 'Grid',
+    subtitle: opts?.subtitle,
+    logo: opts?.logo,
+    orientation: opts?.orientation ?? 'portrait',
+    pageSize: opts?.pageSize,
+    margin: opts?.margin,
+    zebra: opts?.zebra,
+    headerColor: opts?.headerColor,
+  }
+  const visual = buildConditionalResolver(cols, sourceRows, opts?.conditionalFormats)
+  const link = buildLinkResolver(cols, sourceRows)
+  const html = buildPrintDocument({
+    columns,
+    rows: dataRows,
+    cellStyle: (r, c) => visual(r, c),
+    cellLink: link,
+    opts: docOpts,
+  })
+
+  const w = window.open('', '_blank', 'width=900,height=700')
+  if (!w) {
+    throw new Error(
+      '@svgrid/enterprise: print() could not open a window - the browser blocked the popup',
+    )
+  }
+  w.document.open()
+  w.document.write(html)
+  w.document.close()
+  // Give the new window one tick to paint before invoking print.
+  w.focus()
+  w.addEventListener('load', () => {
+    setTimeout(() => w.print(), 50)
+  })
+  // Some browsers fire 'load' before the listener attaches if the document was
+  // already complete. Fall back: try a print after a short delay regardless.
+  setTimeout(() => {
+    try {
+      w.print()
+    } catch {
+      // ignore - the listener path will have fired
+    }
+  }, 300)
+}