@rs-x/cli 2.0.0-next.15 → 2.0.0-next.16

package/templates/next-demo/components/demo-app.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { type FC, useEffect, useState } from 'react';
+
+import { initRsx } from '@/lib/rsx-bootstrap';
+
+import { VirtualTableShell } from './virtual-table-shell';
+
+type ThemeMode = 'light' | 'dark';
+
+function getInitialTheme(): ThemeMode {
+  const storedTheme = window.localStorage.getItem('rsx-theme');
+  if (storedTheme === 'light' || storedTheme === 'dark') {
+    return storedTheme;
+  }
+
+  return 'dark';
+}
+
+export const DemoApp: FC = () => {
+  const [theme, setTheme] = useState<ThemeMode>(() => getInitialTheme());
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+
+    void initRsx().then(() => {
+      if (active) {
+        setReady(true);
+      }
+    });
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+    document.body.setAttribute('data-theme', theme);
+    window.localStorage.setItem('rsx-theme', theme);
+  }, [theme]);
+
+  return (
+    <main className="app-shell">
+      <section className="hero">
+        <div className="container">
+          <div className="heroGrid">
+            <div className="heroLeft">
+              <p className="app-eyebrow">RS-X React Demo</p>
+              <h1 className="hTitle">Virtual Table</h1>
+              <p className="hSubhead">
+                Million-row scrolling with a fixed RS-X expression pool.
+              </p>
+              <p className="hSub">
+                This demo keeps rendering bounded while streaming pages on demand,
+                so scrolling stays smooth without growing expression memory with the
+                dataset.
+              </p>
+
+              <div className="heroActions">
+                <a
+                  className="btn btnGhost"
+                  href="https://www.rsxjs.com/"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  rs-x
+                </a>
+                <button
+                  type="button"
+                  className="btn btnGhost theme-toggle"
+                  aria-label={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+                  onClick={() => {
+                    setTheme((currentTheme) =>
+                      currentTheme === 'dark' ? 'light' : 'dark',
+                    );
+                  }}
+                >
+                  {theme === 'dark' ? 'Light mode' : 'Dark mode'}
+                </button>
+              </div>
+            </div>
+
+            <aside className="card heroNote">
+              <h2 className="cardTitle">What This Shows</h2>
+              <p className="cardText">
+                Only a small row-model pool stays alive while pages stream in
+                around the viewport. That means one million logical rows without
+                one million live bindings.
+              </p>
+            </aside>
+          </div>
+        </div>
+      </section>
+
+      <section className="section">
+        <div className="container">
+          <section className="app-panel card">
+            {ready ? (
+              <VirtualTableShell />
+            ) : (
+              <div className="table-loading">Initializing RS-X…</div>
+            )}
+          </section>
+        </div>
+      </section>
+    </main>
+  );
+};

package/templates/next-demo/components/virtual-table-row.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import { type FC, memo } from 'react';
+
+import { useRsxExpression } from '@rs-x/react';
+
+import type { RowView } from '@/lib/virtual-table-controller';
+
+type VirtualTableRowProps = {
+  item: RowView;
+};
+
+const VirtualTableRowComponent: FC<VirtualTableRowProps> = ({ item }) => {
+  const id = useRsxExpression(item.row.idExpr);
+  const name = useRsxExpression(item.row.nameExpr);
+  const category = useRsxExpression(item.row.categoryExpr);
+  const price = useRsxExpression(item.row.priceExpr);
+  const quantity = useRsxExpression(item.row.quantityExpr);
+  const total = useRsxExpression(item.row.totalExpr);
+  const updatedAt = useRsxExpression(item.row.updatedAtExpr);
+
+  return (
+    <div
+      className="table-row"
+      style={{ transform: `translateY(${item.top}px)` }}
+    >
+      <span data-label="ID">#{id ?? 0}</span>
+      <span data-label="Name">{name ?? ''}</span>
+      <span data-label="Category">{category ?? ''}</span>
+      <span data-label="Price">€{price ?? 0}</span>
+      <span data-label="Qty">{quantity ?? 0}</span>
+      <span data-label="Total" className="total">
+        €{total ?? 0}
+      </span>
+      <span data-label="Updated">{updatedAt ?? '--'}</span>
+    </div>
+  );
+};
+
+export const VirtualTableRow = memo(VirtualTableRowComponent);

package/templates/next-demo/components/virtual-table-shell.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { type FC } from 'react';
+
+import { useVirtualTableController } from '@/hooks/use-virtual-table-controller';
+import { useVirtualTableViewport } from '@/hooks/use-virtual-table-viewport';
+
+import { VirtualTableRow } from './virtual-table-row';
+
+export const VirtualTableShell: FC = () => {
+  const { controller, snapshot } = useVirtualTableController();
+  const viewportRef = useVirtualTableViewport(controller);
+
+  return (
+    <>
+      <section className="table-toolbar">
+        <div className="toolbar-left">
+          <h2>Inventory Snapshot</h2>
+          <p>
+            {snapshot.totalRows} rows • {snapshot.poolSize} pre-wired models
+          </p>
+        </div>
+        <div className="toolbar-right">
+          <button
+            type="button"
+            onClick={() => {
+              controller.toggleSort('price');
+            }}
+          >
+            Sort by price
+          </button>
+          <button
+            type="button"
+            onClick={() => {
+              controller.toggleSort('quantity');
+            }}
+          >
+            Sort by stock
+          </button>
+          <button
+            type="button"
+            onClick={() => {
+              controller.toggleSort('name');
+            }}
+          >
+            Sort by name
+          </button>
+        </div>
+      </section>
+
+      <div className="table-header">
+        <span>ID</span>
+        <span>Name</span>
+        <span>Category</span>
+        <span>Price</span>
+        <span>Qty</span>
+        <span>Total</span>
+        <span>Updated</span>
+      </div>
+
+      <div
+        ref={viewportRef}
+        className="table-viewport"
+        onScroll={(event) => {
+          controller.setScrollTop(event.currentTarget.scrollTop);
+        }}
+      >
+        <div
+          className="table-spacer"
+          style={{ height: `${snapshot.spacerHeight}px` }}
+        />
+        {snapshot.visibleRows.map((item) => (
+          <VirtualTableRow key={item.index} item={item} />
+        ))}
+      </div>
+
+      <div className="table-footer">
+        <div>
+          Rows in view: {snapshot.rowsInView} • Loaded pages:{' '}
+          {snapshot.loadedPageCount}
+        </div>
+        <div>Scroll to stream pages from a 1,000,000-row virtual dataset.</div>
+      </div>
+    </>
+  );
+};

package/templates/next-demo/hooks/use-virtual-table-controller.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import { useRef, useSyncExternalStore } from 'react';
+
+import {
+  VirtualTableController,
+  type VirtualTableSnapshot,
+} from '@/lib/virtual-table-controller';
+
+export function useVirtualTableController(): {
+  controller: VirtualTableController;
+  snapshot: VirtualTableSnapshot;
+} {
+  const controllerRef = useRef<VirtualTableController | null>(null);
+  if (!controllerRef.current) {
+    controllerRef.current = new VirtualTableController();
+  }
+  const controller = controllerRef.current;
+  const snapshot = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+
+  return { controller, snapshot };
+}

package/templates/next-demo/hooks/use-virtual-table-viewport.ts

@@ -0,0 +1,41 @@
+'use client';
+
+import { type RefObject, useEffect, useRef } from 'react';
+
+import type { VirtualTableController } from '@/lib/virtual-table-controller';
+
+const COMPACT_BREAKPOINT_PX = 720;
+const DEFAULT_ROW_HEIGHT = 36;
+const COMPACT_ROW_HEIGHT = 168;
+
+export function useVirtualTableViewport(
+  controller: VirtualTableController,
+): RefObject<HTMLDivElement | null> {
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const syncMetrics = (): void => {
+      controller.setViewportHeight(viewport.clientHeight);
+      controller.setRowHeight(
+        viewport.clientWidth <= COMPACT_BREAKPOINT_PX
+          ? COMPACT_ROW_HEIGHT
+          : DEFAULT_ROW_HEIGHT,
+      );
+    };
+
+    syncMetrics();
+    const observer = new ResizeObserver(syncMetrics);
+    observer.observe(viewport);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [controller]);
+
+  return viewportRef;
+}

package/templates/next-demo/lib/row-data.ts

@@ -0,0 +1,35 @@
+export type SortKey = 'id' | 'name' | 'price' | 'quantity' | 'category';
+export type SortDirection = 'asc' | 'desc';
+
+export type RowData = {
+  id: number;
+  name: string;
+  price: number;
+  quantity: number;
+  category: string;
+  updatedAt: string;
+};
+
+const categories = ['Hardware', 'Software', 'Design', 'Ops'];
+
+function pad(value: number): string {
+  return value.toString().padStart(2, '0');
+}
+
+export function createRowData(id: number): RowData {
+  const zeroBasedId = id - 1;
+  const price = 25 + (zeroBasedId % 1000) / 10;
+  const quantity = 1 + (Math.floor(zeroBasedId / 1000) % 100);
+  const category = categories[zeroBasedId % categories.length] ?? 'General';
+  const month = pad(((zeroBasedId * 7) % 12) + 1);
+  const day = pad(((zeroBasedId * 11) % 28) + 1);
+
+  return {
+    id,
+    name: `Product ${id.toString().padStart(7, '0')}`,
+    price,
+    quantity,
+    category,
+    updatedAt: `2026-${month}-${day}`,
+  };
+}

package/templates/next-demo/lib/row-model.ts

@@ -0,0 +1,45 @@
+import { rsx, type IExpression } from '@rs-x/expression-parser';
+
+import type { RowData } from './row-data';
+
+export type RowModel = {
+  model: RowData;
+  idExpr: IExpression<number>;
+  nameExpr: IExpression<string>;
+  categoryExpr: IExpression<string>;
+  priceExpr: IExpression<number>;
+  quantityExpr: IExpression<number>;
+  updatedAtExpr: IExpression<string>;
+  totalExpr: IExpression<number>;
+};
+
+export function createRowModel(): RowModel {
+  const model: RowData = {
+    id: 0,
+    name: '',
+    price: 0,
+    quantity: 0,
+    category: 'General',
+    updatedAt: '2026-01-01',
+  };
+
+  return {
+    model,
+    idExpr: rsx<number>('id')(model),
+    nameExpr: rsx<string>('name')(model),
+    categoryExpr: rsx<string>('category')(model),
+    priceExpr: rsx<number>('price')(model),
+    quantityExpr: rsx<number>('quantity')(model),
+    updatedAtExpr: rsx<string>('updatedAt')(model),
+    totalExpr: rsx<number>('price * quantity')(model),
+  };
+}
+
+export function updateRowModel(target: RowModel, data: RowData): void {
+  target.model.id = data.id;
+  target.model.name = data.name;
+  target.model.price = data.price;
+  target.model.quantity = data.quantity;
+  target.model.category = data.category;
+  target.model.updatedAt = data.updatedAt;
+}

package/templates/next-demo/lib/rsx-bootstrap.ts

@@ -0,0 +1,46 @@
+import { InjectionContainer } from '@rs-x/core';
+import { RsXExpressionParserModule } from '@rs-x/expression-parser';
+
+let initialized = false;
+
+type RsxCompiledModule = {
+  registerRsxAotCompiledExpressions?: () => void;
+};
+
+type RsxPreparsedModule = {
+  registerRsxAotParsedExpressionCache?: () => void;
+};
+
+async function loadCompiledModule(): Promise<RsxCompiledModule> {
+  try {
+    return (await import(
+      '../app/rsx-generated/' + 'rsx-aot-compiled.generated'
+    )) as RsxCompiledModule;
+  } catch {
+    return {};
+  }
+}
+
+async function loadPreparsedModule(): Promise<RsxPreparsedModule> {
+  try {
+    return (await import(
+      '../app/rsx-generated/' + 'rsx-aot-preparsed.generated'
+    )) as RsxPreparsedModule;
+  } catch {
+    return {};
+  }
+}
+
+export async function initRsx(): Promise<void> {
+  if (initialized) {
+    return;
+  }
+
+  const preparsedModule = await loadPreparsedModule();
+  const compiledModule = await loadCompiledModule();
+
+  preparsedModule.registerRsxAotParsedExpressionCache?.();
+  compiledModule.registerRsxAotCompiledExpressions?.();
+  await InjectionContainer.load(RsXExpressionParserModule);
+  initialized = true;
+}

package/templates/next-demo/lib/virtual-table-controller.ts

@@ -0,0 +1,247 @@
+import { type RowData, type SortDirection, type SortKey } from '@/lib/row-data';
+import { createRowModel, updateRowModel, type RowModel } from '@/lib/row-model';
+import { VirtualTableDataService } from '@/lib/virtual-table-data.service';
+
+export type RowView = {
+  index: number;
+  top: number;
+  row: RowModel;
+};
+
+export type VirtualTableSnapshot = {
+  visibleRows: RowView[];
+  totalRows: number;
+  poolSize: number;
+  rowsInView: number;
+  loadedPageCount: number;
+  spacerHeight: number;
+  sortKey: SortKey;
+  sortDirection: SortDirection;
+};
+
+const ROW_HEIGHT = 36;
+const PAGE_SIZE = 50;
+const POOL_PAGES = 4;
+const CACHE_PADDING_PAGES = 2;
+const RETAIN_PADDING_PAGES = 4;
+
+export class VirtualTableController {
+  public rowHeight = ROW_HEIGHT;
+  public readonly pageSize = PAGE_SIZE;
+  public readonly poolSize = PAGE_SIZE * POOL_PAGES;
+  public readonly totalRows: number;
+
+  private scrollTop = 0;
+  private viewportHeight = 520;
+  private sortKey: SortKey = 'id';
+  private sortDirection: SortDirection = 'asc';
+  private spacerHeight: number;
+  private rowsInView = Math.max(1, Math.ceil(this.viewportHeight / this.rowHeight));
+  private visibleRows: RowView[] = [];
+  private snapshot: VirtualTableSnapshot;
+
+  private readonly listeners = new Set<() => void>();
+  private readonly pool = Array.from({ length: PAGE_SIZE * POOL_PAGES }, () =>
+    createRowModel(),
+  );
+  private readonly dataByIndex = new Map<number, RowData>();
+  private readonly loadedPages = new Set<number>();
+  private readonly pageLoading = new Map<number, Promise<void>>();
+  private readonly dataService = new VirtualTableDataService();
+
+  public constructor() {
+    this.totalRows = this.dataService.totalRows;
+    this.spacerHeight = this.totalRows * this.rowHeight;
+    this.snapshot = {
+      visibleRows: this.visibleRows,
+      totalRows: this.totalRows,
+      poolSize: this.poolSize,
+      rowsInView: this.rowsInView,
+      loadedPageCount: this.loadedPages.size,
+      spacerHeight: this.spacerHeight,
+      sortKey: this.sortKey,
+      sortDirection: this.sortDirection,
+    };
+    this.refresh();
+  }
+
+  public subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  public getSnapshot = (): VirtualTableSnapshot => {
+    return this.snapshot;
+  };
+
+  public setViewportHeight(height: number): void {
+    this.viewportHeight = height;
+    this.rowsInView = Math.max(1, Math.ceil(this.viewportHeight / this.rowHeight));
+    this.refresh();
+  }
+
+  public setRowHeight(height: number): void {
+    if (this.rowHeight === height) {
+      return;
+    }
+
+    this.rowHeight = height;
+    this.spacerHeight = this.totalRows * this.rowHeight;
+    this.rowsInView = Math.max(1, Math.ceil(this.viewportHeight / this.rowHeight));
+    this.refresh();
+  }
+
+  public setScrollTop(value: number): void {
+    this.scrollTop = value;
+    this.refresh();
+  }
+
+  public toggleSort(nextKey: SortKey): void {
+    if (this.sortKey === nextKey) {
+      this.sortDirection = this.sortDirection === 'asc' ? 'desc' : 'asc';
+    } else {
+      this.sortKey = nextKey;
+      this.sortDirection = 'asc';
+    }
+
+    this.resetLoadedData();
+    this.refresh();
+  }
+
+  private refresh(): void {
+    const scrollIndex = Math.floor(this.scrollTop / this.rowHeight);
+    const bufferTop = Math.max(0, Math.floor((this.poolSize - this.rowsInView) / 2));
+    const maxStart = Math.max(0, this.totalRows - this.poolSize);
+    const startIndex = Math.min(Math.max(scrollIndex - bufferTop, 0), maxStart);
+    const endIndex = Math.min(startIndex + this.poolSize, this.totalRows);
+    const startPage = Math.max(
+      0,
+      Math.floor(startIndex / this.pageSize) - CACHE_PADDING_PAGES,
+    );
+    const endPage = Math.min(
+      Math.floor((endIndex - 1) / this.pageSize) + CACHE_PADDING_PAGES,
+      Math.floor((this.totalRows - 1) / this.pageSize),
+    );
+
+    this.ensurePages(startPage, endPage);
+    this.pruneCachedPages(startPage, endPage);
+
+    const nextRows: RowView[] = [];
+    const length = endIndex - startIndex;
+
+    for (let offset = 0; offset < length; offset += 1) {
+      const index = startIndex + offset;
+      const target = this.pool[offset];
+      updateRowModel(target, this.getRowData(index));
+
+      nextRows.push({
+        index,
+        top: index * this.rowHeight,
+        row: target,
+      });
+    }
+
+    this.visibleRows = nextRows;
+    this.snapshot = {
+      visibleRows: this.visibleRows,
+      totalRows: this.totalRows,
+      poolSize: this.poolSize,
+      rowsInView: this.rowsInView,
+      loadedPageCount: this.loadedPages.size,
+      spacerHeight: this.spacerHeight,
+      sortKey: this.sortKey,
+      sortDirection: this.sortDirection,
+    };
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+
+  private ensurePages(startPage: number, endPage: number): void {
+    for (let pageIndex = startPage; pageIndex <= endPage; pageIndex += 1) {
+      this.ensurePageLoaded(pageIndex);
+    }
+  }
+
+  private ensurePageLoaded(pageIndex: number): void {
+    if (this.loadedPages.has(pageIndex) || this.pageLoading.has(pageIndex)) {
+      return;
+    }
+
+    const task = this.loadPageAsync(pageIndex).finally(() => {
+      this.pageLoading.delete(pageIndex);
+      this.loadedPages.add(pageIndex);
+      this.refresh();
+    });
+
+    this.pageLoading.set(pageIndex, task);
+  }
+
+  private async loadPageAsync(pageIndex: number): Promise<void> {
+    const page = await this.dataService.fetchPage(
+      pageIndex,
+      this.pageSize,
+      this.sortKey,
+      this.sortDirection,
+    );
+    const startIndex = pageIndex * this.pageSize;
+
+    for (let offset = 0; offset < page.items.length; offset += 1) {
+      const item = page.items[offset];
+      if (!item) {
+        continue;
+      }
+
+      this.dataByIndex.set(startIndex + offset, item);
+    }
+  }
+
+  private getRowData(index: number): RowData {
+    const cached = this.dataByIndex.get(index);
+    if (cached) {
+      return cached;
+    }
+
+    return {
+      id: index + 1,
+      name: 'Loading...',
+      price: 0,
+      quantity: 0,
+      category: 'Pending',
+      updatedAt: '--',
+    };
+  }
+
+  private resetLoadedData(): void {
+    this.dataByIndex.clear();
+    this.loadedPages.clear();
+    this.pageLoading.clear();
+  }
+
+  private pruneCachedPages(startPage: number, endPage: number): void {
+    const minPage = Math.max(0, startPage - RETAIN_PADDING_PAGES);
+    const maxPage = Math.min(
+      Math.floor((this.totalRows - 1) / this.pageSize),
+      endPage + RETAIN_PADDING_PAGES,
+    );
+
+    for (const pageIndex of Array.from(this.loadedPages)) {
+      if (pageIndex >= minPage && pageIndex <= maxPage) {
+        continue;
+      }
+
+      this.loadedPages.delete(pageIndex);
+      const pageStart = pageIndex * this.pageSize;
+      const pageEnd = Math.min(pageStart + this.pageSize, this.totalRows);
+      for (let index = pageStart; index < pageEnd; index += 1) {
+        this.dataByIndex.delete(index);
+      }
+    }
+  }
+}