@multiplatform.one/components 6.1.0 → 6.4.0

package/src/Tabs/index.tsx

@@ -0,0 +1,541 @@
+/**
+ * Tabs — themed app-level tabs over the tamagui Tabs primitive.
+ *
+ * Wraps `tamagui`'s Tabs (roving focus, tablist/tab/tabpanel aria, automatic
+ * or manual activation) and adds MP1 anatomy + knob wiring:
+ *
+ * - variants: `underline` (desk-style, default) and `contained` (segmented
+ *   track with a sliding content-bearing thumb)
+ * - knobs: size (tab height/font), space (tab gap), radius (contained track
+ *   and thumb), animation (active indicator slide), elevation (thumb)
+ * - intent: accent (default indicator hue) / error / warning / success
+ * - overflow: horizontal scroll with web edge fades when tabs exceed width
+ * - lazyMount: panels mount on first visit and stay mounted (state preserved)
+ *
+ * The strip is EDGE-TO-EDGE (SP-EDGE): padding lives inside each tab, the
+ * underline hairline spans the full wrapper width.
+ */
+
+import {
+  MIN_PRESS_TARGET,
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import React from "react";
+import { useTranslation } from "react-i18next";
+import type { GetProps, ThemeName } from "tamagui";
+import {
+  ScrollView,
+  Tabs as TamaguiTabs,
+  Text,
+  Theme,
+  View,
+  XStack,
+  YStack,
+  getTokens,
+  isWeb,
+  styled,
+} from "tamagui";
+import { componentColors } from "../componentColors";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export type TabsVariant = "underline" | "contained";
+export type TabsSize = "$2" | "$3" | "$4" | "$5";
+
+export interface TabsItem {
+  /** Unique value identifying the tab (used for value/onChange) */
+  value: string;
+  /** Tab label */
+  label: ReactNode;
+  /** Optional leading icon */
+  icon?: ReactNode;
+  /** Optional trailing adornment (e.g. a Badge/count pill) */
+  badge?: ReactNode;
+  /** Disable just this tab */
+  disabled?: boolean;
+  /** Panel content shown when the tab is active */
+  content?: ReactNode;
+}
+
+export interface TabsProps {
+  /** Tabs to render */
+  items: TabsItem[];
+  /** Controlled active value */
+  value?: string;
+  /** Uncontrolled initial value (defaults to the first item) */
+  defaultValue?: string;
+  /** Called when the active tab changes */
+  onChange?: (value: string) => void;
+  /** underline (desk-style, default) or contained (segmented track) */
+  variant?: TabsVariant;
+  /** Accent intent for the active indicator (default) */
+  accent?: boolean;
+  /** Error intent */
+  error?: boolean;
+  /** Warning intent */
+  warning?: boolean;
+  /** Success intent */
+  success?: boolean;
+  /** Size token override for tab height/font */
+  size?: TabsSize;
+  /** Compact sizing (steps size and space down one level) */
+  compact?: boolean;
+  /** Mount panels on first visit and keep them mounted (preserves state) */
+  lazyMount?: boolean;
+  /** automatic (focus selects, default) or manual (Enter/Space selects). Web only. */
+  activationMode?: "automatic" | "manual";
+  /** Loop arrow-key navigation past the ends */
+  loop?: boolean;
+  /** Disable the whole tab strip */
+  disabled?: boolean;
+}
+
+interface TabLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+// Tabbing into the strip focuses the tablist container first; tamagui's
+// roving-focus group then redirects focus to the current tab from inside a
+// focusin handler. Chromium drops keyboard modality on that script focus, so
+// neither :focus-visible nor focusVisibleStyle fire for the redirected tab —
+// the ring is painted manually via the theme keyboard-modality tracker.
+
+// ── Styled components ─────────────────────────────────────────
+
+const StripWrapper = styled(View, {
+  name: "MpTabsStrip",
+  width: "100%",
+  position: "relative",
+
+  variants: {
+    underline: {
+      true: {
+        borderBottomWidth: 1,
+        borderColor: componentColors.surface.border,
+      },
+    },
+  } as const,
+});
+
+const TabsList = styled(TamaguiTabs.List, {
+  name: "MpTabsList",
+  unstyled: true,
+  flexDirection: "row",
+  alignItems: "stretch",
+  alignSelf: "flex-start",
+  position: "relative",
+});
+
+const Trigger = styled(TamaguiTabs.Tab, {
+  name: "MpTabsTab",
+  unstyled: true,
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "center",
+  backgroundColor: "transparent",
+  borderWidth: 0,
+  cursor: "pointer",
+  zIndex: 1,
+  paddingHorizontal: "$3",
+
+  focusVisibleStyle: {
+    outlineColor: "$outlineColor",
+    outlineWidth: 2,
+    outlineStyle: "solid",
+    outlineOffset: -2,
+  },
+});
+
+const UnderlineIndicator = styled(View, {
+  name: "MpTabsUnderline",
+  position: "absolute",
+  bottom: 0,
+  height: 2,
+  borderRadius: 1,
+  backgroundColor: "$color9",
+});
+
+// NEUTRAL raised surface (deliberately outside the intent Theme: intent
+// sub-theme ramps stay hue-anchored at every step, so no step reads as a
+// neutral thumb). The intent hue rides on a border overlay child instead.
+const ThumbIndicator = styled(View, {
+  name: "MpTabsThumb",
+  position: "absolute",
+  backgroundColor: "$background",
+});
+
+// Intent-hued hairline: $color9 measures >=3:1 against the thumb in both
+// schemes (non-text UI contrast), where $color11 washes out on light.
+const ThumbBorder = styled(View, {
+  name: "MpTabsThumbBorder",
+  position: "absolute",
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  borderWidth: 1,
+  borderColor: "$color9",
+});
+
+const TabLabel = styled(Text, {
+  name: "MpTabsLabel",
+  numberOfLines: 1,
+  userSelect: "none",
+});
+
+// ── Maps ──────────────────────────────────────────────────────
+
+// knob sizeToken → label font size (one step down keeps desk-density labels)
+const fontSizeMap: Record<string, string> = {
+  $3: "$2",
+  $4: "$3",
+  $5: "$4",
+};
+
+// ── Tabs Component ────────────────────────────────────────────
+
+export function Tabs({
+  items,
+  value,
+  defaultValue,
+  onChange,
+  variant = "underline",
+  accent,
+  error,
+  warning,
+  success,
+  size,
+  compact,
+  lazyMount = false,
+  activationMode = "automatic",
+  loop = true,
+  disabled = false,
+}: TabsProps) {
+  const { t } = useTranslation();
+  const intent =
+    (accent && "accent") ||
+    (error && "error") ||
+    (warning && "warning") ||
+    (success && "success") ||
+    undefined;
+  const { knobProps } = useResolvedKnobs({ intent, component: "Tabs", size, compact });
+
+  if (isWeb) ensureKeyboardModalityTracking();
+  // Tab value currently showing the manual keyboard focus ring (see tracker note)
+  const [kbFocusValue, setKbFocusValue] = React.useState<string | null>(null);
+  // Roving anchor: while a tab is focused it owns the tablist's single tab
+  // stop (Shift+Tab exits instead of hopping to the selected tab — matters
+  // in manual activation mode where focus and selection diverge).
+  const [focusValue, setFocusValue] = React.useState<string | null>(null);
+
+  const [internalValue, setInternalValue] = React.useState(
+    () => defaultValue ?? items[0]?.value ?? "",
+  );
+  const currentValue = value ?? internalValue;
+
+  const [visited, setVisited] = React.useState<ReadonlySet<string>>(
+    () => new Set(currentValue ? [currentValue] : []),
+  );
+  React.useEffect(() => {
+    if (!currentValue) return;
+    setVisited((prev) => {
+      if (prev.has(currentValue)) return prev;
+      const next = new Set(prev);
+      next.add(currentValue);
+      return next;
+    });
+  }, [currentValue]);
+
+  const handleChange = (next: string) => {
+    if (value === undefined) setInternalValue(next);
+    onChange?.(next);
+  };
+
+  // Active tab layout (relative to the list) for the sliding indicator
+  const [activeLayout, setActiveLayout] = React.useState<TabLayout | null>(null);
+  const handleInteraction = (type: string, layout: TabLayout | null) => {
+    if (type !== "select" || !layout) return;
+    setActiveLayout((prev) =>
+      prev &&
+      prev.x === layout.x &&
+      prev.y === layout.y &&
+      prev.width === layout.width &&
+      prev.height === layout.height
+        ? prev
+        : layout,
+    );
+  };
+
+  // Overflow tracking for edge fades + keep-active-visible scrolling
+  const scrollRef = React.useRef<ScrollView>(null);
+  const scrollMetrics = React.useRef({ offset: 0, viewport: 0, content: 0 });
+  const [fades, setFades] = React.useState({ left: false, right: false });
+  const updateFades = () => {
+    const { offset, viewport, content } = scrollMetrics.current;
+    const left = offset > 4;
+    const right = content - viewport - offset > 4;
+    setFades((prev) => (prev.left === left && prev.right === right ? prev : { left, right }));
+  };
+
+  // Scroll the newly active tab into view when it is clipped
+  React.useEffect(() => {
+    if (!activeLayout) return;
+    const { offset, viewport, content } = scrollMetrics.current;
+    if (content <= viewport) return;
+    const pad = 32;
+    let target: number | undefined;
+    if (activeLayout.x < offset + pad) {
+      target = Math.max(0, activeLayout.x - pad);
+    } else if (activeLayout.x + activeLayout.width > offset + viewport - pad) {
+      target = Math.min(content - viewport, activeLayout.x + activeLayout.width - viewport + pad);
+    }
+    if (target !== undefined) {
+      scrollRef.current?.scrollTo({ x: target, animated: true });
+    }
+  }, [activeLayout]);
+
+  const isUnderline = variant === "underline";
+  const indicatorTheme = (intent ?? "accent") as ThemeName;
+  const sizeToken = knobProps.sizeToken;
+  // DG-LAY-04 / D-02 press-floor: small size knobs ($2/$3) shrink the visual
+  // strip below 44 — the trigger box is floored at 44 via the house
+  // pressTarget* channel (minHeight + negative vertical outset keeps the
+  // strip's layout height at the knob size; hit area extends past the strip).
+  const sizePx = (getTokens().size as any)?.[sizeToken]?.val ?? MIN_PRESS_TARGET;
+  const triggerOutset = Math.max(0, Math.ceil((MIN_PRESS_TARGET - sizePx) / 2));
+  const fontSize = fontSizeMap[sizeToken] ?? "$3";
+  const gapToken = knobProps.gap.gap;
+  const radiusToken = knobProps.borderRadius.borderRadius;
+  const transition = knobProps.transition;
+
+  // Web-only edge fades: a scroll-state mask keeps the fade background-agnostic
+  const maskStyle: Record<string, string> | undefined =
+    isWeb && (fades.left || fades.right)
+      ? (() => {
+          const leftStop = fades.left ? "transparent 0px, black 32px" : "black 0px";
+          const rightStop = fades.right
+            ? "black calc(100% - 32px), transparent 100%"
+            : "black 100%";
+          const mask = `linear-gradient(to right, ${leftStop}, ${rightStop})`;
+          return { maskImage: mask, WebkitMaskImage: mask };
+        })()
+      : undefined;
+
+  const indicator = activeLayout ? (
+    isUnderline ? (
+      <Theme name={indicatorTheme}>
+        <UnderlineIndicator
+          x={activeLayout.x}
+          width={activeLayout.width}
+          {...(transition ? { transition } : undefined)}
+        />
+      </Theme>
+    ) : (
+      <ThumbIndicator
+        x={activeLayout.x}
+        // The trigger's measured box includes the press-floor outset; the
+        // painted thumb keeps the knob-sized visual geometry.
+        y={activeLayout.y + triggerOutset}
+        width={activeLayout.width}
+        height={Math.max(0, activeLayout.height - triggerOutset * 2)}
+        borderRadius={radiusToken}
+        {...(knobProps.elevation !== undefined ? { elevation: knobProps.elevation } : undefined)}
+        {...(transition ? { transition } : undefined)}
+      >
+        <Theme name={indicatorTheme}>
+          <ThumbBorder borderRadius={radiusToken} />
+        </Theme>
+      </ThumbIndicator>
+    )
+  ) : null;
+
+  return (
+    <TamaguiTabs
+      value={currentValue}
+      onValueChange={handleChange}
+      orientation="horizontal"
+      activationMode={activationMode}
+      width="100%"
+      flexDirection="column"
+    >
+      <StripWrapper underline={isUnderline}>
+        <ScrollView
+          ref={scrollRef}
+          horizontal
+          showsHorizontalScrollIndicator={false}
+          scrollEventThrottle={16}
+          style={maskStyle as never}
+          // The scroller clips vertically; pad the content by the press-floor
+          // outset (and pull the scroller back by the same amount) so the
+          // triggers' enlarged hit boxes are never clipped. Net layout: zero.
+          contentContainerStyle={{ paddingVertical: triggerOutset }}
+          marginVertical={-triggerOutset}
+          onScroll={(e) => {
+            scrollMetrics.current.offset = e.nativeEvent.contentOffset.x;
+            updateFades();
+          }}
+          onLayout={(e) => {
+            scrollMetrics.current.viewport = e.nativeEvent.layout.width;
+            updateFades();
+          }}
+          onContentSizeChange={(w) => {
+            scrollMetrics.current.content = w;
+            updateFades();
+          }}
+        >
+          <TabsList
+            loop={loop}
+            aria-label={t("Tabs")}
+            // Native: tamagui's Tabs.List only emits ARIA (web); VO/TalkBack
+            // need the explicit container role (tamagui maps `role` to the
+            // native accessibilityRole — raw accessibility* props are dropped).
+            {...(!isWeb ? { role: "tablist" as const } : undefined)}
+            {...(isUnderline
+              ? { gap: gapToken }
+              : {
+                  backgroundColor: componentColors.interactive.background,
+                  padding: "$1",
+                  gap: "$1",
+                  // Full fragment spread (AGENTS.md knob rule) so the
+                  // cornerSmoothing class rides along with the radius.
+                  ...knobProps.borderRadiusOuter,
+                })}
+          >
+            {indicator}
+            {items.map((item, itemIndex) => {
+              const isActive = item.value === currentValue;
+              const isDisabled = disabled || item.disabled;
+              // Roving tabindex (single tab stop): tamagui's vendored
+              // roving-focus item hardcodes tabIndex=0 on every tab, making
+              // each tab its own Tab stop. Exactly one tab stays in the page
+              // tab order — the focused one while focus is in the tablist,
+              // else the active one (or the first, when value matches
+              // nothing); ArrowLeft/Right move within the tablist.
+              const anchorValue =
+                (focusValue !== null &&
+                items.some((i) => i.value === focusValue && !(disabled || i.disabled))
+                  ? focusValue
+                  : undefined) ??
+                (items.some((i) => i.value === currentValue) ? currentValue : items[0]?.value);
+              const isTabStop =
+                item.value === anchorValue &&
+                itemIndex === items.findIndex((i) => i.value === anchorValue);
+              return (
+                <Trigger
+                  key={item.value}
+                  value={item.value}
+                  disabled={isDisabled}
+                  {...(isWeb
+                    ? { tabIndex: isDisabled ? -1 : isTabStop ? 0 : -1 }
+                    : {
+                        // Native: one a11y element per tab with tab role +
+                        // selected state (the label text composes the name).
+                        // `role`/`aria-selected` are the tamagui-canonical
+                        // spellings — raw accessibilityRole/State are dropped
+                        // by the style system. Web keeps tamagui's ARIA tabs.
+                        accessible: true,
+                        role: "tab" as const,
+                        "aria-selected": isActive,
+                        ...(isDisabled ? { "aria-disabled": true } : undefined),
+                      })}
+                  height={sizeToken}
+                  minHeight={MIN_PRESS_TARGET}
+                  marginVertical={-triggerOutset}
+                  onInteraction={handleInteraction}
+                  opacity={isDisabled ? 0.4 : 1}
+                  cursor={isDisabled ? "default" : "pointer"}
+                  {...(isWeb
+                    ? {
+                        onFocus: () => {
+                          setFocusValue(item.value);
+                          if (wasKeyboardFocus()) setKbFocusValue(item.value);
+                        },
+                        onBlur: () => {
+                          setFocusValue((prev) => (prev === item.value ? null : prev));
+                          setKbFocusValue((prev) => (prev === item.value ? null : prev));
+                        },
+                      }
+                    : undefined)}
+                  {...(kbFocusValue === item.value ? keyboardFocusRingProps : undefined)}
+                  {...(!isActive && !isDisabled
+                    ? isUnderline
+                      ? {
+                          hoverStyle: { backgroundColor: "$color2" },
+                          pressStyle: { backgroundColor: "$color3" },
+                        }
+                      : {
+                          hoverStyle: { backgroundColor: "$color4" },
+                          pressStyle: { backgroundColor: "$color5" },
+                        }
+                    : undefined)}
+                  borderRadius={isUnderline ? undefined : radiusToken}
+                  {...(isUnderline
+                    ? {
+                        borderTopLeftRadius: radiusToken,
+                        borderTopRightRadius: radiusToken,
+                      }
+                    : undefined)}
+                >
+                  <XStack alignItems="center" gap="$1.5" flexShrink={0}>
+                    {item.icon}
+                    <TabLabel
+                      fontSize={fontSize}
+                      fontFamily={knobProps.body.fontFamily}
+                      fontWeight={isActive ? "600" : knobProps.body.fontWeight}
+                      color={
+                        isActive ? componentColors.text.primary : componentColors.text.secondary
+                      }
+                    >
+                      {item.label}
+                    </TabLabel>
+                    {item.badge}
+                  </XStack>
+                </Trigger>
+              );
+            })}
+          </TabsList>
+        </ScrollView>
+      </StripWrapper>
+
+      <YStack>
+        {items.map((item) => {
+          if (item.content === undefined) return null;
+          const isActive = item.value === currentValue;
+          if (lazyMount) {
+            if (!visited.has(item.value)) return null;
+            return (
+              <TamaguiTabs.Content
+                key={item.value}
+                value={item.value}
+                forceMount
+                display={isActive ? "flex" : "none"}
+                paddingTop={gapToken}
+              >
+                {item.content}
+              </TamaguiTabs.Content>
+            );
+          }
+          return (
+            <TamaguiTabs.Content key={item.value} value={item.value} paddingTop={gapToken}>
+              {item.content}
+            </TamaguiTabs.Content>
+          );
+        })}
+      </YStack>
+    </TamaguiTabs>
+  );
+}
+
+// Re-export primitive parts for advanced composition
+Tabs.List = TamaguiTabs.List;
+Tabs.Tab = TamaguiTabs.Tab;
+Tabs.Content = TamaguiTabs.Content;
+
+export type TabsTriggerProps = GetProps<typeof Trigger>;