@tempots/ui 5.2.2 → 6.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "5.2.2",
+  "version": "6.0.1",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderables/router/router-context.d.ts

@@ -0,0 +1,96 @@
+import { Provider, Prop } from '@tempots/dom';
+/**
+ * Represents the context information for a router level in nested routing.
+ *
+ * Each router level (AppRouter or SubRouter) creates a RouterContext that contains
+ * information about the matched path, remaining path for child routers, and accumulated
+ * parameters from all parent router levels.
+ *
+ * @example
+ * ```typescript
+ * // For URL "/admin/users/123" with routes:
+ * // RootRouter: { '/admin/*': () => AdminRoutes() }
+ * // ChildRouter: { '/users/:id': (info) => UserDetail(info) }
+ *
+ * // RootRouter context:
+ * {
+ *   matchedPath: '/admin',
+ *   remainingPath: '/users/123',
+ *   fullPath: '/admin/users/123',
+ *   params: {}
+ * }
+ *
+ * // ChildRouter context:
+ * {
+ *   matchedPath: '/users/123',
+ *   remainingPath: '',
+ *   fullPath: '/admin/users/123',
+ *   params: { id: '123' }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface RouterContext {
+    /**
+     * The portion of the path that was matched by this router level.
+     * For RootRouter, this is the matched portion of the full pathname.
+     * For ChildRouter, this is the matched portion of the remaining path from parent.
+     */
+    readonly matchedPath: string;
+    /**
+     * The remaining path that should be processed by child routers.
+     * Empty string if no remaining path.
+     */
+    readonly remainingPath: string;
+    /**
+     * The full original pathname from the browser location.
+     * This remains the same across all router levels.
+     */
+    readonly fullPath: string;
+    /**
+     * Route parameters extracted at this router level.
+     * These are accumulated with parameters from parent router levels.
+     */
+    readonly params: Record<string, string>;
+}
+/**
+ * Provider for router context stack in nested routing scenarios.
+ *
+ * The RouterContextProvider maintains a stack of RouterContext objects,
+ * where each level represents a router in the nested hierarchy. Child
+ * routers can access the context stack to determine what path remains
+ * to be processed and what parameters have been accumulated from parent
+ * router levels.
+ *
+ * @example
+ * ```typescript
+ * // RootRouter creates the initial context
+ * const RootRouter = <T extends Routes>(routes: T) =>
+ *   Provide(
+ *     RouterContextProvider,
+ *     {},
+ *     () => {
+ *       // Router implementation that creates initial context
+ *       return Use(Location, location => {
+ *         // Match routes and create context...
+ *       })
+ *     }
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // ChildRouter reads parent context and adds its own
+ * const ChildRouter = <T extends Routes>(routes: T) =>
+ *   Use(RouterContextProvider, contextStack => {
+ *     const parentContext = contextStack.value[contextStack.value.length - 1]
+ *     const remainingPath = parentContext?.remainingPath || ''
+ *
+ *     // Match against remaining path and create new context...
+ *   })
+ * ```
+ *
+ * @public
+ */
+export declare const RouterContextProvider: Provider<Prop<RouterContext[]>>;

package/renderables/router/router.d.ts

@@ -1,100 +1,92 @@
 import { TNode, Renderable, Signal } from '@tempots/dom';
 import { ExtractParams, MakeParams, RouteInfo } from './route-info';
 /**
- * Creates a client-side router that maps URL patterns to renderable components.
+ * Creates the root router for an application that provides routing context to child components.
  *
- * The Router component provides declarative routing for single-page applications.
- * It automatically extracts route parameters from URLs and passes them to the
- * corresponding route handlers. The router integrates with the browser's history
- * API and updates the UI when the URL changes.
+ * RootRouter is the top-level router that matches against the full browser pathname
+ * and creates the initial routing context. It provides the RouterContextProvider
+ * that child ChildRouter components can use for nested routing scenarios.
  *
  * @example
  * ```typescript
- * // Basic routing setup
- * const AppRouter = Router({
+ * // Basic app routing
+ * const App = RootRouter({
  *   '/': () => html.div('Home Page'),
  *   '/about': () => html.div('About Page'),
- *   '/contact': () => html.div('Contact Page'),
+ *   '/admin/*': () => AdminSection(), // Passes remaining path to AdminSection
  *   '*': () => html.div('404 - Page Not Found')
  * })
  *
- * render(AppRouter, document.body)
+ * render(App, document.body)
  * ```
  *
  * @example
  * ```typescript
- * // Routes with parameters
- * const BlogRouter = Router({
- *   '/': () => html.div('Blog Home'),
- *   '/posts/:id': (info) => {
- *     const postId = info.$.params.$.id
- *     return html.div(
- *       html.h1('Post ID: ', postId),
- *       html.p('Loading post...')
- *     )
- *   },
- *   '/users/:userId/posts/:postId': (info) => {
- *     const userId = info.$.params.$.userId
- *     const postId = info.$.params.$.postId
- *     return html.div(
- *       html.h1('User ', userId, ' - Post ', postId),
- *       UserPost({ userId, postId })
- *     )
- *   },
- *   '*': () => html.div('Page not found')
+ * // Nested routing with RootRouter and ChildRouter
+ * const App = RootRouter({
+ *   '/': () => html.div('Home'),
+ *   '/admin/*': () => AdminRoutes(),
+ *   '/blog/*': () => BlogRoutes()
+ * })
+ *
+ * const AdminRoutes = ChildRouter({
+ *   '/users': () => html.div('User List'),
+ *   '/users/:id': (info) => html.div('User: ', info.$.params.$.id),
+ *   '/settings': () => html.div('Admin Settings')
  * })
  * ```
  *
+ * @template T - The type of the routes configuration object
+ * @param routes - Object mapping route patterns to handler functions
+ * @returns A renderable router component that handles URL routing and provides context
+ * @throws {Error} When no matching route is found for the current URL
+ * @public
+ */
+export declare const RootRouter: <T extends { [K in keyof T]: (info: K extends string ? Signal<RouteInfo<MakeParams<ExtractParams<K>>, K>> : never) => TNode; }>(routes: T) => Renderable;
+/**
+ * Creates a nested router that matches against the remaining path from parent routers.
+ *
+ * ChildRouter is used for nested routing scenarios where a parent router (RootRouter or
+ * another ChildRouter) has matched a portion of the path and passed the remaining path
+ * to child components. ChildRouter reads the parent routing context and matches its
+ * routes against the remaining path.
+ *
  * @example
  * ```typescript
- * // Using route info for navigation and data
- * const ProductRouter = Router({
- *   '/products': () => ProductList(),
- *   '/products/:id': (info) => {
- *     const productId = info.$.params.$.id
- *     const searchParams = info.$.search
+ * // Parent RootRouter passes remaining path to AdminRoutes
+ * const App = RootRouter({
+ *   '/admin/*': () => AdminRoutes(),
+ *   '/blog/*': () => BlogRoutes()
+ * })
  *
- *     return html.div(
- *       html.h1('Product ', productId),
- *       html.p('Search params: ', searchParams),
- *       ProductDetail({
- *         id: productId,
- *         variant: new URLSearchParams(searchParams.value).get('variant')
- *       })
- *     )
- *   },
- *   '/products/:id/reviews': (info) => {
- *     const productId = info.$.params.$.id
- *     return ProductReviews({ productId })
- *   }
+ * // ChildRouter matches against remaining path
+ * const AdminRoutes = ChildRouter({
+ *   '/users': () => html.div('User List'),
+ *   '/users/:id': (info) => html.div('User: ', info.$.params.$.id),
+ *   '/settings': () => html.div('Admin Settings'),
+ *   '*': () => html.div('Admin 404')
  * })
  * ```
  *
  * @example
  * ```typescript
- * // Programmatic navigation
- * import { Location } from '@tempots/ui'
+ * // Multiple levels of nesting
+ * const BlogRoutes = ChildRouter({
+ *   '/posts/*': () => PostRoutes(),
+ *   '/categories': () => html.div('Categories')
+ * })
  *
- * const Navigation = () => html.nav(
- *   html.button(
- *     on.click(() => Location.navigate('/')),
- *     'Home'
- *   ),
- *   html.button(
- *     on.click(() => Location.navigate('/about')),
- *     'About'
- *   ),
- *   html.button(
- *     on.click(() => Location.navigate('/products/123')),
- *     'Product 123'
- *   )
- * )
+ * const PostRoutes = ChildRouter({
+ *   '/': () => html.div('All Posts'),
+ *   '/:id': (info) => html.div('Post: ', info.$.params.$.id),
+ *   '/:id/comments': (info) => html.div('Comments for: ', info.$.params.$.id)
+ * })
  * ```
  *
  * @template T - The type of the routes configuration object
  * @param routes - Object mapping route patterns to handler functions
- * @returns A renderable router component that handles URL routing
- * @throws {Error} When no matching route is found for the current URL
+ * @returns A renderable router component that handles nested URL routing
+ * @throws {Error} When no matching route is found for the remaining path
  * @public
  */
-export declare const Router: <T extends { [K in keyof T]: (info: K extends string ? Signal<RouteInfo<MakeParams<ExtractParams<K>>, K>> : never) => TNode; }>(routes: T) => Renderable;
+export declare const ChildRouter: <T extends { [K in keyof T]: (info: K extends string ? Signal<RouteInfo<MakeParams<ExtractParams<K>>, K>> : never) => TNode; }>(routes: T) => Renderable;

package/renderables/size.d.ts

@@ -204,15 +204,6 @@ export declare function getAbsoluteRect(el: Element): Rect;
  * @public
  */
 export declare const ElementRect: (fn: (rect: Signal<Rect>) => TNode) => import('@tempots/dom').Renderable;
-/**
- * Creates a renderable function that monitors the size of an element and provides it as a signal.
- *
- * @param fn - The renderable function that receives the size signal and returns a TNode.
- * @returns A function that takes a DOMContext and returns a renderable function.
- * @deprecated use ElementRect instead
- * @public
- */
-export declare const ElementSize: (fn: (size: Signal<Rect>) => TNode) => import('@tempots/dom').Renderable;
 /**
  * Creates a renderable function that monitors the window size and invokes the provided function with the current size.
  * @param fn - The function to be invoked with the current window size.