@awes-io/ui 2.142.3 → 2.144.0

package/docs/configuration.md

@@ -0,0 +1,493 @@
+---
+metaTitle: Configuration | AwesCode UI
+meta:
+  - name: description
+    content: Complete configuration guide for AwesCode UI - static settings, component defaults, and customization options.
+title: Configuration
+---
+
+# Configuration
+
+The AwesCode UI framework provides two types of configuration: static configuration for application-wide settings and dynamic component configuration for runtime customization.
+
+## Static Configuration (awes.config.js)
+
+Create an `awes.config.js` file in your project root to configure static settings like logos, backgrounds, fonts, and internationalization.
+
+### Basic Structure
+
+```javascript
+export default {
+  // Main configuration
+}
+
+export const dark = {
+  // Dark theme overrides
+}
+
+export const lang = {
+  // Internationalization settings
+}
+
+export const dayjs = {
+  // Date/time formatting
+}
+
+export const axios = {
+  // HTTP client settings
+}
+
+export const notify = {
+  // Notification defaults
+}
+```
+
+### Default Configuration Options
+
+#### Logo Configuration
+
+Configure your application logo and its variants:
+
+```javascript
+export default {
+  logo: {
+    src: '/logo.svg',
+    alt: 'My App'
+  },
+
+  fullLogo: {
+    src: '/logo-full.svg',
+    alt: 'My App Full Logo'
+  }
+}
+```
+
+**Default values:**
+- `logo.src`: `'https://static.awes.io/logo-blue.svg'`
+- `logo.alt`: `'AwesCode UI'`
+- `fullLogo.src`: `'https://static.awes.io/logo-blue_white.svg'`
+- `fullLogo.alt`: `'AwesCode UI'`
+
+#### Background
+
+Set a background image for your application:
+
+```javascript
+export default {
+  background: {
+    src: '/background.svg'
+  }
+}
+```
+
+**Default:** `'https://static.awes.io/demo/awes-background.svg'`
+
+#### Google Fonts
+
+Load custom fonts from Google Fonts:
+
+```javascript
+export default {
+  googleFont: 'https://fonts.googleapis.com/css?family=Roboto:400,700&display=swap'
+}
+```
+
+**Default:** `null` (no custom font)
+
+#### Custom Styles
+
+Import and apply custom style configurations:
+
+```javascript
+import styles from '../assets/js/styles'
+
+export default {
+  style: styles.custom
+}
+```
+
+**Default:** `styles.default` (from `@awes-io/ui/assets/js/styles`)
+
+### Dark Theme Configuration
+
+Export a `dark` object to override settings for dark theme:
+
+```javascript
+export const dark = {
+  logo: {
+    src: '/logo-dark.svg',
+    alt: 'My App Dark'
+  },
+
+  fullLogo: {
+    src: '/logo-full-dark.svg',
+    alt: 'My App Full Logo Dark'
+  },
+
+  background: {
+    src: '/background-dark.svg'
+  },
+
+  style: styles.dark
+}
+```
+
+**Default dark theme values:**
+- Inverts logo colors from the main theme
+- Uses `styles.dark` for styling
+
+### Internationalization (i18n)
+
+Configure language and translation settings in `awes.config.js`:
+
+```javascript
+export const lang = {
+  // Available locales
+  locales: ['en', 'es', 'fr'],
+
+  // Default locale
+  locale: 'en',
+
+  // Suppress warnings
+  silentTranslationWarn: true,
+  silentFallbackWarn: true,
+
+  // Fetch translations from API
+  fetchTranslation: true,
+
+  // Translation statistics
+  statsTranslation: false,
+  statsAutoload: false,
+
+  // Language cookie name
+  langCookie: 'i18n_redirected',
+
+  // Retry configuration for loading translations
+  retry: {
+    retries: 5,
+    retryDelay: 5000,
+    block: false
+  }
+}
+```
+
+**Note:** You don't need to configure i18n in `nuxt.config.js`. AwesCode UI handles i18n configuration automatically through `awes.config.js`. Only add the `lang` export if you need to customize from the defaults.
+
+**Defaults:**
+- `locales`: `['en']`
+- `locale`: `'en'`
+- `silentTranslationWarn`: `true`
+- `silentFallbackWarn`: `true`
+- `fetchTranslation`: `false`
+- `statsTranslation`: `false`
+- `statsAutoload`: `false`
+- `langCookie`: `'i18n_redirected'`
+- `retry.retries`: `5`
+- `retry.retryDelay`: `5000`
+- `retry.block`: `false`
+
+### Date/Time Configuration
+
+Configure Day.js for date and time formatting:
+
+```javascript
+export const dayjs = {
+  // String format options
+  stringFormat: {
+    pattern: 'YYYY-MM-DD',
+    format: true
+  },
+
+  // Day.js plugins to load
+  plugins: [
+    'dayjs/plugin/isLeapYear',
+    'dayjs/plugin/relativeTime',
+    'dayjs/plugin/utc',
+    'dayjs/plugin/timezone'
+  ]
+}
+```
+
+**Defaults:**
+- `stringFormat.pattern`: `null`
+- `stringFormat.format`: `true`
+- `plugins`: `['dayjs/plugin/isLeapYear', 'dayjs/plugin/relativeTime']`
+
+### Axios Configuration
+
+Configure the HTTP client:
+
+```javascript
+export const axios = {
+  testUrl: 'https://api.example.com/health'
+}
+```
+
+**Default:** `testUrl: 'https://httpbin.org/get'`
+
+### Notification Defaults
+
+Configure default notification behavior:
+
+```javascript
+export const notify = {
+  duration: 5000,
+  position: 'top-right'
+}
+```
+
+**Default:** `{}` (empty object)
+
+## Dynamic Component Configuration (Plugin)
+
+For component defaults that may need runtime updates (e.g., after API requests), configure them in a Nuxt plugin using `Vue.prototype[CONFIG_VAR]`.
+
+### Creating the Plugin
+
+Create `plugins/components.js`:
+
+```javascript
+import Vue from 'vue'
+import { CONFIG_VAR } from '@AwUtils/component'
+
+export default async ({ app, $axios }) => {
+  // Initialize config object
+  Vue.prototype[CONFIG_VAR] = Vue.prototype[CONFIG_VAR] || {}
+
+  // Example: Fetch settings from API
+  try {
+    const settings = await $axios.$get('/api/settings')
+
+    // Configure components based on API response
+    Vue.prototype[CONFIG_VAR].AwButton = {
+      size: settings.buttonSize || 'md',
+      color: settings.primaryColor || 'accent',
+      theme: 'solid'
+    }
+  } catch (error) {
+    // Fallback to defaults if API fails
+    Vue.prototype[CONFIG_VAR].AwButton = {
+      size: 'md',
+      color: 'accent',
+      theme: 'solid'
+    }
+  }
+
+  // Configure other components
+  Vue.prototype[CONFIG_VAR].AwInput = {
+    baseClass: 'aw-text-field'
+  }
+
+  Vue.prototype[CONFIG_VAR].AwPageHeadline = {
+    breadcrumbMenu: true
+  }
+
+  Vue.prototype[CONFIG_VAR].AwTable = {
+    sortable: true,
+    filterable: true
+  }
+}
+```
+
+### Registering the Plugin
+
+Add the plugin to `nuxt.config.js`:
+
+```javascript
+export default {
+  plugins: [
+    '~/plugins/components.js'
+  ]
+}
+```
+
+### Available Component Configurations
+
+Different components accept different configuration options. Here are some common examples:
+
+#### AwButton
+
+```javascript
+Vue.prototype[CONFIG_VAR].AwButton = {
+  size: 'md',        // sm, md, lg
+  color: 'accent',   // accent, primary, success, error, mono
+  theme: 'solid'     // solid, outline, ghost
+}
+```
+
+#### AwInput
+
+```javascript
+Vue.prototype[CONFIG_VAR].AwInput = {
+  baseClass: 'aw-text-field'
+}
+```
+
+#### AwPageHeadline
+
+```javascript
+Vue.prototype[CONFIG_VAR].AwPageHeadline = {
+  breadcrumbMenu: true
+}
+```
+
+#### AwTable
+
+```javascript
+Vue.prototype[CONFIG_VAR].AwTable = {
+  sortable: true,
+  filterable: true,
+  perPage: 25
+}
+```
+
+## Complete Example
+
+Here's a complete example showing both static and dynamic configuration:
+
+### awes.config.js
+
+```javascript
+import styles from '../assets/js/styles'
+
+export default {
+  logo: {
+    src: '/logo.svg',
+    alt: 'My Application'
+  },
+
+  fullLogo: {
+    src: '/logo-full.svg',
+    alt: 'My Application'
+  },
+
+  background: {
+    src: '/background.svg'
+  },
+
+  googleFont: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap',
+
+  style: styles.default
+}
+
+export const dark = {
+  logo: {
+    src: '/logo-dark.svg'
+  },
+
+  fullLogo: {
+    src: '/logo-full-dark.svg'
+  },
+
+  background: {
+    src: '/background-dark.svg'
+  },
+
+  style: styles.dark
+}
+
+export const lang = {
+  locales: ['en', 'es', 'fr'],
+  locale: 'en',
+  fetchTranslation: true,
+  langCookie: 'app_language'
+}
+
+export const dayjs = {
+  stringFormat: {
+    pattern: 'YYYY-MM-DD',
+    format: true
+  },
+  plugins: [
+    'dayjs/plugin/relativeTime',
+    'dayjs/plugin/utc',
+    'dayjs/plugin/timezone'
+  ]
+}
+```
+
+### plugins/components.js
+
+```javascript
+import Vue from 'vue'
+import { CONFIG_VAR } from '@AwUtils/component'
+
+export default async ({ app, $axios }) => {
+  Vue.prototype[CONFIG_VAR] = Vue.prototype[CONFIG_VAR] || {}
+
+  try {
+    const settings = await $axios.$get('/api/app/settings')
+
+    Vue.prototype[CONFIG_VAR].AwButton = {
+      size: settings.ui.buttonSize,
+      color: settings.ui.primaryColor,
+      theme: 'solid'
+    }
+
+    Vue.prototype[CONFIG_VAR].AwPageHeadline = {
+      breadcrumbMenu: settings.ui.showBreadcrumbs
+    }
+
+    Vue.prototype[CONFIG_VAR].AwTable = {
+      sortable: settings.ui.tableSortable,
+      filterable: settings.ui.tableFilterable,
+      perPage: settings.ui.tablePerPage
+    }
+  } catch (error) {
+    // Fallback to sensible defaults
+    Vue.prototype[CONFIG_VAR].AwButton = {
+      size: 'md',
+      color: 'accent',
+      theme: 'solid'
+    }
+
+    Vue.prototype[CONFIG_VAR].AwPageHeadline = {
+      breadcrumbMenu: true
+    }
+
+    Vue.prototype[CONFIG_VAR].AwTable = {
+      sortable: true,
+      filterable: true,
+      perPage: 25
+    }
+  }
+}
+```
+
+## Accessing Configuration at Runtime
+
+You can access the configuration in your components:
+
+```javascript
+export default {
+  computed: {
+    logoSrc() {
+      return this.$awes._config.logo.src
+    }
+  },
+
+  mounted() {
+    // Access component config
+    const buttonConfig = this[this.$options.CONFIG_VAR]?.AwButton
+    console.log('Button size:', buttonConfig?.size)
+  }
+}
+```
+
+## Best Practices
+
+1. **Static for Branding**: Use `awes.config.js` for logos, colors, fonts, and other branding elements that don't change at runtime.
+
+2. **Dynamic for User Settings**: Use the plugin approach for component configurations that depend on user preferences or API data.
+
+3. **Provide Fallbacks**: Always provide sensible defaults in your plugin in case API requests fail.
+
+4. **Keep It Simple**: Don't over-configure. Only customize what you need to change from the defaults.
+
+5. **Document Custom Settings**: If you add custom configuration options, document them for your team.
+
+## See Also
+
+- [Getting Started](./getting-started.md) - Initial setup guide
+- [Best Practices](./guides/best-practices.md) - Framework patterns and conventions
+- [Component Index](./index.md) - Browse all available components