@multiplatform.one/components 6.1.0 → 6.3.0

package/src/Alert/Alert.stories.tsx

@@ -0,0 +1,207 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Button, Input } from "@multiplatform.one/forms";
+import { useState } from "react";
+import { SizableText, XStack, YStack } from "tamagui";
+import { Alert, type AlertIntent } from "./index";
+
+const meta: Meta<typeof Alert> = {
+  title: "Components/Alert",
+  component: Alert,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Inline Alert/Banner for form validation summaries and page-level messages. Intents ride the semantic ramp (info uses the accent hue) and any Button placed inside inherits the intent, rendering SOLID like intent Buttons everywhere else. role=alert for error/warning, role=status otherwise.",
+      },
+    },
+  },
+  argTypes: {
+    intent: { control: "select", options: ["info", "success", "warning", "error"] },
+    title: { control: "text", description: "Bold first line" },
+    children: { control: "text", description: "Description content" },
+    dismissible: { control: "boolean", description: "Show the dismiss (X) button" },
+    compact: { control: "boolean", description: "Tighter padding/type for dense layouts" },
+    actionLabel: { control: "text", description: "Convenience action button label" },
+    visible: { control: "boolean", description: "Controlled visibility" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Alert>;
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    intent: "info",
+    title: "Scheduled maintenance",
+    children: "The system will be unavailable Saturday from 02:00 to 04:00 UTC.",
+    dismissible: true,
+  },
+};
+
+export const Intents: Story = {
+  render: () => {
+    const intents: AlertIntent[] = ["info", "success", "warning", "error"];
+    const copy: Record<AlertIntent, { title: string; body: string }> = {
+      info: { title: "Heads up", body: "A new version of this document is available." },
+      success: { title: "Saved", body: "Your changes have been saved." },
+      warning: { title: "Unsaved changes", body: "You have unsaved changes on this form." },
+      error: { title: "Save failed", body: "The server rejected the document. Try again." },
+    };
+    return (
+      <YStack gap="$3" maxWidth={640}>
+        {intents.map((intent) => (
+          <Alert key={intent} intent={intent} title={copy[intent].title}>
+            {copy[intent].body}
+          </Alert>
+        ))}
+      </YStack>
+    );
+  },
+};
+
+export const WithAction: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={640}>
+      <Alert
+        intent="error"
+        title="Connection lost"
+        actionLabel="Retry"
+        onAction={() => {}}
+        dismissible
+      >
+        Changes are no longer syncing to the server.
+      </Alert>
+      <Alert intent="warning" title="Trial expiring" actionLabel="Upgrade" onAction={() => {}}>
+        Your trial ends in 3 days.
+      </Alert>
+      <Alert
+        intent="success"
+        title="Import finished"
+        action={
+          <Button compact onPress={() => {}}>
+            View log
+          </Button>
+        }
+      >
+        1,204 records imported, 0 errors.
+      </Alert>
+    </YStack>
+  ),
+};
+
+export const Compact: Story = {
+  render: () => (
+    <YStack gap="$2" maxWidth={640}>
+      <Alert compact intent="info" title="Read-only">
+        You are viewing an archived document.
+      </Alert>
+      <Alert compact intent="error" dismissible>
+        Amount must be greater than zero.
+      </Alert>
+      <Alert compact intent="success">
+        Copied to clipboard.
+      </Alert>
+    </YStack>
+  ),
+};
+
+export const TitleOnlyAndDescriptionOnly: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={640}>
+      <Alert intent="warning" title="This record is locked by another user." />
+      <Alert intent="info">Descriptions can stand alone when a title would be redundant.</Alert>
+      <Alert intent="error" icon={null} title="No icon">
+        Pass icon={"{null}"} to drop the leading icon.
+      </Alert>
+    </YStack>
+  ),
+};
+
+export const Dismissible: Story = {
+  render: () => {
+    const [visible, setVisible] = useState(true);
+    return (
+      <YStack gap="$3" maxWidth={640}>
+        <Alert intent="info" title="Uncontrolled" dismissible>
+          Dismiss hides this alert via internal state.
+        </Alert>
+        <Alert
+          intent="warning"
+          title="Controlled"
+          dismissible
+          visible={visible}
+          onDismiss={() => setVisible(false)}
+        >
+          Parent owns visibility through visible/onDismiss.
+        </Alert>
+        {!visible && (
+          <Button compact onPress={() => setVisible(true)}>
+            Restore controlled alert
+          </Button>
+        )}
+      </YStack>
+    );
+  },
+};
+
+/** Composability demo: a validation summary Alert sits directly above a real
+ * form with zero per-use styling on either side. */
+export const ValidationSummary: Story = {
+  render: () => {
+    const [name, setName] = useState("");
+    const [email, setEmail] = useState("");
+    const [errors, setErrors] = useState<string[]>([]);
+    const [saved, setSaved] = useState(false);
+
+    const submit = () => {
+      const next: string[] = [];
+      if (!name.trim()) next.push("Full name is required.");
+      if (!email.includes("@")) next.push("Email must be a valid address.");
+      setErrors(next);
+      setSaved(next.length === 0);
+    };
+
+    return (
+      <YStack gap="$4" maxWidth={480}>
+        {errors.length > 0 && (
+          <Alert
+            intent="error"
+            title={`Fix ${errors.length} problem${errors.length > 1 ? "s" : ""} before saving`}
+          >
+            <YStack gap="$1">
+              {errors.map((e) => (
+                <SizableText key={e} color="$color12" fontSize="$3" lineHeight={20}>
+                  {"•"} {e}
+                </SizableText>
+              ))}
+            </YStack>
+          </Alert>
+        )}
+        {saved && (
+          <Alert
+            intent="success"
+            title="Contact saved"
+            dismissible
+            onDismiss={() => setSaved(false)}
+          />
+        )}
+        <YStack gap="$3">
+          <Input label="Full name" placeholder="Ada Lovelace" value={name} onChangeText={setName} />
+          <Input
+            label="Email"
+            placeholder="ada@example.com"
+            value={email}
+            onChangeText={setEmail}
+          />
+          <XStack>
+            <Button accent onPress={submit}>
+              Save contact
+            </Button>
+          </XStack>
+        </YStack>
+      </YStack>
+    );
+  },
+};

package/src/Alert/index.tsx

@@ -0,0 +1,256 @@
+import { useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { Intent, useResolvedKnobs, warnBannedErrorWords } from "@multiplatform.one/theme";
+import { Button } from "@multiplatform.one/forms";
+import { CheckCircleIcon, InfoIcon, WarningIcon, XCircleIcon, XIcon } from "@phosphor-icons/react";
+import type { GetProps } from "tamagui";
+import { SizableText, View, XStack, YStack, styled, useTheme } from "tamagui";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export type AlertIntent = "info" | "success" | "warning" | "error";
+
+export interface AlertProps extends Omit<GetProps<typeof AlertFrame>, "role" | "children"> {
+  /** Semantic intent. info rides the accent hue; the rest use the semantic ramp. */
+  intent?: AlertIntent;
+  /** Bold first line. */
+  title?: ReactNode;
+  /** Description content below (or instead of) the title. */
+  children?: ReactNode;
+  /** Override the intent icon; pass null to hide it. */
+  icon?: ReactNode | null;
+  /** Custom trailing action slot (any node; Buttons inherit the intent and render solid). */
+  action?: ReactNode;
+  /** Convenience action button label (renders a compact intent Button). */
+  actionLabel?: string;
+  /** Press handler for the convenience action button. */
+  onAction?: () => void;
+  /** Show a dismiss (X) button. */
+  dismissible?: boolean;
+  /** Called when the dismiss button is pressed. */
+  onDismiss?: () => void;
+  /** Controlled visibility. */
+  visible?: boolean;
+  /** Uncontrolled initial visibility (default true). */
+  defaultVisible?: boolean;
+  /** Tighter padding/type for dense layouts. */
+  compact?: boolean;
+}
+
+// ── Intent mappings ───────────────────────────────────────────
+
+// info rides the accent sub-theme so the whole family (Alert surface + any
+// Button inside) stays on the one unified emphasis system (SB-E-01).
+const intentThemeMap: Record<AlertIntent, "accent" | "error" | "warning" | "success"> = {
+  info: "accent",
+  success: "success",
+  warning: "warning",
+  error: "error",
+};
+
+const intentIconMap: Record<AlertIntent, typeof InfoIcon> = {
+  info: InfoIcon,
+  success: CheckCircleIcon,
+  warning: WarningIcon,
+  error: XCircleIcon,
+};
+
+// ── Styled components ─────────────────────────────────────────
+
+const AlertFrame = styled(XStack, {
+  name: "Alert",
+  width: "100%",
+  alignItems: "flex-start",
+  // Hue tint from the active intent sub-theme: step-3 surface with a step-6
+  // border keeps step-11/12 text AA-readable in both schemes.
+  backgroundColor: "$color3",
+  borderColor: "$color6",
+});
+
+const DismissButton = styled(View, {
+  name: "AlertDismiss",
+  role: "button",
+  tabIndex: 0,
+  cursor: "pointer",
+  alignItems: "center",
+  justifyContent: "center",
+  flexShrink: 0,
+  padding: "$1",
+  borderWidth: 0,
+  backgroundColor: "transparent",
+  borderRadius: "$2",
+  hoverStyle: { backgroundColor: "$color5" },
+  pressStyle: { backgroundColor: "$color6" },
+  focusVisibleStyle: {
+    outlineWidth: 2,
+    outlineStyle: "solid",
+    outlineColor: "$color8",
+    outlineOffset: 1,
+  },
+});
+
+// ── Alert Component ───────────────────────────────────────────
+
+function AlertInner({
+  intent = "info",
+  title,
+  children,
+  icon,
+  action,
+  actionLabel,
+  onAction,
+  dismissible = false,
+  onDismiss,
+  visible,
+  defaultVisible = true,
+  compact = false,
+  ...props
+}: AlertProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "Alert", compact });
+  const theme = useTheme();
+  // Step 11: lowest AA-safe step of the hue on the step-3 tint (resolves to a
+  // CSS var on web, a concrete value on native).
+  const iconColor = theme.color11?.get() as string | undefined;
+  const [uncontrolledVisible, setUncontrolledVisible] = useState(defaultVisible);
+  const shown = visible !== undefined ? visible : uncontrolledVisible;
+  if (!shown) return null;
+
+  // JSX interpolation splits mixed literals into arrays of strings — those
+  // must be wrapped in Text like plain strings or they end up as raw text
+  // nodes inside the View row (RN "text node cannot be a child of a View").
+  const isTextual = (n: unknown): n is string | number =>
+    typeof n === "string" || typeof n === "number";
+  const textualChildren =
+    children != null &&
+    (isTextual(children) || (Array.isArray(children) && children.every(isTextual)))
+      ? Array.isArray(children)
+        ? children.join("")
+        : String(children)
+      : null;
+
+  if (typeof title === "string") {
+    warnBannedErrorWords(title, { component: "Alert" });
+  }
+  if (textualChildren !== null) {
+    warnBannedErrorWords(textualChildren, { component: "Alert" });
+  }
+
+  const handleDismiss = () => {
+    if (visible === undefined) setUncontrolledVisible(false);
+    onDismiss?.();
+  };
+
+  const IconComponent = intentIconMap[intent];
+  const iconNode =
+    icon === null
+      ? null
+      : (icon ?? <IconComponent size={compact ? 18 : 20} weight="fill" color={iconColor} />);
+  const iconSlotHeight = compact ? 20 : 22;
+
+  const actionNode =
+    action ??
+    (actionLabel ? (
+      <Button compact onPress={onAction}>
+        {actionLabel}
+      </Button>
+    ) : null);
+
+  return (
+    <AlertFrame
+      // Interruptive intents announce assertively; the rest politely.
+      role={intent === "error" || intent === "warning" ? "alert" : "status"}
+      borderRadius={knobProps.borderRadius.borderRadius}
+      // Banner keeps at least a hairline so the tint reads as a surface even
+      // under borderWidth-none knob presets.
+      borderWidth={Math.max(knobProps.borderRadius.borderWidth, 1)}
+      padding={compact ? "$2.5" : knobProps.panelPadding.padding}
+      gap={compact ? "$2" : "$3"}
+      transition={knobProps.transition}
+      {...props}
+    >
+      {iconNode ? (
+        <View flexShrink={0} height={iconSlotHeight} justifyContent="center">
+          {iconNode}
+        </View>
+      ) : null}
+      <YStack
+        flexGrow={1}
+        flexShrink={1}
+        gap="$1"
+        justifyContent="center"
+        minHeight={iconSlotHeight}
+      >
+        {title ? (
+          <SizableText
+            {...knobProps.body}
+            fontWeight="600"
+            color="$color12"
+            fontSize={compact ? "$3" : "$4"}
+            lineHeight={compact ? 20 : 22}
+          >
+            {title}
+          </SizableText>
+        ) : null}
+        {children != null &&
+          (textualChildren !== null ? (
+            <SizableText
+              {...knobProps.body}
+              // Step 12, not 11: $color11 on the step-3 tint measured 4.2:1
+              // in the light semantic ramps (below the 4.5 floor); weight and
+              // size keep the title/description hierarchy.
+              color="$color12"
+              fontSize={compact ? "$2" : "$3"}
+              lineHeight={compact ? 18 : 20}
+            >
+              {textualChildren}
+            </SizableText>
+          ) : (
+            children
+          ))}
+      </YStack>
+      {actionNode ? (
+        // Same first-line slot as the icon: trailing controls center on the
+        // title line, so action + dismiss share one line (Axiom 15/16 —
+        // a content-sized slot floated the action ~11px below the dismiss X).
+        <View flexShrink={0} height={iconSlotHeight} justifyContent="center">
+          {actionNode}
+        </View>
+      ) : null}
+      {dismissible ? (
+        <DismissButton
+          aria-label={t("Dismiss")}
+          onPress={handleDismiss}
+          // role=button divs don't get free keyboard activation on web.
+          {...({
+            onKeyDown: (e: { key?: string; preventDefault?: () => void }) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault?.();
+                handleDismiss();
+              }
+            },
+          } as Record<string, unknown>)}
+        >
+          <XIcon size={16} color={iconColor} />
+        </DismissButton>
+      ) : null}
+    </AlertFrame>
+  );
+}
+
+/**
+ * Inline Alert / Banner for form validation summaries and page-level
+ * messages. The whole subtree is wrapped in the matching <Intent> so any
+ * Button placed inside renders SOLID on the same hue as intent Buttons
+ * everywhere else (one emphasis system).
+ */
+export function Alert(props: AlertProps) {
+  const themeName = intentThemeMap[props.intent ?? "info"];
+  return (
+    <Intent name={themeName}>
+      <AlertInner {...props} />
+    </Intent>
+  );
+}
+
+export type AlertFrameProps = GetProps<typeof AlertFrame>;

package/src/Avatar/Avatar.spec.tsx

@@ -0,0 +1,45 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { Avatar, getInitials } from "./index";
+
+describe("getInitials", () => {
+  it("takes first letters of two words", () => {
+    expect(getInitials("Ada Lovelace")).toBe("AL");
+  });
+
+  it("splits email / dotted local parts", () => {
+    expect(getInitials("john.doe@example.com")).toBe("JD");
+  });
+
+  it("falls back to two chars of a single token", () => {
+    expect(getInitials("Ada")).toBe("AD");
+  });
+
+  it("returns ? for empty", () => {
+    expect(getInitials("")).toBe("?");
+  });
+});
+
+describe("Avatar", () => {
+  it("renders initials from name", () => {
+    const { container } = renderWithProviders(<Avatar name="Ada Lovelace" />);
+    expect(container.textContent).toContain("AL");
+  });
+
+  it("respects explicit initials override", () => {
+    const { container } = renderWithProviders(<Avatar name="Ada Lovelace" initials="XX" />);
+    expect(container.textContent).toContain("XX");
+    expect(container.textContent).not.toContain("AL");
+  });
+
+  it("supports compound Fallback children", () => {
+    const { container } = renderWithProviders(
+      <Avatar size="$3">
+        <Avatar.Fallback>
+          <span>OK</span>
+        </Avatar.Fallback>
+      </Avatar>,
+    );
+    expect(container.textContent).toContain("OK");
+  });
+});

package/src/Avatar/Avatar.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { SizableText, XStack, YStack } from "tamagui";
+import { Avatar } from "./index";
+
+const meta: Meta<typeof Avatar> = {
+  title: "Components/Avatar",
+  component: Avatar,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Themed Avatar for assigned users, comments, and activity feeds. Image with initials fallback; size variants; compound Avatar.Image / Avatar.Fallback still available.",
+      },
+    },
+  },
+  argTypes: {
+    name: { control: "text" },
+    src: { control: "text" },
+    size: { control: "text" },
+    circular: { control: "boolean" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    name: "Ada Lovelace",
+  },
+};
+
+export const WithImage: Story = {
+  args: {
+    name: "Grace Hopper",
+    src: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=150&h=150&dpr=2&q=80",
+    size: "$5",
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <XStack gap="$3" alignItems="center">
+      {(["$1.5", "$2", "$3", "$4", "$6"] as const).map((size) => (
+        <YStack key={size} alignItems="center" gap="$1">
+          <Avatar name="Ada Lovelace" size={size} />
+          <SizableText size="$1" color="$color11">
+            {size}
+          </SizableText>
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};
+
+export const InitialsFallback: Story = {
+  render: () => (
+    <XStack gap="$3" alignItems="center">
+      <Avatar name="Ada Lovelace" />
+      <Avatar name="grace.hopper@navy.mil" />
+      <Avatar name="X" />
+      <Avatar initials="MP" name="Multiplatform" />
+    </XStack>
+  ),
+};
+
+export const Compound: Story = {
+  render: () => (
+    <Avatar circular size="$5" backgroundColor="$blue4">
+      <Avatar.Fallback backgroundColor="$blue4" alignItems="center" justifyContent="center">
+        <SizableText fontSize="$3" color="$blue11" fontWeight="600">
+          CH
+        </SizableText>
+      </Avatar.Fallback>
+    </Avatar>
+  ),
+};

package/src/Avatar/getInitials.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive up to two initials from a display name or email local-part.
+ * "Ada Lovelace" → "AL", "john.doe@x" → "JD", "Ada" → "AD".
+ */
+export function getInitials(name: string): string {
+  const trimmed = (name ?? "").trim();
+  if (!trimmed) return "?";
+  const parts = trimmed.split(/[\s@._-]+/).filter(Boolean);
+  if (parts.length >= 2) {
+    const a = parts[0][0] ?? "";
+    const b = parts[1][0] ?? "";
+    return (a + b).toUpperCase();
+  }
+  return trimmed.substring(0, 2).toUpperCase();
+}