@startsimpli/ui 0.4.104 → 0.4.105

package/src/foundry/publication.ts

@@ -0,0 +1,260 @@
+/**
+ * PUBLICATION, as pure logic (the mechanism is tenant-starter
+ * apps/core/public_rls.py).
+ *
+ * WHAT PUBLISHING IS. A `Grant(subject_type='public')` on a row. There is no
+ * published column and there must not be one: the anonymous read path switches
+ * into a read-only Postgres role whose RESTRICTIVE policy is
+ *
+ *     id IN (SELECT entity_id FROM core_grant
+ *            WHERE org_id = current_org AND subject_type = 'public'
+ *              AND (expires_at IS NULL OR expires_at > now()))
+ *
+ * evaluated LIVE on every query. So UNPUBLISHING IS STAMPING `expires_at`, not
+ * deleting the row — "an expired share is a fact worth keeping" (core/models.py)
+ * — and there is no window in which a withdrawn row keeps serving.
+ *
+ * WHY PUBLICATION CASCADES ALONG ONE RELATIONSHIP. The same policy gates
+ * `core_relationship` on BOTH ENDS being published. A published record whose
+ * linked records are not published therefore renders as a page that lists
+ * NOTHING — which, on a page whose whole purpose is to state what a record is
+ * linked to, is not an empty list: it is an affirmative public statement that
+ * there is nothing to list. That is reachable by publishing one row at a time,
+ * so the unit of publication here is the record TOGETHER WITH its dependents.
+ *
+ * AND WHY WITHDRAWAL IS NOT SIMPLY THE INVERSE. A dependent can be linked from
+ * several primaries. Withdrawing one must not withdraw a dependent that another
+ * still-published primary asserts — so `unpublishPlan` subtracts the dependents
+ * still reachable from some OTHER live primary, and names both lists so the
+ * operator sees what stays public.
+ *
+ * PRIMARY AND DEPENDENT, NOT THE FORK'S NOUNS. This shipped inside one tenant as
+ * `article`/`patents`; the mechanism is the tenant platform's, not that tenant's,
+ * so the names here describe the ROLES — the record publication is driven from,
+ * and the records that must follow it to be visible at all.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-16d5.
+ */
+import type { EdgeRole } from './links';
+import {
+  PUBLIC_SUBJECT,
+  sameId,
+  type EntityId,
+  type EntityRecordShape,
+  type GrantShape,
+  type RelationshipEdgeShape,
+} from './types';
+
+/** Is this grant a live publication right now? `expires_at` is compared the same
+ *  way the RLS predicate compares it — NULL means "until revoked". */
+export function isLivePublic(grant: GrantShape, now: number = Date.now()): boolean {
+  if (grant.subjectType !== PUBLIC_SUBJECT) return false;
+  if (!grant.expiresAt) return true;
+  const t = new Date(grant.expiresAt).getTime();
+  return Number.isNaN(t) ? true : t > now;
+}
+
+/** Every public grant on a row, live or lapsed. Order is not assumed — callers
+ *  pick by liveness. */
+export function publicGrantsFor<G extends GrantShape>(grants: G[], entity: EntityId): G[] {
+  return grants.filter((g) => g.subjectType === PUBLIC_SUBJECT && sameId(g.entity, entity));
+}
+
+/** The grant that is publishing this row right now, if any. */
+export function livePublicGrant<G extends GrantShape>(
+  grants: G[],
+  entity: EntityId,
+  now: number = Date.now(),
+): G | null {
+  return publicGrantsFor(grants, entity).find((g) => isLivePublic(g, now)) ?? null;
+}
+
+export function isPublished(
+  grants: GrantShape[],
+  entity: EntityId,
+  now: number = Date.now(),
+): boolean {
+  return livePublicGrant(grants, entity, now) !== null;
+}
+
+/** The set of entity ids currently published. */
+export function publishedIds(grants: GrantShape[], now: number = Date.now()): Set<string> {
+  const out = new Set<string>();
+  for (const g of grants) if (isLivePublic(g, now)) out.add(String(g.entity));
+  return out;
+}
+
+/** One row's part in a plan: create a fresh grant, or revive a lapsed one. */
+export interface PublishAction<G extends GrantShape = GrantShape> {
+  entity: EntityId;
+  label: string;
+  /** A lapsed public grant to clear the expiry on, rather than minting a second
+   *  row that says the same thing. */
+  reinstate: G | null;
+}
+
+export interface PublishPlan<
+  R extends EntityRecordShape = EntityRecordShape,
+  G extends GrantShape = GrantShape,
+> {
+  /** The driving record itself, when it is not already published. */
+  primary: PublishAction<G> | null;
+  /** Linked records that must become public for the primary's list to render. */
+  dependents: PublishAction<G>[];
+  /** Dependents already public — shown so a dialog states the whole outcome. */
+  alreadyPublic: R[];
+}
+
+function actionFor<G extends GrantShape>(
+  record: EntityRecordShape,
+  grants: G[],
+  now: number,
+): PublishAction<G> | null {
+  if (isPublished(grants, record.id, now)) return null;
+  const lapsed = publicGrantsFor(grants, record.id).find((g) => !isLivePublic(g, now)) ?? null;
+  return { entity: record.id, label: record.name || String(record.id), reinstate: lapsed };
+}
+
+/**
+ * What publishing this record makes public. Returns the whole outcome — what
+ * changes AND what was already public — because a confirm dialog's job is to
+ * state the resulting public page, not the diff.
+ */
+export function publishPlan<R extends EntityRecordShape, G extends GrantShape>(
+  primary: R,
+  dependents: R[],
+  grants: G[],
+  now: number = Date.now(),
+): PublishPlan<R, G> {
+  const toPublish: PublishAction<G>[] = [];
+  const alreadyPublic: R[] = [];
+  for (const d of dependents) {
+    const action = actionFor(d, grants, now);
+    if (action) toPublish.push(action);
+    else alreadyPublic.push(d);
+  }
+  return { primary: actionFor(primary, grants, now), dependents: toPublish, alreadyPublic };
+}
+
+export interface UnpublishPlan<
+  R extends EntityRecordShape = EntityRecordShape,
+  G extends GrantShape = GrantShape,
+> {
+  /** The live grants on the primary to stamp with an expiry. */
+  primaryGrants: G[];
+  /** Dependents no other published primary reaches: withdrawn with it. */
+  dependentsToWithdraw: { record: R; grants: G[] }[];
+  /** Dependents another published primary still asserts: left public, and named. */
+  dependentsKept: R[];
+}
+
+/**
+ * What withdrawing this record withdraws.
+ *
+ * `allEdges` is every edge of the cascading relationship in the org; the
+ * primary's own edges are subtracted here rather than by the caller, so "which
+ * dependents does some OTHER live primary still assert" is computed in one place
+ * and cannot be got subtly wrong on a screen that only knows about one record.
+ *
+ * `primaryRole` is which end of the declared edge the PRIMARY occupies — see
+ * links.LinkSide. It defaults to 'source' because that is how a cascade normally
+ * reads ("this record is marked with those"), but a fork whose driving record
+ * sits at the target end gets the mirror by passing it.
+ */
+export function unpublishPlan<R extends EntityRecordShape, G extends GrantShape>(
+  primary: R,
+  dependents: R[],
+  allEdges: RelationshipEdgeShape[],
+  grants: G[],
+  options: { primaryRole?: EdgeRole; now?: number } = {},
+): UnpublishPlan<R, G> {
+  const { primaryRole = 'source', now = Date.now() } = options;
+  const nearOf = (e: RelationshipEdgeShape) => (primaryRole === 'source' ? e.source : e.target);
+  const farOf = (e: RelationshipEdgeShape) => (primaryRole === 'source' ? e.target : e.source);
+
+  const live = publishedIds(grants, now);
+  // Primaries that stay published once this one goes.
+  const stillAsserted = new Set<string>();
+  for (const e of allEdges) {
+    if (sameId(nearOf(e), primary.id)) continue;
+    if (live.has(String(nearOf(e)))) stillAsserted.add(String(farOf(e)));
+  }
+
+  const dependentsToWithdraw: UnpublishPlan<R, G>['dependentsToWithdraw'] = [];
+  const dependentsKept: R[] = [];
+  for (const d of dependents) {
+    if (!isPublished(grants, d.id, now)) continue;
+    if (stillAsserted.has(String(d.id))) {
+      dependentsKept.push(d);
+      continue;
+    }
+    dependentsToWithdraw.push({
+      record: d,
+      grants: publicGrantsFor(grants, d.id).filter((g) => isLivePublic(g, now)),
+    });
+  }
+
+  return {
+    primaryGrants: publicGrantsFor(grants, primary.id).filter((g) => isLivePublic(g, now)),
+    dependentsToWithdraw,
+    dependentsKept,
+  };
+}
+
+/**
+ * Why a DEPENDENT is public, in its own words. Publication is driven from the
+ * primary, so a dependent's screen REPORTS rather than offers a toggle — a
+ * dependent published on its own asserts nothing, and letting somebody make one
+ * is how the two ends drift apart.
+ */
+export type DependentPublicationState<R extends EntityRecordShape = EntityRecordShape> =
+  | { kind: 'not-published' }
+  | { kind: 'published'; viaPrimaries: R[] }
+  | { kind: 'published-orphan' };
+
+export function dependentPublication<R extends EntityRecordShape>(
+  dependent: EntityRecordShape,
+  primaries: R[],
+  grants: GrantShape[],
+  now: number = Date.now(),
+): DependentPublicationState<R> {
+  if (!isPublished(grants, dependent.id, now)) return { kind: 'not-published' };
+  const via = primaries.filter((p) => isPublished(grants, p.id, now));
+  return via.length > 0 ? { kind: 'published', viaPrimaries: via } : { kind: 'published-orphan' };
+}
+
+/**
+ * THE ORDER THE WRITES MUST GO IN, and it is a safety property rather than a
+ * preference — so it lives here, next to the invariant it protects, and is
+ * pinned by a test rather than left as a loop in a component.
+ *
+ * A plan is N separate HTTP writes with no transaction behind them. Whatever
+ * order they run in, a 403 or a dropped connection part-way through leaves a
+ * PARTIAL result — so the only real choice is WHICH partial result is reachable.
+ *
+ *   dependents, then the primary: the failure state is "dependents are public,
+ *   nothing asserts them". Discloses nothing false, and is visible on a
+ *   dependent's own screen as `published-orphan`.
+ *
+ *   the primary, then dependents: the failure state is "a published record whose
+ *   linked records are not public", which the public policy renders as a page
+ *   linked to NOTHING — an affirmative public claim. That is the harm this
+ *   module exists to make unreachable.
+ */
+export function publishOrder<G extends GrantShape>(
+  plan: PublishPlan<EntityRecordShape, G>,
+): PublishAction<G>[] {
+  return [...plan.dependents, ...(plan.primary ? [plan.primary] : [])];
+}
+
+/** One grant to expire, in the order withdrawal must take: the PRIMARY first,
+ *  the mirror of publishOrder — a partial withdrawal must never strip a live
+ *  record's dependents while the record itself is still being served. */
+export function withdrawOrder<G extends GrantShape>(
+  plan: UnpublishPlan<EntityRecordShape, G>,
+): G[] {
+  return [
+    ...plan.primaryGrants,
+    ...plan.dependentsToWithdraw.flatMap((d) => d.grants),
+  ];
+}

package/src/foundry/record-validation.ts

@@ -0,0 +1,109 @@
+/**
+ * REQUIRED-FIELD VALIDATION for a generic record form.
+ *
+ * A tenant's `AttributeDef.required` is declared but nothing in a generic form
+ * honours it by default — so a missing value surfaces as a raw server-error
+ * toast AFTER submit, next to a form that had already drawn a red asterisk on
+ * the field it wanted. This restores the capability FROM THE DECLARED SCHEMA
+ * rather than from a hand-written schema per type.
+ *
+ * PURE, so the rule is tested without a browser and shared by BOTH writers: the
+ * create form and an edit mode. Checking it in the create form only means
+ * blanking a required field on an existing record is free.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-4ph9d.
+ */
+import { toCamelKey, type EntityTypeShape } from './types';
+
+/** Key used for the record's own `Entity.name`, which is not a declared attribute. */
+export const NAME_FIELD = '__name__';
+
+/** attribute name (or NAME_FIELD) -> message. Empty object means valid. */
+export type FieldErrors = Record<string, string>;
+
+function isBlank(value: unknown): boolean {
+  if (value === undefined || value === null) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  return false;
+}
+
+/**
+ * Every problem with a submission, at once — not the first one. A form that
+ * reports one error per attempt makes a four-field type a four-round trip.
+ */
+export function validateRecord(
+  type: EntityTypeShape,
+  name: string,
+  values: Record<string, unknown>,
+): FieldErrors {
+  const errors: FieldErrors = {};
+  if (isBlank(name)) errors[NAME_FIELD] = 'Give this record a name.';
+
+  for (const attr of type.attributes ?? []) {
+    const value = values[attr.name];
+    if (attr.required && isBlank(value)) {
+      errors[attr.name] = `${attr.name.replace(/_/g, ' ')} is required.`;
+      continue;
+    }
+    if (attr.dataType === 'json' && !isBlank(value) && typeof value === 'string') {
+      try {
+        JSON.parse(value);
+      } catch {
+        errors[attr.name] = `${attr.name.replace(/_/g, ' ')} is not valid JSON.`;
+      }
+    }
+  }
+  return errors;
+}
+
+export function hasErrors(errors: FieldErrors): boolean {
+  return Object.keys(errors).length > 0;
+}
+
+/**
+ * THE `data` BLOB AN EDIT WRITES BACK.
+ *
+ * Extracted from the drawer so the one rule that can silently delete a field is
+ * testable without a browser: the backend PATCH REPLACES `data` (it does not
+ * deep-merge), so this returns the FULL blob and every key it fails to carry is
+ * a field deleted from the record.
+ *
+ * THE TRAP IS THAT A GUARD CAN CAUSE THE HARM. A provenance attribute renders
+ * read-only (see ./system-attrs), and the obvious way to protect it — leave it
+ * out of the form — drops it out of `values`, at which point the blank-key rule
+ * below DELETES it on the next save. So it must stay in `values`, unchanged, and
+ * come through here like any other attribute.
+ *
+ * KEYS ARE CANONICALIZED TO camelCase, matching the @startsimpli/api client's
+ * response transform, so a round trip does not end up with both `legacy_uuid`
+ * and `legacyUuid` in one blob.
+ */
+export function mergeRecordData(
+  type: EntityTypeShape,
+  current: Record<string, unknown>,
+  values: Record<string, unknown>,
+  toCamel: (name: string) => string = toCamelKey,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...current };
+  for (const attr of type.attributes ?? []) {
+    const camel = toCamel(attr.name);
+    let val = values[attr.name];
+    if (attr.dataType === 'json') {
+      const s = String(val ?? '').trim();
+      if (!s) {
+        delete next[camel];
+        delete next[attr.name];
+        continue;
+      }
+      val = JSON.parse(s);
+    }
+    if (val === '' || val === undefined || val === null) {
+      delete next[camel];
+      delete next[attr.name];
+    } else {
+      next[camel] = val;
+      if (camel !== attr.name) delete next[attr.name];
+    }
+  }
+  return next;
+}

package/src/foundry/system-attrs.ts

@@ -0,0 +1,51 @@
+/**
+ * SYSTEM-PROVENANCE ATTRIBUTES — declared like any other, editable by nobody.
+ *
+ * A tenant's `legacy_uuid` (or `external_id`, or `source_ref`) is a plain `text`
+ * attribute in the schema, so a generic record form renders it as an ordinary
+ * input. It is also, routinely, the key an inbound URL resolves on: a legacy
+ * address of the form `<host>/products/<uuid>` redirects by finding the row
+ * whose `legacy_uuid` matches. Those strings are already printed on articles in
+ * the field, so an operator who edits or blanks the field breaks the redirect
+ * for goods nobody can recall — silently, from a text box that looks like every
+ * other text box.
+ *
+ * A NAME CONVENTION, NOT A PER-APP LIST. Anything a system stamped to point BACK
+ * at where a row came from is the same class of value, so the rule is the shape
+ * of the name rather than an enumeration: an app that seeds `legacy_id` or
+ * `source_ref` gets the same protection without editing this file.
+ *
+ * IT IS A UI GUARD AND SAYS SO. A tenant API will happily PATCH any declared
+ * attribute; nothing here is a permission. Making it one belongs with the schema
+ * (an `immutable` flag on AttributeDef) and is filed as a platform gap rather
+ * than faked here.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-39dr0.
+ */
+import type { AttributeShape } from './types';
+
+/** Exact names that are provenance regardless of shape. */
+const SYSTEM_ATTR_NAMES = new Set(['legacy_uuid', 'legacy_id', 'external_id', 'source_ref']);
+
+/** Suffixes that make a name provenance by convention. */
+const SYSTEM_ATTR_SUFFIXES = ['_uuid', '_legacy_id'];
+
+/** Prefix reserved for values a system wrote about itself. */
+const SYSTEM_ATTR_PREFIX = '_';
+
+export function isSystemAttribute(name: string): boolean {
+  const n = name.trim().toLowerCase();
+  if (!n) return false;
+  if (SYSTEM_ATTR_NAMES.has(n)) return true;
+  if (n.startsWith(SYSTEM_ATTR_PREFIX)) return true;
+  return SYSTEM_ATTR_SUFFIXES.some((s) => n.endsWith(s));
+}
+
+/** Why the field is locked — shown next to the read-only value, because a
+ *  disabled input with no explanation reads as a bug. */
+export const SYSTEM_ATTR_REASON =
+  'Set when this record was imported. A public URL printed elsewhere resolves on it, so it is not editable here.';
+
+export function isSystemAttributeDef(attr: AttributeShape): boolean {
+  return isSystemAttribute(attr.name);
+}

package/src/foundry/types.ts

@@ -0,0 +1,137 @@
+/**
+ * THE MINIMUM THIS PACKAGE NEEDS TO KNOW about a foundry tenant's data.
+ *
+ * WHY THESE ARE SHAPES AND NOT THE CONTRACT. Every tenant app already declares
+ * its own `foundry-api.ts` — the canonical template's, plus whatever each fork
+ * has added to it. If this package re-declared that contract there would be two
+ * authorities on it, and a tenant could not adopt a new `@startsimpli/ui`
+ * without also adopting a wire format it may not serve yet.
+ *
+ * So each type here lists ONLY the fields the functions below actually read.
+ * TypeScript's structural typing then accepts a tenant's own `EntityRecord`,
+ * `AttributeDef` and friends unchanged, with no import in either direction. A
+ * fork whose contract carries extra fields — or spells an id as a number where
+ * production sends a UUID string — still type-checks.
+ *
+ * IDS ARE `string | number` FOR THE SAME REASON the tenant contract models them
+ * that way: production serves UUID strings and the template's fixtures use
+ * numbers. Every comparison in this module goes through `sameId` rather than
+ * `===` so the two can never silently miss each other.
+ */
+
+/** An Entity's primary key. */
+export type EntityId = string | number;
+
+/** A schema object's primary key (types, attributes, relationships, grants). */
+export type SchemaId = string | number;
+
+/**
+ * The declared data types a tenant attribute can have. Widened to `string` at
+ * every use site so a tenant that adds one does not fail to type-check here.
+ */
+export type AttributeDataType =
+  | 'text'
+  | 'longtext'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'date'
+  | 'enum'
+  | 'json'
+  | (string & {});
+
+/** A declared attribute, as much of one as this package reads. */
+export interface AttributeShape {
+  name: string;
+  dataType?: AttributeDataType;
+  required?: boolean;
+}
+
+/** A declared entity type. */
+export interface EntityTypeShape {
+  id: SchemaId;
+  key: string;
+  label: string;
+  attributes?: AttributeShape[];
+}
+
+/** A record of some entity type. */
+export interface EntityRecordShape {
+  id: EntityId;
+  name?: string | null;
+  externalId?: string | null;
+  data?: Record<string, unknown>;
+}
+
+/** A declared relationship: a fixed source type -> target type edge. */
+export interface RelationshipDefShape {
+  key: string;
+  sourceType: SchemaId;
+  targetType: SchemaId;
+}
+
+/** One edge between two records. */
+export interface RelationshipEdgeShape {
+  id: SchemaId;
+  relType: string;
+  source: EntityId;
+  target: EntityId;
+}
+
+/** A share on a row. `subjectType === 'public'` is what publication means. */
+export interface GrantShape {
+  id: SchemaId;
+  entity: EntityId;
+  subjectType: string;
+  expiresAt: string | null;
+}
+
+/** The `subject_type` that makes a grant a publication. */
+export const PUBLIC_SUBJECT = 'public';
+
+/** Same id, whatever the wire happened to send. */
+export function sameId(a: EntityId | null | undefined, b: EntityId | null | undefined): boolean {
+  if (a == null || b == null) return false;
+  return String(a) === String(b);
+}
+
+/**
+ * snake_case -> camelCase, matching the @startsimpli/api response transform.
+ *
+ * `_+` AND NOT `_`: a run of underscores collapses, because that is what the
+ * client's transform does and a tenant app that spells an attribute `foo__bar`
+ * would otherwise look it up under a key nothing ever wrote — silently, as a
+ * blank cell. Kept identical to the tenant template's own board.ts so a record
+ * read through this module and one read through an app's helper cannot land on
+ * different keys.
+ */
+export function toCamelKey(name: string): string {
+  return name.replace(/_+([a-z0-9])/g, (_m, c: string) => c.toUpperCase());
+}
+
+/**
+ * Read one declared attribute out of a record's `data` blob.
+ *
+ * BOTH SPELLINGS ARE TRIED because the shared api client camelises response
+ * keys: an attribute declared `stock_no` arrives as `stockNo`, but a blob
+ * written before that transform (or by a fixture) still has the snake key.
+ */
+export function readRecordValue(
+  data: Record<string, unknown> | undefined | null,
+  name: string,
+  toCamel: (name: string) => string = toCamelKey,
+): unknown {
+  if (!data) return undefined;
+  return data[toCamel(name)] ?? data[name];
+}
+
+/** A record's display label — `name` first, then its natural key, then the id.
+ *  A type whose rows carry no `name` attribute still reads right, because the
+ *  tenant stamps `Entity.name` at write time. */
+export function recordLabel(
+  record: EntityRecordShape | null | undefined,
+  fallbackId?: EntityId,
+): string {
+  if (!record) return fallbackId != null ? `#${String(fallbackId).slice(0, 8)}` : 'Unknown record';
+  return record.name || record.externalId || `#${String(record.id).slice(0, 8)}`;
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useNow } from './use-now'

package/src/hooks/use-now.ts

@@ -0,0 +1,46 @@
+'use client';
+
+/**
+ * The wall clock, read the way React sanctions.
+ *
+ * WHY THIS EXISTS RATHER THAN `Date.now()` IN RENDER. Anything that renders off
+ * the clock — "expired", "overdue", a relative timestamp — collides with two
+ * rules at once:
+ *
+ *   - the clock is an EXTERNAL MUTABLE SOURCE, so reading it during render is
+ *     impure (react-hooks/purity refuses it outright), and
+ *   - a value computed on the server and again in the browser is a hydration
+ *     mismatch waiting for the one date that falls between the two renders.
+ *
+ * `useSyncExternalStore` is the mechanism built for exactly that: a server
+ * snapshot, a client snapshot, and a re-render when they differ.
+ *
+ * THE SNAPSHOT IS FLOORED TO THE MINUTE because `getSnapshot` must return a
+ * value that is `Object.is`-stable between calls — a raw `Date.now()` would
+ * differ on every read and React would re-render forever.
+ */
+import { useSyncExternalStore } from 'react';
+
+const MINUTE = 60_000;
+
+/** No subscription: nothing pushes clock changes, so the value settles at mount
+ *  and on any later re-render. Minute granularity is far finer than any
+ *  "has this date passed" question needs. */
+function subscribe(): () => void {
+  return () => {};
+}
+
+function getSnapshot(): number {
+  return Math.floor(Date.now() / MINUTE) * MINUTE;
+}
+
+/** 0 on the server: nothing is "expired" in a prerender, which under-claims
+ *  rather than stamping a red "expired" on something that is not. Callers guard
+ *  with `now > 0`. */
+function getServerSnapshot(): number {
+  return 0;
+}
+
+export function useNow(): number {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 // Main entry point for @startsimpli/ui package
 export * from './components'
+export * from './hooks'
 export * from './utils'
 export * from './theme'
 export { THEME_TOKENS } from './theme/contract'

package/src/utils/__tests__/csv.test.ts

@@ -0,0 +1,67 @@
+import { csvCell, csvFilename, toCsv } from '../csv';
+
+describe('csvCell', () => {
+  it('leaves a plain value alone', () => {
+    expect(csvCell('US20230306066A1')).toBe('US20230306066A1');
+    expect(csvCell(0)).toBe('0');
+    expect(csvCell(null)).toBe('');
+  });
+
+  it('quotes commas, quotes and newlines', () => {
+    expect(csvCell('a,b')).toBe('"a,b"');
+    expect(csvCell('say "hi"')).toBe('"say ""hi"""');
+    expect(csvCell('line\nbreak')).toBe('"line\nbreak"');
+  });
+
+  it('defuses a leading formula so Excel does not execute a record name', () => {
+    expect(csvCell('=1+1')).toBe("'=1+1");
+    expect(csvCell('+SUM(A1)')).toBe("'+SUM(A1)");
+    expect(csvCell('@import')).toBe("'@import");
+    // ...and still quotes it if it also needs quoting
+    expect(csvCell('=A1,B1')).toBe('"\'=A1,B1"');
+  });
+});
+
+describe('toCsv', () => {
+  it('writes the header row then one row per record, in column order', () => {
+    const csv = toCsv(
+      [
+        { name: 'Web Crawling Service', patents: 2 },
+        { name: 'Other, Inc', patents: 0 },
+      ],
+      [
+        { header: 'Name', value: (r) => r.name },
+        { header: 'Patents', value: (r) => String(r.patents) },
+      ],
+    );
+    expect(csv).toBe(
+      'Name,Patents\r\nWeb Crawling Service,2\r\n"Other, Inc",0\r\n',
+    );
+  });
+
+  it('writes just the header for an empty list', () => {
+    expect(toCsv([], [{ header: 'Name', value: () => '' }])).toBe('Name\r\n');
+  });
+});
+
+describe('csvFilename', () => {
+  it('slugs the label and stamps the day', () => {
+    expect(csvFilename('Company profile', new Date('2026-08-24T12:00:00Z'))).toBe(
+      'company-profile-2026-08-24.csv',
+    );
+    expect(csvFilename('   ', new Date('2026-08-24T12:00:00Z'))).toBe('export-2026-08-24.csv');
+  });
+});
+
+describe('the table exporter writes the same file', () => {
+  // The unified table shipped its own CSV writer with no formula guard, no BOM
+  // and LF endings. It now goes through the primitives above, so a table export
+  // and a page-level export of the same rows cannot disagree.
+  it('guards a formula that arrives through a column value', () => {
+    const csv = toCsv(
+      [{ name: '=cmd|calc' }],
+      [{ header: 'Name', value: (r) => r.name }],
+    );
+    expect(csv).toBe("Name\r\n'=cmd|calc\r\n");
+  });
+});