`@polymech/ui-next`

A focused proof-of-concept for the next Polymech web shell: React 18, TypeScript, native ESM, and TanStack Router with patterns we intend to use when migrating away from React Router v6.

This package is a sandbox, not a published library. It exists so we can try routing, typing, and UX behaviors in isolation before rolling them into production apps such as pm-pics or shared bundles like @polymech/ecommerce.

Why this stack

Capability	What we gain
Static route tree + typed links	Invalid routes and broken `to` values surface at compile time instead of in QA.
`validateSearch` + Zod	Query strings for tabs, filters, and view modes are parsed and typed once on the route.
Loaders	Data can load with the route, reducing `useEffect` + client fetch waterfalls on big pages.
Scroll restoration	First-class support via `createRouter({ scrollRestoration: true })`, with demos that prove behavior—including lazy-split route chunks.
Router subscriptions	`router.subscribe('onResolved', …)` gives a single place for analytics and instrumentation.

The detailed mapping from React Router habits to TanStack APIs lives in src/examples/migration/MIGRATION_EXAMPLES.md.

Quick start

This workspace uses npm for this package (no pnpm required here).

cd packages/ui-next
npm install
npm run dev

Open the app and use the header or /examples to walk through interactive migration examples (dynamic params, splat, typed search, loaders, redirects, 404, scroll proofs, lazy routes). For the widget registry, plugins, and extension slots scaffold (aligned with packages/ui/docs/widgets-api.md), open /examples/widgets-system or browse src/widgets/.

npm run build    # tsc --noEmit && vite build
npm run preview  # production build preview

Project layout

Path	Purpose
`src/router.tsx`	Root layout, `createRouter`, scroll restoration, global 404
`src/main.tsx`	`RouterProvider`, dev-only `router.subscribe` stub for analytics
`src/examples/migration/`	Runnable demos + `MIGRATION_EXAMPLES.md`
`src/widgets/`	Widget registry, `PluginManager`, `PluginAPI`, hooks, `ExtensionSlot`; demo at `/examples/widgets-system` · Architecture diagrams
`vite.config.ts`	Vite + React; comment shows where `TanStackRouterVite` plugs in for file-based routes later
`tsconfig.json`	Extends `../typescript-config/base.json`, tuned for Vite + `bundler` resolution

What “compelling” looks like here

Scroll restoration: /examples/scroll-restoration uses a live window.scrollY HUD. Scroll, navigate away, hit Back—position is restored, not reset to zero.
Lazy route + same restoration: /examples/lazy-scroll-restoration loads UI from a separate JS chunk (lazyRouteComponent + dynamic import). Production builds list a dedicated LazyScrollRestorationChunk-*.js asset; scroll behavior matches the non-lazy demo.

Relationship to the monorepo

@polymech/ui-next is a packages/* workspace member. Host applications may stay on their current router until migration phases are scheduled; this package does not replace them—it informs the migration plan with working code and checklists.

License

Private to the Polymech monorepo; not published to npm.

3.6 KiB Raw Blame History

@polymech/ui-next