@adukiorg/anza 0.2.0

package/src/core/ui/define/element.js

@@ -0,0 +1,390 @@
+import { BaseElement } from '../base.js';
+import { scheduleFrame } from '../schedule.js';
+import { router } from '../../router/index.js';
+import { specRegistry, internalsMap, initializedMap, pendingUpdatesMap, updateScheduledMap } from './state.js';
+import { preloadResources } from './utils.js';
+import { createComponentContext } from './proxy.js';
+
+// Platform lifecycle method names that must never be overridden by spec.methods.
+const RESERVED = new Set([
+  'connectedCallback', 'disconnectedCallback', 'attributeChangedCallback',
+  'adoptedCallback', 'formAssociatedCallback', 'formDisabledCallback',
+  'formResetCallback', 'formStateRestoreCallback',
+  'mount', 'unmount', 'constructor'
+]);
+
+/**
+ * High-performance declarative element factory.
+ */
+export function element(tag, spec, base) {
+  if (typeof customElements === 'undefined') return;
+  if (customElements.get(tag)) {
+    console.warn(`Declarative Element "${tag}" is already defined. Skipping.`);
+    return;
+  }
+
+  // Normalize prop shorthand (e.g. `count: 0`) into full configs before use.
+  if (spec.props) {
+    spec.props = normalizeProps(spec.props);
+  }
+
+  // Cache element spec for automated layout orchestration and diffing
+  specRegistry.set(tag.toLowerCase(), spec);
+
+  // Automatically register elements with the route matcher if a url pattern is specified
+  if (spec.url) {
+    const meta = { ...spec.meta, container: spec.container };
+    router.register(spec.url, tag, meta);
+  }
+
+  // Define properties to watch and their Symbol backing store keys (R-01)
+  const propKeys = spec.props ? Object.keys(spec.props) : [];
+  const observedAttrs = propKeys.map(k => k.toLowerCase());
+  const store = {};
+  for (const key of propKeys) {
+    store[key] = Symbol(key);
+  }
+
+  // Warn loudly when a relative asset is given without a base — otherwise the
+  // resource would silently fail to load (U2).
+  warnMissingBase(tag, 'style', spec.style, base);
+  warnMissingBase(tag, 'template', spec.template, base);
+
+  // Resolve absolute URLs relative to import.meta.url (base)
+  const styleUrl = spec.style && base && (spec.style.endsWith('.css') || spec.style.startsWith('./') || spec.style.startsWith('/'))
+    ? new URL(spec.style, base).href
+    : null;
+  const templateUrl = spec.template && base && (spec.template.endsWith('.html') || spec.template.startsWith('./') || spec.template.startsWith('/'))
+    ? new URL(spec.template, base).href
+    : null;
+
+  // Initiate resource fetching exactly once per component registration (R-06)
+  let resolved = null;
+  const resourcesPromise = preloadResources(tag, styleUrl, templateUrl, spec.template, spec.style).then(res => {
+    resolved = res;
+    return res;
+  });
+
+  // Handle hot reloading of constructable stylesheets (one global listener per unique styleUrl - R-05)
+  if (styleUrl && typeof window !== 'undefined') {
+    if (!window.__native_hmr_listeners__) {
+      window.__native_hmr_listeners__ = new Set();
+    }
+    if (!window.__native_hmr_listeners__.has(styleUrl)) {
+      window.__native_hmr_listeners__.add(styleUrl);
+      const hmrHandler = async (e) => {
+        const { path: changedPath, css } = e.detail;
+        const absoluteChangedUrl = new URL(changedPath, window.location.origin).href;
+        
+        if (styleUrl === absoluteChangedUrl || styleUrl.endsWith(changedPath)) {
+          const res = await resourcesPromise;
+          if (res.stylesheet) {
+            res.stylesheet.replaceSync(css);
+            console.log(`[HMR] Shared AdoptedStyleSheet hot-swapped for <${tag}>`);
+          }
+        }
+      };
+      window.addEventListener('native:hmr:css', hmrHandler);
+    }
+  }
+
+  class DeclarativeElement extends BaseElement {
+    static observedAttributes = observedAttrs;
+
+    constructor() {
+      super();
+      this.attachShadow({ mode: spec.mode || 'open' });
+      
+      initializedMap.set(this, false);
+      pendingUpdatesMap.set(this, new Map());
+      updateScheduledMap.set(this, false);
+
+      if (spec.form) {
+        const internals = this.attachInternals();
+        internalsMap.set(this, internals);
+      }
+
+      // Initialize default properties backing store dynamically (R-01)
+      if (spec.props) {
+        for (const [key, config] of Object.entries(spec.props)) {
+          const sym = store[key];
+          const attrName = key.toLowerCase();
+          let initial = config.default;
+          if (config.type === Boolean) {
+            initial = this.hasAttribute(attrName);
+          } else {
+            const attrVal = this.getAttribute(attrName);
+            if (attrVal !== null) {
+              initial = config.type === Number ? Number(attrVal) : attrVal;
+            }
+          }
+          this[sym] = initial ?? (config.type === Boolean ? false : null);
+        }
+      }
+    }
+
+    async connectedCallback() {
+      // AbortController bootstrap inside BaseElement
+      super.connectedCallback();
+      
+      // Wait for resolved resources to compile (synchronously if already cached)
+      let res = resolved;
+      if (!res) {
+        res = await resourcesPromise;
+      }
+      const { templateNode, stylesheet, cssText, tagsDescriptor } = res;
+
+      if (!this.ctrl || this.ctrl.signal.aborted || !this.isConnected) {
+        return;
+      }
+
+      if (templateNode && this.shadowRoot.childNodes.length === 0) {
+        this.shadowRoot.appendChild(templateNode.cloneNode(true));
+      }
+
+      if (stylesheet) {
+        // Constructable stylesheets path
+        this.shadowRoot.adoptedStyleSheets = [stylesheet];
+      } else if (cssText) {
+        // Fallback: inject <style> for browsers without adoptedStyleSheets
+        const style = document.createElement('style');
+        style.textContent = cssText;
+        this.shadowRoot.prepend(style);
+      }
+      
+      const context = createComponentContext({
+        el: this,
+        shadowRoot: this.shadowRoot,
+        ctrl: this.ctrl,
+        descriptor: tagsDescriptor,
+        internals: internalsMap.get(this)
+      });
+
+      this._ctx = context;
+      this._tags = context.tags;
+      this._on = context.on;
+      this._refs = context.refs;
+      this._watch = context.watch;
+
+      initializedMap.set(this, true);
+
+      // Mount hook trigger passed with unified AbortController signal
+      if (spec.mount) {
+        try {
+          const res = spec.mount(context);
+          if (res instanceof Promise) {
+            res.catch((err) => {
+              console.error('[Native UI] mount failed:', err);
+            });
+          }
+        } catch (err) {
+          console.error('[Native UI] mount failed:', err);
+        }
+      }
+    }
+
+    disconnectedCallback() {
+      if (spec.unmount) {
+        spec.unmount({ 
+          el: this, 
+          tags: this._tags,
+          refs: this._refs,
+          watch: this._watch,
+          internals: internalsMap.get(this) 
+        });
+      }
+      super.disconnectedCallback();
+    }
+
+    attributeChangedCallback(name, oldVal, newVal) {
+      if (oldVal === newVal) return;
+
+      // Find the camelCase property matching lowercase attribute name
+      const key = propKeys.find(k => k.toLowerCase() === name);
+      if (!key) return;
+
+      const config = spec.props[key];
+      let castedVal = newVal;
+
+      if (config.type === Boolean) {
+        castedVal = newVal !== null;
+      } else if (config.type === Number) {
+        castedVal = newVal !== null ? Number(newVal) : (config.default ?? 0);
+      }
+
+      // Sync property to trigger update callback and schedule updates
+      if (this[key] !== castedVal) {
+        this[key] = castedVal;
+      }
+    }
+
+    // Form-associated lifecycle callbacks — mapped from short spec hook names
+    formAssociatedCallback(form) {
+      spec.associated?.call(this, form);
+    }
+
+    formDisabledCallback(value) {
+      spec.disabled?.call(this, value);
+    }
+
+    formResetCallback() {
+      spec.reset?.call(this);
+    }
+
+    formStateRestoreCallback(state, mode) {
+      spec.restore?.call(this, state, mode);
+    }
+  }
+
+  // 1. Install spec.methods onto the prototype before define (§1.1)
+  if (spec.methods) {
+    for (const [name, fn] of Object.entries(spec.methods)) {
+      if (RESERVED.has(name) || name in DeclarativeElement.prototype) {
+        console.warn(`[Native UI] Method "${name}" conflicts with an existing or reserved name on <${tag}>. Skipping.`);
+        continue;
+      }
+
+      Object.defineProperty(DeclarativeElement.prototype, name, {
+        value: fn,
+        writable: false,
+        configurable: true,
+        enumerable: false
+      });
+    }
+  }
+
+  // 2. Generate type-safe getter/setters dynamically on class prototype (R-01)
+  for (const key of propKeys) {
+    const config = spec.props[key];
+    const attrName = key.toLowerCase();
+    const sym = store[key];
+    // reflect defaults to true for back-compatibility (§1.2)
+    const reflect = config.reflect !== false;
+
+    Object.defineProperty(DeclarativeElement.prototype, key, {
+      get() {
+        return this[sym];
+      },
+      set(val) {
+        const oldVal = this[sym];
+        if (oldVal === val) return;
+
+        this[sym] = val;
+
+        // Attribute reflection — only when reflect !== false (§1.2)
+        if (reflect) {
+          if (config.type === Boolean) {
+            if (val) {
+              if (!this.hasAttribute(attrName)) this.setAttribute(attrName, '');
+            } else {
+              if (this.hasAttribute(attrName)) this.removeAttribute(attrName);
+            }
+          } else if (val === null || val === undefined) {
+            if (this.hasAttribute(attrName)) this.removeAttribute(attrName);
+          } else {
+            const strVal = String(val);
+            if (this.getAttribute(attrName) !== strVal) {
+              this.setAttribute(attrName, strVal);
+            }
+          }
+        }
+
+        // Custom state synchronization (:state(name))
+        const internals = internalsMap.get(this);
+        if (config.state && internals?.states) {
+          if (val) {
+            internals.states.add(key);
+          } else {
+            internals.states.delete(key);
+          }
+        }
+
+        // Schedule batched updates via cooperative microtask scheduling
+        const initialized = initializedMap.get(this);
+        if (initialized && spec.update) {
+          const pendingUpdates = pendingUpdatesMap.get(this);
+          pendingUpdates.set(key, { val, old: oldVal });
+          if (!updateScheduledMap.get(this)) {
+            updateScheduledMap.set(this, true);
+            
+            // Choose queueMicrotask or scheduleFrame depending on update.visual hint (R-03)
+            const flush = (spec.update.visual === true)
+              ? (fn) => scheduleFrame(fn)
+              : (fn) => queueMicrotask(fn);
+              
+            flush(() => {
+              if (!this.ctrl || this.ctrl.signal.aborted || !this.isConnected) {
+                pendingUpdates.clear();
+                updateScheduledMap.set(this, false);
+                return;
+              }
+
+              const changes = Array.from(pendingUpdates.entries());
+              pendingUpdates.clear();
+              updateScheduledMap.set(this, false);
+
+              for (const [name, { val: v, old: o }] of changes) {
+                spec.update({ 
+                  el: this, 
+                  ctrl: this.ctrl,
+                  tags: this._tags,
+                  on: this._on,
+                  refs: this._refs,
+                  watch: this._watch,
+                  name, 
+                  val: v, 
+                  old: o,
+                  prev: o 
+                });
+              }
+            });
+          }
+        }
+      }
+    });
+  }
+
+  // 3. Form association
+  if (spec.form) {
+    Object.defineProperty(DeclarativeElement, 'formAssociated', {
+      value: true,
+      writable: false
+    });
+  }
+
+  // Define element globally
+  customElements.define(tag, DeclarativeElement);
+}
+
+/**
+ * Normalizes prop definitions, expanding shorthand literals into full configs.
+ * `count: 0` -> `count: { type: Number, default: 0 }`. Object configs that
+ * already declare `type` are passed through unchanged.
+ */
+function normalizeProps(props) {
+  const out = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (value && typeof value === 'object' && 'type' in value) {
+      out[key] = value;
+      continue;
+    }
+    let type = String;
+    if (typeof value === 'boolean') type = Boolean;
+    else if (typeof value === 'number') type = Number;
+    out[key] = { type, default: value };
+  }
+  return out;
+}
+
+/**
+ * Warns when a relative `template`/`style` is supplied without a base URL,
+ * which would otherwise silently fail to resolve.
+ */
+function warnMissingBase(tag, field, value, base) {
+  if (!base && typeof value === 'string' && (value.startsWith('./') || value.startsWith('../'))) {
+    console.error(
+      `[Native UI] <${tag}> ${field} "${value}" is relative but no base was given. ` +
+      `Pass import.meta.url as the third argument to ui.element(...).`
+    );
+  }
+}

package/src/core/ui/define/index.js

@@ -0,0 +1,9 @@
+import { define } from './define.js';
+import { element } from './element.js';
+import { container } from './container.js';
+import { initOrchestrator } from './orchestrator.js';
+
+// Initialize the global routing orchestrator
+initOrchestrator();
+
+export { define, element, container };

package/src/core/ui/define/orchestrator.js

@@ -0,0 +1,105 @@
+import { router } from '../../router/index.js';
+import { specRegistry } from './state.js';
+
+let dispose = null; // One-word module-level disposer variable (RT-11)
+
+/**
+ * Initializes the global routing orchestrator.
+ * Listens for navigation found events and dynamically updates layout containers.
+ */
+export function initOrchestrator() {
+  if (typeof window !== 'undefined') {
+    dispose?.();
+    dispose = router.on('found', async ({ tag, params, query, hash, chain, direction }) => {
+      // Resolve the top-level layout element in the chain
+      const topTag = chain && chain.length > 0 ? chain[0].tag : tag;
+      const topParams = chain && chain.length > 0 ? chain[0].params : params;
+
+      // RT-13: Async hydration gate — await custom element definition before mounting
+      if (typeof customElements !== 'undefined' && topTag.includes('-') && !customElements.get(topTag)) {
+        await customElements.whenDefined(topTag);
+      }
+
+      const spec = specRegistry.get(topTag.toLowerCase());
+      if (!spec || !spec.container) return;
+
+      // Use Advanced Container Registry lookup instead of blind DOM query
+      const containerEl = router.getContainer(spec.container);
+      if (!containerEl) {
+        console.warn(`Target container "${spec.container}" not found in DOM for element <${topTag}>`);
+        return;
+      }
+
+      const props = {};
+
+      // 1. Cast params
+      for (const [key, val] of Object.entries(topParams)) {
+        let casted = val;
+        if (spec.props && spec.props[key]) {
+          const type = spec.props[key].type;
+          if (type === Boolean) {
+            casted = val === 'true' || val === '1' || val === '';
+          } else if (type === Number) {
+            const num = Number(val);
+            casted = isNaN(num) ? 0 : num;
+          }
+        }
+        props[key] = casted;
+      }
+
+      // 2. Map query params
+      if (spec.query && Array.isArray(spec.query) && query) {
+        for (const key of spec.query) {
+          const val = query[key];
+          if (val !== undefined) {
+            let casted = val;
+            if (spec.props && spec.props[key]) {
+              const type = spec.props[key].type;
+              if (type === Boolean) {
+                casted = val === 'true' || val === '1' || val === '';
+              } else if (type === Number) {
+                const num = Number(val);
+                casted = isNaN(num) ? 0 : num;
+              }
+            }
+            props[key] = casted;
+          }
+        }
+      }
+
+      // 3. Map hash property
+      if (spec.props && spec.props.hash && hash !== undefined) {
+        props.hash = hash;
+      }
+
+      // Layout-preserving diffing: Sync parameters reactively if the element is already mounted
+      const currentChild = containerEl.querySelector('.page-content');
+      if (currentChild && currentChild.tagName.toLowerCase() === topTag.toLowerCase()) {
+        for (const [key, value] of Object.entries(props)) {
+          currentChild[key] = value;
+        }
+        return;
+      }
+
+      // Instantiate the new declarative page element
+      const pageEl = document.createElement(topTag);
+      pageEl.classList.add('page-content');
+      for (const [key, value] of Object.entries(props)) {
+        pageEl[key] = value;
+      }
+
+      // Delegated UI Swap: If the container implements swapView, let it handle the DOM transitions
+      if (typeof containerEl.swapView === 'function') {
+        await containerEl.swapView(pageEl, { params: props, direction });
+      } else {
+        // Fallback to standard atomic replace
+        containerEl.replaceChildren(pageEl);
+      }
+    });
+  }
+}
+
+export function destroyOrchestrator() {
+  dispose?.();
+  dispose = null;
+}