@webview-native-ui/engine 1.0.1 → 1.0.2

package/src/controls/definitions.ts

@@ -0,0 +1,338 @@
+import type { WebProjectionTransport } from '../index.js';
+import type { NativeUIExtension } from './extensions.js';
+import type { NativeUIListenerHandle as PluginListenerHandle } from './transport.js';
+
+export type NativeUIComponent =
+  'ion-button' | 'ion-buttons' | 'ion-back-button' | 'ion-menu-button' | 'ion-tab-bar' | 'ion-segment' | 'ion-fab';
+
+export interface NativeUIStatus {
+  state: 'web' | 'native' | 'stopped';
+  projected: number;
+  updates: number;
+  reason?: string;
+}
+
+/** Default selection in ordinary (horizontal) or rail (vertical) placement.
+ * Explicit source settings override these defaults. This does not choose placement.
+ */
+export type ControlProjection = boolean | 'horizontalOnly' | 'verticalOnly';
+
+export interface NativeUIControls {
+  /** Group selected ordinary buttons. Does not select children or include back buttons. */
+  buttonGroup?: ControlProjection;
+  /** Select ordinary actions, including menu buttons. */
+  button?: ControlProjection;
+  backButton?: ControlProjection;
+  tabs?: ControlProjection;
+  segment?: ControlProjection;
+  fab?: ControlProjection;
+}
+
+export interface IonicProjectionOptions {
+  /** Discover supported Ionic controls automatically. Explicit sources remain independent. Defaults to true. */
+  auto?: boolean;
+  verticalBars?: {
+    /** Native appearance of vertical Ionic buttons. Local source settings take precedence. Defaults to system. */
+    buttonProjection?: 'system' | 'source';
+    /** Source-style standalone ion-button default; ion-buttons still defaults to clear. Defaults to glass. */
+    buttonDefaultFill?: 'glass' | 'solid';
+    /** Relay Ionic popovers anchored to native rail buttons. Defaults to false. */
+    popover?: boolean;
+  };
+}
+
+export interface NativeUIOptions {
+  /** Connected source subtree. Defaults to document.body. */
+  root?: HTMLElement;
+  /** Default selection and grouping. Scalars apply to every kind; omitted fields default to true. */
+  controls?: ControlProjection | NativeUIControls;
+  verticalBars?: NativeUIVerticalBarsOptions;
+  /** App-local projection definitions, independent of controls.
+   * @experimental API and behavior may change.
+   */
+  extensions?: readonly NativeUIExtension[];
+  ionic?: IonicProjectionOptions;
+  /** Log Web fallback reasons. Defaults to false. */
+  debug?: boolean;
+}
+
+/** Options for the standalone rail entry. */
+export type VerticalControlAreaOptions = NativeUIOptions;
+
+/** @internal Resolved adapter state; not an application configuration API. */
+export interface NativeUIRuntimeOptions extends NativeUIOptions {
+  source?: 'ionic' | 'html' | 'auto' | 'extensions';
+  nativeState?: { edge?: 'left' | 'right' };
+  /** @internal Negotiated native support; absent on older binaries. */
+  coveredSnapshots?: boolean;
+  nativeScroll?: boolean;
+  unavailableExtensions?: ReadonlyMap<string, string>;
+  rail?: { host: HTMLElement; edge: 'left' | 'right' };
+}
+
+/** A running shell. Placement changes preserve all other startup settings. */
+export interface NativeUIHandle extends NativeUIRuntimeHandle {
+  /** Enable rail projection when available, preserving other settings. Rejects after destroy. */
+  enableVerticalControlArea(): Promise<void>;
+  /** Restore rail sources to the Web without stopping ordinary native controls. Rejects after destroy. */
+  disableVerticalControlArea(): Promise<void>;
+}
+
+export interface NativeUIVerticalBarsOptions {
+  /** Defaults to true. Availability is always determined separately. */
+  enabled?: boolean;
+  /** Placement preference, not a declaration of device capability. */
+  placement?: { edge: Exclude<VerticalBarEdge, null>; webHost?: HTMLElement };
+}
+
+export interface NativeUIRuntimeHandle {
+  /** Schedule a source recheck. Calls coalesce; unchanged snapshots are not sent. No-op after destroy or without a runtime. */
+  markForCheck(): void;
+  /** Returns the current Web/native projection state. */
+  getStatus(): NativeUIStatus;
+  /** Restores Web controls until resumed. Use covered only while the background is non-interactive; prepared native images preserve its appearance. */
+  suspend(options?: { covered?: boolean }): Promise<NativeUISuspension>;
+  /** Stops synchronization, restores Web controls and releases native resources. */
+  destroy(): Promise<void>;
+}
+
+/** Logical edge in the reading direction, matching UIVerticalBarEdge and capacitor-foldable. */
+export type VerticalBarEdge = 'leading' | 'trailing' | null;
+
+export interface VerticalBarPlacement {
+  edge: VerticalBarEdge;
+  /** Explicit rail width in CSS pixels; omitted to use the stylesheet's safe-area rules. */
+  inset?: number;
+  /** Ignored. Native availability is read from the plugin’s own device metrics.
+   * @deprecated This input no longer reports native availability.
+   */
+  nativeEdge?: VerticalBarEdge;
+}
+
+export interface VerticalControlAreaHandle extends NativeUIHandle {
+  /** Legacy Web CSS adapter. Use the theme setVerticalBarsLayout helper instead.
+   * @deprecated Web layout belongs to the theme or application.
+   */
+  setPlacement(placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean): void;
+}
+
+export interface NativeUISuspension {
+  /** Releases this suspension. Native projection resumes after all active suspensions are released. */
+  resume(): Promise<void>;
+}
+
+export interface Frame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Measured native rail surface, in Web viewport pixels. */
+export interface NativeUIVerticalBarFrame extends Frame {
+  /** Optional for compatibility with older native binaries. */
+  cornerRadius?: number;
+}
+
+export interface NativeUIBadge {
+  value: string;
+  color: string;
+  textColor: string;
+}
+
+export interface NativeUIItem extends Frame {
+  id: string;
+  /** Toolbar presentation identity; never used to dispatch an action. */
+  transitionId?: string;
+  label: string;
+  accessibilityLabel: string;
+  disabled: boolean;
+  selected: boolean;
+  fontSize: number;
+  fontWeight: number;
+  color: string;
+  /** Resolved ion-button fill for vertical projection; clear omits the native glass background. */
+  buttonFill?: 'clear' | 'solid' | 'outline';
+  backgroundColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  badge?: NativeUIBadge;
+  icon?: string;
+  iconWidth?: number;
+  iconHeight?: number;
+  iconPosition?: 'leading' | 'trailing' | 'top';
+  imagePadding?: number;
+  contentInsetLeading?: number;
+  contentInsetTrailing?: number;
+  iconTemplate?: boolean;
+  visible?: boolean;
+  closeIcon?: string;
+  closeIconWidth?: number;
+  closeIconHeight?: number;
+  iconTransition?: number;
+}
+
+/** Standard native renderers, independent of the source Web framework. */
+export type NativeUIControlKind =
+  'button' | 'button-group' | 'back-button' | 'menu-button' | 'tab-bar' | 'segment' | 'floating-action-button';
+
+/** @internal Layout sample for one native-owned overflow scroll container. */
+export interface NativeUIScrollPlacement {
+  id: string;
+  /** @internal Only reuse a mapping whose update was accepted by Web. */
+  reuse?: boolean;
+  offsetX: number;
+  offsetY: number;
+  viewport: Frame;
+  clip: Frame;
+  contentWidth: number;
+  contentHeight: number;
+  frame: Frame;
+}
+
+export interface NativeUIControl extends Frame {
+  id: string;
+  /** Stable toolbar group identity, independent of the source control ID. */
+  transitionId?: string;
+  kind: NativeUIControlKind | 'extension';
+  scroll?: NativeUIScrollPlacement;
+  extension?: { name: string; props: string; actions: Record<string, string>; tabBarId?: string };
+  /** Lets the native host own adaptive placement instead of mirroring the DOM frame. */
+  placement?: 'vertical-bars';
+  /** Logical Ionic toolbar slot, preserved when projecting to the vertical rail. */
+  toolbarSlot?: 'start' | 'end';
+  items: NativeUIItem[];
+  dark: boolean;
+  rtl: boolean;
+  /** Applied selection tint for native tabs; other tab appearance remains system-owned. */
+  tabTint?: string;
+  tabBarAnchor?: { x: 0 | 0.5 | 1; y: 0 | 1 };
+  search?: NativeUISearch;
+}
+
+export interface NativeUISearch {
+  id: string;
+  field: NativeUIItem;
+  trigger: NativeUIItem;
+  closeId: string;
+  active: boolean;
+  available: boolean;
+  focused: boolean;
+  value: string;
+  placeholder: string;
+  disabled: boolean;
+  editSequence: number;
+  valueVersion: number;
+}
+
+export interface NativeUISearchEvent extends NativeUIActivation {
+  valueVersion: number;
+  phase: 'input' | 'focus' | 'blur' | 'clear' | 'commit';
+  value: string;
+  composing: boolean;
+}
+
+export interface NativeUISnapshot {
+  /** Prepared Web image currently covering the inactive root surface. */
+  coveredSnapshotToken?: string;
+  revision: number;
+  transitionDuration?: number;
+  /** Prepared native toolbar endpoints, controlled by the page animation clock. */
+  toolbarTransition?: { id: number; sourceIds: string[]; destination: NativeUIControl[] };
+  viewportWidth: number;
+  /** Physical side the native rail is drawn on; the runtime resolves the logical edge through the document direction. */
+  verticalBarEdge?: 'left' | 'right';
+  /** Visible foreground modal bounds; omitted for the full page. */
+  verticalBarFrame?: Frame;
+  modalAnimation?: import('./shared/modal-animation.js').ModalAnimation;
+  /** Web-owned page identities, from root through the active rail destination. */
+  verticalBarNavigation?: string[];
+  /** Keep the current native rail until an interactive navigation settles. */
+  verticalBarNavigationPhase?: 'tracking' | 'settling';
+  controls: NativeUIControl[];
+}
+
+export interface NativeUIActivation {
+  revision: number;
+  id: string;
+  sequence: number;
+  /** Native extension action awaiting a Web dispatch acknowledgement. */
+  requestId?: string;
+}
+
+export interface WebViewMetrics {
+  /** The WebView's effective top-left corner radius in points, or `0` when unavailable. */
+  radius: number;
+  /** Device-reported logical rail edge; null when unavailable. */
+  verticalBarEdge?: VerticalBarEdge;
+}
+
+/** @internal Native ownership snapshot; reading it never performs layout. */
+export interface NativeUIConnectionState {
+  session: string;
+  revision: number;
+  sequence: number;
+  listeners: string[];
+  surfaces: { horizontal: boolean; vertical: boolean };
+  overlay?: { id: string; state: 'presented' | 'dismissed' | 'missing' };
+}
+
+/** @internal Prepared native pixels, served through Capacitor's local resource handler. */
+export interface CoveredSnapshot {
+  token: string;
+  parts: (Frame & { ids: string[]; url: string })[];
+}
+
+export interface NativeUIPlugin {
+  configure(options?: { suppressScrollEdgeEffect?: boolean }): Promise<{
+    supported: boolean;
+    extensions?: string[];
+    modalAnimation?: boolean;
+    connectionState?: boolean;
+    coveredSnapshots?: boolean;
+    nativeScroll?: boolean;
+  }>;
+  coveredSnapshot?: WebProjectionTransport['send'];
+  completeExtensionAction(options: { requestId: string; accepted: boolean }): Promise<void>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
+  getVerticalBarsGeometry(options: {
+    viewportWidth: number;
+    ids: string[];
+  }): Promise<{ revision?: number; items: Record<string, NativeUIVerticalBarFrame> }>;
+  prepareOverlay(options: { id: string }): Promise<void>;
+  presentOverlay(options: { id: string; presentation?: NativeUIPopoverPresentation }): Promise<void>;
+  getConnectionState(): Promise<NativeUIConnectionState>;
+  dismissOverlay(options: { id: string; animated: boolean }): Promise<void>;
+  closeOverlay(options: { id: string }): Promise<void>;
+  stopOverlays(): Promise<void>;
+  update(snapshot: NativeUISnapshot): Promise<{
+    revision: number;
+    rejectedSearches?: string[];
+    rejectedControls?: string[];
+    tabBarWidths?: Record<string, number>;
+    toolbarTransition?: number;
+  }>;
+  setToolbarTransitionProgress(options: { id: number; progress: number }): Promise<void>;
+  clear(options: { revision: number }): Promise<void>;
+  addListener(name: 'snapshotInteraction', listener: (event: { active: boolean }) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'activate', listener: (event: NativeUIActivation) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'search', listener: (event: NativeUISearchEvent) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'overlay', listener: (event: NativeUIOverlayEvent) => void): Promise<PluginListenerHandle>;
+}
+
+export interface NativeUIPopoverPresentation {
+  kind: 'popover';
+  animated: boolean;
+  dark: boolean;
+  anchorId: string;
+  width: number;
+  height: number;
+  backgroundColor: string;
+  backdropDismiss: boolean;
+}
+
+export interface NativeUIOverlayEvent {
+  id: string;
+  action: 'dismiss';
+}

package/src/controls/extensions.ts

@@ -0,0 +1,198 @@
+import { readScrollPlacement } from './shared/scroll-placement.js';
+import { fitsClip } from './shared/clipping.js';
+export { projectionAncestors as extensionAncestors } from './shared/clipping.js';
+import type { Candidate, Identify } from './shared/candidate.js';
+import { frame, isDark, visible } from './shared/dom.js';
+import { iconSource, type createIconRenderer } from './shared/icons.js';
+
+export type NativeUIValue = string | number | boolean | null | NativeUIValue[] | { [key: string]: NativeUIValue };
+
+/** Opaque image reference. Return it in props; the shell replaces it with NativeUIImage data before transmission. */
+export type NativeUIImageReference = { readonly $nativeUIImage: string };
+type NativeUIImage = { data: string; width: number; height: number; template: boolean };
+
+export interface NativeUIReadContext {
+  /** Capture a local SVG or resolved ion-icon using the standard renderer. Unsupported artwork returns null. */
+  image(element: SVGElement | HTMLElement | null, options?: { template?: boolean }): NativeUIImageReference | null;
+}
+
+/** An app-local DOM projection. Swift or Kotlin registers its native content under the same name.
+ * @experimental API and behavior may change in future releases.
+ */
+export interface NativeUIExtension {
+  readonly name: string;
+  readonly selector: string;
+  /** Defaults to the source element's frame. Unsupported hosts keep the Web source visible. */
+  readonly placement?: 'element' | 'tab-accessory';
+  /** Experimental iOS native scroll tracking. Return the owning overflow element (Ionic: getScrollElement()).
+   * One untransformed scroll container is supported. Unsupported bindings keep the Web source.
+   * Return null while the container is not ready. Omit to retain JS placement updates.
+   */
+  readonly scrollElement?: (element: HTMLElement) => HTMLElement | null;
+  /** Return null to keep this instance on the Web. Read current source state without side effects. Notify property-only changes with shell.markForCheck(). */
+  readonly read: (
+    element: HTMLElement,
+    context: NativeUIReadContext,
+  ) => {
+    props: { [key: string]: NativeUIValue };
+    /** Click targets must belong to the source element. Null targets are unavailable. */
+    actions?: Record<string, HTMLElement | null>;
+  } | null;
+}
+
+/** Defines a projection locally; it does not start native work or register a Capacitor plugin.
+ * @experimental API and behavior may change in future releases.
+ */
+export const defineNativeUI = <T extends NativeUIExtension>(extension: T): Readonly<T> => Object.freeze({ ...extension });
+
+export const validateExtensions = (extensions: readonly NativeUIExtension[], doc: Document): void => {
+  const names = new Set<string>();
+  for (const extension of extensions) {
+    if (!extension.name.trim() || names.has(extension.name)) throw new Error('Native UI extension names must be nonempty and unique');
+    names.add(extension.name);
+    if (!extension.selector.trim()) throw new Error('Native UI extensions require a selector');
+    doc.querySelector(extension.selector);
+    if (extension.placement && !['element', 'tab-accessory'].includes(extension.placement)) throw new Error('Invalid native UI placement');
+  }
+};
+
+const json = (value: unknown, images: Map<string, NativeUIImage>): string => {
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype)
+    throw new Error('Native UI props must be a JSON object');
+  const result = JSON.stringify(value, (_key, item: unknown) => {
+    if (
+      item === undefined ||
+      typeof item === 'function' ||
+      typeof item === 'symbol' ||
+      (typeof item === 'number' && !Number.isFinite(item)) ||
+      (item !== null && typeof item === 'object' && !Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype)
+    )
+      throw new Error('Native UI props must contain only JSON values');
+    if (item && typeof item === 'object' && '$nativeUIImage' in item) {
+      const image = images.get(item.$nativeUIImage as string);
+      if (!image || Object.keys(item).length !== 1) throw new Error('Invalid native image reference');
+      return image;
+    }
+    return item;
+  });
+  if (!result || result.length > 65536) throw new Error('Native UI props exceed 64K characters');
+  return result;
+};
+
+/** Follow slot assignment too: Ionic scroll containers live inside shadow roots. */
+
+export const readExtension = (
+  element: HTMLElement,
+  extensions: readonly NativeUIExtension[],
+  id: Identify,
+  diagnose: (reason: string) => void = () => {},
+  nativeScroll = false,
+): Candidate | undefined => {
+  const skip = (reason: string): undefined => {
+    diagnose(reason);
+    return undefined;
+  };
+  const matches = extensions.filter((extension) => element.matches(extension.selector));
+  if (matches.length !== 1) return skip('overlapping-selectors: exactly one extension must own this source.');
+  const extension = matches[0];
+  let scrollElement: HTMLElement | null | undefined;
+  if (extension.scrollElement) {
+    if (!nativeScroll || extension.placement === 'tab-accessory') return skip('unsupported-scroll: native scroll tracking is unavailable.');
+    try {
+      scrollElement = extension.scrollElement(element);
+    } catch {
+      return skip('scroll-reader-error: cannot resolve scroll owner.');
+    }
+    if (!scrollElement) return skip('missing-scroll-owner: the scroll element is not ready.');
+  }
+  const scroll = scrollElement ? readScrollPlacement(element, scrollElement, id) : undefined;
+  if (scrollElement && !scroll) return skip('unsupported-scroll: use one untransformed overflow container.');
+  if (!visible(element, !!scroll || extension.placement === 'tab-accessory'))
+    return skip('source-hidden: the source must be visible and inside the viewport.');
+  if (element.closest('ion-modal, ion-popover, ion-menu'))
+    return skip('unsupported-overlay: extension sources inside Web overlays stay on the Web.');
+  if (element.contains(element.ownerDocument.activeElement)) return skip('source-focused: keep the focused Web source until focus leaves.');
+  if (!scroll && extension.placement !== 'tab-accessory' && !fitsClip(element))
+    return skip('source-clipped: the source must fit its clipping ancestors without transformed ancestors.');
+  try {
+    const images: { value: NativeUIImage; source: string }[] = [];
+    const imageValues = new Map<string, NativeUIImage>();
+    let state: ReturnType<NativeUIExtension['read']>;
+    try {
+      state = extension.read(element, {
+        image(owner, options) {
+          if (!owner || !(element.contains(owner) || element.shadowRoot?.contains(owner))) return null;
+          const svg = owner.matches('svg') ? (owner as SVGElement) : owner.shadowRoot?.querySelector<SVGElement>('svg');
+          if (!svg) return null;
+          const source = iconSource(svg);
+          const { width, height } = owner.getBoundingClientRect();
+          if (!source || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+          const value: NativeUIImage = { data: '', width, height, template: options?.template ?? false };
+          const key = String(images.length);
+          images.push({ value, source });
+          imageValues.set(key, value);
+          return { $nativeUIImage: key };
+        },
+      });
+    } catch {
+      return skip('reader-error: the extension reader threw; inspect its implementation.');
+    }
+    if (!state) return skip('reader-opt-out: the reader returned null.');
+    const props = json(state.props, imageValues);
+    const actions = new Map<string, HTMLElement>();
+    const targets: Record<string, string> = {};
+    for (const [name, target] of Object.entries(state.actions ?? {})) {
+      if (!name || (target && !element.contains(target))) return skip('invalid-actions: use named targets inside the source element.');
+      if (
+        !target ||
+        !visible(target, !!scroll || extension.placement === 'tab-accessory') ||
+        (target as HTMLElement & { disabled?: boolean }).disabled ||
+        target.matches(':disabled, [disabled]') ||
+        target.closest('[aria-disabled="true"]') ||
+        getComputedStyle(target).pointerEvents === 'none'
+      )
+        continue;
+      targets[name] = id(target);
+      actions.set(id(target), target);
+    }
+    if (Object.keys(targets).length > 30) return skip('invalid-actions: a source can expose at most 30 actions.');
+    const tabBar =
+      extension.placement === 'tab-accessory'
+        ? Array.from(element.closest('ion-tabs')?.querySelectorAll<HTMLElement>('ion-tab-bar') ?? []).find(
+            (bar) => bar.closest('ion-tabs') === element.closest('ion-tabs'),
+          )
+        : undefined;
+    if (extension.placement === 'tab-accessory' && !tabBar)
+      return skip('missing-tab-owner: a tab accessory needs an owning ion-tabs with ion-tab-bar.');
+    const style = getComputedStyle(element);
+    const control = {
+      id: id(element),
+      kind: 'extension' as const,
+      scroll,
+      ...frame(element.getBoundingClientRect()),
+      items: [],
+      dark: isDark(style),
+      rtl: style.direction === 'rtl',
+      extension: { name: extension.name, props, actions: targets, tabBarId: tabBar ? id(tabBar) : undefined },
+    };
+    return {
+      element,
+      scrollElement: scrollElement ?? undefined,
+      actions,
+      icons: [],
+      control,
+      assets: images.length
+        ? {
+            signature: JSON.stringify(images),
+            async render(renderer: ReturnType<typeof createIconRenderer>) {
+              for (const { value, source } of images) value.data = await renderer.render(source, value.width, value.height);
+              control.extension.props = json(state.props, imageValues);
+            },
+          }
+        : undefined,
+    };
+  } catch {
+    // Keep the source usable without exposing props or application exception data.
+    return skip('invalid-props: return a JSON object with finite values, valid image references, and at most 64K characters.');
+  }
+};

package/src/controls/foldable/fold-state.ts

@@ -0,0 +1,10 @@
+import type { FoldState } from './types.js';
+
+/** @deprecated Import applyFoldStateClasses from @rdlabo/ionic-theme-ios27 instead.
+ * Keep posture on ion-app so descendants can follow it through CSS. */
+export function applyFoldStateClasses(root: HTMLElement, fold: FoldState): void {
+  for (const state of ['flat', 'half-opened', 'closed']) {
+    root.classList.toggle(`ios-theme-fold-${state}`, fold.state === state);
+  }
+  root.classList.toggle('ios-theme-fold-expanded', fold.state === 'half-opened' || (fold.state === 'flat' && !!fold.hingeBounds));
+}

package/src/controls/foldable/types.ts

@@ -0,0 +1,4 @@
+export interface FoldState {
+  state: 'flat' | 'half-opened' | 'closed';
+  hingeBounds?: { x: number; y: number; width: number; height: number };
+}