@pilotiq/pilotiq 0.1.0

package/src/react/fields/ToggleButtonsInput.tsx

@@ -0,0 +1,60 @@
+import React, { useState } from 'react'
+import { useFieldState } from '../FormStateContext.js'
+
+/**
+ * Single-choice field rendered as a horizontal row of pill-shaped
+ * buttons styled like a segmented control. Submits via a hidden input
+ * carrying the active value (form submission contract identical to
+ * `RadioInput`).
+ *
+ * Controlled when inside a `FormStateProvider`, uncontrolled otherwise.
+ */
+export function ToggleButtonsInput({
+  name, defaultValue, disabled, options,
+}: {
+  name:         string
+  defaultValue: string | undefined
+  disabled:     boolean
+  options:      Array<{ value: string; label: string; disabled?: boolean }>
+}): React.ReactElement {
+  const fs = useFieldState(name)
+  const [localValue, setLocalValue] = useState<string>(defaultValue ?? '')
+  const value = fs.controlled
+    ? (fs.value !== undefined && fs.value !== null ? String(fs.value) : '')
+    : localValue
+  const onPick = (next: string): void => {
+    if (disabled) return
+    if (fs.controlled) { fs.setValue(next); fs.triggerLive(next) }
+    else { setLocalValue(next); fs.triggerLive(next) }
+  }
+  return (
+    <div role="radiogroup" className="inline-flex flex-wrap rounded-md border border-input bg-background overflow-hidden">
+      <input type="hidden" name={name} value={value} />
+      {options.map((o, i) => {
+        const active = value === o.value
+        const optDisabled = disabled || Boolean(o.disabled)
+        return (
+          <button
+            key={o.value}
+            type="button"
+            role="radio"
+            aria-checked={active}
+            disabled={optDisabled}
+            data-state={active ? 'on' : 'off'}
+            onClick={() => { if (!optDisabled) onPick(o.value) }}
+            className={
+              'px-3 py-1.5 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring ' +
+              (i > 0 ? 'border-l border-input ' : '') +
+              (active
+                ? 'bg-primary text-primary-foreground hover:bg-primary/90 '
+                : 'bg-transparent hover:bg-accent hover:text-accent-foreground ') +
+              (optDisabled ? 'opacity-50 cursor-not-allowed ' : 'cursor-pointer ')
+            }
+          >
+            {o.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/react/fields/ToggleFieldInput.tsx

@@ -0,0 +1,35 @@
+import React, { useState } from 'react'
+import { useFieldState } from '../FormStateContext.js'
+import { Switch } from '../ui/switch.js'
+
+export function ToggleFieldInput({
+  name, defaultChecked, disabled,
+}: { name: string; defaultChecked: boolean; disabled: boolean }): React.ReactElement {
+  const fs = useFieldState(name)
+  const [localChecked, setLocalChecked] = useState(defaultChecked)
+  const checked = fs.controlled
+    ? (fs.value === true || fs.value === 'true' || fs.value === 1 || fs.value === '1')
+    : localChecked
+  // Base UI Switch's onCheckedChange callback does NOT dispatch a native
+  // bubbling change event, so RepeaterInput's container-level delegate
+  // can't pick up inner-row live() triggers. Call triggerLive explicitly
+  // in BOTH paths — the function is a no-op outside FormStateProvider
+  // and when the field has no `live` config, so it's safe to fire
+  // unconditionally. The value is passed as a `valueOverride` so
+  // dotted-path inner-Repeater fields pass through correctly.
+  const onChange = (next: boolean): void => {
+    if (fs.controlled) { fs.setValue(next); fs.triggerLive(next) }
+    else { setLocalChecked(next); fs.triggerLive(next) }
+  }
+  return (
+    <div className="flex items-center gap-2">
+      <input type="hidden" name={name} value={checked ? 'true' : 'false'} />
+      <Switch
+        id={name}
+        checked={checked}
+        onCheckedChange={onChange}
+        disabled={disabled}
+      />
+    </div>
+  )
+}

package/src/react/fields/rowChromeButton.tsx

@@ -0,0 +1,225 @@
+import React from 'react'
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  GripVerticalIcon,
+  Trash2Icon,
+} from 'lucide-react'
+import { getIcon, type IconType } from '../../icons/registry.js'
+import type {
+  RowButtonColor,
+  RowButtonKind,
+  RowButtonMeta,
+  RowButtonsMeta,
+} from '../../fields/RowButton.js'
+
+/**
+ * Foreground color slot → Tailwind class pair. Mirrors `Action.color()`
+ * semantics with a softer hover transition since these are
+ * icon-only buttons inside a dense row header.
+ */
+const COLOR_CLASS: Record<RowButtonColor, string> = {
+  foreground:  'text-muted-foreground hover:text-foreground',
+  destructive: 'text-muted-foreground hover:text-destructive',
+  primary:     'text-primary hover:text-primary/80',
+  success:     'text-emerald-600 hover:text-emerald-700',
+  warning:     'text-amber-600 hover:text-amber-700',
+  info:        'text-blue-600 hover:text-blue-700',
+  muted:       'text-muted-foreground/60 hover:text-muted-foreground',
+}
+
+interface ButtonDefaults {
+  Icon:    IconType
+  label:   string
+  tooltip: string
+  /**
+   * Default tailwind color class when no `color` override is set. Most
+   * row buttons share `text-muted-foreground hover:text-foreground`;
+   * the trash slot defaults to `…hover:text-destructive`. Defaults always
+   * lose to an explicit `RowButton.color()` call.
+   */
+  colorClass: string
+}
+
+interface ResolvedChrome {
+  Icon:       IconType
+  label:      string
+  tooltip:    string
+  colorClass: string
+}
+
+/**
+ * Merge a meta override on top of a slot's hardcoded defaults. The
+ * override may set any subset of `{ icon, label, color, tooltip }`; missing
+ * keys fall through. An overridden `icon` that doesn't resolve in the
+ * runtime registry falls back to the default Lucide glyph (matches
+ * `useIconFor`'s fail-soft posture).
+ */
+export function resolveRowChrome(
+  defaults: ButtonDefaults,
+  override: RowButtonMeta | undefined,
+): ResolvedChrome {
+  if (override === undefined) return defaults
+  const overrideIcon = override.icon !== undefined ? getIcon(override.icon) : undefined
+  return {
+    Icon:       overrideIcon ?? defaults.Icon,
+    label:      override.label   ?? defaults.label,
+    tooltip:    override.tooltip ?? defaults.tooltip,
+    colorClass: override.color !== undefined ? COLOR_CLASS[override.color] : defaults.colorClass,
+  }
+}
+
+/**
+ * Default chrome for each of the seven slots. Centralized here so both
+ * Repeater and Builder renderers stay in sync — when a new slot lands,
+ * the defaults live in one place. The Icon imports happen at the call
+ * site (renderers already import from lucide-react); we accept them as
+ * inputs to keep this file React-tree-shake friendly.
+ */
+export type SlotDefaults = Record<RowButtonKind, ButtonDefaults>
+
+/** Convenience for renderers — pass a slot kind + the merged buttons meta. */
+export function resolveRowChromeFor(
+  kind:      RowButtonKind,
+  defaults:  ButtonDefaults,
+  buttons:   RowButtonsMeta | undefined,
+): ResolvedChrome {
+  return resolveRowChrome(defaults, buttons?.[kind])
+}
+
+/**
+ * Standard icon-button shell used by every row chrome slot except the
+ * grip (which is a draggable `<span>`) and the Add button (which uses
+ * the shadcn `<Button>` for outline styling). Centralizes the
+ * `disabled` opacity, focus ring, and icon sizing so customizer overrides
+ * land consistently across Repeater + Builder.
+ */
+export function RowChromeIconButton({
+  defaults,
+  override,
+  disabled,
+  onClick,
+  extraClassName = '',
+  ariaExpanded,
+}: {
+  defaults:        ButtonDefaults
+  override:        RowButtonMeta | undefined
+  disabled:        boolean
+  onClick:         () => void
+  extraClassName?: string
+  ariaExpanded?:   boolean
+}): React.ReactElement {
+  const { Icon, label, tooltip, colorClass } = resolveRowChrome(defaults, override)
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+      title={tooltip}
+      {...(ariaExpanded !== undefined ? { 'aria-expanded': ariaExpanded } : {})}
+      className={`${colorClass} disabled:opacity-30 ${extraClassName}`.trim()}
+    >
+      <Icon className="size-4" />
+    </button>
+  )
+}
+
+/**
+ * Drag grip — a `<span>` not a `<button>`, since native HTML5 DnD only
+ * fires `dragstart` on parents with `draggable=true`. Honors the
+ * `reorderAction` customizer for icon / label / tooltip / color so users
+ * can swap the glyph or copy without owning the drag wiring.
+ */
+export function ReorderGrip({
+  disabled,
+  buttons,
+}: {
+  disabled: boolean
+  buttons:  RowButtonsMeta | undefined
+}): React.ReactElement {
+  const { Icon, label, tooltip, colorClass } = resolveRowChromeFor('reorder', DEFAULT_REORDER, buttons)
+  return (
+    <span
+      aria-label={label}
+      title={tooltip}
+      className={`${colorClass} ${disabled ? 'opacity-30' : 'cursor-grab active:cursor-grabbing'}`}
+    >
+      <Icon className="size-4" />
+    </span>
+  )
+}
+
+/**
+ * Collapse chevron — picks the open/closed glyph from state, then lets a
+ * `collapseAction` customizer override icon / label / tooltip / color.
+ * When a custom icon is set, both states use it (matches Filament; flat
+ * customizer surface — separate open/closed icon overrides aren't worth
+ * the extra setter).
+ */
+export function CollapseChevron({
+  isCollapsed,
+  disabled,
+  buttons,
+  onToggle,
+}: {
+  isCollapsed: boolean
+  disabled:    boolean
+  buttons:     RowButtonsMeta | undefined
+  onToggle:    () => void
+}): React.ReactElement {
+  const defaults = {
+    Icon:       isCollapsed ? ChevronRightIcon : ChevronDownIcon,
+    label:      isCollapsed ? 'Expand' : 'Collapse',
+    tooltip:    isCollapsed ? 'Expand' : 'Collapse',
+    colorClass: 'text-muted-foreground hover:text-foreground',
+  }
+  return (
+    <RowChromeIconButton
+      defaults={defaults}
+      override={buttons?.collapse}
+      disabled={disabled}
+      onClick={onToggle}
+      ariaExpanded={!isCollapsed}
+    />
+  )
+}
+
+// ─── Per-slot defaults ─────────────────────────────────────
+// Centralized so Repeater + Builder stay in lockstep. When a new slot
+// lands, defaults live in one place. `colorClass` defaults match the
+// historic hardcoded classes — preserves chrome for non-customized fields.
+
+export const DEFAULT_MOVE_UP: ButtonDefaults = {
+  Icon:       ArrowUpIcon,
+  label:      'Move up',
+  tooltip:    'Move up',
+  colorClass: 'text-muted-foreground hover:text-foreground',
+}
+export const DEFAULT_MOVE_DOWN: ButtonDefaults = {
+  Icon:       ArrowDownIcon,
+  label:      'Move down',
+  tooltip:    'Move down',
+  colorClass: 'text-muted-foreground hover:text-foreground',
+}
+export const DEFAULT_CLONE: ButtonDefaults = {
+  Icon:       CopyIcon,
+  label:      'Duplicate row',
+  tooltip:    'Duplicate row',
+  colorClass: 'text-muted-foreground hover:text-foreground',
+}
+export const DEFAULT_DELETE: ButtonDefaults = {
+  Icon:       Trash2Icon,
+  label:      'Remove row',
+  tooltip:    'Remove row',
+  colorClass: 'text-muted-foreground hover:text-destructive',
+}
+export const DEFAULT_REORDER: ButtonDefaults = {
+  Icon:       GripVerticalIcon,
+  label:      'Drag to reorder',
+  tooltip:    'Drag to reorder',
+  colorClass: 'text-muted-foreground',
+}

package/src/react/fields/syncRowGates.test.ts

@@ -0,0 +1,202 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { syncRowGates, type RowGateMeta } from './syncRowGates.js'
+
+interface TestRow extends RowGateMeta {
+  // Local-only fields the helper must preserve verbatim.
+  children?:    unknown[]
+  type?:        string
+  unknownType?: boolean
+}
+
+function row(id: string, extras: Partial<TestRow> = {}): TestRow {
+  return { id, ...extras }
+}
+
+describe('syncRowGates', () => {
+  it('returns the same reference when every row already matches', () => {
+    const prev = [row('a'), row('b')]
+    const out  = syncRowGates(prev, [{ id: 'a' }, { id: 'b' }])
+    assert.equal(out, prev)
+  })
+
+  it('stamps `hidden: true` when fresh meta hides a previously-visible row', () => {
+    const prev = [row('a'), row('b')]
+    const out  = syncRowGates(prev, [{ id: 'a' }, { id: 'b', hidden: true }])
+    assert.notEqual(out, prev)
+    assert.equal(out[0]?.hidden, undefined)
+    assert.equal(out[1]?.hidden, true)
+  })
+
+  it('clears `hidden` when fresh meta drops the flag', () => {
+    const prev: TestRow[] = [row('a', { hidden: true })]
+    const out = syncRowGates(prev, [{ id: 'a' }])
+    assert.notEqual(out, prev)
+    assert.equal(out[0]?.hidden, undefined)
+    assert.ok(!('hidden' in (out[0] ?? {})))
+  })
+
+  it('toggles each capability flag independently', () => {
+    const prev: TestRow[] = [row('a', { canDelete: false }), row('b', { canClone: false }), row('c', { canReorder: false })]
+    const out = syncRowGates(prev, [
+      { id: 'a' },                          // canDelete cleared
+      { id: 'b', canClone: false },         // canClone unchanged
+      { id: 'c', canDelete: false },        // canReorder cleared, canDelete set
+    ])
+    assert.notEqual(out, prev)
+    assert.equal(out[0]?.canDelete,  undefined)
+    assert.equal(out[1]?.canClone,   false)
+    assert.equal(out[1]?.canDelete,  undefined)
+    assert.equal(out[2]?.canReorder, undefined)
+    assert.equal(out[2]?.canDelete,  false)
+  })
+
+  it('preserves local-only fields (children / type / unknownType) — never echoed back from server', () => {
+    const children = [{ kind: 'placeholder' }]
+    const prev: TestRow[] = [
+      row('a', { children, type: 'heading', unknownType: false }),
+      row('b', { children, type: 'paragraph' }),
+    ]
+    const out = syncRowGates(prev, [{ id: 'a', hidden: true }, { id: 'b' }])
+    assert.equal(out[0]?.children,     children)
+    assert.equal(out[0]?.type,         'heading')
+    assert.equal(out[0]?.unknownType,  false)
+    assert.equal(out[0]?.hidden,       true)
+    assert.equal(out[1]?.children,     children)
+    assert.equal(out[1]?.type,         'paragraph')
+  })
+
+  it('leaves rows whose ids aren\'t in the fresh list untouched (client added a row mid-flight)', () => {
+    const prev = [row('a', { hidden: true }), row('b'), row('c-local-only')]
+    const out = syncRowGates(prev, [{ id: 'a' }, { id: 'b' }])
+    // a's hidden flag cleared because fresh has it, b unchanged, c left alone.
+    assert.equal(out[0]?.hidden, undefined)
+    assert.equal(out[1]?.hidden, undefined)
+    assert.equal(out[2]?.id,     'c-local-only')
+  })
+
+  it('preserves row order — never reorders or appends', () => {
+    const prev = [row('a'), row('b'), row('c')]
+    const out = syncRowGates(prev, [{ id: 'b' }, { id: 'a' }, { id: 'c', hidden: true }])
+    assert.equal(out[0]?.id, 'a')
+    assert.equal(out[1]?.id, 'b')
+    assert.equal(out[2]?.id, 'c')
+    assert.equal(out[2]?.hidden, true)
+  })
+
+  it('does not mutate input rows', () => {
+    const a: TestRow = row('a')
+    const b: TestRow = row('b', { hidden: true })
+    syncRowGates([a, b], [{ id: 'a', hidden: true }, { id: 'b' }])
+    assert.equal(a.hidden, undefined)
+    assert.equal(b.hidden, true)
+  })
+
+  it('returns the same reference when fresh is empty (no row meta to sync)', () => {
+    const prev = [row('a'), row('b')]
+    const out = syncRowGates(prev, [])
+    assert.equal(out, prev)
+  })
+
+  it('treats `hidden: false` and missing `hidden` as equivalent (no-op)', () => {
+    const prev = [row('a')]
+    const out = syncRowGates(prev, [{ id: 'a', hidden: false }])
+    assert.equal(out, prev)
+  })
+
+  it('combines all four flag transitions in a single sync', () => {
+    const prev: TestRow[] = [
+      row('a', { hidden: true, canDelete: false, canClone: false, canReorder: false }),
+    ]
+    const out = syncRowGates(prev, [{ id: 'a' }])
+    assert.notEqual(out, prev)
+    assert.equal(out[0]?.hidden,     undefined)
+    assert.equal(out[0]?.canDelete,  undefined)
+    assert.equal(out[0]?.canClone,   undefined)
+    assert.equal(out[0]?.canReorder, undefined)
+  })
+
+  describe('itemLabel sync', () => {
+    it('updates itemLabel when fresh meta carries a different string', () => {
+      const prev: TestRow[] = [row('a', { itemLabel: 'Apple' })]
+      const out = syncRowGates(prev, [{ id: 'a', itemLabel: 'Apricot' }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.itemLabel, 'Apricot')
+    })
+
+    it('clears itemLabel when fresh meta drops it (label fn returned non-string this resolve)', () => {
+      const prev: TestRow[] = [row('a', { itemLabel: 'Apple' })]
+      const out = syncRowGates(prev, [{ id: 'a' }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.itemLabel, undefined)
+      assert.ok(!('itemLabel' in (out[0] ?? {})))
+    })
+
+    it('stamps itemLabel when fresh meta adds it (was missing on prev)', () => {
+      const prev: TestRow[] = [row('a')]
+      const out = syncRowGates(prev, [{ id: 'a', itemLabel: 'Apple' }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.itemLabel, 'Apple')
+    })
+
+    it('keeps reference identity when itemLabel is byte-identical across resolves', () => {
+      const prev: TestRow[] = [row('a', { itemLabel: 'Apple' })]
+      const out = syncRowGates(prev, [{ id: 'a', itemLabel: 'Apple' }])
+      assert.equal(out, prev)
+    })
+  })
+
+  describe('extraActions sync', () => {
+    it('updates extraActions when the action list changes shape', () => {
+      const prevActions = [{ name: 'send', label: 'Send' }]
+      const freshActions = [{ name: 'send', label: 'Send' }, { name: 'archive', label: 'Archive' }]
+      const prev: TestRow[] = [row('a', { extraActions: prevActions })]
+      const out = syncRowGates(prev, [{ id: 'a', extraActions: freshActions }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.extraActions, freshActions)
+    })
+
+    it('updates extraActions when an action toggles disabled mid-form (visibility re-resolved)', () => {
+      const prevActions  = [{ name: 'send', label: 'Send', disabled: false }]
+      const freshActions = [{ name: 'send', label: 'Send', disabled: true }]
+      const prev: TestRow[] = [row('a', { extraActions: prevActions })]
+      const out = syncRowGates(prev, [{ id: 'a', extraActions: freshActions }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.extraActions, freshActions)
+    })
+
+    it('clears extraActions when fresh meta drops them (every action failed visibility)', () => {
+      const prev: TestRow[] = [row('a', { extraActions: [{ name: 'send' }] })]
+      const out = syncRowGates(prev, [{ id: 'a' }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.extraActions, undefined)
+      assert.ok(!('extraActions' in (out[0] ?? {})))
+    })
+
+    it('treats fresh empty array same as undefined (clears prev)', () => {
+      const prev: TestRow[] = [row('a', { extraActions: [{ name: 'send' }] })]
+      const out = syncRowGates(prev, [{ id: 'a', extraActions: [] }])
+      assert.notEqual(out, prev)
+      assert.equal(out[0]?.extraActions, undefined)
+    })
+
+    it('keeps reference identity when extraActions are byte-identical across resolves', () => {
+      const actions = [{ name: 'send', label: 'Send' }]
+      const prev: TestRow[] = [row('a', { extraActions: actions })]
+      const out = syncRowGates(prev, [{ id: 'a', extraActions: [{ name: 'send', label: 'Send' }] }])
+      assert.equal(out, prev)
+    })
+  })
+
+  it('combines flag + itemLabel + extraActions transitions in a single sync', () => {
+    const prev: TestRow[] = [
+      row('a', { hidden: true, itemLabel: 'Old', extraActions: [{ name: 'a' }] }),
+    ]
+    const out = syncRowGates(prev, [{ id: 'a', itemLabel: 'New', extraActions: [{ name: 'b' }] }])
+    assert.notEqual(out, prev)
+    assert.equal(out[0]?.hidden,       undefined)
+    assert.equal(out[0]?.itemLabel,    'New')
+    assert.deepEqual(out[0]?.extraActions, [{ name: 'b' }])
+  })
+})

package/src/react/fields/syncRowGates.ts

@@ -0,0 +1,66 @@
+// Match by `id`: rows in `fresh` come from server re-resolve of whatever
+// rows the client posted, so any row missing from `fresh` (a client-added
+// row that arrived after the live() request fired) is left untouched.
+// Returns `prev` reference unchanged when nothing differs — caller's
+// `setRows` then no-ops, avoiding a render cascade on idempotent responses.
+export interface RowGateMeta {
+  id:            string
+  hidden?:       boolean
+  canDelete?:    false
+  canClone?:     false
+  canReorder?:   false
+  itemLabel?:    string
+  extraActions?: readonly unknown[]
+}
+
+export function syncRowGates<R extends RowGateMeta>(
+  prev:  R[],
+  fresh: ReadonlyArray<RowGateMeta>,
+): R[] {
+  const byId = new Map<string, RowGateMeta>()
+  for (const r of fresh) byId.set(r.id, r)
+
+  let changed = false
+  const next = prev.map((row): R => {
+    const m = byId.get(row.id)
+    if (!m) return row
+
+    const targetHidden     = m.hidden === true
+    const targetCanDelete  = m.canDelete  === false ? (false as const) : undefined
+    const targetCanClone   = m.canClone   === false ? (false as const) : undefined
+    const targetCanReorder = m.canReorder === false ? (false as const) : undefined
+    const targetItemLabel  = typeof m.itemLabel === 'string' ? m.itemLabel : undefined
+    const targetExtra      = m.extraActions && m.extraActions.length > 0 ? m.extraActions : undefined
+
+    const extraDiffers =
+      (row.extraActions?.length ?? 0) !== (targetExtra?.length ?? 0)
+      || (targetExtra !== undefined && JSON.stringify(row.extraActions) !== JSON.stringify(targetExtra))
+
+    if (
+      Boolean(row.hidden)  === targetHidden &&
+      row.canDelete        === targetCanDelete &&
+      row.canClone         === targetCanClone &&
+      row.canReorder       === targetCanReorder &&
+      row.itemLabel        === targetItemLabel &&
+      !extraDiffers
+    ) return row
+
+    changed = true
+    const updated = { ...row }
+    if (targetHidden)     updated.hidden     = true
+    else delete updated.hidden
+    if (targetCanDelete  === false) updated.canDelete  = false
+    else delete updated.canDelete
+    if (targetCanClone   === false) updated.canClone   = false
+    else delete updated.canClone
+    if (targetCanReorder === false) updated.canReorder = false
+    else delete updated.canReorder
+    if (targetItemLabel !== undefined) updated.itemLabel = targetItemLabel
+    else delete updated.itemLabel
+    if (targetExtra !== undefined) updated.extraActions = targetExtra
+    else delete updated.extraActions
+    return updated
+  })
+
+  return changed ? next : prev
+}