lit-ui-router 1.2.4 → 1.2.5

package/README.md

@@ -7,4 +7,34 @@
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Flit-ui-router.dev)](https://lit-ui-router.dev)
 [![codecov](https://codecov.io/gh/simshanith/lit-ui-router/graph/badge.svg?component=lit-ui-router)](https://app.codecov.io/gh/simshanith/lit-ui-router?components%5B0%5D=lit-ui-router)
 
-A UI Router implementation for Lit.
+A [UI-Router](https://ui-router.github.io/) implementation for [Lit](https://lit.dev/).
+
+## Quick Start
+
+```ts
+import { UIRouterLit } from 'lit-ui-router';
+import { hashLocationPlugin } from '@uirouter/core';
+import { html } from 'lit';
+
+const router = new UIRouterLit();
+router.plugin(hashLocationPlugin);
+
+router.stateRegistry.register([
+  { name: 'home', url: '/', component: () => html`<h1>Home</h1>` },
+  { name: 'about', url: '/about', component: () => html`<h1>About</h1>` },
+]);
+
+router.start();
+```
+
+## Component Styles
+
+| Style               | Best For                      | Example                    |
+| ------------------- | ----------------------------- | -------------------------- |
+| Template function   | Simple views, prototyping     | `` () => html`...` ``      |
+| Template with props | Views needing params/resolves | `` (props) => html`...` `` |
+| LitElement class    | Complex views with lifecycle  | `MyComponent`              |
+
+## Documentation
+
+Visit [lit-ui-router.dev](https://lit-ui-router.dev) for full documentation, tutorials, and API reference.

package/dist/interface.d.ts

@@ -166,21 +166,31 @@ export interface UIViewInjectedProps<T extends DefaultResolvesType = DefaultReso
 /**
  * A function that returns a Lit TemplateResult for rendering in a `<ui-view>`.
  *
- * This is one of the component types that can be used in state declarations.
- * The function receives [[UIViewInjectedProps]] as its argument.
- * [[NormalizedLitViewDeclaration.component]] uses this signature.
+ * This is the **simplest way** to define route components - no LitElement class needed.
+ * The function optionally receives [[UIViewInjectedProps]] as its argument.
  *
- * @example
+ * @example Simple template (no props needed)
  * ```ts
- * const HomeView: RoutedLitTemplate = (props) => {
- *   return html`<h1>Welcome Home</h1>`;
- * };
+ * const HomeView: RoutedLitTemplate = () => html`<h1>Welcome Home</h1>`;
  *
- * router.stateRegistry.register({
- *   name: 'home',
- *   url: '/home',
- *   component: HomeView
- * });
+ * // Or use directly inline in a state declaration:
+ * { name: 'home', url: '/', component: () => html`<h1>Home</h1>` }
+ * ```
+ *
+ * @example With route parameters
+ * ```ts
+ * const UserView: RoutedLitTemplate = (props) => html`
+ *   <h1>User: ${props?.transition?.params().id}</h1>
+ * `;
+ * ```
+ *
+ * @example With resolved data (typed)
+ * ```ts
+ * interface UserResolves { user: { name: string } }
+ *
+ * const UserDetail: RoutedLitTemplate<UserResolves> = (props) => html`
+ *   <h1>${props?.resolves?.user?.name}</h1>
+ * `;
  * ```
  *
  * @category types
@@ -266,38 +276,51 @@ export type LitViewDeclaration<T extends DefaultResolvesType = DefaultResolvesTy
  * State declaration interface for Lit applications.
  *
  * Extends the core [[StateDeclaration]] with Lit-specific component support.
+ * The `component` property accepts template functions, LitElement classes, or both.
  *
- * @example Basic state with template function
+ * @example Simplest: inline template function
  * ```ts
- * const homeState: LitStateDeclaration = {
- *   name: 'home',
- *   url: '/home',
- *   component: () => html`<h1>Home</h1>`
- * };
+ * { name: 'home', url: '/', component: () => html`<h1>Home</h1>` }
+ * ```
+ *
+ * @example Template with route parameters
+ * ```ts
+ * {
+ *   name: 'user',
+ *   url: '/user/:id',
+ *   component: (props) => html`<h1>User ${props?.transition?.params().id}</h1>`
+ * }
  * ```
  *
- * @example State with LitElement class
+ * @example Template with resolved data
  * ```ts
- * const usersState: LitStateDeclaration = {
+ * {
  *   name: 'users',
  *   url: '/users',
- *   component: UserListElement,
- *   resolve: [
- *     { token: 'users', resolveFn: () => fetch('/api/users').then(r => r.json()) }
- *   ]
- * };
+ *   component: (props) => html`
+ *     <ul>${props?.resolves?.users?.map(u => html`<li>${u.name}</li>`)}</ul>
+ *   `,
+ *   resolve: [{ token: 'users', resolveFn: () => fetch('/api/users').then(r => r.json()) }]
+ * }
+ * ```
+ *
+ * @example LitElement class (for complex components)
+ * ```ts
+ * { name: 'dashboard', url: '/dashboard', component: DashboardElement }
  * ```
  *
  * @example Nested states
  * ```ts
  * const states: LitStateDeclaration[] = [
  *   { name: 'app', abstract: true, component: AppShell },
- *   { name: 'app.home', url: '/home', component: HomeView },
+ *   { name: 'app.home', url: '/home', component: () => html`<h1>Home</h1>` },
  *   { name: 'app.users', url: '/users', component: UsersView }
  * ];
  * ```
  *
  * @see [[StateDeclaration]]
+ * @see {@link RoutedLitTemplate}
+ * @see {@link RoutedLitElement}
  *
  * @category types
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lit-ui-router",
   "description": "State-based routing for Lit",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "type": "module",
   "module": "./dist/index.js",
   "homepage": "https://lit-ui-router.dev",