feat: implement fine-grained rerendering control with an async Lit directive

An async Lit directe `subscribe` is implemented to allow for fine-grained reactivity and rerendering of templates.
To support this, `@tanstack/lit-store` is integrated.

Author: fredericbahr

docs/framework/lit/guide/table-state.md

@@ -71,7 +71,7 @@ There are two different questions when reading table state:
 - Do you only need the current value?
 - Or should the Lit host update when that value changes?
 
-Use a direct atom or store read for the current value. Use `table.state` or `table.Subscribe` in render output when the host should reflect selected table state.
+Use a direct atom or store read for the current value. Use `table.state` or `table.subscribe` in render output when the host should reflect selected table state.
 
 #### Reading State Without Subscribing
 
@@ -89,7 +89,7 @@ const tableState = table.store.state
 const pagination = table.store.state.pagination
 ```
 
-These reads are current-value reads. The `TableController` handles host invalidation through its subscriptions to the table store and options store. If the UI needs to stay reactive to table state changes, use `table.state`, `table.Subscribe`, or a TanStack Store subscription.
+These reads are current-value reads. The `TableController` handles host invalidation through its subscriptions to the table store and options store. If the UI needs to stay reactive to table state changes, use `table.state`, `table.subscribe`, or a TanStack Store subscription.
 
 #### Reading Reactive State with TableController
 
@@ -113,22 +113,28 @@ const table = this.tableController.table(
 table.state.pagination
 ```
 
-#### Selecting State with table.Subscribe
+#### Selecting State with table.subscribe
 
-Use `table.Subscribe` in templates to select a slice of table state while rendering.
+Use `table.subscribe` in templates to select a slice of table state while rendering.
 
 ```ts
-${table.Subscribe({
-  selector: (state) => ({
-    pagination: state.pagination,
-  }),
-  children: ({ pagination }) => html`
+private paginationSelector = (state) => ({
+  pagination: state.pagination,
+})
+
+${table.subscribe(
+  table.store,
+  this.paginationSelector,
+  ({ pagination }) => html`
     <span>Page ${pagination.pageIndex + 1}</span>
   `,
-})}
+)}
 ```
 
-`table.Subscribe` can also accept a `source`, but in the current Lit adapter host invalidation is wired through the full `table.store` subscription. Treat source mode as a render-time selection convenience, not a guarantee of source-only host invalidation.
+The template will only be evaluated when the selected state slice changes. The `table.subscribe` API is useful for fine-grained reactivity in templates.
+It is important to provide a stable reference for the selector function to avoid unnecessary re-renders. You can define the selector as a class property or method to ensure it remains stable across renders.
+
+
 
 ### Setting Table State
 

docs/framework/lit/lit-table.md

@@ -39,16 +39,26 @@ const columns: Array<ColumnDef<typeof features, Person>> = [
 export class PeopleTable extends LitElement {
   private tableController = new TableController<typeof features, Person>(this)
 
+  private table = this.tableController.table({
+    features,
+    rowModels: {},
+    columns,
+    data: this.data,
+  })
+
   @state()
   private data: Person[] = []
 
+  protected updated(changedProperties: Map<string, unknown>) {
+    if (changedProperties.has('data')) {
+      this.table.setOption((prev) => ({
+        ...prev,
+        data: this.data,
+      }))
+    }
+  }
+
   protected render() {
-    const table = this.tableController.table({
-      features,
-      rowModels: {},
-      columns,
-      data: this.data,
-    })
 
     return html`...`
   }

examples/lit/basic-subscribe/README.md

@@ -0,0 +1,27 @@
+# Example: Basic Subscribe
+
+This example demonstrates fine-grained state subscriptions using `SubscribeController` for optimized rendering in Lit.
+
+**Key Features:**
+
+- **Fine-grained subscriptions**: Each part of the table subscribes only to the state it needs
+- **SubscribeController**: A new Lit ReactiveController that handles store/atom subscriptions declaratively
+- **External atoms**: State management via `createAtom` from `@tanstack/store` for full control
+- **Performance optimized**: Only affected UI elements re-render when their subscribed state changes
+
+**What this shows:**
+
+1. Global filter input that re-renders only when global filter changes
+2. Table rows that re-render only when filtering/pagination state changes
+3. Pagination controls that re-render only when pagination state changes
+4. Row selection summary that re-renders only when selection changes
+5. Full table state display for debugging
+
+This pattern is ideal for large tables where you want to minimize unnecessary re-renders and have precise control over which components subscribe to which state slices.
+
+## Running the Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm run start` or `yarn start`

examples/lit/basic-subscribe/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>TanStack Lit Table - Basic Subscribe</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+    <lit-table-example></lit-table-example>
+  </body>
+</html>

examples/lit/basic-subscribe/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "tanstack-lit-table-example-basic-subscribe",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "serve": "vite preview",
+    "start": "vite",
+    "lint": "eslint ./src"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^10.4.0",
+    "@tanstack/lit-store": "^0.13.2",
+    "@tanstack/lit-table": "^9.0.0-beta.6",
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@rollup/plugin-replace": "^6.0.3",
+    "typescript": "6.0.3",
+    "vite": "^8.0.16"
+  }
+}