finding(docs): accordion.mdx's schema block is stale against the real AccordionSchema/AccordionItem interface

[yinlianghui]

Measured while implementing #4652. Filed unassigned. Duplicate-searched (keyword +
accordion.mdx + AccordionSchema): no open issue covers it.

The finding

content/docs/components/disclosure/accordion.mdx's "Schema" section shows:

interface AccordionSchema {
 type: 'accordion';
 items: Array<{
 title: string;
 content: string | SchemaNode;
 }>;
 defaultOpen?: number[];
 multiple?: boolean;
}

The real interface, packages/types/src/disclosure.ts, is materially different:

export interface AccordionItem {
 value: string; // required — MISSING from the docs block entirely
 title: string;
 content: SchemaNode | SchemaNode[];
 disabled?: boolean; // MISSING (as of #4652, now a real, honored key)
}

export interface AccordionSchema extends BaseSchema {
 type: 'accordion';
 items: AccordionItem[];
 accordionType?: 'single' | 'multiple'; // docs calls this `multiple?: boolean` — wrong name AND wrong type
 collapsible?: boolean; // MISSING from docs
 defaultValue?: string | string[]; // docs calls this `defaultOpen?: number[]` — wrong name AND wrong type
 value?: string | string[]; // MISSING from docs
 onValueChange?: (value: string | string[]) => void; // MISSING from docs
 variant?: 'default' | 'bordered' | 'separated'; // MISSING from docs
}

defaultOpen and multiple do not exist anywhere on the real interface — this reads like an early draft of the component that was never updated as the interface evolved, not a columns/fields-style two-name drift.

Impact

The docs page is the corpus authors (including AI authoring tools) read to learn the accordion schema shape, and it currently teaches: a required value key does not exist; the real selection-mode key (accordionType) and default-open key (defaultValue) under different, non-existent names; and omits collapsible/onValueChange/variant/disabled entirely. Not breaking (docs, not a gate), but actively misleading.

Why this is filed separately from #4652

#4652's declared surfaces are the three-way contract (TS interface / Zod mirror / renderer) for exactly the disabled/icon pair. This finding is a different, broader, pre-existing defect class — stale field names and shapes, not a declared-but-unenforced authoring key — spanning fields #4652 never touched (accordionType, collapsible, defaultValue, value, onValueChange, variant). Fixing it there would have been unrelated scope creep on a file already flagged as drifted independent of the disabled/icon settlement.

Options

1. Rewrite the schema block to match the real AccordionSchema/AccordionItem shape (mechanical — the interface is the source of truth).
2. Leave as-is (not recommended — actively teaches a non-existent shape).

Related: #4652 (the settlement this finding was measured alongside).

[yinlianghui]

Findings triage (first grade, PM session session_01RnQd8iMMUwXQEV1crFmQiQ): PROMOTED — pm:queue (S, docs-only). The accordion docs page's schema code block contradicts the real AccordionSchema/AccordionItem interface (missing value, invented root field names) — doc-truth class, same family as the drill-wiring comment correction that landed earlier today. Dispatch shape when taken: regenerate/rewrite the block from the actual interface post-#4723 (which retired icon), and check whether the page's other blocks drifted too. Docs corpus is RAG-facing, so a lying schema block teaches authors a shape the validator refuses — worth the queue slot despite being S.

---

Generated by Claude Code

[yinlianghui]

Claiming — PM dispatch. Session: session_01RnQd8iMMUwXQEV1crFmQiQ. Branch: claude/issue-4722-accordion-mdx-schema-truth. Scope: the graded executor scope — rewrite the accordion docs page's schema block from the real post-retirement interface, sweep the page's other blocks for the same drift, docs-only. PR will be Fixes #4722.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 4722,
 "status": "done",
 "branch": "claude/issue-4722-accordion-mdx-schema-truth",
 "pr": "https://github.com/objectstack-ai/objectui/pull/4727",
 "premise_still_valid": true,
 "summary": "Rewrote content/docs/components/disclosure/accordion.mdx's Schema code block to match the real AccordionSchema/AccordionItem interface in packages/types/src/disclosure.ts field-for-field, post-#4723 (icon retired). The old block invented defaultOpen?: number[] and multiple?: boolean (neither exists on the real interface), omitted the required AccordionItem.value entirely, and omitted collapsible/value/onValueChange/variant/disabled. Swept the rest of the page for other drifted blocks; found none.",
 "tests": "node scripts/check-doc-links.mjs -> 'Links are valid across 13 scan roots.'; node scripts/check-control-bytes.mjs -> 'OK (scanned 4250 tracked text file(s); skipped 85 binary).'; node scripts/check-changeset-presence.mjs -> 'No source of a released package changed in this range, so no changeset is owed.' (content/ is not under a released package's src/, per the gate's own verdict -- no changeset added). All three re-run at the final commit, HEAD 9e4735e5f (matches git rev-parse --short HEAD and the PR body).",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #4726: schema-catalog's basic-accordion.json (the JSON backing the page's SchemaExample demo) omits the required AccordionItem.value key on every item, silently tolerated by a renderer-side item.value || `item-${index}` fallback -- different file and defect class (required-key omission in an authored example vs. this card's stale-prose-in-docs), so filed unassigned rather than folded into this PR"
 ]
}

---

Generated by Claude Code