@dainamite/cpq 0.2.2

package/src/modules/cpq/components/CpqListView.tsx

@@ -0,0 +1,431 @@
+"use client"
+import * as React from 'react'
+import type { ColumnDef, SortingState } from '@tanstack/react-table'
+import { DataTable, type BulkAction } from '@open-mercato/ui/backend/DataTable'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { RowActions, type RowActionItem } from '@open-mercato/ui/backend/RowActions'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { useCpqRowActions, type UseCpqRowActionsOptions } from './useCpqRowActions'
+
+// ─── Types ───────────────────────────────────────────────────────
+
+type PaginatedResponse<T> = {
+  items?: T[]
+  total?: number
+  totalPages?: number
+}
+
+export type CpqListData<T> = {
+  rows: T[]
+  total: number
+  totalPages: number
+  page: number
+  isLoading: boolean
+  /** Last successful fetch duration in milliseconds. Surfaces in the
+   *  pagination footer as `... in 1.5s`, matching OM's standard list views. */
+  durationMs: number | null
+  search: string
+  sorting: SortingState
+  filterValues: FilterValues
+  setPage: (page: number) => void
+  setSearch: (value: string) => void
+  setSorting: React.Dispatch<React.SetStateAction<SortingState>>
+  setFilterValues: (values: FilterValues) => void
+  clearFilters: () => void
+  reload: () => void
+  queryString: string
+}
+
+export type UseCpqListDataOptions = {
+  /** API endpoint without query string, e.g. `/api/cpq/product-offerings` */
+  endpoint: string
+  /** Default 50 — keep at or below 100. */
+  pageSize?: number
+  /** Initial sort state. Default `[{ id: 'createdAt', desc: true }]`. */
+  initialSorting?: SortingState
+  /** Map filter values to URL params (only call set on the params arg). */
+  buildFilterParams?: (values: FilterValues, params: URLSearchParams) => void
+  /** Override the flash message shown when the load fails. */
+  loadErrorMessage?: string
+}
+
+/**
+ * Server-side paginated list state for CPQ list views.
+ *
+ * Designed for 100k+ records:
+ *  - search / sort / filter all go to the server
+ *  - default pageSize stays at or below 100
+ *  - debouncing is handled by FilterBar's search input (1s)
+ */
+export function useCpqListData<T extends { id: string }>(
+  options: UseCpqListDataOptions,
+): CpqListData<T> {
+  const {
+    endpoint,
+    pageSize = 50,
+    initialSorting = [{ id: 'createdAt', desc: true }],
+    buildFilterParams,
+    loadErrorMessage,
+  } = options
+  const t = useT()
+
+  const [rows, setRows] = React.useState<T[]>([])
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [page, setPageState] = React.useState(1)
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [durationMs, setDurationMs] = React.useState<number | null>(null)
+  const [reloadToken, setReloadToken] = React.useState(0)
+  const [search, setSearchState] = React.useState('')
+  const [sorting, setSorting] = React.useState<SortingState>(initialSorting)
+  const [filterValues, setFilterValuesState] = React.useState<FilterValues>({})
+
+  const queryString = React.useMemo(() => {
+    const params = new URLSearchParams()
+    params.set('page', String(page))
+    params.set('pageSize', String(pageSize))
+    if (search.trim()) params.set('search', search.trim())
+    const sort = sorting[0]
+    if (sort?.id) {
+      params.set('sortField', sort.id)
+      params.set('sortDir', sort.desc ? 'desc' : 'asc')
+    }
+    if (buildFilterParams) buildFilterParams(filterValues, params)
+    return params.toString()
+  }, [buildFilterParams, filterValues, page, pageSize, search, sorting])
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function load() {
+      setIsLoading(true)
+      // Use `performance.now()` so the wall-clock change during the request
+      // (NTP, DST, manual clock skew) can never produce a negative duration.
+      const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now()
+      try {
+        const fallback: PaginatedResponse<T> = { items: [], total: 0, totalPages: 1 }
+        const call = await apiCall<PaginatedResponse<T>>(
+          `${endpoint}?${queryString}`,
+          undefined,
+          { fallback },
+        )
+        if (cancelled) return
+        if (!call.ok) {
+          flash(loadErrorMessage ?? t('cpq.list.error.load', 'Failed to load'), 'error')
+          return
+        }
+        const payload = call.result ?? fallback
+        const items = Array.isArray(payload.items) ? payload.items : []
+        setRows(items)
+        setTotal(typeof payload.total === 'number' ? payload.total : items.length)
+        setTotalPages(typeof payload.totalPages === 'number' ? payload.totalPages : 1)
+        const finishedAt = typeof performance !== 'undefined' ? performance.now() : Date.now()
+        setDurationMs(Math.max(0, finishedAt - startedAt))
+      } finally {
+        if (!cancelled) setIsLoading(false)
+      }
+    }
+    load()
+    return () => {
+      cancelled = true
+    }
+  }, [endpoint, loadErrorMessage, queryString, reloadToken, t])
+
+  const setSearch = React.useCallback((value: string) => {
+    setSearchState(value)
+    setPageState(1)
+  }, [])
+
+  const setFilterValues = React.useCallback((values: FilterValues) => {
+    setFilterValuesState(values)
+    setPageState(1)
+  }, [])
+
+  const clearFilters = React.useCallback(() => {
+    setFilterValuesState({})
+    setPageState(1)
+  }, [])
+
+  const reload = React.useCallback(() => {
+    setReloadToken((token) => token + 1)
+  }, [])
+
+  return {
+    rows,
+    total,
+    totalPages,
+    page,
+    isLoading,
+    durationMs,
+    search,
+    sorting,
+    filterValues,
+    setPage: setPageState,
+    setSearch,
+    setSorting,
+    setFilterValues,
+    clearFilters,
+    reload,
+    queryString,
+  }
+}
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Declarative shortcut for the standard CRUD-list row actions.
+ *
+ * When provided, CpqListView:
+ *  - registers `useCpqRowActions` internally
+ *  - renders Edit + Delete in every row's `⋯` menu (with optional
+ *    `extraRowItems` per row prepended / appended)
+ *  - adds a "Delete selected" bulk action (after any `bulkActions` you
+ *    pass explicitly, so module-specific bulk ops come first)
+ *  - mounts the confirm-dialog portal in the page footer
+ *
+ * Pass `rowActions` / `bulkActions` directly instead when the page needs
+ * fully custom semantics (e.g. Quotes / Orders have no DELETE endpoint).
+ */
+export type CpqListViewCrudConfig<T extends { id: string }> = Omit<
+  UseCpqRowActionsOptions<T>,
+  'onReload'
+> & {
+  /**
+   * Extra items added to each row's actions menu.
+   * `prepend` renders before Edit, `append` between Edit and Delete.
+   */
+  extraRowItems?: (row: T) => { prepend?: RowActionItem[]; append?: RowActionItem[] }
+}
+
+export type CpqListViewProps<T extends { id: string }> = {
+  /** Page + table title */
+  title: React.ReactNode
+  /** Stable id for perspectives (e.g. `cpq.offerings.list`) */
+  tableId: string
+  /** Stable id for DataTable's selection state (defaults to tableId) */
+  selectionScopeKey?: string
+  /** List state — typically built from `useCpqListData` in the parent */
+  data: CpqListData<T>
+  /** Table columns */
+  columns: ColumnDef<T>[]
+  /** Filter definitions for the FilterBar overlay */
+  filters?: FilterDef[]
+  /** Search input placeholder */
+  searchPlaceholder?: string
+  /** Header actions (e.g. Create button) */
+  actions?: React.ReactNode
+  /** Bulk actions toolbar shown when rows are selected */
+  bulkActions?: BulkAction<T>[]
+  /** Per-row action menu */
+  rowActions?: (row: T) => React.ReactNode
+  /**
+   * Declarative CRUD config. When set, CpqListView produces the standard
+   * `⋯ → Edit / Delete` menu, a "Delete selected" bulk action, and mounts
+   * the confirm-dialog portal — replacing the ~30 lines of boilerplate
+   * each list page used to repeat. Override `rowActions` / `bulkActions`
+   * to take full control instead.
+   */
+  crud?: CpqListViewCrudConfig<T>
+  /** Click handler for whole row (typically navigates to detail) */
+  onRowClick?: (row: T) => void
+  /** Custom empty state */
+  emptyState?: React.ReactNode
+  /** Pagination size (must match `useCpqListData` pageSize) */
+  pageSize?: number
+  /**
+   * Custom content rendered ABOVE the DataTable inside the same Page wrapper.
+   * Use for inline forms, customer pickers, tab switchers, alerts.
+   */
+  toolbarContent?: React.ReactNode
+  /**
+   * Custom content rendered BELOW the DataTable (e.g. confirm dialog portals).
+   */
+  footerContent?: React.ReactNode
+}
+
+/**
+ * Generic CPQ list view. Wraps DataTable + FilterBar + Page in the
+ * Open Mercato standard, with stronger row-hover affordance so users
+ * always know what's clickable.
+ */
+export function CpqListView<T extends { id: string }>({
+  title,
+  tableId,
+  selectionScopeKey,
+  data,
+  columns,
+  filters,
+  searchPlaceholder,
+  actions,
+  bulkActions,
+  rowActions,
+  crud,
+  onRowClick,
+  emptyState,
+  pageSize = 50,
+  toolbarContent,
+  footerContent,
+}: CpqListViewProps<T>) {
+  const t = useT()
+
+  // Wire `crud` into RowActions + bulkActions + footer confirm dialog so the
+  // call-site stays a single declarative config block.
+  // The hook is always called (Rules of Hooks); the helpers below decide
+  // whether to actually use its output based on the presence of `crud`.
+  const crudActions = useCpqRowActions<T>({
+    endpoint: crud?.endpoint ?? '',
+    entityName: crud?.entityName ?? 'item',
+    editHref: crud?.editHref ?? (() => '#'),
+    onReload: data.reload,
+    canDelete: crud?.canDelete,
+  })
+
+  const resolvedRowActions = React.useMemo(() => {
+    if (rowActions) return rowActions
+    if (!crud) return undefined
+    return (row: T) => (
+      <RowActions items={crudActions.buildItems(row, crud.extraRowItems?.(row))} />
+    )
+  }, [crud, crudActions, rowActions])
+
+  const resolvedBulkActions = React.useMemo<BulkAction<T>[] | undefined>(() => {
+    if (!crud) return bulkActions
+    const deleteAction: BulkAction<T> = {
+      id: 'delete',
+      label: t('cpq.list.bulk.deleteSelected', 'Delete selected'),
+      destructive: true,
+      onExecute: crudActions.bulkDelete,
+    }
+    return bulkActions ? [...bulkActions, deleteAction] : [deleteAction]
+  }, [bulkActions, crud, crudActions.bulkDelete, t])
+
+  const resolvedFooter = crud ? (
+    <>
+      {footerContent}
+      {crudActions.ConfirmDialogElement}
+    </>
+  ) : (
+    footerContent
+  )
+
+  return (
+    <Page>
+      <PageBody className="cpq-list-view space-y-6">
+        <CpqInteractionStyles />
+        {toolbarContent}
+        <DataTable<T>
+          title={title}
+          actions={actions}
+          refreshButton={{
+            label: t('cpq.list.actions.refresh', 'Refresh'),
+            onRefresh: data.reload,
+            isRefreshing: data.isLoading,
+          }}
+          columns={columns}
+          data={data.rows}
+          searchValue={data.search}
+          onSearchChange={data.setSearch}
+          searchPlaceholder={searchPlaceholder ?? t('cpq.list.search.placeholder', 'Search...')}
+          filters={filters}
+          filterValues={data.filterValues}
+          onFiltersApply={data.setFilterValues}
+          onFiltersClear={data.clearFilters}
+          sorting={data.sorting}
+          onSortingChange={data.setSorting}
+          bulkActions={resolvedBulkActions}
+          selectionScopeKey={selectionScopeKey ?? tableId}
+          onRowClick={onRowClick}
+          rowActions={resolvedRowActions}
+          perspective={{ tableId }}
+          columnChooser={{ auto: true }}
+          pagination={{
+            page: data.page,
+            pageSize,
+            total: data.total,
+            totalPages: data.totalPages,
+            onPageChange: data.setPage,
+            durationMs: data.durationMs,
+          }}
+          isLoading={data.isLoading}
+          emptyState={emptyState}
+        />
+        {resolvedFooter}
+      </PageBody>
+    </Page>
+  )
+}
+
+// ─── Shared interaction styles ───────────────────────────────────
+
+/**
+ * Inline style block applied inside `.cpq-list-view` (and any `.cpq-page`)
+ * wrappers. Strengthens the OM hover affordance so users can clearly tell
+ * which row their mouse is on, and forces `cursor: pointer` on every
+ * clickable element inside CPQ pages.
+ *
+ * Kept inline to avoid coupling the package to a global stylesheet.
+ */
+export function CpqInteractionStyles() {
+  return (
+    <style>{`
+.cpq-list-view tbody tr.cursor-pointer,
+.cpq-page tbody tr.cursor-pointer {
+  cursor: pointer;
+}
+.cpq-list-view tbody tr.cursor-pointer:hover,
+.cpq-page tbody tr.cursor-pointer:hover {
+  background-color: rgba(0, 0, 0, 0.045);
+}
+.dark .cpq-list-view tbody tr.cursor-pointer:hover,
+.dark .cpq-page tbody tr.cursor-pointer:hover {
+  background-color: rgba(255, 255, 255, 0.06);
+}
+.cpq-list-view button:not(:disabled),
+.cpq-list-view [role="button"]:not([aria-disabled="true"]),
+.cpq-list-view a[href],
+.cpq-list-view [data-clickable="true"],
+.cpq-page button:not(:disabled),
+.cpq-page [role="button"]:not([aria-disabled="true"]),
+.cpq-page a[href],
+.cpq-page [data-clickable="true"] {
+  cursor: pointer;
+}
+/* Row actions \`⋯\` trigger: OM's hover:bg-accent is barely visible in
+   the light theme. Make hover (and the open state) clearly distinct so
+   users see what they're aiming at. */
+.cpq-list-view [aria-haspopup="menu"]:hover,
+.cpq-page [aria-haspopup="menu"]:hover,
+.cpq-list-view [aria-haspopup="menu"][aria-expanded="true"],
+.cpq-page [aria-haspopup="menu"][aria-expanded="true"] {
+  background-color: rgba(0, 0, 0, 0.08);
+}
+.dark .cpq-list-view [aria-haspopup="menu"]:hover,
+.dark .cpq-page [aria-haspopup="menu"]:hover,
+.dark .cpq-list-view [aria-haspopup="menu"][aria-expanded="true"],
+.dark .cpq-page [aria-haspopup="menu"][aria-expanded="true"] {
+  background-color: rgba(255, 255, 255, 0.1);
+}
+/* Items inside the row-actions dropdown menu — strengthen hover so the
+   item under the pointer is unmistakable. The menu portal renders at the
+   document body, so we can't scope it to .cpq-list-view; targeting the
+   role attribute is enough. */
+[role="menu"] [role="menuitem"]:hover,
+[role="menu"] [role="menuitem"]:focus-visible {
+  background-color: rgba(0, 0, 0, 0.06);
+}
+.dark [role="menu"] [role="menuitem"]:hover,
+.dark [role="menu"] [role="menuitem"]:focus-visible {
+  background-color: rgba(255, 255, 255, 0.08);
+}
+/* Align padding between <a href> menu items (OM's px-2) and the <button>
+   variant used for onSelect items (OM's Button size=sm = px-3). Without
+   this the Delete label visibly indents past the Edit label. */
+[role="menu"] button[role="menuitem"] {
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+`}</style>
+  )
+}

package/src/modules/cpq/components/NumberInput.tsx

@@ -0,0 +1,166 @@
+"use client"
+import * as React from 'react'
+import { Input, type InputProps } from '@open-mercato/ui/primitives/input'
+
+// ─── Why this exists ─────────────────────────────────────────────
+//
+// Plain `<input type="number" value={state}>` is hostile when `state === 0`:
+// the field renders "0", the caret lands AFTER it, and typing "5" produces
+// "05" which most browsers normalise back to `5` — the user typed five but
+// the field swallowed the digit they wanted to keep. Same trap when editing
+// any single-digit existing value.
+//
+// NumberInput fixes this with two layered behaviours:
+//
+//   1. **Select on focus.** Tabbing or clicking into the field selects the
+//      whole text, so the next keystroke replaces the existing value
+//      instead of prepending to it. This single change removes ~95 % of the
+//      friction without changing the controlled-component contract.
+//
+//   2. **Internal string state.** The input is rendered with a string we
+//      own, not `String(numericState)`. That lets intermediate edits like
+//      `"-"`, `"1."`, or empty stay visible while the parent only ever sees
+//      a parsed `number | null`. Parent updates (programmatic reset after
+//      save, form initial load) still flow in via the effect below.
+//
+// It also drops `type="number"` in favour of `type="text"` +
+// `inputMode={'numeric' | 'decimal'}` so we get the right mobile keyboard
+// without the spinner buttons and the silent step/min/max coercion that
+// HTML number inputs apply on blur.
+
+export type NumberInputProps = Omit<
+  InputProps,
+  'value' | 'onChange' | 'type' | 'inputMode' | 'defaultValue'
+> & {
+  /**
+   * Numeric value. `null`/`undefined` renders the field empty — that's how
+   * callers signal "no value yet" without colliding with `0` as a real
+   * default.
+   */
+  value: number | null | undefined
+  /** Called with the parsed number, or `null` when the field is cleared. */
+  onChange: (value: number | null) => void
+  /** Selects the input contents on focus. Default true. */
+  selectOnFocus?: boolean
+  /** Restrict input to integers (rejects `.`, `e`, etc). Default false. */
+  integer?: boolean
+  /** Optional minimum (enforced on commit, not while typing). */
+  min?: number
+  /** Optional maximum (enforced on commit, not while typing). */
+  max?: number
+}
+
+function isIntermediateInput(raw: string, integer: boolean): boolean {
+  // Allow the user to type these without us replacing the field mid-edit.
+  // - empty / lone `-`           → not parseable yet
+  // - trailing `.` for decimals  → not parseable yet
+  // - trailing `e` / `e-`        → scientific notation in progress
+  if (raw === '' || raw === '-') return true
+  if (!integer && (raw.endsWith('.') || raw.endsWith('e') || raw.endsWith('e-'))) return true
+  return false
+}
+
+export const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
+  function NumberInput(
+    {
+      value,
+      onChange,
+      selectOnFocus = true,
+      integer = false,
+      min,
+      max,
+      onFocus,
+      onBlur,
+      ...rest
+    },
+    ref,
+  ) {
+    const [text, setText] = React.useState<string>(value == null ? '' : String(value))
+    const lastEmittedRef = React.useRef<number | null | undefined>(value)
+
+    // Sync external updates (form reset after save, initial load, etc.) into
+    // the local text state — but only when the parent's value actually
+    // diverges from what we last emitted, so we don't clobber intermediate
+    // text like "1." while the user is mid-edit.
+    React.useEffect(() => {
+      if (lastEmittedRef.current === value) return
+      setText(value == null ? '' : String(value))
+      lastEmittedRef.current = value
+    }, [value])
+
+    const clamp = React.useCallback(
+      (n: number): number => {
+        let result = n
+        if (typeof min === 'number' && result < min) result = min
+        if (typeof max === 'number' && result > max) result = max
+        return result
+      },
+      [max, min],
+    )
+
+    const handleChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        const raw = e.currentTarget.value
+
+        // Strip characters that are never valid in our numeric formats; this
+        // lets us keep `type="text"` while still rejecting alphabetic input.
+        const allowed = integer ? /[^\d-]/g : /[^\d.\-eE]/g
+        const cleaned = raw.replace(allowed, '')
+
+        if (isIntermediateInput(cleaned, integer)) {
+          setText(cleaned)
+          // Treat intermediates as "no committed value yet" — emit null so
+          // the parent doesn't store a half-typed number. The full value
+          // commits on the next valid keystroke or on blur.
+          if (lastEmittedRef.current !== null) {
+            lastEmittedRef.current = null
+            onChange(null)
+          }
+          return
+        }
+
+        const parsed = integer ? parseInt(cleaned, 10) : parseFloat(cleaned)
+        if (Number.isNaN(parsed)) return // Reject — keep previous state.
+
+        setText(cleaned)
+        const next = clamp(parsed)
+        if (lastEmittedRef.current !== next) {
+          lastEmittedRef.current = next
+          onChange(next)
+        }
+      },
+      [clamp, integer, onChange],
+    )
+
+    const handleBlur = React.useCallback(
+      (e: React.FocusEvent<HTMLInputElement>) => {
+        // On blur, normalise the displayed text to match the committed value
+        // (e.g. "01" → "1", "1." → "1"). Empty stays empty.
+        if (lastEmittedRef.current == null) {
+          if (text !== '') setText('')
+        } else {
+          const normalised = String(lastEmittedRef.current)
+          if (text !== normalised) setText(normalised)
+        }
+        onBlur?.(e)
+      },
+      [onBlur, text],
+    )
+
+    return (
+      <Input
+        ref={ref}
+        {...rest}
+        type="text"
+        inputMode={integer ? 'numeric' : 'decimal'}
+        value={text}
+        onFocus={(e) => {
+          if (selectOnFocus) e.currentTarget.select()
+          onFocus?.(e)
+        }}
+        onChange={handleChange}
+        onBlur={handleBlur}
+      />
+    )
+  },
+)