@lovett/ui 0.0.11 → 0.2.0

package/src/display-store.tsx

@@ -0,0 +1,301 @@
+/**
+ * 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
+ * `<prefix>:<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.
+ *
+ * THE PREFIX IS THE PRODUCT, AND ITS DEFAULT IS FROZEN. This package is a
+ * dependency of more than one app on more than one origin, and `workspace` is
+ * only the right first segment for one of them: a host whose own convention is
+ * `lightwork:<area>:<id>:<key>` was getting the one key on its board that read
+ * as somebody else's. So `prefix` is an option — and its default is `workspace`
+ * FOREVER, not because that name is good but because these keys already exist
+ * in operators' browsers. A store holds a preference the operator set; changing
+ * the default segment would not move that preference to a new key, it would
+ * walk past it and open at the defaults. The suite pins the unprefixed key as a
+ * literal for that reason.
+ *
+ * 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
+}
+
+/**
+ * Everything about the store that is not its settings.
+ *
+ * An OBJECT rather than a fifth positional string, because `allowed` and
+ * `migrations` are both optional and already both objects: a call reading
+ * `createDisplayStore('board', DEFAULTS, undefined, undefined, 'lightwork')`
+ * puts two bare strings at opposite ends of an argument list and names
+ * neither. `{ prefix: 'lightwork' }` says what it is at the call site, and the
+ * next option that earns its place goes beside it rather than becoming a sixth
+ * positional.
+ */
+export interface DisplayStoreOptions {
+  /**
+   * The key's first segment — the PRODUCT, above the store's own `name`.
+   *
+   * Omit it and the key is `workspace:<name>:<scope>:display`, exactly as it
+   * has always been. Pass one and the store moves wholesale onto it, so two
+   * apps sharing this primitive on one origin under the same `name` cannot
+   * read or overwrite each other.
+   *
+   * It is not a migration seam. A store that changes prefix does not carry its
+   * stored settings across; it opens at its defaults on the new key and leaves
+   * the old one behind. Choose it once, when the store is written.
+   */
+  prefix?: 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>,
+  options?: DisplayStoreOptions,
+): DisplayStore<T> {
+  // Resolved once, at construction, so the key cannot differ between the read
+  // on mount and the write on the next change.
+  const prefix = options?.prefix ?? 'workspace'
+  // An EMPTY prefix is refused rather than defaulted, and loudly, because both
+  // quieter options are worse. Falling back to `workspace` would hand a caller
+  // who asked for isolation the shared namespace instead — silently, and
+  // discoverable only as two products reading each other's settings. Accepting
+  // it produces `:board:ws_1:display`, whose empty first segment collides with
+  // every other empty-prefix caller: precisely the cross-product this option
+  // exists to prevent, reintroduced by the option itself.
+  //
+  // A throw at CONSTRUCTION is safe where a throw on read would not be: the
+  // store is built once, at module scope, so this fires before any UI exists
+  // rather than under a user mid-session. `useDisplay` outside a Provider
+  // already throws for the same reason.
+  if (prefix === '') {
+    throw new Error(
+      'createDisplayStore: `prefix` cannot be empty — omit the option to use the default.',
+    )
+  }
+  const storageKey = (scope: string) => `${prefix}:${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 }
+}