@erquhart/heroui-native 1.0.0-beta.10.1

package/src/styles/theme.md

@@ -0,0 +1,423 @@
+# Theming
+
+HeroUI Native uses a powerful theming system built on top of [Uniwind](https://docs.uniwind.dev), providing extensive customization options while maintaining consistency across light and dark modes.
+
+## Setup
+
+### 1. Set Up Uniwind
+
+Follow the [Uniwind installation guide](https://docs.uniwind.dev/quickstart) to set up Tailwind CSS for React Native.
+
+If you're migrating from NativeWind, see the [migration guide](https://docs.uniwind.dev/migration-from-nativewind).
+
+### 2. Configure global.css
+
+Inside your `global.css` file add the following imports:
+
+```css
+@import 'tailwindcss';
+@import 'uniwind';
+
+@import 'heroui-native/styles';
+
+// Path to the heroui-native lib inside node_modules from the root of your project
+@source './node_modules/heroui-native/lib';
+```
+
+## Theme Structure
+
+The HeroUI Native theme system is built on two layers of CSS variables:
+
+### Base Variables
+
+Base variables are defined in [variables.css](./variables.css) and serve as the foundation for the theme. These variables change between light and dark modes and are the source from which all other theme colors are calculated.
+
+#### Primitive Colors (constant across themes)
+
+```css
+--white: oklch(100% 0 0);
+--black: oklch(0% 0 0);
+--snow: oklch(0.9911 0 0);
+--eclipse: oklch(0.2103 0.0059 285.89);
+```
+
+#### Base Radius
+
+```css
+--radius: 0.5rem; /* Default base radius */
+```
+
+#### Opacity
+
+```css
+--opacity-disabled: 0.5;
+```
+
+#### Theme-Specific Base Colors
+
+**Light Mode:**
+
+- `--background`: Background color for the app
+- `--foreground`: Primary text color
+- `--surface`: Background for non-overlay components (cards, accordions)
+- `--surface-foreground`: Text color on surface
+- `--overlay`: Background for floating/overlay components (dialogs, popovers, modals)
+- `--overlay-foreground`: Text color on overlay
+- `--muted`: Muted text color
+- `--default`: Default component background
+- `--default-foreground`: Default component text
+- `--accent`: Accent/primary color
+- `--accent-foreground`: Text on accent color
+
+**Dark Mode:**
+Same variables as light mode but with adjusted values optimized for dark backgrounds. Notably, `--overlay` is lighter than `--surface` in dark mode to provide better contrast for floating components.
+
+#### Status Colors
+
+- `--success`: Success state color
+- `--success-foreground`: Text on success
+- `--warning`: Warning state color
+- `--warning-foreground`: Text on warning
+- `--danger`: Danger/error state color
+- `--danger-foreground`: Text on danger
+
+#### Form Field Base Colors
+
+- `--field-background`: Form input background
+- `--field-foreground`: Form input text
+- `--field-placeholder`: Placeholder text
+- `--field-border`: Form input border (transparent by default)
+
+#### Miscellaneous Colors
+
+- `--border`: Border color (transparent by default)
+- `--divider`: Divider line color
+- `--link`: Link text color
+
+### Calculated Variables
+
+Calculated variables are defined in [theme.css](./theme.css) and are automatically derived from base variables using `color-mix()` functions. These provide consistent variations without manual definition.
+
+#### Color Tokens
+
+All base colors are exposed as `--color-*` tokens:
+
+```css
+--color-background
+--color-foreground
+--color-surface
+--color-accent
+--color-default
+--color-danger
+/* ... and many more */
+```
+
+#### Background Shades
+
+Progressive background variations for layering:
+
+```css
+--color-background-secondary    /* 96% background, 4% foreground */
+--color-background-tertiary     /* 92% background, 8% foreground */
+--color-background-quaternary   /* 86% background, 14% foreground */
+```
+
+#### Hover States
+
+Automatically calculated hover states for all color variants:
+
+```css
+--color-default-hover
+--color-accent-hover
+--color-success-hover
+--color-warning-hover
+--color-danger-hover
+```
+
+#### Soft Colors
+
+Translucent versions (15% opacity) with hover states:
+
+```css
+--color-accent-soft              /* 15% accent */
+--color-accent-soft-foreground
+--color-accent-soft-hover        /* 20% accent */
+--color-danger-soft
+--color-warning-soft
+--color-success-soft
+```
+
+#### Surface Levels
+
+Progressive surface shades for nested components:
+
+```css
+--color-surface-secondary
+--color-surface-tertiary
+--color-surface-quaternary
+--color-on-surface
+--color-on-surface-hover
+```
+
+#### Form Field Tokens
+
+```css
+--color-field
+--color-field-hover
+--color-field-focus
+--color-field-foreground
+--color-field-placeholder
+--color-field-border
+--color-field-border-hover
+--color-field-border-focus
+--radius-field
+--border-width-field
+```
+
+#### Radius Tokens
+
+Calculated from base `--radius` for consistency:
+
+```css
+--radius-xs     /* radius * 0.25 = 0.125rem (2px) */
+--radius-sm     /* radius * 0.5  = 0.25rem (4px) */
+--radius-md     /* radius * 0.75 = 0.375rem (6px) */
+--radius-lg     /* radius * 1    = 0.5rem (8px) */
+--radius-xl     /* radius * 1.5  = 0.75rem (12px) */
+--radius-2xl    /* radius * 2    = 1rem (16px) */
+--radius-3xl    /* radius * 3    = 1.5rem (24px) */
+--radius-4xl    /* radius * 4    = 2rem (32px) */
+```
+
+## Customization
+
+HeroUI Native supports extensive theming customization through Uniwind's theming system.
+
+### Custom Colors
+
+You can override any theme variable to customize colors:
+
+```css
+@layer theme {
+  @variant light {
+    --accent: oklch(0.65 0.25 270); /* Custom purple accent */
+    --background: oklch(0.98 0 0); /* Custom background */
+  }
+
+  @variant dark {
+    --accent: oklch(0.65 0.25 270);
+    --background: oklch(0.15 0 0);
+  }
+}
+```
+
+### Custom Themes
+
+Create multiple themes using Uniwind's variant system:
+
+```css
+@layer theme {
+  :root {
+    @variant ocean {
+      --accent: oklch(0.6 0.2 230);
+      --background: oklch(0.95 0.02 230);
+    }
+
+    @variant forest {
+      --accent: oklch(0.65 0.18 150);
+      --background: oklch(0.96 0.01 150);
+    }
+  }
+}
+```
+
+**Important:** When adding custom themes, you must register them in your Metro config:
+
+```js
+module.exports = withUniwindConfig(wrapWithReanimatedMetroConfig(config), {
+  cssEntryFile: './global.css',
+  dtsFile: './src/uniwind.d.ts',
+  extraThemes: [
+    'ocean',
+    'forest',
+    'lavender-light',
+    'lavender-dark',
+    'mint-light',
+    'mint-dark',
+    'sky-light',
+    'sky-dark',
+  ],
+});
+```
+
+Apply themes in your app:
+
+```tsx
+import { Uniwind } from 'uniwind';
+
+function App() {
+  return <Button onPress={() => Uniwind.setTheme('ocean')}>Ocean Theme</Button>;
+}
+```
+
+For complete custom theme documentation, see [Uniwind Custom Themes Guide](https://docs.uniwind.dev/theming/custom-themes).
+
+> **Note:** If you need the color scheme from the alpha version of HeroUI Native, you can find it in [example/themes/alpha.css](../../example/themes/alpha.css).
+
+### Radius Customization
+
+Change the global border radius scale:
+
+```css
+@theme {
+  --radius: 0.75rem; /* Increase for rounder components */
+}
+```
+
+All radius tokens (`--radius-xs` through `--radius-4xl`) automatically scale accordingly.
+
+### Advanced Customization
+
+For comprehensive theming capabilities, refer to the [Uniwind theming documentation](https://docs.uniwind.dev/theming/basics):
+
+- Creating multiple color schemes
+- Custom design tokens
+- Theme inheritance
+- Dynamic theme switching
+- Per-component theme overrides
+
+## Custom Fonts
+
+To use a custom font family in your app, override the font CSS variables:
+
+```css
+@theme {
+  --font-normal: 'YourFont-Regular';
+  --font-medium: 'YourFont-Medium';
+  --font-semibold: 'YourFont-SemiBold';
+}
+```
+
+All HeroUI Native components automatically use these font variables, ensuring consistent typography throughout your app.
+
+**Note:** Make sure your custom fonts are properly loaded in your React Native app before applying these variables. See [React Native font documentation](https://reactnative.dev/docs/text#limited-style-inheritance) for loading custom fonts.
+
+## Utilities
+
+### useThemeColor Hook
+
+Retrieves theme color values from CSS variables. Supports both single color and multiple colors for efficient batch retrieval.
+
+**Single color usage:**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const accentColor = useThemeColor('accent');
+  const dangerColor = useThemeColor('danger');
+
+  return (
+    <View style={{ borderColor: accentColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```
+
+**Multiple colors usage (more efficient):**
+
+```tsx
+import { useThemeColor } from 'heroui-native';
+
+function MyComponent() {
+  const [accentColor, backgroundColor, dangerColor] = useThemeColor([
+    'accent',
+    'background',
+    'danger',
+  ]);
+
+  return (
+    <View style={{ borderColor: accentColor, backgroundColor }}>
+      <Text style={{ color: dangerColor }}>Error message</Text>
+    </View>
+  );
+}
+```
+
+**Source:** [use-theme-color.ts](../helpers/theme/hooks/use-theme-color.ts)
+
+**Type signatures:**
+
+```tsx
+// Single color
+useThemeColor(themeColor: ThemeColor): string
+
+// Multiple colors (with type inference for tuples)
+useThemeColor<T extends readonly [ThemeColor, ...ThemeColor[]]>(
+  themeColor: T
+): CreateStringTuple<T['length']>
+
+// Multiple colors (array)
+useThemeColor(themeColor: ThemeColor[]): string[]
+```
+
+Available theme colors include: `background`, `foreground`, `surface`, `accent`, `default`, `success`, `warning`, `danger`, and all their variants (hover, soft, foreground, etc.), plus semantic colors like `muted`, `border`, `divider`, `field`, `overlay`, and more.
+
+### cn Utility
+
+The `cn` utility function merges Tailwind CSS classes with proper conflict resolution:
+
+```tsx
+import { cn } from 'heroui-native';
+
+function MyComponent({ className }) {
+  return (
+    <View
+      className={cn(
+        'bg-background p-4 rounded-lg',
+        'border border-divider',
+        className
+      )}
+    />
+  );
+}
+```
+
+**Source:** [cn.ts](../helpers/theme/utils/cn.ts)
+
+The `cn` utility is powered by `tailwind-variants` and includes:
+
+- Automatic Tailwind class merging (`twMerge: true`)
+- Custom opacity class group support
+- Proper conflict resolution (later classes override earlier ones)
+
+**Example with conflicts:**
+
+```tsx
+// 'bg-accent' overrides 'bg-background'
+cn('bg-background p-4', 'bg-accent');
+// Result: 'p-4 bg-accent'
+```
+
+## Dark Mode
+
+HeroUI Native automatically supports dark mode through Uniwind. The theme switches between light and dark variants based on the system or manual selection:
+
+```tsx
+import { Uniwind, useUniwind } from 'uniwind';
+
+function ThemeToggle() {
+  const { theme } = useUniwind();
+
+  return (
+    <Button
+      onPress={() => Uniwind.setTheme(theme === 'light' ? 'dark' : 'light')}
+    >
+      Toggle {theme === 'light' ? 'Dark' : 'Light'} Mode
+    </Button>
+  );
+}
+```
+
+All theme variables automatically adjust based on the active color scheme.

package/src/styles/utilities.css

@@ -0,0 +1,8 @@
+@layer utilities {
+  .h-hairline {
+    height: hairlineWidth();
+  }
+  .w-hairline {
+    width: hairlineWidth();
+  }
+}

package/src/styles/variables.css

@@ -0,0 +1,113 @@
+@theme {
+  /* Primitive Colors (Do not change between light and dark) */
+  --white: oklch(100% 0 0);
+  --black: oklch(0% 0 0);
+  --snow: oklch(0.9911 0 0);
+  --eclipse: oklch(0.2103 0.0059 285.89);
+
+  /* Base radius */
+  --radius: 0.5rem;
+
+  /* Opacity */
+  --opacity-disabled: 0.5;
+}
+
+@layer theme {
+  :root {
+    @variant light {
+      /* Base Colors */
+      --background: oklch(0.9702 0 0);
+      --foreground: var(--eclipse);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: var(--white);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
+      --overlay: var(--white);
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(55.2% 0.016 285.938);
+
+      --default: oklch(94% 0.001 286.375);
+      --default-foreground: var(--eclipse);
+
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: var(--snow);
+
+      /* Form Field Defaults - Colors */
+      --field-background: var(--white);
+      --field-foreground: oklch(0.2103 0.0059 285.89);
+      --field-placeholder: var(--muted);
+      --field-border: transparent; /* no border by default on form fields */
+
+      /* Status Colors */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.7819 0.1585 72.33);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.6532 0.2328 25.74);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: var(--white);
+      --segment-foreground: var(--eclipse);
+
+      /* Misc Colors */
+      --border: oklch(0 0 0 / 0%);
+      --divider: oklch(72% 0.004 286.32);
+      --link: var(--foreground);
+    }
+
+    @variant dark {
+      /* Base Colors */
+      --background: var(--black);
+      --foreground: var(--snow);
+
+      /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
+      --surface: oklch(0.2103 0.0059 285.89);
+      --surface-foreground: var(--foreground);
+
+      /* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) - lighter for contrast */
+      --overlay: oklch(
+        0.2563 0.0058 271.19
+      ); /* Lighter than surface for visibility in dark mode */
+      --overlay-foreground: var(--foreground);
+
+      --muted: oklch(70.5% 0.015 286.067);
+
+      --default: oklch(27.4% 0.006 286.033);
+      --default-foreground: var(--snow);
+
+      --accent: oklch(0.6204 0.195 253.83);
+      --accent-foreground: var(--snow);
+
+      /* Form Field Defaults - Colors (only the ones that are different from light theme) */
+      --field-background: var(--default);
+      --field-foreground: var(--foreground);
+      --field-placeholder: var(--muted);
+      --field-border: transparent; /* no border by default on form fields */
+
+      /* Status Colors */
+      --success: oklch(0.7329 0.1935 150.81);
+      --success-foreground: var(--eclipse);
+
+      --warning: oklch(0.8203 0.1388 76.34);
+      --warning-foreground: var(--eclipse);
+
+      --danger: oklch(0.594 0.1967 24.63);
+      --danger-foreground: var(--snow);
+
+      /* Component Colors */
+      --segment: oklch(0.3964 0.01 285.93);
+      --segment-foreground: var(--foreground);
+
+      /* Misc Colors */
+      --border: oklch(1 0 0 / 0%);
+      --divider: oklch(38% 0.006 286.033);
+      --link: var(--foreground);
+    }
+  }
+}