@pilotiq/pilotiq 0.6.2 → 0.7.0

package/src/elements/Table.ts

@@ -32,6 +32,18 @@ export interface TableContext<R = unknown> {
    * filter `where` clauses in `modelTableRecords`. Set by the framework;
    * users configure it via `ListTab.modifyQuery(fn)`. */
   tabQuery?: (q: import('../orm/modelDefaults.js').ModelQuery) => import('../orm/modelDefaults.js').ModelQuery
+  /** Drill-in scope when the user clicked a group heading. Carries the
+   * resolved `TableGroup` instance + the bucket key (the same value
+   * `getKeyFromRecordUsing` would produce). Set by `loadTableRecords`
+   * after reconciling `?<prefix>groupKey=`. The model adapter calls
+   * `group.resolveScoper()(q, key)` after filters but before pagination;
+   * user-supplied `Table.records(fn)` handlers can branch on this for
+   * cross-table joins or non-default narrowing. */
+  groupScope?: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    group: import('./TableGroup.js').TableGroup<any>
+    key:   string
+  }
   /** Whatever `Pilotiq.user(req => …)` returned for the current request.
    * Forwarded into `Resource.query(ctx)` by `modelTableRecords` so user-
    * installed scopes (tenant filters, etc.) see the same opaque user
@@ -210,6 +222,15 @@ export interface TableMeta extends ElementMeta {
    * (`Table.defaultGroup('col')` only). */
   groups?: TableGroupMeta[]
 
+  /** The drilled-in group key for this request. When set, the renderer
+   * suppresses group banding (no heading rows, no per-group summaries),
+   * shows a "Drilled into <Label>: <Key>" chip above the table with an
+   * × to clear, and the records have already been narrowed to that
+   * bucket server-side via `TableGroup.scopeQueryByKey`. Sparse —
+   * omitted unless `?<prefix>groupKey=<value>` is present AND the named
+   * group exists AND is `scopable`. */
+  activeGroupKey?: string
+
   /** Per-column summary results — keyed by column name, each entry is the
    * computed `SummaryResult[]` for that column's `summarize([…])`. Filled
    * in by `loadTableRecords` after `records()` runs. Renderer emits a
@@ -319,10 +340,11 @@ export class Table<R = unknown, Q = unknown> extends Element {
   private _recordClasses?: RecordClassesHandler<R>
   private _pollInterval?: number
   private _defaultGroup?: string
-  // Variance-relaxed — Filament-style covariant `TableGroup<R>[]` ergonomics
+  // Variance-relaxed — covariant `TableGroup<R>[]` ergonomics
   // matter more than tight invariance against the table's `R` parameter.
   private _groups:        TableGroup<any>[] = []  // eslint-disable-line @typescript-eslint/no-explicit-any
   private _activeGroup?:  string
+  private _activeGroupKey?: string
   private _summaries?:    Record<string, SummaryResult[]>
   private _groupSummaries?: Record<string, Record<string, SummaryResult[]>>
   private _reorderableColumn?: string
@@ -682,6 +704,16 @@ export class Table<R = unknown, Q = unknown> extends Element {
     return this
   }
 
+  /** Render-time setter — the drilled-in group key for this request,
+   * after `?<prefix>groupKey=` was reconciled against a `scopable`
+   * group. Set by `loadTableRecords`. Empty string / undefined both
+   * clear, since drill-in needs an actual key to scope against. */
+  withActiveGroupKey(key: string | undefined): this {
+    if (key === undefined || key === '') delete this._activeGroupKey
+    else this._activeGroupKey = key
+    return this
+  }
+
   // ─── Getters ──────────────────────────────────────────
 
   getQuery(): TableQueryHandler<Q> | undefined { return this._query }
@@ -701,6 +733,7 @@ export class Table<R = unknown, Q = unknown> extends Element {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   getGroups(): TableGroup<any>[] { return this._groups }
   getActiveGroup(): string | undefined { return this._activeGroup }
+  getActiveGroupKey(): string | undefined { return this._activeGroupKey }
   /** Resolve the active column to a `TableGroup` instance. Returns the
    * matching registered group, or — when the active column is set but
    * not registered (bare-column form) — synthesizes a no-metadata group
@@ -782,6 +815,7 @@ export class Table<R = unknown, Q = unknown> extends Element {
         : {}),
       ...(this._summaries    !== undefined ? { summaries:    this._summaries    } : {}),
       ...(this._groupSummaries !== undefined ? { groupSummaries: this._groupSummaries } : {}),
+      ...(this._activeGroupKey !== undefined ? { activeGroupKey: this._activeGroupKey } : {}),
       ...(this._reorderableColumn !== undefined ? { reorderable: true as const, reorderableColumn: this._reorderableColumn } : {}),
       ...(this._reorderUrl   !== undefined ? { reorderUrl:  this._reorderUrl  } : {}),
       ...(this._deferred                   ? { deferred:    true as const   } : {}),

package/src/elements/TableGroup.test.ts

@@ -146,4 +146,115 @@ describe('TableGroup', () => {
       assert.equal(formatDateBucketTitle('blob'), 'blob')
     })
   })
+
+  describe('scopable + scopeQueryByKey + getKeyFromRecordUsing', () => {
+    it('default — not scopable, no meta emit', () => {
+      assert.equal(TableGroup.make('status').isScopable(), false)
+      assert.equal(TableGroup.make('status').toMeta().scopable, undefined)
+    })
+
+    it('scopable() flips the meta flag', () => {
+      assert.equal(TableGroup.make('s').scopable().toMeta().scopable, true)
+      assert.equal(TableGroup.make('s').scopable(false).toMeta().scopable, undefined)
+    })
+
+    it('scopeQueryByKey() auto-arms scopable', () => {
+      const g = TableGroup.make('status').scopeQueryByKey((q, _k) => q)
+      assert.equal(g.isScopable(), true)
+      assert.equal(g.toMeta().scopable, true)
+    })
+
+    it('getKeyFromRecordUsing() auto-arms scopable', () => {
+      const g = TableGroup.make<{ s: string }>('status')
+        .getKeyFromRecordUsing(r => r.s.toUpperCase())
+      assert.equal(g.isScopable(), true)
+    })
+
+    it('scopable(false) after auto-arm opts back out', () => {
+      const g = TableGroup.make('status').scopeQueryByKey((q, _k) => q).scopable(false)
+      assert.equal(g.isScopable(), false)
+      assert.equal(g.toMeta().scopable, undefined)
+    })
+  })
+
+  describe('resolveKey', () => {
+    it('default — raw column value as string', () => {
+      const g = TableGroup.make('status')
+      assert.equal(g.resolveKey({ status: 'draft' }), 'draft')
+      assert.equal(g.resolveKey({ status: 42 }),      '42')
+    })
+
+    it('empty / null collapses to ""', () => {
+      const g = TableGroup.make('status')
+      assert.equal(g.resolveKey({ status: null }),      '')
+      assert.equal(g.resolveKey({ status: undefined }), '')
+      assert.equal(g.resolveKey({ status: '' }),        '')
+    })
+
+    it('date() returns the YYYY-MM-DD bucket', () => {
+      const g = TableGroup.make('createdAt').date()
+      assert.equal(g.resolveKey({ createdAt: '2026-05-04T12:00:00.000Z' }), '2026-05-04')
+    })
+
+    it('user handler wins', () => {
+      const g = TableGroup.make<{ s: string }>('status')
+        .getKeyFromRecordUsing(r => `K_${r.s}`)
+      assert.equal(g.resolveKey({ s: 'a' }), 'K_a')
+    })
+
+    it('handler returning undefined collapses to ""', () => {
+      const g = TableGroup.make<{ s: string | undefined }>('status')
+        .getKeyFromRecordUsing(r => r.s)
+      assert.equal(g.resolveKey({ s: undefined }), '')
+    })
+
+    it('throwing handler fails soft to ""', () => {
+      const g = TableGroup.make('status')
+        .getKeyFromRecordUsing(() => { throw new Error('boom') })
+      assert.equal(g.resolveKey({ status: 'draft' }), '')
+    })
+  })
+
+  describe('resolveScoper defaults', () => {
+    it('plain group — exact match where(col, "=", key)', () => {
+      const calls: Array<[string, string, unknown]> = []
+      const q = { where: (col: string, op: string, val: unknown) => { calls.push([col, op, val]); return q } }
+      const g = TableGroup.make('status')
+      const scoper = g.resolveScoper<typeof q>()
+      scoper(q, 'draft')
+      assert.deepEqual(calls, [['status', '=', 'draft']])
+    })
+
+    it('date group — whole-day range', () => {
+      const calls: Array<[string, string, unknown]> = []
+      const q = { where: (col: string, op: string, val: unknown) => { calls.push([col, op, val]); return q } }
+      const g = TableGroup.make('createdAt').date()
+      const scoper = g.resolveScoper<typeof q>()
+      scoper(q, '2026-05-04')
+      assert.deepEqual(calls, [
+        ['createdAt', '>=', '2026-05-04 00:00:00'],
+        ['createdAt', '<=', '2026-05-04 23:59:59'],
+      ])
+    })
+
+    it('date group — empty key is a no-op (no where call)', () => {
+      let calls = 0
+      const q = { where: (..._args: unknown[]) => { calls++; return q } }
+      const g = TableGroup.make('createdAt').date()
+      const scoper = g.resolveScoper<typeof q>()
+      scoper(q, '')
+      assert.equal(calls, 0)
+    })
+
+    it('user scoper wins over date() default', () => {
+      const calls: string[] = []
+      const q = { where: (col: string, op: string, val: unknown) => { calls.push(`${col} ${op} ${val}`); return q } }
+      const g = TableGroup.make<unknown>('createdAt')
+        .date()
+        .scopeQueryByKey<typeof q>((qq, key) => qq.where('createdAt', '=', key))
+      const scoper = g.resolveScoper<typeof q>()
+      scoper(q, '2026-05-04')
+      assert.deepEqual(calls, ['createdAt = 2026-05-04'])
+    })
+  })
 })

package/src/elements/TableGroup.ts

@@ -18,6 +18,30 @@ export type TableGroupDescriptionHandler<R = unknown> = (
   record: R,
 ) => string | undefined
 
+/**
+ * Per-record key resolver. The returned string is what `scopeQueryByKey`
+ * receives at drill-in time. Default resolution = the raw column value
+ * cast to string (or `YYYY-MM-DD` when `.date()` is on). Override when the
+ * stable bucket key differs from what the column literally stores —
+ * e.g. when grouping by an enum object whose `.value` is the persisted
+ * column.
+ */
+export type TableGroupKeyHandler<R = unknown> = (
+  record: R,
+) => string | undefined
+
+/**
+ * Query scoper applied when the user clicks a group heading to drill into
+ * a single group. Receives the raw model query and the resolved group key
+ * (the same value `getKeyFromRecordUsing` produced). Should narrow the
+ * query to records belonging to that group. Default narrows by exact-match
+ * `where(column, '=', key)`; date groups install a whole-day range default.
+ */
+export type TableGroupQueryScoper<Q = unknown> = (
+  query: Q,
+  key:   string,
+) => Q
+
 /**
  * Comparator on resolved group keys. Receives the same string values that
  * the dispatcher stamps onto `_groupValue` (so for `date()` groups the keys
@@ -38,6 +62,12 @@ export interface TableGroupMeta {
    * already arrives as `YYYY-MM-DD` and `_groupTitle` carries the
    * formatted display text. */
   date?:         true
+  /** Heading is clickable — renderer wraps the title text in a real
+   * `<a href>` that sets `?<prefix>groupKey=<value>` to drill into a
+   * single group. Sparse: omitted unless the user opted in (directly
+   * via `.scopable(true)` or implicitly by calling `.scopeQueryByKey()`
+   * / `.getKeyFromRecordUsing()`). */
+  scopable?:     true
 }
 
 export class TableGroup<R = unknown> {
@@ -49,6 +79,9 @@ export class TableGroup<R = unknown> {
   private _descriptionFn?: TableGroupDescriptionHandler<R>
   private _date           = false
   private _keyComparator?: TableGroupKeyComparator
+  private _scopable       = false
+  private _scopeFn?:       TableGroupQueryScoper<unknown>
+  private _keyFn?:         TableGroupKeyHandler<R>
 
   private constructor(column: string) {
     this._column = column
@@ -111,6 +144,52 @@ export class TableGroup<R = unknown> {
     return this
   }
 
+  /**
+   * Make the group heading clickable — clicking it drills the table into
+   * just that group's rows, suppressing the banded layout. Opt-in: most
+   * tables stay in the banded view. Auto-armed whenever the user calls
+   * `.scopeQueryByKey(fn)` or `.getKeyFromRecordUsing(fn)` since neither
+   * is meaningful without the drill-in affordance; pass `.scopable(false)`
+   * explicitly to opt back out after the fact.
+   */
+  scopable(v: boolean = true): this {
+    this._scopable = v
+    return this
+  }
+
+  /**
+   * Narrow the query to a single group's rows when the user drills in.
+   * Receives the raw model query and the resolved group key (same value
+   * `getKeyFromRecordUsing` produces). Default narrows by exact-match
+   * `where(column, '=', key)`; date groups install a whole-day range
+   * default. Auto-arms `.scopable(true)` since a custom scoper without
+   * a clickable heading would never fire.
+   *
+   * ```ts
+   * TableGroup.make('status').scopeQueryByKey((q, key) =>
+   *   q.where('status', '=', key).where('archived', '=', false),
+   * )
+   * ```
+   */
+  scopeQueryByKey<Q = unknown>(fn: TableGroupQueryScoper<Q>): this {
+    this._scopeFn  = fn as TableGroupQueryScoper<unknown>
+    this._scopable = true
+    return this
+  }
+
+  /**
+   * Override the per-record key resolver. The returned string is the
+   * stable bucket key — it round-trips through `?<prefix>groupKey=` on
+   * drill-in and lands as the second arg of `scopeQueryByKey`. Default
+   * = the raw column value cast to string (or `YYYY-MM-DD` when
+   * `.date()` is on). Auto-arms `.scopable(true)`.
+   */
+  getKeyFromRecordUsing(fn: TableGroupKeyHandler<R>): this {
+    this._keyFn    = fn
+    this._scopable = true
+    return this
+  }
+
   // ─── Getters ──────────────────────────────────────────
 
   getColumn(): string { return this._column }
@@ -122,6 +201,61 @@ export class TableGroup<R = unknown> {
   getDescriptionHandler(): TableGroupDescriptionHandler<R> | undefined { return this._descriptionFn }
   isDate(): boolean { return this._date }
   getKeyComparator(): TableGroupKeyComparator | undefined { return this._keyComparator }
+  isScopable(): boolean { return this._scopable }
+  getKeyHandler(): TableGroupKeyHandler<R> | undefined { return this._keyFn }
+
+  /**
+   * Resolve the active scoper. Returns the user-supplied function when
+   * set; otherwise installs a default:
+   *
+   * - **Date groups** (`.date()`): whole-day range over the column —
+   *   `(q, key) => q.where(col, '>=', key + ' 00:00:00').where(col, '<=', key + ' 23:59:59')`.
+   *   Strings are picked over `Date` instances so the default composes
+   *   with ORMs that accept date-string literals; consumers wanting
+   *   sub-day buckets / timezone-aware ranges supply their own scoper.
+   * - **Plain groups**: exact-match — `(q, key) => q.where(col, '=', key)`.
+   *
+   * Note: the default uses `where(col, '>=', …)` 3-arg form. Adapter that
+   * only supports 2-arg `where(col, value)` need to detect the comparison
+   * argument shape — every ORM pilotiq ships against today supports the
+   * 3-arg form via `ModelQuery.where`.
+   */
+  resolveScoper<Q = unknown>(): TableGroupQueryScoper<Q> {
+    if (this._scopeFn) return this._scopeFn as TableGroupQueryScoper<Q>
+    const col = this._column
+    if (this._date) {
+      return ((q: { where: (...args: unknown[]) => unknown }, key: string) => {
+        // Empty key clears the bucket — fall back to a no-op so a stale
+        // groupKey doesn't accidentally filter the table to zero rows.
+        if (key === '') return q
+        return (q
+          .where(col, '>=', `${key} 00:00:00`) as typeof q)
+          .where(col, '<=', `${key} 23:59:59`)
+      }) as unknown as TableGroupQueryScoper<Q>
+    }
+    return ((q: { where: (...args: unknown[]) => unknown }, key: string) =>
+      q.where(col, '=', key)) as unknown as TableGroupQueryScoper<Q>
+  }
+
+  /**
+   * Derive the stable bucket key for a record. User-supplied handler
+   * wins; otherwise falls back to the column's raw value cast to string
+   * (or the `YYYY-MM-DD` bucket when `.date()` is on). Unparseable /
+   * null values resolve to `''` so they cluster under the empty bucket.
+   */
+  resolveKey(record: R): string {
+    if (this._keyFn) {
+      try {
+        const k = this._keyFn(record)
+        return k === undefined ? '' : String(k)
+      } catch {
+        return ''
+      }
+    }
+    const raw = (record as Record<string, unknown>)[this._column]
+    if (this._date) return bucketDateValue(raw)
+    return raw == null || raw === '' ? '' : String(raw)
+  }
 
   toMeta(): TableGroupMeta {
     return {
@@ -130,6 +264,7 @@ export class TableGroup<R = unknown> {
       ...(this._collapsible ? { collapsible: true as const } : {}),
       ...(this._collapsed   ? { collapsed:   true as const } : {}),
       ...(this._date        ? { date:        true as const } : {}),
+      ...(this._scopable    ? { scopable:    true as const } : {}),
     }
   }
 }

package/src/elements/dispatchForm.ts

@@ -1,7 +1,7 @@
 import { Element } from '../schema/Element.js'
 import { Field, type AfterStateUpdatedContext } from '../fields/Field.js'
 import { RepeaterField, isRepeaterField } from '../fields/RepeaterField.js'
-import type { RepeaterRelationshipConfig } from '../fields/RepeaterField.js'
+import type { RepeaterRelationshipConfig, RepeaterRowContext } from '../fields/RepeaterField.js'
 import { BuilderField, isBuilderField } from '../fields/BuilderField.js'
 import type { BuilderRelationshipConfig } from '../fields/BuilderField.js'
 import { Form, type FormContext } from './Form.js'
@@ -1527,6 +1527,21 @@ async function persistRelationshipRows(
     )
   }
 
+  // Per-row hooks — fire after each create / update / delete completes.
+  // No-op when the field hasn't registered the corresponding handler.
+  // Errors propagate; v1 isn't transactional so a throwing handler
+  // leaves earlier rows persisted.
+  const afterCreate = field.getAfterCreate()
+  const afterUpdate = field.getAfterUpdate()
+  const afterDelete = field.getAfterDelete()
+  const buildRowCtx = (index: number): RepeaterRowContext => ({
+    parent,
+    parentId: parentPk as string | number,
+    field:    field.name,
+    index,
+    mode:     attachment.kind,
+  })
+
   // Compute the morph stamp once — `computeMorphPayload` is pure.
   const morphStamp = attachment.kind === 'morphMany'
     ? computeMorphPayload(parent, attachment.morph)
@@ -1606,8 +1621,17 @@ async function persistRelationshipRows(
       // child-row update (user may have edited the child's own
       // columns through the Repeater). Skip the child write only
       // when the payload would be empty (M2M + pivot-only edits).
+      let updatedRecord: unknown = existingByPk.get(submittedId!)
       if (Object.keys(payload).length > 0) {
-        await model.update(submittedId!, payload)
+        const ret = await model.update(submittedId!, payload)
+        // ModelLike.update may return the updated record OR void; fall
+        // back to the existing snapshot merged with the payload so the
+        // hook always receives a usable record shape.
+        if (ret !== undefined && ret !== null) {
+          updatedRecord = ret
+        } else {
+          updatedRecord = { ...(existingByPk.get(submittedId!) ?? {}), ...payload }
+        }
       }
       if (hasPivotPayload) {
         if (typeof m2mAccessor!.updatePivot !== 'function') {
@@ -1620,13 +1644,15 @@ async function persistRelationshipRows(
         await m2mAccessor!.updatePivot(submittedId!, pivotPayload)
       }
       keptPks.add(submittedId!)
+      if (afterUpdate) await afterUpdate(updatedRecord, buildRowCtx(idx))
     } else {
+      let createdRecord: unknown = undefined
       if (attachment.kind === 'hasMany') {
         payload[attachment.foreignKey] = parentPk
-        await model.create(payload)
+        createdRecord = await model.create(payload)
       } else if (attachment.kind === 'morphMany') {
         Object.assign(payload, morphStamp)
-        await model.create(payload)
+        createdRecord = await model.create(payload)
       } else {
         // M2M: create the related record first, then attach via the
         // pivot accessor. The accessor handles polymorphic stamping
@@ -1647,12 +1673,13 @@ async function persistRelationshipRows(
         } else {
           await m2mAccessor!.attach!([newPk as string | number])
         }
+        createdRecord = created
       }
+      if (afterCreate) await afterCreate(createdRecord, buildRowCtx(idx))
     }
-    void field
   }
 
-  for (const [pkVal, _row] of existingByPk) {
+  for (const [pkVal, removedRow] of existingByPk) {
     if (keptPks.has(pkVal)) continue
     if (isM2M) {
       // Detach the pivot link only — the related record may still be
@@ -1662,7 +1689,7 @@ async function persistRelationshipRows(
     } else {
       await model.delete(pkVal)
     }
-    void _row
+    if (afterDelete) await afterDelete(removedRow, buildRowCtx(-1))
   }
 }