rastack 0.0.55 → 0.0.56

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.56](https://github.com/theserverkid/reactapistack/compare/v0.0.55...v0.0.56) (2026-07-18)
+
+
+### Bug Fixes
+
+* **deps:** pin TypeScript to 5.x, keep esbuild 0.28.1 ([#96](https://github.com/theserverkid/reactapistack/issues/96)) ([2a5984d](https://github.com/theserverkid/reactapistack/commit/2a5984d4d10d5af8cf5cc448cd4eca5348515589)), closes [#76](https://github.com/theserverkid/reactapistack/issues/76)
+
 ### [0.0.55](https://github.com/theserverkid/reactapistack/compare/v0.0.54...v0.0.55) (2026-07-16)
 
 ### [0.0.54](https://github.com/theserverkid/reactapistack/compare/v0.0.53...v0.0.54) (2026-07-16)

package/admin/AdminApp.tsx

@@ -22,11 +22,11 @@ import {
 import type { RastackEngine } from "../provider/types";
 import {
   AdminResource,
-  adminResources,
   changelistHeaders,
   findResource,
 } from "./adapters";
 import {
+  useDashboardStats,
   useDeleteRecord,
   useFilterModel,
   useResourceForm,
@@ -36,9 +36,22 @@ import { Sidebar } from "./ui/Sidebar";
 import { FilterBar } from "./ui/FilterBar";
 import { AdminStyles } from "./ui/styles";
 import {
+  BarChart,
+  CountUp,
+  MeterRow,
+  Reveal,
+  SegmentBar,
+  seriesColor,
+} from "./ui/motion";
+import { DetailsModal, type DetailRow } from "./ui/DetailsModal";
+import {
+  IconActivity,
   IconArrowLeft,
+  IconArrowUpRight,
   IconChevronRight,
+  IconDatabase,
   IconInbox,
+  IconLayers,
   IconLink,
   IconPlus,
   IconTable,
@@ -122,58 +135,267 @@ function PageHead(props: {
   );
 }
 
-// -- index / overview -------------------------------------------------------
+// -- index / Insight dashboard ----------------------------------------------
 
-function IndexScreen(props: { resources: AdminResource[] }): React.JSX.Element {
-  const byApp = useMemo(() => {
-    const map = new Map<string, AdminResource[]>();
-    for (const r of adminResources(props.resources)) {
-      const list = map.get(r.app) ?? [];
-      list.push(r);
-      map.set(r.app, list);
-    }
-    return [...map.entries()].sort(([a], [b]) => a.localeCompare(b));
-  }, [props.resources]);
+/** One KPI tile: an icon, an animated count, and a quiet sublabel. */
+function StatTile(props: {
+  icon: React.ReactNode;
+  label: string;
+  value: number;
+  sub: string;
+  index: number;
+  accent?: string;
+}): React.JSX.Element {
+  return (
+    <Reveal className="ras-stat" index={props.index}>
+      <div className="ras-stat-top">
+        <span className="ras-stat-ico" style={props.accent ? { color: props.accent } : undefined}>
+          {props.icon}
+        </span>
+        <span className="ras-stat-label">{props.label}</span>
+      </div>
+      <div className="ras-stat-value">
+        <CountUp value={props.value} delay={props.index * 80} />
+      </div>
+      <div className="ras-stat-sub">{props.sub}</div>
+    </Reveal>
+  );
+}
+
+function DashboardScreen(props: {
+  engine: RastackEngine;
+  resources: AdminResource[];
+}): React.JSX.Element {
+  const stats = useDashboardStats(props.engine, props.resources);
+  const populated = useMemo(
+    () => stats.models.filter((m) => m.count > 0),
+    [stats.models],
+  );
+  const [details, setDetails] = useState<null | "apps" | "tables">(null);
+
+  const appRows: DetailRow[] = stats.byApp.map((a, i) => ({
+    label: a.app,
+    value: a.count,
+    color: seriesColor(i),
+    meta: `${a.models} ${a.models === 1 ? "table" : "tables"}`,
+  }));
+  const tableRows: DetailRow[] = stats.models.map((m, i) => ({
+    label: m.resource.label,
+    value: m.count,
+    color: seriesColor(i),
+    meta: m.resource.app,
+  }));
 
   return (
     <>
-      <Topbar crumbs={[{ label: "Overview" }]} />
-      <div className="ras-content">
+      <Topbar crumbs={[{ label: "Insight" }]} />
+      <div className="ras-content" key="dashboard">
         <PageHead
           eyebrow="React API Stack"
-          title="Administration"
-          subtitle="Browse and edit every model in the manifest — stored as Apache Iceberg tables on object storage."
+          title="Insight"
+          subtitle="Every model in the manifest, live — stored as Apache Iceberg tables on object storage."
         />
-        {byApp.map(([app, models]) => (
-          <div key={app} style={{ marginBottom: 28 }}>
-            <div className="ras-nav-label" style={{ padding: "0 2px 10px" }}>
-              {app}
-            </div>
-            <div className="ras-cardgrid">
-              {models
-                .slice()
-                .sort((a, b) => a.model.localeCompare(b.model))
-                .map((r) => (
-                  <Card
-                    key={r.key}
-                    className="ras-modelcard"
-                    onClick={() => go(`#/${r.app}/${r.model}/`)}
-                  >
-                    <div className="ras-mc-top">
-                      <span className="ras-mc-icon">
-                        <IconTable size={19} />
-                      </span>
-                    </div>
-                    <div className="ras-mc-name">{r.label}</div>
-                    <div className="ras-mc-go">
-                      View records <IconChevronRight size={14} />
-                    </div>
-                  </Card>
-                ))}
+
+        {/* KPI strip */}
+        <div className="ras-statgrid">
+          <StatTile
+            index={0}
+            icon={<IconDatabase size={17} />}
+            label="Total records"
+            value={stats.totalRecords}
+            sub={stats.loading ? "counting…" : "across every table"}
+          />
+          <StatTile
+            index={1}
+            icon={<IconTable size={17} />}
+            label="Tables"
+            value={stats.modelCount}
+            sub={`${populated.length} with data`}
+            accent="var(--color-success)"
+          />
+          <StatTile
+            index={2}
+            icon={<IconLayers size={17} />}
+            label="Apps"
+            value={stats.appCount}
+            sub="namespaces in the schema"
+            accent="var(--color-warning)"
+          />
+          <StatTile
+            index={3}
+            icon={<IconLink size={17} />}
+            label="Relations"
+            value={stats.relationCount}
+            sub="foreign keys inferred"
+            accent="var(--color-accent)"
+          />
+        </div>
+
+        {/* Data distribution — the animated bar chart */}
+        <Reveal index={4}>
+          <Card className="ras-panel">
+            <div className="ras-panel-head">
+              <div>
+                <div className="ras-panel-title">
+                  <IconActivity size={15} /> Data distribution
+                </div>
+                <div className="ras-panel-sub">Records per table</div>
+              </div>
+              <span className="ras-pill">{stats.modelCount} tables</span>
             </div>
-          </div>
-        ))}
+            {stats.loading ? (
+              <div className="ras-chart-skel" />
+            ) : stats.totalRecords === 0 ? (
+              <div className="ras-panel-empty">
+                No records yet — add data to any table to see it chart here.
+              </div>
+            ) : (
+              <BarChart
+                data={stats.models.map((m) => ({
+                  label: m.resource.label,
+                  value: m.count,
+                }))}
+              />
+            )}
+          </Card>
+        </Reveal>
+
+        {/* Two breakdown cards */}
+        <div className="ras-panel-row">
+          <Reveal index={5}>
+            <Card className="ras-panel">
+              <div className="ras-panel-head">
+                <div>
+                  <div className="ras-panel-title">Records by app</div>
+                  <div className="ras-panel-sub">Share of the warehouse</div>
+                </div>
+                {stats.byApp.length ? (
+                  <button type="button" className="ras-details-btn" onClick={() => setDetails("apps")}>
+                    Details
+                  </button>
+                ) : null}
+              </div>
+              {stats.byApp.length && stats.totalRecords > 0 ? (
+                <>
+                  <SegmentBar
+                    segments={stats.byApp.map((a, i) => ({
+                      label: a.app,
+                      value: a.count,
+                      color: seriesColor(i),
+                    }))}
+                  />
+                  <div className="ras-legend">
+                    {stats.byApp.map((a, i) => (
+                      <div className="ras-legend-row" key={a.app}>
+                        <span className="ras-legend-key">
+                          <span className="ras-legend-dot" style={{ background: seriesColor(i) }} />
+                          {a.app}
+                        </span>
+                        <span className="ras-legend-meta">
+                          {a.models} {a.models === 1 ? "table" : "tables"}
+                        </span>
+                        <span className="ras-legend-val">
+                          <CountUp value={a.count} delay={300 + i * 60} />
+                          <span className="ras-legend-pct">
+                            {Math.round((a.count / stats.totalRecords) * 100)}%
+                          </span>
+                        </span>
+                      </div>
+                    ))}
+                  </div>
+                </>
+              ) : (
+                <div className="ras-panel-empty">No data across any app yet.</div>
+              )}
+            </Card>
+          </Reveal>
+
+          <Reveal index={6}>
+            <Card className="ras-panel">
+              <div className="ras-panel-head">
+                <div>
+                  <div className="ras-panel-title">Largest tables</div>
+                  <div className="ras-panel-sub">By record count</div>
+                </div>
+                {populated.length ? (
+                  <button type="button" className="ras-details-btn" onClick={() => setDetails("tables")}>
+                    Details
+                  </button>
+                ) : null}
+              </div>
+              {populated.length ? (
+                <div className="ras-meters">
+                  {populated.slice(0, 5).map((m, i) => (
+                    <a
+                      key={m.resource.key}
+                      href={`#/${m.resource.app}/${m.resource.model}/`}
+                      className="ras-meter-link"
+                    >
+                      <MeterRow
+                        label={m.resource.label}
+                        value={m.count}
+                        max={populated[0].count}
+                        color={seriesColor(i)}
+                        index={i}
+                      />
+                    </a>
+                  ))}
+                </div>
+              ) : (
+                <div className="ras-panel-empty">Tables fill in as you add records.</div>
+              )}
+            </Card>
+          </Reveal>
+        </div>
+
+        {/* Model launcher */}
+        <Reveal index={7}>
+          <div className="ras-section-label">Browse tables</div>
+        </Reveal>
+        <div className="ras-cardgrid">
+          {stats.models.map((m, i) => (
+            <Reveal key={m.resource.key} index={8 + i} step={45}>
+              <Card
+                className="ras-modelcard"
+                onClick={() => go(`#/${m.resource.app}/${m.resource.model}/`)}
+              >
+                <div className="ras-mc-top">
+                  <span className="ras-mc-icon">
+                    <IconTable size={18} />
+                  </span>
+                  <span className="ras-mc-count">
+                    {stats.loading ? "—" : <CountUp value={m.count} delay={i * 40} />}
+                  </span>
+                </div>
+                <div className="ras-mc-name">{m.resource.label}</div>
+                <div className="ras-mc-meta">{m.resource.app}</div>
+                <div className="ras-mc-go">
+                  View records <IconArrowUpRight size={14} />
+                </div>
+              </Card>
+            </Reveal>
+          ))}
+        </div>
       </div>
+
+      <DetailsModal
+        open={details === "apps"}
+        title="Records by app"
+        subtitle="Every app namespace by total records"
+        rows={appRows}
+        total={stats.totalRecords}
+        unit="records"
+        onClose={() => setDetails(null)}
+      />
+      <DetailsModal
+        open={details === "tables"}
+        title="Tables by record count"
+        subtitle="Every table in the manifest, ranked"
+        rows={tableRows}
+        total={stats.totalRecords}
+        unit="records"
+        onClose={() => setDetails(null)}
+      />
     </>
   );
 }
@@ -278,9 +500,14 @@ function ListScreen(props: {
           eyebrow={resource.app}
           title={resource.label}
           subtitle={
-            table.query.isLoading
-              ? "Loading…"
-              : `${table.itemCount} ${table.itemCount === 1 ? "record" : "records"}`
+            table.query.isLoading ? (
+              "Loading…"
+            ) : (
+              <>
+                <CountUp value={table.itemCount} duration={650} />{" "}
+                {table.itemCount === 1 ? "record" : "records"}
+              </>
+            )
           }
           actions={
             <Button onClick={() => go(addHash)}>
@@ -402,19 +629,44 @@ function FormScreen(props: {
 
 // -- root -------------------------------------------------------------------
 
+const COLLAPSE_KEY = "ras-admin-sidebar-collapsed";
+
+/** Persisted sidebar collapse state; drives the grid-track transition. */
+function useSidebarCollapsed(): [boolean, () => void] {
+  const [collapsed, setCollapsed] = useState(() => {
+    try {
+      return localStorage.getItem(COLLAPSE_KEY) === "1";
+    } catch {
+      return false;
+    }
+  });
+  const toggle = () =>
+    setCollapsed((c) => {
+      const next = !c;
+      try {
+        localStorage.setItem(COLLAPSE_KEY, next ? "1" : "0");
+      } catch {
+        /* storage may be unavailable */
+      }
+      return next;
+    });
+  return [collapsed, toggle];
+}
+
 export function AdminApp(props: {
   engine: RastackEngine;
   resources: AdminResource[];
 }): React.JSX.Element {
   const route = useRoute();
   const { engine, resources } = props;
+  const [collapsed, toggleCollapsed] = useSidebarCollapsed();
 
   const activeKey =
     route.name === "index" ? undefined : `${route.app}.${route.model}`;
 
   let screen: React.ReactNode;
   if (route.name === "index") {
-    screen = <IndexScreen resources={resources} />;
+    screen = <DashboardScreen engine={engine} resources={resources} />;
   } else {
     const resource = findResource(resources, route.app, route.model);
     if (!resource) {
@@ -452,8 +704,13 @@ export function AdminApp(props: {
   return (
     <>
       <AdminStyles />
-      <div className="ras-root">
-        <Sidebar resources={resources} activeKey={activeKey} />
+      <div className={"ras-root" + (collapsed ? " is-collapsed" : "")}>
+        <Sidebar
+          resources={resources}
+          activeKey={activeKey}
+          collapsed={collapsed}
+          onToggleCollapse={toggleCollapsed}
+        />
         <main className="ras-main">{screen}</main>
       </div>
     </>

package/admin/ui/DetailsModal.tsx

@@ -0,0 +1,125 @@
+/**
+ * A backdrop-blur "Details" drill-down modal — the reference's "Details" affordance.
+ * Built to the design-engineer §4 spec, dependency-free:
+ *
+ *   • overlay: fixed inset:0, translucent fill + backdrop-filter blur(16px)
+ *     saturate(140%), fading opacity 0→1 over 400ms
+ *   • content: transform scale(0.95) translate3d(0,10px,0) → identity over 400ms
+ *     on cubic-bezier(0.16, 1, 0.3, 1)
+ *   • execution order: overlay + shell mount → after stabilise, the internal
+ *     horizontal bars animate width 0%→X% over 800ms cubic-bezier(0.4,0,0.2,1)
+ *
+ * All of it honours prefers-reduced-motion (via the stylesheet), and the bars
+ * carry a count-up value. Closes on Escape, backdrop click, or the close button.
+ */
+import React, { useEffect, useState } from "react";
+import { CountUp } from "./motion";
+import { IconClose } from "./icons";
+
+/** One ranked row in the modal: a labelled bar filling to `value / max`. */
+export interface DetailRow {
+  label: string;
+  value: number;
+  color: string;
+  meta?: string;
+}
+
+export function DetailsModal(props: {
+  open: boolean;
+  title: string;
+  subtitle?: string;
+  rows: DetailRow[];
+  total: number;
+  unit?: string;
+  onClose: () => void;
+}): React.JSX.Element | null {
+  const { open, onClose } = props;
+  // `armed` gates the width-fill: it flips true one tick after mount so the bars
+  // transition from 0 rather than appearing full (the §4 "secondary state" step).
+  const [armed, setArmed] = useState(false);
+
+  useEffect(() => {
+    if (!open) {
+      setArmed(false);
+      return;
+    }
+    const raf = requestAnimationFrame(() => setArmed(true));
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      cancelAnimationFrame(raf);
+      window.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+  const max = Math.max(1, ...props.rows.map((r) => r.value));
+
+  return (
+    <div
+      className="ras-modal-overlay"
+      onClick={onClose}
+      role="dialog"
+      aria-modal="true"
+      aria-label={props.title}
+    >
+      <div className="ras-modal" onClick={(e) => e.stopPropagation()}>
+        <div className="ras-modal-head">
+          <div>
+            <div className="ras-modal-title">{props.title}</div>
+            {props.subtitle ? <div className="ras-modal-sub">{props.subtitle}</div> : null}
+          </div>
+          <button type="button" className="ras-modal-x" onClick={onClose} aria-label="Close">
+            <IconClose size={16} />
+          </button>
+        </div>
+
+        <div className="ras-modal-rows">
+          {props.rows.map((row, i) => {
+            const pct = Math.max(1.5, (row.value / max) * 100);
+            const share = props.total > 0 ? Math.round((row.value / props.total) * 100) : 0;
+            return (
+              <div className="ras-modal-row" key={row.label + i}>
+                <div className="ras-modal-row-head">
+                  <span className="ras-modal-row-label">
+                    <span className="ras-legend-dot" style={{ background: row.color }} />
+                    {row.label}
+                    {row.meta ? <span className="ras-modal-row-meta">{row.meta}</span> : null}
+                  </span>
+                  <span className="ras-modal-row-val">
+                    <CountUp value={row.value} delay={120 + i * 55} duration={900} />
+                    <span className="ras-modal-row-pct">{share}%</span>
+                  </span>
+                </div>
+                <div className="ras-modal-track">
+                  <div
+                    className="ras-modal-fill"
+                    style={{
+                      width: armed ? `${pct}%` : "0%",
+                      background: row.color,
+                      transitionDelay: `${i * 55}ms`,
+                    }}
+                  />
+                </div>
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="ras-modal-foot">
+          <span>
+            {props.rows.length} {props.rows.length === 1 ? "row" : "rows"}
+          </span>
+          <span className="ras-modal-total">
+            <CountUp value={props.total} duration={900} /> {props.unit ?? "total"}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/admin/ui/Sidebar.tsx

@@ -10,13 +10,16 @@ import { useThemeMode } from "../../theme";
 import { humanizeKey } from "../../components";
 import type { AdminResource } from "../adapters";
 import { adminResources } from "../adapters";
-import { BrandMark, IconMoon, IconSun, IconTable } from "./icons";
+import { BrandMark, IconMoon, IconPanelLeft, IconSun, IconTable } from "./icons";
 
 export function Sidebar(props: {
   resources: AdminResource[];
   activeKey?: string;
+  collapsed?: boolean;
+  onToggleCollapse?: () => void;
 }): React.JSX.Element {
   const [mode, setMode] = useThemeMode();
+  const collapsed = props.collapsed ?? false;
 
   const byApp = useMemo(() => {
     const map = new Map<string, AdminResource[]>();
@@ -37,15 +40,29 @@ export function Sidebar(props: {
 
   return (
     <aside className="ras-sidebar">
-      <a className="ras-brand" href="#/" aria-label="React API Stack admin">
-        <BrandMark size={32} />
-        <span>
-          <span className="ras-brand-name" style={{ display: "block" }}>
-            React API Stack
+      <div className="ras-brand-row">
+        <a className="ras-brand" href="#/" aria-label="React API Stack admin">
+          <BrandMark size={32} />
+          <span className="ras-brand-text">
+            <span className="ras-brand-name" style={{ display: "block" }}>
+              React API Stack
+            </span>
+            <span className="ras-brand-sub">Admin</span>
           </span>
-          <span className="ras-brand-sub">Admin</span>
-        </span>
-      </a>
+        </a>
+        {props.onToggleCollapse ? (
+          <button
+            type="button"
+            className="ras-icon-btn ras-collapse-btn"
+            aria-label={collapsed ? "Expand sidebar" : "Collapse sidebar"}
+            aria-pressed={collapsed}
+            title={collapsed ? "Expand" : "Collapse"}
+            onClick={props.onToggleCollapse}
+          >
+            <IconPanelLeft size={16} />
+          </button>
+        ) : null}
+      </div>
 
       <nav className="ras-nav">
         {byApp.map(([app, models]) => (
@@ -59,9 +76,10 @@ export function Sidebar(props: {
                   href={`#/${r.app}/${r.model}/`}
                   className={"ras-nav-link" + (active ? " is-active" : "")}
                   aria-current={active ? "page" : undefined}
+                  title={collapsed ? r.label : undefined}
                 >
                   <IconTable size={16} className="ras-ico" />
-                  {r.label}
+                  <span className="ras-nav-text">{r.label}</span>
                 </a>
               );
             })}

package/admin/ui/icons.tsx

@@ -125,6 +125,47 @@ export const IconInbox = (p: SvgProps) => (
   </Svg>
 );
 
+export const IconDatabase = (p: SvgProps) => (
+  <Svg {...p}>
+    <ellipse cx="12" cy="5" rx="8" ry="3" />
+    <path d="M4 5v6c0 1.7 3.6 3 8 3s8-1.3 8-3V5" />
+    <path d="M4 11v6c0 1.7 3.6 3 8 3s8-1.3 8-3v-6" />
+  </Svg>
+);
+
+export const IconLayers = (p: SvgProps) => (
+  <Svg {...p}>
+    <path d="m12 3 9 5-9 5-9-5 9-5Z" />
+    <path d="m3 13 9 5 9-5" />
+  </Svg>
+);
+
+export const IconActivity = (p: SvgProps) => (
+  <Svg {...p}>
+    <path d="M3 12h4l2.5-7 5 14 2.5-7H21" />
+  </Svg>
+);
+
+export const IconArrowUpRight = (p: SvgProps) => (
+  <Svg {...p}>
+    <path d="M7 17 17 7M8 7h9v9" />
+  </Svg>
+);
+
+export const IconPanelLeft = (p: SvgProps) => (
+  <Svg {...p}>
+    <rect x="3.5" y="4.5" width="17" height="15" rx="2" />
+    <path d="M9.5 4.5v15" />
+  </Svg>
+);
+
+export const IconBell = (p: SvgProps) => (
+  <Svg {...p}>
+    <path d="M6 9a6 6 0 0 1 12 0c0 5 2 6 2 6H4s2-1 2-6Z" />
+    <path d="M10 20a2 2 0 0 0 4 0" />
+  </Svg>
+);
+
 /** The brand mark: an isometric "stack" tile in the accent colour. */
 export function BrandMark({ size = 30 }: { size?: number }): React.JSX.Element {
   return (