@heshammesalam/heshjs 0.2.0 → 0.3.0

package/docs/domain-graph.md

@@ -0,0 +1,205 @@
+# Domain Graph first vertical slice (0.3)
+
+This opt-in architecture builds on the existing Hesh compiler, shallow reactivity,
+DOM renderer, router and HMVC. Existing components and `createRouter` remain valid.
+This is the first architecture milestone, not an enterprise-ready framework.
+These APIs require 0.3 or later. Install `@heshammesalam/heshjs@0.3.0` in an
+existing Vite application and enable the architecture option described below.
+The npm creator's default template remains HMVC; it does not scaffold domains.
+The following commands run the reference examples from the framework repository:
+
+```sh
+npm install
+npm run check:architecture
+npm run dev:domains       # JS Identity/Inventory/Finance demo, localhost:5180
+npm run dev:domains:ts    # strict TS alternative, localhost:5181
+```
+
+The JS demo uses mock identity, an abortable timer-backed mock product API and a
+mock tax service. No HTTP server, credentials, payments or real authorization are
+implemented. Browser refresh restores destination/path input, not in-memory demo
+login state. Journeys are deliberately not simulated.
+
+## Descriptors and real implementations
+
+```hesh
+domain Inventory {
+  implementation: "./inventory.js#createInventory";
+  owns { Product; }
+  exposes { products.get; stock.reserve; }
+  consumes { Identity.session; }
+  access { stock.reserve: "inventory.reserve"; }
+}
+presentation ProductScreen {
+  html: "./ui/product.html";
+  logic: "./ui/product.js#createProduct";
+  styles: "./ui/product.css";
+  bindings { title; }
+  actions { reserve; }
+}
+destination ProductDetails {
+  url: "/products/:id";
+  input { id: string; }
+  presentation: ProductScreen;
+  access: "inventory.read";
+}
+```
+
+```js
+// inventory.js: private implementation, no imports from another domain's files.
+export function createInventory(dependencies) {
+  return {
+    products: { get: id => ({ id, title: 'Mock product' }) },
+    stock: { reserve: id => dependencies.Identity.session() + ': ' + id }
+  };
+}
+```
+
+`owns` is metadata, not a generated entity/database/validation system. Exposes are
+checked against the real factory return type. Consumers receive only the listed
+public operations, not the whole implementation object. Factories execute once
+per application domain graph in dependency order. Cycles and missing contracts
+are errors. Dependencies and public facades are frozen; disposed graphs reject
+further operation calls. Factories may use `onCleanup` for owned resources.
+
+The application descriptor imports domain files explicitly and selects names:
+
+```hesh
+import "./domains/identity/domain.hesh";
+import "./domains/inventory/domain.hesh";
+application Shop {
+  domains { Identity; Inventory; }
+  destinations { ProductDetails; }
+}
+```
+
+Every selected destination/presentation belongs to one selected domain directory.
+Each domain has its own directory boundary. Shared code can be imported by domains;
+shared code cannot re-export a private domain implementation as an escape hatch.
+
+## Standard HTML, CSS and explicit bindings
+
+```html
+<section aria-labelledby="title">
+  <h1 id="title">{title}</h1>
+  <button h-action="reserve">Reserve</button>
+</section>
+```
+
+```js
+import { signal } from '@heshammesalam/heshjs';
+export function createProduct({ domains, input, location, signal: cancellation }) {
+  const title = signal(domains.Inventory.products.get(input.id).title);
+  return {
+    bindings: { title },
+    actions: { reserve() { domains.Inventory.stock.reserve(input.id); } }
+  };
+}
+```
+
+Bindings are explicit declared data paths, not arbitrary evaluated JS strings.
+`{product.name}` and `h-bind="product.name"` use text nodes. `\{`/`\}` produce
+literal braces. A whole attribute binding like `disabled="{disabled}"` preserves
+boolean values; mixed attribute text is a string. Standard native HTML/custom tags
+are preserved without Hesh element aliases. Browser forms, labels, ARIA and native
+validation remain available. `h-action` means click, or submit on a form (preventing
+full submission). Events are passed to actions and async errors use onError.
+`h-value="email"` is two-way binding to a root writable signal on text controls.
+
+`h-destination="ProductDetails" h-input-id="productId"` on a native anchor builds
+a real href from the destination contract. Input attributes follow HTML's case
+insensitivity; destination input names must therefore be unique ignoring case.
+Missing/extra/wrongly typed inputs, missing bindings/actions and unsafe directives
+produce located diagnostics. Dynamic any-typed data emits warnings when the shape
+cannot be proven. JS receives inferred checks/JSDoc where present and runtime
+input validation; this does not make arbitrary JavaScript fully type-safe.
+
+HTML is parsed with parse5 at build time and emitted as DOM instructions. No
+innerHTML/eval/Function constructor is used. Script/embedding/foreign/template
+elements, inline event attributes and unknown h-* directives are rejected. SVG,
+keyed h-each, raw HTML and scoped CSS are not implemented in this slice. Standard
+CSS is imported unchanged through Vite, including variables, modern selectors,
+media/container queries, animations and global themes. CSS is global in this release.
+
+## Generated typed destinations
+
+Configure Vite using `hesh({ architecture: { root: 'src' } })`. For a tsconfig
+outside src add `tsconfig: '../tsconfig.json'`. The plugin validates before build
+and generates `src/.hesh-generated/app.js`, app.d.ts and compiled presentation
+modules. Do not hand-edit generated files. Invalid checks block build; last valid
+files are not deleted, so bypassing the check pipeline can use stale output.
+
+```js
+import { createApplication } from './.hesh-generated/app.js';
+const app = createApplication({
+  authorize: policy => policy === 'inventory.read', // CLIENT ONLY
+  onError: error => console.error(error),
+  onDiagnostic: event => console.debug(event.type, event.destination, event.reason)
+});
+const dispose = app.start(document.querySelector('#app'));
+app.destinations.ProductDetails.open({ id: '15' });
+app.destinations.ProductDetails.replace({ id: '20' }, { query: { tab: 'stock' } });
+await app.destinations.ProductDetails.prefetch({ id: '30' });
+```
+
+Generated declarations give each destination its exact required input fields and
+primitive types. Empty-input destinations use `Record<string, never>`. Runtime
+validation also rejects unknown/missing fields, non-finite numbers, empty strings
+and URL dot segments. Inputs are encoded once and decoded once; URL parameter
+names currently use the existing router's ASCII letter/digit/underscore rules.
+Overlapping destination patterns are rejected so an input cannot silently open a
+different static destination. This restriction applies only to the new contracts;
+the existing router retains its static-priority behavior.
+
+Page is the only supported presentation mode. Destinations load their own compiled
+presentation and logic resources lazily. Prefetch deduplicates those code loads;
+it does not fetch business data or authorize operations. Navigation disposes the
+previous presentation, aborts its signal and prevents a late loader from mounting
+stale UI. Dynamic module downloads themselves cannot be canceled. Factories are
+synchronous and start their own asynchronous work using the supplied signal.
+Guard against late results when using non-abortable services. Query/hash changes
+create a fresh presentation instance. Successful mounting focuses a heading or
+`data-hesh-focus`; scroll restoration and modal focus trapping are deferred.
+
+`app.status.get()` is reactive loading/ready/error state. Optional diagnostic
+events identify loading, ready, blocked, errors, cancellation and disposal. They
+do not infer business intent or explain arbitrary reactive dependency chains.
+Client policies default to deny when declared without an authorize callback;
+server-side enforcement is still necessary for every protected operation.
+
+## Architecture validation and graph tooling
+
+```sh
+hesh check ./src --write
+hesh check ./src --tsconfig ../tsconfig.json --write
+hesh graph ./src
+```
+
+From the repository use `node packages/heshjs/cli.js ...`. Root means the directory
+containing app.hesh, typically src. The TS resolver handles aliases, relative paths,
+type imports and re-exports. Canonical paths account for filesystem aliases and
+symlinks. Physical cross-domain imports of implementations are private, even if
+the target JS module exports a function; use declared injection instead. Node and
+server-only modules are blocked in client code. Computed imports in application
+source are rejected because their target cannot be validated. This is build-time
+architecture enforcement for configured projects, not a sandbox against malicious
+application code, reflection or uninspected third-party packages.
+
+Diagnostics include code, severity, path, offset/line/column, explanation and a
+suggestion. HTML locations identify their source node/attribute; entity decoding
+can make the exact inner text offset approximate. Graph JSON contains domain
+dependencies, destination ownership/input schemas and compiled navigation links.
+Descriptor ASTs are reused when unchanged and output writes are content-based.
+Semantic analysis currently rechecks the whole graph; precise dependency-aware
+typecheck invalidation and full HTML/Hesh source maps are deferred. The Vite workflow
+uses full reload rather than state-preserving HMR.
+
+## Deliberate limits
+
+Journeys, modal/panel/nested destination modes, redirects, scroll restoration,
+file routing, generic async resources/caching, deep collections, scoped CSS,
+server authorization, SSR/hydration, advanced scaffolding commands and a language
+server are not implemented. Existing HMVC nested routes remain usable separately.
+Production hosts still need SPA fallback to index.html for direct URLs. No
+performance superiority, globally unique architecture or enterprise-readiness
+claim is made. See architecture/domain-graph-audit.md for migration order.

package/docs/grammar.md

@@ -1,5 +1,9 @@
 # Milestone 1 language (v0.1)
 
+This remains the legacy component grammar. The opt-in architecture descriptor
+extension is specified separately in [contracts.md](contracts.md); it does not
+replace existing .hesh views or add template directives to the brace UI syntax.
+
 The grammar is deliberately smaller than the product roadmap. Source is UTF-8.
 Whitespace and JavaScript comments separate tokens. Identifiers follow JavaScript
 identifier rules. Strings and numbers follow JavaScript lexical rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heshammesalam/heshjs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An experimental independent reactive UI framework with brace-based .hesh components",
   "author": "Hesham",
   "license": "UNLICENSED",
@@ -16,11 +16,16 @@
     "./vite": { "types": "./dist/vite/index.d.ts", "import": "./dist/vite/index.js" },
     "./router": { "types": "./dist/router/index.d.ts", "import": "./dist/router/index.js" },
     "./hmvc": { "types": "./dist/hmvc/index.d.ts", "import": "./dist/hmvc/index.js" },
+    "./domains": { "types": "./dist/domains/index.d.ts", "import": "./dist/domains/index.js" },
+    "./destinations": { "types": "./dist/destinations/index.d.ts", "import": "./dist/destinations/index.js" },
+    "./presentation": { "types": "./dist/presentation/index.d.ts", "import": "./dist/presentation/index.js" },
+    "./architecture": { "types": "./dist/architecture/index.d.ts", "import": "./dist/architecture/index.js" },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "src", "docs", "README.md"],
+  "files": ["dist", "src", "docs", "README.md", "cli.js"],
+  "bin": { "hesh": "./cli.js" },
   "engines": { "node": ">=22.12.0" },
-  "dependencies": { "typescript": "~5.9.3" },
+  "dependencies": { "typescript": "~5.9.3", "parse5": "8.1.0" },
   "peerDependencies": { "vite": "^7.2.2" },
   "peerDependenciesMeta": { "vite": { "optional": true } },
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }

package/src/architecture/diagnostics.ts

@@ -0,0 +1,11 @@
+export interface ArchitectureDiagnostic {
+  code: string; severity: 'error' | 'warning'; message: string;
+  file: string; offset: number; line: number; column: number; suggestion: string;
+}
+export function diagnostic(code: string, message: string, file: string, source: string, offset: number, suggestion: string, severity: 'error' | 'warning' = 'error'): ArchitectureDiagnostic {
+  const lines = source.slice(0, offset).split('\n');
+  return { code, message, file, offset, line: lines.length, column: lines.at(-1)!.length + 1, suggestion, severity };
+}
+export function formatDiagnostic(item: ArchitectureDiagnostic): string {
+  return `${item.file}:${item.line}:${item.column} ${item.code} ${item.severity}: ${item.message}\n  ${item.suggestion}`;
+}

package/src/architecture/html.ts

@@ -0,0 +1,88 @@
+import { parseFragment, type DefaultTreeAdapterMap } from 'parse5';
+import { diagnostic, type ArchitectureDiagnostic } from './diagnostics.js';
+export interface HTMLContract {
+  filename: string; bindings: string[]; actions: string[];
+  destinations: Record<string, Record<string, string>>;
+  validateBinding?: (path: string, offset: number, expected?: string, writable?: boolean) => void;
+}
+export interface HTMLResult { code: string; diagnostics: ArchitectureDiagnostic[]; usedBindings: string[]; usedActions: string[]; destinations: string[] }
+export function compileHTML(source: string, contract: HTMLContract): HTMLResult {
+  const diagnostics: ArchitectureDiagnostic[] = [], usedBindings = new Set<string>(), usedActions = new Set<string>();
+  const report = (code: string, message: string, at: number, suggestion: string, severity: 'error' | 'warning' = 'error') => diagnostics.push(diagnostic(code, message, contract.filename, source, at, suggestion, severity));
+  const fragment = parseFragment(source, { sourceCodeLocationInfo: true, onParseError: error => report('HESH-HTML-001', error.code, error.startOffset, 'Correct the HTML syntax.') });
+  const lines = ["import * as p from '@heshammesalam/heshjs/presentation';", 'export default function render(parent, state, destinations) {'];
+  let serial = 0;
+  const linked = new Set<string>();
+  const path = (value: string, offset: number, expected?: string, writable = false): string => {
+    const pieces = value.trim().split('.');
+    if (pieces.some(piece => !/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(piece) || ['constructor', '__proto__', 'prototype'].includes(piece))) report('HESH-BIND-001', `Invalid binding path ${value}`, offset, 'Use a declared dotted data path, not an expression.');
+    if (!contract.bindings.includes(pieces[0]!)) report('HESH-BIND-002', `Missing data binding ${pieces[0]}`, offset, 'Declare the binding and return it from the presentation factory.');
+    usedBindings.add(pieces[0]!); contract.validateBinding?.(value.trim(), offset, expected, writable);
+    return `p.readBinding(state.bindings, ${JSON.stringify(value.trim())})`;
+  };
+  const interpolation = (value: string, offset: number): string => {
+    const parts: string[] = []; let literal = '', cursor = 0;
+    const emit = () => { if (literal) { parts.push(JSON.stringify(literal)); literal = ''; } };
+    while (cursor < value.length) {
+      if (value[cursor] === '\\' && ['{', '}'].includes(value[cursor + 1] ?? '')) { literal += value[cursor + 1]; cursor += 2; continue; }
+      if (value[cursor] !== '{') { literal += value[cursor++]; continue; }
+      emit(); const start = ++cursor, end = value.indexOf('}', start);
+      if (end < 0) { report('HESH-BIND-001', 'Unterminated interpolation', offset + start - 1, 'Close the binding with }.'); break; }
+      parts.push(`String(${path(value.slice(start, end), offset + start)} ?? '')`); cursor = end + 1;
+    }
+    emit(); return parts.join(' + ') || "''";
+  };
+  const visit = (node: DefaultTreeAdapterMap['childNode'], parent: string): void => {
+    const at = node.sourceCodeLocation?.startOffset ?? 0;
+    if (node.nodeName === '#text') { lines.push(`p.text(${parent}, () => ${interpolation((node as DefaultTreeAdapterMap['textNode']).value, at)});`); return; }
+    if (!('tagName' in node)) return;
+    if (node.namespaceURI !== 'http://www.w3.org/1999/xhtml' || ['script', 'iframe', 'object', 'embed', 'base', 'meta', 'link', 'style', 'template'].includes(node.tagName)) {
+      report('HESH-HTML-002', `Unsupported active/foreign template element <${node.tagName}>`, at, 'Use semantic HTML and declared CSS/JS modules.'); return;
+    }
+    const id = `node${serial++}`;
+    lines.push(`const ${id} = p.element(${parent}, ${JSON.stringify(node.tagName)});`);
+    const attributes = Object.fromEntries(node.attrs.map(attr => [attr.name, attr.value]));
+    const attrAt = (name: string) => node.sourceCodeLocation?.attrs?.[name]?.startOffset ?? at;
+    for (const attr of node.attrs) {
+      if (attr.name.startsWith('h-')) continue;
+      if (/^on/i.test(attr.name) || ['srcdoc', 'innerhtml', 'outerhtml'].includes(attr.name)) { report('HESH-HTML-003', `Unsafe attribute ${attr.name}`, attrAt(attr.name), 'Use h-action and safe DOM bindings.'); continue; }
+      const wholeBinding = attr.value.startsWith('{') && attr.value.endsWith('}') && !attr.value.slice(1, -1).includes('{') && !attr.value.slice(1, -1).includes('}');
+      lines.push(`p.attribute(${id}, ${JSON.stringify(attr.name)}, () => ${wholeBinding ? path(attr.value.slice(1, -1), attrAt(attr.name) + 1) : interpolation(attr.value, attrAt(attr.name))});`);
+    }
+    for (const name of Object.keys(attributes)) if (name.startsWith('h-') && !['h-action', 'h-bind', 'h-value', 'h-destination'].includes(name) && !name.startsWith('h-input-')) report('HESH-HTML-004', `Unsupported directive ${name}`, attrAt(name), 'Use supported directives; keyed lists/scoped templates are a later milestone.');
+    if (attributes['h-bind'] !== undefined) {
+      if (node.childNodes.length) report('HESH-BIND-003', 'h-bind cannot also contain children', at, 'Remove the children or use text interpolation.');
+      lines.push(`p.text(${id}, () => ${path(attributes['h-bind'], attrAt('h-bind'))});`);
+    } else node.childNodes.forEach(child => visit(child, id));
+    if (attributes['h-action'] !== undefined) {
+      const name = attributes['h-action']; usedActions.add(name);
+      if (!contract.actions.includes(name)) report('HESH-ACTION-001', `Missing action ${name}`, attrAt('h-action'), 'Declare and implement the action.');
+      lines.push(`p.bindAction(${id}, state, ${JSON.stringify(name)});`);
+    }
+    if (attributes['h-value'] !== undefined) {
+      const name = attributes['h-value'];
+      if (!['input', 'textarea', 'select'].includes(node.tagName) || name.includes('.') || ['checkbox', 'radio', 'file'].includes(attributes.type ?? '') || attributes.multiple !== undefined) report('HESH-BIND-004', 'h-value requires a single-value text control and root writable signal', attrAt('h-value'), 'Use a text input/textarea/single select and a declared signal.');
+      path(name, attrAt('h-value'), undefined, true);
+      lines.push(`p.bindValue(${id}, state.bindings, ${JSON.stringify(name)});`);
+    }
+    const destination = attributes['h-destination'];
+    const inputs = Object.keys(attributes).filter(name => name.startsWith('h-input-'));
+    if (destination !== undefined) {
+      linked.add(destination);
+      const schema = contract.destinations[destination];
+      if (!schema) report('HESH-NAV-001', `Unknown destination ${destination}`, attrAt('h-destination'), 'Declare this destination in the application.');
+      if (node.tagName !== 'a' || attributes.href !== undefined) report('HESH-NAV-002', 'h-destination requires an anchor without an explicit href', at, 'Use <a h-destination="Name" ...>.');
+      for (const key of Object.keys(schema ?? {})) if (attributes[`h-input-${key.toLowerCase()}`] === undefined) report('HESH-NAV-003', `Missing destination input ${key}`, at, `Add h-input-${key} bound to a declared value.`);
+      const entries = inputs.map(attr => {
+        const key = Object.keys(schema ?? {}).find(key => key.toLowerCase() === attr.slice(8)) ?? attr.slice(8);
+        if (!schema || !Object.hasOwn(schema, key)) report('HESH-NAV-003', `Unknown destination input ${key}`, attrAt(attr), 'Use only inputs declared by the destination.');
+        return `${JSON.stringify(key)}: ${path(attributes[attr]!, attrAt(attr), schema?.[key])}`;
+      });
+      lines.push(`p.attribute(${id}, 'href', () => destinations[${JSON.stringify(destination)}].href({${entries.join(',')}}));`);
+    } else if (inputs.length) report('HESH-NAV-003', 'h-input-* requires h-destination', at, 'Declare the destination on this anchor.');
+  };
+  fragment.childNodes.forEach(node => visit(node, 'parent')); lines.push('}');
+  for (const name of contract.bindings) if (!usedBindings.has(name)) report('HESH-BIND-005', `Unused binding ${name}`, 0, 'Remove the declaration if it is not needed by this template.', 'warning');
+  for (const name of contract.actions) if (!usedActions.has(name)) report('HESH-ACTION-002', `Unused action ${name}`, 0, 'Remove the declaration if it is not needed by this template.', 'warning');
+  return { code: lines.join('\n'), diagnostics, usedBindings: [...usedBindings], usedActions: [...usedActions], destinations: [...linked] };
+}