@butternutbox/pawprint-native 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,30 @@
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.0
+CLI Using tsup config: /home/runner/work/pawprint/pawprint/packages/pawprint-native/tsup.config.ts
+CLI Target: es6
+CLI Cleaning output folder
+CJS Build start
+ESM Build start
+DTS Build start
+CJS dist/ida-narrow-500-normal-C6I2PK4T.woff2              47.41 KB
+CJS dist/ida-narrow-700-normal-UPHPRIN6.woff2              49.90 KB
+CJS dist/ibm-plex-sans-condensed-400-normal-I2XLJNNB.woff2 19.33 KB
+CJS dist/ibm-plex-sans-condensed-500-normal-IEQBNVGX.woff2 19.48 KB
+CJS dist/ibm-plex-sans-condensed-600-normal-UX5ZU5T6.woff2 19.35 KB
+CJS dist/ibm-plex-sans-condensed-700-normal-4PFYFTSO.woff2 18.90 KB
+CJS dist/index.cjs                                         120.33 KB
+CJS dist/index.cjs.map                                     266.09 KB
+CJS ⚡️ Build success in 2528ms
+ESM dist/ida-narrow-500-normal-C6I2PK4T.woff2              47.41 KB
+ESM dist/ida-narrow-700-normal-UPHPRIN6.woff2              49.90 KB
+ESM dist/ibm-plex-sans-condensed-400-normal-I2XLJNNB.woff2 19.33 KB
+ESM dist/ibm-plex-sans-condensed-500-normal-IEQBNVGX.woff2 19.48 KB
+ESM dist/ibm-plex-sans-condensed-600-normal-UX5ZU5T6.woff2 19.35 KB
+ESM dist/ibm-plex-sans-condensed-700-normal-4PFYFTSO.woff2 18.90 KB
+ESM dist/index.js                                          113.16 KB
+ESM dist/index.js.map                                      265.43 KB
+ESM ⚡️ Build success in 2529ms
+DTS ⚡️ Build success in 12741ms
+DTS dist/index.d.cts 31.31 KB
+DTS dist/index.d.ts  31.31 KB

package/COMPONENT_GUIDELINES.md

@@ -0,0 +1,610 @@
+# Component Development Guidelines (React Native)
+
+> **Quick Start:** Type `Create a new component following llms.txt`
+
+## Core Principles
+
+### **1. Component Structure Template**
+
+Use `@emotion/native` `styled()` for styling and `@rn-primitives/*` for accessible foundations where available.
+
+```tsx
+import React from "react"
+import { View, ViewProps, Pressable, PressableProps } from "react-native"
+import styled from "@emotion/native"
+import { useTheme } from "@emotion/react"
+
+// Define prop types based on Figma design
+type [Component]OwnProps = {
+  variant?: "default" | "alt"
+  disabled?: boolean
+  children?: React.ReactNode
+}
+
+export type [Component]Props = [Component]OwnProps &
+  Omit<ViewProps, keyof [Component]OwnProps>
+
+// Helper for parsing string token values to numbers
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+// Styled component — Emotion native forwards all props by default,
+// so prefix internal-only props (e.g. badgeVariant) to avoid clashes.
+const Styled[Component] = styled(View)<{
+  componentVariant: string
+}>(({ theme, componentVariant }) => {
+  const { [componentName] } = theme.tokens.components
+
+  return {
+    // Use design tokens for all values
+    padding: parseTokenValue([componentName].spacing.padding),
+    backgroundColor: [componentName].colour.background[componentVariant]
+  }
+})
+
+// Component with forwardRef
+export const [Component] = React.forwardRef<View, [Component]Props>(
+  ({ variant = "default", disabled = false, children, ...rest }, ref) => {
+    const theme = useTheme()
+
+    return (
+      <Styled[Component]
+        ref={ref}
+        componentVariant={variant}
+        accessible
+        accessibilityRole="button"
+        {...rest}
+      >
+        {children}
+      </Styled[Component]>
+    )
+  }
+)
+
+[Component].displayName = "[Component]"
+```
+
+### **2. When to Use RN Primitives**
+
+**Use @rn-primitives when available:**
+
+```tsx
+// ✅ GOOD: Use rn-primitives for accessible foundation
+import * as CheckboxPrimitive from "@rn-primitives/checkbox"
+import * as SwitchPrimitive from "@rn-primitives/switch"
+import * as SliderPrimitive from "@rn-primitives/slider"
+```
+
+**Build custom when rn-primitives doesn't have the component:**
+
+```tsx
+// ✅ GOOD: Custom component with Pressable for interactivity
+import { Pressable, PressableProps } from "react-native"
+import styled from "@emotion/native"
+
+const StyledButton = styled(Pressable)<{ buttonVariant: string }>(({
+  theme,
+  buttonVariant
+}) => {
+  const { button } = theme.tokens.components.buttons
+  // Token-driven styles
+})
+
+export const Button = React.forwardRef<View, ButtonProps>((props, ref) => {
+  return <StyledButton ref={ref} {...props} />
+})
+```
+
+**When building custom components:**
+
+- Use `Pressable` for interactive elements (not `TouchableOpacity`)
+- Add `accessible`, `accessibilityRole`, and `accessibilityLabel` props
+- Use `accessibilityState` for disabled, checked, selected states
+- Test with VoiceOver (iOS) and TalkBack (Android)
+
+### **3. Design Token Usage**
+
+**Token Access Pattern:**
+
+Tokens are string values — use `parseTokenValue()` to convert to numbers for React Native styles.
+
+```tsx
+const parseTokenValue = (value: string): number => parseFloat(value)
+
+// Inside a styled component:
+const Styled = styled(View)(({ theme }) => {
+  const { badge } = theme.tokens.components.badges
+
+  return {
+    height: parseTokenValue(badge.sizing.medium.height),
+    paddingHorizontal: parseTokenValue(badge.spacing.medium.horizontalPadding),
+    borderRadius: parseTokenValue(badge.primary.borderRadius.default),
+    backgroundColor: badge.colour.background.default
+  }
+})
+
+// Inside a component body (via useTheme):
+const theme = useTheme()
+const color = theme.tokens.semantics.colour.text.primary
+```
+
+**Token Fallback Strategy:**
+
+1. **First choice:** Component tokens — `theme.tokens.components.[componentName]`
+2. **Second choice:** Semantic tokens — `theme.tokens.semantics.[category]`
+3. **Last resort:** Primitive tokens — `theme.tokens.primitives.[category]`
+4. **Temporary only:** Hardcoded values (document with TODO comment)
+
+```tsx
+// ✅ PREFERRED: Component tokens
+const { button } = theme.tokens.components.buttons
+backgroundColor: button.colour.background.primary
+
+// ✅ GOOD: Semantic tokens when component tokens don't exist
+backgroundColor: theme.tokens.semantics.colour.interactive.primary.default
+
+// ⚠️ ACCEPTABLE: Primitive tokens as fallback
+backgroundColor: theme.tokens.primitives.colour.brand.primary[500]
+
+// ❌ TEMPORARY ONLY: Hardcoded values (add TODO)
+backgroundColor: "#6200EA" // TODO: Replace with component token when available
+```
+
+### **4. Accessibility Requirements**
+
+**Essential a11y features:**
+
+- ✅ Use `React.forwardRef` for ref forwarding
+- ✅ Set `accessible={true}` on interactive elements
+- ✅ Use `accessibilityRole` — `"button"`, `"checkbox"`, `"image"`, etc.
+- ✅ Use `accessibilityLabel` for icon-only or image components
+- ✅ Use `accessibilityState={{ disabled, checked, selected }}` for stateful components
+- ✅ Handle `disabled` prop — prevent press handlers and apply disabled tokens
+- ✅ Dev-mode `console.warn` when `aria-label` is missing on icon-only components
+
+```tsx
+// ✅ GOOD: Proper accessibility on a toggle
+<Pressable
+  accessible
+  accessibilityRole="switch"
+  accessibilityLabel={label}
+  accessibilityState={{ checked: isOn, disabled }}
+  onPress={disabled ? undefined : toggle}
+>
+  {/* content */}
+</Pressable>
+
+// ✅ GOOD: Decorative vs meaningful images
+// Meaningful:
+<StyledRoot accessibilityRole="image" accessibilityLabel={ariaLabel}>
+  <IconComponent />
+</StyledRoot>
+
+// Decorative (omit label):
+<StyledRoot accessible={false}>
+  <IconComponent />
+</StyledRoot>
+```
+
+### **5. Interactive States**
+
+React Native does not have CSS pseudo-classes. Handle states in the component body or via `Pressable`'s style callback:
+
+```tsx
+// Approach 1: Pressable style callback
+<Pressable
+  disabled={disabled}
+  style={({ pressed }) => [
+    styles.base,
+    pressed && styles.pressed,
+    disabled && styles.disabled
+  ]}
+>
+
+// Approach 2: Styled component with state props
+const StyledButton = styled(Pressable)<{
+  isPressed: boolean
+  isDisabled: boolean
+}>(({ theme, isPressed, isDisabled }) => ({
+  backgroundColor: isDisabled
+    ? tokens.colour.disabled
+    : isPressed
+      ? tokens.colour.pressed
+      : tokens.colour.default,
+  opacity: isDisabled ? 0.5 : 1
+}))
+
+// Approach 3: useTheme + inline style for dynamic values
+const Button = ({ disabled, ...rest }) => {
+  const theme = useTheme()
+  const tokens = theme.tokens.components.buttons.button
+
+  return (
+    <Pressable
+      disabled={disabled}
+      style={({ pressed }) => ({
+        backgroundColor: disabled
+          ? tokens.colour.background.disabled
+          : pressed
+            ? tokens.colour.background.pressed
+            : tokens.colour.background.default
+      })}
+      {...rest}
+    />
+  )
+}
+```
+
+### **6. Storybook Stories**
+
+**File location:** `[ComponentName].stories.tsx` (co-located with component)
+
+```tsx
+import React from "react"
+import { View, StyleSheet } from "react-native"
+import { [Component] } from "./[Component]"
+import type { [Component]Props } from "./[Component]"
+
+export default {
+  title: "Atoms/[Component]",  // or Molecules/ based on type
+  component: [Component],
+  argTypes: {
+    variant: {
+      control: { type: "select" },
+      options: ["default", "alt"],
+      description: "Visual style variant"
+    },
+    disabled: {
+      control: { type: "boolean" },
+      description: "Prevents interaction"
+    }
+  }
+}
+
+// Interactive playground with controls
+export const Playground = (args: [Component]Props) => <[Component] {...args} />
+Playground.args = {
+  variant: "default",
+  disabled: false
+}
+
+// Showcase all variants
+export const AllVariants = () => (
+  <View style={styles.column}>
+    {variants.map((variant) => (
+      <[Component] key={variant} variant={variant}>
+        {variant}
+      </[Component]>
+    ))}
+  </View>
+)
+
+const styles = StyleSheet.create({
+  column: { flexDirection: "column", gap: 16 }
+})
+```
+
+**Story essentials:**
+
+- `Playground` — interactive story with args for every controllable prop
+- `AllVariants` — visual catalogue of every variant/size combination
+- `argTypes` — every prop must have a `description` field for the controls panel
+- Use `StyleSheet.create` for story layout styles (not inline objects)
+
+### **7. File Structure**
+
+```
+packages/pawprint-native/src/components/atoms/[ComponentName]/
+├── [ComponentName].tsx          # Main component
+├── [ComponentName].stories.tsx  # Storybook stories (co-located)
+└── index.ts                     # Exports
+```
+
+**index.ts:**
+
+```tsx
+export { [Component] } from "./[Component]"
+export type { [Component]Props } from "./[Component]"
+```
+
+**Update barrel exports through the chain:**
+
+```
+atoms/[ComponentName]/index.ts  →  atoms/index.ts  →  components/index.ts  →  src/index.ts
+```
+
+---
+
+## Advanced Best Practices
+
+### **8. Styling: @emotion/native vs StyleSheet**
+
+**Use `@emotion/native` `styled()` for token-driven component styles:**
+
+```tsx
+// ✅ GOOD: Styled component with theme access
+const StyledBadge = styled(View)<{ badgeVariant: string }>(
+  ({ theme, badgeVariant }) => ({
+    backgroundColor:
+      theme.tokens.components.badges.badge.colour.background[badgeVariant],
+    borderRadius: parseTokenValue(
+      theme.tokens.components.badges.badge.primary.borderRadius.default
+    )
+  })
+)
+```
+
+**Use `StyleSheet.create` for static layout styles in stories and wrappers:**
+
+```tsx
+// ✅ GOOD: Static layout styles
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", gap: 12, alignItems: "center" },
+  column: { flexDirection: "column", gap: 24 }
+})
+```
+
+**Avoid inline style objects on hot paths** — they create new references on every render.
+
+### **9. Prop Naming for Styled Components**
+
+Emotion native forwards all props to the underlying RN component. To prevent clashes with native props, prefix internal styling props:
+
+```tsx
+// ✅ GOOD: Prefixed prop names avoid clashing with native View/Pressable props
+const StyledBadge = styled(View)<{
+  badgeVariant: BadgeVariant   // not "variant" (could clash)
+  badgeSize: BadgeSize         // not "size" (clashes with Image)
+  pinned: boolean              // safe — not a native prop
+}>((props) => ({ /* ... */ }))
+
+// Then in the component:
+<StyledBadge badgeVariant={variant} badgeSize={size} pinned={pinned} />
+```
+
+### **10. Controlled & Uncontrolled Components**
+
+Many native components support both modes. Use a discriminated union or simple optional props:
+
+```tsx
+type SwitchProps = {
+  checked?: boolean // controlled
+  defaultChecked?: boolean // uncontrolled (default: false)
+  onCheckedChange?: (checked: boolean) => void // callback
+  disabled?: boolean
+}
+
+const Switch = React.forwardRef<View, SwitchProps>(
+  ({ checked, defaultChecked = false, onCheckedChange, ...rest }, ref) => {
+    // Internal state for uncontrolled mode
+    const [internalChecked, setInternalChecked] = React.useState(defaultChecked)
+    const isControlled = checked !== undefined
+    const isChecked = isControlled ? checked : internalChecked
+
+    const handleChange = (value: boolean) => {
+      if (!isControlled) setInternalChecked(value)
+      onCheckedChange?.(value)
+    }
+
+    return /* ... */
+  }
+)
+```
+
+### **11. Compound Components Pattern**
+
+Use for complex components with multiple related sub-components:
+
+```tsx
+// Input compound component
+const InputRoot = styled(View)(({ theme }) => ({ /* ... */ }))
+const InputLabel = ({ children }) => <Typography>{children}</Typography>
+const InputField = React.forwardRef<TextInput, InputFieldProps>((props, ref) => /* ... */)
+const InputDescription = ({ children }) => <Typography>{children}</Typography>
+const InputError = ({ children }) => <Typography>{children}</Typography>
+
+// Attach sub-components
+const Input = Object.assign(
+  React.forwardRef<TextInput, InputProps>((props, ref) => /* simple API */),
+  {
+    Root: InputRoot,
+    Label: InputLabel,
+    Field: InputField,
+    Description: InputDescription,
+    Error: InputError
+  }
+)
+
+// Usage — simple API:
+<Input label="Email" placeholder="you@example.com" />
+
+// Usage — compound API:
+<Input.Root>
+  <Input.Label>Email</Input.Label>
+  <Input.Field placeholder="you@example.com" />
+  <Input.Description>We'll never share this</Input.Description>
+</Input.Root>
+```
+
+### **12. Typography via the Typography Component**
+
+Never use raw `<Text>` in components — always use the `Typography` component for token-driven text:
+
+```tsx
+// ✅ GOOD: Token-driven text
+<Typography variant="body" size="md" color="primary">
+  Hello world
+</Typography>
+
+// ✅ GOOD: Component-owned text via token mode
+<Typography token={tokens.typography.medium.default} color={tokens.colour.text.primary}>
+  Badge label
+</Typography>
+
+// ❌ BAD: Raw Text with manual styles
+<Text style={{ fontSize: 14, fontFamily: "IBMPlexSansCondensed-Medium" }}>
+  Hello world
+</Text>
+```
+
+### **13. Icons & Illustrations**
+
+Icons and illustrations come from shared packages with platform-specific builds:
+
+```tsx
+// Icons — used via the Icon wrapper component
+import { Icon } from "../Icon"
+import type { PawprintIcon } from "../Icon"
+
+type MyComponentProps = {
+  icon?: PawprintIcon // component from @butternutbox/pawprint-icons
+}
+
+// Inside JSX:
+{
+  icon && (
+    <Icon
+      icon={icon}
+      size={iconSizeMap[size]}
+      colour={iconColourMap[variant]}
+    />
+  )
+}
+
+// Illustrations — used via the Illustration wrapper
+import { Illustration } from "../Illustration"
+import type { PawprintIllustration } from "../Illustration"
+
+{
+  illustration && <Illustration illustration={illustration} size="sm" />
+}
+```
+
+**Key differences from web:**
+
+- Icons use `react-native-svg` under the hood (auto-resolved via package exports)
+- Import paths are the same: `@butternutbox/pawprint-icons/core` — Metro resolves the `.native.js` build automatically
+- No `fill="currentColor"` — native icons receive `color` as a prop
+
+### **14. Performance Considerations**
+
+```tsx
+// ✅ GOOD: Stable style references
+const StyledButton = styled(Pressable)(({ theme }) => ({
+  // Computed once per theme change
+}))
+
+// ❌ BAD: Inline style objects on every render
+<View style={{ padding: parseTokenValue(tokens.spacing.md) }} />
+
+// ✅ GOOD: Memoize expensive lookups
+const styles = useMemo(() => ({
+  container: { backgroundColor: tokens.colour.background.default }
+}), [tokens])
+
+// ✅ GOOD: Use Animated API for animations, not state re-renders
+const opacity = useRef(new Animated.Value(0)).current
+```
+
+**Performance Tips:**
+
+- Use `StyleSheet.create` for static styles
+- Use `styled()` for theme-dependent styles
+- Avoid anonymous functions in `style` props on lists
+- Use `React.memo` sparingly — only for expensive renders with stable props
+- Use `Animated` or `Reanimated` for animations, not `setState`
+
+### **15. Error Handling & Validation**
+
+```tsx
+export const Icon = React.forwardRef<View, IconProps>(
+  ({ icon: IconComponent, "aria-label": ariaLabel, ...rest }, ref) => {
+    // Dev-mode accessibility warning
+    if (process.env.NODE_ENV === "development" && !ariaLabel) {
+      console.warn(
+        "Icon: Consider providing an aria-label for meaningful icons. " +
+          "Omit intentionally for decorative icons only."
+      )
+    }
+
+    return (
+      <StyledRoot
+        ref={ref}
+        accessibilityRole={ariaLabel ? "image" : undefined}
+        accessibilityLabel={ariaLabel}
+        accessible={!!ariaLabel}
+        {...rest}
+      >
+        <IconComponent width={dimension} height={dimension} color={color} />
+      </StyledRoot>
+    )
+  }
+)
+```
+
+### **16. Parity with pawprint-web**
+
+Native components should mirror the web API where possible:
+
+- **Same prop names** — `variant`, `size`, `colour`, `disabled`, `loading`, `icon`
+- **Same variants** — `"filled" | "outlined" | "text"` for Button on both platforms
+- **Same tokens** — read from the same `theme.tokens.components` structure
+- **Same sizes** — `"sm" | "md" | "lg"` etc.
+
+**Document platform differences** when the APIs must diverge:
+
+- Web uses `string | number` for positioning (`top`, `bottom`) — native uses `number` only
+- Web has CSS pseudo-classes (`:hover`, `:focus-visible`) — native uses `Pressable` callbacks
+- Web uses `styled()` from `@mui/system` — native uses `styled()` from `@emotion/native`
+- Web has `shouldForwardProp` — native relies on prop name prefixing
+
+### **17. Documentation Standards**
+
+**Add JSDoc comments for all exported components:**
+
+````tsx
+/**
+ * Brief description of what the component does.
+ *
+ * @param {"variant1" | "variant2"} [variant="variant1"] - Visual style variant.
+ * @param {"sm" | "md" | "lg"} [size="md"] - Size of the component.
+ * @param {boolean} [disabled=false] - Prevents interaction.
+ * @param {React.ReactNode} children - Component content.
+ *
+ * @example
+ * ```tsx
+ * import { Component } from "@butternutbox/pawprint-native"
+ *
+ * <Component variant="default" size="md">Content</Component>
+ * ```
+ */
+export const Component = React.forwardRef<View, ComponentProps>(
+  (props, ref) => {
+    // Implementation
+  }
+)
+````
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ **Don't use raw `<Text>`** — always use `Typography` for token-driven text
+❌ **Don't hardcode colours or sizes** — always use design tokens
+❌ **Don't skip `forwardRef`** — breaks ref forwarding
+❌ **Don't use `TouchableOpacity`** — use `Pressable` instead
+❌ **Don't forget `displayName`** — helps with debugging
+❌ **Don't use inline style objects in loops** — creates new references per render
+❌ **Don't skip `accessibilityRole`** — required for screen readers
+❌ **Don't skip TypeScript types** — maintain type safety
+❌ **Don't use `StyleSheet.create` for theme-dependent styles** — use `styled()` instead
+
+---
+
+## Quick Reference: Architecture Decision Tree
+
+- **Same behaviour + different styles** → Use variants (e.g., Button with filled/outlined/text)
+- **Different behaviour** → Create separate components (e.g., Button vs IconButton)
+- **Multiple related sub-components** → Use compound pattern (e.g., Input.Root, Input.Field)
+- **Accessible primitive exists** → Use `@rn-primitives/*` as foundation
+- **No primitive available** → Build custom with `Pressable` + accessibility props
+- **Controlled + uncontrolled** → Support both with internal state fallback

package/README.md

@@ -0,0 +1,72 @@
+# @butternutbox/pawprint-native
+
+ButternutBox Pawprint Design System - React Native Components
+
+## Installation
+
+```bash
+yarn add @butternutbox/pawprint-native
+```
+
+## Usage
+
+### Theme Provider
+
+Wrap your app with the `PawprintProvider`:
+
+```tsx
+import { PawprintProvider } from "@butternutbox/pawprint-native"
+
+function App() {
+  return <PawprintProvider>{/* Your app */}</PawprintProvider>
+}
+```
+
+### Using Tokens
+
+Access design tokens via the `usePawprint` hook:
+
+```tsx
+import { usePawprint } from "@butternutbox/pawprint-native"
+
+function MyComponent() {
+  const tokens = usePawprint()
+
+  // Access tokens
+  const buttonColor =
+    tokens.components.buttons.filledButton.colour.background.primary.default
+
+  return <View />
+}
+```
+
+### Styled Components
+
+Use the `styled` utility for creating styled React Native components:
+
+```tsx
+import { styled } from "@butternutbox/pawprint-native"
+import { View } from "react-native"
+
+const StyledView = styled(View)(({ theme }) => ({
+  backgroundColor:
+    theme.components.buttons.filledButton.colour.background.primary.default,
+  padding: 16
+}))
+```
+
+## Development
+
+```bash
+# Build the package
+yarn build
+
+# Watch mode
+yarn dev
+
+# Type check
+yarn type:check
+
+# Lint
+yarn lint:check
+```