# 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