@awes-io/ui 2.142.3 → 2.143.0

package/docs/index.md

@@ -1 +1,263 @@
-# UI Component
+# AwesCode UI Component Library
+
+Comprehensive documentation for all UI components in the AwesCode UI component library.
+
+## Documentation Structure
+
+This documentation is organized into the following sections:
+
+- **[Getting Started](./getting-started.md)** - Installation, setup, and quick start
+- **[Framework Integration](./integrations.md)** - How all packages work together
+- **[Guides](./guides/)** - Page patterns, best practices, data fetching, error handling
+- **[Cookbook](./cookbook/)** - Common and advanced patterns with examples
+- **[Components](./components/)** - Complete component reference (atoms, molecules, organisms, pages, layouts)
+- **[Reference](./reference/)** - Plugins, utilities, troubleshooting
+
+## Quick Navigation
+
+**Building Common Pages:**
+- [List Page with Table](./guides/page-patterns/list-pages.md) - Browse and search data
+- [Detail/Edit Page](./guides/page-patterns/detail-pages.md) - Create and edit records
+- [Page with Aside Sidebar](./guides/page-patterns/aside-pages.md) - Forms with summary or contextual info
+- [Dashboard Page](./guides/page-patterns/dashboard-pages.md) - Metrics and charts
+
+**Learning the Framework:**
+- [Best Practices](./guides/best-practices.md) - Patterns and conventions
+- [Data Fetching](./guides/data-fetching.md) - Collections and models
+- [Error Handling](./guides/error-handling.md) - Validation and API errors
+- [Mobile Subnavigation](./guides/mobile-subnavigation.md) - Mobile navigation hubs with submenus
+- [Menu Configuration](./reference/menu.md) - Navigation menu setup and patterns
+- [Plugins & Utilities](./reference/plugins.md) - $notify, $dayjs, $screen, etc.
+
+**Integration with Other Packages:**
+- [Vue-MC Documentation](../../vue-mc/docs/) - Models and collections for API data
+- [Nuxt-Auth Documentation](../../nuxt-auth/docs/) - Authentication, 2FA, OAuth
+- [Nuxt-Laravel Documentation](../../nuxt-laravel/docs/) - Laravel backend integration
+
+## Component System Architecture
+
+The component library is organized into 5 categories following atomic design principles:
+
+### 1. Atoms (`1_atoms/`)
+Simple, reusable components that are wrappers around HTML elements with consistent styling. These components are **globally imported** and always available.
+
+**Import Method:** Global (automatically registered)
+
+**Components:**
+- [AwAccordionFold](components/atoms/aw-accordion-fold.md) - Collapsible content wrapper
+- [AwActionCard](components/atoms/aw-action-card.md) - Card with title and action button
+- [AwActionCardBody](components/atoms/aw-action-card-body.md) - Body section for action cards
+- [AwActionIcon](components/atoms/aw-action-icon.md) - Icon with optional text
+- [AwAvatar](components/atoms/aw-avatar.md) - User avatar component
+- [AwCard](components/atoms/aw-card.md) - Basic card container
+- [AwCheckbox](components/atoms/aw-checkbox.md) - Checkbox input
+- [AwContentPlaceholder](components/atoms/aw-content-placeholder.md) - Loading placeholder with shimmer effect
+- [AwDescription](components/atoms/aw-description.md) - Description text wrapper
+- [AwDock](components/atoms/aw-dock.md) - Slide-up panel component
+- [AwDropdown](components/atoms/aw-dropdown.md) - Dropdown menu
+- [AwDropdownButton](components/atoms/aw-dropdown-button.md) - Dropdown trigger button
+- [AwFile](components/atoms/aw-file.md) - File input wrapper
+- [AwFlow](components/atoms/aw-flow.md) - Flow layout component
+- [AwGrid](components/atoms/aw-grid.md) - Grid layout component
+- [AwHeadline](components/atoms/aw-headline.md) - Heading component
+- [AwIcon](components/atoms/aw-icon.md) - Icon component
+- [AwIconSystemColor](components/atoms/aw-icon-system-color.md) - Multicolor system icons
+- [AwIconSystemMono](components/atoms/aw-icon-system-mono.md) - Monochrome system icons
+- [AwInfo](components/atoms/aw-info.md) - Info display component
+- [AwInput](components/atoms/aw-input.md) - Text input component
+- [AwLabel](components/atoms/aw-label.md) - Label/badge component
+- [AwLink](components/atoms/aw-link.md) - Link component
+- [AwList](components/atoms/aw-list.md) - List component
+- [AwProgress](components/atoms/aw-progress.md) - Progress bar
+- [AwRadio](components/atoms/aw-radio.md) - Radio button input
+- [AwRefreshWrapper](components/atoms/aw-refresh-wrapper.md) - Pull-to-refresh wrapper
+- [AwSelectNative](components/atoms/aw-select-native.md) - Native select dropdown
+- [AwSlider](components/atoms/aw-slider.md) - Slider input
+- [AwSubHeadline](components/atoms/aw-sub-headline.md) - Sub-heading component
+- [AwSwitcher](components/atoms/aw-switcher.md) - Toggle switch
+- [AwTag](components/atoms/aw-tag.md) - Tag component
+- [AwTitle](components/atoms/aw-title.md) - Title component
+- [AwToggler](components/atoms/aw-toggler.md) - Toggleable content wrapper
+
+### 2. Molecules (`2_molecules/`)
+Components that combine atoms with additional logic. Most are **dynamically imported**, except `AwSelect` which is global for compatibility.
+
+**Import Method:** Global (most), Dynamic (some)
+
+**Components:**
+- [AwActionButton](components/molecules/aw-action-button.md) - Action button with icon and descriptions
+- [AwAlert](components/molecules/aw-alert.md) - Alert message component
+- [AwBadge](components/molecules/aw-badge.md) - Badge component
+- [AwBannerText](components/molecules/aw-banner-text.md) - Banner with icon and text
+- [AwButton](components/molecules/aw-button.md) - Button component
+- [AwButtonNav](components/molecules/aw-button-nav.md) - Navigation button
+- [AwDescriptionInput](components/molecules/aw-description-input.md) - Input with description
+- [AwEmptyContainer](components/molecules/aw-empty-container.md) - Empty state container
+- [AwIsland](components/molecules/aw-island.md) - Island component
+- [AwSelect](components/molecules/aw-select.md) - Advanced select component (global)
+- [AwSelectObject](components/molecules/aw-select-object.md) - Select for object options
+- [AwTabNav](components/molecules/aw-tab-nav.md) - Tab navigation
+- [AwTel](components/molecules/aw-tel.md) - Telephone input
+- [AwTextarea](components/molecules/aw-textarea.md) - Textarea input
+- [AwUserpic](components/molecules/aw-userpic.md) - User picture component
+
+### 3. Organisms (`3_organisms/`)
+Complex components built for specific tasks, combining atoms and molecules. These are **dynamically imported**.
+
+**Import Method:** Dynamic
+
+**Components:**
+- [AwAddress](components/organisms/aw-address.md) - Address input component
+- [AwAddressBlock](components/organisms/aw-address-block.md) - Address display block
+- [AwBirthdayPicker](components/organisms/aw-birthday-picker.md) - Birthday date picker
+- [AwBottomBar](components/organisms/aw-bottom-bar.md) - Bottom action bar
+- [AwCalendar](components/organisms/aw-calendar.md) - Calendar component
+- [AwChart](components/organisms/aw-chart.md) - Chart component
+- [AwChip](components/organisms/aw-chip.md) - Chip component
+- [AwChipSelect](components/organisms/aw-chip-select.md) - Chip selection component
+- [AwCode](components/organisms/aw-code.md) - Code input component
+- [AwCodeSnippet](components/organisms/aw-code-snippet.md) - Code snippet display
+- [AwContextMenu](components/organisms/aw-context-menu.md) - Context menu
+- [AwCropper](components/organisms/aw-cropper.md) - Image cropper
+- [AwDate](components/organisms/aw-date.md) - Date input
+- [AwDisplayDate](components/organisms/aw-display-date.md) - Date display
+- [AwDownloadLink](components/organisms/aw-download-link.md) - Download link
+- [AwFetchData](components/organisms/aw-fetch-data.md) - Data fetching wrapper
+- [AwFilterChosen](components/organisms/aw-filter-chosen.md) - Display active filters as chips
+- [AwFilterDateRange](components/organisms/aw-filter-date-range.md) - Date range filter
+- [AwFilterMonth](components/organisms/aw-filter-month.md) - Month filter
+- [AwFilterSelect](components/organisms/aw-filter-select.md) - Dropdown filter
+- [AwForm](components/organisms/aw-form.md) - Form component
+- [AwGmap](components/organisms/aw-gmap.md) - Google Maps component
+- [AwGmapMarker](components/organisms/aw-gmap-marker.md) - Google Maps marker
+- [AwImageUpload](components/organisms/aw-image-upload.md) - Image upload component
+- [AwIslandAvatar](components/organisms/aw-island-avatar.md) - Avatar in island
+- [AwMarkdownEditor](components/organisms/aw-markdown-editor.md) - Markdown editor
+- [AwModal](components/organisms/aw-modal.md) - Modal dialog
+- [AwModalButtons](components/organisms/aw-modal-buttons.md) - Modal button group
+- [AwModelEdit](components/organisms/aw-model-edit.md) - Model edit form
+- [AwMoney](components/organisms/aw-money.md) - Money input
+- [AwMultiBlockBuilder](components/organisms/aw-multi-block-builder.md) - Multi-block builder
+- [AwPagination](components/organisms/aw-pagination.md) - Pagination component
+- [AwPassword](components/organisms/aw-password.md) - Password input
+- [AwPreviewCard](components/organisms/aw-preview-card.md) - Preview card
+- [AwSearch](components/organisms/aw-search.md) - Search input
+- [AwSubnav](components/organisms/aw-subnav.md) - Sub-navigation
+- [AwTable](components/organisms/aw-table.md) - Table component
+- [AwTableBuilder](components/organisms/aw-table-builder.md) - Table builder
+- [AwTags](components/organisms/aw-tags.md) - Tags component
+- [AwToggleShowAside](components/organisms/aw-toggle-show-aside.md) - Toggle aside navigation
+- [AwUploader](components/organisms/aw-uploader.md) - File uploader
+- [AwUploaderFiles](components/organisms/aw-uploader-files.md) - Uploaded files display
+
+### 4. Pages (`4_pages/`)
+Top-level components for building complete pages. These are **dynamically imported**.
+
+**Import Method:** Dynamic
+
+**Components:**
+- [AwPage](components/pages/aw-page.md) - Main page component
+- [AwPageAside](components/pages/aw-page-aside.md) - Page layout with sidebar
+- [AwPageMenuButtons](components/pages/aw-page-menu-buttons.md) - Page menu buttons
+- ~~[AwPageModal](components/pages/aw-page-modal.md)~~ - (deprecated, not commonly used)
+- [AwPageSingle](components/pages/aw-page-single.md) - Single page layout
+
+### 5. Layouts (`5_layouts/`)
+Root-level components that control the overall page layout and navigation. These are **dynamically imported**.
+
+**Import Method:** Dynamic
+
+**Components:**
+- [AwLayout](components/layouts/aw-layout.md) - Default layout with navigation
+- [AwLayoutCenter](components/layouts/aw-layout-center.md) - Centered layout
+- [AwLayoutError](components/layouts/aw-layout-error.md) - Error page layout
+- [AwLayoutProvider](components/layouts/aw-layout-provider.md) - Layout provider (menu management)
+
+## Import Methods
+
+### Global Components
+Atoms and most molecules are registered globally via the Nuxt module. They can be used directly in templates without importing:
+
+```markup
+<template>
+  <AwButton>Click me</AwButton>
+  <AwInput v-model="value" />
+</template>
+```
+
+### Dynamic Components
+Organisms, pages, and layouts are dynamically imported. They can be used in two ways:
+
+1. **Direct usage** (Nuxt auto-imports):
+```markup
+<template>
+  <AwForm url="/api/submit">
+    <!-- form content -->
+  </AwForm>
+</template>
+```
+
+2. **Explicit import** (for better tree-shaking):
+```markup
+<script>
+export default {
+  components: {
+    AwForm: () => import('@awes-io/ui/components/3_organisms/AwForm.vue')
+  }
+}
+</script>
+```
+
+## Configuration
+
+Components can be configured globally via `awes.config.js` in your project:
+
+```javascript
+export default {
+  AwButton: {
+    size: 'md',
+    color: 'accent',
+    theme: 'solid'
+  },
+  AwInput: {
+    baseClass: 'aw-text-field',
+    sizes: ['sm', 'md']
+  }
+}
+```
+
+See individual component documentation for available configuration options.
+
+## Store Integration
+
+The library integrates with Vuex via the `awesIo` store module, which manages:
+- Navigation menus (main, secondary, user, tertiary)
+- Route tracking
+- Dark theme state
+- Screen breakpoints
+- Logo configuration
+- User profile information
+
+See [packages/ui/store/awesIo.js](../store/awesIo.js) for details.
+
+## Plugins
+
+The Nuxt module provides several plugins:
+- **core.plugin.js** - Core utilities (`$awes`, `$notify`)
+- **store.plugin.js** - Vuex store integration
+- **screen.plugin.js** - Responsive screen breakpoints (`$screen`)
+- **router.plugin.js** - Router extensions (`router.setBack`, `router.pushBack`)
+- **dark-theme.plugin.js** - Dark theme management
+- **permissions.plugin.js** - CASL permissions integration
+- **dayjs.plugin.js** - Day.js date library integration
+- **directives.plugin.js** - Vue directives (tooltip)
+
+## Usage Examples
+
+See the [examples](../examples) folder for live usage examples of each component.
+
+## Related Documentation
+
+- [Component Configuration](../components/_config.js) - Default component configurations
+- [Store Module](../store/awesIo.js) - Vuex store module
+- [Nuxt Module](../nuxt/index.js) - Module registration and setup