@factorialco/f0-react-native 0.28.0 → 0.29.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>
 ```
 
@@ -277,14 +283,59 @@ F0Text/                        # Parent folder for text primitives
 
 ### Font Family
 
-F0Text uses **Inter** font family through Tailwind/Uniwind font weight classes:
+F0Text uses the **Inter** font family through Tailwind/Uniwind `font-*` utility classes,
+which map to `--font-*` CSS variables defined in the app's `@theme`:
+
+| Tailwind Class  | CSS Variable      | Font Name      | Font Weight |
+| --------------- | ----------------- | -------------- | ----------- |
+| `font-normal`   | `--font-normal`   | Inter-Regular  | 400         |
+| `font-medium`   | `--font-medium`   | Inter-Medium   | 500         |
+| `font-semibold` | `--font-semibold` | Inter-SemiBold | 600         |
+| `font-bold`     | `--font-bold`     | Inter-Bold     | 700         |
+
+#### Host App Font Setup
+
+The consuming app must embed the Inter `.ttf` files and wire them up for both
+iOS and Android. See the [README "Add Inter Fonts"](../../../../../README.md#5️⃣-add-inter-fonts-host-app) section for the full
+step-by-step guide. The short version:
+
+1. **Name font files to match their PostScript name** (e.g. `Inter-Regular.ttf`
+   for PostScript name `Inter-Regular`). iOS resolves fonts by PostScript name,
+   Android by asset file name — matching them avoids platform-specific overrides.
+
+2. **Register via `expo-font`** config plugin in `app.json`:
+
+```json
+[
+  "expo-font",
+  {
+    "fonts": [
+      "./assets/fonts/Inter/Inter-Regular.ttf",
+      "./assets/fonts/Inter/Inter-Medium.ttf",
+      "./assets/fonts/Inter/Inter-SemiBold.ttf",
+      "./assets/fonts/Inter/Inter-Bold.ttf"
+    ]
+  }
+]
+```
 
-| 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         |
+3. **Define `@theme` variables** in `global.css`:
+
+```css
+@theme {
+  --font-normal: "Inter-Regular";
+  --font-medium: "Inter-Medium";
+  --font-semibold: "Inter-SemiBold";
+  --font-bold: "Inter-Bold";
+}
+```
+
+The `@theme` values must match the file names (without `.ttf`). Uniwind maps
+`font-normal`, `font-medium`, `font-semibold`, and `font-bold` utility classes
+to these variables.
+
+> **Rebuild required:** Font changes are picked up at native build time.
+> Run `npx expo prebuild --clean` after adding or renaming font files.
 
 ## Accessibility
 
@@ -302,11 +353,16 @@ F0Text uses **Inter** font family through Tailwind/Uniwind font weight classes:
 
 <!-- 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

@@ -2,11 +2,12 @@ import { tv, type VariantProps } from "tailwind-variants"
 
 /**
  * Text component variants using tailwind-variants
- * Font weights (font-normal, font-medium, font-semibold) map to
- * Inter font families (Inter-Regular, Inter-Medium, Inter-SemiBold)
+ * Font weights (font-normal, font-medium, font-semibold, font-bold) map to
+ * Inter font families (Inter-Regular, Inter-Medium, Inter-SemiBold, Inter-Bold)
+ * 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">