@exxatdesignux/ui 0.0.6 → 0.0.8

package/template/lib/dashboard-layout-merge.ts

@@ -0,0 +1,63 @@
+/**
+ * Merge saved layout with defaults for any dashboard canvas (Placements, Team, Compliance).
+ */
+
+export const KEY_METRICS_KPI_COUNT_MIN = 1
+export const KEY_METRICS_KPI_COUNT_MAX = 4
+export const KEY_METRICS_KPI_COUNT_DEFAULT = 4
+
+export function clampKeyMetricsKpiCount(n: unknown): number {
+  const x = typeof n === "number" && Number.isFinite(n) ? Math.round(n) : KEY_METRICS_KPI_COUNT_DEFAULT
+  return Math.min(KEY_METRICS_KPI_COUNT_MAX, Math.max(KEY_METRICS_KPI_COUNT_MIN, x))
+}
+
+export interface DashboardLayoutV1 {
+  visible: string[]
+  order: string[]
+  spans?: Record<string, 1 | 2>
+  chartTypes?: Record<string, string>
+  /** How many KPI cells to show on the key-metrics dashboard card (1–4). */
+  keyMetricsKpiCount?: number
+}
+
+export function mergeDashboardLayoutGeneric(
+  saved: DashboardLayoutV1 | null,
+  defaults: {
+    visible: string[]
+    order: string[]
+    spans: Record<string, 1 | 2>
+    chartTypes: Record<string, string>
+    keyMetricsKpiCount?: number
+  },
+  allCardIds: string[],
+): DashboardLayoutV1 {
+  const defaultKpi = clampKeyMetricsKpiCount(defaults.keyMetricsKpiCount)
+  if (!saved) {
+    return {
+      visible: [...defaults.visible],
+      order: [...defaults.order],
+      spans: { ...defaults.spans },
+      chartTypes: { ...defaults.chartTypes },
+      keyMetricsKpiCount: defaultKpi,
+    }
+  }
+  let order = saved.order.length ? [...saved.order] : [...defaults.order]
+  let visible = saved.visible.length ? [...saved.visible] : [...defaults.visible]
+  for (const id of allCardIds) {
+    if (!order.includes(id)) order = [id, ...order.filter(x => x !== id)]
+    if (!visible.includes(id) && defaults.visible.includes(id)) {
+      visible = [...visible, id]
+    }
+  }
+  order = order.filter(id => allCardIds.includes(id))
+  visible = visible.filter(id => allCardIds.includes(id))
+  return {
+    visible: visible.length ? visible : [...defaults.visible],
+    order: order.length ? order : [...defaults.order],
+    spans: { ...defaults.spans, ...saved.spans },
+    chartTypes: { ...defaults.chartTypes, ...saved.chartTypes },
+    keyMetricsKpiCount: clampKeyMetricsKpiCount(
+      saved.keyMetricsKpiCount ?? defaultKpi,
+    ),
+  }
+}

package/template/lib/data-list-display-options.ts

@@ -0,0 +1,35 @@
+/**
+ * Display options for Data list (table / board / etc.) — shared across view types
+ * so hide/show preferences persist when switching views.
+ */
+
+export type BoardLineCount = 1 | 2 | 3
+
+export interface DataListDisplayOptions {
+  /**
+   * Board swimlanes: dataset field (table column key) used to split cards into columns.
+   * Each hub passes allowed keys via `TablePropertiesDrawer` `boardGroupByColumnOptions`.
+   */
+  boardGroupByColumnKey: string
+  /** Max lines for primary text blocks on board cards */
+  boardLineCount: BoardLineCount
+  /** Page title block (Placements + subtitle) */
+  showViewTitle: boolean
+  /** Board: phase column titles + descriptions. Table: column header row. */
+  showColumnLabels: boolean
+  /** Board: “N cards” under each phase column */
+  showBoardColumnCounts: boolean
+  boardNewCardAbove: boolean
+  /** Toolbar search control (table view) */
+  showToolbarSearch: boolean
+}
+
+export const DEFAULT_DATA_LIST_DISPLAY_OPTIONS: DataListDisplayOptions = {
+  boardGroupByColumnKey: "status",
+  boardLineCount: 2,
+  showViewTitle: true,
+  showColumnLabels: true,
+  showBoardColumnCounts: true,
+  boardNewCardAbove: true,
+  showToolbarSearch: true,
+}

package/template/lib/data-list-persistence.ts

@@ -0,0 +1,280 @@
+/**
+ * Persist Data list page UI: per-page shell (tabs, display options) and per–lifecycle-tab table state.
+ * Keys are versioned so future migrations can bump `v` or the key suffix.
+ */
+
+import type { Dispatch, SetStateAction } from "react"
+import type { RowHeight } from "@/lib/row-height"
+import type { DataListDisplayOptions } from "@/lib/data-list-display-options"
+import type { ActiveFilter, ConditionalRule, SortRule } from "@/components/table-properties/types"
+import type { ViewTab } from "@/components/templates/list-page"
+import type { DataListViewType } from "@/lib/data-list-view"
+
+export const DATA_LIST_PAGE_STORAGE_KEY = "exxat-ds:data-list:page:v1"
+
+export function lifecycleStorageKey(lifecycleTabId: string): string {
+  return `exxat-ds:data-list:lifecycle:v1:${lifecycleTabId}`
+}
+
+const LIFECYCLE_SAVE_DEBOUNCE_MS = 400
+const PAGE_SAVE_DEBOUNCE_MS = 400
+
+const lifecycleTimers = new Map<string, ReturnType<typeof setTimeout>>()
+const pageTimer: { t?: ReturnType<typeof setTimeout> } = {}
+
+export interface PersistedLifecycleV1 {
+  v: 1
+  sortRules: SortRule[]
+  search: string
+  activeFilters: ActiveFilter[]
+  filterConnectors: Record<string, "and" | "or">
+  groupBy: string | null
+  colOrder: string[]
+  hiddenCols: string[]
+  colWidths: Record<string, number>
+  colPins: Record<string, "left" | "right">
+  colWrap: Record<string, boolean>
+  colMenuSearch: Record<string, string>
+  rowHeight: RowHeight
+  showGridlines: boolean
+  filterBarVisible: boolean
+  searchOpen: boolean
+  conditionalRules: ConditionalRule[]
+  pagination: boolean
+  paginationPage: number
+  paginationPageSize: number
+}
+
+export interface PersistedPageV1 {
+  v: 1
+  displayOptions: DataListDisplayOptions
+  showMetrics: boolean
+  tabs: ViewTab[]
+  activeTabId: string
+}
+
+/** Narrow surface used to hydrate / snapshot table state without importing the hook implementation. */
+export interface TableStatePersistSlice {
+  sortRules: SortRule[]
+  search: string
+  activeFilters: ActiveFilter[]
+  filterConnectors: Record<string, "and" | "or">
+  groupBy: string | null
+  colOrder: string[]
+  hiddenCols: Set<string>
+  colWidths: Record<string, number>
+  colPins: Record<string, "left" | "right">
+  colWrap: Record<string, boolean>
+  colMenuSearch: Record<string, string>
+  rowHeight: RowHeight
+  showGridlines: boolean
+  filterBarVisible: boolean
+  searchOpen: boolean
+  setSortRules: Dispatch<SetStateAction<SortRule[]>>
+  setSearch: Dispatch<SetStateAction<string>>
+  setActiveFilters: Dispatch<SetStateAction<ActiveFilter[]>>
+  setFilterConnectors: Dispatch<SetStateAction<Record<string, "and" | "or">>>
+  setGroupBy: Dispatch<SetStateAction<string | null>>
+  setColOrder: Dispatch<SetStateAction<string[]>>
+  setHiddenCols: Dispatch<SetStateAction<Set<string>>>
+  setColWidths: Dispatch<SetStateAction<Record<string, number>>>
+  setColPins: Dispatch<SetStateAction<Record<string, "left" | "right">>>
+  setColWrap: Dispatch<SetStateAction<Record<string, boolean>>>
+  setColMenuSearch: Dispatch<SetStateAction<Record<string, string>>>
+  setRowHeight: Dispatch<SetStateAction<RowHeight>>
+  setShowGridlines: Dispatch<SetStateAction<boolean>>
+  setFilterBarVisible: Dispatch<SetStateAction<boolean>>
+  setSearchOpen: Dispatch<SetStateAction<boolean>>
+}
+
+const VIEW_TYPES: DataListViewType[] = ["table", "list", "board", "dashboard"]
+
+function isViewType(v: unknown): v is DataListViewType {
+  return typeof v === "string" && (VIEW_TYPES as string[]).includes(v)
+}
+
+function parseViewTab(raw: unknown): ViewTab | null {
+  if (!raw || typeof raw !== "object") return null
+  const o = raw as Record<string, unknown>
+  if (typeof o.id !== "string" || typeof o.label !== "string") return null
+  if (!isViewType(o.viewType)) return null
+  if (typeof o.icon !== "string" || typeof o.filterId !== "string") return null
+  return {
+    id: o.id,
+    label: o.label,
+    viewType: o.viewType,
+    icon: o.icon,
+    filterId: o.filterId,
+  }
+}
+
+export function parsePersistedPage(raw: string | null): PersistedPageV1 | null {
+  if (!raw) return null
+  try {
+    const j = JSON.parse(raw) as unknown
+    if (!j || typeof j !== "object") return null
+    const o = j as Record<string, unknown>
+    if (o.v !== 1) return null
+    if (!o.displayOptions || typeof o.displayOptions !== "object") return null
+    if (typeof o.showMetrics !== "boolean") return null
+    if (!Array.isArray(o.tabs) || typeof o.activeTabId !== "string") return null
+    const tabs = o.tabs.map(parseViewTab).filter((t): t is ViewTab => t !== null)
+    if (tabs.length === 0) return null
+    return {
+      v: 1,
+      displayOptions: o.displayOptions as DataListDisplayOptions,
+      showMetrics: o.showMetrics,
+      tabs,
+      activeTabId: o.activeTabId,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function parsePersistedLifecycle(raw: string | null): PersistedLifecycleV1 | null {
+  if (!raw) return null
+  try {
+    const j = JSON.parse(raw) as unknown
+    if (!j || typeof j !== "object") return null
+    const o = j as Record<string, unknown>
+    if (o.v !== 1) return null
+    if (!Array.isArray(o.sortRules)) return null
+    if (typeof o.search !== "string") return null
+    if (!Array.isArray(o.activeFilters)) return null
+    if (!o.filterConnectors || typeof o.filterConnectors !== "object") return null
+    if (o.groupBy !== null && typeof o.groupBy !== "string") return null
+    if (!Array.isArray(o.colOrder)) return null
+    if (!Array.isArray(o.hiddenCols)) return null
+    if (!o.colWidths || typeof o.colWidths !== "object") return null
+    if (!o.colPins || typeof o.colPins !== "object") return null
+    if (!o.colWrap || typeof o.colWrap !== "object") return null
+    if (!o.colMenuSearch || typeof o.colMenuSearch !== "object") return null
+    if (typeof o.rowHeight !== "string") return null
+    if (typeof o.showGridlines !== "boolean") return null
+    if (typeof o.filterBarVisible !== "boolean") return null
+    if (typeof o.searchOpen !== "boolean") return null
+    if (!Array.isArray(o.conditionalRules)) return null
+    if (typeof o.pagination !== "boolean") return null
+    if (typeof o.paginationPage !== "number" || typeof o.paginationPageSize !== "number") return null
+    return o as unknown as PersistedLifecycleV1
+  } catch {
+    return null
+  }
+}
+
+function mergeColOrder(saved: string[], columnKeys: Set<string>): string[] {
+  const ordered = saved.filter(k => columnKeys.has(k))
+  for (const k of columnKeys) {
+    if (!ordered.includes(k)) ordered.push(k)
+  }
+  return ordered
+}
+
+function filterRecordKeys<T extends Record<string, unknown>>(obj: T, keys: Set<string>): T {
+  const out = { ...obj }
+  for (const k of Object.keys(out)) {
+    if (!keys.has(k)) delete out[k]
+  }
+  return out
+}
+
+export function applyLifecyclePersisted(
+  ts: TableStatePersistSlice,
+  p: PersistedLifecycleV1,
+  columnKeys: Set<string>,
+): void {
+  const colOrder = mergeColOrder(p.colOrder, columnKeys)
+  const hidden = new Set(p.hiddenCols.filter(k => columnKeys.has(k)))
+  const colWidths = filterRecordKeys(p.colWidths, columnKeys) as Record<string, number>
+  const colPins = filterRecordKeys(p.colPins, columnKeys) as Record<string, "left" | "right">
+  const colWrap = filterRecordKeys(p.colWrap, columnKeys) as Record<string, boolean>
+  const colMenuSearch = filterRecordKeys(p.colMenuSearch, columnKeys) as Record<string, string>
+
+  ts.setSortRules(p.sortRules)
+  ts.setSearch(p.search)
+  ts.setActiveFilters(p.activeFilters)
+  ts.setFilterConnectors(p.filterConnectors)
+  ts.setGroupBy(p.groupBy)
+  ts.setColOrder(colOrder)
+  ts.setHiddenCols(hidden)
+  ts.setColWidths(colWidths)
+  ts.setColPins(colPins)
+  ts.setColWrap(colWrap)
+  ts.setColMenuSearch(colMenuSearch)
+  ts.setRowHeight(p.rowHeight)
+  ts.setShowGridlines(p.showGridlines)
+  ts.setFilterBarVisible(p.filterBarVisible)
+  ts.setSearchOpen(p.searchOpen)
+}
+
+export function serializeLifecycle(
+  ts: TableStatePersistSlice,
+  extras: {
+    conditionalRules: ConditionalRule[]
+    pagination: boolean
+    paginationPage: number
+    paginationPageSize: number
+  },
+): PersistedLifecycleV1 {
+  return {
+    v: 1,
+    sortRules: ts.sortRules,
+    search: ts.search,
+    activeFilters: ts.activeFilters,
+    filterConnectors: ts.filterConnectors,
+    groupBy: ts.groupBy,
+    colOrder: ts.colOrder,
+    hiddenCols: [...ts.hiddenCols],
+    colWidths: { ...ts.colWidths },
+    colPins: { ...ts.colPins },
+    colWrap: { ...ts.colWrap },
+    colMenuSearch: { ...ts.colMenuSearch },
+    rowHeight: ts.rowHeight,
+    showGridlines: ts.showGridlines,
+    filterBarVisible: ts.filterBarVisible,
+    searchOpen: ts.searchOpen,
+    conditionalRules: extras.conditionalRules,
+    pagination: extras.pagination,
+    paginationPage: extras.paginationPage,
+    paginationPageSize: extras.paginationPageSize,
+  }
+}
+
+export function loadLifecycleFromStorage(lifecycleTabId: string): PersistedLifecycleV1 | null {
+  if (typeof window === "undefined") return null
+  return parsePersistedLifecycle(localStorage.getItem(lifecycleStorageKey(lifecycleTabId)))
+}
+
+export function scheduleLifecycleSave(lifecycleTabId: string, payload: PersistedLifecycleV1): void {
+  if (typeof window === "undefined") return
+  const prev = lifecycleTimers.get(lifecycleTabId)
+  if (prev) clearTimeout(prev)
+  const t = setTimeout(() => {
+    lifecycleTimers.delete(lifecycleTabId)
+    try {
+      localStorage.setItem(lifecycleStorageKey(lifecycleTabId), JSON.stringify(payload))
+    } catch {
+      /* quota / private mode */
+    }
+  }, LIFECYCLE_SAVE_DEBOUNCE_MS)
+  lifecycleTimers.set(lifecycleTabId, t)
+}
+
+export function loadPageFromStorage(): PersistedPageV1 | null {
+  if (typeof window === "undefined") return null
+  return parsePersistedPage(localStorage.getItem(DATA_LIST_PAGE_STORAGE_KEY))
+}
+
+export function schedulePageSave(payload: PersistedPageV1): void {
+  if (typeof window === "undefined") return
+  if (pageTimer.t) clearTimeout(pageTimer.t)
+  pageTimer.t = setTimeout(() => {
+    pageTimer.t = undefined
+    try {
+      localStorage.setItem(DATA_LIST_PAGE_STORAGE_KEY, JSON.stringify(payload))
+    } catch {
+      /* quota */
+    }
+  }, PAGE_SAVE_DEBOUNCE_MS)
+}

package/template/lib/data-list-view-surface.ts

@@ -0,0 +1,58 @@
+/**
+ * Maps `DataListViewType` to the UI surface pattern for list pages.
+ *
+ * **Data:** One `useTableState(fullRows, columns, …)` per tab; **filtered/sorted rows**
+ * (`tableState.rows`) are the single source of truth for List, Board, and Dashboard.
+ * Table view renders the same state via `DataTable`.
+ *
+ * | View        | Surface |
+ * |------------|---------|
+ * | `table`    | `DataTable` |
+ * | `list`     | `DataTableToolbar` + list layout |
+ * | `board`    | `DataTableToolbar` + board / kanban |
+ * | `dashboard`| `DataTableToolbar` + KPI (`KeyMetrics`) + optional charts (`ChartCard`, Recharts, etc.) |
+ */
+
+import type { DataListViewType } from "@/lib/data-list-view"
+
+/** What to render for the active view tab (routing / branching). */
+export type DataListViewRenderKind =
+  | "data-table"
+  | "list-with-toolbar"
+  | "board-with-toolbar"
+  | "dashboard-with-toolbar"
+
+/**
+ * Stable classification for switch/if chains. **Every** `DataListViewType` maps to exactly one kind.
+ * Use this so `dashboard` is never mistaken for `board` (a common bug when only `list` is special-cased).
+ */
+export function getDataListViewRenderKind(view: DataListViewType): DataListViewRenderKind {
+  switch (view) {
+    case "table":
+      return "data-table"
+    case "list":
+      return "list-with-toolbar"
+    case "board":
+      return "board-with-toolbar"
+    case "dashboard":
+      return "dashboard-with-toolbar"
+    default: {
+      const _x: never = view
+      return _x
+    }
+  }
+}
+
+export function usesDataTableComponent(view: DataListViewType): boolean {
+  return view === "table"
+}
+
+/** KPI band + optional charts — not the kanban board. */
+export function usesDashboardSurface(view: DataListViewType): boolean {
+  return view === "dashboard"
+}
+
+/** Shared toolbar (search, filters, properties); body differs by view. */
+export function usesToolbarWithFilteredRows(view: DataListViewType): boolean {
+  return view === "list" || view === "board" || view === "dashboard"
+}

package/template/lib/data-list-view.ts

@@ -0,0 +1,29 @@
+/**
+ * Data list “view type” — shared by Properties drawer, ListPageTemplate tabs, and client state.
+ *
+ * **Single source of truth** for view labels/icons: use `DATA_LIST_VIEW_TILES` and
+ * `dataListViewLabel` / `dataListViewIcon` on every page so Table / List / Board / Dashboard
+ * stay consistent and stay wired to the same `useTableState` dataset (see `docs/data-views-pattern.md`).
+ */
+export type DataListViewType = "table" | "list" | "board" | "dashboard"
+
+export const DATA_LIST_VIEW_TILES: readonly {
+  value: DataListViewType
+  label: string
+  icon: string
+}[] = [
+  { value: "table",     icon: "fa-table",         label: "Table view" },
+  { value: "list",      icon: "fa-list",         label: "List view" },
+  { value: "board",     icon: "fa-table-columns", label: "Board view" },
+  { value: "dashboard", icon: "fa-chart-mixed",  label: "Dashboard view" },
+]
+
+/** User-facing name for tabs, Properties summary rows, and tooltips (not entity-specific). */
+export function dataListViewLabel(view: DataListViewType): string {
+  return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.label ?? view
+}
+
+/** Font Awesome icon class (no prefix) for tab / toolbar state when view changes. */
+export function dataListViewIcon(view: DataListViewType): string {
+  return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.icon ?? "fa-table"
+}

package/template/lib/data-view-dashboard-storage.ts

@@ -0,0 +1,101 @@
+/**
+ * Centralized localStorage for **Data** view dashboard canvas (Placements, Team, Compliance).
+ * Single bundle key; per-scope slices. Migrates legacy per-hub keys when a scope is missing.
+ */
+
+import type { DashboardLayoutV1 } from "@/lib/dashboard-layout-merge"
+
+const BUNDLE_KEY = "exxat-ds:data-view-dashboards:v1"
+
+/** Legacy keys (pre-bundle) — read when that scope is absent from the bundle. */
+const LEGACY_KEYS: Record<DataViewScope, string> = {
+  placements: "exxat-dashboard-cards",
+  team: "exxat-team-dashboard-cards",
+  compliance: "exxat-compliance-dashboard-cards",
+}
+
+export type DataViewScope = "placements" | "team" | "compliance"
+
+type LayoutBundle = Partial<Record<DataViewScope, DashboardLayoutV1>>
+
+function parseLayout(raw: unknown): DashboardLayoutV1 | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null
+  const o = raw as Record<string, unknown>
+  if (!Array.isArray(o.visible) || !Array.isArray(o.order)) return null
+  const km = typeof o.keyMetricsKpiCount === "number" ? o.keyMetricsKpiCount : undefined
+  return {
+    visible: o.visible as string[],
+    order: o.order as string[],
+    spans:
+      o.spans && typeof o.spans === "object" && !Array.isArray(o.spans)
+        ? (o.spans as Record<string, 1 | 2>)
+        : undefined,
+    chartTypes:
+      o.chartTypes && typeof o.chartTypes === "object" && !Array.isArray(o.chartTypes)
+        ? (o.chartTypes as Record<string, string>)
+        : undefined,
+    keyMetricsKpiCount: km,
+  }
+}
+
+function readBundleRaw(): LayoutBundle {
+  if (typeof window === "undefined") return {}
+  try {
+    const raw = localStorage.getItem(BUNDLE_KEY)
+    if (!raw) return {}
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {}
+    return parsed as LayoutBundle
+  } catch {
+    return {}
+  }
+}
+
+function writeBundle(bundle: LayoutBundle) {
+  if (typeof window === "undefined") return
+  try {
+    localStorage.setItem(BUNDLE_KEY, JSON.stringify(bundle))
+  } catch {
+    /* ignore quota */
+  }
+}
+
+/**
+ * Merge any missing scopes from legacy keys into the bundle (one-time per scope per session edge cases OK).
+ */
+function ensureBundleWithLegacy(): LayoutBundle {
+  let bundle = readBundleRaw()
+  let changed = false
+  for (const scope of ["placements", "team", "compliance"] as const) {
+    if (bundle[scope]) continue
+    try {
+      const raw = localStorage.getItem(LEGACY_KEYS[scope])
+      if (!raw) continue
+      const layout = parseLayout(JSON.parse(raw) as unknown)
+      if (layout) {
+        bundle = { ...bundle, [scope]: layout }
+        changed = true
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  if (changed) writeBundle(bundle)
+  return bundle
+}
+
+/**
+ * Load persisted layout for a hub (Placements / Team / Compliance Data view).
+ */
+export function loadDataViewLayout(scope: DataViewScope): DashboardLayoutV1 | null {
+  const bundle = ensureBundleWithLegacy()
+  return bundle[scope] ?? null
+}
+
+/**
+ * Save layout for one hub; updates the shared bundle atomically.
+ */
+export function saveDataViewLayout(scope: DataViewScope, layout: DashboardLayoutV1) {
+  const bundle = ensureBundleWithLegacy()
+  writeBundle({ ...bundle, [scope]: layout })
+}

package/template/lib/date-filter.ts

@@ -0,0 +1,8 @@
+export {
+  formatDateUS,
+  formatDateTimeUS,
+  parseRowDateToYmd,
+  formatYmdForDisplay,
+  ymdToLocalDate,
+  localDateToYmd,
+} from "../../../packages/ui/src/lib/date-filter"

package/template/lib/dev-log.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { devLog } from "./dev-log"
+
+describe("devLog", () => {
+  const originalEnv = process.env.NODE_ENV
+
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    process.env.NODE_ENV = originalEnv
+  })
+
+  it("logs in development", () => {
+    process.env.NODE_ENV = "development"
+    devLog("hello", 1)
+    expect(console.log).toHaveBeenCalledWith("hello", 1)
+  })
+
+  it("does not log in production", () => {
+    process.env.NODE_ENV = "production"
+    devLog("silent")
+    expect(console.log).not.toHaveBeenCalled()
+  })
+})

package/template/lib/dev-log.ts

@@ -0,0 +1,8 @@
+/**
+ * Logs only in development. Use for mock flows (export, submit) instead of raw console.log.
+ */
+export function devLog(...args: unknown[]): void {
+  if (process.env.NODE_ENV === "development") {
+    console.log(...args)
+  }
+}

package/template/lib/editable-target.ts

@@ -0,0 +1,10 @@
+/**
+ * True when focus is in a field where global shortcuts should not fire.
+ */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null
+  if (!el) return false
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)
+    return true
+  return el.getAttribute?.("contenteditable") === "true"
+}