@bloomneo/uikit 1.5.0

package/bin/templates/spa/src/utils/asset.ts

@@ -0,0 +1,6 @@
+export const asset = (path: string): string => {
+  const base = (import.meta as any).env?.BASE_URL || '/';
+  const cleanPath = path.startsWith('/') ? path.slice(1) : path;
+  if (base === '/') return `/${cleanPath}`;
+  return `${base}${cleanPath}`;
+};

package/bin/templates/spa/tsconfig.json.template

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Path mapping */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/bin/templates/spa/tsconfig.node.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/bin/templates/spa/vite.config.ts.template

@@ -0,0 +1,36 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+import tailwindcss from '@tailwindcss/vite'
+import { fileURLToPath } from 'url'
+
+// Get __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  // base: '/', // Uncomment this line to make the default asset loading to '/' rather than relative paths
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 5173,
+    host: true,
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          uikit: ['@bloomneo/uikit']
+        }
+      }
+    }
+  }
+})

package/bin/uikit.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview UIKit CLI - Unified command line interface for @bloomneo/uikit
+ * @description Main CLI entry point with subcommands: create, bundle, serve, build, deploy
+ * @package @bloomneo/uikit
+ * @file /bin/uikit.js
+ */
+
+import { program } from 'commander';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import fs from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read package.json for version
+const packageJson = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+);
+
+program
+  .name('uikit')
+  .description('🎨 UIKit CLI - Create projects, generate themes, and build apps')
+  .version(packageJson.version);
+
+// Create command
+program
+  .command('create')
+  .description('Create a new UIKit project')
+  .argument('<name>', 'project name')
+  .option('--spa', 'create single page application template')
+  .option('--multi', 'create multi-page template with routing')
+  .option('--fbca', 'create feature-based component architecture template')
+  .option('--single', 'create single-page theme showcase (default)')
+  .option('--theme <theme>', 'default theme (base|elegant|metro|studio|vivid)', 'base')
+  .action(async (name, options) => {
+    const { createProject } = await import('./commands/create.js');
+    await createProject(name, options);
+  });
+
+// Bundle command
+program
+  .command('bundle')
+  .description('Bundle custom themes into CSS (supports SPA/Multi/FBCA)')
+  .option('--output <path>', 'output file path')
+  .option('--watch', 'watch for changes and rebuild')
+  .option('--verbose', 'verbose logging')
+  .action(async (options) => {
+    const { bundleThemes } = await import('./commands/bundle.js');
+    await bundleThemes(options);
+  });
+
+// Serve command
+program
+  .command('serve')
+  .description('Start development server')
+  .option('--port <number>', 'port number', '5173')
+  .option('--restart', 'force restart (kill existing processes)')
+  .option('--open', 'automatically open browser')
+  .action(async (options) => {
+    const { startServer } = await import('./commands/serve.js');
+    await startServer(options);
+  });
+
+// Build command
+program
+  .command('build')
+  .description('Build for production')
+  .option('--outDir <dir>', 'output directory', 'dist')
+  .option('--analyze', 'analyze bundle size')
+  .action(async (options) => {
+    const { buildProject } = await import('./commands/build.js');
+    await buildProject(options);
+  });
+
+// Generate command
+program
+  .command('generate')
+  .alias('g')
+  .description('Generate features, components, or custom themes')
+  .argument('<type>', 'type (page|component|hook|feature|theme)')
+  .argument('<name>', 'name (e.g., auth, brand, my-component)')
+  .option('--page', 'generate page component with routing')
+  .option('--component', 'generate reusable component')
+  .option('--feature', 'generate complete feature with pages and components')
+  .option('--theme <theme>', 'UIKit theme to use (base|elegant|metro|studio|vivid)', 'base')
+  .action(async (type, name, options) => {
+    const { generateFeature } = await import('./commands/generate.js');
+    await generateFeature(type, name, options);
+  });
+
+// Deploy command
+program
+  .command('deploy')
+  .description('Generate static site for deployment')
+  .option('--base <path>', 'base path for deployment', '/')
+  .option('--github', 'optimize for GitHub Pages')
+  .action(async (options) => {
+    const { deployProject } = await import('./commands/deploy.js');
+    await deployProject(options);
+  });
+
+// Prerender command
+program
+  .command('prerender')
+  .description('Pre-render SPA routes to static HTML for SEO')
+  .option('--dist <dir>', 'distribution directory', 'dist')
+  .option('--port <number>', 'server port for rendering', '4567')
+  .option('--routes <routes>', 'comma-separated routes or "auto"', '/')
+  .option('--config <file>', 'SEO config JSON file', 'seo.config.json')
+  .option('--baseUrl <url>', 'base URL for canonical links')
+  .action(async (options) => {
+    const { prerenderPages } = await import('./commands/prerender.js');
+    await prerenderPages(options);
+  });
+
+// Optimize command
+program
+  .command('optimize')
+  .description('Optimize images (convert to WebP, compress)')
+  .option('--dir <path>', 'directory to scan', 'public')
+  .option('--quality <number>', 'WebP quality 0-100', '80')
+  .option('--maxWidth <number>', 'max width in pixels', '1200')
+  .option('--webp-only', 'only generate WebP, skip PNG fallback')
+  .action(async (options) => {
+    const { optimizeImages } = await import('./commands/optimize.js');
+    await optimizeImages(options);
+  });
+
+// Parse arguments
+program.parse();

package/cookbook/README.md

@@ -0,0 +1,20 @@
+# UIKit Cookbook
+
+Whole-page patterns assembled from UIKit primitives. These are the recipes
+agents and humans should reach for when starting a new feature, instead of
+designing the layout from scratch.
+
+Each file is a single drop-in component with realistic but minimal data.
+Copy, rename, swap the data source, and ship.
+
+## Recipes
+
+| File | Pattern |
+|---|---|
+| [`crud-page.tsx`](./crud-page.tsx) | List → search/sort → row actions → delete with confirmation → toast |
+| [`dashboard.tsx`](./dashboard.tsx) | Sidebar layout + header + stats grid + recent activity table |
+| [`settings.tsx`](./settings.tsx) | Tabs + form sections + save toast |
+| [`login.tsx`](./login.tsx) | Centered card + email/password form + validation errors |
+| [`delete-flow.tsx`](./delete-flow.tsx) | Destructive action with type-to-confirm + toast |
+
+For single-component snippets see [`../examples/`](../examples/).

package/cookbook/crud-page.tsx

@@ -0,0 +1,99 @@
+/**
+ * CRUD page recipe.
+ *
+ * Searchable, sortable user list with row actions and a delete-with-confirm
+ * flow. The whole thing is ~80 lines instead of the usual 600 because every
+ * piece (PageHeader, DataTable, ConfirmProvider/useConfirm, ToastProvider/toast)
+ * is a UIKit primitive.
+ */
+
+import { useState } from 'react';
+import { Pencil, Trash2, Users } from 'lucide-react';
+import {
+  Button,
+  ConfirmProvider,
+  DataTable,
+  PageHeader,
+  ToastProvider,
+  toast,
+  useConfirm,
+  type DataTableColumn,
+  type RowAction,
+} from '@bloomneo/uikit';
+
+type User = { id: string; name: string; email: string; role: 'admin' | 'user' };
+
+const initialUsers: User[] = [
+  { id: '1', name: 'Alice',  email: 'alice@example.com',  role: 'admin' },
+  { id: '2', name: 'Bob',    email: 'bob@example.com',    role: 'user' },
+  { id: '3', name: 'Carol',  email: 'carol@example.com',  role: 'user' },
+  { id: '4', name: 'Dawud',  email: 'dawud@example.com',  role: 'user' },
+];
+
+function UserListInner() {
+  const [users, setUsers] = useState<User[]>(initialUsers);
+  const confirm = useConfirm();
+
+  const columns: DataTableColumn<User>[] = [
+    { id: 'name',  header: 'Name',  accessorKey: 'name',  sortable: true },
+    { id: 'email', header: 'Email', accessorKey: 'email' },
+    { id: 'role',  header: 'Role',  accessorKey: 'role',  sortable: true },
+  ];
+
+  const actions: RowAction<User>[] = [
+    {
+      id: 'edit',
+      label: 'Edit',
+      icon: Pencil,
+      onClick: (row) => toast(`Editing ${row.name}`),
+    },
+    {
+      id: 'delete',
+      label: 'Delete',
+      icon: Trash2,
+      variant: 'destructive',
+      onClick: async (row) => {
+        const ok = await confirm({
+          title: `Delete ${row.name}?`,
+          description: 'This cannot be undone.',
+          confirmLabel: 'Delete',
+          tone: 'destructive',
+        });
+        if (!ok) return;
+        setUsers((prev) => prev.filter((u) => u.id !== row.id));
+        toast.success(`${row.name} deleted`);
+      },
+    },
+  ];
+
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <PageHeader
+        icon={<Users />}
+        title="User management"
+        description="View and manage all users in your workspace"
+        breadcrumbs={[{ label: 'Admin', href: '/admin' }, { label: 'Users' }]}
+        actions={<Button onClick={() => toast.info('Open add-user dialog')}>Add user</Button>}
+      />
+
+      <DataTable<User>
+        data={users}
+        columns={columns}
+        actions={actions}
+        searchable
+        pagination
+        pageSize={10}
+        getRowId={(row) => row.id}
+      />
+    </div>
+  );
+}
+
+export default function CrudPageRecipe() {
+  return (
+    <ConfirmProvider>
+      <ToastProvider />
+      <UserListInner />
+    </ConfirmProvider>
+  );
+}

package/cookbook/dashboard.tsx

@@ -0,0 +1,89 @@
+/**
+ * Dashboard recipe.
+ *
+ * Stats grid + recent activity table inside a standard page shell.
+ * Drop into any admin layout — works inside <AdminLayout> or alone.
+ */
+
+import { Activity, DollarSign, Package, Users } from 'lucide-react';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  DataTable,
+  PageHeader,
+  formatCurrency,
+  type DataTableColumn,
+} from '@bloomneo/uikit';
+
+type Stat = { label: string; value: string; delta: string; icon: React.ReactNode };
+type Order = { id: string; customer: string; amount: number; status: 'paid' | 'pending' };
+
+const stats: Stat[] = [
+  { label: 'Revenue',  value: formatCurrency(48230), delta: '+12.4%', icon: <DollarSign /> },
+  { label: 'Users',    value: '1,284',                delta: '+3.1%',  icon: <Users /> },
+  { label: 'Orders',   value: '342',                  delta: '+8.0%',  icon: <Package /> },
+  { label: 'Sessions', value: '12,932',               delta: '+22.0%', icon: <Activity /> },
+];
+
+const orders: Order[] = [
+  { id: '#1023', customer: 'Alice', amount: 199.0, status: 'paid' },
+  { id: '#1024', customer: 'Bob',   amount: 49.5,  status: 'pending' },
+  { id: '#1025', customer: 'Carol', amount: 320.0, status: 'paid' },
+];
+
+const orderColumns: DataTableColumn<Order>[] = [
+  { id: 'id',       header: 'Order',    accessorKey: 'id' },
+  { id: 'customer', header: 'Customer', accessorKey: 'customer' },
+  {
+    id: 'amount',
+    header: 'Amount',
+    accessor: (row) => formatCurrency(row.amount),
+    sortable: true,
+    dataType: 'number',
+  },
+  { id: 'status', header: 'Status', accessorKey: 'status' },
+];
+
+export default function DashboardRecipe() {
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <PageHeader title="Dashboard" description="Overview for the last 30 days" />
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+        {stats.map((s) => (
+          <Card key={s.label}>
+            <CardHeader className="flex flex-row items-center justify-between pb-2">
+              <CardTitle className="text-sm font-medium text-muted-foreground">
+                {s.label}
+              </CardTitle>
+              <div className="text-muted-foreground [&>svg]:size-4">{s.icon}</div>
+            </CardHeader>
+            <CardContent>
+              <div className="text-2xl font-semibold">{s.value}</div>
+              <p className="text-xs text-muted-foreground">{s.delta} vs last period</p>
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Recent orders</CardTitle>
+          <CardDescription>The latest activity across your store</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <DataTable<Order>
+            data={orders}
+            columns={orderColumns}
+            searchable={false}
+            pagination={false}
+            getRowId={(row) => row.id}
+          />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/cookbook/delete-flow.tsx

@@ -0,0 +1,59 @@
+/**
+ * Destructive action recipe.
+ *
+ * Demonstrates the high-stakes deletion pattern: a button that opens a
+ * confirm dialog where the user has to type the resource name before the
+ * delete button enables. On success a toast confirms the action.
+ *
+ * Use this for irreversible operations: deleting users, dropping databases,
+ * cancelling subscriptions, etc.
+ */
+
+import {
+  Button,
+  ConfirmProvider,
+  ToastProvider,
+  toast,
+  useConfirm,
+} from '@bloomneo/uikit';
+
+const RESOURCE_NAME = 'production-db';
+
+function DeleteResource() {
+  const confirm = useConfirm();
+
+  async function onDelete() {
+    const ok = await confirm.destructive({
+      title: 'Delete production database',
+      description:
+        'This will permanently destroy the database and all of its data. There is no undo.',
+      verifyText: RESOURCE_NAME,
+      confirmLabel: 'I understand, delete it',
+    });
+    if (!ok) return;
+    // → call your delete API here
+    toast.success(`${RESOURCE_NAME} deleted`);
+  }
+
+  return (
+    <Button variant="destructive" onClick={onDelete}>
+      Delete database
+    </Button>
+  );
+}
+
+export default function DeleteFlowRecipe() {
+  return (
+    <ConfirmProvider>
+      <ToastProvider />
+      <div className="flex flex-col items-start gap-4 p-6">
+        <p className="max-w-md text-sm text-muted-foreground">
+          The button below opens a confirmation dialog. The user must type
+          <code className="mx-1 rounded bg-muted px-1">{RESOURCE_NAME}</code>
+          before the delete button enables.
+        </p>
+        <DeleteResource />
+      </div>
+    </ConfirmProvider>
+  );
+}

package/cookbook/login.tsx

@@ -0,0 +1,85 @@
+/**
+ * Login recipe.
+ *
+ * Centered card with email + password form, inline validation, and a
+ * submit button. No backend — wire your auth call where the comment is.
+ */
+
+import { useState } from 'react';
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  FormField,
+  Input,
+  PasswordInput,
+  ToastProvider,
+  toast,
+} from '@bloomneo/uikit';
+
+export default function LoginRecipe() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+
+  const emailError =
+    email && !email.includes('@') ? 'Enter a valid email address' : undefined;
+  const passwordError =
+    password && password.length < 8 ? 'Must be at least 8 characters' : undefined;
+
+  const canSubmit =
+    email && password && !emailError && !passwordError && !submitting;
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setSubmitting(true);
+    try {
+      // → call your auth API here
+      await new Promise((r) => setTimeout(r, 600));
+      toast.success('Welcome back');
+    } catch {
+      toast.error('Login failed');
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <>
+      <ToastProvider />
+      <div className="flex min-h-screen items-center justify-center bg-muted/30 p-6">
+        <Card className="w-full max-w-sm">
+          <CardHeader>
+            <CardTitle>Sign in</CardTitle>
+            <CardDescription>Welcome back to your workspace</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <form className="flex flex-col gap-4" onSubmit={onSubmit}>
+              <FormField label="Email" required error={emailError}>
+                <Input
+                  type="email"
+                  value={email}
+                  onChange={(e) => setEmail(e.target.value)}
+                  autoComplete="email"
+                />
+              </FormField>
+              <FormField label="Password" required error={passwordError}>
+                <PasswordInput
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  autoComplete="current-password"
+                />
+              </FormField>
+              <Button type="submit" disabled={!canSubmit}>
+                {submitting ? 'Signing in…' : 'Sign in'}
+              </Button>
+            </form>
+          </CardContent>
+        </Card>
+      </div>
+    </>
+  );
+}