@expressive/dom 0.0.0

package/README.md

@@ -0,0 +1,79 @@
+<h1 align="center">@expressive/dom</h1>
+
+<p align="center">
+  MVC-native JSX rendering for the browser DOM.
+</p>
+
+---
+
+`@expressive/dom` renders Expressive MVC without React or Preact. Function components are renderer-stateless: they project props and MVC snapshots into DOM, while `State.get()` and `State.use()` supply dependency tracking and owned state.
+
+```bash
+npm install @expressive/mvc @expressive/dom
+```
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@expressive/dom"
+  }
+}
+```
+
+```tsx
+import { State, Component } from '@expressive/mvc';
+import { render } from '@expressive/dom';
+
+class Counter extends State {
+  count = 0;
+  increment() {
+    this.count++;
+  }
+}
+
+function Count() {
+  const { count, increment } = Counter.use();
+  return <button onClick={increment}>{count}</button>;
+}
+
+const unmount = render(<Count />, document.getElementById('app')!);
+```
+
+`style` recursively composes conditional class tokens and inline declarations. Strings become classes; objects merge left-to-right and render inline. Use `className` for a browser-specific class outside the composition. The `class` attribute spelling and CSS declaration strings are not supported.
+
+```tsx
+<button
+  className="external-widget"
+  style={[styles.button, active && 'active', { width }]}
+/>
+```
+
+`style` on a component automatically reaches its rendered host root, including through component, fragment, provider, portal, and collection boundaries. A fragment applies it to each host root. Forwarded style overrides the root's own, with the outermost caller winning. A component which reads its `style` prop while rendering owns placement, and nothing is forwarded. It receives a frozen object of the caller's inline declarations - spread, pluck or merge it freely; the caller's classes travel hidden with it. `className` applies to elements only.
+
+A component may register immutable maps with `style(Component, map)`. A `_name` entry is a rule, applied by a truthy `_name` attribute or a matching host tag and emitted as one class named after its source; nested inside a rule it opens a descendant scope. Component names never match - they do not survive minification. Bare keys are declarations, or macro calls where a macro owns the name, and those at the top of a map form a base rule applied to each of the component's host roots. Macros are defined only by `macro()` - within a map, call a plain function instead. `$name` is reserved. `_` attributes never reach the DOM, and `0` or `''` leaves a rule off. A map never reaches inside a child component; only the class chain inherits.
+
+```tsx
+function Button({ active }: { active: boolean }) {
+  return <button _active={active}>Save</button>;
+}
+
+style(Button, {
+  padding: '8px',
+  _active: { fontWeight: 700 }
+});
+```
+
+Global maps use `macro(map)` and can live in side-effect imports. Register macros and styles before the first relevant render. A key resolves at its topmost definition; a macro returning its own name falls to the next definition down, then through any `'*'` handler. Unhandled keys reach the host, which joins arrays and rejects functions and objects - units belong to a macro, never a guess.
+
+Inline style always beats classes; among classes, a caller's rule beats the callee's, and a rule carried through more component `style` props wins - independent of render order. `false`, `null`, and `undefined` omit an entry; `0` remains a macro argument.
+
+`Component` retains the React adapter's model: fields read by `render()` are dependencies, owned instances mount and clean up with the DOM range, and an externally activated instance can be placed directly without transferring ownership.
+
+The first release includes keyed reconciliation, native events, refs, SVG, `Provider` / `Consumer`, direct `has` / `map` collection rendering, portals, lazy components, error and suspense fallbacks, generated component appearance rules, and retention of committed content while `pending()` work suspends. It deliberately excludes standalone hooks, synthetic events, memo wrappers, SSR, hydration, and build-time style extraction.
+
+See [the DOM renderer guide](../../skills/dom/dom.md) for the API and constraints. This package currently targets browser DOM; native rendering and build-time expressive-jsx extraction are not included.
+
+## License
+
+MIT

package/dist/chunk-vnode-DA7cLTKP.js

@@ -0,0 +1,33 @@
+//#region src/vnode.ts
+const VNODE = Symbol("@expressive/dom.vnode");
+const PORTAL = Symbol("@expressive/dom.portal");
+function vnode(type, props, key) {
+	return {
+		[VNODE]: true,
+		type,
+		props: props || {},
+		key
+	};
+}
+function isVNode(value) {
+	return !!value && typeof value == "object" && value[VNODE] === true;
+}
+function childrenOf(value) {
+	const output = [];
+	function add(child) {
+		if (Array.isArray(child)) child.forEach(add);
+		else if (child !== null && child !== void 0 && typeof child != "boolean") output.push(child);
+	}
+	add(value);
+	return output;
+}
+function createPortal(children, container, key) {
+	return vnode(PORTAL, {
+		children,
+		container
+	}, key);
+}
+
+//#endregion
+export { vnode as a, isVNode as i, childrenOf as n, createPortal as r, PORTAL as t };
+//# sourceMappingURL=chunk-vnode-DA7cLTKP.js.map

package/dist/chunk-vnode-DA7cLTKP.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-vnode-DA7cLTKP.js","names":[],"sources":["../src/vnode.ts"],"sourcesContent":["import type { has, map } from '@expressive/mvc';\n\nconst VNODE = Symbol('@expressive/dom.vnode');\nconst PORTAL = Symbol('@expressive/dom.portal');\n\ntype Key = string | number | null | undefined;\ntype FunctionComponent<P = any> = (props: P) => Node;\ninterface ComponentInstance {\n  readonly props: any;\n  render(props?: any): Node;\n}\ntype ComponentType<P = any> = FunctionComponent<P> | (new (props: P) => ComponentInstance);\n\ntype Node =\n  | VNode\n  | ComponentInstance\n  | string\n  | number\n  | bigint\n  | boolean\n  | null\n  | undefined\n  | readonly Node[]\n  | has.List<Node>\n  | has.Pool<Node, any, any>\n  | map.Managed<unknown, Node>;\n\ninterface VNode<P = any> {\n  readonly [VNODE]: true;\n  readonly type: string | symbol | ComponentType<P>;\n  readonly props: P & { children?: Node };\n  readonly key?: Key;\n}\n\nfunction vnode<P>(type: VNode<P>['type'], props: P, key?: unknown): VNode<P> {\n  return {\n    [VNODE]: true,\n    type,\n    props: (props || {}) as VNode<P>['props'],\n    key: key as Key\n  };\n}\n\nfunction isVNode(value: unknown): value is VNode {\n  return !!value && typeof value == 'object' && (value as VNode)[VNODE] === true;\n}\n\nfunction childrenOf(value: unknown): Node[] {\n  const output: Node[] = [];\n\n  function add(child: unknown) {\n    if (Array.isArray(child)) child.forEach(add);\n    else if (child !== null && child !== undefined && typeof child != 'boolean')\n      output.push(child as Node);\n  }\n\n  add(value);\n  return output;\n}\n\nfunction createPortal(children: Node, container: Element | DocumentFragment, key?: Key): VNode {\n  return vnode(PORTAL, { children, container }, key);\n}\n\nexport {\n  VNODE,\n  PORTAL,\n  childrenOf,\n  createPortal,\n  isVNode,\n  vnode\n};\n\nexport type { ComponentInstance, ComponentType, FunctionComponent, Key, Node, VNode };\n"],"mappings":";AAEA,MAAM,QAAQ,OAAO,wBAAwB;AAC7C,MAAM,SAAS,OAAO,yBAAyB;AA+B/C,SAAS,MAAS,MAAwB,OAAU,KAAyB;AAC3E,QAAO;GACJ,QAAQ;EACT;EACA,OAAQ,SAAS,EAAE;EACd;EACN;;AAGH,SAAS,QAAQ,OAAgC;AAC/C,QAAO,CAAC,CAAC,SAAS,OAAO,SAAS,YAAa,MAAgB,WAAW;;AAG5E,SAAS,WAAW,OAAwB;CAC1C,MAAM,SAAiB,EAAE;CAEzB,SAAS,IAAI,OAAgB;AAC3B,MAAI,MAAM,QAAQ,MAAM,CAAE,OAAM,QAAQ,IAAI;WACnC,UAAU,QAAQ,UAAU,UAAa,OAAO,SAAS,UAChE,QAAO,KAAK,MAAc;;AAG9B,KAAI,MAAM;AACV,QAAO;;AAGT,SAAS,aAAa,UAAgB,WAAuC,KAAkB;AAC7F,QAAO,MAAM,QAAQ;EAAE;EAAU;EAAW,EAAE,IAAI"}

package/dist/chunk-vnode-DHwzzX6t.d.ts

@@ -0,0 +1,25 @@
+import { has, map } from "@expressive/mvc";
+
+//#region src/vnode.d.ts
+declare const VNODE: unique symbol;
+type Key = string | number | null | undefined;
+type FunctionComponent<P = any> = (props: P) => Node;
+interface ComponentInstance {
+  readonly props: any;
+  render(props?: any): Node;
+}
+type ComponentType<P = any> = FunctionComponent<P> | (new (props: P) => ComponentInstance);
+type Node = VNode | ComponentInstance | string | number | bigint | boolean | null | undefined | readonly Node[] | has.List<Node> | has.Pool<Node, any, any> | map.Managed<unknown, Node>;
+interface VNode<P = any> {
+  readonly [VNODE]: true;
+  readonly type: string | symbol | ComponentType<P>;
+  readonly props: P & {
+    children?: Node;
+  };
+  readonly key?: Key;
+}
+declare function vnode<P>(type: VNode<P>['type'], props: P, key?: unknown): VNode<P>;
+declare function createPortal(children: Node, container: Element | DocumentFragment, key?: Key): VNode;
+//#endregion
+export { createPortal as a, VNode as i, FunctionComponent as n, vnode as o, Node as r, ComponentType as t };
+//# sourceMappingURL=chunk-vnode-DHwzzX6t.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { a as createPortal, n as FunctionComponent, r as Node, t as ComponentType } from "./chunk-vnode-DHwzzX6t.js";
+import { Component, Context, State } from "@expressive/mvc";
+
+//#region src/adapter.d.ts
+interface UseState extends State {
+  use?(...props: any[]): Promise<void> | void;
+  mount?(): (() => void) | void;
+}
+type NoVoid<T> = T extends undefined | void ? null : T;
+declare module '@expressive/mvc' {
+  interface UseState extends State {
+    use?(...props: any[]): Promise<void> | void;
+    mount?(): (() => void) | void;
+  }
+  namespace State {
+    type ForceRefresh = {
+      (): void;
+      <T = void>(waitFor: Promise<T>): Promise<T>;
+      <T = void>(invoke: () => Promise<T>): Promise<T>;
+    };
+    type GetFactory<T extends State, R> = (this: T, current: T, refresh: ForceRefresh) => R;
+    type UseArgs<T extends State> = T extends {
+      use(...props: infer P): any;
+    } ? P : State.Args<T>;
+    function get<T extends State>(this: State.Extends<T>): T;
+    function get<T extends State>(this: State.Extends<T>, required: false): T | undefined;
+    function get<T extends State>(this: State.Extends<T>, required: true): Required<T>;
+    function get<T extends State, R>(this: State.Extends<T>, factory: GetFactory<T, R>): NoVoid<R>;
+    function use<T extends UseState>(this: State.Type<T>, ...args: UseArgs<T>): T;
+  }
+  namespace Component {
+    const use: never;
+  }
+  interface Component {
+    mount?(): (() => void) | void;
+  }
+}
+//#endregion
+//#region src/context.d.ts
+declare namespace Consumer {
+  interface Props<T extends State> {
+    for: State.Extends<T>;
+    children: (value: T) => Node;
+  }
+}
+declare function Consumer<T extends State>(props: Consumer.Props<T>): Node;
+declare namespace Provider {
+  type ForEach<T extends State> = (state: T) => void;
+  interface SharedProps {
+    children?: Node;
+    fallback?: Node;
+    name?: string;
+  }
+  type Props<T extends State = State> = SharedProps & {
+    for?: Context.Accept<T>;
+    is?: ForEach<T>;
+  } & Record<string, unknown>;
+}
+declare function Provider<T extends State>(_props: Provider.Props<T>): Component.Node;
+//#endregion
+//#region src/lazy.d.ts
+type Module<P> = {
+  default: ComponentType<P>;
+} | ComponentType<P>;
+declare function lazy<P>(load: () => Promise<Module<P>>): FunctionComponent<P>;
+//#endregion
+//#region src/stylesheet.d.ts
+type Member = Extract<keyof CSSStyleDeclaration, string>;
+type Settable = { [K in Member]-?: CSSStyleDeclaration[K] extends Function ? never : K }[Member];
+type Key = style.Property | keyof macro.Registry | `--${string}` | `_${string}`;
+type Argument<K extends keyof macro.Registry> = macro.Registry[K] extends ((value: infer A, ...rest: any[]) => any) ? A : never;
+declare namespace macro {
+  /**
+   * Macros visible to a style map. A pack augments this interface to declare
+   * what it registers with `macro()`.
+   */
+  interface Registry {}
+  /** Maps one argument to style, or to keys which resolve further. */
+  type Fn = (value: any, key: string) => unknown;
+  /**
+   * Body of a `macro()` map. A name declared in {@link Registry} must match its
+   * declaration; an undeclared one is accepted, and becomes checkable at call
+   * sites once a module augments `Registry` with it.
+   */
+  type Map = Partial<Registry> & { [K in `_${string}`]?: style.Map } & Record<string, Fn | style.Map | undefined>;
+}
+declare namespace style {
+  /** CSS property names, minus the CSSOM's own members. */
+  type Property = Exclude<Settable, 'length' | 'parentRule' | 'cssText'>;
+  /** What a declaration or macro argument may be; never a plain object. */
+  type Value = string | number | boolean | null | undefined | readonly Value[];
+  /**
+   * Body of a `style()` map. Bare keys are declarations or macro calls,
+   * `_name` opens a rule or descendant scope, and `$name` is reserved.
+   */
+  type Map = { [K in Key]?: K extends `_${string}` ? Map : K extends keyof macro.Registry ? Argument<K> : Value };
+}
+declare function style<T extends object>(type: T, rules: style.Map): T;
+declare function macro(rules: macro.Map): macro.Map;
+//#endregion
+//#region src/css.d.ts
+/**
+ * Web macro pack. Register with `macro(css)` to opt into pixel units for
+ * numbers and the axis shorthands CSS itself does not provide.
+ */
+declare const css: {
+  '*': (value: unknown, key: string) => {
+    [x: string]: unknown;
+  };
+  mx: (value: style.Value) => {
+    marginLeft: style.Value;
+    marginRight: style.Value;
+  };
+  my: (value: style.Value) => {
+    marginTop: style.Value;
+    marginBottom: style.Value;
+  };
+  px: (value: style.Value) => {
+    paddingLeft: style.Value;
+    paddingRight: style.Value;
+  };
+  py: (value: style.Value) => {
+    paddingTop: style.Value;
+    paddingBottom: style.Value;
+  };
+  size: (value: style.Value) => {
+    width: any;
+    height: any;
+  };
+};
+declare module './stylesheet' {
+  namespace macro {
+    interface Registry {
+      mx(value: style.Value): style.Map;
+      my(value: style.Value): style.Map;
+      px(value: style.Value): style.Map;
+      py(value: style.Value): style.Map;
+      size(value: style.Value): style.Map;
+    }
+  }
+}
+//#endregion
+//#region src/render.d.ts
+type Container = Element | DocumentFragment;
+declare function render(node: Node, container: Container): () => void;
+//#endregion
+export { Consumer, Provider, createPortal, css, lazy, macro, render, style };
+//# sourceMappingURL=index.d.ts.map