@harkenapp/sdk-react-native 0.0.1-alpha.1 → 0.0.1-alpha.2

package/src/theme/types.ts

@@ -1,15 +1,21 @@
 /**
  * Color tokens for Harken SDK theming.
  * All colors support full override by host apps.
+ *
+ * Base tokens are required. Component tokens are optional and fall back to base tokens.
  */
 export interface HarkenColors {
+  // === BASE TOKENS (required) ===
+
   /** Primary brand color for buttons and accents */
   primary: string;
   /** Darker variant of primary for pressed states */
   primaryPressed: string;
-  /** Background color for the feedback form */
+  /** App-level background color */
   background: string;
-  /** Secondary background (cards, inputs) */
+  /** Container/modal surface color (distinct from background) */
+  surface: string;
+  /** @deprecated Use `surface` instead. Kept for backwards compatibility. */
   backgroundSecondary: string;
   /** Primary text color */
   text: string;
@@ -41,6 +47,106 @@ export interface HarkenColors {
   accent2: string;
   /** Accent color 3 (e.g., files option) */
   accent3: string;
+
+  // === COMPONENT TOKENS (optional, fall back to base tokens) ===
+
+  // Category Chips
+  /** Chip background color (falls back to surface) */
+  chipBackground?: string;
+  /** Selected chip background color (falls back to primary) */
+  chipBackgroundSelected?: string;
+  /** Chip border color (falls back to border) */
+  chipBorder?: string;
+  /** Selected chip border color (falls back to primary) */
+  chipBorderSelected?: string;
+  /** Chip text color (falls back to text) */
+  chipText?: string;
+  /** Selected chip text color (falls back to textOnPrimary) */
+  chipTextSelected?: string;
+
+  // Text Input
+  /** Input background color (falls back to surface) */
+  inputBackground?: string;
+  /** Input border color (falls back to border) */
+  inputBorder?: string;
+  /** Input focused border color (falls back to borderFocused) */
+  inputBorderFocused?: string;
+  /** Input error border color (falls back to error) */
+  inputBorderError?: string;
+  /** Input text color (falls back to text) */
+  inputText?: string;
+  /** Input placeholder color (falls back to textPlaceholder) */
+  inputPlaceholder?: string;
+
+  // Buttons - Primary variant
+  /** Primary button background (falls back to primary) */
+  buttonPrimaryBackground?: string;
+  /** Primary button pressed background (falls back to primaryPressed) */
+  buttonPrimaryBackgroundPressed?: string;
+  /** Primary button text color (falls back to textOnPrimary) */
+  buttonPrimaryText?: string;
+
+  // Buttons - Secondary variant
+  /** Secondary button background (falls back to surface) */
+  buttonSecondaryBackground?: string;
+  /** Secondary button border color (falls back to border) */
+  buttonSecondaryBorder?: string;
+  /** Secondary button text color (falls back to text) */
+  buttonSecondaryText?: string;
+
+  // Buttons - Ghost variant
+  /** Ghost button text color (falls back to text) */
+  buttonGhostText?: string;
+
+  // Attachment Add Button
+  /** Add button background (falls back to surface) */
+  addButtonBackground?: string;
+  /** Add button pressed background (falls back to border) */
+  addButtonBackgroundPressed?: string;
+  /** Add button border color (falls back to border) */
+  addButtonBorder?: string;
+  /** Add button icon color (falls back to textSecondary) */
+  addButtonIcon?: string;
+  /** Add button text color (falls back to textSecondary) */
+  addButtonText?: string;
+
+  // Attachment Tile
+  /** Tile background color (falls back to surface) */
+  tileBackground?: string;
+  /** Tile border color (falls back to border) */
+  tileBorder?: string;
+
+  // Upload Status Overlay
+  /** Upload overlay background (falls back to overlay) */
+  uploadOverlay?: string;
+  /** Upload error overlay background (falls back to overlayDark) */
+  uploadOverlayError?: string;
+  /** Upload progress track color */
+  uploadProgressTrack?: string;
+  /** Upload progress fill color (falls back to primary) */
+  uploadProgressFill?: string;
+  /** Upload success badge color (falls back to success) */
+  uploadBadgeSuccess?: string;
+  /** Upload overlay text color (falls back to textOnPrimary) */
+  uploadText?: string;
+
+  // Attachment Picker
+  /** Picker overlay background (falls back to overlay) */
+  pickerOverlay?: string;
+  /** Picker sheet background (falls back to background) */
+  pickerBackground?: string;
+  /** Picker handle color (falls back to textSecondary) */
+  pickerHandle?: string;
+  /** Picker option background (falls back to surface) */
+  pickerOptionBackground?: string;
+  /** Picker option pressed background (falls back to border) */
+  pickerOptionBackgroundPressed?: string;
+  /** Picker cancel text color (falls back to error) */
+  pickerCancelText?: string;
+
+  // Form Container
+  /** Form background color (falls back to transparent for modal embedding) */
+  formBackground?: string;
 }
 
 /**
@@ -80,23 +186,27 @@ export interface HarkenTypography {
 
 /** Font weight values supported across platforms */
 export type TextWeight =
-  | 'normal'
-  | 'bold'
-  | '100'
-  | '200'
-  | '300'
-  | '400'
-  | '500'
-  | '600'
-  | '700'
-  | '800'
-  | '900';
+  | "normal"
+  | "bold"
+  | "100"
+  | "200"
+  | "300"
+  | "400"
+  | "500"
+  | "600"
+  | "700"
+  | "800"
+  | "900";
 
 /**
  * Spacing tokens for consistent layout.
  * All values are in logical pixels.
+ *
+ * Base tokens are required. Component tokens are optional and fall back to base tokens.
  */
 export interface HarkenSpacing {
+  // === BASE TOKENS (required) ===
+
   /** Extra small spacing (4px default) */
   xs: number;
   /** Small spacing (8px default) */
@@ -109,13 +219,38 @@ export interface HarkenSpacing {
   xl: number;
   /** 2x extra large spacing (48px default) */
   xxl: number;
+
+  // === COMPONENT TOKENS (optional, fall back to base tokens) ===
+
+  /** Chip vertical padding (falls back to sm) */
+  chipPaddingVertical?: number;
+  /** Chip horizontal padding (falls back to md) */
+  chipPaddingHorizontal?: number;
+  /** Gap between chips (falls back to sm) */
+  chipGap?: number;
+  /** Input padding (falls back to md) */
+  inputPadding?: number;
+  /** Button vertical padding (falls back to sm) */
+  buttonPaddingVertical?: number;
+  /** Button horizontal padding (falls back to md) */
+  buttonPaddingHorizontal?: number;
+  /** Form container padding (falls back to lg) */
+  formPadding?: number;
+  /** Gap between form sections (falls back to lg) */
+  sectionGap?: number;
+  /** Gap between attachment tiles (falls back to sm) */
+  tileGap?: number;
 }
 
 /**
  * Border radius tokens for rounded corners.
  * All values are in logical pixels.
+ *
+ * Base tokens are required. Component tokens are optional and fall back to base tokens.
  */
 export interface HarkenRadii {
+  // === BASE TOKENS (required) ===
+
   /** No radius */
   none: number;
   /** Small radius for subtle rounding (4px default) */
@@ -128,16 +263,62 @@ export interface HarkenRadii {
   xl: number;
   /** Full/pill radius */
   full: number;
+
+  // === COMPONENT TOKENS (optional, fall back to base tokens) ===
+
+  /** Chip border radius (falls back to full) */
+  chip?: number;
+  /** Input border radius (falls back to md) */
+  input?: number;
+  /** Button border radius (falls back to md) */
+  button?: number;
+  /** Attachment tile border radius (falls back to md) */
+  tile?: number;
+  /** Form container border radius (falls back to lg) */
+  form?: number;
+  /** Picker sheet border radius (falls back to xl) */
+  picker?: number;
+}
+
+/**
+ * Sizing tokens for component dimensions.
+ * All values are in logical pixels and optional with sensible defaults.
+ */
+export interface HarkenSizing {
+  /** Button minimum height (default: 48) */
+  buttonMinHeight?: number;
+  /** Input minimum height (default: 44) */
+  inputMinHeight?: number;
+  /** Attachment tile size (default: 80) */
+  tileSize?: number;
+  /** Add button icon size (default: 28) */
+  addButtonIconSize?: number;
+  /** Picker icon container size (default: 44) */
+  pickerIconSize?: number;
 }
 
 /**
- * Complete theme object combining all token types.
+ * Opacity tokens for interactive states.
+ * All values are between 0 and 1 and optional with sensible defaults.
+ */
+export interface HarkenOpacity {
+  /** Disabled state opacity (default: 0.6) */
+  disabled?: number;
+  /** Pressed state opacity (default: 0.8) */
+  pressed?: number;
+}
+
+/**
+ * Input theme object with optional component tokens.
+ * Used for theme configuration by consumers.
  */
 export interface HarkenTheme {
   colors: HarkenColors;
   typography: HarkenTypography;
   spacing: HarkenSpacing;
   radii: HarkenRadii;
+  sizing?: HarkenSizing;
+  opacity?: HarkenOpacity;
 }
 
 /**
@@ -149,9 +330,266 @@ export type PartialHarkenTheme = {
   typography?: Partial<HarkenTypography>;
   spacing?: Partial<HarkenSpacing>;
   radii?: Partial<HarkenRadii>;
+  sizing?: Partial<HarkenSizing>;
+  opacity?: Partial<HarkenOpacity>;
 };
 
 /**
  * Theme mode for automatic light/dark theming.
  */
-export type ThemeMode = 'light' | 'dark' | 'system';
+export type ThemeMode = "light" | "dark" | "system";
+
+// ============================================================================
+// RESOLVED THEME TYPES
+// These types represent the fully-resolved theme after fallback resolution.
+// Components should use these types - all values are guaranteed to exist.
+// ============================================================================
+
+/**
+ * Fully resolved color tokens with all component tokens populated.
+ * All optional component tokens have been resolved to their fallback values.
+ */
+export interface ResolvedHarkenColors {
+  // Base tokens
+  primary: string;
+  primaryPressed: string;
+  background: string;
+  surface: string;
+  backgroundSecondary: string;
+  text: string;
+  textSecondary: string;
+  textPlaceholder: string;
+  textOnPrimary: string;
+  border: string;
+  borderFocused: string;
+  error: string;
+  success: string;
+  warning: string;
+  info: string;
+  overlay: string;
+  overlayDark: string;
+  accent1: string;
+  accent2: string;
+  accent3: string;
+
+  // Component tokens (all resolved, no longer optional)
+  chipBackground: string;
+  chipBackgroundSelected: string;
+  chipBorder: string;
+  chipBorderSelected: string;
+  chipText: string;
+  chipTextSelected: string;
+
+  inputBackground: string;
+  inputBorder: string;
+  inputBorderFocused: string;
+  inputBorderError: string;
+  inputText: string;
+  inputPlaceholder: string;
+
+  buttonPrimaryBackground: string;
+  buttonPrimaryBackgroundPressed: string;
+  buttonPrimaryText: string;
+  buttonSecondaryBackground: string;
+  buttonSecondaryBorder: string;
+  buttonSecondaryText: string;
+  buttonGhostText: string;
+
+  addButtonBackground: string;
+  addButtonBackgroundPressed: string;
+  addButtonBorder: string;
+  addButtonIcon: string;
+  addButtonText: string;
+
+  tileBackground: string;
+  tileBorder: string;
+
+  uploadOverlay: string;
+  uploadOverlayError: string;
+  uploadProgressTrack: string;
+  uploadProgressFill: string;
+  uploadBadgeSuccess: string;
+  uploadText: string;
+
+  pickerOverlay: string;
+  pickerBackground: string;
+  pickerHandle: string;
+  pickerOptionBackground: string;
+  pickerOptionBackgroundPressed: string;
+  pickerCancelText: string;
+
+  formBackground: string;
+}
+
+/**
+ * Fully resolved spacing tokens with all component tokens populated.
+ */
+export interface ResolvedHarkenSpacing {
+  // Base tokens
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+  xxl: number;
+
+  // Component tokens (all resolved)
+  chipPaddingVertical: number;
+  chipPaddingHorizontal: number;
+  chipGap: number;
+  inputPadding: number;
+  buttonPaddingVertical: number;
+  buttonPaddingHorizontal: number;
+  formPadding: number;
+  sectionGap: number;
+  tileGap: number;
+}
+
+/**
+ * Fully resolved radii tokens with all component tokens populated.
+ */
+export interface ResolvedHarkenRadii {
+  // Base tokens
+  none: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+  full: number;
+
+  // Component tokens (all resolved)
+  chip: number;
+  input: number;
+  button: number;
+  tile: number;
+  form: number;
+  picker: number;
+}
+
+/**
+ * Fully resolved sizing tokens.
+ */
+export interface ResolvedHarkenSizing {
+  buttonMinHeight: number;
+  inputMinHeight: number;
+  tileSize: number;
+  addButtonIconSize: number;
+  pickerIconSize: number;
+}
+
+/**
+ * Fully resolved opacity tokens.
+ */
+export interface ResolvedHarkenOpacity {
+  disabled: number;
+  pressed: number;
+}
+
+/**
+ * Structured component token aliases for better discoverability.
+ * Maps to flat tokens but grouped by component for ergonomic access.
+ */
+export interface HarkenComponentTokens {
+  chip: {
+    background: string;
+    backgroundSelected: string;
+    border: string;
+    borderSelected: string;
+    text: string;
+    textSelected: string;
+    paddingVertical: number;
+    paddingHorizontal: number;
+    gap: number;
+    radius: number;
+  };
+  input: {
+    background: string;
+    border: string;
+    borderFocused: string;
+    borderError: string;
+    text: string;
+    placeholder: string;
+    padding: number;
+    radius: number;
+    minHeight: number;
+  };
+  button: {
+    primary: {
+      background: string;
+      backgroundPressed: string;
+      text: string;
+    };
+    secondary: {
+      background: string;
+      border: string;
+      text: string;
+    };
+    ghost: {
+      text: string;
+    };
+    paddingVertical: number;
+    paddingHorizontal: number;
+    radius: number;
+    minHeight: number;
+  };
+  addButton: {
+    background: string;
+    backgroundPressed: string;
+    border: string;
+    icon: string;
+    text: string;
+    iconSize: number;
+  };
+  tile: {
+    background: string;
+    border: string;
+    radius: number;
+    size: number;
+    gap: number;
+  };
+  upload: {
+    overlay: string;
+    overlayError: string;
+    progressTrack: string;
+    progressFill: string;
+    badgeSuccess: string;
+    text: string;
+  };
+  picker: {
+    overlay: string;
+    background: string;
+    handle: string;
+    optionBackground: string;
+    optionBackgroundPressed: string;
+    cancelText: string;
+    radius: number;
+    iconSize: number;
+  };
+  form: {
+    background: string;
+    padding: number;
+    sectionGap: number;
+    radius: number;
+  };
+}
+
+/**
+ * Fully resolved theme object with all fallbacks applied.
+ * This is what components receive - all values are guaranteed to exist.
+ */
+export interface ResolvedHarkenTheme {
+  /** Flat color tokens (for compatibility) */
+  colors: ResolvedHarkenColors;
+  /** Typography tokens */
+  typography: HarkenTypography;
+  /** Flat spacing tokens (for compatibility) */
+  spacing: ResolvedHarkenSpacing;
+  /** Flat radii tokens (for compatibility) */
+  radii: ResolvedHarkenRadii;
+  /** Sizing tokens */
+  sizing: ResolvedHarkenSizing;
+  /** Opacity tokens */
+  opacity: ResolvedHarkenOpacity;
+  /** Structured component tokens (for discoverability) */
+  components: HarkenComponentTokens;
+}

package/src/types/config.ts

@@ -1,5 +1,5 @@
-import type { PartialHarkenTheme, ThemeMode } from '../theme';
-import type { SecureStorage } from '../storage';
+import type { PartialHarkenTheme, ThemeMode } from "../theme";
+import type { SecureStorage } from "../storage";
 
 /**
  * Configuration options for the Harken SDK.
@@ -88,12 +88,12 @@ export interface HarkenProviderProps {
 /**
  * Feedback category types supported by the API.
  */
-export type FeedbackCategory = 'bug' | 'idea' | 'ux' | 'other';
+export type FeedbackCategory = "bug" | "idea" | "ux" | "other";
 
 /**
  * Platform type for device metadata.
  */
-export type Platform = 'ios' | 'android';
+export type Platform = "ios" | "android";
 
 /**
  * Device metadata collected with feedback submissions.

package/src/types/index.ts

@@ -4,7 +4,7 @@ export type {
   FeedbackCategory,
   Platform,
   DeviceMetadata,
-} from './config.js';
+} from "./config.js";
 
 // Re-export OpenAPI generated types
-export type { components, operations, paths } from './openapi.js';
+export type { components, operations, paths } from "./openapi.js";

package/src/utils/index.ts

@@ -1 +1 @@
-export { generateUUID } from './uuid';
+export { generateUUID } from "./uuid";

package/src/utils/uuid.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import { generateUUID } from "./uuid";
+
+describe("generateUUID", () => {
+  // UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+  // where y is one of [8, 9, a, b]
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+  it("generates valid UUID v4 format", () => {
+    const uuid = generateUUID();
+    expect(uuid).toMatch(uuidV4Regex);
+  });
+
+  it("generates 36-character string with hyphens", () => {
+    const uuid = generateUUID();
+    expect(uuid).toHaveLength(36);
+    expect(uuid.split("-")).toHaveLength(5);
+  });
+
+  it("has version 4 identifier in correct position", () => {
+    const uuid = generateUUID();
+    // The 13th character (index 14, after first two groups) should be '4'
+    expect(uuid[14]).toBe("4");
+  });
+
+  it("has valid variant bits", () => {
+    const uuid = generateUUID();
+    // The 17th character (index 19, after third group) should be 8, 9, a, or b
+    expect(["8", "9", "a", "b"]).toContain(uuid[19]!.toLowerCase());
+  });
+
+  it("uses lowercase hex characters", () => {
+    // Generate multiple to ensure consistent format
+    for (let i = 0; i < 10; i++) {
+      const uuid = generateUUID();
+      const hexPart = uuid.replace(/-/g, "");
+      expect(hexPart).toMatch(/^[0-9a-f]+$/);
+    }
+  });
+
+  describe("with crypto.getRandomValues available", () => {
+    it("uses crypto for randomness", () => {
+      // crypto.getRandomValues is available in Node.js
+      const uuid = generateUUID();
+      expect(uuid).toMatch(uuidV4Regex);
+    });
+  });
+
+  describe("fallback with Math.random", () => {
+    // Note: We can't easily test the Math.random fallback in Node.js
+    // because crypto is a read-only property. The fallback path
+    // is tested implicitly by the fact that our implementation handles
+    // the case where crypto might not exist (React Native older runtimes).
+    //
+    // Instead, we verify the algorithm produces valid UUIDs with any
+    // randomness source by testing the format constraints.
+
+    it("algorithm produces valid version and variant bits", () => {
+      // The UUID generation algorithm sets version=4 and variant=RFC4122
+      // regardless of which random source is used. We verify this by
+      // generating many UUIDs and checking format compliance.
+      for (let i = 0; i < 100; i++) {
+        const uuid = generateUUID();
+        // Version 4 at position 14
+        expect(uuid[14]).toBe("4");
+        // Variant at position 19 is 8, 9, a, or b
+        expect(["8", "9", "a", "b"]).toContain(uuid[19]!.toLowerCase());
+      }
+    });
+  });
+
+  describe("format consistency", () => {
+    it("consistently produces 8-4-4-4-12 format", () => {
+      for (let i = 0; i < 10; i++) {
+        const uuid = generateUUID();
+        const parts = uuid.split("-");
+        expect(parts[0]).toHaveLength(8);
+        expect(parts[1]).toHaveLength(4);
+        expect(parts[2]).toHaveLength(4);
+        expect(parts[3]).toHaveLength(4);
+        expect(parts[4]).toHaveLength(12);
+      }
+    });
+  });
+});

package/src/utils/uuid.ts

@@ -18,10 +18,7 @@ declare const crypto:
  */
 export function generateUUID(): string {
   // Use crypto.getRandomValues if available (React Native has this)
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.getRandomValues === 'function'
-  ) {
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
     return generateUUIDCrypto();
   }
 
@@ -64,8 +61,8 @@ function generateUUIDFallback(): string {
  */
 function formatUUID(bytes: Uint8Array): string {
   const hex = Array.from(bytes)
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
 
   return [
     hex.slice(0, 8),
@@ -73,5 +70,5 @@ function formatUUID(bytes: Uint8Array): string {
     hex.slice(12, 16),
     hex.slice(16, 20),
     hex.slice(20, 32),
-  ].join('-');
+  ].join("-");
 }