0
# Internal APIs
1

2
Advanced and internal APIs for Storybook Dark Mode that provide low-level access to theme management functionality.
3

4
## Capabilities
5

6
### Theme Store Management
7

8
Core store functions for managing theme state and persistence.
9

10
```typescript { .api }
11
/**
12
 * Get or update the dark mode store with user configuration
13
 * @param userTheme - Optional partial configuration to merge with stored settings
14
 * @returns Complete DarkModeStore configuration object
15
 */
16
function store(userTheme?: Partial<DarkModeStore>): DarkModeStore;
17

18
/**
19
 * Persist dark mode settings to localStorage
20
 * @param newStore - Complete store configuration to persist
21
 */
22
function updateStore(newStore: DarkModeStore): void;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { store, updateStore } from 'storybook-dark-mode';
29

30
// Get current store configuration
31
const currentStore = store();
32
console.log('Current theme:', currentStore.current);
33

34
// Update store with new configuration
35
const updatedStore = store({
36
  current: 'dark',
37
  darkClass: ['custom-dark'],
38
  stylePreview: true
39
});
40

41
// Manually persist configuration
42
updateStore(updatedStore);
43
```
44

45
### OS Preference Detection
46

47
MediaQueryList for detecting user's system color scheme preference.
48

49
```typescript { .api }
50
/**
51
 * MediaQueryList that matches dark color scheme preference
52
 * Used for automatic theme detection when user hasn't explicitly set preference
53
 */
54
const prefersDark: MediaQueryList;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { prefersDark } from 'storybook-dark-mode';
61

62
// Check current OS preference
63
console.log('OS prefers dark mode:', prefersDark.matches);
64

65
// Listen for OS preference changes
66
const handlePreferenceChange = (event: MediaQueryListEvent) => {
67
  console.log('OS preference changed to:', event.matches ? 'dark' : 'light');
68
};
69

70
prefersDark.addListener(handlePreferenceChange);
71

72
// Cleanup listener
73
prefersDark.removeListener(handlePreferenceChange);
74
```
75

76
### Toolbar Component
77

78
The main toolbar component that provides the dark mode toggle UI element.
79

80
```typescript { .api }
81
/**
82
 * Main dark mode toolbar component
83
 * @param props - Component props containing Storybook API instance
84
 * @returns React component rendering theme toggle button
85
 */
86
function DarkMode(props: DarkModeProps): React.ReactElement;
87

88
interface DarkModeProps {
89
  /** Storybook manager API instance */
90
  api: API;
91
}
92
```
93

94
**Note:** This component is typically registered automatically by the addon and doesn't need manual usage.
95

96
### Storage Configuration
97

98
Constants and types related to localStorage persistence.
99

100
```typescript { .api }
101
/** localStorage key used for persisting theme settings */
102
const STORAGE_KEY: 'sb-addon-themes-3';
103

104
/** Default parameter values used when no user configuration is provided */
105
interface DefaultParams {
106
  classTarget: 'body';
107
  dark: ThemeVars;
108
  darkClass: ['dark'];
109
  light: ThemeVars;
110
  lightClass: ['light'];
111
  stylePreview: false;
112
  userHasExplicitlySetTheTheme: false;
113
}
114
```
115

116
### Internal Utility Functions
117

118
Helper functions used internally by the addon for class and iframe management.
119

120
```typescript { .api }
121
/**
122
 * Convert string or array of class names to array format
123
 * @param classes - Single class name or array of class names
124
 * @returns Array of class names
125
 */
126
function arrayify(classes: string | string[]): string[];
127

128
/**
129
 * Apply theme classes to specified element
130
 * @param el - Target element to apply classes to
131
 * @param store - Theme store configuration
132
 */
133
function toggleDarkClass(el: Element, store: DarkModeStore): void;
134

135
/**
136
 * Update preview iframe with current theme classes
137
 * @param store - Theme store configuration
138
 */
139
function updatePreview(store: DarkModeStore): void;
140

141
/**
142
 * Update manager iframe with current theme classes
143
 * @param store - Theme store configuration
144
 */
145
function updateManager(store: DarkModeStore): void;
146
```
147

148
**Note:** These internal functions are not typically needed for standard usage but may be useful for advanced customization scenarios.
149

150
## Advanced Usage Patterns
151

152
### Custom Store Management
153

154
```typescript
155
import { store, updateStore, prefersDark } from 'storybook-dark-mode';
156

157
// Initialize with custom defaults
158
const customStore = store({
159
  current: prefersDark.matches ? 'dark' : 'light',
160
  darkClass: ['app-dark', 'high-contrast'],
161
  lightClass: ['app-light', 'standard-contrast'],
162
  stylePreview: true,
163
  classTarget: 'html'
164
});
165

166
// Update and persist
167
updateStore(customStore);
168
```
169

170
### Dynamic Theme Configuration
171

172
```typescript
173
import { store, updateStore } from 'storybook-dark-mode';
174
import { themes } from '@storybook/theming';
175

176
// Dynamically update theme based on user preferences
177
function applyUserTheme(userPrefs: UserThemePreferences) {
178
  const currentStore = store();
179
  
180
  const updatedStore = {
181
    ...currentStore,
182
    dark: {
183
      ...themes.dark,
184
      appBg: userPrefs.darkBackground,
185
      textColor: userPrefs.darkText
186
    },
187
    light: {
188
      ...themes.light,
189
      appBg: userPrefs.lightBackground,
190
      textColor: userPrefs.lightText
191
    }
192
  };
193
  
194
  updateStore(updatedStore);
195
}
196
```