@adukiorg/anza 0.2.0

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

@@ -0,0 +1,134 @@
+import { assetCache } from './state.js';
+
+// Detect constructable stylesheet + adoptedStyleSheets support once.
+const supportsSheets =
+  typeof CSSStyleSheet !== 'undefined' &&
+  'adoptedStyleSheets' in Document.prototype &&
+  'adoptedStyleSheets' in ShadowRoot.prototype;
+
+/**
+ * Preloads style and HTML template resources asynchronously exactly once.
+ * Returns { templateNode, stylesheet, cssText, tagsDescriptor }.
+ * When constructable stylesheets are unsupported, stylesheet is null and
+ * cssText carries the raw CSS for <style> injection.
+ */
+export async function preloadResources(tag, styleUrl, templateUrl, inlineTemplate, inlineStyle) {
+  let templateNode = null;
+  let stylesheet = null;
+  let cssText = null;
+  let tagsDescriptor = null;
+
+  // Compile / Fetch styles
+  if (styleUrl) {
+    if (assetCache.has(styleUrl)) {
+      const cached = assetCache.get(styleUrl);
+      if (supportsSheets) {
+        stylesheet = cached;
+      } else {
+        cssText = cached;
+      }
+    } else {
+      try {
+        const res = await fetch(styleUrl);
+        if (res.ok) {
+          const css = await res.text();
+          if (supportsSheets) {
+            stylesheet = new CSSStyleSheet();
+            stylesheet.replaceSync(css);
+            assetCache.set(styleUrl, stylesheet);
+          } else {
+            cssText = css;
+            assetCache.set(styleUrl, css);
+          }
+        }
+      } catch (err) {
+        console.error(`Failed to load style resource for element ${tag}:`, err);
+      }
+    }
+  } else if (inlineStyle) {
+    if (supportsSheets) {
+      stylesheet = new CSSStyleSheet();
+      stylesheet.replaceSync(inlineStyle);
+    } else {
+      cssText = inlineStyle;
+    }
+  }
+
+  // Compile / Fetch Template markup
+  if (templateUrl) {
+    if (assetCache.has(templateUrl)) {
+      templateNode = assetCache.get(templateUrl);
+    } else {
+      try {
+        const res = await fetch(templateUrl);
+        if (res.ok) {
+          const html = await res.text();
+          templateNode = createTemplateFragment(html);
+          assetCache.set(templateUrl, templateNode);
+        }
+      } catch (err) {
+        console.error(`Failed to fetch template resource for element ${tag}:`, err);
+      }
+    }
+
+    // Fetch Tags Descriptor
+    const tagsUrl = templateUrl.replace(/\.html$/, '.tags.json');
+    if (assetCache.has(tagsUrl)) {
+      tagsDescriptor = assetCache.get(tagsUrl);
+    } else {
+      try {
+        const res = await fetch(tagsUrl);
+        if (res.ok) {
+          const raw = await res.json();
+          tagsDescriptor = validateDescriptor(raw);
+          assetCache.set(tagsUrl, tagsDescriptor);
+        }
+      } catch (_) {
+        // Safe to ignore — not all elements have a tags descriptor
+      }
+    }
+  } else if (inlineTemplate) {
+    templateNode = createTemplateFragment(inlineTemplate);
+  }
+
+  return { templateNode, stylesheet, cssText, tagsDescriptor };
+}
+
+/**
+ * Validates a raw tags descriptor JSON object.
+ * Returns a safe descriptor with only array-typed fields, or null if unusable.
+ */
+export function validateDescriptor(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const safe = {};
+  if (typeof raw.version === 'number') safe.version = raw.version;
+
+  const known = new Set(['version', 'refs', 'ids', 'classes', 'tags', 'compound']);
+
+  for (const field of ['refs', 'ids', 'classes', 'tags', 'compound']) {
+    safe[field] = Array.isArray(raw[field]) ? raw[field] : [];
+  }
+
+  // Preserve unknown future fields without mutating them
+  for (const [k, v] of Object.entries(raw)) {
+    if (!known.has(k)) {
+      safe[k] = v;
+    }
+  }
+
+  return safe;
+}
+
+/**
+ * Compiles an HTML string into a DocumentFragment utilizing the fastest native methods.
+ */
+export function createTemplateFragment(htmlString) {
+  const tpl = document.createElement('template');
+  if (typeof tpl.setHTMLUnsafe === 'function') {
+    tpl.setHTMLUnsafe(htmlString);
+  } else {
+    tpl.innerHTML = htmlString;
+  }
+  return tpl.content;
+}

package/src/core/ui/implementation.md

@@ -0,0 +1,170 @@
+# Native UI Implementation Checklist
+
+This checklist is the execution companion to `plan.md`, `watch.md`, and `usage.md`.
+
+Status: **Fully Implemented and Verified**
+
+- All phases (Phase 1 through Phase 7) are completed, optimized, and verified.
+- The runtime helpers, event delegation, mutation watcher, lifecycle injection, Rust scanner, and comprehensive test suite are fully operational and integrated.
+
+## Phase 1: Runtime Helpers
+
+Files:
+
+- `src/core/ui/define/proxy.js`
+- `src/core/ui/define/element.js`
+- optional new `src/core/ui/define/context.js`
+
+Tasks:
+
+- Split `TagsCache` into separate `one` and `all` caches.
+- Add `TagsCache.has(selector)` if desired.
+- Add descriptor-free `refs` fallback scanning.
+- Add duplicate-ref development warnings.
+- Add context builder for `{ el, ctrl, tags, on, refs, watch, internals }`.
+- Install cache invalidation for `replaceChildren` and `innerHTML`.
+- Return stable context objects for mount/update.
+
+Acceptance:
+
+- `tags.one('button')` and `tags.all('button')` can be called in any order.
+- `refs` works with and without `.tags.json`.
+- Existing `ui.element` components continue to mount.
+
+## Phase 2: Event Delegation
+
+File:
+
+- `src/core/ui/define/proxy.js`
+
+Tasks:
+
+- Replace per-binding root listeners with one root listener per event type.
+- Store event registrations in sets keyed by event type.
+- Support `on.click(selector, handler)`.
+- Support `on.click(selector, handler, signal)`.
+- Support `on.click(selector, handler, options)`.
+- Support `on.click.once(selector, handler)`.
+- Return disposer functions.
+- Remove bindings on custom signal abort.
+- Remove all bindings on component signal abort.
+
+Acceptance:
+
+- Dynamically added matching elements work without rebinding.
+- Multiple click handlers do not create multiple native click listeners on the shadow root.
+- `.once` fires once and removes only itself.
+
+## Phase 3: `watch`
+
+File:
+
+- `src/core/ui/define/proxy.js` or new `src/core/ui/define/watch.js`
+
+Tasks:
+
+- Implement `createMutationWatcher(shadowRoot, defaultSignal)`.
+- Support `watch.attr`, `watch.kids`, `watch.text`, `watch.tree`.
+- Support `.once` on each method.
+- Accept selector strings and direct element references.
+- Accept custom `AbortSignal` or options object.
+- Return disposer functions.
+- Recompute observer options from active registrations.
+- Dispatch reshaped handler arguments.
+- Guard callbacks after lifecycle abort.
+
+Acceptance:
+
+- One `MutationObserver` exists per component instance.
+- Attribute, child, text, and tree handlers receive documented arguments.
+- Component disconnect clears all registrations.
+
+## Phase 4: Lifecycle Injection
+
+File:
+
+- `src/core/ui/define/element.js`
+
+Tasks:
+
+- Use the context builder after template/style hydration.
+- Pass `watch` to `spec.mount`.
+- Pass `watch` and `prev` to `spec.update`.
+- Preserve `internals` behavior for form-associated elements.
+- Keep `spec.unmount` shape stable.
+
+Acceptance:
+
+- Existing components using `{ tags, on, refs }` still work.
+- New components can destructure `{ watch }`.
+- Updates receive `prev` consistently.
+
+## Phase 5: Rust Scanner
+
+Files:
+
+- `tools/src/extract/html.rs`
+- `tools/src/extract/runner.rs`
+- `tools/src/watcher/runner.rs`
+- `tools/src/main.rs`
+
+Tasks:
+
+- Refactor scanner into `parse_html`, `parse_file`, `emit_descriptor`, and `parse_and_emit`.
+- Return `Result` instead of silently swallowing errors.
+- Add descriptor `version`.
+- Add duplicate-ref diagnostics.
+- Keep sorted deterministic output.
+- Consider `attrs` and `refTypes` fields.
+- Add subcommands or document current flags until subcommands land.
+- Regenerate descriptors on HTML watcher events.
+- Remove stale descriptors when source HTML is deleted.
+
+Acceptance:
+
+- Build mode emits descriptors for all HTML templates.
+- Dev watcher regenerates a changed template descriptor.
+- Malformed HTML fragments do not panic.
+
+## Phase 6: Tests
+
+JavaScript tests:
+
+- `tags` cache shapes and invalidation.
+- `refs` descriptor and fallback behavior.
+- `on` delegation, custom events, once, signal cleanup.
+- `watch` attr/kids/text/tree, once, direct refs, selector misses, lifecycle abort.
+
+Rust tests:
+
+- Descriptor parsing.
+- Stable JSON ordering.
+- Duplicate refs.
+- Watcher-triggered regeneration.
+
+## Phase 7: Documentation
+
+Files:
+
+- `src/core/ui/plan.md`
+- `src/core/ui/watch.md`
+- `src/core/ui/usage.md`
+- `src/core/ui/implementation.md`
+
+Tasks:
+
+- Keep `plan.md` as the architectural implementation plan.
+- Keep `watch.md` as the `watch` API and internals spec.
+- Keep `usage.md` as the public usage guide.
+- Keep this file as the execution checklist.
+
+## Done Definition
+
+The work is complete when:
+
+- Runtime injects `refs`, `tags`, `on`, and `watch`.
+- All helpers clean up from `ctrl.signal`.
+- Rust emits descriptors deterministically.
+- Dev watcher keeps descriptors current.
+- Usage docs cover every public call shape.
+- Tests prove lifecycle cleanup and cache correctness.

package/src/core/ui/index.js

@@ -0,0 +1,41 @@
+/**
+ * src/core/ui/index.js
+ *
+ * Public UI base entry point.
+ * Aggregates BaseElement foundations, cooperative task scheduling, transition
+ * orchestrators, templates, declarative element factory, and safe reactive element observers.
+ *
+ * Source: doc 04 — Web Components §1, doc 12 — Performance §2
+ */
+
+import { BaseElement } from './base.js';
+import { define, element, container } from './define/index.js';
+import { schedule, scheduleFrame, yieldTask } from './schedule.js';
+import { transition } from './transitions.js';
+import { template } from './template.js';
+import * as observe from './observe.js';
+
+export const ui = {
+  define,
+  element,
+  container,
+  schedule,
+  scheduleFrame,
+  yield: yieldTask,
+  transition,
+  template,
+  observe
+};
+
+export {
+  BaseElement,
+  define,
+  element,
+  container,
+  schedule,
+  scheduleFrame,
+  yieldTask,
+  transition,
+  template,
+  observe
+};

package/src/core/ui/observe.js

@@ -0,0 +1,117 @@
+/**
+ * src/core/ui/observe.js
+ *
+ * Safe Observer Factories.
+ * Wraps browser ResizeObserver, IntersectionObserver, MutationObserver, and PerformanceObserver
+ * APIs with automatic AbortSignal-driven disconnect cleanups to secure observers
+ * against lifecycle memory leaks.
+ *
+ * Abort listeners are removed when manual disposal runs first, preventing
+ * long-lived signals from retaining stale closures.
+ *
+ * Source: doc 14 — Memory Management §5, doc 17 — Browser API §10
+ */
+
+/**
+ * ResizeObserver with automatic AbortSignal cleanup.
+ */
+export function resize(el, fn, signal) {
+  if (signal?.aborted) return () => {};
+
+  const observer = new ResizeObserver((entries) => {
+    try {
+      fn(entries);
+    } catch (err) {
+      console.error('Error in ResizeObserver callback:', err);
+    }
+  });
+
+  observer.observe(el);
+
+  const dispose = () => {
+    observer.disconnect();
+    signal?.removeEventListener('abort', dispose);
+  };
+
+  signal?.addEventListener('abort', dispose);
+
+  return dispose;
+}
+
+/**
+ * IntersectionObserver with automatic AbortSignal cleanup.
+ */
+export function intersection(el, fn, signal, options = {}) {
+  if (signal?.aborted) return () => {};
+
+  const observer = new IntersectionObserver((entries) => {
+    try {
+      fn(entries);
+    } catch (err) {
+      console.error('Error in IntersectionObserver callback:', err);
+    }
+  }, options);
+
+  observer.observe(el);
+
+  const dispose = () => {
+    observer.disconnect();
+    signal?.removeEventListener('abort', dispose);
+  };
+
+  signal?.addEventListener('abort', dispose);
+
+  return dispose;
+}
+
+/**
+ * MutationObserver with automatic AbortSignal cleanup.
+ */
+export function mutation(el, fn, signal, options = { childList: true }) {
+  if (signal?.aborted) return () => {};
+
+  const observer = new MutationObserver((mutations) => {
+    try {
+      fn(mutations);
+    } catch (err) {
+      console.error('Error in MutationObserver callback:', err);
+    }
+  });
+
+  observer.observe(el, options);
+
+  const dispose = () => {
+    observer.disconnect();
+    signal?.removeEventListener('abort', dispose);
+  };
+
+  signal?.addEventListener('abort', dispose);
+
+  return dispose;
+}
+
+/**
+ * PerformanceObserver with automatic AbortSignal cleanup.
+ */
+export function performance(types, fn, signal, options = {}) {
+  if (signal?.aborted) return () => {};
+
+  const observer = new PerformanceObserver((list) => {
+    try {
+      fn(list);
+    } catch (err) {
+      console.error('Error in PerformanceObserver callback:', err);
+    }
+  });
+
+  observer.observe({ entryTypes: types, ...options });
+
+  const dispose = () => {
+    observer.disconnect();
+    signal?.removeEventListener('abort', dispose);
+  };
+
+  signal?.addEventListener('abort', dispose);
+
+  return dispose;
+}