@multiplatform.one/components 6.7.0 → 7.1.0

package/src/layouts/page.tsx

@@ -16,10 +16,9 @@
  */
 
 import {
+  Surface,
   hairline,
   layoutBreakpoints,
-  radiusClassProps,
-  readingWidthStyle,
   resolvePageTitleScale,
   useResolvedKnobs,
   type PageTitleScale,
@@ -43,6 +42,7 @@ import {
 import { componentColors, sectionHeading } from "../componentColors";
 import {
   PageHeadingScope,
+  usePageChromeInset,
   useRegisterPageHeading,
   type PageHeadingLevel,
 } from "./pageHeadingScope";
@@ -50,12 +50,10 @@ import {
 /** Semantic level → tamagui heading component (runtime `tag` is not honored). */
 const PAGE_HEADING_TAGS = { 1: H1, 2: H2, 3: H3, 4: H4, 5: H5, 6: H6 } as const;
 
-/** Header lede: one step above the sizeToken body scale (medium = old $5). */
-const subtitleSizeMap: Record<string, "$4" | "$5" | "$6"> = {
-  $3: "$4",
-  $4: "$5",
-  $5: "$6",
-};
+/** `$4` → `$-4` so PageHeader can cancel Screen's panel padding. */
+function negateSpaceToken(token: string): `$-${string}` {
+  return `$-${token.startsWith("$") ? token.slice(1) : token}`;
+}
 
 // ---------------------------------------------------------------------------
 // Screen — page outer shell (scroll, max-width, padding, theme background)
@@ -90,7 +88,15 @@ export interface ScreenProps extends YStackProps {
  *   <FrappeImageView doctype="Pokemon" />
  * </Screen>
  */
-export function Screen({
+export function Screen(props: ScreenProps) {
+  return (
+    <Surface density="comfortable">
+      <ScreenInner {...props} />
+    </Surface>
+  );
+}
+
+function ScreenInner({
   children,
   scroll = true,
   maxWidth = CONTENT_MAX_WIDTH,
@@ -110,8 +116,11 @@ export function Screen({
       {...knobProps.gapLg}
       {...rest}
     >
-      {/* DG-A11Y-02: one h1 budget per Screen — catalog headings register here. */}
-      <PageHeadingScope>{children}</PageHeadingScope>
+      {/* DG-A11Y-02: one h1 budget per Screen — catalog headings register here.
+          insetToken lets PageHeader bleed its hairline to the column edges. */}
+      <PageHeadingScope insetToken={noPadding ? null : (knobProps.panelPadding.padding as string)}>
+        {children}
+      </PageHeadingScope>
     </YStack>
   );
 
@@ -150,6 +159,12 @@ export interface PageHeaderProps extends YStackProps {
   heading?: ReactNode;
   /** Trailing actions (buttons, switchers, etc.) shown right of the title. */
   actions?: ReactNode;
+  /**
+   * Underline navigation (tabs) that sits on the header hairline.
+   * The header still draws the edge-to-edge rule; the nav is pulled onto it
+   * so the active indicator is not a second competing line.
+   */
+  nav?: ReactNode;
   /** Adds a subtle divider rule under the header. Default: true. */
   divider?: boolean;
   /**
@@ -170,14 +185,20 @@ export interface PageHeaderProps extends YStackProps {
 }
 
 /**
- * Standard page header. Title left, actions right, optional subtitle and
- * a thin divider rule beneath. Stacks vertically on narrow viewports.
+ * Standard page header (Polaris Page / Primer PageHeader / Linear).
+ *
+ * Title + subtitle stack as one column (lede under the title, not under the
+ * actions). Type comes from the shared heading / pageTitle / body fragments —
+ * no local subtitle scale. The hairline is a container-owned edge that bleeds
+ * to the Screen column. `nav` (tabs) is pulled onto that edge so the active
+ * indicator shares the one rule instead of stacking a second line.
  */
 export function PageHeader({
   title,
   subtitle,
   heading,
   actions,
+  nav,
   divider = true,
   headingLevel = 1,
   titleScale,
@@ -185,6 +206,7 @@ export function PageHeader({
   ...rest
 }: PageHeaderProps) {
   const { knobProps } = useResolvedKnobs();
+  const insetToken = usePageChromeInset();
   // DG-A11Y-02: count the built-in title toward the Screen's h1 budget.
   // Custom `heading` nodes have an unknown level and are not registered.
   useRegisterPageHeading({
@@ -208,48 +230,77 @@ export function PageHeader({
   const titleNode =
     heading ??
     (title ? (
-      <TitleTag margin={0} {...titleSize} {...headingFamily}>
+      <TitleTag
+        margin={0}
+        fontWeight={knobProps.heading.fontWeight}
+        {...titleSize}
+        {...headingFamily}
+      >
         {title}
       </TitleTag>
     ) : null);
 
+  // When nav is present the strip's active indicator sits ON this rule
+  // (negative margin), so there is one hairline — not a second competing line.
+  const showHairline = Boolean(divider);
+  const bleed = insetToken ? { marginHorizontal: negateSpaceToken(insetToken) as "$4" } : null;
+  const contentPad = insetToken ? { paddingHorizontal: insetToken as "$4" } : null;
+
   return (
-    <YStack {...knobProps.gap} {...rest}>
-      <XStack justifyContent="space-between" alignItems="center" flexWrap="wrap" {...knobProps.gap}>
-        {/* LC-10 FRAME-CONTAINMENT: title + actions must shrink and wrap at
-            narrow widths instead of painting past the frame. flexShrink:1 +
-            minWidth:0 lets the H1 wrap (DF-02) and each action wrap below the
-            title rather than clip off-canvas (DF-01). */}
-        {titleNode ? (
-          <YStack flexShrink={1} minWidth={0}>
-            {titleNode}
-          </YStack>
-        ) : null}
-        {actions ? (
-          <XStack
-            {...knobProps.gap}
-            alignItems="center"
-            flexWrap="wrap"
-            flexShrink={1}
-            minWidth={0}
-          >
-            {actions}
-          </XStack>
-        ) : null}
-      </XStack>
-      {subtitle ? (
-        // Lede rides one step above the size-knob body scale (medium keeps
-        // the previous $5), so the size knob reaches the header copy (LC-18).
-        <Paragraph
-          color={componentColors.text.muted}
-          size={subtitleSizeMap[knobProps.sizeToken] ?? "$5"}
-          margin={0}
+    <YStack
+      data-testid="page-header"
+      overflow="visible"
+      {...bleed}
+      {...(showHairline ? { ...hairline.bottom, borderColor: componentColors.divider } : null)}
+      {...(nav ? knobProps.gap : null)}
+      {...rest}
+    >
+      <YStack {...contentPad} paddingBottom={nav ? 0 : (knobProps.gap.gap as "$4")}>
+        <XStack
+          justifyContent="space-between"
+          alignItems={subtitle ? "flex-start" : "center"}
+          flexWrap="wrap"
+          {...knobProps.gap}
+        >
+          {/* LC-10 FRAME-CONTAINMENT: title + actions must shrink and wrap at
+              narrow widths instead of painting past the frame. flexShrink:1 +
+              minWidth:0 lets the H1 wrap (DF-02) and each action wrap below the
+              title rather than clip off-canvas (DF-01). */}
+          {titleNode || subtitle ? (
+            <YStack flexGrow={1} flexShrink={1} minWidth={0} gap="$1">
+              {titleNode}
+              {subtitle ? (
+                // T-HELPER on the shared body fragment — not a local size map.
+                <Paragraph margin={0} {...knobProps.body} color={componentColors.text.muted}>
+                  {subtitle}
+                </Paragraph>
+              ) : null}
+            </YStack>
+          ) : null}
+          {actions ? (
+            <XStack
+              {...knobProps.gap}
+              alignItems="center"
+              flexWrap="wrap"
+              flexShrink={1}
+              minWidth={0}
+            >
+              {actions}
+            </XStack>
+          ) : null}
+        </XStack>
+        {children}
+      </YStack>
+      {nav ? (
+        <YStack
+          width="100%"
+          data-page-header-nav=""
+          // Sit the tab indicator on the header hairline (Primer / Linear).
+          marginBottom={showHairline ? -1 : 0}
         >
-          {subtitle}
-        </Paragraph>
+          {nav}
+        </YStack>
       ) : null}
-      {children}
-      {divider ? <Separator {...hairline.line} backgroundColor={componentColors.divider} /> : null}
     </YStack>
   );
 }
@@ -323,12 +374,7 @@ export function PageSection({
       <YStack gap="$2">
         {headingNode}
         {description ? (
-          // Section copy follows the size-knob body scale (medium = $4).
-          <Paragraph
-            color={componentColors.text.muted}
-            size={knobProps.sizeToken as any}
-            margin={0}
-          >
+          <Paragraph margin={0} {...knobProps.body} color={componentColors.text.muted}>
             {description}
           </Paragraph>
         ) : null}
@@ -356,116 +402,9 @@ export function PageSection({
   );
 }
 
-// ---------------------------------------------------------------------------
-// EmptyState — placeholder for empty/error/loading screens
-// ---------------------------------------------------------------------------
-
-export interface EmptyStateProps extends YStackProps {
-  title: string;
-  description?: string;
-  /** Icon or illustration shown above the title. */
-  icon?: ReactNode;
-  /** Action button(s) shown below the description. */
-  action?: ReactNode;
-  /** Smaller type + no flex-fill, for inline use inside tables/columns. */
-  compact?: boolean;
-  /**
-   * Visual intent. `error` marks sober failure chrome (DG-ST-01) — use via
-   * AsyncBoundary; never for a successful empty dataset.
-   */
-  intent?: "neutral" | "error";
-}
-
-/**
- * Centered empty/error state. Use for "no data", "not configured",
- * "permission denied" placeholder screens.
- *
- * Prefer `<AsyncBoundary>` for async data views so empty chrome can never
- * render on a failed load (DG-ST-01).
- */
-export function EmptyState({
-  title,
-  description,
-  icon,
-  action,
-  compact = false,
-  intent = "neutral",
-  children,
-  ...rest
-}: EmptyStateProps) {
-  // compact steps the resolved size/space knobs down one level, so the
-  // icon well, gaps, and copy shrink through the one pipeline (Axiom 5).
-  const { knobProps } = useResolvedKnobs({ compact });
-  // See PageHeader: native-only heading family from the headingFont knob.
-  const headingFamily = isWeb ? null : { fontFamily: knobProps.heading.fontFamily };
-  return (
-    <YStack
-      flex={compact ? undefined : 1}
-      alignItems="center"
-      justifyContent="center"
-      data-empty-intent={intent}
-      {...knobProps.panelPadding}
-      {...knobProps.gap}
-      {...rest}
-    >
-      {icon ? (
-        <YStack
-          alignItems="center"
-          justifyContent="center"
-          backgroundColor="$color3"
-          // R-PILL icon well: always a circle; its inset scales with the
-          // size knob (spec: empty icon well consumes sizeToken). Declared so
-          // the `radius:none` sweep licenses the circle instead of guessing
-          // from its geometry (D-09 / LC-60).
-          {...radiusClassProps("R-PILL", "empty icon well")}
-          padding={knobProps.sizeToken as any}
-          borderRadius={1000}
-        >
-          {icon}
-        </YStack>
-      ) : null}
-      {/* RN has no hyphenation, so a long single word (brand names, ids)
-          character-wraps and orphans its tail on phone widths. $sm steps the
-          42px H2 down on web; native scales the text to FIT instead
-          (adjustsFontSizeToFit) -- deterministic at any width, no media
-          dependency. */}
-      {compact ? (
-        <Paragraph
-          color={componentColors.text.muted}
-          textAlign="center"
-          margin={0}
-          {...(!isWeb && { numberOfLines: 2, adjustsFontSizeToFit: true, minimumFontScale: 0.55 })}
-        >
-          {title}
-        </Paragraph>
-      ) : (
-        <H2
-          {...headingFamily}
-          textAlign="center"
-          margin={0}
-          fontWeight="600"
-          $sm={{ fontSize: "$8", lineHeight: 42 }}
-          {...(!isWeb && { numberOfLines: 2, adjustsFontSizeToFit: true, minimumFontScale: 0.55 })}
-        >
-          {title}
-        </H2>
-      )}
-      {description ? (
-        <Paragraph
-          color={componentColors.text.muted}
-          size={knobProps.sizeToken as any}
-          textAlign="center"
-          margin={0}
-          {...readingWidthStyle()}
-        >
-          {description}
-        </Paragraph>
-      ) : null}
-      {action}
-      {children}
-    </YStack>
-  );
-}
+// EmptyState lives in ./EmptyState — re-exported so Screen/PageHeader
+// consumers that import the page shell keep a stable path.
+export { EmptyState, type EmptyStateProps } from "./EmptyState";
 
 // ---------------------------------------------------------------------------
 // ScreenToolbar — minimal back/edit-style screen toolbar

package/src/layouts/pageHeadingScope.tsx

@@ -11,6 +11,9 @@
  * Registration is voluntary: raw `<H1>` tags dropped in by consumers are not
  * detected — the guardrail covers the catalog path (PageHeader, frappe-ui
  * Heading) where the level is known.
+ *
+ * The same scope carries the page chrome inset (`insetToken`) so PageHeader
+ * can bleed its hairline to the column edges without a second context.
  */
 
 import { devWarn } from "@multiplatform.one/theme";
@@ -23,6 +26,11 @@ export type PageHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface PageHeadingRegistry {
   /** Register a mounted level-1 heading; returns the unregister cleanup. */
   registerH1: (detail?: { component?: string; label?: string }) => () => void;
+  /**
+   * Horizontal padding the page shell applied. PageHeader bleeds its
+   * hairline by this token so the rule is edge-to-edge of the column.
+   */
+  insetToken: string | null;
 }
 
 const PageHeadingScopeContext = createContext<PageHeadingRegistry | null>(null);
@@ -31,6 +39,11 @@ export interface PageHeadingScopeProps {
   children: ReactNode;
   /** Scope owner named in the DEV warn. Default: "Screen". */
   name?: string;
+  /**
+   * Horizontal padding the hosting page shell applied (`knobProps.panelPadding.padding`).
+   * Omitted / null — PageHeader does not bleed (isolated / `noPadding` screens).
+   */
+  insetToken?: string | null;
 }
 
 /**
@@ -38,10 +51,15 @@ export interface PageHeadingScopeProps {
  * subtree. Nested scopes shadow the outer one (a nested full page shell owns
  * its own h1 budget).
  */
-export function PageHeadingScope({ children, name = "Screen" }: PageHeadingScopeProps) {
+export function PageHeadingScope({
+  children,
+  name = "Screen",
+  insetToken = null,
+}: PageHeadingScopeProps) {
   const h1CountRef = useRef(0);
   const value = useMemo<PageHeadingRegistry>(
     () => ({
+      insetToken: insetToken ?? null,
       registerH1: (detail) => {
         h1CountRef.current += 1;
         if (h1CountRef.current > 1) {
@@ -57,13 +75,21 @@ export function PageHeadingScope({ children, name = "Screen" }: PageHeadingScope
         };
       },
     }),
-    [name],
+    [name, insetToken],
   );
   return (
     <PageHeadingScopeContext.Provider value={value}>{children}</PageHeadingScopeContext.Provider>
   );
 }
 
+/**
+ * Horizontal inset the nearest page shell applied, or null when the header
+ * is not inside a padded `Screen` (isolated stories, `noPadding`).
+ */
+export function usePageChromeInset(): string | null {
+  return useContext(PageHeadingScopeContext)?.insetToken ?? null;
+}
+
 /**
  * Register a mounted catalog heading with the nearest PageHeadingScope.
  * Only level-1 headings count toward the `multiple-h1` guardrail; other