@factorialco/f0-react-native 0.28.1 → 0.30.0

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

@@ -40,18 +40,19 @@ import { F0Text } from "@factorialco/f0-react-native"
 
 ### 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               |
+| 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                |
+| `className`     | `string`            | `undefined`         | Layout/positioning classes (margin, padding, flex, etc.) |
 
-All React Native `TextProps` are also supported (onPress, testID, etc.).
+All React Native `TextProps` are also supported (onPress, testID, etc.), **except `style`** which is omitted from the type and filtered at runtime.
 
-**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 is controlled exclusively by semantic props (variant, color, align, etc.) and always takes precedence — any typography classes passed via `className` are automatically overridden by the semantic props via `twMerge`.
 
 ### Typography Variants
 
@@ -180,26 +181,33 @@ All variants use **Inter** font family with the weight included in the variant n
 
 ### Spacing & Layout
 
-F0Text doesn't accept `className` to prevent typography override. Use a View wrapper for spacing:
+F0Text accepts `className` for layout and positioning. Typography classes in `className` are safely overridden by semantic props via `twMerge`:
 
 <!-- prettier-ignore -->
 ```tsx
 <>
-  {/* Spacing with View wrapper */}
-  <View className="mt-4 mb-2">
-    <F0Text variant="body-sm-default">Text with margin</F0Text>
-  </View>
+  {/* Spacing directly on the text */}
+  <F0Text variant="body-sm-default" className="mt-4 mb-2">
+    Text with margin
+  </F0Text>
 
-  {/* Layout with View wrapper */}
-  <View className="flex-1">
-    <F0Text variant="body-sm-default">Flexible text</F0Text>
-  </View>
+  {/* Layout directly on the text */}
+  <F0Text variant="body-sm-default" className="flex-1">
+    Flexible text
+  </F0Text>
 
   {/* Icon + Text pattern */}
   <View className="flex-row items-center gap-2">
     <F0Icon icon={Check} size="sm" />
-    <F0Text variant="body-sm-default">Success message</F0Text>
+    <F0Text variant="body-sm-default" className="flex-1">
+      Success message
+    </F0Text>
   </View>
+
+  {/* Typography override attempts are safely ignored */}
+  <F0Text variant="body-sm-default" className="mt-4 font-bold text-red-500">
+    font-bold and text-red-500 are ignored; mt-4 is applied
+  </F0Text>
 </>
 ```
 
@@ -236,18 +244,16 @@ F0Text doesn't accept `className` to prevent typography override. Use a View wra
 <!-- 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="heading-sm" className="mb-2">
+    Card Title
+  </F0Text>
   <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>
+  <F0Text variant="body-xs-medium" color="tertiary" className="mt-2">
+    Last updated 2 hours ago
+  </F0Text>
 </View>
 ```
 
@@ -347,11 +353,16 @@ to these variables.
 
 <!-- prettier-ignore -->
 ```tsx
-// ✅ Good: Use appropriate variant
+// ✅ Good: Use semantic props for typography
 <F0Text variant="body-md-semibold">Bold text</F0Text>
 
-// ❌ Bad: Don't try to override with className (not supported)
-// <F0Text className="font-bold">Text</F0Text>
+// ✅ Good: Use className for layout
+<F0Text variant="body-md-semibold" className="mt-4 flex-1">Bold text</F0Text>
+
+// ❌ Bad: Don't use className for typography (it will be overridden)
+<F0Text variant="body-sm-default" className="font-bold text-red-500">
+  font-bold and text-red-500 are silently ignored
+</F0Text>
 ```
 
 <!-- prettier-ignore -->

package/src/components/primitives/F0Text/F0Text/F0Text.styles.ts

@@ -7,7 +7,7 @@ import { tv, type VariantProps } from "tailwind-variants"
  * via --font-* CSS variables defined in @theme.
  */
 export const textVariants = tv({
-  base: "",
+  base: "no-underline normal-case tracking-normal",
   variants: {
     variant: {
       // Heading variants

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

@@ -1,7 +1,7 @@
 import React from "react"
 import { Text as RNText } from "react-native"
 
-import { omitProps } from "../../../../lib/utils"
+import { cn, omitProps } from "../../../../lib/utils"
 
 import { textVariants } from "./F0Text.styles"
 import { F0_TEXT_BANNED_PROPS, type F0TextProps } from "./F0Text.types"
@@ -9,10 +9,13 @@ import { F0_TEXT_BANNED_PROPS, type F0TextProps } from "./F0Text.types"
 /**
  * F0Text - Primitive Text component with semantic typography variants
  *
+ * Typography is controlled by semantic props and always takes precedence.
+ * `className` is accepted for layout/positioning (margin, padding, flex, etc.).
+ *
  * @example
  * <F0Text variant="heading-lg">Large Heading</F0Text>
  * <F0Text variant="body-sm-default" color="secondary">Secondary text</F0Text>
- * <F0Text variant="body-md-medium" numberOfLines={2}>Truncated text...</F0Text>
+ * <F0Text variant="body-sm-default" className="mt-4 flex-1">Positioned text</F0Text>
  */
 const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
   (
@@ -22,6 +25,7 @@ const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
       align = "left",
       decoration = "none",
       transform = "none",
+      className,
       children,
       numberOfLines,
       ...rest
@@ -30,14 +34,17 @@ const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
   ) => {
     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/F0Text/F0Text.types.ts

@@ -1,11 +1,11 @@
 import type { TextProps as RNTextProps } from "react-native"
 
 /**
- * Props that must not be passed through to the underlying RN Text
- * (`style` and `className` are handled by F0 instead).
- * Used with omitProps for runtime safety.
+ * Props that must not be passed through to the underlying RN Text.
+ * `style` is blocked to enforce the semantic API; `className` is allowed
+ * for layout/positioning and merged with typography classes via twMerge.
  */
-export const F0_TEXT_BANNED_PROPS = ["style", "className"] as const
+export const F0_TEXT_BANNED_PROPS = ["style"] as const
 
 /**
  * Typography variant types based on semantic design tokens
@@ -73,10 +73,14 @@ export const TEXT_TRANSFORMS = [
 export type TextTransform = (typeof TEXT_TRANSFORMS)[number]
 
 /**
- * Internal props for the F0Text component.
- * @private
+ * Props for the F0Text component.
+ *
+ * `className` is available for layout/positioning (margin, padding, flex, etc.).
+ * Typography is controlled exclusively by semantic props (variant, color, align, etc.)
+ * and always takes precedence — any typography classes in `className` are overridden.
+ * `style` is NOT available (omitted from RNTextProps and filtered at runtime).
  */
-interface F0TextPropsInternal extends Omit<RNTextProps, "style"> {
+export interface F0TextProps extends Omit<RNTextProps, "style"> {
   /**
    * Semantic typography variant
    * @default "body-sm-default"
@@ -118,17 +122,17 @@ interface F0TextPropsInternal extends Omit<RNTextProps, "style"> {
   children?: React.ReactNode
 
   /**
-   * Excluded from public API via Omit<F0TextPropsInternal, "className">.
-   * @private
+   * 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
 }
-
-/**
- * Public props for the F0Text component
- *
- * Note: `className` and `style` props are NOT available.
- * Use semantic props (variant, color, align, etc.) for typography.
- * For spacing/layout, wrap F0Text in a View with className.
- */
-export type F0TextProps = Omit<F0TextPropsInternal, "className">

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

@@ -142,6 +142,7 @@ describe("F0Text", () => {
       )
       const element = getByText("Underlined text")
       expect(element.props.className).toContain("underline")
+      expect(element.props.className).not.toContain("no-underline")
     })
 
     it("applies transform classes", () => {
@@ -150,6 +151,7 @@ describe("F0Text", () => {
       )
       const element = getByText("uppercase text")
       expect(element.props.className).toContain("uppercase")
+      expect(element.props.className).not.toContain("normal-case")
     })
 
     it("sets numberOfLines prop correctly", () => {
@@ -193,36 +195,358 @@ describe("F0Text", () => {
       expect(element.props.style).toBeUndefined()
     })
 
-    it("filters className prop at runtime (prevents override via spread)", () => {
-      const propsWithClassName = {
-        className: "font-bold text-red-500",
-        children: "Text with className attempt",
-      }
+    it("handles ref forwarding", () => {
+      const ref = React.createRef<RNText>()
+      render(<F0Text ref={ref}>Ref text</F0Text>)
+      expect(ref.current).toBeTruthy()
+    })
+
+    it("renders nested children", () => {
+      const { getByText } = render(
+        <F0Text>
+          Parent <F0Text variant="body-xs-medium">nested</F0Text> text
+        </F0Text>
+      )
+      expect(getByText("nested")).toBeTruthy()
+    })
+  })
+
+  describe("className — layout classes pass through", () => {
+    it("applies margin classes", () => {
+      const { getByText } = render(
+        <F0Text className="mx-3 mt-4 mb-2">Margin text</F0Text>
+      )
+      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(
+        <F0Text className="p-4 px-2 py-1">Padded text</F0Text>
+      )
+      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(
+        <F0Text className="flex-1 flex-shrink-0">Flex text</F0Text>
+      )
+      const element = getByText("Flex text")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("flex-shrink-0")
+    })
+
+    it("applies self-alignment classes", () => {
+      const { getByText } = render(
+        <F0Text className="self-center">Self-aligned text</F0Text>
+      )
+      const element = getByText("Self-aligned text")
+      expect(element.props.className).toContain("self-center")
+    })
+
+    it("applies position classes", () => {
+      const { getByText } = render(
+        <F0Text className="absolute top-0 left-0">Positioned text</F0Text>
+      )
+      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 width and height classes", () => {
+      const { getByText } = render(
+        <F0Text className="w-full max-w-xs">Sized text</F0Text>
+      )
+      const element = getByText("Sized text")
+      expect(element.props.className).toContain("w-full")
+      expect(element.props.className).toContain("max-w-xs")
+    })
+
+    it("applies opacity classes", () => {
+      const { getByText } = render(
+        <F0Text className="opacity-50">Faded text</F0Text>
+      )
+      const element = getByText("Faded text")
+      expect(element.props.className).toContain("opacity-50")
+    })
+
+    it("applies display/visibility classes", () => {
+      const { getByText } = render(
+        <F0Text className="hidden">Hidden text</F0Text>
+      )
+      const element = getByText("Hidden text")
+      expect(element.props.className).toContain("hidden")
+    })
+
+    it("applies z-index classes", () => {
+      const { getByText } = render(
+        <F0Text className="z-10">Layered text</F0Text>
+      )
+      const element = getByText("Layered text")
+      expect(element.props.className).toContain("z-10")
+    })
+
+    it("preserves layout classes with all variant combinations", () => {
+      const { getByText } = render(
+        <F0Text
+          variant="heading-lg"
+          color="critical"
+          align="center"
+          decoration="underline"
+          transform="uppercase"
+          className="mt-4 flex-1 self-end"
+        >
+          Full combo
+        </F0Text>
+      )
+      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(
+        <F0Text variant="body-sm-default" className="text-xs">
+          Size override attempt
+        </F0Text>
+      )
+      const element = getByText("Size override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).not.toContain("text-xs")
+    })
+
+    it("rejects arbitrary font-size override", () => {
+      const { getByText } = render(
+        <F0Text variant="body-sm-default" className="text-[40px]">
+          Size override attempt
+        </F0Text>
+      )
+      const element = getByText("Size override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).not.toContain("text-[40px]")
+    })
+
+    it("rejects font-weight override", () => {
+      const { getByText } = render(
+        <F0Text variant="body-sm-default" className="font-bold">
+          Weight override attempt
+        </F0Text>
+      )
+      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(
+        <F0Text variant="body-sm-default" className="leading-10">
+          Leading override attempt
+        </F0Text>
+      )
+      const element = getByText("Leading override attempt")
+      expect(element.props.className).toContain("leading-[20px]")
+      expect(element.props.className).not.toContain("leading-10")
+    })
+
+    it("rejects letter-spacing override", () => {
+      const { getByText } = render(
+        <F0Text variant="heading-lg" className="tracking-widest">
+          Tracking override attempt
+        </F0Text>
+      )
+      const element = getByText("Tracking override attempt")
+      expect(element.props.className).toContain("tracking-[-0.2px]")
+      expect(element.props.className).not.toContain("tracking-widest")
+    })
+
+    it("rejects text-color override", () => {
+      const { getByText } = render(
+        <F0Text color="default" className="text-red-500">
+          Color override attempt
+        </F0Text>
+      )
+      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 text-align override", () => {
+      const { getByText } = render(
+        <F0Text align="left" className="text-center">
+          Align override attempt
+        </F0Text>
+      )
+      const element = getByText("Align override attempt")
+      expect(element.props.className).toContain("text-left")
+      expect(element.props.className).not.toContain("text-center")
+    })
+
+    it("rejects text-decoration override", () => {
+      const { getByText } = render(
+        <F0Text decoration="none" className="underline">
+          Decoration override attempt
+        </F0Text>
+      )
+      const element = getByText("Decoration override attempt")
+      const classes = element.props.className.split(" ")
+      expect(classes).not.toContain("underline")
+      expect(classes).toContain("no-underline")
+    })
+
+    it("rejects text-transform override", () => {
+      const { getByText } = render(
+        <F0Text transform="none" className="uppercase">
+          Transform override attempt
+        </F0Text>
+      )
+      const element = getByText("Transform override attempt")
+      expect(element.props.className).not.toContain("uppercase")
+    })
+
+    it("rejects multiple typography overrides simultaneously", () => {
+      const { getByText } = render(
+        <F0Text
+          variant="body-sm-default"
+          color="default"
+          className="text-xl leading-loose font-bold tracking-wider text-blue-500"
+        >
+          Multi override attempt
+        </F0Text>
+      )
+      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(
         <F0Text
-          {...(propsWithClassName as React.ComponentProps<typeof F0Text>)}
+          variant="heading-md"
+          className="mt-4 flex-1 p-2 text-xl font-bold text-red-500"
         >
-          Text with className attempt
+          Mixed attempt
         </F0Text>
       )
-      const element = getByText("Text with className attempt")
+      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("handles ref forwarding", () => {
-      const ref = React.createRef<RNText>()
-      render(<F0Text ref={ref}>Ref text</F0Text>)
-      expect(ref.current).toBeTruthy()
+    it("handles real-world card pattern without View wrapper", () => {
+      const { getByText } = render(
+        <F0Text variant="heading-sm" className="mb-2">
+          Card Title
+        </F0Text>
+      )
+      const element = getByText("Card Title")
+      expect(element.props.className).toContain("mb-2")
+      expect(element.props.className).toContain("text-[16px]")
+      expect(element.props.className).toContain("font-semibold")
     })
 
-    it("renders nested children", () => {
+    it("handles icon + text row pattern", () => {
       const { getByText } = render(
-        <F0Text>
-          Parent <F0Text variant="body-xs-medium">nested</F0Text> text
+        <F0Text variant="body-sm-default" className="ml-2 flex-1">
+          Row item text
         </F0Text>
       )
-      expect(getByText("nested")).toBeTruthy()
+      const element = getByText("Row item text")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("ml-2")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+    })
+  })
+
+  describe("className — edge cases", () => {
+    it("works correctly when className is undefined", () => {
+      const { getByText } = render(<F0Text>No className</F0Text>)
+      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(
+        <F0Text className="">Empty className</F0Text>
+      )
+      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(
+        <F0Text className="  mt-4   mb-2  ">Whitespace className</F0Text>
+      )
+      const element = getByText("Whitespace className")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("mb-2")
+    })
+
+    it("still blocks style prop even when className is allowed", () => {
+      const propsWithBoth = {
+        style: { color: "red", marginTop: 10 },
+        className: "mt-4",
+        children: "Both props",
+      }
+      const { getByText } = render(
+        <F0Text {...(propsWithBoth as React.ComponentProps<typeof F0Text>)}>
+          Both props
+        </F0Text>
+      )
+      const element = getByText("Both props")
+      expect(element.props.style).toBeUndefined()
+      expect(element.props.className).toContain("mt-4")
+    })
+
+    it("produces correct output without className", () => {
+      const { getByText } = render(
+        <F0Text variant="heading-lg" color="accent" align="center">
+          No className
+        </F0Text>
+      )
+      const element = getByText("No className")
+      expect(element.props.className).toContain("no-underline")
+      expect(element.props.className).toContain("normal-case")
+      expect(element.props.className).toContain("text-[24px]")
+      expect(element.props.className).toContain("leading-[32px]")
+      expect(element.props.className).toContain("tracking-[-0.2px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.className).toContain("text-f0-foreground-accent")
+      expect(element.props.className).toContain("text-center")
     })
   })
 })