@multiplatform.one/components 6.1.0 → 6.3.0

package/src/ProgressSteps/index.tsx

@@ -0,0 +1,291 @@
+import { CheckIcon } from "@phosphor-icons/react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useTranslation } from "react-i18next";
+import type { ReactNode } from "react";
+import type { GetProps } from "tamagui";
+import { SizableText, View, XStack, YStack, styled } from "tamagui";
+import { componentColors } from "../componentColors";
+import { withInterp } from "../shared/t";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface ProgressStep {
+  /** Stable id (falls back to index). */
+  id?: string;
+  /** Step label shown under / beside the marker. */
+  label: ReactNode;
+  /** Optional secondary line. */
+  description?: ReactNode;
+  /** Force completed even when index >= current. */
+  completed?: boolean;
+  /** Disable jump-to for this step. */
+  disabled?: boolean;
+}
+
+export interface ProgressStepsProps extends Omit<GetProps<typeof StepsRoot>, "children"> {
+  /** Ordered steps. */
+  steps: ProgressStep[];
+  /** Current (0-based) step index. */
+  current: number;
+  /** Called when an interactive step is activated. */
+  onStepChange?: (index: number) => void;
+  /** Orientation. @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Allow clicking completed / upcoming steps when onStepChange is set. */
+  allowJump?: boolean;
+  /** Compact markers + type. */
+  compact?: boolean;
+}
+
+type StepState = "completed" | "current" | "upcoming";
+
+// ── Knob-derived geometry ─────────────────────────────────────
+// Markers are R-PILL (always circles); their diameter, glyph, and type scale
+// with the size knob (LC-18; Pagination-indicator class). The `compact` prop
+// steps the resolved sizeToken down via useResolvedKnobs, so medium+compact
+// lands on the old 22px marker.
+
+const markerSizeMap: Record<string, number> = { $3: 22, $4: 28, $5: 34 };
+const markerIconSizeMap: Record<string, number> = { $3: 12, $4: 14, $5: 16 };
+const markerTextSizeMap: Record<string, string> = { $3: "$1", $4: "$2", $5: "$3" };
+const labelSizeMap: Record<string, string> = { $3: "$2", $4: "$3", $5: "$4" };
+
+// space→gap map in the house helper pattern (getTableCellPadding precedent):
+// medium equals the previous hardcoded values so default density is unchanged.
+const stepGapMap: Record<string, { step: string; markerLabel: string }> = {
+  small: { step: "$1.5", markerLabel: "$2" },
+  medium: { step: "$2", markerLabel: "$3" },
+  large: { step: "$3", markerLabel: "$4" },
+};
+
+// ── Styled ────────────────────────────────────────────────────
+
+const StepsRoot = styled(YStack, {
+  name: "ProgressSteps",
+  width: "100%",
+});
+
+const Marker = styled(View, {
+  name: "ProgressStepMarker",
+  alignItems: "center",
+  justifyContent: "center",
+  borderRadius: 1000,
+  borderWidth: 2,
+  flexShrink: 0,
+});
+
+// ── Helpers ───────────────────────────────────────────────────
+
+function stepState(index: number, current: number, forcedCompleted?: boolean): StepState {
+  if (forcedCompleted || index < current) return "completed";
+  if (index === current) return "current";
+  return "upcoming";
+}
+
+// ── Component ─────────────────────────────────────────────────
+
+/**
+ * Multi-step wizard / progress indicator (gallery: Progress indicator /
+ * Stepper / Steps). Distinct from forms Progress (continuous bar) and
+ * forms Stepper (quantity nudger). Timeline covers the chronological alias.
+ */
+export function ProgressSteps({
+  steps,
+  current,
+  onStepChange,
+  orientation = "horizontal",
+  allowJump = true,
+  compact = false,
+  ...props
+}: ProgressStepsProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "ProgressSteps", compact });
+  const markerSize = markerSizeMap[knobProps.sizeToken] ?? 28;
+  const markerIconSize = markerIconSizeMap[knobProps.sizeToken] ?? 14;
+  const markerTextSize = markerTextSizeMap[knobProps.sizeToken] ?? "$2";
+  const labelSize = labelSizeMap[knobProps.sizeToken] ?? "$3";
+  const gaps = stepGapMap[knobProps.space] ?? stepGapMap.medium;
+  const connectorThickness = 2;
+  const interactive = !!onStepChange && allowJump;
+  const horizontal = orientation === "horizontal";
+
+  return (
+    <StepsRoot role="list" aria-label={t("Progress")} {...props}>
+      <XStack
+        flexDirection={horizontal ? "row" : "column"}
+        alignItems={horizontal ? "flex-start" : "stretch"}
+        width="100%"
+        gap={horizontal ? 0 : (gaps.step as any)}
+      >
+        {steps.map((step, index) => {
+          const state = stepState(index, current, step.completed);
+          const isLast = index === steps.length - 1;
+          const canActivate = interactive && !step.disabled && state !== "current";
+          const markerBg =
+            state === "completed"
+              ? componentColors.indicator.completed
+              : state === "current"
+                ? componentColors.indicator.current
+                : componentColors.interactive.background;
+          const markerBorder = state === "upcoming" ? componentColors.indicator.track : markerBg;
+          const markerFg = state === "upcoming" ? componentColors.text.muted : "$color1";
+
+          const marker = (
+            <Marker
+              width={markerSize}
+              height={markerSize}
+              backgroundColor={markerBg}
+              borderColor={markerBorder}
+              {...(state === "current"
+                ? ({ "aria-current": "step" } as Record<string, unknown>)
+                : undefined)}
+            >
+              {state === "completed" ? (
+                <CheckIcon size={markerIconSize} color="white" weight="bold" />
+              ) : (
+                <SizableText
+                  fontSize={markerTextSize as any}
+                  fontWeight="600"
+                  color={state === "current" ? "$color1" : markerFg}
+                >
+                  {index + 1}
+                </SizableText>
+              )}
+            </Marker>
+          );
+
+          const labelBlock = (
+            <YStack
+              gap="$0.5"
+              flexShrink={1}
+              {...(horizontal
+                ? { alignItems: "center", marginTop: gaps.step as any, maxWidth: 140 }
+                : { flexGrow: 1, justifyContent: "center" })}
+            >
+              <SizableText
+                {...knobProps.body}
+                fontSize={labelSize as any}
+                fontWeight={state === "current" ? "600" : "500"}
+                color={
+                  state === "upcoming" ? componentColors.text.muted : componentColors.text.primary
+                }
+                // undefined = natural start alignment, so vertical labels mirror in RTL
+                textAlign={horizontal ? "center" : undefined}
+              >
+                {step.label}
+              </SizableText>
+              {step.description != null ? (
+                <SizableText
+                  fontSize="$1"
+                  color={componentColors.text.muted}
+                  textAlign={horizontal ? "center" : undefined}
+                >
+                  {step.description}
+                </SizableText>
+              ) : null}
+            </YStack>
+          );
+
+          const connector =
+            !isLast && horizontal ? (
+              <View
+                flexGrow={1}
+                height={connectorThickness}
+                backgroundColor={
+                  index < current
+                    ? componentColors.indicator.completed
+                    : componentColors.indicator.track
+                }
+                marginTop={(markerSize - connectorThickness) / 2}
+                marginHorizontal={gaps.step as any}
+                minWidth={16}
+              />
+            ) : !isLast && !horizontal ? (
+              <View
+                width={connectorThickness}
+                height={20}
+                backgroundColor={
+                  index < current
+                    ? componentColors.indicator.completed
+                    : componentColors.indicator.track
+                }
+                marginInlineStart={(markerSize - connectorThickness) / 2}
+                marginVertical={2}
+              />
+            ) : null;
+
+          const body = horizontal ? (
+            <YStack
+              role="listitem"
+              alignItems="center"
+              flexShrink={0}
+              opacity={step.disabled ? 0.45 : 1}
+            >
+              {marker}
+              {labelBlock}
+            </YStack>
+          ) : (
+            <XStack
+              role="listitem"
+              alignItems="flex-start"
+              gap={gaps.markerLabel as any}
+              opacity={step.disabled ? 0.45 : 1}
+            >
+              {marker}
+              {labelBlock}
+            </XStack>
+          );
+
+          const wrapped = canActivate ? (
+            <View
+              key={step.id ?? index}
+              role="button"
+              tabIndex={0}
+              cursor="pointer"
+              flexGrow={horizontal ? 0 : undefined}
+              flexShrink={horizontal ? 0 : undefined}
+              aria-label={withInterp(t("Go to step {{number}}: {{label}}"), {
+                number: index + 1,
+                label: typeof step.label === "string" ? step.label : index + 1,
+              })}
+              onPress={() => onStepChange?.(index)}
+              focusVisibleStyle={{
+                outlineColor: "$outlineColor",
+                outlineWidth: 2,
+                outlineStyle: "solid",
+                outlineOffset: 2,
+              }}
+              {...({
+                onKeyDown: (e: { key?: string; preventDefault?: () => void }) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault?.();
+                    onStepChange?.(index);
+                  }
+                },
+              } as Record<string, unknown>)}
+            >
+              {body}
+            </View>
+          ) : (
+            <View key={step.id ?? index} flexShrink={horizontal ? 0 : undefined}>
+              {body}
+            </View>
+          );
+
+          return (
+            <XStack
+              key={`row-${step.id ?? index}`}
+              flexDirection={horizontal ? "row" : "column"}
+              alignItems={horizontal ? "flex-start" : "stretch"}
+              flexGrow={horizontal ? 1 : undefined}
+              flexBasis={horizontal ? 0 : undefined}
+            >
+              {wrapped}
+              {connector}
+            </XStack>
+          );
+        })}
+      </XStack>
+    </StepsRoot>
+  );
+}

package/src/Quote/Quote.spec.tsx

@@ -0,0 +1,17 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { Quote } from "./index";
+
+describe("Quote", () => {
+  it("renders as a blockquote with body text", () => {
+    const { container } = renderWithProviders(<Quote>Invent the future.</Quote>);
+    expect(container.querySelector("blockquote")).toBeTruthy();
+    expect(container.textContent).toContain("Invent the future.");
+  });
+
+  it("renders cite attribution", () => {
+    const { container } = renderWithProviders(<Quote cite="Alan Kay">Invent the future.</Quote>);
+    expect(container.textContent).toContain("Alan Kay");
+    expect(container.querySelector("cite")).toBeTruthy();
+  });
+});

package/src/Quote/Quote.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import { Quote } from "./index";
+
+const meta: Meta<typeof Quote> = {
+  title: "Components/Quote",
+  component: Quote,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Standalone pull / block quote with logical-start accent bar (RTL-safe). Same chrome as markdown Blockquote, usable outside MDX.",
+      },
+    },
+  },
+  argTypes: {
+    children: { control: "text" },
+    cite: { control: "text" },
+    compact: { control: "boolean" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Quote>;
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    children: "The best way to predict the future is to invent it.",
+    cite: "Alan Kay",
+  },
+};
+
+export const WithoutCite: Story = {
+  args: {
+    children: "Simplicity is a great virtue but it requires hard work to achieve it.",
+  },
+};
+
+export const Compact: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={480}>
+      <Quote compact cite="Design guidelines">
+        Prefer one composition over a dashboard of cards.
+      </Quote>
+      <Quote compact>Short callout without attribution.</Quote>
+    </YStack>
+  ),
+};

package/src/Quote/index.tsx

@@ -0,0 +1,100 @@
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import type { GetProps } from "tamagui";
+import { SizableText, View, YStack, getTokens, isWeb, styled, useTheme } from "tamagui";
+import { componentColors } from "../componentColors";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface QuoteProps extends Omit<GetProps<typeof QuoteFrame>, "children"> {
+  /** Quote body. */
+  children: ReactNode;
+  /** Attribution / cite line. */
+  cite?: ReactNode;
+  /** Compact padding / type. */
+  compact?: boolean;
+}
+
+// ── Styled ────────────────────────────────────────────────────
+
+const QuoteFrame = styled(YStack, {
+  name: "Quote",
+  width: "100%",
+});
+
+// ── Component ─────────────────────────────────────────────────
+
+/**
+ * Standalone pull / block quote. Mirrors the markdown Blockquote chrome
+ * (logical-start accent bar) for use outside MDX.
+ */
+export function Quote({ children, cite, compact = false, ...props }: QuoteProps) {
+  const { knobProps } = useResolvedKnobs({ component: "Quote", compact });
+  const theme = useTheme();
+  const padToken = (compact ? "$3" : knobProps.panelPadding.padding) as number | string;
+  const pad =
+    typeof padToken === "number"
+      ? padToken
+      : ((getTokens().space as any)?.[padToken]?.val ?? padToken);
+
+  return (
+    <QuoteFrame
+      render="blockquote"
+      backgroundColor={componentColors.surface.background}
+      // Padded card frame: radius follows the knob with the Axiom 1
+      // child-clip cap (R-SCALE + cap, Blockquote contract).
+      {...knobProps.containerRadius}
+      paddingVertical={compact ? "$2" : knobProps.gap.gap}
+      marginVertical={compact ? "$2" : "$3"}
+      {...(isWeb
+        ? {
+            style: {
+              borderInlineStartWidth: 4,
+              borderInlineStartStyle: "solid",
+              borderInlineStartColor: theme.color8?.val ?? theme.color8?.get() ?? "#999",
+              paddingInlineStart: pad,
+              marginInlineStart: 0,
+              marginInlineEnd: 0,
+            } as Record<string, unknown>,
+          }
+        : {
+            borderStartWidth: 4,
+            borderStartColor: componentColors.indicator.track,
+            paddingStart: padToken,
+          })}
+      {...props}
+    >
+      {typeof children === "string" ? (
+        <SizableText
+          {...knobProps.body}
+          // Quote body scales with the size knob (compact already steps the
+          // resolved sizeToken down one level via useResolvedKnobs).
+          fontSize={knobProps.sizeToken as any}
+          color={componentColors.text.primary}
+          fontStyle="italic"
+          lineHeight={knobProps.sizeToken as any}
+        >
+          {children}
+        </SizableText>
+      ) : (
+        children
+      )}
+      {cite != null ? (
+        <View marginTop={compact ? "$1.5" : "$2"}>
+          {typeof cite === "string" ? (
+            <SizableText
+              render="cite"
+              fontSize={compact ? "$1" : "$2"}
+              color={componentColors.text.muted}
+              fontStyle="normal"
+            >
+              — {cite}
+            </SizableText>
+          ) : (
+            cite
+          )}
+        </View>
+      ) : null}
+    </QuoteFrame>
+  );
+}

package/src/SheetFrame.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useEffect, useState } from "react";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { isWeb, Paragraph, SizableText, YStack } from "tamagui";
+import { SheetModal } from "./SheetModal";
+import { SheetFrame } from "./surfaces";
+
+function SheetHarness({ long = false, startOpen = true }: { long?: boolean; startOpen?: boolean }) {
+  const [open, setOpen] = useState(startOpen);
+  // Tamagui Sheet has no key handling of its own (Dialog dismisses via
+  // Dismissable; Sheet does not), so Escape must be wired here for the
+  // dismissal intent to reach the sheet at all. Bubble phase: inner popups
+  // that own Escape stopPropagation() and keep the sheet open.
+  useEffect(() => {
+    if (!isWeb || !open) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape" || event.defaultPrevented) return;
+      setOpen(false);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [open]);
+  return (
+    <YStack minHeight={480}>
+      <Button onPress={() => setOpen(true)}>Open sheet</Button>
+      {/* SheetModal: tamagui Sheet modal on web; RN Modal on native (raw
+          Sheet cannot (re)present from a trigger tap on device). */}
+      <SheetModal
+        open={open}
+        onOpenChange={setOpen}
+        scrollable={long}
+        header={<SizableText fontWeight="600">Sheet title</SizableText>}
+      >
+        {long ? (
+          <YStack gap="$2">
+            {Array.from({ length: 40 }).map((_, i) => (
+              <Paragraph key={i}>Sheet scroll line {i + 1}.</Paragraph>
+            ))}
+          </YStack>
+        ) : (
+          <Paragraph>Short sheet body content.</Paragraph>
+        )}
+      </SheetModal>
+    </YStack>
+  );
+}
+
+const meta: Meta<typeof SheetFrame> = {
+  title: "Components/SheetFrame",
+  component: SheetFrame,
+  parameters: {
+    status: { type: "beta" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Sheet.Frame wrapper applying surface, borderRadius and panelPadding knob recipes (no elevation — the modal overlay separates).",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SheetFrame>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => <SheetHarness />,
+};
+
+export const LongScroll: Story = {
+  render: () => <SheetHarness long />,
+};
+
+export const Closed: Story = {
+  render: () => <SheetHarness startOpen={false} />,
+};

package/src/SheetModal/index.native.tsx

@@ -0,0 +1,140 @@
+/**
+ * SheetModal (native) — React Native Modal bottom sheet.
+ *
+ * The web implementation (./index.tsx) renders a tamagui `Sheet modal`. On
+ * device (Expo Go, tamagui 2.0.0-rc.41) the modal Sheet's portal/animation
+ * machinery never (re)presents from a trigger tap — flipping `open` shows
+ * nothing (mount-time opens present once, then the sheet is dead). This twin
+ * swaps the overlay for a core React Native `Modal`, a native
+ * view-controller presentation: no portal host, no animation driver — the
+ * exact workaround proven by forms' FloatingPanel (index.native.tsx).
+ *
+ * Semantics preserved:
+ * - `open` presents; slide-up from the bottom, themed surface, drag-handle
+ *   affordance, safe-area padding
+ * - backdrop tap and the Android back button dismiss (onOpenChange(false))
+ * - VoiceOver escape gesture (two-finger Z) dismisses
+ * - opening tap cannot instantly self-dismiss (backdrop arms after onShow)
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  KeyboardAvoidingView,
+  Modal,
+  Platform,
+  Pressable,
+  ScrollView as RNScrollView,
+  StyleSheet,
+  useWindowDimensions,
+} from "react-native";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useTranslation } from "react-i18next";
+import { View, YStack } from "tamagui";
+
+import type { SheetModalProps } from "./index";
+export type { SheetModalProps } from "./index";
+
+const sheetMaxHeightRatio = 0.85;
+// Home-indicator / gesture-bar clearance (no react-native-safe-area-context
+// dependency in this package).
+const bottomInset = Platform.OS === "ios" ? 24 : 16;
+
+export function SheetModal({
+  open,
+  onOpenChange,
+  children,
+  header,
+  snapPoint: _snapPoint,
+  scrollable,
+}: SheetModalProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const { height: windowHeight } = useWindowDimensions();
+  const [backdropArmed, setBackdropArmed] = useState(false);
+  const armTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+
+  const handleBackdropPress = useCallback(() => {
+    if (backdropArmed) close();
+  }, [backdropArmed, close]);
+
+  const handleModalShow = useCallback(() => {
+    if (armTimerRef.current) clearTimeout(armTimerRef.current);
+    // One frame + small delay so the opening tap cannot dismiss immediately.
+    armTimerRef.current = setTimeout(() => setBackdropArmed(true), 280);
+  }, []);
+
+  useEffect(() => {
+    if (!open) {
+      setBackdropArmed(false);
+      if (armTimerRef.current) {
+        clearTimeout(armTimerRef.current);
+        armTimerRef.current = null;
+      }
+    }
+    return () => {
+      if (armTimerRef.current) clearTimeout(armTimerRef.current);
+    };
+  }, [open]);
+
+  const maxHeight = Math.round(windowHeight * sheetMaxHeightRatio);
+
+  return (
+    <Modal
+      visible={open}
+      transparent
+      animationType="slide"
+      statusBarTranslucent
+      onRequestClose={close}
+      onShow={handleModalShow}
+    >
+      <KeyboardAvoidingView
+        style={{ flex: 1, justifyContent: "flex-end" }}
+        behavior={Platform.OS === "ios" ? "padding" : undefined}
+      >
+        <Pressable
+          style={StyleSheet.absoluteFill}
+          onPress={handleBackdropPress}
+          accessibilityRole="button"
+          accessibilityLabel={t("Close")}
+        >
+          <View flex={1} backgroundColor="rgba(0,0,0,0.4)" />
+        </Pressable>
+        {/* Sheet sits above the absoluteFill backdrop in z-order (later
+            sibling). Do NOT claim the responder on a wrapper here — that
+            steals presses from content controls. */}
+        <YStack
+          backgroundColor="$background"
+          borderTopLeftRadius="$6"
+          borderTopRightRadius="$6"
+          maxHeight={maxHeight}
+          paddingTop="$2"
+          paddingBottom={bottomInset}
+          elevation="$4"
+          // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
+          onAccessibilityEscape={close}
+        >
+          <View
+            alignSelf="center"
+            width={40}
+            height={4}
+            borderRadius={2}
+            backgroundColor="$color8"
+            marginBottom="$2"
+          />
+          <YStack padding={knobProps.panelPadding.padding} gap={knobProps.gap.gap} flexShrink={1}>
+            {header}
+            {scrollable ? (
+              <RNScrollView style={{ flexGrow: 0 }} keyboardShouldPersistTaps="handled">
+                {children}
+              </RNScrollView>
+            ) : (
+              children
+            )}
+          </YStack>
+        </YStack>
+      </KeyboardAvoidingView>
+    </Modal>
+  );
+}