@ccheever/exact-renderer 0.1.0

package/src/components.ts

@@ -0,0 +1,214 @@
+/**
+ * Exact Primitive Components
+ *
+ * This module exports the primitive components for building Exact UIs.
+ * Components are organized into two categories:
+ *
+ * 1. Web-style tags (lowercase): div, span, text, img, input, button
+ *    - Use CSS flexbox defaults (flexDirection: 'row')
+ *    - Use web-style props (src, alt, objectFit)
+ *
+ * 2. React Native-style components (PascalCase): View, Text, Image, ScrollView, Pressable
+ *    - Use RN defaults (flexDirection: 'column')
+ *    - Use RN-style props (source, resizeMode)
+ *
+ * Both styles render to the same underlying views. Choose based on your
+ * preferred API style and which defaults make sense for your UI.
+ *
+ * @example Web-style
+ * ```tsx
+ * <div style={{ flex: 1, backgroundColor: '#fff' }}>
+ *   <text style={{ fontSize: 16 }}>Hello</text>
+ *   <img src="https://example.com/image.png" style={{ width: 100, height: 100 }} />
+ * </div>
+ * ```
+ *
+ * @example React Native-style
+ * ```tsx
+ * <View style={{ flex: 1, backgroundColor: '#fff' }}>
+ *   <Text style={{ fontSize: 16 }}>Hello</Text>
+ *   <Image source={{ uri: 'https://example.com/image.png' }} style={{ width: 100, height: 100 }} />
+ * </View>
+ * ```
+ */
+
+import { createElement } from 'react';
+
+import type {
+  ContainerProps,
+  TextElementProps,
+  ImageElementProps,
+  PressableElementProps,
+  TextInputProps,
+  ToggleProps,
+} from './types.js';
+import {
+  button as platformButton,
+  div as platformDiv,
+  img as platformImg,
+  input as platformInput,
+  span as platformSpan,
+  text as platformText,
+  View as platformView,
+} from './web-primitives.js';
+
+// =============================================================================
+// Web-Style Tags
+// =============================================================================
+
+/**
+ * Generic container element.
+ *
+ * Default flex direction: 'row' (CSS default)
+ *
+ * @example
+ * ```tsx
+ * <div style={{ flex: 1, flexDirection: 'column' }}>
+ *   <div style={{ height: 100, backgroundColor: '#f00' }} />
+ *   <div style={{ height: 100, backgroundColor: '#0f0' }} />
+ * </div>
+ * ```
+ */
+/**
+ * Lowercase `div` now uses the same platform-aware bridge as the other
+ * primitives. On React DOM it renders a standard `<div>` with row defaults;
+ * on the custom reconciler path it still emits the raw `div` tag.
+ */
+export const div = platformDiv;
+
+/**
+ * Inline container element.
+ *
+ * Alias for div. Default flex direction: 'row' (CSS default)
+ *
+ * @example
+ * ```tsx
+ * <span style={{ padding: 8, backgroundColor: '#eee' }}>
+ *   <text>Hello</text>
+ * </span>
+ * ```
+ */
+/**
+ * Lowercase `span` follows the same bridge pattern as `div`, but preserves
+ * inline semantics on the React DOM path.
+ */
+export const span = platformSpan;
+
+/**
+ * Text content element.
+ *
+ * Use this to display text. Text content should be placed as children.
+ *
+ * @example
+ * ```tsx
+ * <text style={{ fontSize: 16, color: '#333' }}>
+ *   Hello, world!
+ * </text>
+ * ```
+ */
+export const text = platformText;
+
+/**
+ * Image element (web-style).
+ *
+ * Uses web-style props: src, alt, objectFit.
+ *
+ * @example
+ * ```tsx
+ * <img
+ *   src="https://example.com/image.png"
+ *   alt="Description"
+ *   style={{ width: 200, height: 200 }}
+ *   objectFit="cover"
+ * />
+ * ```
+ */
+/**
+ * Lowercase `img` is now platform-aware too. This keeps Facet's web-style
+ * image usage working on React DOM without giving up the custom-reconciler tag.
+ */
+export const img = platformImg;
+
+/**
+ * Text input element (web-style).
+ *
+ * @example
+ * ```tsx
+ * <input
+ *   style={{ height: 40, borderWidth: 1, borderColor: '#ccc' }}
+ *   placeholder="Enter text..."
+ *   value={text}
+ *   onChangeText={setText}
+ * />
+ * ```
+ */
+/**
+ * Lowercase `input` now maps to the web text-input wrapper on React DOM so
+ * `onChangeText`, `multiline`, and the rest of Exact's input contract still
+ * work when apps render outside the custom reconciler.
+ */
+export const input = platformInput;
+
+/**
+ * Button element (pressable).
+ *
+ * A pressable container that responds to touch events.
+ * Default flex direction: 'row' (CSS default)
+ *
+ * @example
+ * ```tsx
+ * <button
+ *   style={{ padding: 12, backgroundColor: '#007AFF', borderRadius: 8 }}
+ *   onPress={() => console.log('Pressed!')}
+ * >
+ *   <text style={{ color: '#fff' }}>Click me</text>
+ * </button>
+ * ```
+ */
+export const button = platformButton;
+
+/**
+ * Toggle/Switch element (web-style).
+ *
+ * A native iOS toggle with optional liquid glass effect.
+ *
+ * @example
+ * ```tsx
+ * <toggle
+ *   value={isOn}
+ *   onValueChange={setIsOn}
+ *   glassEffect
+ *   tintColor="#34d399"
+ * />
+ * ```
+ */
+export const toggle = 'toggle' as unknown as React.FC<ToggleProps>;
+
+// =============================================================================
+// React Native-Style Components
+//
+// These are platform-aware: on web they render standard HTML elements with
+// React Native-like defaults (flex column, onPress → onClick, etc.); on
+// native they emit string tags for the Exact custom reconciler.
+// =============================================================================
+
+export {
+  View,
+  Text,
+  Image,
+  Svg,
+  List,
+  ScrollView,
+  TextInput,
+  Pressable,
+  Toggle,
+  Switch,
+} from './web-primitives.js';
+
+export const SelectionGroup: React.FC<ContainerProps> = function SelectionGroup(props) {
+  return createElement(platformView, {
+    ...props,
+    selectable: props.selectable ?? 'contain',
+    __exactComponentName: props.__exactComponentName ?? 'SelectionGroup',
+  });
+};

package/src/css-variable-context.ts

@@ -0,0 +1,83 @@
+/**
+ * CSS Custom Property context for native className resolution (RFC 0024 Phase 3).
+ *
+ * On native, CSS custom properties set via `style={{ '--brand': '#ff6b35' }}`
+ * are extracted from the style prop and provided to descendants via React context.
+ * The className resolver reads this context to resolve `var()` references at
+ * runtime (Layer 2).
+ *
+ * On web, `--`-prefixed keys are forwarded to the DOM `style` attribute and the
+ * browser handles `var()` resolution natively. This module is not used on web.
+ */
+import { createContext, createElement, useContext, useMemo, type ReactNode } from 'react';
+
+export type CSSVariableMap = Readonly<Record<string, string>>;
+
+const EMPTY_MAP: CSSVariableMap = Object.freeze({});
+
+const CSSVariableContext = createContext<CSSVariableMap>(EMPTY_MAP);
+
+/**
+ * Read the inherited CSS variable map from context. Used by the className
+ * resolver to resolve runtime `var()` references.
+ */
+export function useCSSVariables(): CSSVariableMap {
+  return useContext(CSSVariableContext);
+}
+
+/**
+ * Provide scoped CSS custom properties to descendants.
+ *
+ * When `declaredVars` is empty or undefined, the provider is a passthrough
+ * (returns the inherited context unchanged — zero cost via useMemo identity).
+ * This allows unconditional rendering without unmount/remount concerns.
+ */
+export function CSSVariableProvider({
+  declaredVars,
+  children,
+}: {
+  declaredVars: CSSVariableMap | undefined;
+  children: ReactNode;
+}): ReactNode {
+  const inherited = useContext(CSSVariableContext);
+  const merged = useMemo(() => {
+    if (!declaredVars || Object.keys(declaredVars).length === 0) {
+      return inherited;
+    }
+    return { ...inherited, ...declaredVars };
+  }, [inherited, declaredVars]);
+
+  return createElement(CSSVariableContext.Provider, { value: merged }, children);
+}
+
+/**
+ * Extract `--`-prefixed keys from a style object, returning the extracted
+ * variables and the remaining style without them.
+ */
+export function extractCSSVariables(
+  style: Record<string, unknown> | undefined,
+): { cssVars: CSSVariableMap | undefined; cleanStyle: Record<string, unknown> | undefined } {
+  if (!style) {
+    return { cssVars: undefined, cleanStyle: undefined };
+  }
+
+  let cssVars: Record<string, string> | undefined;
+  let cleanStyle: Record<string, unknown> | undefined;
+
+  for (const key of Object.keys(style)) {
+    if (key.startsWith('--')) {
+      if (!cssVars) cssVars = {};
+      cssVars[key] = String(style[key]);
+    } else {
+      if (!cleanStyle) cleanStyle = {};
+      cleanStyle[key] = style[key];
+    }
+  }
+
+  // If no -- keys found, return original style object to preserve identity
+  if (!cssVars) {
+    return { cssVars: undefined, cleanStyle: style };
+  }
+
+  return { cssVars, cleanStyle };
+}

package/src/dom-hydration.ts

@@ -0,0 +1,160 @@
+// @system @ref LLP 0201 W3 / LLP 0210 — Contract web host hydration adoption.
+
+import type {
+  DomHydrationAdopter,
+  DomHydrationAdopterFactoryOptions,
+  DomHydrationManifestLike,
+  DomMirrorHostChild,
+} from './dom-mirror.js';
+import type { ElementNode, TextNode } from './nodes/node.js';
+import { NodeKind } from './nodes/node.js';
+
+type HydrationNode = NonNullable<DomHydrationManifestLike['nodes']>[number];
+
+function buildHydrationAnchorMap(
+  hydrate: DomHydrationAdopterFactoryOptions['hydrate'],
+): Map<string, HydrationNode> {
+  const out = new Map<string, HydrationNode>();
+  for (const node of hydrate.manifest.nodes ?? []) {
+    if (typeof node.nodeId === 'string' && node.nodeId.length > 0) {
+      out.set(node.nodeId, node);
+    }
+  }
+  return out;
+}
+
+function resolveDomPath(root: ParentNode, path: readonly number[]): Node | null {
+  let current: ParentNode | Node = root;
+  for (const index of path) {
+    if (!Number.isInteger(index) || index < 0 || !('childNodes' in current)) {
+      return null;
+    }
+    const next = current.childNodes.item(index);
+    if (!next) {
+      return null;
+    }
+    current = next;
+  }
+  return current as Node;
+}
+
+function hydrationIdFor(child: DomMirrorHostChild): string | undefined {
+  if (child.kind === NodeKind.Text) {
+    return (child as TextNode & { __exactHydrationId?: string }).__exactHydrationId;
+  }
+  const value = ((child as ElementNode).originalProps ?? {})['data-exact-hydration-id'];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function createDomHydrationAdopter(
+  options: DomHydrationAdopterFactoryOptions,
+): DomHydrationAdopter | null {
+  const hydrationAnchors = buildHydrationAnchorMap(options.hydrate);
+  const hydrationResults = new Map<number, {
+    adoptedNodes: number;
+    recreatedNodes: number;
+    mismatches: string[];
+    rootId: number;
+  }>();
+  const reportedHydrationRoots = new Set<number>();
+
+  function resultFor(rootId: number) {
+    let result = hydrationResults.get(rootId);
+    if (!result) {
+      result = { rootId, adoptedNodes: 0, recreatedNodes: 0, mismatches: [] };
+      hydrationResults.set(rootId, result);
+    }
+    return result;
+  }
+
+  return {
+    adoptRootContainer(rootId, base, rootAttribute) {
+      if (options.hydrate.rootId !== rootId) {
+        return null;
+      }
+      if (base.getAttribute(rootAttribute) === String(rootId)) {
+        options.markMirrored(base);
+        return base;
+      }
+      const existing = base.querySelector(`[${rootAttribute}="${rootId}"]`);
+      if (existing && existing.nodeType === 1) {
+        options.markMirrored(existing);
+        return existing as HTMLElement;
+      }
+      return null;
+    },
+
+    adoptDom(child, rootId, rootContainer, desiredTag) {
+      if (options.hydrate.rootId !== rootId) {
+        return null;
+      }
+      const hydrationId = hydrationIdFor(child);
+      if (!hydrationId) {
+        return null;
+      }
+      const anchor = hydrationAnchors.get(hydrationId);
+      if (!anchor?.domPath) {
+        resultFor(rootId).mismatches.push(`${hydrationId}: missing hydration anchor`);
+        resultFor(rootId).recreatedNodes += 1;
+        return null;
+      }
+      const candidate = resolveDomPath(rootContainer, anchor.domPath);
+      if (!candidate) {
+        resultFor(rootId).mismatches.push(
+          `${hydrationId}: domPath ${anchor.domPath.join('.')} did not resolve`,
+        );
+        resultFor(rootId).recreatedNodes += 1;
+        return null;
+      }
+      if (child.kind === NodeKind.Text) {
+        if (candidate.nodeType !== 3) {
+          resultFor(rootId).mismatches.push(`${hydrationId}: expected text node`);
+          resultFor(rootId).recreatedNodes += 1;
+          return null;
+        }
+        if (anchor.textGuard !== undefined && candidate.nodeValue !== anchor.textGuard) {
+          resultFor(rootId).mismatches.push(`${hydrationId}: textGuard mismatch`);
+          resultFor(rootId).recreatedNodes += 1;
+          return null;
+        }
+        options.markMirrored(candidate);
+        resultFor(rootId).adoptedNodes += 1;
+        return candidate;
+      }
+      if (candidate.nodeType !== 1) {
+        resultFor(rootId).mismatches.push(`${hydrationId}: expected element node`);
+        resultFor(rootId).recreatedNodes += 1;
+        return null;
+      }
+      const elementCandidate = candidate as HTMLElement;
+      if (desiredTag && elementCandidate.localName !== desiredTag) {
+        resultFor(rootId).mismatches.push(
+          `${hydrationId}: expected <${desiredTag}>, got <${elementCandidate.localName}>`,
+        );
+        resultFor(rootId).recreatedNodes += 1;
+        return null;
+      }
+      const marker = elementCandidate.getAttribute('data-exact-hydration-id');
+      if (marker !== hydrationId) {
+        resultFor(rootId).mismatches.push(`${hydrationId}: marker mismatch`);
+        resultFor(rootId).recreatedNodes += 1;
+        return null;
+      }
+      options.markMirrored(elementCandidate);
+      resultFor(rootId).adoptedNodes += 1;
+      return elementCandidate;
+    },
+
+    report(rootId) {
+      if (options.hydrate.rootId !== rootId || reportedHydrationRoots.has(rootId)) {
+        return;
+      }
+      reportedHydrationRoots.add(rootId);
+      options.hydrate.onResult?.(resultFor(rootId));
+    },
+  };
+}
+
+export function installDomHydrationAdopterFactory(): void {
+  globalThis.__exactDomHydrationAdopterFactory = createDomHydrationAdopter;
+}