create-nativecore 0.1.1 → 0.2.1

package/template/src/styles/variables.css

@@ -0,0 +1,152 @@
+/**
+ * CSS Variables - Design System
+ * 
+ * ⚠️ DEVELOPER CUSTOMIZATION ZONE ⚠️
+ * 
+ * This file is for YOUR custom variables and theme overrides.
+ * Feel free to add, modify, or remove any variables here.
+ * 
+ * Framework variables (prefixed with --nc-) are in core-variables.css.
+ * DO NOT use the --nc- prefix here to avoid conflicts.
+ * 
+ * Optional: Override framework theme colors by setting --nc-theme-* variables:
+ * --nc-theme-primary: #your-color;
+ * --nc-theme-primary-light: #your-light-color;
+ * --nc-theme-primary-dark: #your-dark-color;
+ * --nc-theme-secondary: #your-secondary-color;
+ * --nc-theme-accent: #your-accent-color;
+ */
+:root {
+    /* Brand Colors - Professional Emerald & Slate */
+    --color-primary: #10b981;
+    --color-primary-light: #34d399;
+    --color-primary-white: #ffffff;
+    --color-primary-dark: #059669;
+    --color-secondary: #3b82f6;
+    --color-accent: #0f172a;
+    
+    /* Gradients - Subtle and Modern */
+    --gradient-primary: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    --gradient-secondary: linear-gradient(135deg, #3b82f6 0%, #2563eb 100%);
+    --gradient-accent: linear-gradient(135deg, #0f172a 0%, #1e293b 100%);
+    --gradient-success: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    --gradient-subtle: linear-gradient(180deg, rgba(255, 255, 255, 0) 0%, rgba(0, 0, 0, 0.02) 100%);
+    --gradient-hero: linear-gradient(135deg, rgba(16, 185, 129, 0.1) 0%, rgba(5, 150, 105, 0.05) 100%);
+    
+    /* Metallic Gradients - Removed for cleaner look */
+    --gradient-gold: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    --gradient-silver: linear-gradient(135deg, #64748b 0%, #475569 100%);
+    --gradient-platinum: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%);
+    --gradient-bronze: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    
+    /* Neutral Colors - Tailwind Slate Palette */
+    --color-white: #ffffff;
+    --color-black: #000000;
+    --color-gray-50: #f8fafc;
+    --color-gray-100: #f1f5f9;
+    --color-gray-200: #e2e8f0;
+    --color-gray-300: #cbd5e1;
+    --color-gray-400: #94a3b8;
+    --color-gray-500: #64748b;
+    --color-gray-600: #475569;
+    --color-gray-700: #334155;
+    --color-gray-800: #1e293b;
+    --color-gray-900: #0f172a;
+    
+    /* Semantic Colors */
+    --color-success: #10b981;
+    --color-warning: #f59e0b;
+    --color-error: #ef4444;
+    --color-info: #3b82f6;
+    
+    /* Text Colors */
+    --color-text: #0f172a;
+    --color-text-secondary: #64748b;
+    --color-text-muted: #94a3b8;
+    
+    /* Background Colors */
+    --color-bg: #ffffff;
+    --color-bg-secondary: #f8fafc;
+    --color-bg-tertiary: #f1f5f9;
+    --color-border: #e2e8f0;
+    
+    /* Short aliases for component use */
+    --primary: var(--color-primary);
+    --primary-dark: var(--color-primary-dark);
+    --secondary: var(--color-secondary);
+    --secondary-dark: #2563eb;
+    --success: var(--color-success);
+    --danger: var(--color-error);
+    --text: var(--color-text);
+    --text-secondary: var(--color-text-secondary);
+    --bg: var(--color-bg);
+    --bg-secondary: var(--color-bg-secondary);
+    --border: var(--color-border);
+    
+    /* Shadows - Subtle and Modern */
+    --shadow-xs: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+    --shadow-sm: 0 1px 3px 0 rgba(0, 0, 0, 0.08), 0 1px 2px 0 rgba(0, 0, 0, 0.04);
+    --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.08), 0 2px 4px -1px rgba(0, 0, 0, 0.04);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.08), 0 4px 6px -2px rgba(0, 0, 0, 0.04);
+    --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.08), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+    --shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.15);
+    --shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.06);
+    
+    /* Colored Shadows - For hover effects */
+    --shadow-primary: 0 4px 12px rgba(16, 185, 129, 0.25);
+    --shadow-secondary: 0 4px 12px rgba(59, 130, 246, 0.25);
+    --shadow-success: 0 4px 12px rgba(16, 185, 129, 0.25);
+    
+    /* Typography */
+    --font-family: 'Geist', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    --font-family-mono: 'Geist Mono', 'SF Mono', Monaco, 'Cascadia Code', Consolas, monospace;
+    
+    --font-size-xs: 0.75rem;      /* 12px */
+    --font-size-sm: 0.875rem;     /* 14px */
+    --font-size-base: 1rem;       /* 16px */
+    --font-size-lg: 1.125rem;     /* 18px */
+    --font-size-xl: 1.25rem;      /* 20px */
+    --font-size-2xl: 1.5rem;      /* 24px */
+    --font-size-3xl: 1.875rem;    /* 30px */
+    --font-size-4xl: 2.25rem;     /* 36px */
+    
+    --font-weight-normal: 400;
+    --font-weight-medium: 500;
+    --font-weight-semibold: 600;
+    --font-weight-bold: 700;
+    
+    /* Spacing */
+    --spacing-xs: 0.25rem;    /* 4px */
+    --spacing-sm: 0.5rem;     /* 8px */
+    --spacing-md: 1rem;       /* 16px */
+    --spacing-lg: 1.5rem;     /* 24px */
+    --spacing-xl: 2rem;       /* 32px */
+    --spacing-2xl: 3rem;      /* 48px */
+    --spacing-3xl: 4rem;      /* 64px */
+    
+    /* Border Radius */
+    --radius-sm: 0.25rem;     /* 4px */
+    --radius-md: 0.5rem;      /* 8px */
+    --radius-lg: 0.75rem;     /* 12px */
+    --radius-xl: 1rem;        /* 16px */
+    --radius-2xl: 1.5rem;     /* 24px */
+    --radius-full: 9999px;
+    
+    /* Transitions - Smooth animations */
+    --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-base: 250ms cubic-bezier(0.4, 0, 0.2, 1);
+    --transition-slow: 350ms cubic-bezier(0.4, 0, 0.2, 1);
+    
+    /* Layout */
+    --container-max-width: 100%;
+    --header-height: 70px;
+    
+    /* Z-index Scale */
+    --z-dropdown: 1000;
+    --z-sticky: 1020;
+    --z-fixed: 1030;
+    --z-modal-backdrop: 1040;
+    --z-modal: 1050;
+    --z-popover: 1060;
+    --z-tooltip: 1070;
+}

package/template/src/types/global.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Global Type Declarations
+ */
+
+interface Toast {
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info(message: string): void;
+}
+
+// ── Custom Element Registry ──────────────────────────────────────────────────
+// Registering nc-* elements here gives TypeScript IntelliSense in .ts files:
+//   document.querySelector('nc-button')  →  typed as NcButton
+//   document.createElement('nc-tabs')    →  typed as NcTabs
+
+import type { NcA }        from '../components/core/nc-a.js';
+import type { NcButton }   from '../components/core/nc-button.js';
+import type { NcCard }     from '../components/core/nc-card.js';
+import type { NcTabs }     from '../components/core/nc-tabs.js';
+import type { NcTabItem }  from '../components/core/nc-tab-item.js';
+import type { NcMenu }     from '../components/core/nc-menu.js';
+import type { NcMenuItem } from '../components/core/nc-menu-item.js';
+
+declare global {
+    interface Window {
+        Toast: Toast;
+        router: unknown;
+        __NATIVECORE_DEV__?: boolean;
+        dom: {
+            query: (selector: string) => Element | null;
+            queryAll: (selector: string) => NodeListOf<Element>;
+            $: (selector: string) => Element | null;
+            $$: (selector: string) => NodeListOf<Element>;
+        };
+    }
+
+    interface HTMLElementTagNameMap {
+        'nc-a':         NcA;
+        'nc-button':    NcButton;
+        'nc-card':      NcCard;
+        'nc-tabs':      NcTabs;
+        'nc-tab-item':  NcTabItem;
+        'nc-menu':      NcMenu;
+        'nc-menu-item': NcMenuItem;
+    }
+}

package/template/src/utils/cacheBuster.ts

@@ -0,0 +1,20 @@
+/**
+ * Cache Busting Utility
+ */
+
+const isDevelopment = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';
+
+export const cacheVersion = isDevelopment
+    ? Date.now()
+    : '1.0.0-20260414231644';
+
+export function bustCache(url: string): string {
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}v=${cacheVersion}`;
+}
+
+export async function importWithBust(modulePath: string): Promise<any> {
+    return import(bustCache(modulePath));
+}
+
+export default { cacheVersion, bustCache, importWithBust };

package/template/src/utils/dom.ts

@@ -0,0 +1,149 @@
+/**
+ * DOM Utility Functions
+ * Shorthand helpers for common DOM operations
+ */
+
+export const dom = {
+    /**
+     * Query single element (shorthand for document.querySelector)
+     */
+    query: <T extends Element = Element>(selector: string): T | null =>
+        document.querySelector<T>(selector),
+
+    /**
+     * Query multiple elements (shorthand for document.querySelectorAll)
+     */
+    queryAll: <T extends Element = Element>(selector: string): NodeListOf<T> =>
+        document.querySelectorAll<T>(selector),
+
+    /**
+     * Alias for query (similar to jQuery)
+     */
+    $: <T extends Element = Element>(selector: string): T | null =>
+        document.querySelector<T>(selector),
+
+    /**
+     * Alias for queryAll (similar to jQuery)
+     */
+    $$: <T extends Element = Element>(selector: string): NodeListOf<T> =>
+        document.querySelectorAll<T>(selector),
+
+    /**
+     * Query within a specific parent element (scoped query)
+     * @example dom.within(shadowRoot, '.btn')
+     * @example dom.within('#sidebar', 'a.active')
+     */
+    within: <T extends Element = Element>(
+        parent: Element | ShadowRoot | string,
+        selector: string
+    ): T | null => {
+        const el = typeof parent === 'string' ? document.querySelector(parent) : parent;
+        return el ? el.querySelector<T>(selector) : null;
+    },
+
+    /**
+     * Query all within a specific parent element (scoped query)
+     */
+    withinAll: <T extends Element = Element>(
+        parent: Element | ShadowRoot | string,
+        selector: string
+    ): NodeListOf<T> | T[] => {
+        const el = typeof parent === 'string' ? document.querySelector(parent) : parent;
+        return el ? el.querySelectorAll<T>(selector) : ([] as T[]);
+    },
+
+    /**
+     * Create an element with optional attributes and children
+     * @example dom.create('button', { class: 'btn', type: 'button' }, 'Click me')
+     * @example dom.create('div', { id: 'wrapper' }, childEl1, childEl2)
+     */
+    create: <K extends keyof HTMLElementTagNameMap>(
+        tag: K,
+        attrs?: Record<string, string> | null,
+        ...children: Array<string | Node>
+    ): HTMLElementTagNameMap[K] => {
+        const el = document.createElement(tag);
+        if (attrs) {
+            for (const [key, val] of Object.entries(attrs)) {
+                el.setAttribute(key, val);
+            }
+        }
+        for (const child of children) {
+            if (typeof child === 'string') {
+                el.appendChild(document.createTextNode(child));
+            } else {
+                el.appendChild(child);
+            }
+        }
+        return el;
+    },
+
+    /**
+     * Add one or more CSS classes to an element
+     */
+    addClass: (el: Element | string | null, ...classes: string[]): void => {
+        const target = typeof el === 'string' ? document.querySelector(el) : el;
+        if (target) target.classList.add(...classes);
+    },
+
+    /**
+     * Remove one or more CSS classes from an element
+     */
+    removeClass: (el: Element | string | null, ...classes: string[]): void => {
+        const target = typeof el === 'string' ? document.querySelector(el) : el;
+        if (target) target.classList.remove(...classes);
+    },
+
+    /**
+     * Toggle a CSS class on an element
+     */
+    toggleClass: (el: Element | string | null, cls: string, force?: boolean): void => {
+        const target = typeof el === 'string' ? document.querySelector(el) : el;
+        if (target) target.classList.toggle(cls, force);
+    },
+
+    /**
+     * Show an element (removes display:none inline style)
+     */
+    show: (el: Element | string | null): void => {
+        const target = typeof el === 'string' ? document.querySelector(el) : el;
+        if (target) (target as HTMLElement).style.removeProperty('display');
+    },
+
+    /**
+     * Hide an element (sets display:none inline style)
+     */
+    hide: (el: Element | string | null): void => {
+        const target = typeof el === 'string' ? document.querySelector(el) : el;
+        if (target) (target as HTMLElement).style.display = 'none';
+    },
+
+    /**
+     * Add event listener — returns an unsubscribe function for cleanup
+     * @example const off = dom.listen('#btn', 'click', handler); off(); // removes listener
+     */
+    listen: (
+        selectorOrElement: string | Element | null,
+        eventName: string,
+        handler: (event: any) => void,
+        options?: boolean | AddEventListenerOptions
+    ): () => void => {
+        const element = typeof selectorOrElement === 'string'
+            ? document.querySelector(selectorOrElement)
+            : selectorOrElement;
+
+        if (element) {
+            element.addEventListener(eventName, handler as EventListener, options);
+            return () => element.removeEventListener(eventName, handler as EventListener, options);
+        }
+
+        return () => {};
+    }
+};
+
+// Expose to window for console debugging
+if (typeof window !== 'undefined') {
+    (window as any).dom = dom;
+}
+
+export default dom;

package/template/src/utils/events.ts

@@ -0,0 +1,203 @@
+/**
+ * Event handling utilities for controllers
+ * Works with any component and any event type
+ */
+
+/**
+ * Generic event listener with cleanup
+ * 
+ * Usage:
+ *   on('#myBtn', 'click', handleClick);
+ *   on('#myBtn', 'nc-click', handleClick);
+ *   on('.input', 'input', handleInput);
+ */
+export function on<T = Event>(
+    selector: string, 
+    eventName: string, 
+    handler: (event: T) => void
+): () => void {
+    const elements = document.querySelectorAll(selector);
+    
+    elements.forEach(el => {
+        el.addEventListener(eventName, handler as EventListener);
+    });
+    
+    // Return cleanup function
+    return () => {
+        elements.forEach(el => {
+            el.removeEventListener(eventName, handler as EventListener);
+        });
+    };
+}
+
+/**
+ * Batch event binding for cleaner controller syntax
+ * 
+ * Usage:
+ *   const cleanup = bindEvents({
+ *     'click': {
+ *       '#submitBtn': handleSubmit,
+ *       '#cancelBtn': handleCancel
+ *     },
+ *     'nc-click': {
+ *       '.action-btn': handleAction
+ *     },
+ *     'input': {
+ *       '#searchInput': handleSearch
+ *     }
+ *   });
+ */
+export function bindEvents(
+    bindings: Record<string, Record<string, (event: any) => void>>
+): () => void {
+    const cleanups: Array<() => void> = [];
+    
+    for (const [eventName, handlers] of Object.entries(bindings)) {
+        for (const [selector, handler] of Object.entries(handlers)) {
+            cleanups.push(on(selector, eventName, handler));
+        }
+    }
+    
+    // Return cleanup function that removes all listeners
+    return () => {
+        cleanups.forEach(cleanup => cleanup());
+    };
+}
+
+/**
+ * Shorthand for common events
+ */
+export const onClick = (selector: string, handler: (event: Event) => void) => 
+    on(selector, 'click', handler);
+
+export const onChange = (selector: string, handler: (event: Event) => void) => 
+    on(selector, 'change', handler);
+
+export const onInput = (selector: string, handler: (event: Event) => void) => 
+    on(selector, 'input', handler);
+
+export const onSubmit = (selector: string, handler: (event: Event) => void) => 
+    on(selector, 'submit', handler);
+
+/**
+ * Delegate event to parent container (for dynamic elements)
+ * 
+ * Usage:
+ *   delegate('#container', 'click', '.dynamic-btn', handleClick);
+ */
+export function delegate<T = Event>(
+    containerSelector: string,
+    eventName: string,
+    targetSelector: string,
+    handler: (event: T, target: Element) => void
+): () => void {
+    const container = document.querySelector(containerSelector);
+    if (!container) return () => {};
+    
+    const delegateHandler = (event: Event) => {
+        const target = (event.target as Element).closest(targetSelector);
+        if (target && container.contains(target)) {
+            handler(event as T, target);
+        }
+    };
+    
+    container.addEventListener(eventName, delegateHandler);
+    
+    return () => {
+        container.removeEventListener(eventName, delegateHandler);
+    };
+}
+
+/**
+ * Event scope tracker - automatically collects all listeners for cleanup
+ * Perfect for controllers that need comprehensive cleanup
+ * 
+ * Usage:
+ *   export function myController() {
+ *     const events = trackEvents();
+ *     
+ *     events.on('#btn1', 'click', handler1);
+ *     events.on('#btn2', 'click', handler2);
+ *     events.onClick('#btn3', handler3);
+ *     
+ *     return events.cleanup;
+ *   }
+ */
+export function trackEvents() {
+    const cleanupFunctions: Array<() => void> = [];
+    
+    return {
+        on<T = Event>(selector: string, eventName: string, handler: (event: T) => void): void {
+            cleanupFunctions.push(on(selector, eventName, handler));
+        },
+        
+        onClick(selector: string, handler: (event: Event) => void): void {
+            cleanupFunctions.push(onClick(selector, handler));
+        },
+        
+        onChange(selector: string, handler: (event: Event) => void): void {
+            cleanupFunctions.push(onChange(selector, handler));
+        },
+        
+        onInput(selector: string, handler: (event: Event) => void): void {
+            cleanupFunctions.push(onInput(selector, handler));
+        },
+        
+        onSubmit(selector: string, handler: (event: Event) => void): void {
+            cleanupFunctions.push(onSubmit(selector, handler));
+        },
+        
+        delegate<T = Event>(
+            containerSelector: string,
+            eventName: string,
+            targetSelector: string,
+            handler: (event: T, target: Element) => void
+        ): void {
+            cleanupFunctions.push(delegate(containerSelector, eventName, targetSelector, handler));
+        },
+        
+        cleanup(): void {
+            cleanupFunctions.forEach(cleanup => cleanup());
+            cleanupFunctions.length = 0; // Clear array
+        }
+    };
+}
+
+/**
+ * Subscription scope tracker - automatically collects state watcher unsubscribes for cleanup
+ * The reactive analog to trackEvents() — use this alongside it in controllers and components
+ *
+ * Usage:
+ *   export async function myController() {
+ *     const subs = trackSubscriptions();
+ *     const events = trackEvents();
+ *
+ *     subs.watch(store.user.watch(user => renderUser(user)));
+ *     subs.watch(store.isLoading.watch(loading => toggleSpinner(loading)));
+ *     events.onClick('#btn', handleClick);
+ *
+ *     return () => {
+ *       subs.cleanup();
+ *       events.cleanup();
+ *     };
+ *   }
+ */
+export function trackSubscriptions() {
+    const unsubscribers: Array<() => void> = [];
+
+    return {
+        /**
+         * Register a state watcher unsubscribe function
+         * Pass the return value of any .watch() call directly
+         * @example subs.watch(myState.watch(val => doSomething(val)));
+         */
+        watch(unsubscribe: () => void): void {
+            unsubscribers.push(unsubscribe);
+        },
+
+        cleanup(): void {
+            unsubscribers.forEach(fn => fn());
+            unsubscribers.length = 0;
+        }
+    };
+}