@multiplatform.one/components 6.0.4 → 6.3.0

package/src/layouts/pageHeadingScope.tsx

@@ -0,0 +1,87 @@
+/**
+ * Page-heading scope — DG-A11Y-02 "exactly one h1 per page".
+ *
+ * A page shell (`Screen` here; the Desk scaffolding in
+ * `@multiplatform.one/frappe-ui`) hosts one scope per page. Catalog
+ * components that render a heading register their resolved semantic level;
+ * when a second level-1 heading mounts under the same scope, the scope emits
+ * the `multiple-h1` DEV warn from the shared devWarn catalog
+ * (`@multiplatform.one/theme`, no-op in production builds).
+ *
+ * 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.
+ */
+
+import { devWarn } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useMemo, useRef } from "react";
+
+/** Semantic heading levels used by catalog page components. */
+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;
+}
+
+const PageHeadingScopeContext = createContext<PageHeadingRegistry | null>(null);
+
+export interface PageHeadingScopeProps {
+  children: ReactNode;
+  /** Scope owner named in the DEV warn. Default: "Screen". */
+  name?: string;
+}
+
+/**
+ * Hosts the h1 registry for one page. Renders no DOM — safe to wrap any
+ * subtree. Nested scopes shadow the outer one (a nested full page shell owns
+ * its own h1 budget).
+ */
+export function PageHeadingScope({ children, name = "Screen" }: PageHeadingScopeProps) {
+  const h1CountRef = useRef(0);
+  const value = useMemo<PageHeadingRegistry>(
+    () => ({
+      registerH1: (detail) => {
+        h1CountRef.current += 1;
+        if (h1CountRef.current > 1) {
+          devWarn("multiple-h1", {
+            component: name,
+            id: detail?.component,
+            value: detail?.label,
+            count: h1CountRef.current,
+          });
+        }
+        return () => {
+          h1CountRef.current -= 1;
+        };
+      },
+    }),
+    [name],
+  );
+  return (
+    <PageHeadingScopeContext.Provider value={value}>{children}</PageHeadingScopeContext.Provider>
+  );
+}
+
+/**
+ * Register a mounted catalog heading with the nearest PageHeadingScope.
+ * Only level-1 headings count toward the `multiple-h1` guardrail; other
+ * levels and unscoped mounts are no-ops.
+ */
+export function useRegisterPageHeading(args: {
+  level: number;
+  /** Component name reported in the warn (e.g. "PageHeader"). */
+  component?: string;
+  /** Heading text reported in the warn. */
+  label?: string;
+  /** Pass false when the heading is not actually rendered (skeleton, custom node). */
+  enabled?: boolean;
+}): void {
+  const registry = useContext(PageHeadingScopeContext);
+  const { level, component, label, enabled = true } = args;
+  useEffect(() => {
+    if (!enabled || level !== 1 || !registry) return;
+    return registry.registerH1({ component, label });
+  }, [enabled, level, registry, component, label]);
+}

package/src/layouts/pageHeadings.spec.tsx

@@ -0,0 +1,151 @@
+/**
+ * DG-A11Y-02 — exactly one h1 per page, sequential heading levels.
+ *
+ * Covers: PageHeader renders the single h1 under Screen, headingLevel steps
+ * the semantic tag without visual change, PageSection/Timeline defaults sit
+ * at h2, and the `multiple-h1` DEV warn fires when a second level-1 heading
+ * mounts under one Screen.
+ */
+
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { __resetDevWarnSeen } from "@multiplatform.one/theme";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PageHeader, PageSection, Screen } from "./page";
+import { PageHeadingScope } from "./pageHeadingScope";
+import { Timeline } from "./timeline";
+
+afterEach(cleanup);
+
+function headingSequence(container: HTMLElement): Array<{ level: number; text: string }> {
+  return [...container.querySelectorAll("h1,h2,h3,h4,h5,h6")].map((el) => ({
+    level: Number(el.tagName[1]),
+    text: (el.textContent ?? "").trim(),
+  }));
+}
+
+describe("DG-A11Y-02 heading structure", () => {
+  it("Screen + PageHeader renders the page title as the single h1", () => {
+    const { container } = renderWithProviders(
+      <Screen scroll={false}>
+        <PageHeader title="Pokemon" subtitle="All pokemon" />
+        <PageSection title="Stats" />
+      </Screen>,
+    );
+
+    const h1s = container.querySelectorAll("h1");
+    expect(h1s).toHaveLength(1);
+    expect(h1s[0]?.textContent).toBe("Pokemon");
+  });
+
+  it("section headings step h1 → h2 without skips", () => {
+    const { container } = renderWithProviders(
+      <Screen scroll={false}>
+        <PageHeader title="Pokemon" />
+        <PageSection title="Stats" />
+        <PageSection title="Moves" />
+      </Screen>,
+    );
+
+    expect(headingSequence(container)).toEqual([
+      { level: 1, text: "Pokemon" },
+      { level: 2, text: "Stats" },
+      { level: 2, text: "Moves" },
+    ]);
+  });
+
+  it("PageHeader headingLevel demotes the tag (no h1) without dropping the title", () => {
+    const { container } = renderWithProviders(<PageHeader title="Nested pane" headingLevel={2} />);
+
+    expect(container.querySelectorAll("h1")).toHaveLength(0);
+    expect(container.querySelector("h2")?.textContent).toBe("Nested pane");
+  });
+
+  it("PageSection headingLevel steps nested sections to h3", () => {
+    const { container } = renderWithProviders(<PageSection title="Sub section" headingLevel={3} />);
+
+    expect(container.querySelectorAll("h2")).toHaveLength(0);
+    expect(container.querySelector("h3")?.textContent).toBe("Sub section");
+  });
+
+  it("Timeline label is an h2 section heading by default and steps via headingLevel", () => {
+    const first = renderWithProviders(<Timeline entries={[]} label="Activity" />);
+    expect(first.container.querySelector("h2")?.textContent).toBe("Activity");
+    cleanup();
+
+    const second = renderWithProviders(<Timeline entries={[]} label="Activity" headingLevel={3} />);
+    expect(second.container.querySelector("h3")?.textContent).toBe("Activity");
+    expect(second.container.querySelectorAll("h2")).toHaveLength(0);
+  });
+});
+
+describe("multiple-h1 DEV warn (PageHeadingScope)", () => {
+  beforeEach(() => {
+    __resetDevWarnSeen();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function multipleH1Warnings(warn: ReturnType<typeof vi.spyOn>): string[] {
+    return warn.mock.calls.map((call) => String(call[0])).filter((m) => m.includes("multiple-h1"));
+  }
+
+  it("warns when two h1 page headings mount under one Screen", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    renderWithProviders(
+      <Screen scroll={false}>
+        <PageHeader title="First" />
+        <PageHeader title="Second" />
+      </Screen>,
+    );
+
+    expect(multipleH1Warnings(warn).length).toBeGreaterThan(0);
+  });
+
+  it("does not warn for a single h1 with stepped sections", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    renderWithProviders(
+      <Screen scroll={false}>
+        <PageHeader title="Only title" />
+        <PageSection title="Section" />
+        <Timeline entries={[]} label="Activity" />
+      </Screen>,
+    );
+
+    expect(multipleH1Warnings(warn)).toEqual([]);
+  });
+
+  it("does not warn when the second header is demoted via headingLevel", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    renderWithProviders(
+      <Screen scroll={false}>
+        <PageHeader title="Page title" />
+        <PageHeader title="Pane title" headingLevel={2} />
+      </Screen>,
+    );
+
+    expect(multipleH1Warnings(warn)).toEqual([]);
+  });
+
+  it("scopes the budget: sibling scopes each allow their own h1", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    renderWithProviders(
+      <>
+        <PageHeadingScope>
+          <PageHeader title="Page A" />
+        </PageHeadingScope>
+        <PageHeadingScope>
+          <PageHeader title="Page B" />
+        </PageHeadingScope>
+      </>,
+    );
+
+    expect(multipleH1Warnings(warn)).toEqual([]);
+  });
+});

package/src/layouts/sidebar.tsx

@@ -1,10 +1,19 @@
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  hairline,
+  hairlineWidth,
+  useReadableTextOn,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type React from "react";
-import { Group, Label, ListItem, ScrollView, Separator, Text, YStack } from "tamagui";
+import { Group, Label, ListItem, ScrollView, Separator, Text, YStack, isWeb } from "tamagui";
 import { componentColors } from "../componentColors";
 
 export interface SidebarSection {
-  title: string;
+  /**
+   * Section caption. Omit to render the group without a label — e.g. when a
+   * sidebar has a single group, the caption is noise (Axiom 16).
+   */
+  title?: string;
   items: SidebarItem[];
 }
 
@@ -26,51 +35,117 @@ export interface SidebarProps {
 
 export function Sidebar({ sections, width = 250 }: SidebarProps) {
   const { knobProps } = useResolvedKnobs();
+  // UX-P02 / Axiom 15: the active row paints `$accentBackground`, so its label
+  // and count must sit on the accent fill with a luminance-computed foreground
+  // (paper/ink whichever reads) — the scheme `$color` ink measured 2.59:1 on
+  // the accent. Resolved once (all active rows share the fill).
+  const onAccent = useReadableTextOn("$accentBackground");
+  // SP-EDGE: rows own the horizontal inset (space knob via the panelPadding
+  // token); the container contributes none, so row highlights and separators
+  // run edge-to-edge across the panel.
+  const rowPad = knobProps.panelPadding.padding;
   return (
-    <YStack width={width} borderRightWidth={1} borderColor="$borderColor">
+    <YStack
+      width={width}
+      borderColor="$borderColor"
+      // Logical end edge so the divider mirrors in RTL; tamagui
+      // borderEndWidth does not compile to working CSS on web (SB-M-1215).
+      // Hairline: panel edge is a divider, not a control border (Axiom 15).
+      {...(isWeb
+        ? {
+            borderInlineEndWidth: hairlineWidth,
+            borderInlineEndStyle: "solid" as any,
+            className: "mp-hairline-ie",
+          }
+        : { borderEndWidth: hairlineWidth })}
+    >
       <ScrollView>
-        <YStack {...knobProps.panelPadding} {...knobProps.gapLg}>
+        <YStack {...knobProps.panelPadding} paddingHorizontal={0} {...knobProps.gapLg}>
           {sections.map((section, sectionIdx) => (
-            <YStack key={section.title} {...knobProps.gap}>
-              <Label
-                fontSize="$2"
-                fontWeight="600"
-                textTransform="uppercase"
-                color={componentColors.text.muted}
-                paddingHorizontal="$2"
-                size={knobProps.sizeToken}
-              >
-                {section.title}
-              </Label>
+            <YStack key={section.title ?? sectionIdx} {...knobProps.gap}>
+              {section.title ? (
+                <Label
+                  size={knobProps.sizeToken}
+                  fontSize="$2"
+                  fontWeight="600"
+                  textTransform="uppercase"
+                  color={componentColors.text.muted}
+                  // Align with row text (LC-02): the inset rides as MARGIN so
+                  // the caption's box starts at the shared row text edge —
+                  // padding-based insets left the box at the panel edge, which
+                  // is the exact anti-pattern the rule's origin fixed. Drop the
+                  // size-derived control height — a section caption should not
+                  // consume a 44px row.
+                  paddingHorizontal={0}
+                  marginHorizontal={rowPad}
+                  height="auto"
+                  lineHeight="$1"
+                >
+                  {section.title}
+                </Label>
+              ) : null}
 
-              <Group>
+              {/* Section group seam follows the radius knob (radius channel
+                  only): tamagui Group's built-in $4 default held a 9px arc
+                  at borderRadius:none (UX-P06 "Sidebar GroupFrames br=9"). */}
+              <Group borderRadius={knobProps.borderRadius.borderRadius}>
                 {section.items.map((item, itemIdx) => (
                   <Group.Item key={item.label}>
-                    {itemIdx > 0 && <Separator />}
+                    {itemIdx > 0 && <Separator {...hairline.line} />}
                     <ListItem
                       title={item.label}
                       subTitle={item.subTitle}
                       icon={item.icon as any}
                       iconAfter={
                         item.count !== undefined ? (
-                          <Text color={componentColors.text.muted} fontSize="$2">
+                          <Text
+                            color={item.active && onAccent ? onAccent : componentColors.text.muted}
+                            fontSize="$2"
+                          >
                             ({item.count})
                           </Text>
                         ) : undefined
                       }
                       size={knobProps.sizeToken}
+                      // SP-EDGE: the row owns its inset (space knob), on top
+                      // of a full-panel-width frame.
+                      paddingHorizontal={rowPad}
+                      // Item rows are R-SCALE (spec Sidebar): the hover /
+                      // active row surface rounds with the radius knob.
+                      borderRadius={knobProps.borderRadius.borderRadius}
                       theme={item.active ? "active" : undefined}
                       backgroundColor={item.active ? "$accentBackground" : "transparent"}
+                      // Label rides the accent fill: luminance-computed fg
+                      // (ListItem shares `color` with its title via context).
+                      {...(item.active && onAccent ? { color: onAccent } : undefined)}
                       hoverStyle={{ backgroundColor: componentColors.surface.background }}
                       pressStyle={{ backgroundColor: componentColors.interactive.background }}
                       cursor={item.onPress ? "pointer" : "default"}
                       onPress={item.onPress}
+                      {...(item.onPress
+                        ? {
+                            role: "button" as const,
+                            tabIndex: 0,
+                            focusVisibleStyle: {
+                              outlineColor: "$outlineColor",
+                              outlineWidth: 2,
+                              outlineStyle: "solid" as const,
+                              outlineOffset: -2,
+                            },
+                            onKeyDown: ((e: React.KeyboardEvent) => {
+                              if (e.key === "Enter" || e.key === " ") {
+                                e.preventDefault();
+                                item.onPress?.();
+                              }
+                            }) as unknown as () => void,
+                          }
+                        : undefined)}
                     />
                   </Group.Item>
                 ))}
               </Group>
 
-              {sectionIdx < sections.length - 1 && <Separator />}
+              {sectionIdx < sections.length - 1 && <Separator {...hairline.line} />}
             </YStack>
           ))}
         </YStack>

package/src/layouts/tags-trigger.spec.tsx

@@ -0,0 +1,73 @@
+// Regression test for the Tags "Add Tag" trigger scale (post Tags→Chip
+// consolidation): the trigger previously rendered as a Tamagui Button whose
+// size token sets a fixed field height ($4 → 44px) — 2x the content-driven
+// Chip pill (22px). The trigger now shares ChipFrame/ChipText, so its
+// padding/font atomic classes must match the pills exactly and it must not
+// carry a fixed height class.
+// jsdom's getComputedStyle cannot cascade Tamagui's class-based CSS, so this
+// asserts on the atomic classes (same approach as timeline-radius.spec.tsx).
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Tags } from "./tags";
+
+afterEach(cleanup);
+
+const tags = [{ id: "tag-1", label: "urgent" }];
+
+function classesByPrefix(el: Element, prefixes: string[]): string[] {
+  return String(el.className || "")
+    .split(" ")
+    .filter((c) => prefixes.some((p) => c.startsWith(p)))
+    .sort();
+}
+
+/** Walk up from the chip label to the ChipFrame (first ancestor with padding classes). */
+function chipFrameOf(label: HTMLElement): HTMLElement {
+  let el: HTMLElement | null = label.parentElement;
+  for (let i = 0; i < 8 && el; i++) {
+    if (classesByPrefix(el, ["_pt-", "_pl-"]).length > 0) return el;
+    el = el.parentElement;
+  }
+  throw new Error("chip frame not found");
+}
+
+function renderTags() {
+  return renderWithProviders(<Tags tags={tags} onAdd={vi.fn()} onRemove={vi.fn()} />);
+}
+
+describe("Tags Add Tag trigger (chip-scale)", () => {
+  it("trigger padding classes match the chip pill exactly", () => {
+    renderTags();
+    const chip = chipFrameOf(screen.getByText("urgent"));
+    const trigger = screen.getByLabelText("Add Tag");
+    const paddingPrefixes = ["_pt-", "_pb-", "_pl-", "_pr-"];
+    expect(classesByPrefix(trigger, paddingPrefixes)).toEqual(
+      classesByPrefix(chip, paddingPrefixes),
+    );
+  });
+
+  it("trigger has no fixed height class (content-driven like the chip)", () => {
+    renderTags();
+    const chip = chipFrameOf(screen.getByText("urgent"));
+    const trigger = screen.getByLabelText("Add Tag");
+    expect(classesByPrefix(trigger, ["_h-"])).toEqual(classesByPrefix(chip, ["_h-"]));
+    expect(classesByPrefix(trigger, ["_h-"])).toEqual([]);
+  });
+
+  it("trigger label font size class matches the chip label", () => {
+    renderTags();
+    const chipLabel = screen.getByText("urgent");
+    const triggerLabel = screen.getByText("Add Tag");
+    expect(classesByPrefix(triggerLabel, ["_fos-"])).toEqual(classesByPrefix(chipLabel, ["_fos-"]));
+  });
+
+  it("clicking the trigger opens the add-tag panel", async () => {
+    renderTags();
+    fireEvent.click(screen.getByLabelText("Add Tag"));
+    await waitFor(() => {
+      expect(document.querySelector('input[placeholder="Add tag..."]')).toBeTruthy();
+    });
+  });
+});