0
# Theme and Mode Resolution
1

2
The Theme and Mode Resolution system provides dynamic theme switching and responsive mode detection for components. It supports multiple themes ('tiny', 'saas') and responsive modes ('pc', 'mobile', 'mobile-first') with hierarchical resolution from props, injection, and global configuration.
3

4
## Capabilities
5

6
### Mode Resolution
7

8
Automatic detection and resolution of component display modes based on device characteristics and user preferences.
9

10
```typescript { .api }
11
/**
12
 * Resolve component display mode from various sources
13
 * @param props - Component props object
14
 * @param context - Component context
15
 * @returns Resolved mode string
16
 */
17
function resolveMode(props: any, context: any): 'pc' | 'mobile' | 'mobile-first';
18
```
19

20
**Mode Types:**
21
- `'pc'` - Desktop/PC optimized layout and interactions
22
- `'mobile'` - Mobile-specific layout with touch optimizations
23
- `'mobile-first'` - Mobile-first responsive design approach
24

25
**Resolution Priority:**
26
1. `props.tiny_mode` - Component-level prop
27
2. Injected `TinyMode` - Parent component injection
28
3. Global configuration - Application-level setting
29
4. Default fallback - `'pc'`
30

31
**Usage Examples:**
32

33
```typescript
34
import { resolveMode, hooks } from "@opentiny/vue-common";
35

36
export default {
37
  props: {
38
    tiny_mode: String,
39
    tiny_mode_root: Boolean
40
  },
41
  setup(props, context) {
42
    // Resolve current mode
43
    const currentMode = resolveMode(props, context);
44
    
45
    // Mode-based component behavior
46
    const componentConfig = hooks.computed(() => {
47
      switch (currentMode) {
48
        case 'mobile':
49
          return {
50
            itemSize: 'large',
51
            touchOptimized: true,
52
            gestureEnabled: true
53
          };
54
        case 'mobile-first':
55
          return {
56
            responsive: true,
57
            breakpointBased: true,
58
            adaptiveLayout: true
59
          };
60
        default: // 'pc'
61
          return {
62
            itemSize: 'medium',
63
            hoverEffects: true,
64
            keyboardNavigation: true
65
          };
66
      }
67
    });
68
    
69
    return {
70
      currentMode,
71
      componentConfig
72
    };
73
  }
74
};
75
```
76

77
### Theme Resolution
78

79
Dynamic theme switching supporting multiple design systems and theme variants.
80

81
```typescript { .api }
82
/**
83
 * Resolve component theme from various sources
84
 * @param props - Component props object  
85
 * @param context - Component context
86
 * @returns Resolved theme string
87
 */
88
function resolveTheme(props: any, context: any): 'tiny' | 'saas';
89
```
90

91
**Theme Types:**
92
- `'tiny'` - Default TinyVue theme with enterprise styling
93
- `'saas'` - SaaS-optimized theme with modern design patterns
94

95
**Resolution Priority:**
96
1. `props.tiny_theme` - Component-level prop
97
2. Injected `TinyTheme` - Parent component injection
98
3. Global configuration - Application-level setting
99
4. Default fallback - `'tiny'`
100

101
**Usage Examples:**
102

103
```typescript
104
import { resolveTheme, hooks } from "@opentiny/vue-common";
105

106
export default {
107
  props: {
108
    tiny_theme: String
109
  },
110
  setup(props, context) {
111
    // Resolve current theme
112
    const currentTheme = resolveTheme(props, context);
113
    
114
    // Theme-based styling
115
    const themeClasses = hooks.computed(() => {
116
      const baseClasses = 'component-base';
117
      
118
      const themeStyles = {
119
        tiny: 'tiny-theme border-gray-300 shadow-sm',
120
        saas: 'saas-theme border-blue-200 shadow-md rounded-lg'  
121
      };
122
      
123
      return `${baseClasses} ${themeStyles[currentTheme]}`;
124
    });
125
    
126
    // Theme-specific configuration
127
    const themeConfig = hooks.computed(() => {
128
      switch (currentTheme) {
129
        case 'saas':
130
          return {
131
            borderRadius: '8px',
132
            shadowLevel: 'medium',
133
            colorScheme: 'modern',
134
            animations: true
135
          };
136
        default: // 'tiny'
137
          return {
138
            borderRadius: '4px',
139
            shadowLevel: 'subtle',
140
            colorScheme: 'enterprise',
141
            animations: false
142
          };
143
      }
144
    });
145
    
146
    return {
147
      currentTheme,
148
      themeClasses,
149
      themeConfig
150
    };
151
  }
152
};
153
```
154

155
### Chart Theme Resolution
156

157
Specialized theme resolution for chart and data visualization components.
158

159
```typescript { .api }
160
/**
161
 * Resolve chart theme configuration (internal function)
162
 * @param props - Component props object
163
 * @param context - Component context  
164
 * @returns Chart theme configuration object or null
165
 */
166
// resolveChartTheme(props: any, context: any): any | null;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { setup } from "@opentiny/vue-common";
173

174
export default {
175
  props: {
176
    tiny_chart_theme: Object
177
  },
178
  setup(props, context) {
179
    return setup({
180
      props,
181
      context,
182
      renderless: (props, hooks, utils) => {
183
        // Chart theme is automatically resolved and available in utils.vm.chartTheme
184
        const chartTheme = utils.vm.chartTheme;
185
        
186
        const chartConfig = hooks.computed(() => ({
187
          theme: chartTheme || {
188
            backgroundColor: '#ffffff',
189
            textColor: '#333333',
190
            lineColor: '#e0e0e0'
191
          }
192
        }));
193
        
194
        return {
195
          chartConfig
196
        };
197
      },
198
      api: ['chartConfig']
199
    });
200
  }
201
};
202
```
203

204
## Global Configuration
205

206
### Mode Configuration
207

208
Application-level mode configuration for consistent behavior across components.
209

210
**Setting Global Mode:**
211

212
```typescript
213
import { createApp } from 'vue';
214
import { hooks } from "@opentiny/vue-common";
215

216
const app = createApp({});
217

218
// Set global mode configuration
219
app.config.globalProperties.tiny_mode = 'mobile-first';
220

221
// Or use provide/inject
222
app.provide('TinyMode', 'mobile-first');
223
```
224

225
**Root Mode Provider:**
226

227
```typescript
228
import { resolveMode } from "@opentiny/vue-common";
229

230
export default {
231
  props: {
232
    tiny_mode_root: Boolean,
233
    tiny_mode: String
234
  },
235
  setup(props, context) {
236
    // This component will provide mode to all children
237
    const mode = resolveMode(props, context);
238
    
239
    // Mode is automatically provided when tiny_mode_root is true
240
    return {
241
      mode
242
    };
243
  }
244
};
245
```
246

247
### Theme Configuration
248

249
Application-level theme configuration and switching.
250

251
**Setting Global Theme:**
252

253
```typescript
254
import { createApp } from 'vue';
255

256
const app = createApp({});
257

258
// Global theme configuration
259
app.config.globalProperties.tiny_theme = { value: 'saas' };
260

261
// Or use provide/inject
262
app.provide('TinyTheme', 'saas');
263
```
264

265
**Dynamic Theme Switching:**
266

267
```typescript
268
import { hooks } from "@opentiny/vue-common";
269

270
export default {
271
  setup() {
272
    const globalTheme = hooks.ref('tiny');
273
    
274
    const switchTheme = (newTheme) => {
275
      globalTheme.value = newTheme;
276
      // Update global configuration
277
      app.config.globalProperties.tiny_theme = { value: newTheme };
278
    };
279
    
280
    // Provide theme to child components
281
    hooks.provide('TinyTheme', globalTheme);
282
    
283
    return {
284
      globalTheme,
285
      switchTheme
286
    };
287
  }
288
};
289
```
290

291
## Advanced Usage Patterns
292

293
### Multi-Theme Component
294

295
Component that adapts to multiple theme systems.
296

297
```typescript
298
import { resolveTheme, resolveMode, hooks } from "@opentiny/vue-common";
299

300
export default {
301
  props: {
302
    tiny_theme: String,
303
    tiny_mode: String
304
  },
305
  setup(props, context) {
306
    const theme = resolveTheme(props, context);
307
    const mode = resolveMode(props, context);
308
    
309
    // Combined theme and mode styling
310
    const adaptiveClasses = hooks.computed(() => {
311
      const base = 'adaptive-component';
312
      
313
      // Theme-based classes
314
      const themeClass = theme === 'saas' ? 'saas-styling' : 'tiny-styling';
315
      
316
      // Mode-based classes  
317
      const modeClasses = {
318
        'pc': 'desktop-layout hover-effects',
319
        'mobile': 'mobile-layout touch-friendly',
320
        'mobile-first': 'responsive-layout adaptive-spacing'
321
      };
322
      
323
      return `${base} ${themeClass} ${modeClasses[mode]}`;
324
    });
325
    
326
    // Theme and mode specific configuration
327
    const componentConfig = hooks.computed(() => ({
328
      // Layout configuration
329
      layout: mode === 'mobile' ? 'vertical' : 'horizontal',
330
      spacing: mode === 'mobile' ? 'compact' : 'comfortable',
331
      
332
      // Visual configuration
333
      borderRadius: theme === 'saas' ? '8px' : '4px',
334
      elevation: theme === 'saas' ? 2 : 1,
335
      
336
      // Interaction configuration
337
      hoverEffects: mode === 'pc' && theme === 'saas',
338
      touchOptimized: mode !== 'pc',
339
      animations: theme === 'saas'
340
    }));
341
    
342
    return {
343
      theme,
344
      mode,
345
      adaptiveClasses,
346
      componentConfig
347
    };
348
  }
349
};
350
```
351

352
### Theme Context Provider
353

354
Component that manages theme context for child components.
355

356
```typescript
357
import { resolveTheme, hooks } from "@opentiny/vue-common";
358

359
export default {
360
  props: {
361
    tiny_theme: String,
362
    themeOverride: Object
363
  },
364
  setup(props, context) {
365
    const baseTheme = resolveTheme(props, context);
366
    
367
    // Create enhanced theme context
368
    const themeContext = hooks.computed(() => ({
369
      name: baseTheme,
370
      tokens: {
371
        ...getThemeTokens(baseTheme),
372
        ...props.themeOverride
373
      },
374
      utilities: {
375
        getColor: (colorKey) => getThemeTokens(baseTheme).colors[colorKey],
376
        getSpacing: (spaceKey) => getThemeTokens(baseTheme).spacing[spaceKey],
377
        getComponent: (componentName) => getThemeTokens(baseTheme).components[componentName]
378
      }
379
    }));
380
    
381
    // Provide enhanced theme context
382
    hooks.provide('EnhancedTheme', themeContext);
383
    
384
    return {
385
      themeContext
386
    };
387
  }
388
};
389

390
function getThemeTokens(theme) {
391
  const tokens = {
392
    tiny: {
393
      colors: { primary: '#1890ff', secondary: '#666666' },
394
      spacing: { small: '8px', medium: '16px', large: '24px' },
395
      components: { button: { height: '32px', padding: '4px 15px' } }
396
    },
397
    saas: {
398
      colors: { primary: '#4f46e5', secondary: '#6b7280' },
399
      spacing: { small: '6px', medium: '12px', large: '20px' },
400
      components: { button: { height: '36px', padding: '8px 16px' } }
401
    }
402
  };
403
  
404
  return tokens[theme] || tokens.tiny;
405
}
406
```
407

408
## Integration with Component Setup
409

410
The theme and mode resolution is automatically integrated with the component setup system:
411

412
```typescript
413
import { setup } from "@opentiny/vue-common";
414

415
export default {
416
  setup(props, context) {
417
    return setup({
418
      props,
419
      context,
420
      renderless: (props, hooks, utils) => {
421
        // Theme and mode are automatically available in utils.vm
422
        const theme = utils.vm.theme; // Result of resolveTheme()
423
        const chartTheme = utils.vm.chartTheme; // Result of resolveChartTheme()
424
        // Mode is available through utils.mode
425
        
426
        return {
427
          // Component logic using resolved theme and mode
428
        };
429
      },
430
      api: []
431
    });
432
  }
433
};
434
```