@@ -0,0 +1,22 @@
+---
+'@object-ui/types': minor
+---
+
+A bind-only `list` is accepted: `ListSchema.items` is optional on both faces, and the zod face requires at least one of `bind` / `items` (objectui#11405).
+
+The `list` renderer reads `useDataScope(schema.bind)` first and falls back to `schema.items` when the bound value is not an array. So a `list` that carries only `bind` draws one entry per element of the bound array. Both published faces nevertheless required `items`: `safeValidateSchema`, the function `objectui validate` calls, refused `{ "type": "list", "bind": "customerNames" }` with `invalid_type` at `items`, the strict face agreed, and the TypeScript face refused the same literal. The published `skills/objectui` guides author that shape in four marked examples.
+
+The accept set moves in one direction only, measured through the arm, `safeValidateSchema` and the strict face against a rebuilt `dist`:
+
+| document | before | after |
+| --- | --- | --- |
+| `bind` only | refused at `items` (`invalid_type`) | **accepted** |
+| `items` only | accepted | accepted |
+| both | accepted | accepted |
+| neither | refused at `items` (`invalid_type`) | refused at the node (`custom`, `params.code` = `LIST_ENTRIES_REQUIRED`) |
+
+Nothing went from accepted to refused. The rule is at least one and not exactly one, because `items` is the renderer's fallback beside `bind`. Presence is `!== undefined`, as in the record-source refinement the `object-*` arms carry, so `bind: ''` and `items: []` each count. The node-level issue is reported beside any other issue on the node, so a `list` with neither key and a bad `ordered` reports both.
+
+On the TypeScript face `items?: ListItem[]` is optional, so a reader of `ListSchema['items']` now sees `ListItem[] | undefined`. The only reader in this repository, the `list` renderer, already guards the read with `Array.isArray`. The TypeScript face cannot express the at-least-one rule, so a literal with neither key still compiles; the validator enforces it.
+
+Marked `minor` per this repo's version-alignment rule.
@@ -15,13 +15,30 @@ import type { SchemaNode } from '@object-ui/types';
 interface ListSchema {
   type: 'list';
   title?: string;           // heading drawn above the list
-  items: SchemaNode[];
+  bind?: string;            // path to an array in the host scope, read first
+  items?: SchemaNode[];     // drawn when `bind` resolves no array
   ordered?: boolean;
   className?: string;
   wrapperClass?: string;
 }
 ```
 
+A `list` needs at least one of `bind` and `items`. The renderer reads `bind` through
+`useDataScope` first and falls back to `items` when the bound value is not an array, so
+a node may carry both. A bind-only list draws one entry per element of the bound array:
+
+```json
+{
+  "type": "list",
+  "bind": "customerNames"
+}
+```
+
+A `list` with neither key is refused at the node by `safeValidateSchema` and the strict
+face, with `params.code` set to `LIST_ENTRIES_REQUIRED`. Until objectui#11405 `items` was
+required, so the bind-only list above was refused at `items`. The TypeScript face declares
+`items` optional and cannot express the at-least-one rule; the validator enforces it.
+
 <Callout type="warn">
   `wrapperClass` is now typed. The renderer has read it all along — it lands on the
   wrapper element around the list — but it went undeclared until objectui#7722,
 
@@ -0,0 +1,179 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * objectui#11405 — a bind-only `list` is accepted: `ListSchema.items` is
+ * optional on both published faces, and the zod face requires AT LEAST ONE of
+ * `bind` / `items`.
+ *
+ * ## The defect
+ *
+ * `list.tsx` reads `useDataScope(schema.bind)` first and falls back to
+ * `schema.items` when the bound value is not an array, so a `list` carrying only
+ * `bind` draws one entry per element of the bound array. Both published faces
+ * nevertheless REQUIRED `items`: `safeValidateSchema({ type: 'list', bind:
+ * 'customerNames' })` was refused with `invalid_type` at `items`, the strict face
+ * agreed, and the TypeScript face refused the same literal (`TS2741`). Four
+ * marked fences in two published guides author exactly that shape, and their
+ * marker only checks that they parse, so nothing noticed.
+ *
+ * Triage's ruling (comment 5941529511): the arm follows the renderer, and the
+ * guides are not edited. The rule is at least one and ⛔ not exactly one,
+ * because `items` is the renderer's real fallback beside `bind`.
+ *
+ * ## What this file pins
+ *
+ * - the zod face, through the arm itself, through `safeValidateSchema` (the
+ *   function `objectui validate` calls) and through the strict face: a bind-only
+ *   `list`, an items-only one and one carrying both are accepted, and one with
+ *   neither is refused ONCE, at the node, keyed `LIST_ENTRIES_REQUIRED`;
+ * - the TypeScript face: the bind-only literal compiles. That half is judged by
+ *   `tsc -p tsconfig.test.json` (`pnpm --filter @object-ui/types type-check`),
+ *   not by vitest, which strips types. The TypeScript face cannot spell "at
+ *   least one" with an optional member, so a literal with neither key still
+ *   compiles; the rule lives on the mirror, as it does for `object-kanban`
+ *   (objectui#7780);
+ * - the guides: every marked fence that authors a bind-only `list` is READ OFF
+ *   DISK with `scanSkillFences`, the reader the marker's own gate uses, and fed
+ *   to `safeValidateSchema`. A copy here would not notice a guide change. A fence
+ *   the guide itself marks ❌ is wrong for another reason (its `children` and
+ *   its `${item.name}`), so for it this file pins only that `items` is no longer
+ *   what refuses it.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// @ts-expect-error -- plain-JS shared helper, intentionally untyped (`allowJs: false`)
+import { scanSkillFences as scanUntyped, stripJsonComments as stripUntyped } from '../../../../scripts/check-skill-examples.mjs';
+import { ListSchema, safeValidateSchema, StrictAnyComponentSchema } from '../zod/index.zod';
+import type { ListSchema as TsListSchema } from '../data-display';
+
+/** Local annotations, since the import above is untyped — the call sites stay checked. */
+type ScannedFence = { kind: 'ts' | 'json'; language: string; fenceLine: number; body: string; marked: boolean };
+const scanSkillFences: (source: string) => { fences: ScannedFence[]; orphans: number[] } = scanUntyped;
+const stripJsonComments: (source: string) => string = stripUntyped;
+
+/** Rooted at THIS file, never at `process.cwd()`. */
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '..', '..', '..', '..');
+
+const GUIDES = [
+  'skills/objectui/guides/data-integration.md',
+  'skills/objectui/guides/schema-expressions.md',
+] as const;
+
+/* ── The TypeScript face (judged by `tsc -p tsconfig.test.json`) ── */
+
+// Refused with TS2741 (`items` is missing) before objectui#11405.
+const BIND_ONLY: TsListSchema = { type: 'list', bind: 'customerNames' };
+const ITEMS_ONLY: TsListSchema = { type: 'list', items: [{ content: 'Ada' }] };
+const BOTH: TsListSchema = { type: 'list', bind: 'rows', items: [{ content: 'Ada' }] };
+
+type Issue = { code: string; path: PropertyKey[]; params?: Record<string, unknown> };
+
+/** The issues a parse raised, or `[]` when it passed. */
+function issuesOf(result: { success: boolean; error?: { issues: readonly unknown[] } }): Issue[] {
+  return result.success ? [] : ((result.error?.issues ?? []) as Issue[]);
+}
+
+/** Every face a node goes through: the arm, the published validator, the strict face. */
+const FACES = {
+  arm: (node: unknown) => ListSchema.safeParse(node),
+  safeValidateSchema: (node: unknown) => safeValidateSchema(node),
+  strict: (node: unknown) => StrictAnyComponentSchema.safeParse(node),
+} as const;
+
+describe('a `list` needs at least one of `bind` / `items` (objectui#11405)', () => {
+  for (const [face, parse] of Object.entries(FACES)) {
+    it(`${face}: bind-only, items-only and both are accepted`, () => {
+      for (const node of [BIND_ONLY, ITEMS_ONLY, BOTH]) {
+        expect(issuesOf(parse(node)), JSON.stringify(node)).toEqual([]);
+      }
+    });
+
+    it(`${face}: a list with neither is refused once, at the node, keyed LIST_ENTRIES_REQUIRED`, () => {
+      const issues = issuesOf(parse({ type: 'list', ordered: true }));
+      expect(issues).toHaveLength(1);
+      expect(issues[0]).toMatchObject({ code: 'custom', path: [], params: { code: 'LIST_ENTRIES_REQUIRED' } });
+    });
+  }
+
+  it('the rule is reported BESIDE an unrelated fault on the same node, not hidden by it', () => {
+    const issues = issuesOf(safeValidateSchema({ type: 'list', ordered: 'yes' }));
+    expect(issues.map((i) => [i.code, i.path.join('.')])).toEqual([
+      ['invalid_type', 'ordered'],
+      ['custom', ''],
+    ]);
+  });
+
+  it('a `bind` that fails its own type is refused at `bind`, and the rule does not fire twice', () => {
+    const issues = issuesOf(safeValidateSchema({ type: 'list', bind: 42 }));
+    expect(issues.map((i) => [i.code, i.path.join('.')])).toEqual([['invalid_type', 'bind']]);
+  });
+
+  it('a nested list with neither is refused at its own path', () => {
+    const issues = issuesOf(safeValidateSchema({ type: 'div', children: [{ type: 'list' }] }));
+    expect(issues).toHaveLength(1);
+    expect(issues[0]).toMatchObject({ code: 'custom', path: ['children', 0], params: { code: 'LIST_ENTRIES_REQUIRED' } });
+  });
+});
+
+/* ── The guides' marked fences, read off disk ── */
+
+type Fence = { guide: string; fenceLine: number; teachesWrong: boolean; node: Record<string, unknown> };
+
+/** Every marked json/jsonc fence in the two guides whose root is a `list` with `bind` and no `items`. */
+function bindOnlyListFences(): Fence[] {
+  const out: Fence[] = [];
+  for (const guide of GUIDES) {
+    const { fences } = scanSkillFences(readFileSync(resolve(REPO_ROOT, guide), 'utf8'));
+    for (const fence of fences) {
+      if (!fence.marked || fence.kind !== 'json') continue;
+      // The marker's own gate already requires every marked fence to parse.
+      const node = JSON.parse(fence.language === 'jsonc' ? stripJsonComments(fence.body) : fence.body);
+      if (!node || typeof node !== 'object' || node.type !== 'list') continue;
+      if (node.bind === undefined || node.items !== undefined) continue;
+      out.push({ guide, fenceLine: fence.fenceLine, teachesWrong: fence.body.includes('❌'), node });
+    }
+  }
+  return out;
+}
+
+describe('the guides\' bind-only `list` fences (objectui#11405)', () => {
+  const fences = bindOnlyListFences();
+
+  it('COUNTER-PROBE: the reader reaches a bind-only list in each guide, and the ❌ example among them', () => {
+    for (const guide of GUIDES) {
+      expect(fences.filter((f) => f.guide === guide).length, guide).toBeGreaterThan(0);
+    }
+    expect(fences.some((f) => f.teachesWrong)).toBe(true);
+  });
+
+  it('every fence taught as valid passes safeValidateSchema and the strict face', () => {
+    const taught = fences.filter((f) => !f.teachesWrong);
+    expect(taught.length).toBeGreaterThan(0);
+    for (const { guide, fenceLine, node } of taught) {
+      const where = `${guide}, fence opened on its line ${fenceLine}`;
+      expect(issuesOf(safeValidateSchema(node)), where).toEqual([]);
+      expect(issuesOf(StrictAnyComponentSchema.safeParse(node)), where).toEqual([]);
+    }
+  });
+
+  it('the ❌ example is still refused, and never for a missing `items`', () => {
+    for (const { guide, fenceLine, node, teachesWrong } of fences) {
+      if (!teachesWrong) continue;
+      const where = `${guide}, fence opened on its line ${fenceLine}`;
+      const issues = issuesOf(safeValidateSchema(node));
+      expect(issues.length, where).toBeGreaterThan(0);
+      expect(issues.filter((i) => i.path[0] === 'items'), where).toEqual([]);
+      expect(issues.filter((i) => i.params?.code === 'LIST_ENTRIES_REQUIRED'), where).toEqual([]);
+    }
+  });
+});
@@ -299,9 +299,24 @@ export interface ListSchema extends BaseSchema {
    */
   title?: string;
   /**
-   * List items
-   */
-  items: ListItem[];
+   * List items — the entries drawn when {@link BaseSchema.bind} resolves no
+   * array.
+   *
+   * READ SITE: `packages/components/src/renderers/data-display/list.tsx`, which
+   * reads `useDataScope(schema.bind)` FIRST and falls back to this member only
+   * when the bound value is not an array (`Array.isArray(schema.items)`, so the
+   * read is guarded).
+   *
+   * Optional since objectui#11405. It was REQUIRED, so a bind-only `list` —
+   * which draws one entry per element of the bound array — was refused by both
+   * published faces and could not be annotated with its own type. The
+   * requirement the renderer really has, at least one of `bind` / `items`
+   * present (⛔ not exactly one: `items` is the fallback beside `bind`), lives
+   * on the mirror as a refinement (`listHasAnEntrySource` in
+   * `zod/data-display.zod.ts`, keyed `LIST_ENTRIES_REQUIRED`), so the published
+   * declaration and the published validator say the same thing.
+   */
+  items?: ListItem[];
   /**
    * Whether list is ordered
    * @default false
 
@@ -180,14 +180,53 @@ export const ListItemSchema = z.object({
   ),
 });
 
+/**
+ * A `list` draws its entries from `bind` or from `items`, so it needs at least
+ * one of the two (objectui#11405).
+ *
+ * `list.tsx` reads `useDataScope(schema.bind)` FIRST and falls back to
+ * `schema.items` when the bound value is not an array, so both keys are live
+ * inputs and `items` is the real fallback beside `bind`. That is why the rule is
+ * AT LEAST one and ⛔ not exactly one: a node carrying both is the fallback
+ * shape, and refusing it would refuse a document the renderer draws. Until
+ * objectui#11405 `items` was REQUIRED here, so a bind-only `list` — the shape the
+ * renderer and this arm's own tombstone text name, and the one the published
+ * `skills/objectui` guides author — was refused with `invalid_type` at `items`.
+ *
+ * Presence is `!== undefined`, the wording `requireRecordSource` in
+ * `./objectql.zod.ts` uses for its own at-least-one rule, so `bind: ''` and
+ * `items: []` each count. The issue sits at the ROOT, because no single key is
+ * at fault when both are missing, and it carries `params.code` so a consumer
+ * can tell this refusal from the others without parsing the message.
+ *
+ * Installed with `when: () => true`, for the reason `requireRecordSource`
+ * gives: zod skips a refinement once an earlier issue aborts the parse, and the
+ * required member this replaces was reported BESIDE every other issue on the
+ * node. So the body reads the raw input defensively.
+ */
+function listHasAnEntrySource(node: unknown, ctx: z.core.$RefinementCtx): void {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+  // Read as a plain record: `bind` stays declared once, on `BaseSchema` (objectui#6357).
+  const keys = node as Record<string, unknown>;
+  if (keys.bind !== undefined || keys.items !== undefined) return;
+  ctx.addIssue({
+    code: 'custom',
+    path: [],
+    params: { code: 'LIST_ENTRIES_REQUIRED' },
+    message: '`list` has no entries to draw: declare `items`, or `bind` a path to an array in the host scope',
+  });
+}
+
 /**
  * List Schema - List component
  */
 export const ListSchema = BaseSchema.extend({
   type: z.literal('list'),
   title: z.string().optional()
     .describe('Heading drawn above the list (objectui#11347)'),
-  items: z.array(ListItemSchema).describe('List items'),
+  // Optional since objectui#11405: a bind-only `list` draws its entries from the
+  // host scope. The at-least-one rule is `listHasAnEntrySource` above.
+  items: z.array(ListItemSchema).optional().describe('List items'),
   ordered: z.boolean().optional().describe('Whether list is ordered'),
   dividers: z.boolean().optional().describe('Show dividers between items'),
   dense: z.boolean().optional().describe('Dense spacing'),
@@ -217,7 +256,7 @@ export const ListSchema = BaseSchema.extend({
     + '`ui:list` is the measured SOLE owner of the bare `list` key (`view:list` passes `skipFallback: true`); '
     + 're-derive with `pnpm check:registry-bare-names --table` (objectui#9264).',
   ),
-});
+}).superRefine(listHasAnEntrySource, { when: () => true });
 
 /**
  * Table Column Schema
 
@@ -492,6 +492,19 @@ export const ADJUDICATED = new Map([
     'packages/types/src/__tests__/held-public-block-arms-10872.test.ts',
     { reads: ['content/docs/guide/quick-start.md'] },
   ],
+  // objectui#11405. Reads every marked fence in the two guides that authors a
+  // bind-only `list`, with the marker gate's own `scanSkillFences`, and judges it
+  // through `safeValidateSchema` and the strict face -- so an edit to either guide
+  // is an edit to this test's input.
+  [
+    'packages/types/src/__tests__/list-bind-only-11405.test.ts',
+    {
+      reads: [
+        'skills/objectui/guides/data-integration.md',
+        'skills/objectui/guides/schema-expressions.md',
+      ],
+    },
+  ],
   [
     'packages/types/src/__tests__/object-calendar-record-source-7313.test.ts',
     { reads: ['content/docs/plugins/plugin-calendar.mdx'] },