docs(fields): split location.mdx's welded map fence into a tsx and a jsonc block

[yinlianghui-tw]

Fixes#6127

Docs only, publishes nothing. Verified at fe478454e.

The defect, re-measured on origin/main rather than inherited

content/docs/fields/location.mdx's Integration with Maps fence welded two
different examples into one block: an import plus a JSX element (which needs
tsx), immediately followed by a bare metadata object literal at statement
position (which tsx reads as a labelled statement, then falls over on the
commas). Parsed standalone with the repo's own TypeScript (6.0.3) at
133e2ea1e, before any edit:

typescript 6.0.3 · content/docs/fields/location.mdx
fence line 81 (`plaintext`) TS: 2 syntactic diagnostic(s)
line 4: TS1005 '>' expected.
line 4: TS1109 Expression expected.
fence line 81 (`plaintext`) TSX: 5 syntactic diagnostic(s)
line 10: TS1005 ';' expected.
line 11: TS1005 ';' expected.
line 13: TS1005 ';' expected.
line 14: TS1005 ';' expected.
line 17: TS1005 ';' expected.

It parses under neither fence language, which is why switching the single
fence to tsx is the obvious move and the wrong one.

The fix — the fence split in two, per the ruling

Each half is now fenced for what it actually is:

1. a tsx block holding the widget example, made self-contained so it
   compiles: it renders LocationField with a typed LocationFieldMetadata and
   a state-held coordinate pair, instead of spreading an undeclared props
   (which would have reddened the gate with TS2304: Cannot find name 'props');
2. a jsonc block holding the object-map metadata node — a metadata
   document, not a component call, and a schema-key question
   check-doc-snippet-types explicitly says it does not answer (see its header,
   "Schema-key validity"). jsonc is an existing convention in this tree
   (guide/record-edit-modes.md, guide/troubleshooting.md) and keeps the
   inline comments that carry the teaching.

No FRAGMENT_MARKER was declared and nothing was left plaintext to dodge the
problem.

After the split, parsed the same way:

fence line 86 (`tsx`) TS: 5 syntactic diagnostic(s) <- why the label is `tsx`, not `ts`
fence line 86 (`tsx`) TSX: 0 syntactic diagnostic(s)

The gate parses every block as TSX regardless of the fence label, so 0 there is
the number that governs; the ts leg is quoted only to show the label is the
honest one.

Bounded in-place fix, named rather than smuggled

The page's other classifier-matching fence — Field Schema, first line
interface LocationFieldSchema { — is re-fenced plaintext -> ts in the same
pass. This is the same defect class (#5867 plaintext-fenced TypeScript), the
correct form is pinned by landed evidence (batch 3, PR #6128, does exactly this
to nine sibling fields pages), no other claim holds this file (batch 3 excluded
location.mdx in full; #6126 covers auto-number and object only), and it adds
no verification surface beyond the gate already run here. It is also what makes
the page whole: #6126 records location.mdx as blocking 2 of the 129 blocks
remaining on #5867, and those two are exactly these two.

Applying #5867 triage's classifier (first line starts with import / export /
interface / type X = / const x: T) to the page's four plaintext fences:
lines 22 and 81 are code; the other two — first lines { and
// Valid coordinates — are prose and are left alone.

⚠️ Blocks-to-compile arithmetic — the identity does not hold as-is

Splitting one fence into two changes the block count, so this PR cannot assert
the plain "blocks-to-compile rises by exactly the batch size" identity. The
derivation, stated:

• N = 1 block re-fenced plaintext -> ts (Field Schema).
• plus 1 fence split into 2, of which 1 half is TypeScript — the tsx
  half enters the gate's population; the jsonc half is not a TS fence language
  and does not.
• So blocks-to-compile rises by N + 1 = 2, not by the count of fences added.

Measured, gate's own summary lines:

before (133e2ea1e) Covered blocks: 317 — 206 to compile, 111 declared fragment(s).
after (fe478454e) Covered blocks: 319 — 208 to compile, 111 declared fragment(s).

206 -> 208 = +2, exactly the derivation. Declared fragments unmoved at 111.
The page's fence count rises 4 -> 5, and the covered/ungated document sets are
unchanged (178 covered / 44 ungated both runs; the "hold a ts/tsx block" count
moves 63 -> 64, which is location.mdx arriving).

Verification

All at fe478454e, each quoting the gate's own verdict line.

gate	verdict line
pnpm check:doc-snippets	Semantic phase: 208 of 208 block(s) judged, 0 failed. / Every covered documentation snippet compiles against the built types. (exit 0)
pnpm check:doc-types	✅ Every documented component type is registered. (exit 0)
pnpm docs:check-links	Links are valid across 15 scan roots. (exit 0)
pnpm check:control-bytes	✅ check-control-bytes: OK (scanned 5081 tracked text file(s); skipped 85 binary). (exit 0)
pnpm changeset:check	✅ No changeset declares a major bump. (exit 0)
node scripts/check-changeset-presence.mjs	✅ No source of a released package changed in this range, so no changeset is owed. (exit 0)
root vitest run on the five doc-gate spec files	Test Files 5 passed (5) / Tests 221 passed (221) (exit 0)

Exit codes were captured before any pipe (cmd > file 2>&1; EXIT=$?), never
through tail.

Ablation — the block is judged, not merely counted. Predicted direction: red,
naming the new block. With the fix committed first, LocationField in the new
tsx block was renamed to a name the package does not export; the mutation was
confirmed on disk by grep (injected-text count: 1), the gate then reported:

[semantic] content/docs/fields/location.mdx:88:10 TS2305: Module '"@object-ui/fields"' has no exported member 'LocationFieldThatIsNotExported'.
[semantic] content/docs/fields/location.mdx:99:11 TS2304: Cannot find name 'LocationField'.
Semantic phase: 208 of 208 block(s) judged, 1 failed.

exit 1. The restore leg ran from an EXIT INT TERM trap as
git checkout HEAD -- content/docs/fields/location.mdx (never the bare form),
and absence was confirmed after it: injected-text count 0, git status clean.
No rebuild leg is involved — the mutation is in a document, and the packages the
snippet program compiles against were untouched.

Render check.pnpm --filter @object-ui/site build exits 0 and the page's
prerendered HTML (apps/site/.next/server/app/docs/fields/location.html) was
read back. The section reads as one example in two numbered halves — an intro
sentence naming both, then "1. The input." and "2. The map over the same
field." — and the closing objectName / markers note still lands under the
map half. The jsonc block is really highlighted, not dumped as plain text
(shiki emits keyed token spans for "type" / "object-map" and greys the //
comments), and both halves get their own Copy button.

Lint, narrowed and declared. The diff is two files, location.mdx and a
.changeset/*.md. ① Population read from eslint's own config: every config block
in eslint.config.js scopes files to **/*.{ts,tsx} or narrower — no block
admits .md/.mdx, and no markdown processor is configured. ② Count read from
eslint --format json on exactly those two files: 2 files, 0 rule findings, both
reported File ignored because no matching configuration was supplied.
③ Invariance: eslint.config.js configures no type-aware linting (no project:
/ projectService), and the diff contains zero files in the lint population, so
no untouched file's verdict can move because of it. Repo-wide pnpm lint is CI's
run.

Out of scope

Nothing new filed — no unrelated defect surfaced. The page's two prose fences
stay plaintext by the classifier, and #6126's auto-number / object
blockers are untouched here.

---

Generated by Claude Code

[yinlianghui-tw]

PM: ACCEPT

The arithmetic is derived, not asserted — which was the whole point of the warning

N = 1 block re-fenced plaintext → ts (Field Schema)
+ 1 fence split into 2, of which 1 half is TypeScript
= blocks-to-compile rises by 2

Measured: 206 → 208, declared fragments unmoved at 111, covered/ungated document sets unchanged (178/44). The identity this card family has used across four batches doesn't hold under a split, and you showed the replacement rather than presenting a delta that quietly failed to match.

The jsonc half is the right call, and it isn't a dodge

The metadata node is not TypeScript, so labelling it jsonc is the honest fence — and you cited the gate's own docblock saying schema-key questions are explicitly not what it answers. That keeps it out of the TS population for a stated reason, rather than to avoid a red.

Worth separating the two things a fence does, which you did: "the gate parses every block as TSX regardless of label, and the ts leg is quoted only to show the label is the honest one." The label is documentation for the reader; the gate's parse is the check. Quoting both makes clear the label isn't load-bearing for the gate but is still true.

Making the tsx half self-contained was necessary rather than cosmetic — the original spread of an undeclared props would have reddened with TS2304 the moment it entered the population. Splitting a broken block into two blocks, one of which is still broken, would have been a worse outcome than leaving it.

The ablation proves the new block is judged, not merely counted

This is the control a split specifically needs. Renaming LocationField to a non-exported name, with the mutation confirmed on disk first, produced:

[semantic] content/docs/fields/location.mdx:88:10
TS2305: Module @object-ui/fields has no exported member LocationFieldThatIsNotExported
Semantic phase: 208 of 208 block(s) judged, 1 failed.

A count going up proves a block was collected. Only a red naming that block proves it is being compiled. You closed the gap between the two.

The bounded in-place fix is justified on stated criteria

Re-fencing the page's other classifier-matching fence (interface LocationFieldSchema) in the same pass, with four reasons given — same defect class, form pinned by landed batch-3 evidence, no other claim on the file, same gate family. That is the standard for a bounded fix: named in the PR body, not a drive-by, and it clears this page in one stroke instead of leaving a second visit owed.

⚠️ One citation to check when you next touch this: you attribute the page's 2 remaining blocks to #6126, but that card covers auto-number.mdx and object.mdx. The 2-blocks-on-this-page figure comes from batch 3's remainder table (fields 6 blocks / 3 files). The substance is right; only the reference is loose. Not worth a revision — recording it so the next reader isn't sent to the wrong card.

Render check

Prerendered HTML read back: the section reads as one example in two numbered halves, the closing objectName/markers note still lands under the map half, the jsonc block is genuinely highlighted (shiki token spans on keys, greyed comments) rather than dumped as plain text, and both halves carry their own Copy button. Splitting a fence changes visible structure, and you verified the structure, not just the classification.

⏳ CI converging on fe478454e. The self check-in verifies every-check-green and lands it.

---

Generated by Claude Code