feat(meta-to-blocks): lower _meta to a navigation document

[pyramation]

Summary

A console needs a way in before it needs screens, and the table list is already in _meta. This adds the one part of auto-admin that needs no query runtime: navigation as a document.

metaToNavDocument(tables, options?) // Page > Nav > NavGroup (per schema) > NavLink (per table)

The lowering is a pure function in meta-to-blocks (src/nav.ts), so a sidebar follows the database instead of a hand-maintained route list:

• one NavGroup per schemaName (titleized, count of its links), or flat: true for a single group;
• junction tables are dropped — they are discovered from table.relations.manyToMany[].junctionTable.name, not by name heuristics — unless includeJunctionTables is set;
• href, label, tables / omitTables, tableOrder, schemaLabels, and per-table overrides (label, href, icon, omit) are the customization surface; the default route is `/${table.name}`.

blocks-ui registers the three types. NavLink is a plain anchor and takes its current state from the scope rather than a second source of truth:

const active = props.active === true || scope.pathname === href;

A node with a click action gets preventDefault + onAction, so a host keeps client-side routing either through actions or by overriding NavLink with its framework's Link.

Nav, NavGroup, NavLink join BLOCK_NODE_TYPES in blocks-schema, which is additive — the vocabulary is a superset, so existing documents and registries are unaffected.

Rendering

/blocks/documents gains a "Navigation from database metadata" section: six fixture tables across two schemas render as a live sidebar next to the generated JSON, with a scope.pathname selector so the active-link behavior is visible. The join table (post_categories) is absent from the nav by construction. Docs links are hash-based to keep the static-page reference check satisfied; the code sample shows the real /admin/:schema/:table route builder.

Verification

pnpm check and pnpm build:pages pass. 8 new tests (5 lowering, 3 rendering).

Link to Devin session: https://app.devin.ai/sessions/027937d092794c92a31c6ee49c513f59
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[tenki-reviewer]

Review complete. No issues found — approved ✅.

---

This PR introduces an end-to-end navigation feature across three packages plus docs and demos. packages/blocks-schema/src/node.ts registers Nav, NavGroup, and NavLink in BLOCK_NODE_TYPES. packages/meta-to-blocks adds nav.ts/types.ts/index.ts exposing metaToNavNodes, parseNavDocument, and NavOptions/NavTableOverride, lowering _meta tables (with join-table omission, schema grouping, and per-table label/href/omit overrides) into a nav document. packages/blocks-ui adds nav.tsx (active-link highlighting, click-action deferral, aria-current), registry.ts, and index exports for the new Nav block, with tests in both packages. apps/blocks adds a documents page and showcase demo; READMEs and package manifests are updated. Review found no findings meeting the confidence threshold; several candidate issues (href scheme sanitization, flat-mode <li> wrapping, junction schema-qualification, CHILD_BEARING_BLOCKS coverage) were verified but fell below the keep threshold and are noted as lower-confidence considerations rather than blocking findings.

Files	Change
packages/blocks-schema/src/node.ts	Registers Nav/NavGroup/NavLink block node types.
packages/meta-to-blocks/src/{nav,types,index}.ts	Adds _meta-table-to-nav-document lowering with NavOptions/NavTableOverride.
packages/blocks-ui/src/{nav,registry,index}.tsx/.ts	Adds the Nav renderer, registry entry, and public exports.
apps/blocks + READMEs + package.json	Adds documents page, showcase demo, and docs; wires workspace deps.

_{Reviewed commit: 0cb7e50}

[devin-ai-integration]

Runtime verification — nav document from _meta

Docs app dev server on feat/meta-nav, /blocks/documents → "Navigation from database metadata".

Default render — groups, counts, and join-table drop

• APP PUBLIC count 3 → Posts, Categories, Users; APP PRIVATE count 2 → Audit log entries, Feature flags.
• post_categories (the manyToMany junction) appears nowhere: 0 occurrences in the rendered DOM, absent from the generated JSON, absent from the scope.pathname select (5 options).
• JSON panel renders Page > Nav > NavGroup(count) > NavLink(href/table/schemaName/description) and scrolls inside its own box.

scope.pathname drives the active link

#app_private/feature_flags	#app_public/categories

Each change moves both the accent highlight and aria-current="page"; exactly one nav-demo anchor is current at a time.

Light theme

No console errors or hydration warnings.

Labels are sentence case ("Audit log entries") because they go through the existing titleize in meta-to-blocks, which is what form labels and column headers already use — left as-is for consistency rather than special-cased for nav.