@ccheever/exact-renderer 0.1.0

package/src/attrs.ts

@@ -0,0 +1,596 @@
+// @system @ref LLP 0202 §2.3 / LLP 0205 S1 — shared semantic DOM attr lowering.
+
+export type DomTagName =
+  | 'div'
+  | 'span'
+  | 'a'
+  | 'button'
+  | 'input'
+  | 'textarea'
+  | 'img'
+  | 'main'
+  | 'nav'
+  | 'header'
+  | 'footer'
+  | 'aside'
+  | 'article'
+  | 'section'
+  | 'blockquote'
+  | 'pre'
+  | 'code'
+  | 'hr'
+  | 'ul'
+  | 'li'
+  | 'label'
+  | `h${1 | 2 | 3 | 4 | 5 | 6}`;
+
+export interface HostAttrNode {
+  tag: string;
+  props?: Record<string, unknown>;
+}
+
+export interface HostSemanticAttrs {
+  tag?: string;
+  role?: string;
+  label?: string;
+  hint?: string;
+  headingLevel?: number;
+  live?: string;
+  labelledBy?: string;
+  describedBy?: string;
+  for?: string;
+  nativeID?: string;
+  testID?: string;
+  testId?: string;
+  focusable?: boolean;
+  inert?: boolean;
+}
+
+export interface LowerHostAttrsOptions {
+  defaultTag?: DomTagName;
+  defaultRole?: string;
+  inferTag?: boolean;
+}
+
+export interface LoweredHostAttrs {
+  tag: DomTagName;
+  attrs: Record<string, unknown>;
+  aria: Record<string, unknown>;
+  tabIndex?: number;
+  inert?: boolean;
+  role?: string;
+  labelAssociation: {
+    for?: string;
+    labelledBy?: string;
+    describedBy?: string;
+  };
+}
+
+const NON_DOM_PROPS = new Set([
+  'testID',
+  'testId',
+  'style',
+  'children',
+  'key',
+  'ref',
+  'agentId',
+  'disabledReason',
+  'onTransitionEnd',
+  'onFocusIn',
+  'onFocusOut',
+  'numberOfLines',
+  'ellipsizeMode',
+  'selectable',
+  'selection',
+  'selectionCopyText',
+  'onSelectionChange',
+  'horizontal',
+  'focusScope',
+  'inert',
+  'scrollLocked',
+  'portalTarget',
+  'accessibilityRole',
+  'accessibilityLabel',
+  'accessibilityHeadingLevel',
+  'accessibilityHint',
+  'accessibilityModal',
+  'accessibilityExpanded',
+  'accessibilitySelected',
+  'accessibilityChecked',
+  'accessibilityDisabled',
+  'accessibilityLive',
+  'accessibilityValueNow',
+  'accessibilityValueMin',
+  'accessibilityValueMax',
+  'accessibilityValueText',
+  'focusable',
+  'nativeID',
+  'accessibilityFor',
+  'accessibilityLabelledBy',
+  'accessibilityDescribedBy',
+  'accessibilityBusy',
+  'showsVerticalScrollIndicator',
+  'showsHorizontalScrollIndicator',
+  'onScroll',
+  'contentContainerStyle',
+  'onPress',
+  'onPressIn',
+  'onPressOut',
+  'onLongPress',
+  'delayLongPress',
+  'onChangeText',
+  'onSubmitEditing',
+  'secureTextEntry',
+  'keyboardType',
+  'returnKeyType',
+  'placeholderTextColor',
+  'editable',
+  'source',
+  'resizeMode',
+  'objectFit',
+  'objectPosition',
+  'svgSource',
+  'alt',
+  'decorative',
+  'longDescription',
+  'loading',
+  'placeholder',
+  'onLoadStart',
+  'onLoad',
+  'onError',
+  'onDisplay',
+  'onValueChange',
+  'glassEffect',
+  'glass',
+  'glassVariant',
+  'glassTint',
+  'glassInteractive',
+  'tintColor',
+  'agentSemantics',
+  'colors',
+  'pixelDensity',
+  '__exactPresencePhase',
+  '__exactPortalLevel',
+  '__exactPortalPresentation',
+  '__exactDismissableLayer',
+  '__exactDismissAction',
+  '__exactFocusRestore',
+  '__exactAnchorTarget',
+  '__exactAnchorPlacement',
+  '__exactAnchorStrategy',
+  '__exactAnchorOffset',
+  '__exactComponentName',
+  '__exactComponentSlot',
+  '__exactSourceFilePath',
+  '__exactVariantProps',
+  '__exactInteractionState',
+  '__exactRenderMode',
+  '__exactSemanticTag',
+]);
+
+const URL_ATTRS = new Set(['href', 'src', 'action', 'formaction', 'xlink:href']);
+
+const SAFE_PASSTHROUGH_ATTRS = new Set([
+  'id',
+  'class',
+  'className',
+  'htmlFor',
+  'for',
+  'role',
+  'title',
+  'href',
+  'target',
+  'rel',
+  'tabIndex',
+  'type',
+  'name',
+  'value',
+  'checked',
+  'disabled',
+  'placeholder',
+  'autoComplete',
+  'autocomplete',
+  'alt',
+  'src',
+  'width',
+  'height',
+  'loading',
+  'inert',
+]);
+
+function isSafeUrlAttrValue(value: unknown): boolean {
+  if (typeof value !== 'string') {
+    return true;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return true;
+  }
+  if (trimmed.startsWith('/') || trimmed.startsWith('#') || trimmed.startsWith('?')) {
+    return true;
+  }
+  try {
+    const url = new URL(trimmed, 'https://exact.invalid');
+    return ['http:', 'https:', 'mailto:', 'tel:'].includes(url.protocol);
+  } catch {
+    return false;
+  }
+}
+
+export function isSafeHostDomAttr(name: string, value: unknown): boolean {
+  const lowerName = name.toLowerCase();
+  if (lowerName === 'style' || lowerName === 'srcdoc') {
+    return false;
+  }
+  if (lowerName.startsWith('on')) {
+    return typeof value === 'function';
+  }
+  if (lowerName.startsWith('aria-') || lowerName.startsWith('data-')) {
+    return true;
+  }
+  if (!SAFE_PASSTHROUGH_ATTRS.has(name) && !SAFE_PASSTHROUGH_ATTRS.has(lowerName)) {
+    return false;
+  }
+  if (URL_ATTRS.has(lowerName) && !isSafeUrlAttrValue(value)) {
+    return false;
+  }
+  return true;
+}
+
+const KNOWN_DOM_TAGS = new Set<DomTagName>([
+  'div',
+  'span',
+  'a',
+  'button',
+  'input',
+  'textarea',
+  'img',
+  'main',
+  'nav',
+  'header',
+  'footer',
+  'aside',
+  'article',
+  'section',
+  'blockquote',
+  'pre',
+  'code',
+  'hr',
+  'ul',
+  'li',
+  'label',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+]);
+
+function stringProp(props: Record<string, unknown>, key: string): string | undefined {
+  const value = props[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function boolProp(props: Record<string, unknown>, key: string): boolean | undefined {
+  const value = props[key];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function finiteNumberProp(props: Record<string, unknown>, key: string): number | undefined {
+  const value = props[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function semanticProps(
+  props: Record<string, unknown>,
+  semantic: HostSemanticAttrs | undefined,
+): Record<string, unknown> {
+  if (!semantic) {
+    return props;
+  }
+
+  const next = { ...props };
+  if (semantic.role !== undefined) next.accessibilityRole ??= semantic.role;
+  if (semantic.label !== undefined) next.accessibilityLabel ??= semantic.label;
+  if (semantic.hint !== undefined) next.accessibilityHint ??= semantic.hint;
+  if (semantic.headingLevel !== undefined) next.accessibilityHeadingLevel ??= semantic.headingLevel;
+  if (semantic.live !== undefined) next.accessibilityLive ??= semantic.live;
+  if (semantic.labelledBy !== undefined) next.accessibilityLabelledBy ??= semantic.labelledBy;
+  if (semantic.describedBy !== undefined) next.accessibilityDescribedBy ??= semantic.describedBy;
+  if (semantic.for !== undefined) next.accessibilityFor ??= semantic.for;
+  if (semantic.nativeID !== undefined) next.nativeID ??= semantic.nativeID;
+  if (semantic.testID !== undefined) next.testID ??= semantic.testID;
+  if (semantic.testId !== undefined) next.testId ??= semantic.testId;
+  if (semantic.focusable !== undefined) next.focusable ??= semantic.focusable;
+  if (semantic.inert !== undefined) next.inert ??= semantic.inert;
+  return next;
+}
+
+function coerceHeadingTag(level: number | undefined): DomTagName | undefined {
+  if (level === undefined) {
+    return undefined;
+  }
+  const clamped = Math.max(1, Math.min(6, Math.trunc(level))) as 1 | 2 | 3 | 4 | 5 | 6;
+  return `h${clamped}`;
+}
+
+function coerceDefaultTag(tag: unknown, fallback: DomTagName): DomTagName {
+  return typeof tag === 'string' && KNOWN_DOM_TAGS.has(tag as DomTagName)
+    ? (tag as DomTagName)
+    : fallback;
+}
+
+function tagForSemanticTag(tag: string | undefined): DomTagName | undefined {
+  switch (tag) {
+    case 'main':
+    case 'nav':
+    case 'header':
+    case 'footer':
+    case 'aside':
+    case 'article':
+    case 'section':
+    case 'blockquote':
+    case 'pre':
+    case 'code':
+    case 'hr':
+      return tag;
+    case 'a':
+    case 'link':
+      return 'a';
+    case 'list':
+      return 'ul';
+    case 'listitem':
+      return 'li';
+    case 'label':
+      return 'label';
+    default:
+      return undefined;
+  }
+}
+
+function tagForRole(role: string | undefined): DomTagName | undefined {
+  switch (role) {
+    case 'main':
+      return 'main';
+    case 'navigation':
+      return 'nav';
+    case 'link':
+      return 'a';
+    case 'banner':
+      return 'header';
+    case 'contentinfo':
+      return 'footer';
+    case 'complementary':
+      return 'aside';
+    case 'article':
+      return 'article';
+    case 'list':
+      return 'ul';
+    case 'listitem':
+      return 'li';
+    default:
+      return undefined;
+  }
+}
+
+function implicitRoleForTag(tag: DomTagName): string | undefined {
+  switch (tag) {
+    case 'button':
+      return 'button';
+    case 'a':
+      return 'link';
+    case 'main':
+      return 'main';
+    case 'nav':
+      return 'navigation';
+    case 'header':
+      return 'banner';
+    case 'footer':
+      return 'contentinfo';
+    case 'aside':
+      return 'complementary';
+    case 'article':
+      return 'article';
+    case 'ul':
+      return 'list';
+    case 'li':
+      return 'listitem';
+    case 'input':
+    case 'textarea':
+      return 'textbox';
+    case 'h1':
+    case 'h2':
+    case 'h3':
+    case 'h4':
+    case 'h5':
+    case 'h6':
+      return 'heading';
+    default:
+      return undefined;
+  }
+}
+
+function resolveDomTag(
+  node: HostAttrNode,
+  props: Record<string, unknown>,
+  semantic: HostSemanticAttrs | undefined,
+  options: LowerHostAttrsOptions,
+): DomTagName {
+  const defaultTag = options.defaultTag ?? coerceDefaultTag(node.tag, 'div');
+  if (options.inferTag === false) {
+    return defaultTag;
+  }
+  const role = stringProp(props, 'accessibilityRole') ?? stringProp(props, 'role') ?? options.defaultRole;
+  const headingLevel = finiteNumberProp(props, 'accessibilityHeadingLevel');
+
+  return (
+    tagForSemanticTag(semantic?.tag) ??
+    (role === 'heading' ? coerceHeadingTag(headingLevel) : undefined) ??
+    tagForRole(role) ??
+    defaultTag
+  );
+}
+
+export function lowerHostAttrs(
+  node: HostAttrNode,
+  semantic?: HostSemanticAttrs,
+  options: LowerHostAttrsOptions = {},
+): LoweredHostAttrs {
+  const props = semanticProps(node.props ?? {}, semantic);
+  const tag = resolveDomTag(node, props, semantic, options);
+  const implicitRole = implicitRoleForTag(tag);
+  const role =
+    stringProp(props, 'accessibilityRole') ??
+    stringProp(props, 'role') ??
+    options.defaultRole;
+  const attrs: Record<string, unknown> = {};
+  const aria: Record<string, unknown> = {};
+  const labelAssociation: LoweredHostAttrs['labelAssociation'] = {};
+
+  const testId = stringProp(props, 'testID') ?? stringProp(props, 'testId');
+  if (testId) attrs['data-testid'] = testId;
+
+  const id = stringProp(props, 'nativeID') ?? stringProp(props, 'id');
+  if (id) attrs.id = id;
+
+  if (role && role !== implicitRole) {
+    attrs.role = role;
+  }
+
+  const accessibilityLabel =
+    stringProp(props, 'accessibilityLabel') ?? stringProp(props, 'aria-label');
+  if (accessibilityLabel) {
+    aria['aria-label'] = accessibilityLabel;
+    attrs['aria-label'] = accessibilityLabel;
+  }
+
+  const hint = stringProp(props, 'accessibilityHint');
+  if (hint) {
+    aria['aria-description'] = hint;
+    attrs['aria-description'] = hint;
+  }
+
+  const modal = boolProp(props, 'accessibilityModal');
+  if (modal !== undefined) {
+    aria['aria-modal'] = modal;
+    attrs['aria-modal'] = modal;
+  }
+
+  const expanded = boolProp(props, 'accessibilityExpanded');
+  if (expanded !== undefined) {
+    aria['aria-expanded'] = expanded;
+    attrs['aria-expanded'] = expanded;
+  }
+
+  const selected = boolProp(props, 'accessibilitySelected');
+  if (selected !== undefined) {
+    aria['aria-selected'] = selected;
+    attrs['aria-selected'] = selected;
+  }
+
+  if (typeof props.accessibilityChecked === 'boolean' || props.accessibilityChecked === 'mixed') {
+    aria['aria-checked'] = props.accessibilityChecked;
+    attrs['aria-checked'] = props.accessibilityChecked;
+  }
+
+  const accessibilityDisabled = boolProp(props, 'accessibilityDisabled');
+  if (accessibilityDisabled !== undefined && attrs['aria-disabled'] === undefined) {
+    aria['aria-disabled'] = accessibilityDisabled;
+    attrs['aria-disabled'] = accessibilityDisabled;
+  }
+
+  const live = stringProp(props, 'accessibilityLive');
+  if (live) {
+    aria['aria-live'] = live;
+    attrs['aria-live'] = live;
+  }
+
+  for (const [prop, attr] of [
+    ['accessibilityValueNow', 'aria-valuenow'],
+    ['accessibilityValueMin', 'aria-valuemin'],
+    ['accessibilityValueMax', 'aria-valuemax'],
+  ] as const) {
+    const value = finiteNumberProp(props, prop);
+    if (value !== undefined) {
+      aria[attr] = value;
+      attrs[attr] = value;
+    }
+  }
+
+  const valueText = stringProp(props, 'accessibilityValueText');
+  if (valueText) {
+    aria['aria-valuetext'] = valueText;
+    attrs['aria-valuetext'] = valueText;
+  }
+
+  const labelledBy = stringProp(props, 'accessibilityLabelledBy');
+  if (labelledBy) {
+    labelAssociation.labelledBy = labelledBy;
+    aria['aria-labelledby'] = labelledBy;
+    attrs['aria-labelledby'] = labelledBy;
+  }
+
+  const describedBy = stringProp(props, 'accessibilityDescribedBy');
+  if (describedBy) {
+    labelAssociation.describedBy = describedBy;
+    aria['aria-describedby'] = describedBy;
+    attrs['aria-describedby'] = describedBy;
+  }
+
+  const htmlFor = stringProp(props, 'accessibilityFor');
+  if (htmlFor) {
+    labelAssociation.for = htmlFor;
+    attrs.htmlFor = htmlFor;
+  }
+
+  const busy = boolProp(props, 'accessibilityBusy');
+  if (busy !== undefined) {
+    aria['aria-busy'] = busy;
+    attrs['aria-busy'] = busy;
+  }
+
+  const headingLevel = finiteNumberProp(props, 'accessibilityHeadingLevel');
+  if (headingLevel !== undefined && implicitRole !== 'heading') {
+    aria['aria-level'] = headingLevel;
+    attrs['aria-level'] = headingLevel;
+  }
+
+  if (props.focusable === true && attrs.tabIndex === undefined) {
+    attrs.tabIndex = 0;
+  }
+
+  if (props.inert === true) {
+    attrs.inert = true;
+    attrs['aria-hidden'] ??= true;
+    aria['aria-hidden'] ??= true;
+  }
+
+  if (props.scrollLocked === true) {
+    attrs['data-exact-scroll-locked'] = 'true';
+  }
+
+  for (const key of Object.keys(props)) {
+    if (!NON_DOM_PROPS.has(key) && attrs[key] === undefined && isSafeHostDomAttr(key, props[key])) {
+      attrs[key] = props[key];
+    }
+  }
+
+  return {
+    tag,
+    attrs,
+    aria,
+    tabIndex: typeof attrs.tabIndex === 'number' ? attrs.tabIndex : undefined,
+    inert: attrs.inert === true,
+    role: typeof attrs.role === 'string' ? attrs.role : undefined,
+    labelAssociation,
+  };
+}
+
+/** Strip props that are not valid DOM attributes to avoid React warnings. */
+export function filterDOMProps(props: Record<string, unknown>): Record<string, unknown> {
+  return lowerHostAttrs({ tag: 'div', props }, undefined, {
+    defaultTag: 'div',
+    inferTag: false,
+  }).attrs;
+}

package/src/classname-contract.ts

@@ -0,0 +1,87 @@
+import type { CanonicalStyle } from './types.js';
+
+/**
+ * The runtime resolver and the server-side compiler intentionally share this
+ * file so the cross-boundary stylesheet artifact is explicit and easy to audit.
+ * Nothing here imports React, Lightning CSS, or Node-only modules.
+ */
+
+export type SupportedPseudo =
+  | 'disabled'
+  | 'hover'
+  | 'focus'
+  | 'active'
+  | 'focus-visible'
+  | 'first-child'
+  | 'last-child';
+
+export interface MediaCondition {
+  readonly feature:
+    | 'min-width'
+    | 'max-width'
+    | 'min-height'
+    | 'max-height'
+    | 'gt-width'
+    | 'gt-height'
+    | 'lt-width'
+    | 'lt-height'
+    | 'orientation'
+    | 'prefers-color-scheme'
+    | 'prefers-reduced-motion';
+  readonly value: number | string;
+}
+
+export type SerializedFragmentCondition =
+  | { readonly type: 'pseudo'; readonly pseudo: SupportedPseudo }
+  | { readonly type: 'media'; readonly media: readonly MediaCondition[] }
+  | {
+      readonly type: 'group';
+      readonly groupName: string | null;
+      readonly pseudo: 'hover' | 'focus' | 'active';
+    }
+  | {
+      readonly type: 'peer';
+      readonly peerName: string | null;
+      readonly pseudo: 'hover' | 'focus' | 'active';
+    };
+
+export interface SerializedCompiledFragment {
+  readonly order: number;
+  readonly condition: SerializedFragmentCondition | null;
+  readonly mediaGate: readonly MediaCondition[] | null;
+  readonly style: CanonicalStyle;
+}
+
+export interface SerializedExactStyleSheet {
+  readonly classes: Record<string, SerializedCompiledFragment[]>;
+  readonly warnings: string[];
+}
+
+export interface InteractionState {
+  readonly hovered: boolean;
+  readonly focused: boolean;
+  readonly active: boolean;
+  readonly focusVisible: boolean;
+}
+
+export interface SiblingPosition {
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+}
+
+export interface MediaState {
+  readonly width: number;
+  readonly height: number;
+  readonly orientation: 'portrait' | 'landscape';
+  readonly colorScheme: 'light' | 'dark';
+  readonly reducedMotion: boolean;
+}
+
+export interface ClassNameResolutionContext {
+  readonly props?: Record<string, unknown>;
+  readonly interaction?: InteractionState;
+  readonly position?: SiblingPosition;
+  readonly groupStates?: ReadonlyMap<string | null, InteractionState>;
+  readonly peerStates?: { getState(name: string | null): InteractionState | undefined };
+  readonly cssVars?: Readonly<Record<string, string>>;
+}