@vc-shell/create-vc-app 1.1.98-rc.5 → 1.1.99-alpha.0

package/dist/templates/base/ai-guides/guides/ui-components-reference.md

@@ -0,0 +1,903 @@
+# UI Components Reference
+
+Complete reference for all 45 UI components in VC-Shell framework, organized by category.
+
+## Atoms (20 components)
+
+### VcBadge
+**Purpose**: Notification badge for status indicators
+
+**Props**:
+- `content`: string | number - Badge content
+- `active`: boolean - Active state
+- `disabled`: boolean - Disabled state
+- `clickable`: boolean - Makes badge clickable
+- `size`: 's' | 'm' - Size variant
+- `isDot`: boolean - Show as dot
+- `variant`: 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'secondary' - Color variant
+- `customPosition`: boolean - Custom positioning
+- `top`: string - Top position
+- `right`: string - Right position
+
+**Events**:
+- `click` - Click event
+
+**Slots**:
+- `default` - Badge content
+
+**Example**:
+```vue
+<VcBadge :content="5" variant="danger" />
+```
+
+### VcButton
+**Purpose**: Action button with icons
+
+**Props**:
+- `icon`: string - Icon name
+- `iconClass`: string - Icon CSS class
+- `iconSize`: string - Icon size
+- `variant`: 'primary' | 'secondary' - Button variant
+- `disabled`: boolean - Disabled state
+- `size`: 'xs' | 'sm' | 'base' - Button size
+- `selected`: boolean - Selected state
+- `text`: string - Button text
+
+**Events**:
+- `click` - Click event
+
+**Slots**:
+- `default` - Button content
+
+**Example**:
+```vue
+<VcButton icon="save" variant="primary" @click="handleSave">Save</VcButton>
+```
+
+### VcCard
+**Purpose**: Container card with header
+
+**Props**:
+- `header`: string - Header text
+- `icon`: string - Header icon
+- `isCollapsable`: boolean - Can collapse
+- `isCollapsed`: boolean - Collapsed state
+- `fill`: boolean - Fill container
+- `variant`: 'default' | 'success' | 'danger' - Card variant
+
+**Events**:
+- `header:click` - Header click
+- `state:collapsed` - Collapse state change
+
+**Slots**:
+- `default` - Card content
+- `actions` - Header actions
+- `header` - Custom header
+
+**Example**:
+```vue
+<VcCard header="Details" icon="info">
+  Content here
+</VcCard>
+```
+
+### VcCol
+**Purpose**: Column in grid layout
+
+**Props**:
+- `size`: number - Column size (1-12)
+
+**Slots**:
+- `default` - Column content
+
+**Example**:
+```vue
+<VcCol :size="6">Left column</VcCol>
+```
+
+### VcContainer
+**Purpose**: Scrollable container
+
+**Props**:
+- `shadow`: boolean - Show shadow
+- `noPadding`: boolean - Remove padding
+- `usePtr`: boolean - Pull to refresh
+
+**Events**:
+- `scroll:ptr` - Pull to refresh
+- `scroll` - Scroll event
+
+**Methods**:
+- `scrollTop()` - Scroll to top
+
+**Example**:
+```vue
+<VcContainer @scroll="handleScroll">
+  Content
+</VcContainer>
+```
+
+### VcHint
+**Purpose**: Helper text
+
+**Slots**:
+- `default` - Hint text
+
+**Example**:
+```vue
+<VcHint>This field is required</VcHint>
+```
+
+### VcIcon
+**Purpose**: Universal icon component
+
+**Props**:
+- `icon`: string - Icon name (material-, bi-, lucide-, fas fa-, svg:)
+- `size`: 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl' | 'xxxl' - Icon size
+- `variant`: 'warning' | 'danger' | 'success' - Icon variant
+- `customSize`: string - Custom size
+- `useContainer`: boolean - Use container
+
+**Example**:
+```vue
+<VcIcon icon="material-save" size="m" />
+```
+
+### VcImage
+**Purpose**: Image display
+
+**Props**:
+- `src`: string - Image source
+- `alt`: string - Alt text
+- `size`: string - Image size
+- `aspectRatio`: string - Aspect ratio
+- `bordered`: boolean - Show border
+- `rounded`: boolean - Rounded corners
+
+**Example**:
+```vue
+<VcImage src="/path/to/image.jpg" alt="Product" />
+```
+
+### VcLabel
+**Purpose**: Form label
+
+**Props**:
+- `text`: string - Label text
+- `required`: boolean - Required indicator
+
+**Slots**:
+- `default` - Label content
+
+**Example**:
+```vue
+<VcLabel text="Name" :required="true" />
+```
+
+### VcLink
+**Purpose**: Navigation link
+
+**Props**:
+- `to`: string - Router link
+- `href`: string - External link
+- `target`: string - Link target
+
+**Slots**:
+- `default` - Link text
+
+**Example**:
+```vue
+<VcLink to="/products">Products</VcLink>
+```
+
+### VcLoading
+**Purpose**: Loading indicator
+
+**Props**:
+- `active`: boolean - Show loading
+
+**Example**:
+```vue
+<VcLoading :active="loading" />
+```
+
+### VcProgress
+**Purpose**: Progress bar
+
+**Props**:
+- `value`: number - Progress value (0-100)
+- `variant`: string - Progress variant
+
+**Example**:
+```vue
+<VcProgress :value="75" />
+```
+
+### VcRow
+**Purpose**: Row in grid layout
+
+**Slots**:
+- `default` - Row content
+
+**Example**:
+```vue
+<VcRow>
+  <VcCol :size="6">Content</VcCol>
+</VcRow>
+```
+
+### VcSkeleton
+**Purpose**: Loading skeleton
+
+**Props**:
+- `variant`: 'text' | 'circle' | 'rect' - Skeleton variant
+- `width`: string - Width
+- `height`: string - Height
+- `count`: number - Number of skeletons
+
+**Example**:
+```vue
+<VcSkeleton variant="text" :count="3" />
+```
+
+### VcStatus
+**Purpose**: Status indicator
+
+**Props**:
+- `variant`: string - Status variant
+- `outline`: boolean - Outline style
+- `extend`: boolean - Extended style
+
+**Slots**:
+- `default` - Status text
+
+**Example**:
+```vue
+<VcStatus variant="success">Active</VcStatus>
+```
+
+### VcStatusIcon
+**Purpose**: Status icon
+
+**Props**:
+- `variant`: string - Status variant
+
+**Example**:
+```vue
+<VcStatusIcon variant="success" />
+```
+
+### VcTooltip
+**Purpose**: Tooltip for help text
+
+**Props**:
+- `text`: string - Tooltip text
+- `placement`: string - Tooltip placement
+- `width`: string - Tooltip width
+- `maxWidth`: string - Max width
+
+**Slots**:
+- `default` - Trigger element
+
+**Example**:
+```vue
+<VcTooltip text="Help text">
+  <VcIcon icon="help" />
+</VcTooltip>
+```
+
+### VcVideo
+**Purpose**: Video player
+
+**Props**:
+- `src`: string - Video source
+- `poster`: string - Poster image
+- `controls`: boolean - Show controls
+- `autoplay`: boolean - Autoplay
+- `loop`: boolean - Loop video
+- `muted`: boolean - Muted
+
+**Example**:
+```vue
+<VcVideo src="/video.mp4" :controls="true" />
+```
+
+### VcWidget
+**Purpose**: Dashboard widget
+
+**Props**:
+- `title`: string - Widget title
+- `icon`: string - Widget icon
+- `value`: string | number - Widget value
+- `loading`: boolean - Loading state
+
+**Events**:
+- `click` - Click event
+
+**Example**:
+```vue
+<VcWidget title="Orders" icon="shopping_cart" :value="42" />
+```
+
+### VcBanner
+**Purpose**: Banner message
+
+**Props**:
+- `variant`: string - Banner variant
+- `icon`: string - Banner icon
+- `iconSize`: string - Icon size
+- `iconVariant`: string - Icon variant
+
+**Slots**:
+- `title` - Banner title
+- `default` - Banner content
+- `trigger` - Trigger element
+
+**Example**:
+```vue
+<VcBanner variant="info">
+  <template #title>Information</template>
+  Banner content
+</VcBanner>
+```
+
+## Molecules (18 components)
+
+### VcBreadcrumbs
+**Purpose**: Navigation breadcrumbs
+
+**Props**:
+- `items`: Array<{id: string, title: string, icon?: string}> - Breadcrumb items
+
+**Events**:
+- `item:click` - Item click event
+
+**Example**:
+```vue
+<VcBreadcrumbs :items="breadcrumbItems" />
+```
+
+### VcCheckbox
+**Purpose**: Checkbox input
+
+**Props**:
+- `modelValue`: boolean - Checked state
+- `label`: string - Checkbox label
+- `disabled`: boolean - Disabled state
+- `errorMessage`: string - Error message
+- `hint`: string - Helper text
+
+**Events**:
+- `update:modelValue` - Value change
+
+**Example**:
+```vue
+<VcCheckbox v-model="checked" label="I agree" />
+```
+
+### VcEditor
+**Purpose**: Rich text editor (TipTap)
+
+**Props**:
+- `modelValue`: string - Editor content
+- `placeholder`: string - Placeholder text
+- `editable`: boolean - Editable state
+- `customToolbar`: boolean - Custom toolbar
+
+**Events**:
+- `update:modelValue` - Content change
+
+**Example**:
+```vue
+<VcEditor v-model="content" placeholder="Enter text" />
+```
+
+### VcField
+**Purpose**: Form field wrapper
+
+**Props**:
+- `label`: string - Field label
+- `required`: boolean - Required indicator
+- `errorMessage`: string - Error message
+- `hint`: string - Helper text
+- `tooltip`: string - Tooltip text
+
+**Slots**:
+- `default` - Field input
+
+**Example**:
+```vue
+<VcField label="Name" :required="true">
+  <VcInput v-model="name" />
+</VcField>
+```
+
+### VcForm
+**Purpose**: Form container (VeeValidate)
+
+**Events**:
+- `submit` - Form submit
+
+**Slots**:
+- `default` - Form content
+
+**Example**:
+```vue
+<VcForm @submit="handleSubmit">
+  <!-- form fields -->
+</VcForm>
+```
+
+### VcInput
+**Purpose**: Text input
+
+**Props**:
+- `modelValue`: string - Input value
+- `label`: string - Input label
+- `placeholder`: string - Placeholder text
+- `type`: string - Input type
+- `disabled`: boolean - Disabled state
+- `required`: boolean - Required indicator
+- `clearable`: boolean - Show clear button
+- `errorMessage`: string - Error message
+- `tooltip`: string - Tooltip text
+- `maxlength`: number - Max length
+- `prefix`: string - Prefix text
+- `suffix`: string - Suffix text
+
+**Events**:
+- `update:modelValue` - Value change
+- `blur` - Blur event
+- `focus` - Focus event
+- `clear` - Clear event
+
+**Example**:
+```vue
+<VcInput 
+  v-model="name" 
+  label="Name" 
+  placeholder="Enter name"
+  :required="true"
+/>
+```
+
+### VcInputCurrency
+**Purpose**: Currency input
+
+**Props**:
+- `modelValue`: number - Currency value
+- `label`: string - Field label
+- `currency`: string - Currency code
+- `locale`: string - Locale
+- `disabled`: boolean - Disabled state
+- `required`: boolean - Required indicator
+- `errorMessage`: string - Error message
+
+**Events**:
+- `update:modelValue` - Value change
+
+**Example**:
+```vue
+<VcInputCurrency v-model="price" label="Price" currency="USD" />
+```
+
+### VcInputDropdown
+**Purpose**: Input with dropdown
+
+**Props**:
+- `modelValue`: string - Input value
+- `option`: any - Selected option
+- `options`: Array<any> - Options list
+- `label`: string - Field label
+- `placeholder`: string - Placeholder text
+- `disabled`: boolean - Disabled state
+
+**Events**:
+- `update:modelValue` - Value change
+- `update:option` - Option change
+
+**Example**:
+```vue
+<VcInputDropdown 
+  v-model="search" 
+  :options="options"
+  placeholder="Search..."
+/>
+```
+
+### VcMultivalue
+**Purpose**: Multi-value input
+
+**Props**:
+- `modelValue`: Array<any> - Selected values
+- `placeholder`: string - Placeholder text
+- `disabled`: boolean - Disabled state
+- `dictionary`: Array<any> - Dictionary values
+
+**Events**:
+- `update:modelValue` - Values change
+
+**Example**:
+```vue
+<VcMultivalue v-model="tags" placeholder="Add tags" />
+```
+
+### VcPagination
+**Purpose**: Pagination controls
+
+**Props**:
+- `pages`: number - Total pages
+- `currentPage`: number - Current page
+- `maxVisiblePages`: number - Max visible pages
+
+**Events**:
+- `itemClick` - Page click
+
+**Example**:
+```vue
+<VcPagination 
+  :pages="totalPages" 
+  :current-page="currentPage"
+  @item-click="handlePageChange"
+/>
+```
+
+### VcRadioButton
+**Purpose**: Radio button
+
+**Props**:
+- `modelValue`: any - Selected value
+- `value`: any - Radio value
+- `label`: string - Radio label
+- `name`: string - Radio name
+- `disabled`: boolean - Disabled state
+
+**Events**:
+- `update:modelValue` - Value change
+
+**Example**:
+```vue
+<VcRadioButton 
+  v-model="selected" 
+  value="option1" 
+  label="Option 1"
+/>
+```
+
+### VcRating
+**Purpose**: Star rating
+
+**Props**:
+- `modelValue`: number - Rating value
+- `max`: number - Max rating
+- `readonly`: boolean - Readonly state
+- `size`: string - Star size
+
+**Events**:
+- `update:modelValue` - Rating change
+
+**Example**:
+```vue
+<VcRating v-model="rating" :max="5" />
+```
+
+### VcSelect
+**Purpose**: Dropdown select with async search
+
+**Props**:
+- `modelValue`: any - Selected value
+- `options`: Array<any> - Options list
+- `label`: string - Field label
+- `placeholder`: string - Placeholder text
+- `multiple`: boolean - Multiple selection
+- `searchable`: boolean - Searchable
+- `clearable`: boolean - Clearable
+- `disabled`: boolean - Disabled state
+- `loading`: boolean - Loading state
+- `errorMessage`: string - Error message
+- `optionValue`: string - Option value field
+- `optionLabel`: string - Option label field
+- `searchMethod`: Function - Search method
+- `tooltip`: string - Tooltip text
+
+**Events**:
+- `update:modelValue` - Value change
+- `search` - Search event
+- `open` - Open event
+- `close` - Close event
+
+**Example**:
+```vue
+<VcSelect 
+  v-model="category" 
+  :options="categories"
+  label="Category"
+  searchable
+/>
+```
+
+### VcSlider
+**Purpose**: Range slider
+
+**Props**:
+- `modelValue`: number - Slider value
+- `min`: number - Minimum value
+- `max`: number - Maximum value
+- `step`: number - Step value
+- `disabled`: boolean - Disabled state
+
+**Events**:
+- `update:modelValue` - Value change
+
+**Example**:
+```vue
+<VcSlider v-model="value" :min="0" :max="100" :step="1" />
+```
+
+### VcSwitch
+**Purpose**: Toggle switch
+
+**Props**:
+- `modelValue`: boolean - Switch state
+- `label`: string - Switch label
+- `disabled`: boolean - Disabled state
+
+**Events**:
+- `update:modelValue` - State change
+
+**Example**:
+```vue
+<VcSwitch v-model="enabled" label="Enable feature" />
+```
+
+### VcTextarea
+**Purpose**: Multi-line text input
+
+**Props**:
+- `modelValue`: string - Textarea value
+- `label`: string - Field label
+- `placeholder`: string - Placeholder text
+- `rows`: number - Number of rows
+- `maxlength`: number - Max length
+- `disabled`: boolean - Disabled state
+- `required`: boolean - Required indicator
+- `errorMessage`: string - Error message
+
+**Events**:
+- `update:modelValue` - Value change
+
+**Example**:
+```vue
+<VcTextarea 
+  v-model="description" 
+  label="Description"
+  :rows="5"
+/>
+```
+
+### VcToast
+**Purpose**: Toast notification
+
+**Props**:
+- `variant`: string - Toast variant
+- `text`: string - Toast text
+- `timeout`: number - Auto-close timeout
+- `closable`: boolean - Show close button
+
+**Usage via API**:
+```typescript
+notification.success('Success message');
+notification.error('Error message');
+```
+
+## Organisms (7 components)
+
+### VcApp
+**Purpose**: Application shell
+
+**Props**:
+- `disableMenu`: boolean - Disable menu
+- `disableAppSwitcher`: boolean - Disable app switcher
+- `version`: string - App version
+- `avatar`: string - User avatar
+- `name`: string - User name
+- `role`: string - User role
+- `appsList`: Array<any> - Apps list
+- `isEmbedded`: boolean - Embedded mode
+
+**Events**:
+- `menuItemClick` - Menu item click
+- `switchApp` - App switch
+
+**Slots**:
+- `navmenu` - Navigation menu
+- `userDropdown` - User dropdown
+- `appSwitcher` - App switcher
+- `toolbar` - Toolbar
+- `default` - Main content
+
+### VcBlade
+**Purpose**: Blade container
+
+**Props**:
+- `title`: string - Blade title
+- `toolbarItems`: IBladeToolbar[] - Toolbar items
+- `expanded`: boolean - Expansion state (required)
+- `closable`: boolean - Can be closed (required)
+- `param`: string - Entity ID (required)
+- `options`: unknown - Additional data (required)
+- `width`: string - Blade width
+- `modified`: boolean - Modified indicator
+
+**Events**:
+- `parent:call` - Communication with parent
+- `close:blade` - Close blade
+- `collapse:blade` - Collapse blade
+- `expand:blade` - Expand blade
+
+**Slots**:
+- `default` - Blade content
+- `toolbar` - Custom toolbar
+- `actions` - Action buttons
+
+**Example**:
+```vue
+<VcBlade 
+  :expanded="true"
+  :closable="true"
+  :param="id"
+  :options="undefined"
+  title="Details"
+>
+  Content
+</VcBlade>
+```
+
+### VcDynamicProperty
+**Purpose**: Dynamic properties form
+
+**Props**:
+- `properties`: Array<any> - Property definitions
+- `modelValue`: any - Property values
+- `disabled`: boolean - Disabled state
+
+**Events**:
+- `update:modelValue` - Values change
+
+**Example**:
+```vue
+<VcDynamicProperty 
+  :properties="properties"
+  v-model="values"
+/>
+```
+
+### VcGallery
+**Purpose**: Image gallery
+
+**Props**:
+- `images`: Array<string> - Image URLs
+- `activeIndex`: number - Active image index
+
+**Events**:
+- `update:activeIndex` - Index change
+- `close` - Close gallery
+
+**Example**:
+```vue
+<VcGallery :images="images" v-model:active-index="index" />
+```
+
+### VcLoginForm
+**Purpose**: Login form
+
+**Props**:
+- `logo`: string - Logo URL
+- `title`: string - Form title
+
+**Events**:
+- `submit` - Form submit
+
+**Example**:
+```vue
+<VcLoginForm @submit="handleLogin" />
+```
+
+### VcPopup
+**Purpose**: Modal popup
+
+**Props**:
+- `modelValue`: boolean - Show popup
+- `title`: string - Popup title
+- `variant`: string - Popup variant
+- `width`: string - Popup width
+- `maxWidth`: string - Max width
+- `closable`: boolean - Show close button
+
+**Events**:
+- `update:modelValue` - Visibility change
+- `close` - Close event
+
+**Slots**:
+- `default` - Popup content
+- `actions` - Action buttons
+- `title` - Custom title
+
+**Example**:
+```vue
+<VcPopup v-model="showPopup" title="Confirm">
+  <template #actions>
+    <VcButton @click="confirm">Confirm</VcButton>
+  </template>
+</VcPopup>
+```
+
+### VcTable
+**Purpose**: Data table with sorting, pagination, selection
+
+**Props**:
+- `items`: Array<any> - Table items
+- `columns`: ITableColumn[] - Column definitions
+- `loading`: boolean - Loading state
+- `selectedItemId`: string - Selected item ID
+- `totalCount`: number - Total items count
+- `pages`: number - Total pages
+- `currentPage`: number - Current page
+- `enableItemActions`: boolean - Enable row actions
+- `itemActionBuilder`: Function - Action builder
+- `multiselect`: boolean - Multiple selection
+- `stateKey`: string - State persistence key
+
+**Events**:
+- `itemClick` - Item click
+- `selectionChanged` - Selection change
+- `headerClick` - Header click
+- `pageChanged` - Page change
+- `reorder` - Column reorder
+
+**Slots**:
+- `header` - Custom header
+- `filters` - Filter row
+- `mobile-item` - Mobile item template
+- `item_[field]` - Custom field cell
+- `header_[field]` - Custom header cell
+- `notfound` - No results template
+- `empty` - Empty state template
+- `footer` - Table footer
+
+**Column Definition**:
+```typescript
+interface ITableColumn {
+  id: string;
+  title: string;
+  field: string;
+  type?: string;
+  sortable?: boolean;
+  width?: number | string;
+  alwaysVisible?: boolean;
+}
+```
+
+**Example**:
+```vue
+<VcTable 
+  :items="items"
+  :columns="columns"
+  :loading="loading"
+  @item-click="handleItemClick"
+/>
+```
+
+## Best Practices
+
+1. Always use proper TypeScript types
+2. Handle all events appropriately
+3. Use slots for customization
+4. Follow component naming (Vc prefix)
+5. Use proper validation with VeeValidate
+6. Implement loading states
+7. Handle errors gracefully
+8. Use localization for text
+9. Follow accessibility guidelines
+10. Test all component interactions
+