@svgrid/enterprise 2.3.2 → 2.5.0

package/src/edit-panel.test.ts

@@ -4,6 +4,8 @@ import {
   buildInitialValues,
   controlKind,
   editMode,
+  evalValidationRules,
+  fieldState,
   rowId,
   toSubmitValues,
   validateAll,
@@ -13,7 +15,9 @@ import {
   fromNumberValue,
   toSliderValue,
   toTags,
+  visibleFormFields,
 } from './edit-panel'
+import { schemaToFormFields, type FormFieldDescriptor } from './schema'
 
 type Customer = {
   id: string
@@ -175,39 +179,144 @@ describe('rowId', () => {
     expect(rowId(schema, { id: 99 } as unknown as Customer)).toBe('99')
   })
 })
-
-describe('editor value coercion', () => {
-  it('formats a Date to a local yyyy-MM-dd (no UTC shift)', () => {
-    // Local midnight - toISOString would shift the day in negative-offset zones; local formatting must not.
-    const d = new Date(2024, 0, 2, 0, 0) // 2 Jan 2024, local
-    expect(toDateString(d)).toBe('2024-01-02')
-    expect(toDateString(null)).toBe('')
-  })
-
-  it('formats a Date to a local yyyy-MM-ddTHH:mm', () => {
-    expect(toDateTimeString(new Date(2024, 2, 4, 9, 5))).toBe('2024-03-04T09:05')
-    expect(toDateTimeString(null)).toBe('')
-  })
-
-  it('coerces numbers in/out with the empty-string convention', () => {
-    expect(toNumberValue(1200)).toBe(1200)
-    expect(toNumberValue('1200')).toBeNull() // strings are not numbers
-    expect(toNumberValue(NaN)).toBeNull()
-    expect(fromNumberValue(null)).toBe('')
-    expect(fromNumberValue(0)).toBe(0) // 0 is a real value, not empty
-  })
-
-  it('slider falls back to min when unset', () => {
-    expect(toSliderValue(42, 0)).toBe(42)
-    expect(toSliderValue('', 10)).toBe(10)
-    expect(toSliderValue(undefined, 5)).toBe(5)
-  })
-
-  it('coerces tags from arrays, comma strings, or empty', () => {
-    expect(toTags(['a', 'b'])).toEqual(['a', 'b'])
-    expect(toTags('a, b ,c')).toEqual(['a', 'b', 'c'])
-    expect(toTags('')).toEqual([])
-    expect(toTags(null)).toEqual([])
-    expect(toTags([1, 2])).toEqual(['1', '2'])
-  })
-})
+
+describe('editor value coercion', () => {
+  it('formats a Date to a local yyyy-MM-dd (no UTC shift)', () => {
+    // Local midnight - toISOString would shift the day in negative-offset zones; local formatting must not.
+    const d = new Date(2024, 0, 2, 0, 0) // 2 Jan 2024, local
+    expect(toDateString(d)).toBe('2024-01-02')
+    expect(toDateString(null)).toBe('')
+  })
+
+  it('formats a Date to a local yyyy-MM-ddTHH:mm', () => {
+    expect(toDateTimeString(new Date(2024, 2, 4, 9, 5))).toBe('2024-03-04T09:05')
+    expect(toDateTimeString(null)).toBe('')
+  })
+
+  it('coerces numbers in/out with the empty-string convention', () => {
+    expect(toNumberValue(1200)).toBe(1200)
+    expect(toNumberValue('1200')).toBeNull() // strings are not numbers
+    expect(toNumberValue(NaN)).toBeNull()
+    expect(fromNumberValue(null)).toBe('')
+    expect(fromNumberValue(0)).toBe(0) // 0 is a real value, not empty
+  })
+
+  it('slider falls back to min when unset', () => {
+    expect(toSliderValue(42, 0)).toBe(42)
+    expect(toSliderValue('', 10)).toBe(10)
+    expect(toSliderValue(undefined, 5)).toBe(5)
+  })
+
+  it('coerces tags from arrays, comma strings, or empty', () => {
+    expect(toTags(['a', 'b'])).toEqual(['a', 'b'])
+    expect(toTags('a, b ,c')).toEqual(['a', 'b', 'c'])
+    expect(toTags('')).toEqual([])
+    expect(toTags(null)).toEqual([])
+    expect(toTags([1, 2])).toEqual(['1', '2'])
+  })
+})
+
+// --- the form builder: value-driven fields -----------------------------------
+
+/** `field <op> value` as a serializable predicate leaf. */
+const cmp = (column: string, op: string, value: unknown) =>
+  ({ kind: 'cmp', column, op, value }) as never
+
+type Order = { id: string; reason: string; other: string; total: number; approver: string }
+
+const orders: EntitySchema<Order> = {
+  name: 'orders',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'reason', type: 'enum', options: [{ value: 'damaged', label: 'Damaged' }, { value: 'other', label: 'Other' }] },
+    // Only asked for, and only demanded, when the reason is "other".
+    {
+      field: 'other',
+      type: 'text',
+      when: { visible: cmp('reason', 'equals', 'other'), required: cmp('reason', 'equals', 'other') },
+    },
+    { field: 'total', type: 'number' },
+    // Locked once the order is large enough to need sign-off.
+    { field: 'approver', type: 'text', when: { disabled: cmp('total', 'lessThan', 1000) } },
+  ],
+}
+
+describe('conditional fields', () => {
+  const specOf = (name: string) => schemaToFormFields(orders).find((f) => f.field === name)!
+
+  it('shows and demands a field only while its condition holds', () => {
+    const hidden = fieldState(specOf('other'), { reason: 'damaged', other: '' })
+    expect(hidden.visible).toBe(false)
+    expect(hidden.required).toBe(false)
+
+    const shown = fieldState(specOf('other'), { reason: 'other', other: '' })
+    expect(shown.visible).toBe(true)
+    expect(shown.required).toBe(true)
+  })
+
+  it('locks a field while its disabled condition holds, and readonly always wins', () => {
+    expect(fieldState(specOf('approver'), { total: 10 }).disabled).toBe(true)
+    expect(fieldState(specOf('approver'), { total: 5000 }).disabled).toBe(false)
+    expect(fieldState(specOf('id'), { total: 5000 }).disabled).toBe(true)
+  })
+
+  it('lists only the fields the form is currently showing', () => {
+    expect(visibleFormFields(orders, { reason: 'damaged' }).map((f) => f.field)).not.toContain('other')
+    expect(visibleFormFields(orders, { reason: 'other' }).map((f) => f.field)).toContain('other')
+  })
+
+  it('never blocks a save on a field the user cannot see', async () => {
+    // `other` is required-when-visible, but the reason is "damaged", so it is
+    // neither shown nor demanded.
+    expect(await validateAll(orders, { reason: 'damaged', other: '', total: 1 })).toEqual({})
+    expect(await validateAll(orders, { reason: 'other', other: '', total: 1 })).toEqual({
+      other: 'Other is required',
+    })
+  })
+
+  it('leaves a hidden field out of the payload, so a stale value is never written', () => {
+    const hidden = toSubmitValues(orders, { reason: 'damaged', other: 'stale text', total: 1, approver: '' })
+    expect(hidden).not.toHaveProperty('other')
+    const shown = toSubmitValues(orders, { reason: 'other', other: 'kept', total: 1, approver: '' })
+    expect(shown.other).toBe('kept')
+  })
+
+  it('falls back to showing a field when its condition is malformed', () => {
+    // A broken rule must never hide data or block a save.
+    const broken: FormFieldDescriptor = {
+      field: 'x', label: 'X', type: 'text', editorType: 'text',
+      required: false, readonly: false, span: 1,
+      when: { visible: { kind: 'nonsense' } as never },
+    }
+    expect(fieldState(broken, {}).visible).toBe(true)
+    expect(fieldState(broken, {}).disabled).toBe(false)
+  })
+})
+
+describe('no-code validation rules at runtime', () => {
+  it('applies each operator the generated server applies', () => {
+    const values = { name: 'ab', qty: 5, max: 3 }
+    expect(evalValidationRules([{ field: 'name', op: 'minLen', value: 3, message: 'Too short' }], values))
+      .toEqual({ name: 'Too short' })
+    expect(evalValidationRules([{ field: 'name', op: 'minLen', value: 2, message: 'Too short' }], values)).toEqual({})
+    expect(evalValidationRules([{ field: 'qty', op: 'lte', compareTo: 'max', message: 'Over the max' }], values))
+      .toEqual({ qty: 'Over the max' })
+    expect(evalValidationRules([{ field: 'missing', op: 'required', message: 'Needed' }], values))
+      .toEqual({ missing: 'Needed' })
+  })
+
+  it('runs as part of validateAll, so a rule fires in the form, not just on the server', async () => {
+    const withRules: EntitySchema<{ id: string; code: string }> = {
+      name: 'things',
+      idField: 'id',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true, readonly: true },
+        { field: 'code', type: 'text' },
+      ],
+      validations: [{ field: 'code', op: 'minLen', value: 4, message: 'Code needs 4+ characters' }],
+    }
+    expect(await validateAll(withRules, { code: 'ab' })).toEqual({ code: 'Code needs 4+ characters' })
+    expect(await validateAll(withRules, { code: 'abcd' })).toEqual({})
+  })
+})

package/src/edit-panel.ts

@@ -13,7 +13,10 @@ import {
   validateField,
   type EntitySchema,
   type FormFieldDescriptor,
-} from './schema'
+  type ValidationRuleSpec,
+} from './schema.js'
+import { evaluatePredicate } from './expressions/evaluate.js'
+import type { PredicateExpr } from './expressions/expression-types.js'
 
 export type EditMode = 'create' | 'edit'
 
@@ -136,6 +139,117 @@ export function builtInError(field: FormFieldDescriptor, value: unknown): string
   return null
 }
 
+/**
+ * Evaluate one of a field's `when` conditions against the values currently in
+ * the form. A malformed condition falls back rather than throwing: a bad rule
+ * should not make the form unusable, and the safe answer differs per flag
+ * (a field stays visible, stays enabled, keeps its static required flag).
+ */
+function test(expr: PredicateExpr | undefined, values: Record<string, unknown>, fallback: boolean): boolean {
+  if (!expr) return fallback
+  try {
+    const result = evaluatePredicate(expr, { row: values })
+    // An unrecognised node evaluates to undefined rather than throwing, so a
+    // non-boolean answer counts as "no opinion" and takes the fallback too.
+    return typeof result === 'boolean' ? result : fallback
+  } catch {
+    return fallback
+  }
+}
+
+/** Whether a field is shown, editable, and demanded, for the current values. */
+export type FieldState = { visible: boolean; disabled: boolean; required: boolean }
+
+/**
+ * Resolve a field's live state from its `when` conditions. Read-only always
+ * wins over a `disabled` condition, and `when.required` replaces the static
+ * `required` flag rather than adding to it, so a rule can make a normally
+ * required field optional as well as the other way round.
+ */
+export function fieldState(field: FormFieldDescriptor, values: Record<string, unknown>): FieldState {
+  return {
+    visible: test(field.when?.visible, values, true),
+    disabled: field.readonly || test(field.when?.disabled, values, false),
+    required: field.when?.required ? test(field.when.required, values, false) : field.required,
+  }
+}
+
+/** Whether a form section's `visibleWhen` holds for the current values. */
+export function sectionVisible(expr: PredicateExpr, values: Record<string, unknown>): boolean {
+  return test(expr, values, true)
+}
+
+/** The fields the form currently shows, in order. */
+export function visibleFormFields<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  values: Record<string, unknown>,
+): FormFieldDescriptor[] {
+  return schemaToFormFields(schema).filter((f) => fieldState(f, values).visible)
+}
+
+/** True when any field's behaviour depends on the values (i.e. has a `when`). */
+export function hasFieldConditions<TData extends RowData>(schema: EntitySchema<TData>): boolean {
+  return schema.fields.some((f) => !!f.when && (!!f.when.visible || !!f.when.disabled || !!f.when.required))
+}
+
+/**
+ * Drop the values of fields hidden by a `when.visible` condition.
+ *
+ * The edit panel already leaves them out via `toSubmitValues`; a server that
+ * builds its own payload (the generated SSR route reads a `FormData`) runs it
+ * through this so both paths write exactly the same fields. Without it, a field
+ * the user could not see would still be saved from a posted form.
+ */
+export function stripHiddenValues<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!hasFieldConditions(schema)) return values
+  const out: Record<string, unknown> = {}
+  const shown = new Set(visibleFormFields(schema, values).map((f) => f.field))
+  for (const [field, value] of Object.entries(values)) {
+    if (!schema.fields.some((f) => f.field === field) || shown.has(field)) out[field] = value
+  }
+  return out
+}
+
+/**
+ * Run the schema's no-code validation rules (`EntitySchema.validations`).
+ *
+ * These already compile into the generated app's server-side `hooks.validate`;
+ * this is the matching interpreter, so the same rule also fires live in the edit
+ * panel and the designer preview instead of only after a round-trip to a
+ * generated server. The comparisons mirror `compileValidation` in
+ * `studio/emit-schema.ts` exactly - string equality for eq/ne, numeric ordering
+ * for lt/lte/gt/gte, length for minLen/maxLen - so a rule cannot mean one thing
+ * in the form and another on the server.
+ */
+export function evalValidationRules(rules: ReadonlyArray<ValidationRuleSpec>, values: Record<string, unknown>): Record<string, string> {
+  const errors: Record<string, string> = {}
+  for (const rule of rules) {
+    if (errors[rule.field]) continue // first failing rule per field wins
+    const left = values[rule.field]
+    const num = () => (rule.compareTo ? Number(values[rule.compareTo]) : Number(rule.value))
+    const str = () => (rule.compareTo ? String(values[rule.compareTo]) : String(rule.value ?? ''))
+    const len = String(left ?? '').length
+    let holds: boolean
+    switch (rule.op) {
+      case 'eq': holds = String(left) === str(); break
+      case 'ne': holds = String(left) !== str(); break
+      case 'lt': holds = Number(left) < num(); break
+      case 'lte': holds = Number(left) <= num(); break
+      case 'gt': holds = Number(left) > num(); break
+      case 'gte': holds = Number(left) >= num(); break
+      case 'required': holds = left != null && left !== ''; break
+      case 'maxLen': holds = len <= Number(rule.value); break
+      case 'minLen': holds = len >= Number(rule.value); break
+      default: holds = true
+    }
+    if (!holds) errors[rule.field] = rule.message
+  }
+  return errors
+}
+
 /**
  * Seed the form's editable state. Uses the row's value when editing, else the
  * field's `defaultValue`, else a type-appropriate empty. Covers every field the
@@ -156,6 +270,48 @@ export function buildInitialValues<TData extends RowData>(
   return values
 }
 
+/**
+ * The error for one field, or null. Required-but-empty first, then the field's
+ * own constraints, then its Standard Schema validator. Read-only and
+ * condition-hidden fields never produce one: the user cannot act on them, so an
+ * error there would be a dead end.
+ *
+ * Shared by whole-form validation and by the panel's on-blur check, so a field
+ * cannot pass one and fail the other.
+ */
+async function fieldError(f: FormFieldDescriptor, values: Record<string, unknown>): Promise<string | null> {
+  if (f.readonly) return null
+  const state = fieldState(f, values)
+  if (!state.visible) return null
+  const value = values[f.field]
+  if (state.required && f.type !== 'boolean' && isEmpty(value)) return `${f.label} is required`
+  const builtIn = builtInError(f, value)
+  if (builtIn) return builtIn
+  if (!isEmpty(value)) return (await validateField(f, value)) ?? null
+  return null
+}
+
+/**
+ * Validate a single field, for checking as the user leaves it rather than making
+ * them submit to find out. Includes the schema-level rules that name this field,
+ * so a cross-field rule surfaces on the field it blames.
+ */
+export async function validateOne<TData extends RowData>(
+  schema: EntitySchema<TData>,
+  field: string,
+  values: Record<string, unknown>,
+): Promise<string | null> {
+  const descriptor = schemaToFormFields(schema).find((f) => f.field === field)
+  if (!descriptor) return null
+  const own = await fieldError(descriptor, values)
+  if (own) return own
+  if (schema.validations?.length) {
+    const byRule = evalValidationRules(schema.validations, values)[field]
+    if (byRule) return byRule
+  }
+  return (await validateEntity(schema, values as Partial<TData>))[field] ?? null
+}
+
 /**
  * Validate every editable field: required-but-empty first, then the field's
  * Standard Schema validator (if any), then the schema-level cross-field
@@ -169,23 +325,15 @@ export async function validateAll<TData extends RowData>(
 ): Promise<Record<string, string>> {
   const errors: Record<string, string> = {}
   for (const f of schemaToFormFields(schema)) {
-    if (f.readonly) continue
-    const value = values[f.field]
-    if (f.required && f.type !== 'boolean' && isEmpty(value)) {
-      errors[f.field] = `${f.label} is required`
-      continue
-    }
-    const builtIn = builtInError(f, value)
-    if (builtIn) {
-      errors[f.field] = builtIn
-      continue
-    }
-    if (!isEmpty(value)) {
-      const msg = await validateField(f, value)
-      if (msg) errors[f.field] = msg
+    const msg = await fieldError(f, values)
+    if (msg) errors[f.field] = msg
+  }
+  // No-code rules, then the cross-field hook. Neither overwrites a per-field error.
+  if (schema.validations?.length) {
+    for (const [field, message] of Object.entries(evalValidationRules(schema.validations, values))) {
+      if (!errors[field]) errors[field] = message
     }
   }
-  // Cross-field rules run last, and never overwrite a per-field error.
   const crossField = await validateEntity(schema, values as Partial<TData>)
   for (const [field, message] of Object.entries(crossField)) {
     if (!errors[field]) errors[field] = message
@@ -216,6 +364,9 @@ export function toSubmitValues<TData extends RowData>(
   const out: Record<string, unknown> = {}
   for (const f of schemaToFormFields(schema)) {
     if (f.readonly) continue
+    // A field hidden by its `when.visible` condition is left out entirely, so a
+    // value the user can no longer see is never written back.
+    if (!fieldState(f, values).visible) continue
     out[f.field] = coerceOut(f, values[f.field])
   }
   return out as Partial<TData>

package/src/expressions/evaluate.ts

@@ -11,7 +11,7 @@ import type {
   ExprRow,
   PredicateExpr,
   ScalarExpr,
-} from './expression-types'
+} from './expression-types.js'
 
 type Scalar = number | string | boolean | null
 

package/src/expressions/parse.ts

@@ -28,13 +28,13 @@ import type {
   ComparisonOp,
   PredicateExpr,
   ScalarExpr,
-} from './expression-types'
+} from './expression-types.js'
 import {
   columnRefText,
   resolveColumnRef,
   type ExprColumn,
-} from './expression-columns'
-import { isBuiltinFunction } from './evaluate'
+} from './expression-columns.js'
+import { isBuiltinFunction } from './evaluate.js'
 
 // ---------------------------------------------------------------------------
 // Tokenizer

package/src/index.ts

@@ -181,6 +181,8 @@ export {
   type EntityFieldType,
   type EntityHooks,
   type FormFieldDescriptor,
+  type FormLayout,
+  type FormSection,
   type StudioEditorType,
   type StandardSchemaV1,
   type StandardSchemaResult,
@@ -274,11 +276,17 @@ export {
   buildInitialValues,
   controlKind,
   editMode,
+  evalValidationRules,
+  fieldState,
+  hasFieldConditions,
   rowId,
+  stripHiddenValues,
   toSubmitValues,
   validateAll,
+  visibleFormFields,
   type EditMode,
   type ControlKind,
+  type FieldState,
 } from './edit-panel'
 export { default as SvGridEditPanel } from './SvGridEditPanel.svelte'
 export { default as SvLookupInput } from './SvLookupInput.svelte'

package/src/license-core.ts

@@ -22,14 +22,86 @@ export type LicenseInfo = {
   status: LicenseStatus
   /** True when the key permits use (dev / eval / licensed). */
   valid: boolean
+  /** Expiry encoded in the key, when it carries one. Undefined otherwise. */
+  expiresAt?: Date
+  /**
+   * True once `expiresAt` has passed. Deliberately does NOT clear `valid`:
+   * an expired trial keeps working and the callers nudge instead. Turning a
+   * lapsed key into a hard stop would break a running app on a date boundary,
+   * which is exactly what a soft gate exists to avoid.
+   */
+  expired?: boolean
 }
 
-/** Classify a license key string. Pure and side-effect-free. */
-export function checkLicenseKey(key: string | null | undefined): LicenseInfo {
+/**
+ * Pull the expiry out of a key.
+ *
+ * Keys are `SVENTERPRISE[-KIND]-<SLUG>-<SEATS>-<DATE>-<RANDOM>`, so the date is
+ * always the second-to-last segment regardless of whether a KIND is present.
+ * Two widths are accepted:
+ *
+ *   YYYYMM   - subscription granularity; expires at the end of that month.
+ *   YYYYMMDD - trial granularity; expires at the end of that day.
+ *
+ * The 6-digit form came first, so every key issued before day-precision trials
+ * existed still parses. Anything else (including the older keys whose slug sits
+ * in that position) yields null, which reads as "no expiry encoded".
+ *
+ * Boundaries are UTC so a key does not lapse at a different instant per
+ * timezone. Kept in sync with `tools/issue-license.mjs`.
+ */
+export function parseLicenseExpiry(key: string | null | undefined): Date | null {
+  if (!key) return null
+  const segments = key.split('-')
+  if (segments.length < 3) return null
+  const stamp = segments[segments.length - 2]
+  if (stamp == null) return null
+
+  if (/^\d{6}$/.test(stamp)) {
+    const year = Number(stamp.slice(0, 4))
+    const month = Number(stamp.slice(4, 6))
+    if (month < 1 || month > 12) return null
+    // Date.UTC's month is 0-based, so passing the 1-based month lands on the
+    // first of the FOLLOWING month; one millisecond earlier is the last instant
+    // of the month the key names.
+    return new Date(Date.UTC(year, month, 1) - 1)
+  }
+
+  if (/^\d{8}$/.test(stamp)) {
+    const year = Number(stamp.slice(0, 4))
+    const month = Number(stamp.slice(4, 6))
+    const day = Number(stamp.slice(6, 8))
+    if (month < 1 || month > 12 || day < 1 || day > 31) return null
+    const end = new Date(Date.UTC(year, month - 1, day, 23, 59, 59, 999))
+    // Reject a date that rolled over (e.g. 20260231), which would otherwise
+    // silently grant a few extra days.
+    if (end.getUTCMonth() !== month - 1) return null
+    return end
+  }
+
+  return null
+}
+
+/** Classify a license key string. Pure and side-effect-free.
+ *  `now` is injectable so expiry behaviour is testable without faking clocks. */
+export function checkLicenseKey(
+  key: string | null | undefined,
+  now: Date = new Date(),
+): LicenseInfo {
   if (key == null || key === '') return { status: 'unset', valid: false }
   if (!key.startsWith(VALID_PREFIX)) return { status: 'invalid', valid: false }
   if (REVOKED_KEYS.has(key)) return { status: 'revoked', valid: false }
-  if (key.startsWith('SVENTERPRISE-DEV')) return { status: 'dev', valid: true }
-  if (key.startsWith('SVENTERPRISE-EVAL')) return { status: 'eval', valid: true }
-  return { status: 'licensed', valid: true }
+
+  const expiresAt = parseLicenseExpiry(key) ?? undefined
+  // Left undefined rather than false when the key encodes no date, so callers
+  // can tell "not expired" apart from "no expiry to check".
+  const expired = expiresAt ? now.getTime() > expiresAt.getTime() : undefined
+
+  const status: LicenseStatus = key.startsWith('SVENTERPRISE-DEV')
+    ? 'dev'
+    : key.startsWith('SVENTERPRISE-EVAL')
+      ? 'eval'
+      : 'licensed'
+
+  return { status, valid: true, expiresAt, expired }
 }

package/src/license-expiry.test.ts

@@ -0,0 +1,91 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { checkLicenseKey, parseLicenseExpiry } from './license-core'
+import {
+  assertEnterpriseLicensed,
+  clearLicenseKey,
+  getLicenseExpiry,
+  isLicenseExpired,
+  setLicenseKey,
+} from './license'
+import { dismissUpgradePrompt } from './upgrade-prompt'
+
+const KEY = 'SVENTERPRISE-EVAL-GUNEI-5-20260904-RGY2TN'
+const CARD = '[data-svgrid-enterprise-upgrade]'
+
+describe('trial key expiry parsing', () => {
+  it('unlocks Enterprise today', () => {
+    const info = checkLicenseKey(KEY, new Date('2026-08-21T12:00:00Z'))
+    expect(info).toMatchObject({ status: 'eval', valid: true, expired: false })
+  })
+
+  it('expires end of 2026-09-04, not end of September', () => {
+    expect(parseLicenseExpiry(KEY)?.toISOString()).toBe('2026-09-04T23:59:59.999Z')
+  })
+
+  it('still valid on the final day', () => {
+    expect(checkLicenseKey(KEY, new Date('2026-09-04T23:00:00Z')).expired).toBe(false)
+  })
+
+  it('expired the next day, but still permitted', () => {
+    const info = checkLicenseKey(KEY, new Date('2026-09-05T00:30:00Z'))
+    expect(info.expired).toBe(true)
+    expect(info.valid).toBe(true)
+  })
+
+  it('keeps parsing month-granularity keys issued before day precision', () => {
+    expect(parseLicenseExpiry('SVENTERPRISE-ACME-5-202705-ABC123')?.toISOString()).toBe(
+      '2027-05-31T23:59:59.999Z',
+    )
+  })
+
+  it('a key with no encoded date has no expiry', () => {
+    const info = checkLicenseKey('SVENTERPRISE-EVAL-acme-2026')
+    expect(info.expiresAt).toBeUndefined()
+    expect(info.expired).toBeUndefined()
+  })
+})
+
+describe('what happens after the trial ends', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+    clearLicenseKey()
+    dismissUpgradePrompt()
+    document.body.innerHTML = ''
+  })
+
+  it('during the trial: no card, and nothing thrown', () => {
+    vi.useFakeTimers({ now: new Date('2026-08-25T10:00:00Z') })
+    setLicenseKey(KEY)
+    expect(isLicenseExpired()).toBe(false)
+    expect(() => assertEnterpriseLicensed('Export')).not.toThrow()
+    expect(document.querySelector(CARD)).toBeNull()
+  })
+
+  it('after the trial: pops the message, and STILL does not throw', () => {
+    vi.useFakeTimers({ now: new Date('2026-09-20T10:00:00Z') })
+    setLicenseKey(KEY)
+    expect(isLicenseExpired()).toBe(true)
+
+    expect(() => assertEnterpriseLicensed('Export')).not.toThrow()
+
+    const card = document.querySelector(CARD)
+    expect(card).not.toBeNull()
+    expect(card!.textContent).toContain('Your trial has ended')
+    expect(card!.textContent).toContain('everything still works')
+  })
+
+  it('exposes the expiry date so a host can render its own banner', () => {
+    vi.useFakeTimers({ now: new Date('2026-09-20T10:00:00Z') })
+    setLicenseKey(KEY)
+    expect(getLicenseExpiry()?.toISOString()).toBe('2026-09-04T23:59:59.999Z')
+  })
+
+  it('a paid key never shows the card', () => {
+    vi.useFakeTimers({ now: new Date('2026-09-20T10:00:00Z') })
+    setLicenseKey('SVENTERPRISE-ACME-5-202705-ABC123')
+    expect(isLicenseExpired()).toBe(false)
+    assertEnterpriseLicensed('Export')
+    expect(document.querySelector(CARD)).toBeNull()
+  })
+})