@furystack/shades 11.1.0 → 12.0.1

package/src/components/nested-route-link.tsx

@@ -0,0 +1,100 @@
+import { compileRoute } from '../compile-route.js'
+import type { ChildrenList } from '../models/children-list.js'
+import type { PartialElement } from '../models/partial-element.js'
+import { LocationService } from '../services/location-service.js'
+import { createComponent } from '../shade-component.js'
+import { Shade } from '../shade.js'
+import type { ExtractRouteParams, ExtractRoutePaths } from './nested-route-types.js'
+import type { NestedRoute } from './nested-router.js'
+
+/**
+ * Props for the NestedRouteLink component.
+ * Combines SPA navigation from RouteLink with parameter compilation from LinkToRoute.
+ */
+export type NestedRouteLinkProps = {
+  href: string
+  params?: Record<string, string>
+} & PartialElement<Omit<HTMLAnchorElement, 'onclick' | 'href'>>
+
+/**
+ * Props for a type-safe nested route link.
+ * When the path contains parameters (e.g. `:id`), the `params` prop becomes required.
+ * @typeParam TPath - A specific route path string
+ */
+export type TypedNestedRouteLinkProps<TPath extends string> = {
+  href: TPath
+} & (string extends keyof ExtractRouteParams<TPath>
+  ? { params?: Record<string, string> }
+  : { params: ExtractRouteParams<TPath> }) &
+  PartialElement<Omit<HTMLAnchorElement, 'onclick' | 'href'>>
+
+const _NestedRouteLink = Shade<NestedRouteLinkProps>({
+  shadowDomName: 'nested-route-link',
+  elementBase: HTMLAnchorElement,
+  elementBaseName: 'a',
+  css: {
+    color: 'inherit',
+    textDecoration: 'inherit',
+  },
+  render: ({ children, props, injector, useHostProps }) => {
+    const { href, params } = props
+    const resolvedUrl = params ? compileRoute(href, params) : href
+
+    useHostProps({
+      href: resolvedUrl,
+      onclick: (ev: MouseEvent) => {
+        ev.preventDefault()
+        history.pushState('', props.title || '', resolvedUrl)
+        injector.getInstance(LocationService).updateState()
+      },
+    })
+    return <>{children}</>
+  },
+})
+
+/**
+ * A link component for NestedRouter that supports SPA navigation with
+ * type-safe route parameter compilation.
+ *
+ * Intercepts click events to use `history.pushState` for client-side navigation,
+ * and compiles parameterized routes (e.g. `/users/:id`) when `params` is provided.
+ *
+ * Route parameters are automatically inferred from the `href` pattern:
+ * - `href="/buttons"` — `params` is optional
+ * - `href="/users/:id"` — `params: { id: string }` is required
+ *
+ * For additional URL validation against a route tree, use {@link createNestedRouteLink}.
+ */
+export const NestedRouteLink = _NestedRouteLink as unknown as <TPath extends string = string>(
+  props: TypedNestedRouteLinkProps<TPath>,
+  children?: ChildrenList,
+) => JSX.Element
+
+/**
+ * Creates a type-safe wrapper around NestedRouteLink constrained to a specific route tree.
+ * The returned component has the same runtime behavior but narrows `href` to only accept
+ * valid route paths, and requires `params` when the route has parameters.
+ *
+ * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
+ * @returns A narrowed NestedRouteLink component
+ *
+ * @example
+ * ```typescript
+ * const AppLink = createNestedRouteLink<typeof appRoutes>()
+ *
+ * // Type-safe: only valid paths accepted
+ * <AppLink href="/buttons">Buttons</AppLink>
+ *
+ * // TypeScript error: invalid path
+ * <AppLink href="/nonexistent">Error!</AppLink>
+ *
+ * // Params required for parameterized routes
+ * <AppLink href="/users/:id" params={{ id: '123' }}>User</AppLink>
+ * ```
+ */
+export const createNestedRouteLink = <TRoutes extends Record<string, NestedRoute<unknown>>>() => {
+  return _NestedRouteLink as unknown as <TPath extends ExtractRoutePaths<TRoutes>>(
+    props: TypedNestedRouteLinkProps<TPath>,
+    children?: ChildrenList,
+  ) => JSX.Element
+}

package/src/components/nested-route-types.ts

@@ -0,0 +1,42 @@
+import type { NestedRoute } from './nested-router.js'
+
+/**
+ * Concatenates parent and child route paths, handling the '/' root specially
+ * to avoid double slashes.
+ * @typeParam Parent - The parent route path
+ * @typeParam Child - The child route path
+ */
+export type ConcatPaths<Parent extends string, Child extends string> = Parent extends '/' ? Child : `${Parent}${Child}`
+
+/**
+ * Recursively extracts all valid full URL paths from a nested route tree.
+ * @typeParam T - A record of route patterns to NestedRoute definitions
+ */
+export type ExtractRoutePaths<T extends Record<string, NestedRoute<unknown>>> = {
+  [K in keyof T & string]:
+    | K
+    | (T[K] extends { children: infer C extends Record<string, NestedRoute<unknown>> }
+        ? ConcatPaths<K, ExtractRoutePaths<C> & string>
+        : never)
+}[keyof T & string]
+
+/**
+ * Extracts route parameter names from a URL pattern and creates a record type
+ * mapping each parameter name to `string`.
+ * Returns `Record<string, never>` when no parameters are present.
+ * @typeParam T - A URL pattern string potentially containing `:param` segments
+ */
+export type ExtractRouteParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
+  ? { [K in Param | keyof ExtractRouteParams<`/${Rest}`>]: string }
+  : T extends `${string}:${infer Param}`
+    ? { [K in Param]: string }
+    : Record<string, never>
+
+/**
+ * A recursive type for validating URL constant objects against a set of valid paths.
+ * Leaf values must be valid route paths, and intermediate values can be nested UrlTree objects.
+ * @typeParam TPaths - Union of valid route path strings
+ */
+export type UrlTree<TPaths extends string> = {
+  [key: string]: TPaths | UrlTree<TPaths>
+}