create-nativecore 0.1.1 → 0.2.0

package/template/src/components/core/nc-form.ts

@@ -0,0 +1,312 @@
+/**
+ * NcForm + NcField Components
+ *
+ * nc-form:
+ *   A form wrapper that collects values from all nc-* form controls within it,
+ *   runs validation, and emits structured events.
+ *
+ *   Attributes:
+ *     - novalidate: boolean — skip HTML5 native validation
+ *
+ *   Methods:
+ *     - form.getValues(): Record<string, string> — collect all named form control values
+ *     - form.validate(): boolean — trigger validation; returns true if all valid
+ *     - form.reset() — reset all fields to initial value/clear errors
+ *
+ *   Events:
+ *     - submit: CustomEvent<{ values: Record<string, string> }> — on valid submit
+ *     - invalid: CustomEvent<{ fields: string[] }> — on invalid submit (list of failing names)
+ *
+ * nc-field:
+ *   A labelled wrapper for a single form control. Handles the label, hint, and
+ *   error message display in a consistent layout. Pairs naturally with nc-input,
+ *   nc-select, nc-textarea, nc-autocomplete, nc-date-picker, etc.
+ *
+ *   Attributes:
+ *     - label: string — field label
+ *     - for: string — id of the slotted input (for focus on label click)
+ *     - required: boolean — shows required marker
+ *     - hint: string — sub-label hint text
+ *     - error: string — error message (shown in red; overrides hint)
+ *
+ * Usage:
+ *   <nc-form id="signup-form">
+ *     <nc-field label="Email" required hint="We'll never share your email.">
+ *       <nc-input name="email" type="email" placeholder="you@example.com"></nc-input>
+ *     </nc-field>
+ *     <nc-field label="Password" required>
+ *       <nc-input name="password" type="password" show-password-toggle></nc-input>
+ *     </nc-field>
+ *     <nc-button type="submit">Sign up</nc-button>
+ *   </nc-form>
+ *
+ *   document.getElementById('signup-form').addEventListener('submit', e => {
+ *     console.log(e.detail.values);
+ *   });
+ */
+
+import { Component, defineComponent } from '@core/component.js';
+
+// ── NcField ──────────────────────────────────────────────────────────────────
+
+export class NcField extends Component {
+    static useShadowDOM = true;
+
+    static get observedAttributes() {
+        return ['label', 'for', 'required', 'hint', 'error'];
+    }
+
+    template() {
+        const label = this.getAttribute('label') || '';
+        const forAttr = this.getAttribute('for') || '';
+        const required = this.hasAttribute('required');
+        const hint = this.getAttribute('hint') || '';
+        const error = this.getAttribute('error') || '';
+
+        return `
+            <style>
+                :host { display: block; font-family: var(--nc-font-family); }
+
+                .field { display: flex; flex-direction: column; gap: 4px; }
+
+                label {
+                    font-size: var(--nc-font-size-sm);
+                    font-weight: var(--nc-font-weight-medium);
+                    color: var(--nc-text);
+                    cursor: ${forAttr ? 'pointer' : 'default'};
+                }
+
+                .required {
+                    color: var(--nc-danger, #ef4444);
+                    margin-left: 2px;
+                }
+
+                .subtext {
+                    font-size: var(--nc-font-size-xs);
+                    line-height: 1.4;
+                }
+                .subtext--hint  { color: var(--nc-text-muted); }
+                .subtext--error { color: var(--nc-danger, #ef4444); }
+            </style>
+            <div class="field">
+                ${label ? `
+                <label ${forAttr ? `for="${forAttr}"` : ''}>
+                    ${label}${required ? `<span class="required" aria-hidden="true">*</span>` : ''}
+                </label>` : ''}
+                <slot></slot>
+                ${error
+                    ? `<span class="subtext subtext--error" role="alert">${error}</span>`
+                    : hint ? `<span class="subtext subtext--hint">${hint}</span>` : ''}
+            </div>
+        `;
+    }
+
+    setError(msg: string) {
+        if (msg) this.setAttribute('error', msg);
+        else this.removeAttribute('error');
+    }
+
+    clearError() { this.removeAttribute('error'); }
+
+    attributeChangedCallback(name: string, oldValue: string, newValue: string) {
+        if (oldValue !== newValue && this._mounted) this.render();
+    }
+}
+
+defineComponent('nc-field', NcField);
+
+// ── NcForm ───────────────────────────────────────────────────────────────────
+
+const FORM_CONTROLS = [
+    'nc-input', 'nc-textarea', 'nc-select', 'nc-checkbox', 'nc-radio',
+    'nc-switch', 'nc-slider', 'nc-rating', 'nc-number-input',
+    'nc-autocomplete', 'nc-date-picker', 'nc-time-picker', 'nc-color-picker',
+    'input', 'textarea', 'select',
+];
+
+export class NcForm extends Component {
+    static useShadowDOM = true;
+
+    private readonly _submitHandler = this._onSubmit.bind(this);
+
+    private readonly _keydownHandler = (e: Event) => {
+        const ke = e as KeyboardEvent;
+        const target = ke.target as HTMLElement;
+        if (ke.key === 'Enter' && target.tagName !== 'TEXTAREA') {
+            this._handleSubmit();
+        }
+    };
+
+    private readonly _clickHandler = (e: Event) => {
+        const btn = (e.target as HTMLElement).closest<HTMLElement>('[type="submit"], nc-button[type="submit"]');
+        if (btn && this.contains(btn)) {
+            e.preventDefault();
+            this._handleSubmit();
+        }
+    };
+
+    template() {
+        return `
+            <style>
+                :host {
+                    display: block;
+                    width: 100%;
+                }
+            </style>
+            <slot></slot>
+        `;
+    }
+
+    connectedCallback() {
+        super.connectedCallback?.();
+        this.addEventListener('submit', this._submitHandler as EventListener);
+        this.addEventListener('keydown', this._keydownHandler);
+        this.addEventListener('click', this._clickHandler);
+    }
+
+    disconnectedCallback() {
+        this.removeEventListener('submit', this._submitHandler as EventListener);
+        this.removeEventListener('keydown', this._keydownHandler);
+        this.removeEventListener('click', this._clickHandler);
+        super.disconnectedCallback?.();
+    }
+
+    private _onSubmit(e: Event) {
+        const customEvent = e as CustomEvent<{ values?: Record<string, string> }>;
+        if (customEvent.detail?.values) {
+            return;
+        }
+
+        e.preventDefault();
+        this._handleSubmit();
+    }
+
+    private _handleSubmit() {
+        if (!this.hasAttribute('novalidate')) {
+            const valid = this.validate();
+            if (!valid) return;
+        }
+        const values = this.getValues();
+        this.dispatchEvent(new CustomEvent('submit', {
+            bubbles: true, composed: true,
+            detail: { values }
+        }));
+    }
+
+    getValues(): Record<string, string> {
+        const result: Record<string, string> = {};
+        FORM_CONTROLS.forEach(tag => {
+            this.querySelectorAll<HTMLElement>(tag).forEach(el => {
+                const name = el.getAttribute('name');
+                if (!name) return;
+                // nc-checkbox/nc-switch: use checked state
+                if (tag === 'nc-checkbox' || tag === 'nc-switch') {
+                    result[name] = el.hasAttribute('checked') ? 'true' : 'false';
+                } else {
+                    const controlWithValue = el as HTMLElement & { value?: string };
+                    result[name] = controlWithValue.value ?? el.getAttribute('value') ?? (el as HTMLInputElement).value ?? '';
+                }
+            });
+        });
+        return result;
+    }
+
+    validate(): boolean {
+        let valid = true;
+        const invalidFields: string[] = [];
+
+        // Check nc-field wrappers first
+        this.querySelectorAll<NcField>('nc-field').forEach(field => {
+            // Find the first named control inside this field
+            const ctrl = FORM_CONTROLS.map(tag => field.querySelector<HTMLElement>(tag)).find(Boolean) as (HTMLElement & {
+                value?: string;
+                checkValidity?: () => boolean;
+                getValidationMessage?: () => string;
+                clearValidationError?: () => void;
+                validate?: () => boolean;
+            }) | undefined;
+            if (!ctrl) return;
+
+            const name = ctrl.getAttribute('name') || '';
+            const value = ctrl.value ?? ctrl.getAttribute('value') ?? (ctrl as HTMLInputElement).value ?? '';
+            const isRequired = field.hasAttribute('required') || ctrl.hasAttribute('required');
+
+            if (isRequired && !String(value).trim()) {
+                valid = false;
+                field.setError('This field is required.');
+                invalidFields.push(name);
+                ctrl.clearValidationError?.();
+                return;
+            }
+
+            if (typeof ctrl.checkValidity === 'function' && !ctrl.checkValidity()) {
+                valid = false;
+                field.setError(
+                    typeof ctrl.getValidationMessage === 'function'
+                        ? ctrl.getValidationMessage()
+                        : 'Enter a valid value.'
+                );
+                invalidFields.push(name);
+                ctrl.clearValidationError?.();
+                return;
+            }
+
+            field.clearError();
+            ctrl.clearValidationError?.();
+        });
+
+        // Validate standalone controls not wrapped in nc-field.
+        FORM_CONTROLS.forEach(tag => {
+            this.querySelectorAll<HTMLElement>(tag).forEach(ctrl => {
+                if (ctrl.closest('nc-field')) return;
+
+                const element = ctrl as HTMLElement & {
+                    validate?: () => boolean;
+                    checkValidity?: () => boolean;
+                    clearValidationError?: () => void;
+                };
+
+                if (typeof element.validate === 'function') {
+                    const isValid = element.validate();
+                    if (!isValid) {
+                        valid = false;
+                        const name = ctrl.getAttribute('name');
+                        if (name) invalidFields.push(name);
+                    }
+                    return;
+                }
+
+                if (typeof element.checkValidity === 'function' && !element.checkValidity()) {
+                    valid = false;
+                    const name = ctrl.getAttribute('name');
+                    if (name) invalidFields.push(name);
+                    return;
+                }
+
+                element.clearValidationError?.();
+            });
+        });
+
+        if (!valid) {
+            this.dispatchEvent(new CustomEvent('invalid', {
+                bubbles: true, composed: true,
+                detail: { fields: Array.from(new Set(invalidFields)) }
+            }));
+        }
+        return valid;
+    }
+
+    reset() {
+        FORM_CONTROLS.forEach(tag => {
+            this.querySelectorAll<HTMLElement>(tag).forEach(el => {
+                el.setAttribute('value', '');
+                if (tag === 'nc-checkbox' || tag === 'nc-switch') el.removeAttribute('checked');
+            });
+        });
+        this.querySelectorAll<NcField>('nc-field').forEach(f => f.clearError());
+    }
+
+    attributeChangedCallback(_name: string, _oldValue: string, _newValue: string) {}
+}
+
+defineComponent('nc-form', NcForm);

package/template/src/components/core/nc-image.ts

@@ -0,0 +1,184 @@
+/**
+ * NcImage Component — responsive image with lazy loading and skeleton placeholder
+ *
+ * Attributes:
+ *   src         — image URL
+ *   alt         — alt text (required for accessibility)
+ *   width       — intrinsic width (CSS value or px integer)
+ *   height      — intrinsic height
+ *   fit         — CSS object-fit: 'cover'(default)|'contain'|'fill'|'none'|'scale-down'
+ *   position    — CSS object-position (default: 'center')
+ *   radius      — border-radius CSS value or preset: 'none'|'sm'|'md'|'lg'|'full'
+ *   loading     — 'lazy'(default)|'eager'
+ *   fallback    — fallback image URL on error
+ *   placeholder — 'skeleton'(default)|'blur'|'none'
+ *   aspect      — aspect ratio shorthand: '16/9'|'4/3'|'1/1'|'3/2' etc.
+ *   caption     — optional caption text below image
+ *
+ * Events:
+ *   load  — image loaded
+ *   error — image failed
+ *
+ * Usage:
+ *   <nc-image src="/photo.jpg" alt="Mountain view" aspect="16/9" radius="md"></nc-image>
+ */
+import { Component, defineComponent } from '@core/component.js';
+
+const RADIUS: Record<string, string> = {
+    none: '0',
+    sm:   'var(--nc-radius-sm)',
+    md:   'var(--nc-radius-md)',
+    lg:   'var(--nc-radius-lg)',
+    full: '9999px',
+};
+
+export class NcImage extends Component {
+    static useShadowDOM = true;
+
+    private _loaded  = false;
+    private _errored = false;
+
+    static get observedAttributes() { return ['src', 'alt', 'width', 'height', 'fit', 'radius', 'aspect', 'fallback']; }
+
+    template() {
+        const src         = this.getAttribute('src') ?? '';
+        const alt         = this.getAttribute('alt') ?? '';
+        const width       = this.getAttribute('width') ?? '';
+        const height      = this.getAttribute('height') ?? '';
+        const fit         = this.getAttribute('fit') ?? 'cover';
+        const pos         = this.getAttribute('position') ?? 'center';
+        const radius      = this.getAttribute('radius') ?? 'none';
+        const loading     = this.getAttribute('loading') ?? 'lazy';
+        const placeholder = this.getAttribute('placeholder') ?? 'skeleton';
+        const aspect      = this.getAttribute('aspect') ?? '';
+        const caption     = this.getAttribute('caption') ?? '';
+
+        const radVal = RADIUS[radius] ?? radius;
+        const aspectStyle = aspect ? `aspect-ratio: ${aspect.replace('/', '/')};` : '';
+        const wStyle  = width  ? `width:${/^\d+$/.test(width)  ? width  + 'px' : width};`  : '';
+        const hStyle  = height ? `height:${/^\d+$/.test(height) ? height + 'px' : height};` : '';
+        const showSkeleton = !this._loaded && !this._errored && placeholder === 'skeleton';
+
+        return `
+            <style>
+                :host { display: inline-block; }
+                figure {
+                    margin: 0;
+                    padding: 0;
+                    display: block;
+                    ${wStyle} ${hStyle}
+                    border-radius: ${radVal};
+                    overflow: hidden;
+                    position: relative;
+                    ${aspectStyle}
+                }
+                .skeleton {
+                    position: absolute;
+                    inset: 0;
+                    background: linear-gradient(
+                        90deg,
+                        var(--nc-bg-secondary) 25%,
+                        var(--nc-bg-tertiary, #e2e8f0) 50%,
+                        var(--nc-bg-secondary) 75%
+                    );
+                    background-size: 200% 100%;
+                    animation: nc-img-shimmer 1.4s infinite linear;
+                    border-radius: inherit;
+                    display: ${showSkeleton ? 'block' : 'none'};
+                }
+                @keyframes nc-img-shimmer {
+                    0%   { background-position: -200% 0; }
+                    100% { background-position:  200% 0; }
+                }
+                img {
+                    display: block;
+                    width: 100%;
+                    height: 100%;
+                    object-fit: ${fit};
+                    object-position: ${pos};
+                    border-radius: inherit;
+                    opacity: ${this._loaded ? 1 : 0};
+                    transition: opacity var(--nc-transition-base);
+                }
+                .error-plate {
+                    display: ${this._errored ? 'flex' : 'none'};
+                    align-items: center;
+                    justify-content: center;
+                    position: absolute;
+                    inset: 0;
+                    background: var(--nc-bg-secondary);
+                    color: var(--nc-text-muted);
+                    font-size: var(--nc-font-size-xs);
+                    font-family: var(--nc-font-family);
+                    flex-direction: column;
+                    gap: 4px;
+                }
+                figcaption {
+                    font-family: var(--nc-font-family);
+                    font-size: var(--nc-font-size-xs);
+                    color: var(--nc-text-muted);
+                    text-align: center;
+                    padding-top: 4px;
+                    line-height: 1.4;
+                }
+            </style>
+            <figure>
+                <div class="skeleton"></div>
+                <img
+                    id="img"
+                    src="${src}"
+                    alt="${alt}"
+                    loading="${loading}"
+                    decoding="async"
+                    ${width  ? `width="${width}"`   : ''}
+                    ${height ? `height="${height}"` : ''}
+                />
+                <div class="error-plate" aria-hidden="true">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+                        <rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/>
+                    </svg>
+                    <span>Image not found</span>
+                </div>
+            </figure>
+            ${caption ? `<figcaption>${caption}</figcaption>` : ''}
+        `;
+    }
+
+    onMount() {
+        const img = this.$<HTMLImageElement>('#img');
+        if (!img) return;
+
+        if (img.complete && img.naturalWidth > 0) {
+            this._loaded = true;
+            this.render();
+            return;
+        }
+
+        img.addEventListener('load', () => {
+            this._loaded  = true;
+            this._errored = false;
+            this.render();
+            this.dispatchEvent(new CustomEvent('load', { bubbles: true, composed: true }));
+        }, { once: true });
+
+        img.addEventListener('error', () => {
+            const fallback = this.getAttribute('fallback');
+            if (fallback && img.src !== fallback) {
+                img.src = fallback;
+                return;
+            }
+            this._errored = true;
+            this._loaded  = false;
+            this.render();
+            this.dispatchEvent(new CustomEvent('error', { bubbles: true, composed: true }));
+        }, { once: true });
+    }
+
+    attributeChangedCallback(n: string, o: string, v: string) {
+        if (o === v || !this._mounted) return;
+        if (n === 'src') { this._loaded = false; this._errored = false; }
+        this.render();
+    }
+}
+
+defineComponent('nc-image', NcImage);