Pager

import { Pager, PagerOrientation, PagerPage } from '@wearables-ui-toolkit/mrbd';

export function Onboarding({ startPreview }: { startPreview: () => void }) {
  return (
    <Pager
      aria-label="Onboarding"
      orientation={PagerOrientation.HORIZONTAL}
      requestInitialFocusOnMount
    >
      <PagerPage key="welcome">
        <WelcomeStep />
      </PagerPage>
      <PagerPage key="preview" onWillShowPage={startPreview}>
        <PreviewStep />
      </PagerPage>
      <PagerPage key="finish">
        <FinishStep />
      </PagerPage>
    </Pager>
  );
}

import { useState } from 'react';
import { Pager, PagerPage } from '@wearables-ui-toolkit/mrbd';

export function MediaPages({ items }: { items: ReadonlyArray<MediaItem> }) {
  const [pageIndex, setPageIndex] = useState(0);

  return (
    <Pager
      aria-label="Media"
      currentPageIndex={pageIndex}
      onPageChange={nextIndex => setPageIndex(nextIndex)}
    >
      {items.map(item => (
        <PagerPage key={item.id}>
          <MediaDetail item={item} />
        </PagerPage>
      ))}
    </Pager>
  );
}

import { useMemo, useState } from 'react';
import { usePagerPageLifecycle } from '@wearables-ui-toolkit/mrbd';

function DraftPage({ saveDraft }: { saveDraft: () => void }) {
  const [isDirty, setIsDirty] = useState(false);

  usePagerPageLifecycle(
    useMemo(
      () => ({
        shouldPreventNavigation: () => isDirty,
        onWillHidePage: () => saveDraft(),
      }),
      [isDirty, saveDraft],
    ),
  );

  return <DraftEditor onChange={() => setIsDirty(true)} />;
}

• HORIZONTAL
• VERTICAL

• LEFT — horizontal navigation to a higher index
• RIGHT — horizontal navigation to a lower index
• UP — vertical navigation to a higher index
• DOWN — vertical navigation to a lower index
• START — the first page shown when no previous page exists
• BACK — back-to-home navigation

• direction: NavigationDirection
• pageIndex: number
• previousPageIndex: number — -1 when no previous page exists

• pageIndex: number
• previousPageIndex: number — -1 when no previous page exists

• preloadPageIfNeeded(index: number): void — forces the page at index to mount off screen, including when unmountInactivePages is on, and cancels any earlier unloadPage call for the same index. The method ignores out-of-range indices. Consider it only when measured performance supports preloading because eagerly mounting a non-trivial page costs more than mounting it during navigation.
• unloadPage(index: number): void — unmounts the page at index after firing onWillUnloadPage. It throws when the index is out of range or identifies the visible page. The page remains unmounted, even when unmountInactivePages is off, until it becomes current or is preloaded. Navigating back to it mounts it again.
• isNavigationLocked(): boolean — reports whether navigation is currently locked.
• pageCount(): number — reports the number of pages.
• isPageTransitionInProgress(): boolean — reports whether a transition is animating.

• The root is a region with the role description of a carousel. It uses aria-label, or the ariaLabel alias, as its accessible name and otherwise defaults to a generic page-viewer name. Applications should supply a specific name so users can identify the sequence.
• The caller can override role, aria-label, and aria-roledescription. The standard aria-label attribute takes precedence over the ariaLabel alias.
• Each page is a group with the role description of a slide and a label that states its position in the sequence. The page is programmatically focusable so it can receive focus even when it contains no focusable controls.
• Non-current pages are inert and aria-hidden, which keeps focus and assistive technology within the visible page.
• The peek scrim is decorative and hidden from assistive technology.

• Give every page a stable React key so lifecycle registration follows the intended page.
• Keep application page state and any separate pagination indicator synchronized with the pager. Pager does not persist its index in browser history, and PageTransition does not capture pager position. If the current page must survive leaving and returning to a route, control currentPageIndex and store it outside the route component.
• Prefer PagerPage for static lifecycle behavior and usePagerPageLifecycle for callbacks that depend on state or refs inside the page.
• Let the pager place initial focus. Override placement through onRequestInitialFocus when the page has a more appropriate target.
• Name the pager with aria-label so assistive technology announces a specific sequence rather than a generic page viewer.

• Avoid nesting a same-axis carousel or scroll region in a pager unless the directional interaction remains unambiguous.
• Do not rely on shouldPreventNavigation to block a controlled index change; controlled navigation bypasses the page veto by contract.
• When Back should return home, set homeIndex and keep useBackButtonForHome on. Verify both system Back on the device and Escape during desktop testing.
• Consider preloadPageIfNeeded only after measuring a loading or transition issue rather than using it as a default performance measure.
• Do not call unloadPage for the visible page because the method throws.