@pilotiq/pilotiq 0.6.1 → 0.7.0

package/src/elements/dispatchTable.test.ts

@@ -17,6 +17,7 @@ import {
 import {
   parseTableQuery,
   parseActiveGroup,
+  parseActiveGroupKey,
   findTables,
   loadTableRecords,
 } from './dispatchTable.js'
@@ -790,6 +791,190 @@ describe('loadTableRecords', () => {
     })
   })
 
+  describe('TableGroup.scopeQueryByKey — drill-in', () => {
+    it('parseActiveGroupKey: returns the key when group is scopable', () => {
+      const t = Table.make()
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+      assert.equal(parseActiveGroupKey({ groupKey: 'draft' }, t, 'status'), 'draft')
+    })
+
+    it('parseActiveGroupKey: drops silently when group is not scopable', () => {
+      const t = Table.make()
+        .groups([TableGroup.make('status')])  // not scopable
+        .defaultGroup('status')
+      assert.equal(parseActiveGroupKey({ groupKey: 'draft' }, t, 'status'), undefined)
+    })
+
+    it('parseActiveGroupKey: drops silently when no active group', () => {
+      const t = Table.make()
+      assert.equal(parseActiveGroupKey({ groupKey: 'draft' }, t, undefined), undefined)
+    })
+
+    it('parseActiveGroupKey: drops silently when group not registered (bare-column form)', () => {
+      const t = Table.make().defaultGroup('status')  // bare; no scopable() call
+      assert.equal(parseActiveGroupKey({ groupKey: 'draft' }, t, 'status'), undefined)
+    })
+
+    it('parseActiveGroupKey: empty string explicitly clears', () => {
+      const t = Table.make()
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+      assert.equal(parseActiveGroupKey({ groupKey: '' }, t, 'status'), undefined)
+    })
+
+    it('suppresses _groupValue banding when drilled in', async () => {
+      const t = Table.make<{ id: string; status: string }>()
+        .columns([Column.make('status')])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async () => [
+          { id: '1', status: 'draft' },
+          { id: '2', status: 'draft' },
+        ])
+
+      await loadTableRecords([t], { groupKey: 'draft' })
+      const meta = (await resolveSchema([t]))[0]!
+      const rows = meta['rows'] as Array<Record<string, unknown>>
+      // No banding when drilled in — the rows are already filtered to
+      // the bucket, so heading rows would be redundant.
+      assert.equal(rows[0]!['_groupValue'], undefined)
+      assert.equal(rows[1]!['_groupValue'], undefined)
+      assert.equal(meta['activeGroupKey'], 'draft')
+      assert.equal(meta['defaultGroup'], 'status')  // active group preserved
+    })
+
+    it('resets the visible page to 1 on drill-in', async () => {
+      const t = Table.make<{ id: string }>()
+        .columns([Column.make('id')])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async () => [{ id: '1' }])
+
+      await loadTableRecords([t], { groupKey: 'draft', page: '5' })
+      const meta = (await resolveSchema([t]))[0]!
+      assert.equal(meta['currentPage'], 1)
+    })
+
+    it('threads ctx.groupScope into the records handler', async () => {
+      let received: unknown
+      const t = Table.make<{ id: string }>()
+        .columns([Column.make('id')])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async (ctx) => {
+          received = (ctx as { groupScope?: unknown }).groupScope
+          return []
+        })
+
+      await loadTableRecords([t], { groupKey: 'draft' })
+      const scope = received as { group?: { getColumn: () => string }; key?: string }
+      assert.equal(scope?.group?.getColumn(), 'status')
+      assert.equal(scope?.key, 'draft')
+    })
+
+    it('omits ctx.groupScope when not drilled in', async () => {
+      let received: unknown = 'unset'
+      const t = Table.make<{ id: string }>()
+        .columns([Column.make('id')])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async (ctx) => {
+          received = (ctx as { groupScope?: unknown }).groupScope
+          return [{ id: '1' }]
+        })
+
+      await loadTableRecords([t], {})
+      assert.equal(received, undefined)
+    })
+
+    it('suppresses groupSummaries when drilled in', async () => {
+      const t = Table.make<{ id: string; status: string; price: number }>()
+        .columns([
+          Column.make('status'),
+          Column.make('price').summarize([Sum.make()]),
+        ])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async () => [
+          { id: '1', status: 'draft', price: 100 },
+          { id: '2', status: 'draft', price: 200 },
+        ])
+
+      await loadTableRecords([t], { groupKey: 'draft' })
+      const meta = (await resolveSchema([t]))[0]!
+      // Global summary still computed across the bucket — it's the only
+      // total that makes sense once you've drilled in.
+      assert.ok(meta['summaries'] !== undefined)
+      // Per-group summary block is gone because banding is gone.
+      assert.equal(meta['groupSummaries'], undefined)
+    })
+
+    it('queryStringIdentifier — drilled key reads from <id>_groupKey', async () => {
+      const t = Table.make<{ id: string; status: string }>()
+        .queryStringIdentifier('orders')
+        .columns([Column.make('status')])
+        .groups([TableGroup.make('status').scopable()])
+        .defaultGroup('status')
+        .records(async () => [{ id: '1', status: 'draft' }])
+
+      // Bare `?groupKey=` shouldn't drill in when the table is prefixed.
+      await loadTableRecords([t], { groupKey: 'wat' })
+      let meta = (await resolveSchema([t]))[0]!
+      assert.equal(meta['activeGroupKey'], undefined)
+
+      await loadTableRecords([t], { orders_group: 'status', orders_groupKey: 'draft' })
+      meta = (await resolveSchema([t]))[0]!
+      assert.equal(meta['activeGroupKey'], 'draft')
+    })
+
+    it('date() group — drill-in threads bucket key through scope', async () => {
+      let calls: Array<[string, string, unknown]> = []
+      const t = Table.make<{ id: string; createdAt: string }>()
+        .columns([Column.make('createdAt')])
+        .groups([TableGroup.make('createdAt').date().scopable()])
+        .defaultGroup('createdAt')
+        .records(async (ctx) => {
+          const scope = (ctx as { groupScope?: { group: { resolveScoper: <Q>() => (q: Q, k: string) => Q }; key: string } }).groupScope
+          if (scope) {
+            const q = { where: (col: string, op: string, val: unknown) => { calls.push([col, op, val]); return q } }
+            scope.group.resolveScoper<typeof q>()(q, scope.key)
+          }
+          return [] as { id: string; createdAt: string }[]
+        })
+
+      calls = []
+      await loadTableRecords([t], { groupKey: '2026-05-04' })
+      assert.deepEqual(calls, [
+        ['createdAt', '>=', '2026-05-04 00:00:00'],
+        ['createdAt', '<=', '2026-05-04 23:59:59'],
+      ])
+    })
+
+    it('user-supplied scopeQueryByKey wins over default', async () => {
+      let captured = ''
+      const t = Table.make<{ id: string; status: string }>()
+        .columns([Column.make('status')])
+        .groups([
+          TableGroup.make('status').scopeQueryByKey<{ where: (...a: unknown[]) => unknown }>(
+            (q, key) => { captured = `custom:${key}`; return q },
+          ),
+        ])
+        .defaultGroup('status')
+        .records(async (ctx) => {
+          const scope = (ctx as { groupScope?: { group: { resolveScoper: <Q>() => (q: Q, k: string) => Q }; key: string } }).groupScope
+          if (scope) {
+            const q = { where: () => q }
+            scope.group.resolveScoper<typeof q>()(q, scope.key)
+          }
+          return []
+        })
+
+      await loadTableRecords([t], { groupKey: 'draft' })
+      assert.equal(captured, 'custom:draft')
+    })
+  })
+
   describe('Table.recordClasses', () => {
     it('stamps _recordClasses on each row when a handler is set', async () => {
       const t = Table.make<{ id: string; status: string }>()
@@ -1061,6 +1246,88 @@ describe('loadTableRecords', () => {
       const rows = t.getRows() as Array<Record<string, unknown>>
       assert.equal(rows[0]!['_cellEditable'], undefined)
     })
+
+    describe('SelectColumn.options(record => …) per-row resolver', () => {
+      it('stamps _cellSelectOptions per row when canEdit allows', async () => {
+        const t = Table.make<{ id: string; teamId: string }>()
+          .columns([
+            Column.make('id'),
+            SelectColumn.make('assigneeId').options((row) => {
+              const r = row as { teamId: string }
+              return r.teamId === 'red'
+                ? { alice: 'Alice', bob: 'Bob' }
+                : { carol: 'Carol' }
+            }),
+          ])
+          .records(async () => ({
+            rows:  [{ id: '1', teamId: 'red' }, { id: '2', teamId: 'blue' }],
+            total: 2,
+          }))
+
+        await loadTableRecords([t], {}, undefined, undefined, { canEdit: () => true })
+        const rows = t.getRows() as Array<Record<string, unknown>>
+        assert.deepEqual(rows[0]!['_cellSelectOptions'], {
+          assigneeId: [
+            { value: 'alice', label: 'Alice' },
+            { value: 'bob',   label: 'Bob' },
+          ],
+        })
+        assert.deepEqual(rows[1]!['_cellSelectOptions'], {
+          assigneeId: [{ value: 'carol', label: 'Carol' }],
+        })
+      })
+
+      it('does not stamp when canEdit denies the row (cell stays read-only)', async () => {
+        const t = Table.make<{ id: string }>()
+          .columns([
+            Column.make('id'),
+            SelectColumn.make('assigneeId').options(() => ({ a: 'A' })),
+          ])
+          .records(async () => ({ rows: [{ id: '1' }], total: 1 }))
+
+        await loadTableRecords([t], {}, undefined, undefined, { canEdit: () => false })
+        const rows = t.getRows() as Array<Record<string, unknown>>
+        assert.equal(rows[0]!['_cellEditable'],       undefined)
+        assert.equal(rows[0]!['_cellSelectOptions'],  undefined)
+      })
+
+      it('throwing resolver leaves the slot unset on that row only — others still stamp', async () => {
+        const t = Table.make<{ id: string; bad: boolean }>()
+          .columns([
+            Column.make('id'),
+            SelectColumn.make('assigneeId').options((row) => {
+              const r = row as { bad: boolean }
+              if (r.bad) throw new Error('lookup failed')
+              return { x: 'X' }
+            }),
+          ])
+          .records(async () => ({
+            rows:  [{ id: '1', bad: true }, { id: '2', bad: false }],
+            total: 2,
+          }))
+
+        await loadTableRecords([t], {}, undefined, undefined, { canEdit: () => true })
+        const rows = t.getRows() as Array<Record<string, unknown>>
+        assert.equal(rows[0]!['_cellSelectOptions'], undefined)
+        assert.deepEqual(rows[1]!['_cellSelectOptions'], {
+          assigneeId: [{ value: 'x', label: 'X' }],
+        })
+      })
+
+      it('skips _cellSelectOptions entirely when no resolver is configured', async () => {
+        const t = Table.make<{ id: string }>()
+          .columns([
+            Column.make('id'),
+            SelectColumn.make('assigneeId').options({ a: 'A' }),
+          ])
+          .records(async () => ({ rows: [{ id: '1' }], total: 1 }))
+
+        await loadTableRecords([t], {}, undefined, undefined, { canEdit: () => true })
+        const rows = t.getRows() as Array<Record<string, unknown>>
+        assert.equal(rows[0]!['_cellEditable']?.['assigneeId' as never], true)
+        assert.equal(rows[0]!['_cellSelectOptions'], undefined)
+      })
+    })
   })
 })
 

package/src/elements/dispatchTable.ts

@@ -3,7 +3,8 @@ import { Table, type TableContext, type SortDirection } from './Table.js'
 import { TableGroup, bucketDateValue, formatDateBucketTitle } from './TableGroup.js'
 import type { Filter } from '../filters/Filter.js'
 import { Action } from '../actions/Action.js'
-import { Column } from '../Column.js'
+import { Column, type ColumnSelectOption } from '../Column.js'
+import { SelectColumn, normalizeSelectOptions, type SelectColumnOptionsResolver } from '../columns/SelectColumn.js'
 import { ListTab } from '../Tab.js'
 import { isRepeaterField } from '../fields/RepeaterField.js'
 import { isBuilderField } from '../fields/BuilderField.js'
@@ -23,7 +24,7 @@ export interface QueryParams {
   [key: string]: unknown
 }
 
-const RESERVED_QUERY_KEYS = new Set(['search', 'sort', 'page', 'perPage', 'group'])
+const RESERVED_QUERY_KEYS = new Set(['search', 'sort', 'page', 'perPage', 'group', 'groupKey'])
 
 export function prefixedKey(prefix: string | undefined, key: string): string {
   return prefix === undefined || prefix === '' ? key : `${prefix}_${key}`
@@ -147,6 +148,35 @@ export function parseActiveGroup(
   return table.getDefaultGroup()
 }
 
+/**
+ * Read the drilled-in group key from the URL. Returns the key string when
+ * the URL carries a value AND the active group exists AND is `scopable`;
+ * `undefined` otherwise (stale bookmark, group dropped, or never set).
+ *
+ * The active column resolution runs first so the drill-in state can be
+ * silently dropped without affecting the parent group's reconciliation —
+ * a stale `groupKey` from a renamed-column or non-scopable group falls
+ * through to "no drill-in", which is the same as the user not having
+ * clicked a heading.
+ */
+export function parseActiveGroupKey(
+  query:  QueryParams,
+  table:  Table,
+  activeColumn: string | undefined,
+  prefix?: string,
+): string | undefined {
+  if (activeColumn === undefined) return undefined
+  const raw = query[prefixedKey(prefix, 'groupKey')]
+  if (typeof raw !== 'string') return undefined
+  if (raw === '') return undefined  // explicit clear
+  const group = table.getGroups().find(g => g.getColumn() === activeColumn)
+  // Bare-column groups (synthesized from defaultGroup with no entry in
+  // `groups([…])`) can't be scopable — `.scopeQueryByKey()` is a builder
+  // call. Drop the drill-in silently.
+  if (!group || !group.isScopable()) return undefined
+  return raw
+}
+
 /** Walk an Element tree and return every `Table` instance in document order. */
 export function findTables(elements: ReadonlyArray<Element>): Table[] {
   const tables: Table[] = []
@@ -224,6 +254,20 @@ export async function loadTableRecords(
     // `ctx.tabQuery` to splice the predicate into its ORM query chain.
     const activeTab = findActiveTab(elements)
 
+    // Reconcile group + drill-in BEFORE building ctx so `groupScope` can
+    // be threaded into the records handler (model adapter splices the
+    // scoper after filters). A live drill-in also resets the page to 1
+    // server-side — clicking a heading should reliably land on the first
+    // page of the bucket regardless of where the user was paginated to.
+    const activeGroupCol  = parseActiveGroup(query, table, prefix)
+    // Stamp the reconciled column onto the table early so
+    // `getActiveGroupInstance()` can resolve to a registered group (or
+    // synthesize a bare-column instance) consistently across the file.
+    table.withActiveGroup(activeGroupCol ?? '')
+    const activeGroup     = table.getActiveGroupInstance()
+    const drilledKey      = parseActiveGroupKey(query, table, activeGroupCol, prefix)
+    const effectivePageWithDrill = drilledKey !== undefined ? 1 : effectivePage
+
     const ctx: TableContext = {
       ...(search !== undefined           ? { search }                       : {}),
       ...(effectiveSort !== undefined    ? { sort: effectiveSort }          : {}),
@@ -232,7 +276,10 @@ export async function loadTableRecords(
       ...(activeTab            ? { tab: activeTab.name }                    : {}),
       ...(activeTab?.getQuery() ? { tabQuery: activeTab.getQuery()! }       : {}),
       ...(user != null         ? { user }                                  : {}),
-      page: effectivePage,
+      ...(drilledKey !== undefined && activeGroup !== undefined
+        ? { groupScope: { group: activeGroup, key: drilledKey } }
+        : {}),
+      page: effectivePageWithDrill,
     }
 
     // Apply the tab's TableContext customizer last (escape hatch — wins
@@ -305,25 +352,31 @@ export async function loadTableRecords(
         .filter((c): c is Column => c instanceof Column && c.isEditable())
       const canEditEditableColumns = editableColumns.length > 0 && hooks?.canEdit !== undefined
 
+      // SelectColumns with a per-row options resolver — pre-filtered so the
+      // row loop doesn't re-walk `editableColumns` to find them. Stamps
+      // `row._cellSelectOptions[col.name]` with the resolved option list.
+      const selectColumnsWithResolver: Array<{ name: string; resolve: SelectColumnOptionsResolver }> =
+        editableColumns
+          .filter((c): c is SelectColumn => c instanceof SelectColumn)
+          .map(c => ({ name: c.name, resolve: c.getOptionsResolver() }))
+          .filter((c): c is { name: string; resolve: SelectColumnOptionsResolver } => c.resolve !== undefined)
+
       const recordUrlFn     = table.getRecordUrl()
       const recordClassesFn = table.getRecordClasses()
       const cardSchemaFn    = table.isCardsLayout() ? table.getCardSchema() : undefined
-      // Reconcile `?group=` against the configured groups + defaultGroup.
-      // Stamp the resolved column back onto the table so `toMeta()`
-      // emits it as the meta's `defaultGroup` (the renderer reads from
-      // there). Empty-string "explicit clear" is distinct from `undefined`
-      // ("never reconciled") so we can tell tests-skipping-loadTableRecords
-      // apart from URL-cleared.
-      const activeGroupCol  = parseActiveGroup(query, table, prefix)
-      table.withActiveGroup(activeGroupCol ?? '')
-      // Resolve to a TableGroup instance — synth a no-metadata instance
-      // for bare-column / unregistered columns so per-row stamping has
-      // a uniform shape.
-      const activeGroup     = activeGroupCol === undefined
-        ? undefined
-        : (table.getGroups().find(g => g.getColumn() === activeGroupCol)
-            ?? TableGroup.make(activeGroupCol))
-      const groupColumn     = activeGroup?.getColumn()
+      // `activeGroupCol` + `activeGroup` are reconciled at the top of
+      // the table-async callback. Stamp the drilled key back onto the
+      // table here so `toMeta()` emits `activeGroupKey` alongside the
+      // rest of the render-time state. When drilled in, the rendered
+      // set is already filtered to one bucket — the renderer doesn't
+      // want heading rows or per-group summaries. `bandingActive`
+      // gates every banding-side decision (`_groupValue` stamping,
+      // stable-sort, per-group summaries); `activeGroup` stays bound
+      // so the chip + scope wiring can still reach the resolved
+      // group instance.
+      table.withActiveGroupKey(drilledKey)
+      const bandingActive   = activeGroup !== undefined && drilledKey === undefined
+      const groupColumn     = bandingActive ? activeGroup!.getColumn() : undefined
 
       const needsRowMutation =
         rowActionsWithRules.length > 0 ||
@@ -419,7 +472,7 @@ export async function loadTableRecords(
                 const sanitizeOpt = col.getSanitize()
                 const finalHtml = sanitizeOpt === false
                   ? html
-                  : sanitizeHtml(html, sanitizeOpt === true ? undefined : sanitizeOpt)
+                  : await sanitizeHtml(html, sanitizeOpt === true ? undefined : sanitizeOpt)
                 formatted[col.name] = finalHtml
                 rich[col.name]      = true
               }
@@ -448,30 +501,28 @@ export async function loadTableRecords(
               }
             }
 
-            if (activeGroup !== undefined) {
-              const raw = recordObj[activeGroup.getColumn()]
+            if (bandingActive) {
+              const raw = recordObj[activeGroup!.getColumn()]
               // Date-bucketed groups use `YYYY-MM-DD` as the stable-sort
               // key so all rows from the same day cluster together;
               // unparseable values bucket to '' (bottom).
-              const value = activeGroup.isDate()
-                ? bucketDateValue(raw)
-                : (raw == null || raw === '' ? '' : String(raw))
+              const value = activeGroup!.resolveKey(row)
               out['_groupValue'] = value
 
               // Per-row resolved title. User-supplied handler wins over
               // the date() default formatter. Throwing handler stays
               // silent — falls back to the raw `_groupValue`.
-              const titleFn = activeGroup.getTitleHandler()
+              const titleFn = activeGroup!.getTitleHandler()
               if (titleFn) {
                 try {
                   const t = titleFn(row)
                   if (t !== undefined) out['_groupTitle'] = String(t)
                 } catch { /* silent */ }
-              } else if (activeGroup.isDate() && value !== '') {
+              } else if (activeGroup!.isDate() && value !== '') {
                 out['_groupTitle'] = formatDateBucketTitle(raw)
               }
 
-              const descFn = activeGroup.getDescriptionHandler()
+              const descFn = activeGroup!.getDescriptionHandler()
               if (descFn) {
                 try {
                   const d = descFn(row)
@@ -531,6 +582,30 @@ export async function loadTableRecords(
                 if (Object.keys(disabledMap).length > 0) {
                   out['_cellDisabled'] = disabledMap
                 }
+
+                // Per-row select options. Resolvers run in parallel so a
+                // table with several SelectColumn resolvers doesn't stall
+                // on serial awaits. A throwing resolver leaves the slot
+                // unset — the renderer falls back to the column-level
+                // static `selectOptions` (or an empty list) so one bad
+                // row doesn't break the whole table.
+                if (selectColumnsWithResolver.length > 0) {
+                  const resolvedEntries = await Promise.all(selectColumnsWithResolver.map(async (c) => {
+                    try {
+                      const opts = await c.resolve(recordObj)
+                      return [c.name, normalizeSelectOptions(opts)] as const
+                    } catch {
+                      return [c.name, undefined] as const
+                    }
+                  }))
+                  const optionsMap: Record<string, ColumnSelectOption[]> = {}
+                  for (const [name, opts] of resolvedEntries) {
+                    if (opts !== undefined) optionsMap[name] = opts
+                  }
+                  if (Object.keys(optionsMap).length > 0) {
+                    out['_cellSelectOptions'] = optionsMap
+                  }
+                }
               }
             }
 
@@ -566,11 +641,13 @@ export async function loadTableRecords(
         table.withSummaries(summaries)
 
         // Per-group summaries — one summary set per `_groupValue`. Only
-        // computed when a group is active; otherwise the global tfoot
+        // computed when a group is banded; otherwise the global tfoot
         // is the only summary row. Empty-group bucket ('') still gets
         // its own row when present (mirrors the bucket-to-bottom rule
-        // already used for sorting).
-        if (activeGroup !== undefined) {
+        // already used for sorting). Drill-in mode (`bandingActive=false`)
+        // intentionally skips per-group summaries — the visible rows are
+        // already one bucket.
+        if (bandingActive) {
           const buckets: Record<string, Array<Record<string, unknown>>> = {}
           for (const r of finalRows as Array<Record<string, unknown>>) {
             const key = String(r['_groupValue'] ?? '')
@@ -594,10 +671,12 @@ export async function loadTableRecords(
     }
 
     // Mirror the resolved context back onto the table so the renderer can
-    // produce sort/search/page links without re-parsing the URL.
+    // produce sort/search/page links without re-parsing the URL. Drilled-in
+    // requests reset the visible page to 1 — keep the mirror in sync so
+    // pagination chrome doesn't claim page N on a single-bucket render.
     if (effectiveSort)  table.withSort(effectiveSort.column, effectiveSort.direction)
     if (search !== undefined) table.withSearch(search)
-    table.withPage(effectivePage)
+    table.withPage(effectivePageWithDrill)
     if (pathname) table.withCurrentPath(pathname)
   }))
 }

package/src/fields/Field.test.ts

@@ -393,6 +393,21 @@ describe('Field cross-field plumbing (Plan #6)', () => {
       const meta = TextField.make('amount').inlineLabel().inlineLabel(false).toMeta()
       assert.equal('inlineLabel' in meta, false)
     })
+
+    it('reads RenderContext.inlineLabelDefault as a fallback when unset', () => {
+      const meta = TextField.make('amount').toMeta({ inlineLabelDefault: true })
+      assert.equal(meta.inlineLabel, true)
+    })
+
+    it('explicit inlineLabel(false) wins over RenderContext.inlineLabelDefault', () => {
+      const meta = TextField.make('amount').inlineLabel(false).toMeta({ inlineLabelDefault: true })
+      assert.equal('inlineLabel' in meta, false)
+    })
+
+    it('explicit inlineLabel(true) emits regardless of ctx', () => {
+      const meta = TextField.make('amount').inlineLabel(true).toMeta({ inlineLabelDefault: false })
+      assert.equal(meta.inlineLabel, true)
+    })
   })
 
   describe('default()', () => {

package/src/fields/Field.ts

@@ -250,7 +250,7 @@ export abstract class Field extends Element {
   protected _prefix?: FieldDecoration
   protected _suffix?: FieldDecoration
   protected _helperText?: string
-  protected _inlineLabel = false
+  protected _inlineLabel?: boolean
   protected _default?: unknown
   protected _dehydrated = true
   protected _formatStateUsing?: FormatStateUsingHandler
@@ -452,7 +452,12 @@ export abstract class Field extends Element {
   /**
    * Render the label to the left of the input rather than above it.
    * Mirrors `Entry.inlineLabel()`. Default is label-above; pass `false`
-   * to clear the flag.
+   * to clear the flag — including overriding a cascading default set
+   * via `Form.inlineLabel()` / `Section.inlineLabel()`.
+   *
+   * Resolution at meta-build time: explicit field setting wins; when
+   * unset, the nearest ancestor `Form` / `Section` cascade kicks in
+   * (`RenderContext.inlineLabelDefault`); when neither is set, label-above.
    */
   inlineLabel(v = true): this { this._inlineLabel = v; return this }
 
@@ -756,7 +761,7 @@ export abstract class Field extends Element {
       ...(this._prefix !== undefined ? { prefix: this._prefix } : {}),
       ...(this._suffix !== undefined ? { suffix: this._suffix } : {}),
       ...(this._helperText !== undefined ? { helperText: this._helperText } : {}),
-      ...(this._inlineLabel ? { inlineLabel: true } : {}),
+      ...(this._inlineLabel === true || (this._inlineLabel === undefined && ctx?.inlineLabelDefault === true) ? { inlineLabel: true } : {}),
       ...(this._default !== undefined ? { defaultValue: this._default } : {}),
       ...(formattedValue !== undefined ? { formattedValue } : {}),
       ...(this._autofocus ? { autofocus: true } : {}),