@mohammad-irfan/create-dashboard-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Irfan 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @mohammad-irfan/create-dashboard-kit
+
+A zero-dependency CLI and project generator for scaffolding standalone, production-ready dashboard applications extracted from JobTrack's signature visual system.
+
+- **Package**: `@mohammad-irfan/create-dashboard-kit`
+- **CLI Command**: `create-dashboard-kit`
+
+---
+
+## 1. Overview
+
+The `create-dashboard-kit` CLI allows you to instantly generate self-contained, domain-agnostic dashboards with:
+- **Curved Canvas Shell** (`sm:rounded-tl-[36px] lg:rounded-tl-[48px]`).
+- **Collapsible Desktop Sidebar Rail & Mobile Drawer**.
+- **Light / Dark Theme System** with anti-flash script and CSS variable tokens.
+- **Centralized Dashboard Configuration** (`src/config/dashboard.config.ts`).
+- **Prebuilt Generic UI Primitives**: AppShell, Header, Sidebar, HeroSurface, PriorityCard, Panel, QuietListCard, EmptyState, StatCard, MetricRow, StatusBadge, Button, Input, Select, SearchBar, ThemeToggle, and scalable SVG icons.
+
+---
+
+## 2. Usage
+
+### Quick Start
+Generate a new dashboard application with zero setup via `npx`:
+
+```bash
+npx @mohammad-irfan/create-dashboard-kit my-dashboard
+```
+
+---
+
+### Interactive Mode
+Run the generator and follow the guided prompts:
+
+```bash
+# Guided interactive questionnaire
+npx @mohammad-irfan/create-dashboard-kit cafe-os
+```
+
+You will be prompted for:
+1. Display / Brand name
+2. Theme preset (`JobTrack Blue`, `Cafe OS Amber`, or `Custom`)
+3. Primary and accent colors (hex)
+4. Default color mode (`system`, `dark`, or `light`)
+5. Button shape (`pill`, `rounded`, `square`)
+6. Card border radius (`large`, `medium`, `small`)
+7. Default sidebar state (`expanded`, `collapsed`)
+8. Include demo data (`yes`, `no`)
+
+---
+
+### Non-Interactive & Preset Examples
+Pass configuration flags to scaffold instantly without prompts:
+
+```bash
+# 1. Preset: Cafe OS Amber (F&B / Kitchen operations)
+npx @mohammad-irfan/create-dashboard-kit cafe-os --preset cafe
+
+# 2. Preset: JobTrack Blue (Modern SaaS Command Center)
+npx @mohammad-irfan/create-dashboard-kit my-saas --preset jobtrack --mode dark
+
+# 3. Custom theme with tailored brand & accent colors
+npx @mohammad-irfan/create-dashboard-kit crm-dashboard --preset custom \
+  --brand "Apex CRM" \
+  --primary "#7c3aed" \
+  --accent "#06b6d4" \
+  --shape pill \
+  --radius large
+```
+
+---
+
+### Global Installation (Optional)
+Install globally to use the `create-dashboard-kit` command directly anywhere:
+
+```bash
+npm install -g @mohammad-irfan/create-dashboard-kit
+create-dashboard-kit my-dashboard
+```
+
+---
+
+## 3. CLI Command Options
+
+| Flag | Description | Values / Examples | Default |
+| :--- | :--- | :--- | :--- |
+| `<project-name>` | Target directory and package name | `my-dashboard`, `cafe-os` | Required |
+| `--brand` | Display / brand title | `"Acme Ops"`, `"Cafe OS"` | Derived from name |
+| `--preset` | Theme preset | `jobtrack`, `cafe`, `custom` | `jobtrack` |
+| `--primary` | Primary brand color (hex) | `#2563eb`, `#d97706`, `#7c3aed` | `#2563eb` |
+| `--accent` | Accent feedback color (hex) | `#059669`, `#15803d`, `#06b6d4` | `#059669` |
+| `--mode` | Default color mode | `system`, `light`, `dark` | `system` |
+| `--shape` | Button border radius shape | `pill`, `rounded`, `square` | `pill` |
+| `--radius` | Card border radius | `large` (2xl), `medium` (xl), `small` (lg) | `large` |
+| `--sidebar` | Default desktop sidebar state | `expanded`, `collapsed` | `expanded` |
+| `--demo` / `--no-demo` | Include mock panels and metrics | `true`, `false` | `true` |
+| `--force`, `-f` | Overwrite existing directory | Flag | `false` |
+| `--help`, `-h` | Display usage instructions | Flag | |
+| `--version`, `-v`| Print CLI version | Flag | |
+
+---
+
+## 4. Generated Project Structure
+
+Every generated project is completely self-contained and independent:
+
+```
+my-dashboard/
+├── index.html
+├── package.json
+├── tsconfig.json
+├── tsconfig.app.json
+├── tsconfig.node.json
+├── vite.config.ts
+├── README.md
+├── public/
+│   └── assets/
+│       └── logo.svg
+├── src/
+│   ├── main.tsx
+│   ├── App.tsx
+│   ├── index.css
+│   ├── index.ts
+│   ├── config/
+│   │   └── dashboard.config.ts    # Central configuration file
+│   ├── design-system/
+│   │   ├── tokens.css             # Theme colors & CSS variables
+│   │   ├── typography.css         # Tabular figures & typography tokens
+│   │   └── animations.css         # Transitions
+│   ├── theme/
+│   │   ├── ThemeContext.tsx       # Light / Dark / System theme provider
+│   │   └── useTheme.ts
+│   └── components/
+│       ├── controls/              # Button, Input, Select, SearchBar, ThemeToggle
+│       ├── feedback/              # StatusBadge, NotificationCenter, Skeleton
+│       ├── icons/                 # Scalable SVG IconSet
+│       ├── layout/                # AppShell, Sidebar, Header, PageHeader
+│       ├── metrics/               # StatCard, MetricRow
+│       ├── navigation/            # NavItem, ShortcutPill
+│       └── surfaces/              # HeroSurface, Panel, PriorityCard, QuietListCard, EmptyState
+└── tests/
+    └── dashboard.test.ts
+```
+
+---
+
+## 5. Security & Safety Principles
+
+- **No Remote Dependencies**: The CLI runs entirely on native Node.js built-ins (`node:readline/promises`, `node:fs`, `node:path`).
+- **Path Traversal Guards**: Project paths are sanitized and validated to prevent writing outside the target working directory.
+- **Overwrite Protection**: Will never overwrite an existing non-empty directory unless `--force` is explicitly specified.
+- **Zero Telemetry**: Never sends network requests, collects metrics, or prompts for credentials.
+- **Zero Business Coupling**: Completely free of Supabase, JobTrack schemas, and backend dependencies.

package/bin/create-dashboard.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { runCli } from '../dist/cli.js'
+
+runCli(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exit(exitCode)
+  })
+  .catch((err) => {
+    console.error('Fatal CLI Error:', err)
+    process.exit(1)
+  })

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+import type { CliFlags } from './types.js';
+export declare function parseArgs(args: string[]): {
+    projectName?: string;
+    flags: CliFlags;
+};
+export declare function printHelp(): void;
+export declare function runCli(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,223 @@
+import path from 'node:path';
+import { validateHexColor } from './validation.js';
+import { promptInteractive } from './prompts.js';
+import { generateProject } from './generator.js';
+export function parseArgs(args) {
+    const flags = {};
+    let projectName;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            flags.help = true;
+        }
+        else if (arg === '--version' || arg === '-v') {
+            flags.version = true;
+        }
+        else if (arg === '--force' || arg === '-f') {
+            flags.force = true;
+        }
+        else if (arg === '--demo') {
+            flags.demo = true;
+        }
+        else if (arg === '--no-demo') {
+            flags.demo = false;
+        }
+        else if (arg === '--brand' && i + 1 < args.length) {
+            flags.brand = args[++i];
+        }
+        else if (arg.startsWith('--brand=')) {
+            flags.brand = arg.slice(8);
+        }
+        else if (arg === '--preset' && i + 1 < args.length) {
+            flags.preset = args[++i];
+        }
+        else if (arg.startsWith('--preset=')) {
+            flags.preset = arg.slice(9);
+        }
+        else if (arg === '--primary' && i + 1 < args.length) {
+            flags.primary = args[++i];
+        }
+        else if (arg.startsWith('--primary=')) {
+            flags.primary = arg.slice(10);
+        }
+        else if (arg === '--accent' && i + 1 < args.length) {
+            flags.accent = args[++i];
+        }
+        else if (arg.startsWith('--accent=')) {
+            flags.accent = arg.slice(9);
+        }
+        else if (arg === '--mode' && i + 1 < args.length) {
+            flags.mode = args[++i];
+        }
+        else if (arg.startsWith('--mode=')) {
+            flags.mode = arg.slice(7);
+        }
+        else if (arg === '--shape' && i + 1 < args.length) {
+            flags.shape = args[++i];
+        }
+        else if (arg.startsWith('--shape=')) {
+            flags.shape = arg.slice(8);
+        }
+        else if (arg === '--radius' && i + 1 < args.length) {
+            flags.radius = args[++i];
+        }
+        else if (arg.startsWith('--radius=')) {
+            flags.radius = arg.slice(9);
+        }
+        else if (arg === '--sidebar' && i + 1 < args.length) {
+            flags.sidebar = args[++i];
+        }
+        else if (arg.startsWith('--sidebar=')) {
+            flags.sidebar = arg.slice(10);
+        }
+        else if (!arg.startsWith('-') && !projectName) {
+            projectName = arg;
+        }
+    }
+    return { projectName, flags };
+}
+export function printHelp() {
+    console.log(`
+create-dashboard-kit — Scaffold customized dashboard applications
+
+USAGE:
+  create-dashboard-kit <project-name> [options]
+
+OPTIONS:
+  --brand <name>        Display/brand name
+  --preset <preset>     Theme preset: 'jobtrack' | 'cafe' | 'custom'
+  --primary <hex>       Primary brand color in hex (e.g. #2563eb)
+  --accent <hex>        Accent brand color in hex (e.g. #059669)
+  --mode <mode>         Default color mode: 'system' | 'light' | 'dark'
+  --shape <shape>       Button shape: 'pill' | 'rounded' | 'square'
+  --radius <radius>     Card radius: 'small' | 'medium' | 'large'
+  --sidebar <state>     Sidebar desktop state: 'expanded' | 'collapsed'
+  --demo / --no-demo    Include demo panels & mock metrics (default: true)
+  --force, -f           Overwrite target directory if it already exists
+  --help, -h            Show this help message
+  --version, -v         Show version
+
+EXAMPLES:
+  # Interactive mode
+  create-dashboard-kit my-dashboard
+
+  # Non-interactive Cafe OS setup
+  create-dashboard-kit cafe-os \
+    --brand "Cafe OS" \
+    --preset cafe \
+    --primary "#d97706" \
+    --accent "#15803d" \
+    --mode dark
+
+  # Non-interactive Custom SaaS setup
+  create-dashboard-kit my-saas \
+    --brand "My SaaS" \
+    --preset custom \
+    --primary "#7c3aed" \
+    --accent "#06b6d4" \
+    --shape pill \
+    --radius large
+`);
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    const { projectName: cliProjectName, flags } = parseArgs(argv);
+    if (flags.help) {
+        printHelp();
+        return 0;
+    }
+    if (flags.version) {
+        console.log('create-dashboard-kit v1.0.0');
+        return 0;
+    }
+    let options;
+    // Determine if all required options are provided non-interactively
+    const isNonInteractive = Boolean(cliProjectName) &&
+        (Boolean(flags.preset) || Boolean(flags.primary) || Boolean(flags.brand));
+    if (isNonInteractive && cliProjectName) {
+        const rawPreset = flags.preset?.toLowerCase();
+        const preset = rawPreset === 'cafe' ? 'cafe' : rawPreset === 'custom' ? 'custom' : 'jobtrack';
+        let primary = flags.primary || (preset === 'cafe' ? '#d97706' : '#2563eb');
+        let accent = flags.accent || (preset === 'cafe' ? '#15803d' : '#059669');
+        if (flags.primary && !validateHexColor(flags.primary)) {
+            console.error(`❌ Invalid primary color: "${flags.primary}". Must be a valid hex color (e.g. #2563eb).`);
+            return 1;
+        }
+        if (flags.accent && !validateHexColor(flags.accent)) {
+            console.error(`❌ Invalid accent color: "${flags.accent}". Must be a valid hex color (e.g. #059669).`);
+            return 1;
+        }
+        const rawMode = flags.mode?.toLowerCase();
+        const defaultMode = rawMode === 'light' ? 'light' : rawMode === 'dark' ? 'dark' : 'system';
+        const rawShape = flags.shape?.toLowerCase();
+        const buttonShape = rawShape === 'rounded' ? 'rounded' : rawShape === 'square' ? 'square' : 'pill';
+        const rawRadius = flags.radius?.toLowerCase();
+        const cardRadius = rawRadius === 'small' ? 'small' : rawRadius === 'medium' ? 'medium' : 'large';
+        const rawSidebar = flags.sidebar?.toLowerCase();
+        const sidebarState = rawSidebar === 'collapsed' ? 'collapsed' : 'expanded';
+        const derivedName = path.basename(cliProjectName.replace(/[\\/]+$/, ''));
+        const defaultBrand = derivedName
+            .split(/[-_]/)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(' ');
+        const targetDir = cliProjectName.startsWith('.') || cliProjectName.startsWith('/')
+            ? cliProjectName
+            : `./${cliProjectName}`;
+        options = {
+            projectName: derivedName,
+            targetDir,
+            brandName: flags.brand || defaultBrand,
+            preset,
+            primaryColor: primary,
+            accentColor: accent,
+            defaultMode,
+            buttonShape,
+            cardRadius,
+            sidebarState,
+            includeDemo: flags.demo !== false,
+            framework: 'react-vite',
+            force: flags.force,
+        };
+    }
+    else {
+        // Interactive prompt mode
+        try {
+            options = await promptInteractive(cliProjectName);
+            options.force = flags.force;
+        }
+        catch (err) {
+            if (err?.message?.includes('closed') || err?.name === 'AbortError') {
+                console.log('\nOperation cancelled.');
+                return 130;
+            }
+            throw err;
+        }
+    }
+    // Execute Project Generator
+    try {
+        console.log(`\n📦 Scaffolding dashboard in ${options.targetDir}...`);
+        const result = generateProject(options);
+        const presetName = options.preset === 'cafe'
+            ? 'Cafe OS Amber'
+            : options.preset === 'custom'
+                ? 'Custom Theme'
+                : 'JobTrack Blue';
+        console.log('\n' + '='.repeat(50));
+        console.log('✅ Created project:');
+        console.log(`   ${options.brandName}`);
+        console.log('\n📍 Location:');
+        console.log(`   ${path.resolve(result.targetDir)}`);
+        console.log('\n🎨 Theme:');
+        console.log(`   ${presetName} (${options.primaryColor})`);
+        console.log(`   Mode: ${options.defaultMode} | Shape: ${options.buttonShape} | Radius: ${options.cardRadius}`);
+        console.log('\n🚀 Next steps:');
+        console.log(`   cd ${options.projectName}`);
+        console.log('   npm install');
+        console.log('   npm run dev');
+        console.log('='.repeat(50) + '\n');
+        return 0;
+    }
+    catch (err) {
+        console.error(`\n❌ Error: ${err?.message || String(err)}\n`);
+        return 1;
+    }
+}

package/dist/configBuilder.d.ts

@@ -0,0 +1,8 @@
+import type { GeneratorOptions } from './types.js';
+export declare function buildDashboardConfigFile(options: GeneratorOptions): string;
+export declare function buildTokensCssFile(options: GeneratorOptions): string;
+export declare function buildIndexHtml(options: GeneratorOptions): string;
+export declare function buildLogoSvg(options: GeneratorOptions): string;
+export declare function buildAppTsx(options: GeneratorOptions): string;
+export declare function buildPackageJson(options: GeneratorOptions): string;
+export declare function buildProjectReadme(options: GeneratorOptions): string;