@factorialco/f0-react-native 0.28.1 → 0.30.0

package/src/components/primitives/F0Icon/__tests__/F0Icon.tokens.spec.ts

@@ -0,0 +1,39 @@
+// @ts-ignore - Node built-ins are available in Jest runtime
+import fs from "fs"
+// @ts-ignore - Node built-ins are available in Jest runtime
+import path from "path"
+
+import { ICON_COLORS } from "../F0Icon.types"
+
+describe("F0Icon token sync", () => {
+  it("ICON_COLORS matches f0-icon-* tokens in theme.css", () => {
+    const css = fs.readFileSync(
+      // @ts-ignore - __dirname is available in Jest runtime
+      path.resolve(__dirname, "../../../../styles/theme.css"),
+      "utf-8"
+    )
+
+    // Extract all --color-f0-icon-<name> tokens, excluding sub-tokens
+    // that are already captured (e.g. --color-f0-icon-mood-positive
+    // but not --color-f0-icon which maps to "default")
+    const tokenRegex = /--color-f0-icon-([a-z0-9][a-z0-9-]*):/g
+    const tokensFromCSS = new Set<string>()
+    let match: RegExpExecArray | null
+    while ((match = tokenRegex.exec(css)) !== null) {
+      tokensFromCSS.add(match[1])
+    }
+
+    // "default" in ICON_COLORS maps to the base --color-f0-icon token
+    const colorsFromType = new Set<string>(
+      ICON_COLORS.filter((c) => c !== "default")
+    )
+
+    const missingInType = [...tokensFromCSS].filter(
+      (t) => !colorsFromType.has(t)
+    )
+    const extraInType = [...colorsFromType].filter((t) => !tokensFromCSS.has(t))
+
+    expect(missingInType).toEqual([])
+    expect(extraInType).toEqual([])
+  })
+})

package/src/components/primitives/F0Icon/index.ts

@@ -0,0 +1,10 @@
+/**
+ * F0Icon - Icon primitive component
+ *
+ * @see F0Icon.md for documentation
+ */
+
+export { default as F0Icon } from "./F0Icon"
+export type { F0IconProps, IconType, IconColor } from "./F0Icon.types"
+export { ICON_COLORS } from "./F0Icon.types"
+export { applyIconInterop } from "./F0Icon"

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

@@ -5,6 +5,7 @@ Animated text primitive for React Native with semantic typography variants and R
 ## Features
 
 - All F0Text semantic typography variants and colors
+- `className` for layout/positioning (margin, padding, flex, etc.) — typography always wins via twMerge
 - Reanimated `entering`/`exiting` layout animations
 - Animated `style` prop for custom animations via `useAnimatedStyle`
 - Layout transition animations
@@ -90,6 +91,41 @@ import { LinearTransition } from "react-native-reanimated"
 </>
 ```
 
+### className for Layout/Positioning
+
+`className` accepts Tailwind classes for layout and positioning. Typography classes
+in `className` are ignored — semantic props always take precedence via twMerge.
+
+<!-- prettier-ignore -->
+```tsx
+import { AnimatedF0Text } from "@factorialco/f0-react-native"
+import { FadeIn } from "react-native-reanimated"
+import { useAnimatedStyle, useSharedValue } from "react-native-reanimated"
+
+const opacity = useSharedValue(1)
+const animatedStyle = useAnimatedStyle(() => ({ opacity: opacity.value }))
+
+<>
+  {/* className for static layout, style for animated values */}
+  <AnimatedF0Text
+    variant="heading-sm"
+    className="mt-4 flex-1"
+    style={animatedStyle}
+  >
+    Positioned animated heading
+  </AnimatedF0Text>
+
+  {/* className for layout + entering animation */}
+  <AnimatedF0Text
+    variant="body-sm-default"
+    className="mb-2 self-center"
+    entering={FadeIn.duration(300)}
+  >
+    Centered fade-in text
+  </AnimatedF0Text>
+</>
+```
+
 ## API Reference
 
 ### Props
@@ -98,14 +134,15 @@ AnimatedF0Text accepts all F0Text semantic props plus Reanimated animation props
 
 #### Typography Props (shared with F0Text)
 
-| Prop            | Type                | Default             | Description                              |
-| --------------- | ------------------- | ------------------- | ---------------------------------------- |
-| `variant`       | `TypographyVariant` | `'body-sm-default'` | Typography variant                       |
-| `color`         | `TextColor`         | `'default'`         | Text color from F0 semantic color system |
-| `align`         | `TextAlign`         | `'left'`            | Text alignment                           |
-| `decoration`    | `TextDecoration`    | `'none'`            | Text decoration                          |
-| `transform`     | `TextTransform`     | `'none'`            | Text transform                           |
-| `numberOfLines` | `number`            | `undefined`         | Max lines before truncation              |
+| Prop            | Type                | Default             | Description                                                                                               |
+| --------------- | ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------- |
+| `variant`       | `TypographyVariant` | `'body-sm-default'` | Typography variant                                                                                        |
+| `color`         | `TextColor`         | `'default'`         | Text color from F0 semantic color system                                                                  |
+| `align`         | `TextAlign`         | `'left'`            | Text alignment                                                                                            |
+| `decoration`    | `TextDecoration`    | `'none'`            | Text decoration                                                                                           |
+| `transform`     | `TextTransform`     | `'none'`            | Text transform                                                                                            |
+| `numberOfLines` | `number`            | `undefined`         | Max lines before truncation                                                                               |
+| `className`     | `string`            | `undefined`         | Tailwind classes for layout/positioning. Typography classes are overridden by semantic props via twMerge. |
 
 #### Animation Props
 

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

@@ -2,6 +2,7 @@ import React from "react"
 import { Text as RNText } from "react-native"
 import Animated from "react-native-reanimated"
 
+import { cn } from "../../../../lib/utils"
 import { textVariants } from "../F0Text/F0Text.styles"
 
 import type { AnimatedF0TextProps } from "./AnimatedF0Text.types"
@@ -15,10 +16,17 @@ const AnimatedText = Animated.createAnimatedComponent(RNText)
  * typography system as F0Text. Supports `entering`, `exiting`, `layout`
  * animations and animated `style` props.
  *
+ * Typography is controlled by semantic props and always takes precedence.
+ * `className` is accepted for layout/positioning (margin, padding, flex, etc.).
+ * `style` is accepted for Reanimated animated values.
+ *
  * @example
  * <AnimatedF0Text variant="heading-xl" entering={FadeIn.duration(300)}>
  *   Welcome back
  * </AnimatedF0Text>
+ * <AnimatedF0Text variant="body-sm-default" className="mt-4 flex-1" style={animatedStyle}>
+ *   Positioned animated text
+ * </AnimatedF0Text>
  */
 const AnimatedF0TextComponent = React.forwardRef<
   React.ComponentRef<typeof AnimatedText>,
@@ -31,6 +39,7 @@ const AnimatedF0TextComponent = React.forwardRef<
       align = "left",
       decoration = "none",
       transform = "none",
+      className,
       children,
       numberOfLines,
       style,
@@ -40,14 +49,17 @@ const AnimatedF0TextComponent = React.forwardRef<
   ) => {
     const textClassName = React.useMemo(
       () =>
-        textVariants({
-          variant,
-          color,
-          align,
-          decoration,
-          transform,
-        }),
-      [variant, color, align, decoration, transform]
+        cn(
+          className,
+          textVariants({
+            variant,
+            color,
+            align,
+            decoration,
+            transform,
+          })
+        ),
+      [variant, color, align, decoration, transform, className]
     )
 
     return (

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

@@ -58,4 +58,19 @@ export interface AnimatedF0TextProps extends Omit<
    * Children content
    */
   children?: React.ReactNode
+
+  /**
+   * Tailwind classes for layout and positioning.
+   *
+   * Allowed: margin, padding, flex, position, width, height, opacity, z-index, etc.
+   * Ignored: font-size, font-weight, line-height, letter-spacing, color, text-align,
+   * text-decoration, text-transform — these are controlled by semantic props and
+   * always take precedence via twMerge.
+   *
+   * @example
+   * className="mt-4 flex-1"
+   * className="mb-2 self-center"
+   * className="absolute top-0 left-0"
+   */
+  className?: string
 }

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

@@ -128,4 +128,224 @@ describe("AnimatedF0Text", () => {
       expect(element.props.testID).toBe("test-animated-text")
     })
   })
+
+  describe("className — layout classes pass through", () => {
+    it("applies margin classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="mx-3 mt-4 mb-2">Margin text</AnimatedF0Text>
+      )
+      const element = getByText("Margin text")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("mb-2")
+      expect(element.props.className).toContain("mx-3")
+    })
+
+    it("applies padding classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="p-4 px-2 py-1">Padded text</AnimatedF0Text>
+      )
+      const element = getByText("Padded text")
+      expect(element.props.className).toContain("p-4")
+      expect(element.props.className).toContain("px-2")
+      expect(element.props.className).toContain("py-1")
+    })
+
+    it("applies flex classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="flex-1 flex-shrink-0">
+          Flex text
+        </AnimatedF0Text>
+      )
+      const element = getByText("Flex text")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("flex-shrink-0")
+    })
+
+    it("applies position classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="absolute top-0 left-0">
+          Positioned text
+        </AnimatedF0Text>
+      )
+      const element = getByText("Positioned text")
+      expect(element.props.className).toContain("absolute")
+      expect(element.props.className).toContain("top-0")
+      expect(element.props.className).toContain("left-0")
+    })
+
+    it("applies opacity classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="opacity-50">Faded text</AnimatedF0Text>
+      )
+      const element = getByText("Faded text")
+      expect(element.props.className).toContain("opacity-50")
+    })
+
+    it("preserves layout classes with all variant combinations", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-lg"
+          color="critical"
+          align="center"
+          decoration="underline"
+          transform="uppercase"
+          className="mt-4 flex-1 self-end"
+        >
+          Full combo
+        </AnimatedF0Text>
+      )
+      const element = getByText("Full combo")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("self-end")
+      expect(element.props.className).toContain("text-[24px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.className).toContain("text-f0-foreground-critical")
+      expect(element.props.className).toContain("text-center")
+      expect(element.props.className).toContain("underline")
+      expect(element.props.className).toContain("uppercase")
+    })
+  })
+
+  describe("className — typography overrides are rejected", () => {
+    it("rejects font-size override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="text-xs">
+          Size override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Size override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).not.toContain("text-xs")
+    })
+
+    it("rejects font-weight override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="font-bold">
+          Weight override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Weight override attempt")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).not.toContain("font-bold")
+    })
+
+    it("rejects line-height override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="leading-10">
+          Leading override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Leading override attempt")
+      expect(element.props.className).toContain("leading-[20px]")
+      expect(element.props.className).not.toContain("leading-10")
+    })
+
+    it("rejects text-color override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text color="default" className="text-red-500">
+          Color override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Color override attempt")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("text-red-500")
+    })
+
+    it("rejects multiple typography overrides simultaneously", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="body-sm-default"
+          color="default"
+          className="text-xl leading-loose font-bold tracking-wider text-blue-500"
+        >
+          Multi override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Multi override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).toContain("leading-[20px]")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("text-xl")
+      expect(element.props.className).not.toContain("font-bold")
+      expect(element.props.className).not.toContain("leading-loose")
+      expect(element.props.className).not.toContain("text-blue-500")
+      expect(element.props.className).not.toContain("tracking-wider")
+    })
+  })
+
+  describe("className — mixed layout + typography attempts", () => {
+    it("keeps layout classes, rejects typography overrides", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-md"
+          className="mt-4 flex-1 p-2 text-xl font-bold text-red-500"
+        >
+          Mixed attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Mixed attempt")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("p-2")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("text-[20px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("font-bold")
+      expect(element.props.className).not.toContain("text-red-500")
+      expect(element.props.className).not.toContain("text-xl")
+    })
+
+    it("works with both className and style simultaneously", () => {
+      const animatedStyle = { opacity: 0.5 }
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-sm"
+          className="mb-2 flex-1"
+          style={animatedStyle}
+        >
+          className + style
+        </AnimatedF0Text>
+      )
+      const element = getByText("className + style")
+      expect(element.props.className).toContain("mb-2")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("text-[16px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.style).toEqual(animatedStyle)
+    })
+  })
+
+  describe("className — edge cases", () => {
+    it("works correctly when className is undefined", () => {
+      const { getByText } = render(
+        <AnimatedF0Text>No className</AnimatedF0Text>
+      )
+      const element = getByText("No className")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).toContain("text-f0-foreground")
+    })
+
+    it("works correctly when className is empty string", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="">Empty className</AnimatedF0Text>
+      )
+      const element = getByText("Empty className")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+    })
+
+    it("handles className with extra whitespace", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="  mt-4   mb-2  ">
+          Whitespace className
+        </AnimatedF0Text>
+      )
+      const element = getByText("Whitespace className")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("mb-2")
+    })
+  })
 })

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

@@ -2,7 +2,7 @@
 
 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"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-normal text-f0-foreground text-left"
 >
   body-md-default
    text
@@ -11,7 +11,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-medium text-f0-foreground text-left"
 >
   body-md-medium
    text
@@ -20,7 +20,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
 >
   body-md-semibold
    text
@@ -29,7 +29,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   body-sm-default
    text
@@ -38,7 +38,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-medium text-f0-foreground text-left"
 >
   body-sm-medium
    text
@@ -47,7 +47,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-semibold text-f0-foreground text-left"
 >
   body-sm-semibold
    text
@@ -56,7 +56,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case tracking-normal text-[12px] leading-[16px] font-medium text-f0-foreground text-left"
 >
   body-xs-medium
    text
@@ -65,7 +65,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 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"
+  className="no-underline normal-case text-[24px] leading-[32px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-lg
    text
@@ -74,7 +74,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 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"
+  className="no-underline normal-case text-[20px] leading-[28px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-md
    text
@@ -83,7 +83,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-sm 1`] = `
 <Text
-  className="text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
 >
   heading-sm
    text
@@ -92,7 +92,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 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"
+  className="no-underline normal-case text-[36px] leading-[40px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-xl
    text
@@ -101,7 +101,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-accent 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-accent text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-accent text-left"
 >
   accent
    text
@@ -110,7 +110,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-accent 1`]
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-critical 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-critical text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-critical text-left"
 >
   critical
    text
@@ -119,7 +119,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-critical 1`
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-default 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   default
    text
@@ -128,7 +128,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-default 1`]
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-secondary 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-secondary text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-secondary text-left"
 >
   secondary
    text
@@ -137,7 +137,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-secondary 1
 
 exports[`AnimatedF0Text Snapshots renders with default variant (body-sm-default) 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   Default text
 </Text>