create-lacspace-app 2.13.0 → 2.14.0

package/README.md

@@ -20,6 +20,12 @@ npx create-lacspace-app my-app --template saas --fullstack
 
 You choose the *kind* of site you're building. It writes a **real Next.js 15 + React 19 + Tailwind v4 app** — not a hello-world, but a genuinely **polished, modern site**: a fluid `clamp()` type scale, tight display headings, a refined light **and** dark palette, glass chrome, soft layered shadows, a smooth logo marquee, animated counters, scroll reveals and a shimmering primary CTA — every page filled in, an SEO stack wired end-to-end, and a **26-component UI kit** you can drop in anywhere.
 
+> **New in v2.14 — the UI kit (18 add-ons).** The scaffold now comes with a real component layer, not just a page:
+> - **`ui`** — the **96-component `@lacspace/components` library** wired into your template: a working settings page (form validation, a confirm dialog that waits for its promise, toasts), a `<UIProvider>` for app-wide use, and a **theme bridge** that maps your template's accent, radius and font onto the kit's `--lac-*` variables — so the components match your brand and follow your existing dark-mode toggle out of the box. Frontend, any template.
+> - **`dataviz`** — a working `/insights` page from **`@lacspace/charts` + `@lacspace/table` + `@lacspace/date`**: stat cards, an SVG line chart, a date-range filter and a sortable, searchable, CSV-exportable table. No canvas, no D3, no grid licence. Frontend, any template.
+>
+> `npx create-lacspace-app my-app --template saas --with ui,dataviz`
+
 > **New in v2.12 — real-time & privacy (16 add-ons).** Two more keyless, no-vendor add-ons:
 > - **`realtime`** — live server→browser updates over **Server-Sent Events** (`@lacspace/sse`): a channel hub + a `/live` stream + a React `useSSE` feed. No WebSocket server. Full-stack.
 > - **`consent`** — **GDPR-friendly cookie consent** (`@lacspace/consent`): a drop-in `<ConsentBanner/>`, per-category choices, cookie persistence and `whenConsent()` script-gating. Frontend.
@@ -159,6 +165,8 @@ In the interactive flow, after you pick a template you're offered the same list
 | --- | --- | --- |
 | **`ai-chat`** | A streaming chat route `app/api/chat/route.ts` + a chat UI `app/chat/page.tsx`. Reads provider config from env, runs input through a prompt-injection guard, and streams the reply. | `@lacspace/ai` `@lacspace/prompt` `@lacspace/stream` `@lacspace/providers` `@lacspace/memory` `@lacspace/moderation` |
 | **`rag`** | "Chat with your docs": `content/welcome.md`, an indexer `scripts/index-content.mjs` (+ `rag:index` script), a retrieval+rerank answer route `app/api/ask/route.ts`, and an ask UI `app/ask/page.tsx`. | `@lacspace/rag` `@lacspace/embeddings` `@lacspace/vector` `@lacspace/chunk` `@lacspace/rerank` `@lacspace/providers` `@lacspace/ai` |
+| **`ui`** | The component library, themed to your template: `app/ui/page.tsx` (a real form, a confirm dialog and toasts), `app/ui/layout.tsx`, a `<UIProvider>`, and `app/lacspace-ui.css` — the bridge that maps your tokens onto the kit's. | `@lacspace/components` |
+| **`dataviz`** | A working `/insights` page: stat cards, an SVG line chart, a date-range filter, and a sortable/searchable/exportable data table. | `@lacspace/charts` `@lacspace/table` `@lacspace/date` `@lacspace/components` |
 
 ### 🆓 Free & local by default — no API key
 
@@ -202,6 +210,8 @@ Every template is Next.js 15 App Router + React 19 + Tailwind v4 — dark, moder
 | `--no-install` | skip installing dependencies |
 | `--no-git` | skip git init |
 | `-y, --yes` | accept defaults (needs a project name) |
+| `-h, --help` | show every flag |
+| `-v, --version` | print the installed version |
 
 ### 🎨 Themes
 

package/dist/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync, mkdirSync, writeFileSync } from 'fs';
-import { resolve, basename, join, dirname } from 'path';
+import { realpathSync, existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { basename, resolve, join, dirname } from 'path';
 import { createInterface } from 'readline/promises';
-import { argv, stdout, exit, stdin, cwd } from 'process';
+import { stdout, exit, argv, stdin, cwd } from 'process';
 import { spawnSync } from 'child_process';
-import { pathToFileURL } from 'url';
+import { pathToFileURL, fileURLToPath } from 'url';
 
 var C = {
   reset: "\x1B[0m",
@@ -2434,8 +2434,364 @@ var FEATURES = [
       "SSE auto-reconnects and needs no WebSocket server \u2014 great for notifications and live feeds."
     ],
     learn: "https://developer.lacspace.com/packages/sse"
+  },
+  {
+    key: "ui",
+    label: "UI components",
+    description: "The @lacspace/components library wired into this template \u2014 96 accessible components, a theme bridge so they inherit your accent and dark mode, and a working settings page. Frontend, any template.",
+    deps: { "@lacspace/components": "^1.0.1" },
+    files: () => ({
+      "app/lacspace-ui.css": uiThemeBridge(),
+      "app/ui/layout.tsx": uiRouteLayout(),
+      "app/ui/page.tsx": uiShowcasePage(),
+      "components/ui-provider.tsx": uiProviderComponent()
+    }),
+    nextSteps: [
+      "Run `npm run dev` and open http://localhost:3000/ui \u2014 a real form, a confirm dialog and toasts, already themed.",
+      'Use the kit anywhere: import "@lacspace/components/styles.css" and "./lacspace-ui.css" in app/layout.tsx, then wrap <body> with <UIProvider> from @/components/ui-provider.',
+      "Rebrand everything from app/lacspace-ui.css \u2014 it maps this template's accent, radius and font onto the kit's --lac-* variables, so dark mode follows your theme toggle."
+    ],
+    learn: "https://developer.lacspace.com/components"
+  },
+  {
+    key: "dataviz",
+    label: "Charts, tables & dates",
+    description: "A working insights page from @lacspace/charts, @lacspace/table and @lacspace/date \u2014 SVG charts, a sortable/exportable data table and a date-range filter. No canvas, no D3, no grid licence. Frontend, any template.",
+    deps: {
+      "@lacspace/components": "^1.0.1",
+      "@lacspace/charts": "^1.0.0",
+      "@lacspace/table": "^1.0.0",
+      "@lacspace/date": "^1.0.0"
+    },
+    files: () => ({
+      "app/lacspace-ui.css": uiThemeBridge(),
+      "app/insights/layout.tsx": dataVizRouteLayout(),
+      "app/insights/page.tsx": dataVizPage()
+    }),
+    nextSteps: [
+      "Run `npm run dev` and open http://localhost:3000/insights \u2014 stats, a line chart, a date-range filter and an exportable table.",
+      "Swap the sample arrays at the top of app/insights/page.tsx for your own data; everything else is already wired.",
+      "The CSV export neutralises leading =, +, - and @, so an exported cell can never run as a formula in Excel."
+    ],
+    learn: "https://developer.lacspace.com/components#charts"
+  }
+];
+var uiThemeBridge = () => `/* Map this app's tokens onto @lacspace/components.
+ *
+ * The kit's own dark palette lives behind \`prefers-color-scheme\` and a
+ * \`data-theme\` attribute, but this app switches themes with a \`.dark\` class on
+ * <html>. The repeated \`:root\` below is deliberate: it raises specificity just
+ * enough to win against the kit's own theme blocks, whatever the OS setting is,
+ * so the components follow YOUR toggle and never fight it.
+ *
+ * Every line here is a suggestion \u2014 change any of them and the whole kit
+ * follows. The full token list is at the top of @lacspace/components/styles.css.
+ */
+:root:root:root {
+  /* Brand */
+  --lac-accent: var(--accent-to);
+  --lac-accent-hover: var(--accent-from);
+  --lac-accent-active: var(--accent-from);
+  --lac-accent-fg: var(--on-accent);
+  --lac-accent-soft: color-mix(in oklab, var(--accent-to) 14%, transparent);
+  --lac-accent-ring: color-mix(in oklab, var(--accent-to) 38%, transparent);
+
+  /* Surfaces & text \u2014 these already swap with the .dark class, so dark mode
+     comes along for free. */
+  --lac-bg: var(--bg);
+  --lac-bg-subtle: var(--surface);
+  --lac-bg-muted: var(--panel);
+  --lac-surface: var(--surface);
+  --lac-surface-raised: var(--panel);
+  --lac-fg: var(--fg);
+  --lac-fg-muted: var(--muted);
+  --lac-fg-faint: var(--faint);
+  --lac-fg-on-accent: var(--on-accent);
+
+  /* Lines & depth */
+  --lac-border: var(--hairline);
+  --lac-border-strong: color-mix(in oklab, var(--fg) 22%, transparent);
+  --lac-shadow-sm: var(--shadow-sm);
+  --lac-shadow: var(--shadow);
+  --lac-shadow-lg: var(--shadow-lg);
+
+  /* Shape & type */
+  --lac-radius: var(--radius);
+  --lac-radius-lg: var(--radius-lg);
+  --lac-font: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
+}
+`;
+var uiRouteLayout = () => `import "@lacspace/components/styles.css";
+import "../lacspace-ui.css";
+import { ToastProvider } from "@lacspace/components";
+
+// Scoped to this route so the add-on needs no edits to app/layout.tsx. To use
+// the kit across the whole app, move these two imports there and wrap <body>
+// with <UIProvider> from @/components/ui-provider instead.
+export default function UILayout({ children }: { children: React.ReactNode }) {
+  return <ToastProvider>{children}</ToastProvider>;
+}
+`;
+var uiProviderComponent = () => `"use client";
+import { ToastProvider } from "@lacspace/components";
+
+/**
+ * Wrap <body> with this once to use the component kit across the whole app,
+ * and import the two stylesheets in app/layout.tsx:
+ *
+ *   import "@lacspace/components/styles.css";
+ *   import "./lacspace-ui.css";
+ */
+export function UIProvider({ children }: { children: React.ReactNode }) {
+  return <ToastProvider position="bottom-right">{children}</ToastProvider>;
+}
+`;
+var uiShowcasePage = () => `"use client";
+import { useState } from "react";
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  CardBody,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  ConfirmDialog,
+  Field,
+  Input,
+  PasswordInput,
+  Select,
+  Stack,
+  Switch,
+  useToast,
+} from "@lacspace/components";
+
+// Everything below is real: a form that validates, a dialog that waits for its
+// promise, and a toast queue \u2014 none of it styled with utility classes. The look
+// comes from app/lacspace-ui.css, which maps this template's tokens onto the kit.
+export default function UIPage() {
+  const { toast } = useToast();
+  const [confirming, setConfirming] = useState(false);
+  const [updates, setUpdates] = useState(true);
+  const [errors, setErrors] = useState<{ email?: string }>({});
+
+  function save(form: FormData) {
+    const email = String(form.get("email") ?? "");
+    if (!email.includes("@")) {
+      setErrors({ email: "That doesn't look like an email address." });
+      return;
+    }
+    setErrors({});
+    toast({ title: "Settings saved", tone: "success" });
   }
+
+  return (
+    <main className="mx-auto max-w-2xl px-6 py-16">
+      <Stack gap={4}>
+        <Card>
+          <CardHeader>
+            <CardTitle>Account settings</CardTitle>
+            <CardDescription>
+              96 components from @lacspace/components \u2014 accessible, server-render safe, and
+              themed by CSS variables instead of utility classes.
+            </CardDescription>
+          </CardHeader>
+          <CardBody>
+            <form action={save}>
+              <Stack gap={3}>
+                <Field label="Work email" hint="We never share it." error={errors.email}>
+                  {({ id, describedBy, invalid }) => (
+                    <Input
+                      id={id}
+                      name="email"
+                      type="email"
+                      defaultValue="you@company.com"
+                      aria-describedby={describedBy}
+                      invalid={invalid}
+                    />
+                  )}
+                </Field>
+
+                <Field label="New password" hint="At least 12 characters.">
+                  {({ id, describedBy }) => (
+                    <PasswordInput id={id} name="password" aria-describedby={describedBy} strength />
+                  )}
+                </Field>
+
+                <Field label="Plan">
+                  {({ id }) => (
+                    <Select
+                      id={id}
+                      name="plan"
+                      defaultValue="pro"
+                      options={[
+                        { value: "free", label: "Free" },
+                        { value: "pro", label: "Pro" },
+                        { value: "team", label: "Team" },
+                      ]}
+                    />
+                  )}
+                </Field>
+
+                <Switch checked={updates} onChange={setUpdates} label="Email me about product updates" />
+
+                <Button type="submit" full>
+                  Save changes
+                </Button>
+              </Stack>
+            </form>
+          </CardBody>
+        </Card>
+
+        <Alert tone="info" title="Rebrand the whole kit from one file">
+          Open <code>app/lacspace-ui.css</code>. It maps this template&rsquo;s accent, radius and font
+          onto the kit&rsquo;s variables, so the components already match \u2014 and they follow your
+          existing dark-mode toggle.
+        </Alert>
+
+        <Card>
+          <CardBody>
+            <Stack direction="row" gap={2} align="center" wrap>
+              <Badge tone="success" dot>
+                Live
+              </Badge>
+              <Button variant="soft" onClick={() => toast("Saved to drafts")}>
+                Show a toast
+              </Button>
+              <Button tone="danger" variant="soft" onClick={() => setConfirming(true)}>
+                Delete account
+              </Button>
+            </Stack>
+          </CardBody>
+        </Card>
+      </Stack>
+
+      <ConfirmDialog
+        open={confirming}
+        onOpenChange={setConfirming}
+        tone="danger"
+        title="Delete this account?"
+        message="Everything in it goes with it. This cannot be undone."
+        confirmLabel="Delete account"
+        onConfirm={async () => {
+          // Return a promise and the button spins, blocks repeat clicks, and
+          // keeps the dialog open if it rejects \u2014 a failed delete never looks
+          // like a successful one.
+          await new Promise((resolve) => setTimeout(resolve, 700));
+          toast({ title: "Account deleted", tone: "success" });
+        }}
+      />
+    </main>
+  );
+}
+`;
+var dataVizRouteLayout = () => `import "@lacspace/components/styles.css";
+import "@lacspace/charts/styles.css";
+import "@lacspace/table/styles.css";
+import "@lacspace/date/styles.css";
+import "../lacspace-ui.css";
+
+// Scoped to this route; move these imports to app/layout.tsx to use the kit
+// everywhere. Order matters: lacspace-ui.css maps this app's tokens onto the
+// kit, so it comes last.
+export default function InsightsLayout({ children }: { children: React.ReactNode }) {
+  return <>{children}</>;
+}
+`;
+var dataVizPage = () => `"use client";
+import { useState } from "react";
+import { Heading, Grid, Stack, Stat, Text } from "@lacspace/components";
+import { LineChart } from "@lacspace/charts";
+import { DataTable, textColumn, badgeColumn, currencyColumn, numberColumn } from "@lacspace/table";
+import { DateRangePicker, defaultPresets } from "@lacspace/date";
+
+// Swap these three arrays for your own data \u2014 nothing else needs to change.
+const MONTHS = ["Apr", "May", "Jun", "Jul", "Aug", "Sep"];
+const REVENUE = [18, 21, 25, 24, 31, 38];
+const TARGET = [20, 22, 24, 26, 28, 30];
+
+type Account = {
+  id: string;
+  account: string;
+  plan: string;
+  seats: number;
+  mrr: number;
+};
+
+const ACCOUNTS: Account[] = [
+  { id: "1", account: "Northwind", plan: "team", seats: 42, mrr: 1890 },
+  { id: "2", account: "Umbrella", plan: "pro", seats: 12, mrr: 540 },
+  { id: "3", account: "Initech", plan: "team", seats: 68, mrr: 3060 },
+  { id: "4", account: "Hooli", plan: "free", seats: 3, mrr: 0 },
+  { id: "5", account: "Stark Industries", plan: "pro", seats: 19, mrr: 855 },
+  { id: "6", account: "Wayne Enterprises", plan: "team", seats: 51, mrr: 2295 },
 ];
+
+export default function InsightsPage() {
+  const [range, setRange] = useState<unknown>(null);
+
+  return (
+    <main className="mx-auto max-w-5xl px-6 py-16">
+      <Stack gap={5}>
+        <Stack direction="row" justify="between" align="center" gap={3} wrap>
+          <div>
+            <Heading level={1}>Insights</Heading>
+            <Text tone="muted">Charts, a data table and a date filter \u2014 all zero-dependency.</Text>
+          </div>
+          <DateRangePicker
+            numberOfMonths={2}
+            presets={defaultPresets()}
+            separator=" \u2013 "
+            onChange={setRange}
+          />
+        </Stack>
+
+        <Grid columns={{ base: 1, md: 3 }} gap={3}>
+          <Stat label="MRR" value="$8,640" delta={12.4} comparison="vs last month" />
+          <Stat label="Seats" value="195" delta={6.1} comparison="vs last month" />
+          <Stat label="Churn" value="1.8%" delta={-0.3} invertDelta comparison="vs last month" />
+        </Grid>
+
+        <LineChart
+          labels={MONTHS}
+          series={[
+            { name: "Revenue", data: REVENUE, area: true },
+            { name: "Target", data: TARGET, dashed: true },
+          ]}
+          curve
+          dots
+          tooltip
+          responsive
+          dataTable
+          formatValue={(n) => "$" + n + "k"}
+        />
+
+        <DataTable<Account>
+          caption="Accounts"
+          data={ACCOUNTS}
+          getRowId={(row) => row.id}
+          columns={[
+            textColumn<Account>("account", { header: "Account", key: "account", pinned: "left" }),
+            badgeColumn<Account>("plan", {
+              header: "Plan",
+              key: "plan",
+              tones: { team: "success", pro: "info", free: "default" },
+            }),
+            numberColumn<Account>("seats", { header: "Seats", key: "seats", aggregate: "sum" }),
+            currencyColumn<Account>("mrr", { header: "MRR", key: "mrr", currency: "USD", aggregate: "sum" }),
+          ]}
+          defaultSort={[{ id: "mrr", direction: "desc" }]}
+          searchable
+          selectable
+          exportable
+          stickyHeader
+        />
+      </Stack>
+    </main>
+  );
+}
+`;
 var aiChatRoute = (_ctx) => `import { resolveConfig } from "@lacspace/providers";
 import { stream } from "@lacspace/ai";
 import type { Message } from "@lacspace/ai";
@@ -8014,9 +8370,24 @@ function backendFiles(ctx) {
   }
   return files;
 }
+function cliVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const rel of ["../package.json", "./package.json", "../../package.json"]) {
+      const file = resolve(here, rel);
+      if (!existsSync(file)) continue;
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      const version = parsed.version;
+      const name = parsed.name;
+      if (typeof version === "string" && (name === "create-lacspace-app" || rel !== "../../package.json")) return version;
+    }
+  } catch {
+  }
+  return "unknown";
+}
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, dryRun: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, version: false, dryRun: false, unknown: [] };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -8039,6 +8410,7 @@ function parseArgs(list) {
     } else if (arg === "--recipe") a.recipe = next();
     else if (arg.startsWith("--recipe=")) a.recipe = arg.slice(9);
     else if (arg === "-h" || arg === "--help") a.help = true;
+    else if (arg === "-v" || arg === "-V" || arg === "--version") a.version = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
@@ -8046,6 +8418,7 @@ function parseArgs(list) {
     else if (arg.startsWith("--with=")) a.features.push(...splitList(arg.slice(7)));
     else if (arg.startsWith("--features=")) a.features.push(...splitList(arg.slice(11)));
     else if (!arg.startsWith("-") && !a.name) a.name = arg;
+    else if (arg.startsWith("-")) a.unknown.push(arg);
   }
   return a;
 }
@@ -8153,6 +8526,7 @@ ${c("bold", "Options")}
   --no-git               Skip git init
   -y, --yes              Accept defaults (needs <name>)
   -h, --help             Show this help
+  -v, --version          Print the version and exit
 
 ${c("bold", "Feature add-ons")} ${c("dim", "(--with) \u2014 free & keyless, local by default")}
 ${FEATURES.map((f) => `  ${f.key.padEnd(11)} ${f.description}`).join("\n")}
@@ -8626,6 +9000,16 @@ async function main() {
     stdout.write(HELP + "\n");
     return;
   }
+  if (args.version) {
+    stdout.write(`create-lacspace-app ${cliVersion()}
+`);
+    return;
+  }
+  if (args.unknown.length) {
+    stdout.write(c("yellow", `
+  ! Unknown option${args.unknown.length > 1 ? "s" : ""}: ${args.unknown.join(", ")} \u2014 ignoring. Run with --help to see every flag.
+`));
+  }
   stdout.write(`
 ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a gorgeous Next.js starter, batteries wired")}
 
@@ -8824,8 +9208,18 @@ ${c("bold", "Your feature add-ons")} ${c("dim", "\u2014 details in LEARN.md")}
 
 `);
 }
-var invokedAsCli = argv[1] ? import.meta.url === pathToFileURL(argv[1]).href : false;
-if (invokedAsCli) {
+function isDirectRun() {
+  const entry = argv[1];
+  if (!entry) return false;
+  const here = import.meta.url;
+  if (here === pathToFileURL(entry).href) return true;
+  try {
+    if (here === pathToFileURL(realpathSync(entry)).href) return true;
+  } catch {
+  }
+  return basename(entry).replace(/\.[cm]?js$/, "") === "create-lacspace-app";
+}
+if (isDirectRun()) {
   main().catch((err) => {
     stdout.write(c("red", `
 \u2717 ${err instanceof Error ? err.message : String(err)}