@freighttech/ui 0.13.18

package/src/backend/dynamic-table/split-view/index.ts

@@ -0,0 +1,48 @@
+export { SplitViewHost } from './SplitViewHost'
+export type { SplitViewHostProps } from './SplitViewHost'
+export { EmptySlot } from './EmptySlot'
+export {
+  ARRANGE_PRESETS,
+  GRID_TEMPLATES,
+  GRID_TEMPLATE_LIST,
+  PANE_MIN_HEIGHT_PX,
+  PANE_MIN_WIDTH_PX,
+  SPLIT_LAYOUT_VERSION,
+  applyGridTemplate,
+  applyPreset,
+  countPanes,
+  countSlots,
+  evenAll,
+  evenSizes,
+  fillSlot,
+  getNode,
+  listPanes,
+  listSlots,
+  makePaneId,
+  normalizeLayout,
+  paneTableId,
+  removePane,
+  resizeAt,
+  setAllPaneChrome,
+  setPaneChrome,
+  splitPane,
+  tableContent,
+} from './types'
+export type {
+  EmptyNode,
+  GridTemplate,
+  GridTemplateId,
+  LayoutNode,
+  LegacySplitLayoutV1,
+  NodePath,
+  PaneChrome,
+  PaneContentRef,
+  PaneNode,
+  PresetId,
+  SlotNode,
+  SplitDirection,
+  SplitLayout,
+  SplitNode,
+} from './types'
+export { useSplitViewLayouts } from './useSplitViewLayouts'
+export type { SavedSplitLayout } from './useSplitViewLayouts'

package/src/backend/dynamic-table/split-view/layoutPersistence.ts

@@ -0,0 +1,185 @@
+'use client'
+
+/**
+ * WORKING-LAYOUT PERSISTENCE — what you left on screen is what you come back to.
+ *
+ * Without this the split view was amnesiac: open invoicing beside transports,
+ * drag the divider, hide a toolbar, reload — and you were back to one pane at
+ * the default width with the chrome restored. Every arrangement had to be
+ * rebuilt by hand on every page load, which makes the feature decorative.
+ *
+ * This is the WORKING layout (the one you are using right now), which is a
+ * different thing from a NAMED layout (`useSplitViewLayouts`, saved to the
+ * server under a name you chose). Named layouts are deliberate and shareable;
+ * the working layout is incidental and personal. Only the latter is stored
+ * here.
+ *
+ * localStorage, user-scoped, for the same reasons `useDensityPreference`
+ * argues at length: it CANNOT leak between users (the A3 incident, where one
+ * person's view change hit the whole organisation, was received as a bug), it
+ * is synchronous so the first paint is already correct rather than flashing
+ * one-pane-then-two, and a layout is a statement about the SCREEN you are
+ * sitting at — a 27" desk monitor and a 13" laptop want different answers.
+ *
+ * The scope segment reuses density's `fms.dt.uid` cache rather than resolving
+ * identity a third way, so all three stores agree on who the user is.
+ */
+
+import { DENSITY_SCOPE_CACHE_KEY } from '../hooks/useDensityPreference'
+import { getCurrentOrganizationScope } from '@open-mercato/shared/lib/frontend/organizationEvents'
+import {
+  countPanes,
+  normalizeLayout,
+  type LayoutNode,
+  type PaneContentRef,
+  type SplitLayout,
+} from './types'
+
+export const SPLIT_LAYOUT_STORAGE_PREFIX = 'fms.dt.split'
+
+const FALLBACK_SCOPE = 'shared'
+
+/**
+ * Every scope this user could plausibly have written under, best first.
+ *
+ * The scope segment is NOT stable across a page load: the shared `fms.dt.uid`
+ * cache is populated asynchronously, so an early write (first paint, before
+ * identity resolves) lands under the organisation or `shared`, while a later
+ * read resolves the real user id. Keying on a single "current" scope therefore
+ * loses the layout on the next load — observed as the split view forgetting a
+ * four-pane arrangement immediately after login.
+ *
+ * Rather than coordinate on the async hydration, reads try every candidate and
+ * writes collapse to the best one, so at most one entry survives per table.
+ */
+function scopeCandidates(): string[] {
+  const scopes: string[] = []
+  try {
+    const cached = window.localStorage.getItem(DENSITY_SCOPE_CACHE_KEY)
+    if (cached) scopes.push(cached)
+  } catch {
+    /* storage unavailable — the org scope below still applies */
+  }
+  try {
+    const org = getCurrentOrganizationScope().organizationId
+    if (org) scopes.push(org)
+  } catch {
+    /* scope module not ready */
+  }
+  scopes.push(FALLBACK_SCOPE)
+  return Array.from(new Set(scopes))
+}
+
+/** One entry per ANCHOR table: the transports page and the invoicing page each
+ *  remember their own arrangement, which is how users think about them. */
+function keyFor(anchorTableId: string, scope: string): string {
+  return `${SPLIT_LAYOUT_STORAGE_PREFIX}:${scope}:${anchorTableId}`
+}
+
+/**
+ * Drop panes whose CONTENT the user can no longer open.
+ *
+ * A stored layout outlives the grant that created it: a feature can be revoked,
+ * a module removed, a table renamed, a widget dropped from the catalogue.
+ * Restoring such a pane would mount an unresolvable id and leave a permanently
+ * empty box the user cannot get rid of — it carries no toolbar, so it carries
+ * no menu to close it with — so the pane is dropped and its siblings absorb the
+ * space.
+ *
+ * EMPTY slots always survive: a hole the user deliberately left in a grid
+ * template is content in its own right, and it is removable from the UI.
+ *
+ * Returns `null` when nothing survives — the caller then falls back to the
+ * plain single pane rather than rendering an empty split.
+ */
+function pruneUnknown(
+  node: LayoutNode,
+  isKnown: (content: PaneContentRef) => boolean,
+): LayoutNode | null {
+  if (node.kind === 'pane') return isKnown(node.content) ? node : null
+  if (node.kind === 'empty') return node
+
+  const kept: LayoutNode[] = []
+  const sizes: number[] = []
+  node.children.forEach((child, index) => {
+    const pruned = pruneUnknown(child, isKnown)
+    if (!pruned) return
+    kept.push(pruned)
+    sizes.push(node.sizes?.[index] ?? 1 / node.children.length)
+  })
+
+  if (kept.length === 0) return null
+  // A split with one surviving child is not a split any more.
+  if (kept.length === 1) return kept[0]
+
+  const total = sizes.reduce((sum, value) => sum + value, 0) || 1
+  return { ...node, children: kept, sizes: sizes.map((value) => value / total) }
+}
+
+/**
+ * Read the stored working layout, or `null` when there is none, it is corrupt,
+ * it predates the current tree model, or none of its tables resolve.
+ *
+ * Deliberately total: a user whose stored layout cannot be honoured gets the
+ * default view, never a crash and never an empty screen.
+ */
+export function readStoredLayout(
+  anchorTableId: string,
+  isKnown: (content: PaneContentRef) => boolean,
+): SplitLayout | null {
+  if (typeof window === 'undefined') return null
+  let raw: string | null = null
+  try {
+    for (const scope of scopeCandidates()) {
+      raw = window.localStorage.getItem(keyFor(anchorTableId, scope))
+      if (raw) break
+    }
+  } catch {
+    return null
+  }
+  if (!raw) return null
+
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== 'object') return null
+    const layout = normalizeLayout(parsed, anchorTableId)
+    if (!layout?.root) return null
+    const pruned = pruneUnknown(layout.root, isKnown)
+    if (!pruned) return null
+    // A workspace with nothing left in it is not worth restoring: the page's
+    // own table is a better answer than a screen of holes, and the user can
+    // pick a template again in two clicks.
+    if (countPanes(pruned) === 0) return null
+    return { ...layout, root: pruned }
+  } catch {
+    // Corrupt JSON, or a shape from a future/never-shipped version. Treated
+    // exactly like "no stored layout" — the default is always safe.
+    return null
+  }
+}
+
+/** Best-effort write. A user with no reachable storage simply gets today's
+ *  amnesiac behaviour rather than an error. */
+export function writeStoredLayout(anchorTableId: string, layout: SplitLayout): void {
+  if (typeof window === 'undefined') return
+  try {
+    const [best, ...stale] = scopeCandidates()
+    window.localStorage.setItem(keyFor(anchorTableId, best), JSON.stringify(layout))
+    // Collapse to one entry: once identity resolves, anything written earlier
+    // under the org/`shared` fallback is a duplicate that would later shadow or
+    // resurrect an older arrangement.
+    for (const scope of stale) window.localStorage.removeItem(keyFor(anchorTableId, scope))
+  } catch {
+    /* quota exceeded / storage blocked — persistence is best-effort */
+  }
+}
+
+/** Used by tests, and by any future "reset this page's layout" affordance. */
+export function clearStoredLayout(anchorTableId: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    for (const scope of scopeCandidates()) window.localStorage.removeItem(keyFor(anchorTableId, scope))
+  } catch {
+    /* nothing to do */
+  }
+}

package/src/backend/dynamic-table/split-view/sharedCriteria.ts

@@ -0,0 +1,196 @@
+/**
+ * Workspace-level shared criteria — one question asked of every pane at once.
+ *
+ * WHY A MAPPING AT ALL: panes hold DIFFERENT entities. "Customer" is
+ * `contractorId` on transports, `customerId` on offers and nothing at all on a
+ * ships map. Matching on column name was rejected (FMS schemas barely share
+ * names, so nearly every pane would grey out); matching semantically off
+ * `entityId` was rejected for a worse reason — when a pane silently fails to
+ * filter, the user is reading the wrong rows *believing* they are filtered.
+ *
+ * So every table DECLARES which of its own fields answers each criterion
+ * (`TableDefinitionMetadata.sharedFilters`), and anything that cannot be
+ * answered is RETURNED as `unmapped` for the pane to say so out loud. Silence
+ * is the failure mode this module exists to prevent.
+ *
+ * Pure functions, no React, no I/O — the whole mechanism is unit-testable.
+ *
+ * Spec: .ai/specs/2026-08-17-split-view-workspace-composition.md
+ */
+
+import type { FilterRow } from '../types/index'
+import { needsValueInput, type FilterOperator } from '../types/filters'
+
+/**
+ * The vocabulary. CLOSED, deliberately: an open one cannot be mapped onto a
+ * table's own field names, validated on the server, or explained to a user when
+ * a pane cannot honour it.
+ *
+ * MUST stay identical to `SHARED_CRITERION_KEYS` in
+ * `packages/split-view/src/modules/split_views/data/validators.ts` — that zod
+ * enum is the server's authority and rejects anything it does not know, so a
+ * key added here alone would 400 on save with no clue why.
+ */
+export const SHARED_CRITERION_KEYS = ['customer', 'dateRange', 'status', 'transportMode'] as const
+
+export type SharedCriterionKey = (typeof SHARED_CRITERION_KEYS)[number]
+
+export type SharedCriterionRule = {
+  key: SharedCriterionKey
+  operator: FilterOperator
+  values: unknown[]
+}
+
+/** What the workspace bar owns: one search string plus zero or more rules. */
+export type SharedCriteria = {
+  search?: string
+  rules: SharedCriterionRule[]
+}
+
+/** A table's (or widget's) answer to the vocabulary, in its OWN field names. */
+export type SharedFilterMapping = Partial<Record<SharedCriterionKey, string>>
+
+/**
+ * The result of asking one pane to honour the criteria.
+ *
+ * `unmapped` is not diagnostics — it is what the pane renders as "not filtered
+ * by customer". A caller that drops it reintroduces exactly the silent wrong
+ * data this module was written to prevent.
+ */
+export type MappedCriteria = {
+  filters: FilterRow[]
+  unmapped: SharedCriterionKey[]
+}
+
+/** Shared identity for "nothing to apply", so callers can compare by reference. */
+const NOTHING: MappedCriteria = Object.freeze({
+  filters: Object.freeze([]) as unknown as FilterRow[],
+  unmapped: Object.freeze([]) as unknown as SharedCriterionKey[],
+})
+
+/** `FilterRow.id` prefix. Deterministic — see `mapCriteriaForTable`. */
+export const SHARED_FILTER_ID_PREFIX = 'shared:'
+
+export function isSharedCriterionKey(value: unknown): value is SharedCriterionKey {
+  return (SHARED_CRITERION_KEYS as readonly unknown[]).includes(value)
+}
+
+/** True for a rule that would filter nothing away, so it is not worth sending. */
+function isInert(rule: SharedCriterionRule): boolean {
+  return needsValueInput(rule.operator) && rule.values.length === 0
+}
+
+function mapWith(criteria: SharedCriteria | null | undefined, mapping: SharedFilterMapping | undefined): MappedCriteria {
+  const rules = criteria?.rules
+  if (!rules || rules.length === 0) return NOTHING
+
+  const filters: FilterRow[] = []
+  const unmapped: SharedCriterionKey[] = []
+
+  for (const rule of rules) {
+    // A key outside the vocabulary is DROPPED here and never reaches the
+    // request. It cannot be reported as unmapped either — `unmapped` is typed
+    // to the vocabulary, and a pane cannot honestly caption a criterion whose
+    // meaning nobody defines. The server's zod enum rejects it on save; this is
+    // the same refusal one layer earlier, for criteria restored from an older
+    // client or a hand-edited row.
+    if (!isSharedCriterionKey(rule.key)) continue
+
+    const field = mapping?.[rule.key]
+    if (!field) {
+      if (!unmapped.includes(rule.key)) unmapped.push(rule.key)
+      continue
+    }
+    if (isInert(rule)) continue
+
+    filters.push({
+      // Deterministic, not random: the same criteria must produce the same
+      // request string on every render, or the list query key churns and the
+      // pane refetches on every parent re-render. The prefix also lets a
+      // consumer tell a shared row from one the user authored.
+      id: `${SHARED_FILTER_ID_PREFIX}${rule.key}`,
+      field,
+      operator: rule.operator,
+      values: [...rule.values],
+    })
+  }
+
+  if (filters.length === 0 && unmapped.length === 0) return NOTHING
+  return { filters, unmapped }
+}
+
+/**
+ * Translate the workspace criteria into ONE table's own field names.
+ *
+ * `metadata` is deliberately a structural type rather than the whole
+ * `TableDefinitionMetadata`: this stays testable without building a registry
+ * entry, and a table that never declares `sharedFilters` simply reports every
+ * live criterion as unmapped.
+ */
+export function mapCriteriaForTable(
+  criteria: SharedCriteria | null | undefined,
+  metadata: { sharedFilters?: SharedFilterMapping } | null | undefined,
+): MappedCriteria {
+  return mapWith(criteria, metadata?.sharedFilters)
+}
+
+/**
+ * Widget shared-filter mappings, keyed by widget id.
+ *
+ * WHY IT IS HERE and not on the widget: `DashboardWidgetMetadata` is an
+ * `@open-mercato/*` type this repo consumes read-only. Declaring the mapping on
+ * it would be an upstream change, which this spec forbids outright — so the
+ * declaration lives on our side of the line instead.
+ *
+ * DELIBERATELY EMPTY. A widget appears here only once someone has READ its
+ * component and confirmed it accepts an equivalent value through `settings`;
+ * an invented entry would produce a pane that claims to be filtered and is not,
+ * which is strictly worse than one that admits it is not filtered.
+ *
+ * To add one:
+ *   1. Open the widget and find the `settings` key it filters on.
+ *   2. Add `'<module>:<widget>': { customer: 'contractorId' }` below.
+ *   3. The pane stops reporting that criterion as unmapped, and the host passes
+ *      the mapped value through the slot's `settings`.
+ */
+export const WIDGET_SHARED_FILTERS: Record<string, SharedFilterMapping> = {}
+
+/**
+ * Same contract as `mapCriteriaForTable`, for a widget pane.
+ *
+ * A widget with no entry reports every live criterion as unmapped and STILL
+ * RENDERS — its own data, unfiltered, with the pane saying so. Blanking it
+ * would destroy the reason the user put it on screen.
+ */
+export function mapCriteriaForWidget(
+  criteria: SharedCriteria | null | undefined,
+  widgetId: string | null | undefined,
+): MappedCriteria {
+  return mapWith(criteria, widgetId ? WIDGET_SHARED_FILTERS[widgetId] : undefined)
+}
+
+/**
+ * The pane's OWN filters combined with the workspace's, for one request.
+ *
+ * Two invariants, both load-bearing:
+ *
+ *  1. **`own` is never mutated and never re-ordered.** Shared criteria are a
+ *     view over the pane's state, not a write to it — otherwise turning the
+ *     workspace toggle off could not restore what the user had, because it
+ *     would have been overwritten.
+ *  2. **With nothing shared, the SAME array reference comes back**, so every
+ *     memo downstream of it (query params, and through them the list query key)
+ *     is byte-identical to a build without this feature.
+ *
+ * Precedence: a shared rule REPLACES the pane's own rule on the same field for
+ * the duration of the request. Sending both would AND two rules over one column
+ * — usually zero rows — and the bar is the control the user is looking at.
+ */
+export function mergeSharedFilters(
+  own: FilterRow[],
+  shared: FilterRow[] | null | undefined,
+): FilterRow[] {
+  if (!shared || shared.length === 0) return own
+  const sharedFields = new Set(shared.map((row) => row.field))
+  return [...own.filter((row) => !sharedFields.has(row.field)), ...shared]
+}