@multiplatform.one/components 7.79.0 → 7.80.0

package/src/appShell/AppShell.stories.tsx

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import {
+  GearIcon,
+  HouseIcon,
+  LightningIcon,
+  SparkleIcon,
+  SquaresFourIcon,
+  StackIcon,
+} from "@phosphor-icons/react";
+import { useState } from "react";
+import { XStack, YStack } from "tamagui";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { PageBarButton, PageHeader, PageSection, Screen } from "../layouts/page";
+import { Pagination } from "../Pagination";
+import { Text } from "../Text";
+import { AppShell, type AppShellDestination } from "./AppShell";
+
+const destinations: AppShellDestination[] = [
+  { key: "/", label: "Home", icon: HouseIcon },
+  { key: "/pokemon", label: "Pokemon", icon: SparkleIcon },
+  { key: "/moves", label: "Moves", icon: LightningIcon },
+  { key: "/backoffice", label: "Backoffice", icon: SquaresFourIcon },
+  { key: "/settings", label: "Settings", icon: GearIcon, placement: "more" },
+];
+
+function Mark() {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack
+      width="$2"
+      height="$2"
+      borderRadius="$3"
+      backgroundColor="$color4"
+      alignItems="center"
+      justifyContent="center"
+    >
+      <StackIcon size={knobProps.controlIcon.width} weight="bold" />
+    </YStack>
+  );
+}
+
+function DemoPage({ path, open }: { path: string; open: (path: string) => void }) {
+  const pushed = path.split("/").filter(Boolean).length > 1;
+  const name = destinations.find((item) => path.startsWith(item.key) && item.key !== "/");
+  const title = pushed ? "Pikachu" : (name?.label ?? "Home");
+  return (
+    <Screen>
+      <PageHeader title={title} subtitle={pushed ? "#025 · Electric" : "1,025 entries"} />
+      <PageSection title="Recent">
+        {Array.from({ length: 14 }, (_, index) => (
+          <XStack key={index} alignItems="center" minHeight="$4">
+            <Text flexGrow={1}>Row {index + 1}</Text>
+            {pushed ? null : (
+              <Button
+                size="$3"
+                chromeless
+                onPress={() => open(`${path === "/" ? "" : path}/pikachu`)}
+              >
+                Open
+              </Button>
+            )}
+          </XStack>
+        ))}
+      </PageSection>
+    </Screen>
+  );
+}
+
+function Demo({ initialPath, accessory }: { initialPath: string; accessory?: boolean }) {
+  const [path, setPath] = useState(initialPath);
+  return (
+    <AppShell
+      destinations={destinations}
+      path={path}
+      onNavigate={setPath}
+      onBack={setPath}
+      title="multiplatform.one"
+      logo={<Mark />}
+      actions={<PageBarButton aria-label="Theme" icon={GearIcon} edge="end" />}
+      accessory={accessory ? <Pagination total={41} defaultPage={1} variant="dots" /> : undefined}
+      ownChrome={["/backoffice"]}
+    >
+      <DemoPage path={path} open={setPath} />
+    </AppShell>
+  );
+}
+
+/**
+ * The composed app frame (LC-175). Size class follows the viewport: below
+ * `md` the phone frame (nav bar, content, bottom accessory, tab bar), above
+ * it the split frame (sidebar of destinations beside the content column).
+ */
+const meta: Meta<typeof AppShell> = {
+  title: "Components/AppShell",
+  component: AppShell,
+  parameters: { layout: "fullscreen", status: { type: "beta" } },
+};
+
+export default meta;
+type Story = StoryObj<typeof AppShell>;
+
+/** A tab root: the mark leads, the large title sits in the page, tabs below. */
+export const TabRoot: Story = { render: () => <Demo initialPath="/pokemon" /> };
+
+/** A pushed route: tinted back to the destination, its tab still selected. */
+export const Pushed: Story = { render: () => <Demo initialPath="/pokemon/pikachu" /> };
+
+/** A page that hands the shell a bottom accessory: the tab bar floats it above itself. */
+export const WithAccessory: Story = {
+  render: () => <Demo initialPath="/pokemon" accessory />,
+};

package/src/appShell/AppShell.tsx

@@ -0,0 +1,526 @@
+/**
+ * AppShell — the one composed app frame every MPO app mounts at its root
+ * (LC-175 MPO-ONLY-REUSE). An app declares its destinations and hands over
+ * the current path; the shell draws the rest:
+ *
+ * - compact (phone): the nav bar on top (UINavigationBar: tinted back on a
+ *   pushed route, the page's large title collapsing into it, trailing
+ *   actions), the routed content, and the `tab` destinations in TabHost
+ *   (FZ-8105): the system tab bar where the binary has one, the floating
+ *   MPO TabBar (LC-150) elsewhere. The bar publishes the height it covers,
+ *   which a Screen pads its content by. `more` destinations open from a
+ *   pull-down in the bar.
+ * - regular (tablet, desktop): MPO's Sidebar on the translucent chrome
+ *   material with the app's name, every destination and the app's actions
+ *   at its foot (UISplitViewController's sidebar), the content centred at a
+ *   readable width, and a page's panel stacked under the sidebar's rows
+ *   (LC-101 ONE-SIDEBAR).
+ *
+ * A route listed in `ownChrome` mounts its own full chrome (a desk), so the
+ * shell draws nothing around it. A page whose `Screen` pins its own top bar
+ * (LC-157) owns the nav bar on a phone, so the shell's bar steps aside there.
+ */
+import { zIndex } from "@multiplatform.one/forms";
+import { isWeb } from "@multiplatform.one/platform";
+import {
+  MIN_PRESS_TARGET,
+  Surface,
+  hairline,
+  transitionProps,
+  useLayoutSizeClass,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import { ListIcon } from "@phosphor-icons/react";
+import { createElement, useEffect, useMemo, useState, type ReactNode } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import { SizableText, XStack, YStack } from "tamagui";
+import { componentColors } from "../componentColors";
+import { DropdownMenu, type DropdownMenuEntry } from "../DropdownMenu";
+import { PageBackButton, PageBarButton, READABLE_MAX_WIDTH } from "../layouts/page";
+import { ShellScrollReportScope, useShellScrollReports } from "../layouts/screenScroll";
+import {
+  ShellSidebarSlotProvider,
+  useShellSidebarSlotState,
+  type ShellSidebarPanel,
+} from "../layouts/shellSidebarSlot";
+import { BottomAccessory } from "../layouts/bottomAccessory";
+import { Sidebar } from "../layouts/sidebar";
+import { useTranslation } from "../shared/i18n";
+import type { TabBarIcon, TabBarItem } from "./TabBar";
+import { TabHost } from "./TabHost";
+import { useBottomChromeInset, useFloatingBarMounted } from "./bottomChrome";
+
+export interface AppShellDestination {
+  /** The destination's route; a path under it keeps it selected. */
+  key: string;
+  /** One short word: it is the tab caption and the back label. */
+  label: string;
+  icon: TabBarIcon;
+  /** The SF Symbol the iOS system tab bar draws for this destination. */
+  nativeIcon?: TabBarItem["nativeIcon"];
+  /**
+   * `tab` (default) sits in the phone's tab bar; `more` opens from the bar's
+   * pull-down. Every destination sits in the regular-width sidebar.
+   */
+  placement?: "tab" | "more";
+  /** Runs instead of `onNavigate(key)`, e.g. an external link. */
+  onPress?: () => void;
+}
+
+export interface AppShellProps {
+  destinations: readonly AppShellDestination[];
+  /** The current route path. */
+  path: string;
+  onNavigate: (key: string) => void;
+  /** The app's name: the sidebar's title and the home control's label. */
+  title: string;
+  /** The app's mark, leading the bar on a phone and the name in the sidebar. */
+  logo?: ReactNode;
+  /** Pressing the name or mark. Default: the first destination. */
+  onTitlePress?: () => void;
+  /** Trailing bar actions (theme, account). */
+  actions?: ReactNode;
+  /** Shows a tinted back on a route pushed below its destination (its key). */
+  onBack?: (destinationKey: string) => void;
+  /** The phone's bottom accessory (LC-174), handed to the tab bar or pinned to the bottom edge. */
+  accessory?: ReactNode;
+  /** Route prefixes that mount their own chrome; the shell draws none there. */
+  ownChrome?: readonly string[];
+  children?: ReactNode;
+  testID?: string;
+}
+
+function underKey(path: string, key: string): boolean {
+  if (key === "/") return path === "/";
+  return path === key || path.startsWith(`${key}/`);
+}
+
+/** The destination that owns `path` (the longest key it sits under). */
+export function appShellRoute(
+  destinations: readonly AppShellDestination[],
+  path: string,
+): { destination: AppShellDestination | undefined; pushed: boolean } {
+  const normal = path.length > 1 ? path.replace(/\/+$/, "") : path;
+  let destination: AppShellDestination | undefined;
+  for (const candidate of destinations) {
+    if (candidate.onPress || !underKey(normal, candidate.key)) continue;
+    if (!destination || candidate.key.length > destination.key.length) destination = candidate;
+  }
+  return { destination, pushed: Boolean(destination && normal !== destination.key) };
+}
+
+/** Web: the document scrolls under the sticky bar; native reports via Screen. */
+function useDocumentScrolled(enabled: boolean): boolean {
+  const [scrolled, setScrolled] = useState(false);
+  useEffect(() => {
+    if (!enabled || typeof document === "undefined") return;
+    const sync = () => setScrolled(window.scrollY > 1);
+    sync();
+    window.addEventListener("scroll", sync, { passive: true });
+    return () => window.removeEventListener("scroll", sync);
+  }, [enabled]);
+  return scrolled;
+}
+
+const sticky = (edge: "top" | "bottom") =>
+  isWeb ? { position: "sticky" as const, [edge]: 0, zIndex: zIndex.stickyHeader } : null;
+
+function HomeControl({
+  title,
+  onPress,
+  children,
+}: {
+  title: string;
+  onPress: () => void;
+  children: ReactNode;
+}) {
+  return (
+    <XStack
+      role="link"
+      aria-label={title}
+      alignItems="center"
+      minHeight={MIN_PRESS_TARGET}
+      flexShrink={1}
+      minWidth={0}
+      gap="$2"
+      cursor="pointer"
+      onPress={onPress}
+      data-testid="app-shell-home"
+    >
+      {children}
+    </XStack>
+  );
+}
+
+interface NavBarProps {
+  /** Centres the bar's row in the content column's readable width. */
+  maxWidth?: number;
+  leading: ReactNode;
+  trailing: ReactNode;
+  title: string | null;
+  showTitle: boolean;
+  scrolled: boolean;
+}
+
+/**
+ * The shell's nav bar: one 44pt row on the page fill. Its hairline appears
+ * once content scrolls under it (scroll-edge appearance) and the inline
+ * title fades in once the page's large title has scrolled away, centred
+ * clear of the wider side group, both on the control motion role (LC-68).
+ */
+function AppShellNavBar({ maxWidth, leading, trailing, title, showTitle, scrolled }: NavBarProps) {
+  const { knobProps } = useResolvedKnobs({ component: "ScreenToolbar" });
+  const [sides, setSides] = useState({ leading: 0, trailing: 0 });
+  const measure = (side: "leading" | "trailing") => (event: LayoutChangeEvent) => {
+    const width = Math.ceil(event.nativeEvent.layout.width);
+    setSides((prev) => (prev[side] === width ? prev : { ...prev, [side]: width }));
+  };
+  const motion = transitionProps(knobProps.motion.control);
+  const clearance = Math.max(sides.leading, sides.trailing);
+  return (
+    <Surface bar>
+      <YStack
+        role="banner"
+        data-testid="app-shell-bar"
+        data-scroll-edge={scrolled ? "" : undefined}
+        backgroundColor="$background"
+        flexShrink={0}
+        {...hairline.bottom}
+        borderColor={(scrolled ? componentColors.divider : "transparent") as never}
+        {...motion}
+        {...sticky("top")}
+      >
+        <XStack
+          position="relative"
+          width="100%"
+          {...(maxWidth ? { maxWidth, alignSelf: "center" as const } : null)}
+          minHeight={MIN_PRESS_TARGET}
+          alignItems="center"
+          flexWrap="nowrap"
+          paddingHorizontal={knobProps.panelPadding.padding as "$4"}
+          {...knobProps.gap}
+        >
+          <XStack
+            alignItems="center"
+            flexShrink={1000}
+            minWidth={0}
+            {...knobProps.gap}
+            onLayout={measure("leading")}
+          >
+            {leading}
+          </XStack>
+          <XStack flexGrow={1} />
+          <XStack
+            alignItems="center"
+            flexShrink={1}
+            minWidth={0}
+            justifyContent="flex-end"
+            {...knobProps.gap}
+            onLayout={measure("trailing")}
+          >
+            {trailing}
+          </XStack>
+          {title ? (
+            <XStack
+              position="absolute"
+              top={0}
+              bottom={0}
+              left={clearance}
+              right={clearance}
+              alignItems="center"
+              justifyContent="center"
+              pointerEvents="none"
+              aria-hidden={!showTitle}
+              data-testid="app-shell-bar-title"
+              opacity={showTitle ? 1 : 0}
+              {...motion}
+            >
+              <SizableText {...knobProps.body} fontWeight="600" color="$color12" numberOfLines={1}>
+                {title}
+              </SizableText>
+            </XStack>
+          ) : null}
+        </XStack>
+      </YStack>
+    </Surface>
+  );
+}
+
+function StackedPanel({ panel }: { panel: ShellSidebarPanel }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack
+      paddingHorizontal={knobProps.panelPadding.padding as "$4"}
+      {...knobProps.gap}
+      data-testid="app-shell-page-panel"
+    >
+      <SizableText
+        {...knobProps.body}
+        size="$2"
+        textTransform="uppercase"
+        color={knobProps.textAccentColor}
+        numberOfLines={1}
+      >
+        {panel.title}
+      </SizableText>
+      {panel.content}
+    </YStack>
+  );
+}
+
+export function AppShell({
+  destinations,
+  path,
+  onNavigate,
+  title,
+  logo,
+  onTitlePress,
+  actions,
+  onBack,
+  accessory,
+  ownChrome = [],
+  children,
+  testID = "app-shell",
+}: AppShellProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const compact = useLayoutSizeClass() === "compact";
+  const { report, reporter } = useShellScrollReports();
+  const sidebarSlot = useShellSidebarSlotState();
+  const documentScrolled = useDocumentScrolled(isWeb);
+  const chromeInset = useBottomChromeInset();
+  const floatingBar = useFloatingBarMounted();
+
+  const { destination, pushed } = appShellRoute(destinations, path);
+  const ownsChrome = ownChrome.some((prefix) => underKey(path, prefix));
+  const go = (item: AppShellDestination) => (item.onPress ? item.onPress() : onNavigate(item.key));
+  const goHome = onTitlePress ?? (() => destinations[0] && go(destinations[0]));
+
+  const tabs = useMemo(
+    () => destinations.filter((item) => (item.placement ?? "tab") === "tab"),
+    [destinations],
+  );
+  const more = useMemo(
+    () => destinations.filter((item) => item.placement === "more"),
+    [destinations],
+  );
+
+  if (ownsChrome) {
+    return (
+      <YStack
+        flex={1}
+        minHeight={0}
+        backgroundColor="$background"
+        {...(isWeb ? { height: "100dvh" as never } : null)}
+        data-testid={testID}
+        data-chrome="own"
+      >
+        {children}
+      </YStack>
+    );
+  }
+
+  const pageBar = Boolean(report?.ownTopBar);
+  const scrolled = isWeb ? documentScrolled : Boolean(report?.scrolled);
+  const largeTitle = report?.title ?? null;
+  const barTitle = largeTitle ?? destination?.label ?? null;
+  const showTitle = largeTitle ? Boolean(report?.collapsed) : Boolean(barTitle);
+  const back =
+    pushed && onBack && destination && !pageBar ? (
+      <PageBackButton label={destination.label} onPress={() => onBack(destination.key)} />
+    ) : null;
+  const showBar = compact ? !pageBar : Boolean(back);
+
+  const moreMenu =
+    compact && more.length > 0 ? (
+      <DropdownMenu
+        placement="bottom-end"
+        items={more.map<DropdownMenuEntry>((item) => ({
+          key: item.key,
+          label: item.label,
+          icon: createElement(item.icon),
+          onSelect: () => go(item),
+        }))}
+      >
+        <PageBarButton
+          edge="end"
+          icon={ListIcon}
+          aria-label={t("More")}
+          data-testid="app-shell-more"
+        />
+      </DropdownMenu>
+    ) : null;
+
+  const bar = showBar ? (
+    <AppShellNavBar
+      leading={
+        back ??
+        (compact && logo ? (
+          <HomeControl title={title} onPress={goHome}>
+            {logo}
+          </HomeControl>
+        ) : null)
+      }
+      trailing={
+        compact ? (
+          <>
+            {actions}
+            {moreMenu}
+          </>
+        ) : null
+      }
+      maxWidth={compact ? undefined : READABLE_MAX_WIDTH}
+      title={barTitle}
+      showTitle={showTitle}
+      scrolled={scrolled}
+    />
+  ) : null;
+
+  const content = (
+    <YStack
+      role="main"
+      flex={1}
+      minWidth={0}
+      {...(isWeb ? null : { minHeight: 0 })}
+      data-testid="app-shell-content"
+    >
+      {compact ? (
+        children
+      ) : (
+        <YStack
+          flex={1}
+          width="100%"
+          maxWidth={READABLE_MAX_WIDTH}
+          alignSelf="center"
+          {...(isWeb ? null : { minHeight: 0 })}
+          data-testid="app-shell-readable"
+        >
+          {children}
+        </YStack>
+      )}
+    </YStack>
+  );
+
+  const showTabs = compact && Boolean(destination && tabs.includes(destination));
+  const tabItems: TabBarItem[] = tabs.map(({ key, label, icon, nativeIcon }) => ({
+    key,
+    label,
+    icon,
+    nativeIcon,
+  }));
+  // The floating TabBar takes the accessory into its own capsule. Otherwise
+  // it renders in place, and on native it clears the system tab bar, which
+  // the content runs under.
+  const pageAccessory = accessory ? (
+    <YStack flexShrink={0} {...(isWeb || floatingBar ? null : { paddingBottom: chromeInset })}>
+      <BottomAccessory>{accessory}</BottomAccessory>
+    </YStack>
+  ) : null;
+
+  const frame = compact ? (
+    <YStack
+      flex={1}
+      backgroundColor="$background"
+      {...(isWeb ? { minHeight: "100dvh" as never } : null)}
+      data-testid={testID}
+      data-size="compact"
+    >
+      {bar}
+      {tabItems.length > 0 ? (
+        <TabHost
+          items={tabItems}
+          activeKey={showTabs ? destination?.key : undefined}
+          onTabPress={(key) => {
+            const item = tabs.find((tab) => tab.key === key);
+            if (item) go(item);
+          }}
+        >
+          {content}
+          {pageAccessory}
+        </TabHost>
+      ) : (
+        <>
+          {content}
+          {pageAccessory}
+        </>
+      )}
+    </YStack>
+  ) : (
+    <XStack
+      flex={1}
+      backgroundColor="$background"
+      {...(isWeb ? { minHeight: "100dvh" as never } : null)}
+      data-testid={testID}
+      data-size="regular"
+    >
+      <YStack
+        flexShrink={0}
+        alignSelf="stretch"
+        {...(isWeb ? { position: "sticky" as const, top: 0, height: "100dvh" as never } : null)}
+        data-testid="app-shell-sidebar"
+      >
+        <Sidebar
+          material
+          aria-label={title}
+          header={
+            <XStack
+              paddingHorizontal={knobProps.panelPadding.padding as "$4"}
+              alignItems="center"
+              minHeight={MIN_PRESS_TARGET}
+            >
+              <HomeControl title={title} onPress={goHome}>
+                {logo}
+                <SizableText
+                  {...knobProps.heading}
+                  fontWeight="700"
+                  color="$color12"
+                  numberOfLines={1}
+                >
+                  {title}
+                </SizableText>
+              </HomeControl>
+            </XStack>
+          }
+          footer={
+            actions ? (
+              <XStack
+                paddingHorizontal={knobProps.panelPadding.padding as "$4"}
+                alignItems="center"
+                minHeight={MIN_PRESS_TARGET}
+                flexWrap="wrap"
+                {...knobProps.gap}
+                data-testid="app-shell-sidebar-actions"
+              >
+                {actions}
+              </XStack>
+            ) : undefined
+          }
+          sections={[
+            {
+              items: destinations.map((item) => ({
+                label: item.label,
+                value: item.key,
+                icon: createElement(item.icon),
+                active: item === destination,
+                onPress: () => go(item),
+              })),
+            },
+          ]}
+        >
+          {sidebarSlot.panel ? <StackedPanel panel={sidebarSlot.panel} /> : null}
+        </Sidebar>
+      </YStack>
+      <YStack flex={1} minWidth={0}>
+        {bar}
+        {content}
+        {pageAccessory}
+      </YStack>
+    </XStack>
+  );
+
+  return (
+    <ShellSidebarSlotProvider value={compact ? null : sidebarSlot.value}>
+      <ShellScrollReportScope reporter={reporter}>{frame}</ShellScrollReportScope>
+    </ShellSidebarSlotProvider>
+  );
+}

package/src/appShell/index.ts

@@ -6,4 +6,5 @@ export { TabHost, type TabHostProps } from "./TabHost";
 export * from "./Springboard";
 export type { AppEntry } from "./appTile";
 export * from "./SettingsSplit";
+export * from "./AppShell";
 export { useBottomChromeInset } from "./bottomChrome";

package/src/layouts/Sidebar.spec.tsx

@@ -120,3 +120,34 @@ describe("Sidebar footer", () => {
     expect(result.getByTestId("rail").querySelector("[data-sidebar-footer]")).toBeNull();
   });
 });
+
+describe("Sidebar on the shell material (FZ-7996)", () => {
+  const sections = [
+    {
+      items: [
+        { value: "home", label: "Home", active: true, onPress: () => {} },
+        { value: "pokemon", label: "Pokemon", onPress: () => {} },
+        { value: "moves", label: "Moves", onPress: () => {} },
+      ],
+    },
+  ];
+
+  it("sets every row as a rounded pill with no rule between rows", () => {
+    const result = renderWithProviders(<Sidebar material sections={sections} />);
+    const rows = [...result.container.querySelectorAll("[data-sidebar-row]")];
+    expect(rows).toHaveLength(3);
+    for (const row of rows) {
+      expect(row.className).toMatch(/_btlr-/);
+      expect(row.className).toMatch(/_bbrr-/);
+    }
+    expect(rows[1]!.previousElementSibling).toBe(rows[0]);
+    expect(rows[2]!.previousElementSibling).toBe(rows[1]);
+  });
+
+  it("keeps the stacked group with rules between rows off the material", () => {
+    const result = renderWithProviders(<Sidebar sections={sections} />);
+    const rows = [...result.container.querySelectorAll("[data-sidebar-row]")];
+    expect(rows[1]!.previousElementSibling).not.toBe(rows[0]);
+    expect(rows[1]!.previousElementSibling?.hasAttribute("data-sidebar-row")).toBe(false);
+  });
+});