@factorialco/f0-react-native 0.29.0 → 0.30.0

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

@@ -0,0 +1,77 @@
+import type { ForwardRefExoticComponent, RefAttributes } from "react"
+import type { SvgProps } from "react-native-svg"
+import type { Svg } from "react-native-svg"
+import type { VariantProps } from "tailwind-variants"
+
+import type { iconVariants } from "./F0Icon.styles"
+
+/**
+ * Icon component type - forward ref to SVG component with className support
+ */
+export type IconType = ForwardRefExoticComponent<
+  SvgProps &
+    RefAttributes<Svg> & {
+      className?: string
+    }
+>
+
+/**
+ * Icon color variants derived from f0-icon-* tokens in src/styles/theme.css
+ * Sync is enforced by F0Icon.tokens.spec.ts
+ */
+export const ICON_COLORS = [
+  "default",
+  "secondary",
+  "inverse",
+  "bold",
+  "critical",
+  "critical-bold",
+  "accent",
+  "info",
+  "warning",
+  "positive",
+  "promote",
+  "selected",
+  "selected-hover",
+  "mood-super-negative",
+  "mood-negative",
+  "mood-neutral",
+  "mood-positive",
+  "mood-super-positive",
+] as const
+
+export type IconColor = (typeof ICON_COLORS)[number]
+
+/**
+ * Public F0Icon props
+ * Supports semantic color via `color` prop, with `className` as escape hatch.
+ */
+export interface F0IconProps extends Omit<SvgProps, "style"> {
+  /**
+   * Tailwind className for custom styling or color overrides.
+   * Prefer the `color` prop for semantic icon colors.
+   */
+  className?: string
+
+  /**
+   * Semantic icon color from the F0 design system
+   * Maps to f0-icon-* tokens (e.g. color="critical" -> text-f0-icon-critical)
+   */
+  color?: IconColor
+
+  /**
+   * Icon component to render (from icons directory)
+   */
+  icon: IconType
+
+  /**
+   * Icon size variant
+   * @default 'md'
+   */
+  size?: VariantProps<typeof iconVariants>["size"]
+
+  /**
+   * Test ID for testing
+   */
+  testID?: string
+}

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

@@ -0,0 +1,131 @@
+import { render } from "@testing-library/react-native"
+import React from "react"
+
+import { Archive } from "../../../../icons/app"
+import { Home } from "../../../../icons/modules"
+import { applyIconInterop } from "../F0Icon"
+import F0Icon from "../F0Icon"
+
+describe("F0Icon", () => {
+  it("renders correctly with an app icon", () => {
+    const { getByTestId } = render(<F0Icon icon={Archive} testID="icon" />)
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  it("renders correctly with a module icon", () => {
+    const { getByTestId } = render(<F0Icon icon={Home} testID="icon" />)
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  it("applies the correct size variant", () => {
+    const { getByTestId } = render(
+      <F0Icon icon={Archive} size="lg" testID="icon" />
+    )
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  it("returns null when no icon is provided", () => {
+    // @ts-expect-error - Testing runtime behavior
+    const { queryByTestId } = render(<F0Icon testID="icon" />)
+    expect(queryByTestId("icon")).toBeNull()
+  })
+
+  it("applies default size when size prop is not provided", () => {
+    const { getByTestId } = render(<F0Icon icon={Archive} testID="icon" />)
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  it("forwards ref correctly", () => {
+    const ref = React.createRef<React.ElementRef<typeof F0Icon>>()
+    render(<F0Icon icon={Archive} ref={ref} testID="icon" />)
+    expect(ref.current).toBeTruthy()
+  })
+
+  it("renders with a color prop", () => {
+    const { getByTestId } = render(
+      <F0Icon icon={Archive} color="critical" testID="icon" />
+    )
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  it("caches wrapped icon: applyIconInterop returns same instance for same icon", () => {
+    const wrapped1 = applyIconInterop(Archive)
+    const wrapped2 = applyIconInterop(Archive)
+    expect(wrapped1).toBe(wrapped2)
+  })
+
+  it("caches per icon type: different icons return different wrapped instances", () => {
+    const wrappedArchive = applyIconInterop(Archive)
+    const wrappedHome = applyIconInterop(Home)
+    expect(wrappedArchive).not.toBe(wrappedHome)
+  })
+
+  it("renders with both color and className", () => {
+    const { getByTestId } = render(
+      <F0Icon icon={Archive} color="info" className="-ml-0.5" testID="icon" />
+    )
+    expect(getByTestId("icon")).toBeTruthy()
+  })
+
+  describe("className — cn() merging", () => {
+    it("passes through layout classes from className", () => {
+      const { getByTestId } = render(
+        <F0Icon icon={Archive} className="-ml-0.5" testID="icon" />
+      )
+      const element = getByTestId("icon")
+      expect(element.props.className).toContain("-ml-0.5")
+    })
+
+    it("merges conflicting size: custom w-* overrides variant", () => {
+      const { getByTestId } = render(
+        <F0Icon icon={Archive} size="md" className="h-10 w-10" testID="icon" />
+      )
+      const element = getByTestId("icon")
+      expect(element.props.className).toContain("w-10")
+      expect(element.props.className).toContain("h-10")
+      expect(element.props.className).not.toContain("w-5")
+      expect(element.props.className).not.toContain("h-5")
+    })
+
+    it("merges conflicting color: custom text-* overrides variant", () => {
+      const { getByTestId } = render(
+        <F0Icon
+          icon={Archive}
+          color="critical"
+          className="text-red-500"
+          testID="icon"
+        />
+      )
+      const element = getByTestId("icon")
+      expect(element.props.className).toContain("text-red-500")
+      expect(element.props.className).not.toContain("text-f0-icon-critical")
+    })
+
+    it("uses only variant classes when className is undefined", () => {
+      const { getByTestId } = render(
+        <F0Icon icon={Archive} size="sm" color="positive" testID="icon" />
+      )
+      const element = getByTestId("icon")
+      expect(element.props.className).toContain("w-4")
+      expect(element.props.className).toContain("h-4")
+      expect(element.props.className).toContain("text-f0-icon-positive")
+    })
+
+    it("combines non-conflicting variant and className", () => {
+      const { getByTestId } = render(
+        <F0Icon
+          icon={Archive}
+          size="lg"
+          color="info"
+          className="opacity-50"
+          testID="icon"
+        />
+      )
+      const element = getByTestId("icon")
+      expect(element.props.className).toContain("w-6")
+      expect(element.props.className).toContain("h-6")
+      expect(element.props.className).toContain("text-f0-icon-info")
+      expect(element.props.className).toContain("opacity-50")
+    })
+  })
+})

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/icons/index.ts

@@ -2,4 +2,3 @@ import * as AppIcons from "./app"
 import * as ModuleIcons from "./modules"
 export { AppIcons, ModuleIcons }
 export * from "./types"
-export { Icon } from "../components/Icon"

package/lib/module/components/Icon/README.md

@@ -1,63 +0,0 @@
-# Icon Component
-
-The Icon component is used to render SVG icons from the F0 Design System in React Native applications.
-
-## Import Pattern
-
-```tsx
-// Import the Icon component
-import { Icon } from "@factorialco/f0-react-native";
-
-// Import specific icons from app or modules directories
-import { AppIcons, ModuleIcons } from "@factorialco/f0-react-native";
-
-// Use the Icon component with the icon as a prop
-<Icon icon={AppIcons.Archive} size="md" />
-<Icon icon={ModuleIcons.Home} size="lg" />
-```
-
-## Props
-
-| Prop      | Type                         | Default | Description                             |
-| --------- | ---------------------------- | ------- | --------------------------------------- |
-| icon      | IconType                     |         | The icon component to render            |
-| size      | "xs" \| "sm" \| "md" \| "lg" | "md"    | The size of the icon                    |
-| className | string                       |         | Additional classes for styling the icon |
-| testID    | string                       |         | Test ID for testing                     |
-| ...props  | SvgProps                     |         | Additional props for the SVG component  |
-
-## Styling with UniWind
-
-The Icon component is designed to work with UniWind, allowing you to style icons using Tailwind CSS classes:
-
-```tsx
-// Style using Tailwind CSS classes
-<Icon icon={AppIcons.Archive} className="text-f0-icon-secondary" />
-```
-
-## Available Icons
-
-The library includes two sets of icons:
-
-1. **App Icons** - General purpose icons used throughout the application
-2. **Module Icons** - Icons representing specific modules in the Factorial application
-
-## Examples
-
-```tsx
-import { Icon } from "@factorialco/f0-react-native";
-import { AppIcons, ModuleIcons } from "@factorialco/f0-react-native";
-
-// Basic usage
-<Icon icon={AppIcons.Calendar} />
-
-// With size variant
-<Icon icon={AppIcons.ChevronDown} size="xs" />
-<Icon icon={AppIcons.Check} size="sm" />
-<Icon icon={ModuleIcons.Home} size="md" />
-<Icon icon={ModuleIcons.Settings} size="lg" />
-
-// With color styling
-<Icon icon={AppIcons.Heart} className="text-red-500" />
-<Icon icon={AppIcons.InfoCircle} className="text-blue-500" />
-```

package/src/components/Icon/README.md

@@ -1,63 +0,0 @@
-# Icon Component
-
-The Icon component is used to render SVG icons from the F0 Design System in React Native applications.
-
-## Import Pattern
-
-```tsx
-// Import the Icon component
-import { Icon } from "@factorialco/f0-react-native";
-
-// Import specific icons from app or modules directories
-import { AppIcons, ModuleIcons } from "@factorialco/f0-react-native";
-
-// Use the Icon component with the icon as a prop
-<Icon icon={AppIcons.Archive} size="md" />
-<Icon icon={ModuleIcons.Home} size="lg" />
-```
-
-## Props
-
-| Prop      | Type                         | Default | Description                             |
-| --------- | ---------------------------- | ------- | --------------------------------------- |
-| icon      | IconType                     |         | The icon component to render            |
-| size      | "xs" \| "sm" \| "md" \| "lg" | "md"    | The size of the icon                    |
-| className | string                       |         | Additional classes for styling the icon |
-| testID    | string                       |         | Test ID for testing                     |
-| ...props  | SvgProps                     |         | Additional props for the SVG component  |
-
-## Styling with UniWind
-
-The Icon component is designed to work with UniWind, allowing you to style icons using Tailwind CSS classes:
-
-```tsx
-// Style using Tailwind CSS classes
-<Icon icon={AppIcons.Archive} className="text-f0-icon-secondary" />
-```
-
-## Available Icons
-
-The library includes two sets of icons:
-
-1. **App Icons** - General purpose icons used throughout the application
-2. **Module Icons** - Icons representing specific modules in the Factorial application
-
-## Examples
-
-```tsx
-import { Icon } from "@factorialco/f0-react-native";
-import { AppIcons, ModuleIcons } from "@factorialco/f0-react-native";
-
-// Basic usage
-<Icon icon={AppIcons.Calendar} />
-
-// With size variant
-<Icon icon={AppIcons.ChevronDown} size="xs" />
-<Icon icon={AppIcons.Check} size="sm" />
-<Icon icon={ModuleIcons.Home} size="md" />
-<Icon icon={ModuleIcons.Settings} size="lg" />
-
-// With color styling
-<Icon icon={AppIcons.Heart} className="text-red-500" />
-<Icon icon={AppIcons.InfoCircle} className="text-blue-500" />
-```