@rdlabo/capacitor-native-ui 0.0.0-stage → 1.2.1

package/src/native/definitions.ts

@@ -0,0 +1,324 @@
+import type { NativeUIExtension } from './extensions';
+import type { PluginListenerHandle } from '@capacitor/core';
+
+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;
+}
+
+export interface ToolbarProjectionOptions {
+  /** Group selected actions; never selects children or back buttons. Defaults to true. */
+  buttons?: boolean;
+  /** Automatically select ordinary actions, inside or outside groups. Defaults to true. */
+  button?: boolean;
+  /** Automatically select back navigation independently of groups. Defaults to true. */
+  backButton?: boolean;
+}
+
+export interface VerticalControlAreaOptions {
+  /** App-local DOM readers with matching SwiftUI or Compose registrations.
+   * @experimental API and behavior may change in future releases.
+   */
+  extensions?: readonly NativeUIExtension[];
+  /** Opt-in popovers anchored to native Vertical Bars buttons. */
+  controls?: Pick<NativeUIControls, 'popover'>;
+  /** Ordinary horizontal toolbar selection/grouping. true enables all three options; false disables them.
+   * Object fields default to true. Local data-horizontal-bars overrides still apply.
+   * Only enableNativeUI projects horizontal controls.
+   */
+  horizontal?: boolean | ToolbarProjectionOptions;
+  /** Vertical toolbar selection/grouping. true enables all three options; false disables them.
+   * Object fields default to true. Local data-vertical-bars overrides still apply.
+   * Neither layout setting controls tabs, segments or FABs.
+   */
+  vertical?: boolean | ToolbarProjectionOptions;
+  /** Appearance of native vertical ion-button and ion-menu-button actions.
+   * `system` (default) uses SwiftUI styling and template icons; `source` projects supported Ionic fill and colors.
+   * Local data-projection="source|system" or ios-theme-projection-source / ios-theme-projection-system take precedence:
+   * the button itself, then its nearest ion-buttons, then this option. On the same element, a valid attribute wins;
+   * otherwise system wins if both classes are present. Invalid attribute values are ignored.
+   * Local settings update live; removing them restores inheritance. Actions, disabled state and grouping are preserved.
+   * Does not affect back buttons, tabs, FABs, horizontal controls, source elements or Web clones.
+   */
+  buttonProjection?: 'source' | 'system';
+  /** Default fill for native vertical ion-button actions resolved to `source`, including local overrides.
+   * Use `solid` for Ionic's default design, or `null` (also the omitted default) for the iOS theme's glass design.
+   * Applies when fill is omitted or `default`, outside ion-buttons. Inside ion-buttons the default is clear.
+   * Explicit clear, solid and outline take precedence; clear and outline cannot be configured as defaults.
+   * Source elements and Web clones are unchanged.
+   */
+  buttonDefaultFill?: 'solid' | null;
+}
+
+export interface NativeUIOptions extends VerticalControlAreaOptions {
+  /** Log Web fallback reasons and their source elements once per reason during this activation. Defaults to false. */
+  debug?: boolean;
+  verticalBars?: NativeUIVerticalBarsOptions;
+  /** Ionic adapter settings. Explicit data-native-ui sources and extensions remain independent. */
+  ionic?: IonicProjectionOptions;
+  /** Source subtree. Defaults to document.body. */
+  root?: HTMLElement;
+  /** @deprecated Call destroy() on the running handle to stop the shell. */
+  enabled?: boolean;
+  /** @deprecated Use ionic.auto for automatic Ionic projection and verticalBars.popover for popovers. */
+  controls?: NativeUIControls;
+  /** @deprecated Use verticalBars.only. */
+  verticalBarsOnly?: boolean;
+}
+
+/** @internal Resolved adapter state; not an application configuration API. */
+export interface NativeUIRuntimeOptions extends NativeUIOptions {
+  source?: 'ionic' | 'html' | 'auto' | 'extensions';
+  /** @internal Preserves legacy controls.buttons behavior for explicit sources. */
+  explicitControls?: boolean;
+  nativeState?: { edge?: 'left' | 'right' };
+  /** @internal Keep unavailable definitions discoverable for diagnostics without calling their readers. */
+  unavailableExtensions?: ReadonlyMap<string, string>;
+  rail?: { host: HTMLElement; edge: 'left' | 'right' };
+}
+
+export interface IonicProjectionOptions {
+  /** Automatic Ionic projection. Defaults to true; partial objects keep omitted kinds enabled. */
+  auto?: boolean | AutoIonicControls;
+}
+
+export interface AutoIonicControls {
+  buttons?: boolean;
+  tabs?: boolean;
+  segment?: boolean;
+  fab?: boolean;
+}
+
+export interface NativeUIControls {
+  /** Toolbar actions and explicitly marked HTML buttons. Defaults to true. */
+  buttons?: boolean;
+  /** Projects tab bars and their native search presentation. */
+  tabs?: boolean;
+  /** @deprecated Use buttons. Projects toolbar buttons, including back and menu buttons. */
+  toolbar?: boolean;
+  /** Projects segments. */
+  segment?: boolean;
+  /** Projects floating action buttons. */
+  fab?: boolean;
+  /** Relays popovers anchored to native Vertical Bars buttons. Defaults to false. */
+  popover?: boolean;
+}
+
+/** 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;
+  /** Project only rail controls; unavailable or disabled rails leave controls on the Web. */
+  only?: boolean;
+  buttonProjection?: 'system' | 'source';
+  /** Source-style standalone buttons with no explicit fill. Defaults to glass. */
+  buttonDefaultFill?: 'glass' | 'solid';
+  /** Ionic popover relay. Defaults to false. */
+  popover?: 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 projected controls to the Web until the returned lease is resumed. */
+  suspend(): 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;
+}
+
+export interface NativeUIBadge {
+  value: string;
+  color: string;
+  textColor: string;
+}
+
+export interface NativeUIItem extends Frame {
+  id: 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';
+
+export interface NativeUIControl extends Frame {
+  id: string;
+  kind: NativeUIControlKind | 'extension';
+  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;
+  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 {
+  revision: number;
+  transitionDuration?: number;
+  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;
+  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;
+}
+
+export interface NativeUIPlugin {
+  configure(options?: { verticalBarsOnly?: boolean }): Promise<{ supported: boolean; extensions?: string[] }>;
+  completeExtensionAction(options: { requestId: string; accepted: boolean }): Promise<void>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
+  getVerticalBarsGeometry(options: { viewportWidth: number; ids: string[] }): Promise<{ revision?: number; items: Record<string, Frame> }>;
+  prepareOverlay(options: { id: string }): Promise<void>;
+  presentOverlay(options: { id: string; presentation?: NativeUIPopoverPresentation }): Promise<void>;
+  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[] }>;
+  clear(options: { revision: number }): Promise<void>;
+  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/native/extensions.ts

@@ -0,0 +1,176 @@
+import { fitsClip } from './shared/clipping';
+export { projectionAncestors as extensionAncestors } from './shared/clipping';
+import type { Candidate, Identify } from './shared/candidate';
+import { frame, isDark, visible } from './shared/dom';
+import { iconSource, type createIconRenderer } from './shared/icons';
+
+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';
+  /** 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 = () => {},
+): 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.');
+  if (!visible(element)) 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.');
+  const extension = matches[0];
+  if (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) ||
+        (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,
+      ...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,
+      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/native/foldable/fold-state.ts

@@ -0,0 +1,10 @@
+import type { FoldState } from './types';
+
+/** @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/native/foldable/types.ts

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