@lovett/ui 0.0.10 → 0.1.0

package/src/display-store.tsx

@@ -0,0 +1,242 @@
+/**
+ * createDisplayStore — one factory for "how should this view look" settings.
+ *
+ * `docs/design-briefs/tasks-board-header-primitives.md` §4 records two
+ * separate defects in the source, and this file exists to make both
+ * impossible:
+ *
+ *   1. THE COPY-PASTE. Their store shape (`Record<Key, boolean>` + `toggle` +
+ *      `reset` + persist) is duplicated verbatim across FIVE stores. This is
+ *      one factory called five times.
+ *
+ *   2. THE SINGLETON — the trap worth inverting. Their cards subscribe to a
+ *      module-level zustand store directly (`issue-line.tsx:19`,
+ *      `issue-grid.tsx:81`), so two boards on one page cannot hold different
+ *      display settings, and a card cannot be rendered in a preview with
+ *      settings of its own. Here the settings travel through REACT CONTEXT:
+ *      the state lives in a `<Provider>` instance, so two providers are two
+ *      independent panels, and a component that wants the settings takes them
+ *      from the nearest one (or, for a preview, as a plain prop).
+ *
+ * PERSISTENCE IS PER SCOPE. `scope` is whatever partition the host needs —
+ * for a lens that is the brand id, because ADR-116 D10 requires brand A's
+ * preferences never to surface on brand B. The key is
+ * `workspace:<name>:<scope>:display`, matching CLAUDE.md §3's namespacing
+ * rule. Changing `scope` re-reads: the provider does not remount, so an
+ * in-flight draft elsewhere in the tree survives a brand switch.
+ *
+ * READING IS DEFENSIVE. `localStorage` is untrusted input — a hand-edited
+ * value, a key left behind by an older build, a private window that throws on
+ * access. Every persisted key is checked against the default's TYPE and, when
+ * the caller declares one, against an allow-list of values. Anything that
+ * fails falls back to the default rather than reaching a component as a
+ * setting nothing knows how to render.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+
+/**
+ * What a display setting may be. Enough for a select, a toggle — and a
+ * MEASUREMENT.
+ *
+ * `number` joined the union for a size the operator drags rather than picks
+ * (the item detail's panel width). It is validated harder than the other two,
+ * because `NaN` and `Infinity` are both `typeof 'number'` and both survive a
+ * `JSON.parse` round trip through `null`-free hand editing: a non-finite value
+ * reaching a layout is a pane with no width, so it is rejected on read like
+ * any other value that does not hold up.
+ */
+export type DisplayValue = string | boolean | number
+
+/**
+ * The settings object. A TYPE alias, not an interface, on purpose: an
+ * interface has no implicit index signature and would not satisfy this
+ * constraint at the call site.
+ */
+export type DisplaySettings = Readonly<Record<string, DisplayValue>>
+
+/** Allowed values per key, for the enumerated ones. Unlisted keys are open. */
+export type DisplayAllowed<T extends DisplaySettings> = {
+  readonly [K in keyof T]?: readonly T[K][]
+}
+
+/**
+ * A per-key rewrite applied to the PERSISTED value before it is validated.
+ *
+ * The narrow case this exists for: a setting whose vocabulary changes, where
+ * the old value has an exact successor. Without it the allow-list rejects the
+ * stored value and the operator's preference is silently replaced by the
+ * default — which is a preference thrown away, not a preference migrated. The
+ * tasks lens widened `detailPresentation` from two values to three and its
+ * `drawer` became `panel`; nobody who had chosen the side panel should be put
+ * back on the default because of it.
+ *
+ * It runs on UNTRUSTED input, so it takes `unknown` and may return anything:
+ * whatever it produces still has to survive the type check and the allow-list
+ * afterwards. A migration cannot widen what is permitted, only translate into
+ * it.
+ */
+export type DisplayMigrations<T extends DisplaySettings> = {
+  readonly [K in keyof T]?: (raw: unknown) => unknown
+}
+
+export interface DisplayController<T extends DisplaySettings> {
+  readonly settings: T
+  readonly set: <K extends keyof T>(key: K, value: T[K]) => void
+  readonly reset: () => void
+  /** True when nothing has been changed from the defaults. */
+  readonly isDefault: boolean
+}
+
+export interface DisplayProviderProps {
+  /**
+   * The persistence partition — a brand id in a lens. Omit for a panel that
+   * should not persist at all (a preview, a test).
+   */
+  scope?: string
+  children: ReactNode
+}
+
+export interface DisplayStore<T extends DisplaySettings> {
+  /** Holds the state. Two providers are two independent panels. */
+  readonly Provider: (props: DisplayProviderProps) => ReactNode
+  /** Reads the nearest provider. Throws outside one — a silent default here
+   *  would render a board with settings the panel is not editing. */
+  readonly useDisplay: () => DisplayController<T>
+  readonly defaults: T
+  /** Exposed so a host can name the key it is clearing. */
+  readonly storageKey: (scope: string) => string
+}
+
+function isDisplayValue(value: unknown): value is DisplayValue {
+  if (typeof value === 'string' || typeof value === 'boolean') return true
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+export function createDisplayStore<T extends DisplaySettings>(
+  name: string,
+  defaults: T,
+  allowed?: DisplayAllowed<T>,
+  migrations?: DisplayMigrations<T>,
+): DisplayStore<T> {
+  const storageKey = (scope: string) => `workspace:${name}:${scope}:display`
+
+  /** One key's persisted value, or `null` when it does not hold up. */
+  function validate<K extends keyof T & string>(key: K, input: unknown): T[K] | null {
+    const fallback = defaults[key]
+    // The migration runs FIRST and on the raw value, then everything below
+    // judges its output exactly as it would judge a stored one.
+    const migrate = migrations?.[key]
+    const raw = migrate === undefined ? input : migrate(input)
+    if (!isDisplayValue(raw)) return null
+    if (typeof raw !== typeof fallback) return null
+    const permitted = allowed?.[key]
+    if (permitted && !permitted.includes(raw as T[K])) return null
+    return raw as T[K]
+  }
+
+  function read(scope: string | undefined): T {
+    if (!scope || typeof window === 'undefined') return defaults
+    let parsed: unknown
+    try {
+      const raw = window.localStorage.getItem(storageKey(scope))
+      if (!raw) return defaults
+      parsed = JSON.parse(raw)
+    } catch {
+      // A private window, blocked site data, or a truncated value. The panel
+      // opens at its defaults rather than not at all.
+      return defaults
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      return defaults
+    }
+    const record = parsed as Record<string, unknown>
+    const next: Record<string, DisplayValue> = { ...defaults }
+    for (const key of Object.keys(defaults)) {
+      if (!Object.hasOwn(record, key)) continue
+      const value = validate(key, record[key])
+      if (value !== null) next[key] = value
+    }
+    return next as unknown as T
+  }
+
+  function write(scope: string | undefined, settings: T): void {
+    if (!scope || typeof window === 'undefined') return
+    try {
+      window.localStorage.setItem(storageKey(scope), JSON.stringify(settings))
+    } catch {
+      // Never let a full or blocked store break the view.
+    }
+  }
+
+  const Ctx = createContext<DisplayController<T> | null>(null)
+
+  function Provider({ scope, children }: DisplayProviderProps): ReactNode {
+    const [settings, setSettings] = useState<T>(() => read(scope))
+
+    // A scope change RE-READS rather than remounting, so unsaved work
+    // elsewhere in the tree survives a brand switch (ADR-116 D10).
+    const previousScope = useRef(scope)
+    useEffect(() => {
+      if (previousScope.current === scope) return
+      previousScope.current = scope
+      setSettings(read(scope))
+    }, [scope])
+
+    const set = useCallback(
+      <K extends keyof T>(key: K, value: T[K]) => {
+        setSettings((current) => {
+          if (current[key] === value) return current
+          const next = { ...current, [key]: value }
+          write(scope, next)
+          return next
+        })
+      },
+      [scope],
+    )
+
+    const reset = useCallback(() => {
+      setSettings(() => {
+        write(scope, defaults)
+        return defaults
+      })
+    }, [scope])
+
+    const value = useMemo<DisplayController<T>>(
+      () => ({
+        settings,
+        set,
+        reset,
+        isDefault: Object.keys(defaults).every(
+          (key) => settings[key] === defaults[key],
+        ),
+      }),
+      [settings, set, reset],
+    )
+
+    return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+  }
+
+  function useDisplay(): DisplayController<T> {
+    const ctx = useContext(Ctx)
+    if (!ctx) {
+      throw new Error(
+        `[display-store] useDisplay for "${name}" must be called inside its ` +
+          `Provider. Rendering with silent defaults would show a view the ` +
+          `display panel is not actually editing.`,
+      )
+    }
+    return ctx
+  }
+
+  return { Provider, useDisplay, defaults, storageKey }
+}