@byline/admin 3.12.1 → 3.12.2

package/src/forms/status-transitions.ts

@@ -0,0 +1,86 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { WorkflowStatus } from '@byline/core'
+
+export interface StatusTransitions {
+  primaryStatus: WorkflowStatus | undefined
+  secondaryStatuses: WorkflowStatus[]
+  isTerminal: boolean
+}
+
+/**
+ * Compute the primary and secondary status transitions for the ComboButton.
+ * - Primary: the main action (forward step), or the current status itself
+ *   when the document has reached the final workflow step (terminal state).
+ * - Secondary: other available transitions to show as dropdown options.
+ * - isTerminal: true when the document is at the final workflow status —
+ *   the primary button renders as a non-actionable indicator and all
+ *   back-steps move into the dropdown.
+ */
+export function computeStatusTransitions(
+  currentStatus: string | undefined,
+  workflowStatuses: WorkflowStatus[] | undefined,
+  nextStatus: WorkflowStatus | undefined
+): StatusTransitions {
+  if (!workflowStatuses || workflowStatuses.length === 0 || !currentStatus) {
+    return { primaryStatus: nextStatus, secondaryStatuses: [], isTerminal: false }
+  }
+
+  // Single-status workflows (e.g. SINGLE_STATUS_WORKFLOW for lookups) have
+  // no transitions — short-circuit so the form shows only Close / Save.
+  if (workflowStatuses.length <= 1) {
+    return { primaryStatus: undefined, secondaryStatuses: [], isTerminal: false }
+  }
+
+  const currentIndex = workflowStatuses.findIndex((s) => s.name === currentStatus)
+  if (currentIndex === -1) {
+    return { primaryStatus: nextStatus, secondaryStatuses: [], isTerminal: false }
+  }
+
+  const isAtEnd = currentIndex === workflowStatuses.length - 1
+  const isAtStart = currentIndex === 0
+
+  // Collect all available target statuses
+  const availableTargets: WorkflowStatus[] = []
+
+  // Reset to first (if not at first)
+  if (!isAtStart && workflowStatuses[0]) {
+    availableTargets.push(workflowStatuses[0])
+  }
+
+  // Back one step (if not at start and the previous is not already the first)
+  const prev = workflowStatuses[currentIndex - 1]
+  if (currentIndex > 1 && prev) {
+    availableTargets.push(prev)
+  }
+
+  // Forward one step (if not at end) - this is the nextStatus
+  const next = workflowStatuses[currentIndex + 1]
+  if (!isAtEnd && next) {
+    availableTargets.push(next)
+  }
+
+  if (isAtEnd) {
+    // Terminal state: the primary button is a non-actionable indicator of the
+    // current status; both back-steps (revert to previous / reset to first)
+    // are surfaced in the dropdown.
+    return {
+      primaryStatus: workflowStatuses[currentIndex],
+      secondaryStatuses: availableTargets,
+      isTerminal: true,
+    }
+  }
+
+  // Not at end: primary is the forward step (nextStatus)
+  return {
+    primaryStatus: nextStatus,
+    secondaryStatuses: availableTargets.filter((s) => s.name !== nextStatus?.name),
+    isTerminal: false,
+  }
+}

package/src/forms/use-form-layout.test.node.ts

@@ -0,0 +1,82 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { CollectionAdminConfig, Field, GroupDefinition, RowDefinition } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { buildFieldToTabPath } from './use-form-layout'
+
+const field = (name: string): Field => ({ name, type: 'text', label: name }) as Field
+
+const fieldNames = ['title', 'body', 'seoTitle', 'seoDesc', 'note']
+const fieldByName = new Map<string, Field>(fieldNames.map((n) => [n, field(n)]))
+
+const rowByName = new Map<string, RowDefinition>([
+  ['seoRow', { name: 'seoRow', fields: ['seoTitle', 'seoDesc'] }],
+])
+const groupByName = new Map<string, GroupDefinition>([
+  ['seoGroup', { name: 'seoGroup', label: 'SEO', fields: ['seoRow'] }],
+])
+
+describe('buildFieldToTabPath', () => {
+  it('returns an empty map when there are no tab sets', () => {
+    const map = buildFieldToTabPath(undefined, fieldByName, rowByName, groupByName)
+    expect(map.size).toBe(0)
+  })
+
+  it('maps direct fields to their tab set + tab', () => {
+    const adminConfig = {
+      tabSets: [
+        {
+          name: 'main',
+          tabs: [
+            { name: 'content', label: 'Content', fields: ['title', 'body'] },
+            { name: 'meta', label: 'Meta', fields: ['note'] },
+          ],
+        },
+      ],
+    } as unknown as CollectionAdminConfig
+
+    const map = buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName)
+    expect(map.get('title')).toEqual({ tabSetName: 'main', tabName: 'content' })
+    expect(map.get('body')).toEqual({ tabSetName: 'main', tabName: 'content' })
+    expect(map.get('note')).toEqual({ tabSetName: 'main', tabName: 'meta' })
+  })
+
+  it('recurses through rows and groups to reach nested fields', () => {
+    const adminConfig = {
+      tabSets: [
+        {
+          name: 'main',
+          tabs: [{ name: 'seo', label: 'SEO', fields: ['seoGroup'] }],
+        },
+      ],
+    } as unknown as CollectionAdminConfig
+
+    const map = buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName)
+    // seoGroup → seoRow → [seoTitle, seoDesc]
+    expect(map.get('seoTitle')).toEqual({ tabSetName: 'main', tabName: 'seo' })
+    expect(map.get('seoDesc')).toEqual({ tabSetName: 'main', tabName: 'seo' })
+    // Container names themselves are not fields, so are not indexed.
+    expect(map.has('seoGroup')).toBe(false)
+    expect(map.has('seoRow')).toBe(false)
+  })
+
+  it('does not loop forever on a self-referential row cycle', () => {
+    const cyclicRows = new Map<string, RowDefinition>([
+      ['loop', { name: 'loop', fields: ['loop', 'title'] }],
+    ])
+    const adminConfig = {
+      tabSets: [{ name: 'main', tabs: [{ name: 't', label: 'T', fields: ['loop'] }] }],
+    } as unknown as CollectionAdminConfig
+
+    const map = buildFieldToTabPath(adminConfig, fieldByName, cyclicRows, groupByName)
+    // The cycle guard stops the re-visit; the real field is still indexed.
+    expect(map.get('title')).toEqual({ tabSetName: 'main', tabName: 't' })
+  })
+})

package/src/forms/use-form-layout.ts

@@ -0,0 +1,134 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { useMemo } from 'react'
+
+import type {
+  CollectionAdminConfig,
+  Field,
+  GroupDefinition,
+  LayoutDefinition,
+  RowDefinition,
+  TabSetDefinition,
+} from '@byline/core'
+
+/** Which tab set + tab a schema field is placed under. */
+export interface TabPath {
+  tabSetName: string
+  tabName: string
+}
+
+/**
+ * Derived lookup tables that drive the form's layout walk and per-tab error
+ * badges. All are pure derivations of `adminConfig` + `fields`; the startup
+ * validator guarantees every reachable name resolves and every schema field is
+ * placed at most once, so the consuming render-time lookups stay unguarded.
+ */
+export interface FormLayout {
+  /** Schema field name → field definition. */
+  fieldByName: Map<string, Field>
+  tabSetByName: Map<string, TabSetDefinition>
+  rowByName: Map<string, RowDefinition>
+  groupByName: Map<string, GroupDefinition>
+  /** Region placement; synthesised to `{ main: <all fields> }` when omitted. */
+  layout: LayoutDefinition
+  /** Reverse index: schema field name → which tab set + tab it lives in. */
+  fieldToTabPath: Map<string, TabPath>
+}
+
+/**
+ * Build the reverse index from schema field name to its enclosing tab set +
+ * tab. Fields not under any tab set (e.g. raw-field placement directly in
+ * `layout.main`) are absent from the map. Rows and groups are recursed into;
+ * the `seen` set guards against a config that references a row/group cycle.
+ */
+export function buildFieldToTabPath(
+  adminConfig: CollectionAdminConfig | undefined,
+  fieldByName: Map<string, Field>,
+  rowByName: Map<string, RowDefinition>,
+  groupByName: Map<string, GroupDefinition>
+): Map<string, TabPath> {
+  const map = new Map<string, TabPath>()
+  const visit = (
+    names: readonly string[],
+    tabSetName: string,
+    tabName: string,
+    seen: Set<string>
+  ) => {
+    for (const name of names) {
+      if (fieldByName.has(name)) {
+        map.set(name, { tabSetName, tabName })
+      } else if (seen.has(name)) {
+      } else if (rowByName.has(name)) {
+        const row = rowByName.get(name)!
+        const next = new Set(seen).add(name)
+        visit(row.fields, tabSetName, tabName, next)
+      } else if (groupByName.has(name)) {
+        const group = groupByName.get(name)!
+        const next = new Set(seen).add(name)
+        visit(group.fields, tabSetName, tabName, next)
+      }
+    }
+  }
+  for (const set of adminConfig?.tabSets ?? []) {
+    for (const tab of set.tabs) {
+      visit(tab.fields, set.name, tab.name, new Set())
+    }
+  }
+  return map
+}
+
+/**
+ * Memoise the layout primitives + lookup tables the form renderer walks.
+ * Rebuilt only when `adminConfig` / `fields` change.
+ */
+export function useFormLayout(
+  adminConfig: CollectionAdminConfig | undefined,
+  fields: Field[]
+): FormLayout {
+  const fieldByName = useMemo(() => {
+    const map = new Map<string, Field>()
+    for (const field of fields) {
+      if ('name' in field) map.set(field.name, field)
+    }
+    return map
+  }, [fields])
+
+  const tabSetByName = useMemo(() => {
+    const map = new Map<string, TabSetDefinition>()
+    for (const set of adminConfig?.tabSets ?? []) map.set(set.name, set)
+    return map
+  }, [adminConfig])
+
+  const rowByName = useMemo(() => {
+    const map = new Map<string, RowDefinition>()
+    for (const row of adminConfig?.rows ?? []) map.set(row.name, row)
+    return map
+  }, [adminConfig])
+
+  const groupByName = useMemo(() => {
+    const map = new Map<string, GroupDefinition>()
+    for (const group of adminConfig?.groups ?? []) map.set(group.name, group)
+    return map
+  }, [adminConfig])
+
+  // When `layout` is omitted, synthesise main = all schema fields in order.
+  const layout = useMemo<LayoutDefinition>(() => {
+    if (adminConfig?.layout) return adminConfig.layout
+    return { main: fields.filter((f) => 'name' in f).map((f) => (f as { name: string }).name) }
+  }, [adminConfig, fields])
+
+  const fieldToTabPath = useMemo(
+    () => buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName),
+    [adminConfig, fieldByName, rowByName, groupByName]
+  )
+
+  return { fieldByName, tabSetByName, rowByName, groupByName, layout, fieldToTabPath }
+}

package/src/forms/use-tracked-slot.ts

@@ -0,0 +1,101 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { type RefObject, useCallback, useRef } from 'react'
+
+/**
+ * A dirty-tracked, ref-backed form slot with its own listener set — the shared
+ * machinery behind the document-grain system fields (`path`, advertised
+ * `availableLocales`, …). Each slot holds the current value, the value it was
+ * loaded with, and a set of subscribers; a `set` that moves the value away from
+ * its loaded baseline registers the slot's `dirtyKey` in the form's shared
+ * dirty set (and clears it again when the value returns to baseline), so the
+ * single Save button can branch on which buckets changed.
+ *
+ * Adding a new system slot is then a one-liner at the call site rather than a
+ * copy of ref + initial-ref + listener-set + get/set/subscribe.
+ */
+export interface TrackedSlot<T> {
+  /** Current value (live ref read — not React state). */
+  get: () => T
+  /** Write a value; toggles `dirtyKey` against the loaded baseline. */
+  set: (value: T) => void
+  /** Subscribe to value changes; returns an unsubscribe fn. */
+  subscribe: (listener: (value: T) => void) => () => void
+  /** Re-baseline: adopt the current value as the new "clean" baseline (called on save). */
+  commitInitial: () => void
+}
+
+export interface UseTrackedSlotConfig<T> {
+  /** Initial / loaded value. */
+  initial: T
+  /** Key registered in the shared dirty set while this slot diverges from baseline. */
+  dirtyKey: string
+  /** The form's shared dirty-key set. */
+  dirtyFields: RefObject<Set<string>>
+  /** Notify the form's meta listeners (drives hasChanges → Save button). */
+  notifyMeta: () => void
+  /** Equality against the baseline. Defaults to `===` (identity). */
+  isEqual?: (a: T, b: T) => boolean
+  /** Defensive copy on read-in / write. Defaults to identity (fine for immutables). */
+  clone?: (value: T) => T
+}
+
+export function useTrackedSlot<T>(config: UseTrackedSlotConfig<T>): TrackedSlot<T> {
+  // Snapshot the config on every render into a ref so the returned callbacks
+  // can stay referentially stable (empty deps) while still reading the latest
+  // isEqual / clone / notifyMeta — matching the stable identities the previous
+  // inline implementation relied on.
+  const cfgRef = useRef(config)
+  cfgRef.current = config
+
+  const clone = useCallback((value: T): T => {
+    const fn = cfgRef.current.clone
+    return fn ? fn(value) : value
+  }, [])
+
+  const valueRef = useRef<T>(clone(config.initial))
+  const initialRef = useRef<T>(clone(config.initial))
+  const listeners = useRef<Set<(value: T) => void>>(new Set())
+
+  const get = useCallback(() => valueRef.current, [])
+
+  const set = useCallback(
+    (value: T) => {
+      const { dirtyKey, dirtyFields, notifyMeta, isEqual } = cfgRef.current
+      const next = clone(value)
+      valueRef.current = next
+      const equal = isEqual ? isEqual(next, initialRef.current) : next === initialRef.current
+      if (equal) {
+        dirtyFields.current.delete(dirtyKey)
+      } else {
+        dirtyFields.current.add(dirtyKey)
+      }
+      listeners.current.forEach((listener) => {
+        listener(next)
+      })
+      notifyMeta()
+    },
+    [clone]
+  )
+
+  const subscribe = useCallback((listener: (value: T) => void) => {
+    listeners.current.add(listener)
+    return () => {
+      listeners.current.delete(listener)
+    }
+  }, [])
+
+  const commitInitial = useCallback(() => {
+    initialRef.current = clone(valueRef.current)
+  }, [clone])
+
+  return { get, set, subscribe, commitInitial }
+}