@opensaas/stack-core 0.29.0 → 0.31.0

package/src/config/nav-count.ts

@@ -0,0 +1,85 @@
+import type { AccessContext } from '../access/types.js'
+import { getDbKey } from '../lib/case-utils.js'
+import type { ListConfig, OpenSaasConfig, TypeInfo } from './types.js'
+
+/**
+ * The minimal shape a `context.db[list]` delegate needs for a nav count. The
+ * access-controlled DB carries an `any` index signature, so this narrows the
+ * lookup to just the access-scoped `count` we call.
+ */
+type CountDelegate = {
+  count?: (args?: { where?: unknown }) => Promise<number>
+}
+
+/**
+ * Whether a list's query access is **statically denied** — provably no session
+ * can read any row without evaluating a session-dependent function.
+ *
+ * Mirrors the list view's `canDeleteList` static check (issue #733): query
+ * access is statically denied when it is absent (deny-by-default, matching the
+ * access engine) or the literal boolean `false`. A function — or `true` —
+ * cannot be decided up front, so the count is fetched through the secured
+ * context, which re-applies the real rule per row.
+ *
+ * A statically-denied list must render no nav count at all: a `0` there would
+ * imply "this list is empty" when the truth is "you may see none of it".
+ */
+export function isListQueryStaticallyDenied(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+): boolean {
+  const queryAccess = listConfig.access?.operation?.query
+  if (queryAccess === undefined) return true
+  if (typeof queryAccess === 'boolean') return !queryAccess
+  return false
+}
+
+/**
+ * Resolve the access-scoped nav counts for the lists that opt in via
+ * `ui.navCount` (issue #735).
+ *
+ * The returned map is keyed by list key and contains an entry **only** for a
+ * list that:
+ *
+ * 1. opts in (`ui.navCount === true`) — no count query runs for any other list,
+ * 2. is not a singleton (a single-record list has no meaningful count), and
+ * 3. does not have statically-denied query access (see
+ *    {@link isListQueryStaticallyDenied}).
+ *
+ * Each count is read through the secured `context.db`, whose `count` applies the
+ * access filter, so the number reflects exactly what the current session may
+ * see (a denied row is not counted). Counts are fetched concurrently.
+ */
+export async function resolveNavCounts(
+  context: AccessContext,
+  config: OpenSaasConfig,
+): Promise<Record<string, number>> {
+  const counts: Record<string, number> = {}
+  const lists = config.lists ?? {}
+
+  const optedIn = Object.keys(lists).filter((listKey) => {
+    const listConfig = lists[listKey] as ListConfig<TypeInfo> | undefined
+    if (!listConfig) return false
+    if (listConfig.ui?.navCount !== true) return false
+    if (listConfig.isSingleton) return false
+    return !isListQueryStaticallyDenied(listConfig)
+  })
+
+  await Promise.all(
+    optedIn.map(async (listKey) => {
+      const delegate: CountDelegate | undefined = context.db?.[getDbKey(listKey)]
+      if (!delegate?.count) return
+      // A single list's count failing (a DB hiccup, a throwing access filter or
+      // hook) must not blank the whole admin chrome — `AdminUI` awaits this
+      // before rendering the shell. Degrade like the sibling `ListView`: log and
+      // omit just that badge. Other lists' counts are unaffected.
+      try {
+        counts[listKey] = await delegate.count()
+      } catch (error) {
+        console.error(`Failed to resolve nav count for ${listKey}:`, error)
+      }
+    }),
+  )
+
+  return counts
+}

package/src/config/types.ts

@@ -1,4 +1,5 @@
 import type { AccessControl, FieldAccess } from '../access/types.js'
+import type { FilterSpec } from '../filter/types.js'
 import type { z } from 'zod'
 
 /**
@@ -663,6 +664,29 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
     type: string
     optional: boolean
   }
+  /**
+   * Declare this field's filtering capability — its {@link FilterSpec} — for the
+   * admin UI's Filter builder (ADR-0017). Optional and additive: a field that
+   * omits it (like `password`, `json`, `virtual`, or a third-party field that
+   * hasn't adopted filtering) is simply not filterable and never suggested, so
+   * absence degrades gracefully everywhere.
+   *
+   * Self-contained, like {@link getPrismaType} and friends — the filter engine
+   * delegates to each field's spec rather than switching on field type. The
+   * returned `toCondition` mapper must stay pure (no DB/Prisma imports); its
+   * output is ANDed with the access filter through the secured context.
+   *
+   * @param fieldName The field's config key (closed over by the mapper).
+   * @param listKey   The owning list's key.
+   * @param config    The full config (e.g. relationship specs resolve their
+   *   target list's label field from it).
+   * @returns The field's Filter spec, or `undefined` when not filterable.
+   */
+  getFilterSpec?: (
+    fieldName: string,
+    listKey: string,
+    config: OpenSaasConfig,
+  ) => FilterSpec | undefined
   /**
    * Get TypeScript imports needed for this field's type
    * @returns Array of import statements needed for the generated types file
@@ -814,9 +838,34 @@ export type PasswordField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConf
   }
 }
 
+/**
+ * Badge-variant vocabulary a select option can map its value to for status-Cell
+ * rendering in the admin UI (issue #729). Mirrors the admin UI Badge primitive's
+ * variants; `secondary` is the neutral fallback used for unmapped options.
+ */
+export type SelectOptionVariant =
+  'default' | 'secondary' | 'success' | 'warning' | 'destructive' | 'outline'
+
+/**
+ * A single choice in a `select` field.
+ *
+ * `label`/`value` are the long-standing shape; `ui` is additive, optional
+ * metadata (issue #729). `ui.variant` lets a value render as a coloured status
+ * badge in list-table Cells — an option without it renders with the neutral
+ * badge, so existing options keep working unchanged.
+ */
+export type SelectOption = {
+  label: string
+  value: string
+  ui?: {
+    /** Badge variant used when this option's value renders as a status Cell. */
+    variant?: SelectOptionVariant
+  }
+}
+
 export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'select'
-  options: Array<{ label: string; value: string }>
+  options: Array<SelectOption>
   defaultValue?: string
   db?: {
     /**
@@ -880,6 +929,93 @@ export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig
   }
 }
 
+/**
+ * Item-view configuration for a single to-many relationship field — the
+ * per-relationship overrides for the admin item view's Relationship table
+ * (issue #734). All values are plain, serialisable data so they can cross the
+ * server→client boundary via the existing field-config serialisation.
+ */
+export type RelationshipItemViewConfig = {
+  /**
+   * How this to-many relationship is presented on the owning record's item
+   * view:
+   * - `'table'` (default): a read-only Relationship table of related rows.
+   * - `'picker'`: demote it back to the compact relationship picker inside the
+   *   details card (the pre-#734 behaviour).
+   *
+   * @default 'table'
+   */
+  displayMode?: 'table' | 'picker'
+  /**
+   * The related list's fields to show as Relationship-table columns, in order.
+   *
+   * When omitted, the columns default to the related list's own column
+   * curation (`ui.listView.initialColumns`, else all non-system fields) minus
+   * the back-reference field that points at the parent record.
+   *
+   * @example
+   * ```typescript
+   * posts: relationship({
+   *   ref: 'Post.author',
+   *   many: true,
+   *   ui: { itemView: { columns: ['title', 'status'] } },
+   * })
+   * ```
+   */
+  columns?: string[]
+  /**
+   * The maximum number of related rows to fetch and render in this
+   * Relationship table (issue #752). The item view fetches related rows
+   * through the secured context bounded by this `take`, so a record with many
+   * related rows never loads/renders every one on edit-page open. The totals
+   * footer still shows the full access-scoped total ("showing N of M").
+   *
+   * When omitted, a sensible default cap applies (the UI's
+   * `DEFAULT_ITEM_VIEW_TAKE`). Must be a positive integer; non-positive or
+   * non-integer values fall back to the default.
+   *
+   * @example
+   * ```typescript
+   * sessions: relationship({
+   *   ref: 'Session.user',
+   *   many: true,
+   *   ui: { itemView: { take: 5 } },
+   * })
+   * ```
+   */
+  take?: number
+  /**
+   * The numeric columns whose values are summed in the Relationship table's
+   * totals footer. The row count is always shown; sums appear only for the
+   * columns listed here, each formatted by that column's Cell.
+   *
+   * @example
+   * ```typescript
+   * lineItems: relationship({
+   *   ref: 'LineItem.order',
+   *   many: true,
+   *   ui: { itemView: { sum: ['amount'] } },
+   * })
+   * ```
+   */
+  sum?: string[]
+  /**
+   * How a row's ✕ control removes a related row from this table (ADR-0018).
+   *
+   * - `'disconnect'` (default): non-destructively unlinks the related row from
+   *   this record — the row itself is untouched and still appears on its own
+   *   list. Gated on the related list's update access. Hidden statically when
+   *   the schema makes disconnect impossible (a required foreign key on the
+   *   related side, i.e. the back-reference declares `db.isNullable: false`).
+   * - `'delete'`: opts into truly deleting the related row, behind a
+   *   confirmation, gated on the related list's delete access.
+   * - `'none'`: hides the removal control entirely.
+   *
+   * @default 'disconnect'
+   */
+  removeAction?: 'disconnect' | 'delete' | 'none'
+}
+
 export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
   BaseFieldConfig<TTypeInfo> & {
     type: 'relationship'
@@ -1006,6 +1142,13 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
     }
     ui?: {
       displayMode?: 'select' | 'cards'
+      /**
+       * Item-view (Relationship table) overrides for this to-many relationship
+       * — columns, summed columns, and demotion to the compact picker (issue
+       * #734). Ignored for single (`many: false`) relationships, which always
+       * render inside the details card.
+       */
+      itemView?: RelationshipItemViewConfig
     }
     /**
      * Get the complete Prisma schema contribution for this relationship field.
@@ -1731,6 +1874,13 @@ export type ListUIConfig = {
    * Keystone's `ui.listView`.
    */
   listView?: ListViewUIConfig
+  /**
+   * Item-view (record edit page) configuration for this list — controls the
+   * placement/order of the shape-derived Relationship-table sections (issue
+   * #734). When omitted, sections appear in field-declaration order and the
+   * layout is derived purely from the number of to-many relationships.
+   */
+  itemView?: ItemViewUIConfig
   /**
    * The field used to represent a row as a single label — in relationship
    * cells, dropdown options, and page headings. Must reference a declared,
@@ -1745,6 +1895,141 @@ export type ListUIConfig = {
    * ```
    */
   labelField?: string
+  /**
+   * Opt this list into an access-scoped record count next to its Admin chrome
+   * nav item (issue #735). Default `false` — no count query runs for lists that
+   * don't opt in. The count is fetched through the secured context, so it only
+   * ever reflects what the current session may see; a list whose query access
+   * is statically denied renders no count rather than a misleading zero.
+   *
+   * @example
+   * ```typescript
+   * ui: { navCount: true }
+   * ```
+   */
+  navCount?: boolean
+  /**
+   * Opt this list's label column into an initials-avatar Cell (issue #735) — an
+   * initials bubble whose text and colour derive deterministically from the row,
+   * rendered ahead of the emphasized {@link getItemLabel Item label}. Default
+   * `false` (text-only label). A per-field cell override (`ui.cell`) on the
+   * label field still wins.
+   *
+   * @example
+   * ```typescript
+   * ui: { avatar: true }
+   * ```
+   */
+  avatar?: boolean
+}
+
+/**
+ * Item-view (record edit page) configuration, mirroring the `ui.listView`
+ * shape but for the shape-derived item layout (issue #734).
+ *
+ * The layout itself — single card / two-column split / stacked — is derived
+ * from the number of to-many relationships rendered as Relationship tables and
+ * needs no configuration. This block only reorders those sections; the
+ * per-relationship column/sum/picker overrides live on the relationship field
+ * (`ui.itemView`, see {@link RelationshipItemViewConfig}).
+ */
+export type ItemViewUIConfig = {
+  /**
+   * The order of the Relationship-table sections, by their to-many
+   * relationship field name. Listed fields come first in this order; any
+   * to-many relationship not listed keeps its declaration order after them.
+   *
+   * @example
+   * ```typescript
+   * ui: { itemView: { order: ['orders', 'reviews'] } }
+   * ```
+   */
+  order?: string[]
+}
+
+/**
+ * A button variant for a custom Bulk action, matching the admin UI's Button
+ * variants. Serializable — it crosses to the client selection bar as a plain
+ * string.
+ */
+export type BulkActionVariant =
+  'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+
+/**
+ * Arguments passed to a custom Bulk action's server-side `handler` (issue #736).
+ *
+ * The handler runs entirely server-side — it is NEVER serialized to the client —
+ * and must do all of its work through the SECURED `context` (never raw Prisma),
+ * so per-row access control still applies and a denied row is a Silent failure.
+ */
+export interface BulkActionContext {
+  /** The list the action was invoked on (PascalCase list key). */
+  listKey: string
+  /** The explicit set of selected row ids the admin chose. */
+  ids: string[]
+  /**
+   * The access-scoped context. All database work MUST go through `context.db`
+   * so the list's access control and hooks are enforced for every id.
+   */
+  context: import('../access/types.js').AccessContext
+}
+
+/**
+ * The outcome a Bulk action `handler` returns. The optional `message` is shown
+ * in the selection bar's status line once the action completes; returning
+ * nothing yields a generic completion message.
+ */
+export interface BulkActionResult {
+  /** Human-readable outcome shown to the admin (e.g. "Published 3 of 5"). */
+  message?: string
+}
+
+/**
+ * A list-specific custom Bulk action declared in `ui.listView.bulkActions`
+ * (issue #736). Rendered as a button in the list view's selection bar, in
+ * declaration order, alongside the built-in Delete.
+ *
+ * SERIALISATION BOUNDARY: only `key`, `label`, `variant` and `destructive`
+ * cross to the client (as plain data). `handler` and `hasAccess` are
+ * server-side functions and never leave the server — the client sends `key`
+ * back through the generic server action, which looks the handler up and runs
+ * it with the freshly-rebuilt secured context.
+ */
+export interface BulkAction {
+  /**
+   * Stable identifier the client echoes back to dispatch this action
+   * server-side. Must be unique within the list.
+   */
+  key: string
+  /** Button label shown in the selection bar. */
+  label: string
+  /** Button variant (defaults to `'outline'`). */
+  variant?: BulkActionVariant
+  /**
+   * When true, the admin is asked to confirm before the action runs, reusing
+   * the same confirmation affordance as the built-in Delete.
+   */
+  destructive?: boolean
+  /**
+   * Optional visibility gate, evaluated server-side against the session before
+   * the button is offered (user story 14 — "only see actions I may perform").
+   * Returning `false` hides the button.
+   *
+   * This ONLY controls visibility; the `handler` always runs through the
+   * secured context, so per-row access is enforced regardless. It is also
+   * re-checked server-side on dispatch, so a hidden action cannot be invoked.
+   */
+  hasAccess?: (args: {
+    session: import('../access/types.js').Session | null
+    context: import('../access/types.js').AccessContext
+    listKey: string
+  }) => boolean | Promise<boolean>
+  /**
+   * The server-side handler. Receives the selected ids and the secured
+   * `context`; do all work through `context.db`. Returns an optional
+   * `{ message }` shown in the selection bar when the action completes.
+   */
+  handler: (args: BulkActionContext) => BulkActionResult | void | Promise<BulkActionResult | void>
 }
 
 /**
@@ -1783,6 +2068,39 @@ export type ListViewUIConfig = {
     /** The sort direction. */
     direction: 'asc' | 'desc'
   }
+  /**
+   * Custom list-specific Bulk actions shown in the list view's selection bar,
+   * in declaration order, alongside the built-in Delete (issue #736). Each
+   * action's `handler` runs server-side over the selected ids through the
+   * secured context; only serializable metadata (`key`/`label`/`variant`/
+   * `destructive`) crosses to the client.
+   *
+   * @example
+   * ```typescript
+   * ui: {
+   *   listView: {
+   *     bulkActions: [
+   *       {
+   *         key: 'publish',
+   *         label: 'Publish',
+   *         handler: async ({ ids, context }) => {
+   *           let n = 0
+   *           for (const id of ids) {
+   *             const r = await context.db.post.update({
+   *               where: { id },
+   *               data: { status: 'published' },
+   *             })
+   *             if (r) n++
+   *           }
+   *           return { message: `Published ${n} of ${ids.length}` }
+   *         },
+   *       },
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  bulkActions?: BulkAction[]
 }
 
 /**

package/src/context/hook-pipeline.ts

@@ -6,6 +6,7 @@ import {
   executeFieldResolveInputHooks,
   executeFieldValidateHooks,
   validateFieldRules,
+  splitMultiColumnFields,
   ValidationError,
 } from '../hooks/index.js'
 import { applyCreateDefaults } from './apply-defaults.js'
@@ -66,12 +67,17 @@ export interface HookPipeline {
  *     → list `validate`
  *     → field `validate`
  *     → built-in field rules (`validateFieldRules`)
+ *     → split multi-column fields (`splitMultiColumnFields`)
  *
  * Contract preserved exactly:
  *   - `resolvedData` starts as `inputData` and is threaded through each phase;
  *   - validate hooks report failures via `addValidationError` → THROW
  *     `ValidationError` (never silent);
  *   - built-in field rule failures THROW `ValidationError`;
+ *   - a multi-column field (e.g. storage image()/file() in Keystone-parity
+ *     mode) is validated under its LOGICAL key BEFORE it is split into
+ *     physical columns (#789) — an unrecognised value throws instead of being
+ *     silently split into null/undefined columns;
  *   - on success returns the transformed `resolvedData`.
  */
 async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResult> {
@@ -160,6 +166,19 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
     throw new ValidationError(validation.errors, validation.fieldErrors)
   }
 
+  // ── Phase 4: split multi-column fields into physical columns ──────────────
+  // Only reached once the logical value has passed validation (#789). Replaces
+  // each multi-column field's logical key with its per-part columns, gated by
+  // the field's own write access (see `splitMultiColumnFields`).
+  resolvedData = await splitMultiColumnFields(
+    inputData,
+    resolvedData,
+    listConfig.fields,
+    operation,
+    context,
+    item,
+  )
+
   return { resolvedData }
 }