@ccheever/exact-renderer 0.1.0

package/src/tags/tag-map.ts

@@ -0,0 +1,289 @@
+/**
+ * Tag Mapping
+ *
+ * This module defines how user-facing tags (both web and React Native)
+ * map to canonical internal types and their default properties.
+ *
+ * Design Principles:
+ * - Web semantics are primary (flexDirection defaults to 'row')
+ * - RN tags are aliases that use RN defaults (flexDirection defaults to 'column')
+ * - All tags resolve to a small set of canonical types
+ *
+ * Canonical Types:
+ * - view: Generic container (maps to View node type)
+ * - text: Text content (maps to Text node type)
+ * - image: Image display (maps to Image node type)
+ * - svg: SVG display (maps to Svg node type)
+ * - scroll: Scrollable container (maps to ScrollView node type)
+ * - list: Host-owned virtual list container (maps to List node type)
+ * - input: Text input (maps to TextInput node type)
+ * - pressable: Touchable wrapper (RN Pressable maps to Pressable; web tags
+ *   render as View with event bindings)
+ * - nativeView: Module-backed native view, including first-party controls
+ */
+
+import type {
+  CanonicalTagType,
+  FlexDirection,
+  NativeViewSelectionGesturePolicy,
+  NativeViewSelectionTier,
+} from '../types.js';
+import { NodeType } from '@exact/core/protocol/opcodes';
+
+export interface NativeViewTagSelection {
+  readonly tier: NativeViewSelectionTier;
+  readonly gesturePolicy?: NativeViewSelectionGesturePolicy;
+}
+
+export interface NativeViewTagMetadata {
+  readonly moduleName: string;
+  readonly propKeys: readonly string[];
+  readonly selection?: NativeViewTagSelection;
+}
+
+/**
+ * Tag configuration specifying how a tag behaves.
+ */
+export interface TagConfig {
+  /** The canonical internal type */
+  readonly canonicalType: CanonicalTagType;
+
+  /** The protocol NodeType for creating views */
+  readonly nodeType: NodeType;
+
+  /** Whether this tag uses RN semantics */
+  readonly isRNStyle: boolean;
+
+  /** Default flex direction for this tag */
+  readonly defaultFlexDirection: FlexDirection;
+
+  /** Whether this tag is a text container (allows raw text children) */
+  readonly isTextContainer: boolean;
+
+  /** Whether this tag supports press events */
+  readonly supportsPressEvents: boolean;
+
+  /** Whether this tag supports change events (for toggles, inputs) */
+  readonly supportsChangeEvents?: boolean;
+
+  /** Whether this tag supports transition lifecycle events */
+  readonly supportsTransitionEvents?: boolean;
+
+  /** Native-view metadata for dynamically registered module-backed views. */
+  readonly nativeView?: NativeViewTagMetadata;
+}
+
+interface TagConfigOptions {
+  isRNStyle?: boolean;
+  supportsPressEvents?: boolean;
+  supportsChangeEvents?: boolean;
+  nativeView?: NativeViewTagMetadata;
+}
+
+function createTagConfig(
+  canonicalType: CanonicalTagType,
+  nodeType: NodeType,
+  options: TagConfigOptions = {},
+): TagConfig {
+  const isRNStyle = options.isRNStyle === true;
+  return {
+    canonicalType,
+    nodeType,
+    isRNStyle,
+    defaultFlexDirection: isRNStyle ? 'column' : 'row',
+    isTextContainer: canonicalType === 'text',
+    supportsPressEvents: options.supportsPressEvents === true,
+    ...(options.supportsChangeEvents === true ? { supportsChangeEvents: true } : {}),
+    supportsTransitionEvents: true,
+    ...(options.nativeView ? { nativeView: options.nativeView } : {}),
+  };
+}
+
+function tagEntries(
+  tags: readonly string[],
+  canonicalType: CanonicalTagType,
+  nodeType: NodeType,
+  options: TagConfigOptions = {},
+): Array<[string, TagConfig]> {
+  return tags.map((tag) => [
+    tag,
+    createTagConfig(canonicalType, nodeType, options),
+  ]);
+}
+
+const WEB_VIEW_TAGS = [
+  'div',
+  'span',
+  'section',
+  'main',
+  'article',
+  'nav',
+  'aside',
+  'header',
+  'footer',
+  'form',
+  'label',
+] as const;
+const WEB_TEXT_TAGS = ['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'text'] as const;
+const TOGGLE_NATIVE_VIEW: NativeViewTagMetadata = {
+  moduleName: 'exact.toggle',
+  propKeys: ['value', 'tintColor', 'disabled', 'glassEffect', 'accessibilityLabel'],
+  selection: {
+    tier: 'delegated',
+    gesturePolicy: 'internal',
+  },
+};
+
+/**
+ * Web tag configurations.
+ * These use CSS defaults: flexDirection = 'row'.
+ */
+const webTags: Record<string, TagConfig> = Object.fromEntries([
+  ...tagEntries(WEB_VIEW_TAGS, 'view', NodeType.View),
+  ...tagEntries(WEB_TEXT_TAGS, 'text', NodeType.Text),
+  ['img', createTagConfig('image', NodeType.Image, { supportsChangeEvents: true })],
+  ['svg', createTagConfig('svg', NodeType.Svg)],
+  ['input', createTagConfig('input', NodeType.TextInput, { supportsChangeEvents: true })],
+  ['button', createTagConfig('pressable', NodeType.View, { supportsPressEvents: true })],
+  ['a', createTagConfig('pressable', NodeType.View, { supportsPressEvents: true })],
+  ['textarea', createTagConfig('input', NodeType.TextInput, { supportsChangeEvents: true })],
+  ['toggle', createTagConfig('nativeView', NodeType.NativeView, {
+    supportsChangeEvents: true,
+    nativeView: TOGGLE_NATIVE_VIEW,
+  })],
+]);
+
+/**
+ * React Native tag configurations.
+ * These use RN defaults: flexDirection = 'column'.
+ */
+const rnTags: Record<string, TagConfig> = Object.fromEntries([
+  ['View', createTagConfig('view', NodeType.View, { isRNStyle: true })],
+  ['Text', createTagConfig('text', NodeType.Text, { isRNStyle: true })],
+  ['Image', createTagConfig('image', NodeType.Image, { isRNStyle: true, supportsChangeEvents: true })],
+  ['Svg', createTagConfig('svg', NodeType.Svg, { isRNStyle: true })],
+  ['VideoView', createTagConfig('video', NodeType.Video, { isRNStyle: true })],
+  ['ScrollView', createTagConfig('scroll', NodeType.ScrollView, { isRNStyle: true })],
+  ['List', createTagConfig('list', NodeType.List, { isRNStyle: true })],
+  ['TextInput', createTagConfig('input', NodeType.TextInput, { isRNStyle: true, supportsChangeEvents: true })],
+  ['Pressable', createTagConfig('pressable', NodeType.Pressable, { isRNStyle: true, supportsPressEvents: true })],
+  ['Toggle', createTagConfig('nativeView', NodeType.NativeView, {
+    isRNStyle: true,
+    supportsChangeEvents: true,
+    nativeView: TOGGLE_NATIVE_VIEW,
+  })],
+  ['Switch', createTagConfig('nativeView', NodeType.NativeView, {
+    isRNStyle: true,
+    supportsChangeEvents: true,
+    nativeView: TOGGLE_NATIVE_VIEW,
+  })],
+]);
+
+/**
+ * Combined tag map for all supported tags.
+ */
+const tagMap: Record<string, TagConfig> = {
+  ...webTags,
+  ...rnTags,
+};
+
+const nativeViewTags = new Map<string, TagConfig>();
+const nativeViewTagNamesByModule = new Map<string, string>();
+
+/**
+ * Get the configuration for a tag.
+ * Returns null if the tag is not recognized.
+ *
+ * @param tag - The tag name (e.g., 'div', 'View', 'text')
+ */
+export function getTagConfig(tag: string): TagConfig | null {
+  return nativeViewTags.get(tag) ?? tagMap[tag] ?? null;
+}
+
+/**
+ * Check if a tag is a valid Exact tag.
+ *
+ * @param tag - The tag name to check
+ */
+export function isValidTag(tag: string): boolean {
+  return nativeViewTags.has(tag) || tag in tagMap;
+}
+
+/**
+ * Check if a tag is a web tag.
+ *
+ * @param tag - The tag name to check
+ */
+export function isWebTag(tag: string): boolean {
+  return tag in webTags;
+}
+
+export function registerNativeViewTag(metadata: NativeViewTagMetadata): string {
+  const existingTag = nativeViewTagNamesByModule.get(metadata.moduleName);
+  if (existingTag) {
+    return existingTag;
+  }
+
+  const tag = `ExactNativeView:${metadata.moduleName}`;
+  nativeViewTagNamesByModule.set(metadata.moduleName, tag);
+  nativeViewTags.set(tag, {
+    // RFC 0073 routes native control changes back through the existing
+    // renderer event binding path, so native-view tags must opt into Change
+    // events when callers provide an `onChange` prop.
+    ...createTagConfig('nativeView', NodeType.NativeView, {
+      isRNStyle: true,
+      supportsChangeEvents: true,
+      nativeView: metadata,
+    }),
+  });
+  return tag;
+}
+
+export function _clearNativeViewTagsForTesting(): void {
+  nativeViewTags.clear();
+  nativeViewTagNamesByModule.clear();
+}
+
+/**
+ * Check if a tag is a React Native tag.
+ *
+ * @param tag - The tag name to check
+ */
+export function isRNTag(tag: string): boolean {
+  return tag in rnTags;
+}
+
+/**
+ * Get all valid web tag names.
+ */
+export function getWebTags(): string[] {
+  return Object.keys(webTags);
+}
+
+/**
+ * Get all valid RN tag names.
+ */
+export function getRNTags(): string[] {
+  return Object.keys(rnTags);
+}
+
+/**
+ * Get all valid tag names.
+ */
+export function getAllTags(): string[] {
+  return [...Object.keys(tagMap), ...nativeViewTags.keys()];
+}
+
+/**
+ * Default tag config for unknown tags (treated as View).
+ * This provides a fallback for development but should warn.
+ */
+export const defaultTagConfig: TagConfig = {
+  canonicalType: 'view',
+  nodeType: NodeType.View,
+  isRNStyle: false,
+  defaultFlexDirection: 'row',
+  isTextContainer: false,
+  supportsPressEvents: false,
+  supportsTransitionEvents: true,
+};

package/src/text/paragraph-lowering.ts

@@ -0,0 +1,310 @@
+import { createParagraphKey } from '@exact/text/paragraph-key';
+import type {
+  ParagraphDirection,
+  ParagraphSpec,
+  ParagraphSpan,
+  ParagraphTextAlign,
+  ParagraphTextStyle,
+  ParagraphTruncation,
+  ParagraphWritingMode,
+} from '@exact/text/paragraph-spec';
+import { isValidElement } from 'react';
+
+interface ParagraphLoweringContext {
+  readonly inheritedStyle?: ParagraphTextStyle;
+  readonly locale?: string;
+}
+
+export interface TextParagraphLoweringResult {
+  readonly key: string;
+  readonly plainText: string;
+  readonly spec: ParagraphSpec;
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readPositiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.trunc(value)
+    : undefined;
+}
+
+function readFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function toParagraphDirection(value: unknown): ParagraphDirection | undefined {
+  return value === 'ltr' || value === 'rtl' || value === 'auto' ? value : undefined;
+}
+
+function toParagraphWritingMode(value: unknown): ParagraphWritingMode | undefined {
+  return value === 'horizontal-tb' || value === 'vertical-rl' || value === 'vertical-lr'
+    ? value
+    : undefined;
+}
+
+function toParagraphTextAlign(value: unknown): ParagraphTextAlign | undefined {
+  return value === 'auto' ||
+    value === 'left' ||
+    value === 'right' ||
+    value === 'center' ||
+    value === 'justify'
+    ? value
+    : undefined;
+}
+
+function toParagraphTruncation(value: unknown): ParagraphTruncation | undefined {
+  return value === 'head' || value === 'middle' || value === 'tail' || value === 'clip'
+    ? value
+    : undefined;
+}
+
+function toParagraphFontStyle(value: unknown): ParagraphTextStyle['fontStyle'] | undefined {
+  return value === 'normal' || value === 'italic' ? value : undefined;
+}
+
+function toParagraphFontWeight(value: unknown): ParagraphTextStyle['fontWeight'] | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  return value === 'normal' ||
+    value === 'bold' ||
+    value === '100' ||
+    value === '200' ||
+    value === '300' ||
+    value === '400' ||
+    value === '500' ||
+    value === '600' ||
+    value === '700' ||
+    value === '800' ||
+    value === '900'
+    ? value
+    : undefined;
+}
+
+function toParagraphTextDecorationLine(
+  value: unknown,
+): ParagraphTextStyle['textDecorationLine'] | undefined {
+  return value === 'none' ||
+    value === 'underline' ||
+    value === 'line-through' ||
+    value === 'underline line-through'
+    ? value
+    : undefined;
+}
+
+function readTextStyleObject(
+  props: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  return typeof props.style === 'object' && props.style !== null
+    ? (props.style as Record<string, unknown>)
+    : undefined;
+}
+
+function normalizeParagraphTextStyle(
+  style: ParagraphTextStyle | undefined,
+): ParagraphTextStyle | undefined {
+  if (!style) {
+    return undefined;
+  }
+
+  const normalized = {
+    ...(style.color !== undefined ? { color: style.color } : null),
+    ...(style.fontFamily !== undefined ? { fontFamily: style.fontFamily } : null),
+    ...(style.fontSize !== undefined ? { fontSize: style.fontSize } : null),
+    ...(style.fontWeight !== undefined ? { fontWeight: style.fontWeight } : null),
+    ...(style.fontStyle !== undefined ? { fontStyle: style.fontStyle } : null),
+    ...(style.fontVariantNumeric !== undefined
+      ? { fontVariantNumeric: style.fontVariantNumeric }
+      : null),
+    ...(style.fontFeatureSettings !== undefined
+      ? { fontFeatureSettings: style.fontFeatureSettings }
+      : null),
+    ...(style.fontVariationSettings !== undefined
+      ? { fontVariationSettings: style.fontVariationSettings }
+      : null),
+    ...(style.lineHeight !== undefined ? { lineHeight: style.lineHeight } : null),
+    ...(style.letterSpacing !== undefined ? { letterSpacing: style.letterSpacing } : null),
+    ...(style.textDecorationLine !== undefined
+      ? { textDecorationLine: style.textDecorationLine }
+      : null),
+    ...(style.locale !== undefined ? { locale: style.locale } : null),
+  } satisfies ParagraphTextStyle;
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function paragraphTextStyleKey(style: ParagraphTextStyle | undefined): string {
+  return JSON.stringify(style ?? null);
+}
+
+function mergeParagraphTextStyle(
+  inheritedStyle: ParagraphTextStyle | undefined,
+  overrideStyle: ParagraphTextStyle | undefined,
+  locale: string | undefined,
+): ParagraphTextStyle | undefined {
+  const merged = normalizeParagraphTextStyle({
+    ...inheritedStyle,
+    ...overrideStyle,
+    ...(locale !== undefined ? { locale } : null),
+  });
+  return merged;
+}
+
+function resolveParagraphTextStyleFromProps(
+  props: Record<string, unknown>,
+  locale: string | undefined,
+): ParagraphTextStyle | undefined {
+  const rawStyle = readTextStyleObject(props);
+
+  return normalizeParagraphTextStyle({
+    color: readNonEmptyString(rawStyle?.color),
+    fontFamily:
+      typeof rawStyle?.fontFamily === 'string' ||
+      (Array.isArray(rawStyle?.fontFamily) &&
+        rawStyle.fontFamily.every((entry) => typeof entry === 'string'))
+        ? (rawStyle.fontFamily as string | readonly string[])
+        : undefined,
+    fontSize: readFiniteNumber(rawStyle?.fontSize),
+    fontWeight: toParagraphFontWeight(rawStyle?.fontWeight),
+    fontStyle: toParagraphFontStyle(rawStyle?.fontStyle),
+    fontVariantNumeric: readNonEmptyString(rawStyle?.fontVariantNumeric),
+    fontFeatureSettings: readNonEmptyString(rawStyle?.fontFeatureSettings),
+    fontVariationSettings: readNonEmptyString(rawStyle?.fontVariationSettings),
+    lineHeight: readFiniteNumber(rawStyle?.lineHeight),
+    letterSpacing: readFiniteNumber(rawStyle?.letterSpacing),
+    textDecorationLine: toParagraphTextDecorationLine(rawStyle?.textDecorationLine),
+    locale,
+  });
+}
+
+function pushTextSpan(
+  spans: ParagraphSpan[],
+  text: string,
+  style: ParagraphTextStyle | undefined,
+): void {
+  if (text.length === 0) {
+    return;
+  }
+
+  const normalizedStyle = normalizeParagraphTextStyle(style);
+  const previous = spans[spans.length - 1];
+
+  if (
+    previous &&
+    previous.type === 'text' &&
+    paragraphTextStyleKey(previous.style) === paragraphTextStyleKey(normalizedStyle)
+  ) {
+    spans[spans.length - 1] = {
+      ...previous,
+      text: previous.text + text,
+    };
+    return;
+  }
+
+  spans.push({
+    type: 'text',
+    text,
+    style: normalizedStyle,
+  });
+}
+
+function appendParagraphSpans(
+  spans: ParagraphSpan[],
+  children: unknown,
+  context: ParagraphLoweringContext,
+): void {
+  if (children === null || children === undefined || typeof children === 'boolean') {
+    return;
+  }
+
+  if (typeof children === 'string' || typeof children === 'number') {
+    pushTextSpan(spans, String(children), context.inheritedStyle);
+    return;
+  }
+
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      appendParagraphSpans(spans, child, context);
+    }
+    return;
+  }
+
+  if (!isValidElement(children)) {
+    return;
+  }
+
+  const props =
+    typeof children.props === 'object' && children.props !== null
+      ? (children.props as Record<string, unknown>)
+      : {};
+  const nextLocale = readNonEmptyString(props.lang) ?? context.locale;
+  const nextStyle = mergeParagraphTextStyle(
+    context.inheritedStyle,
+    resolveParagraphTextStyleFromProps(props, nextLocale),
+    nextLocale,
+  );
+
+  appendParagraphSpans(spans, props.children, {
+    inheritedStyle: nextStyle,
+    locale: nextLocale,
+  });
+}
+
+export function extractPlainTextFromParagraphSpec(
+  spec: ParagraphSpec | null | undefined,
+): string | undefined {
+  if (!spec) {
+    return undefined;
+  }
+
+  const plainText = spec.spans
+    .map((span) => (span.type === 'text' ? span.text : span.altText ?? ''))
+    .join('');
+
+  return plainText.length > 0 ? plainText : undefined;
+}
+
+export function lowerTextPropsToParagraphSpec(
+  props: Record<string, unknown>,
+): TextParagraphLoweringResult | null {
+  const locale = readNonEmptyString(props.lang);
+  const paragraphStyle = resolveParagraphTextStyleFromProps(props, locale);
+  const rawStyle = readTextStyleObject(props);
+  const spans: ParagraphSpan[] = [];
+
+  appendParagraphSpans(spans, props.children, {
+    inheritedStyle: paragraphStyle,
+    locale,
+  });
+
+  if (spans.length === 0) {
+    return null;
+  }
+
+  const spec: ParagraphSpec = {
+    spans,
+    locale,
+    baseDirection: toParagraphDirection(rawStyle?.direction),
+    writingMode: toParagraphWritingMode(rawStyle?.writingMode),
+    textAlign: toParagraphTextAlign(rawStyle?.textAlign),
+    maxLines: readPositiveInteger(props.numberOfLines),
+    truncation: toParagraphTruncation(props.ellipsizeMode),
+  };
+  const key = createParagraphKey(spec);
+
+  return {
+    key,
+    plainText: extractPlainTextFromParagraphSpec(spec) ?? '',
+    spec,
+  };
+}
+
+export function getParagraphKeyForTextProps(
+  props: Record<string, unknown>,
+): string | null {
+  return lowerTextPropsToParagraphSpec(props)?.key ?? null;
+}