@pilotiq/pilotiq 0.6.1 → 0.7.0

package/src/react/SchemaRenderer.tsx

@@ -68,6 +68,7 @@ import {
   CircleIcon, InboxIcon, GripVerticalIcon,
   ChevronDownIcon, CopyIcon, CheckIcon, XIcon,
   InfoIcon, TriangleAlertIcon, CircleCheckIcon, CircleAlertIcon,
+  Columns3Icon,
 } from 'lucide-react'
 import type { ComponentType } from 'react'
 import { useNavigate, type NavigateFn } from './navigate.js'
@@ -2058,16 +2059,60 @@ function SectionRenderer({ el, index }: { el: ElementMeta; index: number }) {
 
 // ─── Wizard (Plan #8) ───────────────────────────────────────
 
+/**
+ * Resolve the initial active step for `WizardRenderer`. Priority:
+ * 1. URL `?<queryKey>=N` (1-based — wizards expose human-friendly indexes
+ *    when `Wizard.persistStepInQueryString()` is enabled).
+ * 2. `localStorage[<storageKey>]` (0-based, set by the persist effect).
+ * 3. `startOnStep` configured on the Wizard.
+ *
+ * SSR-safe: returns `startOnStep` when `window` is undefined.
+ */
+function readInitialWizardStep(
+  total:       number,
+  startOnStep: number,
+  storageKey:  string | undefined,
+  queryKey:    string | undefined,
+): number {
+  if (typeof window === 'undefined') return startOnStep
+  if (queryKey) {
+    try {
+      const raw = new URL(window.location.href).searchParams.get(queryKey)
+      if (raw !== null && raw !== '') {
+        const n = Number(raw) - 1
+        if (Number.isFinite(n) && n >= 0 && n < total) return n
+      }
+    } catch { /* ignore */ }
+  }
+  if (storageKey) {
+    try {
+      const stored = window.localStorage.getItem(storageKey)
+      if (stored !== null) {
+        const n = Number(stored)
+        if (Number.isFinite(n) && n >= 0 && n < total) return n
+      }
+    } catch { /* ignore */ }
+  }
+  return startOnStep
+}
+
 /**
  * Multi-step form layout. Tracks active step in `useState`, optionally
- * persisted to localStorage. On Next click, POSTs `{ step, values }` to
- * the form's `wizardUrl` (stamped by the route handler when the form
- * has a Wizard descendant). 200 → advance; 422 → stamp inline errors;
- * absent `wizardUrl` → advance immediately (no validation).
+ * persisted to localStorage and/or the URL query string. On Next click,
+ * POSTs `{ step, values }` to the form's `wizardUrl` (stamped by the
+ * route handler when the form has a Wizard descendant). 200 → advance;
+ * 422 → stamp inline errors; absent `wizardUrl` → advance immediately
+ * (no validation).
  *
  * Inactive steps render hidden (display:none) rather than unmounted so
  * controlled inputs preserve their values across step transitions and
  * cross-step `$get` works on the resolved meta.
+ *
+ * Nav buttons honor `Wizard.submitAction() / nextAction() / previousAction()`
+ * — chrome (label / icon / color / size / outlined / iconOnly / tooltip /
+ * disabled rules) carries through to the rendered button while the click
+ * behavior stays hardwired (advance / recede / submit-form). Bare wizards
+ * keep the built-in defaults.
  */
 function WizardRenderer({ el, index }: {
   el: ElementMeta
@@ -2082,26 +2127,22 @@ function WizardRenderer({ el, index }: {
   const startOnStep = Math.max(0, Math.min(Math.max(0, steps.length - 1), Number(el['startOnStep'] ?? 0)))
   const persist     = el['persist'] !== false
   const storageKey  = persist && formId ? `pilotiq.wizard.${formId}.step` : undefined
+  const queryKey    = typeof el['persistStepInQueryString'] === 'string'
+    ? String(el['persistStepInQueryString'])
+    : undefined
 
-  const [active, setActive] = useState(startOnStep)
+  const submitActionMeta   = el['submitAction']   as ElementMeta | undefined
+  const nextActionMeta     = el['nextAction']     as ElementMeta | undefined
+  const previousActionMeta = el['previousAction'] as ElementMeta | undefined
+
+  // Initial-step resolution priority: URL (?<key>=N, 1-based) > localStorage >
+  // startOnStep. URL wins on first paint so deep links land on the right step
+  // before localStorage can override. Lazy initializer — resolution runs once.
+  const [active, setActive] = useState(() => readInitialWizardStep(steps.length, startOnStep, storageKey, queryKey))
   const [advancing, setAdvancing] = useState(false)
   const [advanceError, setAdvanceError] = useState<string | null>(null)
 
-  // Hydrate persisted step from localStorage after mount.
-  useEffect(() => {
-    if (!storageKey) return
-    if (typeof window === 'undefined') return
-    try {
-      const stored = window.localStorage.getItem(storageKey)
-      if (stored !== null) {
-        const n = Number(stored)
-        if (Number.isFinite(n) && n >= 0 && n < steps.length) setActive(n)
-      }
-    } catch { /* ignore */ }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [storageKey])
-
-  // Persist active step changes.
+  // Persist active step changes to localStorage (when enabled).
   useEffect(() => {
     if (!storageKey) return
     if (typeof window === 'undefined') return
@@ -2109,6 +2150,20 @@ function WizardRenderer({ el, index }: {
     catch { /* ignore */ }
   }, [storageKey, active])
 
+  // Mirror active step to the URL via replaceState — purely client-side state
+  // sync, no SPA re-fetch. 1-based externally; cleared when on the first step
+  // so bare URLs don't grow ?step=1 noise.
+  useEffect(() => {
+    if (!queryKey) return
+    if (typeof window === 'undefined') return
+    try {
+      const url = new URL(window.location.href)
+      if (active === 0) url.searchParams.delete(queryKey)
+      else              url.searchParams.set(queryKey, String(active + 1))
+      window.history.replaceState(window.history.state, '', url.toString())
+    } catch { /* ignore */ }
+  }, [queryKey, active])
+
   if (steps.length === 0) {
     return (
       <div key={index} className="rounded-lg border border-dashed p-8 text-center text-sm text-muted-foreground">
@@ -2223,34 +2278,106 @@ function WizardRenderer({ el, index }: {
       )}
 
       {/* Step nav. The Form's Save button (in Heading actions or page chrome)
-          stays as-is — only the final step's submit goes through. We expose
-          Back / Next here. The final-step "Save" is the form's submit; the
-          renderer flips Next → submit-button on the final step. */}
+          stays as-is by default — only the final step's submit goes through
+          the form. `Wizard.submitAction()` opts into a wizard-owned submit
+          button on the final step (use this when the wizard is the entire
+          form and there's no page chrome). `nextAction() / previousAction()`
+          customize the chrome of the built-in Back / Next buttons. */}
       <div className="flex items-center justify-between gap-2">
-        <button
-          type="button"
+        <WizardNavButton
+          actionMeta={previousActionMeta}
+          fallbackLabel="Back"
           disabled={isFirst || advancing}
           onClick={() => advance(active - 1)}
-          className="rounded-md border border-border px-3 py-1.5 text-sm font-medium text-foreground hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed"
-        >
-          Back
-        </button>
+        />
         {isLast
-          ? <span className="text-xs text-muted-foreground">Submit the form to finish.</span>
-          : <button
-              type="button"
+          ? (submitActionMeta
+              ? <WizardNavButton
+                  actionMeta={submitActionMeta}
+                  fallbackLabel="Submit"
+                  type="submit"
+                  disabled={advancing}
+                />
+              : <span className="text-xs text-muted-foreground">Submit the form to finish.</span>)
+          : <WizardNavButton
+              actionMeta={nextActionMeta}
+              fallbackLabel={advancing ? 'Validating…' : 'Next'}
               disabled={advancing}
               onClick={() => advance(active + 1)}
-              className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed"
-            >
-              {advancing ? 'Validating…' : 'Next'}
-            </button>
+            />
         }
       </div>
     </div>
   )
 }
 
+/**
+ * Renders one wizard nav slot (Back / Next / Submit). Falls back to plain
+ * built-in chrome (border button for Back, primary button for Next/Submit)
+ * when no `actionMeta` is supplied; otherwise reads the resolved Action's
+ * chrome (`label / icon / color / size / outlined / iconOnly / tooltip /
+ * disabled`) and applies it to a button whose click is hardwired by the
+ * surrounding wizard. `type="submit"` lets the Submit slot trigger the
+ * surrounding form's onSubmit dispatcher (no `onClick` needed).
+ *
+ * Hidden actions (`.visible(false)` resolved-away) drop the slot entirely
+ * — the resolver returns `undefined` for hidden Action elements, which
+ * arrives here as `actionMeta == null` so we fall through to the default
+ * chrome. Use `Wizard.skippable()` semantics to hide nav buttons when
+ * appropriate; for permanent removal subclass the wizard.
+ */
+function WizardNavButton({
+  actionMeta,
+  fallbackLabel,
+  type = 'button',
+  disabled,
+  onClick,
+}: {
+  actionMeta:     ElementMeta | undefined
+  fallbackLabel:  string
+  type?:          'button' | 'submit'
+  disabled?:      boolean
+  onClick?:       () => void
+}) {
+  // Bare default — keep historical chrome for back-compat (un-customized
+  // wizards look identical to before this change).
+  if (!actionMeta) {
+    const isPrimary = type === 'submit' || fallbackLabel !== 'Back'
+    return (
+      <button
+        type={type}
+        disabled={disabled}
+        onClick={onClick}
+        className={isPrimary
+          ? 'rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed'
+          : 'rounded-md border border-border px-3 py-1.5 text-sm font-medium text-foreground hover:bg-muted disabled:opacity-50 disabled:cursor-not-allowed'}
+      >
+        {fallbackLabel}
+      </button>
+    )
+  }
+
+  const ownDisabled = Boolean(actionMeta['disabled'])
+  const label       = String(actionMeta['label'] ?? fallbackLabel)
+  const tooltip     = actionMeta['tooltip'] ? String(actionMeta['tooltip']) : undefined
+  const iconOnly    = Boolean(actionMeta['iconOnly'])
+  const className   = actionButtonClass(actionMeta, {})
+  const node = (
+    <button
+      type={type}
+      disabled={disabled || ownDisabled}
+      onClick={onClick}
+      className={`${className} disabled:opacity-50 disabled:cursor-not-allowed`}
+      aria-label={iconOnly ? label : undefined}
+    >
+      {renderActionIcon(actionMeta)}
+      {!iconOnly && <span>{label}</span>}
+      {renderActionBadge(actionMeta)}
+    </button>
+  )
+  return <>{withTooltip(node, tooltip)}</>
+}
+
 // ─── Top-level dispatch ─────────────────────────────────────
 
 const TEXT_COLOR_CLASSES: Record<string, string> = {
@@ -3477,6 +3604,11 @@ interface TableUrlState {
    * in the dropdown to override `defaultGroup`); `undefined` omits the
    * key entirely so the configured default takes over. */
   group?:  string
+  /** Drilled-in group key for `?groupKey=`. `undefined` omits — the
+   * heading is banded (or no group at all); empty string explicitly
+   * clears (used by the chip's × so a stale URL value doesn't return
+   * via foreign-param round-trip). */
+  groupKey?: string
 }
 
 // Mirror of `prefixedKey` in `elements/dispatchTable.ts`. Kept inline so
@@ -3531,6 +3663,7 @@ function buildTableQuery(
       prefixK(prefix, 'page'),
       prefixK(prefix, 'perPage'),
       prefixK(prefix, 'group'),
+      prefixK(prefix, 'groupKey'),
       ...Object.keys(filterValues).map(n => prefixK(prefix, n)),
     ])
     for (const [k, v] of currentParams) {
@@ -3548,6 +3681,11 @@ function buildTableQuery(
   if (merged.sort)      params.set(prefixK(prefix, 'sort'), `${merged.sort.column}:${merged.sort.direction}`)
   if (merged.page && merged.page > 1) params.set(prefixK(prefix, 'page'), String(merged.page))
   if (merged.group !== undefined) params.set(prefixK(prefix, 'group'), merged.group)
+  // groupKey is sparse — only writes when the override sets a non-empty
+  // value. Drill-out (chip ×) passes `''` to clear; the foreign-param
+  // dedupe set above already filtered the stale value out, so an empty
+  // override produces a URL without the key.
+  if (merged.groupKey) params.set(prefixK(prefix, 'groupKey'), merged.groupKey)
   const qs = params.toString()
   // Always anchor to a real pathname — Vike's client-side router treats
   // a bare `?qs` href as a fresh URL with empty pathname, which routes
@@ -4882,6 +5020,78 @@ function RecordCellLink({
   )
 }
 
+/**
+ * "Drilled into <Label>: <Value>" chip above the table when a group
+ * heading has been clicked. The × clears `?<prefix>groupKey=`, returning
+ * the table to its banded view. Real `<a href>` with `useNavigate()`
+ * intercept on plain left-click so cmd-click / middle-click open a
+ * fresh tab (rare but valid for sharing the banded view URL).
+ */
+function ActiveGroupKeyChip({
+  label, value, displayValue, clearHref, navigate,
+}: {
+  label:        string
+  value:        string
+  displayValue: string
+  clearHref:    string
+  navigate:     NavigateFn
+}) {
+  const onClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    if (e.button !== 0) return
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+    e.preventDefault()
+    void navigate(clearHref)
+  }
+  return (
+    <div className="flex items-center gap-2 rounded-md border bg-muted/40 px-3 py-2 text-sm">
+      <span className="text-muted-foreground">Drilled into</span>
+      <span className="font-medium text-foreground">
+        {label ? `${label}: ` : ''}{displayValue || value}
+      </span>
+      <a
+        href={clearHref}
+        onClick={onClick}
+        aria-label="Clear drill-in"
+        className="ms-auto text-muted-foreground hover:text-foreground"
+      >
+        ×
+      </a>
+    </div>
+  )
+}
+
+/**
+ * Group-heading text wrapped in a real `<a href>` that SPA-navs into the
+ * drilled-in URL. Plain left-click intercepts for `useNavigate()`;
+ * cmd/ctrl/shift-click + middle-click fall through to the browser so
+ * "open in new tab" semantics work. Visually inherits the heading
+ * styling — the link adds underline-on-hover affordance without
+ * disturbing the surrounding text-transform / size.
+ */
+function GroupHeadingLink({
+  href, navigate, children,
+}: {
+  href:     string
+  navigate: NavigateFn
+  children: React.ReactNode
+}) {
+  const onClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    if (e.button !== 0) return
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+    e.preventDefault()
+    void navigate(href)
+  }
+  return (
+    <a
+      href={href}
+      onClick={onClick}
+      className="inline-flex items-center gap-1 text-inherit no-underline hover:underline focus:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded"
+    >
+      {children}
+    </a>
+  )
+}
+
 /**
  * List-page tab strip — Filament-style query shortcuts above the table
  * ("All / Drafts / Published / Archived"). Each trigger is a real `<a>`
@@ -5121,6 +5331,61 @@ function SortByPicker({
   )
 }
 
+/**
+ * Toolbar dropdown for `Column.toggleable()` columns. Lists every
+ * toggleable column with a checkbox; toggling writes through to a
+ * caller-supplied `onToggle` (the `TableRendererBody` owns the state
+ * + the localStorage round-trip). Mounted only when at least one
+ * column is toggleable.
+ */
+function ColumnsToggleDropdown({
+  columns, hidden, onToggle,
+}: {
+  columns: ElementMeta[]
+  hidden:  Set<string>
+  onToggle: (name: string, nextHidden: boolean) => void
+}) {
+  if (columns.length === 0) return null
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={(props) => (
+          <button
+            {...props}
+            type="button"
+            className="inline-flex h-9 items-center gap-1.5 rounded-md border border-input bg-background px-3 text-sm font-medium text-foreground hover:bg-accent"
+            aria-label="Show or hide columns"
+          >
+            <Columns3Icon className="h-4 w-4" aria-hidden="true" />
+            <span>Columns</span>
+          </button>
+        )}
+      />
+      <DropdownMenuContent align="end" className="min-w-[12rem]">
+        {columns.map((col, i) => {
+          const name  = String(col['name']  ?? '')
+          const label = String(col['label'] ?? name)
+          const isHidden = hidden.has(name)
+          return (
+            <DropdownMenuItem
+              key={i}
+              // Suppress menu-close so users can toggle multiple columns
+              // without re-opening the dropdown.
+              closeOnClick={false}
+              onClick={() => onToggle(name, !isHidden)}
+            >
+              <span className="inline-flex w-4 items-center justify-center">
+                {!isHidden && <CheckIcon className="h-4 w-4" aria-hidden="true" />}
+              </span>
+              <span>{label}</span>
+            </DropdownMenuItem>
+          )
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
 /**
  * Lookup tables for responsive grid column-counts in `contentLayout:
  * 'cards'`. Tailwind's JIT scanner needs **literal** class strings; we
@@ -5318,6 +5583,11 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
   const navigate = useNavigate()
   const children = el.children ?? []
   const columns  = children.filter(c => c.type === 'column')
+  // `Column.toggleable()` columns — sourced from the resolved meta. The
+  // user's per-table visibility map is owned + persisted below; the full
+  // `columns` list stays available for the toolbar dropdown so hidden
+  // columns can be re-shown without a roundtrip.
+  const toggleableColumns = columns.filter(c => c['toggleable'] !== undefined)
   // Actions and ActionGroups share placement — both show up in the
   // header/bulk/row toolbars depending on their `placement` field.
   const actionLike = children.filter(c => c.type === 'action' || c.type === 'actionGroup' || c.type === 'slotComponent')
@@ -5326,6 +5596,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
   const hasRecordClasses = Boolean(el['recordClasses'])
   const pollInterval     = typeof el['pollInterval'] === 'number' ? el['pollInterval'] as number : undefined
   const defaultGroup     = typeof el['defaultGroup'] === 'string' ? el['defaultGroup'] as string : undefined
+  const activeGroupKey   = typeof el['activeGroupKey'] === 'string' ? el['activeGroupKey'] as string : undefined
   const summaries        = el['summaries'] as Record<string, Array<{ kind: string; value: string; label?: string }>> | undefined
   const groupSummaries   = el['groupSummaries'] as
     Record<string, Record<string, Array<{ kind: string; value: string; label?: string }>>> | undefined
@@ -5335,6 +5606,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
     collapsible?: true
     collapsed?:   true
     date?:        true
+    scopable?:    true
   }> | undefined) ?? []
   // Active group's registered metadata (if any). Falls back to a synth
   // for the bare-column form so the heading row still has a label.
@@ -5348,6 +5620,11 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
       })
     : undefined
   const groupColumnLabel = activeGroupMeta?.label
+  // Heading text becomes a real `<a href>` when the active group opts in
+  // via `.scopable()`. Synthesized bare-column groups can't be scopable
+  // (no builder call ran).
+  const groupHeadingScopable = activeGroupMeta !== undefined
+    && (activeGroupMeta as { scopable?: true }).scopable === true
 
   // Auto-refresh: re-visit current URL on a timer so sort/filter/pagination
   // state survives. Pause while the document is hidden — background tabs
@@ -5393,6 +5670,59 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
   const perPage     = el['perPage'] as number | undefined
   const searchable  = Boolean(el['searchable'])
   const currentPath = (el['currentPath'] as string | undefined) ?? ''
+
+  // `Column.toggleable()` user-visibility map. Persisted per-table at
+  // `pilotiq.table.<currentPath>.columns.<name>` ('1' = hidden,
+  // '0' = visible). On first paint, fall back to `meta.toggleable.initiallyHidden`.
+  // SSR returns the meta default — the localStorage hydrate happens
+  // inside the effect so server + first client render match.
+  const columnsVisibilityKey = (name: string): string =>
+    `pilotiq.table.${currentPath}.columns.${name}`
+  const initialHidden = (): Set<string> => {
+    const out = new Set<string>()
+    for (const col of toggleableColumns) {
+      const cfg = col['toggleable'] as { initiallyHidden?: boolean } | undefined
+      if (cfg?.initiallyHidden) out.add(String(col['name']))
+    }
+    return out
+  }
+  const [hiddenColumns, setHiddenColumns] = useState<Set<string>>(initialHidden)
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    if (toggleableColumns.length === 0) return
+    const next = new Set<string>()
+    for (const col of toggleableColumns) {
+      const name = String(col['name'])
+      const cfg  = col['toggleable'] as { initiallyHidden?: boolean } | undefined
+      try {
+        const stored = window.localStorage.getItem(columnsVisibilityKey(name))
+        if (stored === '1') next.add(name)
+        else if (stored === '0') { /* visible */ }
+        else if (cfg?.initiallyHidden) next.add(name)
+      } catch {
+        if (cfg?.initiallyHidden) next.add(name)
+      }
+    }
+    setHiddenColumns(next)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentPath, toggleableColumns.length])
+  const toggleColumnHidden = (name: string, nextHidden: boolean): void => {
+    setHiddenColumns(prev => {
+      const next = new Set(prev)
+      if (nextHidden) next.add(name)
+      else            next.delete(name)
+      if (typeof window !== 'undefined') {
+        try { window.localStorage.setItem(columnsVisibilityKey(name), nextHidden ? '1' : '0') }
+        catch { /* private mode / quota — silent */ }
+      }
+      return next
+    })
+  }
+  // Filtered column list used by every render path (header, body cells,
+  // group + footer summaries, empty-state colSpan). Non-toggleable
+  // columns always survive.
+  const visibleColumns = columns.filter(c => !hiddenColumns.has(String(c['name'])))
+
   // Tier-3 — when the table opts into `Table.queryStringIdentifier(...)`,
   // every URL key (search / sort / page / perPage / group / filter names)
   // gets prefixed with `${id}_` so multiple tables on one page don't
@@ -5474,6 +5804,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
     ...(urlGroup     !== undefined ? { group: urlGroup }
         : defaultGroup !== undefined ? { group: defaultGroup }
         : {}),
+    ...(activeGroupKey !== undefined ? { groupKey: activeGroupKey } : {}),
   }
 
   // Snapshot active filter values for sort/pagination href construction.
@@ -5485,6 +5816,17 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
     if (typeof v === 'string' && v !== '') activeFilters[String(f['name'])] = v
   }
 
+  // Drill-in / drill-out URL builders for the group heading link and the
+  // active-key chip's clear button. Drill-in sets `?<prefix>groupKey=v`
+  // and resets `page`; drill-out clears it. Both round-trip foreign
+  // params (other tables' state) through `buildTableQuery`.
+  const buildGroupKeyHref = (value: string): string => buildTableQuery(
+    state, { groupKey: value, page: 1 }, currentPath, activeFilters, queryPrefix,
+  )
+  const drillOutHref = (): string => buildTableQuery(
+    state, { groupKey: '', page: 1 }, currentPath, activeFilters, queryPrefix,
+  )
+
   // Track which row ids are currently checked. Keyed by id (string), not
   // by index, so pagination and re-renders don't drop selection state.
   const [selected, setSelected] = useState<Set<string>>(() => new Set())
@@ -5634,7 +5976,8 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
   // Only modal + collapsible mount a toolbar widget; the always-visible
   // strip modes don't add anything to the header bar.
   const showFiltersInToolbar = hasFilters && (filtersInModal || filtersCollapsible)
-  const showHeaderBar    = searchable || headerActions.length > 0 || showFiltersInToolbar || hasGroupPicker || hasSortPicker
+  const hasColumnsToggle = toggleableColumns.length > 0
+  const showHeaderBar    = searchable || headerActions.length > 0 || showFiltersInToolbar || hasGroupPicker || hasSortPicker || hasColumnsToggle
   const hasBulkActions = bulkActions.length > 0
   const hasRowActions  = rowActions.length > 0
 
@@ -5657,7 +6000,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
     !searchActive                   &&
     currentPage === 1
   const reorderColumnVisible = reorderableColumn !== undefined
-  const totalCols = columns.length
+  const totalCols = visibleColumns.length
                   + (hasBulkActions      ? 1 : 0)
                   + (hasRowActions       ? 1 : 0)
                   + (reorderColumnVisible ? 1 : 0)
@@ -5686,7 +6029,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
       )}
       {showHeaderBar && (
         <div className="flex flex-col-reverse gap-2 sm:flex-row sm:items-center sm:justify-between">
-          {(searchable || showFiltersInToolbar || hasGroupPicker || hasSortPicker) ? (
+          {(searchable || showFiltersInToolbar || hasGroupPicker || hasSortPicker || hasColumnsToggle) ? (
             <div className="flex items-center gap-2">
               {searchable && (
                 <form method="get" action={currentPath || undefined} className="flex items-end gap-2">
@@ -5753,6 +6096,13 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                   }}
                 />
               )}
+              {toggleableColumns.length > 0 && (
+                <ColumnsToggleDropdown
+                  columns={toggleableColumns}
+                  hidden={hiddenColumns}
+                  onToggle={toggleColumnHidden}
+                />
+              )}
             </div>
           ) : <span />}
           {headerActions.length > 0 && (
@@ -5766,6 +6116,29 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
       {hasFilters && filtersAbove && filtersOpen && (
         <FilterStrip filters={filters} prefix={queryPrefix} />
       )}
+      {activeGroupKey !== undefined && (
+        <ActiveGroupKeyChip
+          label={groupColumnLabel ?? defaultGroup ?? ''}
+          value={activeGroupKey}
+          displayValue={(() => {
+            // Prefer a row-resolved `_groupTitle` (server stamped via
+            // `getTitleFromRecordUsing`) so the chip reads the same as
+            // a banded heading. Falls back to the raw bucket key when
+            // no row matched — empty drilled-in pages still show what
+            // they're drilled into.
+            for (const r of rows) {
+              const obj = r as Record<string, unknown>
+              if (String(obj['_groupValue'] ?? '') !== activeGroupKey) continue
+              const t = obj['_groupTitle']
+              if (typeof t === 'string' && t !== '') return t
+              break
+            }
+            return activeGroupKey
+          })()}
+          clearHref={drillOutHref()}
+          navigate={navigate}
+        />
+      )}
       {hasBulkActions && someChecked && (
         <div className="flex items-center justify-between gap-2 rounded-md border bg-muted/40 px-3 py-2 text-sm">
           <span className="text-muted-foreground">
@@ -5809,6 +6182,8 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
           toggleGroupCollapsed={toggleGroupCollapsed}
           cardsPerRow={cardsPerRow}
           navigate={navigate}
+          groupHeadingScopable={groupHeadingScopable}
+          buildGroupKeyHref={buildGroupKeyHref}
         />
       ) : (
       <div className="rounded-xl border bg-card overflow-hidden">
@@ -5827,7 +6202,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                   />
                 </TableHead>
               )}
-              {columns.map((col, i) => {
+              {visibleColumns.map((col, i) => {
                 const name     = String(col['name'] ?? '')
                 const label    = String(col['label'] ?? name)
                 const sortable = Boolean(col['sortable'])
@@ -5931,34 +6306,44 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                       colSpan={totalCols}
                       className="px-3 py-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground"
                     >
-                      {groupCollapsible ? (
-                        <button
-                          type="button"
-                          className="flex w-full items-center gap-2 text-left"
-                          onClick={() => toggleGroupCollapsed(groupValue!)}
-                          aria-expanded={!isInCollapsedGroup}
-                        >
-                          <ChevronDownIcon
-                            className={[
-                              'size-4 transition-transform',
-                              isInCollapsedGroup ? '-rotate-90' : '',
-                            ].filter(Boolean).join(' ')}
-                          />
+                      {(() => {
+                        const drillable = groupHeadingScopable
+                          && groupValue !== undefined
+                          && groupValue !== ''
+                        const headingText = (
                           <GroupHeaderText
                             label={groupColumnLabel}
                             value={groupValue}
                             title={groupTitle}
                             description={groupDescription}
                           />
-                        </button>
-                      ) : (
-                        <GroupHeaderText
-                          label={groupColumnLabel}
-                          value={groupValue}
-                          title={groupTitle}
-                          description={groupDescription}
-                        />
-                      )}
+                        )
+                        const headingNode = drillable
+                          ? <GroupHeadingLink href={buildGroupKeyHref(groupValue!)} navigate={navigate}>{headingText}</GroupHeadingLink>
+                          : headingText
+                        if (groupCollapsible) {
+                          return (
+                            <div className="flex w-full items-center gap-2">
+                              <button
+                                type="button"
+                                className="inline-flex items-center"
+                                onClick={() => toggleGroupCollapsed(groupValue!)}
+                                aria-expanded={!isInCollapsedGroup}
+                                aria-label={isInCollapsedGroup ? 'Expand group' : 'Collapse group'}
+                              >
+                                <ChevronDownIcon
+                                  className={[
+                                    'size-4 transition-transform',
+                                    isInCollapsedGroup ? '-rotate-90' : '',
+                                  ].filter(Boolean).join(' ')}
+                                />
+                              </button>
+                              {headingNode}
+                            </div>
+                          )
+                        }
+                        return headingNode
+                      })()}
                     </TableCell>
                   </TableRow>
                 )}
@@ -5999,7 +6384,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                       />
                     </TableCell>
                   )}
-                  {columns.map((col, ci) => {
+                  {visibleColumns.map((col, ci) => {
                     const name = String(col['name'] ?? '')
                     const value = recordObj[name]
                     const align = col['alignment'] === 'center' ? 'text-center'
@@ -6022,9 +6407,18 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                       : null
                     if (EditableComp && editUrl !== undefined) {
                       const cellDisabled = col['disabled'] === true || cellDisabledMap?.[name] === true
+                      const cellSelectOptionsMap = recordObj['_cellSelectOptions'] as
+                        Record<string, Array<{ value: string; label: string }>> | undefined
+                      const rowOptions = cellSelectOptionsMap?.[name]
                       return (
                         <TableCell key={ci} className={`text-sm text-foreground ${align} p-0`} style={widthStyle}>
-                          <EditableComp url={editUrl} col={col} value={value} disabled={cellDisabled} />
+                          <EditableComp
+                            url={editUrl}
+                            col={col}
+                            value={value}
+                            disabled={cellDisabled}
+                            {...(rowOptions ? { rowOptions } : {})}
+                          />
                         </TableCell>
                       )
                     }
@@ -6064,7 +6458,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
                     <TableRow key={`group-summary-${id}`} className="bg-muted/20 hover:bg-muted/20">
                       {reorderColumnVisible && <TableCell />}
                       {hasBulkActions      && <TableCell />}
-                      {columns.map((col, ci) => {
+                      {visibleColumns.map((col, ci) => {
                         const name  = String(col['name'] ?? '')
                         const align = col['alignment'] === 'center' ? 'text-center'
                                     : col['alignment'] === 'end'    ? 'text-right'
@@ -6094,7 +6488,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
               <TableRow>
                 {reorderColumnVisible && <TableCell />}
                 {hasBulkActions && <TableCell />}
-                {columns.map((col, ci) => {
+                {visibleColumns.map((col, ci) => {
                   const name  = String(col['name'] ?? '')
                   const align = col['alignment'] === 'center' ? 'text-center'
                               : col['alignment'] === 'end'    ? 'text-right'
@@ -6174,6 +6568,7 @@ function CardsLayoutBody({
   striped, activeEmpty, EmptyIcon, hasFilterOrSearch,
   defaultGroup, groupColumnLabel, groupCollapsible, collapsedGroups, toggleGroupCollapsed,
   cardsPerRow, navigate,
+  groupHeadingScopable, buildGroupKeyHref,
 }: {
   el:                ElementMeta
   columns:           ElementMeta[]
@@ -6197,6 +6592,10 @@ function CardsLayoutBody({
   toggleGroupCollapsed: (groupValue: string) => void
   cardsPerRow:       Record<string, number> | undefined
   navigate:          NavigateFn
+  // Drill-in affordances. Sparse: when `groupHeadingScopable` is false,
+  // the heading renders as before; `buildGroupKeyHref` is unused.
+  groupHeadingScopable?: boolean
+  buildGroupKeyHref?:    (value: string) => string
 }) {
   void el // keep prop for future telemetry; silences unused-prop lint
   void columns
@@ -6260,38 +6659,48 @@ function CardsLayoutBody({
           && collapsedGroups[section.groupValue] === true
         return (
           <div key={si} className="flex flex-col gap-3">
-            {section.groupValue !== undefined && (
-              groupCollapsible ? (
-                <button
-                  type="button"
-                  className="flex w-full items-center gap-2 text-left text-xs font-semibold uppercase tracking-wider text-muted-foreground"
-                  onClick={() => toggleGroupCollapsed(section.groupValue!)}
-                  aria-expanded={!collapsed}
-                >
-                  <ChevronDownIcon
-                    className={[
-                      'size-4 transition-transform',
-                      collapsed ? '-rotate-90' : '',
-                    ].filter(Boolean).join(' ')}
-                  />
-                  <GroupHeaderText
-                    label={groupColumnLabel}
-                    value={section.groupValue}
-                    title={section.title}
-                    description={section.description}
-                  />
-                </button>
-              ) : (
+            {section.groupValue !== undefined && (() => {
+              const drillable = groupHeadingScopable === true
+                && buildGroupKeyHref !== undefined
+                && section.groupValue !== ''
+              const headingText = (
+                <GroupHeaderText
+                  label={groupColumnLabel}
+                  value={section.groupValue}
+                  title={section.title}
+                  description={section.description}
+                />
+              )
+              const headingNode = drillable
+                ? <GroupHeadingLink href={buildGroupKeyHref!(section.groupValue!)} navigate={navigate}>{headingText}</GroupHeadingLink>
+                : headingText
+              if (groupCollapsible) {
+                return (
+                  <div className="flex w-full items-center gap-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                    <button
+                      type="button"
+                      className="inline-flex items-center"
+                      onClick={() => toggleGroupCollapsed(section.groupValue!)}
+                      aria-expanded={!collapsed}
+                      aria-label={collapsed ? 'Expand group' : 'Collapse group'}
+                    >
+                      <ChevronDownIcon
+                        className={[
+                          'size-4 transition-transform',
+                          collapsed ? '-rotate-90' : '',
+                        ].filter(Boolean).join(' ')}
+                      />
+                    </button>
+                    {headingNode}
+                  </div>
+                )
+              }
+              return (
                 <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-                  <GroupHeaderText
-                    label={groupColumnLabel}
-                    value={section.groupValue}
-                    title={section.title}
-                    description={section.description}
-                  />
+                  {headingNode}
                 </div>
               )
-            )}
+            })()}
             {!collapsed && (
               <div className={gridClass}>
                 {section.indices.map((ri) => {