@factorialco/f0-react-native 0.26.0 → 0.28.0

package/src/components/primitives/F0Text/AnimatedF0Text/AnimatedF0Text.types.ts

@@ -0,0 +1,61 @@
+import type { TextProps as RNTextProps } from "react-native"
+import type { AnimatedProps } from "react-native-reanimated"
+
+import type {
+  TextAlign,
+  TextColor,
+  TextDecoration,
+  TextTransform,
+  TypographyVariant,
+} from "../F0Text/F0Text.types"
+
+/**
+ * Props for the AnimatedF0Text component.
+ *
+ * Combines F0Text semantic typography props with Reanimated animation
+ * capabilities (`entering`, `exiting`, `layout`, animated `style`).
+ */
+export interface AnimatedF0TextProps extends Omit<
+  AnimatedProps<RNTextProps>,
+  "className"
+> {
+  /**
+   * Semantic typography variant
+   * @default "body-sm-default"
+   */
+  variant?: TypographyVariant
+
+  /**
+   * Text color from F0 semantic color system
+   * @default "default"
+   */
+  color?: TextColor
+
+  /**
+   * Text alignment
+   * @default "left"
+   */
+  align?: TextAlign
+
+  /**
+   * Text decoration
+   * @default "none"
+   */
+  decoration?: TextDecoration
+
+  /**
+   * Text transform
+   * @default "none"
+   */
+  transform?: TextTransform
+
+  /**
+   * Maximum number of lines before truncating with ellipsis
+   */
+  numberOfLines?: number
+
+  /**
+   * Children content
+   */
+  children?: React.ReactNode
+}

package/src/components/primitives/F0Text/AnimatedF0Text/__tests__/AnimatedF0Text.spec.tsx

@@ -0,0 +1,131 @@
+import { render } from "@testing-library/react-native"
+import React from "react"
+
+import { AnimatedF0Text } from "../AnimatedF0Text"
+
+describe("AnimatedF0Text", () => {
+  describe("Snapshots", () => {
+    it("renders with default variant (body-sm-default)", () => {
+      const { toJSON } = render(<AnimatedF0Text>Default text</AnimatedF0Text>)
+      expect(toJSON()).toMatchSnapshot()
+    })
+
+    it("renders all typography variants", () => {
+      const variants = [
+        "heading-xl",
+        "heading-lg",
+        "heading-md",
+        "heading-sm",
+        "body-md-default",
+        "body-md-medium",
+        "body-md-semibold",
+        "body-sm-default",
+        "body-sm-medium",
+        "body-sm-semibold",
+        "body-xs-medium",
+      ] as const
+
+      variants.forEach((variant) => {
+        const { toJSON } = render(
+          <AnimatedF0Text variant={variant}>{variant} text</AnimatedF0Text>
+        )
+        expect(toJSON()).toMatchSnapshot(`variant-${variant}`)
+      })
+    })
+
+    it("renders with color variants", () => {
+      const colors = ["default", "secondary", "accent", "critical"] as const
+
+      colors.forEach((color) => {
+        const { toJSON } = render(
+          <AnimatedF0Text color={color}>{color} text</AnimatedF0Text>
+        )
+        expect(toJSON()).toMatchSnapshot(`color-${color}`)
+      })
+    })
+  })
+
+  describe("Behavior", () => {
+    it("renders children correctly", () => {
+      const { getByText } = render(<AnimatedF0Text>Hello World</AnimatedF0Text>)
+      expect(getByText("Hello World")).toBeTruthy()
+    })
+
+    it("applies correct variant classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="heading-xl">XL Heading</AnimatedF0Text>
+      )
+      const element = getByText("XL Heading")
+      expect(element.props.className).toContain("text-[36px]")
+      expect(element.props.className).toContain("leading-[40px]")
+      expect(element.props.className).toContain("tracking-[-0.2px]")
+      expect(element.props.className).toContain("font-semibold")
+    })
+
+    it("applies correct color classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text color="secondary">Secondary text</AnimatedF0Text>
+      )
+      const element = getByText("Secondary text")
+      expect(element.props.className).toContain("text-f0-foreground-secondary")
+    })
+
+    it("applies correct alignment classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text align="center">Centered text</AnimatedF0Text>
+      )
+      const element = getByText("Centered text")
+      expect(element.props.className).toContain("text-center")
+    })
+
+    it("applies decoration classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text decoration="underline">Underlined text</AnimatedF0Text>
+      )
+      const element = getByText("Underlined text")
+      expect(element.props.className).toContain("underline")
+    })
+
+    it("applies transform classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text transform="uppercase">uppercase text</AnimatedF0Text>
+      )
+      const element = getByText("uppercase text")
+      expect(element.props.className).toContain("uppercase")
+    })
+
+    it("sets numberOfLines prop correctly", () => {
+      const { getByText } = render(
+        <AnimatedF0Text numberOfLines={3}>Multiline text</AnimatedF0Text>
+      )
+      const element = getByText("Multiline text")
+      expect(element.props.numberOfLines).toBe(3)
+      expect(element.props.ellipsizeMode).toBe("tail")
+    })
+
+    it("does not set ellipsizeMode when numberOfLines is not provided", () => {
+      const { getByText } = render(<AnimatedF0Text>Normal text</AnimatedF0Text>)
+      const element = getByText("Normal text")
+      expect(element.props.ellipsizeMode).toBeUndefined()
+    })
+
+    it("accepts style prop for animated styles", () => {
+      const animatedStyle = { opacity: 0.5 }
+      const { getByText } = render(
+        <AnimatedF0Text style={animatedStyle}>Styled text</AnimatedF0Text>
+      )
+      const element = getByText("Styled text")
+      expect(element.props.style).toEqual(animatedStyle)
+    })
+
+    it("forwards additional props", () => {
+      const { getByText } = render(
+        <AnimatedF0Text testID="test-animated-text">
+          Pressable text
+        </AnimatedF0Text>
+      )
+      const element = getByText("Pressable text")
+      expect(element.props.testID).toBe("test-animated-text")
+    })
+  })
+})

package/src/components/primitives/F0Text/AnimatedF0Text/__tests__/__snapshots__/AnimatedF0Text.spec.tsx.snap

@@ -0,0 +1,144 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-default 1`] = `
+<Text
+  className="text-[16px] leading-[24px] font-normal text-f0-foreground text-left"
+>
+  body-md-default
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-medium 1`] = `
+<Text
+  className="text-[16px] leading-[24px] font-medium text-f0-foreground text-left"
+>
+  body-md-medium
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-semibold 1`] = `
+<Text
+  className="text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
+>
+  body-md-semibold
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-default 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+>
+  body-sm-default
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-medium 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-medium text-f0-foreground text-left"
+>
+  body-sm-medium
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-semibold 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-semibold text-f0-foreground text-left"
+>
+  body-sm-semibold
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-xs-medium 1`] = `
+<Text
+  className="text-[12px] leading-[16px] font-medium text-f0-foreground text-left"
+>
+  body-xs-medium
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-lg 1`] = `
+<Text
+  className="text-[24px] leading-[32px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+>
+  heading-lg
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-md 1`] = `
+<Text
+  className="text-[20px] leading-[28px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+>
+  heading-md
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-sm 1`] = `
+<Text
+  className="text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
+>
+  heading-sm
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-xl 1`] = `
+<Text
+  className="text-[36px] leading-[40px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+>
+  heading-xl
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders with color variants: color-accent 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground-accent text-left"
+>
+  accent
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders with color variants: color-critical 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground-critical text-left"
+>
+  critical
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders with color variants: color-default 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+>
+  default
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders with color variants: color-secondary 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground-secondary text-left"
+>
+  secondary
+   text
+</Text>
+`;
+
+exports[`AnimatedF0Text Snapshots renders with default variant (body-sm-default) 1`] = `
+<Text
+  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+>
+  Default text
+</Text>
+`;

package/src/components/primitives/F0Text/AnimatedF0Text/index.ts

@@ -0,0 +1,8 @@
+/**
+ * AnimatedF0Text - Animated text primitive component
+ *
+ * @see AnimatedF0Text.md for documentation
+ */
+
+export { AnimatedF0Text } from "./AnimatedF0Text"
+export type { AnimatedF0TextProps } from "./AnimatedF0Text"

package/src/components/primitives/F0Text/F0Text/F0Text.md

@@ -0,0 +1,320 @@
+# F0Text
+
+Primitive text component for React Native with semantic typography variants and optimized performance.
+
+## Features
+
+- Semantic typography variants (heading and body styles)
+- F0 semantic color system integration
+- Inter font family support
+- Type-safe TypeScript API
+- Uniwind (Tailwind) styling
+- Performance optimized with React.memo and useMemo
+- Full accessibility support
+
+## Installation
+
+```tsx
+import { F0Text } from "@factorialco/f0-react-native"
+```
+
+## Usage
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  <F0Text variant="heading-lg">Welcome</F0Text>
+  <F0Text variant="body-sm-default" color="secondary">
+    Secondary text
+  </F0Text>
+  <F0Text variant="body-md-medium" align="center">
+    Centered text
+  </F0Text>
+  <F0Text variant="body-sm-default" numberOfLines={2}>
+    Truncated text...
+  </F0Text>
+</>
+```
+
+## API Reference
+
+### Props
+
+| Prop            | Type                | Default             | Description                                             |
+| --------------- | ------------------- | ------------------- | ------------------------------------------------------- |
+| `variant`       | `TypographyVariant` | `'body-sm-default'` | Typography variant with weight included                 |
+| `color`         | `TextColor`         | `'default'`         | Text color from F0 semantic color system                |
+| `align`         | `TextAlign`         | `'left'`            | Text alignment (left, center, right, justify)           |
+| `decoration`    | `TextDecoration`    | `'none'`            | Text decoration (none, underline, line-through)         |
+| `transform`     | `TextTransform`     | `'none'`            | Text transform (none, uppercase, lowercase, capitalize) |
+| `numberOfLines` | `number`            | `undefined`         | Max lines before truncation with ellipsis               |
+
+All React Native `TextProps` are also supported (onPress, testID, etc.).
+
+**Note**: `className` and `style` props are **not available**. Use semantic props for typography. For spacing/layout, wrap F0Text in a View. Both props are filtered at runtime to prevent override via spread.
+
+### Typography Variants
+
+All variants use **Inter** font family with the weight included in the variant name.
+
+#### Heading Variants
+
+| Variant      | Size | Line Height | Weight         | Letter Spacing |
+| ------------ | ---- | ----------- | -------------- | -------------- |
+| `heading-xl` | 36px | 40px        | Semibold (600) | -0.2px         |
+| `heading-lg` | 24px | 32px        | Semibold (600) | -0.2px         |
+| `heading-md` | 20px | 28px        | Semibold (600) | -0.2px         |
+| `heading-sm` | 16px | 24px        | Semibold (600) | -              |
+
+#### Body Variants
+
+| Variant            | Size | Line Height | Weight         | Letter Spacing |
+| ------------------ | ---- | ----------- | -------------- | -------------- |
+| `body-md-default`  | 16px | 24px        | Regular (400)  | -              |
+| `body-md-medium`   | 16px | 24px        | Medium (500)   | -              |
+| `body-md-semibold` | 16px | 24px        | Semibold (600) | -              |
+| `body-sm-default`  | 14px | 20px        | Regular (400)  | -              |
+| `body-sm-medium`   | 14px | 20px        | Medium (500)   | -              |
+| `body-sm-semibold` | 14px | 20px        | Semibold (600) | -              |
+| `body-xs-medium`   | 12px | 16px        | Medium (500)   | -              |
+
+### Color Variants
+
+| Color               | Usage                              |
+| ------------------- | ---------------------------------- |
+| `default`           | Primary text                       |
+| `secondary`         | Secondary information              |
+| `tertiary`          | Tertiary/subtle text               |
+| `inverse`           | Text on dark backgrounds           |
+| `inverse-secondary` | Secondary text on dark backgrounds |
+| `disabled`          | Disabled state text                |
+| `accent`            | Highlighted/accent text            |
+| `critical`          | Error messages                     |
+| `info`              | Informational text                 |
+| `warning`           | Warning messages                   |
+| `positive`          | Success messages                   |
+| `selected`          | Selected state text                |
+
+## Examples
+
+### Typography Variants
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  {/* Headings */}
+  <F0Text variant="heading-xl">Extra Large Heading</F0Text>
+  <F0Text variant="heading-lg">Large Heading</F0Text>
+  <F0Text variant="heading-md">Medium Heading</F0Text>
+  <F0Text variant="heading-sm">Small Heading</F0Text>
+
+  {/* Body with different weights */}
+  <F0Text variant="body-md-default">Regular body text</F0Text>
+  <F0Text variant="body-md-medium">Medium body text</F0Text>
+  <F0Text variant="body-md-semibold">Semibold body text</F0Text>
+
+  {/* Smaller sizes */}
+  <F0Text variant="body-sm-default">Small regular text</F0Text>
+  <F0Text variant="body-xs-medium">Extra small medium text</F0Text>
+</>
+```
+
+### Colors
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  <F0Text variant="body-sm-default" color="default">
+    Primary text
+  </F0Text>
+  <F0Text variant="body-sm-default" color="secondary">
+    Secondary information
+  </F0Text>
+  <F0Text variant="body-sm-default" color="critical">
+    Error message
+  </F0Text>
+  <F0Text variant="body-sm-default" color="positive">
+    Success message
+  </F0Text>
+  <F0Text variant="body-sm-default" color="accent">
+    Highlighted text
+  </F0Text>
+</>
+```
+
+### Text Decorations & Transforms
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  <F0Text variant="body-sm-default" decoration="underline">
+    Underlined text
+  </F0Text>
+  <F0Text variant="body-sm-default" decoration="line-through">
+    Strikethrough text
+  </F0Text>
+  <F0Text variant="body-sm-default" transform="uppercase">
+    uppercase text
+  </F0Text>
+  <F0Text variant="body-sm-default" transform="capitalize">
+    capitalize words
+  </F0Text>
+</>
+```
+
+### Truncation
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  <F0Text variant="body-sm-default" numberOfLines={1}>
+    This long text will be truncated after one line with an ellipsis...
+  </F0Text>
+
+  <F0Text variant="body-md-default" numberOfLines={3}>
+    This text can span up to three lines before being truncated with an ellipsis
+    at the end. Perfect for card descriptions or preview text.
+  </F0Text>
+</>
+```
+
+### Spacing & Layout
+
+F0Text doesn't accept `className` to prevent typography override. Use a View wrapper for spacing:
+
+<!-- prettier-ignore -->
+```tsx
+<>
+  {/* Spacing with View wrapper */}
+  <View className="mt-4 mb-2">
+    <F0Text variant="body-sm-default">Text with margin</F0Text>
+  </View>
+
+  {/* Layout with View wrapper */}
+  <View className="flex-1">
+    <F0Text variant="body-sm-default">Flexible text</F0Text>
+  </View>
+
+  {/* Icon + Text pattern */}
+  <View className="flex-row items-center gap-2">
+    <F0Icon icon={Check} size="sm" />
+    <F0Text variant="body-sm-default">Success message</F0Text>
+  </View>
+</>
+```
+
+### Combined Props
+
+<!-- prettier-ignore -->
+```tsx
+<F0Text
+  variant="heading-md"
+  color="accent"
+  align="center"
+  decoration="underline"
+  transform="uppercase"
+>
+  Featured Title
+</F0Text>
+```
+
+### Nested Text
+
+<!-- prettier-ignore -->
+```tsx
+<F0Text variant="body-sm-default">
+  This is regular text with{" "}
+  <F0Text variant="body-sm-semibold" color="accent">
+    bold accent nested text
+  </F0Text>{" "}
+  inside.
+</F0Text>
+```
+
+### Real-world Card Example
+
+<!-- prettier-ignore -->
+```tsx
+<View className="rounded-lg bg-f0-background-secondary p-4">
+  <View className="mb-2">
+    <F0Text variant="heading-sm">Card Title</F0Text>
+  </View>
+  <F0Text variant="body-sm-default" color="secondary" numberOfLines={2}>
+    This is a description that will be truncated after two lines if it's too
+    long to fit in the available space.
+  </F0Text>
+  <View className="mt-2">
+    <F0Text variant="body-xs-medium" color="tertiary">
+      Last updated 2 hours ago
+    </F0Text>
+  </View>
+</View>
+```
+
+## Architecture
+
+```
+F0Text/                        # Parent folder for text primitives
+├── F0Text/                    # Static text component
+│   ├── F0Text.tsx             # Main component
+│   ├── F0Text.md              # Documentation
+│   ├── F0Text.types.ts        # TypeScript types
+│   ├── F0Text.styles.ts       # Tailwind variants config
+│   ├── index.ts               # Public exports
+│   └── __tests__/
+│       ├── F0Text.spec.tsx
+│       └── __snapshots__/
+├── AnimatedF0Text/            # Animated text component
+│   ├── AnimatedF0Text.tsx
+│   ├── AnimatedF0Text.md
+│   ├── AnimatedF0Text.types.ts
+│   ├── index.ts
+│   └── __tests__/
+│       ├── AnimatedF0Text.spec.tsx
+│       └── __snapshots__/
+└── index.ts                   # Barrel re-exporting both
+```
+
+### Font Family
+
+F0Text uses **Inter** font family through Tailwind/Uniwind font weight classes:
+
+| Tailwind Class  | React Native Font Family | Font Weight |
+| --------------- | ------------------------ | ----------- |
+| `font-normal`   | Inter-Regular            | 400         |
+| `font-medium`   | Inter-Medium             | 500         |
+| `font-semibold` | Inter-SemiBold           | 600         |
+| `font-bold`     | Inter-Bold               | 700         |
+
+## Accessibility
+
+- Fully supports React Native `Text` accessibility props
+- Supports `accessibilityRole`, `accessibilityLabel`, `accessibilityHint`, `accessibilityState`, and `accessible`
+- Proper ellipsis and truncation with `numberOfLines`
+- F0 color system helps ensure sufficient contrast; verify with platform accessibility tools
+
+## Performance
+
+- **React.memo**: Prevents re-renders when props unchanged
+- **useMemo**: Memoizes className computation
+
+### Best Practices
+
+<!-- prettier-ignore -->
+```tsx
+// ✅ Good: Use appropriate variant
+<F0Text variant="body-md-semibold">Bold text</F0Text>
+
+// ❌ Bad: Don't try to override with className (not supported)
+// <F0Text className="font-bold">Text</F0Text>
+```
+
+<!-- prettier-ignore -->
+```tsx
+// ✅ Good: Memoized handler
+const handlePress = useCallback(() => {}, [])
+<F0Text onPress={handlePress}>Click</F0Text>
+
+// ❌ Bad: Inline function
+<F0Text onPress={() => {}}>Click</F0Text>
+```