@ccheever/exact-renderer 0.1.0

package/src/safe-area.ts

@@ -0,0 +1,543 @@
+import type { ElementNode, RootNode } from './nodes/node.js';
+import {
+  getRootWindowMetrics,
+  getWindowViewportForRoot,
+} from '@exact/core/window-state';
+import type { Frame } from '@exact/core/agent/types';
+import type {
+  KeyboardState,
+  SafeAreaInsets,
+  SafeAreaRegionInsets,
+  SafeAreaRegionName,
+} from '@exact/core/window-types';
+import type {
+  CanonicalStyle,
+  ResolvedSafeAreaConfig,
+  ResolvedSafeAreaState,
+  SafeAreaEdge,
+  SafeAreaEdgeMode,
+  SafeAreaEdgeModes,
+  SafeAreaInsetProp,
+  SafeAreaPropagationState,
+  SafeAreaRegionSet,
+  SafeAreaStrategy,
+} from './types.js';
+import { NodeKind } from './nodes/node.js';
+
+const SAFE_AREA_EDGES: readonly SafeAreaEdge[] = ['top', 'right', 'bottom', 'left'] as const;
+const SAFE_AREA_REGIONS: readonly SafeAreaRegionName[] = [
+  'container',
+  'keyboard',
+  'displayCutout',
+  'gestures',
+] as const;
+const PADDING_KEYS: Record<SafeAreaEdge, 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft'> = {
+  top: 'paddingTop',
+  right: 'paddingRight',
+  bottom: 'paddingBottom',
+  left: 'paddingLeft',
+};
+
+const DEFAULT_EDGE_MODES: Readonly<SafeAreaEdgeModes> = Object.freeze({
+  top: 'additive',
+  right: 'additive',
+  bottom: 'additive',
+  left: 'additive',
+});
+
+function cloneInsets(insets: SafeAreaInsets): SafeAreaInsets {
+  return { ...insets };
+}
+
+function zeroInsets(): SafeAreaInsets {
+  return {
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+  };
+}
+
+function zeroRegions(): SafeAreaRegionInsets {
+  return {
+    container: zeroInsets(),
+    displayCutout: zeroInsets(),
+    gestures: zeroInsets(),
+  };
+}
+
+function cloneRegions(regions: SafeAreaRegionInsets): SafeAreaRegionInsets {
+  return {
+    container: cloneInsets(regions.container),
+    displayCutout: cloneInsets(regions.displayCutout),
+    gestures: cloneInsets(regions.gestures),
+  };
+}
+
+function cloneKeyboardState(state: KeyboardState): KeyboardState {
+  return {
+    ...state,
+    occlusion: { ...state.occlusion },
+  };
+}
+
+function hasInset(insets: SafeAreaInsets): boolean {
+  return (
+    insets.top > 0 ||
+    insets.right > 0 ||
+    insets.bottom > 0 ||
+    insets.left > 0
+  );
+}
+
+function maxInsets(left: SafeAreaInsets, right: SafeAreaInsets): SafeAreaInsets {
+  return {
+    top: Math.max(left.top, right.top),
+    right: Math.max(left.right, right.right),
+    bottom: Math.max(left.bottom, right.bottom),
+    left: Math.max(left.left, right.left),
+  };
+}
+
+function addInsets(left: SafeAreaInsets, right: SafeAreaInsets): SafeAreaInsets {
+  return {
+    top: left.top + right.top,
+    right: left.right + right.right,
+    bottom: left.bottom + right.bottom,
+    left: left.left + right.left,
+  };
+}
+
+function subtractInsets(left: SafeAreaInsets, right: SafeAreaInsets): SafeAreaInsets {
+  return {
+    top: Math.max(0, left.top - right.top),
+    right: Math.max(0, left.right - right.right),
+    bottom: Math.max(0, left.bottom - right.bottom),
+    left: Math.max(0, left.left - right.left),
+  };
+}
+
+function readNumericPadding(
+  style: CanonicalStyle,
+  edge: SafeAreaEdge,
+  viewport: { width: number; height: number },
+): number {
+  const source = style[PADDING_KEYS[edge]];
+  if (source == null) {
+    return 0;
+  }
+
+  if (source.type === 'points') {
+    return source.value;
+  }
+
+  if (source.type === 'percent') {
+    const base = edge === 'left' || edge === 'right'
+      ? viewport.width
+      : viewport.height;
+    return base * (source.value / 100);
+  }
+
+  return 0;
+}
+
+function setPadding(
+  style: CanonicalStyle,
+  edge: SafeAreaEdge,
+  value: number,
+): void {
+  style[PADDING_KEYS[edge]] = { type: 'points', value };
+}
+
+function defaultRegionsForNode(
+  tagType: ElementNode['tagType'],
+  parent: ElementNode | RootNode | null | undefined,
+): SafeAreaRegionName[] {
+  // Direct children of the synthetic root behave as the layout root from the
+  // RFC’s point of view. Regular views therefore default to container safety.
+  if (tagType === 'scroll') {
+    return ['container', 'keyboard'];
+  }
+  if (parent?.kind === NodeKind.Root) {
+    return ['container'];
+  }
+  return [];
+}
+
+function normalizeRegionSet(
+  regions: SafeAreaRegionSet | undefined,
+  fallback: SafeAreaRegionName[],
+): SafeAreaRegionName[] {
+  if (regions == null) {
+    return fallback.slice();
+  }
+
+  if (regions === 'all') {
+    return SAFE_AREA_REGIONS.slice();
+  }
+
+  if (regions === 'none') {
+    return [];
+  }
+
+  if (regions === 'container' || regions === 'keyboard') {
+    return [regions];
+  }
+
+  if (!Array.isArray(regions)) {
+    return fallback.slice();
+  }
+
+  const next: SafeAreaRegionName[] = [];
+  for (const entry of regions) {
+    if (isSafeAreaRegionName(entry)) {
+      if (!next.includes(entry)) {
+        next.push(entry);
+      }
+    }
+  }
+  return next;
+}
+
+function normalizeEdgeModes(
+  raw: Record<string, unknown>,
+): SafeAreaEdgeModes {
+  const next: SafeAreaEdgeModes = { ...DEFAULT_EDGE_MODES };
+  for (const edge of SAFE_AREA_EDGES) {
+    const value = raw[edge];
+    if (value === 'additive' || value === 'maximum' || value === 'off') {
+      next[edge] = value;
+    }
+  }
+  return next;
+}
+
+function resolveSafeAreaConfig(
+  tagType: ElementNode['tagType'],
+  parent: ElementNode | RootNode | null | undefined,
+  raw: unknown,
+): ResolvedSafeAreaConfig {
+  if (raw === 'none') {
+    return {
+      explicit: true,
+      regions: [],
+      edges: { ...DEFAULT_EDGE_MODES },
+      strategy: tagType === 'scroll' ? 'contentInset' : 'framePadding',
+    };
+  }
+
+  const fallbackRegions = defaultRegionsForNode(tagType, parent);
+  if (typeof raw !== 'object' || raw == null) {
+    return {
+      explicit: false,
+      regions: fallbackRegions,
+      edges: { ...DEFAULT_EDGE_MODES },
+      strategy: tagType === 'scroll' ? 'contentInset' : 'framePadding',
+    };
+  }
+
+  const record = raw as Record<string, unknown>;
+  return {
+    explicit: true,
+    regions: normalizeRegionSet(record.regions as SafeAreaRegionSet | undefined, fallbackRegions),
+    edges: normalizeEdgeModes(record),
+    strategy: tagType === 'scroll' ? 'contentInset' : 'framePadding',
+  };
+}
+
+function readDeclaredSafeAreaInset(
+  raw: unknown,
+): SafeAreaInsetProp | undefined {
+  if (typeof raw !== 'object' || raw == null) {
+    return undefined;
+  }
+
+  const record = raw as Record<string, unknown>;
+  const edge = record.edge;
+  const size = record.size;
+  if (
+    isSafeAreaEdge(edge) &&
+    typeof size === 'number' &&
+    Number.isFinite(size) &&
+    size > 0
+  ) {
+    return {
+      edge,
+      size,
+    };
+  }
+
+  return undefined;
+}
+
+function isSafeAreaEdge(value: unknown): value is SafeAreaEdge {
+  return (SAFE_AREA_EDGES as readonly unknown[]).includes(value);
+}
+
+function isSafeAreaRegionName(value: unknown): value is SafeAreaRegionName {
+  return (SAFE_AREA_REGIONS as readonly unknown[]).includes(value);
+}
+
+function accumulateSiblingExpansion(
+  parent: ElementNode | RootNode | null | undefined,
+  currentNode: ElementNode,
+): SafeAreaInsets {
+  if (!parent || (parent.kind !== NodeKind.Root && parent.kind !== NodeKind.Element)) {
+    return zeroInsets();
+  }
+
+  const expansion = zeroInsets();
+  for (const child of parent.children) {
+    if (child.kind !== NodeKind.Element || child.id === currentNode.id) {
+      continue;
+    }
+
+    const declaredInset = readDeclaredSafeAreaInset(child.originalProps.safeAreaInset);
+    if (!declaredInset) {
+      continue;
+    }
+
+    expansion[declaredInset.edge] += declaredInset.size;
+  }
+
+  return expansion;
+}
+
+function readRenderedFrame(
+  node: ElementNode,
+  rootId: number,
+): Frame | null {
+  const viewport = getWindowViewportForRoot(rootId);
+  const exactBridge = (
+    globalThis as {
+      exact?: {
+        getAbsoluteLayout?: (viewId: number) => Frame | null;
+        getLayout?: (viewId: number) => Frame | null;
+      };
+    }
+  ).exact;
+
+  const frame = exactBridge?.getAbsoluteLayout?.(node.id) ?? exactBridge?.getLayout?.(node.id) ?? null;
+  if (frame) {
+    return frame;
+  }
+
+  // Before the first layout pass there may be no host frame yet. For the first
+  // child under the synthetic root we can still use the root viewport as a
+  // useful approximation, which is enough for docked-keyboard heuristics.
+  if (node.parent?.kind === NodeKind.Root) {
+    return {
+      x: 0,
+      y: 0,
+      width: viewport.width,
+      height: viewport.height,
+    };
+  }
+
+  return null;
+}
+
+function computeKeyboardOverlap(
+  frame: Frame | null,
+  keyboard: KeyboardState,
+  viewport: { width: number; height: number },
+): SafeAreaInsets {
+  if (!keyboard.visible || keyboard.occlusion.width <= 0 || keyboard.occlusion.height <= 0) {
+    return zeroInsets();
+  }
+
+  const occlusion = keyboard.occlusion;
+
+  // Docked keyboards can fall back to a pure bottom inset even when the node
+  // has not been laid out yet. Floating/split keyboards require an actual frame
+  // because globalizing them would recreate the very bug this RFC is avoiding.
+  if (!frame) {
+    if (keyboard.mode === 'docked') {
+      return {
+        top: 0,
+        right: 0,
+        bottom: Math.max(0, viewport.height - occlusion.y),
+        left: 0,
+      };
+    }
+    return zeroInsets();
+  }
+
+  const horizontallyOverlaps =
+    frame.x < occlusion.x + occlusion.width &&
+    frame.x + frame.width > occlusion.x;
+  const verticallyOverlaps =
+    frame.y < occlusion.y + occlusion.height &&
+    frame.y + frame.height > occlusion.y;
+
+  if (!horizontallyOverlaps || !verticallyOverlaps) {
+    return zeroInsets();
+  }
+
+  return {
+    top: 0,
+    right: 0,
+    bottom: Math.max(0, frame.y + frame.height - occlusion.y),
+    left: 0,
+  };
+}
+
+function consumeStaticRegions(
+  regions: SafeAreaRegionInsets,
+  appliedInsets: SafeAreaInsets,
+  activeRegions: readonly SafeAreaRegionName[],
+): SafeAreaRegionInsets {
+  // Keyboard consumption is geometry-driven and therefore implicit: when a
+  // parent shifts itself away from the keyboard, descendants naturally see less
+  // or no overlap because their frames move. Static regions are different. They
+  // must only be marked "consumed" when this node explicitly opted into that
+  // static region; a keyboard-only node must not accidentally zero out the
+  // container safe area for its descendants.
+  const consumedStaticInsets = activeRegions.some((region) => region === 'container')
+    ? appliedInsets
+    : zeroInsets();
+  const consumedDisplayCutoutInsets = activeRegions.some((region) => region === 'displayCutout')
+    ? appliedInsets
+    : zeroInsets();
+  const consumedGestureInsets = activeRegions.some((region) => region === 'gestures')
+    ? appliedInsets
+    : zeroInsets();
+
+  return {
+    container: subtractInsets(regions.container, consumedStaticInsets),
+    displayCutout: subtractInsets(regions.displayCutout, consumedDisplayCutoutInsets),
+    gestures: subtractInsets(regions.gestures, consumedGestureInsets),
+  };
+}
+
+function deriveAvailableInsets(
+  regions: SafeAreaRegionInsets,
+  keyboardOverlap: SafeAreaInsets,
+  activeRegions: SafeAreaRegionName[],
+): SafeAreaInsets {
+  let available = zeroInsets();
+  for (const region of activeRegions) {
+    switch (region) {
+      case 'container':
+        available = maxInsets(available, regions.container);
+        break;
+      case 'displayCutout':
+        available = maxInsets(available, regions.displayCutout);
+        break;
+      case 'gestures':
+        available = maxInsets(available, regions.gestures);
+        break;
+      case 'keyboard':
+        available = maxInsets(available, keyboardOverlap);
+        break;
+    }
+  }
+  return available;
+}
+
+function applySafeAreaPadding(
+  baseStyle: CanonicalStyle,
+  safeAreaInsets: SafeAreaInsets,
+  edges: SafeAreaEdgeModes,
+  viewport: { width: number; height: number },
+): CanonicalStyle {
+  if (!hasInset(safeAreaInsets)) {
+    return baseStyle;
+  }
+
+  const nextStyle: CanonicalStyle = { ...baseStyle };
+  for (const edge of SAFE_AREA_EDGES) {
+    const safeAreaValue = safeAreaInsets[edge];
+    if (safeAreaValue <= 0 || edges[edge] === 'off') {
+      continue;
+    }
+
+    const basePadding = readNumericPadding(baseStyle, edge, viewport);
+    const resolved =
+      edges[edge] === 'maximum'
+        ? Math.max(basePadding, safeAreaValue)
+        : basePadding + safeAreaValue;
+    setPadding(nextStyle, edge, resolved);
+  }
+
+  return nextStyle;
+}
+
+export function createRootSafeAreaPropagation(
+  rootId: number,
+): SafeAreaPropagationState {
+  const metrics = getRootWindowMetrics(rootId);
+  return {
+    rootId,
+    regions: cloneRegions(metrics.regions),
+    keyboard: cloneKeyboardState(metrics.keyboard),
+  };
+}
+
+export function resolveSafeAreaForElement(
+  node: ElementNode,
+  parent: ElementNode | RootNode | null | undefined,
+  baseStyle: CanonicalStyle,
+  inherited: SafeAreaPropagationState,
+): {
+  style: CanonicalStyle;
+  safeAreaState: ResolvedSafeAreaState | null;
+  propagatedSafeArea: SafeAreaPropagationState;
+} {
+  const viewport = getWindowViewportForRoot(inherited.rootId);
+  const config = resolveSafeAreaConfig(node.tagType, parent, node.originalProps.safeArea);
+  const siblingExpansion = accumulateSiblingExpansion(parent, node);
+  const sourceRegions = cloneRegions(inherited.regions);
+  sourceRegions.container = addInsets(sourceRegions.container, siblingExpansion);
+
+  const frame = readRenderedFrame(node, inherited.rootId);
+  const keyboardOverlap =
+    config.regions.includes('keyboard')
+      ? computeKeyboardOverlap(frame, inherited.keyboard, viewport)
+      : zeroInsets();
+  const availableInsets = deriveAvailableInsets(sourceRegions, keyboardOverlap, config.regions);
+
+  // `maximum` still counts as consumption even when author padding is already
+  // large enough. Descendants should not re-apply the same safe area again.
+  const appliedInsets = cloneInsets(availableInsets);
+  for (const edge of SAFE_AREA_EDGES) {
+    if (config.edges[edge] === 'off') {
+      appliedInsets[edge] = 0;
+    }
+  }
+
+  const style = applySafeAreaPadding(baseStyle, appliedInsets, config.edges, viewport);
+  const remainingRegions = consumeStaticRegions(
+    sourceRegions,
+    appliedInsets,
+    config.regions,
+  );
+  const propagatedSafeArea: SafeAreaPropagationState = {
+    rootId: inherited.rootId,
+    regions: remainingRegions,
+    keyboard: cloneKeyboardState(inherited.keyboard),
+  };
+
+  const shouldExposeState =
+    config.explicit ||
+    config.regions.length > 0 ||
+    hasInset(siblingExpansion);
+
+  return {
+    style,
+    safeAreaState: shouldExposeState
+      ? {
+          config,
+          strategy: config.strategy,
+          sourceRegions,
+          siblingExpansion,
+          availableInsets,
+          keyboardOverlap,
+          appliedInsets,
+          remainingRegions,
+          keyboardState: cloneKeyboardState(inherited.keyboard),
+        }
+      : null,
+    propagatedSafeArea,
+  };
+}