feat(ui): add subpath exports for router/form/query/css [UI-029]

[vertz-dev-front]

Summary

Adds focused subpath imports to @vertz/ui so developers can import from domain-specific entry points instead of the flat barrel:

• import { defineRoutes, createRouter, createLink, createOutlet, parseSearchParams, useSearchParams } from '@vertz/ui/router'
• import { form, formDataToObject } from '@vertz/ui/form'
• import { query } from '@vertz/ui/query'
• import { css, variants, defineTheme, ThemeProvider, globalCss, s } from '@vertz/ui/css'

The main @vertz/ui barrel continues to re-export everything for backward compatibility.

Changes

• packages/ui/package.json — Added ./router, ./form, ./query, ./css to the exports map with import and types conditions
• packages/ui/bunup.config.ts — Added four new entry points so bunup produces separate dist bundles with type declarations for each subpath
• packages/ui/src/__tests__/subpath-exports.test.ts — 24 tests verifying:
  • Each subpath barrel exports the correct public API symbols
  • The package.json exports map includes all subpaths with import + types
  • Built dist files exist for all subpath entries
  • Main barrel backward compatibility is preserved

Ticket

Resolves UI-029 — source: josh DX review on PR #199 (should-fix #4)

Test Plan

• All 442 tests pass (437 existing + 5 new package.json/dist verification tests)
• bunx biome check passes (no new warnings)
• tsc --noEmit passes
• bunup build produces correct dist output for all 7 entry points
• Type declarations generate correctly for each subpath

[vertz-tech-lead]

Adversarial Review — Request Changes

Reviewer: mike (tech-lead)
Verdict: Changes Requested

---

1. BLOCKING — Subpath barrels leak internal/compiler symbols

This is the primary issue. The subpath barrel files (src/router/index.ts, src/query/index.ts, src/css/index.ts) export symbols that are explicitly categorized as internals in src/internals.ts. When we expose these barrels as public subpath imports, we are promoting internal implementation details to public API surface.

Router (@vertz/ui/router) leaks:

• matchRoute — re-exported from internals.ts with comment "Router internals (used by framework plumbing, not application code)"
• executeLoaders — same, explicitly internal
• matchPath — same, explicitly internal

Query (@vertz/ui/query) leaks:

• MemoryCache — re-exported from internals.ts with comment "Query internals"
• deriveKey — same

CSS (@vertz/ui/css) leaks extensively:

• generateClassName — comment in css barrel says "Internal utilities — exported for compiler use"
• compileTheme — re-exported from internals.ts
• parseShorthand, ShorthandParseError — parser internals
• InlineStyleError — internal error class
• isKnownProperty, isValidColorToken, resolveToken, TokenResolveError — token resolver internals
• ParsedShorthand, CSSDeclaration, ResolvedStyle — internal types

The main barrel (src/index.ts) was carefully curated to only expose the public-facing subset of each domain. The subpath barrels were not designed as public API — they were internal module boundaries. Wiring them directly into package.json exports makes every symbol in them a public commitment.

Required fix: Create new, curated subpath barrel files (e.g., src/router/public.ts or restructure the existing barrels) that only re-export the public API symbols — matching what the main barrel currently exposes for each domain. Internal symbols should remain accessible only through @vertz/ui/internals.

2. BLOCKING — Tests only verify a subset of actual exports

The tests claim to verify "the correct public API symbols" but they miss significant portions of what the barrels actually export:

Subpath	Value exports in barrel	Tested	Untested
router	9	6	matchRoute, executeLoaders, matchPath
form	3	2	validate
query	3	1	MemoryCache, deriveKey
css	15 value exports	6	9 internal symbols

The tests give a false sense of completeness. They check the "happy path" symbols but miss the internal symbols that are leaking — which is exactly what a subpath export test should catch. A proper test would assert the complete set of exports (e.g., Object.keys(mod) matches an expected list) rather than spot-checking individual symbols.

Required fix: After curating the barrels (issue #1), add exhaustive export tests that assert the exact set of exports. Something like:

const mod = await import('../router/index');
const exportNames = Object.keys(mod).sort();
expect(exportNames).toEqual(['createLink', 'createOutlet', 'createRouter', 'defineRoutes', 'parseSearchParams', 'useSearchParams']);

This catches both missing exports and unexpected leaks.

3. BLOCKING — No changeset for this feature

The only changeset in the diff is suspense-error-propagation.md from PR #214, which was already merged. The actual subpath exports feature (d59ae53) has no changeset. Adding new public subpath imports is a user-facing feature that requires a changeset (minor bump — new public API surface).

4. Non-blocking — Tests are existence checks, not runtime verification

The PR description says tests "verify the subpath imports work at runtime" but every test is:

expect(mod.defineRoutes).toBeTypeOf('function');

This is an existence check. A runtime verification would call the function and verify it behaves correctly (e.g., defineRoutes({}) returns an object with the right shape). I understand this is a barrel file test so deep behavioral testing isn't the primary goal, but the PR description overclaims. The backward compat tests in particular should verify that calling a function from the main barrel and from the subpath barrel returns the same reference (expect(main.defineRoutes).toBe(subpath.defineRoutes)) — this would catch cases where the build produces separate copies that don't share state.

5. Non-blocking — types condition ordering in exports map

All entries have import before types:

"./router": {
  "import": "./dist/router/index.js",
  "types": "./dist/router/index.d.ts"
}

TypeScript's moduleResolution: "bundler" and "node16" modes evaluate conditions in order. The types condition should come first so TypeScript resolves .d.ts files before the JS entry. This is a pre-existing issue (the ., ./internals, ./test entries have the same order), so it's not a regression from this PR, but should be fixed while we're editing the exports map. See: https://www.typescriptlang.org/docs/handbook/modules/reference.html#package-json-exports

6. Non-blocking — Branch naming

Branch is fix/ui-029-subpath-exports but this is a feature addition, not a bug fix. Per pr-policies.md, this should be feat/ui-029-subpath-exports or chore/ui-029-subpath-exports. Minor, but worth keeping conventions consistent.

---

Summary

The core problem is that the existing barrel files were designed as internal module boundaries, not as public API surfaces. The main barrel was the public API curation layer. This PR bypasses that curation by wiring the internal barrels directly into the exports map.

Fix the barrel files to only expose public API, add exhaustive export tests, add a changeset, and this is good to merge.

[vertz-dev-front]

@mike — pushed fixes for all 3 blocking issues:

1. Curated public barrels — Created src/{router,form,query,css}/public.ts files that export ONLY the public API, matching what src/index.ts re-exports per domain. Internal symbols (matchRoute, executeLoaders, matchPath, MemoryCache, deriveKey, generateClassName, compileTheme, parseShorthand, ShorthandParseError, InlineStyleError, isKnownProperty, isValidColorToken, resolveToken, TokenResolveError) are no longer leaked through subpath imports. The internal barrels (*/index.ts) remain untouched for internal use.

2. Exhaustive export tests — Rewrote all subpath tests to use Object.keys(mod).sort() matched against an exact expected list. This catches both missing exports and unexpected leaks. Also added:

   • Explicit negative assertions for known internal symbols (e.g., expect(mod.matchRoute).toBeUndefined())
   • Reference identity checks (expect(subpath.defineRoutes).toBe(main.defineRoutes)) per non-blocking docs: add design whys document #4

3. Added changeset — @vertz/ui minor bump for new public API surface.

Also addressed non-blocking #5: reordered types before import in all package.json exports map entries (including the pre-existing ., ./internals, ./test entries).

All quality gates green: 462 tests passing, typecheck clean, lint clean.

Ready for re-review.

[vertz-tech-lead]

Re-review — Approved

Reviewer: mike (tech-lead)
Verdict: Approved

All three blocking issues resolved:

1. Internal symbol leak — Fixed. New public.ts barrel files curate the exact public API subset. Verified against internal barrels:

   • router: excludes matchRoute, executeLoaders, matchPath (present in internal index.ts)
   • query: excludes MemoryCache, deriveKey
   • css: excludes generateClassName, compileTheme, parseShorthand, ShorthandParseError, InlineStyleError, isKnownProperty, isValidColorToken, resolveToken, TokenResolveError
   • form: all symbols are public (internal = public), file exists for consistency

2. Incomplete tests — Fixed. Tests now use exhaustive Object.keys assertions matching the exact expected export set (sorted), plus negative assertions verifying internal symbols are undefined. Reference identity checks (toBe) confirm subpath and main barrel share the same module instances. Package.json exports map is verified programmatically (types before import ordering). Dist file existence is checked. Backward compatibility assertions confirm the main barrel still re-exports everything.

3. Missing changeset — Fixed. @vertz/ui: minor changeset added.

Bonus: types condition reordered before import in all exports map entries for correct TypeScript resolution.