@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/src/interfaces/ComponentEvents.ts

@@ -0,0 +1,214 @@
+// The events the native side sends for a screen, as the JavaScript side receives them (`ANN.<Name>`). Each carries the
+// id of the screen as `componentId`; the public events give it to the app as `screen: { id, name }`.
+
+/**
+ * What a component that appears is. The three appearance events are sent for screens and for the React components of
+ * the bars; the app is told only about screens.
+ */
+export type ComponentType =
+  'Component' | 'TopBarTitle' | 'TopBarButton' | 'TopBarBackground' | 'BottomTabItem';
+
+/** The fields every appearance event has. */
+interface ComponentAppearanceEvent {
+  /** The id of the component: the screen, or the screen the bar component belongs to. */
+  componentId: string;
+  /** The name of the component: for a screen, its name without any internal prefix. */
+  componentName: string;
+  /**
+   * What the component is. `'Component'` is a screen; the other values are the React components set in the options of
+   * a bar (`BottomTabItem` on Android only).
+   */
+  componentType: ComponentType;
+}
+
+/**
+ * A screen starts to appear: its transition has begun. At most one is sent per appearance, after the content of the
+ * screen is drawn or the wait for it has ended.
+ */
+export interface ComponentWillAppearEvent extends ComponentAppearanceEvent {}
+
+/** A screen is in place: its transition has ended. At most one is sent per appearance. */
+export interface ComponentDidAppearEvent extends ComponentAppearanceEvent {}
+
+/**
+ * A screen disappeared: another screen covers it, or it left. It is sent only for a screen that had appeared, and it
+ * also makes the navigation state recalculate.
+ */
+export interface ComponentDidDisappearEvent extends ComponentAppearanceEvent {}
+
+/**
+ * A screen left its stack, by any means: the back button, a swipe, `pop`, `popTo`, `popToRoot`, a new stack root, or
+ * a tab left with `popToRootOnBlur`. It is sent before the content of the screen stops, once for each screen that
+ * left (for both screens of a pair). A cancelled swipe sends nothing.
+ */
+export interface ScreenPoppedEvent {
+  /** The id of the screen that left. */
+  componentId: string;
+}
+
+/**
+ * A button was pressed. The sources are the buttons of the bar and of the toolbar, the items of their menus, the item
+ * of the title menu (iOS), the back button when it is set not to pop, a swipe back with
+ * `navigationButtonEventOnSwipeBack` (iOS), the hardware back in a modal that stays open (Android) and the items of
+ * the menu of a preview (iOS).
+ */
+export interface NavigationButtonPressedEvent {
+  /** The id of the screen whose button it is: the visible screen, and for a pair its primary. */
+  componentId: string;
+  /**
+   * The id of the button or of the menu item. The back button has the id set in `topBar.backButton.id`, or
+   * `ApexNavigation.back`; the hardware back of a modal has `ApexNavigation.hardwareBackButton`.
+   */
+  buttonId: string;
+  /** (iOS) For a button with `toggle`: its new state, already written into the options of the screen. */
+  selected?: boolean;
+}
+
+/**
+ * A modal went away, however it was closed: a command, a swipe, the hardware back, a tap on the dimmed area of a
+ * sheet or outside a popover. Closing every modal at once sends one event with their count. Replacing the root and
+ * reloading JavaScript send none.
+ */
+export interface ModalDismissedEvent {
+  /** The id of the visible screen of the modal (of the topmost modal when several were closed). */
+  componentId: string;
+  /** The name of that screen. */
+  componentName: string;
+  /** How many modals were closed. */
+  modalsDismissed: number;
+}
+
+/**
+ * The user tried to dismiss a modal whose `modal.swipeToDismiss` is `false`: a swipe down on a sheet, or a tap on the
+ * dimmed area or outside a popover. The modal stays. The hardware back button of Android sends a button event
+ * instead.
+ */
+export interface ModalAttemptedToDismissEvent {
+  /** The id of the visible screen of the modal. */
+  componentId: string;
+}
+
+/**
+ * The user dragged a sheet to another detent. A change made through `mergeOptions` is not reported.
+ */
+export interface SheetDetentChangedEvent {
+  /** The id of the visible screen of the modal. */
+  componentId: string;
+  /**
+   * The detent the sheet stopped at: `'medium'`, `'large'`, or a height (points on iOS, dp on Android). `'content'`
+   * is sent on iOS for a detent that fits the content; Android names such a detent `'medium'`.
+   */
+  detent: 'medium' | 'large' | 'content' | number;
+}
+
+/**
+ * The text, the focus or the scope of a search field changed, or a token was removed from it. Changes made through
+ * `mergeOptions` are not reported. The screen and its results component each get the event.
+ */
+export interface SearchBarUpdatedEvent {
+  /** The id of the screen with the search field. */
+  componentId: string;
+  /** The text in the field. */
+  text: string;
+  /** Whether the field has the focus. */
+  isFocused: boolean;
+  /** The id of the selected scope filter. Set only when the field has a scope bar. */
+  scope?: string;
+  /** (iOS) The ids of the tokens in the field. Set only when the field uses tokens. */
+  tokens?: string[];
+}
+
+/** The search key of the keyboard was pressed. The keyboard hides; the text and the results stay. */
+export interface SearchBarSubmittedEvent {
+  /** The id of the screen with the search field. */
+  componentId: string;
+  /** The text in the field. */
+  text: string;
+  /** The id of the selected scope filter. Set only when the field has a scope bar. */
+  scope?: string;
+  /** (iOS) The ids of the tokens in the field. Set only when the field uses tokens. */
+  tokens?: string[];
+}
+
+/**
+ * The search was cancelled: the Cancel button (iOS), or closing the search with the arrow or the back button
+ * (Android, followed by a search update).
+ */
+export interface SearchBarCancelPressedEvent {
+  /** The id of the screen with the search field. */
+  componentId: string;
+}
+
+/** (iOS 16+, Android) The user picked a suggestion of `searchBar.suggestions`. The text stays. */
+export interface SearchSuggestionPickedEvent {
+  /** The id of the screen with the search field. */
+  componentId: string;
+  /** The id of the suggestion that was picked. */
+  suggestionId: string;
+}
+
+/**
+ * (iOS 16+) The user renamed the title with the Rename item of the title menu (`topBar.title.rename`). The title text
+ * of the screen already is the new one. An empty name restores the old title and sends nothing.
+ */
+export interface TitleRenamedEvent {
+  /** The id of the screen whose title was renamed. */
+  componentId: string;
+  /** The new title. */
+  text: string;
+}
+
+/**
+ * (iOS 26+) The system moved the accessory above the tabs. It is sent when the accessory is first shown and on each
+ * change of its place, never twice for the same place.
+ */
+export interface BottomAccessoryPlacementChangedEvent {
+  /** The id of the accessory component (`bottomTabs.bottomAccessory.component`). */
+  componentId: string;
+  /** Where the accessory is: above the tab bar (`'regular'`) or beside the collapsed tab bar (`'inline'`). */
+  placement: 'regular' | 'inline';
+}
+
+/** (iOS) A key command of a screen was pressed on a hardware keyboard. */
+export interface KeyCommandPressedEvent {
+  /** The id of the screen that has the key command. */
+  componentId: string;
+  /** The id of the key command, as set in the `keyCommands` of the screen. */
+  keyCommandId: string;
+}
+
+/**
+ * (iOS) The user pressed the preview of a pushed screen (the context menu of `usePreview`). It is sent before the
+ * push. If the preview is to be committed and the source screen is still in its stack, the preview screen is pushed
+ * afterwards.
+ */
+export interface PreviewCompletedEvent {
+  /** The id of the screen the preview was opened from. */
+  componentId: string;
+  /** The id of the screen of the preview. */
+  previewComponentId: string;
+}
+
+/** The modes a split view can show its columns in. */
+export type SplitViewDisplayMode =
+  | 'automatic'
+  | 'secondaryOnly'
+  | 'oneBesideSecondary'
+  | 'oneOverSecondary'
+  | 'twoBesideSecondary'
+  | 'twoOverSecondary'
+  | 'twoDisplaceSecondary';
+
+/**
+ * (iOS) The display mode of a split view changed: the user used the button of the sidebar or swiped, the width
+ * changed, or `mergeOptions` set a mode. It is also sent at the first layout, and when the inspector shows or hides.
+ * The same state is not sent twice.
+ */
+export interface SplitViewDisplayModeChangedEvent {
+  /** The id of the split view. */
+  componentId: string;
+  /** The mode the columns are shown in. */
+  displayMode: SplitViewDisplayMode;
+  /** (iPadOS 26+) Whether the inspector column is visible. Set only for a split view that has an inspector. */
+  inspectorVisible?: boolean;
+}

package/src/interfaces/Events.ts

@@ -0,0 +1,227 @@
+// The events the native side sends that are not tied to one screen's content, or that name a container, as the
+// JavaScript side receives them (`ANN.<Name>`). The events of a screen are in `ComponentEvents.ts`.
+
+/**
+ * The native side is ready for JavaScript to start the app. It carries no data. JavaScript answers by setting the
+ * default options and the root. It is sent after each bundle load, after a reload, and (Android) for each new
+ * activity.
+ */
+export type AppLaunchedEvent = Record<string, never>;
+
+/** The commands that report their completion with `CommandCompletedEvent`. */
+export type CompletedCommandName =
+  | 'setRoot'
+  | 'push'
+  | 'pop'
+  | 'popTo'
+  | 'popToRoot'
+  | 'setStackRoot'
+  | 'showInColumn'
+  | 'showModal'
+  | 'dismissModal'
+  | 'dismissAllModals'
+  | 'showOverlay'
+  | 'dismissOverlay'
+  | 'dismissAllOverlays';
+
+/**
+ * A command finished successfully. It is sent after the promise of the command resolved, never for a command that was
+ * refused. The library itself does not listen to it: it is for external tools, such as end-to-end tests and latency
+ * measurements.
+ */
+export interface CommandCompletedEvent {
+  /** The name of the command. */
+  commandName: CompletedCommandName;
+  /** The id of this call of the command. */
+  commandId: string;
+  /** When the command finished, in milliseconds since the Unix epoch. */
+  completionTime: number;
+}
+
+/**
+ * What the user sees changed. It is sent only when the state differs from the last one sent, and before the promise of
+ * a command that changed it resolves.
+ */
+export interface NavigationStateChangedEvent {
+  /**
+   * The visible screen with its name in `screens`, or `null` when there is none. In a container the visible screen is
+   * the one it shows.
+   */
+  screen: { id: string; name: string } | null;
+  /** The index of the selected tab of the nearest tabs around the visible screen, or `null` outside tabs. */
+  tab: number | null;
+}
+
+/**
+ * A tab was selected by the user: a press on the tab, a pick from the "More" list or a press on "More" that showed a
+ * tab (iOS). It is sent after the selection, and only when the tab changed; a press on the current tab is reported by
+ * `BottomTabPressedEvent` alone. Selecting a tab from code sends nothing.
+ */
+export interface BottomTabSelectedEvent {
+  /** The index of the tab that is now selected. */
+  selectedTabIndex: number;
+  /** The index of the tab that was selected before. */
+  unselectedTabIndex: number;
+  /** The id of the tabs. */
+  bottomTabsId: string;
+}
+
+/**
+ * A tab was pressed, the selected one too. It is sent before the tab is selected; with `selectTabOnPress: false` it is
+ * the only thing that happens. A long press sends `BottomTabLongPressedEvent` instead.
+ */
+export interface BottomTabPressedEvent {
+  /** The index of the tab that was pressed. */
+  tabIndex: number;
+  /** The id of the tabs. */
+  bottomTabsId: string;
+  /** The id of the screen the tab shows: the top of its stack. */
+  screenId?: string;
+  /** Whether the tab was the selected one already; a press on the selected tab scrolls its content to the top. */
+  wasSelected: boolean;
+}
+
+/**
+ * A tab was pressed and held. The tab is not selected and gets no press event. On iOS it is not sent for the tabs
+ * that are components (`bottomTab.component`, `bottomTabs.customRow`), for "More", or for the tab strip at the top of an
+ * iPad. On Android it replaces the tooltip of the tab.
+ */
+export interface BottomTabLongPressedEvent {
+  /** The index of the tab that was pressed. */
+  selectedTabIndex: number;
+  /** The id of the tabs. */
+  bottomTabsId: string;
+}
+
+/**
+ * Whether the columns of a split view are shown as one stack, one over the other: on iOS a split view collapsed
+ * without a compact layout, on Android the sliding pane. It is sent when the split view enters the window or is first
+ * laid out, and on each change.
+ */
+export interface SplitViewColumnsStackedEvent {
+  /** The id of the split view. */
+  componentId: string;
+  /** Whether the columns are shown as one stack. */
+  stacked: boolean;
+}
+
+/**
+ * A screen of the single React tree was destroyed and the slot still belongs to it: JavaScript removes the slot from
+ * its tree. It is not sent for a prepared screen that was never pushed, nor when JavaScript reloads.
+ */
+export interface SlotDestroyedEvent {
+  /** The id of the screen that owned the slot. */
+  componentId: string;
+}
+
+/**
+ * The distances by which the bars and the system cover the content of a screen on each side, in points on iOS and dp
+ * on Android: what the safe area view of the screen did not already take off. It is sent after the screen is laid out
+ * and on each change, never twice with the same values. The same values are read synchronously with
+ * `getScreenInsets`.
+ */
+export interface ScreenInsetsChangedEvent {
+  /** The id of the screen. */
+  componentId: string;
+  /** The distance at the top. */
+  top: number;
+  /** The distance at the right. */
+  right: number;
+  /** The distance at the bottom. */
+  bottom: number;
+  /** The distance at the left. */
+  left: number;
+}
+
+/** A rectangle in the coordinates of a screen. */
+export interface ScreenRegionRect {
+  /** The distance of its left edge from the left edge of the screen. */
+  x: number;
+  /** The distance of its top edge from the top edge of the screen. */
+  y: number;
+  /** Its width. */
+  width: number;
+  /** Its height. */
+  height: number;
+}
+
+/**
+ * The parts of a screen that the device divides or covers, only those inside the screen. It is sent when they change.
+ * The same values are read synchronously with `getScreenRegions`. On iOS it needs iOS 27.1; Android takes the folds
+ * from the window.
+ */
+export interface ScreenRegionsChangedEvent {
+  /** The id of the screen. */
+  componentId: string;
+  /** The folds, without margins. */
+  division: ScreenRegionRect[];
+  /** The areas covered by a camera or anything else that hides part of the screen. */
+  occlusion: ScreenRegionRect[];
+}
+
+/**
+ * How the screens of a pair are shown. It is sent for a screen of a pair when this changes. The same state is read
+ * synchronously with `getArrangementState`.
+ */
+export interface ArrangementChangedEvent {
+  /** The id of the screen of the pair. */
+  componentId: string;
+  /** Which part of the pair the screen is. */
+  placement: 'primary' | 'secondary';
+  /** How the pair lies: side by side, one over the other, one over the other as an overlay, or only one of them. */
+  layout: 'sideBySide' | 'stacked' | 'overlay' | 'single';
+  /** Whether the screen is in front. */
+  front: boolean;
+  /** Whether the screen is hidden. */
+  hidden: boolean;
+}
+
+/** The state of the hinge of a foldable device. */
+export type HingeState = 'closed' | 'partiallyOpen' | 'fullyOpen' | 'unknown';
+
+/**
+ * The hinge of the device changed. It is sent only while JavaScript has turned hinge updates on, each value once. An
+ * empty event means the device has no hinge, or it is no longer known.
+ */
+export interface HingeChangedEvent {
+  /**
+   * The state of the hinge. On Android `closed` means the device has no fold, or its angle is below 90 degrees.
+   */
+  state?: HingeState;
+  /**
+   * The angle of the hinge in degrees (on iOS to tenths). Missing when the state is `unknown` and where the system
+   * gives no angle.
+   */
+  angle?: number;
+}
+
+/**
+ * A native screen calls into JavaScript: a function among its props, or a navigation command made from the screen.
+ * JavaScript answers with `resolveNativeScreenCall`, with a value or an error. A call made while the navigation is not
+ * running fails at once; one pending when JavaScript reloads fails with `JavaScript reloaded`.
+ */
+export interface NativeScreenCallEvent {
+  /** The id of the native screen that makes the call. */
+  componentId: string;
+  /** The id of the call, to answer it. */
+  callId: string;
+  /** What is called: a function of the props, or a navigation command. */
+  kind: 'function' | 'command';
+  /**
+   * The name of the function, or of the command: `push`, `pop`, `popTo`, `popToRoot`, `showInColumn`, `showModal`,
+   * `dismiss`, `showOverlay`, `setOptions`, `selectTab` or `setTabBadge`.
+   */
+  name: string;
+  /** The arguments of the call. */
+  args: unknown[];
+}
+
+/**
+ * A native screen left the layout, however it left: back, a swipe, a closed modal, a new root, or (Android) the
+ * activity going away. It is sent once; JavaScript lets go of the hook and the functions of the screen. It is not sent
+ * when JavaScript reloads.
+ */
+export interface NativeScreenReleasedEvent {
+  /** The id of the native screen. */
+  componentId: string;
+}

package/src/interfaces/Layout.ts

@@ -0,0 +1,161 @@
+// The layout tree as the public builders (`Root`, `Stack`, `Tabs`, `Screen`, `SideMenu`, `SplitView`) produce it and
+// as the app can also write it by hand. The engine turns it into the JSON nodes the native side reads
+// (`src/engine/layout.ts`); these types are not that JSON.
+import type { Options } from './Options';
+
+/**
+ * A screen of the app, a React Native one: the name it has in `screens`, the props it gets, and the options of this
+ * show.
+ */
+export interface LayoutComponent {
+  /**
+   * The id of the screen, to address it in commands and events. Without it, the library gives the screen one. An id
+   * names one screen in the whole app at a time: a layout that gives it twice, or a command that shows a screen
+   * under the id of one that is already shown elsewhere, is refused.
+   */
+  id?: string;
+  /** The name of the screen in `screens`. A name that is not there is refused before anything is sent. */
+  name: string;
+  /**
+   * The props the screen gets. They stay in JavaScript, under the id of the screen; the native side never sees them.
+   */
+  passProps?: object;
+  /** The options of this show of the screen, over its own options and under those of its containers. */
+  options?: Options;
+}
+
+/**
+ * A screen the app creates in native code and registered under a name. The native side makes it through the creator
+ * registered for the name.
+ */
+export interface ExternalComponent {
+  /** The id of the screen. Without it, the library gives the screen one. */
+  id?: string;
+  /** The name the screen is registered under on the native side; it need not be a name in `screens`. */
+  name: string;
+  /**
+   * The props the native screen gets, as JSON: functions are dropped from the data (the native screen calls them by
+   * name), `undefined` values are left out and dates become strings.
+   */
+  passProps?: object;
+  /** The options of the screen: its bar, its buttons, as for a React screen. */
+  options?: Options;
+}
+
+/**
+ * A stack of screens. The last child shows; going back reveals the one before it. A stack takes screens only, a
+ * container inside a stack is refused.
+ */
+export interface LayoutStack {
+  /** The id of the stack. Without it, the library gives the stack one. */
+  id?: string;
+  /**
+   * The screens from the bottom up. A stack without screens is refused by the native side. The screens under the
+   * last one are created at once, but they are shown and drawn only when they are reached.
+   */
+  children?: LayoutStackChildren[];
+  /** The options of the stack: defaults for its screens, such as their bar or their animations. */
+  options?: Options;
+}
+
+/**
+ * What a stack holds: a screen, React Native or native. It is a layout that sets one of the two screen keys.
+ */
+export type LayoutStackChildren = Pick<Layout, 'component' | 'externalComponent'>;
+
+/**
+ * A set of bottom tabs. Each child is a tab. The tab bar button is built from the `bottomTab` options of the child
+ * and of its screens.
+ */
+export interface LayoutBottomTabs {
+  /**
+   * The id of the tabs, named by `bottomTabsId` in the tab events. Without it, the library gives the tabs one. The
+   * commands that act on a tab take the id of the tab itself, not this one.
+   */
+  id?: string;
+  /**
+   * The tabs in order: the index of a child is the index of its tab in events and options. A stack, a screen, or a
+   * side menu fits a tab. Android shows at most 5 tabs and refuses a layout with more; iOS shows the tabs after the
+   * fourth under "More" on an iPhone. Tabs without children are refused by the native side.
+   */
+  children?: Layout[];
+  /** The options of the tabs, such as the tab to show first (`bottomTabs.currentTabIndex`, `currentTabId`). */
+  options?: Options;
+}
+
+/**
+ * A side menu: a center and, at its sides, up to two menus.
+ */
+export interface LayoutSideMenu {
+  /** The id of the side menu. Without it, the library gives the menu one. */
+  id?: string;
+  /** The content of the menu at the left (leading) edge. Without it, there is no menu on that side. */
+  left?: Layout;
+  /** The content that the menus belong to. A side menu cannot be built without it. */
+  center: Layout;
+  /** The content of the menu at the right (trailing) edge. Without it, there is no menu on that side. */
+  right?: Layout;
+  /** The options of the side menu: its visibility, widths and gestures. */
+  options?: Options;
+}
+
+/**
+ * A split view: columns side by side, or one over the other when the window is narrow. `master` and `detail` are
+ * required; a layout without them is refused.
+ */
+export interface LayoutSplitView {
+  /** The id of the split view. Without it, the library gives the split view one. */
+  id?: string;
+  /** The primary column. */
+  master: Layout;
+  /** The secondary column, the one that shows the content of the item chosen in the primary. */
+  detail: Layout;
+  /** (iOS) The middle column. A split view with it has three columns. */
+  supplementary?: Layout;
+  /**
+   * What an iPhone, a narrow window and a narrow Android screen show in place of the columns. Without it, the
+   * columns collapse by the rules of the platform.
+   */
+  compact?: Layout;
+  /** (iPadOS 26+) The column at the trailing edge. Android has no such column and ignores it. */
+  inspector?: Layout;
+  /** The options of the split view: its display mode, column widths and buttons. */
+  options?: Options;
+}
+
+/**
+ * One node of a layout: exactly one of its keys is set, and it names the kind of the node. A layout with none of them
+ * is refused before it is sent.
+ */
+export interface Layout {
+  /** A React Native screen. */
+  component?: LayoutComponent;
+  /** A screen created in native code. */
+  externalComponent?: ExternalComponent;
+  /** A stack of screens. */
+  stack?: LayoutStack;
+  /** Bottom tabs. */
+  bottomTabs?: LayoutBottomTabs;
+  /** A side menu. */
+  sideMenu?: LayoutSideMenu;
+  /** A split view. */
+  splitView?: LayoutSplitView;
+}
+
+/**
+ * The layout of the whole app: what `setRoot` takes. A modal or an overlay is not a kind of node: any node becomes
+ * one when it is listed under `modals` or `overlays`.
+ */
+export interface LayoutRoot {
+  /** The root of the app. It replaces the previous one. */
+  root: Layout;
+  /**
+   * The modals to show over the root once it is in place, in order, each over the one before. Only the last one is
+   * animated; the ones under it come at once. Without it, none.
+   */
+  modals?: Layout[];
+  /**
+   * The overlays to show after the modals, one by one. Overlays shown before the new root stay. Without it, none.
+   */
+  overlays?: Layout[];
+}