@ccheever/exact-renderer 0.1.0

package/src/group-context.ts

@@ -0,0 +1,69 @@
+/**
+ * Group state context for Tailwind group-* modifiers (RFC 0024 Phase 4).
+ *
+ * A view with `className="group"` provides its interaction state via context.
+ * Descendant views with `group-hover:*` classes consume this context to
+ * conditionally apply styles.
+ *
+ * Named groups (`group/sidebar`) get separate context entries so multiple
+ * nested groups don't conflict.
+ */
+import { createContext, createElement, useContext, useMemo, type ReactNode } from 'react';
+import type { InteractionState } from './classname-contract.js';
+
+/**
+ * Map from group name (null = unnamed default group) to its interaction state.
+ */
+type GroupStateMap = ReadonlyMap<string | null, InteractionState>;
+
+const EMPTY_MAP: GroupStateMap = new Map();
+
+const GroupStateContext = createContext<GroupStateMap>(EMPTY_MAP);
+
+/**
+ * Read the current group states from context. Used by the className resolver
+ * to evaluate `group-hover:*`, `group-focus:*`, `group-active:*` conditions.
+ */
+export function useGroupStates(): GroupStateMap {
+  return useContext(GroupStateContext);
+}
+
+/**
+ * Provide a group's interaction state to descendants.
+ *
+ * @param name - The group name (null for unnamed `group`, string for `group/name`)
+ * @param state - The group view's current interaction state
+ */
+export function GroupStateProvider({
+  name,
+  state,
+  children,
+}: {
+  name: string | null;
+  state: InteractionState;
+  children: ReactNode;
+}): ReactNode {
+  const inherited = useContext(GroupStateContext);
+  const merged = useMemo(() => {
+    const next = new Map(inherited);
+    next.set(name, state);
+    return next;
+  }, [inherited, name, state]);
+
+  return createElement(GroupStateContext.Provider, { value: merged }, children);
+}
+
+/**
+ * Check if a className string includes "group" or "group/{name}".
+ * Returns the group name (null for unnamed) or undefined if not a group.
+ */
+const WS_RE = /\s+/;
+
+export function extractGroupName(className: string): string | null | undefined {
+  const tokens = className.split(WS_RE);
+  for (const token of tokens) {
+    if (token === 'group') return null;
+    if (token.startsWith('group/')) return token.slice(6);
+  }
+  return undefined;
+}

package/src/host-config.ts

@@ -0,0 +1,431 @@
+// @system @ref LLP 0007 — React reconciler host integration
+/**
+ * React Reconciler Host Config
+ *
+ * This module implements the HostConfig interface required by react-reconciler.
+ * It bridges React's component tree to our host node model and protocol encoder.
+ *
+ * Design Principles:
+ * - Mutation-based rendering (supportsMutation = true)
+ * - No persistence or hydration
+ * - Clear separation between tree building and commit phases
+ * - Batched mutations for efficient updates
+ *
+ * Key Concepts:
+ * - Instance: Our ElementNode representing a host element
+ * - TextInstance: Our TextNode representing raw text
+ * - Container: RootNode (the root container with ID 0)
+ * - HostContext: Tag defaults for child elements
+ */
+
+// Note: We use 'any' for the HostConfig type because the exact type signature
+// varies between react-reconciler versions and is complex to maintain.
+// The implementation is correct; this is just for type checking convenience.
+
+import type { FullStyle } from './types.js';
+
+// Import shared infrastructure from host-ops
+import {
+  // Types
+  type ElementNode,
+  type TextNode,
+  type RootNode,
+  type TagConfig,
+  
+  // Node operations
+  NodeKind,
+  nodeAppendChild,
+  nodeInsertBefore,
+  nodeRemoveChild,
+  nodeClearChildren,
+  
+  // Instance creation
+  createInstance,
+  createTextInstance,
+  
+  // Tree operations
+  appendChild as hostAppendChild,
+  insertBefore as hostInsertBefore,
+  removeChild as hostRemoveChild,
+  clearContainer as hostClearContainer,
+  commitBatch,
+  
+  // Updates
+  updateInstanceProps,
+  updateTextContent,
+  finalizeInstance,
+  
+  // Tag config
+  getTagConfig,
+  defaultTagConfig,
+
+  // Event handling
+  processEventProps,
+  cleanupNodeHandlers,
+  
+  // Encoder access
+  getEncoder,
+  _getEncoder,
+  
+  // Handler registry (re-export for reconciler.ts)
+  getHandler,
+  _clearHandlers,
+  
+  // Protocol encoding
+  encodeChildren,
+  encodeEvents,
+  encodeDestroy,
+} from './host-ops.js';
+
+// Re-export for reconciler.ts
+export { getHandler, _getEncoder, _clearHandlers };
+
+// =============================================================================
+// Development Mode Flag
+// =============================================================================
+
+/**
+ * Development mode flag - gate verbose logging.
+ * In production builds, bundlers should replace this with false.
+ */
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+function hasOnlyTextChildren(children: unknown): boolean {
+  if (children === null || children === undefined) {
+    return true;
+  }
+
+  switch (typeof children) {
+    case 'string':
+    case 'number':
+      return true;
+    case 'boolean':
+      return true;
+    default:
+      break;
+  }
+
+  if (Array.isArray(children)) {
+    return children.every(hasOnlyTextChildren);
+  }
+
+  return false;
+}
+
+
+// =============================================================================
+// Type Aliases for React Reconciler
+// =============================================================================
+
+type Type = string;
+type Props = Record<string, unknown>;
+type Instance = ElementNode;
+type TextInstance = TextNode;
+type Container = RootNode;
+type ChildSet = never; // Not used in mutation mode
+type HostContext = TagConfig;
+type SuspenseInstance = never;
+type HydratableInstance = never;
+type PublicInstance = ElementNode | TextNode;
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+type NoTimeout = -1;
+
+// Get the shared encoder
+const encoder = getEncoder();
+
+// =============================================================================
+// Event Priority Constants (React 19)
+// =============================================================================
+
+const DiscreteEventPriority = 2;
+const ContinuousEventPriority = 8;
+const DefaultEventPriority = 32;
+const IdleEventPriority = 268435456;
+
+let currentUpdatePriority = DefaultEventPriority;
+
+// =============================================================================
+// Host Config Implementation
+// =============================================================================
+
+/**
+ * The host config for the Exact renderer.
+ * We use 'any' here because HostConfig generic signature varies between
+ * react-reconciler versions. The implementation is type-safe internally.
+ */
+export const hostConfig: any = {
+  // ===========================================================================
+  // Feature Flags
+  // ===========================================================================
+
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+  isPrimaryRenderer: true,
+  noTimeout: -1 as const,
+  warnsIfNotActing: false,
+
+  // ===========================================================================
+  // Renderer Info
+  // ===========================================================================
+
+  rendererVersion: '19.0.0',
+  rendererPackageName: 'exact-renderer',
+  extraDevToolsConfig: null,
+
+  // ===========================================================================
+  // Priority Management (React 19)
+  // ===========================================================================
+
+  setCurrentUpdatePriority(priority: number): void {
+    currentUpdatePriority = priority;
+  },
+
+  getCurrentUpdatePriority(): number {
+    return currentUpdatePriority;
+  },
+
+  resolveUpdatePriority(): number {
+    return currentUpdatePriority || DefaultEventPriority;
+  },
+
+  resolveEventTimeStamp(): number {
+    return performance.now();
+  },
+
+  resolveEventType(): null {
+    return null;
+  },
+
+  trackSchedulerEvent(): void {},
+
+  // ===========================================================================
+  // Suspense Stubs (React 19)
+  // ===========================================================================
+
+  maySuspendCommit(): boolean {
+    return false;
+  },
+
+  maySuspendCommitOnUpdate(): boolean {
+    return false;
+  },
+
+  maySuspendCommitInSyncRender(): boolean {
+    return false;
+  },
+
+  preloadInstance(): boolean {
+    return true;
+  },
+
+  startSuspendingCommit(): void {},
+
+  suspendInstance(): void {},
+
+  waitForCommitToBeReady(): null {
+    return null;
+  },
+
+  shouldAttemptEagerTransition(): boolean {
+    return false;
+  },
+
+  // ===========================================================================
+  // Context
+  // ===========================================================================
+
+  getRootHostContext(_rootContainer: Container): HostContext {
+    // Root context uses web defaults
+    return defaultTagConfig;
+  },
+
+  getChildHostContext(parentContext: HostContext, type: Type, _rootContainer: Container): HostContext {
+    // Get the config for this child type
+    const config = getTagConfig(type);
+    if (config) {
+      return config;
+    }
+
+    // Unknown type - warn in dev and use default
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`[Exact] Unknown element type: ${type}. Treating as view.`);
+    }
+    return defaultTagConfig;
+  },
+
+  // ===========================================================================
+  // Instance Creation
+  // ===========================================================================
+
+  createInstance(
+    type: Type,
+    props: Props,
+    _rootContainer: Container,
+    hostContext: HostContext,
+    _internalHandle: unknown
+  ): Instance {
+    // Use shared createInstance from host-ops
+    return createInstance(type, props);
+  },
+
+  createTextInstance(
+    text: string,
+    _rootContainer: Container,
+    _hostContext: HostContext,
+    _internalHandle: unknown
+  ): TextInstance {
+    // Use shared createTextInstance from host-ops
+    return createTextInstance(text);
+  },
+
+  // ===========================================================================
+  // Initial Children (during createInstance tree building)
+  // ===========================================================================
+
+  appendInitialChild(parent: Instance, child: Instance | TextInstance): void {
+    // During initial mounting, just build the tree structure (no encoding yet)
+    nodeAppendChild(parent, child);
+  },
+
+  finalizeInitialChildren(
+    instance: Instance,
+    _type: Type,
+    _props: Props,
+    _rootContainer: Container,
+    _hostContext: HostContext
+  ): boolean {
+    // Use shared finalizeInstance from host-ops
+    finalizeInstance(instance);
+    // Return false - no commit-time work needed
+    return false;
+  },
+
+  // ===========================================================================
+  // Mutation Methods
+  // ===========================================================================
+
+  appendChild(parent: Instance, child: Instance | TextInstance): void {
+    hostAppendChild(parent, child);
+  },
+
+  appendChildToContainer(container: Container, child: Instance | TextInstance): void {
+    hostAppendChild(container, child);
+  },
+
+  insertBefore(
+    parent: Instance,
+    child: Instance | TextInstance,
+    beforeChild: Instance | TextInstance
+  ): void {
+    hostInsertBefore(parent, child, beforeChild);
+  },
+
+  insertInContainerBefore(
+    container: Container,
+    child: Instance | TextInstance,
+    beforeChild: Instance | TextInstance
+  ): void {
+    hostInsertBefore(container, child, beforeChild);
+  },
+
+  removeChild(parent: Instance, child: Instance | TextInstance): void {
+    hostRemoveChild(parent, child);
+  },
+
+  removeChildFromContainer(container: Container, child: Instance | TextInstance): void {
+    hostRemoveChild(container, child);
+  },
+
+  clearContainer(container: Container): void {
+    hostClearContainer(container);
+  },
+
+  // ===========================================================================
+  // Updates
+  // ===========================================================================
+
+  // react-reconciler 0.33 removed prepareUpdate; commitUpdate is called as
+  // commitUpdate(instance, type, oldProps, newProps, fiber).
+  commitUpdate(
+    instance: Instance,
+    _type: Type,
+    oldProps: Props,
+    newProps: Props,
+    _internalHandle: unknown
+  ): void {
+    // Use shared updateInstanceProps from host-ops
+    updateInstanceProps(instance, oldProps, newProps);
+  },
+
+  commitTextUpdate(
+    instance: TextInstance,
+    oldText: string,
+    newText: string
+  ): void {
+    // Use shared updateTextContent from host-ops
+    updateTextContent(instance, newText);
+  },
+
+  // ===========================================================================
+  // Text Content
+  // ===========================================================================
+
+  shouldSetTextContent(type: Type, props: Props): boolean {
+    const config = getTagConfig(type) ?? defaultTagConfig;
+    return config.isTextContainer && hasOnlyTextChildren(props.children);
+  },
+
+  // ===========================================================================
+  // Commit Phase
+  // ===========================================================================
+
+  prepareForCommit(_containerInfo: Container): Record<string, unknown> | null {
+    return null;
+  },
+
+  resetAfterCommit(container: Container): void {
+    commitBatch(container);
+  },
+
+  // ===========================================================================
+  // Public Instance
+  // ===========================================================================
+
+  getPublicInstance(instance: Instance | TextInstance): PublicInstance {
+    return instance;
+  },
+
+  // ===========================================================================
+  // Scheduling
+  // ===========================================================================
+
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+
+  getCurrentEventPriority(): number {
+    return DefaultEventPriority;
+  },
+
+  // ===========================================================================
+  // Misc Stubs
+  // ===========================================================================
+
+  getInstanceFromNode(): Instance | null {
+    return null;
+  },
+
+  beforeActiveInstanceBlur(): void {},
+
+  afterActiveInstanceBlur(): void {},
+
+  prepareScopeUpdate(): void {},
+
+  getInstanceFromScope(): Instance | null {
+    return null;
+  },
+
+  detachDeletedInstance(_instance: Instance): void {},
+
+  preparePortalMount(): void {},
+};