mono/packages/ui-next

@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.