infaira-canvas 0.1.9

package/dist/commands/upload.js

@@ -0,0 +1,164 @@
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import http from 'http';
+import { URL } from 'url';
+import { validateBundleJson } from './init.js';
+// ─── .env reader (no external deps) ──────────────────────────────────────────
+function readDotEnv() {
+    const envPath = path.resolve(process.cwd(), '.env');
+    if (!fs.existsSync(envPath))
+        return {};
+    const lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+    const result = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx < 1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+        if (key)
+            result[key] = val;
+    }
+    return result;
+}
+// ─── Multipart form builder ───────────────────────────────────────────────────
+function buildMultipartBody(boundary, fields) {
+    const parts = [];
+    for (const field of fields) {
+        const header = `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="${field.name}"; filename="${field.filename}"\r\n` +
+            `Content-Type: ${field.contentType}\r\n\r\n`;
+        parts.push(Buffer.from(header, 'utf-8'));
+        parts.push(field.data);
+        parts.push(Buffer.from('\r\n', 'utf-8'));
+    }
+    parts.push(Buffer.from(`--${boundary}--\r\n`, 'utf-8'));
+    return Buffer.concat(parts);
+}
+// ─── HTTP request helper ──────────────────────────────────────────────────────
+function postMultipart(targetUrl, token, body, boundary) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(targetUrl);
+        const isHttps = parsed.protocol === 'https:';
+        const lib = isHttps ? https : http;
+        const options = {
+            method: 'POST',
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            headers: {
+                'Content-Type': `multipart/form-data; boundary=${boundary}`,
+                'Content-Length': body.length,
+                Authorization: `Bearer ${token}`,
+            },
+        };
+        const req = lib.request(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+// ─── Main export ──────────────────────────────────────────────────────────────
+export async function handleUpload(opts) {
+    const env = readDotEnv();
+    // Resolve url and token: flags take precedence, then .env, then ICAN_* env vars
+    const url = opts.url || env['ICAN_URL'] || process.env['ICAN_URL'] || '';
+    const token = opts.token || env['ICAN_TOKEN'] || process.env['ICAN_TOKEN'] || '';
+    if (!url) {
+        console.error('Error: portal URL is required.\n  Pass --url <url> or set ICAN_URL in .env');
+        process.exit(1);
+    }
+    if (!token) {
+        console.error('Error: auth token is required.\n  Pass --token <token> or set ICAN_TOKEN in .env');
+        process.exit(1);
+    }
+    const { bundlePath, scriptPath } = opts;
+    const resolvedBundle = path.resolve(bundlePath);
+    const resolvedScript = path.resolve(scriptPath);
+    // ── Check files exist ──
+    if (!fs.existsSync(resolvedBundle)) {
+        console.error(`Error: bundle.json not found: ${resolvedBundle}`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(resolvedScript)) {
+        const isDefaultDist = resolvedScript.includes('dist/main.js') || resolvedScript.includes('dist\\main.js');
+        if (isDefaultDist) {
+            console.error(`Error: dist/main.js not found. Run "npm run build" first.`);
+        }
+        else {
+            console.error(`Error: script file not found: ${resolvedScript}`);
+        }
+        process.exit(1);
+    }
+    const bundleData = fs.readFileSync(resolvedBundle);
+    const scriptData = fs.readFileSync(resolvedScript);
+    // ── Validate bundle.json structure ──
+    const validation = validateBundleJson(bundleData.toString('utf-8'));
+    if (!validation.valid) {
+        console.error(`Error: invalid bundle.json — ${validation.error}`);
+        process.exit(1);
+    }
+    const bundleName = validation.data.name ?? validation.data.id;
+    const widgetCount = validation.data.widgets.length;
+    // ── Upload ──
+    const boundary = `----ICanFormBoundary${Date.now().toString(16)}`;
+    const body = buildMultipartBody(boundary, [
+        { name: 'bundleJson', filename: 'bundle.json', contentType: 'application/json', data: bundleData },
+        { name: 'scriptFile', filename: 'main.js', contentType: 'application/javascript', data: scriptData },
+    ]);
+    const uploadUrl = url.replace(/\/$/, '') + '/api/bundles/upload';
+    const scriptKb = (scriptData.length / 1024).toFixed(1);
+    console.log('');
+    console.log(`  Bundle   : ${bundleName}`);
+    console.log(`  Widgets  : ${widgetCount}`);
+    console.log(`  Size     : ${scriptKb} KB`);
+    console.log(`  Endpoint : ${uploadUrl}`);
+    console.log('');
+    process.stdout.write('  Uploading ...');
+    let responseText;
+    try {
+        responseText = await postMultipart(uploadUrl, token, body, boundary);
+        process.stdout.write(' done\n\n');
+    }
+    catch (err) {
+        process.stdout.write('\n');
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: upload failed — ${message}`);
+        process.exit(1);
+    }
+    let result;
+    try {
+        result = JSON.parse(responseText);
+    }
+    catch {
+        console.error('Error: unexpected response from server (not JSON):');
+        console.error(responseText.slice(0, 500));
+        process.exit(1);
+    }
+    if (!result.success) {
+        const errCode = result.error?.code ?? 'UNKNOWN';
+        const errMsg = result.error?.message ?? 'Unknown error';
+        console.error(`\u2716 Upload failed [${errCode}]: ${errMsg}`);
+        process.exit(1);
+    }
+    const data = result.data ?? {};
+    console.log('\u2714 Bundle uploaded successfully!');
+    if (data.id)
+        console.log(`  Bundle ID : ${data.id}`);
+    if (data.name)
+        console.log(`  Name      : ${data.name}`);
+    if (data.version)
+        console.log(`  Version   : ${data.version}`);
+    if (data.widgets && data.widgets.length > 0) {
+        console.log(`  Widgets   : ${data.widgets.map((w) => w.name).join(', ')}`);
+    }
+    console.log('');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { handleInit, validateBundleJson } from './commands/init.js';
+import { handleUpload } from './commands/upload.js';
+import fs from 'fs';
+import path from 'path';
+// ─── Help text ────────────────────────────────────────────────────────────────
+function printHelp() {
+    console.log(`
+  infaira-canvas — InfAIra Canvas Widget CLI
+
+  Usage:
+    infaira-canvas init <name>            Scaffold a new widget project
+    infaira-canvas upload [options]       Upload a built widget bundle to the portal
+    infaira-canvas validate               Validate bundle.json in the current directory
+    infaira-canvas help                   Show this help message
+
+  Examples:
+    infaira-canvas init my-sales-widget
+
+    infaira-canvas validate
+
+    infaira-canvas upload \\
+      --bundle ./bundle.json \\
+      --script ./dist/main.js
+    (reads ICAN_URL and ICAN_TOKEN from .env automatically)
+
+    infaira-canvas upload \\
+      --url http://localhost:4000 \\
+      --token eyJhbGci... \\
+      --bundle ./bundle.json \\
+      --script ./dist/main.js
+
+  Upload options:
+    --url      <url>     Portal base URL (overrides ICAN_URL in .env)
+    --token    <token>   Auth token JWT (overrides ICAN_TOKEN in .env)
+    --bundle   <path>    Path to bundle.json  (default: ./bundle.json)
+    --script   <path>    Path to main.js      (default: ./dist/main.js)
+
+  Environment variables (set in .env or shell):
+    ICAN_URL      Portal base URL
+    ICAN_TOKEN    Auth token JWT
+`);
+}
+// ─── Argument parser ──────────────────────────────────────────────────────────
+function parseFlags(args) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--') && i + 1 < args.length) {
+            const key = arg.slice(2);
+            const next = args[i + 1];
+            if (!next.startsWith('--')) {
+                flags[key] = next;
+                i++;
+            }
+        }
+    }
+    return flags;
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        printHelp();
+        process.exit(0);
+    }
+    const command = args[0];
+    switch (command) {
+        case 'init': {
+            const name = args[1];
+            if (!name) {
+                console.error('Error: missing widget name.\n  Usage: infaira-canvas init <name>');
+                process.exit(1);
+            }
+            await handleInit(name);
+            break;
+        }
+        case 'validate': {
+            const bundlePath = path.resolve(process.cwd(), 'bundle.json');
+            if (!fs.existsSync(bundlePath)) {
+                console.error('Error: bundle.json not found in current directory.');
+                console.error('       Run this command from inside your widget project folder.');
+                process.exit(1);
+            }
+            const raw = fs.readFileSync(bundlePath, 'utf-8');
+            const result = validateBundleJson(raw);
+            if (!result.valid) {
+                console.error(`\u2716 bundle.json is invalid: ${result.error}`);
+                process.exit(1);
+            }
+            const { data } = result;
+            console.log('\u2714 bundle.json is valid');
+            console.log(`  Bundle ID : ${data.id}`);
+            console.log(`  Name      : ${data.name ?? '(not set)'}`);
+            console.log(`  Version   : ${data.version ?? '(not set)'}`);
+            console.log(`  Widgets   : ${data.widgets.map(w => w.id).join(', ')}`);
+            break;
+        }
+        case 'upload': {
+            const flags = parseFlags(args.slice(1));
+            // Apply sensible defaults so you can just run "infaira-canvas upload" from widget folder
+            const bundle = flags['bundle'] ?? './bundle.json';
+            const script = flags['script'] ?? './dist/main.js';
+            await handleUpload({
+                url: flags['url'] ?? '',
+                token: flags['token'] ?? '',
+                bundlePath: bundle,
+                scriptPath: script,
+            });
+            break;
+        }
+        default: {
+            console.error(`Unknown command: "${command}"`);
+            printHelp();
+            process.exit(1);
+        }
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Fatal error: ${message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "infaira-canvas",
+  "version": "0.1.9",
+  "description": "InfAIra Canvas CLI — Widget development toolkit for InfAIra Canvas",
+  "keywords": [
+    "infaira",
+    "ican",
+    "widget",
+    "cli",
+    "scaffold"
+  ],
+  "homepage": "https://infaira.co",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "infaira-canvas": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates/resources",
+    "templates/ican.d.ts",
+    "templates/designer.d.ts",
+    "templates/index.html",
+    "templates/ui.html",
+    "templates/site.webmanifest",
+    "templates/README.md",
+    "templates/ICan-Widget-Theming-Guide.md",
+    "templates/ICan-Customizing-Components.md",
+    "templates/ICan-Widget-Styling-Patterns.md",
+    "templates/ICan-Widget-Development-Guide.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/ICan-Customizing-Components.md

@@ -0,0 +1,195 @@
+# Customizing ICan Components — `style` and `className`
+
+Every ICan component (`Card`, `Button`, `Badge`, `StatCard`, `Input`, `Tabs`,
+`Modal`, charts, etc.) accepts two universal style hooks:
+
+| Prop        | Purpose                                                                  |
+|-------------|--------------------------------------------------------------------------|
+| `style`     | Inline overrides merged on top of the component’s default inline styles  |
+| `className` | A custom class merged with the component’s built-in class (if any)       |
+
+Both work identically in `npm run dev` (the local harness) and in the ICan portal
+after upload — the dev harness mirrors the portal’s `widget-bridge.ts` behavior.
+
+---
+
+## The Three Customization Patterns
+
+### 1. ICan component + your `style` prop
+
+Use this when you want to keep the component’s structure but tweak its
+appearance with one-off overrides. Always go through CSS variables so themes
+keep working:
+
+```tsx
+<Card style={{
+  border: '2px solid var(--ican-accent)',
+  background: 'var(--ican-accent-dim)',
+  borderRadius: 'var(--ican-radius-lg)',
+  padding: '24px',
+}}>
+  …
+</Card>
+
+<Button
+  label="View Report"
+  variant="primary"
+  style={{
+    borderRadius: 'var(--ican-radius-md)',
+    padding: '8px 20px',
+    fontWeight: 600,
+  }}
+  onClick={onClick}
+/>
+```
+
+### 2. Build your own elements (no ICan component)
+
+Skip the component library entirely and style raw `<div>` / `<button>` elements
+in SCSS using ICan CSS variables:
+
+```tsx
+<div className="stat-card">
+  <span className="stat-card__label">Active Users</span>
+  <span className="stat-card__value">12,847</span>
+</div>
+```
+
+```scss
+.stat-card {
+  background: var(--ican-card-bg);
+  border: 1px solid var(--ican-glass-border);
+  border-radius: var(--ican-radius-lg);
+  padding: 16px;
+  backdrop-filter: var(--ican-backdrop-filter);
+}
+.stat-card__label { color: var(--ican-secondary-text); font-size: 11px; }
+.stat-card__value { color: var(--ican-primary-text); font-size: 1.5rem; }
+```
+
+### 3. ICan component + `className` AND `style`
+
+Use `className` for layout / structural rules (in your SCSS) and `style` for
+small contextual overrides. This keeps SCSS the source of truth for theming
+while inline `style` handles per-instance tweaks:
+
+```tsx
+<Card className="order-card" style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+  <Badge className="live-badge" label="LIVE" variant="success" />
+  <Button className="go-btn" label="Go to Orders →" style={{ width: '100%' }} onClick={onClick} />
+</Card>
+```
+
+```scss
+.order-card  { padding: 20px !important; border-radius: var(--ican-radius-lg) !important; }
+.live-badge  { padding: 3px 8px !important; }
+.go-btn      { margin-top: auto; border-radius: var(--ican-radius-md) !important; }
+```
+
+> Why `!important`?  ICan components ship with inline `style`. SCSS class rules
+> can’t override inline styles without `!important`. If you’d rather avoid it,
+> put the value in the `style` prop instead.
+
+---
+
+## Style Merge Order (most → least specific)
+
+When all three are present, the final rendered style is computed as:
+
+1. Component’s built-in inline `style`  *(lowest priority)*
+2. Your `style` prop                    *(overrides #1)*
+3. Your `className` rule with `!important` in SCSS *(overrides everything)*
+4. Your `className` rule **without** `!important` *(only overrides #1)*
+
+Pick the layer that matches the override’s scope:
+
+| Override type                              | Best layer                          |
+|--------------------------------------------|-------------------------------------|
+| One-off inline tweak                       | `style` prop                        |
+| Reusable structural rule                   | `className` + SCSS                  |
+| Replace a built-in inline default          | `className` + SCSS + `!important`   |
+
+---
+
+## Always Use ICan CSS Variables Inside Overrides
+
+Whether you go via `style` or `className`, your overrides must still resolve
+through CSS variables so the four themes (Dark / Light / Glass-Dark /
+Glass-Light) keep working:
+
+```tsx
+// ✅  Theme-aware
+style={{ background: 'var(--ican-accent-dim)', color: 'var(--ican-primary-text)' }}
+
+// ❌  Hardcoded — breaks on 3 of 4 themes
+style={{ background: '#7c3aed22', color: '#fafafa' }}
+```
+
+See [ICan-Widget-Theming-Guide.md](./ICan-Widget-Theming-Guide.md) for the full
+list of CSS variables and the four-theme matrix.
+
+---
+
+## Dev Harness vs. Portal Parity
+
+The dev harness mock (`resources/ican-components.js`) and the portal’s
+`widget-bridge.ts` both apply your `className` and merge your `style` over the
+component’s defaults. So if a customization works in `npm run dev`, it works in
+the portal — and vice versa.
+
+If you ever notice a mismatch, it’s a harness bug — please file an issue and
+we’ll sync the harness back to the portal’s behavior.
+
+---
+
+## v0.1.9 — New Component Features
+
+The 0.1.9 release added several developer-friendly props to existing
+components. Highlights worth knowing:
+
+| Component | What’s new |
+|-----------|-----------|
+| `Button` | `icon` prop — render an icon (string or emoji) before the label. |
+| `Card` | `header` and `footer` slots — pass any node; rendered with built-in dividers. |
+| `StatCard` | `description` prop — small subtext under the value (e.g. “vs last month”). |
+| `NotificationBlock` | `title` prop — bold heading above `message`. |
+| `Modal` | Closes on **Escape** by default. Pass `closable={false}` to disable Escape, X-button, and backdrop click for forced flows. |
+| `Tabs` | Arrow-key navigation between tabs (`role="tablist"` for a11y). |
+| `Tooltip` | `delay` prop (default 200ms) prevents flicker on quick mouse-overs. |
+| `Pagination` | Shows `Page X / Y` and a jump-to-page input when there are >5 pages. |
+| `DataTable` | Set `sortable: true` per column → header becomes clickable; cycles `asc → desc → off`. Row-hover background uses `--ican-hover`. |
+| `ItemCard` | When `onClick` is provided, the card lifts on hover (`translateY(-2px)` + shadow). |
+| `RadialGauge` | Hover anywhere on the gauge → tooltip showing exact value and percentage. |
+| `LineChart` / `BarChart` | Render a clean *“No data”* state when given empty input (no more crashes). |
+| `Input`, `TextArea`, `Select` | Themed focus ring using `--ican-accent` / `--ican-accent-dim`. |
+
+### Quick examples
+
+```tsx
+<Button icon="↻" label="Refresh" onClick={refresh} />
+
+<Card header="Active Sessions" footer={<Button label="View all" onClick={…} />}>
+  …
+</Card>
+
+<StatCard label="Revenue" value="$248K" trend={12.4} description="vs last month" />
+
+<NotificationBlock type="warning" title="High load" message="Approaching rate limit." />
+
+<Modal open={open} onClose={…} title="Required" closable={false}>
+  Accept the terms to continue.
+</Modal>
+
+<DataTable
+  rows={rows}
+  columns={[
+    { key: 'name',   label: 'Name',   sortable: true },
+    { key: 'status', label: 'Status', sortable: true },
+    { key: 'load',   label: 'Load' },
+  ]}
+/>
+
+<Tooltip content="Refresh data" delay={400}>
+  <IconButton type="refresh" onClick={refresh} />
+</Tooltip>
+```