@adukiorg/anza 0.2.0 → 0.2.2

package/src/tokens/index.css

@@ -24,3 +24,4 @@
 @import './semantic/dark.css';
 @import './semantic/contrast.css';
 @import './semantic/components.css';
+@import './semantic/transitions.css';

package/src/tokens/semantic/contrast.css

@@ -30,4 +30,22 @@
   --color-border-default:  var(--color-neutral-1000);
   --color-border-strong:   var(--color-neutral-1000);
   --color-border-focus:    var(--color-brand-900);
+
+  /* Automatic theme morph — same timing as light theme */
+  transition:
+    --color-surface-page 220ms var(--ease-out),
+    --color-surface-card 220ms var(--ease-out),
+    --color-surface-elevated 220ms var(--ease-out),
+    --color-surface-inverse 220ms var(--ease-out),
+    --color-content-primary 180ms var(--ease-out),
+    --color-content-secondary 180ms var(--ease-out),
+    --color-content-disabled 180ms var(--ease-out),
+    --color-content-inverse 180ms var(--ease-out),
+    --color-content-link 180ms var(--ease-out),
+    --color-interactive 180ms var(--ease-out),
+    --color-interactive-hover 180ms var(--ease-out),
+    --color-interactive-active 180ms var(--ease-out),
+    --color-border-default 180ms var(--ease-out),
+    --color-border-strong 180ms var(--ease-out),
+    --color-border-focus 180ms var(--ease-out);
 }

package/src/tokens/semantic/transitions.css

@@ -0,0 +1,32 @@
+/**
+ * tokens/semantic/transitions.css
+ *
+ * View Transition pseudo-element theming.
+ * Connects the browser's CSS View Transitions API to the semantic token system.
+ */
+
+:root {
+  /* Backdrop behind old and new page snapshots during a transition */
+  --transition-bg: var(--color-surface-page);
+
+  /* Timing tokens used by JS when calling startViewTransition */
+  --transition-duration: var(--duration-normal);
+  --transition-easing: var(--ease-out);
+
+  /* Directional modifiers — pushed pages feel different from popped pages */
+  --transition-push: var(--ease-out);
+  --transition-pop: var(--ease-in);
+  --transition-replace: var(--ease-in-out);
+}
+
+::view-transition-old(root),
+::view-transition-new(root) {
+  background: var(--transition-bg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --transition-duration: 0ms;
+    --transition-easing: linear;
+  }
+}

package/types/core/platform/index.d.ts

@@ -4,57 +4,86 @@
  * TypeScript declarations for browser-native feature detection flags and platform guards.
  */
 
-export const supports: {
+export interface Supports {
+  // --- Routing ---
   readonly navigationAPI: boolean;
   readonly urlPattern: boolean;
+
+  // --- Component Model ---
   readonly declarativeShadowDOM: boolean;
   readonly customStatePseudo: boolean;
   readonly formAssociated: boolean;
+
+  // --- Overlay / Popover ---
   readonly popoverAPI: boolean;
   readonly anchorPositioning: boolean;
+
+  // --- Animation ---
   readonly viewTransitions: boolean;
   readonly scrollTimeline: boolean;
   readonly viewTimeline: boolean;
+
+  // --- Scheduling ---
   readonly schedulerPostTask: boolean;
   readonly schedulerYield: boolean;
+
+  // --- CSS ---
   readonly contentVisibility: boolean;
   readonly cssScope: boolean;
   readonly cssLayer: boolean;
   readonly cssModuleScripts: boolean;
+
+  // --- Module System ---
   readonly importMaps: boolean;
+
+  // --- Security ---
   readonly sanitizerAPI: boolean;
   readonly trustedTypes: boolean;
   readonly subtleCrypto: boolean;
+
+  // --- Storage ---
   readonly opfs: boolean;
   readonly storageManager: boolean;
   readonly fileSystemPickers: boolean;
   readonly compression: boolean;
   readonly storagePersistence: boolean;
+
+  // --- Networking / Workers ---
   readonly backgroundSync: boolean;
   readonly speculationRules: boolean;
   readonly sharedWorker: boolean;
   readonly webLocks: boolean;
   readonly offscreenCanvas: boolean;
+
+  // --- Notifications / Push ---
   readonly pushAPI: boolean;
   readonly notificationsAPI: boolean;
+
+  // --- Device ---
   readonly screenWakeLock: boolean;
   readonly idleDetection: boolean;
   readonly webAuthn: boolean;
-};
+}
 
-export function reset(key: keyof typeof supports): void;
+export const supports: Supports;
+
+export function reset(key: keyof Supports): void;
+
+export function typeGuard(key: keyof Supports, message?: string): void;
 
 export interface SanitizerWrapper {
   sanitizeToString(input: string): string;
 }
 
-export const guard: {
-  urlPattern(): Promise<any>;
-  navigation(): Promise<any>;
+export interface Guard {
+  urlPattern(): Promise<typeof URLPattern>;
+  navigation(): Promise<Navigation>;
   popover(): Promise<void>;
-  shadow(root?: ParentNode): Promise<void>;
-  anchor(floating: HTMLElement, anchorEl: HTMLElement, options?: any): Promise<void>;
+  shadow(root?: Document | ShadowRoot): Promise<void>;
+  anchor(floating: HTMLElement, anchorEl: HTMLElement, options?: object): Promise<void>;
   sanitizer(): Promise<SanitizerWrapper>;
-  scheduler(): Promise<any>;
+  scheduler(): Promise<Scheduler>;
   yield(): Promise<void>;
-};
+}
+
+export const guard: Guard;

package/types/core/router/index.d.ts

@@ -192,6 +192,15 @@ export function unregisterContainer(name: string): void;
 export function getContainer(name: string): Element | null;
 export function clearContainers(): void;
 
+export interface TransitionsApi {
+  run(
+    updateDOM: () => void | Promise<void>,
+    options?: { sourceElement?: HTMLElement; name?: string }
+  ): Promise<void>;
+}
+
+export const transitions: TransitionsApi;
+
 export class RouteOutlet extends HTMLElement {
   update(detail: { chain: ChainSegment[]; query: Record<string, string>; hash: string }): Promise<void>;
 }

package/types/core/theme/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * types/core/theme/index.d.ts
+ *
+ * TypeScript declarations for the anza theme API.
+ */
+
+export interface ThemeApi {
+  /** Return the active theme name: light, dark, contrast, or auto. */
+  get(): string;
+
+  /** Apply a theme name and persist it. */
+  set(name: string): void;
+
+  /** Toggle between light and dark. */
+  toggle(): void;
+}
+
+export const theme: ThemeApi;

package/types/core/ui/index.d.ts

@@ -420,6 +420,16 @@ export function scheduleFrame<T>(fn: () => T): Promise<T>;
 
 export function yieldTask(): Promise<void>;
 
+export function dock(
+  name: string,
+  config?: {
+    tag?: string;
+    parent?: string;
+    template?: { html?: string; css?: string; shadow?: boolean };
+  },
+  base?: string | URL
+): void;
+
 export function transition<T>(
   fn: () => T
 ): Promise<ViewTransitionLike<T>>;
@@ -435,6 +445,7 @@ export interface UiApi {
   define: typeof define;
   element: typeof element;
   container: typeof container;
+  dock: typeof dock;
   schedule: typeof schedule;
   scheduleFrame: typeof scheduleFrame;
   yield: typeof yieldTask;

package/types/index.d.ts

@@ -15,4 +15,5 @@ export * as ui from './core/ui/index.d.ts';
 export * as security from './core/security/index.d.ts';
 export * as offline from './core/offline/index.d.ts';
 export * as animations from './core/animations/index.d.ts';
+export * as theme from './core/theme/index.d.ts';
 export * as elements from './elements/index.d.ts';

package/bin/anza.js

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * library/bin/anza.js
- *
- * Node.js wrapper for the anza Rust binary.
- * Detects the platform and spawns the correct pre-built binary.
- *
- * In development: uses tools/target/release/anza (two levels up).
- * In npm install: uses pre-built platform binary from bin/.
- */
-
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { existsSync } from 'fs';
-import { spawn } from 'child_process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = dirname(__filename);
-
-// library/bin/ → library/ → repo root
-const library = join(__dirname, '..');
-const root    = join(library, '..');
-
-function binary() {
-  // Development: repo binary (built by `node scripts/build.js`)
-  const dev = join(root, 'tools', 'target', 'release', 'anza');
-  if (existsSync(dev)) return dev;
-
-  // npm install: pre-built platform binary alongside this script
-  const platform = process.platform;
-  const arch     = process.arch;
-
-  const map = {
-    darwin: { x64: 'anza-macos-x64',    arm64: 'anza-macos-arm64' },
-    linux:  { x64: 'anza-linux-x64',    arm64: 'anza-linux-arm64' },
-    win32:  { x64: 'anza-windows-x64.exe', arm64: 'anza-windows-arm64.exe' },
-  };
-
-  const name = map[platform]?.[arch];
-  if (!name) {
-    console.error(`Unsupported platform: ${platform} ${arch}`);
-    process.exit(1);
-  }
-
-  const prebuilt = join(__dirname, name);
-  if (existsSync(prebuilt)) return prebuilt;
-
-  console.error(
-    'anza binary not found.\n' +
-    'Run: node scripts/build.js  (from the repo root)'
-  );
-  process.exit(1);
-}
-
-const child = spawn(binary(), process.argv.slice(2), { stdio: 'inherit' });
-
-child.on('error', (err) => {
-  console.error('Failed to spawn anza:', err.message);
-  process.exit(1);
-});
-
-child.on('exit', (code) => process.exit(code ?? 0));

package/bin/create.js

@@ -1,150 +0,0 @@
-#!/usr/bin/env node
-/**
- * scripts/create.js  (also used as library/bin/create.js → npx anza-create)
- *
- * Scaffolds a new anza app project in the given directory.
- * Usage:
- *   npx anza-create myapp
- *   npx anza-create .          (current directory)
- */
-
-import { mkdirSync, writeFileSync, existsSync } from 'fs';
-import { join, resolve, basename } from 'path';
-
-const arg = process.argv[2];
-
-if (!arg || arg === '--help' || arg === '-h') {
-  console.log('Usage: npx anza-create <name>');
-  console.log('       npx anza-create .     (scaffold in current dir)');
-  process.exit(arg ? 0 : 1);
-}
-
-const target = resolve(arg);
-const name = arg === '.' ? basename(process.cwd()) : basename(target);
-
-if (existsSync(target) && arg !== '.') {
-  console.error(`Error: '${target}' already exists.`);
-  process.exit(1);
-}
-
-console.log(`Scaffolding anza app: ${name}\n`);
-
-// Directory structure
-const dirs = [
-  '',
-  'src',
-  'src/elements',
-  'src/styles',
-  'src/tokens',
-];
-
-for (const dir of dirs) {
-  mkdirSync(join(target, dir), { recursive: true });
-}
-
-// src/index.html
-writeFileSync(join(target, 'src', 'index.html'), `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${name}</title>
-
-    <!-- Tokens & global styles -->
-    <link rel="stylesheet" href="/dist/tokens/index.css" />
-    <link rel="stylesheet" href="/dist/styles/global.css" />
-
-    <!-- App entry -->
-    <script type="module" src="/dist/index.js"></script>
-  </head>
-  <body>
-    <!-- App root -->
-  </body>
-</html>
-`);
-
-// src/index.js
-writeFileSync(join(target, 'src', 'index.js'), `/**
- * src/index.js — app entry point
- */
-import '@adukiorg/anza/ui';
-
-// Import your elements
-// import './elements/dashboard/index.js';
-`);
-
-// src/styles/global.css
-writeFileSync(join(target, 'src', 'styles', 'global.css'), `/* global.css — global app styles */
-
-*,
-*::before,
-*::after {
-  box-sizing: border-box;
-  margin: 0;
-  padding: 0;
-}
-
-body {
-  font-family: system-ui, sans-serif;
-  line-height: 1.5;
-}
-`);
-
-// src/tokens/index.css
-writeFileSync(join(target, 'src', 'tokens', 'index.css'), `/* tokens/index.css — design tokens */
-
-:root {
-  /* Colors */
-  --color-primary: #6366f1;
-  --color-surface: #ffffff;
-  --color-text: #111827;
-
-  /* Spacing */
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-4: 1rem;
-  --space-8: 2rem;
-
-  /* Radius */
-  --radius-sm: 0.25rem;
-  --radius-md: 0.5rem;
-  --radius-lg: 1rem;
-
-  /* Shadow */
-  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
-  --shadow-md: 0 4px 6px rgb(0 0 0 / 0.07);
-}
-`);
-
-// package.json
-writeFileSync(join(target, 'package.json'), JSON.stringify({
-  name,
-  version: '0.1.0',
-  private: true,
-  type: 'module',
-  scripts: {
-    dev: 'anza dev',
-    build: 'anza build',
-  },
-  devDependencies: {
-    '@adukiorg/anza': 'latest',
-  }
-}, null, 2));
-
-// .gitignore
-writeFileSync(join(target, '.gitignore'), `node_modules/
-dist/
-.anza-build-cache.json
-`);
-
-console.log('Created:');
-for (const dir of dirs.filter(Boolean)) {
-  console.log(`  ${name}/${dir}/`);
-}
-console.log(`  ${name}/src/index.html`);
-console.log(`  ${name}/src/index.js`);
-console.log(`  ${name}/package.json`);
-console.log(`\nNext steps:`);
-console.log(`  cd ${arg === '.' ? '.' : name}`);
-console.log(`  npm install`);
-console.log(`  npm run dev`);

package/src/core/api/plan.md

@@ -1,209 +0,0 @@
-# API Client & Cache Enhancement Plan
-
-This document outlines the blueprint for enhancing the `core.api` networking client with localized, fine-grained caching, prefix registration, namespace-level invalidation, and custom network/status-code events.
-
----
-
-## 1. Architectural Architecture & Requirements
-
-We will extend `core.api` to provide:
-
-1. **Default Zero-Cache Policy:** All calls default to no cache, running directly against the network.
-2. **TTL/Expiry-based API Caching:** Active caching when `expiry` or `ttl` (Time-To-Live) options are provided. Hits cache first, falls back to the network on a miss, and caches successful responses.
-3. **Namespace-level Glob Invalidation:** Support for clearing the entire cache, a single URL, or a glob namespace pattern (e.g. `/user/*`).
-4. **Outbound Prefix Resolution:** Initializing base prefixes once (optionally) to cleanly rewrite and resolve endpoint URLs.
-5. **Network Event Hub:** An integrated event listener system firing on generic network failures (errors, timeouts) or specific responses (status codes like `401`, `500`, or content types like `json`, `text`).
-
----
-
-## 2. Structural & Folder Layout
-
-In accordance with our naming and folder conventions (`RULE[user_global]`), we will group caching and events into highly structured subfolders under `src/core/api/`:
-
-```
-src/core/api/
-├── caches/               # Subfolder for caching adapters & glob matching
-│   ├── glob.js           # Glob/Namespace pattern matching helper
-│   └── index.js          # Unified local API cache client
-├── events/               # Subfolder for network telemetry events
-│   └── index.js          # API event emitter implementation
-├── prefixes/             # Subfolder for prefix/base URL resolving
-│   └── index.js          # Prefix store and path normalization
-├── index.js              # Core API client entry point
-├── fetch.js              # Network request executor
-├── pipeline.js           # Inbound/Outbound pipeline coordinator
-├── retry.js              # Exponential backoff retry handler
-├── stream.js             # Streams and NDJSON transform pipeline
-└── upload.js             # XMLHttpRequest-based upload gateway
-```
-
----
-
-## 3. Technical Blueprint & Interface Design
-
-### Caches & Glob Purging (`src/core/api/caches/`)
-
-The API cache uses the native browser Cache API with custom header tags to track record creation times and TTL.
-
-```javascript
-// src/core/api/caches/index.js
-export class ApiCache {
-  constructor(name = 'platform-api-cache') {
-    this.name = name;
-  }
-
-  async get(url) {
-    if (typeof caches === 'undefined') return null;
-    const store = await caches.open(this.name);
-    const cached = await store.match(url);
-    if (!cached) return null;
-
-    const expiresAt = cached.headers.get('x-expires-at');
-    if (expiresAt && Date.now() > Number(expiresAt)) {
-      await store.delete(url);
-      return null;
-    }
-    return cached.clone();
-  }
-
-  async set(url, response, ttlMs) {
-    if (typeof caches === 'undefined') return;
-    const store = await caches.open(this.name);
-    const headers = new Headers(response.headers);
-    headers.set('x-expires-at', String(Date.now() + ttlMs));
-
-    const cloned = new Response(response.body ? response.clone().body : null, {
-      status: response.status,
-      statusText: response.statusText,
-      headers
-    });
-    await store.put(url, cloned);
-  }
-
-  async delete(pattern) {
-    if (typeof caches === 'undefined') return;
-    const store = await caches.open(this.name);
-
-    if (pattern.includes('*')) {
-      const regex = globToRegex(pattern);
-      const keys = await store.keys();
-      for (const req of keys) {
-        if (regex.test(req.url) || regex.test(new URL(req.url).pathname)) {
-          await store.delete(req);
-        }
-      }
-    } else {
-      await store.delete(pattern);
-    }
-  }
-
-  async clear() {
-    if (typeof caches === 'undefined') return;
-    await caches.delete(this.name);
-  }
-}
-```
-
-Glob to Regex conversion helper:
-
-```javascript
-// src/core/api/caches/glob.js
-export function globToRegex(pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-  const wildcarded = escaped.replace(/\*/g, '.*');
-  return new RegExp(`^${wildcarded}$`);
-}
-```
-
-### Prefix Resolver (`src/core/api/prefixes/`)
-
-```javascript
-// src/core/api/prefixes/index.js
-export class PrefixRegistry {
-  #prefixes = new Map();
-
-  add(name, value) {
-    this.#prefixes.set(name, value);
-  }
-
-  resolve(url) {
-    if (url.startsWith('http://') || url.startsWith('https://')) {
-      return url;
-    }
-    for (const [prefix, base] of this.#prefixes.entries()) {
-      if (url.startsWith(`/${prefix}/`)) {
-        return base + url.slice(prefix.length + 1);
-      }
-      if (url.startsWith(`${prefix}/`)) {
-        return base + '/' + url.slice(prefix.length);
-      }
-    }
-    // Default fallback to registered root or baseline domain
-    const root = this.#prefixes.get('root') || this.#prefixes.get('default');
-    if (root) {
-      return root + (url.startsWith('/') ? url : '/' + url);
-    }
-    return url;
-  }
-}
-```
-
-### Telemetry Events (`src/core/api/events/`)
-
-```javascript
-// src/core/api/events/index.js
-export class ApiEventEmitter {
-  #listeners = new Map();
-
-  on(event, handler, signal) {
-    if (signal?.aborted) return () => {};
-    if (!this.#listeners.has(event)) {
-      this.#listeners.set(event, new Set());
-    }
-    const listener = { handler };
-    this.#listeners.get(event).add(listener);
-
-    const dispose = () => {
-      const set = this.#listeners.get(event);
-      if (set) {
-        set.delete(listener);
-        if (set.size === 0) this.#listeners.delete(event);
-      }
-    };
-
-    if (signal) {
-      signal.addEventListener('abort', dispose);
-    }
-    return dispose;
-  }
-
-  emit(event, detail) {
-    const set = this.#listeners.get(event);
-    if (!set) return;
-    const customEvent = { type: event, detail };
-    for (const listener of [...set]) {
-      try {
-        listener.handler(customEvent);
-      } catch (err) {
-        console.error(`Error in API event listener for "${event}":`, err);
-      }
-    }
-  }
-}
-```
-
----
-
-## 4. Verification Plan
-
-### Automated Verification
-
-- Write comprehensive test coverage validating:
-  - Cache hits on active TTL/Expiry options.
-  - Glob namespace clearing matches (e.g. `/user/*` successfully purges `/user/profile` and `/user/settings`).
-  - Outbound path prefix expansion.
-  - Correct event dispatching for generic `'error'`, `'timeout'`, specific codes (`status:401`), and content types (`type:json`).
-
-### Integration Check
-
-- Assert network trace outputs and test page lifecycle triggers inside the browser environment.