@pilotiq/pilotiq 0.1.0

package/src/react/cells/EditableCell.tsx

@@ -0,0 +1,376 @@
+import React, { useEffect, useRef, useState } from 'react'
+
+import { Input } from '../ui/input.js'
+import { Switch } from '../ui/switch.js'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '../ui/select.js'
+import { useToast } from '../Toaster.js'
+import type { NotificationMeta } from '../../notifications/Notification.js'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '../ui/dialog.js'
+import { Button } from '../ui/button.js'
+
+const DEFAULT_DEBOUNCE_MS = 500
+
+/** Shared shape consumed by all three editable-cell renderers. */
+export interface EditableCellProps {
+  /** PATCH endpoint stamped per row by `tagCellEditUrls`. */
+  url:      string
+  /** Column meta as serialized to the client. */
+  col:      Record<string, unknown>
+  /** Raw value from the row (pre-coerce, post-server). */
+  value:    unknown
+  /** Disabled = static `disabled()` OR per-row `_cellDisabled[col]`. */
+  disabled: boolean
+}
+
+interface PatchResultOk {
+  ok:            true
+  value:         unknown
+  notifications: NotificationMeta[] | undefined
+}
+interface PatchResultErrors {
+  ok:     false
+  errors: Record<string, string[]>
+}
+interface PatchResultError {
+  ok:    false
+  error: string
+}
+type PatchResult = PatchResultOk | PatchResultErrors | PatchResultError
+
+async function patchCell(url: string, value: unknown): Promise<PatchResult> {
+  const res = await fetch(url, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+    body:    JSON.stringify({ value }),
+  })
+  let body: unknown = null
+  try { body = await res.json() } catch { /* fall through */ }
+  if (res.ok && body && typeof body === 'object') {
+    const b = body as Record<string, unknown>
+    return {
+      ok: true,
+      value: b['value'],
+      notifications: Array.isArray(b['notifications'])
+        ? b['notifications'] as NotificationMeta[]
+        : undefined,
+    }
+  }
+  if (body && typeof body === 'object') {
+    const b = body as Record<string, unknown>
+    if (b['errors']) {
+      return { ok: false, errors: b['errors'] as Record<string, string[]> }
+    }
+    if (typeof b['error'] === 'string') {
+      return { ok: false, error: b['error'] }
+    }
+  }
+  return { ok: false, error: `Request failed (${res.status})` }
+}
+
+/** Pull the first error message out of a `{ errors: { value: [...] } }`
+ * response. Falls back to a generic "Couldn't save" string. */
+function firstErrorMessage(result: PatchResultErrors | PatchResultError): string {
+  if ('errors' in result) {
+    const fieldErrs = result.errors['value']
+    if (fieldErrs && fieldErrs.length > 0) return fieldErrs[0]!
+  }
+  if ('error' in result) return result.error
+  return "Couldn't save"
+}
+
+/** Confirm-gated wrapper. Renders a Dialog with the `confirm` message
+ * before invoking `onConfirm`; cancel calls `onCancel` so the caller can
+ * roll back the optimistic state. Mounts only when `open=true` so its
+ * children aren't kept alive between confirm cycles. */
+function ConfirmDialog({
+  open, message, onConfirm, onCancel,
+}: {
+  open:      boolean
+  message:   string
+  onConfirm: () => void
+  onCancel:  () => void
+}): React.ReactElement | null {
+  if (!open) return null
+  return (
+    <Dialog open={open} onOpenChange={(v) => { if (!v) onCancel() }}>
+      <DialogContent className="sm:max-w-sm">
+        <DialogHeader>
+          <DialogTitle>Confirm change</DialogTitle>
+          <DialogDescription>{message}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button variant="ghost" onClick={onCancel}>Cancel</Button>
+          <Button onClick={onConfirm}>Confirm</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+// ─── TextInput cell ────────────────────────────────────
+
+export function CellTextInput(props: EditableCellProps): React.ReactElement {
+  const { url, col, value, disabled } = props
+  const inputType    = (col['inputType']        as string | undefined) ?? 'text'
+  const placeholder  = col['inputPlaceholder']  as string | undefined
+  const step         = col['inputStep']         as number | undefined
+  const minVal       = col['inputMin']          as number | undefined
+  const maxVal       = col['inputMax']          as number | undefined
+  const debounceMs   = (col['debounceMs']       as number | undefined) ?? DEFAULT_DEBOUNCE_MS
+  const confirmMsg   = col['confirm']           as string | undefined
+
+  const [localValue, setLocalValue] = useState<string>(() =>
+    value === null || value === undefined ? '' : String(value),
+  )
+  const committedRef = useRef<string>(localValue)
+  const debounceRef  = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const seqRef       = useRef(0)
+  const [pendingConfirm, setPendingConfirm] = useState<string | null>(null)
+  const { notify } = useToast()
+
+  useEffect(() => {
+    return () => { if (debounceRef.current) clearTimeout(debounceRef.current) }
+  }, [])
+
+  const commit = async (next: string): Promise<void> => {
+    if (next === committedRef.current) return
+    const prev = committedRef.current
+    committedRef.current = next
+    const seq = ++seqRef.current
+    const result = await patchCell(url, next)
+    if (seq !== seqRef.current) return  // a newer commit has already fired
+    if (result.ok) {
+      // Success: keep the local + committed in sync. No success toast — saving
+      // every keystroke would be noise.
+      result.notifications?.forEach(n => notify(n))
+    } else {
+      committedRef.current = prev
+      setLocalValue(prev)
+      notify({
+        type:  'error',
+        title: "Couldn't save",
+        body:  firstErrorMessage(result),
+      })
+    }
+  }
+
+  const queueCommit = (next: string): void => {
+    if (debounceRef.current) clearTimeout(debounceRef.current)
+    if (confirmMsg) {
+      // Confirm-gated: don't send anything until the user accepts.
+      setPendingConfirm(next)
+      return
+    }
+    debounceRef.current = setTimeout(() => { void commit(next) }, debounceMs)
+  }
+
+  const flushOnBlur = (): void => {
+    if (debounceRef.current) { clearTimeout(debounceRef.current); debounceRef.current = null }
+    if (confirmMsg) return                        // wait for the dialog
+    void commit(localValue)
+  }
+
+  return (
+    <div className="px-2 py-1" data-no-row-nav>
+      <Input
+        type={inputType}
+        value={localValue}
+        placeholder={placeholder}
+        step={step}
+        min={minVal}
+        max={maxVal}
+        disabled={disabled}
+        onChange={(e) => { setLocalValue(e.target.value); queueCommit(e.target.value) }}
+        onBlur={flushOnBlur}
+        className="h-8"
+      />
+      <ConfirmDialog
+        open={pendingConfirm !== null}
+        message={confirmMsg ?? ''}
+        onConfirm={() => {
+          const next = pendingConfirm!
+          setPendingConfirm(null)
+          void commit(next)
+        }}
+        onCancel={() => {
+          // Roll back the local state to the committed value.
+          setLocalValue(committedRef.current)
+          setPendingConfirm(null)
+        }}
+      />
+    </div>
+  )
+}
+
+// ─── Toggle cell ───────────────────────────────────────
+
+export function CellToggle(props: EditableCellProps): React.ReactElement {
+  const { url, value, disabled, col } = props
+  const confirmMsg = col['confirm'] as string | undefined
+  const [localValue, setLocalValue] = useState<boolean>(() => Boolean(value))
+  const committedRef = useRef<boolean>(localValue)
+  const seqRef       = useRef(0)
+  const [pendingConfirm, setPendingConfirm] = useState<boolean | null>(null)
+  const { notify } = useToast()
+
+  const commit = async (next: boolean): Promise<void> => {
+    const prev = committedRef.current
+    committedRef.current = next
+    const seq = ++seqRef.current
+    const result = await patchCell(url, next)
+    if (seq !== seqRef.current) return
+    if (result.ok) {
+      result.notifications?.forEach(n => notify(n))
+    } else {
+      committedRef.current = prev
+      setLocalValue(prev)
+      notify({
+        type:  'error',
+        title: "Couldn't save",
+        body:  firstErrorMessage(result),
+      })
+    }
+  }
+
+  const onChange = (next: boolean): void => {
+    setLocalValue(next)
+    if (confirmMsg) { setPendingConfirm(next); return }
+    void commit(next)
+  }
+
+  return (
+    <div className="px-2 py-2" data-no-row-nav>
+      <Switch
+        checked={localValue}
+        disabled={disabled}
+        onCheckedChange={onChange}
+      />
+      <ConfirmDialog
+        open={pendingConfirm !== null}
+        message={confirmMsg ?? ''}
+        onConfirm={() => {
+          const next = pendingConfirm!
+          setPendingConfirm(null)
+          void commit(next)
+        }}
+        onCancel={() => {
+          // Roll back to the committed value — flips the switch back.
+          setLocalValue(committedRef.current)
+          setPendingConfirm(null)
+        }}
+      />
+    </div>
+  )
+}
+
+// ─── Select cell ───────────────────────────────────────
+
+export function CellSelect(props: EditableCellProps): React.ReactElement {
+  const { url, value, disabled, col } = props
+  const opts: Array<{ value: string; label: string }> =
+    Array.isArray(col['selectOptions']) ? col['selectOptions'] as Array<{ value: string; label: string }> : []
+  const nullable    = col['selectNullable'] === true
+  const showPlaceholderOnce = col['selectablePlaceholder'] !== false  // default true (keep showing)
+  const confirmMsg  = col['confirm'] as string | undefined
+
+  const valueAsString = (v: unknown): string =>
+    v === null || v === undefined ? '' : String(v)
+
+  const [localValue, setLocalValue] = useState<string>(() => valueAsString(value))
+  const committedRef = useRef<string>(localValue)
+  const seqRef       = useRef(0)
+  const [pendingConfirm, setPendingConfirm] = useState<string | null>(null)
+  const { notify } = useToast()
+
+  const commit = async (next: string): Promise<void> => {
+    const prev = committedRef.current
+    committedRef.current = next
+    const seq = ++seqRef.current
+    // Empty-string value with `nullable()` becomes `null` on the wire so
+    // the server-side coerce path treats it as a clear, not an option key.
+    const wire: string | null = next === '' && nullable ? null : next
+    const result = await patchCell(url, wire)
+    if (seq !== seqRef.current) return
+    if (result.ok) {
+      result.notifications?.forEach(n => notify(n))
+    } else {
+      committedRef.current = prev
+      setLocalValue(prev)
+      notify({
+        type:  'error',
+        title: "Couldn't save",
+        body:  firstErrorMessage(result),
+      })
+    }
+  }
+
+  const onChange = (next: string): void => {
+    setLocalValue(next)
+    if (confirmMsg) { setPendingConfirm(next); return }
+    void commit(next)
+  }
+
+  // Hide the placeholder option once a value is set when the user opted out.
+  const showPlaceholder = showPlaceholderOnce || localValue === ''
+  const placeholderText = nullable ? '—' : 'Select…'
+
+  return (
+    <div className="px-2 py-1" data-no-row-nav>
+      <Select
+        value={localValue}
+        onValueChange={(v) => onChange(typeof v === 'string' ? v : '')}
+        disabled={disabled}
+      >
+        <SelectTrigger className="h-8 w-full">
+          <SelectValue placeholder={placeholderText} />
+        </SelectTrigger>
+        <SelectContent>
+          {nullable && showPlaceholder && (
+            <SelectItem value="">{placeholderText}</SelectItem>
+          )}
+          {opts.map(o => (
+            <SelectItem key={o.value} value={o.value}>{o.label}</SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <ConfirmDialog
+        open={pendingConfirm !== null}
+        message={confirmMsg ?? ''}
+        onConfirm={() => {
+          const next = pendingConfirm!
+          setPendingConfirm(null)
+          void commit(next)
+        }}
+        onCancel={() => {
+          setLocalValue(committedRef.current)
+          setPendingConfirm(null)
+        }}
+      />
+    </div>
+  )
+}
+
+/** Discriminator for the SchemaRenderer cell switch — pick the right
+ * editable-cell renderer based on `columnType`. Returns `null` when the
+ * column is read-only so the caller falls through to `formatCell`. */
+export function pickEditableCell(columnType: string): React.FC<EditableCellProps> | null {
+  switch (columnType) {
+    case 'textInput': return CellTextInput
+    case 'toggle':    return CellToggle
+    case 'select':    return CellSelect
+    default:          return null
+  }
+}

package/src/react/fieldJsHandler.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { runJsHandler, __clearJsHandlerCacheForTests } from './fieldJsHandler.js'
+
+describe('runJsHandler — afterStateUpdatedJs runtime', () => {
+  beforeEach(() => {
+    __clearJsHandlerCacheForTests()
+  })
+
+  it('runs the body with $state bound to the changed value', () => {
+    const calls: unknown[] = []
+    const $set = (n: string, v: unknown) => calls.push([n, v])
+    runJsHandler({
+      body:      `$set('out', $state)`,
+      fieldName: 'title',
+      state:     'Hello',
+      $get:      () => undefined,
+      $set,
+    })
+    assert.deepEqual(calls, [['out', 'Hello']])
+  })
+
+  it('exposes $get for sibling reads', () => {
+    const values: Record<string, unknown> = { price: 10, qty: 3 }
+    const $get = (n: string) => values[n]
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown) => writes.push([n, v])
+    runJsHandler({
+      body:      `$set('total', Number($get('price')) * Number($state))`,
+      fieldName: 'qty',
+      state:     3,
+      $get,
+      $set,
+    })
+    assert.deepEqual(writes, [['total', 30]])
+  })
+
+  it('caches compiled handlers by string identity', () => {
+    const body = `$set('out', $state)`
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown) => writes.push([n, v])
+
+    // Run twice with the same body — should compile once.
+    runJsHandler({ body, fieldName: 'a', state: 1, $get: () => undefined, $set })
+    runJsHandler({ body, fieldName: 'a', state: 2, $get: () => undefined, $set })
+    assert.equal(writes.length, 2)
+  })
+
+  it('catches throws inside the body without re-raising', () => {
+    const errSpy = mock.method(console, 'error', () => {})
+    try {
+      runJsHandler({
+        body:      `throw new Error('nope')`,
+        fieldName: 'title',
+        state:     'x',
+        $get:      () => undefined,
+        $set:      () => {},
+      })
+      assert.equal(errSpy.mock.callCount(), 1)
+    } finally {
+      errSpy.mock.restore()
+    }
+  })
+
+  it('catches compile errors and skips eval on subsequent runs', () => {
+    const errSpy = mock.method(console, 'error', () => {})
+    try {
+      const $set = mock.fn()
+      // Same bad body run twice — should compile-error once, skip silently after.
+      runJsHandler({ body: `not valid {`, fieldName: 'x', state: 1, $get: () => undefined, $set })
+      runJsHandler({ body: `not valid {`, fieldName: 'x', state: 2, $get: () => undefined, $set })
+      assert.equal(errSpy.mock.callCount(), 1, 'compile-error logged once')
+      assert.equal($set.mock.callCount(), 0, 'never invoked $set')
+    } finally {
+      errSpy.mock.restore()
+    }
+  })
+
+  it('runs in strict mode (no implicit global writes)', () => {
+    const errSpy = mock.method(console, 'error', () => {})
+    try {
+      // In strict mode, assigning to an undeclared identifier throws.
+      runJsHandler({
+        body:      `accidentalGlobal = 1`,
+        fieldName: 'x',
+        state:     undefined,
+        $get:      () => undefined,
+        $set:      () => {},
+      })
+      assert.equal(errSpy.mock.callCount(), 1)
+    } finally {
+      errSpy.mock.restore()
+    }
+  })
+
+  it('does not expose `this` to the body', () => {
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown) => writes.push([n, v])
+    runJsHandler({
+      body:      `$set('thisType', typeof this)`,
+      fieldName: 'x',
+      state:     undefined,
+      $get:      () => undefined,
+      $set,
+    })
+    // Function-constructor + strict mode → `this` is undefined.
+    assert.deepEqual(writes, [['thisType', 'undefined']])
+  })
+
+  it('lets bodies use multi-line statements + helpers', () => {
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown) => writes.push([n, v])
+    runJsHandler({
+      body: `
+        const slug = String($state).toLowerCase().replace(/\\s+/g, '-')
+        $set('slug', slug)
+      `,
+      fieldName: 'title',
+      state:     'Hello World',
+      $get:      () => undefined,
+      $set,
+    })
+    assert.deepEqual(writes, [['slug', 'hello-world']])
+  })
+
+  it('empty / whitespace body compiles to a no-op', () => {
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown) => writes.push([n, v])
+    runJsHandler({
+      body:      `   `,
+      fieldName: 'x',
+      state:     undefined,
+      $get:      () => undefined,
+      $set,
+    })
+    assert.equal(writes.length, 0)
+  })
+})
+
+describe('runJsHandler — readNestedValue / writeNestedValue integration via $get/$set', () => {
+  beforeEach(() => {
+    __clearJsHandlerCacheForTests()
+  })
+
+  it('callers can route dotted-path access through $get/$set themselves', () => {
+    // The handler doesn't itself know about dotted paths — the caller
+    // (FormStateProvider.runFieldJs) wires that. This test just confirms
+    // the contract: $get/$set are pure user-supplied functions.
+    const values: Record<string, unknown> = { items: [{ qty: 2 }, { qty: 5 }] }
+    const $get = (n: string): unknown => {
+      if (n === 'items.0.qty') return (values.items as Array<{ qty: number }>)[0]!.qty
+      return undefined
+    }
+    const writes: unknown[] = []
+    const $set = (n: string, v: unknown): void => { writes.push([n, v]) }
+    runJsHandler({
+      body:      `$set('items.0.qty', Number($get('items.0.qty')) + Number($state))`,
+      fieldName: 'increment',
+      state:     1,
+      $get,
+      $set,
+    })
+    assert.deepEqual(writes, [['items.0.qty', 3]])
+  })
+})

package/src/react/fieldJsHandler.ts

@@ -0,0 +1,79 @@
+/**
+ * Tier-2 follow-up to Plan #5 — `Field.afterStateUpdatedJs(body)`.
+ *
+ * Compiles a user-provided JS body string into a callable function and
+ * caches the result by source identity. The body sees three names:
+ *
+ *   $state — the changed field's new value
+ *   $get   — read a sibling field's current value
+ *   $set   — write a sibling field's value (no cascade)
+ *
+ * Treated as admin-trusted code: written at schema-definition time,
+ * never derived from request input. Uses `new Function` (CSP
+ * `unsafe-eval` required); compile / run failures are caught and
+ * `console.error`'d so a bad handler never breaks the form.
+ */
+
+type GetFn = (name: string) => unknown
+type SetFn = (name: string, value: unknown) => void
+
+type HandlerFn = (state: unknown, $get: GetFn, $set: SetFn) => void
+
+type CompiledHandler =
+  | { ok: true;  fn: HandlerFn }
+  | { ok: false; error: string }
+
+const handlerCache = new Map<string, CompiledHandler>()
+
+function compileHandler(body: string, fieldName: string): CompiledHandler {
+  const cached = handlerCache.get(body)
+  if (cached) return cached
+
+  try {
+    // Prepend a sourceURL pragma so devtools attribute thrown frames to a
+    // stable, identifiable name instead of the anonymous "Function" frame.
+    const source = `'use strict';\n${body}\n//# sourceURL=pilotiq:afterStateUpdatedJs:${fieldName}`
+    const fn = new Function('$state', '$get', '$set', source) as HandlerFn
+    const entry: CompiledHandler = { ok: true, fn }
+    handlerCache.set(body, entry)
+    return entry
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err)
+    const entry: CompiledHandler = { ok: false, error }
+    handlerCache.set(body, entry)
+    console.error(`[pilotiq] afterStateUpdatedJs compile failed for "${fieldName}":`, err)
+    return entry
+  }
+}
+
+export interface RunJsHandlerArgs {
+  body:      string
+  fieldName: string
+  state:     unknown
+  $get:      GetFn
+  $set:      SetFn
+}
+
+/** Compile (cached) and run the JS body. Throws inside the body are
+ *  caught + logged; the form is left untouched on failure. Compile
+ *  failures are also cached so we don't re-attempt every change. */
+export function runJsHandler({ body, fieldName, state, $get, $set }: RunJsHandlerArgs): void {
+  const compiled = compileHandler(body, fieldName)
+  if (!compiled.ok) return
+
+  try {
+    // Invoke with `.call(undefined, …)` so the body's `this` is `undefined`
+    // (in strict mode). A bare `compiled.fn(…)` would bind `this` to the
+    // cache entry object — leaking the framework's internals into the
+    // user-supplied JS.
+    compiled.fn.call(undefined, state, $get, $set)
+  } catch (err) {
+    console.error(`[pilotiq] afterStateUpdatedJs run failed for "${fieldName}":`, err)
+  }
+}
+
+/** Test-only: clear the compile cache between runs. Production code
+ *  has no reason to call this. */
+export function __clearJsHandlerCacheForTests(): void {
+  handlerCache.clear()
+}