@crystin001/theme-settings-lib 1.0.0 → 1.2.0

package/README.md

@@ -1,368 +1,402 @@
-# Theme & Settings Library
-
-A reusable library for theme management, settings, and internationalization that can be shared across multiple React Native applications.
-
-## Features
-
-- 🎨 **Multiple Theme Families** - 8 theme families with light and dark variants
-- 🌍 **Internationalization** - Built-in i18n support with extensible translations
-- 💾 **Persistent Settings** - Theme and language preferences saved automatically
-- ♿ **Accessibility** - WCAG-compliant contrast utilities
-- 🔧 **Type-Safe** - Full TypeScript support with declaration files
-
-## Installation
-
-### Option A: Git Repository (Recommended)
-
-Add to your `package.json`:
-
-```json
-{
-  "dependencies": {
-    "@crystin001/theme-settings-lib": "git+https://github.com/trial-and-code/theme-settings-lib.git"
-  }
-}
-```
-
-Then run `npm install`.
-
-To install a specific version or branch:
-
-```json
-{
-  "dependencies": {
-    "@crystin001/theme-settings-lib": "git+https://github.com/trial-and-code/theme-settings-lib.git#v1.0.0"
-  }
-}
-```
-
-### Option B: Local Package (Monorepo)
-
-If the library is in the same repository:
-
-```json
-{
-  "dependencies": {
-    "@crystin001/theme-settings-lib": "file:../packages/theme-settings-lib"
-  }
-}
-```
-
-### Option C: npm Package (Future)
-
-```bash
-npm install @crystin001/theme-settings-lib
-```
-
-## Usage
-
-### 1. Wrap Your App with SettingsProvider
-
-Wrap your root component with `SettingsProvider` to enable theme and settings management:
-
-```tsx
-// app/_layout.tsx or App.tsx
-import { SettingsProvider } from '@crystin001/theme-settings-lib';
-import { Stack } from 'expo-router';
-
-export default function RootLayout() {
-  return (
-    <SettingsProvider>
-      <Stack>
-        {/* Your app screens */}
-      </Stack>
-    </SettingsProvider>
-  );
-}
-```
-
-### 2. Use Theme Hooks in Your Components
-
-Access theme colors and settings in your components:
-
-```tsx
-import { View, Text, Button } from 'react-native';
-import { useTheme, useSettings } from '@crystin001/theme-settings-lib';
-
-function MyComponent() {
-  const colors = useTheme();
-  const { setThemeFamily } = useSettings();
-
-  return (
-    <View style={{ backgroundColor: colors.background }}>
-      <Text style={{ color: colors.text }}>Hello World</Text>
-      <Button 
-        onPress={() => setThemeFamily('neon-surf')} 
-        title="Change to Neon Surf" 
-      />
-    </View>
-  );
-}
-```
-
-### 3. Use Translations
-
-Access translations using the `useTranslation` hook:
-
-```tsx
-import { Text } from 'react-native';
-import { useTranslation } from '@crystin001/theme-settings-lib';
-
-function MyComponent() {
-  const { t } = useTranslation();
-
-  return (
-    <Text>{t('common.welcome')}</Text>
-  );
-}
-```
-
-### 4. Get Specific Theme Colors
-
-Use `useThemeColor` to get specific colors from the current theme:
-
-```tsx
-import { View, Text } from 'react-native';
-import { useThemeColor } from '@crystin001/theme-settings-lib';
-
-function MyComponent() {
-  const backgroundColor = useThemeColor({}, 'background');
-  const textColor = useThemeColor({}, 'text');
-  const primaryColor = useThemeColor({}, 'primary');
-
-  return (
-    <View style={{ backgroundColor }}>
-      <Text style={{ color: textColor }}>Primary: {primaryColor}</Text>
-    </View>
-  );
-}
-```
-
-### 5. Extend Translations
-
-Add app-specific translations by extending the i18n instance:
-
-```tsx
-import { i18n } from '@crystin001/theme-settings-lib';
-
-// Add custom translations
-i18n.addResourceBundle('en-US', 'translation', {
-  myFeature: {
-    title: 'My Feature',
-    description: 'This is my feature',
-  },
-}, true, true);
-```
-
-### 6. Complete Example: Integration with React Navigation
-
-Here's a complete example showing integration with React Navigation:
-
-```tsx
-// app/_layout.tsx
-import { Stack } from 'expo-router';
-import { StatusBar } from 'expo-status-bar';
-import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
-import { SettingsProvider, useSettings } from '@crystin001/theme-settings-lib';
-
-function RootLayoutNav() {
-  const { currentTheme } = useSettings();
-  const isDarkTheme = currentTheme.endsWith('-dark');
-
-  return (
-    <ThemeProvider value={isDarkTheme ? DarkTheme : DefaultTheme}>
-      <Stack>
-        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
-      </Stack>
-      <StatusBar style={isDarkTheme ? 'light' : 'dark'} />
-    </ThemeProvider>
-  );
-}
-
-export default function RootLayout() {
-  return (
-    <SettingsProvider>
-      <RootLayoutNav />
-    </SettingsProvider>
-  );
-}
-```
-
-## Available Theme Families
-
-- **System** - Follows device theme preference (default)
-- **Neon Surf** - Vibrant neon colors (hot pink, cyan, yellow, orange)
-- **Pink & Purple** - Soft purple and pink tones
-- **Pastel** - Gentle pastel colors
-- **GitHub** - GitHub-inspired theme
-- **High Contrast** - Maximum contrast for accessibility
-- **Solarized** - Solarized color scheme
-- **Dark Plus** - Dark theme with blue accents
-
-Each theme family has both light and dark variants that automatically switch based on device settings.
-
-## API Reference
-
-### Hooks
-
-#### `useTheme()`
-
-Returns all colors from the current theme.
-
-```tsx
-const colors = useTheme();
-// Returns: { text, background, tint, icon, ... }
-```
-
-#### `useThemeColor(props?, colorName?)`
-
-Get a specific color from the current theme.
-
-```tsx
-const backgroundColor = useThemeColor({}, 'background');
-const textColor = useThemeColor({ light: '#000', dark: '#fff' }, 'text');
-```
-
-#### `useSettings()`
-
-Access theme and language settings.
-
-```tsx
-const {
-  selectedThemeFamily,
-  currentTheme,
-  setThemeFamily,
-  language,
-  setLanguage,
-  availableThemeFamilies,
-  availableLanguages
-} = useSettings();
-```
-
-#### `useTranslation()`
-
-Get the translation function.
-
-```tsx
-const { t } = useTranslation();
-const welcomeText = t('common.welcome');
-```
-
-### Settings Context
-
-The `useSettings()` hook returns:
-
-- `selectedThemeFamily` - Currently selected theme family (e.g., `'neon-surf'`)
-- `currentTheme` - Effective theme being used (includes variant, e.g., `'neon-surf-light'`)
-- `setThemeFamily(family)` - Change theme family
-- `language` - Current language code (e.g., `'en-US'`)
-- `setLanguage(lang)` - Change language
-- `availableThemeFamilies` - Array of all available theme families with metadata
-- `availableLanguages` - Array of all available languages
-
-### Color Utilities
-
-#### `getContrastRatio(color1, color2)`
-
-Calculate the contrast ratio between two colors (returns 1-21).
-
-```tsx
-import { getContrastRatio } from '@crystin001/theme-settings-lib';
-
-const ratio = getContrastRatio('#000000', '#FFFFFF'); // Returns ~21
-```
-
-#### `getContrastTextColor(backgroundColor, lightColor?, darkColor?, minContrast?)`
-
-Get a readable text color for a given background.
-
-```tsx
-import { getContrastTextColor } from '@crystin001/theme-settings-lib';
-
-const textColor = getContrastTextColor('#000000'); // Returns '#FFFFFF'
-```
-
-#### `meetsContrastRequirement(foreground, background, level?)`
-
-Check if a color combination meets WCAG contrast requirements.
-
-```tsx
-import { meetsContrastRequirement } from '@crystin001/theme-settings-lib';
-
-const isAccessible = meetsContrastRequirement('#000000', '#FFFFFF', 'AA'); // Returns true
-```
-
-#### `ensureContrast(foreground, background, level?)`
-
-Ensure a color combination has readable contrast, adjusting if needed.
-
-```tsx
-import { ensureContrast } from '@crystin001/theme-settings-lib';
-
-const readableColor = ensureContrast('#888888', '#FFFFFF', 'AA');
-```
-
-## Development
-
-### Building the Library
-
-```bash
-npm run build
-```
-
-This compiles TypeScript to JavaScript and generates type declaration files in the `dist/` folder.
-
-### Project Structure
-
-```
-theme-settings-lib/
-├── src/
-│   ├── hooks/          # React hooks
-│   ├── theme.ts        # Theme definitions
-│   ├── i18n.ts         # Internationalization setup
-│   ├── settings-context.tsx  # Settings provider
-│   ├── color-utils.ts  # Color utility functions
-│   └── index.ts        # Main exports
-├── dist/               # Compiled output (generated)
-├── package.json
-└── tsconfig.json
-```
-
-## Updating the Library
-
-To update themes or translations across all apps:
-
-1. Make changes in `src/` directory
-2. Run `npm run build` to compile
-3. Update the version in `package.json`
-4. Commit and push to the repository
-5. In each app, update the dependency version and run `npm install`
-6. Apps will automatically get the latest themes and translations
-
-## Versioning
-
-The library follows [Semantic Versioning](https://semver.org/):
-
-- **Major** (x.0.0) - Breaking API changes
-- **Minor** (0.x.0) - New themes, features, or languages
-- **Patch** (0.0.x) - Bug fixes and theme adjustments
-
-## Peer Dependencies
-
-This library requires the following peer dependencies (installed by your app):
-
-- `react` - React library
-- `react-native` - React Native framework
-- `i18next` - Internationalization framework
-- `react-i18next` - React bindings for i18next
-- `expo-localization` - Expo localization utilities
-- `@react-native-async-storage/async-storage` - Async storage for persistence
-- `color` (optional) - Color manipulation library
-
-## License
-
-MIT
-
-## Repository
-
-[https://github.com/trial-and-code/theme-settings-lib](https://github.com/trial-and-code/theme-settings-lib)
+# Theme & Settings Library
+
+A reusable library for theme management, settings, and internationalization that can be shared across multiple React Native applications.
+
+## Features
+
+- 🎨 **Multiple Theme Families** - 8 theme families with light and dark variants
+- 🌍 **Internationalization** - Built-in i18n support with extensible translations
+- 💾 **Persistent Settings** - Theme and language preferences saved automatically
+- ♿ **Accessibility** - WCAG-compliant contrast utilities
+- 🔧 **Type-Safe** - Full TypeScript support with declaration files
+
+## Installation
+
+### Option A: Git Repository (Recommended)
+
+Add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@crystin001/theme-settings-lib": "git+https://github.com/trial-and-code/theme-settings-lib.git"
+  }
+}
+```
+
+Then run `npm install`. The library will automatically build during installation.
+
+**Note:** The library requires TypeScript to build. It will be installed automatically as a dev dependency and the build will run during `npm install`.
+
+To install a specific version or branch:
+
+```json
+{
+  "dependencies": {
+    "@crystin001/theme-settings-lib": "git+https://github.com/trial-and-code/theme-settings-lib.git#v1.0.0"
+  }
+}
+```
+
+### Option B: Local Package (Development)
+
+For local development, you can use a file path to link the library directly:
+
+```json
+{
+  "dependencies": {
+    "@crystin001/theme-settings-lib": "file:../theme-settings-lib"
+  }
+}
+```
+
+**Note:** Make sure to run `npm run build` in the library directory after making changes.
+
+### Option C: npm Package (Future)
+
+```bash
+npm install @crystin001/theme-settings-lib
+```
+
+## Usage
+
+### 1. Wrap Your App with SettingsProvider
+
+Wrap your root component with `SettingsProvider` to enable theme and settings management:
+
+```tsx
+// app/_layout.tsx or App.tsx
+import { SettingsProvider } from '@crystin001/theme-settings-lib';
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <SettingsProvider>
+      <Stack>
+        {/* Your app screens */}
+      </Stack>
+    </SettingsProvider>
+  );
+}
+```
+
+### 2. Use Theme Hooks in Your Components
+
+Access theme colors and settings in your components:
+
+```tsx
+import { View, Text, Button } from 'react-native';
+import { useTheme, useSettings } from '@crystin001/theme-settings-lib';
+
+function MyComponent() {
+  const colors = useTheme();
+  const { setThemeFamily } = useSettings();
+
+  return (
+    <View style={{ backgroundColor: colors.background }}>
+      <Text style={{ color: colors.text }}>Hello World</Text>
+      <Button 
+        onPress={() => setThemeFamily('neon-surf')} 
+        title="Change to Neon Surf" 
+      />
+    </View>
+  );
+}
+```
+
+### 3. Use Translations
+
+Access translations using the `useTranslation` hook:
+
+```tsx
+import { Text } from 'react-native';
+import { useTranslation } from '@crystin001/theme-settings-lib';
+
+function MyComponent() {
+  const { t } = useTranslation();
+
+  return (
+    <Text>{t('common.welcome')}</Text>
+  );
+}
+```
+
+### 4. Get Specific Theme Colors
+
+Use `useThemeColor` to get specific colors from the current theme:
+
+```tsx
+import { View, Text } from 'react-native';
+import { useThemeColor } from '@crystin001/theme-settings-lib';
+
+function MyComponent() {
+  const backgroundColor = useThemeColor({}, 'background');
+  const textColor = useThemeColor({}, 'text');
+  const primaryColor = useThemeColor({}, 'primary');
+
+  return (
+    <View style={{ backgroundColor }}>
+      <Text style={{ color: textColor }}>Primary: {primaryColor}</Text>
+    </View>
+  );
+}
+```
+
+### 5. Extend Translations
+
+Add app-specific translations by extending the i18n instance:
+
+```tsx
+import { i18n } from '@crystin001/theme-settings-lib';
+
+// Add custom translations
+i18n.addResourceBundle('en-US', 'translation', {
+  myFeature: {
+    title: 'My Feature',
+    description: 'This is my feature',
+  },
+}, true, true);
+```
+
+### 6. Complete Example: Integration with React Navigation
+
+Here's a complete example showing integration with React Navigation:
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
+import { SettingsProvider, useSettings } from '@crystin001/theme-settings-lib';
+
+function RootLayoutNav() {
+  const { currentTheme } = useSettings();
+  const isDarkTheme = currentTheme.endsWith('-dark');
+
+  return (
+    <ThemeProvider value={isDarkTheme ? DarkTheme : DefaultTheme}>
+      <Stack>
+        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+      </Stack>
+      <StatusBar style={isDarkTheme ? 'light' : 'dark'} />
+    </ThemeProvider>
+  );
+}
+
+export default function RootLayout() {
+  return (
+    <SettingsProvider>
+      <RootLayoutNav />
+    </SettingsProvider>
+  );
+}
+```
+
+## Available Theme Families
+
+- **System** - Follows device theme preference (default)
+- **Neon Surf** - Vibrant neon colors (hot pink, cyan, yellow, orange)
+- **Pink & Purple** - Soft purple and pink tones
+- **Pastel** - Gentle pastel colors
+- **GitHub** - GitHub-inspired theme
+- **High Contrast** - Maximum contrast for accessibility
+- **Solarized** - Solarized color scheme
+- **Dark Plus** - Dark theme with blue accents
+
+Each theme family has both light and dark variants that automatically switch based on device settings.
+
+## API Reference
+
+### Hooks
+
+#### `useTheme()`
+
+Returns all colors from the current theme.
+
+```tsx
+const colors = useTheme();
+// Returns: { text, background, tint, icon, ... }
+```
+
+#### `useThemeColor(props?, colorName?)`
+
+Get a specific color from the current theme.
+
+```tsx
+const backgroundColor = useThemeColor({}, 'background');
+const textColor = useThemeColor({ light: '#000', dark: '#fff' }, 'text');
+```
+
+#### `useSettings()`
+
+Access theme and language settings.
+
+```tsx
+const {
+  selectedThemeFamily,
+  currentTheme,
+  setThemeFamily,
+  language,
+  setLanguage,
+  availableThemeFamilies,
+  availableLanguages
+} = useSettings();
+```
+
+#### `useTranslation()`
+
+Get the translation function.
+
+```tsx
+const { t } = useTranslation();
+const welcomeText = t('common.welcome');
+```
+
+### Settings Context
+
+The `useSettings()` hook returns:
+
+- `selectedThemeFamily` - Currently selected theme family (e.g., `'neon-surf'`)
+- `currentTheme` - Effective theme being used (includes variant, e.g., `'neon-surf-light'`)
+- `setThemeFamily(family)` - Change theme family
+- `language` - Current language code (e.g., `'en-US'`)
+- `setLanguage(lang)` - Change language
+- `availableThemeFamilies` - Array of all available theme families with metadata
+- `availableLanguages` - Array of all available languages
+
+### Color Utilities
+
+#### `getContrastRatio(color1, color2)`
+
+Calculate the contrast ratio between two colors (returns 1-21).
+
+```tsx
+import { getContrastRatio } from '@crystin001/theme-settings-lib';
+
+const ratio = getContrastRatio('#000000', '#FFFFFF'); // Returns ~21
+```
+
+#### `getContrastTextColor(backgroundColor, lightColor?, darkColor?, minContrast?)`
+
+Get a readable text color for a given background.
+
+```tsx
+import { getContrastTextColor } from '@crystin001/theme-settings-lib';
+
+const textColor = getContrastTextColor('#000000'); // Returns '#FFFFFF'
+```
+
+#### `meetsContrastRequirement(foreground, background, level?)`
+
+Check if a color combination meets WCAG contrast requirements.
+
+```tsx
+import { meetsContrastRequirement } from '@crystin001/theme-settings-lib';
+
+const isAccessible = meetsContrastRequirement('#000000', '#FFFFFF', 'AA'); // Returns true
+```
+
+#### `ensureContrast(foreground, background, level?)`
+
+Ensure a color combination has readable contrast, adjusting if needed.
+
+```tsx
+import { ensureContrast } from '@crystin001/theme-settings-lib';
+
+const readableColor = ensureContrast('#888888', '#FFFFFF', 'AA');
+```
+
+## Contributing / Development
+
+For information about developing the library, including:
+- Building the library
+- Running the example app for visual theme development
+- Project structure
+- Development workflow
+
+See [SETUP.md](./SETUP.md) in the repository.
+
+## Versioning
+
+The library follows [Semantic Versioning](https://semver.org/):
+
+- **Major** (x.0.0) - Breaking API changes
+- **Minor** (0.x.0) - New themes, features, or languages
+- **Patch** (0.0.x) - Bug fixes and theme adjustments
+
+## Troubleshooting
+
+### "Unable to resolve path to module" Error
+
+If you get an error like `Unable to resolve path to module '@crystin001/theme-settings-lib'`, try these steps:
+
+1. **The library should build automatically during installation.** If you're using a local file path and made changes, rebuild:
+   ```bash
+   cd theme-settings-lib
+   npm run build
+   ```
+   
+   **Note:** When installing from git, the library builds automatically via the `prepare` script. You only need to manually build if using a local `file:` path and making changes.
+
+2. **Clear Metro cache and restart:**
+   ```bash
+   # In your app directory
+   npx react-native start --reset-cache
+   # Or for Expo:
+   npx expo start --clear
+   ```
+
+3. **Reinstall dependencies:**
+   ```bash
+   # In your app directory
+   rm -rf node_modules
+   npm install
+   # Or if using yarn:
+   rm -rf node_modules
+   yarn install
+   ```
+
+4. **If using local file path, verify the path is correct:**
+   ```json
+   {
+     "dependencies": {
+       "@crystin001/theme-settings-lib": "file:../theme-settings-lib"
+     }
+   }
+   ```
+   Make sure the relative path from your app's `package.json` to the library is correct.
+
+5. **For Expo projects, you may need to restart the development server completely:**
+   ```bash
+   # Stop the server, then:
+   npx expo start --clear
+   ```
+
+6. **Check that `dist/` folder exists and contains compiled files:**
+   The library must be built before it can be used. Run `npm run build` in the library directory.
+
+## Peer Dependencies
+
+This library requires the following peer dependencies (installed by your app):
+
+- `react` - React library
+- `react-native` - React Native framework
+- `i18next` - Internationalization framework
+- `react-i18next` - React bindings for i18next
+- `expo-localization` - Expo localization utilities
+- `@react-native-async-storage/async-storage` - Async storage for persistence
+- `color` (optional) - Color manipulation library
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/trial-and-code/theme-settings-lib](https://github.com/trial-and-code/theme-settings-lib)
+
+---
+
+**For developers:** See [SETUP.md](./SETUP.md) for development setup, building the library, and running the example app.
+
+