@spree/dashboard-ui 0.1.0

package/src/spree/copy-to-clipboard-button.tsx

@@ -0,0 +1,90 @@
+import { CheckIcon, CopyIcon } from 'lucide-react'
+import type { ComponentProps, ReactNode } from 'react'
+import { useCopyToClipboard } from '../hooks/use-copy-to-clipboard'
+import { cn } from '../lib/utils'
+import { Button } from '../ui/button'
+
+type ButtonProps = ComponentProps<typeof Button>
+
+type CopyToClipboardButtonProps = Omit<ButtonProps, 'onClick' | 'children'> & {
+  /** Text to write to the clipboard. */
+  value: string
+  /** Accessible label for the button — required by a11y rules. */
+  'aria-label': string
+  /** Custom icon for the idle state. Defaults to `CopyIcon`. */
+  icon?: ReactNode
+  /** Custom icon for the copied state. Defaults to `CheckIcon`. */
+  copiedIcon?: ReactNode
+  /** Optional label rendered alongside the icon (e.g. "Copy"). */
+  label?: ReactNode
+  /** Optional label rendered alongside the icon while in the copied state. */
+  copiedLabel?: ReactNode
+  /**
+   * How long the copied state stays true after a successful copy. Forwarded to
+   * `useCopyToClipboard`. Defaults to 1200ms (the hook's default).
+   */
+  resetMs?: number
+  /**
+   * Stop the click event from bubbling. Useful inside `<ResourceTable>` rows
+   * where `useRowClickBridge` would otherwise also fire. Defaults to `true`
+   * since that's the common case — pass `false` to opt out.
+   */
+  stopPropagation?: boolean
+}
+
+/**
+ * Universal copy-to-clipboard button. Renders a standard `<Button>` with a
+ * copy icon that flips to a check icon for a short flash after a successful
+ * copy. Forwards every `<Button>` prop except `onClick` + `children`, so the
+ * caller controls variant, size, className, etc.
+ *
+ * @example  Bare icon button next to a value
+ *   <span>
+ *     <code>{token}</code>
+ *     <CopyToClipboardButton value={token} aria-label="Copy token" size="icon-xs" variant="ghost" />
+ *   </span>
+ *
+ * @example  Labelled button inside a modal
+ *   <CopyToClipboardButton
+ *     value={secret}
+ *     aria-label="Copy secret"
+ *     size="sm"
+ *     variant="outline"
+ *     label="Copy"
+ *     copiedLabel="Copied"
+ *   />
+ */
+export function CopyToClipboardButton({
+  value,
+  icon = <CopyIcon />,
+  copiedIcon = <CheckIcon />,
+  label,
+  copiedLabel,
+  resetMs,
+  stopPropagation = true,
+  className,
+  size = 'icon-xs',
+  variant = 'ghost',
+  type = 'button',
+  ...rest
+}: CopyToClipboardButtonProps) {
+  const { copied, copy } = useCopyToClipboard(resetMs !== undefined ? { resetMs } : undefined)
+  const displayedLabel = copied && copiedLabel !== undefined ? copiedLabel : label
+
+  return (
+    <Button
+      {...rest}
+      type={type}
+      size={size}
+      variant={variant}
+      className={cn(className)}
+      onClick={(e) => {
+        if (stopPropagation) e.stopPropagation()
+        copy(value)
+      }}
+    >
+      {copied ? copiedIcon : icon}
+      {displayedLabel}
+    </Button>
+  )
+}

package/src/spree/country-flag.tsx

@@ -0,0 +1,30 @@
+import { cn } from '../lib/utils'
+
+interface CountryFlagProps {
+  /** ISO 3166-1 alpha-2 country code (case-insensitive). */
+  iso: string
+  /** Override the default `1.333em` × `1em` size. Pass any Tailwind size. */
+  className?: string
+}
+
+/**
+ * Renders a country flag via the `flag-icons` CSS sprite. The sprite resolves
+ * `.fi.fi-{iso}` to a `background-image` URL pointing at the matching SVG —
+ * the browser lazy-loads each flag only when it actually appears on screen.
+ *
+ * Decorative by design (`aria-hidden`); the surrounding label/text carries
+ * the country name for screen readers.
+ */
+export function CountryFlag({ iso, className }: CountryFlagProps) {
+  if (!iso) return null
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'fi shrink-0 rounded-[2px] shadow-[0_0_0_0.5px_rgba(0,0,0,0.08)]',
+        `fi-${iso.toLowerCase()}`,
+        className,
+      )}
+    />
+  )
+}

package/src/spree/data-grid/cells.tsx

@@ -0,0 +1,415 @@
+import { type KeyboardEvent, type ReactNode, useEffect, useId, useRef, useState } from 'react'
+import { cn } from '../../lib/utils'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../ui/select'
+import { Switch } from '../../ui/switch'
+import { modeFor, useDataGridContext } from './context'
+import type { CellCoords } from './types'
+import { useStableCellRegistration } from './use-stable-cell-registration'
+
+interface BaseCellProps {
+  coords: CellCoords
+  ariaLabel: string
+}
+
+interface NumberCellProps extends BaseCellProps {
+  value: number
+  onChange: (next: number) => void
+  /** Visual hint — e.g. low-stock items get a colored border. */
+  intent?: 'default' | 'warning'
+}
+
+/** Editable numeric cell. In selection mode the underlying input is
+ *  read-only (so arrow keys navigate the grid); in edit mode it accepts
+ *  typing and arrow keys move the caret. */
+export function NumberCell({
+  coords,
+  value,
+  onChange,
+  ariaLabel,
+  intent = 'default',
+}: NumberCellProps) {
+  const ctx = useDataGridContext()
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const [draft, setDraft] = useState(value.toString())
+  const isSelected = ctx.isSelected(coords)
+  const mode = modeFor(ctx.editing, coords)
+  const isEditing = mode === 'edit'
+  const isFocused = ctx.anchor?.row === coords.row && ctx.anchor?.col === coords.col
+
+  // Resync draft with external value when not editing this cell.
+  useEffect(() => {
+    if (!isEditing) setDraft(value.toString())
+  }, [value, isEditing])
+
+  // Auto-focus + select when entering edit mode.
+  useEffect(() => {
+    if (isEditing) {
+      const el = inputRef.current
+      if (el) {
+        el.focus()
+        el.select()
+      }
+    }
+  }, [isEditing])
+
+  useStableCellRegistration(coords, {
+    focus: () => inputRef.current?.focus(),
+    read: () => value.toString(),
+    write: (next) => {
+      const n = Number(next)
+      if (!Number.isFinite(n)) return
+      onChange(Math.trunc(n))
+    },
+    canWrite: (next) => next === '' || Number.isFinite(Number(next)),
+  })
+
+  function commit() {
+    const n = Number(draft)
+    if (Number.isFinite(n)) onChange(Math.trunc(n))
+    else setDraft(value.toString())
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (!isEditing) {
+      // Selection mode: forward navigation keys to the grid by NOT preventing
+      // default. Mark this cell as the anchor on plain mouse-click style focus.
+      return
+    }
+    if (event.key === 'Enter') {
+      event.preventDefault()
+      commit()
+      ctx.setEditing(null)
+      // Move down to mirror Excel.
+      const next = { row: coords.row + 1, col: coords.col }
+      ctx.setAnchor(next)
+      ctx.setExtent(next)
+      ctx.cells.get(`${next.row}.${next.col}`)?.focus()
+    } else if (event.key === 'Escape') {
+      event.preventDefault()
+      setDraft(value.toString())
+      ctx.setEditing(null)
+    } else if (event.key === 'Tab') {
+      event.preventDefault()
+      commit()
+      ctx.setEditing(null)
+      const dx = event.shiftKey ? -1 : 1
+      const next = { row: coords.row, col: coords.col + dx }
+      ctx.setAnchor(next)
+      ctx.setExtent(next)
+      ctx.cells.get(`${next.row}.${next.col}`)?.focus()
+    }
+  }
+
+  return (
+    <input
+      ref={inputRef}
+      type="text"
+      inputMode="numeric"
+      value={isEditing ? draft : value.toString()}
+      readOnly={!isEditing}
+      onChange={(e) => setDraft(e.target.value)}
+      onFocus={() => {
+        ctx.setAnchor(coords)
+        ctx.setExtent(coords)
+      }}
+      onDoubleClick={() => ctx.setEditing(coords)}
+      onKeyDown={onKeyDown}
+      onBlur={() => {
+        if (isEditing) {
+          commit()
+          ctx.setEditing(null)
+        }
+      }}
+      aria-label={ariaLabel}
+      className={cn(
+        'block h-9 w-full cursor-cell border-0 bg-transparent px-3 text-right tabular-nums outline-none ring-inset transition-colors',
+        isSelected && 'bg-blue-500/10',
+        isFocused && !isEditing && 'ring-2 ring-blue-500',
+        isEditing && 'cursor-text bg-card ring-2 ring-blue-500',
+        intent === 'warning' && !isSelected && !isFocused && 'text-amber-700',
+      )}
+    />
+  )
+}
+
+interface MoneyCellProps extends BaseCellProps {
+  /** Canonical decimal string (`12.50`) coming back from the API, or
+   *  `null`/blank for unset. */
+  value: string | null
+  /** Receives the user's raw input — locale-formatted strings like
+   *  `"12,50"` are fine, the backend's `Spree::LocalizedNumber` does the
+   *  parsing. `null` only when the user explicitly blanks the field. */
+  onChange: (next: string | null) => void
+  /** Currency symbol rendered as a non-editable prefix (`$`, `€`, `kr`, …). */
+  symbol: string
+  /**
+   * Locale decimal separator used only for display (canonical `.` →
+   * locale char). Whatever the user types is shipped as-is; the
+   * backend handles thousands separators, grouped digits, and so on.
+   * Default `.`.
+   */
+  decimal?: string
+}
+
+/**
+ * Editable money cell. Like `NumberCell` but keeps decimals (no truncation)
+ * and renders a currency-symbol prefix. Mirrors the rails admin's
+ * `edit_prices` bulk editor: format the API's canonical value with the
+ * locale's decimal mark for display, but ship the user's raw input
+ * untouched on save. `Spree::LocalizedNumber.parse` on the backend handles
+ * locale-aware parsing (thousands separators, decimal comma, etc.) so the
+ * SPA doesn't have to reimplement it.
+ */
+export function MoneyCell({
+  coords,
+  value,
+  onChange,
+  symbol,
+  decimal = '.',
+  ariaLabel,
+}: MoneyCellProps) {
+  const ctx = useDataGridContext()
+  const inputRef = useRef<HTMLInputElement | null>(null)
+
+  const formatDisplay = (v: string | null): string =>
+    v == null || v === '' ? '' : v.replace('.', decimal)
+
+  const [draft, setDraft] = useState(formatDisplay(value))
+  const isSelected = ctx.isSelected(coords)
+  const mode = modeFor(ctx.editing, coords)
+  const isEditing = mode === 'edit'
+  const isFocused = ctx.anchor?.row === coords.row && ctx.anchor?.col === coords.col
+
+  // Resync draft with external value when not editing.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional resync
+  useEffect(() => {
+    if (!isEditing) setDraft(formatDisplay(value))
+  }, [value, isEditing, decimal])
+
+  // Auto-focus + select when entering edit mode.
+  useEffect(() => {
+    if (isEditing) {
+      const el = inputRef.current
+      if (el) {
+        el.focus()
+        el.select()
+      }
+    }
+  }, [isEditing])
+
+  // The wrapping div is what the FillHandle measures and what
+  // elementFromPoint hits during a fill drag — register it as the
+  // cell's element. The input itself is what we focus.
+  const wrapRef = useRef<HTMLDivElement | null>(null)
+  useStableCellRegistration(coords, {
+    focus: () => inputRef.current?.focus(),
+    read: () => formatDisplay(value),
+    write: (next) => onChange(next.trim() ? next : null),
+    canWrite: () => true,
+    getElement: () => wrapRef.current,
+  })
+
+  function commit() {
+    // Ship the user's raw input; the backend's `Spree::LocalizedNumber`
+    // handles locale-aware parsing. Empty string is the only "clear"
+    // signal we generate frontend-side.
+    onChange(draft.trim() ? draft : null)
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (!isEditing) return
+    if (event.key === 'Enter') {
+      event.preventDefault()
+      commit()
+      ctx.setEditing(null)
+      const next = { row: coords.row + 1, col: coords.col }
+      ctx.setAnchor(next)
+      ctx.setExtent(next)
+      ctx.cells.get(`${next.row}.${next.col}`)?.focus()
+    } else if (event.key === 'Escape') {
+      event.preventDefault()
+      setDraft(formatDisplay(value))
+      ctx.setEditing(null)
+    } else if (event.key === 'Tab') {
+      event.preventDefault()
+      commit()
+      ctx.setEditing(null)
+      const dx = event.shiftKey ? -1 : 1
+      const next = { row: coords.row, col: coords.col + dx }
+      ctx.setAnchor(next)
+      ctx.setExtent(next)
+      ctx.cells.get(`${next.row}.${next.col}`)?.focus()
+    }
+  }
+
+  return (
+    <div
+      ref={wrapRef}
+      className={cn(
+        'flex h-9 w-full items-center transition-colors',
+        isSelected && 'bg-blue-500/10',
+        isFocused && !isEditing && 'ring-2 ring-blue-500 ring-inset',
+        isEditing && 'bg-card ring-2 ring-blue-500 ring-inset',
+      )}
+    >
+      <span
+        className="pl-3 text-muted-foreground pointer-events-none select-none tabular-nums"
+        aria-hidden
+      >
+        {symbol}
+      </span>
+      <input
+        ref={inputRef}
+        type="text"
+        inputMode="decimal"
+        value={isEditing ? draft : formatDisplay(value)}
+        readOnly={!isEditing}
+        onChange={(e) => setDraft(e.target.value)}
+        onFocus={() => {
+          ctx.setAnchor(coords)
+          ctx.setExtent(coords)
+        }}
+        onDoubleClick={() => ctx.setEditing(coords)}
+        onKeyDown={onKeyDown}
+        onBlur={() => {
+          if (isEditing) {
+            commit()
+            ctx.setEditing(null)
+          }
+        }}
+        aria-label={ariaLabel}
+        className={cn(
+          'block h-9 w-full cursor-cell border-0 bg-transparent pl-1 pr-3 text-right tabular-nums outline-none',
+          isEditing && 'cursor-text',
+        )}
+      />
+    </div>
+  )
+}
+
+interface SwitchCellProps extends BaseCellProps {
+  value: boolean
+  onChange: (next: boolean) => void
+}
+
+/** Boolean cell. Space toggles; there's no separate edit mode because the
+ *  switch is a single-action control. */
+export function SwitchCell({ coords, value, onChange, ariaLabel }: SwitchCellProps) {
+  const ctx = useDataGridContext()
+  const wrapRef = useRef<HTMLDivElement | null>(null)
+  const isSelected = ctx.isSelected(coords)
+  const isFocused = ctx.anchor?.row === coords.row && ctx.anchor?.col === coords.col
+
+  useStableCellRegistration(coords, {
+    focus: () => wrapRef.current?.focus(),
+    read: () => (value ? 'true' : 'false'),
+    write: (next) => {
+      const lower = next.toLowerCase().trim()
+      if (lower === 'true' || lower === '1' || lower === 'yes') onChange(true)
+      else if (lower === 'false' || lower === '0' || lower === 'no' || lower === '') onChange(false)
+    },
+    canWrite: (next) =>
+      ['', 'true', 'false', '1', '0', 'yes', 'no'].includes(next.toLowerCase().trim()),
+  })
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (event.key === ' ' || event.key === 'Enter') {
+      event.preventDefault()
+      onChange(!value)
+    }
+  }
+
+  return (
+    <div
+      ref={wrapRef}
+      tabIndex={0}
+      role="switch"
+      aria-checked={value}
+      aria-label={ariaLabel}
+      onFocus={() => {
+        ctx.setAnchor(coords)
+        ctx.setExtent(coords)
+      }}
+      onKeyDown={onKeyDown}
+      className={cn(
+        'flex h-9 w-full cursor-cell items-center px-3 outline-none ring-inset transition-colors',
+        isSelected && 'bg-blue-500/10',
+        isFocused && 'ring-2 ring-blue-500',
+      )}
+    >
+      <Switch checked={value} onCheckedChange={onChange} aria-hidden tabIndex={-1} />
+    </div>
+  )
+}
+
+interface SelectCellProps<V extends string> extends BaseCellProps {
+  value: V
+  onChange: (next: V) => void
+  options: ReadonlyArray<{ value: V; label: string }>
+}
+
+/** Cell for fixed-option pickers. Enter opens the Select; arrow keys inside
+ *  the open Select navigate options (Base UI default). Esc closes. */
+export function SelectCell<V extends string>({
+  coords,
+  value,
+  onChange,
+  options,
+  ariaLabel,
+}: SelectCellProps<V>) {
+  const ctx = useDataGridContext()
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const isSelected = ctx.isSelected(coords)
+  const isFocused = ctx.anchor?.row === coords.row && ctx.anchor?.col === coords.col
+  const id = useId()
+
+  useStableCellRegistration(coords, {
+    focus: () => triggerRef.current?.focus(),
+    read: () => value,
+    write: (next) => {
+      if (options.some((o) => o.value === next)) onChange(next as V)
+    },
+    canWrite: (next) => options.some((o) => o.value === next) || next === '',
+  })
+
+  return (
+    <Select items={options} value={value} onValueChange={(v) => onChange(v as V)}>
+      <SelectTrigger
+        ref={triggerRef}
+        id={id}
+        aria-label={ariaLabel}
+        onFocus={() => {
+          ctx.setAnchor(coords)
+          ctx.setExtent(coords)
+        }}
+        className={cn(
+          // Strip the Select's standard chrome so the cell reads as a flat
+          // grid slot. The cell's own ring/bg comes from below.
+          'h-9 min-h-0 w-full cursor-cell rounded-none border-0 bg-transparent px-3 text-sm shadow-none ring-inset transition-colors focus:border-0 focus:shadow-none',
+          isSelected && 'bg-blue-500/10',
+          isFocused && 'ring-2 ring-blue-500',
+        )}
+      >
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {options.map((opt) => (
+          <SelectItem key={opt.value} value={opt.value}>
+            {opt.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  )
+}
+
+interface ReadOnlyCellProps {
+  children: ReactNode
+  className?: string
+}
+
+/** Plain non-editable cell — first column of a row (e.g. label / link).
+ *  Not registered with the grid, so Tab/arrows skip it. */
+export function ReadOnlyCell({ children, className }: ReadOnlyCellProps) {
+  return <div className={cn('flex h-9 items-center px-3 text-sm', className)}>{children}</div>
+}

package/src/spree/data-grid/context.ts

@@ -0,0 +1,59 @@
+import { createContext, useContext } from 'react'
+import type { CellCoords, CellKey, CellRegistration, GridMode } from './types'
+
+export interface DataGridContextValue {
+  /** Stable map of `${row}.${col}` → registration. Mutated imperatively by
+   *  cells in their mount effect so we don't churn React state on every
+   *  render. Consumers should iterate via `eachCell()` rather than peeking
+   *  at the Map directly. */
+  cells: Map<CellKey, CellRegistration>
+
+  /** Bounds, recomputed when cells register/unregister. */
+  bounds: { maxRow: number; maxCol: number }
+
+  /** Selection anchor (origin of a Shift+Arrow extension) and extent (current
+   *  far corner). When equal, only one cell is selected. Null means no
+   *  selection at all. */
+  anchor: CellCoords | null
+  extent: CellCoords | null
+
+  /** Currently editing cell. When set, keyboard nav shortcuts are routed
+   *  through the cell instead of the grid. */
+  editing: CellCoords | null
+
+  /** Dispatchers — components react via subscribed selectors below. */
+  setAnchor: (coords: CellCoords | null) => void
+  setExtent: (coords: CellCoords | null) => void
+  setEditing: (coords: CellCoords | null) => void
+
+  /** Register/unregister a cell. Returns a cleanup. */
+  registerCell: (reg: CellRegistration) => () => void
+
+  /** Snapshot helpers used by the keyboard hook. */
+  isSelected: (coords: CellCoords) => boolean
+  selectedCells: () => CellRegistration[]
+}
+
+export const DataGridContext = createContext<DataGridContextValue | null>(null)
+
+export function useDataGridContext(): DataGridContextValue {
+  const ctx = useContext(DataGridContext)
+  if (!ctx) {
+    throw new Error('Data grid cells must be rendered inside <DataGrid>.')
+  }
+  return ctx
+}
+
+/** Inclusive rectangle test. */
+export function coordsInRect(c: CellCoords, a: CellCoords | null, b: CellCoords | null): boolean {
+  if (!a || !b) return false
+  const minRow = Math.min(a.row, b.row)
+  const maxRow = Math.max(a.row, b.row)
+  const minCol = Math.min(a.col, b.col)
+  const maxCol = Math.max(a.col, b.col)
+  return c.row >= minRow && c.row <= maxRow && c.col >= minCol && c.col <= maxCol
+}
+
+export function modeFor(editing: CellCoords | null, coords: CellCoords): GridMode {
+  return editing && editing.row === coords.row && editing.col === coords.col ? 'edit' : 'select'
+}