@multiplatform.one/components 6.1.0 → 6.3.0

package/src/Avatar/index.tsx

@@ -0,0 +1,158 @@
+import type { ReactNode } from "react";
+import { useReadableTextOn, useResolvedKnobs } from "@multiplatform.one/theme";
+import type { GetProps, SizeTokens } from "tamagui";
+import { Avatar as TamaguiAvatar, SizableText, withStaticProperties } from "tamagui";
+import { componentColors } from "../componentColors";
+import { getInitials } from "./getInitials";
+
+export { getInitials } from "./getInitials";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export type AvatarSize = SizeTokens | number;
+
+export interface AvatarProps extends Omit<GetProps<typeof TamaguiAvatar>, "children"> {
+  /** Image URL. When missing or failing, the initials / fallback slot shows. */
+  src?: string;
+  /** Display name used for initials + default alt text. */
+  name?: string;
+  /** Accessible label for the image (defaults to `name`). */
+  alt?: string;
+  /** Override the initials string (defaults to {@link getInitials}(name)). */
+  initials?: string;
+  /** Fallback surface color when showing initials. */
+  fallbackBackgroundColor?: string;
+  /** Initials text color. */
+  fallbackColor?: string;
+  /** Custom fallback node (replaces initials text). */
+  fallback?: ReactNode;
+  /** Size token or number. @default "$3" */
+  size?: AvatarSize;
+  /** Circular clip (default true for user avatars). */
+  circular?: boolean;
+  /** Advanced: compound children (`Avatar.Image` / `Avatar.Fallback`). */
+  children?: ReactNode;
+}
+
+// ── Size knob → avatar size mapping ───────────────────────────
+
+/** One step below the sizeToken body scale; medium keeps the old $3. */
+const avatarSizeMap: Record<string, SizeTokens> = {
+  $3: "$2",
+  $4: "$3",
+  $5: "$4",
+};
+
+// ── Size → font mapping ───────────────────────────────────────
+
+function initialsFontSize(size: AvatarSize | undefined): SizeTokens {
+  if (typeof size === "number") {
+    if (size <= 24) return "$1";
+    if (size <= 40) return "$2";
+    return "$3";
+  }
+  switch (size) {
+    case "$0.5":
+    case "$1":
+    case "$1.5":
+      return "$1";
+    case "$2":
+    case "$2.5":
+    case "$3":
+      return "$2";
+    default:
+      return "$3";
+  }
+}
+
+// ── Avatar ────────────────────────────────────────────────────
+
+/**
+ * Themed Avatar: image + initials fallback + size variants.
+ * Convenience props (`src`/`name`) cover the desk assigned-user case;
+ * compound `Avatar.Image` / `Avatar.Fallback` remain available for advanced layouts.
+ */
+function AvatarRoot({
+  src,
+  name,
+  alt,
+  initials,
+  fallbackBackgroundColor = "$accentBackground",
+  fallbackColor,
+  fallback,
+  size: sizeProp,
+  circular = true,
+  children,
+  backgroundColor,
+  ...props
+}: AvatarProps) {
+  // Consumer size ejects; otherwise the size knob drives avatar geometry
+  // (LC-18) — one step below the body scale keeps the previous $3 default.
+  const { knobProps } = useResolvedKnobs();
+  // UX-P20 / Axiom 15: initials on the accent tint need a luminance-computed
+  // foreground — the accent theme's near-white `$color` measured 3.95:1 in
+  // dark; paper/ink-on-fill lands the readable anchor (dark ink → 4.02+).
+  const onAccentInitials = useReadableTextOn("$accentBackground");
+  const size = sizeProp ?? avatarSizeMap[knobProps.sizeToken] ?? "$3";
+  if (children != null) {
+    return (
+      <TamaguiAvatar
+        circular={circular}
+        size={size}
+        backgroundColor={backgroundColor ?? fallbackBackgroundColor}
+        {...props}
+      >
+        {children}
+      </TamaguiAvatar>
+    );
+  }
+
+  const label = alt ?? name ?? "Avatar";
+  const initialsText = initials ?? (name ? getInitials(name) : "?");
+
+  const onAccent = fallbackBackgroundColor === "$accentBackground";
+
+  return (
+    <TamaguiAvatar
+      circular={circular}
+      size={size}
+      backgroundColor={backgroundColor ?? fallbackBackgroundColor}
+      aria-label={label}
+      {...props}
+    >
+      {src ? <TamaguiAvatar.Image src={src} alt={label} /> : null}
+      <TamaguiAvatar.Fallback
+        backgroundColor={fallbackBackgroundColor}
+        alignItems="center"
+        justifyContent="center"
+        // Omit delayMs so Fallback mounts immediately (tamagui treats
+        // delayMs=0 as "wait for timeout" and starts canRender=false).
+        {...(src ? { delayMs: 600 } : {})}
+      >
+        {fallback ?? (
+          <SizableText
+            fontSize={initialsFontSize(size)}
+            // Luminance-computed on-fill foreground (Axiom 15): the paper/ink
+            // anchor that reads best on the resolved accent tint, not the
+            // accent theme's fixed near-white.
+            color={
+              fallbackColor ??
+              (onAccent ? (onAccentInitials ?? "$color") : componentColors.text.primary)
+            }
+            fontWeight="600"
+            textAlign="center"
+          >
+            {initialsText}
+          </SizableText>
+        )}
+      </TamaguiAvatar.Fallback>
+    </TamaguiAvatar>
+  );
+}
+
+export const Avatar = withStaticProperties(AvatarRoot, {
+  Image: TamaguiAvatar.Image,
+  Fallback: TamaguiAvatar.Fallback,
+});
+
+export type { AvatarProps as AvatarFrameProps };

package/src/Badge/Badge.stories.tsx

@@ -15,6 +15,18 @@ const meta: Meta<typeof Badge> = {
       },
     },
   },
+  argTypes: {
+    count: { control: "number", description: "Count to display" },
+    max: { control: "number", description: "Maximum count before showing max+" },
+    showZero: { control: "boolean", description: "Show badge when count is 0" },
+    dot: { control: "boolean", description: "Show as a dot instead of count" },
+    visible: { control: "boolean", description: "Whether the badge is visible" },
+    color: { control: "select", options: ["red", "blue", "green", "orange", "gray"] },
+    position: {
+      control: "select",
+      options: ["top-right", "top-left", "bottom-right", "bottom-left"],
+    },
+  },
 };
 export default meta;
 
@@ -35,8 +47,31 @@ const IconButton = ({ children }: { children: React.ReactNode }) => (
 
 export const Default: Story = {
   name: "Main",
-  render: () => (
-    <Badge count={5}>
+  args: { count: 5 },
+  render: (args) => (
+    <Badge {...args}>
+      <IconButton>
+        <BellIcon size={24} />
+      </IconButton>
+    </Badge>
+  ),
+};
+
+export const DotWithCount: Story = {
+  args: { dot: true, count: 7 },
+  render: (args) => (
+    <Badge {...args}>
+      <IconButton>
+        <BellIcon size={24} />
+      </IconButton>
+    </Badge>
+  ),
+};
+
+export const NoCountNoDot: Story = {
+  args: {},
+  render: (args) => (
+    <Badge {...args}>
       <IconButton>
         <BellIcon size={24} />
       </IconButton>

package/src/Badge/index.tsx

@@ -3,6 +3,7 @@ import { useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ColorTokens, GetProps } from "tamagui";
 import { Text, View, styled } from "tamagui";
 import { componentColors } from "../componentColors";
+import { useAsyncBoundary } from "../layouts/AsyncBoundary";
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -33,12 +34,24 @@ export interface BadgeProps {
 
 // ── Color mappings ────────────────────────────────────────────
 
+// $color1 flips with the scheme (near-white in light, near-black in dark),
+// pairing with the step-11 badge surfaces for >=4.5:1 count text (SB-R-02).
 const colorMap: Record<BadgeColor, { bg: ColorTokens; text: ColorTokens }> = {
-  red: { bg: componentColors.badge.red, text: "white" },
-  blue: { bg: componentColors.badge.blue, text: "white" },
-  green: { bg: componentColors.badge.green, text: "white" },
-  orange: { bg: componentColors.badge.orange, text: "white" },
-  gray: { bg: componentColors.badge.gray, text: "white" },
+  red: { bg: componentColors.badge.red, text: "$color1" },
+  blue: { bg: componentColors.badge.blue, text: "$color1" },
+  green: { bg: componentColors.badge.green, text: "$color1" },
+  orange: { bg: componentColors.badge.orange, text: "$color1" },
+  gray: { bg: componentColors.badge.gray, text: "$color1" },
+};
+
+// ── Size mappings ─────────────────────────────────────────────
+
+// R-PILL stays a pill, but capsule/dot geometry scales with the size knob
+// (spec:483-486); medium keeps the previous 18/11/8 geometry.
+const badgeGeometryMap: Record<string, { capsule: number; font: number; dot: number }> = {
+  $3: { capsule: 16, font: 10, dot: 6 },
+  $4: { capsule: 18, font: 11, dot: 8 },
+  $5: { capsule: 22, font: 13, dot: 10 },
 };
 
 // ── Position mappings ─────────────────────────────────────────
@@ -107,13 +120,20 @@ export function Badge({
 }: BadgeProps) {
   const { knobProps } = useResolvedKnobs();
   const colors = colorMap[color];
+  const geometry = badgeGeometryMap[knobProps.sizeToken] ?? badgeGeometryMap.$4;
   const posStyles = positionMap[position];
+  // DG-ST-04: degrade — hide counts/badges when a parent AsyncBoundary failed.
+  const asyncCtx = useAsyncBoundary();
+  const effectiveVisible = visible && !asyncCtx?.hideBadges;
+  const effectiveCount = asyncCtx?.hideBadges ? undefined : count;
 
   // Determine if badge should be shown
-  const shouldShow = visible && (dot || (count !== undefined && (count > 0 || showZero)));
+  const shouldShow =
+    effectiveVisible && (dot || (effectiveCount !== undefined && (effectiveCount > 0 || showZero)));
 
   // Format display value
-  const displayValue = count !== undefined && count > max ? `${max}+` : count;
+  const displayValue =
+    effectiveCount !== undefined && effectiveCount > max ? `${max}+` : effectiveCount;
 
   // Calculate offset transforms
   const [offsetX, offsetY] = offset;
@@ -125,6 +145,9 @@ export function Badge({
         <BadgeIndicator
           dot={dot}
           backgroundColor={colors.bg}
+          {...(dot
+            ? { minWidth: geometry.dot, width: geometry.dot, height: geometry.dot }
+            : { minWidth: geometry.capsule, height: geometry.capsule })}
           style={{
             ...posStyles,
             transform: [
@@ -133,8 +156,15 @@ export function Badge({
             ],
           }}
         >
-          {!dot && count !== undefined && (
-            <BadgeText color={colors.text as any} {...knobProps.body}>
+          {/* body spread first so the intended 600 weight wins (SB-M-101) */}
+          {!dot && effectiveCount !== undefined && (
+            <BadgeText
+              {...knobProps.body}
+              fontWeight="600"
+              fontSize={geometry.font}
+              lineHeight={geometry.capsule}
+              color={colors.text as any}
+            >
               {displayValue}
             </BadgeText>
           )}

package/src/Card.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { Paragraph, SizableText, XStack, YStack } from "tamagui";
+import { Card } from "./surfaces";
+
+const meta: Meta<typeof Card> = {
+  title: "Components/Card",
+  component: Card,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Knob-aware Card wrapper applying the surface-tier recipes (content/elevated/feature) plus panelPadding and gap by default.",
+      },
+    },
+  },
+  argTypes: {
+    tier: {
+      control: "select",
+      options: ["content", "elevated", "feature"],
+    },
+  },
+  args: { tier: "content" },
+};
+export default meta;
+
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <Card {...args} maxWidth={420}>
+      <SizableText fontWeight="600">Card content</SizableText>
+      <Paragraph>Body copy inside the knob-aware card surface.</Paragraph>
+    </Card>
+  ),
+};
+
+export const Tiers: Story = {
+  render: () => (
+    <XStack gap="$4" flexWrap="wrap">
+      {(["content", "elevated", "feature"] as const).map((tier) => (
+        <Card key={tier} tier={tier} width={220}>
+          <SizableText fontWeight="600">{tier}</SizableText>
+          <Paragraph>Tier surface.</Paragraph>
+        </Card>
+      ))}
+    </XStack>
+  ),
+};
+
+export const WithHeaderFooter: Story = {
+  render: (args) => (
+    <Card {...args} maxWidth={420}>
+      <Card.Header>
+        <SizableText fontWeight="600">Header title</SizableText>
+      </Card.Header>
+      <Paragraph>Main content between header and footer.</Paragraph>
+      <Card.Footer>
+        <XStack gap="$2">
+          <Button variant="outlined">Cancel</Button>
+          <Button>Confirm</Button>
+        </XStack>
+      </Card.Footer>
+    </Card>
+  ),
+};
+
+export const Empty: Story = {
+  render: (args) => <Card {...args} width={220} height={80} />,
+};
+
+export const Nested: Story = {
+  render: (args) => (
+    <Card {...args} maxWidth={480}>
+      <SizableText fontWeight="600">Outer card</SizableText>
+      <Card {...args}>
+        <Paragraph>Inner nested card — padding should not compound unexpectedly.</Paragraph>
+      </Card>
+    </Card>
+  ),
+};
+
+export const LongContent: Story = {
+  render: (args) => (
+    <Card {...args} maxWidth={420}>
+      <YStack gap="$2">
+        {Array.from({ length: 12 }).map((_, i) => (
+          <Paragraph key={i}>Long content line {i + 1} to stretch the card vertically.</Paragraph>
+        ))}
+      </YStack>
+    </Card>
+  ),
+};

package/src/CardFooter.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { Paragraph, XStack, YStack } from "tamagui";
+import { Card } from "./surfaces";
+
+const CardFooter = Card.Footer;
+
+const meta: Meta<typeof CardFooter> = {
+  title: "Components/CardFooter",
+  component: CardFooter,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Card.Footer action row — zero padding of its own; the Card frame owns the inset.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof CardFooter>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <Card maxWidth={420}>
+      <Paragraph>Card body content.</Paragraph>
+      <Card.Footer>
+        <XStack gap="$2">
+          <Button variant="outlined">Cancel</Button>
+          <Button>Confirm</Button>
+        </XStack>
+      </Card.Footer>
+    </Card>
+  ),
+};
+
+export const EmptyFooter: Story = {
+  render: () => (
+    <Card maxWidth={420}>
+      <Paragraph>Body above an empty footer.</Paragraph>
+      <Card.Footer />
+    </Card>
+  ),
+};
+
+export const ManyActionsNarrow: Story = {
+  render: () => (
+    <YStack maxWidth={260}>
+      <Card>
+        <Paragraph>Narrow card body.</Paragraph>
+        <Card.Footer>
+          <XStack gap="$2" flexWrap="wrap">
+            <Button size="$2" variant="outlined">
+              A very long action label
+            </Button>
+            <Button size="$2" variant="outlined">
+              Another action
+            </Button>
+            <Button size="$2">Primary confirm</Button>
+          </XStack>
+        </Card.Footer>
+      </Card>
+    </YStack>
+  ),
+};

package/src/CardHeader.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { SizableText, XStack, YStack } from "tamagui";
+import { Card } from "./surfaces";
+
+const CardHeader = Card.Header;
+
+const meta: Meta<typeof CardHeader> = {
+  title: "Components/CardHeader",
+  component: CardHeader,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Card.Header title row — zero padding of its own; the Card frame owns the inset.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof CardHeader>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <Card maxWidth={420}>
+      <Card.Header>
+        <SizableText fontWeight="600">Header title</SizableText>
+      </Card.Header>
+    </Card>
+  ),
+};
+
+export const WithActions: Story = {
+  render: () => (
+    <Card maxWidth={420}>
+      <Card.Header>
+        <XStack justifyContent="space-between" alignItems="center" gap="$2" flexWrap="wrap">
+          <SizableText fontWeight="600">Header with actions</SizableText>
+          <Button size="$2" variant="outlined">
+            Edit
+          </Button>
+        </XStack>
+      </Card.Header>
+    </Card>
+  ),
+};
+
+export const LongTitleNarrow: Story = {
+  render: () => (
+    <YStack maxWidth={260}>
+      <Card>
+        <Card.Header>
+          <XStack justifyContent="space-between" alignItems="center" gap="$2" flexWrap="wrap">
+            <SizableText fontWeight="600" flexShrink={1}>
+              A very long header title that must wrap inside a narrow card without clipping
+            </SizableText>
+            <Button size="$2">Act</Button>
+          </XStack>
+        </Card.Header>
+      </Card>
+    </YStack>
+  ),
+};

package/src/Carousel/Carousel.stories.tsx

@@ -1,6 +1,7 @@
 import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Card, Image, Text, View, YStack } from "tamagui";
+import { Card, Text, View, YStack } from "tamagui";
+import { Image } from "../images/Image";
 import { Carousel } from "./index";
 
 const meta: Meta<typeof Carousel> = {
@@ -20,7 +21,7 @@ export default meta;
 
 type Story = StoryObj<typeof Carousel>;
 
-const colors = ["$red9", "$orange9", "$yellow9", "$green9", "$blue9", "$purple9"];
+const colors = ["red", "orange", "yellow", "green", "blue", "purple"];
 
 const SlideContent = ({
   index,
@@ -31,14 +32,11 @@ const SlideContent = ({
   color: string;
   height?: number;
 }) => (
-  <View
-    backgroundColor={color}
-    height={height}
-    alignItems="center"
-    justifyContent="center"
-    borderRadius="$3"
-  >
-    <Text color="white" fontSize="$6" fontWeight="bold">
+  // No slide-owned radius (G-15 story honesty): the Carousel viewport clips
+  // slides at the knob radius — a pinned $3 held a 7px arc at
+  // borderRadius:none (UX-P06 "Carousel slides br=7").
+  <View backgroundColor={`$${color}3`} height={height} alignItems="center" justifyContent="center">
+    <Text color={`$${color}12`} fontSize="$6" fontWeight="bold">
       Slide {index + 1}
     </Text>
   </View>
@@ -149,12 +147,13 @@ export const ImageCarousel: Story = {
     <View width={500}>
       <Carousel loop>
         {[1, 2, 3, 4].map((i) => (
-          <View key={i} borderRadius="$3" overflow="hidden">
+          <View key={i} overflow="hidden">
             <Image
-              source={{ uri: `https://picsum.photos/500/300?random=${i}` }}
+              src={`https://picsum.photos/500/300?random=${i}`}
+              alt={`Sample landscape photo ${i}`}
               width="100%"
               height={300}
-              resizeMode="cover"
+              objectFit="cover"
             />
           </View>
         ))}
@@ -170,11 +169,11 @@ export const CardCarousel: Story = {
         {[1, 2, 3, 4].map((i) => (
           <Card key={i} bordered padding="$4" height={200}>
             <YStack gap="$2">
-              <View width={60} height={60} backgroundColor="$color5" borderRadius="$3" />
+              <View width={60} height={60} backgroundColor="$color5" />
               <Text fontWeight="bold" fontSize="$5">
                 Card {i}
               </Text>
-              <Text color="$color10" fontSize="$3">
+              <Text color="$color11" fontSize="$3">
                 This is a sample card in the carousel. It demonstrates how cards can be used as
                 slides.
               </Text>
@@ -202,7 +201,7 @@ export const SingleSlide: Story = {
   render: () => (
     <View width={400}>
       <Carousel>
-        <SlideContent index={0} color="$blue9" />
+        <SlideContent index={0} color="blue" />
       </Carousel>
     </View>
   ),