@factorialco/f0-react-native 0.33.0 → 0.35.0

package/src/components/F0Button/F0Button.md

@@ -0,0 +1,163 @@
+# F0Button
+
+Primary interactive button component for the F0 Design System.
+
+## Overview
+
+F0Button is the semantic button API for React Native in F0. It supports:
+
+- Visual variants (`default`, `outline`, `critical`, `neutral`, `ghost`, `promote`)
+- Size variants (`sm`, `md`, `lg`)
+- Optional icon / emoji content
+- Icon-only round mode
+- Async press handlers with automatic loading-state handling
+- Visible loading indicator when busy
+- Press feedback control through `PressableFeedback`
+
+## Architecture
+
+- **Pattern:** Props API (Atomic) - element order is fixed: icon -> emoji -> label
+- **Press feedback:** Uses `PressableFeedback` component for smooth animations
+- **Press state:** Tracks pressed state with `useState` for color changes by variant
+- **Loading state:** Supports auto-loading when `onPress` returns a Promise
+- **Styling:** `className` and `style` are blocked in the public API and filtered at runtime
+- **Location:** `src/components/F0Button/`
+
+## Usage
+
+<!-- prettier-ignore -->
+```tsx
+import { F0Button } from "@factorialco/f0-react-native"
+import { Archive } from "@factorialco/f0-react-native/icons/app"
+
+<F0Button label="Submit" onPress={handleSubmit} />
+
+<F0Button label="Delete" variant="critical" icon={Archive} />
+
+<F0Button label="Add" icon={Archive} hideLabel round />
+
+<F0Button label="Save" onPress={async () => await saveData()} />
+
+<F0Button label="Love" emoji="🥰" variant="neutral" />
+
+<F0Button label="Custom" feedback="scale" />
+```
+
+## Props
+
+| Prop                | Type                             | Default     | Description                                                |
+| ------------------- | -------------------------------- | ----------- | ---------------------------------------------------------- |
+| `label`             | `string`                         | required    | Visible label and accessibility base label                 |
+| `onPress`           | `() => void \| Promise<unknown>` | —           | Press handler; async return enables auto-loading           |
+| `variant`           | `F0ButtonVariant`                | `"default"` | Visual style variant                                       |
+| `size`              | `F0ButtonSize`                   | `"md"`      | Control height and radius                                  |
+| `disabled`          | `boolean`                        | `false`     | Disabled state                                             |
+| `loading`           | `boolean`                        | `false`     | External loading control                                   |
+| `icon`              | `IconType`                       | —           | Optional icon                                              |
+| `emoji`             | `string`                         | —           | Optional emoji                                             |
+| `hideLabel`         | `boolean`                        | `false`     | Hide visible label (keeps accessibility label)             |
+| `round`             | `boolean`                        | `false`     | Makes icon-only mode circular                              |
+| `showBadge`         | `boolean`                        | `false`     | Notification badge (outline variant only)                  |
+| `fullWidth`         | `boolean`                        | `false`     | Makes button fill available horizontal space               |
+| `feedback`          | `PressableFeedbackVariant`       | `"both"`    | Press feedback mode (`both`, `scale`, `highlight`, `none`) |
+| `accessibilityHint` | `string`                         | —           | Optional screen-reader hint                                |
+| `testID`            | `string`                         | —           | Test identifier                                            |
+
+### Variants
+
+- `default` - primary/high-emphasis action
+- `outline` - secondary action with border
+- `critical` - destructive action
+- `neutral` - neutral secondary action
+- `ghost` - subtle transparent action
+- `promote` - promotional/highlighted action
+
+### Sizes
+
+- `sm` - compact
+- `md` - default
+- `lg` - large
+
+## Runtime Behavior
+
+### Async onPress auto-loading
+
+If `onPress` returns a Promise, F0Button enters internal loading state until it resolves.
+
+<!-- prettier-ignore -->
+```tsx
+<F0Button
+  label="Save"
+  onPress={async () => {
+    await saveData()
+  }}
+/>
+```
+
+### Loading visuals
+
+When `loading` is `true` (external) or an async `onPress` is pending (internal):
+
+- the button becomes non-interactive (`disabled`)
+- a centered spinner indicator is rendered
+- button content is visually hidden (`opacity`) to keep layout stable
+
+### Press feedback
+
+F0Button delegates touch feedback to `PressableFeedback` and supports semantic control via `feedback`.
+
+<!-- prettier-ignore -->
+```tsx
+<F0Button label="Both" feedback="both" />
+<F0Button label="Scale only" feedback="scale" />
+<F0Button label="Highlight only" feedback="highlight" />
+<F0Button label="No visual feedback" feedback="none" />
+```
+
+## Styling Contract
+
+F0Button is semantic-first:
+
+- `className` is **not** part of `F0ButtonProps`
+- `style` is **not** part of `F0ButtonProps`
+- Both are filtered at runtime before forwarding props to internal pressable primitives
+
+This guarantees semantic variants remain source-of-truth and prevents style overrides from bypassing the API contract.
+
+## Accessibility
+
+- Always sets `accessibilityRole="button"`
+- Auto-builds `accessibilityLabel` from `label` plus state:
+  - `"label, disabled"`
+  - `"label, disabled, loading"`
+- Exposes `accessibilityState` with:
+  - `disabled`
+  - `busy`
+- `hideLabel` does not remove accessibility label
+
+## Testing
+
+Main test suite:
+
+- `src/components/F0Button/__tests__/F0Button.spec.tsx`
+
+Coverage includes:
+
+- snapshots across variants/sizes/states
+- async loading behavior
+- accessibility label/state
+- badge rendering rules
+- runtime blocking of `className`/`style`
+
+## File Structure
+
+```
+src/components/F0Button/
+├── F0Button.tsx
+├── F0Button.types.ts
+├── F0Button.styles.ts
+├── F0Button.md
+├── __tests__/
+│   └── F0Button.spec.tsx
+└── index.ts
+```

package/src/components/F0Button/F0Button.styles.ts

@@ -0,0 +1,141 @@
+import { tv } from "tailwind-variants"
+
+import type { IconColor } from "../primitives/F0Icon"
+import type { TextColor } from "../primitives/F0Text"
+
+import type { ButtonVariant } from "./F0Button.types"
+
+export const buttonVariants = tv({
+  base: "flex-row items-center justify-center rounded border-none grow-0",
+  variants: {
+    variant: {
+      default: "bg-f0-background-accent-bold",
+      outline: "bg-f0-background-inverse-secondary border border-f0-border",
+      neutral: "bg-f0-background-secondary",
+      critical: "bg-f0-background-secondary border border-f0-border",
+      ghost: "bg-transparent",
+      promote: "bg-f0-background-promote border border-f0-border-promote",
+    },
+    size: {
+      sm: "h-6 rounded-sm",
+      md: "h-8 rounded",
+      lg: "h-10 rounded-md",
+    },
+    disabled: {
+      true: "opacity-50",
+      false: "",
+    },
+    round: {
+      true: "aspect-square p-0",
+      false: "gap-1 px-2 sm:px-3 lg:px-4",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+    size: "md",
+    disabled: false,
+    round: false,
+  },
+})
+
+export const pressedVariants = tv({
+  base: "",
+  variants: {
+    variant: {
+      default: "bg-f0-background-accent-bold-hover",
+      outline: "bg-f0-background-tertiary border-opacity-70",
+      neutral: "bg-f0-background-secondary-hover",
+      critical: "bg-f0-background-critical-bold border-transparent",
+      ghost: "bg-f0-background-secondary-hover",
+      promote: "bg-f0-background-promote-hover",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+  },
+})
+
+export const loadingContentVariants = tv({
+  variants: {
+    loading: {
+      true: "opacity-0",
+      false: "opacity-100",
+    },
+  },
+  defaultVariants: {
+    loading: false,
+  },
+})
+
+export const loadingIndicatorVariants = tv({
+  base: "rounded-full border-solid border-t-transparent",
+  variants: {
+    variant: {
+      default: "border-f0-foreground-inverse",
+      outline: "border-f0-foreground",
+      neutral: "border-f0-foreground",
+      critical: "border-f0-icon-critical",
+      ghost: "border-f0-foreground",
+      promote: "border-f0-icon-promote",
+    },
+    size: {
+      sm: "h-3 w-3 border",
+      md: "h-4 w-4 border-2",
+      lg: "h-5 w-5 border-2",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+    size: "md",
+  },
+})
+
+export const getIconColor = (
+  variant: ButtonVariant,
+  isPressed: boolean
+): IconColor => {
+  switch (variant) {
+    case "default":
+      return "inverse"
+    case "critical":
+      return isPressed ? "inverse" : "critical-bold"
+    default:
+      return "default"
+  }
+}
+
+export const getIconOnlyColor = (
+  variant: ButtonVariant,
+  isPressed: boolean
+): IconColor => {
+  switch (variant) {
+    case "critical":
+      return isPressed ? "inverse" : "critical-bold"
+    case "default":
+      return "inverse"
+    case "outline":
+    case "neutral":
+    case "ghost":
+    case "promote":
+    default:
+      return "bold"
+  }
+}
+
+export const getTextColor = (
+  variant: ButtonVariant,
+  isPressed: boolean
+): TextColor => {
+  if (isPressed && variant === "critical") {
+    return "inverse"
+  }
+
+  switch (variant) {
+    case "default":
+      return "inverse"
+    case "critical":
+      return "critical"
+    default:
+      return "default"
+  }
+}

package/src/components/F0Button/F0Button.tsx

@@ -0,0 +1,228 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from "react"
+import { View } from "react-native"
+import Animated, {
+  Easing,
+  cancelAnimation,
+  useAnimatedStyle,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from "react-native-reanimated"
+
+import { cn, omitProps } from "../../lib/utils"
+import { F0Icon } from "../primitives/F0Icon"
+import { F0Text } from "../primitives/F0Text"
+import { PressableFeedback } from "../primitives/PressableFeedback"
+
+import {
+  buttonVariants,
+  loadingContentVariants,
+  loadingIndicatorVariants,
+  pressedVariants,
+  getIconColor,
+  getIconOnlyColor,
+  getTextColor,
+} from "./F0Button.styles"
+import {
+  F0_BUTTON_BLOCKED_FORWARD_PROPS,
+  type F0ButtonProps,
+} from "./F0Button.types"
+
+const F0Button = React.memo(
+  forwardRef<View, F0ButtonProps>(function F0Button(
+    {
+      label,
+      onPress,
+      disabled = false,
+      loading = false,
+      icon,
+      emoji,
+      hideLabel = false,
+      variant = "default",
+      size = "md",
+      round = false,
+      accessibilityHint,
+      showBadge = false,
+      fullWidth = false,
+      testID,
+      feedback = "both",
+      ...rest
+    },
+    ref
+  ) {
+    const [isLoading, setIsLoading] = useState(false)
+    const [isPressed, setIsPressed] = useState(false)
+    const spinnerRotation = useSharedValue(0)
+
+    const isBusy = loading || isLoading
+    const isDisabled = disabled || isBusy
+    const isRound = hideLabel && round
+
+    const handlePress = useCallback(async () => {
+      if (!onPress || isDisabled) return
+
+      try {
+        const result = onPress()
+
+        if (result && typeof result.then === "function") {
+          setIsLoading(true)
+          try {
+            await result
+          } catch {
+            // Avoid bubbling async handler rejections from a design-system component.
+          } finally {
+            setIsLoading(false)
+          }
+        }
+      } catch {
+        // Avoid bubbling sync exceptions from a design-system component.
+      }
+    }, [onPress, isDisabled])
+
+    useEffect(() => {
+      if (!isBusy) {
+        cancelAnimation(spinnerRotation)
+        spinnerRotation.value = 0
+        return
+      }
+
+      spinnerRotation.value = 0
+      spinnerRotation.value = withRepeat(
+        withTiming(1, {
+          duration: 1000,
+          easing: Easing.linear,
+        }),
+        -1,
+        false
+      )
+    }, [isBusy, spinnerRotation])
+
+    const handlePressIn = useCallback(() => {
+      if (!isDisabled) {
+        setIsPressed(true)
+      }
+    }, [isDisabled])
+
+    const handlePressOut = useCallback(() => {
+      setIsPressed(false)
+    }, [])
+
+    const baseClassName = useMemo(
+      () =>
+        buttonVariants({
+          variant,
+          size,
+          disabled: isDisabled,
+          round: isRound,
+        }),
+      [variant, size, isDisabled, isRound]
+    )
+
+    const accessibilityLabel = useMemo(() => {
+      const parts = [label]
+      if (isDisabled) parts.push("disabled")
+      if (isBusy) parts.push("loading")
+      return parts.join(", ")
+    }, [label, isBusy, isDisabled])
+
+    const shouldShowPressed = isPressed && !isDisabled
+
+    const className = shouldShowPressed
+      ? cn(baseClassName, pressedVariants({ variant }))
+      : baseClassName
+
+    const iconIsOnly = isRound || (hideLabel && !emoji)
+    const iconColor = icon
+      ? iconIsOnly
+        ? getIconOnlyColor(variant, shouldShowPressed)
+        : getIconColor(variant, shouldShowPressed)
+      : undefined
+    const textColor = getTextColor(variant, shouldShowPressed)
+    const forwardedProps = omitProps(rest, F0_BUTTON_BLOCKED_FORWARD_PROPS)
+    const loadingIndicatorStyle = useAnimatedStyle(() => {
+      return {
+        borderTopColor: "transparent",
+        transform: [{ rotateZ: `${spinnerRotation.value * 360}deg` }],
+      }
+    })
+
+    return (
+      <View className={`flex ${fullWidth ? "flex-1" : "items-start"}`}>
+        <PressableFeedback
+          ref={ref}
+          {...forwardedProps}
+          disabled={isDisabled}
+          variant={feedback}
+          onPress={handlePress}
+          onPressIn={handlePressIn}
+          onPressOut={handlePressOut}
+          accessibilityLabel={accessibilityLabel}
+          accessibilityRole="button"
+          accessibilityState={{
+            disabled: isDisabled,
+            busy: isBusy,
+          }}
+          accessibilityHint={accessibilityHint}
+          testID={testID}
+        >
+          <View className={cn("relative", className)}>
+            <View
+              testID="f0-button-content"
+              className={loadingContentVariants({ loading: isBusy })}
+            >
+              <View className="flex-row items-center justify-center gap-1">
+                {icon && (
+                  <F0Icon
+                    icon={icon}
+                    size="lg"
+                    className={isRound ? undefined : "-ml-0.5"}
+                    color={iconColor}
+                  />
+                )}
+                {emoji && (
+                  <F0Text variant="body-md-medium" color={textColor}>
+                    {emoji}
+                  </F0Text>
+                )}
+                {!hideLabel && (
+                  <F0Text variant="body-md-medium" color={textColor}>
+                    {label}
+                  </F0Text>
+                )}
+              </View>
+            </View>
+            {isBusy && (
+              <View
+                pointerEvents="none"
+                className="absolute inset-0 items-center justify-center"
+              >
+                <Animated.View
+                  testID="f0-button-loading-indicator"
+                  accessibilityLabel="Loading indicator"
+                  className={loadingIndicatorVariants({ variant, size })}
+                  style={loadingIndicatorStyle}
+                />
+              </View>
+            )}
+          </View>
+        </PressableFeedback>
+        {showBadge && variant === "outline" && (
+          <View
+            accessibilityLabel="Notification Badge"
+            className="absolute top-1.5 right-1.5 h-1.5 w-1.5 rounded-full bg-f0-icon-accent"
+          />
+        )}
+      </View>
+    )
+  })
+)
+
+F0Button.displayName = "F0Button"
+
+export { F0Button }

package/src/components/F0Button/F0Button.types.ts

@@ -0,0 +1,82 @@
+import type { IconType } from "../primitives/F0Icon"
+import type {
+  PressableFeedbackProps,
+  PressableFeedbackVariant,
+} from "../primitives/PressableFeedback"
+
+/**
+ * Button variant types
+ */
+export const BUTTON_VARIANTS = [
+  "default",
+  "outline",
+  "critical",
+  "neutral",
+  "ghost",
+  "promote",
+] as const
+
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number]
+export type F0ButtonVariant = ButtonVariant
+
+/**
+ * Button size types
+ */
+export const BUTTON_SIZES = ["sm", "md", "lg"] as const
+
+export type ButtonSize = (typeof BUTTON_SIZES)[number]
+export type F0ButtonSize = ButtonSize
+
+/**
+ * Props that are controlled by F0Button and must not be passed through.
+ * This preserves F0Button press-state behavior and accessibility contract.
+ */
+const F0_BUTTON_CONTROLLED_PASSTHROUGH_PROPS = [
+  "onPressIn",
+  "onPressOut",
+  "accessibilityLabel",
+  "accessibilityRole",
+  "accessibilityState",
+] as const
+
+export const F0_BUTTON_BANNED_PROPS = ["style", "className"] as const
+
+export const F0_BUTTON_BLOCKED_FORWARD_PROPS = [
+  ...F0_BUTTON_CONTROLLED_PASSTHROUGH_PROPS,
+  ...F0_BUTTON_BANNED_PROPS,
+] as const
+
+interface F0ButtonPropsInternal extends Omit<
+  PressableFeedbackProps,
+  | "children"
+  | "variant"
+  | "disabled"
+  | (typeof F0_BUTTON_CONTROLLED_PASSTHROUGH_PROPS)[number]
+> {
+  label: string
+  onPress?: () => void | Promise<unknown>
+  variant?: ButtonVariant
+  size?: ButtonSize
+  disabled?: boolean
+  loading?: boolean
+  icon?: IconType
+  emoji?: string
+  hideLabel?: boolean
+  round?: boolean
+  showBadge?: boolean
+  fullWidth?: boolean
+  accessibilityHint?: string
+  testID?: string
+  feedback?: PressableFeedbackVariant
+}
+
+/**
+ * Public props for the F0Button component.
+ *
+ * Note: `className` and `style` props are NOT available.
+ * Use semantic props (variant, size, etc.) for styling.
+ */
+export type F0ButtonProps = Omit<
+  F0ButtonPropsInternal,
+  (typeof F0_BUTTON_BANNED_PROPS)[number]
+>