@heshammesalam/heshjs 0.1.0 → 0.3.0

package/src/destinations/index.ts

@@ -0,0 +1,146 @@
+import { createRouter } from '../router/index.js';
+import { defineModule, useController, type RouteLocation } from '../hmvc/index.js';
+import { createDomainGraph, ClientPolicyDenied, type DomainDefinition, type DomainOptions, type DomainGraph } from '../domains/index.js';
+import { signal, effect, onCleanup, scope, type Disposer } from '../reactivity/index.js';
+import { mount, element, text } from '../dom/index.js';
+import type { PresentationState } from '../presentation/index.js';
+export type InputType = 'string' | 'number' | 'boolean';
+export interface TransitionOptions { query?: Record<string, string>; hash?: string; presentation?: 'page' }
+export interface Destination<I extends object> {
+  readonly name: string;
+  href(input: I, options?: TransitionOptions): string;
+  open(input: I, options?: TransitionOptions): void;
+  replace(input: I, options?: TransitionOptions): void;
+  /** Prefetch code/resources, not business data or authorization results. */
+  prefetch(input: I): Promise<void>;
+}
+export interface PresentationContext {
+  domains: Record<string, unknown>;
+  input: Record<string, string | number | boolean>;
+  location: RouteLocation;
+  signal: AbortSignal;
+}
+export interface PresentationResources {
+  create(context: PresentationContext): PresentationState;
+  view(parent: Node, state: PresentationState, destinations: Record<string, Destination<Record<string, unknown>>>): void;
+}
+export interface DestinationDefinition {
+  name: string; url: string; input: Record<string, InputType>; owner: string; access?: string;
+  load(): Promise<PresentationResources>;
+}
+export interface DestinationEvent { type: 'loading' | 'ready' | 'blocked' | 'error' | 'cancelled' | 'disposed'; destination: string; reason?: string }
+export interface ApplicationOptions extends DomainOptions { window?: Window; onError?: (error: unknown) => void; onDiagnostic?: (event: DestinationEvent) => void }
+export interface GraphApplication<D = Record<string, Destination<Record<string, unknown>>>, G = Record<string, Record<string, unknown>>> {
+  destinations: D;
+  domains: G;
+  status: { get(): { phase: 'idle' | 'loading' | 'ready' | 'error'; destination?: string; error?: unknown } };
+  start(parent: Node): Disposer;
+  stop(): void;
+}
+export function validateInput(schema: Record<string, InputType>, input: object): Record<string, string | number | boolean> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Destination input must be an object');
+  const values = input as Record<string, unknown>;
+  for (const key of Object.keys(values)) if (!Object.hasOwn(schema, key)) throw new Error(`Unknown destination input ${key}`);
+  const result: Record<string, string | number | boolean> = Object.create(null);
+  for (const [key, type] of Object.entries(schema)) {
+    const value = values[key];
+    if (!Object.hasOwn(values, key) || typeof value !== type || (type === 'number' && !Number.isFinite(value)) || (type === 'string' && !(value as string).length)) throw new Error(`Destination input ${key} must be ${type}${type === 'string' ? ' (nonempty)' : ''}`);
+    if (type === 'string' && (value === '.' || value === '..')) throw new Error(`Destination input ${key} cannot be a URL dot segment`);
+    result[key] = value as string | number | boolean;
+  }
+  return result;
+}
+function decodeInput(definition: DestinationDefinition, params: Readonly<Record<string, string>>): Record<string, string | number | boolean> {
+  const values: Record<string, unknown> = Object.create(null);
+  for (const [key, type] of Object.entries(definition.input)) {
+    const raw = params[key];
+    if (raw === undefined) throw new Error(`Missing URL input ${key}`);
+    if (type === 'boolean' && raw !== 'true' && raw !== 'false') throw new Error(`URL input ${key} must be true/false`);
+    if (type === 'number' && !raw.trim()) throw new Error(`URL input ${key} must be numeric`);
+    values[key] = type === 'number' ? Number(raw) : type === 'boolean' ? raw === 'true' : raw;
+  }
+  return validateInput(definition.input, values);
+}
+export function createGraphApplication(definitions: readonly DomainDefinition[], pages: readonly DestinationDefinition[], options: ApplicationOptions = {}): GraphApplication {
+  const graph = createDomainGraph(definitions, options);
+  const status = signal<{ phase: 'idle' | 'loading' | 'ready' | 'error'; destination?: string; error?: unknown }>({ phase: 'idle' });
+  const report = options.onError ?? (error => console.error(error));
+  const emit = (type: DestinationEvent['type'], destination: string, error?: unknown) => {
+    if (!options.onDiagnostic) return;
+    try { options.onDiagnostic({ type, destination, ...(error === undefined ? {} : { reason: error instanceof Error ? error.message : String(error) }) }); }
+    catch (failure) { report(failure); }
+  };
+  const destinations: Record<string, Destination<Record<string, unknown>>> = Object.create(null);
+  const code = new Map<string, Promise<PresentationResources>>();
+  let stopped = false;
+  const load = (page: DestinationDefinition) => {
+    let result = code.get(page.name);
+    if (!result) { result = Promise.resolve().then(page.load).catch(error => { code.delete(page.name); throw error; }); code.set(page.name, result); }
+    return result;
+  };
+  const authorize = (page: DestinationDefinition) => {
+    if (page.access && options.authorize?.(page.access) !== true) throw new ClientPolicyDenied(page.access, page.name);
+  };
+  const routes = pages.map(page => ({ path: page.url, module: defineModule({
+    model: context => context.route,
+    controller: route => route,
+    view(parent) {
+      const route = useController<{ get(): RouteLocation }>();
+      effect(() => {
+        const location = route.get();
+        const abort = new AbortController(); let dispose: Disposer | undefined, settled = false;
+        onCleanup(() => { abort.abort(); dispose?.(); emit(settled ? 'disposed' : 'cancelled', page.name); });
+        const message = element(parent, 'p'); message.setAttribute('role', 'status'); text(message, () => 'Loading…');
+        status.set({ phase: 'loading', destination: page.name });
+        emit('loading', page.name);
+        const failed = (error: unknown) => {
+          if (abort.signal.aborted) return;
+          settled = true;
+          message.textContent = 'Unable to open this destination.'; message.setAttribute('role', 'alert');
+          status.set({ phase: 'error', destination: page.name, error }); emit(error instanceof ClientPolicyDenied ? 'blocked' : 'error', page.name, error); report(error);
+        };
+        let input: ReturnType<typeof validateInput>;
+        try { authorize(page); input = decodeInput(page, location.params); } catch (error) { failed(error); return; }
+        void load(page).then(resources => {
+          if (abort.signal.aborted) return;
+          const owned = scope(() => {
+            const state = resources.create({ input, domains: graph.forDomain(page.owner), location, signal: abort.signal });
+            if (state && typeof (state as unknown as { then?: unknown }).then === 'function') throw new Error('Presentation factories must be synchronous; use the provided AbortSignal for async work');
+            mount(() => resources.view(parent, state, destinations), parent, { onError: report });
+          });
+          dispose = owned.dispose;
+          if (abort.signal.aborted) { dispose(); return; }
+          settled = true; message.remove(); status.set({ phase: 'ready', destination: page.name }); emit('ready', page.name);
+          // Page-only focus management; opt-in target or the first heading.
+          const target = (parent as Element).querySelector?.('[data-hesh-focus], h1, h2') as HTMLElement | null | undefined;
+          if (target) { if (!target.hasAttribute('tabindex')) target.setAttribute('tabindex', '-1'); target.focus({ preventScroll: true }); }
+        }).catch(failed);
+      });
+    }
+  }) }));
+  let router: ReturnType<typeof createRouter>;
+  try { router = createRouter({ routes, window: options.window, onError: report }); }
+  catch (error) { graph.dispose(); throw error; }
+  for (const page of pages) {
+    if (destinations[page.name]) { graph.dispose(); throw new Error(`Duplicate destination ${page.name}`); }
+    const href = (input: object, transition: TransitionOptions = {}) => {
+      if (stopped) throw new Error('Application is disposed');
+      if (transition.presentation && transition.presentation !== 'page') throw new Error('Only page presentation is supported');
+      const values = validateInput(page.input, input);
+      const path = page.url.split('/').map(part => part.startsWith(':') ? encodeURIComponent(String(values[part.slice(1)])) : part).join('/');
+      const query = new URLSearchParams(transition.query).toString();
+      const hash = transition.hash ? '#' + encodeURIComponent(transition.hash) : '';
+      return path + (query ? '?' + query : '') + hash;
+    };
+    destinations[page.name] = Object.freeze({ name: page.name, href,
+      open(input: object, transition?: TransitionOptions) { authorize(page); router.navigate(href(input, transition)); },
+      replace(input: object, transition?: TransitionOptions) { authorize(page); router.navigate(href(input, transition), { replace: true }); },
+      async prefetch(input: object) { href(input); await load(page); }
+    });
+  }
+  const stop = () => { if (stopped) return; stopped = true; try { router.stop(); } finally { try { graph.dispose(); } finally { code.clear(); status.set({ phase: 'idle' }); } } };
+  return { destinations: Object.freeze(destinations), domains: graph.domains, status: { get: status.get },
+    start(parent) { if (stopped) throw new Error('Application is disposed'); try { router.start(parent); return stop; } catch (error) { stop(); throw error; } }, stop };
+}
+export { createDomainGraph };
+export type { DomainDefinition, DomainGraph };

package/src/dom/index.ts

@@ -12,7 +12,12 @@ export function mount(component: Component, parent: Node, options: MountOptions
 }
 
 export function element(parent: Node, name: string): HTMLElement {
-  const node = parent.ownerDocument!.createElement(aliases[name] ?? name);
+  return nativeElement(parent, aliases[name] ?? name);
+}
+
+/** Creates the exact HTML tag name, without Hesh shorthand aliases. */
+export function nativeElement(parent: Node, name: string): HTMLElement {
+  const node = parent.ownerDocument!.createElement(name);
   parent.appendChild(node);
   onCleanup(() => node.remove());
   return node;

package/src/domains/index.ts

@@ -0,0 +1,97 @@
+import { scope, type Disposer } from '../reactivity/index.js';
+export interface DomainDefinition {
+  name: string;
+  exposes: readonly string[];
+  consumes: readonly string[];
+  access?: Readonly<Record<string, string>>;
+  factory: (dependencies: Record<string, Record<string, unknown>>) => unknown;
+}
+export interface DomainOptions { authorize?: (policy: string) => boolean }
+export class ClientPolicyDenied extends Error {
+  readonly code = 'HESH-ACCESS-001';
+  constructor(readonly policy: string, readonly contract: string) {
+    super(`Client policy denied: ${policy} (${contract}). Server authorization is still required.`);
+  }
+}
+export interface DomainGraph<T = Record<string, Record<string, unknown>>> {
+  readonly domains: T;
+  forDomain(name: string): Record<string, unknown>;
+  dispose: Disposer;
+}
+const unsafe = new Set(['__proto__', 'constructor', 'prototype']);
+export function contractPath(path: string): string[] {
+  const parts = path.split('.');
+  if (parts.some(p => !p || unsafe.has(p))) throw new Error(`Invalid contract path ${path}`);
+  return parts;
+}
+function project(target: Record<string, unknown>, path: string[], value: unknown): void {
+  const name = path[0]!;
+  if (path.length === 1) { target[name] = value; return; }
+  if (target[name] !== undefined && (typeof target[name] !== 'object' || target[name] === null)) throw new Error(`Overlapping public contracts at ${name}`);
+  const next = (target[name] ??= Object.create(null)) as Record<string, unknown>;
+  project(next, path.slice(1), value);
+}
+function freeze(value: Record<string, unknown>): Record<string, unknown> {
+  for (const child of Object.values(value)) if (child && typeof child === 'object') freeze(child as Record<string, unknown>);
+  return Object.freeze(value);
+}
+function lookup(value: unknown, parts: string[]): { value: unknown; receiver: unknown } {
+  let receiver: unknown;
+  for (const part of parts) {
+    receiver = value;
+    value = value != null && Object.hasOwn(Object(value), part) ? (value as Record<string, unknown>)[part] : undefined;
+  }
+  return { value, receiver };
+}
+export function createDomainGraph(definitions: readonly DomainDefinition[], options: DomainOptions = {}): DomainGraph {
+  const byName = new Map(definitions.map(d => [d.name, d]));
+  if (byName.size !== definitions.length) throw new Error('Duplicate domain name');
+  const domains: Record<string, Record<string, unknown>> = Object.create(null);
+  const contexts: Record<string, Record<string, unknown>> = Object.create(null);
+  const building = new Set<string>();
+  let disposed = false;
+  const owned = scope(() => {
+    const build = (name: string): Record<string, unknown> => {
+      if (domains[name]) return domains[name]!;
+      const definition = byName.get(name);
+      if (!definition) throw new Error(`Missing domain ${name}`);
+      if (building.has(name)) throw new Error(`Circular domain dependency at ${name}`);
+      building.add(name);
+      const dependencies: Record<string, Record<string, unknown>> = Object.create(null);
+      for (const dependency of definition.consumes) {
+        const [provider, ...operation] = contractPath(dependency);
+        if (!operation.length) throw new Error(`Dependency must name an operation: ${dependency}`);
+        const target = build(provider!);
+        const value = lookup(target, operation).value;
+        if (typeof value !== 'function') throw new Error(`Missing public operation ${dependency}`);
+        project(dependencies[provider!] ??= Object.create(null), operation, value);
+      }
+      freeze(dependencies);
+      const implementation = definition.factory(dependencies);
+      if (implementation && typeof (implementation as { then?: unknown }).then === 'function') throw new Error(`Domain ${name} factory must be synchronous`);
+      const facade: Record<string, unknown> = Object.create(null);
+      for (const operation of definition.exposes) {
+        const parts = contractPath(operation);
+        const { value, receiver } = lookup(implementation, parts);
+        if (typeof value !== 'function') throw new Error(`Unresolved implementation ${name}.${operation}`);
+        project(facade, parts, (...args: unknown[]) => {
+          if (disposed) throw new Error('Domain graph is disposed');
+          const policy = definition.access?.[operation];
+          if (policy && options.authorize?.(policy) !== true) throw new ClientPolicyDenied(policy, `${name}.${operation}`);
+          return Reflect.apply(value, receiver, args);
+        });
+      }
+      domains[name] = freeze(facade);
+      contexts[name] = Object.freeze({ ...dependencies, [name]: domains[name] });
+      building.delete(name);
+      return domains[name]!;
+    };
+    for (const definition of definitions) build(definition.name);
+    freeze(domains);
+  });
+  return {
+    domains,
+    forDomain(name) { if (disposed) throw new Error('Domain graph is disposed'); if (!contexts[name]) throw new Error(`Unknown domain context ${name}`); return contexts[name]!; },
+    dispose() { if (disposed) return; disposed = true; owned.dispose(); }
+  };
+}

package/src/hmvc/index.ts

@@ -0,0 +1,71 @@
+import { mount, element, type Component, type MountOptions } from '../dom/index.js';
+import { signal, type Signal, type Disposer } from '../reactivity/index.js';
+
+export interface RouteLocation {
+  readonly url: URL;
+  readonly pathname: string;
+  readonly params: Readonly<Record<string, string>>;
+  readonly query: URLSearchParams;
+  readonly hash: string;
+}
+export interface ModuleContext<M = unknown, C = unknown> {
+  readonly route: Pick<Signal<RouteLocation>, 'get'>;
+  readonly parent?: ModuleContext;
+  readonly model: M;
+  readonly controller: C;
+}
+export interface ModuleDefinition<M, C> {
+  model: (context: Pick<ModuleContext, 'route' | 'parent'>) => M;
+  controller: (model: M, context: Pick<ModuleContext, 'route' | 'parent'>) => C;
+  view: Component;
+}
+export interface MountedModule {
+  readonly context: ModuleContext;
+  readonly outlet?: Node;
+  readonly dispose: Disposer;
+  update(location: RouteLocation): void;
+}
+export interface AppModule {
+  attach(parent: Node, location: RouteLocation, parentContext?: ModuleContext, options?: MountOptions): MountedModule;
+}
+let current: { context: ModuleContext; outlet?: Node } | undefined;
+
+export function useModule<M = unknown, C = unknown>(): ModuleContext<M, C> {
+  if (!current) throw new Error('Module context is only available during a module view mount');
+  return current.context as ModuleContext<M, C>;
+}
+export function useController<C = unknown>(): C { return useModule<unknown, C>().controller; }
+export function useModel<M = unknown>(): M { return useModule<M>().model; }
+
+/** Child route outlet. Import this component in a .hesh layout and call Outlet(). */
+export function Outlet(parent: Node): void {
+  if (!current) throw new Error('Outlet requires a module view');
+  if (current.outlet) throw new Error('A module may render only one Outlet');
+  current.outlet = element(parent, 'div');
+  (current.outlet as HTMLElement).setAttribute('data-hesh-outlet', '');
+}
+
+export function defineModule<M, C>(definition: ModuleDefinition<M, C>): AppModule {
+  return {
+    attach(parent, location, parentContext, options) {
+      const route = signal(location);
+      let state: { context: ModuleContext; outlet?: Node } | undefined;
+      const dispose = mount(() => {
+        const context = { route: { get: route.get }, parent: parentContext };
+        const model = definition.model(context);
+        const controller = definition.controller(model, context);
+        for (const value of [model, controller]) {
+          if (value && typeof (value as { then?: unknown }).then === 'function') throw new Error('HMVC model/controller factories must be synchronous');
+        }
+        state = { context: { ...context, model, controller } };
+        const previous = current;
+        current = state;
+        try {
+          const result: unknown = definition.view(parent);
+          if (result && typeof (result as { then?: unknown }).then === 'function') throw new Error('HMVC views must mount synchronously');
+        } finally { current = previous; }
+      }, parent, options);
+      return { context: state!.context, outlet: state!.outlet, dispose, update: next => { route.set(next); } };
+    }
+  };
+}

package/src/parser/index.ts

@@ -4,7 +4,15 @@ export interface Expression extends Location { source: string }
 export interface State extends Location { kind: 'state' | 'const'; name: string; value: Expression }
 export interface Element extends Location { kind: 'element'; name: string; value?: Expression; handler?: Expression; async: boolean; children: Element[] }
 export interface View extends Location { name: string; exported: boolean; default: boolean; body: (State | Element)[] }
-export interface Module { source: string; filename: string; imports: Expression[]; views: View[] }
+export interface ContractEntry extends Location { name: string; value?: string }
+export interface Contract extends Location {
+  kind: 'domain' | 'presentation' | 'destination' | 'application';
+  name: string;
+  fields: Record<string, ContractEntry>;
+  blocks: Record<string, ContractEntry[]>;
+}
+export interface Module { source: string; filename: string; imports: Expression[]; views: View[]; contracts?: Contract[] }
+export interface ParsedModule extends Module { contracts: Contract[] }
 export class HeshError extends Error {
   readonly line: number;
   readonly column: number;
@@ -61,7 +69,7 @@ export function tokenize(source: string, filename = 'component.hesh'): Token[] {
   return tokens;
 }
 
-export function parse(source: string, filename = 'component.hesh'): Module {
+export function parse(source: string, filename = 'component.hesh'): ParsedModule {
   const tokens = tokenize(source, filename);
   let at = 0;
   const peek = () => tokens[at]?.text;
@@ -119,8 +127,51 @@ export function parse(source: string, filename = 'component.hesh'): Module {
     else take(';');
     return { kind: 'element', name: name.text, start: name.start, end: tokens[at - 1]!.end, value, handler, async, children };
   };
-  const module: Module = { source, filename, imports: [], views: [] };
+  const contract = (): Contract => {
+    const kind = take(); const name = identifier(); take('{');
+    const result: Contract = { kind: kind.text as Contract['kind'], name: name.text, start: kind.start, end: 0, fields: Object.create(null), blocks: Object.create(null) };
+    const schemas: Record<Contract['kind'], Record<string, string>> = {
+      domain: { implementation: 'string', owns: 'list', exposes: 'list', consumes: 'list', access: 'map' },
+      presentation: { html: 'string', logic: 'string', styles: 'string', bindings: 'list', actions: 'list' },
+      destination: { url: 'string', input: 'map', presentation: 'identifier', access: 'string' },
+      application: { domains: 'list', destinations: 'list' }
+    };
+    const path = (): ContractEntry => {
+      const first = identifier(); let name = first.text;
+      while (peek() === '.') { take(); name += '.' + identifier().text; }
+      for (const part of name.split('.')) if (['__proto__', 'prototype', 'constructor'].includes(part)) fail('Unsafe contract identifier', first.start);
+      return { name, start: first.start, end: tokens[at - 1]!.end };
+    };
+    const string = () => {
+      const token = take();
+      if (token.kind !== ts.SyntaxKind.StringLiteral) fail('Expected quoted string', token.start);
+      const parsed = ts.createSourceFile('literal.js', token.text, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+      return ((parsed.statements[0] as ts.ExpressionStatement).expression as ts.StringLiteral).text;
+    };
+    while (peek() && peek() !== '}') {
+      const key = take(); const type = Object.hasOwn(schemas[result.kind], key.text) ? schemas[result.kind][key.text] : undefined;
+      if (!type) fail(`Unknown ${result.kind} field ${key.text}`, key.start);
+      if (result.fields[key.text] || result.blocks[key.text]) fail(`Duplicate field ${key.text}`, key.start);
+      if (type === 'string' || type === 'identifier') {
+        take(':'); const value = type === 'string' ? string() : identifier().text; const end = take(';').end;
+        result.fields[key.text] = { name: key.text, value, start: key.start, end };
+      } else {
+        take('{'); const entries: ContractEntry[] = []; const seen = new Set<string>();
+        while (peek() && peek() !== '}') {
+          const entry = path();
+          if (seen.has(entry.name)) fail(`Duplicate entry ${entry.name}`, entry.start); seen.add(entry.name);
+          if (type === 'map') { take(':'); entry.value = key.text === 'input' ? identifier().text : string(); }
+          entry.end = take(';').end; entries.push(entry);
+        }
+        take('}'); result.blocks[key.text] = entries;
+      }
+    }
+    result.end = take('}').end;
+    return result;
+  };
+  const module: ParsedModule = { source, filename, imports: [], views: [], contracts: [] };
   while (tokens[at]) {
+    if (['domain', 'presentation', 'destination', 'application'].includes(peek() ?? '')) { module.contracts.push(contract()); continue; }
     if (peek() === 'import') {
       if (module.views.length) fail('Imports must precede views');
       const start = take().start;
@@ -144,6 +195,6 @@ export function parse(source: string, filename = 'component.hesh'): Module {
     const end = take('}').end;
     module.views.push({ name, body, start, end, exported, default: isDefault });
   }
-  if (!module.views.length) fail('Expected at least one view');
+  if (!module.views.length && !module.contracts.length) fail('Expected at least one view or architecture declaration');
   return module;
 }

package/src/presentation/index.ts

@@ -0,0 +1,31 @@
+import { effect } from '../reactivity/index.js';
+import { nativeElement as element, text, attribute, listen } from '../dom/index.js';
+export { element, text, attribute, listen };
+export interface PresentationState { bindings: Record<string, unknown>; actions: Record<string, (event: Event) => unknown> }
+export function readBinding(bindings: Record<string, unknown>, path: string): unknown {
+  const unwrap = (value: unknown): unknown => {
+    if (typeof value === 'function') return value();
+    if (value && typeof (value as { get?: unknown }).get === 'function') return (value as { get(): unknown }).get();
+    return value;
+  };
+  let value: unknown = bindings;
+  for (const part of path.split('.')) {
+    if (['__proto__', 'constructor', 'prototype'].includes(part)) throw new Error('Unsafe binding path');
+    value = (unwrap(value) as Record<string, unknown> | null)?.[part];
+  }
+  return unwrap(value);
+}
+export function bindValue(node: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, bindings: Record<string, unknown>, name: string): void {
+  const state = bindings[name] as { get?(): unknown; set?(value: unknown): void };
+  if (typeof state?.get !== 'function' || typeof state.set !== 'function') throw new Error(`h-value ${name} requires a writable signal`);
+  effect(() => { const value = String(state.get!() ?? ''); if (node.value !== value) node.value = value; });
+  listen(node, 'input', () => state.set!(node.value));
+}
+export function bindAction(node: HTMLElement, state: PresentationState, name: string): void {
+  const handler = state.actions[name];
+  if (typeof handler !== 'function') throw new Error(`Missing presentation action ${name}`);
+  listen(node, node.tagName === 'FORM' ? 'submit' : 'click', event => {
+    if (node.tagName === 'FORM') event.preventDefault();
+    return handler.call(state.actions, event);
+  });
+}

package/src/router/index.ts

@@ -0,0 +1,171 @@
+import { signal, batch, type Disposer } from '../reactivity/index.js';
+import type { AppModule, MountedModule, RouteLocation } from '../hmvc/index.js';
+export type { RouteLocation } from '../hmvc/index.js';
+export interface RouteRecord { path: string; module: AppModule; children?: readonly RouteRecord[] }
+export interface RouterOptions {
+  routes: readonly RouteRecord[];
+  window?: Window;
+  notFound?: AppModule;
+  onError?: (error: unknown) => void;
+}
+interface Entry { record: RouteRecord; params: Record<string, string> }
+interface Active extends Entry { instance: MountedModule }
+
+function segments(path: string): string[] { return path.split('/').filter(Boolean); }
+function validate(routes: readonly RouteRecord[], ancestors = new Set<string>()): void {
+  const siblings = new Set<string>();
+  for (const route of routes) {
+    if (/[?#]/.test(route.path)) throw new Error(`Route paths cannot contain query/hash: ${route.path}`);
+    const parts = segments(route.path);
+    const signature = parts.map(p => p.startsWith(':') ? ':' : p).join('/');
+    if (siblings.has(signature)) throw new Error(`Duplicate sibling route: ${route.path}`);
+    siblings.add(signature);
+    const names = new Set(ancestors);
+    parts.forEach((p, i) => {
+      if (p === '*' && (i !== parts.length - 1 || route.children?.length)) throw new Error('Wildcard must end a leaf route');
+      if (p.startsWith(':')) {
+        const name = p.slice(1);
+        if (!/^[a-zA-Z_][a-zA-Z\d_]*$/.test(name) || names.has(name) || ['__proto__', 'prototype', 'constructor'].includes(name)) throw new Error(`Invalid or duplicate route param: ${name}`);
+        names.add(name);
+      }
+    });
+    validate(route.children ?? [], names);
+  }
+}
+function find(routes: readonly RouteRecord[], parts: string[], at = 0, params: Record<string, string> = {}): Entry[] | undefined {
+  const ordered = [...routes].sort((a, b) => {
+    const aa = segments(a.path), bb = segments(b.path);
+    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+      const rank = (p?: string) => p === '*' ? 0 : p?.startsWith(':') ? 1 : p ? 2 : 0.5;
+      const diff = rank(bb[i]) - rank(aa[i]); if (diff) return diff;
+    }
+    return 0;
+  });
+  for (const record of ordered) {
+    const own = { ...params }; let cursor = at, matched = true;
+    for (const part of segments(record.path)) {
+      if (part === '*') { own['wildcard'] = parts.slice(cursor).join('/'); cursor = parts.length; break; }
+      const actual = parts[cursor++];
+      if (actual === undefined) { matched = false; break; }
+      if (part.startsWith(':')) own[part.slice(1)] = actual;
+      else if (part !== actual) { matched = false; break; }
+    }
+    if (!matched) continue;
+    const entry = { record, params: own };
+    const children = find(record.children ?? [], parts, cursor, own);
+    if (children) return [entry, ...children];
+    if (cursor === parts.length) return [entry];
+  }
+  return undefined;
+}
+
+export function createRouter(options: RouterOptions) {
+  validate(options.routes);
+  const browser = options.window ?? (typeof window !== 'undefined' ? window : undefined);
+  if (!browser) throw new Error('createRouter requires a browser Window');
+  const report = options.onError ?? ((error: unknown) => console.error(error));
+  const location = signal<RouteLocation>(makeLocation(new URL(browser.location.href), {}));
+  let root: Node | undefined, active: Active[] = [], fallback: HTMLElement | undefined;
+  let transitioning = false;
+  let generation = 0;
+  const notFoundRecord: RouteRecord | undefined = options.notFound ? { path: '*', module: options.notFound } : undefined;
+  function makeLocation(url: URL, params: Record<string, string>): RouteLocation {
+    return Object.freeze({ url: new URL(url), pathname: url.pathname, params: Object.freeze({ ...params }), query: new URLSearchParams(url.search), hash: url.hash });
+  }
+  function render(url: URL): void {
+    if (!root) throw new Error('Start the router before navigating');
+    if (transitioning) throw new Error('Navigation during module mounting is not supported');
+    transitioning = true;
+    try {
+      let entries: Entry[] | undefined;
+      try { entries = find(options.routes, segments(url.pathname).map(decodeURIComponent)); }
+      catch (error) { if (!(error instanceof URIError)) throw error; }
+      if (!entries && notFoundRecord) entries = [{ record: notFoundRecord, params: {} }];
+      entries ??= [];
+      let keep = 0;
+      while (keep < active.length && keep < entries.length && active[keep]!.record === entries[keep]!.record && JSON.stringify(active[keep]!.params) === JSON.stringify(entries[keep]!.params)) keep++;
+      const removed = active.splice(keep);
+      const errors: unknown[] = [];
+      for (const item of removed.reverse()) { try { item.instance.dispose(); } catch (error) { errors.push(error); } }
+      fallback?.remove(); fallback = undefined;
+      if (errors.length) throw new AggregateError(errors, 'Route cleanup failed');
+      const added: Active[] = [];
+      try {
+        for (let i = keep; i < entries.length; i++) {
+          const entry = entries[i]!;
+          const parent = active.at(-1);
+          const outlet = parent ? parent.instance.outlet : root;
+          if (!outlet) throw new Error(`Parent module ${parent!.record.path} must render Outlet()`);
+          const instance = entry.record.module.attach(outlet, makeLocation(url, entry.params), parent?.instance.context, { onError: report });
+          const item = { ...entry, instance };
+          active.push(item); added.push(item);
+        }
+      } catch (error) {
+        active.splice(keep);
+        for (const item of added.reverse()) { try { item.instance.dispose(); } catch (cleanupError) { report(cleanupError); } }
+        throw error;
+      }
+      if (!entries.length) {
+        fallback = root.ownerDocument!.createElement('p');
+        fallback.setAttribute('role', 'status'); fallback.textContent = 'Page not found'; root.appendChild(fallback);
+      }
+      batch(() => {
+        for (const item of active) item.instance.update(makeLocation(url, item.params));
+        location.set(makeLocation(url, entries.at(-1)?.params ?? {}));
+      });
+    } finally { transitioning = false; }
+  }
+  function navigate(to: string, navigation: { replace?: boolean } = {}): void {
+    if (!root) throw new Error('Start the router before navigating');
+    const url = new URL(to, browser!.location.href);
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser!.location.origin) throw new Error('Router navigation requires a same-origin HTTP(S) URL');
+    if (url.href === browser!.location.href) return;
+    render(url);
+    browser!.history[navigation.replace ? 'replaceState' : 'pushState'](null, '', url.href);
+  }
+  const popstate = () => {
+    try { if (location.get().url.href !== browser!.location.href) render(new URL(browser!.location.href)); }
+    catch (error) { report(error); }
+  };
+  const click = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+    const target = event.target as Element | null;
+    const anchor = target?.closest?.('a[href]');
+    if (!anchor || anchor.hasAttribute('download') || anchor.hasAttribute('data-hesh-reload') || (anchor.getAttribute('target') && anchor.getAttribute('target')!.toLowerCase() !== '_self')) return;
+    const href = anchor.getAttribute('href')!;
+    if (href.startsWith('#')) return;
+    let url: URL;
+    try { url = new URL(href, browser!.document.baseURI); } catch { return; }
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser!.location.origin) return;
+    if (url.pathname === browser!.location.pathname && url.search === browser!.location.search && url.hash) return;
+    event.preventDefault();
+    try { navigate(url.href); } catch (error) { report(error); }
+  };
+  function stop(): void {
+    if (transitioning) throw new Error('Cannot stop the router during module mounting');
+    browser!.document.removeEventListener('click', click);
+    browser!.removeEventListener('popstate', popstate);
+    browser!.removeEventListener('hashchange', popstate);
+    const old = active; active = []; root = undefined;
+    generation++;
+    fallback?.remove(); fallback = undefined;
+    const errors: unknown[] = [];
+    for (const item of old.reverse()) { try { item.instance.dispose(); } catch (error) { errors.push(error); } }
+    if (errors.length) throw new AggregateError(errors, 'Router cleanup failed');
+  }
+  return {
+    location: { get: location.get }, navigate, stop,
+    start(parent: Node): Disposer {
+      if (root) throw new Error('Router is already started');
+      if (parent.ownerDocument !== browser!.document) throw new Error('Router root must belong to its Window');
+      const started = ++generation;
+      root = parent;
+      try { render(new URL(browser!.location.href)); }
+      catch (error) { stop(); throw error; }
+      browser!.document.addEventListener('click', click);
+      browser!.addEventListener('popstate', popstate);
+      browser!.addEventListener('hashchange', popstate);
+      return () => { if (generation === started) stop(); };
+    }
+  };
+}