@startsimpli/ui 0.4.113 → 0.4.114

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.113",
+  "version": "0.4.114",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,9 +47,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.58"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -123,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.3"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/unified-table/UnifiedTable.tsx

@@ -11,6 +11,7 @@ import { TablePagination } from './components/TablePagination'
 import { StandardTableToolbar } from './components/Toolbar'
 import { Loader2 } from 'lucide-react'
 import { cn } from '../../utils'
+import { reconcileColumnVisibility, readStoredColumnVisibility, isForcedVisible } from './utils/columnVisibility'
 
 export function UnifiedTable<TData>({
   data,
@@ -56,31 +57,38 @@ export function UnifiedTable<TData>({
     return urlState.getURLState()
   }, []) // Only run once on mount
 
-  // Column visibility state
-  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() => {
-    // Try to load from localStorage if persistKey is set
-    if (columnVisibilityConfig?.persistKey && typeof window !== 'undefined') {
-      try {
-        const stored = localStorage.getItem(`table-columns-${columnVisibilityConfig.persistKey}`)
-        if (stored) {
-          return JSON.parse(stored)
-        }
-      } catch {
-        // Ignore localStorage errors
-      }
-    }
+  // Column visibility state.
+  //
+  // A stored map is never trusted verbatim: it is reconciled against the
+  // columns actually on screen, so an attribute declared AFTER the user last
+  // saved a choice takes `defaultVisible` instead of being pinned visible for
+  // that one browser (bd startsim-7r2ta). See utils/columnVisibility.ts for the
+  // three rules — absent takes the default, a stored `false` survives,
+  // `alwaysVisible` outranks both.
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>(() =>
+    reconcileColumnVisibility(
+      columns,
+      readStoredColumnVisibility(columnVisibilityConfig?.persistKey),
+      columnVisibilityConfig
+    )
+  )
 
-    // Initialize default visibility
-    const initial: ColumnVisibilityState = {}
-    columns.forEach(col => {
-      if (columnVisibilityConfig?.defaultVisible) {
-        initial[col.id] = columnVisibilityConfig.defaultVisible.includes(col.id)
-      } else {
-        initial[col.id] = true // Default all visible
-      }
-    })
-    return initial
-  })
+  // Callers that render before their schema lands (a runtime-declared entity
+  // type, a lazily loaded column set) hand us a short `columns` array for a
+  // render or two, so the reconciliation has to hold for the columns that
+  // arrive later as well. Reading through this memo rather than off state means
+  // a late column is never visible for a frame before being corrected.
+  const resolvedColumnVisibility = useMemo(
+    () => reconcileColumnVisibility(columns, columnVisibility, columnVisibilityConfig),
+    [columns, columnVisibility, columnVisibilityConfig]
+  )
+
+  useEffect(() => {
+    // Identity-stable when nothing changed, so this settles in one pass.
+    if (resolvedColumnVisibility !== columnVisibility) {
+      setColumnVisibility(resolvedColumnVisibility)
+    }
+  }, [resolvedColumnVisibility, columnVisibility])
 
   // Client-side sorting state (used when no external sorting config is provided)
   const [localSort, setLocalSort] = useState<SortState>(() => {
@@ -100,13 +108,13 @@ export function UnifiedTable<TData>({
       try {
         localStorage.setItem(
           `table-columns-${columnVisibilityConfig.persistKey}`,
-          JSON.stringify(columnVisibility)
+          JSON.stringify(resolvedColumnVisibility)
         )
       } catch {
         // Ignore localStorage errors
       }
     }
-  }, [columnVisibility, columnVisibilityConfig?.persistKey])
+  }, [resolvedColumnVisibility, columnVisibilityConfig?.persistKey])
 
   // Toggle column visibility
   const toggleColumnVisibility = useCallback((columnId: string) => {
@@ -114,9 +122,12 @@ export function UnifiedTable<TData>({
     if (columnVisibilityConfig?.alwaysVisible?.includes(columnId)) {
       return
     }
+    // Anything but an explicit `false` is on screen, so that's what a toggle
+    // has to turn off — `!prev[id]` would SHOW a column whose id the map has
+    // yet to learn, which is the very state this component used to render.
     setColumnVisibility(prev => ({
       ...prev,
-      [columnId]: !prev[columnId]
+      [columnId]: prev[columnId] === false
     }))
   }, [columnVisibilityConfig?.alwaysVisible])
 
@@ -125,8 +136,14 @@ export function UnifiedTable<TData>({
     if (!columnVisibilityConfig?.enabled) {
       return columns
     }
-    return columns.filter(col => columnVisibility[col.id] !== false)
-  }, [columns, columnVisibility, columnVisibilityConfig?.enabled])
+    return columns.filter(col =>
+      // "Cannot be hidden" is a promise to the caller, not a default: a stored
+      // map written before the column joined that list must not be able to
+      // drop it, and the picker won't offer it back.
+      isForcedVisible(col, columnVisibilityConfig.alwaysVisible) ||
+      resolvedColumnVisibility[col.id] !== false
+    )
+  }, [columns, resolvedColumnVisibility, columnVisibilityConfig?.enabled, columnVisibilityConfig?.alwaysVisible])
 
   // Get hideable columns for the dropdown
   const hideableColumns = useMemo(() => {
@@ -263,7 +280,7 @@ export function UnifiedTable<TData>({
   // Get current view state for saving
   const getCurrentViewState = useCallback((): Omit<SavedView, 'id' | 'name' | 'createdAt'> => {
     return {
-      columnVisibility: columnVisibilityConfig?.enabled ? columnVisibility : undefined,
+      columnVisibility: columnVisibilityConfig?.enabled ? resolvedColumnVisibility : undefined,
       columnOrder: columnReorderConfig?.enabled ? columnReorder.columnOrder : undefined,
       sortBy: currentSortBy,
       sortDirection: currentSortDirection,
@@ -271,7 +288,7 @@ export function UnifiedTable<TData>({
       pageSize: paginationConfig?.pageSize,
     }
   }, [
-    columnVisibility,
+    resolvedColumnVisibility,
     columnVisibilityConfig?.enabled,
     columnReorder.columnOrder,
     columnReorderConfig?.enabled,
@@ -450,7 +467,7 @@ export function UnifiedTable<TData>({
         searchDebounceMs={searchConfig?.debounceMs}
         columnVisibilityEnabled={columnVisibilityConfig?.enabled}
         hideableColumns={hideableColumns}
-        columnVisibility={columnVisibility}
+        columnVisibility={resolvedColumnVisibility}
         onToggleColumnVisibility={toggleColumnVisibility}
         exportEnabled={exportConfig?.enabled}
         exportData={sortedData}

package/src/components/unified-table/__tests__/integration/column-visibility-persistence.test.tsx

@@ -0,0 +1,234 @@
+/**
+ * A saved column map must not force-show columns declared after it (bd startsim-7r2ta).
+ *
+ * UnifiedTable seeds `columnVisibility` from localStorage and then keeps a
+ * column whose id is missing from that map, because the filter asks
+ * `map[id] !== false` and `undefined !== false`. On a runtime-declared schema —
+ * every foundry tenant — that means every attribute added AFTER a reviewer last
+ * touched the column picker is pinned visible for that reviewer alone, and
+ * invisible to anyone checking in a clean browser.
+ *
+ * The reconciliation has to thread three needles at once:
+ *   1. an id ABSENT from the stored map falls back to `defaultVisible`,
+ *   2. a stored `false` is a deliberate hide and survives,
+ *   3. `alwaysVisible` outranks both.
+ */
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { useState } from 'react'
+import { UnifiedTable } from '../../index'
+import { ColumnConfig } from '../../types'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const rows: Row[] = [{ id: '1', name: 'Alpha' }]
+
+const NAME: ColumnConfig<Row> = { id: 'name', header: 'Name', accessorKey: 'name' }
+const STATUS: ColumnConfig<Row> = { id: 'status', header: 'Status', accessorKey: 'status' }
+const SCOPE: ColumnConfig<Row> = { id: 'scope_path', header: 'Scope path', accessorKey: 'scope_path' }
+const ACTIONS: ColumnConfig<Row> = { id: '__actions', header: 'Actions' }
+
+const PERSIST_KEY = 'records-topic'
+const STORAGE_KEY = `table-columns-${PERSIST_KEY}`
+
+function seedStoredMap(map: Record<string, boolean>) {
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(map))
+}
+
+function readStoredMap(): Record<string, boolean> {
+  return JSON.parse(window.localStorage.getItem(STORAGE_KEY) ?? '{}')
+}
+
+/** Only the headers of the rendered grid — the column picker lists them too. */
+function headers(): string[] {
+  return within(screen.getByRole('table'))
+    .getAllByRole('columnheader')
+    .map((th) => th.textContent?.trim() ?? '')
+}
+
+beforeEach(() => {
+  window.localStorage.clear()
+})
+
+describe('a stored column map is reconciled against the current columns', () => {
+  it('hides a column the stored map never heard of when defaults exclude it', () => {
+    // The reviewer saved a choice back when the type had name + status. Since
+    // then the schema grew a scope_path attribute, which the app does NOT
+    // default on.
+    seedStoredMap({ name: true, status: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('still shows an unheard-of column when the caller defaults everything on', () => {
+    // No defaultVisible => "all visible" is the documented default, so an
+    // absent id must stay visible. The fix must not turn absence into a hide.
+    seedStoredMap({ name: true })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{ enabled: true, persistKey: PERSIST_KEY }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+
+  it('keeps a deliberate hide the user saved', () => {
+    // status is in defaultVisible, but the stored map says false. Persistence
+    // exists precisely so that choice outlives the default.
+    seedStoredMap({ name: true, status: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, SCOPE]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name'])
+  })
+
+  it('overrides a stored hide of an always-visible column', () => {
+    // The caller added __actions to alwaysVisible after this user had hidden
+    // it (or the column was renamed into the always-visible set). An
+    // always-visible column that the table drops takes the row actions with it.
+    seedStoredMap({ name: false, status: true, __actions: false })
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('shows an always-visible column that defaultVisible forgot', () => {
+    // Nothing stored at all: the seed path must not let a defaultVisible list
+    // that omits an always-visible id hide it.
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, ACTIONS]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          alwaysVisible: ['name', '__actions'],
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Actions'])
+  })
+
+  it('keeps a hideable:false column that the defaults leave out', () => {
+    // `hideable: false` is already excluded from the column picker, so a
+    // reconciliation that hid one would strand it: off the table and off the
+    // menu that puts it back.
+    const pinned: ColumnConfig<Row> = { ...SCOPE, hideable: false }
+
+    render(
+      <UnifiedTable<Row>
+        data={rows}
+        columns={[NAME, STATUS, pinned]}
+        tableId="records"
+        getRowId={(r) => r.id}
+        columnVisibility={{
+          enabled: true,
+          defaultVisible: ['name', 'status'],
+          persistKey: PERSIST_KEY,
+        }}
+      />
+    )
+
+    expect(headers()).toEqual(['Name', 'Status', 'Scope path'])
+  })
+})
+
+describe('columns that arrive after mount', () => {
+  function LateSchema() {
+    const [cols, setCols] = useState<ColumnConfig<Row>[]>([NAME])
+    return (
+      <>
+        <button onClick={() => setCols([NAME, STATUS, SCOPE])}>load schema</button>
+        <UnifiedTable<Row>
+          data={rows}
+          columns={cols}
+          tableId="records"
+          getRowId={(r) => r.id}
+          columnVisibility={{
+            enabled: true,
+            alwaysVisible: ['name'],
+            defaultVisible: ['name', 'status'],
+            persistKey: PERSIST_KEY,
+          }}
+        />
+      </>
+    )
+  }
+
+  it('reconciles a column the table had not been handed at mount', () => {
+    seedStoredMap({ name: true, status: true })
+    render(<LateSchema />)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(headers()).toEqual(['Name', 'Status'])
+  })
+
+  it('does not wipe a saved hide for a column that has not arrived yet', () => {
+    // Reconciling by rebuilding the map from `columns` alone would drop
+    // status:false while the schema is still in flight, and the persist effect
+    // would write that loss straight back to localStorage.
+    seedStoredMap({ name: true, status: false })
+    render(<LateSchema />)
+
+    expect(readStoredMap().status).toBe(false)
+
+    fireEvent.click(screen.getByText('load schema'))
+
+    expect(readStoredMap().status).toBe(false)
+    expect(headers()).toEqual(['Name'])
+  })
+})

package/src/components/unified-table/__tests__/utils/column-visibility.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit cover for the reconciliation UnifiedTable applies to a stored column
+ * map (bd startsim-7r2ta). The integration test pins the rendered result; this
+ * pins the rules themselves, including the cases a rendered table can't easily
+ * show — an id the current schema no longer declares, a corrupt stored value.
+ */
+import { reconcileColumnVisibility } from '../../utils/columnVisibility'
+
+const cols = [{ id: 'name' }, { id: 'status' }, { id: 'scope_path' }]
+
+describe('reconcileColumnVisibility', () => {
+  it('falls an unknown id back to defaultVisible, not to visible', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true, status: true }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: true, scope_path: false })
+  })
+
+  it('treats "no defaultVisible" as all-visible for unknown ids', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: true }, { enabled: true })
+    ).toEqual({ name: true, status: true, scope_path: true })
+  })
+
+  it('preserves a stored false even when the defaults say otherwise', () => {
+    expect(
+      reconcileColumnVisibility(cols, { status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status', 'scope_path'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+
+  it('forces an always-visible column on over a stored hide', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: false, status: false }, {
+        enabled: true,
+        alwaysVisible: ['name'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('forces an always-visible column on when defaultVisible omits it', () => {
+    expect(
+      reconcileColumnVisibility([...cols, { id: '__actions' }], null, {
+        enabled: true,
+        alwaysVisible: ['__actions'],
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false, __actions: true })
+  })
+
+  it('keeps a stored choice for a column the current schema has not declared', () => {
+    // Mid-flight schemas hand the table a short `columns` array. Rebuilding the
+    // map from `columns` alone would drop the hide, and the persist effect
+    // would write that loss back to localStorage.
+    expect(
+      reconcileColumnVisibility([{ id: 'name' }], { name: true, status: false }, {
+        enabled: true,
+        defaultVisible: ['name', 'status'],
+      })
+    ).toEqual({ name: true, status: false })
+  })
+
+  it('ignores non-boolean values in a corrupt stored map', () => {
+    expect(
+      reconcileColumnVisibility(cols, { name: 'yes', status: null } as never, {
+        enabled: true,
+        defaultVisible: ['name'],
+      })
+    ).toEqual({ name: true, status: false, scope_path: false })
+  })
+
+  it('returns the same object when nothing needs reconciling', () => {
+    // The mount-time seed feeds this straight into setState on every columns
+    // change; a fresh object every time would loop.
+    const stored = { name: true, status: false, scope_path: false }
+    expect(
+      reconcileColumnVisibility(cols, stored, { enabled: true, defaultVisible: ['name'] })
+    ).toBe(stored)
+  })
+
+  it('forces a hideable:false column on, since the picker will not offer it back', () => {
+    // Same promise as alwaysVisible, and the one the caller is likelier to get
+    // wrong: hiding such a column leaves the user no way to restore it.
+    expect(
+      reconcileColumnVisibility(
+        [{ id: 'name' }, { id: 'status' }, { id: 'scope_path', hideable: false }],
+        { name: true, scope_path: false },
+        { enabled: true, defaultVisible: ['name'] }
+      )
+    ).toEqual({ name: true, status: false, scope_path: true })
+  })
+})

package/src/components/unified-table/utils/columnVisibility.ts

@@ -0,0 +1,105 @@
+import { ColumnVisibilityConfig, ColumnVisibilityState } from '../types'
+
+/** The two fields of a column this reconciliation reads. */
+export interface ReconcilableColumn {
+  id: string
+  /** `false` is the same promise as listing the id in `alwaysVisible`. */
+  hideable?: boolean
+}
+
+/**
+ * Column visibility persists as a map of column id -> boolean, and the table
+ * treats a MISSING id as visible (`map[id] !== false`). That is the right
+ * reading for a fresh browser, and the wrong one for a stored map: a schema
+ * declared at runtime — every foundry tenant — grows attributes after a
+ * reviewer last saved a column choice, and each new one lands outside the
+ * stored map and is therefore pinned on for that reviewer alone, invisible to
+ * anyone checking in a clean session. Bumping the persist key clears it once
+ * and the next attribute brings it back (bd startsim-7r2ta).
+ *
+ * So a stored map is reconciled against the columns actually on screen:
+ *
+ *   - an id the stored map has never heard of takes `defaultVisible`
+ *     (or stays visible when the caller declared no defaults at all),
+ *   - a stored `false` is a deliberate hide and is left alone — that is the
+ *     entire point of persisting,
+ *   - `alwaysVisible` outranks both, so neither a stale stored `false` nor a
+ *     `defaultVisible` list that forgot the id can drop the name column or the
+ *     row-actions column. `hideable: false` carries the same promise and is
+ *     forced the same way: the column picker already refuses to list such a
+ *     column, so hiding one would leave the user no way to bring it back.
+ *
+ * Ids the current `columns` no longer declare are carried through untouched.
+ * A caller that renders before its schema arrives hands us a short column list
+ * for a render or two, and rebuilding the map from `columns` alone would erase
+ * the user's saved hides in that window — and the persist effect would then
+ * write the loss back to localStorage.
+ *
+ * Returns the `stored` object itself when nothing needed changing, so callers
+ * can feed the result straight back into `setState` without looping.
+ */
+export function reconcileColumnVisibility(
+  columns: ReconcilableColumn[],
+  stored: ColumnVisibilityState | null | undefined,
+  config?: ColumnVisibilityConfig
+): ColumnVisibilityState {
+  const { defaultVisible, alwaysVisible } = config ?? {}
+
+  const next: ColumnVisibilityState = {}
+  let changed = false
+
+  // Carry the stored choices forward. A non-boolean is a corrupt entry (hand-
+  // edited storage, an older shape) and is treated as absent.
+  for (const [id, value] of Object.entries(stored ?? {})) {
+    if (typeof value === 'boolean') next[id] = value
+    else changed = true
+  }
+
+  for (const col of columns) {
+    const id = col.id
+    const desired = isForcedVisible(col, alwaysVisible)
+      ? true
+      : id in next
+        ? next[id]
+        : defaultVisible
+          ? defaultVisible.includes(id)
+          : true
+    if (next[id] !== desired) {
+      next[id] = desired
+      changed = true
+    }
+  }
+
+  return stored && !changed ? stored : next
+}
+
+/**
+ * A column the user is not allowed to hide — which therefore must not end up
+ * hidden by a stale stored map or by a `defaultVisible` list that omits it.
+ */
+export function isForcedVisible(
+  column: ReconcilableColumn,
+  alwaysVisible: string[] | undefined
+): boolean {
+  return column.hideable === false || !!alwaysVisible?.includes(column.id)
+}
+
+/**
+ * The persisted half of the above: read the map UnifiedTable wrote for
+ * `persistKey`, tolerating a browser that has no localStorage (SSR, privacy
+ * mode) and a value that no longer parses.
+ */
+export function readStoredColumnVisibility(
+  persistKey: string | undefined
+): ColumnVisibilityState | null {
+  if (!persistKey || typeof window === 'undefined') return null
+  try {
+    const stored = window.localStorage.getItem(`table-columns-${persistKey}`)
+    if (!stored) return null
+    const parsed = JSON.parse(stored)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed as ColumnVisibilityState
+  } catch {
+    return null
+  }
+}

package/src/components/unified-table/utils/index.ts

@@ -2,3 +2,4 @@ export * from './renderers'
 export * from './themes'
 export * from './validation'
 export * from './export'
+export * from './columnVisibility'