You have unread messages
This is scrollable content inside a container.
The container will automatically handle overflow and scrolling.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Vivamus pellentesque tortor id lacus viverra, ut mollis libero auctor.
Curabitur viverra, justo eu convallis pulvinar, dui nisi luctus quam.
This content has no padding from the container, allowing it to extend all the way to the edges.
Content can define its own padding as needed.
Another section with a different background.
VcContainer is often used to create scrollable panels within a larger layout.
Note: This component handles overflow automatically.
You can include various types of content including:
Add as much content as needed, and the container will handle scrolling.
- Paragraph {{ n }} -
Content length: {{ content.length }} characters
{{ product.description }}
Size: 1
Size: 2
This is card content for card {{ i }}.
This is the main content area that takes up more space with a size of 3.
Description for sub-item {{ i }}.
Additional content can go here.
This content will stack vertically on mobile.
{{ size }}
Current value: {{ amount }} {{ currency }}
Selected categories: {{ selectedValues.length }}
This is the content of the popup.
This action will save the current version of your document.
Are you sure you want to delete this item? This action cannot be undone.
Unable to save changes. Please check your connection and try again.
Error code: 503
This feature is only available to premium subscribers.
- Upload complete! -
Selected Product:
Name: {{ selectedProduct.name }}
Price: ${{ selectedProduct.price }}
Select your preferred contact method:
{{ slide.comment }}
There was an error processing your request. Please try again later.
- This tutorial will guide you through the basic features of our product and help you get started quickly. - Watch the full video for step-by-step instructions. -
Received param: {{ props.param }}
Source: {{ props.options.source }}
Form to edit a review will go here.
By User ID: {{ review.userId }} on {{ review.reviewDate }}
{{ review.comment }}
Currently open: {{ openItem }}
{{ selected.length }} items selected
+ {{ item.name }} +
Nothing matched your search.
` for format examples. +- Multiple VcHint components can stack below a single field. They render as block-level elements with no built-in margin, so add `tw-mt-1` or a parent with `tw-space-y-1` for spacing. + +## Accessibility + +- When `error` is true, the hint renders with `role="alert"` for live screen reader announcement +- Use the `id` prop with `aria-describedby` on the associated input to create a programmatic link +- Muted color styling differentiates hints from primary content visually + +## Related Components + +- [VcLabel](../misc/vc-label.md) -- field label component, typically placed above the input +- [VcBanner](./vc-banner.md) -- for longer or more prominent alert messages +- [VcInput](../form/vc-input.md) -- form input component often paired with VcHint + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-loading.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-loading.md new file mode 100644 index 0000000000..7a60b2093c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-loading.md @@ -0,0 +1,150 @@ + + + + + +# VcLoading + +A lightweight animated loading overlay that displays a sweeping progress bar over its parent container. The overlay uses a translucent backdrop with a subtle blur effect, drawing user attention to the animated bar while keeping the underlying content partially visible so users retain context about what is loading. + + + + Open in Storybook ↗ + + +## When to Use + +- Show loading state while fetching data for a blade, card, or section +- Overlay a form or table during save/submit operations +- Indicate background processing after a user action (e.g., bulk update) +- When NOT to use: full-page loading screens (use a page-level spinner instead); determinate progress with a known percentage (use [VcProgress](./vc-progress.md) instead) + +## Basic Usage + +```vue + + + + Your content here + + + + +``` + +> **Important:** The parent container must have `position: relative` (or `absolute`/`fixed`) so the overlay positions correctly. VcLoading uses `position: absolute` internally. + +## Key Props + +| Prop | Type | Default | Description | +| -------- | --------- | ------- | --------------------------- | +| `active` | `boolean` | `false` | Controls overlay visibility | + +## CSS Custom Properties + +| Variable | Default | Description | +| ---------------------- | ----------------------- | ----------------------------- | +| `--loading-bar-color` | `var(--primary-500)` | Progress bar fill color | +| `--loading-bar-track` | `var(--primary-100)` | Progress bar track background | +| `--loading-overlay-bg` | `rgba(255,255,255,0.6)` | Overlay background color | +| `--loading-bar-width` | `140px` | Width of the progress bar | +| `--loading-bar-height` | `4px` | Height of the progress bar | +| `--loading-z-index` | `9998` | Z-index of the overlay layer | + + + + Open in Storybook ↗ + + +## Recipe: Loading State in a Blade + +Blades have a built-in loading mechanism, but you can use VcLoading to cover a specific section within a blade body — for example, loading a chart or a related-items panel independently. + +```vue + + + + + + + + + + + +``` + +## Recipe: Toggle Loading on Async Operations + +```vue + +``` + +## Recipe: Custom Brand Color + +Override the bar color to match a specific status or brand theme: + +```vue + + + + Saving changes... + + +``` + +## Tips + +- VcLoading is hidden with `display: none` when inactive, so it adds zero layout cost when idle. +- The sweep animation runs on a 1.5-second infinite loop using CSS `@keyframes` — no JavaScript timers involved. +- The overlay applies `backdrop-filter: blur(3px)` for a frosted-glass effect. If you need a fully opaque overlay, set `--loading-overlay-bg: rgba(255,255,255,1)`. +- When using inside a scrollable container, the overlay covers only the visible viewport of that container because it is absolutely positioned. + +## Accessibility + +- `role="status"` announces loading state to screen readers +- `aria-busy` reflects the `active` prop +- `aria-live="polite"` provides non-intrusive announcements +- Screen-reader-only text reads "Loading..." when active + +## Related Components + +- **VcBlade** -- blades use VcLoading internally for their loading state +- [VcProgress](./vc-progress.md) -- determinate progress bar when percentage is known + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-popup.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-popup.md new file mode 100644 index 0000000000..6d448c023b --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-popup.md @@ -0,0 +1,595 @@ + + + + + +# VcPopup + +A modal dialog component built on [HeadlessUI Dialog](https://headlessui.com/vue/dialog). Use it for confirmations, alerts, error messages, and focused form interactions that require the user's immediate attention. + +## When to Use + +| Scenario | Component | +| ------------------------------------------------- | ----------- | +| Confirmation prompt ("Delete this item?") | **VcPopup** | +| Error or success alert after an API call | **VcPopup** | +| Short form that must block background interaction | **VcPopup** | +| Side panel for contextual workflows | VcSidebar | +| Stacked detail views (master-detail) | VcBlade | + +!!! tip "Prefer blades for CRUD workflows" +Reserve popups for brief, interruptive interactions such as confirmations and alerts. Use `VcBlade` for CRUD detail views and `VcSidebar` for contextual side panels. + + + + Open in Storybook ↗ + + +--- + +## Quick Start + +```vue + + Open Popup + + + + This is a simple popup with a title and content. + + + OK + + + + + +``` + +--- + +## Features + +### Variants + + + + Open in Storybook ↗ + + +The `variant` prop adds a semantic icon and color to the popup. Available values: `"default"`, `"info"`, `"success"`, `"warning"`, `"error"`. + +```vue + + Your changes have been saved successfully. + + + + Could not reach the server. Please try again later. + +``` + +When `variant` is anything other than `"default"`, a large icon is rendered to the left of the content area: + +| Variant | Icon | Color token | +| --------- | ----------------------- | --------------- | +| `warning` | `lucide-triangle-alert` | `--warning-500` | +| `error` | `lucide-circle-alert` | `--danger-500` | +| `success` | `lucide-circle-check` | `--success-500` | +| `info` | `lucide-info` | `--info-500` | + +### Title + +Pass a string via the `title` prop. For richer markup, use the `#header` slot instead (see [Custom Header](#custom-header)). + +```vue + + + +``` + +### Custom Header + +The `#header` slot replaces the default title text entirely. The close button (X) is rendered outside the slot, so it remains available. + +```vue + + + + + Advanced Settings + + + + + + +``` + +### Dismissal Behavior + +By default a closable popup can be dismissed three ways: + +1. **Close button (X)** in the title bar +2. **Clicking the overlay** backdrop +3. **Pressing Escape** + +Fine-tune each channel independently: + +```vue + + + + +``` + +Set `:closable="false"` to disable all three at once (the close button is hidden, overlay and Escape are blocked). + +> **Important:** When `closeOnOverlay` or `closeOnEscape` are not explicitly set, they inherit the value of `closable`. + +### The `close` Event + +The `close` event carries a `PopupCloseReason` string so you can react differently depending on how the user dismissed the popup: + +```vue + + + + + +``` + +### Slots + +#### `#content` + +The main body of the popup. Place text, form fields, tables, or any Vue template here. + +```vue + + + Are you sure you want to archive 5 items? + This action cannot be undone. + + +``` + +#### `#footer` + +The footer area sits below a separator line. It exposes a scoped `close` function you can call from any button. + +```vue + + + Cancel + Delete + + +``` + +> **Note:** If you omit the `#footer` slot entirely, no footer is rendered. If you provide it without content, a default "Close" button appears via the slot fallback. + +### Controlled Popup (v-model) + +Use `v-model` to bind visibility to a reactive boolean. The popup emits `update:modelValue` on every close attempt. + +```vue + + Open + + Visible state: {{ isOpen }} + + + + +``` + +> **Tip:** You can also use `v-if` instead of `v-model` for a simpler pattern when you do not need animated exit transitions: +> +> ```vue +> +> ``` + +### Custom Width + +The `modalWidth` prop accepts a Tailwind CSS max-width class. The default is `"tw-max-w-md"` (448px). + +```vue + + + + + + + + +``` + +### Fullscreen Mode + +Two props control fullscreen behavior: + +| Prop | Effect | +| -------------------- | ----------------------------------------------------------------------- | +| `isFullscreen` | Full viewport on **all** screen sizes | +| `isMobileFullscreen` | Full viewport on **mobile only** (detected via `IsMobileKey` injection) | + +```vue + + + + + + + +``` + +--- + +## Recipes + +### Confirmation Dialog + + + + Open in Storybook ↗ + + +The most common pattern. Uses the `warning` variant and a two-button footer. + +```vue + + Delete Order + + + Are you sure you want to delete this order? This action cannot be undone. + + + Cancel + Delete + + + + + + +``` + +#### Programmatic Confirmation with `usePopup` + +For toolbar handlers and composables, use the `usePopup()` composable instead of template markup: + +```ts +import { usePopup } from "@vc-shell/framework"; + +const { showConfirmation, showError, showInfo } = usePopup(); + +// Returns a Promise +async function handleDelete() { + const confirmed = await showConfirmation("Are you sure you want to delete this item?"); + if (confirmed) { + await deleteItem(); + } +} +``` + +The composable provides three convenience methods: + +| Method | Variant | Returns | +| --------------------------- | ------- | ------------------ | +| `showConfirmation(message)` | warning | `Promise` | +| `showError(message)` | error | `void` | +| `showInfo(message)` | info | `void` | + +### Popup with Form and Validation + +Use `Field` from `vee-validate` inside the popup content for inline validation. + +```vue + + + + + + + + + + + + + + + + Cancel + Save + + + + + + +``` + +### Error Popup from API Catch + +Display server errors using the programmatic `showError`: + +```ts +import { usePopup } from "@vc-shell/framework"; + +const { showError } = usePopup(); + +async function saveOffer() { + try { + await api.updateOffer(offer.value); + } catch (e: unknown) { + const message = e instanceof Error ? e.message : "An unexpected error occurred."; + showError(message); + } +} +``` + +Or display a richer error popup in-template: + +```vue + + + {{ errorMessage }} + + If the problem persists, contact support. + + + + Dismiss + + +``` + +--- + +## Common Mistakes + +### Forgetting `v-model` or `v-if` + +```vue + + + Stuck open forever. + + + + + Can be opened and closed. + + + + + Mounted only when open. + +``` + +### Not calling `close()` in footer actions + +```vue + + + Confirm + + + + + Confirm + +``` + +### Using `closable="false"` without a close mechanism + +```vue + + + No way out! + + + + + Please acknowledge this message. + + I Understand + + +``` + +--- + +## Props + +| Prop | Type | Default | Description | +| -------------------- | ---------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------- | +| `modelValue` | `boolean` | `undefined` | Controlled visibility via `v-model`. When omitted, the popup is visible if mounted. | +| `title` | `string` | `undefined` | Dialog title text rendered in the header bar. | +| `closable` | `boolean` | `true` | Show the close button (X) and allow dismissal. When `false`, all dismiss channels are disabled. | +| `variant` | `"default" \| "error" \| "warning" \| "success" \| "info"` | `"default"` | Semantic variant that determines the icon and its color. | +| `modalWidth` | `string` | `"tw-max-w-md"` | Tailwind max-width class applied to the dialog panel. | +| `isMobileFullscreen` | `boolean` | `false` | Expand to fullscreen on mobile viewports only. | +| `isFullscreen` | `boolean` | `false` | Expand to fullscreen on all viewports. | +| `closeOnOverlay` | `boolean` | Inherits `closable` | Whether clicking the backdrop overlay closes the popup. | +| `closeOnEscape` | `boolean` | Inherits `closable` | Whether pressing the Escape key closes the popup. | + +## Events + +| Event | Payload | Description | +| ------------------- | ------------------ | ------------------------------------------------------------------------- | +| `update:modelValue` | `boolean` | Emitted with `false` when the popup requests to close. Used by `v-model`. | +| `close` | `PopupCloseReason` | Reason the popup was closed: `"overlay"`, `"escape"`, or `"action"`. | + +## Slots + +| Slot | Scoped Props | Description | +| --------- | ----------------------- | ---------------------------------------------------------------------------------------------- | +| `header` | -- | Replaces the default title text. The close button (X) remains visible beside the slot content. | +| `content` | -- | Main body area of the popup. | +| `footer` | `{ close: () => void }` | Footer area below a separator line. Call `close()` to dismiss the popup from any button. | + +## CSS Custom Properties + +| Variable | Default | Description | +| ---------------------------- | ---------------------- | ------------------------------------ | +| `--popup-border-radius` | `6px` | Border radius of the dialog panel | +| `--popup-shadow` | `var(--shadow-md)` | Box shadow around the panel | +| `--popup-overlay-blur` | `var(--overlay-blur)` | Backdrop blur amount | +| `--popup-bg` | `var(--additional-50)` | Background color of the dialog panel | +| `--popup-header-color` | `var(--primary-700)` | Title text color | +| `--popup-content-text-color` | `var(--primary-700)` | Content text color | +| `--popup-footer-separator` | `var(--neutrals-200)` | Footer top border color | +| `--popup-overlay` | `var(--overlay-bg)` | Overlay background color | + +## Accessibility + +- Built on HeadlessUI `Dialog`, which provides: + - **Focus trap** -- focus is locked inside the popup while open + - **`aria-labelledby`** -- automatically linked to the `DialogTitle` element + - **Inert background** -- content behind the popup is marked inert for screen readers +- **Escape key** handling respects the `closeOnEscape` prop +- **Overlay click** handling respects the `closeOnOverlay` prop +- The close button (X) has an `aria-label` for screen readers +- Animated enter/leave transitions use opacity and scale for smooth motion + +## Related Components + +- **VcSidebar** -- slide-over panel for contextual workflows (not centered modal) +- **VcBlade** -- stacked panel navigation for CRUD detail views +- **`usePopup()`** -- composable for programmatic confirmation, error, and info popups without template markup diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-progress.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-progress.md new file mode 100644 index 0000000000..1696008da8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-progress.md @@ -0,0 +1,191 @@ + + + + + +# VcProgress + +A horizontal progress bar that visualizes the completion percentage of a task or process. The bar fills smoothly from left to right using a CSS `transform` transition, and an optional striped variant adds an animated diagonal pattern to indicate active processing. + + + + Open in Storybook ↗ + + +## When to Use + +- Display upload, import, or export progress +- Show step completion in multi-stage workflows +- Visualize quota usage (e.g., storage consumed out of total) +- When NOT to use: indeterminate loading with no known percentage (use [VcLoading](./vc-loading.md) instead); very short operations where the bar would flash and disappear (skip the indicator) + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ----------- | ------------------------ | ------------ | --------------------------------------------------------- | +| `value` | `number` | `0` | Current progress (0--100). Clamped automatically. | +| `variant` | `"default" \| "striped"` | `"default"` | Visual style; `striped` adds an animated diagonal pattern | +| `ariaLabel` | `string` | `"Progress"` | Accessible label describing what the bar represents | + +## Common Patterns + +### Labeled Progress with Percentage + +```vue + + + + Importing catalog... + {{ progress }}% + + + + +``` + + + + Open in Storybook ↗ + + +### Multiple Progress Stages + +```vue + + + + {{ stage.label }} + + + + +``` + +### Quota / Usage Indicator + +```vue + + + + Storage + {{ usedGB }} / {{ totalGB }} GB + + + + You are running low on storage. + + + +``` + +## Recipe: File Upload Progress in a Blade + +```vue + + + + + + {{ isUploading ? "Uploading..." : "Select File" }} + + + + + {{ uploadProgress }}% complete + + + +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| -------------------------------- | --------------------- | -------------------------- | +| `--progressbar-height` | `8px` | Bar height | +| `--progressbar-border-radius` | `9999px` | Border radius (pill shape) | +| `--progressbar-background-color` | `var(--neutrals-200)` | Track background | +| `--progressbar-foreground-color` | `var(--primary-500)` | Fill color | +| `--progressbar-striped-bg` | gradient | Striped variant background | + +## Tips + +- The `value` prop is clamped between 0 and 100 internally, so passing values outside that range is safe — negative values become 0 and values above 100 become 100. +- The fill transitions smoothly over 300ms with `ease-out` timing. Rapid value updates (e.g., every 50ms) will look fluid. +- The striped variant uses a CSS `@keyframes` animation that runs continuously. It is a good visual cue for "processing" states where progress is advancing but the user should wait. +- To change the bar color dynamically (e.g., red when near quota), override `--progressbar-foreground-color` with an inline style: `style="--progressbar-foreground-color: var(--danger-500)"`. +- For a thinner or thicker bar, set `--progressbar-height` on the parent or component element. + +## Accessibility + +- `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` +- Custom `aria-label` prop for describing the progress context +- Fill transitions smoothly (300ms ease-out) so screen magnifier users can follow changes + +## Related Components + +- [VcLoading](./vc-loading.md) -- indeterminate loading overlay when percentage is unknown +- [VcHint](./vc-hint.md) -- helper text to display percentage or status message below the bar + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-skeleton.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-skeleton.md new file mode 100644 index 0000000000..92479586de --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-skeleton.md @@ -0,0 +1,148 @@ + + + + + +# VcSkeleton + +A loading placeholder component that renders animated shimmer shapes (text lines, circles, or rectangular blocks) to indicate content is being fetched. + + + + Open in Storybook ↗ + + +## When to Use + +- Show placeholder UI while async data loads for blades, lists, or cards +- Preserve layout structure during loading to prevent content shift +- When NOT to use: progress with a known percentage (use [VcProgress](./vc-progress.md)); indeterminate overlay (use [VcLoading](./vc-loading.md)) + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ----------- | ------------------------------- | -------------- | -------------------------------------------------- | +| `variant` | `"text" \| "circle" \| "block"` | `"text"` | Shape variant: text rows, circular, or rectangular | +| `rows` | `number` | `1` | Number of text rows (only for `variant="text"`) | +| `width` | `string \| number` | -- | Custom width for circle/block (number = px) | +| `height` | `string \| number` | -- | Custom height for circle/block (number = px) | +| `animated` | `boolean` | `true` | Enables pulse animation | +| `ariaLabel` | `string` | `"Loading..."` | Screen reader announcement | + +## Common Patterns + +### Text Paragraph Placeholder + +The last row automatically renders at 60% width for a natural paragraph feel. + +```vue + +``` + +### Avatar Placeholder + +```vue + +``` + + + + Open in Storybook ↗ + + +### Card Skeleton + +```vue + + + + + + + + + + + +``` + +### List with Avatar and Text + +```vue + + + + + + + + + + + + + +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ----------------------------- | --------------------- | -------------------------------------- | +| `--vc-skeleton-bg` | `var(--neutrals-200)` | Shape background color | +| `--vc-skeleton-highlight` | `var(--neutrals-300)` | Highlight color (for future shimmer) | +| `--vc-skeleton-border-radius` | `6px` | Corner radius for text rows and blocks | +| `--vc-skeleton-row-height` | `16px` | Height of each text row | +| `--vc-skeleton-row-gap` | `12px` | Vertical gap between text rows | + +## Accessibility + +- `role="status"` with `aria-busy="true"` on all variants +- Screen-reader-only text announces the `ariaLabel` value +- Decorative shape elements are marked `aria-hidden="true"` + +## Related Components + +- [VcLoading](./vc-loading.md) -- animated overlay for sections already rendered +- [VcProgress](./vc-progress.md) -- determinate progress bar + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status-icon.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status-icon.md new file mode 100644 index 0000000000..4712d0bb46 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status-icon.md @@ -0,0 +1,173 @@ + + + + + +# VcStatusIcon + +A simple boolean status indicator that displays a green check icon for active/success or a muted cross icon for inactive/failure. It is designed for compact spaces like table cells and lists where a full text label would be too verbose. + + + + Open in Storybook ↗ + + +## When to Use + +- Show on/off or pass/fail state in tables and lists (e.g., "Is Active", "Email Verified") +- Display system health checks with a quick visual indicator +- Compact boolean display in dense data views +- When NOT to use: multi-state status with labels (use [VcStatus](./vc-status.md) instead); when you need to show more than two states (consider VcBadge with inline mode) + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| -------- | --------- | ----------- | --------------------------------------------------------------------- | +| `status` | `boolean` | `undefined` | `true` shows a green check circle; `false` shows a muted cross circle | + +## Common Patterns + +### Boolean Column in a Table + +```vue + + + + + + + +``` + +### Multiple Boolean Columns + +```vue + + + + + + + + + + + + + + + + + + + +``` + +### System Health Dashboard + +```vue + + + + {{ service.name }} + + {{ service.status ? "Online" : "Offline" }} + + + + + +``` + + + + Open in Storybook ↗ + + +## Recipe: Status Icon with Custom Label + +VcStatusIcon is intentionally minimal. If you need a text label next to the icon, compose it yourself: + +```vue + + + + + {{ order.isPaid ? "Paid" : "Unpaid" }} + + + +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ------------------------------ | --------------------- | ----------------------- | +| `--status-icon-success-color` | `var(--success-500)` | Color of the check icon | +| `--status-icon-inactive-color` | `var(--neutrals-300)` | Color of the cross icon | + +## Tips + +- The component uses Lucide icons (`lucide-circle-check` and `lucide-circle-x`) internally. The icon inherits its size from the parent font size, so you can control it with Tailwind text-size classes on a wrapper. +- When `status` is `undefined`, the component still renders the inactive (cross) icon. If you want to hide the icon entirely when the value is unknown, use `v-if` on the component. +- For theming, override `--status-icon-success-color` to change the positive indicator to a different palette (e.g., `var(--primary-500)` for brand color). + +## Accessibility + +- Container has `role="img"` with `aria-label` set to "Active" or "Inactive" based on `status` +- Icons are marked `aria-hidden="true"` since the container carries the label +- Uses Lucide icons (`lucide-circle-check` and `lucide-circle-x`) + +## Related Components + +- [VcStatus](./vc-status.md) -- labeled multi-variant status badge for richer state display +- [VcIcon](../misc/vc-icon.md) -- standalone icon component used internally +- [VcBadge](../misc/vc-badge.md) -- inline pill badges for multi-state indicators + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status.md new file mode 100644 index 0000000000..3800eb62f3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-status.md @@ -0,0 +1,143 @@ + + + + + +# VcStatus + +A colored badge that communicates the state of an entity -- such as an order, product, or workflow step -- using semantic color variants. + + + + Open in Storybook ↗ + + +## When to Use + +- Display order or fulfillment status (e.g., "Paid", "Pending", "Cancelled") +- Tag items with severity levels in tables or detail views +- Show a compact dot indicator when label text is not needed +- When NOT to use: boolean on/off state (use [VcStatusIcon](./vc-status-icon.md) instead) + +## Basic Usage + +```vue + + Published + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| --------- | -------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- | +| `variant` | `"info" \| "warning" \| "danger" \| "success" \| "light-danger" \| "info-dark" \| "primary"` | `"info"` | Semantic color theme | +| `extend` | `boolean` | -- | Extended layout with larger padding, rounded corners, and colored background | +| `dot` | `boolean` | `false` | Renders as a small colored circle without text | + +## Common Patterns + + + + Open in Storybook ↗ + + +### Status in a Table Cell + +```vue + + + {{ order.status }} + + + + +``` + +### Dot Indicators + +Use the `dot` prop for compact status representation alongside text labels. + +```vue + + + + Online + + +``` + +### Extended Alert-Style Status + +The `extend` prop creates a banner-like status with a colored background, suitable for detail blade headers. + +```vue + + + + + + Payment Failed + The last transaction was declined. Please update your payment method. + + + + +``` + +## CSS Custom Properties + +Each variant has its own set of CSS variables following the pattern `--status-{variant}-color`, `--status-{variant}-main-color`, `--status-{variant}-bg-color`. Key shared variables: + +| Variable | Default | Description | +| --------------------------------- | --------------------- | --------------------------------- | +| `--status-border-radius` | `9999px` | Pill shape for standard mode | +| `--status-border-radius-extended` | `6px` | Rounded corners for extended mode | +| `--status-dot-size` | `10px` | Diameter of the dot indicator | +| `--status-text-color` | `var(--neutrals-700)` | Default label text color | + +## Accessibility + +- `role="status"` for screen reader announcements +- In `dot` mode, `aria-label` is set to the variant name so the color meaning is conveyed +- Text content is truncated with `text-overflow: ellipsis` in standard mode; extended mode wraps normally + +## Related Components + +- [VcStatusIcon](./vc-status-icon.md) -- boolean check/cross icon for active/inactive states +- [VcBadge](../misc/vc-badge.md) -- numeric count badge overlay + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-toast.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-toast.md new file mode 100644 index 0000000000..47a86e3acb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-toast.md @@ -0,0 +1,337 @@ + + + + + +!!! tip "Quick reference" +Jump to [Props](#props-component) · [Events](#events) · [Notification Service Methods](#notification-service-methods) · [CSS Variables](#css-variables) + +# VcToast + +Toast notification component with type-based styling, auto-dismiss timer, swipe-to-dismiss on touch devices, and Sonner-style stacking animations. Most applications interact with toasts through the `notification` service rather than mounting the component directly. + +## When to Use + +- Displaying transient feedback messages (success, error, warning, info) +- Non-blocking notifications that auto-dismiss after a timeout +- Feedback for async operations (upload progress, save confirmation) +- Rich notifications with custom component content + +When NOT to use: + +- For persistent alerts or banners -- use a dedicated alert component +- For inline field validation -- use `VcHint` or form-level error display +- For modal confirmations requiring user action -- use a dialog/modal + +## Quick Start + + + + Open in Storybook ↗ + + +The recommended approach is the `notification` service, not direct component usage: + +```ts +import { notification } from "@vc-shell/framework"; + +// Simple string notifications +notification("Order saved successfully"); +notification.success("Product published!"); +notification.error("Failed to save changes."); +notification.warning("This action cannot be undone."); +``` + +## Features + +### Notification Service API + +The `notification` function is the primary interface for creating and managing toasts. + +#### Creating Notifications + +```ts +import { notification } from "@vc-shell/framework"; + +// Default type (info) +notification("Processing your request..."); + +// Typed notifications +notification.success("Changes saved successfully"); +notification.error("Network error. Please try again."); +notification.warning("You have unsaved changes"); + +// With options +notification("Quick note", { timeout: 2000 }); // Dismiss after 2 seconds +notification("Please wait...", { timeout: false }); // Persistent (no auto-dismiss) +notification("Hover me", { pauseOnHover: true }); // Pause timer on hover (default) +``` + +Each call returns a unique `id` that can be used to update or remove the notification later. + +#### Updating Notifications + +Update an existing notification's content, type, or timeout. This is useful for progress-style patterns. + +```ts +const id = notification("Uploading files...", { timeout: false }); + +// Later, when upload completes: +notification.update(id, { + content: "Upload complete!", + type: "success", + timeout: 3000, +}); + +// Or if upload fails: +notification.update(id, { + content: "Upload failed. Please retry.", + type: "error", + timeout: 5000, +}); +``` + +#### Removing Notifications + +```ts +// Remove a specific notification +notification.remove(id); + +// Remove all notifications +notification.clearAll(); +``` + +#### Changing Position + +```ts +notification.setPosition("top-right"); +``` + +Available positions: `"top-center"`, `"top-right"`, `"top-left"`, `"bottom-center"`, `"bottom-right"`, `"bottom-left"`. + +### Notification Types + + + + Open in Storybook ↗ + + +Each type displays a distinct icon and colored left accent border. + +| Type | Icon | Accent Color | Use Case | +| --------- | -------------- | ------------------------ | ---------------------------- | +| `default` | Info circle | `--notification-info` | General information | +| `success` | Check circle | `--notification-success` | Successful operations | +| `error` | Alert circle | `--notification-error` | Failed operations, errors | +| `warning` | Alert triangle | `--notification-warning` | Caution, destructive actions | + +### Custom Component Content + +Instead of a string, pass a Vue component for rich notification content. + +```ts +import { defineComponent } from "vue"; +import { notification } from "@vc-shell/framework"; + +const OrderNotification = defineComponent({ + template: ` + + New Order #1234 + 3 items, $149.99 + + `, +}); + +notification(OrderNotification, { timeout: 10000, pauseOnHover: true }); +``` + +### Stacking, Swipe, and Auto-dismiss + + + + Open in Storybook ↗ + + +Toasts use Sonner-style stacking: the newest toast is in front, older toasts scale down behind it, and hovering expands the full stack. Only 3 toasts are visible by default in the collapsed state. + +On touch devices, horizontal swipe dismisses toasts (threshold: 45px or velocity > 0.11px/ms). + +The auto-dismiss timer (default 5000ms) pauses on hover. Set `timeout: false` for persistent toasts. + +```ts +notification("Quick flash", { timeout: 1500 }); +const id = notification("Please wait...", { timeout: false }); +notification.remove(id); // dismiss programmatically +``` + +## Recipes + +### Async Operation with Progress Feedback + +```ts +import { notification } from "@vc-shell/framework"; + +async function publishProduct(productId: string) { + const id = notification("Publishing product...", { timeout: false }); + + try { + await api.publishProduct(productId); + notification.update(id, { + content: "Product published successfully!", + type: "success", + timeout: 3000, + }); + } catch (error) { + notification.update(id, { + content: `Failed to publish: ${error.message}`, + type: "error", + timeout: 8000, + }); + } +} +``` + +### Undo Action Pattern + +Pass a component with an undo button as the notification content: + +```ts +function deleteItem(item: { id: string; name: string }) { + softDelete(item.id); + const UndoContent = defineComponent({ + setup() { + const undo = () => { + restoreItem(item.id); + notification.remove(notifId); + }; + return () => h("div", { class: "tw-flex tw-gap-3" }, [h("span", `"${item.name}" deleted.`), h("button", { class: "tw-text-[color:var(--primary-600)] tw-underline", onClick: undo }, "Undo")]); + }, + }); + const notifId = notification(UndoContent, { timeout: 8000, pauseOnHover: true }); +} +``` + +## Common Mistakes + +### 1. Forgetting to store the notification ID for later updates + +```ts +// WRONG: can't update or remove this notification later +notification("Uploading...", { timeout: false }); +// ... no way to update the toast when upload finishes + +// CORRECT: store the returned ID +const id = notification("Uploading...", { timeout: false }); +notification.update(id, { content: "Done!", type: "success", timeout: 3000 }); +``` + +### 2. Using the component directly instead of the service + +```vue + + + + + +``` + +### 3. Setting timeout to 0 instead of false for persistent notifications + +```ts +// WRONG: timeout of 0 may behave unexpectedly +notification("Please wait...", { timeout: 0 }); + +// CORRECT: use false to disable auto-dismiss +notification("Please wait...", { timeout: false }); +``` + +## Props (Component) + +These props are used internally by the notification system. You rarely need to set them directly. + +| Prop | Type | Default | Description | +| ---------------- | ------------------------------------------------ | -------------- | ------------------------------------------------------ | +| `content` | `string \| Component` | -- | Notification message or custom component | +| `notificationId` | `number \| string` | -- | Unique identifier | +| `updateId` | `number \| string` | -- | ID for update tracking | +| `type` | `"default" \| "success" \| "error" \| "warning"` | `"default"` | Notification type (determines icon and accent color) | +| `timeout` | `number \| boolean` | `5000` | Auto-dismiss delay in ms, or `false` to disable | +| `pauseOnHover` | `boolean` | `true` | Pause timeout while mouse hovers over the toast | +| `limit` | `number` | -- | Maximum number of visible notifications | +| `position` | `NotificationPosition` | `"top-center"` | Screen position for the toast | +| `dismissing` | `boolean` | -- | Programmatic dismissal trigger | +| `toastIndex` | `number` | `0` | Stack index (0 = front/newest) | +| `toastsCount` | `number` | -- | Total number of toasts in the position stack | +| `expanded` | `boolean` | `true` | Whether the toast group is in expanded (hovered) state | +| `visibleToasts` | `number` | `3` | Maximum visible toasts in collapsed stack | +| `onReportHeight` | `(id, height) => void` | -- | Callback to report measured height to container | + +## Events + +| Event | Payload | Description | +| ------- | ------------------------------- | -------------------------------------------------- | +| `close` | `number \| string \| undefined` | Toast dismissed (by user click, timeout, or swipe) | + +## Notification Service Methods + +| Method | Signature | Description | +| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------- | +| `notification()` | `(message: string \| Component, options?: NotificationOptions) => string \| number` | Show a default notification | +| `notification.success()` | `(message: string \| Component) => string \| number` | Show a success notification | +| `notification.error()` | `(message: string \| Component) => string \| number` | Show an error notification | +| `notification.warning()` | `(message: string \| Component) => string \| number` | Show a warning notification | +| `notification.update()` | `(id, options: Partial) => void` | Update an existing notification | +| `notification.remove()` | `(id: string \| number) => void` | Remove a specific notification | +| `notification.clearAll()` | `() => void` | Remove all notifications | +| `notification.setPosition()` | `(position: NotificationPosition) => void` | Change the global position | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------------ | ----------------------------- | ---------------------------------- | +| `--notification-background` | `var(--additional-50)` | Toast background color | +| `--notification-border-radius` | `6px` | Corner radius | +| `--notification-border-color` | `var(--neutrals-200)` | Border color | +| `--notification-content-color` | `var(--neutrals-800)` | Text color | +| `--notification-shadow` | `0 4px 12px rgba(0,0,0,0.08)` | Default box shadow | +| `--notification-hover-shadow` | `0 4px 16px rgba(0,0,0,0.12)` | Box shadow on hover | +| `--notification-dismiss-color` | `var(--neutrals-400)` | Dismiss button icon color | +| `--notification-dismiss-hover-color` | `var(--neutrals-600)` | Dismiss button hover color | +| `--notification-success` | `var(--success-500)` | Success accent and icon color | +| `--notification-error` | `var(--danger-500)` | Error accent and icon color | +| `--notification-warning` | `var(--warning-500)` | Warning accent and icon color | +| `--notification-info` | `var(--info-500)` | Info/default accent and icon color | +| `--notification-accent-width` | `3px` | Left accent border width | +| `--notification-focus-ring-color` | `var(--primary-100)` | Focus ring color on dismiss button | + +## Accessibility + +- **Error toasts** use `role="alert"` for immediate screen reader announcement +- **Other types** use `role="status"` for polite screen reader announcements +- The dismiss button has `aria-label="Dismiss notification"` for screen readers +- The dismiss button icon is marked `aria-hidden="true"` +- **Escape key** on the dismiss button closes the toast +- **Reduced motion**: animations and transitions are disabled when `prefers-reduced-motion: reduce` is active +- Toast content supports `overflow-wrap: anywhere` for long text without word breaks + +## Related Components + +- [VcHint](./vc-hint.md) -- inline hint/error text for form fields +- [VcIcon](../misc/vc-icon.md) -- used internally for type-specific icons + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-tooltip.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-tooltip.md new file mode 100644 index 0000000000..91919d0c1e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/feedback/vc-tooltip.md @@ -0,0 +1,358 @@ + + + + + +# VcTooltip + +A floating tooltip that appears on hover or focus to provide contextual information about a trigger element. Powered by Floating UI for automatic positioning, collision detection, and arrow alignment. The tooltip is teleported to the document body for proper stacking above all content. + +## Quick Start + + + + Open in Storybook ↗ + + +```vue + + + + Delete selected items + + + + +``` + +The tooltip appears when the user hovers over or focuses the trigger element. + +## Placement + +VcTooltip supports 12 placement positions relative to the trigger element. The tooltip automatically flips to the opposite side if it would overflow the viewport. + +```vue +... +... +... +... +``` + +### All placement options + +| Primary | Start Variant | End Variant | +| -------- | -------------- | ------------ | +| `top` | `top-start` | `top-end` | +| `bottom` | `bottom-start` | `bottom-end` | +| `left` | `left-start` | `left-end` | +| `right` | `right-start` | `right-end` | + +The `start` and `end` variants align the tooltip to the beginning or end of the trigger element along the cross axis: + +```vue + + + Hover me + Aligned to the start + +``` + +## Variants + + + + Open in Storybook ↗ + + +Three visual themes control the tooltip's appearance. + +```vue + + Default (light) + Light background with dark text + + + + Dark + Dark background with light text + + + + Info + Primary-colored background with white text + +``` + +| Variant | Background | Text Color | Use Case | +| --------- | ------------------------------ | ------------------------------ | ------------------------------------- | +| `default` | `var(--additional-50)` (light) | `var(--neutrals-700)` | General-purpose tooltips | +| `dark` | `var(--neutrals-800)` | `var(--additional-50)` (white) | High-contrast tooltips, dark UI areas | +| `info` | `var(--primary-600)` | `var(--additional-50)` (white) | Branded or informational tooltips | + +## Delayed Display + +Prevent accidental tooltip activation when the mouse passes over many elements by adding a delay: + +```vue + + + This tooltip appears after 300ms + +``` + +The delay only applies to showing the tooltip. Hiding is always immediate when the mouse leaves or focus moves away. If the mouse leaves before the delay elapses, the tooltip never appears. + +## Arrow Control + +The directional arrow is shown by default. Disable it for a cleaner look: + +```vue + + No arrow + Clean floating tooltip without arrow + +``` + +## Offset and Spacing + +Control the distance between the trigger and the tooltip: + +```vue + +... + + +... + + +... +``` + +| Axis | Direction | Default | +| ----------- | ------------------------------------------------------- | ------- | +| `mainAxis` | Away from the trigger (perpendicular to placement edge) | `8` | +| `crossAxis` | Along the trigger edge (parallel to placement edge) | `0` | + +## Width Control + +Set a maximum width to prevent wide tooltips from stretching across the screen: + +```vue + +... + + +... + + +... +``` + +## Disabling the Tooltip + +Suppress the tooltip dynamically without removing it from the template: + +```vue + + Edit + Click to edit this item + +``` + +## Rich Content + +The `#tooltip` slot accepts any HTML or Vue components, not just text: + +```vue + + + Fulfillment status + + + + About fulfillment + + Awaiting -- order received, not yet shipped + Shipped -- tracking number assigned + Delivered -- confirmed by carrier + + + + +``` + +!!! warning "No interactive content inside tooltips" +Tooltips should not contain interactive content (buttons, links, inputs). The tooltip panel has `pointer-events: none` — clicks and keyboard focus inside it are blocked. If you need interactive content in a floating panel, use a popover or dropdown component instead. + +## Recipes + +### Icon Toolbar with Tooltips + +```vue + + + + + {{ action.label }} + + + + + +``` + +### Truncated Text with Full-Value Tooltip + +```vue + + + + {{ longProductName }} + + {{ longProductName }} + + +``` + +## Common Mistakes + +### Putting interactive content inside a tooltip + +```vue + + + Hover for help + + Read the documentation + + + + + + Click for help + + Read the documentation + + +``` + +### Forgetting the #tooltip slot + +```vue + + + + + + + + + More information + +``` + +### Using tooltip as a label replacement + +```vue + + + + Enter your email address + + + + + Email Address + + + We will send order confirmations to this address + + +``` + +## Props + +| Prop | Type | Default | Description | +| ----------- | ------------------------------------------- | ----------------- | ----------------------------------------------- | +| `placement` | `TooltipPlacement` | `"bottom"` | Position relative to the trigger (12 options) | +| `variant` | `"default" \| "dark" \| "info"` | `"default"` | Visual theme | +| `arrow` | `boolean` | `true` | Show directional arrow pointing at the trigger | +| `delay` | `number` | `0` | Milliseconds to wait before showing | +| `maxWidth` | `number \| string` | `240` | Maximum width (number = px, string = CSS value) | +| `offset` | `{ mainAxis?: number; crossAxis?: number }` | `{ mainAxis: 8 }` | Distance from the trigger element | +| `disabled` | `boolean` | `false` | Suppress the tooltip entirely | + +## Slots + +| Slot | Description | +| --------- | --------------------------------------------------------- | +| `default` | Trigger element that activates the tooltip on hover/focus | +| `tooltip` | Content rendered inside the floating tooltip panel | + +## CSS Custom Properties + +| Variable | Default | Description | +| ------------------------- | ---------------------- | -------------------------- | +| `--tooltip-bg` | `var(--additional-50)` | Default variant background | +| `--tooltip-text` | `var(--neutrals-700)` | Default variant text color | +| `--tooltip-dark-bg` | `var(--neutrals-800)` | Dark variant background | +| `--tooltip-dark-text` | `var(--additional-50)` | Dark variant text color | +| `--tooltip-info-bg` | `var(--primary-600)` | Info variant background | +| `--tooltip-info-text` | `var(--additional-50)` | Info variant text color | +| `--tooltip-border-radius` | `6px` | Corner radius | +| `--tooltip-font-size` | `12px` | Text size | +| `--tooltip-padding-x` | `10px` | Horizontal padding | +| `--tooltip-padding-y` | `6px` | Vertical padding | +| `--tooltip-z-index` | `1002` | Stacking order | + +## Accessibility + +- `role="tooltip"` is set on the floating element +- `aria-describedby` links the trigger to the tooltip when visible +- Shows on `focusin`, hides on `focusout` for keyboard users +- Escape key dismisses the tooltip +- Tooltip is teleported to the document body for proper stacking context +- Fade transition (150ms in, 100ms out) provides smooth visual feedback +- The tooltip has `pointer-events: none` -- it cannot be interacted with directly + +## Related Components + +- [VcHint](./vc-hint.md) -- inline hint text below form fields (always visible) +- [VcLabel](../misc/vc-label.md) -- label component with built-in tooltip support via its own `#tooltip` slot +- [VcIcon](../misc/vc-icon.md) -- commonly used as a tooltip trigger for info indicators + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/.pages new file mode 100644 index 0000000000..6bd1ffc2bb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/.pages @@ -0,0 +1,26 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Form +nav: + - MultilanguageSelector: multilanguage-selector.md + - VcCheckbox: vc-checkbox.md + - VcCheckboxGroup: vc-checkbox-group.md + - VcColorInput: vc-color-input.md + - VcDatePicker: vc-date-picker.md + - VcDynamicProperty: vc-dynamic-property.md + - VcEditor: vc-editor.md + - VcField: vc-field.md + - VcFileUpload: vc-file-upload.md + - VcForm: vc-form.md + - VcInput: vc-input.md + - VcInputCurrency: vc-input-currency.md + - VcInputDropdown: vc-input-dropdown.md + - VcInputGroup: vc-input-group.md + - VcMultivalue: vc-multivalue.md + - VcRadioButton: vc-radio-button.md + - VcRadioGroup: vc-radio-group.md + - VcRating: vc-rating.md + - VcSelect: vc-select.md + - VcSlider: vc-slider.md + - VcSwitch: vc-switch.md + - VcTextarea: vc-textarea.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/multilanguage-selector.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/multilanguage-selector.md new file mode 100644 index 0000000000..7898504726 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/multilanguage-selector.md @@ -0,0 +1,160 @@ + + + + + +# MultilanguageSelector + +Compact circular flag button that opens a dropdown for selecting a content language. Designed for use in detail blades where entities have multilingual fields (e.g., product name, offer description, category title). This is distinct from the `LanguageSelector` settings entry, which changes the application UI locale -- `MultilanguageSelector` controls which language version of the content the user is editing. + +## When to Use + +- Use in detail blade toolbars to switch the editing language for multilingual content +- When you need a compact language picker with flag icons that fits in a blade header +- Do NOT use for switching the application UI locale (use `LanguageSelector` instead) + +## Basic Usage + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------ | ------------------ | ------- | --------------------------------- | +| `modelValue` | `string` | `""` | Currently selected language value | +| `options` | `LanguageOption[]` | `[]` | Available language options | +| `disabled` | `boolean` | `false` | Disables interaction | + +Each `LanguageOption` has: `{ value: string; label: string; flag?: string }`. + + + + Open in Storybook ↗ + + +## Recipe: Multilingual Product Editing Blade + +A typical use case is a product detail blade where the user can edit the name and description in multiple languages: + +```vue + + + + + + + + + + + + +``` + +## Recipe: Dynamic Languages from API + +Fetch available content languages from the platform instead of hardcoding them: + +```typescript +import { ref, onMounted } from "vue"; + +const languages = ref([]); + +onMounted(async () => { + const locales = await api.getAvailableContentLocales(); + languages.value = locales.map((locale) => ({ + value: locale.code, + label: locale.displayName, + flag: `/flags/${locale.countryCode.toLowerCase()}.svg`, + })); +}); +``` + +## Details + +- **Compact layout**: The button renders as a small circle showing the flag of the currently selected language. Clicking it opens a dropdown with all available options. +- **v-model binding**: The component uses `modelValue` / `update:modelValue` for two-way binding, following the standard Vue 3 v-model convention. +- **Flag images**: The `flag` property on each option is optional. When provided, it shows the flag image; otherwise, the language code text is displayed. +- **Dropdown positioning**: The dropdown is positioned relative to the button and adjusts to avoid viewport overflow. + +## Tips + +- Place the selector in the blade's `#actions` slot so it appears in the toolbar area alongside save/cancel buttons. +- The `disabled` prop is useful when the blade is in a read-only or loading state. +- If a language has no content yet, the form fields will be empty for that language. Consider showing a visual indicator (like a badge) on the selector to mark languages with missing translations. +- Keep the `value` field consistent with the locale codes used by your API (typically BCP 47 format like `"en-US"`, `"de-DE"`). + +## Related Components + +- [LanguageSelector](../language-selector/language-selector.docs.md) -- settings menu entry for UI locale switching (different purpose) diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox-group.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox-group.md new file mode 100644 index 0000000000..6153a15d14 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox-group.md @@ -0,0 +1,171 @@ + + + + + +# VcCheckboxGroup + +Accessible checkbox group that wraps multiple checkboxes in a semantic fieldset with shared label, hint, error state, and layout control. + + + + Open in Storybook ↗ + + +## When to Use + +- Selecting multiple options from a set (e.g., notification channels, feature flags) +- When checkboxes need shared validation, label, and error messaging +- When NOT to use: for mutually exclusive options, use `VcRadioGroup`; for a single toggle, use `VcCheckbox` or `VcSwitch` + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| -------------- | ---------------------------- | -------------- | ----------------------------------------- | +| `modelValue` | `T[]` | `[]` | Selected values (v-model) | +| `options` | `CheckboxGroupOption[]` | `[]` | Options to render as checkboxes | +| `label` | `string` | — | Group label (rendered as fieldset legend) | +| `tooltip` | `string` | — | Tooltip on the label | +| `hint` | `string` | — | Hint text below the group | +| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction of options | +| `size` | `"s" \| "m" \| "l"` | `"s"` | Checkbox size for all items | +| `name` | `string` | auto-generated | Shared name for native checkboxes | +| `disabled` | `boolean` | `false` | Disable all checkboxes | +| `required` | `boolean` | `false` | Mark group as required | +| `error` | `boolean` | `false` | External error flag | +| `errorMessage` | `string` | — | Error message text | + +## CheckboxGroupOption Interface + +```ts +interface CheckboxGroupOption { + label: string; + value: V; + disabled?: boolean; // Disable individual options +} +``` + +## Events + +| Event | Payload | Description | +| ------------------- | ------- | ----------------------- | +| `update:modelValue` | `T[]` | Selected values changed | + +## Slots + +| Slot | Description | +| --------- | --------------------------------------------------------- | +| `default` | Custom checkbox layout (replaces options-based rendering) | + +## Common Patterns + +### Horizontal Layout + + + + Open in Storybook ↗ + + +```vue + +``` + +### With Disabled Option + + + + Open in Storybook ↗ + + +```vue + +``` + +### Validation Error + +```vue + +``` + +### Custom Slot Layout + +```vue + + Feature A + Feature B + Feature C + +``` + +## Accessibility + +- Container is a semantic `` with `role="group"` +- Label is rendered as a `` element +- All checkboxes share the group `name` attribute +- Hint and error messages are linked via `aria-describedby` +- Individual options can be disabled independently + +## Related Components + +- [VcCheckbox](./vc-checkbox.md) — individual checkbox component +- [VcRadioGroup](./vc-radio-group.md) — mutually exclusive option group +- [VcInputGroup](./vc-input-group.md) — generic form field group (used internally) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox.md new file mode 100644 index 0000000000..884d5c3cef --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-checkbox.md @@ -0,0 +1,394 @@ + + + + + +# VcCheckbox + +A checkbox component supporting boolean toggling, array-based multi-selection, indeterminate state, three size variants, and animated check/uncheck transitions. Works as both a standalone boolean toggle and a member of a multi-select group. + +!!! note "Large reference" +This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables). + + + + Open in Storybook ↗ + + +## When to Use + +- Single boolean toggle with an inline label (e.g., "I agree to terms") +- Multi-select from a set of options (bind an array to `v-model` with a `value` prop) +- "Select all" patterns using the `indeterminate` prop +- Table row selection indicators + +**When NOT to use:** + +- On/off feature toggle that applies immediately -- use [VcSwitch](./vc-switch.md) +- Mutually exclusive single choice -- use [VcRadioButton](./vc-radio-button.md) + +## Quick Start + +```vue + + I agree to the terms and conditions + + + +``` + +## Features + +### Boolean Mode vs. Array Mode + +**Boolean mode** -- bind a `boolean` ref to `v-model`. The checkbox toggles between `trueValue` (default `true`) and `falseValue` (default `false`). + +```vue +Active +``` + +**Array mode** -- bind an array ref to `v-model` and provide a `value` prop. Checking adds the value to the array; unchecking removes it. + +```vue + + + + Express shipping + Shipping insurance + Gift wrapping + + +``` + +### Size Variants + + + + Open in Storybook ↗ + + +Three sizes are available via the `size` prop: + +| Size | Value | Pixel dimension | +| ------ | --------------- | --------------- | +| Small | `"s"` (default) | 16 x 16 px | +| Medium | `"m"` | 20 x 20 px | +| Large | `"l"` | 24 x 24 px | + +```vue +Small checkbox +Medium checkbox +Large checkbox +``` + +### Indeterminate State (Select All) + + + + Open in Storybook ↗ + + +The `indeterminate` prop renders a horizontal dash instead of a checkmark. This is commonly used for "select all" checkboxes where only some children are selected. + +```vue + + + + + Select all + + + Option A + Option B + Option C + +``` + +> **Tip:** The `indeterminate` state is visual only -- it does not affect the `modelValue`. The native `` element's `indeterminate` property is set programmatically via a watcher. + +### Validation with vee-validate Field + +Connect the checkbox to vee-validate for form validation: + +```vue + + + + I accept the privacy policy + + + + + +``` + +### States + +```vue + +Accept terms + + +I agree to the terms + + +Cannot be changed + + + + I have read the disclaimer + +``` + +## Recipes + +### Multi-select Group with VcInputGroup + +Use `VcInputGroup` to add a shared label and semantic grouping: + +```vue + + + Courier delivery + Store pickup + Postal service + + + + +``` + +### Custom Content in the Default Slot + +The default slot accepts any markup, not just plain text: + +```vue + + + Premium Plan + + Includes priority support and advanced analytics + + + +``` + +## Common Mistakes + +### 1. Forgetting to wire handleChange with vee-validate + +```vue + + + + I agree + + + + + + + I agree + + +``` + +### 2. Using boolean mode when array mode is needed + +```vue + +const val = ref(false); +Option A +Option B + + +const selected = ref([]); +Option A +Option B +``` + +### 3. Controlling indeterminate without managing modelValue separately + +```vue + +Select all + + + + Select all + +``` + +## Props + +| Prop | Type | Default | Description | +| --------------- | ------------------- | ----------- | ---------------------------------------------------------------------- | +| `modelValue` | `boolean \| T[]` | `undefined` | Bound value via `v-model`. Boolean for single, array for multi-select. | +| `value` | `T` | -- | Value added to the array when checked (array mode only) | +| `label` | `string` | -- | Label text displayed above the checkbox | +| `tooltip` | `string` | -- | Tooltip on the label info icon | +| `size` | `"s" \| "m" \| "l"` | `"s"` | Checkbox size variant | +| `indeterminate` | `boolean` | `false` | Shows the indeterminate (dash) visual state | +| `trueValue` | `boolean` | `true` | Value emitted when checked (boolean mode) | +| `falseValue` | `boolean` | `false` | Value emitted when unchecked (boolean mode) | +| `disabled` | `boolean` | `false` | Disables the checkbox | +| `required` | `boolean` | `false` | Shows a required indicator | +| `error` | `boolean` | `false` | Enables error styling | +| `errorMessage` | `string` | -- | Error message displayed below the checkbox | +| `name` | `string` | `"Field"` | HTML name attribute | +| `outline` | `boolean` | `false` | Applies outline style variant | + +## Events + +| Event | Payload | Description | +| ------------------- | ---------------- | ------------------------------------ | +| `update:modelValue` | `boolean \| T[]` | Emitted when the checkbox is toggled | + +## Slots + +| Slot | Description | +| --------- | ------------------------------------------------------- | +| `default` | Inline text or content displayed next to the checkbox | +| `icon` | Replace the check/indeterminate icon with custom markup | +| `error` | Custom error message markup | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------------- | ---------------------- | ------------------------ | +| `--checkbox-size-s` | `16px` | Small variant size | +| `--checkbox-size-m` | `20px` | Medium variant size | +| `--checkbox-size-l` | `24px` | Large variant size | +| `--checkbox-border-color` | `var(--neutrals-300)` | Default border color | +| `--checkbox-border-color-hover` | `var(--neutrals-400)` | Border color on hover | +| `--checkbox-bg-color` | `var(--additional-50)` | Unchecked background | +| `--checkbox-checked-bg-color` | `var(--primary-500)` | Checked background color | +| `--checkbox-checked-border-color` | `var(--primary-500)` | Checked border color | +| `--checkbox-indeterminate-bg-color` | `var(--primary-500)` | Indeterminate background | +| `--checkbox-indeterminate-line-color` | `var(--additional-50)` | Indeterminate dash color | +| `--checkbox-error-border-color` | `var(--danger-500)` | Error state border | +| `--checkbox-error-ring-color` | `var(--danger-100)` | Error ring color | +| `--checkbox-focus-ring-color` | `var(--primary-100)` | Focus ring color | +| `--checkbox-border-radius` | `4px` | Corner radius | +| `--checkbox-disabled-opacity` | `0.5` | Opacity when disabled | +| `--checkbox-transition-duration` | `200ms` | Animation duration | + +## Accessibility + +- Uses a native hidden `` for full form semantics +- `aria-invalid`, `aria-required`, and `aria-describedby` are set appropriately +- Focus ring appears on `:focus-visible` via the custom checkbox visual +- Keyboard: Space toggles the checkbox, Tab navigates between fields +- Check and indeterminate icons have animated enter/leave transitions +- When `indeterminate` is set, the native `input.indeterminate` property is synced + +## Related Components + +- [VcSwitch](./vc-switch.md) -- toggle switch for on/off settings +- [VcRadioButton](./vc-radio-button.md) -- mutually exclusive single selection +- [VcInputGroup](./vc-input-group.md) -- semantic wrapper for grouping checkboxes or radio buttons + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-color-input.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-color-input.md new file mode 100644 index 0000000000..87116809a0 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-color-input.md @@ -0,0 +1,228 @@ + + + + + +!!! tip "Quick reference" +See [Key Props](#key-props) for the full prop table, or jump to [Common Patterns](#common-patterns) for copy-paste examples. + +# VcColorInput + +A color input that combines a text field for hex values with a clickable color swatch that opens the native browser color picker. Accepts hex codes and CSS color names. + + + + Open in Storybook ↗ + + +## Overview + +Color selection is needed in various admin scenarios: configuring brand colors, setting category badges, defining product attribute colors, or customizing theme variables. The native HTML `` provides a color picker but lacks text entry, validation, and consistent styling. + +`VcColorInput` combines the best of both approaches: a text field where users can type hex codes or CSS color names directly, and a color swatch button that opens the native browser color picker for visual selection. Changes from either input method synchronize in real time. + +The component follows the same prop interface as other vc-shell form fields (`ITextFieldProps`), so it integrates seamlessly with form layouts, validation, and error display. + +> **Note:** `VcInput` with `type="color"` automatically delegates to this component. You can also use `VcColorInput` directly. + +## When to Use + +- Selecting a color value (brand colors, theme settings, product attributes) +- When both manual hex entry and visual picking are desired +- When NOT to use: general text input (use [VcInput](./vc-input.md)) + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------------------ | ---------------------- | ----------- | -------------------------------------------------------- | +| `modelValue` | `string \| null` | `undefined` | Color value via `v-model` (hex string or CSS color name) | +| `label` | `string` | -- | Label text above the field | +| `placeholder` | `string` | -- | Placeholder text | +| `clearable` | `boolean` | `false` | Shows a clear button when a value is present | +| `size` | `"default" \| "small"` | `"default"` | Field height variant | +| `error` / `errorMessage` | `boolean` / `string` | -- | Error styling and validation message | +| `disabled` | `boolean` | `false` | Disables the input and color picker | + +## Common Patterns + +### With Validation + + + + Open in Storybook ↗ + + +```vue + + + +``` + +### Pre-filled Value + +```vue + + + + + + +``` + +### In a Form with Other Fields + +```vue + + + + + + + +``` + +### Via VcInput Type Delegation + +You can use `VcInput` with `type="color"` instead of importing `VcColorInput` directly: + +```vue + + + + + +``` + +### Multiple Color Pickers in a Theme Editor + +```vue + + Theme Colors + + + + + + + + + +``` + +## How It Works + +1. Type a hex value (e.g., `#ff5733`) or a CSS color name (e.g., `red`) in the text field +2. The color swatch updates in real-time to reflect the entered color +3. Click the color swatch to open the native browser color picker +4. Selecting from the picker updates both the swatch and the text field + +## Accessibility + +- Label linked via `aria-labelledby` +- Hint/error linked via `aria-describedby` +- `aria-invalid` set in error state +- Color swatch button has descriptive `aria-label` (e.g., "Pick color: #ff5733") +- Clear button has `aria-label="Clear color"` +- Focus ring on both the text input and the color swatch button + +## CSS Variables + +Uses the same `--input-*` variables as VcInput, plus: + +- `--color-input-swatch-size` -- swatch square size (default 20px) +- `--color-input-swatch-border-radius`, `--color-input-swatch-border-color` + +## Tip: CSS Color Names + +The component accepts any valid CSS color name in addition to hex codes. Common names like `red`, `blue`, `green`, `coral`, `steelblue`, and `cornflowerblue` all work. However, the native color picker always returns hex values, so the text field will switch to hex format after a picker selection. + +## Common Mistake + +The native color picker does not support alpha/transparency. If you need RGBA color selection, you will need a custom color picker component. `VcColorInput` works with opaque RGB hex values only (`#RRGGBB` or `#RGB` shorthand). + +## Related Components + +- [VcInput](./vc-input.md) -- general-purpose input (delegates to VcColorInput for `type="color"`) +- [VcField](./vc-field.md) -- read-only field display (for showing a color value without editing) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-date-picker.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-date-picker.md new file mode 100644 index 0000000000..34b8e8e111 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-date-picker.md @@ -0,0 +1,384 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcDatePicker + +A date and datetime picker that wraps the [VueDatePicker](https://vue3datepicker.com/) library with the standard form field chrome (label, hint, error, focus ring). Formats dates using the browser's locale and automatically detects 12-hour vs. 24-hour time format. + + + + Open in Storybook ↗ + + +## When to Use + +- Selecting a single date value (e.g., delivery date, publication date) +- Selecting a date and time value (e.g., scheduled publishing, event start) +- When consistent locale-aware date formatting is needed across the application + +**When NOT to use:** + +- Free-form text entry -- use [VcInput](./vc-input.md) +- Time-only input -- use `VcInput` with `type="time"` +- Selecting multiple dates or date ranges -- currently not supported (use VueDatePicker directly) + +> **Note:** `VcInput` with `type="date"` or `type="datetime-local"` automatically delegates to this component internally. You can also use `VcDatePicker` directly for more explicit control over date-specific props. + +## Quick Start + +```vue + + + + + +``` + +## Features + +### Date vs. DateTime Mode + + + + Open in Storybook ↗ + + +The `type` prop controls whether the picker shows a date-only calendar or includes an inline time picker. + +```vue + + + + + +``` + +In `datetime-local` mode, the time picker is rendered inline below the calendar. The component auto-detects whether to show 12-hour (AM/PM) or 24-hour format based on the browser's locale. + +### Clearable + +When `clearable` is set, a small "x" button appears once a date is selected, allowing the user to reset the field to `null`. + +```vue + +``` + +### Size Variants + +Two height variants are available: + +| Size | Value | Height | +| ------- | ----------- | ------ | +| Default | `"default"` | 36px | +| Small | `"small"` | 32px | + +```vue + + +``` + +The small variant is useful in compact layouts such as table filter headers or inline editing fields. + +### Custom VueDatePicker Options + +Pass any VueDatePicker prop through the `datePickerOptions` prop for advanced configurations like minimum/maximum dates, disabled dates, or calendar starting day. + +```vue + +``` + +> **Tip:** Refer to the [VueDatePicker documentation](https://vue3datepicker.com/) for the full list of available options. All props passed via `datePickerOptions` are spread onto the underlying `` component. + +### Validation with vee-validate Field + +Integrate with vee-validate for form-level validation: + +```vue + + + + + + + +``` + +### States + + + + Open in Storybook ↗ + + +```vue + + + + + + + + + + + +``` + +### Multilanguage Support + +Like other form fields, the date picker supports the multilanguage label indicator: + +```vue + +``` + +## Recipes + +### Date Range with Two Pickers + +Use two `VcDatePicker` instances with min/max constraints to create a date range: + +```vue + + + + + + + + + + + + +``` + +### Scheduling with DateTime in a Blade + +```vue + + + + + + + + + + + + + +``` + +## Common Mistakes + +### 1. Forgetting to wire handleChange with vee-validate + +```vue + + + + + + + + + +``` + +### 2. Passing a string instead of a Date object + +```vue + +const date = ref("2025-01-15"); + + +const date = ref(new Date("2025-01-15")); +``` + +> **Important:** The `modelValue` type accepts `Date | string | null`, but for reliable behavior always prefer `Date` objects. If you receive ISO strings from an API, convert them to `Date` before binding. + +### 3. Setting clearable on a required field without handling null + +```vue + + + + + + + +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------ | +| `modelValue` | `Date \| string \| null` | `undefined` | Bound value via `v-model` | +| `type` | `"date" \| "datetime-local"` | `"date"` | Date only or date + time mode | +| `label` | `string` | -- | Label text above the field | +| `placeholder` | `string` | auto (localized) | Placeholder text; auto-generated from locale if not provided | +| `hint` | `string` | -- | Helper text below the field | +| `tooltip` | `string` | -- | Tooltip on the label info icon | +| `clearable` | `boolean` | `false` | Shows a clear button when a date is selected | +| `loading` | `boolean` | `false` | Shows a spinning loader icon | +| `size` | `"default" \| "small"` | `"default"` | Field height variant | +| `required` | `boolean` | `false` | Shows a required indicator | +| `error` | `boolean` | `false` | Enables error styling | +| `errorMessage` | `string` | -- | Error message below the field | +| `disabled` | `boolean` | `false` | Disables the date picker | +| `autofocus` | `boolean` | `false` | Focus the field on mount | +| `name` | `string` | `"Field"` | HTML name attribute | +| `multilanguage` | `boolean` | `false` | Shows language badge on the label | +| `currentLanguage` | `string` | -- | Language code for the badge | +| `datePickerOptions` | `VueDatePickerProps` | -- | Pass-through options to VueDatePicker | + +## Events + +| Event | Payload | Description | +| ------------------- | ------------------------ | --------------------------------------------- | +| `update:modelValue` | `Date \| string \| null` | Emitted when the selected date changes | +| `focus` | -- | Emitted when the picker gains focus or opens | +| `blur` | `Event` | Emitted when the picker loses focus or closes | + +## CSS Variables + +Uses the same `--input-*` variables as VcInput for consistent styling across all input molecules: + +| Variable | Default | Description | +| ---------------------------- | ---------------------- | -------------------------- | +| `--input-height` | `36px` | Default field height | +| `--input-height-small` | `32px` | Small variant field height | +| `--input-border-radius` | `6px` | Corner radius | +| `--input-border-color` | `var(--neutrals-300)` | Default border color | +| `--input-border-color-focus` | `var(--primary-500)` | Focus border color | +| `--input-border-color-error` | `var(--danger-500)` | Error border color | +| `--input-background-color` | `var(--additional-50)` | Background color | +| `--input-text-color` | `var(--neutrals-800)` | Text color | +| `--input-placeholder-color` | `var(--neutrals-400)` | Placeholder color | +| `--input-focus-ring-color` | `var(--primary-100)` | Focus ring color | +| `--input-error-ring-color` | `var(--danger-100)` | Error ring color | + +## Accessibility + +- Label is linked via `aria-labelledby` +- Hint and error text are linked via `aria-describedby` +- `aria-invalid` is set in error state +- `aria-required` is set for required fields +- Clear button has `aria-label="Clear date"` +- On mobile, the picker popup teleports to the center of the screen for better usability +- Auto-detects 12h/24h time format from the browser's locale +- Date-only mode limits the maximum date to `9999-12-31` to prevent invalid entries + +## Related Components + +- [VcInput](./vc-input.md) -- general-purpose input; delegates to VcDatePicker for `type="date"` and `type="datetime-local"` +- [VcMultivalue](./vc-multivalue.md) -- can handle multiple date values with `type="date"` + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-dynamic-property.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-dynamic-property.md new file mode 100644 index 0000000000..db6c70a0f2 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-dynamic-property.md @@ -0,0 +1,184 @@ + + + + + +# VcDynamicProperty + +Renders a VirtoCommerce platform dynamic property as the appropriate form control, automatically selecting the input component based on value type, dictionary, and multivalue flags. VcDynamicProperty eliminates the need for manual `v-if` chains when rendering properties whose type is determined at runtime — it maps each combination of `valueType`, `dictionary`, and `multivalue` to the correct input molecule and passes through all relevant props. + + + + Open in Storybook ↗ + + +## When to Use + +- Use to render dynamic properties from the VirtoCommerce platform (catalog properties, member properties, store properties, etc.) +- Use when the input type is determined at runtime based on property metadata +- Use inside `v-for` loops to render a list of dynamic properties from the API +- When NOT to use: for static, known-at-design-time form fields (use VcInput, VcSelect, etc. directly) + +## Basic Usage + +```vue + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| -------------------- | ---------- | ------- | ----------------------------------------------------------------------------- | +| `property` | `T` | - | Property object with `id` and metadata | +| `modelValue` | `any` | - | Current property value (v-model) | +| `valueType` | `string` | - | Type: ShortText, LongText, Number, Integer, DateTime, Boolean, Measure, Color | +| `name` | `string` | - | Property name for display and field identification | +| `required` | `boolean` | - | Whether the field is required | +| `disabled` | `boolean` | `false` | Disables the input | +| `dictionary` | `boolean` | `false` | Uses VcSelect/VcMultivalue with options | +| `multivalue` | `boolean` | `false` | Supports multiple values | +| `multilanguage` | `boolean` | `false` | Supports localized values | +| `optionsGetter` | `Function` | - | Async loader for dictionary options | +| `measurementsGetter` | `Function` | - | Async loader for measurement units | +| `rules` | `object` | - | Validation rules: `{ min, max, regex }` | + + + + Open in Storybook ↗ + + +## Value Type to Component Mapping + +| valueType | dictionary | multivalue | Component | +| --------- | ---------- | ---------- | ---------------------------- | +| ShortText | false | false | VcInput | +| ShortText | false | true | VcMultivalue | +| ShortText | true | false | VcSelect | +| ShortText | true | true | VcMultivalue (with options) | +| LongText | - | - | VcTextarea | +| Number | - | false | VcInput (number) | +| Number | - | true | VcMultivalue (number) | +| Integer | - | false | VcInput (integer, step=1) | +| Integer | - | true | VcMultivalue (integer) | +| DateTime | - | - | VcInput (datetime-local) | +| Boolean | - | - | VcSwitch | +| Measure | - | - | VcInputDropdown | +| Color | false | false | VcInput (color) | +| Color | false | true | VcMultivalue (color) | +| Color | true | false | VcSelect (with swatches) | +| Color | true | true | VcMultivalue (with swatches) | + +## Recipe: Rendering a List of Dynamic Properties + +The most common pattern is iterating over an array of properties from the API: + +```vue + + + + + + + +``` + + + + Open in Storybook ↗ + + +## Recipe: Dynamic Property with Validation + +```vue + +``` + +## Recipe: Measurement Property with Units + +```vue + +``` + +## Common Mistakes + +- **Passing the wrong `valueType` string** -- The value type must match exactly: `"ShortText"`, `"LongText"`, `"Number"`, `"Integer"`, `"DateTime"`, `"Boolean"`, `"Measure"`, `"Color"`. Mismatched casing or typos will result in no component being rendered. +- **Forgetting `optionsGetter` for dictionary properties** -- When `dictionary` is true, VcDynamicProperty needs `optionsGetter` to fetch dropdown options. Without it, the select will have no items. +- **Not unwrapping the value** -- The API returns values as `[{ value: "actual" }]`. Pass `prop.values?.[0]?.value` as `modelValue`, not the entire values array. + +## Tips + +- VcDynamicProperty uses vee-validate internally. Validation errors appear automatically below the input when rules are violated. +- For Color type with `dictionary: true`, the dropdown options include color swatches alongside text labels, making it easy for users to identify colors visually. +- The `multilanguage` prop enables localized value editing. When active, the component shows a language selector and manages separate values per locale. +- Boolean properties render as VcSwitch, which does not have a "required" visual indicator. If you need to enforce a boolean value, handle it in your form validation logic. + +## Accessibility + +- Each rendered input component provides its own label association and ARIA attributes +- Required fields are indicated visually through the child component +- Validation errors from vee-validate are displayed as error messages below the input +- All input types support keyboard navigation (Tab, Enter, Escape where applicable) +- Color dictionary options display color swatches alongside text for visual identification + +## Related Components + +- **VcInput** - Text, number, date, and color inputs +- **VcTextarea** - Multi-line text input +- **VcSelect** - Dropdown select for dictionary properties +- **VcMultivalue** - Tag-based multi-value input +- **VcSwitch** - Boolean toggle +- **VcInputDropdown** - Input with dropdown (used for Measure type) diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-editor.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-editor.md new file mode 100644 index 0000000000..6c683f29f9 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-editor.md @@ -0,0 +1,332 @@ + + + + + +# VcEditor + +A rich text editor built on TipTap that supports both Markdown and HTML content. Includes a customizable toolbar, multiple view modes (WYSIWYG, preview, source, split), fullscreen editing, image upload, character limits, and plugin-style custom toolbar buttons. + +## When to Use + +- Rich text content editing: product descriptions, blog posts, documentation +- Markdown or HTML authoring with live formatting and preview +- Content that requires image uploads alongside text +- Situations where authors need source-level control over markup + +When NOT to use: + +- Plain text input -- use [VcTextarea](./vc-textarea.md) +- Short single-line values -- use [VcInput](./vc-input.md) +- Code editing with syntax highlighting -- use a dedicated code editor + +## Quick Start + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +## Features + +### Editor Modes + +The editor header provides four view modes plus a fullscreen toggle: + +| Mode | Description | +| -------------------- | ---------------------------------------------------------- | +| **Editor** (default) | WYSIWYG rich text editing with toolbar | +| **Preview** | Read-only rendered HTML preview (sanitized via DOMPurify) | +| **Source** | Raw Markdown/HTML textarea for direct markup editing | +| **Split** | Side-by-side editor + source view for simultaneous editing | +| **Fullscreen** | Any mode expanded to fill the entire viewport | + +The editor automatically detects whether content is Markdown or HTML based on pattern analysis and outputs in the same format. HTML content is auto-formatted with Prettier in source/split views. + +!!! note "Content format is auto-detected" +VcEditor detects whether content is Markdown or HTML and outputs in the same format. If you pass Markdown input, you will get Markdown output. If you need HTML output, start with HTML content. + +### Custom Toolbar Configuration + +Limit which toolbar buttons appear by passing a `toolbar` array. Only the specified buttons will render. Available toolbar names: + +`"bold"`, `"italic"`, `"underline"`, `"strikethrough"`, `"heading1"`, `"heading2"`, `"heading3"`, `"bulletList"`, `"orderedList"`, `"blockquote"`, `"link"`, `"image"`, `"table"`, `"fontSize"`, `"separator"` + +```vue + +``` + +When no `toolbar` prop is provided, all buttons are shown by default. + +### Character Limit + +The `maxlength` prop enforces a character limit. A counter is displayed in source and split modes, and the counter turns to a warning style when 90% of the limit is reached. Input beyond the limit is blocked. + +```vue + +``` + +### Image Upload + +When `assetsFolder` is provided, the image toolbar button becomes functional. Clicking it opens a file picker for images. Selected files are uploaded via `POST /api/assets?folderUrl=/` and inserted at the cursor position. + +```vue + +``` + +Multiple images can be selected at once. The upload accepts any image file type (`image/*`). + + + + Open in Storybook ↗ + + +### Custom Toolbar Buttons (Plugin System) + +Extend the toolbar with custom buttons or dropdowns. Each custom button specifies an `id`, `label`, `icon`, `action` callback, and optional `group`/`order` for positioning. + +#### Button Plugin + +```vue + +``` + +#### Dropdown Plugin + +Dropdown plugins use `options` array instead of `action`, plus a `getValue` function to read the current state: + +```ts +{ + id: 'text-align', + label: 'Text Align', + options: [ + { value: 'left', label: 'Left', action: (editor) => editor.chain().focus().setTextAlign('left').run() }, + { value: 'center', label: 'Center', action: (editor) => editor.chain().focus().setTextAlign('center').run() }, + ], + getValue: (editor) => editor.getAttributes('paragraph').textAlign || 'left', + group: 'align', + order: 1, +} +``` + +#### Component Plugin + +For fully custom toolbar UI, provide a `component` property. The component receives `editor` and `disabled` props. + +### Additional TipTap Extensions + +Pass extra TipTap extensions via the `extensions` prop to augment the built-in set (StarterKit, Underline, TextStyle, FontSize, Table, Link, Image, Placeholder, Markdown). + +```vue + +``` + + + + Open in Storybook ↗ + + +### Validation with vee-validate Field + +Integrate with vee-validate's `Field` component for form-level validation. + +```vue + + + + + + + +``` + +> **Note:** VcEditor uses `errorMessage` directly (no separate `error` boolean prop needed). The error state is derived from the truthiness of `errorMessage`. + +## Recipes + +### Multilanguage Product Description + +```vue + +``` + +### Minimal Comment Editor + +```vue + +``` + +## Common Mistakes + +### 1. Missing assetsFolder for image uploads + +```vue + + + + + +``` + +### 2. Using error prop instead of errorMessage + +```vue + + + + + +``` + +### 3. Expecting HTML output from Markdown content + +```ts +// The editor auto-detects content format. If you pass Markdown, output is Markdown. +// If you need HTML, pass HTML content initially or convert after the fact. + +// WRONG assumption: editor always outputs HTML +const content = ref("# Title"); +// content.value after editing will be Markdown, not "Title" + +// CORRECT: if you need HTML output, start with HTML +const content = ref("Title"); +``` + +## Props + +| Prop | Type | Default | Description | +| ----------------- | --------------------- | ----------- | ------------------------------------------------------------- | +| `modelValue` | `string` | `""` | Content string via `v-model` (Markdown or HTML) | +| `label` | `string` | -- | Label text above the editor | +| `placeholder` | `string` | -- | Placeholder when editor is empty | +| `disabled` | `boolean` | `false` | Disables all editing | +| `required` | `boolean` | `false` | Shows a required asterisk on the label | +| `tooltip` | `string` | -- | Tooltip text shown on label hover | +| `errorMessage` | `string` | -- | Error message below the editor (also activates error styling) | +| `name` | `string` | -- | Form field name attribute | +| `toolbar` | `ToolbarNames[]` | all buttons | Array of toolbar button names to show | +| `maxlength` | `number` | -- | Character limit (counter shown in source/split mode) | +| `assetsFolder` | `string` | -- | API folder path for image uploads | +| `extensions` | `Extension[]` | -- | Additional TipTap extensions | +| `customButtons` | `CustomToolbarItem[]` | -- | Plugin toolbar buttons or dropdowns | +| `multilanguage` | `boolean` | `false` | Enables multilanguage indicator on the label | +| `currentLanguage` | `string` | -- | Current language code for multilanguage mode | + +## Events + +| Event | Payload | Description | +| ------------------- | --------------------- | ------------------------------------------------------------- | +| `update:modelValue` | `string \| undefined` | Emitted when content changes (from WYSIWYG or source editing) | +| `upload-image` | -- | Emitted when image upload is triggered | + +## Slots + +| Slot | Description | +| ------- | ----------------------------------------------------- | +| `error` | Custom error message markup (replaces default VcHint) | + +## CSS Variables + +| Variable | Default | Description | +| --------------------------------- | --------------------------------------------------------- | ---------------------------------------------------- | +| `--vc-editor-border` | `var(--neutrals-300)` | Default border color | +| `--vc-editor-background` | `transparent` | Editor background | +| `--vc-editor-surface` | `var(--additional-50)` | Content area surface color | +| `--vc-editor-text-primary` | `var(--neutrals-900)` | Primary text color | +| `--vc-editor-text-secondary` | `var(--neutrals-500)` | Secondary text color (char counter) | +| `--vc-editor-text-muted` | `var(--neutrals-400)` | Muted text color (placeholder) | +| `--vc-editor-text-disabled` | `var(--neutrals-500)` | Text color when disabled | +| `--vc-editor-background-disabled` | `var(--neutrals-200)` | Background when disabled | +| `--vc-editor-focus-border` | `var(--primary-500)` | Border color on focus | +| `--vc-editor-focus-ring-color` | `color-mix(in srgb, var(--primary-500) 30%, transparent)` | Focus ring color | +| `--vc-editor-error-border` | `var(--danger-500)` | Border color on error | +| `--vc-editor-error-ring-color` | `rgba(239, 68, 68, 0.2)` | Error ring color | +| `--vc-editor-error-text` | `var(--danger-500)` | Error message text color | +| `--vc-editor-separator` | `var(--neutrals-200)` | Divider lines (blockquote border, table borders, hr) | +| `--vc-editor-table-header` | `var(--neutrals-100)` | Table header cell background | + +## Accessibility + +- The root element has `aria-label` set from the `label` prop +- `aria-invalid` is set when `errorMessage` is truthy +- `aria-disabled` is set when the editor is disabled +- Toolbar buttons have descriptive `aria-label` attributes (e.g., "Preview", "Source code", "Fullscreen") +- Fullscreen toggle and view mode buttons are keyboard accessible +- The editor content area is a standard TipTap `contenteditable` region with full keyboard support; preview content is sanitized via DOMPurify + +## Related Components + +- [VcTextarea](./vc-textarea.md) -- plain multi-line text input (no formatting) +- [VcInput](./vc-input.md) -- single-line text input + + + + Open in Storybook ↗ + + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-field.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-field.md new file mode 100644 index 0000000000..d0b38c5513 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-field.md @@ -0,0 +1,260 @@ + + + + + +# VcField + +Read-only display component for labeled information, supporting various content types like text, dates, links, and emails. + +## Overview + +Blade detail views often need to show read-only information alongside editable fields: creation dates, order numbers, customer emails, store URLs, and similar metadata. Using `VcInput` in a disabled state for this purpose adds unnecessary complexity and visual noise. + +`VcField` is a purpose-built read-only display component that renders a labeled value with type-aware formatting. It supports dates (absolute and relative), clickable links, email addresses with `mailto:` links, and plain text. An optional copy-to-clipboard button lets users quickly grab values like order IDs or tracking numbers. + +The component uses a vertical layout by default (label above value), but supports horizontal layout with configurable column aspect ratios for key-value pair displays. + +## When to Use + +- Displaying read-only detail fields in blade views (e.g., order date, customer email) +- Showing labeled key-value pairs in summary sections +- When NOT editing data -- use `VcInput` for editable fields + +## Basic Usage + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +!!! tip "Prefer VcField over disabled VcInput for read-only data" +VcField renders without form-field chrome (borders, focus rings, placeholders) and formats content in a type-aware way. A disabled `VcInput` carries unnecessary visual noise for display-only scenarios. + +## Key Props + +| Prop | Type | Default | Description | +| ------------- | ----------------------------------------------------- | ------------ | --------------------------------------------------------- | +| `label` | `string` | -- | Field label text | +| `modelValue` | `string \| number \| Date` | -- | Field content to display | +| `type` | `"text" \| "date" \| "date-ago" \| "link" \| "email"` | `"text"` | Content type for formatting | +| `copyable` | `boolean` | `false` | Show a copy-to-clipboard button | +| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction of label and value | +| `aspectRatio` | `[number, number]` | `[1, 1]` | Column width ratio for label and value in horizontal mode | +| `tooltip` | `string` | -- | Tooltip shown on the label | + +## Type Formatting + +Each `type` value renders the content differently: + +| Type | Behavior | +| ------------ | -------------------------------------------------------- | +| `"text"` | Renders the value as plain text | +| `"date"` | Formats the value as a localized date string | +| `"date-ago"` | Formats the value as relative time (e.g., "3 hours ago") | +| `"link"` | Renders as a clickable `` tag opening in a new tab | +| `"email"` | Renders as a clickable `mailto:` link | + +## Common Patterns + +### Order Details Panel + +```vue + + + + + + + + + +``` + + + + Open in Storybook ↗ + + +### Horizontal Layout with Custom Ratio + +Use horizontal layout for compact key-value displays where the label and value sit side by side. The `aspectRatio` controls the relative widths of the label and value columns: + +```vue + + + + + + + +``` + + + + Open in Storybook ↗ + + +### Copyable ID Fields + +The copy button provides visual feedback (checkmark icon for 1 second) after a successful copy: + +```vue + + + + + +``` + +### Conditional Type Based on Data + +```vue + + + + + +``` + +## CSS Variables + +| Variable | Default | Description | +| ------------- | -------- | -------------------------------------------- | +| `--field-gap` | `0.5rem` | Gap between label and value in vertical mode | + +## Accessibility + +- The label is rendered via `VcLabel`, which associates with the field content +- The copy button has `aria-label="Copy to clipboard"` +- Provides visual feedback (checkmark icon) after successful copy + +## Tip: Prefer VcField Over Disabled VcInput + +For read-only display, `VcField` is lighter and cleaner than a disabled `VcInput`. It renders without form-field chrome (borders, focus rings, placeholder) and formats content type-aware: + +```vue + + + + + +``` + +## Common Mistake + +The `type` prop affects rendering, not validation. Setting `type="email"` does not validate the email format -- it only renders the value as a `mailto:` link. For input validation, use VcInput with validation rules. + +## Horizontal Layout Without Label + +In `orientation="horizontal"` the component reserves the `aspectRatio[0]` track even when `label` is omitted. This keeps a column of `VcField`s aligned with their labeled siblings in a form grid. Use vertical orientation if you do not want this reservation. + +```vue + + +``` + +## Related Components + +- [VcInput](./vc-input.md) -- editable text field (use instead when user input is needed) +- [VcLabel](../misc/vc-label.md) -- standalone label atom used internally +- [VcCol](../layout/vc-col.md) -- column layout atom used for aspect ratio + + + + Open in Storybook ↗ + + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-file-upload.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-file-upload.md new file mode 100644 index 0000000000..444924cf25 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-file-upload.md @@ -0,0 +1,365 @@ + + + + + +# VcFileUpload + +Drag-and-drop file upload zone with file type filtering, validation, loading state, and error display. Provides both drag-and-drop and click-to-browse interactions in a single drop zone. + +## When to Use + +- Uploading images, documents, or other files within forms +- When drag-and-drop UX is preferred alongside a traditional browse button +- Collecting one or more files before processing or sending to a server + +**Alternatives:** + +- For image gallery management with preview, reorder, and delete capabilities, use [VcGallery](../data-display/vc-gallery.md) +- For a simple file input without the drag-and-drop zone, use a native `` wrapped in your own UI + +## Quick Start + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +## File Type Filtering + +Control which file types are accepted with the `accept` prop. This sets the native HTML `accept` attribute on the hidden file input, filtering the file browser dialog and providing a hint for drag-and-drop: + +```vue + + + + + + + + + + + +``` + +> **Note:** The `accept` prop filters the file browser dialog but does not prevent all invalid files from being dropped. For strict validation, combine `accept` with the `rules` prop. + +## Multiple File Selection + +Allow selecting several files at once: + +```vue + +``` + +When `multiple` is `false` (default), only one file can be selected per interaction. + +## Validation with Rules + +Integrate with vee-validate for file validation rules such as size limits: + +```vue + +``` + +When validation fails, the error is displayed below the drop zone using the built-in `VcHint` component. The `upload` event is only emitted when validation passes. + +!!! warning "FileList is not a plain Array" +The `upload` event emits a `FileList` object, not `File[]`. Always convert with `Array.from(files)` before calling array methods like `.map()` or `.filter()`. + +## Loading State + +Show a loading overlay while files are being processed or uploaded: + +```vue + +``` + +Set `isUploading` to `true` before the upload and reset in a `finally` block. The loading overlay uses the `v-loading` directive and displays a spinner centered over the drop zone. + +## Custom Text and Icon + +Override the default drag-and-drop instructions and icon: + +```vue + +``` + +The default icon is `"lucide-cloud-upload"`. The default text is pulled from the `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.DRAG_HERE` and `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.BROWSE` locale keys. + + + + Open in Storybook ↗ + + +## Error Display + +Errors can come from three sources (by priority): the `errorMessage` prop, vee-validate `rules`, or the `error` slot for fully custom rendering. + +```vue + + + + + + + Only PNG files under 2 MB. + + +``` + +When any error is present, the drop zone border changes to the error color and a ring appears. + + + + Open in Storybook ↗ + + +## Disabled State + +Disable all interactions (drag, drop, click, keyboard): + +```vue + +``` + +The disabled state reduces opacity and applies `pointer-events: none`. + +## Recipe: Product Image Upload in a Form + +```vue + + + + + Save Product + + + + +``` + +## Recipe: CSV Data Import + +```vue + +``` + +```ts +const isImporting = ref(false); +const importError = ref(""); + +async function importCsv(files: FileList) { + importError.value = ""; + isImporting.value = true; + try { + await parseCsvAndImport(files[0]); + } catch (e) { + importError.value = `Import failed: ${e.message}`; + } finally { + isImporting.value = false; + } +} +``` + +## Common Mistakes + +**Not handling the FileList correctly -- treating it like an Array** + +``` +// Wrong -- FileList is not an array, Array methods do not work directly +function handleUpload(files: FileList) { + files.map(f => f.name); // TypeError: files.map is not a function +} +``` + +``` +// Correct -- convert to array first +function handleUpload(files: FileList) { + Array.from(files).map(f => f.name); +} +``` + +**Expecting the upload event to fire when validation fails** + +``` +// Wrong -- the upload event only fires when validation passes + +// If a 5 MB file is dropped, processFile is never called +``` + +``` +// Correct -- handle both success and error states + +``` + +**Forgetting to reset the loading state on error** + +``` +// Wrong -- spinner stays forever if upload fails +async function onUpload(files: FileList) { + isUploading.value = true; + await uploadToServer(files); // Throws, loading never resets +} +``` + +``` +// Correct -- use try/finally +async function onUpload(files: FileList) { + isUploading.value = true; + try { + await uploadToServer(files); + } finally { + isUploading.value = false; + } +} +``` + +## Props + +| Prop | Type | Default | Description | +| -------------- | -------------------------------------- | ----------------------------------------- | --------------------------------------------------- | +| `accept` | `string` | `".jpg, .png, .jpeg, .webp, .heic, .svg"` | Accepted file types (HTML accept attribute format) | +| `multiple` | `boolean` | `false` | Allow selecting multiple files | +| `loading` | `boolean` | `false` | Show loading spinner overlay | +| `icon` | `string` | `"lucide-cloud-upload"` | Icon displayed in the upload zone | +| `customText` | `{ dragHere: string; browse: string }` | -- | Override default drag/browse instruction text | +| `rules` | `IValidationRules` | -- | Vee-validate validation rules (e.g., `{ size: 5 }`) | +| `name` | `string` | `"Gallery"` | Form field name attribute | +| `label` | `string` | -- | Field label text | +| `tooltip` | `string` | -- | Tooltip on the label | +| `disabled` | `boolean` | `false` | Disable all interactions | +| `required` | `boolean` | `false` | Mark field as required | +| `error` | `boolean` | `false` | External error flag | +| `errorMessage` | `string` | -- | Error message text (sets error state when truthy) | + +## Events + +| Event | Payload | Description | +| -------- | ---------- | ------------------------------------------------------------------------------------ | +| `upload` | `FileList` | Emitted when valid files are selected or dropped. Only fires after validation passes | + +## Slots + +| Slot | Scope | Description | +| ------- | ----- | ----------------------------------------------------------------- | +| `error` | -- | Custom error content. Replaces the default `VcHint` error display | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------------- | --------------------- | --------------------------------- | +| `--file-upload-border-color` | `var(--neutrals-200)` | Default border color | +| `--file-upload-border-color-hover` | `var(--neutrals-400)` | Hover border color | +| `--file-upload-border-color-dragover` | `var(--primary-500)` | Border color while dragging over | +| `--file-upload-border-color-error` | `var(--danger-500)` | Error state border color | +| `--file-upload-border-radius` | `6px` | Corner radius | +| `--file-upload-drag-bg` | `var(--neutrals-100)` | Background color during drag-over | +| `--file-upload-background-color` | `transparent` | Default background color | +| `--file-upload-icon-color` | `var(--neutrals-400)` | Upload icon color | +| `--file-upload-text-color` | `var(--neutrals-400)` | Instruction text color | +| `--file-upload-error-color` | `var(--danger-500)` | Error text color | +| `--file-upload-focus-ring-color` | `var(--primary-100)` | Focus ring color | +| `--file-upload-error-ring-color` | `var(--danger-100)` | Error state ring color | + +## Accessibility + +- The drop zone has `role="button"` with `tabindex="0"` for keyboard focus. +- `aria-label` describes the upload action (uses `customText.dragHere` or the default "Upload files"). +- `aria-describedby` links to error messages and any parent form group context. +- `aria-disabled` is set when the field is disabled. +- `aria-required` is set when the field is required. +- Enter and Space keys trigger the file browser dialog. +- The disabled state applies `pointer-events: none` and reduced opacity. + +## Related Components + +- [VcGallery](../data-display/vc-gallery.md) -- Full image gallery with preview, reorder, drag-and-drop sorting, and upload +- [VcImageTile](../data-display/vc-image-tile.md) -- Image display tile used inside galleries +- [VcHint](../feedback/vc-hint.md) -- Used internally for error message display + + + + Open in Storybook ↗ + + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-form.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-form.md new file mode 100644 index 0000000000..dbc82f260d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-form.md @@ -0,0 +1,563 @@ + + + + + +# VcForm + +A lightweight `` wrapper that provides consistent styling, prevents default browser submission, and serves as the standard container for validated form fields in blade detail views. + +## When to Use + +| Scenario | Component | +| -------------------------------------- | -------------------------- | +| Blade detail view with editable fields | **VcForm** | +| Popup with a short input form | **VcForm** | +| Read-only display of data | Plain `` or `VcField` | + +> **Important:** VcForm renders a native `` element with `novalidate`. All validation is handled by **vee-validate** `Field` components, not by the browser. + +--- + +## Quick Start + + + + Open in Storybook ↗ + + +```vue + + + + + + Save + + + + + +``` + +--- + +!!! note "Form validation is handled by vee-validate" +VcForm itself does not validate fields — it only provides the `` wrapper. Use vee-validate's `Field` component around each input that needs validation rules. + +## Features + +### Basic Form Layout (VcForm + VcRow + VcCol) + +Use `VcRow` and `VcCol` inside VcForm to create multi-column layouts that match the standard blade form appearance. + +```vue + + + + + + + + + + + + + + + +``` + +`VcRow` renders a horizontal flex row. `VcCol` accepts a `:size` prop (1 = full width, 2 = half width) to control column spans. + +### Validation with vee-validate `Field` (The Critical Pattern) + +VcForm itself does **not** manage validation. Validation is provided by wrapping each input with the `Field` component from `vee-validate`. This is the standard pattern used across the entire codebase: + +```vue + + + +``` + +**How it works step by step:** + +1. `Field` receives the current value via `:model-value` and tracks it under `name` +2. The `rules` prop defines validation rules (e.g. `"required"`, `"required|email"`, `"required|min:3"`) +3. The scoped slot exposes `errors`, `errorMessage`, and `handleChange` +4. The inner input uses `v-model` for two-way binding and calls `handleChange` on every update so vee-validate stays in sync +5. `:error="!!errors.length"` toggles the input's error visual state +6. `:error-message="errorMessage"` displays the validation message below the input + +> **Important:** You must call `handleChange` via `@update:model-value`. Without it, vee-validate does not know the value changed and validation will not trigger. + +This same pattern works with all VcShell inputs: + +```vue + + + + + + + + + +``` + +### Form States with `useForm()` + +The `useForm()` composable from vee-validate provides reactive metadata about the form's validity, dirty state, and submission status. In VcShell blades, it is typically used to control toolbar button states. + +```vue + +``` + +Common usage in blade toolbar: + +```ts +const bladeToolbar = ref([ + { + id: "save", + title: "Save", + icon: "lucide-save", + disabled: computed(() => !meta.value.valid || !modified.value), + async clickHandler() { + if (meta.value.valid) { + await saveItem(); + } else { + showError("Please fix validation errors before saving."); + } + }, + }, +]); +``` + +--- + + + + Open in Storybook ↗ + + +## Recipes + +### Complete CRUD Blade Form + +This is the standard pattern for a detail blade with validated fields, toolbar save/delete, and unsaved-changes confirmation. + +```vue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + + + + Open in Storybook ↗ + + +### Form with Mixed Field Types + +Demonstrates inputs, selects, checkboxes, and switches together in a single form. + +```vue + + + + + + + + + + + + + + + + + + + + + + +``` + +> **Tip:** Only wrap fields in `Field` when they need validation rules. Simple toggles like `VcSwitch` and `VcCheckbox` can be used directly with `v-model`. + +### Server-Side Validation Errors + +Use `setFieldError()` from `useForm()` to display errors returned by the API: + +```ts +import { useForm, Field } from "vee-validate"; + +const { setFieldError } = useForm({ validateOnMount: false }); + +async function save() { + try { + await api.updateItem(item.value); + } catch (e: unknown) { + // Assume the API returns { errors: { fieldName: ["message"] } } + if (e instanceof ApiValidationError) { + for (const [field, messages] of Object.entries(e.errors)) { + setFieldError(field, messages.join("\n")); + } + } + } +} +``` + +Real-world example from the Offers module -- validating SKU uniqueness with a debounced API call: + +```ts +const validateSku = (value: string) => { + const debouncedValidation = useDebounceFn(async () => { + const errors = await validateOffer({ ...offer.value, sku: value }); + const skuErrors = errors?.filter((e) => e.propertyName?.toLowerCase() === "sku"); + setFieldError("sku", skuErrors.map((e) => t(`ERRORS.${e.errorCode}`, { value: e.attemptedValue })).join("\n")); + }, 1000); + + debouncedValidation(); +}; +``` + +--- + +## Common Mistakes + +### Not wiring `handleChange` to the input + +```vue + + + + + + + + + +``` + +### Forgetting `:model-value` on `Field` + +```vue + + + + + + + + + +``` + +### Using `validateOnMount: true` unintentionally + +```ts +// BAD: shows errors on all fields immediately when the blade opens +const { meta } = useForm({ validateOnMount: true }); + +// GOOD: validate only after user interaction +const { meta } = useForm({ validateOnMount: false }); +``` + +### Checking `meta.dirty` instead of a dedicated `modified` ref + +```ts +// BAD: meta.dirty only tracks vee-validate Field changes, +// misses switches, checkboxes, and other non-validated fields +disabled: computed(() => !meta.value.dirty), + +// GOOD: use a dedicated modification tracker from your composable +disabled: computed(() => !modified.value), +``` + +--- + +## Props + +| Prop | Type | Default | Description | +| ---------------- | -------- | ----------- | ----------------------------------------- | +| `ariaLabel` | `string` | `undefined` | Accessible label for the `` element | +| `ariaLabelledby` | `string` | `undefined` | ID of an element that labels the form | + +## Events + +| Event | Payload | Description | +| -------- | ------- | --------------------------------------------------------------------------- | +| `submit` | -- | Emitted on form submission. Native `submit` is already `preventDefault`-ed. | + +## Slots + +| Slot | Description | +| --------- | --------------------------------------------------------------- | +| `default` | Form content -- inputs, buttons, fieldsets, VcRow/VcCol layouts | + +## CSS Custom Properties + +| Variable | Default | Description | +| ------------ | ------- | ------------------------------------------------------- | +| `--form-gap` | `1rem` | Default gap between form children (when using flex gap) | + +## Accessibility + +- Renders a native `` element with `novalidate` (browser validation is disabled in favor of vee-validate) +- Supports `aria-label` and `aria-labelledby` for screen readers +- The `submit` event is automatically `preventDefault`-ed to avoid page reloads + +## Related Components + +- **[VcInput](./vc-input.md)** -- text input field +- **[VcSelect](./vc-select.md)** -- dropdown select field +- **[VcTextarea](./vc-textarea.md)** -- multiline text input +- **[VcSwitch](./vc-switch.md)** -- toggle switch +- **[VcCheckbox](./vc-checkbox.md)** -- checkbox input +- **[VcRow](../layout/vc-row.md)** -- horizontal flex row for form layout +- **[VcCol](../layout/vc-col.md)** -- column within a VcRow +- **[VcCard](../vc-card/)** -- collapsible card for grouping form sections +- **[VcBlade](../layout/vc-blade.md)** -- blade container that hosts the form +- **[VcPopup](../feedback/vc-popup.md)** -- modal dialog, often used for inline forms diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-currency.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-currency.md new file mode 100644 index 0000000000..cb99b083bd --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-currency.md @@ -0,0 +1,373 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcInputCurrency + +A specialized currency input that combines locale-aware number formatting (grouping separators, decimal precision) with a dropdown for selecting the currency. Built on top of [vue-currency-input](https://dm4t2.github.io/vue-currency-input/) and [VcInputDropdown](./vc-input-dropdown.md). + + + + Open in Storybook ↗ + + +## When to Use + +- Entering monetary values with currency selection (e.g., product prices, order totals, shipping costs) +- When locale-aware thousand separators and decimal formatting are needed +- When the user must be able to switch between currencies within the same field + +**When NOT to use:** + +- Plain numbers without formatting -- use [VcInput](./vc-input.md) with `type="number"` +- Monetary values without currency selection -- use [VcInput](./vc-input.md) with a prefix/suffix +- Selecting a currency without entering a value -- use [VcSelect](./vc-select.md) + +## Quick Start + +```vue + + + + + +``` + +## Features + +### Dual v-model Binding + +The component uses two `v-model` bindings: + +- **`v-model`** (or `v-model:modelValue`) -- the numeric amount (type `number | null`) +- **`v-model:option`** -- the selected currency code (type `string`) + +```vue + +``` + +The dropdown portion renders the available currencies. Use `optionLabel` and `optionValue` to map your data structure to display labels and values. + +### Precision Control + + + + Open in Storybook ↗ + + +The `precision` prop controls the number of decimal places (0--15). The formatting engine rounds and pads the value accordingly. + +```vue + + + + + + + + +``` + +> **Tip:** When switching currencies, consider updating `precision` dynamically. For example, JPY uses 0 decimals while USD uses 2. + +### Currency Display Mode + +The `currencyDisplay` prop controls how the currency symbol appears inside the input field: + +| Value | Example | Description | +| -------------------- | --------------------- | ------------------------ | +| `"hidden"` (default) | `1,234.56` | No currency symbol shown | +| `"symbol"` | `$1,234.56` | Locale currency symbol | +| `"code"` | `USD 1,234.56` | ISO currency code | +| `"name"` | `1,234.56 US dollars` | Full currency name | + +```vue + +``` + +### Prefix and Suffix + +Add static text decorations before or after the input value: + +```vue + + + +``` + +### Validation with vee-validate Field + +Connect to vee-validate for form-level validation: + +```vue + + + + + + + +``` + +### States + + + + Open in Storybook ↗ + + +```vue + + + + + + + + + + + + + + +``` + +## Recipes + +### Product Price Editor in a Blade + +A common pattern in e-commerce blade forms: + +```vue + + + + + + + + + + + + + + + + +``` + +### Searchable Currency Dropdown + +When working with many currencies, enable the dropdown search: + +```vue + +``` + +## Common Mistakes + +### 1. Forgetting to wire handleChange with vee-validate + +```vue + + + + + + + + + +``` + +### 2. Binding a string instead of a number + +```vue + +const price = ref("100.00"); + + +const price = ref(100); +``` + +### 3. Trying to enter negative values + +```vue + + + + + +``` + +> **Important:** The component blocks the minus key (`-`) and the exponential notation key (`e`) at the keyboard level. Pasting negative numbers is also prevented. This is intentional for currency inputs where negative values are not valid. + +## Props + +| Prop | Type | Default | Description | +| ----------------- | ------------------------------------------ | ---------- | ------------------------------------------------ | +| `modelValue` | `number \| null` | -- | Numeric value via `v-model` | +| `option` | `string` | -- | Selected currency code via `v-model:option` | +| `options` | `unknown[]` | `[]` | Available currency options for the dropdown | +| `optionValue` | `string \| Function` | `"id"` | Property or function to extract the option value | +| `optionLabel` | `string \| Function` | `"title"` | Property or function to extract the option label | +| `precision` | `0-15` | `2` | Number of decimal places | +| `currencyDisplay` | `"symbol" \| "code" \| "name" \| "hidden"` | `"hidden"` | How the currency symbol is displayed | +| `label` | `string` | -- | Label text above the field | +| `placeholder` | `string` | -- | Placeholder text | +| `hint` | `string` | -- | Helper text below the field | +| `tooltip` | `string` | -- | Tooltip on the label info icon | +| `prefix` | `string` | -- | Static text before the input value | +| `suffix` | `string` | -- | Static text after the input value | +| `clearable` | `boolean` | `false` | Shows a clear button | +| `loading` | `boolean` | `false` | Shows a spinning loader | +| `disabled` | `boolean` | `false` | Disables the entire component | +| `required` | `boolean` | `false` | Shows a required indicator | +| `error` | `boolean` | `false` | Enables error styling | +| `errorMessage` | `string` | -- | Error message below the field | +| `name` | `string` | -- | HTML name attribute | +| `autofocus` | `boolean` | `false` | Focus on mount | +| `maxlength` | `string \| number` | `1024` | Maximum input length | +| `debounce` | `string \| number` | `0` | Debounce for search input (ms) | +| `searchable` | `boolean` | `false` | Enable search in the currency dropdown | + +## Events + +| Event | Payload | Description | +| -------------------- | ---------------- | ------------------------------------------- | +| `update:model-value` | `number \| null` | Emitted when the numeric value changes | +| `update:option` | `unknown` | Emitted when the currency selection changes | +| `change` | `number \| null` | Emitted on value change (alias) | +| `blur` | `Event` | Emitted when the input loses focus | + +## CSS Variables + +| Variable | Default | Description | +| --------------------------- | -------------------- | ---------------------------- | +| `--input-curr-toggle-color` | `var(--primary-500)` | Dropdown toggle accent color | + +Additionally inherits all `--input-*` CSS variables from VcInput/VcInputDropdown. + +## Accessibility + +- Inherits all accessibility features from VcInputDropdown and VcInput +- Keyboard: Tab navigates between the number input and the dropdown toggle +- Enter key in the input blurs the field and moves focus to the next tabbable element +- Negative values are blocked at the keyboard level (minus and "e" keys prevented) +- Pasting negative numbers is prevented + +## Related Components + +- [VcInputDropdown](./vc-input-dropdown.md) -- the underlying composite input + dropdown component +- [VcInput](./vc-input.md) -- plain input for non-currency numbers +- [VcSelect](./vc-select.md) -- standalone dropdown selection + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-dropdown.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-dropdown.md new file mode 100644 index 0000000000..fc4c341ddc --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-dropdown.md @@ -0,0 +1,337 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcInputDropdown + +A composite component that combines a text input field with a dropdown option selector in a single control. The user types a value in the input while also selecting a category, unit, or format from the attached dropdown. + + + + Open in Storybook ↗ + + +## When to Use + +- Input value paired with a unit selector (e.g., "100 cm", "50 kg") +- Amount with currency selection (for raw implementation; prefer [VcInputCurrency](./vc-input-currency.md) for formatted currency display) +- Value with format choice (e.g., a date input with selectable date format) +- Any scenario requiring a free-form value plus a constrained option in one field + +**Alternatives:** + +- If you only need a dropdown without a text input, use [VcSelect](./vc-select.md) +- If you only need a text input without a dropdown, use [VcInput](./vc-input.md) +- For currency inputs with built-in locale formatting, use [VcInputCurrency](./vc-input-currency.md) + +## Quick Start + +```vue + + + + + +``` + +The component uses a dual `v-model` pattern: `v-model` controls the input value, and `v-model:option` controls the selected dropdown option. + +## Object Options + + + + Open in Storybook ↗ + + +When options are objects instead of primitives, use `optionValue` and `optionLabel` to tell the component which properties to use: + +```vue + + + + + +``` + +You can also pass functions for `optionValue` and `optionLabel` for more complex extraction logic: + +```vue + +``` + +## Searchable Dropdown + +Enable filtering inside the dropdown with the `searchable` prop. This is useful when the options list is long: + +```vue + +``` + +## Input Types + +The `inputType` prop controls the HTML input type, enabling browser-native behaviors: + +```vue + + + + + + + + +``` + +Supported types: `"text"`, `"password"`, `"email"`, `"tel"`, `"number"`, `"integer"`, `"url"`, `"time"`, `"date"`, `"datetime-local"`. + +## Component States + + + + Open in Storybook ↗ + + +VcInputDropdown inherits all standard form field states: + +```vue + + + + + + + + + + + +``` + +## Custom Dropdown Button + +Replace the default dropdown toggle with a custom element using the `button` slot: + +```vue + + + + {{ currency.symbol }} {{ currency.code }} + + + + +``` + +> **Important:** Always use `.stop.prevent` modifiers on click handlers inside the `button` slot to prevent the event from bubbling to the input. + +## Recipe: Measurement Input in a Product Form + +```vue + + + + + + Save + + +``` + +## Common Mistakes + +**Forgetting `v-model:option` -- the dropdown selection is not bound** + +``` +// Wrong -- dropdown shows options but selection is lost on re-render + +``` + +``` +// Correct -- bind both the input and the option + +``` + +**Using object options without specifying optionValue/optionLabel** + +``` +// Wrong -- dropdown shows "[object Object]" for each option + +``` + +``` +// Correct -- tell the component which properties to read + +``` + +**Missing `.stop.prevent` on custom button slot click handler** + +``` +// Wrong -- click event bubbles to the input, causing focus issues + + Toggle + +``` + +``` +// Correct -- stop propagation and prevent default + + Toggle + +``` + +## Props + +| Prop | Type | Default | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------ | +| `modelValue` | `string \| number \| Date \| null` | -- | Input field value via `v-model` | +| `option` | `unknown` | -- | Selected dropdown option via `v-model:option` | +| `options` | `unknown[]` | `[]` | Available options for the dropdown | +| `optionValue` | `string \| ((opt: unknown) => unknown)` | `"id"` | Property name or function to extract the option value | +| `optionLabel` | `string \| ((opt: unknown) => string)` | `"title"` | Property name or function to extract the display label | +| `inputType` | `"text" \| "number" \| "email" \| "tel" \| "password" \| "url" \| "time" \| "date" \| "datetime-local" \| "integer"` | `"text"` | HTML input type | +| `searchable` | `boolean` | `false` | Enable search filtering in the dropdown | +| `debounce` | `string \| number` | `0` | Debounce delay (ms) for search input | +| `clearable` | `boolean` | `false` | Show a clear button on the input | +| `prefix` | `string` | -- | Static prefix text inside the input | +| `suffix` | `string` | -- | Static suffix text inside the input | +| `maxlength` | `string \| number` | `1024` | Maximum character length for the input | +| `label` | `string` | -- | Field label text | +| `placeholder` | `string` | -- | Input placeholder text | +| `hint` | `string` | -- | Hint text below the field | +| `tooltip` | `string` | -- | Tooltip on the label | +| `disabled` | `boolean` | `false` | Disable all interactions | +| `required` | `boolean` | `false` | Mark field as required (shows asterisk) | +| `loading` | `boolean` | `false` | Show loading spinner | +| `autofocus` | `boolean` | `false` | Auto-focus on mount | +| `error` | `boolean` | `false` | External error flag | +| `errorMessage` | `string` | -- | Error message (sets error state when truthy) | +| `name` | `string` | -- | HTML name attribute for the input | + +## Events + +| Event | Payload | Description | +| ------------------- | ---------------------------------- | -------------------------- | +| `update:modelValue` | `string \| number \| Date \| null` | Input value changed | +| `update:option` | `unknown` | Dropdown selection changed | +| `change` | `unknown` | Generic change event | +| `blur` | `Event` | Input lost focus | + +## Slots + +| Slot | Scope | Description | +| --------------- | ------------------------------------------------- | ------------------------------------------ | +| `button` | `{ toggleHandler: () => void }` | Replace the dropdown toggle button | +| `control` | `{ placeholder, focused, modelValue, emitValue }` | Replace the entire input element | +| `option` | `{ index, opt, selected, toggleOption }` | Custom rendering for each dropdown option | +| `prepend` | -- | Content before the field (outside) | +| `append` | -- | Content after the field (outside) | +| `prepend-inner` | -- | Content inside the field, before the input | +| `append-inner` | -- | Content inside the field, after the input | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------- | -------------------- | --------------------------------------------------------- | +| `--input-dropdown-toggle-color` | `var(--primary-500)` | Color of the dropdown toggle button text and chevron icon | + +> **Note:** VcInputDropdown inherits all CSS variables from [VcInput](./vc-input.md) for input styling and from [VcSelect](./vc-select.md) for dropdown styling. + +## Accessibility + +- The dropdown toggle button has `aria-label="Select option"`, `aria-expanded`, and `aria-haspopup="listbox"`. +- Keyboard interaction: Tab moves focus between the input and dropdown button. Enter and Space on the toggle open/close the dropdown. +- All input accessibility features are inherited from VcInput, including label association and `aria-describedby` for error messages. +- When `disabled` is true, the entire component becomes non-interactive. + +## Related Components + +- [VcInputCurrency](./vc-input-currency.md) -- Currency-specific variant with built-in locale formatting +- [VcInput](./vc-input.md) -- Standalone text input (used internally) +- [VcSelect](./vc-select.md) -- Standalone dropdown selection (used internally) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-group.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-group.md new file mode 100644 index 0000000000..ce3374c9ff --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input-group.md @@ -0,0 +1,138 @@ + + + + + +# VcInputGroup + +A semantic `` wrapper that groups related form controls under a shared label, error state, and ARIA context. Propagates `disabled` and `name` to child controls via provide/inject. + + + + Open in Storybook ↗ + + +## When to Use + +- Grouping related form fields with a shared section label (e.g., "Billing details", "Shipping address") +- Wrapping radio buttons with `role="radiogroup"` for proper semantics +- Wrapping a set of checkboxes under a shared label +- Applying group-level disabled or error state +- When NOT to use: a single standalone field (use the field's own `label`), layout-only wrapping (use plain ``) + +## Basic Usage + +```vue + + + + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------------------ | ---------------------------- | ------------ | ------------------------------------------ | +| `label` | `string` | -- | Group label rendered as a `` | +| `tooltip` | `string` | -- | Tooltip on the label's info icon | +| `hint` | `string` | -- | Helper text below the group | +| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction for child controls | +| `role` | `"group" \| "radiogroup"` | `"group"` | ARIA role for the fieldset | +| `disabled` | `boolean` | `false` | Disables all controls in the group | +| `error` / `errorMessage` | `boolean` / `string` | -- | Group-level error styling and message | +| `required` | `boolean` | `false` | Shows required indicator on the label | +| `name` | `string` | -- | Shared `name` propagated to child controls | + +## Common Patterns + +### Radio Group + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +### Checkbox Group with Error + +```vue + + Search + Filters + Export + +``` + +### Horizontal Input Layout + +```vue + + + + +``` + +## Slots + +| Slot | Description | +| --------- | --------------------------- | +| `default` | The grouped form controls | +| `error` | Custom error message markup | +| `hint` | Custom hint text markup | + +## Accessibility + +- Renders a native `` with `` for screen readers +- `aria-labelledby` on the fieldset points to the legend +- `aria-describedby` links to hint or error text +- `aria-invalid` set when the group is in error state +- `disabled` attribute on `` natively disables all form controls inside + +## CSS Variables + +- `--input-group-gap` -- vertical gap between controls +- `--input-group-horizontal-gap` -- horizontal gap in horizontal orientation +- `--input-group-legend-spacing` -- space below the legend + +## Related Components + +- [VcCheckbox](./vc-checkbox.md) -- checkbox controls to group +- [VcRadioButton](./vc-radio-button.md) -- radio buttons to group +- [VcInput](./vc-input.md) -- text inputs to group +- [VcSelect](./vc-select.md) -- selects to group + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input.md new file mode 100644 index 0000000000..8b7e5ea5d2 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-input.md @@ -0,0 +1,819 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcInput + +A single-line text input component for forms in vc-shell applications. Supports multiple input types (text, number, password, email, and more), prefix/suffix decorations, inner/outer slot content, built-in clearable state, password visibility toggle, loading indicator, debounced model updates, and integration with vee-validate for validation. + + + + Open in Storybook ↗ + + +## When to Use + +| Scenario | Component | +| ---------------------------------------------------- | ---------------------------------------------------------------------- | +| Single-line text: names, emails, URLs, phone numbers | **VcInput** | +| Password entry with show/hide toggle | **VcInput** `type="password"` | +| Numeric entry (integers or decimals) | **VcInput** `type="number"` or `type="integer"` | +| Input with prefix/suffix text or inner icons | **VcInput** with `prefix`/`suffix` props or slots | +| Multi-line text | [VcTextarea](./vc-textarea.md) | +| Rich text / HTML editing | [VcEditor](./vc-editor.md) | +| Selecting from a dropdown list | [VcSelect](./vc-select.md) | +| Currency with formatting and currency selector | [VcInputCurrency](./vc-input-currency.md) | +| Date or date-time picking | [VcDatePicker](./vc-date-picker.md) (also available via `type="date"`) | +| Color selection | [VcColorInput](./vc-color-input.md) (also available via `type="color"`) | + +> **Note:** When you set `type="date"`, `type="datetime-local"`, or `type="color"`, VcInput internally delegates to VcDatePicker or VcColorInput. All props are forwarded automatically. You can use VcInput as a single entry point for all these types, but for date/color-specific options (like `datePickerOptions`), consider using the dedicated component directly. + +--- + +## Quick Start + +The simplest possible usage -- a text input bound to a reactive ref: + +```vue + + + + + +``` + +This renders a labeled text input with placeholder text. The value is two-way bound via `v-model`. + + + + Open in Storybook ↗ + + +--- + +## Input Types + + + + Open in Storybook ↗ + + +VcInput supports the following `type` values. Each type adjusts the native `` behavior and, in some cases, adds extra UI or filtering logic. + +| Type | Behavior | +| ---------------- | ------------------------------------------------------------------------------------ | +| `text` (default) | Standard single-line text input | +| `password` | Masked input with a built-in show/hide toggle button | +| `email` | Native email keyboard on mobile, browser email validation hints | +| `number` | Numeric input; blocks `-`, `e`, `+` keys; emits parsed `number` or `null` | +| `integer` | Like `number` but blocks decimal points and non-digit keys; emits truncated integers | +| `tel` | Telephone keyboard on mobile devices | +| `url` | URL keyboard on mobile devices | +| `time` | Native time input | +| `date` | Delegates to **VcDatePicker** with locale-aware formatting | +| `datetime-local` | Delegates to **VcDatePicker** in datetime mode | +| `color` | Delegates to **VcColorInput** | + +### Number vs. Integer + +```vue + + + + + +``` + +> **Important:** Both `number` and `integer` types block negative values. The `number` type emits a parsed `float`; the `integer` type emits a truncated `int`. Both emit `null` when the field is cleared. + +--- + +## Validation with vee-validate Field + +This is the **standard validation pattern** in vc-shell applications. VcInput does not have built-in validation rules. Instead, you wrap it with the `Field` component from [vee-validate](https://vee-validate.logaretm.com/v4/) and pass validation state through props. + +### Basic Pattern + +```vue + + + + + + + +``` + +### How It Works + +1. **`Field` wraps `VcInput`** and manages the validation lifecycle. It does NOT render any extra DOM -- it uses a scoped slot (`v-slot`). +2. **`:model-value` on `Field`** tells vee-validate what the current value is, so it can evaluate rules against it. +3. **`@update:model-value="handleChange"`** is critical. Without it, `Field` never knows the value changed, so validation never triggers. This is the most common mistake developers make. +4. **`errors` and `errorMessage`** flow from `Field` to VcInput's `:error` and `:error-message` props, which control the red border and error text display. +5. **`useForm()`** at the blade level collects all `Field` instances. Use `meta.valid` to check if the entire form passes validation before saving. + +### Multiple Rules + +```vue + + + +``` + +### Checking Form Validity Before Save + +```ts +const { meta, resetForm } = useForm({ validateOnMount: false }); + +// In your toolbar save handler: +async function onSave() { + if (meta.value.valid) { + await saveData(); + } else { + showError("Please fix validation errors before saving."); + } +} + +// Reset validation state when discarding changes: +function onReset() { + resetFormData(); + resetForm(); +} +``` + +> **Tip:** Set `validateOnMount: false` in `useForm()` to avoid showing errors immediately when the blade opens. Errors will appear after the user interacts with a field. + +--- + +## States + +### Disabled + +A disabled input is non-interactive, visually dimmed, and has `pointer-events: none`. + +```vue + +``` + +### Loading + +Shows a spinning loader icon inside the field. The input remains interactive. + +```vue + +``` + +### Error + +Error state is activated when `error` is `true` or `errorMessage` is truthy. The border turns red and an error ring appears. If `errorMessage` is provided, it displays below the field with a slide-up animation. + +```vue + +``` + +### Required + +Adds a red asterisk to the label. This is purely visual -- actual validation must be handled via `Field` from vee-validate (see [Validation](#validation-with-vee-validate-field)). + +```vue + +``` + +--- + +## Slots + +VcInput provides six slots for customizing different areas of the component. + +### prepend / append (outer slots) + +Content placed **outside** the input border, to the left (`prepend`) or right (`append`). Useful for buttons or labels that are visually separate from the field. + +```vue + + + + https:// + + + + Verify + + +``` + +### prepend-inner / append-inner (inner slots) + +Content placed **inside** the input border. Useful for icons, badges, or character counters. + +```vue + + + + + + + {{ searchQuery.length }}/100 + + + +``` + +All four positional slots receive a `{ focus }` function in their scope, which you can call to programmatically focus the native input: + +```vue + + + +``` + +### control slot + +Replaces the native `` element entirely while keeping the VcInput shell (label, border, error display, etc.). Useful for integrating third-party input components. + +```vue + + + + + +``` + +| Scope property | Type | Description | +| -------------- | ---------------------------------- | ------------------------------------------------- | +| `modelValue` | `string \| number \| Date \| null` | Current field value | +| `emitValue` | `(value) => void` | Call this to update the model (respects debounce) | +| `placeholder` | `string \| undefined` | The placeholder prop value | +| `editable` | `boolean \| undefined` | Whether the field is disabled | +| `focused` | `boolean \| undefined` | Whether autofocus is set | + +### error / hint slots + +Override the default error message or hint text rendering. + +```vue + + + + + This promo code has expired. View active codes + + + +``` + +--- + +## Sizes + + + + Open in Storybook ↗ + + +Two size variants are available: + +| Size | Height | Use case | +| ----------- | ------ | ------------------------------------------ | +| `"default"` | 36px | Standard forms, blade detail pages | +| `"small"` | 32px | Compact UI, table inline editing, toolbars | + +```vue + +``` + +--- + +## Clearable + +When `clearable` is `true`, a small "x" button appears inside the field whenever the value is non-empty. Clicking it sets the model to `null`. + +```vue + +``` + +> **Note:** The clear button does not appear on `type="password"` fields. Password fields always show the show/hide toggle instead. + +--- + +## Prefix and Suffix + +Static text displayed inside the field, before or after the user's input. Useful for units, currency symbols, or URL protocols. + +```vue + +``` + +Prefix and suffix elements are non-interactive (`pointer-events: none`) and do not receive focus. + +--- + +## Debounce + +Delays the `update:modelValue` emission by the specified number of milliseconds. Useful for search fields to avoid firing API requests on every keystroke. + +```vue + +``` + +When debounce is set, the internal `temp` value updates immediately (so the user sees their typing), but the `v-model` update and any `@update:model-value` handlers fire only after the debounce period elapses without further input. + +--- + +## Multilanguage Label + +When a field supports multiple languages, enable the language badge on the label: + +```vue + +``` + +This renders a small language indicator (e.g., "EN-US") next to the label, signaling to the user which language they are editing. + +--- + +## Tooltip + +Display additional context about a field via a tooltip icon next to the label: + +```vue + +``` + +--- + +## Recipes + +### Input in a Blade Form with VcRow/VcCol Layout + +This is the standard pattern for detail blade forms in vc-shell applications. Fields are organized into rows and columns using `VcRow` and `VcCol`, wrapped in `VcForm` and `VcContainer`. + +```vue + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Password Field with Toggle Visibility + +VcInput handles this automatically when `type="password"`. An eye icon appears inside the field that toggles between masked and plain text. + +```vue + + + + + +``` + +The toggle button automatically receives appropriate ARIA labels ("Show password" / "Hide password"). + +### Search Input with Debounce + +Combine the `debounce` prop with `prepend-inner` slot for a search icon and `clearable` for easy reset: + +```vue + + + + + + + + + +``` + +### Address Form with Multiple Validated Fields + +A realistic example from a fulfillment center blade, showing multiple `Field`-wrapped inputs in a two-column layout: + +```vue + + + + + + + + + + + + +``` + +--- + +## Common Mistakes + +### 1. Forgetting `handleChange` on `@update:model-value` + +Without calling `handleChange`, vee-validate never knows the value changed, so validation never triggers and `meta.valid` stays stale. + +```vue + + + + + + + + + +``` + +### 2. Using VcInput validation props without Field + +The `required` prop on VcInput only adds a visual asterisk. It does NOT perform validation. You must wrap with `Field` for actual validation. + +```vue + + + + + + + +``` + +### 3. Setting error-message without error prop + +VcInput only shows the error message when the computed `invalid` state is true. If you pass `error-message` but forget `error`, the message may not display. + +```vue + + + + + +``` + +> **Note:** As of the current implementation, `invalid` is computed as `!!error || !!errorMessage`. So passing only `errorMessage` does work, but it is best practice to pass both for clarity and forward compatibility. + +### 4. Expecting negative numbers from type="number" + +VcInput blocks the minus key for both `number` and `integer` types. If you need negative numbers, use the `control` slot to provide your own `` element. + +```vue + + + + + + + + + +``` + +--- + +## Full API Reference + +### Props + +| Prop | Type | Default | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- | +| `modelValue` | `string \| number \| Date \| null` | `undefined` | Bound value via `v-model` | +| `type` | `"text" \| "password" \| "email" \| "tel" \| "url" \| "time" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"` | Input type. `date`/`datetime-local` delegate to VcDatePicker; `color` delegates to VcColorInput | +| `label` | `string` | -- | Label text displayed above the field | +| `placeholder` | `string` | -- | Placeholder text inside the field | +| `hint` | `string` | -- | Help text displayed below the field | +| `tooltip` | `string` | -- | Tooltip text shown on hover next to the label | +| `prefix` | `string` | -- | Static text rendered before the input value | +| `suffix` | `string` | -- | Static text rendered after the input value | +| `name` | `string` | `"Field"` | HTML `name` attribute on the native input | +| `clearable` | `boolean` | `false` | Shows a clear (x) button when the field has a value | +| `disabled` | `boolean` | `false` | Disables the input (also inherits from `VcInputGroup` context) | +| `required` | `boolean` | `false` | Adds a red asterisk to the label (visual only, no validation) | +| `loading` | `boolean` | `false` | Shows a spinning loader icon inside the field | +| `autofocus` | `boolean` | `false` | Auto-focuses the input on mount | +| `error` | `boolean` | `false` | Activates error styling (red border and ring) | +| `errorMessage` | `string` | -- | Error text shown below the field; also activates error styling when truthy | +| `debounce` | `string \| number` | -- | Delay in ms before emitting model updates | +| `maxlength` | `string \| number` | `"1024"` | Maximum character length | +| `step` | `string` | `"1"` | Step granularity for number inputs | +| `size` | `"default" \| "small"` | `"default"` | Field height variant (36px / 32px) | +| `multilanguage` | `boolean` | `false` | Shows a language indicator badge on the label | +| `currentLanguage` | `string` | -- | Language code to display in the multilanguage badge | +| `datePickerOptions` | `VueDatePickerProps` | -- | Options forwarded to VcDatePicker (only when `type` is `date` or `datetime-local`) | + +### Events + +| Event | Payload | Description | +| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `update:modelValue` | `string \| number \| Date \| null \| undefined` | Emitted when the value changes. For `number`/`integer` types, the payload is a parsed number or `null`. Respects `debounce` if set. | +| `blur` | `Event` | Emitted when the native input loses focus | +| `focus` | -- | Emitted when the native input receives focus | + +### Slots + +| Slot | Scope | Description | +| --------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | +| `prepend` | `{ focus: () => void }` | Content **outside** the field border, to the left | +| `append` | `{ focus: () => void }` | Content **outside** the field border, to the right | +| `prepend-inner` | `{ focus: () => void }` | Content **inside** the field border, to the left | +| `append-inner` | `{ focus: () => void }` | Content **inside** the field border, to the right | +| `control` | `{ editable, focused, modelValue, emitValue, placeholder }` | Replaces the native `` element entirely | +| `error` | -- | Custom error message markup (replaces default VcHint error) | +| `hint` | -- | Custom hint text markup (replaces default VcHint) | + +--- + +## CSS Variables + +VcInput uses CSS custom properties for theming, defined on `:root`. Override these to customize the appearance across your application. + +| Variable | Default | Description | +| ----------------------------- | ---------------------- | ---------------------------------------------- | +| `--input-height` | `36px` | Height of the default size field | +| `--input-height-small` | `32px` | Height of the small size field | +| `--input-border-radius` | `6px` | Border radius of the field wrapper | +| `--input-border-color` | `var(--neutrals-300)` | Border color in the normal state | +| `--input-padding` | `12px` | Horizontal padding inside the field | +| `--input-background-color` | `var(--additional-50)` | Background color of the field | +| `--input-placeholder-color` | `var(--neutrals-400)` | Color of placeholder text | +| `--input-text-color` | `var(--neutrals-800)` | Color of the input text | +| `--input-clear-color` | `var(--neutrals-400)` | Color of the clear and show/hide buttons | +| `--input-clear-color-hover` | `var(--neutrals-600)` | Hover color of the clear and show/hide buttons | +| `--input-disabled-text-color` | `var(--neutrals-500)` | Text color when disabled | +| `--input-disabled-bg-color` | `var(--neutrals-200)` | Background color when disabled | +| `--input-text-color-error` | `var(--danger-500)` | Text color in error state | +| `--input-border-color-error` | `var(--danger-500)` | Border color in error state | +| `--input-border-color-focus` | `var(--primary-500)` | Border color when focused | +| `--input-focus-ring-color` | `var(--primary-100)` | Focus ring color (3px outline) | +| `--input-error-ring-color` | `var(--danger-100)` | Error ring color (3px outline) | + +### Theming Example + +```css +/* In your app's global styles or a scoped blade style */ +.my-custom-form { + --input-border-radius: 8px; + --input-border-color-focus: var(--primary-400); + --input-focus-ring-color: var(--primary-50); +} +``` + +--- + +## Accessibility + +VcInput follows WAI-ARIA best practices for form fields: + +- **Label association:** The label element is linked to the native `` via `aria-labelledby`, ensuring screen readers announce the label when the input is focused. +- **Error and hint association:** Error and hint text are linked via `aria-describedby`. Screen readers announce these descriptions when the user focuses the field. +- **Error state:** When `error` is true or `errorMessage` is truthy, the native input receives `aria-invalid="true"`. +- **Required fields:** The native input exposes `aria-required="true"` when the `required` prop is set. +- **Password toggle:** The show/hide button has a dynamic `aria-label` that reads "Show password" or "Hide password" depending on the current state. +- **Clear button:** The clear button has `aria-label="Clear"`. +- **Keyboard navigation:** The input is fully tabbable (`tabindex="0"`). Clear and password toggle buttons are standard `` elements and can be activated with Enter or Space. +- **InputGroup context:** When VcInput is used inside a `VcInputGroup`, it automatically inherits the group's disabled state, name, and `aria-describedby` values. + +--- + +## Related Components + +- [VcTextarea](./vc-textarea.md) -- Multi-line text input +- [VcSelect](./vc-select.md) -- Dropdown selection +- [VcInputCurrency](./vc-input-currency.md) -- Formatted currency input with currency selector +- [VcInputDropdown](./vc-input-dropdown.md) -- Input with an attached dropdown for unit/option selection +- [VcDatePicker](./vc-date-picker.md) -- Standalone date picker (also used internally when `type="date"`) +- [VcColorInput](./vc-color-input.md) -- Standalone color picker (also used internally when `type="color"`) +- [VcInputGroup](./vc-input-group.md) -- Groups multiple inputs with shared label, error state, and disabled state +- [VcLabel](../misc/vc-label.md) -- The label atom used internally by VcInput +- [VcHint](../feedback/vc-hint.md) -- The hint/error atom used internally by VcInput + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-multivalue.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-multivalue.md new file mode 100644 index 0000000000..d42c2fbaf6 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-multivalue.md @@ -0,0 +1,383 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcMultivalue + +A multi-value input component for collecting multiple entries as chips/tags. Supports two distinct modes: **free-form entry** (text, number, date, color) where users type values and press Enter, and **dictionary mode** with a searchable dropdown of predefined options. + + + + Open in Storybook ↗ + + +## When to Use + +- Collecting multiple tags, keywords, or labels (e.g., product tags, email recipients) +- Selecting multiple items from a predefined list (dictionary mode) +- Entering multiple numeric values, dates, or color codes +- Building tokenized inputs where each value is displayed as a removable chip + +When NOT to use: + +- Selecting from a list without manual entry -- use [VcSelect](./vc-select.md) with `multiple` +- Single value entry -- use [VcInput](./vc-input.md) +- Rich text content -- use [VcEditor](./vc-editor.md) + +## Quick Start + +```vue + + + + + +``` + +## Features + +### Free-form Text Entry + +In the default mode (`multivalue` is `false`), users type a value into the input and press **Enter** or **comma** to add it as a chip. This mode works with different input types. + +```vue + +``` + +### Dictionary Mode (Dropdown Selection) + + + + Open in Storybook ↗ + + +When the `multivalue` prop is `true` and `options` are provided, the component displays a searchable dropdown. Users click the field to open the dropdown, search within options, and select items. Already-selected items are automatically excluded from the dropdown. + +```vue + + + + + +``` + +### Typed Input Variants + +The `type` prop controls the input behavior: `"text"`, `"number"`, `"integer"`, `"date"`, `"datetime-local"`, `"color"`. + +```vue + + + +``` + +> **Note:** Date/datetime types constrain max width to 220px on desktop. This is removed on mobile. + +### Validation with vee-validate Field + +Integrate with vee-validate's `Field` component for form-level validation. The critical pattern passes `error`, `errorMessage`, and forwards the `handleChange` callback. + +```vue + + + + + + + +``` + +### Loading and Clearable States + +```vue + + + + + +``` + +### Custom Rendering with Slots + + + + Open in Storybook ↗ + + +Use `#option` for dropdown items and `#selected-item` for chips: + +```vue + + + + + {{ item.title }} + + + + + {{ value }} + × + + + +``` + +## Recipes + +### Tag Editor with Server-side Search + +```vue + + + + + +``` + +### Color Palette Builder + +```vue + +``` + +The color type displays a colored square for each chip. Items may include a `colorCode` property. + +## Common Mistakes + +### 1. Forgetting `multivalue` prop for dictionary mode + +```vue + + + + + +``` + +### 2. Incorrect modelValue type + +```vue + + + + + +``` + +```ts +// WRONG +const singleItem = ref({ id: "1", title: "Option 1" }); + +// CORRECT +const selectedArray = ref([{ id: "1", title: "Option 1" }]); +``` + +### 3. Missing handleChange in vee-validate integration + +```vue + + + + + + + + + +``` + +## Props + +| Prop | Type | Default | Description | +| ----------------- | -------------------------------------------------------------------------- | --------- | ------------------------------------------------------ | +| `modelValue` | `T[]` | `[]` | Array of selected values via `v-model` | +| `type` | `"text" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"` | Input type for manual entry | +| `options` | `T[]` | `[]` | Predefined options for dictionary mode | +| `optionValue` | `string` | `"id"` | Property name used as the option's unique key | +| `optionLabel` | `string` | `"title"` | Property name used as the option's display text | +| `multivalue` | `boolean` | `false` | Enables dictionary mode with dropdown | +| `clearable` | `boolean` | `false` | Shows a clear-all button when values are selected | +| `loading` | `boolean` | `false` | Shows a loading spinner in the field | +| `placeholder` | `string` | -- | Input placeholder text | +| `label` | `string` | -- | Label text above the field | +| `tooltip` | `string` | -- | Tooltip shown on label hover | +| `hint` | `string` | -- | Helper text displayed below the field | +| `disabled` | `boolean` | `false` | Disables the entire field | +| `required` | `boolean` | `false` | Shows a required asterisk on the label | +| `name` | `string` | `"Field"` | Form field name attribute | +| `error` | `boolean` | `false` | External error flag for styling | +| `errorMessage` | `string` | -- | Error message text (also sets error state when truthy) | +| `multilanguage` | `boolean` | `false` | Enables multilanguage indicator on the label | +| `currentLanguage` | `string` | -- | Current language code for multilanguage mode | + +## Events + +| Event | Payload | Description | +| -------------------- | -------- | -------------------------------------------------------- | +| `update:model-value` | `T[]` | Emitted when the selected values change | +| `close` | -- | Emitted when the dropdown closes | +| `search` | `string` | Emitted when the user types in the dropdown search field | + +## Slots + +| Slot | Scope | Description | +| --------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `option` | `{ item: T, index: number }` | Custom rendering for dropdown options (dictionary mode) | +| `selected-item` | `{ value: string \| number, item: T, index: number, remove: () => void }` | Custom rendering for selected value chips | +| `prepend` | -- | Content rendered before the field area (inside the border) | +| `append` | -- | Content rendered after the field area (inside the border) | +| `error` | -- | Custom error message markup (replaces default VcHint) | +| `hint` | -- | Custom hint markup (replaces default VcHint) | + +## CSS Variables + +The component uses `--multivalue-*` variables that fall back to `--select-*` tokens for visual consistency with VcSelect. + +| Variable | Default | Description | +| ------------------------------------ | ---------------------------------------------------------------------- | --------------------------------- | +| `--multivalue-height` | `36px` | Minimum height of the input field | +| `--multivalue-border-radius` | `var(--select-border-radius, 6px)` | Border radius | +| `--multivalue-border-color` | `var(--select-border-color, var(--neutrals-300))` | Default border color | +| `--multivalue-background-color` | `var(--select-background-color, transparent)` | Field background | +| `--multivalue-text-color` | `var(--select-text-color, var(--neutrals-800))` | Field text color | +| `--multivalue-chip-background-color` | `var(--select-multiple-options-background-color, var(--neutrals-100))` | Chip background | +| `--multivalue-chip-border-color` | `var(--select-multiple-options-border-color, var(--neutrals-200))` | Chip border | +| `--multivalue-border-color-focus` | `var(--select-border-color-focus, var(--primary-500))` | Border color on focus | +| `--multivalue-focus-ring-color` | `var(--select-focus-ring-color, var(--primary-100))` | Focus ring color | +| `--multivalue-border-color-error` | `var(--select-border-color-error, var(--danger-500))` | Border on error | +| `--multivalue-error-ring-color` | `var(--select-error-ring-color, var(--danger-100))` | Error ring color | +| `--multivalue-disabled-text-color` | `var(--neutrals-500)` | Disabled text color | +| `--multivalue-loading-color` | `var(--select-loading-color, var(--info-500))` | Loading spinner color | + +## Accessibility + +- Label linked to the field via `aria-labelledby` +- Hint and error messages linked via `aria-describedby` +- Dropdown list has `role="listbox"` with a generated `id` +- Chip remove buttons are individually focusable +- Keyboard navigation: + - **Enter** / **comma** -- submits the current input as a new value + - **Backspace** -- removes the last chip when the input is empty + - **Arrow keys** -- navigate items in the dropdown (dictionary mode) + - **Escape** -- closes the dropdown +- The `required` prop sets `aria-required` on the field +- Disabled state prevents all keyboard and pointer interaction + +## Related Components + +- [VcSelect](./vc-select.md) -- dropdown for single/multi selection without manual entry +- [VcInput](./vc-input.md) -- single-value text input +- [VcInputGroup](./vc-input-group.md) -- semantic wrapper for grouping form controls + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-button.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-button.md new file mode 100644 index 0000000000..d8d9aa9e65 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-button.md @@ -0,0 +1,231 @@ + + + + + +# VcRadioButton + +A radio button component for selecting a single option from a group. Supports string, number, and boolean value types. + +!!! note "Large reference" +This page is over 200 lines. Use the section headings to jump directly to what you need: [Basic Usage](#basic-usage), [Common Patterns](#common-patterns), [Props](#key-props), [Accessibility](#accessibility). + + + + Open in Storybook ↗ + + +## Overview + +Radio buttons are the standard UI pattern for selecting exactly one option from a small, visible set. Unlike dropdowns (VcSelect), radio buttons show all options simultaneously, making them ideal when there are 2-6 choices and the user benefits from seeing everything at once. + +`VcRadioButton` renders a styled native `` with custom CSS, ensuring full keyboard accessibility and screen reader support while matching the vc-shell design system. Multiple radio buttons sharing the same `v-model` and `name` attribute form a group where only one can be selected at a time. + +The component also supports a `binary` mode for simple true/false toggles, where clicking the radio button toggles between `true` and `false` instead of comparing against a fixed `value`. + +## When to Use + +- Choosing exactly one option from a small set (2-6 options) +- When the user needs to see all options at once +- When NOT to use: many options (use [VcSelect](./vc-select.md)), multi-select (use [VcCheckbox](./vc-checkbox.md) group), on/off toggle (use [VcSwitch](./vc-switch.md)) + +## Basic Usage + +```vue + + + + + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------------------ | -------------------- | -------------- | --------------------------------------------------------------- | +| `modelValue` | `T` | `undefined` | Bound value via `v-model` (shared across the group) | +| `value` | `T` | -- | This radio button's value. Selected when `modelValue === value` | +| `label` | `string` | -- | Text label next to the radio circle | +| `name` | `string` | `"RadioField"` | HTML `name` attribute (must be shared within a group) | +| `binary` | `boolean` | `false` | Enables boolean toggle mode (clicking toggles `true`/`false`) | +| `disabled` | `boolean` | `false` | Disables this radio button | +| `error` / `errorMessage` | `boolean` / `string` | -- | Error styling and message | + +## Common Patterns + +### Horizontal Layout + +Wrap radio buttons in a `VcInputGroup` with horizontal orientation for inline display: + +```vue + + + + + +``` + +### With Numeric Values + +```vue + + + + + + + + + +``` + +### Binary Mode + + + + Open in Storybook ↗ + + +In binary mode, clicking toggles between `true` and `false` rather than comparing to a `value`. This is useful for standalone boolean options: + +```vue + +``` + +### With Validation Error + +```vue + + + + +``` + +## Slots + +| Slot | Description | +| ------- | --------------------------- | +| `error` | Custom error message markup | + +## Accessibility + +- Uses a native `` with custom CSS styling +- `aria-invalid`, `aria-required`, `aria-describedby` set appropriately +- Focus ring on `:focus-visible` +- Keyboard: Arrow keys navigate within a group (same `name`), Space selects + +## CSS Variables + +- `--radio-size` / `--radio-dot-size` -- circle and dot dimensions +- `--radio-border-color`, `--radio-active` -- border and selected colors +- `--radio-focus-ring-color`, `--radio-error-ring-color` +- `--radio-disabled-opacity` + +## Tip: Always Set the name Attribute + +All radio buttons in the same group must share the same `name` attribute. This is required for native keyboard navigation (arrow keys) and form semantics. Without a shared `name`, arrow keys will not move between options: + +```vue + + + + + + + +``` + +## Common Mistake + +Do not mix `binary` mode with regular `value` comparison in the same group. Binary mode toggles a boolean, while normal mode compares against a specific value. Using both in one group produces unpredictable behavior: + +```vue + + + + + + + +``` + +## Related Components + +- [VcCheckbox](./vc-checkbox.md) -- for multi-select or boolean toggles +- [VcSwitch](./vc-switch.md) -- for on/off toggles +- [VcInputGroup](./vc-input-group.md) -- semantic wrapper with `role="radiogroup"` +- [VcSelect](./vc-select.md) -- dropdown for larger option sets + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-group.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-group.md new file mode 100644 index 0000000000..afc7497641 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-radio-group.md @@ -0,0 +1,171 @@ + + + + + +# VcRadioGroup + +Accessible radio button group that wraps radio controls in a semantic fieldset with shared label, hint, error state, and layout control. + + + + Open in Storybook ↗ + + +## When to Use + +- Selecting exactly one option from a set (e.g., payment method, shipping speed) +- When radio buttons need shared validation, label, and error messaging +- When NOT to use: for multiple selections, use `VcCheckboxGroup`; for two-state toggle, use `VcSwitch` + +## Basic Usage + +```vue + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| -------------- | ---------------------------- | -------------- | ----------------------------------------- | +| `modelValue` | `T` | — | Selected value (v-model) | +| `options` | `RadioGroupOption[]` | `[]` | Options to render as radio buttons | +| `label` | `string` | — | Group label (rendered as fieldset legend) | +| `tooltip` | `string` | — | Tooltip on the label | +| `hint` | `string` | — | Hint text below the group | +| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction of options | +| `name` | `string` | auto-generated | Shared name for native radio inputs | +| `disabled` | `boolean` | `false` | Disable all radio buttons | +| `required` | `boolean` | `false` | Mark group as required | +| `error` | `boolean` | `false` | External error flag | +| `errorMessage` | `string` | — | Error message text | + +## RadioGroupOption Interface + +```ts +interface RadioGroupOption { + label: string; + value: V; + disabled?: boolean; // Disable individual options +} +``` + +## Events + +| Event | Payload | Description | +| ------------------- | ------- | ---------------------- | +| `update:modelValue` | `T` | Selected value changed | + +## Slots + +| Slot | Description | +| --------- | ------------------------------------------------------------- | +| `default` | Custom radio button layout (replaces options-based rendering) | + +## Common Patterns + +### Horizontal Layout + + + + Open in Storybook ↗ + + +```vue + +``` + +### With Disabled Option + + + + Open in Storybook ↗ + + +```vue + +``` + +### Validation Error + +```vue + +``` + +### Custom Slot Layout + +```vue + + + + + +``` + +## Accessibility + +- Container is a `` with `role="radiogroup"` +- Label is rendered as a `` element +- All radio buttons share the group `name` attribute +- Hint and error messages are linked via `aria-describedby` +- Arrow keys navigate between options (native radio group behavior) +- Individual options can be disabled independently + +## Related Components + +- [VcRadioButton](./vc-radio-button.md) — individual radio button component +- [VcCheckboxGroup](./vc-checkbox-group.md) — multiple-selection option group +- [VcInputGroup](./vc-input-group.md) — generic form field group (used internally) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-rating.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-rating.md new file mode 100644 index 0000000000..2b2c051dfb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-rating.md @@ -0,0 +1,307 @@ + + + + + +# VcRating + +Read-only rating display component that visualizes a numeric value as stars, a star-and-text combination, or plain text. Designed for displaying aggregate ratings in detail views, list columns, and dashboards. + +## When to Use + +- Displaying product or seller ratings in detail views +- Showing aggregate review scores in list columns or cards +- Presenting any numeric value on a bounded scale (e.g., 1-5, 1-10) + +**Alternatives:** + +- For interactive click-to-rate input, this component is display-only and does not support user interaction. Build a custom interactive rating component if needed. +- For a simple numeric field without star visualization, use [VcField](./vc-field.md) + +## Quick Start + + + + Open in Storybook ↗ + + +```vue + + + + + +``` + +!!! tip "Display-only component" +VcRating is a read-only display component. It does not support user interaction for selecting a rating. For interactive rating input, build a custom component. + +## Display Variants + +VcRating offers three visual modes controlled by the `variant` prop: + +### Stars (Default) + +Renders filled and empty star icons. Best for visual scanning at a glance. + +```vue + + +``` + +### Star and Text + +Shows a single filled star icon alongside a numeric fraction. Compact and precise. + +```vue + + +``` + +### Text Only + +Displays just the numeric fraction. Minimal footprint for dense layouts like table cells. + + + + Open in Storybook ↗ + + +```vue + + +``` + +## Custom Max Value + +The default scale is 1-5 stars. Override with the `max` prop for different scales: + +```vue + + + + + +``` + +> **Tip:** For scales larger than 5, prefer the `"star-and-text"` or `"text"` variant. Rendering 10 individual star icons can be visually crowded. + + + + Open in Storybook ↗ + + +## Placeholder for No Rating + +When `modelValue` is `0`, `null`, or `undefined`, display a placeholder message: + +```vue + + + + +``` + +If no `placeholder` is provided and the value is falsy, the component renders an empty area. + +## Label and Tooltip + +Add a label above the rating and an optional tooltip for context: + +```vue + +``` + +The label is rendered using the internal `VcLabel` component with consistent styling across all form fields. + +## Details Slot + +Add supplementary content below the rating using the `details` slot. This is ideal for review count breakdowns or additional context: + +```vue + + + + Based on 128 reviews + + 5 stars75% + + + 4 stars15% + + + 3 stars5% + + + + +``` + +> **Note:** The `details` slot is only rendered when `variant` is `"star-and-text"` or `"text"` (i.e., inside the `text-container`). It does not appear in the pure `"stars"` variant. + +## Recipe: Product Detail View + +Display the rating alongside other product information in a typical detail blade: + +```vue + + + + + + + ({{ product.reviewCount }} reviews) + + + + + +``` + +## Recipe: Rating in a Data Table Column + +Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact display: + +```vue + + + + + + + +``` + +## Common Mistakes + +**Passing a value greater than max** + +``` +// Wrong -- 7 filled stars out of 5 looks broken + +``` + +``` +// Correct -- clamp the value before passing + +``` + +**Using the stars variant with a large max value** + +``` +// Wrong -- 10 tiny star icons are hard to read + +``` + +``` +// Correct -- use star-and-text or text for large scales + +``` + +**Expecting the details slot to render in stars variant** + +``` +// Wrong -- the details slot is only available in star-and-text/text variants + + This will not appear + +``` + +``` +// Correct -- switch to star-and-text to use the details slot + + 128 reviews + +``` + +## Props + +| Prop | Type | Default | Description | +| ------------- | -------------------------------------- | --------- | ---------------------------------------- | +| `modelValue` | `number` | -- | Current rating value to display | +| `max` | `number` | `5` | Maximum rating value (defines the scale) | +| `variant` | `"stars" \| "star-and-text" \| "text"` | `"stars"` | Display variant | +| `label` | `string` | -- | Field label text above the rating | +| `tooltip` | `string` | -- | Tooltip shown on the label | +| `placeholder` | `string` | -- | Text shown when `modelValue` is falsy | + +## Slots + +| Slot | Scope | Description | +| --------- | ----- | -------------------------------------------------------------------------------------- | +| `details` | -- | Additional content below the rating (available in `star-and-text` and `text` variants) | + +## CSS Variables + +| Variable | Default | Description | +| --------------------------------- | --------------------- | ----------------------------------------------------------------- | +| `--rating-placeholder-color` | `var(--neutrals-400)` | Color of the placeholder text | +| `--rating-star-size` | `1em` | Size of star icons | +| `--rating-gap` | `2px` | Gap between star icons | +| `--rating-special-color` | `var(--warning-500)` | Color of filled stars | +| `--rating-special-color-hover` | `var(--warning-600)` | Hover color for star icons (reserved for future interactive mode) | +| `--rating-special-color-disabled` | `var(--warning-200)` | Disabled color for star icons (reserved for future use) | + +## Accessibility + +- The rating display has `role="img"` with a descriptive `aria-label` (e.g., "Rating: 4 out of 5"). +- When no value is present, the `aria-label` falls back to the placeholder text or "No rating". +- The label is rendered via `VcLabel` with optional tooltip, maintaining consistent label semantics. +- Star icons are decorative and do not receive focus since the component is display-only. + +## Related Components + +- [VcField](./vc-field.md) -- Read-only field display, often used alongside ratings in detail views +- [VcLabel](../misc/vc-label.md) -- Label atom used internally for the label and tooltip +- [VcIcon](../misc/vc-icon.md) -- Renders the star icons internally + + + + Open in Storybook ↗ + + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-select.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-select.md new file mode 100644 index 0000000000..b250758794 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-select.md @@ -0,0 +1,735 @@ + + + + + +# VcSelect + +A dropdown list component for selecting one or multiple values. Supports synchronous and asynchronous data sources, search with debounce, infinite scrolling, custom option templates, and full integration with the framework's validation system. + +VcSelect is one of the most widely used components in vc-shell. It covers most selection scenarios: from a simple dropdown with a static list to searching via a server API with pagination. + +!!! note "Large reference" +This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Data Sources](#data-sources), [Multiple Selection](#multiple-selection), [Slots](#slots), [Props](#props). + + + + Open in Storybook ↗ + + +## When to Use + +| Scenario | Component | +| --------------------------------------- | ---------------------------------------- | +| Selection from a list (single/multiple) | **VcSelect** | +| Free text input | [VcInput](./vc-input.md) | +| Number input + unit selection | [VcInputDropdown](./vc-input-dropdown.md) | +| Tags with free-form input | [VcMultivalue](./vc-multivalue.md) | +| Date selection | [VcDatePicker](./vc-date-picker.md) | +| Color selection | [VcColorInput](./vc-color-input.md) | + +## Quick Start + +The simplest example — a static list: + +```vue + + + + + +``` + +> **Important:** by default `emitValue: true` — only the value (string/number) is passed to `v-model`, not the entire option object. If you need the full object, pass `:emit-value="false"`. + +--- + +## Data Sources + +VcSelect supports three ways to provide options. + +### Static Array of Objects + +The simplest approach. Pass an array directly: + +```vue + +``` + +By default `option-value="id"` and `option-label="title"` — if your objects use these fields, you don't need to specify them. + +### Array of Primitives + +For simple lists of strings or numbers: + +```vue + +``` + +In this case `optionValue` and `optionLabel` are not needed — the component uses the value as-is. + +### Async Function (Server API) + + + + Open in Storybook ↗ + + +To load data from a server, pass a function instead of an array. This is the most powerful mode — it automatically provides: + +- Search with debounce (500ms by default) +- Infinite scrolling (loads more on scroll down) +- Automatic resolution of the initial value by `ids` + +```vue + + + + + +``` + +> **How infinite scrolling works:** when the user scrolls to the end of the list, VcSelect calls your function with an increased `skip`. Loading continues as long as `results.length < totalCount`. + +> **How the initial value works:** if `v-model` already contains an ID but the list has not been loaded yet, VcSelect will call the function with `ids: [currentValue]` to retrieve the object for displaying the label. + +--- + +## Multiple Selection + + + + Open in Storybook ↗ + + +Add `multiple` to enable selecting several values. The model becomes an array: + +```vue + + + Выбрано: {{ selectedTags.length }} тегов + + + +``` + +Selected values are displayed as chips with a remove button. The `clearable` button resets all selections. + +--- + +## Search and Filtering + + + + Open in Storybook ↗ + + +Enable `searchable` to add a search field to the dropdown: + +```vue + +``` + +- **Static array:** filtering happens on the client side (by `optionLabel`) +- **Async function:** the search query is passed as the `keyword` parameter to your function +- **debounce:** delay before sending the request (500ms by default; can be reduced for local filtering) + +--- + +## Custom Option Rendering + + + + Open in Storybook ↗ + + +Use the `#option` slot for full control over how each option is rendered: + +```vue + + + + + + + + + {{ opt.title }} + {{ opt.description }} + + + + + + + + + +``` + +> **Required:** when using `#option`, you must call `toggleOption(opt)` on click yourself — the component does not add a click handler automatically. + +--- + +## Custom Rendering of Selected Values + +The `#selected-item` slot lets you change how chips look in multiple mode: + +```vue + + + + + {{ opt.name }} + × + + + +``` + +--- + +## Form Validation + +VcSelect **does not contain built-in validation**. For validation, use the `Field` wrapper from vee-validate, which manages the error state and passes it to VcSelect through the `error` and `error-message` props. + +### Basic Pattern — Field + VcSelect + +```vue + + + + + + + +``` + +**How it works:** + +1. `Field` wraps VcSelect and tracks the value through `:model-value` +2. `rules="required"` — the validation rule (you can combine them: `rules="required|min:1"`) +3. `v-slot="{ errorMessage, handleChange, errors }"` — destructuring the validation state +4. `@update:model-value="handleChange"` — **required!** Notifies Field about value changes +5. `:error="!!errors.length"` — switches VcSelect to the error (red) state +6. `:error-message="errorMessage"` — error text displayed below the field + +> **Important:** `handleChange` must be called manually via `@update:model-value`. Without it, Field will not be aware of the change and validation will not trigger. + +### Async Select with Validation + +For an async select with search, the pattern is the same, but `handleChange` is called alongside business logic: + +```vue + + + +``` + +### Server-Side Validation + +For errors coming from the server (e.g., duplicate SKU), use `setFieldError` from `useForm`: + +```vue + +``` + +### Complete Form with Multiple Fields + +```vue + + + + + + + + + + + + + + + + + +``` + +> **Tip:** `useForm()` collects all `Field` instances within the component. Check `meta.valid` before saving. + +--- + +## Replacing the Trigger (Custom Control) + +The `#control` slot lets you completely replace the trigger button: + +```vue + + + + {{ currentViewLabel }} + + + +``` + +--- + +## Recipes + +### Linked Selects (Cascading Selection) + +A typical pattern: selecting a category loads subcategories: + +```vue + + + + + + + +``` + +> **Key point:** `:key="categoryId"` on the second VcSelect forces the component to be fully recreated when the category changes, resetting the internal options cache. + +### Select Inside a Blade Form + +A typical pattern in vc-shell — a select on a details page: + +```vue + + + + + + + + + + + + + + + + + + + +``` + +### Empty State with a Custom Message + +```vue + + + + + No products found. Try a different search term. + + + +``` + +--- + +## Common Mistakes + +### Problem: v-model contains an object instead of an ID + +```vue + + + + + + +``` + +### Problem: Label is not displayed for the initial value + +If `v-model` contains an ID but the list has not been loaded yet — for static arrays, `mapOptions: true` (default) will resolve the label automatically. For async functions, the component will call your function with `ids: [currentValue]`. + +```vue + +const loadUsers = async (keyword?: string, skip?: number) => { return api.searchUsers({ keyword, skip, take: 20 }); }; + + +const loadUsers = async (keyword?: string, skip?: number, ids?: string[]) => { if (ids?.length) { const users = await api.getUsersByIds(ids); return { results: users, totalCount: users.length }; } return api.searchUsers({ keyword, skip, take: 20 }); }; +``` + +### Problem: Unnecessary requests with cascading selects + +Don't forget `:key` with cascading selects, otherwise the second select will retain the cache of old options. + +--- + +## Props + +| Prop | Type | Default | Description | +| ----------------- | ------------------------------------------------ | ----------- | ----------------------------------------------------------- | +| `modelValue` | `T \| T[] \| string \| string[] \| null` | `undefined` | Value (v-model). Type depends on `emitValue` and `multiple` | +| `options` | `T[] \| ((keyword?, skip?, ids?) => Promise)` | `[]` | Static array or async function | +| `optionValue` | `string \| ((opt: T) => string)` | `"id"` | Object property used as the value | +| `optionLabel` | `string \| ((opt: T) => string)` | `"title"` | Object property used for display | +| `multiple` | `boolean` | `false` | Multiple selection | +| `searchable` | `boolean` | `false` | Search through options | +| `emitValue` | `boolean` | `true` | `true` = emit the value, `false` = emit the full object | +| `clearable` | `boolean` | `true` | Clear button | +| `debounce` | `number \| string` | `500` | Search delay (ms) | +| `mapOptions` | `boolean` | `true` | Automatically look up label by value in the array | +| `placement` | `string` | `"bottom"` | Dropdown position (Floating UI placements) | +| `size` | `"default" \| "small"` | `"default"` | Field size | +| `outline` | `boolean` | `true` | Show border outline | +| `loading` | `boolean` | `false` | Loading state | +| `label` | `string` | — | Label text | +| `placeholder` | `string` | — | Placeholder | +| `required` | `boolean` | `false` | Required field (asterisk) | +| `disabled` | `boolean` | `false` | Disable the component | +| `error` | `boolean` | `false` | Error state | +| `errorMessage` | `string` | — | Error text | +| `hint` | `string` | — | Hint text below the field | +| `tooltip` | `string` | — | Tooltip next to the label | +| `prefix` | `string` | — | Prefix inside the field | +| `suffix` | `string` | — | Suffix inside the field | +| `multilanguage` | `boolean` | `false` | Multilanguage icon on the label | +| `currentLanguage` | `string` | — | Current language | +| `name` | `string` | `"Field"` | Field name for validation | + +## Events + +| Event | Payload | Description | +| ------------------- | ---------------------------------------- | ---------------------- | +| `update:modelValue` | `T \| T[] \| string \| string[] \| null` | Selected value changed | +| `search` | `string` | Search query changed | +| `close` | — | Dropdown closed | + +## Slots + +| Slot | Scope | Description | +| -------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ | +| `option` | `{ index, opt, selected, toggleOption }` | Custom option rendering. **You must call `toggleOption(opt)` on click.** | +| `selected-item` | `{ index, opt, selected, removeAtIndex }` | Custom rendering of selected chips (multiple) | +| `control` | `{ toggleHandler, isOpened }` | Full trigger replacement | +| `prepend` / `append` | — | Content outside the field | +| `prepend-inner` / `append-inner` | — | Content inside the field | +| `no-options` | — | Shown when there are no options | +| `error` / `hint` | — | Custom rendering of error/hint | + +## CSS Variables + +```css +:root { + --select-height: 36px; + --select-height-small: 28px; + --select-border-radius: 4px; + --select-border-color: var(--neutrals-300); + --select-border-color-focus: var(--primary-100); + --select-border-color-error: var(--danger-500); + --select-text-color: var(--neutrals-800); + --select-padding: 10px; + --select-background-color: var(--additional-50); + --select-background-color-disabled: var(--neutrals-200); + --select-placeholder-color: var(--neutrals-400); + --select-chevron-color: var(--primary-500); + --select-clear-color: var(--primary-500); + --select-dropdown-bg: var(--additional-50); + --select-option-background-color-hover: var(--accent-100); + --select-option-background-color-selected: var(--accent-200); +} +``` + +## Accessibility + +- **Role:** the trigger has `role="combobox"` with `aria-expanded` and `aria-haspopup="listbox"` +- **Listbox:** the dropdown has `role="listbox"` linked via `aria-controls` +- **Label:** connected via `aria-labelledby`; hint/error connected via `aria-describedby` +- **Keyboard:** Arrow Down/Up for navigation, Enter to select, Escape to close, Tab to move focus +- **Multiple:** chip remove buttons are focusable +- **Required:** `aria-required` is passed for screen readers + +## Related Components + +- [VcMultivalue](./vc-multivalue.md) — tags with free-form input (when options are created on the fly) +- [VcInputDropdown](./vc-input-dropdown.md) — text input + dropdown (number + unit of measurement) +- [VcInput](./vc-input.md) — simple text field +- [VcDatePicker](./vc-date-picker.md) — date selection +- [VcField](./vc-field.md) — wrapper with label/error/hint (read-only display) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md new file mode 100644 index 0000000000..ef90c1c420 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md @@ -0,0 +1,150 @@ + + + + + +# VcSlider + +A content carousel component built on Swiper.js for displaying slides with optional navigation buttons. Renders any content via the default slot. + + + + Open in Storybook ↗ + + +## When to Use + +- Image carousels (product galleries, banners) +- Horizontally scrollable content cards +- Any list of items that should be browsable one screen at a time +- When NOT to use: vertical scrolling lists (use standard layout), tabbed content (use tabs) + +## Basic Usage + +```vue + + + + + + {{ slide.name }} + + + + + + +``` + +## Key Props + +| Prop | Type | Default | Description | +| -------------------- | ---------------------------------------- | -------------------- | ------------------------------------------------------- | +| `slides` | `Record[] \| unknown[]` | `[]` | Array of slide data objects | +| `navigation` | `boolean` | `false` | Show previous/next navigation buttons | +| `slidesPerView` | `string \| "auto"` | `"auto"` | Number of visible slides at once | +| `spaceBetweenSlides` | `number` | `10` | Gap between slides in pixels | +| `overflow` | `boolean` | `false` | Allow slides to be visible outside the container bounds | +| `ariaLabel` | `string` | `"Content carousel"` | Accessible label for the slider region | + +## Common Patterns + +### Fixed Slides Per View + +```vue + + + + + +``` + +### Custom Navigation Buttons + + + + Open in Storybook ↗ + + +```vue + + + + + + + + + + + + + + + +``` + +### Single Slide View + +```vue + + + + + +``` + +## Slots + +| Slot | Scope | Description | +| --------- | ----------- | --------------------------------- | +| `default` | `{ slide }` | Content for each slide | +| `prevBtn` | -- | Custom previous navigation button | +| `nextBtn` | -- | Custom next navigation button | + +## Accessibility + +- Container has `role="region"` with `aria-label` +- Navigation buttons have `aria-label` ("Previous slide" / "Next slide") +- Navigation icons are `aria-hidden="true"` +- Focus ring on navigation buttons via `:focus-visible` +- Disabled navigation buttons have reduced opacity + +## CSS Variables + +- `--slider-button-background`, `--slider-button-border` -- navigation button appearance +- `--slider-button-text`, `--slider-button-text-disabled` -- button icon colors +- `--slider-button-border-radius` +- `--slider-focus-ring-color` + +## Related Components + +- [VcImage](../media/vc-image.md) -- image component often used inside slides + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-switch.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-switch.md new file mode 100644 index 0000000000..f38fc800a1 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-switch.md @@ -0,0 +1,324 @@ + + + + + +# VcSwitch + +A toggle switch component for binary on/off choices. Renders as a sliding track with a thumb indicator and supports labels, hints, validation, and value inversion. + +!!! note "Large reference" +This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables). + + + + Open in Storybook ↗ + + +## When to Use + +- Toggling a feature or setting on/off (e.g., "Enable notifications", "Publish product") +- Any boolean preference that takes effect immediately or on form save +- Settings panels where multiple toggles are listed vertically + +**When NOT to use:** + +- Selecting from more than two options -- use [VcRadioButton](./vc-radio-button.md) or [VcSelect](./vc-select.md) +- Agreement checkboxes where the user must actively check a box -- use [VcCheckbox](./vc-checkbox.md) +- Tri-state or indeterminate logic -- use [VcCheckbox](./vc-checkbox.md) with `indeterminate` + +## Quick Start + +```vue + + + + + +``` + +## Features + +### Label and Hint Text + +The `label` prop renders text above the switch. Use `hint` for helper text below the track, and `labelTooltip` for an info icon on the label itself. + +```vue + +``` + +> **Important:** The `tooltip` prop is deprecated. It previously rendered as hint text below the switch (not as a true tooltip). Use `hint` for text below the switch, or `labelTooltip` for the label info icon. A console warning is emitted in development mode if `tooltip` is used. + +### Value Inversion with trueValue / falseValue + + + + Open in Storybook ↗ + + +By default, `v-model` maps `true` to the checked (on) state and `false` to unchecked (off). The `trueValue` and `falseValue` props let you invert the mapping when your data model uses opposite semantics. + +```vue + + +``` + +When `trueValue` is `false`, the switch shows as "on" when `modelValue` is `false`, which lets you present affirmative labels ("Visible") even when the underlying boolean is negative ("isHidden"). + +### Validation with vee-validate Field + +Use vee-validate's `Field` component to integrate the switch with form validation: + +```vue + + + + + + + +``` + +### States + +```vue + + + + + + + + + + + +``` + +### In a Settings Form + +Switches work well stacked in settings panels: + +```vue + + + + + + + + + + + + + + +``` + +## Recipes + +### Feature Flag Toggle in a Module Settings Blade + +```vue + + + + + + + + + + + + + + +``` + +### Conditional Field Visibility + +Use a switch to show or hide additional fields dynamically: + +```vue + + + +``` + +## Common Mistakes + +### 1. Forgetting to wire handleChange with vee-validate + +```vue + + + + + + + + + +``` + +### 2. Using the deprecated tooltip prop for hint text + +```vue + + + + + + + + +``` + +### 3. Binding a non-boolean value + +```vue + +const status = ref("active"); + + + +const isActive = ref(true); + +``` + +## Props + +| Prop | Type | Default | Description | +| -------------- | ---------------------- | ------- | ---------------------------------------------------- | +| `modelValue` | `boolean \| undefined` | -- | Bound value via `v-model` | +| `label` | `string` | -- | Label text above the switch | +| `hint` | `string` | -- | Helper text displayed below the switch | +| `labelTooltip` | `string` | -- | Tooltip shown on the label info icon | +| `tooltip` | `string` | -- | **Deprecated.** Use `hint` or `labelTooltip` instead | +| `trueValue` | `boolean` | `true` | Value that represents the checked state | +| `falseValue` | `boolean` | `false` | Value that represents the unchecked state | +| `disabled` | `boolean` | `false` | Disables the switch | +| `required` | `boolean` | `false` | Shows a required indicator on the label | +| `error` | `boolean` | `false` | Enables error styling | +| `errorMessage` | `string` | -- | Error message displayed below the switch | +| `name` | `string` | -- | HTML name attribute for the hidden input | + +## Events + +| Event | Payload | Description | +| ------------------- | ---------------------- | ---------------------------------- | +| `update:modelValue` | `boolean \| undefined` | Emitted when the switch is toggled | + +## Slots + +| Slot | Description | +| ------- | ----------------------------------------------------------------- | +| `error` | Custom error message markup. Replaces the default `VcHint` error. | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------- | --------------------------- | ---------------------------------- | +| `--switch-width` | `36px` | Track width | +| `--switch-height` | `20px` | Track height | +| `--switch-thumb-size` | `16px` | Thumb diameter | +| `--switch-translate` | `16px` | Thumb travel distance when checked | +| `--switch-active-color` | `var(--primary-500)` | Track color when checked | +| `--switch-inactive-color` | `var(--neutrals-300)` | Track color when unchecked | +| `--switch-hover-active-color` | `var(--primary-600)` | Hover track color when checked | +| `--switch-hover-inactive-color` | `var(--neutrals-400)` | Hover track color when unchecked | +| `--switch-thumb-color` | `var(--additional-50)` | Thumb background color | +| `--switch-thumb-shadow` | `0 1px 3px rgba(0,0,0,0.1)` | Thumb box shadow | +| `--switch-focus-ring-color` | `var(--primary-100)` | Focus ring color | +| `--switch-error-ring-color` | `var(--danger-100)` | Error ring color | +| `--switch-error-border-color` | `var(--danger-500)` | Error border color | +| `--switch-border-radius` | `9999px` | Track border radius | +| `--switch-disabled-opacity` | `0.5` | Opacity when disabled | + +## Accessibility + +- Renders a native `` with `role="switch"` +- `aria-checked` reflects the current state +- `aria-invalid` is set when in error state +- `aria-required` is set for required fields +- `aria-describedby` links to hint and error elements +- Keyboard: Space or Enter toggles the switch, Tab navigates focus +- Focus ring appears on `:focus-visible` only (not on mouse click) +- Disabled state applies `pointer-events: none` and reduced opacity + +## Related Components + +- [VcCheckbox](./vc-checkbox.md) -- for checkboxes and checkbox groups +- [VcRadioButton](./vc-radio-button.md) -- for mutually exclusive choices +- [VcInputGroup](./vc-input-group.md) -- semantic wrapper for grouping form controls + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-textarea.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-textarea.md new file mode 100644 index 0000000000..00559f2987 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-textarea.md @@ -0,0 +1,332 @@ + + + + + +!!! note "Large reference page" +This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need. + +# VcTextarea + +A multi-line text input field for entering and editing large blocks of text. Provides label, placeholder, hint text, validation error display, character limits, and multilanguage support out of the box. + + + + Open in Storybook ↗ + + +## When to Use + +- Multi-line free-form text: descriptions, comments, notes, addresses, bios +- Content that typically exceeds a single line +- Form fields where the user needs to see multiple lines at once + +**When NOT to use:** + +- Single-line values such as names or emails -- use [VcInput](./vc-input.md) +- Rich formatted text with bold, lists, or links -- use [VcEditor](./vc-editor.md) + +## Quick Start + +```vue + + + + + +``` + +## Features + +### Character Limit + +Set `maxlength` to restrict the number of characters. The browser enforces the limit natively on the `` element. + +```vue +<VcTextarea v-model="bio" label="Short bio" maxlength="200" hint="Maximum 200 characters" /> +``` + +> **Tip:** Combine `maxlength` with a `hint` slot to show a live character counter if your form requires one. + +### Hint and Tooltip + +Use `hint` for helper text below the field, and `tooltip` for an info icon on the label. + +```vue +<VcTextarea v-model="notes" label="Internal notes" hint="These notes are visible only to administrators" tooltip="Will not appear on the public storefront" /> +``` + +When an error message is present, the hint is automatically hidden and replaced by the error message. The transition between them is animated. + +### Multilanguage Indicator + +When editing translatable content, enable the language badge on the label: + +```vue +<VcTextarea v-model="localizedDescription" label="Description" multilanguage current-language="en-US" placeholder="Enter description in English..." /> +``` + +### Validation with vee-validate Field + +The recommended way to integrate form validation is through vee-validate's `Field` component. This connects the textarea to the form's validation schema and provides real-time error feedback. + +```vue +<template> + <Field + v-slot="{ errorMessage, handleChange, errors }" + :model-value="form.description" + name="description" + rules="required|min:10" + > + <VcTextarea + v-model="form.description" + label="Product description" + required + placeholder="Describe the product..." + :error="!!errors.length" + :error-message="errorMessage" + @update:model-value="handleChange" + /> + </Field> +</template> + +<script setup lang="ts"> +import { reactive } from "vue"; +import { Field } from "vee-validate"; +import { VcTextarea } from "@vc-shell/framework"; + +const form = reactive({ + description: "", +}); +</script> +``` + +### States + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=form-vctextarea--with-error&viewMode=story" + loading="lazy" + title="form-vctextarea--with-error" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/form-vctextarea--with-error" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +```vue +<!-- Required field --> +<VcTextarea v-model="value" label="Address" required /> + +<!-- Disabled field --> +<VcTextarea v-model="value" label="Read-only notes" disabled /> + +<!-- Error state --> +<VcTextarea v-model="value" label="Comments" :error="true" error-message="Comments must not be empty" /> +``` + +## Recipes + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=form-vctextarea--with-max-length&viewMode=story" + loading="lazy" + title="form-vctextarea--with-max-length" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/form-vctextarea--with-max-length" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +### Product Description in a Blade Form + +A typical product-editing blade with a description textarea and character limit: + +```vue +<template> + <VcBlade title="Edit Product"> + <VcContainer> + <VcRow> + <VcCol size="8"> + <VcInput + v-model="product.name" + label="Product name" + required + /> + </VcCol> + </VcRow> + <VcRow> + <VcCol size="12"> + <Field + v-slot="{ errorMessage, handleChange, errors }" + :model-value="product.description" + name="description" + rules="required|max:2000" + > + <VcTextarea + v-model="product.description" + label="Description" + required + maxlength="2000" + placeholder="Describe the product for customers..." + hint="HTML is not supported. Maximum 2000 characters." + :error="!!errors.length" + :error-message="errorMessage" + @update:model-value="handleChange" + /> + </Field> + </VcCol> + </VcRow> + </VcContainer> + </VcBlade> +</template> +``` + +### Custom Error Slot + +Override the default error rendering with the `error` slot: + +```vue +<VcTextarea v-model="value" label="JSON payload" :error="!!jsonError" :error-message="jsonError"> + <template #error> + <div class="tw-flex tw-items-center tw-gap-1 tw-text-[color:var(--danger-500)] tw-text-xs tw-mt-1"> + <VcIcon icon="lucide-alert-triangle" size="xs" /> + <span>{{ jsonError }}</span> + </div> + </template> +</VcTextarea> +``` + +## Common Mistakes + +### 1. Forgetting to wire handleChange with vee-validate + +```vue +<!-- ❌ Validation never triggers — Field does not know about changes --> +<Field v-slot="{ errorMessage, errors }" :model-value="form.notes" name="notes" rules="required"> + <VcTextarea + v-model="form.notes" + :error="!!errors.length" + :error-message="errorMessage" + /> +</Field> + +<!-- ✅ Always emit handleChange so Field tracks the value --> +<Field v-slot="{ errorMessage, handleChange, errors }" :model-value="form.notes" name="notes" rules="required"> + <VcTextarea + v-model="form.notes" + :error="!!errors.length" + :error-message="errorMessage" + @update:model-value="handleChange" + /> +</Field> +``` + +### 2. Setting error-message without error flag + +```vue +<!-- ❌ Error message appears but no visual error styling --> +<VcTextarea v-model="value" error-message="Something went wrong" /> + +<!-- ✅ Either set both, or just set errorMessage (which auto-triggers invalid state internally) --> +<VcTextarea v-model="value" :error="true" error-message="Something went wrong" /> +``` + +> **Important:** The component computes `invalid` from `props.error || props.errorMessage`. Providing `errorMessage` alone is sufficient to trigger the error ring, but explicitly passing `:error="true"` makes intent clearer. + +### 3. Using v-model on the wrong type + +```vue +<!-- ❌ Passing a number — textarea always emits string --> +<VcTextarea v-model="count" /> + +<!-- ✅ Use a string ref --> +const description = ref<string>(""); +<VcTextarea v-model="description" /> +``` + +## Props + +| Prop | Type | Default | Description | +| ----------------- | --------- | ----------- | ----------------------------------------------- | +| `modelValue` | `string` | `undefined` | Bound value via `v-model` | +| `label` | `string` | -- | Label text displayed above the textarea | +| `placeholder` | `string` | -- | Placeholder text inside the empty textarea | +| `hint` | `string` | -- | Helper text displayed below the field | +| `tooltip` | `string` | -- | Tooltip on the label info icon | +| `maxlength` | `string` | `"1024"` | Maximum character count (native HTML attribute) | +| `required` | `boolean` | `false` | Shows a required indicator on the label | +| `error` | `boolean` | `false` | Enables error styling (red border + ring) | +| `errorMessage` | `string` | -- | Error message text below the field | +| `disabled` | `boolean` | `false` | Disables the textarea | +| `name` | `string` | `"Field"` | HTML name attribute | +| `multilanguage` | `boolean` | `false` | Shows language badge on the label | +| `currentLanguage` | `string` | -- | Language code displayed in the badge | + +## Events + +| Event | Payload | Description | +| ------------------- | --------------------- | -------------------------------- | +| `update:modelValue` | `string \| undefined` | Emitted on every input keystroke | + +## Slots + +| Slot | Description | +| ------- | ----------------------------------------------------------------- | +| `error` | Custom error message markup. Replaces the default `VcHint` error. | +| `hint` | Custom hint text markup. Replaces the default `VcHint`. | + +## Exposed Methods + +| Method | Description | +| --------- | -------------------------------------------------------- | +| `focus()` | Programmatically focuses the native `<textarea>` element | + +## CSS Variables + +| Variable | Default | Description | +| -------------------------------- | --------------------- | ------------------------------ | +| `--textarea-height` | `120px` | Minimum height of the textarea | +| `--textarea-border-color` | `var(--neutrals-300)` | Default border color | +| `--textarea-border-color-focus` | `var(--primary-500)` | Border color on focus | +| `--textarea-border-color-error` | `var(--danger-500)` | Border color in error state | +| `--textarea-border-radius` | `6px` | Corner radius | +| `--textarea-background-color` | `transparent` | Background color | +| `--textarea-text-color` | `var(--neutrals-800)` | Text color | +| `--textarea-text-color-error` | `var(--danger-500)` | Text color in error state | +| `--textarea-placeholder-color` | `var(--neutrals-400)` | Placeholder text color | +| `--textarea-focus-ring-color` | `var(--primary-100)` | Focus ring color | +| `--textarea-error-ring-color` | `var(--danger-100)` | Error ring color | +| `--textarea-disabled-text-color` | `var(--neutrals-500)` | Text color when disabled | + +## Accessibility + +- The `<label>` is linked to the `<textarea>` via `aria-labelledby` +- Hint and error text are connected via `aria-describedby` +- Error state sets `aria-invalid="true"` on the native textarea +- Required fields expose `aria-required="true"` +- Keyboard: fully tabbable, standard textarea behavior (Enter creates new lines, Tab moves focus) +- The field wrapper also responds to `textarea[aria-invalid="true"]` via a CSS `:has()` selector for future-proof form system integration + +## Related Components + +- [VcInput](./vc-input.md) -- single-line text input +- [VcEditor](./vc-editor.md) -- rich text / Markdown editor +- [VcInputGroup](./vc-input-group.md) -- semantic wrapper for grouping form controls + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/.pages new file mode 100644 index 0000000000..8691fcaf44 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/.pages @@ -0,0 +1,13 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Layout +nav: + - VcApp: vc-app.md + - VcAuthLayout: vc-auth-layout.md + - VcBlade: vc-blade.md + - VcCard: vc-card.md + - VcCol: vc-col.md + - VcContainer: vc-container.md + - VcRow: vc-row.md + - VcScrollableContainer: vc-scrollable-container.md + - VcSidebar: vc-sidebar.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-app.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-app.md new file mode 100644 index 0000000000..0f2fd4403c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-app.md @@ -0,0 +1,251 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-app/vc-app.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcApp + +The root application shell that bootstraps the VirtoCommerce admin UI. It provides the desktop sidebar / mobile top bar layout, blade navigation workspace, popup container, module loading, and service registration. Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcapp--desktop-expanded&viewMode=story" + loading="lazy" + title="layout-vcapp--desktop-expanded" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcapp--desktop-expanded" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +!!! note "One VcApp per application" +Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree. Multiple instances cause service registration conflicts. + +## When to Use + +- Every VirtoCommerce admin application must have exactly one `VcApp` at the root. +- It should wrap the entire authenticated application experience. +- When NOT to use: for authentication pages use `VcAuthLayout` instead. + +## Basic Usage + +```vue +<template> + <VcApp + :is-ready="isReady" + :logo="logoUrl" + :title="appTitle" + :name="user.name" + :role="user.role" + /> +</template> + +<script setup lang="ts"> +import { ref, reactive } from "vue"; +import { VcApp } from "@vc-shell/framework"; + +const isReady = ref(true); +const logoUrl = "/logo.svg"; +const appTitle = "Vendor Portal"; +const user = reactive({ name: "John", role: "Admin" }); +</script> +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------- | --------- | ------------------ | --------------------------------------------------------------------------------------------------------- | +| `isReady` | `boolean` | _required_ | When false, shows a full-screen loading spinner. | +| `logo` | `string` | -- | Logo image URL for the sidebar/top bar. | +| `title` | `string` | -- | Application title shown in the sidebar. | +| `version` | `string` | -- | App version string (informational). | +| `avatar` | `string` | -- | User avatar image URL. | +| `name` | `string` | -- | Current user display name. | +| `role` | `string` | -- | Current user role label. | +| `disableMenu` | `boolean` | `false` | Hide navigation menu items. | +| `disableAppHub` | `boolean` | `false` | Hide the Applications section inside the App Hub. | +| `showSearch` | `boolean` | `false` | Show a search input in the sidebar that filters menu items by title. | +| `searchPlaceholder` | `string` | `"Search keyword"` | Placeholder text for the sidebar search input. Falls back to i18n key `SHELL.SIDEBAR.SEARCH_PLACEHOLDER`. | + +## Slots + +| Slot | Props | Description | +| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `layout` | `{ isMobile, sidebar, appsList, switchApp, openRoot, handleMenuItemClick }` | Override the entire layout (sidebar + navigation). | +| `menu` | `{ expanded, onItemClick, searchQuery }` | Custom navigation menu. `searchQuery` contains the current search input value (empty string when search is inactive). | +| `sidebar-header` | `{ logo, expanded, isMobile }` | Custom sidebar header. | +| `sidebar-footer` | `{ avatar, name, role }` | Custom sidebar footer (user info). | +| `workspace` | `{ isAuthenticated }` | Override the blade navigation workspace. | +| `app-hub` | `{ appsList, switchApp }` | Custom content for the Applications section of the App Hub. | + + + +## Features + +### Responsive Layout Switching + +On desktop viewports, VcApp renders a collapsible sidebar on the left with navigation menu items, user info in the footer, and the blade workspace on the right. On mobile viewports, the sidebar is replaced by a top bar with a hamburger menu that opens a slide-over navigation panel. + +### Sidebar Menu Search + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcapp--with-sidebar-search&viewMode=story" + loading="lazy" + title="layout-vcapp--with-sidebar-search" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcapp--with-sidebar-search" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +When `showSearch` is `true`, a search input appears at the top of the sidebar (desktop) or mobile navigation panel. It filters menu items in real time (300ms debounce) by matching the search query against translated item titles: + +- **Standalone items** — shown if their title contains the query. +- **Group items** — if the group title matches, all accessible children are shown. Otherwise, only children whose titles match are displayed. +- The search query is automatically cleared when a menu item is clicked or when the sidebar collapses. + +On desktop, the search input is visible only when the sidebar is expanded (pinned). On mobile, it appears inside the slide-out navigation panel. + +If you use the `menu` slot to provide a custom menu, the `searchQuery` prop is passed to your slot so you can implement your own filtering logic. + +```vue +<template> + <VcApp + :is-ready="true" + logo="/logo.svg" + title="Admin" + show-search + search-placeholder="Find a module..." + > + <!-- Default menu with built-in filtering — no extra code needed --> + </VcApp> +</template> +``` + +#### Custom Menu with Search + +```vue +<template> + <VcApp + :is-ready="true" + logo="/logo.svg" + title="Admin" + show-search + > + <template #menu="{ expanded, onItemClick, searchQuery }"> + <MyCustomMenu + :expanded="expanded" + :filter="searchQuery" + @select="onItemClick" + /> + </template> + </VcApp> +</template> +``` + +### Dynamic Module Registration + +Modules registered via `useDynamicModules()` are loaded at runtime. Each module can contribute menu items, blades, toolbar actions, settings pages, and dashboard widgets. VcApp handles module loading errors gracefully by displaying notification toasts. + +### App Hub + +The App Hub is a popover panel (desktop) or a swipeable tab (mobile) that combines two sections: + +- **Applications** — tile grid of registered apps (e.g., Vendor Portal, Marketplace Admin). Clicking an app switches context without a full page reload. This section can be hidden with `disableAppHub` or customized via the `app-hub` slot. The list is searchable via a built-in search input inside the hub. +- **Widgets** — registered app bar widgets (notifications, background tasks, etc.). Clicking a widget expands its content inline (desktop) or navigates to its panel (mobile). Widgets are registered via `useAppBarWidget()` and can display badges for unread counts. + +On desktop, the App Hub opens from the sidebar header menu button (`AppHubPopover`). On mobile, it appears as a second tab ("Hub") in the slide-out navigation panel — users can swipe between Menu and Hub tabs. + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcapp--mobile&viewMode=story" + loading="lazy" + title="layout-vcapp--mobile" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcapp--mobile" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Minimal App Setup + +```vue +<script setup lang="ts"> +import { ref, onMounted } from "vue"; +import { VcApp } from "@vc-shell/framework"; + +const isReady = ref(false); +const user = ref({ name: "", role: "" }); + +onMounted(async () => { + const profile = await fetchUserProfile(); + user.value = profile; + isReady.value = true; +}); +</script> + +<template> + <VcApp + :is-ready="isReady" + logo="/img/logo.svg" + title="My Admin" + :name="user.name" + :role="user.role" + /> +</template> +``` + +## Recipe: Custom Sidebar Footer + +Replace the default user info section with a custom footer: + +```vue +<template> + <VcApp + :is-ready="true" + logo="/logo.svg" + title="Admin" + > + <template #sidebar-footer="{ avatar, name, role }"> + <div class="tw-flex tw-items-center tw-gap-3 tw-p-3"> + <img + :src="avatar" + class="tw-w-8 tw-h-8 tw-rounded-full" + /> + <div> + <div class="tw-text-sm tw-font-medium">{{ name }}</div> + <div class="tw-text-xs tw-text-gray-500">{{ role }}</div> + </div> + <VcButton + variant="ghost" + size="icon" + icon="lucide-log-out" + @click="logout" + /> + </div> + </template> + </VcApp> +</template> +``` + +## Common Mistakes + +- **Nesting VcApp inside another VcApp** -- There must be exactly one VcApp per page. Multiple instances will cause service registration conflicts and duplicate sidebars. +- **Setting `isReady` to true before user data loads** -- If the app renders before authentication is confirmed, users may see a flash of the shell with empty user info. Keep `isReady` false until your auth check completes. +- **Using VcApp for auth pages** -- Auth pages (login, register, reset password) should use `VcAuthLayout`, not VcApp. Your router should switch between the two at the top level. + +## Tips + +- The `disableMenu` prop is useful for single-purpose apps that do not need sidebar navigation (e.g., a standalone settings page or an embedded widget). +- Use the `layout` slot only as a last resort for completely custom layouts. For most customizations, the more specific slots (`menu`, `sidebar-header`, `sidebar-footer`) are sufficient. +- The `version` prop is informational and can be displayed in the sidebar footer or a settings page. It does not affect any runtime behavior. +- VcApp provides shell services via Vue's provide/inject system. Child components access them through composables like `useMenuService()`, `useToolbarService()`, etc. + +## Accessibility + +- Responsive layout adapts to mobile/desktop viewports automatically. +- Sidebar navigation is keyboard-accessible with arrow key navigation. +- Loading state uses a full-screen spinner with no interactive elements. +- Mobile menu opens as a slide-over panel with focus trapping. + +## Related Components + +- **VcBlade** -- the panel component rendered inside the workspace. +- **VcBladeNavigation** -- manages blade stack and horizontal scrolling. +- **VcAuthLayout** -- layout for pre-authentication pages (login, register). +- **VcSidebar** -- the slide-over panel component (used internally for mobile nav). diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-auth-layout.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-auth-layout.md new file mode 100644 index 0000000000..bb74966420 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-auth-layout.md @@ -0,0 +1,236 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcAuthLayout + +A full-page centered authentication layout for login, registration, password reset, and other auth-related screens. VcAuthLayout renders a vertically and horizontally centered card on top of an optional background image, with a logo, title, subtitle, form content area, and a footer slot for legal links. It is the standard layout for all pre-authentication pages in VirtoCommerce admin applications. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcauthlayout--default&viewMode=story" + loading="lazy" + title="layout-vcauthlayout--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcauthlayout--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +!!! warning "Use outside VcApp" +VcAuthLayout is a full-page layout meant to replace `VcApp`, not nest inside it. Your router should switch between VcAuthLayout (for auth routes) and VcApp (for authenticated routes) at the top level. + +## When to Use + +- Use for any authentication page: sign-in, sign-up, password reset, email verification +- Use when you need a centered card with logo, title, and form content +- When NOT to use: for in-app layouts, dashboards, or blade-based content (use VcApp with blade navigation instead); for modal auth prompts inside the app (use VcPopup) + +## Basic Usage + +```vue +<template> + <VcAuthLayout + logo="/img/logo.svg" + title="Sign In" + subtitle="Welcome back" + > + <form @submit.prevent="handleLogin"> + <VcInput + v-model="email" + label="Email" + /> + <VcInput + v-model="password" + label="Password" + type="password" + /> + <button type="submit">Sign In</button> + </form> + <template #footer> <a href="/terms">Terms of Service</a> | <a href="/privacy">Privacy Policy</a> </template> + </VcAuthLayout> +</template> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------ | -------- | -------- | -------------------------------- | +| `logo` | `string` | - | Path or URL to the logo image | +| `logoAlt` | `string` | `"Logo"` | Alt text for the logo | +| `title` | `string` | - | Card heading | +| `subtitle` | `string` | - | Card subheading | +| `background` | `string` | - | Background image URL (preloaded) | +| `bgColor` | `string` | - | Background color CSS override | + +## Slots + +| Slot | Description | +| --------- | ----------------------------------------------------- | +| `default` | Form content (fields, buttons, SSO providers, errors) | +| `footer` | Below-card area (terms, privacy links) | + +## Features + +### Background Image Preloading + +When a `background` URL is provided, VcAuthLayout preloads the image before displaying it, preventing a flash of unstyled content. The image fills the viewport behind the card. + +### Responsive Card + +The card is centered both vertically and horizontally. On narrow viewports, it stretches to fill the available width with appropriate padding, ensuring the form remains usable on mobile devices. + +### Semantic Structure + +The layout uses a `<main>` element as the page landmark and an `<h2>` for the card title, providing a correct heading hierarchy for screen readers and SEO. + +## Recipe: Sign-In Page with SSO + +```vue +<template> + <VcAuthLayout + logo="/img/logo.svg" + title="Sign In" + subtitle="Enter your credentials or use a social provider" + background="/img/auth-bg.jpg" + > + <form + @submit.prevent="handleLogin" + class="tw-space-y-4" + > + <VcInput + v-model="email" + label="Email" + type="email" + required + /> + <VcInput + v-model="password" + label="Password" + type="password" + required + /> + <VcButton + type="submit" + variant="primary" + class="tw-w-full" + > + Sign In + </VcButton> + </form> + + <div class="tw-my-4 tw-text-center tw-text-sm tw-text-gray-500">or</div> + + <div class="tw-space-y-2"> + <VcButton + variant="outline" + class="tw-w-full" + @click="loginWithGoogle" + > + Continue with Google + </VcButton> + <VcButton + variant="outline" + class="tw-w-full" + @click="loginWithAzure" + > + Continue with Azure AD + </VcButton> + </div> + + <template #footer> + <nav + aria-label="Legal links" + class="tw-text-sm tw-text-gray-500" + > + <a href="/terms">Terms</a> · <a href="/privacy">Privacy</a> + </nav> + </template> + </VcAuthLayout> +</template> +``` + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcauthlayout--with-sso-providers&viewMode=story" + loading="lazy" + title="layout-vcauthlayout--with-sso-providers" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcauthlayout--with-sso-providers" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Password Reset Page + +```vue +<template> + <VcAuthLayout + logo="/img/logo.svg" + title="Reset Password" + subtitle="Enter your email to receive a reset link" + > + <form + @submit.prevent="sendResetLink" + class="tw-space-y-4" + > + <VcInput + v-model="email" + label="Email" + type="email" + required + /> + <VcBanner + v-if="successMessage" + variant="success" + icon="lucide-circle-check" + > + {{ successMessage }} + </VcBanner> + <VcBanner + v-if="errorMessage" + variant="danger" + icon="lucide-circle-alert" + > + {{ errorMessage }} + </VcBanner> + <VcButton + type="submit" + variant="primary" + class="tw-w-full" + :disabled="isSending" + > + Send Reset Link + </VcButton> + </form> + <div class="tw-mt-4 tw-text-center"> + <VcLink @click="goToSignIn">Back to Sign In</VcLink> + </div> + </VcAuthLayout> +</template> +``` + +## Common Mistakes + +- **Using VcAuthLayout inside VcApp** -- VcAuthLayout is a full-page layout meant to replace VcApp, not nest inside it. Your router should switch between VcAuthLayout (for auth routes) and VcApp (for authenticated routes). +- **Missing form accessibility** -- Always add `aria-required`, `autocomplete` attributes, and `<label>` associations on inputs inside the form. VcInput handles this when you use its `label` prop. +- **Forgetting the logo** -- Without a `logo` prop, the card has no branding. Always provide a logo path for a professional appearance. + +## Tips + +- Use `bgColor` for a solid background when you do not have a background image. Example: `bg-color="#1a1a2e"`. +- The `background` prop accepts any valid CSS image URL. For best results, use a high-resolution image (1920x1080 or larger) with some blur or overlay in the image itself to keep the card readable. +- The footer slot is ideal for legal links (Terms of Service, Privacy Policy). Wrap them in a `<nav>` with `aria-label` for accessibility. +- VcAuthLayout does not include any routing logic. Handle navigation between sign-in, sign-up, and password reset using your Vue Router configuration. + +## Accessibility + +- Uses semantic `<main>` element as the page landmark +- `<h2>` for the card title provides heading hierarchy +- Logo image has configurable `alt` text via `logoAlt` prop +- Form content should include `aria-required`, `autocomplete`, and proper `<label>` associations +- Footer area should use `<nav>` with `aria-label` for link groups + +## Related Components + +- **VcInput** - Text input fields commonly used inside auth forms +- **VcButton** - Action buttons for form submission +- **VcPopup** - Modal dialogs (for in-app auth prompts, not full-page auth) +- **VcApp** - The authenticated application shell (counterpart to VcAuthLayout) diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-blade.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-blade.md new file mode 100644 index 0000000000..757f086bf8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-blade.md @@ -0,0 +1,715 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-blade/vc-blade.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcBlade + +The foundational container component of the VirtoCommerce admin shell. Blades are stacked panels -- inspired by the Azure Portal -- that form the primary navigation paradigm. Every screen in a vc-shell application is a blade. + +## Why Blades? + +Traditional admin panels use page-based routing: click a link, the entire viewport changes. Context is lost. Blades solve this by **stacking panels horizontally**. When a user clicks an item in a list, a details blade slides in from the right while the list remains visible. This preserves context, enables comparison, and supports deep drill-down workflows without losing your place. + +``` ++----------------+-------------------+---------------------+ +| | | | +| Products | Product Details | Edit Variant | +| (workspace) | (child blade) | (grandchild blade) | +| | | | +| [list...] | Name: Widget | Color: Red | +| [list...] | SKU: WDG-001 | Size: Large | +| | | | ++----------------+-------------------+---------------------+ +``` + +| Aspect | Pages/Routes | Blades | +| --------- | -------------------- | -------------------------------- | +| Context | Lost on navigate | Parent remains visible | +| Data flow | Query params / store | `param`, `options`, `callParent` | +| Layout | Full viewport | Side-by-side panels | +| Depth | Flat (1 level) | Unlimited nesting | + +## When to Use + +| Scenario | Component | +| ------------------------------------------------- | -------------------------------------------- | +| Stacked panel with toolbar, header, and lifecycle | **VcBlade** | +| One-off confirmation or input dialog | [VcPopup](../../molecules/vc-popup/) | +| Full-page route without blade stack | Vue Router view | +| Scrollable content section inside a blade | [VcContainer](../../molecules/vc-container/) | + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcblade--default&viewMode=story" + loading="lazy" + title="navigation-vcblade--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcblade--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Use VcBlade for every screen in a vc-shell application -- it is the standard container that integrates with the navigation system, toolbar, breadcrumbs, and unsaved-changes guards. **Do not use** VcBlade for transient dialogs (use `VcPopup` / `usePopup()`) or for content areas that do not need their own header and close button. + +## Quick Start + +```vue +<template> + <VcBlade + title="My First Blade" + icon="lucide-box" + @close="$emit('close:blade')" + > + <div class="tw-p-4">Hello from a blade!</div> + </VcBlade> +</template> + +<script setup lang="ts"> +defineOptions({ name: "MyFirstBlade", url: "/my-first-blade" }); +</script> +``` + +!!! tip "Every blade needs a name" +Every blade must define a `name` in `defineOptions`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment. + +## Blade Anatomy + +A blade has four visual zones, rendered top-to-bottom: + +``` ++--------------------------------------+ +| [icon] Title / Subtitle [close] | <-- Header +|--------------------------------------| +| [Save] [Delete] [Refresh] [More >] | <-- Toolbar +|--------------------------------------| +| ** Status banners (stacked) ** | <-- Status Banners +|--------------------------------------| +| | +| Content (default slot) | <-- Content Area +| | ++--------------------------------------+ +``` + +**Header** -- Displays `icon`, `title`, `subtitle`, close button, and expand/collapse controls. The `#actions` slot injects custom elements next to the title. On mobile, the header is hidden when only one blade is in the stack. + +**Toolbar** -- Action buttons from the `toolbarItems` prop. Overflow items automatically collapse into a "More" dropdown (via `ResizeObserver`). + +**Status Banners** -- Unified, priority-sorted banner area. System banners: yellow when `modified` is `true`, red when the blade has an error (via `setError()`). Custom banners can be added programmatically via `useBlade().addBanner()` — see [useBlade docs](../../../core/composables/useBlade/useBlade.docs.md#banner-management). + +**Content Area** -- The `default` slot. Scrolls independently of header and toolbar. + +## Creating a Blade Component + +```vue +<template> + <VcBlade + :title="title" + icon="lucide-tag" + width="50%" + :expanded="expanded" + :closable="closable" + :toolbar-items="toolbar" + :modified="hasChanges" + :loading="isLoading" + @close="$emit('close:blade')" + @expand="$emit('expand:blade')" + @collapse="$emit('collapse:blade')" + > + <!-- Your content here --> + </VcBlade> +</template> + +<script setup lang="ts"> +import { computed, ref } from "vue"; +import { useBlade, type IBladeToolbar } from "@vc-shell/framework"; + +// Registration metadata +defineOptions({ + name: "OfferDetails", // Required: unique blade name + url: "/offer", // Optional: URL segment + routable: false, // Optional: exclude from direct URL access +}); + +// Standard props injected by the navigation system +export interface Props { + expanded: boolean; + closable: boolean; + param?: string; // Entity ID + options?: { sellerProduct?: object }; +} + +const props = withDefaults(defineProps<Props>(), { + expanded: true, + closable: true, +}); + +export interface Emits { + (event: "close:blade"): void; + (event: "expand:blade"): void; + (event: "collapse:blade"): void; +} +const emit = defineEmits<Emits>(); + +const { openBlade, closeSelf, callParent, onBeforeClose } = useBlade(); + +const title = computed(() => (props.param ? "Edit Offer" : "New Offer")); +const isLoading = ref(false); +const hasChanges = ref(false); + +const toolbar = ref<IBladeToolbar[]>([ + { + id: "save", + title: "Save", + icon: "lucide-save", + clickHandler: () => save(), + disabled: computed(() => !hasChanges.value), + }, +]); + +// Expose title for breadcrumbs +defineExpose({ title }); +</script> +``` + +### defineOptions Reference + +| Property | Type | Description | +| ------------- | --------- | ----------------------------------------------------------------------- | +| `name` | `string` | **Required.** Unique blade identifier for `openBlade({ name: "..." })`. | +| `url` | `string` | URL path segment (e.g., `"/offers"` produces `/#/.../offers`). | +| `isWorkspace` | `boolean` | Marks blade as a workspace (root-level, not closable). | +| `routable` | `boolean` | When `false`, blade cannot be opened via direct URL navigation. | +| `menuItem` | `object` | Registers a sidebar menu entry: `{ id, title, icon, priority }`. | + +### defineExpose + +Always expose a `title` computed. The navigation system reads it for breadcrumbs. You can also expose methods that children call via `callParent`: + +```ts +defineExpose({ + title, + reload: () => loadData(), +}); +``` + +## Opening Blades + +```ts +const { openBlade } = useBlade(); + +// Basic +openBlade({ name: "ProductDetails", param: "product-123" }); + +// With options (not encoded in URL) +openBlade({ + name: "ProductDetails", + param: "product-123", + options: { mode: "edit", category: selectedCategory.value }, +}); + +// With lifecycle hooks +openBlade({ + name: "ProductDetails", + param: item.id, + onOpen() { + selectedItemId.value = item.id; + }, + onClose() { + selectedItemId.value = undefined; + }, +}); + +// Open a workspace (replaces entire blade stack) +openBlade({ name: "SettingsWorkspace", isWorkspace: true }); +``` + +> **Tip:** `openBlade` works everywhere -- inside blades, dashboard cards, notification templates. Inside a blade it opens a child; outside it opens relative to the active blade. + +### Replacing the Current Blade + +After creating an entity, replace the "New" blade with the "Edit" blade: + +```ts +const { replaceWith } = useBlade(); + +async function save() { + const newId = await createProduct(data); + await replaceWith({ name: "ProductDetails", param: newId }); +} +``` + +## Passing Data Between Blades + +### param -- Entity Identifier + +A single string (typically an entity ID), encoded in the URL: + +```ts +openBlade({ name: "OrderDetails", param: order.id }); + +// In child blade +onMounted(async () => { + if (props.param) + await loadOrder(props.param); // Existing + else initNewOrder(); // New +}); +``` + +### options -- Rich Context Data + +Arbitrary data stored in `history.state` only (NOT in URL). Use for large objects: + +```ts +openBlade({ + name: "OfferDetails", + param: offer.id, + options: { sellerProduct: currentProduct.value, readOnly: true }, +}); +``` + +### query -- URL Query Parameters + +Bookmarkable key-value pairs: + +```ts +openBlade({ name: "ProductsList", query: { category: "electronics" } }); + +const { query } = useBlade(); +const category = computed(() => query.value?.category); +``` + +## Parent-Child Communication + +### Child Calls Parent + +`callParent` invokes methods the parent exposed via `defineExpose`: + +```ts +// Parent blade +defineExpose({ title: bladeTitle, reload: async () => loadProducts() }); + +// Child blade -- after saving +const { callParent } = useBlade(); +await callParent("reload"); + +// callParent returns the method's return value +const count = await callParent<number>("getItemCount"); +``` + +### Blade Context (for Widgets and Extensions) + +Share reactive data with widgets rendered inside the blade: + +```ts +import { defineBladeContext, injectBladeContext } from "@vc-shell/framework"; + +// In blade setup +defineBladeContext({ item: offer }); + +// In widget or nested component +const ctx = injectBladeContext(); +const entityId = computed(() => ctx.value.item?.id); +``` + +## Blade Lifecycle + +### Expanded / Collapsed + +`expanded` indicates whether this blade is the active (rightmost) one. The navigation system manages it -- just pass through: + +```vue +<VcBlade :expanded="expanded" @expand="$emit('expand:blade')" @collapse="$emit('collapse:blade')"> +``` + +### Closing + +```ts +const { closeSelf, closeChildren } = useBlade(); + +await closeSelf(); // Close this blade +await closeChildren(); // Close all children, keep this blade +``` + +### Preventing Close (Unsaved Changes Guard) + +Return `true` to **prevent** closing, `false` to **allow** it: + +```ts +const { onBeforeClose } = useBlade(); +const { showConfirmation } = usePopup(); + +onBeforeClose(async () => { + if (hasUnsavedChanges.value) { + const confirmed = await showConfirmation("Discard unsaved changes?"); + return !confirmed; // true = prevent close, false = allow + } + return false; +}); +``` + +> **Important:** The semantics are "should we prevent closing?" -- `true` keeps the blade open, `false` allows it to close. + +## Toolbar Integration + +```ts +const toolbar = ref<IBladeToolbar[]>([ + { + id: "save", + title: computed(() => t("TOOLBAR.SAVE")), + icon: "lucide-save", + clickHandler: () => save(), + disabled: computed(() => !modified.value), + }, + { + id: "delete", + title: "Delete", + icon: "lucide-trash-2", + clickHandler: () => confirmDelete(), + isVisible: computed(() => !!props.param), // Only for existing entities + }, +]); +``` + +### IBladeToolbar Interface + +```ts +interface IBladeToolbar { + id?: string; + title?: string | Ref<string> | ComputedRef<string>; + icon?: string | (() => string); + clickHandler?(): void; + disabled?: boolean | ComputedRef<boolean>; + isVisible?: boolean | Ref<boolean> | ComputedRef<boolean> | ((blade?: BladeDescriptor) => boolean); + separator?: "left" | "right" | "both"; +} +``` + +- `title`, `disabled`, and `isVisible` accept reactive values for dynamic toolbar behavior. +- Overflow items are moved to a "More" dropdown automatically. +- Use `separator` for visual dividers between toolbar groups. + +## Loading State and Skeleton + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcblade--loading&viewMode=story" + loading="lazy" + title="navigation-vcblade--loading" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcblade--loading" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +`loading` shows skeleton placeholders for header, toolbar, and content: + +```vue +<VcBlade title="Product Details" :loading="isLoading" :toolbar-items="toolbar"> + <ProductForm :data="product" /> +</VcBlade> +``` + +> **Tip:** Content is hidden (not unmounted) while loading, so `onMounted` hooks still fire. + +> **Note:** During `loading=true`, the header keeps its **close/expand controls operational** — only the icon, title, and subtitle are replaced with skeleton placeholders. Users can always close or maximize a loading blade. The `actions` slot, breadcrumbs, and modified-status dot are hidden until loading finishes. + +> **Note:** The toolbar zone uses an in-place skeleton: `BladeToolbar` itself renders skeleton buttons/widgets when its `loading` prop is true (no separate skeleton component is mounted). On mobile, the toolbar is omitted entirely while loading. + +Merge multiple loading sources with `useLoading`: + +```ts +import { useLoading } from "@vc-shell/framework"; + +const allLoading = useLoading(dataLoading, settingsLoading, languagesLoading); +``` + +## Unsaved Changes Indicator + +`modified` shows a yellow dot in the header and a status banner: + +```vue +<VcBlade title="Edit Product" :modified="hasChanges"> +``` + +Combine with `onBeforeClose` and `useBeforeUnload` for full protection: + +```ts +import { useBeforeUnload } from "@vc-shell/framework"; +useBeforeUnload(hasChanges); // Browser tab close warning +``` + +## Custom Banners + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcblade--custom-banners&viewMode=story" + loading="lazy" + title="navigation-vcblade--custom-banners" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcblade--custom-banners" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity. + +```vue +<script setup lang="ts"> +import { useBlade } from "@vc-shell/framework"; + +const { addBanner, removeBanner, clearBanners } = useBlade(); + +// Info banner (e.g. read-only mode) +addBanner({ variant: "info", message: "This record is read-only" }); + +// Dismissible warning with action +addBanner({ + variant: "warning", + message: "License expires in 7 days", + dismissible: true, + action: { label: "Renew", handler: () => openRenewal() }, +}); +</script> +``` + +Four variants are available: `danger`, `warning`, `info`, `success`. System banners (error and unsaved changes) are always present and cannot be removed by `clearBanners()`. For the full API reference, see [useBlade — Banner Management](../../../core/composables/useBlade/useBlade.docs.md#banner-management). + +## Blade Width Control + +```vue +<VcBlade :width="350"> <!-- Pixels (number) --> +<VcBlade width="50%"> <!-- CSS value (string) --> +<VcBlade> <!-- Default: "30%" --> +``` + +On mobile, width is forced to `100%`. When `expanded` is `true`, the blade fills all available space. + +## Recipes + +### Master-Detail (List + Details) + +The most common vc-shell pattern. Key points from real-world usage (see `offers-list.vue` and `offers-details.vue`): + +**List blade** -- Opens a details blade on row click, tracks selected item: + +```ts +defineOptions({ name: "Offers", url: "/offers", isWorkspace: true }); + +const { openBlade } = useBlade(); +const selectedItemId = ref<string>(); + +const onItemClick = (event: { data: Offer }) => { + openBlade({ + name: "Offer", + param: event.data.id, + onOpen() { + selectedItemId.value = event.data.id; + }, + onClose() { + selectedItemId.value = undefined; + }, + }); +}; + +// Expose reload for child to call after save +defineExpose({ title: bladeTitle, reload }); +``` + +**Details blade** -- Loads entity, saves, notifies parent, replaces self on create: + +```ts +defineOptions({ name: "Offer", url: "/offer", routable: false }); + +const { callParent, replaceWith, onBeforeClose } = useBlade(); + +async function save() { + if (props.param) { + await updateOffer(offer.value); + } else { + await createOffer(offer.value); + await replaceWith({ name: "Offer", param: offer.value.id }); + } + await callParent("reload"); +} + +onBeforeClose(async () => { + if (modified.value) return !(await showConfirmation("Discard?")); + return false; +}); + +defineBladeContext({ item: offer }); +useBeforeUnload(modified); +defineExpose({ title }); +``` + +### Blade with Form Validation + +Using `vee-validate` with `Field` components: + +```vue +<VcBlade title="Create Offer" :toolbar-items="toolbar" :modified="modified"> + <VcContainer :no-padding="true"> + <VcForm class="tw-p-4 tw-space-y-4"> + <Field v-slot="{ errorMessage, handleChange, errors }" + :model-value="offer.name" name="name" rules="required"> + <VcInput v-model="offer.name" label="Name" required + :error="!!errors.length" :error-message="errorMessage" + @update:model-value="handleChange" /> + </Field> + </VcForm> + </VcContainer> +</VcBlade> +``` + +```ts +const { meta } = useForm({ validateOnMount: false }); + +const toolbar = ref([ + { + id: "save", + title: "Save", + icon: "lucide-save", + clickHandler: () => (meta.value.valid ? save() : showError("Fix validation errors.")), + disabled: computed(() => !meta.value.valid || !modified.value), + }, +]); +``` + +### Blade with Data Table + +```vue +<VcBlade :title="$t('ORDERS.LIST.TITLE')" icon="lucide-file-text" width="50%" :expanded="expanded" :closable="closable" :toolbar-items="toolbar"> + <VcDataTable + v-model:sort-field="sortField" v-model:sort-order="sortOrder" + v-model:search-value="searchValue" v-model:active-item-id="selectedItemId" + :items="orders" :loading="loading" :searchable="true" + :pagination="{ currentPage, pages }" :total-count="totalCount" + state-key="orders_list" @row-click="onItemClick"> + <VcColumn id="number" title="Order #" :sortable="true" :always-visible="true" /> + <VcColumn id="customerName" title="Customer" :sortable="true" /> + <VcColumn id="createdDate" title="Date" type="date-ago" :sortable="true" /> + <VcColumn id="status" title="Status" type="status-icon" :always-visible="true" /> + </VcDataTable> +</VcBlade> +``` + +## Common Mistakes + +### Missing blade name + +```ts +// WRONG -- openBlade({ name: "ProductDetails" }) will fail +defineOptions({}); + +// CORRECT +defineOptions({ name: "ProductDetails", url: "/product" }); +``` + +### Forgetting to expose the title + +```ts +// WRONG -- Breadcrumbs show nothing +const title = computed(() => product.value?.name); + +// CORRECT +defineExpose({ title }); +``` + +### Wrong onBeforeClose return value + +```ts +// WRONG -- true from showConfirmation PREVENTS close +onBeforeClose(async () => await showConfirmation("Discard?")); + +// CORRECT -- negate confirmation result +onBeforeClose(async () => !(await showConfirmation("Discard?"))); +``` + +### Using blade-specific methods outside a blade + +```ts +// WRONG -- closeSelf() throws outside blade context +const { closeSelf } = useBlade(); +closeSelf(); + +// CORRECT -- only openBlade works everywhere +const { openBlade } = useBlade(); +openBlade({ name: "ProductsList" }); +``` + +### Not passing expanded/closable through + +```vue +<!-- WRONG -- hardcoded, ignores navigation system --> +<VcBlade :expanded="true" :closable="true"> + +<!-- CORRECT -- pass props from navigation --> +<VcBlade :expanded="expanded" :closable="closable"> +``` + +## Props + +| Prop | Type | Default | Description | +| -------------- | ------------------ | ----------- | ------------------------------------------------------------ | +| `title` | `string` | `undefined` | Title text in the blade header. | +| `subtitle` | `string` | `undefined` | Secondary text below the title. | +| `icon` | `string` | `undefined` | Icon name (e.g., `"lucide-box"`) displayed before the title. | +| `width` | `number \| string` | `"30%"` | Blade width. Numbers are pixels; strings are CSS values. | +| `expanded` | `boolean` | `false` | Whether the blade fills all available width. | +| `closable` | `boolean` | `true` | Whether the close button is shown. | +| `toolbarItems` | `IBladeToolbar[]` | `[]` | Action buttons in the toolbar zone. | +| `modified` | `boolean` | `undefined` | Shows unsaved changes indicator and banner. | +| `loading` | `boolean` | `false` | Shows skeleton placeholders for all blade zones. | + +## Events + +| Event | Payload | Description | +| ---------- | ------- | ----------------------------------------------- | +| `close` | -- | Close button clicked. Re-emit as `close:blade`. | +| `expand` | -- | Blade expanded. Re-emit as `expand:blade`. | +| `collapse` | -- | Blade collapsed. Re-emit as `collapse:blade`. | + +## Slots + +| Slot | Description | +| --------- | -------------------------------------------------- | +| `default` | Main scrollable content area. | +| `actions` | Custom elements in the header, right of the title. | + +## CSS Custom Properties + +```css +:root { + --blade-background-color: var(--additional-50); + --blade-border-color: var(--neutrals-200); + --blade-shadow-color: var(--primary-700); + --blade-shadow: 2px 2px 8px rgb(from var(--blade-shadow-color) r g b / 14%); + --blade-color-error: var(--danger-500); + --blade-color-unsaved-changes: var(--secondary-600); + --blade-text-color: var(--additional-50); +} +``` + +## Accessibility + +- `role="region"` with `aria-labelledby` pointing to the title element. +- `aria-label` fallback when title is unavailable (during loading). +- Close button is keyboard-accessible. +- Unique `blade-title-{uid}` ID for ARIA labeling. + +## Mobile Behavior + +- Width forced to `100%` regardless of prop value. +- Header hidden when only one blade is in the stack. +- Toolbar rendered as a floating pill at the bottom. +- Back button replaces close button for stack navigation. + +## Related + +| Resource | Description | +| ----------------------------------------------- | ---------------------------------------------------------------------------------- | +| `useBlade()` | Unified composable: identity, navigation, communication, guards, error management. | +| `defineBladeContext()` / `injectBladeContext()` | Provide/inject reactive data for widgets and extensions. | +| `VcBladeNavigation` | Manages blade stack and horizontal scroll (part of `vc-app.vue`). | +| `IBladeToolbar` | TypeScript interface for toolbar button definitions. | +| `useBeforeUnload()` | Browser tab close warning for unsaved changes. | +| `useLoading()` | Merges multiple loading refs into a single boolean. | +| `usePopup()` | Confirmation dialogs and error messages. | +| `useBladeWidgets()` | Register contextual widgets for the blade widget area. | + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-card.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-card.md new file mode 100644 index 0000000000..e13d3ffb38 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-card.md @@ -0,0 +1,431 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-card/vc-card.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcCard + +A bordered container with an optional header, icon, action buttons, and collapsible body. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vccard--default&viewMode=story" + loading="lazy" + title="data-display-vccard--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vccard--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +| Scenario | Component | +| --------------------------------------------- | ---------------------------------------------------------------------------- | +| Grouping form fields or content with a header | **VcCard** | +| Scrollable content wrapper without a header | [VcContainer](./vc-container.md) | +| Collapsible section with rich toggle behavior | [VcAccordion](../data-display/vc-accordion.md) (for multiple exclusive panels) | +| Alert or notification banner | [VcBanner](../feedback/vc-banner.md) | + +Use VcCard to visually separate content sections on a blade -- especially when you need a titled header, action buttons, or collapsible body. **Do not use** VcCard for dismissible alerts or status messages (use `VcBanner`), and avoid nesting VcCard when a simple `VcContainer` with padding would suffice. + +## Quick Start + +```vue +<template> + <VcCard header="Product Details"> + <div class="tw-p-4"> + <p>Card body content goes here.</p> + </div> + </VcCard> +</template> + +<script setup lang="ts"> +import { VcCard } from "@vc-shell/framework"; +</script> +``` + +## Header with Icon + +Add an icon to the left of the header title for visual context: + +```vue +<VcCard header="Shipping Information" icon="lucide-truck"> + <div class="tw-p-4"> + <!-- shipping form fields --> + </div> +</VcCard> +``` + +The icon renders at `xl` size using the `VcIcon` component. It inherits the header's text color, which changes based on the variant. + +## Variants + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vccard--all-variants&viewMode=story" + loading="lazy" + title="data-display-vccard--all-variants" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vccard--all-variants" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Three variants control the header's background and text color to communicate semantic meaning. + +```vue +<VcCard header="Order Details" variant="default"> + <div class="tw-p-4">Standard content section</div> +</VcCard> + +<VcCard header="Payment Confirmed" variant="success"> + <div class="tw-p-4">Order has been paid successfully</div> +</VcCard> + +<VcCard header="Validation Errors" variant="danger"> + <div class="tw-p-4"> + <ul class="tw-list-disc tw-pl-4"> + <li>SKU is required</li> + <li>Price must be positive</li> + </ul> + </div> +</VcCard> +``` + +| Variant | Header Background | Header Text | Use Case | +| --------- | ---------------------------------- | ----------------------------- | ------------------------------------- | +| `default` | `var(--secondary-50)` (light gray) | `var(--secondary-950)` (dark) | Standard content grouping | +| `success` | `var(--success-100)` (light green) | `var(--success-600)` (green) | Positive state confirmation | +| `danger` | `var(--danger-100)` (light red) | `var(--danger-600)` (red) | Errors, warnings, destructive content | + +## Collapsible Sections + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vccard--collapsable&viewMode=story" + loading="lazy" + title="data-display-vccard--collapsable" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vccard--collapsable" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Enable collapse/expand behavior by setting `is-collapsable`. The card header becomes clickable and shows a chevron indicator. + +```vue +<VcCard header="Advanced Settings" is-collapsable> + <div class="tw-p-4"> + <!-- advanced form fields, hidden by default until expanded --> + </div> +</VcCard> +``` + +### Initially collapsed + +Start in the collapsed state by adding `is-collapsed`: + +```vue +<VcCard header="Additional Options" is-collapsable is-collapsed> + <div class="tw-p-4"> + <!-- content hidden on initial render --> + </div> +</VcCard> +``` + +### Controlled collapse state + +Listen to the `state:collapsed` event to sync the collapse state with external logic: + +```vue +<script setup lang="ts"> +import { ref } from "vue"; + +const isAdvancedHidden = ref(true); +</script> + +<template> + <VcCard + header="Advanced Settings" + is-collapsable + :is-collapsed="isAdvancedHidden" + @state:collapsed="isAdvancedHidden = $event" + > + <div class="tw-p-4"> + <!-- advanced fields --> + </div> + </VcCard> +</template> +``` + +The collapse animation uses CSS `grid-template-rows` transitions (200ms ease-out) for smooth height animation without JavaScript measurement. + +## Header Actions + +Use the `#actions` slot to place buttons or controls on the right side of the header: + +```vue +<VcCard header="Order Items"> + <template #actions> + <VcButton variant="primary" size="sm" icon="lucide-plus" @click="addItem"> + Add Item + </VcButton> + </template> + <div class="tw-p-4"> + <!-- order items table --> + </div> +</VcCard> +``` + +Multiple actions are supported: + +```vue +<VcCard header="Product Images"> + <template #actions> + <VcButton variant="ghost" size="icon-sm" icon="lucide-upload" aria-label="Upload" @click="upload" /> + <VcButton variant="ghost" size="icon-sm" icon="lucide-trash-2" aria-label="Remove all" @click="clearAll" /> + </template> + <div class="tw-p-4"> + <!-- image gallery --> + </div> +</VcCard> +``` + +## Custom Header + +Replace the entire header content using the `#header` slot. This overrides the default title + icon rendering: + +```vue +<VcCard> + <template #header> + <div class="tw-flex tw-items-center tw-gap-2"> + <VcIcon icon="lucide-package" size="m" /> + <span class="tw-font-bold">Custom Header</span> + <VcBadge variant="success">Active</VcBadge> + </div> + </template> + <div class="tw-p-4"> + <!-- card body --> + </div> +</VcCard> +``` + +!!! note "Header required for header section" +The `header` prop must be set (even to an empty string) for the header section to render. If neither `header` prop nor `#header` slot is provided, no header is displayed. + +## Fill Mode + +When `fill` is `true`, the card body applies `display: flex` to allow child content to fill the available vertical space. Useful when the card is inside a flex container and the body content (like a table) should stretch: + +```vue +<VcCard header="Product List" fill> + <!-- Table fills the remaining card height --> + <VcDataTable :items="products" :columns="columns" /> +</VcCard> +``` + +## Recipes + +### Form Section Layout + +```vue +<template> + <div class="tw-flex tw-flex-col tw-gap-4"> + <VcCard + header="Basic Information" + icon="lucide-file-text" + > + <div class="tw-p-4 tw-grid tw-grid-cols-2 tw-gap-4"> + <VcInput + v-model="form.name" + label="Product Name" + required + /> + <VcInput + v-model="form.sku" + label="SKU" + required + /> + <VcInput + v-model="form.price" + label="Price" + type="number" + /> + <VcSelect + v-model="form.category" + label="Category" + :options="categories" + /> + </div> + </VcCard> + + <VcCard + header="SEO Settings" + icon="lucide-search" + is-collapsable + is-collapsed + > + <div class="tw-p-4 tw-grid tw-grid-cols-2 tw-gap-4"> + <VcInput + v-model="form.metaTitle" + label="Meta Title" + /> + <VcInput + v-model="form.metaDescription" + label="Meta Description" + /> + <VcInput + v-model="form.slug" + label="URL Slug" + /> + </div> + </VcCard> + + <VcCard + header="Inventory" + icon="lucide-warehouse" + is-collapsable + > + <div class="tw-p-4"> + <!-- inventory fields --> + </div> + </VcCard> + </div> +</template> +``` + +### Conditional Variant Based on Data State + +```vue +<template> + <VcCard + :header="validationHeader" + :variant="errors.length > 0 ? 'danger' : 'success'" + :icon="errors.length > 0 ? 'lucide-alert-triangle' : 'lucide-check-circle'" + > + <div class="tw-p-4"> + <ul + v-if="errors.length > 0" + class="tw-list-disc tw-pl-4 tw-space-y-1" + > + <li + v-for="error in errors" + :key="error" + > + {{ error }} + </li> + </ul> + <p v-else>All validations passed.</p> + </div> + </VcCard> +</template> + +<script setup lang="ts"> +import { computed } from "vue"; + +const errors = ref<string[]>([]); +const validationHeader = computed(() => (errors.value.length > 0 ? `${errors.value.length} Validation Error(s)` : "Validation Passed")); +</script> +``` + +## Common Mistakes + +### Forgetting padding on card body + +```vue +<!-- Wrong -- content touches the card border with no spacing --> +<VcCard header="Details"> + <p>This text has no padding.</p> +</VcCard> + +<!-- Correct -- add padding to the body content --> +<VcCard header="Details"> + <div class="tw-p-4"> + <p>This text has proper spacing.</p> + </div> +</VcCard> +``` + +### Using VcCard for alert messages + +```vue +<!-- Wrong -- VcCard is for content grouping, not alerts --> +<VcCard header="Error" variant="danger"> + <div class="tw-p-4">Something went wrong.</div> +</VcCard> + +<!-- Correct -- use VcBanner for dismissible alert messages --> +<VcBanner variant="danger">Something went wrong.</VcBanner> +``` + +### Expecting collapse without is-collapsable + +```vue +<!-- Wrong -- is-collapsed has no effect without is-collapsable --> +<VcCard header="Settings" is-collapsed> + <div class="tw-p-4">This is always visible.</div> +</VcCard> + +<!-- Correct -- both props are needed --> +<VcCard header="Settings" is-collapsable is-collapsed> + <div class="tw-p-4">This starts collapsed.</div> +</VcCard> +``` + +## Props + +| Prop | Type | Default | Description | +| --------------- | ------------------------------------ | ----------- | --------------------------------------------------------- | +| `header` | `string` | -- | Title text displayed in the card header | +| `icon` | `string` | -- | Icon identifier shown before the title | +| `variant` | `"default" \| "success" \| "danger"` | `"default"` | Header color variant | +| `isCollapsable` | `boolean` | `false` | Enables collapse/expand on header click | +| `isCollapsed` | `boolean` | `false` | Controls the collapsed state (requires `isCollapsable`) | +| `fill` | `boolean` | `false` | Makes body content fill available vertical space via flex | + +## Events + +| Event | Payload | Description | +| ----------------- | --------- | ---------------------------------------------------------------------------- | +| `header:click` | -- | Emitted when the header is clicked (always, regardless of collapsable state) | +| `state:collapsed` | `boolean` | Emitted when the collapsed state changes (`true` = collapsed) | + +## Slots + +| Slot | Description | +| --------- | --------------------------------------------------------- | +| `default` | Card body content | +| `header` | Custom header content (replaces the default title + icon) | +| `actions` | Action buttons rendered on the right side of the header | + +## CSS Custom Properties + +| Variable | Default | Description | +| ---------------------------------- | ---------------------------- | ---------------------------------- | +| `--card-background` | `var(--additional-50)` | Card body background | +| `--card-border-color` | `var(--neutrals-200)` | Border color | +| `--card-border-radius` | `6px` | Corner radius | +| `--card-header-background` | `var(--secondary-50)` | Default header background | +| `--card-header-color` | `var(--secondary-950)` | Default header text color | +| `--card-header-background-success` | `var(--success-100)` | Success variant header background | +| `--card-header-background-danger` | `var(--danger-100)` | Danger variant header background | +| `--card-header-color-success` | `var(--success-600)` | Success variant header text | +| `--card-header-color-danger` | `var(--danger-600)` | Danger variant header text | +| `--card-header-padding-hor` | `24px` | Header horizontal padding | +| `--card-header-padding-vert` | `17px` | Header vertical padding | +| `--card-hover-shadow` | `0 2px 8px rgba(0,0,0,0.06)` | Hover shadow | +| `--card-focus-ring-color` | `var(--primary-300)` | Focus ring for collapsable headers | + +## Accessibility + +- Collapsable headers render with `role="button"` and `tabindex="0"` for keyboard access +- `aria-expanded` reflects the current collapsed/expanded state +- `aria-controls` links the header to the body panel via a unique auto-generated ID +- Supports Enter and Space key activation for toggling collapse +- Focus ring appears on `:focus-visible` for keyboard navigation (inset ring, 2px) +- Non-collapsable headers have no role or tabindex (not interactive) + +## Related Components + +- [VcContainer](./vc-container.md) -- scrollable content wrapper without header or collapsing +- [VcBanner](../feedback/vc-banner.md) -- for alert/notification messages rather than content grouping +- [VcCol](./vc-col.md) / [VcRow](./vc-row.md) -- for grid-based layout within card bodies + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, VcCard shows a skeleton header (if the `header` prop is set) while its body content renders normally — child components self-skeletonize via their own `BladeLoadingKey` injection. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-col.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-col.md new file mode 100644 index 0000000000..1ea2f15621 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-col.md @@ -0,0 +1,170 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-col/vc-col.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcCol + +A flexbox column layout primitive that stacks its children vertically. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vccol--default&viewMode=story" + loading="lazy" + title="layout-vccol--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vccol--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Create vertical stacking layouts within a row-based grid +- Control proportional column widths using the `size` prop +- Stack form fields, images, or content blocks vertically +- When NOT to use: for horizontal layouts, use [VcRow](./vc-row.md); for scrollable content areas, use [VcContainer](./vc-container.md) + +## Basic Usage + +```vue +<VcRow> + <VcCol :size="1">Sidebar</VcCol> + <VcCol :size="3">Main content</VcCol> +</VcRow> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------ | -------- | ------- | ----------------------------------------------------------------------------------- | +| `size` | `number` | `1` | Flex-grow value controlling how much space the column occupies relative to siblings | + +## CSS Variables + +| Variable | Default | Description | +| ----------- | ------- | ----------------------------------- | +| `--col-gap` | `0` | Vertical gap between child elements | + +## Common Patterns + +### Proportional Two-Column Layout + +```vue +<VcRow class="tw-gap-4"> + <VcCol :size="1"> + <VcImage :src="product.imageUrl" size="xl" /> + </VcCol> + <VcCol :size="2"> + <h3>{{ product.name }}</h3> + <p>{{ product.description }}</p> + </VcCol> +</VcRow> +``` + +### Three-Column Grid with Equal Widths + +```vue +<VcRow class="tw-gap-4"> + <VcCol v-for="item in items" :key="item.id"> + <VcCard :header="item.title"> + <div class="tw-p-4">{{ item.summary }}</div> + </VcCard> + </VcCol> +</VcRow> +``` + +### Stacked Form Fields with Gap + +```vue +<VcCol class="tw-gap-4"> + <VcInput label="First Name" v-model="form.firstName" /> + <VcInput label="Last Name" v-model="form.lastName" /> + <VcInput label="Email" v-model="form.email" /> +</VcCol> +``` + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vccol--content-layout&viewMode=story" + loading="lazy" + title="layout-vccol--content-layout" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vccol--content-layout" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Blade Detail Form with Sidebar + +A common blade layout places metadata in a narrow sidebar column and form fields in the wider main column: + +```vue +<template> + <VcRow class="tw-gap-6"> + <VcCol + :size="3" + class="tw-gap-4" + > + <VcInput + label="Name" + v-model="form.name" + required + /> + <VcTextarea + label="Description" + v-model="form.description" + /> + <VcSelect + label="Category" + v-model="form.category" + :options="categories" + /> + </VcCol> + <VcCol + :size="1" + class="tw-gap-4" + > + <VcStatusIcon :status="form.isPublished" /> + <VcHint>Created: {{ form.createdDate }}</VcHint> + <VcHint>Modified: {{ form.modifiedDate }}</VcHint> + </VcCol> + </VcRow> +</template> +``` + +## Recipe: Nested Columns + +VcCol can be nested inside another VcCol for complex sub-layouts: + +```vue +<VcRow class="tw-gap-4"> + <VcCol :size="1"> + <VcRow class="tw-gap-2"> + <VcCol :size="1"> + <VcInput label="Width" v-model="dimensions.width" type="number" /> + </VcCol> + <VcCol :size="1"> + <VcInput label="Height" v-model="dimensions.height" type="number" /> + </VcCol> + </VcRow> + </VcCol> + <VcCol :size="1"> + <VcInput label="Weight" v-model="dimensions.weight" type="number" /> + </VcCol> +</VcRow> +``` + +## Tips + +- The `size` prop sets `flex-grow` on the element. Two columns with `size="1"` share space equally; `size="1"` next to `size="3"` gives a 25/75 split. +- VcCol uses `flex-basis: 0` and `min-width: 0`, which means columns shrink to fit even if their content is wider. This prevents overflow in tight layouts. +- For vertical spacing between child elements, use the Tailwind `tw-gap-*` utility on the VcCol directly (e.g., `class="tw-gap-4"`), which is more ergonomic than the `--col-gap` CSS variable. +- VcCol can be used standalone (without VcRow) as a simple vertical stack container. + +## Accessibility + +- Renders as a `<div>` with no semantic role; add appropriate ARIA attributes to content as needed +- Uses `min-width: 0` to allow content to shrink properly in flex layouts + +## Related Components + +- [VcRow](./vc-row.md) -- horizontal flex container; the natural parent for VcCol +- [VcContainer](./vc-container.md) -- scrollable wrapper for overflow content +- [VcCard](./vc-card.md) -- bordered section container often used inside columns diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-container.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-container.md new file mode 100644 index 0000000000..7d825c26dd --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-container.md @@ -0,0 +1,141 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-container/vc-container.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcContainer + +A scrollable content wrapper that fills its parent, provides configurable padding, and optionally shows an inset shadow to indicate overflow. The standard building block for blade body content. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vccontainer--default&viewMode=story" + loading="lazy" + title="layout-vccontainer--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vccontainer--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Wrap blade body content that may exceed the visible area +- Create scrollable panels within fixed-height layouts +- Indicate scrollable content with a subtle shadow cue +- When NOT to use: for grouped/titled sections, use [VcCard](./vc-card.md); for simple column stacking, use [VcCol](./vc-col.md) + +## Basic Usage + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vccontainer--with-shadow&viewMode=story" + loading="lazy" + title="layout-vccontainer--with-shadow" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vccontainer--with-shadow" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +```vue +<VcContainer shadow> + <p>Scrollable content goes here...</p> +</VcContainer> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ----------- | --------- | ------- | ------------------------------------------------------------------------ | +| `shadow` | `boolean` | `false` | Shows an inset shadow when content overflows | +| `noPadding` | `boolean` | `false` | Removes the default 16px inner padding | +| `ariaLabel` | `string` | — | When provided, renders as `<section>` with this label instead of `<div>` | + +## CSS Variables + +| Variable | Default | Description | +| --------------------------- | ------------- | ------------------------------------ | +| `--container-padding` | `16px` | Inner padding of the scrollable area | +| `--container-bg` | `transparent` | Background color | +| `--container-border-radius` | `0` | Border radius | +| `--container-gap` | `0` | Gap between child elements | + +## Exposed Methods + +| Method | Description | +| ------------- | ------------------------------------------------ | +| `scrollTop()` | Programmatically scroll the container to the top | +| `component` | Ref to the inner scrollable DOM element | + +## Events + +| Event | Payload | Description | +| -------- | ------- | ----------------------------- | +| `scroll` | `Event` | Emitted on every scroll event | + +## Common Patterns + +### Blade Body with Scroll Shadow + +```vue +<template> + <VcBlade title="Product Details"> + <VcContainer shadow> + <!-- form fields, cards, etc. --> + </VcContainer> + </VcBlade> +</template> +``` + +### Edge-to-Edge Content (No Padding) + +```vue +<VcContainer no-padding> + <div class="tw-bg-neutrals-100 tw-p-4"> + Full-width section with custom background + </div> + <div class="tw-p-4"> + Content with its own padding + </div> +</VcContainer> +``` + +### Programmatic Scroll to Top + +```vue +<script setup lang="ts"> +import { ref } from "vue"; + +const containerRef = ref(); + +function scrollToTop() { + containerRef.value?.scrollTop(); +} +</script> + +<template> + <VcContainer + ref="containerRef" + shadow + > + <!-- long content --> + </VcContainer> + <VcButton @click="scrollToTop">Back to Top</VcButton> +</template> +``` + +### Semantic Section Landmark + +```vue +<VcContainer aria-label="Order history" shadow> + <!-- renders as <section aria-label="Order history"> --> +</VcContainer> +``` + +## Accessibility + +- When `ariaLabel` is provided, renders as a `<section>` landmark for screen readers +- Without `ariaLabel`, renders as a neutral `<div>` +- Scroll shadow provides a visual-only overflow cue; screen readers access all content normally + +## Related Components + +- [VcCard](./vc-card.md) — bordered container with header and collapsing +- [VcCol](./vc-col.md) — column layout primitive for flex grids diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-row.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-row.md new file mode 100644 index 0000000000..11b917c499 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-row.md @@ -0,0 +1,181 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-row/vc-row.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcRow + +A simple layout primitive that arranges child elements in a horizontal flexbox row + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcrow--default&viewMode=story" + loading="lazy" + title="layout-vcrow--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcrow--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Lay out sibling elements (images, cards, form fields) side by side +- Build responsive rows that stack on mobile automatically +- Pair with [VcCol](./vc-col.md) for proportional multi-column layouts +- When NOT to use: complex grid layouts with explicit column sizing (use CSS grid or Tailwind utilities directly); single-column stacking (use VcCol alone) + +## Basic Usage + +```vue +<template> + <VcRow> + <VcImage + src="/img/a.jpg" + size="xl" + /> + <VcImage + src="/img/b.jpg" + size="xl" + /> + <VcImage + src="/img/c.jpg" + size="xl" + /> + </VcRow> +</template> + +<script setup lang="ts"> +import { VcRow, VcImage } from "@vc-shell/framework"; +</script> +``` + +## Key Props + +VcRow has no props. It accepts any children via its default slot. + +## Common Patterns + +### Row with Custom Gap + +The `--row-gap` CSS variable (default `0`) controls spacing. You can also override with Tailwind utility classes. + +```vue +<template> + <VcRow class="tw-gap-4"> + <div + v-for="i in 4" + :key="i" + class="tw-p-4 tw-bg-gray-100 tw-rounded" + > + Item {{ i }} + </div> + </VcRow> +</template> +``` + +### Cards in a Row + +```vue +<template> + <VcRow class="tw-gap-4"> + <div + v-for="card in cards" + :key="card.id" + class="tw-w-64 tw-p-4 tw-border tw-rounded tw-shadow-sm" + > + <h3 class="tw-font-medium">{{ card.title }}</h3> + <p class="tw-text-sm tw-text-gray-600">{{ card.description }}</p> + </div> + </VcRow> +</template> +``` + +### Proportional Columns with VcCol + +```vue +<template> + <VcRow class="tw-gap-6"> + <VcCol :size="1"> + <VcImage + :src="product.imageUrl" + size="xl" + /> + </VcCol> + <VcCol :size="2"> + <VcInput + label="Product Name" + v-model="product.name" + /> + <VcInput + label="SKU" + v-model="product.sku" + /> + </VcCol> + </VcRow> +</template> +``` + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcrow--with-cards&viewMode=story" + loading="lazy" + title="layout-vcrow--with-cards" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcrow--with-cards" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Form Section with Label and Fields + +Use VcRow to place a section label next to a group of fields in a blade detail view: + +```vue +<template> + <VcRow class="tw-gap-4 tw-py-4 tw-border-b"> + <VcCol :size="1"> + <span class="tw-font-medium tw-text-sm tw-text-gray-700">Pricing</span> + </VcCol> + <VcCol + :size="3" + class="tw-gap-3" + > + <VcInput + label="List Price" + v-model="form.listPrice" + type="number" + /> + <VcInput + label="Sale Price" + v-model="form.salePrice" + type="number" + /> + <VcSelect + label="Currency" + v-model="form.currency" + :options="currencies" + /> + </VcCol> + </VcRow> +</template> +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ----------- | ------- | -------------------------- | +| `--row-gap` | `0` | Gap between child elements | + +## Tips + +- On mobile (when a `.vc-app--mobile` ancestor is present), VcRow switches from `display: flex` to `display: grid`, causing children to stack vertically. This happens automatically via the framework's responsive class. +- VcRow uses `flex-wrap: nowrap` and `align-items: stretch` by default. If you need wrapping, add `class="tw-flex-wrap"`. +- For spacing, prefer the Tailwind `tw-gap-*` utility over `--row-gap` since it is more intuitive and co-locates with other layout classes. +- VcRow is purely presentational — it renders a plain `<div>` with no ARIA attributes. Add roles or labels on the content elements as needed. + +## Accessibility + +- No special ARIA attributes; VcRow is a purely presentational layout container +- On mobile (`.vc-app--mobile` ancestor), switches from `flex` to `grid` for stacked layout + +## Related Components + +- [VcCol](./vc-col.md) -- vertical flex column, the natural child for proportional layouts +- [VcContainer](./vc-container.md) -- higher-level layout container for blade content sections diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-scrollable-container.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-scrollable-container.md new file mode 100644 index 0000000000..9d496957ed --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-scrollable-container.md @@ -0,0 +1,160 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcScrollableContainer + +A container component that wraps overflowing content with auto-hiding scroll arrows at the top and bottom edges. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcscrollablecontainer--default&viewMode=story" + loading="lazy" + title="layout-vcscrollablecontainer--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcscrollablecontainer--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Constrained-height menus, sidebars, or dropdown panels where a native scrollbar is undesirable +- Lists inside blades or popups that need subtle scroll affordance +- Settings panels or filter lists with many items +- When NOT to use: full-page scroll areas where a native scrollbar is expected; horizontally scrolling content (this component only handles vertical overflow) + +## Basic Usage + +```vue +<template> + <VcScrollableContainer style="height: 200px;"> + <div + v-for="i in 30" + :key="i" + class="tw-px-3 tw-py-2" + > + Item {{ i }} + </div> + </VcScrollableContainer> +</template> + +<script setup lang="ts"> +import { VcScrollableContainer } from "@vc-shell/framework"; +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------- | -------- | ------- | ---------------------------------------------------------------- | +| `speed` | `number` | `2` | Scroll speed in px/frame. Captured once at mount (not reactive). | + +## Slots + +| Slot | Description | +| ------------ | ------------------------------------------------------ | +| `default` | Content rendered inside the scrollable viewport | +| `arrow-up` | Custom up-arrow indicator (replaces default chevron) | +| `arrow-down` | Custom down-arrow indicator (replaces default chevron) | + +## Exposed + +| Property | Type | Description | +| ------------------- | -------------------------- | -------------------------------------------- | +| `viewportRef` | `Ref<HTMLElement \| null>` | Direct reference to the viewport DOM element | +| `updateScrollState` | `() => void` | Manually recalculate arrow visibility | + +<div class="vc-storybook-embed" style="--height: 350px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcscrollablecontainer--custom-speed&viewMode=story" + loading="lazy" + title="layout-vcscrollablecontainer--custom-speed" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcscrollablecontainer--custom-speed" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Sidebar Filter List in a Blade + +```vue +<template> + <div class="tw-w-64 tw-border-r tw-border-gray-200"> + <h3 class="tw-px-3 tw-py-2 tw-font-semibold tw-text-sm">Filters</h3> + <VcScrollableContainer + style="max-height: 320px;" + :speed="3" + > + <label + v-for="filter in filters" + :key="filter.id" + class="tw-flex tw-items-center tw-gap-2 tw-px-3 tw-py-1.5 hover:tw-bg-gray-50 tw-cursor-pointer" + > + <input + type="checkbox" + v-model="filter.active" + /> + <span class="tw-text-sm">{{ filter.label }}</span> + </label> + </VcScrollableContainer> + </div> +</template> +``` + +## Recipe: Programmatic Scroll Reset + +Use the exposed `viewportRef` to scroll back to the top when content changes: + +```vue +<script setup lang="ts"> +import { ref, watch } from "vue"; + +const scrollContainer = ref<InstanceType<typeof VcScrollableContainer>>(); +const activeCategory = ref("all"); + +watch(activeCategory, () => { + scrollContainer.value?.viewportRef?.scrollTo({ top: 0, behavior: "smooth" }); +}); +</script> + +<template> + <VcScrollableContainer + ref="scrollContainer" + style="height: 300px;" + > + <ItemList :category="activeCategory" /> + </VcScrollableContainer> +</template> +``` + +## Recipe: Custom Arrow Icons + +Replace the default chevrons with custom indicators: + +```vue +<VcScrollableContainer style="height: 200px;"> + <template #arrow-up> + <span class="tw-text-xs tw-text-gray-400">Scroll up</span> + </template> + <template #arrow-down> + <span class="tw-text-xs tw-text-gray-400">Scroll down</span> + </template> + <div v-for="i in 50" :key="i" class="tw-p-2">Row {{ i }}</div> +</VcScrollableContainer> +``` + +## Tips + +- The `speed` prop is captured once at mount time and is not reactive. If you need to change speed dynamically, remount the component with a `:key` binding. +- Call `updateScrollState()` after programmatically adding or removing items so the arrows recalculate visibility. +- The viewport hides its scrollbar with `scrollbar-width: none` and the `-webkit-scrollbar` pseudo-element, but native scroll behavior (mouse wheel, trackpad) still works. +- Arrow indicators auto-hide with an opacity transition when the user cannot scroll further in that direction. + +## Accessibility + +- `role="region"` with `aria-label="Scrollable content"` on the root element +- Viewport is focusable (`tabindex="0"`) for keyboard navigation +- Up/Down arrow keys scroll content in discrete steps (40px) +- Scroll-arrow indicators are `aria-hidden="true"` + +## Related Components + +- **VcIcon** -- used internally for the default chevron arrows diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-sidebar.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-sidebar.md new file mode 100644 index 0000000000..bbb2ed05fd --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/layout/vc-sidebar.md @@ -0,0 +1,248 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-sidebar/vc-sidebar.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcSidebar + +A slide-over panel for contextual workflows, settings, and detail views. Supports left, right, and bottom positions with animated transitions, focus trapping, scroll locking, and swipe-to-dismiss gestures. VcSidebar is built for use cases where a full blade is too heavy but a popup is too small — settings panels, filter drawers, item detail previews, and mobile bottom sheets. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcsidebar--elevated-panel&viewMode=story" + loading="lazy" + title="overlay-vcsidebar--elevated-panel" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcsidebar--elevated-panel" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +!!! tip "Sidebar vs Popup vs Blade" +Use VcSidebar for contextual workflows that need persistent visibility. Use `VcPopup` for brief confirmation dialogs. Use `VcBlade` for primary CRUD content that belongs in the navigation stack. + +## When to Use + +- Settings panels, filter drawers, or contextual detail views. +- Bottom sheet on mobile (with `position="bottom"` and `draggable`). +- Full-screen takeover for complex sub-workflows (`size="full"`). +- When NOT to use: for confirmation dialogs use `VcPopup`; for primary content use `VcBlade`. + +## Basic Usage + +```vue +<template> + <VcButton @click="open = true">Open Sidebar</VcButton> + + <VcSidebar + v-model="open" + title="Settings" + position="right" + size="md" + > + <div class="tw-p-4">Sidebar content</div> + + <template #footer> + <VcButton @click="open = false">Close</VcButton> + </template> + </VcSidebar> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; +import { VcSidebar, VcButton } from "@vc-shell/framework"; + +const open = ref(false); +</script> +``` + +## Props + +| Prop | Type | Default | Description | +| ---------------- | -------------------------------------- | ----------- | --------------------------------------------------- | +| `modelValue` | `boolean` | _required_ | Open/close state (v-model). | +| `position` | `"left" \| "right" \| "bottom"` | `"right"` | Slide-in direction. | +| `size` | `"sm" \| "md" \| "lg" \| "full"` | `"sm"` | Panel size preset (300/380/520px or full viewport). | +| `variant` | `"default" \| "elevated" \| "minimal"` | `"default"` | Visual style. | +| `width` | `number \| string` | -- | Custom width override (left/right positions). | +| `height` | `number \| string` | -- | Custom height override (bottom position). | +| `title` | `string` | `""` | Header title text. | +| `subtitle` | `string` | `""` | Header subtitle text. | +| `showOverlay` | `boolean` | `true` | Show backdrop overlay. | +| `closeOnOverlay` | `boolean` | `true` | Close when clicking overlay. | +| `closeOnEscape` | `boolean` | `true` | Close on Escape key. | +| `closeButton` | `boolean` | `true` | Show close button in header. | +| `trapFocus` | `boolean` | `true` | Trap keyboard focus inside panel. | +| `lockScroll` | `boolean` | `true` | Prevent body scroll while open. | +| `inset` | `boolean` | `true` | Add rounded inset gap from viewport edges. | +| `draggable` | `boolean` | `false` | Enable swipe-to-dismiss (bottom only). | +| `dragHandle` | `boolean` | `false` | Show iOS-style drag handle bar. | + +## Events + +| Event | Payload | Description | +| ------------------- | -------------------- | ----------------------------------------------- | +| `update:modelValue` | `boolean` | v-model update. | +| `close` | `SidebarCloseReason` | Reason: `"overlay"`, `"escape"`, or `"action"`. | + +## Slots + +| Slot | Props | Description | +| --------- | ----------- | --------------------------------------------- | +| `default` | -- | Main content area. | +| `header` | `{ close }` | Custom header replacing title + close button. | +| `actions` | `{ close }` | Extra buttons in the header actions area. | +| `footer` | -- | Sticky footer area. | + +## Features + +### Animated Transitions + +The panel slides in from its configured `position` with a smooth CSS transition. The overlay fades in simultaneously. When `prefers-reduced-motion` is active, transitions are disabled for accessibility. + +### Focus Trapping and Scroll Locking + +When `trapFocus` is true (default), Tab key cycles through focusable elements inside the panel. When `lockScroll` is true (default), the page body scroll is locked, preventing background content from scrolling under the overlay. + +### Swipe-to-Dismiss (Bottom Sheet) + +When `position="bottom"` and `draggable` is true, users can swipe the panel down to dismiss it. The `dragHandle` prop adds a visible handle bar at the top of the panel for better affordance. + +### Size Presets + +| Size | Width/Height | +| ------ | ------------- | +| `sm` | 300px | +| `md` | 380px | +| `lg` | 520px | +| `full` | Full viewport | + +Override with the `width` or `height` prop for custom dimensions. + +## Common Patterns + +### Bottom Sheet with Swipe-to-Dismiss + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcsidebar--bottom-sheet&viewMode=story" + loading="lazy" + title="overlay-vcsidebar--bottom-sheet" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcsidebar--bottom-sheet" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +```vue +<VcSidebar v-model="open" position="bottom" size="md" draggable drag-handle> + <div class="tw-p-4">Swipe down to close</div> +</VcSidebar> +``` + +### Elevated Variant with Custom Width + +```vue +<VcSidebar v-model="open" variant="elevated" :width="480" title="Details"> + <div class="tw-p-5">Content</div> +</VcSidebar> +``` + +## Recipe: Filter Drawer in a List Blade + +```vue +<script setup lang="ts"> +import { ref, reactive } from "vue"; + +const showFilters = ref(false); +const filters = reactive({ + status: "", + dateFrom: "", + dateTo: "", + category: "", +}); + +function applyFilters() { + showFilters.value = false; + loadItems(filters); +} + +function resetFilters() { + Object.assign(filters, { status: "", dateFrom: "", dateTo: "", category: "" }); +} +</script> + +<template> + <VcButton + icon="lucide-filter" + @click="showFilters = true" + >Filters</VcButton + > + + <VcSidebar + v-model="showFilters" + title="Filters" + position="right" + size="sm" + > + <div class="tw-p-4 tw-space-y-4"> + <VcSelect + label="Status" + v-model="filters.status" + :options="statusOptions" + /> + <VcInput + label="Date From" + v-model="filters.dateFrom" + type="date" + /> + <VcInput + label="Date To" + v-model="filters.dateTo" + type="date" + /> + <VcSelect + label="Category" + v-model="filters.category" + :options="categoryOptions" + /> + </div> + + <template #footer> + <div class="tw-flex tw-gap-2 tw-p-4"> + <VcButton + variant="primary" + @click="applyFilters" + >Apply</VcButton + > + <VcButton + variant="outline" + @click="resetFilters" + >Reset</VcButton + > + </div> + </template> + </VcSidebar> +</template> +``` + +## Common Mistakes + +- **Using `draggable` with left/right position** -- Swipe-to-dismiss only works with `position="bottom"`. Setting `draggable` on a left or right sidebar has no effect. +- **Forgetting `v-model`** -- VcSidebar requires a `v-model` binding to control open/close state. Without it, the panel cannot be dismissed. +- **Nested scrolling conflicts** -- If the sidebar content is scrollable and `lockScroll` is true, the body scroll is locked but the sidebar content scrolls normally. If you have nested scroll containers, test carefully on mobile. + +## Tips + +- Listen to the `close` event to distinguish how the sidebar was closed (`"overlay"` click, `"escape"` key, or `"action"` button). This is useful when you need to prompt for unsaved changes only on certain close methods. +- The `inset` prop (default `true`) adds a small gap between the sidebar and the viewport edges with rounded corners. Set `inset` to `false` for an edge-to-edge panel that looks more like a traditional drawer. +- The `minimal` variant removes the header background and border, useful for lightweight panels that blend into the content. +- Use the `header` slot to completely replace the default header when you need a custom layout (e.g., tabs in the header, search input, breadcrumbs). + +## Accessibility + +- Uses `role="dialog"` with `aria-modal` when overlay is shown. +- Focus is trapped inside the panel and restored to the trigger element on close. +- Keyboard: Escape closes, Tab cycles through focusable elements. +- Reduced motion: transitions are disabled when `prefers-reduced-motion` is active. + +## Related Components + +- **VcPopup** -- centered modal dialog for confirmations and alerts. +- **VcBlade** -- primary content panel in the blade navigation stack. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/.pages new file mode 100644 index 0000000000..25c7e0002e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/.pages @@ -0,0 +1,7 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Media +nav: + - VcImage: vc-image.md + - VcImageUpload: vc-image-upload.md + - VcVideo: vc-video.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image-upload.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image-upload.md new file mode 100644 index 0000000000..5f7cc2a6f5 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image-upload.md @@ -0,0 +1,163 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-image-upload/vc-image-upload.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcImageUpload + +A single-image upload organism that displays either a drag-and-drop upload zone or an image tile with preview and remove actions. VcImageUpload manages three visual states automatically: an interactive dropzone when no image is set, an image tile with action overlays when an image is provided, and a disabled empty state with a hint message. It integrates with vee-validate for file validation (size, format) and supports lightbox preview via the built-in VcImageTile component. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcimageupload--empty&viewMode=story" + loading="lazy" + title="data-display-vcimageupload--empty" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcimageupload--empty" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Use **VcImageUpload** for single-image fields (avatar, logo, thumbnail, hero image). +- Use when you need drag-and-drop file selection with validation. +- For multi-image galleries with reorder support, use **VcGallery** instead. +- When NOT to use: for multiple images (use VcGallery); for non-image file uploads (build a custom uploader). + +## Props + +| Prop | Type | Default | Description | +| ------------- | -------------------------------- | ---------------------------------- | ---------------------------------------------- | +| `image` | `ICommonAsset` | `undefined` | The currently displayed image asset. | +| `disabled` | `boolean` | `false` | Disables upload and remove actions. | +| `loading` | `boolean` | `false` | Shows a loading spinner on the upload zone. | +| `accept` | `string` | `.jpg,.png,.jpeg,.webp,.heic,.svg` | Accepted file extensions. | +| `rules` | `IValidationRules` | `undefined` | Validation rules (e.g. `{ fileWeight: 300 }`). | +| `name` | `string` | `"Image"` | Field name for validation messages. | +| `icon` | `string` | `"lucide-cloud-upload"` | Upload zone placeholder icon. | +| `placeholder` | `{ text: string; link: string }` | `undefined` | Custom text for the upload zone. | +| `previewable` | `boolean` | `true` | Enables lightbox preview on click. | +| `removable` | `boolean` | `true` | Shows the remove action on the image tile. | + +## Events + +| Event | Payload | Description | +| -------- | -------------- | ------------------------------------------- | +| `upload` | `FileList` | Emitted when files are selected or dropped. | +| `remove` | `ICommonAsset` | Emitted when the remove button is clicked. | + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcimageupload--with-image&viewMode=story" + loading="lazy" + title="data-display-vcimageupload--with-image" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcimageupload--with-image" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Visual States + +The component has three visual states: + +1. **Upload zone** -- No image and not disabled. Shows a dropzone with icon, placeholder text, and a clickable link. Accepts drag-and-drop or click to open the file picker. +2. **Image tile** -- An image is provided. Shows the image with optional preview (lightbox) and remove action buttons on hover. +3. **Empty disabled** -- No image and disabled. Shows an empty hint message indicating that uploading is not available. + +## Basic Usage + +```vue +<VcImageUpload :image="product.thumbnail" accept=".jpg,.png,.webp" :rules="{ fileWeight: 500 }" @upload="handleUpload" @remove="handleRemove" /> +``` + +## Recipe: Avatar Upload in a User Profile Blade + +```vue +<script setup lang="ts"> +import { ref } from "vue"; +import type { ICommonAsset } from "@vc-shell/framework"; + +const avatar = ref<ICommonAsset | undefined>(); + +async function handleUpload(files: FileList) { + const file = files[0]; + const uploaded = await uploadAvatar(file); + avatar.value = uploaded; +} + +function handleRemove() { + avatar.value = undefined; +} +</script> + +<template> + <VcBlade title="User Profile"> + <VcLabel>Profile Picture</VcLabel> + <VcImageUpload + :image="avatar" + accept=".jpg,.png,.webp" + :rules="{ fileWeight: 200 }" + name="Avatar" + icon="lucide-user" + :placeholder="{ text: 'Drop your photo here or', link: 'browse' }" + @upload="handleUpload" + @remove="handleRemove" + /> + <VcHint>Recommended size: 200x200px, max 200KB</VcHint> + </VcBlade> +</template> +``` + +<div class="vc-storybook-embed" style="--height: 250px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcimageupload--loading&viewMode=story" + loading="lazy" + title="data-display-vcimageupload--loading" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcimageupload--loading" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Recipe: Conditional Upload with Loading State + +```vue +<script setup lang="ts"> +const isUploading = ref(false); + +async function handleUpload(files: FileList) { + isUploading.value = true; + try { + product.value.thumbnail = await api.uploadImage(files[0]); + } finally { + isUploading.value = false; + } +} +</script> + +<template> + <VcImageUpload + :image="product.thumbnail" + :loading="isUploading" + :disabled="!canEdit" + :removable="canEdit" + @upload="handleUpload" + @remove="handleRemove" + /> +</template> +``` + +## Common Mistakes + +- **Forgetting to handle the `upload` event** -- VcImageUpload does not upload files itself. You must handle the `upload` event, send the file to your API, and update the `image` prop with the result. +- **Using watch URL instead of asset object** -- The `image` prop expects an `ICommonAsset` object (with `url`, `name`, etc.), not a plain URL string. +- **Not setting validation rules** -- Without `rules`, any file size or format is accepted. Always set `{ fileWeight: <maxKB> }` to prevent oversized uploads. + +## Tips + +- The `accept` prop is passed directly to the underlying `<input type="file">` element. Use comma-separated extensions (`.jpg,.png`) or MIME types (`image/jpeg,image/png`). +- Set `previewable` to `false` if the image tile should not open a lightbox on click (e.g., when the image is an icon or logo that does not benefit from full-screen preview). +- The upload zone supports both click-to-browse and drag-and-drop. The drag feedback is automatic (the zone highlights on dragover). +- When `loading` is true, a spinner replaces the upload zone icon. Use this while your API call is in progress. + +## Related Components + +- **VcGallery** -- multi-image gallery with drag-and-drop reorder +- **VcImageTile** -- the internal tile component that renders the image preview and action buttons +- **VcLabel** / **VcHint** -- use alongside VcImageUpload for field labeling and helper text diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image.md new file mode 100644 index 0000000000..46ebb64d73 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-image.md @@ -0,0 +1,117 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-image/vc-image.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcImage + +An image display component with predefined sizes, aspect ratio control, and a placeholder for missing sources. Renders images as CSS backgrounds with automatic HTTPS enforcement. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcimage--default&viewMode=story" + loading="lazy" + title="data-display-vcimage--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcimage--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Display product thumbnails, profile avatars, or media previews +- Show images with consistent aspect ratios across a layout +- Provide clickable image tiles (e.g., gallery lightbox triggers) +- When NOT to use: for icons or symbolic graphics, use [VcIcon](../misc/vc-icon.md); for full-page hero images, use a standard `<img>` tag + +## Basic Usage + +```vue +<VcImage src="https://example.com/product.jpg" size="l" /> +``` + +## Key Props + +| Prop | Type | Default | Description | +| --------------- | --------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `src` | `string` | — | Image URL; shows a placeholder icon when empty | +| `size` | `"auto" \| "xxs" \| "xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl"` | `"auto"` | Predefined width | +| `aspect` | `"1x1" \| "16x9" \| "4x3" \| "3x2"` | `"1x1"` | Aspect ratio of the container | +| `background` | `"cover" \| "contain" \| "auto"` | `"cover"` | CSS background-size mode | +| `rounded` | `boolean` | `false` | Applies fully rounded corners (circular on 1x1) | +| `bordered` | `boolean` | `false` | Adds a subtle border | +| `clickable` | `boolean` | `false` | Makes the image interactive with cursor and click event | +| `emptyIcon` | `string` | `"lucide-image"` | Icon shown when `src` is empty | +| `alt` | `string` | — | Accessible alt text | +| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` | + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcimage--size-variants&viewMode=story" + loading="lazy" + title="data-display-vcimage--size-variants" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcimage--size-variants" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Size Reference + +| Size | Width | +| ------ | -------------- | +| `xxs` | 24px | +| `xs` | 32px | +| `s` | 48px | +| `m` | 64px | +| `l` | 96px | +| `xl` | 128px | +| `xxl` | 145px | +| `auto` | 100% of parent | + +## Common Patterns + +### Product Thumbnail in a List + +```vue +<VcImage :src="product.primaryImage" size="s" aspect="1x1" bordered :alt="product.name" /> +``` + +### Profile Avatar + +```vue +<VcImage :src="user.avatarUrl" size="m" rounded :alt="user.displayName" /> +``` + +### Widescreen Banner + +```vue +<VcImage :src="category.bannerUrl" aspect="16x9" background="cover" alt="Category banner" /> +``` + +### Clickable Gallery Image + +```vue +<VcImage :src="image.url" size="l" bordered clickable :alt="image.caption" @click="openLightbox(image)" /> +``` + +### Empty State Placeholder + +```vue +<VcImage size="xl" empty-icon="lucide-package" alt="" /> +``` + +## Accessibility + +- When `src` is present and no `clickable`, the container has `role="img"` with `aria-label` from `alt` +- Clickable images receive `role="button"`, `tabindex="0"`, and keyboard support (Enter/Space) +- Empty placeholder icon is marked `aria-hidden="true"` +- Focus ring appears on `:focus-visible` for clickable images +- HTTP URLs are automatically upgraded to HTTPS when the page is served over HTTPS + +!!! tip "Use thumbnailSize for faster load times" +When displaying images in lists or grids, pass a `thumbnailSize` (e.g. `"128x128"`) to request a pre-scaled variant from the platform CDN instead of loading the full-resolution original. This significantly reduces bandwidth and speeds up initial render. + +## Related Components + +- [VcIcon](../misc/vc-icon.md) — for symbolic icons rather than photographic content +- [VcImageTile](../data-display/vc-image-tile.md) — combines VcImage with overlay actions for gallery use + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-video.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-video.md new file mode 100644 index 0000000000..7646923e75 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/media/vc-video.md @@ -0,0 +1,146 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-video/vc-video.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcVideo + +An embedded video player that renders an iframe for external video sources (YouTube, Vimeo, etc.) with an optional label and tooltip. When no source URL is provided, the component displays a centered film icon placeholder instead of a blank space, giving users a clear visual cue that a video can be attached. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcvideo--default&viewMode=story" + loading="lazy" + title="data-display-vcvideo--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcvideo--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Embed product or tutorial videos in blade detail views +- Display instructional content alongside form fields +- Show a placeholder for an optional video field that has not been filled yet +- When NOT to use: native HTML5 video playback from local files (use a plain `<video>` element); audio-only content (use an `<audio>` element) + +## Basic Usage + +```vue +<template> + <VcVideo + source="https://www.youtube.com/embed/PeXX-V-dwpA" + label="Product Overview" + /> +</template> + +<script setup lang="ts"> +import { VcVideo } from "@vc-shell/framework"; +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| --------- | -------- | ------- | -------------------------------------------------- | +| `source` | `string` | -- | Embed URL for the video (e.g., YouTube embed link) | +| `label` | `string` | -- | Label text displayed above the video | +| `tooltip` | `string` | -- | Tooltip text shown on the label's info icon | + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcvideo--with-tooltip&viewMode=story" + loading="lazy" + title="data-display-vcvideo--with-tooltip" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcvideo--with-tooltip" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Common Patterns + +### Video with Label and Tooltip + +```vue +<VcVideo source="https://www.youtube.com/embed/dQw4w9WgXcQ" label="Setup Guide" tooltip="This video walks through the initial configuration steps" /> +``` + +### Placeholder When Source Is Missing + +When `source` is not provided, VcVideo renders a centered film icon placeholder instead of a blank space. + +```vue +<VcVideo label="Video Not Available" /> +``` + +### Conditional Video in a Product Blade + +```vue +<template> + <VcBlade title="Product Details"> + <VcInput + label="Video URL" + v-model="product.videoUrl" + placeholder="https://youtube.com/embed/..." + /> + <VcVideo + :source="product.videoUrl" + label="Product Video" + tooltip="Paste a YouTube or Vimeo embed URL above" + /> + </VcBlade> +</template> +``` + +## Recipe: Side-by-Side Video and Description + +```vue +<template> + <VcRow class="tw-gap-4"> + <VcCol :size="1"> + <VcVideo + :source="tutorial.embedUrl" + :label="tutorial.title" + /> + </VcCol> + <VcCol :size="1"> + <h3 class="tw-font-medium tw-mb-2">{{ tutorial.title }}</h3> + <p class="tw-text-sm tw-text-gray-600">{{ tutorial.description }}</p> + <VcHint>Duration: {{ tutorial.duration }}</VcHint> + </VcCol> + </VcRow> +</template> +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ------------------------ | --------------------- | ----------------------- | +| `--video-icon-color` | `var(--neutrals-400)` | Placeholder icon color | +| `--video-placeholder-bg` | `var(--neutrals-100)` | Placeholder background | +| `--video-border-radius` | `6px` | Container corner radius | +| `--video-border-color` | `var(--neutrals-200)` | Container border color | + +## Tips + +- Always use the **embed** URL format, not the standard watch URL. For YouTube, use `https://www.youtube.com/embed/VIDEO_ID` instead of `https://www.youtube.com/watch?v=VIDEO_ID`. +- The iframe has `loading="lazy"`, so videos below the fold are not loaded until the user scrolls to them. This keeps initial page load fast. +- The `sandbox` attribute restricts iframe capabilities to `allow-scripts allow-same-origin allow-presentation allow-popups` for security. If your video host requires additional permissions, you may need a custom wrapper. +- The iframe renders at a fixed height of 300px. To customize the height, override the iframe styles via a scoped CSS rule targeting `.vc-video__container iframe`. +- The placeholder has a height of 200px so the layout does not collapse when no source is provided. + +## Accessibility + +- The iframe uses the `title` attribute (set to `label` or "Video") for screen readers +- `sandbox` attribute restricts iframe capabilities to `allow-scripts allow-same-origin allow-presentation allow-popups` +- `loading="lazy"` defers iframe load until visible +- Placeholder state uses `role="img"` with `aria-label="No video source"` + +!!! warning "Always use embed URLs, not watch URLs" +YouTube watch URLs (`youtube.com/watch?v=...`) will be blocked by the browser's frame policy. Always convert to the embed format (`youtube.com/embed/VIDEO_ID`). Vimeo similarly requires `player.vimeo.com/video/VIDEO_ID`. + +## Related Components + +- [VcLabel](../misc/vc-label.md) -- used internally for the label with tooltip +- [VcIcon](../misc/vc-icon.md) -- renders the placeholder film icon +- [VcRow](../layout/vc-row.md) / [VcCol](../layout/vc-col.md) -- layout primitives for placing video alongside other content + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/.pages new file mode 100644 index 0000000000..eaff07e773 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/.pages @@ -0,0 +1,9 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Misc +nav: + - VcBadge: vc-badge.md + - VcButton: vc-button.md + - VcIcon: vc-icon.md + - VcLabel: vc-label.md + - VcWidget: vc-widget.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-badge.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-badge.md new file mode 100644 index 0000000000..4378c36d0f --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-badge.md @@ -0,0 +1,161 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-badge/vc-badge.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcBadge + +A small indicator component for displaying counts, status dots, or short text labels. Supports two rendering modes: **positioned overlay** on a slotted element (e.g., notification count on a bell icon), or **standalone inline** badge (e.g., a tag/pill label in a list). Inline badges use a softer color palette with tinted backgrounds, while overlay badges use solid fills for maximum contrast. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcbadge--default&viewMode=story" + loading="lazy" + title="data-display-vcbadge--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcbadge--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Show unread notification counts on icons or buttons +- Display item counts (cart, wishlist, messages) +- Indicate status with a colored dot (online, new content) +- Render inline tag/pill labels with semantic color variants +- When NOT to use: for longer status text or multi-line content, use [VcBanner](../feedback/vc-banner.md) instead; for labeled multi-state indicators, consider [VcStatus](../feedback/vc-status.md) + +## Basic Usage + +```vue +<VcBadge content="3" variant="danger"> + <VcIcon icon="lucide-bell" size="xl" /> +</VcBadge> +``` + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcbadge--variants&viewMode=story" + loading="lazy" + title="data-display-vcbadge--variants" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcbadge--variants" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Key Props + +| Prop | Type | Default | Description | +| ---------------- | -------------------------------------------------------------------------- | ----------- | --------------------------------------------------------- | +| `content` | `string \| number` | -- | Text or number displayed inside the badge | +| `variant` | `"primary" \| "success" \| "warning" \| "danger" \| "info" \| "secondary"` | `"primary"` | Color variant | +| `size` | `"s" \| "m"` | `"m"` | Badge size | +| `isDot` | `boolean` | `false` | Renders as a small dot without text | +| `inline` | `boolean` | `false` | Renders as an inline element without absolute positioning | +| `clickable` | `boolean` | `false` | Makes the badge respond to click events | +| `disabled` | `boolean` | `false` | Disables interaction on clickable badges | +| `customPosition` | `boolean` | `false` | Enables custom `top`/`right` positioning | +| `top` | `string` | -- | Custom top offset (requires `customPosition`) | +| `right` | `string` | -- | Custom right offset (requires `customPosition`) | +| `ariaLabel` | `string` | -- | Custom accessible label for the badge | + +<div class="vc-storybook-embed" style="--height: 350px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcbadge--use-cases&viewMode=story" + loading="lazy" + title="data-display-vcbadge--use-cases" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcbadge--use-cases" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Common Patterns + +### Notification Count on an Icon + +```vue +<VcBadge :content="unreadCount" variant="danger"> + <VcButton variant="ghost" size="icon" icon="lucide-bell" aria-label="Notifications" /> +</VcBadge> +``` + +### Dot Indicator for New Content + +```vue +<VcBadge is-dot variant="success"> + <VcIcon icon="lucide-message-square" size="l" /> +</VcBadge> +``` + +### Inline Tag / Pill + +```vue +<div class="tw-flex tw-gap-2"> + <VcBadge inline content="Active" variant="success" /> + <VcBadge inline content="Draft" variant="secondary" /> + <VcBadge inline content="Rejected" variant="danger" /> +</div> +``` + +### Clickable Badge with Dismiss + +```vue +<VcBadge :content="count" clickable variant="primary" @click="clearNotifications"> + <VcIcon icon="lucide-inbox" size="xl" /> +</VcBadge> +``` + +## Recipe: Status Tags in a Table Cell + +```vue +<VcColumn id="status" header="Status" :width="120"> + <template #default="{ row }"> + <VcBadge + inline + :content="row.status" + :variant="statusVariantMap[row.status]" + size="s" + /> + </template> +</VcColumn> +``` + +```ts +const statusVariantMap: Record<string, string> = { + Active: "success", + Pending: "warning", + Archived: "secondary", + Rejected: "danger", +}; +``` + +## Recipe: Custom Positioned Badge + +Fine-tune the badge position relative to its parent: + +```vue +<VcBadge content="NEW" variant="info" custom-position top="-4px" right="-12px"> + <img src="/product.jpg" class="tw-w-16 tw-h-16 tw-rounded" /> +</VcBadge> +``` + +## Tips + +- Content longer than 2 characters is automatically truncated with an ellipsis and capped at 40px width. For short counts, prefer numbers (`3`, `99+`) over words. +- Inline badges use a softer color scheme (e.g., `bg-primary-50` / `text-primary-700`) compared to overlay badges that use solid fills (`bg-primary-500` / white text). This is handled automatically based on the `inline` prop. +- The `isDot` variant ignores the `content` prop entirely and renders a small circle. Use it for presence indicators (online/offline) rather than counts. +- When `clickable` is true, the badge gains `role="button"`, `tabindex="0"`, and keyboard event handlers for Enter and Space. Always provide an `ariaLabel` for clickable badges so screen readers can announce the action. + +## Accessibility + +- Clickable badges receive `role="button"` and are keyboard-focusable (`tabindex="0"`) +- Supports Enter and Space key activation +- Dot badges default to `aria-label="Notification"` when no custom `ariaLabel` is provided +- Disabled clickable badges set `aria-disabled="true"` +- Focus ring appears on `:focus-visible` for keyboard navigation + +## Related Components + +- [VcButton](./vc-button.md) -- for primary interactive actions +- [VcIcon](./vc-icon.md) -- commonly used as slotted content inside badges +- [VcBanner](../feedback/vc-banner.md) -- for longer contextual messages and alerts +- [VcStatus](../feedback/vc-status.md) -- labeled multi-variant status indicator + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-button.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-button.md new file mode 100644 index 0000000000..838ae0a5f3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-button.md @@ -0,0 +1,352 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-button/vc-button.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcButton + +A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application — from toolbar buttons and form submissions to inline table actions and navigation. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vcbutton--primary&viewMode=story" + loading="lazy" + title="action-vcbutton--primary" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vcbutton--primary" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +| Scenario | Component | +| ------------------------------------------- | --------------------------------------------------------- | +| Triggering an action (save, delete, submit) | **VcButton** | +| Navigating to another URL or route | `<router-link>` or `<a>` tag | +| Action inside a blade toolbar | `IBladeToolbar` items (rendered as buttons automatically) | +| Inline text-style link within a paragraph | Native `<a>` or `<router-link>` | + +Use VcButton for any user-initiated action that does not navigate to a URL. **Do not use** VcButton for navigation -- the `link` variant looks like a link but calls `preventDefault()`, so actual URL navigation will not work. For toolbar actions, define `IBladeToolbar` objects instead of placing VcButton manually. + +## Quick Start + +```vue +<template> + <VcButton + variant="primary" + @click="handleSave" + >Save Changes</VcButton + > +</template> + +<script setup lang="ts"> +import { VcButton } from "@vc-shell/framework"; +</script> +``` + +## Variants + +VcButton provides 9 visual variants organized into three emphasis levels. + +<div class="vc-storybook-embed" style="--height: 500px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vcbutton--all-variants&viewMode=story" + loading="lazy" + title="action-vcbutton--all-variants" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vcbutton--all-variants" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +### Filled Variants (High Emphasis) + +Solid background colors for primary and prominent actions. + +```vue +<VcButton variant="primary">Primary Action</VcButton> +<VcButton variant="danger">Delete</VcButton> +<VcButton variant="warning">Caution</VcButton> +<VcButton variant="success">Approve</VcButton> +<VcButton variant="info">Learn More</VcButton> +``` + +| Variant | Use Case | Text Color | +| --------- | -------------------------------------- | ------------------- | +| `primary` | Main CTA -- save, submit, confirm | White | +| `danger` | Destructive actions -- delete, remove | White | +| `warning` | Caution actions -- override, force | Dark (for contrast) | +| `success` | Positive actions -- approve, publish | White | +| `info` | Informational actions -- details, help | White | + +### Structural Variants (Medium Emphasis) + +Bordered or transparent backgrounds for secondary actions. + +```vue +<VcButton variant="secondary">Cancel</VcButton> +<VcButton variant="outline">Export</VcButton> +``` + +| Variant | Use Case | Hover Behavior | +| ----------- | ------------------------------------- | ------------------------------------------------ | +| `secondary` | Cancel, dismiss, secondary actions | Background changes to primary-50 | +| `outline` | Alternative actions alongside primary | Background changes to primary-50, border darkens | + +### Minimal Variants (Low Emphasis) + +No border or background, used for inline or de-emphasized actions. + +```vue +<VcButton variant="ghost">Settings</VcButton> +<VcButton variant="link">View Documentation</VcButton> +``` + +| Variant | Use Case | Hover Behavior | +| ------- | ---------------------------------- | --------------------- | +| `ghost` | Toolbar icons, inline actions | Light background tint | +| `link` | Text-like navigation, inline links | Underline on text | + +## Sizes + +Five size options cover all common use cases from toolbar icons to prominent CTAs. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vcbutton--all-sizes&viewMode=story" + loading="lazy" + title="action-vcbutton--all-sizes" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vcbutton--all-sizes" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +```vue +<VcButton size="sm">Small</VcButton> +<VcButton size="default">Default</VcButton> +<VcButton size="lg">Large</VcButton> +<VcButton size="icon" icon="lucide-settings" aria-label="Settings" /> +<VcButton size="icon-sm" icon="lucide-pencil" aria-label="Edit" /> +``` + +| Size | Height | Padding | Typical Use | +| --------- | ------- | ----------------------------- | ----------------------------------- | +| `sm` | 32px | 12px horizontal | Compact form actions, table footers | +| `default` | 36px | 16px horizontal, 8px vertical | Standard blade actions | +| `lg` | 40px | 24px horizontal | Prominent CTAs, dialog actions | +| `icon` | 36x36px | 0 (square) | Toolbar icon buttons | +| `icon-sm` | 24x24px | 0 (square) | Table cell actions, inline controls | + +!!! note "Legacy size aliases" +`xs` (maps to `sm`) and `base` (maps to `default`) are supported for backward compatibility but should not be used in new code. + +## Icons + +VcButton supports icons via the `icon` prop. Icons appear to the left of the button text, or centered for icon-only buttons. + +```vue +<!-- Icon + text --> +<VcButton variant="primary" icon="lucide-plus">Add Item</VcButton> + +<!-- Icon only (requires aria-label) --> +<VcButton variant="ghost" size="icon" icon="lucide-settings" aria-label="Settings" /> + +<!-- Custom icon size --> +<VcButton icon="lucide-download" icon-size="m">Download</VcButton> +``` + +The `icon` prop accepts a string (icon identifier like `lucide-plus`) or a Vue component. + +## Loading State + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vcbutton--loading&viewMode=story" + loading="lazy" + title="action-vcbutton--loading" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vcbutton--loading" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +When `loading` is `true`, the button shows a spinner in place of its icon and becomes non-interactive: + +```vue +<VcButton variant="primary" :loading="isSaving" @click="save"> + Save Changes +</VcButton> +``` + +During loading: + +- The icon is replaced with a spinning `lucide-loader-2` +- The button is disabled (`pointer-events: none`) +- The cursor changes to `wait` +- `aria-busy="true"` is set for assistive technologies + +## Selected State + +The `selected` prop applies a visual highlight. Useful for toggle buttons or active states: + +```vue +<VcButton variant="ghost" :selected="isGridView" icon="lucide-grid" aria-label="Grid view" @click="isGridView = true" /> +``` + +When selected, `aria-pressed="true"` is set on the button element. + +## Text Modifier + +The `text` prop renders the button with no background or border, showing only the text in the variant's color. Useful for inline actions: + +```vue +<VcButton variant="primary" text @click="viewAll">View All</VcButton> +<VcButton variant="danger" text @click="clearAll">Clear</VcButton> +``` + +## Button Groups + +VcButton integrates with `VcButtonGroup` via provide/inject. The group can set a shared `size` for all child buttons: + +```vue +<VcButtonGroup size="sm"> + <VcButton variant="outline">Left</VcButton> + <VcButton variant="outline">Center</VcButton> + <VcButton variant="outline">Right</VcButton> +</VcButtonGroup> +``` + +## Recipes + +### Toolbar Save / Cancel Pair + +```vue +<template> + <div class="tw-flex tw-gap-2"> + <VcButton + variant="secondary" + @click="cancel" + >Cancel</VcButton + > + <VcButton + variant="primary" + :loading="isSaving" + @click="save" + > + Save + </VcButton> + </div> +</template> +``` + +### Confirmation Dialog Actions + +```vue +<template> + <div class="tw-flex tw-justify-end tw-gap-3 tw-p-4"> + <VcButton + variant="outline" + @click="dismiss" + >Cancel</VcButton + > + <VcButton + variant="danger" + :loading="isDeleting" + icon="lucide-trash-2" + @click="confirmDelete" + > + Delete Permanently + </VcButton> + </div> +</template> +``` + +!!! warning "Don't disable buttons during async actions" +Use the `loading` prop, not `disabled`. A disabled button gives no progress feedback; a loading button shows a spinner and announces busy state via `aria-busy`. + +## Common Mistakes + +### Missing aria-label on icon-only buttons + +```vue +<!-- Wrong -- no accessible name for screen readers --> +<VcButton size="icon" icon="lucide-trash-2" @click="remove" /> + +<!-- Correct --> +<VcButton size="icon" icon="lucide-trash-2" aria-label="Remove item" @click="remove" /> +``` + +### Using link variant for actual navigation + +```vue +<!-- Wrong -- VcButton prevents default on click, navigation will not work --> +<VcButton variant="link" @click="router.push('/orders')">Orders</VcButton> + +<!-- Correct -- use a router-link or <a> for URL navigation --> +<router-link to="/orders" class="tw-text-primary-700">Orders</router-link> +``` + +### Relying on disabled instead of loading + +```vue +<!-- Wrong -- user sees a frozen button with no feedback --> +<VcButton :disabled="isSaving" @click="save">Save</VcButton> + +<!-- Correct -- loading shows a spinner and communicates progress --> +<VcButton :loading="isSaving" @click="save">Save</VcButton> +``` + +## Props + +| Prop | Type | Default | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------- | +| `variant` | `"primary" \| "secondary" \| "danger" \| "warning" \| "success" \| "info" \| "outline" \| "ghost" \| "link"` | `"primary"` | Visual style variant | +| `size` | `"sm" \| "default" \| "lg" \| "icon" \| "icon-sm"` | `"default"` | Button size | +| `icon` | `string \| Component` | -- | Icon identifier or Vue component | +| `iconClass` | `string` | -- | Additional CSS class for the icon element | +| `iconSize` | `IconSize` | `"s"` | Size of the icon (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`, `"xxl"`) | +| `loading` | `boolean` | `false` | Shows spinner, disables interaction, sets `aria-busy` | +| `disabled` | `boolean` | `false` | Disables the button | +| `selected` | `boolean` | `false` | Applies selected/active visual state, sets `aria-pressed` | +| `text` | `boolean` | `false` | Renders as borderless text in the variant's color | +| `type` | `"button" \| "submit" \| "reset"` | `"button"` | HTML button type | +| `ariaLabel` | `string` | -- | Accessible label (required for icon-only buttons) | + +## Events + +| Event | Payload | Description | +| ------- | ------- | ------------------------------------------------------------------------ | +| `click` | `Event` | Emitted when the button is clicked (suppressed when disabled or loading) | + +## Slots + +| Slot | Description | +| --------- | ----------------------------------------------------------------- | +| `default` | Button text content. When empty, the button renders as icon-only. | + +## CSS Custom Properties + +All visual properties are customizable through CSS custom properties. Each variant has three property sets (normal, hover, disabled) for background, text, and border colors. + +| Pattern | Example | Description | +| ------------------------------------------- | ----------------------------------------- | ----------------------------- | +| `--button-{variant}-background-color` | `--button-primary-background-color` | Normal background | +| `--button-{variant}-background-color-hover` | `--button-primary-background-color-hover` | Hover background | +| `--button-{variant}-text-color` | `--button-primary-text-color` | Normal text color | +| `--button-{variant}-border-color` | `--button-primary-border-color` | Normal border color | +| `--button-border-radius` | `6px` | Corner radius for all buttons | +| `--button-focus-ring-color` | `var(--primary-300)` | Focus ring color | +| `--button-focus-ring-width` | `2px` | Focus ring thickness | +| `--button-{size}-height` | `--button-default-height: 36px` | Height per size | + +## Accessibility + +- Focus ring appears on `:focus-visible` only (keyboard navigation), not on mouse click +- Touch target is expanded to 44px minimum via a `::after` pseudo-element (WCAG 2.5.8) +- `aria-busy` is set to `true` during loading state +- `aria-pressed` reflects the `selected` prop for toggle buttons +- Icon-only buttons **must** include `ariaLabel` for screen reader users +- Disabled buttons use `pointer-events: none` and `opacity: 0.5` to prevent interaction +- The `click` event calls `e.preventDefault()` -- use `type="submit"` for form submissions + +## Related Components + +- [VcIcon](./vc-icon.md) — used internally for button icons +- [VcBadge](./vc-badge.md) — can wrap a button to show notification counts +- `VcButtonGroup` — groups buttons with shared size context (see component source for usage) + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-icon.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-icon.md new file mode 100644 index 0000000000..7228dc1917 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-icon.md @@ -0,0 +1,142 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-icon/vc-icon.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcIcon + +A unified icon component that renders icons from multiple libraries. Lucide Icons (`lucide-` prefix) are the standard; legacy libraries (FontAwesome, Bootstrap, Material) are deprecated. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcicon--basic&viewMode=story" + loading="lazy" + title="layout-vcicon--basic" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcicon--basic" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Display icons in buttons, menus, toolbars, and status indicators +- Indicate status with color variants (success, warning, danger) +- Render custom Vue icon components inline +- When NOT to use: for decorative images or product photos, use [VcImage](../media/vc-image.md) + +## Basic Usage + +```vue +<VcIcon icon="lucide-home" size="m" /> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------ | ------------------------------------------------------ | ----------------- | ---------------------------------------- | +| `icon` | `string \| Component` | `"lucide-square"` | Icon identifier or Vue component | +| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl" \| "xxl" \| "xxxl"` | `"m"` | Predefined size | +| `variant` | `"warning" \| "danger" \| "success"` | — | Semantic color variant | +| `customSize` | `number` | — | Custom size in pixels (overrides `size`) | +| `ariaLabel` | `string` | — | Accessible label for meaningful icons | +| `basePath` | `string` | `"/assets/icons"` | Base path for SVG sprite icons | + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcicon--all-sizes&viewMode=story" + loading="lazy" + title="layout-vcicon--all-sizes" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcicon--all-sizes" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Size Reference + +| Size | Pixels | +| ------ | ------ | +| `xs` | 12px | +| `s` | 14px | +| `m` | 18px | +| `l` | 20px | +| `xl` | 22px | +| `xxl` | 30px | +| `xxxl` | 64px | + +<div class="vc-storybook-embed" style="--height: 200px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=layout-vcicon--all-variants&viewMode=story" + loading="lazy" + title="layout-vcicon--all-variants" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/layout-vcicon--all-variants" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Icon Prefix Guide + +| Prefix | Library | Status | +| ----------------- | ---------------------- | ---------------------- | +| `lucide-` | Lucide Icons | Standard (recommended) | +| `fa-` / `fas fa-` | Font Awesome | Deprecated | +| `bi-` | Bootstrap Icons | Deprecated | +| `material-` | Material Symbols | Deprecated | +| `svg:` | SVG sprite file | Supported | +| _(Component)_ | Vue component instance | Supported | + +## Common Patterns + +### Status Indicator + +```vue +<div class="tw-flex tw-items-center tw-gap-2"> + <VcIcon icon="lucide-circle-check" variant="success" size="l" /> + <span>In Stock</span> +</div> +``` + +### Icon Inside a Button + +```vue +<VcButton variant="primary" icon="lucide-plus">Add Item</VcButton> +``` + +### Custom Pixel Size + +```vue +<VcIcon icon="lucide-shield" :custom-size="48" /> +``` + +### Meaningful Icon with Accessible Label + +```vue +<VcIcon icon="lucide-triangle-alert" variant="warning" size="l" aria-label="Warning: low stock" /> +``` + +### Custom Vue Component as Icon + +```vue +<script setup lang="ts"> +import { VcIcon } from "@vc-shell/framework"; +import MyCustomIcon from "./MyCustomIcon.vue"; +</script> + +<template> + <VcIcon + :icon="MyCustomIcon" + size="l" + /> +</template> +``` + +## Accessibility + +- Decorative icons (default) render with `aria-hidden="true"` +- When `ariaLabel` is provided, the icon receives `role="img"` and `aria-label` instead +- Always provide `ariaLabel` for icons that convey meaning not available in surrounding text +- Icon color inherits from `currentColor` by default, ensuring it follows parent text color + +## Related Components + +- [VcButton](./vc-button.md) — uses VcIcon internally for button icons +- [VcImage](../media/vc-image.md) — for photos and larger imagery +- [VcBanner](../feedback/vc-banner.md) — uses VcIcon for the leading alert icon + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-label.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-label.md new file mode 100644 index 0000000000..546d6be609 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-label.md @@ -0,0 +1,185 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-label/vc-label.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcLabel + +A form field label component with support for required indicators, info tooltips, multilanguage badges, and error states. Renders as a `<label>` when linked to an input via `htmlFor`, or a `<div>` otherwise. VcLabel is the standard way to label any form control in the framework and is used internally by most input molecules (VcInput, VcSelect, VcTextarea, etc.). + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vclabel--default&viewMode=story" + loading="lazy" + title="data-display-vclabel--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vclabel--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Label form inputs, selects, and textareas +- Indicate required fields with an asterisk +- Provide contextual help via tooltip icons +- Show the current language on multilingual fields +- When NOT to use: for helper text below a field, use [VcHint](../feedback/vc-hint.md); for section headings, use a standard heading element or [VcCard](../layout/vc-card.md) header + +## Basic Usage + +```vue +<VcLabel html-for="product-name" required> + Product Name + <template #tooltip>The display name shown to customers</template> +</VcLabel> +<input id="product-name" /> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ----------------- | --------- | --------------- | --------------------------------------------------------------------- | +| `required` | `boolean` | `false` | Shows a red asterisk after the label text | +| `error` | `boolean` | `false` | Renders the label in error state (danger color) | +| `htmlFor` | `string` | -- | Links the label to an input; when set, renders as `<label for="...">` | +| `tooltipIcon` | `string` | `"lucide-info"` | Icon used for the tooltip trigger | +| `multilanguage` | `boolean` | `false` | Shows a language indicator badge | +| `currentLanguage` | `string` | -- | Language code displayed in the badge (e.g. `"EN"`, `"DE"`) | + +## Slots + +| Slot | Description | +| --------- | -------------------------------------------- | +| `default` | Label text content | +| `tooltip` | Content displayed inside the tooltip popover | + +## CSS Custom Properties + +| Variable | Default | Description | +| ------------------------ | --------------------- | ------------------------------ | +| `--label-text-color` | `var(--neutrals-700)` | Default text color | +| `--label-required-color` | `var(--danger-500)` | Color of the required asterisk | +| `--label-tooltip-color` | `var(--neutrals-400)` | Tooltip icon color | +| `--label-lang-color` | `var(--neutrals-500)` | Language badge text color | +| `--label-error-color` | `var(--danger-500)` | Text color in error state | + +<div class="vc-storybook-embed" style="--height: 200px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vclabel--required&viewMode=story" + loading="lazy" + title="data-display-vclabel--required" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vclabel--required" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Common Patterns + +### Required Field with Tooltip + +```vue +<VcLabel html-for="sku" required> + SKU + <template #tooltip> + Stock Keeping Unit. Must be unique across all products. + </template> +</VcLabel> +``` + +### Multilanguage Field Label + +```vue +<VcLabel html-for="description" multilanguage :current-language="locale"> + Description +</VcLabel> +``` + +### Error State + +```vue +<VcLabel html-for="price" required :error="!!errors.price"> + Price +</VcLabel> +<VcInput id="price" v-model="form.price" :error="!!errors.price" /> +<VcHint v-if="errors.price" error>{{ errors.price }}</VcHint> +``` + +### Simple Label Without Tooltip + +```vue +<VcLabel html-for="notes">Notes</VcLabel> +``` + +## Recipe: Complete Form Field Group + +Compose VcLabel, an input, and VcHint into a reusable field pattern: + +```vue +<template> + <div class="tw-space-y-1"> + <VcLabel + html-for="slug" + required + :error="!!slugError" + > + URL Slug + <template #tooltip> The URL-friendly identifier for this page. Auto-generated from the title if left blank. </template> + </VcLabel> + <VcInput + id="slug" + v-model="form.slug" + :error="!!slugError" + aria-describedby="slug-hint" + aria-required="true" + /> + <VcHint + id="slug-hint" + :error="!!slugError" + > + {{ slugError || "Lowercase letters, numbers, and hyphens only." }} + </VcHint> + </div> +</template> +``` + +## Recipe: Custom Tooltip Icon + +Use a different icon for the tooltip trigger: + +```vue +<VcLabel html-for="api-key" tooltip-icon="lucide-shield"> + API Key + <template #tooltip> + Keep this key secret. Rotate it regularly for security. + </template> +</VcLabel> +``` + +## Tips + +- When `htmlFor` is provided, VcLabel renders as a native `<label>` element. Clicking the label will focus the linked input automatically. Without `htmlFor`, it renders as a `<div>` and does not create an implicit association. +- The required asterisk is purely visual (`aria-hidden="true"`). Always set `aria-required="true"` on the input itself so screen readers convey the requirement. +- The language badge (shown when `multilanguage` is true) appears on the right side of the label and uses a small pill with a neutral background. It displays the value of `currentLanguage` (e.g., "EN", "DE", "FR"). +- Label text is truncated with an ellipsis if it overflows. For very long labels, consider using the tooltip slot to provide the full text. + +## Accessibility + +- Renders as a native `<label>` when `htmlFor` is provided, creating an implicit input association +- The required asterisk is marked `aria-hidden="true"` since the required state should be communicated via `aria-required` on the input itself +- Tooltip icon is focusable and keyboard-accessible via the underlying VcTooltip component +- Error state changes the visual color but does not add ARIA attributes to the label; pair with `aria-invalid` and `aria-describedby` on the input + +<div class="vc-storybook-embed" style="--height: 300px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vclabel--with-form-field&viewMode=story" + loading="lazy" + title="data-display-vclabel--with-form-field" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vclabel--with-form-field" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Related Components + +- [VcHint](../feedback/vc-hint.md) -- helper/error text placed below the input +- [VcTooltip](../feedback/vc-tooltip.md) -- used internally for the info tooltip +- [VcInput](../form/vc-input.md) -- form input component commonly paired with VcLabel + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-widget.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-widget.md new file mode 100644 index 0000000000..65d41544d6 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/misc/vc-widget.md @@ -0,0 +1,139 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-widget/vc-widget.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcWidget + +A clickable widget tile with an icon, title, and optional badge counter. Used in blade toolbars and sidebars to trigger blade-level actions or navigation. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcwidget--default&viewMode=story" + loading="lazy" + title="data-display-vcwidget--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcwidget--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Build widget panels in blade sidebars (e.g., "Orders", "Reviews", "Notifications") +- Show action shortcuts with counts in dashboard layouts +- When NOT to use: primary form actions (use [VcButton](./vc-button.md)); standalone navigation links (use [VcLink](../navigation/vc-link.md)) + +## Basic Usage + +```vue +<template> + <VcWidget + icon="lucide-bell" + title="Notifications" + :value="unreadCount" + @click="openNotifications" + /> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; +import { VcWidget } from "@vc-shell/framework"; + +const unreadCount = ref(5); + +function openNotifications() { + // open notifications blade +} +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ------------ | ------------------ | ------- | ----------------------------------------------------------------- | +| `icon` | `string` | -- | Icon name (Lucide format, e.g., `"lucide-save"`) | +| `title` | `string` | -- | Label text below (or beside) the icon | +| `value` | `string \| number` | -- | Badge count displayed on the icon; numbers above 99 show as "99+" | +| `disabled` | `boolean` | `false` | Prevents clicks and applies muted styling | +| `isExpanded` | `boolean` | `false` | Expanded visual state | +| `horizontal` | `boolean` | `false` | Arranges icon and title side by side instead of stacked | + +## Events + +| Event | Payload | Description | +| ------- | ------- | ------------------------------------------------------------- | +| `click` | none | Fired when the widget is clicked (suppressed when `disabled`) | + +<div class="vc-storybook-embed" style="--height: 350px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=data-display-vcwidget--sidebar-layout&viewMode=story" + loading="lazy" + title="data-display-vcwidget--sidebar-layout" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/data-display-vcwidget--sidebar-layout" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Common Patterns + +### Sidebar Widget Panel + +```vue +<template> + <div class="tw-flex tw-flex-col tw-gap-2"> + <VcWidget + v-for="widget in widgets" + :key="widget.id" + :icon="widget.icon" + :title="widget.title" + :value="widget.count" + @click="onWidgetClick(widget)" + /> + </div> +</template> +``` + +### Horizontal Layout + +Use `horizontal` for compact inline widget rows, such as blade header actions. + +```vue +<VcWidget icon="lucide-mail" title="Messages" :value="3" horizontal /> +``` + +### Large Badge Count Truncation + +Badge values above 99 are automatically displayed as "99+". + +```vue +<VcWidget icon="lucide-inbox" title="Inbox" :value="142" /> +<!-- Badge shows "99+" --> +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ---------------------------- | --------------------- | -------------------- | +| `--widget-bg-color` | `transparent` | Background color | +| `--widget-bg-hover-color` | `var(--neutrals-50)` | Background on hover | +| `--widget-icon-color` | `var(--neutrals-700)` | Icon color | +| `--widget-icon-hover-color` | `var(--primary-600)` | Icon color on hover | +| `--widget-title-color` | `var(--neutrals-600)` | Title text color | +| `--widget-title-hover-color` | `var(--primary-600)` | Title color on hover | +| `--widget-border-radius` | `8px` | Corner radius | +| `--widget-focus-ring-color` | `var(--primary-300)` | Focus ring color | + +## Accessibility + +- Renders with `role="button"` and `tabindex="0"` for keyboard interaction +- Activates on Enter and Space key presses +- `aria-disabled` set when disabled; `tabindex="-1"` removes from tab order +- `aria-label` set to the `title` value +- Icon is marked `aria-hidden="true"` +- Focus-visible ring for keyboard navigation + +## Related Components + +- [VcBadge](./vc-badge.md) -- used internally for the count badge overlay +- [VcIcon](./vc-icon.md) -- used internally for the widget icon +- [VcButton](./vc-button.md) -- for standard action buttons + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/.pages new file mode 100644 index 0000000000..facaf7916e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/.pages @@ -0,0 +1,10 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Navigation +nav: + - VcBreadcrumbs: vc-breadcrumbs.md + - VcDropdown: vc-dropdown.md + - VcDropdownPanel: vc-dropdown-panel.md + - VcLink: vc-link.md + - VcMenu: vc-menu.md + - VcPagination: vc-pagination.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-breadcrumbs.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-breadcrumbs.md new file mode 100644 index 0000000000..05d50e4153 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-breadcrumbs.md @@ -0,0 +1,314 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Quick reference" +Jump to [Props](#props) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility) + +# VcBreadcrumbs + +Navigation breadcrumb trail that displays the user's location within a hierarchy and adaptively collapses middle items into a dropdown when horizontal space is limited. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcbreadcrumbs--default&viewMode=story" + loading="lazy" + title="navigation-vcbreadcrumbs--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcbreadcrumbs--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Showing the user's current position in a blade navigation hierarchy +- Providing quick navigation back to parent views or previously visited pages +- Displaying a multi-level path in a constrained header area + +**Alternatives:** + +- For tab-style navigation between sibling views, use a tab bar or menu instead +- For a simple "back" action without a full trail, use a single back button + +## Quick Start + +```vue +<template> + <VcBreadcrumbs :items="breadcrumbItems" /> +</template> + +<script setup lang="ts"> +import { VcBreadcrumbs } from "@vc-shell/framework"; + +const breadcrumbItems = [ + { id: "home", title: "Home", icon: "lucide-house" }, + { id: "products", title: "Products" }, + { id: "detail", title: "Wireless Headphones" }, +]; +</script> +``` + +## Breadcrumb Item Interface + +Every item in the `items` array must conform to the `Breadcrumbs` interface: + +```ts +interface Breadcrumbs { + id: string; + title: MaybeRef<string | undefined>; + icon?: string; + clickHandler?: (id: string) => void | boolean | Promise<void | boolean>; +} +``` + +- `id` -- Unique identifier for deduplication and click callbacks. +- `title` -- Display text. Accepts a plain string or a Vue `Ref<string>` for reactive labels. +- `icon` -- Optional Lucide icon name shown before the title (e.g., `"lucide-house"`). +- `clickHandler` -- Called when the user clicks the item. Return `true` (or void) to trim the trail to this point; return `false` to keep the trail unchanged. + +## Adaptive Overflow + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcbreadcrumbs--many-items&viewMode=story" + loading="lazy" + title="navigation-vcbreadcrumbs--many-items" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcbreadcrumbs--many-items" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +VcBreadcrumbs monitors the container width with `useAdaptiveItems` and automatically collapses middle items into a dropdown when they do not fit. The first and last items stay visible; overflow items appear behind a "more" button (vertical ellipsis). + +The collapse algorithm uses a reverse strategy -- it hides items starting from the left (after the first) so the current page (last item) always remains visible. + +```vue +<!-- In a narrow container, middle items collapse automatically --> +<div style="max-width: 400px;"> + <VcBreadcrumbs :items="deepHierarchy" separated /> +</div> +``` + +## Separated Style + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcbreadcrumbs--separated&viewMode=story" + loading="lazy" + title="navigation-vcbreadcrumbs--separated" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcbreadcrumbs--separated" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Enable slash separators between items with the `separated` prop: + +```vue +<VcBreadcrumbs :items="items" separated /> +<!-- Renders: Home / Products / Electronics --> +``` + +When `separated` is `false` (default), items are spaced with a gap but have no visible separator character. + +## Collapsed Mode + +Force all items into the dropdown by setting `collapsed` to `true`. This is useful when the breadcrumb area must be minimized but remain accessible: + +```vue +<VcBreadcrumbs :items="items" collapsed /> +<!-- Only the dropdown trigger is visible; click to see all items --> +``` + +## Light Variant + +Use the `"light"` variant for a subtler visual weight, for example inside a secondary toolbar: + +```vue +<VcBreadcrumbs :items="items" variant="light" /> +``` + +## Click Handlers for Navigation + +Attach a `clickHandler` to each item to navigate when the user clicks: + +```vue +<script setup lang="ts"> +const items = [ + { + id: "home", + title: "Home", + icon: "lucide-house", + clickHandler: () => router.push("/"), + }, + { + id: "products", + title: "Products", + clickHandler: () => router.push("/products"), + }, + { + id: "detail", + title: "Wireless Headphones", + // No clickHandler on the current page + }, +]; +</script> +``` + +## Using the useBreadcrumbs Composable + +For applications built on the VC-Shell framework, manage breadcrumb state reactively with `useBreadcrumbs()`: + +```vue +<template> + <VcBreadcrumbs + :items="breadcrumbs" + separated + /> +</template> + +<script setup lang="ts"> +import { useBreadcrumbs } from "@vc-shell/framework"; + +const { breadcrumbs, push, remove } = useBreadcrumbs(); + +// Add a breadcrumb as the user navigates deeper +push({ + id: "products", + title: "Products", + clickHandler: (id) => { + router.push("/products"); + return true; // Returning true trims the trail to this item + }, +}); + +// Programmatically remove specific breadcrumbs +remove(["products", "categories"]); +</script> +``` + +**Composable API:** + +| Method | Signature | Description | +| ------------- | ----------------------------- | ---------------------------------- | +| `breadcrumbs` | `ComputedRef<Breadcrumbs[]>` | Reactive array of current items | +| `push` | `(item: Breadcrumbs) => void` | Add an item (deduplicates by `id`) | +| `remove` | `(ids: string[]) => void` | Remove items by their IDs | + +> **Note:** When `push` is called with an `id` that already exists, the existing entry is updated in place rather than duplicated. + +## Custom Trigger Button + +Replace the default overflow button with any element using the `trigger` slot: + +```vue +<VcBreadcrumbs :items="items"> + <template #trigger="{ click, isActive }"> + <VcButton text @click="click"> + {{ isActive ? 'Close' : 'More pages' }} + </VcButton> + </template> +</VcBreadcrumbs> +``` + +## Recipe: Blade Navigation Breadcrumbs + +In a typical VC-Shell blade hierarchy, push a breadcrumb each time a child blade opens and rely on the click handler to navigate back: + +```vue +<script setup lang="ts"> +import { useBreadcrumbs, useBladeContext } from "@vc-shell/framework"; + +const { breadcrumbs, push } = useBreadcrumbs(); +const { openBlade, closeSelf } = useBladeContext(); + +function openProductDetail(product: Product) { + push({ + id: "product-detail", + title: product.name, + clickHandler: () => { + closeSelf(); + return true; + }, + }); + openBlade({ component: ProductDetailBlade, props: { product } }); +} +</script> +``` + +## Common Mistakes + +**Forgetting a unique `id` on each item** + +``` +// Wrong -- duplicate IDs cause the composable to overwrite entries +push({ id: "page", title: "Products" }); +push({ id: "page", title: "Electronics" }); // Overwrites "Products" +``` + +``` +// Correct -- use unique IDs +push({ id: "products", title: "Products" }); +push({ id: "electronics", title: "Electronics" }); +``` + +**Returning `false` from clickHandler and expecting the trail to shorten** + +``` +// Wrong -- returning false keeps the trail unchanged +clickHandler: () => { navigate(); return false; } +``` + +``` +// Correct -- return true (or void) to trim the trail +clickHandler: () => { navigate(); return true; } +``` + +**Using a reactive title without MaybeRef** + +``` +// Wrong -- loses reactivity +{ id: "x", title: someRef.value } +``` + +``` +// Correct -- pass the ref directly +{ id: "x", title: someRef } +``` + +## Props + +| Prop | Type | Default | Description | +| ----------- | ---------------------- | ----------- | ------------------------------------ | +| `items` | `Breadcrumbs[]` | `[]` | Array of breadcrumb items to display | +| `variant` | `"default" \| "light"` | `"default"` | Visual style variant | +| `separated` | `boolean` | `false` | Show `/` separators between items | +| `collapsed` | `boolean` | `false` | Force all items into the dropdown | + +## Slots + +| Slot | Scope | Description | +| --------- | ------------------------------------------ | ------------------------------------------------------------------ | +| `trigger` | `{ click: () => void, isActive: boolean }` | Custom dropdown trigger button replacing the default ellipsis icon | + +## CSS Variables + +| Variable | Default | Description | +| ----------------------------------------- | ---------------------- | ------------------------------------ | +| `--separator-color` | `var(--neutrals-400)` | Color of the `/` separator character | +| `--breadcrumbs-item-border-color` | `var(--secondary-300)` | Border color of breadcrumb items | +| `--breadcrumbs-expand-button-color` | `var(--neutrals-500)` | Color of the overflow "more" button | +| `--breadcrumbs-expand-button-color-hover` | `var(--neutrals-600)` | Hover color of the overflow button | + +## Accessibility + +- The component renders inside a `<nav>` element with `aria-label="Breadcrumb"`. +- Items are structured as an `<ol>` list for semantic ordering. +- The last visible item carries `aria-current="page"` to indicate the current location. +- Separator characters are marked `aria-hidden="true"` so screen readers skip them. +- When items overflow, the dropdown is accessible via the trigger button with standard keyboard interaction (Enter/Space to open). + +## Related Components + +- [VcDropdown](./vc-dropdown.md) -- Used internally to render the overflow menu +- [VcBreadcrumbsItem](./_internal/vc-breadcrumbs-item/) -- Internal sub-component for individual breadcrumb rendering +- [VcButton](../misc/vc-button.md) -- Can be used inside the `trigger` slot for a styled overflow button + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown-panel.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown-panel.md new file mode 100644 index 0000000000..2155b253d8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown-panel.md @@ -0,0 +1,169 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcDropdownPanel + +Floating dropdown panel positioned relative to an anchor element, with header, scrollable content, and optional footer. Built on `@floating-ui/vue`. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcdropdownpanel--default&viewMode=story" + loading="lazy" + title="overlay-vcdropdownpanel--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcdropdownpanel--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Rich dropdown content with a title bar and action buttons (e.g., filter panels, settings popovers) +- Panels that need header/footer structure alongside scrollable body content +- Nested panel scenarios where panels can spawn sub-panels +- When NOT to use: for simple item lists, prefer `VcDropdown`; for full-page overlays, use a dialog/modal + +## Basic Usage + +```vue +<template> + <button + ref="anchorEl" + @click="open = !open" + > + Toggle Panel + </button> + <VcDropdownPanel + v-model:show="open" + :anchor-ref="anchorEl" + title="Filter Options" + > + <div class="tw-p-4"> + <p>Panel content here</p> + </div> + </VcDropdownPanel> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; +import { VcDropdownPanel } from "@vc-shell/framework"; + +const anchorEl = ref<HTMLElement | null>(null); +const open = ref(false); +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| --------------------- | --------------------- | ---------------- | ------------------------------------------------------------------ | +| `show` | `boolean` | — | Panel visibility (v-model:show) | +| `anchorRef` | `HTMLElement \| null` | `null` | Anchor element for floating positioning | +| `title` | `string` | `""` | Header title text (header hidden when empty and no `#header` slot) | +| `placement` | `Placement` | `"bottom-start"` | Floating UI placement relative to anchor | +| `width` | `string` | `"280px"` | Panel min-width | +| `maxWidth` | `string` | `"400px"` | Panel max-width | +| `maxHeight` | `number` | `350` | Max height in pixels (clamped by viewport) | +| `contentScrollable` | `boolean` | `true` | Enable scrolling in the content area | +| `closeOnClickOutside` | `boolean` | `true` | Close when clicking outside | +| `closeOnEscape` | `boolean` | `true` | Close on Escape key | + +## Events + +| Event | Payload | Description | +| ------------- | --------- | ------------------------ | +| `update:show` | `boolean` | Panel visibility changed | + +## Slots + +| Slot | Props | Description | +| --------- | ----------- | ----------------------------------------------------- | +| `default` | — | Scrollable content area | +| `header` | `{ close }` | Custom header (replaces default title + close button) | +| `footer` | — | Footer area, typically for action buttons | + +## Common Patterns + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcdropdownpanel--with-footer&viewMode=story" + loading="lazy" + title="overlay-vcdropdownpanel--with-footer" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcdropdownpanel--with-footer" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +### Filter Panel with Footer Actions + +```vue +<VcDropdownPanel v-model:show="showFilters" :anchor-ref="filterButton" title="Filters"> + <div class="tw-p-4 tw-flex tw-flex-col tw-gap-2"> + <VcCheckbox v-model="filters.active">Active only</VcCheckbox> + <VcCheckbox v-model="filters.inStock">In stock</VcCheckbox> + <VcSelect v-model="filters.category" :options="categories" label="Category" /> + </div> + <template #footer> + <VcButton variant="secondary" @click="resetFilters">Reset</VcButton> + <VcButton @click="applyFilters">Apply</VcButton> + </template> +</VcDropdownPanel> +``` + +### Custom Header + +```vue +<VcDropdownPanel v-model:show="open" :anchor-ref="anchor"> + <template #header="{ close }"> + <div class="tw-flex tw-items-center tw-justify-between tw-w-full tw-px-4 tw-py-3"> + <span class="tw-font-semibold">Custom Header</span> + <button @click="close">Dismiss</button> + </div> + </template> + <div class="tw-p-4">Content here</div> +</VcDropdownPanel> +``` + +### Scrollable List + +```vue +<VcDropdownPanel v-model:show="open" :anchor-ref="anchor" title="Long Content" :max-height="250"> + <div class="tw-py-1"> + <div + v-for="item in items" + :key="item.id" + class="tw-px-4 tw-py-2 tw-text-sm tw-cursor-pointer hover:tw-bg-[var(--neutrals-100)]" + > + {{ item.name }} + </div> + </div> +</VcDropdownPanel> +``` + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------------ | ----------------------------- | ------------------------ | +| `--dropdown-panel-bg` | `var(--additional-50)` | Panel background | +| `--dropdown-panel-border-color` | `var(--neutrals-200)` | Border color | +| `--dropdown-panel-border-radius` | `6px` | Corner radius | +| `--dropdown-panel-shadow` | `0 4px 16px rgba(0,0,0,0.08)` | Box shadow | +| `--dropdown-panel-z-index` | `10001` | Z-index | +| `--dropdown-panel-title-color` | `var(--neutrals-900)` | Title text color | +| `--dropdown-panel-close-color` | `var(--neutrals-400)` | Close button color | +| `--dropdown-panel-close-hover-color` | `var(--neutrals-600)` | Close button hover color | +| `--dropdown-panel-footer-bg` | `var(--neutrals-50)` | Footer background | + +## Accessibility + +- Close button has `aria-label="Close"` +- Escape key dismisses the panel (configurable via `closeOnEscape`) +- Click-outside detection uses `pointerdown` for reliable z-index handling +- Supports nested panels via an internal anchor registry -- child panel clicks do not close parent panels +- Exposes `close()` method via template ref + +## Related Components + +- [VcDropdown](./vc-dropdown.md) — headless dropdown for simple item lists +- [VcSelect](../form/vc-select.md) — form field selection dropdown + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown.md new file mode 100644 index 0000000000..bc6812d04b --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-dropdown.md @@ -0,0 +1,399 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/molecules/vc-dropdown/vc-dropdown.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Quick reference" +Jump to [Props](#props) · [Events](#events) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility) + +# VcDropdown + +A headless, accessible dropdown primitive for building menus and listboxes. Provides floating positioning via `@floating-ui`, full keyboard navigation, slot-based rendering, and configurable close behavior. This is a low-level building block -- for form field selection, use VcSelect instead. + +## When to Use + +- Contextual action menus ("more actions" button, right-click style menus) +- Compact option pickers and workspace/context switchers +- Any trigger + floating list pattern with custom item rendering +- Notification panels or custom popovers with item lists + +When NOT to use: + +- For form field selection -- use [VcSelect](../form/vc-select.md) +- For rich panel content with header/footer/scrollable body -- use [VcDropdownPanel](./vc-dropdown-panel.md) +- For navigation menus -- use [VcMenu](./vc-menu.md) + +## Quick Start + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcdropdown--action-menu&viewMode=story" + loading="lazy" + title="overlay-vcdropdown--action-menu" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcdropdown--action-menu" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +```vue +<template> + <VcDropdown + v-model="isOpen" + :items="actions" + floating + close-on-select + @item-click="onAction" + > + <template #trigger="{ toggle }"> + <VcButton @click="toggle">Actions</VcButton> + </template> + <template #item="{ item, click }"> + <button + class="tw-w-full tw-text-left tw-px-3 tw-py-2" + @click="click" + > + {{ item.title }} + </button> + </template> + </VcDropdown> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; +import { VcDropdown, VcButton } from "@vc-shell/framework"; + +const isOpen = ref(false); +const actions = [ + { id: "edit", title: "Edit" }, + { id: "duplicate", title: "Duplicate" }, + { id: "delete", title: "Delete" }, +]; + +function onAction(item: { id: string; title: string }) { + console.log("Selected:", item.id); +} +</script> +``` + +## Features + +### Floating Positioning + +When `floating` is `true`, the dropdown panel is positioned using `@floating-ui` with automatic flip and shift middleware. The panel is teleported to the body to avoid z-index stacking context issues. + +```vue +<VcDropdown v-model="open" :items="items" floating placement="bottom-start" :offset="{ mainAxis: 4 }" :z-index="10000"> + <template #trigger="{ toggle }"> + <VcButton @click="toggle">Open</VcButton> + </template> + <template #item="{ item, click }"> + <button @click="click">{{ item.title }}</button> + </template> +</VcDropdown> +``` + +Available `placement` values follow Floating UI conventions: `"top"`, `"top-start"`, `"top-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"`, `"left"`, `"right"`, and their start/end variants. + +### Action Menu with Icons and Shortcuts + +Build rich action menus by customizing the `#item` slot with icons, labels, and keyboard shortcut hints. + +```vue +<VcDropdown v-model="open" :items="actions" floating placement="bottom-start" close-on-select @item-click="handleAction"> + <template #trigger="{ toggle }"> + <VcButton icon="lucide-ellipsis" @click="toggle" /> + </template> + <template #item="{ item, click }"> + <button class="tw-flex tw-items-center tw-gap-2 tw-px-2 tw-py-1.5 tw-w-full" @click="click"> + <VcIcon :icon="item.icon" size="s" /> + <span class="tw-flex-1">{{ item.title }}</span> + <kbd class="tw-ml-auto tw-text-xs tw-text-[color:var(--neutrals-400)]">{{ item.shortcut }}</kbd> + </button> + </template> +</VcDropdown> +``` + +### Listbox Mode (Selection Switcher) + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=overlay-vcdropdown--workspace-switcher&viewMode=story" + loading="lazy" + title="overlay-vcdropdown--workspace-switcher" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/overlay-vcdropdown--workspace-switcher" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +Use `role="listbox"` for option-selection patterns. Combine with `isItemActive` to highlight the current selection and `aria-selected` is set automatically. + +```vue +<VcDropdown v-model="open" :items="workspaces" role="listbox" :is-item-active="(item) => item.id === activeId" close-on-select floating @item-click="(item) => (activeId = item.id)"> + <template #trigger="{ toggle }"> + <VcButton variant="outline" @click="toggle">{{ currentWorkspace }}</VcButton> + </template> + <template #item="{ item, click }"> + <button class="tw-flex tw-items-center tw-justify-between tw-w-full tw-px-2 tw-py-1.5" @click="click"> + {{ item.title }} + <VcIcon v-if="item.id === activeId" icon="lucide-check" size="s" /> + </button> + </template> +</VcDropdown> +``` + +### Close Behavior Control + +Fine-tune when the dropdown closes: + +```vue +<VcDropdown v-model="open" :items="items" floating :close-on-click-outside="true" :close-on-escape="true" :close-on-select="false"> + <!-- Multi-select pattern: dropdown stays open after each selection --> +</VcDropdown> +``` + +The `close` event payload tells you the reason: `"outside"` (clicked away), `"escape"` (pressed Escape), or `"action"` (programmatic close or item selected with `closeOnSelect`). + +### Custom Items Container + +For full control over the list rendering (e.g., grouped items, sections with dividers), use the `#items-container` slot. + +```vue +<VcDropdown v-model="open" :items="allItems" floating> + <template #trigger="{ toggle }"> + <VcButton @click="toggle">Grouped Menu</VcButton> + </template> + <template #items-container="{ items, close }"> + <div class="tw-py-1"> + <div class="tw-px-3 tw-py-1 tw-text-xs tw-font-semibold tw-text-[color:var(--neutrals-400)]">Actions</div> + <button + v-for="item in items.filter(i => i.group === 'actions')" + :key="item.id" + class="tw-block tw-w-full tw-text-left tw-px-3 tw-py-1.5" + @click="() => { handleAction(item); close(); }" + > + {{ item.title }} + </button> + <div class="tw-border-t tw-border-[color:var(--neutrals-200)] tw-my-1" /> + <div class="tw-px-3 tw-py-1 tw-text-xs tw-font-semibold tw-text-[color:var(--neutrals-400)]">Danger</div> + <button + v-for="item in items.filter(i => i.group === 'danger')" + :key="item.id" + class="tw-block tw-w-full tw-text-left tw-px-3 tw-py-1.5 tw-text-[color:var(--danger-500)]" + @click="() => { handleAction(item); close(); }" + > + {{ item.title }} + </button> + </div> + </template> +</VcDropdown> +``` + +### Non-padded Mode for Rich Content + +By default, `padded` is `true`, which adds compact padding and rounded item backgrounds suitable for menus. Set `padded` to `false` for rich content where items should span the full panel width (e.g., notification lists). + +```vue +<VcDropdown v-model="open" :items="notifications" floating :padded="false" :max-height="400"> + <template #item="{ item, click }"> + <div class="tw-px-4 tw-py-3 tw-border-b tw-border-[color:var(--neutrals-100)]" @click="click"> + <div class="tw-font-medium">{{ item.title }}</div> + <div class="tw-text-sm tw-text-[color:var(--neutrals-500)]">{{ item.description }}</div> + </div> + </template> +</VcDropdown> +``` + +## Recipes + +### Confirmation Dropdown + +```vue +<template> + <VcDropdown + v-model="confirmOpen" + floating + placement="bottom-end" + :close-on-select="false" + > + <template #trigger="{ toggle }"> + <VcButton + variant="danger" + @click="toggle" + >Delete</VcButton + > + </template> + <template #items-container="{ close }"> + <div class="tw-p-4 tw-w-64"> + <p class="tw-text-sm tw-mb-3">Are you sure you want to delete this item?</p> + <div class="tw-flex tw-gap-2 tw-justify-end"> + <VcButton + size="s" + variant="outline" + @click="close" + >Cancel</VcButton + > + <VcButton + size="s" + variant="danger" + @click=" + () => { + confirmDelete(); + close(); + } + " + >Delete</VcButton + > + </div> + </div> + </template> + </VcDropdown> +</template> +``` + +### Programmatic Open/Close + +```vue +<template> + <VcDropdown + v-model="isOpen" + :items="items" + floating + > + <template #trigger="{ open, close, isActive }"> + <VcButton + @mouseenter="open" + @mouseleave="close" + > + {{ isActive ? "Hover to close" : "Hover to open" }} + </VcButton> + </template> + <template #item="{ item, click }"> + <button @click="click">{{ item.title }}</button> + </template> + </VcDropdown> +</template> +``` + +## Common Mistakes + +### 1. Forgetting the `floating` prop + +```vue +<!-- WRONG: dropdown renders inline, no positioning --> +<VcDropdown v-model="open" :items="items"> + <template #trigger="{ toggle }"> + <VcButton @click="toggle">Menu</VcButton> + </template> +</VcDropdown> + +<!-- CORRECT: enable floating for proper overlay positioning --> +<VcDropdown v-model="open" :items="items" floating> + <template #trigger="{ toggle }"> + <VcButton @click="toggle">Menu</VcButton> + </template> +</VcDropdown> +``` + +### 2. Not calling click in the item slot + +```vue +<!-- WRONG: clicking the item does nothing, no events emitted --> +<template #item="{ item }"> + <button>{{ item.title }}</button> +</template> + +<!-- CORRECT: call the provided click handler --> +<template #item="{ item, click }"> + <button @click="click">{{ item.title }}</button> +</template> +``` + +### 3. Using VcDropdown for form field selection + +```vue +<!-- WRONG: VcDropdown is a headless primitive, not a form control --> +<VcDropdown v-model="open" :items="options" floating> + <!-- No label, no validation, no v-model for selected value --> +</VcDropdown> + +<!-- CORRECT: use VcSelect for form field selection --> +<VcSelect v-model="selectedValue" :options="options" label="Choose option" /> +``` + +## Props + +| Prop | Type | Default | Description | +| --------------------- | ---------------------------------------------- | ------------------------------- | ------------------------------------------------------ | +| `modelValue` | `boolean` | `false` | Controls open/closed state via `v-model` | +| `items` | `T[]` | `[]` | Items to render in the dropdown | +| `emptyText` | `string` | `""` | Text shown when items array is empty | +| `itemText` | `(item: T) => string` | -- | Maps an item to display text (default renderer only) | +| `isItemActive` | `(item: T) => boolean` | -- | Marks the currently active item (highlighted state) | +| `itemKey` | `(item: T, index: number) => string \| number` | index | Unique key function for items | +| `floating` | `boolean` | `false` | Enable floating positioning via `@floating-ui` | +| `teleport` | `boolean` | -- | Force teleport to body (defaults to match `floating`) | +| `teleportTo` | `string \| HTMLElement` | -- | Custom teleport target | +| `placement` | `Placement` | `"bottom"` | Floating UI placement | +| `offset` | `{ mainAxis?: number; crossAxis?: number }` | `{ mainAxis: 0, crossAxis: 0 }` | Offset from the trigger element | +| `variant` | `"default" \| "secondary"` | `"default"` | Visual style variant | +| `maxHeight` | `number \| string` | `300` | Maximum panel height (number = px, string = CSS value) | +| `role` | `"menu" \| "listbox"` | `"menu"` | ARIA role for the dropdown panel | +| `closeOnClickOutside` | `boolean` | `true` | Close when clicking outside the dropdown | +| `closeOnEscape` | `boolean` | `true` | Close on Escape key press | +| `closeOnSelect` | `boolean` | `false` | Close after selecting an item | +| `autoFocusPanel` | `boolean` | `true` | Focus the panel element when opened | +| `padded` | `boolean` | `true` | Apply compact padding and rounded item backgrounds | +| `zIndex` | `number` | `10000` | Z-index for the floating panel | + +## Events + +| Event | Payload | Description | +| ------------------- | ----------------------------------- | --------------------------- | +| `update:modelValue` | `boolean` | Open/close state changed | +| `item-click` | `T` | An item was selected | +| `open` | -- | Dropdown opened | +| `close` | `"outside" \| "escape" \| "action"` | Dropdown closed with reason | + +## Slots + +| Slot | Props | Description | +| ----------------- | -------------------------------------------------------------------------------- | --------------------------------- | +| `trigger` | `{ isActive: boolean, toggle: () => void, open: () => void, close: () => void }` | Custom trigger element | +| `item` | `{ item: T, click: () => void }` | Custom item rendering | +| `empty` | -- | Content when items array is empty | +| `items-container` | `{ items: T[], close: () => void }` | Full control over the items list | + +## CSS Variables + +| Variable | Default | Description | +| ----------------------------------------- | ---------------------- | ---------------------------- | +| `--vc-dropdown-bg` | `var(--additional-50)` | Panel background color | +| `--vc-dropdown-text` | `var(--neutrals-950)` | Default text color | +| `--vc-dropdown-border` | `var(--neutrals-200)` | Floating panel border color | +| `--vc-dropdown-accent` | `var(--neutrals-100)` | Hover/focus background color | +| `--vc-dropdown-accent-foreground` | `var(--neutrals-900)` | Hover/focus text color | +| `--vc-dropdown-divider` | `var(--neutrals-200)` | Mobile item divider color | +| `--vc-dropdown-trigger-focus-ring-width` | `2px` | Trigger focus ring width | +| `--vc-dropdown-trigger-focus-ring-offset` | `1px` | Trigger focus ring offset | +| `--vc-dropdown-trigger-focus-ring-color` | `var(--primary-300)` | Trigger focus ring color | + +## Accessibility + +- **Trigger element**: has `role="button"`, `tabindex="0"`, `aria-expanded`, and `aria-haspopup` set to the dropdown role +- **Panel**: uses the specified `role` attribute (`"menu"` or `"listbox"`) +- **Items**: use `role="menuitem"` (menu mode) or `role="option"` (listbox mode) +- **Active item tracking**: `aria-activedescendant` on the panel tracks the currently focused item +- **Listbox selection**: `aria-selected` is set on items when `role="listbox"` and `isItemActive` returns `true` +- **Keyboard navigation**: + - **Arrow Down / Arrow Up** -- move focus between items (wraps around) + - **Home / End** -- jump to first/last item + - **Enter / Space** -- select the focused item + - **Escape** -- close the dropdown (when `closeOnEscape` is `true`) +- **Focus management**: panel auto-focuses on open (`autoFocusPanel`); focus index syncs to active item +- **Transition**: enter/leave animations are placement-aware (top placements slide downward) + +## Related Components + +- [VcDropdownPanel](./vc-dropdown-panel.md) -- floating panel with header, footer, and scrollable content +- [VcSelect](../form/vc-select.md) -- form field dropdown for selecting values with label and validation +- [VcMenu](./vc-menu.md) -- sidebar navigation menu + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-link.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-link.md new file mode 100644 index 0000000000..19b5806277 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-link.md @@ -0,0 +1,165 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/atoms/vc-link/vc-link.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcLink + +A clickable inline link element styled as a button, used for navigation or triggering actions within text or toolbars. Despite its link-like appearance, VcLink renders as a native `<button>` element, which provides correct keyboard behavior and avoids the need for an `href` attribute when the action is handled in JavaScript. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vclink--default&viewMode=story" + loading="lazy" + title="action-vclink--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vclink--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Trigger navigation or actions inline with other content +- Build tab-like or breadcrumb-style navigation bars +- Secondary actions in toolbars or table cells +- When NOT to use: for primary call-to-action buttons (use [VcButton](../misc/vc-button.md) instead); for real URL navigation with `href` (use a plain `<a>` tag or router-link) + +## Basic Usage + +```vue +<template> + <VcLink @click="openDetails">View details</VcLink> +</template> + +<script setup lang="ts"> +import { VcLink } from "@vc-shell/framework"; + +function openDetails() { + // handle navigation +} +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ---------- | --------- | ------- | ---------------------------------------------- | +| `active` | `boolean` | `false` | Highlights the link as currently selected | +| `disabled` | `boolean` | `false` | Prevents interaction and applies muted styling | + +## Events + +| Event | Payload | Description | +| ------- | ------- | ----------------------------------------------------------- | +| `click` | none | Fired when the link is clicked (suppressed when `disabled`) | + +<div class="vc-storybook-embed" style="--height: 250px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=action-vclink--navigation-example&viewMode=story" + loading="lazy" + title="action-vclink--navigation-example" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/action-vclink--navigation-example" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## Common Patterns + +### Navigation Bar + +```vue +<template> + <div class="tw-flex tw-gap-4"> + <VcLink + :active="currentTab === 'home'" + @click="currentTab = 'home'" + >Home</VcLink + > + <VcLink + :active="currentTab === 'products'" + @click="currentTab = 'products'" + >Products</VcLink + > + <VcLink disabled>Admin</VcLink> + </div> +</template> +``` + +### Inline Action in a Table Cell + +```vue +<VcColumn id="actions" header="Actions" :width="120"> + <template #default="{ row }"> + <div class="tw-flex tw-gap-3"> + <VcLink @click="editItem(row)">Edit</VcLink> + <VcLink @click="duplicateItem(row)">Copy</VcLink> + </div> + </template> +</VcColumn> +``` + +### Breadcrumb Trail + +```vue +<template> + <nav class="tw-flex tw-items-center tw-gap-1 tw-text-sm"> + <VcLink @click="goTo('catalog')">Catalog</VcLink> + <span class="tw-text-gray-400">/</span> + <VcLink @click="goTo('category')">Electronics</VcLink> + <span class="tw-text-gray-400">/</span> + <span class="tw-font-medium">Laptop Model X</span> + </nav> +</template> +``` + +## Recipe: Toggle Active Link from a List + +```vue +<script setup lang="ts"> +import { ref } from "vue"; + +const tabs = ["Overview", "Pricing", "SEO", "Properties"]; +const activeTab = ref("Overview"); +</script> + +<template> + <div class="tw-flex tw-gap-4 tw-border-b tw-pb-2"> + <VcLink + v-for="tab in tabs" + :key="tab" + :active="activeTab === tab" + @click="activeTab = tab" + > + {{ tab }} + </VcLink> + </div> +</template> +``` + +## CSS Custom Properties + +| Variable | Default | Description | +| ---------------------------- | --------------------- | -------------------------- | +| `--link-text-color` | `var(--primary-500)` | Default text color | +| `--link-text-color-hover` | `var(--primary-400)` | Text color on hover | +| `--link-text-color-active` | `var(--primary-700)` | Text color in active state | +| `--link-text-color-disabled` | `var(--neutrals-300)` | Text color when disabled | +| `--link-focus-ring-color` | `primary-500 at 30%` | Focus ring color | + +## Tips + +- VcLink resets all default button styles (`background`, `border`, `padding`) so it looks like a text link. If you need a visible button shape, use VcButton instead. +- The `active` state applies a darker color and removes the hover underline, making it suitable for indicating the currently selected item in a tab bar. +- Disabled links show `cursor: not-allowed` and reduced opacity. The `click` event is never emitted when disabled. +- Combine with Tailwind utility classes for font size or weight: `<VcLink class="tw-text-xs tw-font-semibold">`. + +## Accessibility + +- Renders as a native `<button>` element for keyboard operability +- `disabled` prop sets both the HTML `disabled` attribute and `aria-disabled` +- Focus-visible ring for keyboard navigation +- Underlines on hover for visual affordance + +## Related Components + +- [VcButton](../misc/vc-button.md) -- for primary actions and form submissions + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-menu.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-menu.md new file mode 100644 index 0000000000..731902a479 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-menu.md @@ -0,0 +1,149 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/molecules/vc-menu/vc-menu.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcMenu + +Compositional navigation menu component for building sidebar navigation with sections, groups, nested items, badges, and loading skeletons. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcmenu--default&viewMode=story" + loading="lazy" + title="navigation-vcmenu--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcmenu--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Building the main navigation sidebar in admin applications +- Multi-level navigation with collapsible groups and sections +- When the sidebar needs expanded (full) and collapsed (icon-only) states +- When NOT to use: for contextual dropdown menus, use `VcDropdown` instead + +## Basic Usage + +```vue +<template> + <VcMenu :expanded="sidebarExpanded"> + <VcMenuItem + icon="lucide-home" + title="Dashboard" + :active="currentRoute === '/dashboard'" + @click="navigate('/dashboard')" + /> + <VcMenuGroup + group-id="catalog" + icon="lucide-box" + title="Catalog" + > + <VcMenuItem + title="Products" + nested + @click="navigate('/products')" + /> + <VcMenuItem + title="Categories" + nested + @click="navigate('/categories')" + /> + </VcMenuGroup> + <VcMenuItem + icon="lucide-settings" + title="Settings" + @click="navigate('/settings')" + /> + </VcMenu> +</template> + +<script setup lang="ts"> +import { VcMenu, VcMenuItem, VcMenuGroup } from "@vc-shell/framework"; +</script> +``` + +## Key Props + +| Prop | Type | Default | Description | +| ---------- | --------- | ------- | --------------------------------------------------------- | +| `expanded` | `boolean` | `true` | Show full menu (titles visible) or collapsed (icons only) | +| `loading` | `boolean` | `false` | Show skeleton loading placeholders instead of content | + +## Slots + +| Slot | Description | +| --------- | ---------------------------------------- | +| `default` | Menu items (`VcMenuItem`, `VcMenuGroup`) | + +## Common Patterns + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcmenu--sections&viewMode=story" + loading="lazy" + title="navigation-vcmenu--sections" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcmenu--sections" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +### Section Groups with Nested Items + +```vue +<VcMenu :expanded="expanded" :loading="isLoading"> + <VcMenuGroup group-id="activity" title="Activity" variant="section"> + <VcMenuItem icon="lucide-file-text" title="New Orders" @click="navigate('/orders/new')" /> + <VcMenuItem icon="lucide-clock" title="Pending Reviews" @click="navigate('/reviews')" /> + </VcMenuGroup> + + <VcMenuGroup group-id="catalog" title="Catalog" variant="section"> + <VcMenuItem icon="lucide-box" title="Products" @click="navigate('/products')" /> + <VcMenuGroup group-id="orders" icon="lucide-file" title="Orders"> + <VcMenuItem title="Accepted" icon="lucide-check" nested @click="navigate('/accepted')" /> + <VcMenuItem title="Declined" icon="lucide-x" nested @click="navigate('/declined')" /> + </VcMenuGroup> + </VcMenuGroup> +</VcMenu> +``` + +### Items with Badges + +```vue +<VcMenuItem icon="lucide-shopping-cart" title="New Orders" :badge="{ content: 5, variant: 'primary' }" /> +<VcMenuItem icon="lucide-alert-triangle" title="Returns" :badge="{ content: 99, variant: 'danger' }" /> +<VcMenuItem icon="lucide-bell" title="Notifications" :badge="{ isDot: true, variant: 'warning' }" /> +``` + +### Collapsed State + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcmenu--collapsed&viewMode=story" + loading="lazy" + title="navigation-vcmenu--collapsed" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcmenu--collapsed" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +When `expanded` is `false`, the menu shows only icons and letter abbreviations. Groups show tooltips on hover. The container width should be reduced (e.g., 64px). + +## CSS Variables + +| Variable | Default | Description | +| --------------- | ------- | ---------------------- | +| `--vc-menu-gap` | `2px` | Gap between menu items | + +## Accessibility + +- Menu items are keyboard-focusable +- Groups expand/collapse with animated transitions +- Active state is explicit via the `active` prop on `VcMenuItem` +- Collapsed mode shows tooltips for discoverability + +## Related Components + +- [VcMenuItem](./vc-menu.md) — individual menu item with icon, title, badge +- [VcMenuGroup](./vc-menu.md) — collapsible group container (supports `variant="section"` for top-level sections) +- [VcDropdown](./vc-dropdown.md) — contextual dropdown menus + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-pagination.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-pagination.md new file mode 100644 index 0000000000..8142dda672 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/navigation/vc-pagination.md @@ -0,0 +1,320 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/molecules/vc-pagination/vc-pagination.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Quick reference" +Jump to [Props](#props) · [Events](#events) · [CSS Variables](#css-variables) · [Accessibility](#accessibility) + +# VcPagination + +Page navigation control with first/previous/next/last buttons and a sliding window of page numbers. Automatically adapts the number of visible page buttons for mobile viewports. + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcpagination--default&viewMode=story" + loading="lazy" + title="navigation-vcpagination--default" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcpagination--default" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +## When to Use + +- Navigating paginated data sets in tables, lists, or grids +- Any UI where content is split across discrete pages and the user must move between them +- Pairing with server-side pagination that uses `skip`/`take` parameters + +**Alternatives:** + +- For infinite scroll or "load more" patterns, handle loading programmatically without pagination controls +- For stepping through a wizard, use a stepper component instead + +## Quick Start + +```vue +<template> + <VcPagination + :pages="totalPages" + :current-page="currentPage" + @item-click="onPageChange" + /> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; +import { VcPagination } from "@vc-shell/framework"; + +const totalPages = 15; +const currentPage = ref(1); + +function onPageChange(page: number) { + currentPage.value = page; +} +</script> +``` + +## Sliding Page Window + +<div class="vc-storybook-embed" style="--height: 400px"> + <iframe + src="https://vc-shell-storybook.govirto.com/iframe.html?id=navigation-vcpagination--many-pages&viewMode=story" + loading="lazy" + title="navigation-vcpagination--many-pages" + ></iframe> + <a href="https://vc-shell-storybook.govirto.com/?path=/story/navigation-vcpagination--many-pages" target="_blank" rel="noopener">Open in Storybook ↗</a> +</div> + +VcPagination displays a sliding window of page number buttons centered on the current page. The window size adapts automatically: + +- **Desktop:** 5 visible page buttons (default) +- **Mobile:** 3 visible page buttons (default) + +The component detects the viewport via the injected `IsMobileKey`. You can override the window size with the `maxPages` prop regardless of viewport. + +```vue +<!-- Always show exactly 3 page buttons --> +<VcPagination :pages="100" :current-page="50" :max-pages="3" /> + +<!-- Always show 7 page buttons for a spacious layout --> +<VcPagination :pages="100" :current-page="50" :max-pages="7" /> +``` + +When the current page is near the beginning or end of the range, the window shifts to avoid going out of bounds while maintaining the configured button count. + +## First/Last Page Buttons + +By default, first-page and last-page buttons (double chevrons) are shown. Hide them for a more compact control: + +```vue +<VcPagination :pages="10" :current-page="5" :show-first-last="false" /> +<!-- Only shows: < [4] [5] [6] > --> +``` + +## Pairing with VcDataTable + +The most common use case is paginating a data table: + +```vue +<template> + <VcDataTable + :items="pagedItems" + :columns="columns" + /> + <VcPagination + :pages="Math.ceil(totalItems / pageSize)" + :current-page="currentPage" + @item-click="loadPage" + /> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; + +const pageSize = 20; +const totalItems = ref(0); +const currentPage = ref(1); +const pagedItems = ref([]); + +async function loadPage(page: number) { + currentPage.value = page; + const result = await fetchItems({ + skip: (page - 1) * pageSize, + take: pageSize, + }); + pagedItems.value = result.items; + totalItems.value = result.totalCount; +} + +// Load the first page on mount +loadPage(1); +</script> +``` + +## Controlled Component Pattern + +VcPagination maintains an internal `localCurrentPage` ref that syncs with the `currentPage` prop. This means you can control it from the parent while still getting smooth UI updates: + +```vue +<script setup lang="ts"> +const currentPage = ref(1); + +// You can programmatically change the page from outside +function goToFirstPage() { + currentPage.value = 1; +} + +function goToLastPage() { + currentPage.value = totalPages; +} +</script> +``` + +## Recipe: Pagination with Page Size Selector + +Combine VcPagination with a page-size dropdown for a complete pagination toolbar: + +```vue +<template> + <div class="tw-flex tw-items-center tw-justify-between tw-mt-4"> + <div class="tw-flex tw-items-center tw-gap-2"> + <span class="tw-text-sm">Rows per page:</span> + <VcSelect + v-model="pageSize" + :options="[10, 20, 50, 100]" + @update:model-value="onPageSizeChange" + /> + </div> + <VcPagination + :pages="totalPages" + :current-page="currentPage" + @item-click="loadPage" + /> + <span class="tw-text-sm tw-text-gray-500"> + {{ (currentPage - 1) * pageSize + 1 }} + - {{ Math.min(currentPage * pageSize, totalItems) }} of {{ totalItems }} + </span> + </div> +</template> + +<script setup lang="ts"> +import { ref, computed } from "vue"; + +const pageSize = ref(20); +const totalItems = ref(350); +const currentPage = ref(1); +const totalPages = computed(() => Math.ceil(totalItems.value / pageSize.value)); + +function onPageSizeChange() { + currentPage.value = 1; // Reset to first page when page size changes + loadPage(1); +} + +async function loadPage(page: number) { + currentPage.value = page; + // Fetch data with skip/take... +} +</script> +``` + +## Recipe: URL-Synced Pagination + +Keep the current page in the URL query string for shareable links: + +```vue +<script setup lang="ts"> +import { useRoute, useRouter } from "vue-router"; +import { computed } from "vue"; + +const route = useRoute(); +const router = useRouter(); + +const currentPage = computed(() => Number(route.query.page) || 1); + +function onPageChange(page: number) { + router.push({ query: { ...route.query, page: String(page) } }); + fetchItems(page); +} +</script> + +<template> + <VcPagination + :pages="totalPages" + :current-page="currentPage" + @item-click="onPageChange" + /> +</template> +``` + +## Common Mistakes + +**Passing `0` as the total pages count** + +``` +// Wrong -- results in no buttons rendered +<VcPagination :pages="0" :current-page="1" /> +``` + +``` +// Correct -- always ensure at least 1 page +<VcPagination :pages="Math.max(1, totalPages)" :current-page="1" /> +``` + +**Forgetting to update currentPage in the handler** + +``` +// Wrong -- UI does not move to the clicked page +function onPageChange(page: number) { + fetchItems(page); // forgot to update currentPage +} +``` + +``` +// Correct -- update the ref so the component highlights the new page +function onPageChange(page: number) { + currentPage.value = page; + fetchItems(page); +} +``` + +**Setting currentPage higher than total pages** + +``` +// Wrong -- can happen after filtering reduces the dataset +currentPage.value = 5; // but totalPages is now 3 +``` + +``` +// Correct -- clamp after data changes +currentPage.value = Math.min(currentPage.value, totalPages.value); +``` + +## Props + +| Prop | Type | Default | Description | +| --------------- | ------------------------ | ----------- | ---------------------------------------------------------------------- | +| `pages` | `number` | `1` | Total number of pages | +| `currentPage` | `number` | `1` | Currently active page (1-based) | +| `maxPages` | `number` | -- | Override visible page button count. Default: 3 on mobile, 5 on desktop | +| `showFirstLast` | `boolean` | `true` | Show first/last page navigation buttons | +| `variant` | `"default" \| "minimal"` | `"default"` | Visual style variant | + +## Events + +| Event | Payload | Description | +| ----------- | -------- | --------------------------------------------------------------------------- | +| `itemClick` | `number` | Emitted when any page button is clicked. Payload is the 1-based page number | + +## CSS Variables + +| Variable | Default | Description | +| --------------------------------------------- | ---------------------- | ---------------------------------------- | +| `--pagination-item-width` | `29px` | Width of each page button | +| `--pagination-item-height` | `29px` | Height of each page button | +| `--pagination-item-color` | `var(--neutrals-500)` | Default text color | +| `--pagination-item-color-hover` | `var(--primary-500)` | Hover text color | +| `--pagination-item-color-current` | `var(--additional-50)` | Current page text color | +| `--pagination-item-background-color` | `var(--additional-50)` | Default background | +| `--pagination-item-background-color-hover` | `var(--primary-100)` | Hover background | +| `--pagination-item-background-color-current` | `var(--primary-500)` | Current page background | +| `--pagination-item-color-disabled` | `var(--neutrals-400)` | Disabled button text color | +| `--pagination-item-background-color-disabled` | `var(--neutrals-100)` | Disabled button background | +| `--pagination-item-border-color` | `var(--secondary-100)` | Default border color | +| `--pagination-focus-ring-color` | `var(--primary-100)` | Focus ring color for keyboard navigation | + +## Accessibility + +- Wrapped in a `<nav>` element with `aria-label="Pagination"`. +- Each page button has `aria-label="Page N"` for screen reader clarity. +- The current page button carries `aria-current="page"`. +- First/previous buttons are disabled (native `disabled` attribute) on page 1. +- Next/last buttons are disabled on the last page. +- All buttons show a `focus-visible` ring when navigated via keyboard. +- Navigation icons are marked `aria-hidden="true"` since the button already has an `aria-label`. + +## Related Components + +- [VcDataTable](../../organisms/vc-table) -- Data table that commonly pairs with pagination for large datasets +- [VcSelect](../form/vc-select.md) -- Can be used alongside pagination for a "rows per page" selector + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/.pages new file mode 100644 index 0000000000..e2be5995c5 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/.pages @@ -0,0 +1,12 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Composables +nav: + - blade-navigation + - data + - ui-state + - services + - user + - notifications + - forms + - utilities diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/.pages new file mode 100644 index 0000000000..01519d71a4 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/.pages @@ -0,0 +1,9 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Blade Navigation +nav: + - Blade Navigation Composables: blade-nav-composables.md + - useBlade: useBlade.md + - useBladeContext: useBladeContext.md + - useBladeRegistry: useBladeRegistry.md + - useBladeWidgets: useBladeWidgets.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/blade-nav-composables.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/blade-nav-composables.md new file mode 100644 index 0000000000..c0094b2ca8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/blade-nav-composables.md @@ -0,0 +1,152 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/blade-navigation/blade-nav-composables.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Blade Navigation Composables + +The core composables that implement the blade navigation system -- the stacked-panel UI paradigm used throughout VirtoCommerce admin applications. + +## Overview + +Blade navigation manages an ordered stack of blade descriptors (plain data objects). Three composables divide responsibilities: + +1. **useBladeStack** -- the state machine: open, close, replace blades in the stack. +2. **useBladeMessaging** -- inter-blade communication: parent-child method calls. +3. **useBladeNavigation** (adapter) -- legacy API adapter that maps the old index-based API onto the new ID-based stack and messaging systems. + +## When to Use + +- Build or extend the blade navigation infrastructure itself (plugin authors, framework internals) +- Need direct access to the blade stack state machine (`useBladeStack`) or inter-blade messaging (`useBladeMessaging`) +- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()`, which wraps these low-level composables with a cleaner, context-aware API + + + +## useBladeStack + +The blade stack state machine. Manages an ordered array of `BladeDescriptor` objects. + +### Factory: `createBladeStack(bladeRegistry, hasAccess?)` + +Creates a new stack instance. Called once by the navigation plugin. + +### API + +| Method | Description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `openWorkspace(event)` | Sets the root blade (index 0). Closes all existing blades unconditionally. | +| `openBlade(event)` | Opens a child blade after a parent. Closes any blades deeper than the parent (with guard checks). | +| `closeBlade(bladeId)` | Closes a blade and all its children. Returns `true` if a guard prevented closing. | +| `closeChildren(parentId)` | Closes all blades after the given parent. | +| `replaceCurrentBlade(event)` | Destroys the current active blade and creates a new one at the same stack index with the same `parentId`. | +| `coverCurrentBlade(event)` | Hides the current active blade (keeps it in the stack) and opens a new blade on top. Closing the covering blade restores the hidden blade. | +| `registerBeforeClose(bladeId, guard)` | Registers a guard function. Return `true` from the guard to PREVENT closing. | +| `unregisterBeforeClose(bladeId)` | Removes a close guard. | +| `setBladeError(bladeId, error)` | Sets an error on a blade descriptor (displayed as error banner). | +| `clearBladeError(bladeId)` | Clears a blade's error. | +| `setBladeTitle(bladeId, title)` | Updates the blade's title in the descriptor. | + +### Computed + +| Property | Type | Description | +| ------------- | ---------------------------- | ------------------------ | +| `workspace` | `BladeDescriptor` | The root blade (index 0) | +| `blades` | `readonly BladeDescriptor[]` | Full ordered stack | +| `activeBlade` | `BladeDescriptor` | The last visible blade | + +### Composable: `useBladeStack()` + +Injects the stack from the component tree. Throws if used outside the navigation plugin. + +## useBladeMessaging + +Inter-blade communication via exposed methods. + +### Factory: `createBladeMessaging(bladeStack)` + +| Method | Description | +| ------------------------------------------ | ------------------------------------------------------------------------- | +| `exposeToChildren(bladeId, methods)` | Registers methods that child blades can call | +| `callParent(callerBladeId, method, args?)` | Calls a method on the caller's parent blade. Returns the method's result. | +| `cleanup(bladeId)` | Removes exposed methods for a blade (called on close). | + +### Composable: `useBladeMessaging()` + +Injects the messaging instance from the component tree. + +## useBladeNavigation (Adapter) + +The primary composable for module developers. Maps the legacy `IUseBladeNavigation` API onto the new stack/messaging system. + +### Key Methods + +```typescript +const { + openBlade, // Open a child blade + closeBlade, // Close by index (deprecated -- use useBlade().closeSelf()) + resolveBladeByName, // Look up a blade component by name + onParentCall, // Call parent blade method (deprecated -- use useBlade().callParent()) + onBeforeClose, // Register close guard (deprecated -- use useBlade().onBeforeClose()) + blades, // Reactive blade array (shim objects) + activeWorkspace, // Current workspace blade +} = useBladeNavigation(); +``` + +### Opening a blade + +```typescript +openBlade({ + blade: resolveBladeByName("OrderDetails"), + param: orderId, + options: { mode: "edit" }, + onOpen: () => console.log("opened"), + onClose: () => console.log("closed"), +}); +``` + +### Replacing the current blade (legacy adapter) + +```typescript +// Legacy: replaceCurrentBlade flag maps to coverCurrentBlade (hide + stack) +openBlade({ + blade: resolveBladeByName("AlternateView"), + replaceCurrentBlade: true, +}); + +// New API — prefer useBlade() methods: +// replaceWith() — true replacement (destroy old, create new at same index) +// coverWith() — hide old, open new on top (closing new reveals old) +``` + +## BladeDescriptor + +The plain data object stored in the stack for each blade: + +| Field | Type | Description | +| ---------- | ---------- | -------------------------------------------------------------------------- | +| `id` | `string` | Unique instance ID (auto-generated) | +| `name` | `string` | Blade registration name | +| `url` | `string?` | URL segment for address bar sync | +| `param` | `unknown` | Parameter passed when opening (e.g., entity ID) | +| `query` | `Record?` | Query parameters | +| `options` | `unknown` | Arbitrary options passed to the blade | +| `parentId` | `string?` | ID of the parent blade | +| `visible` | `boolean` | Whether the blade is rendered (false when covered via `coverCurrentBlade`) | +| `error` | `unknown?` | Error state for the error banner | +| `title` | `string?` | Dynamic title override | + +## Tips + +- Prefer `useBlade()` / `useBladeContext()` for new code -- they provide a cleaner API than the legacy adapter. +- Close guards return `true` to PREVENT closing (opposite of the legacy convention where `false` prevented closing). The adapter handles the inversion. +- `replaceCurrentBlade` destroys the current blade and creates a new one at the same index with the same `parentId`. Use `coverCurrentBlade` to hide instead of destroy — the covering blade's `callParent` reaches the hidden blade's exposed methods. +- URL sync only updates the address bar for blades that have a `url` segment. Third-level detail panels without URLs leave the previous URL intact. +- `useBladeNavigation()` requires the navigation plugin to be installed. It throws if called before plugin initialization. + +## Related + +- [`useBlade`](./useBlade.md) -- recommended API for everyday blade operations +- [`useBladeContext`](../composables/bladeContext/) -- share reactive blade data with descendant components + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBlade.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBlade.md new file mode 100644 index 0000000000..322e73d221 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBlade.md @@ -0,0 +1,764 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBlade/useBlade.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBlade + +Unified composable for blade navigation, identity, communication, guards, and error management in VC-Shell applications. This is the primary API for working with the blade navigation system -- the stacked panel paradigm (similar to Azure Portal) that drives every screen in a VC-Shell app. + +`useBlade()` works **everywhere**: inside blades it provides the full API (identity, navigation, communication, guards, errors); outside blades (dashboard cards, notification templates, composables) it provides navigation only (`openBlade`). Blade-specific methods throw a descriptive runtime error if called outside blade context. + +## When to Use + +- Open, close, replace, or cover blades from any component (blade, dashboard widget, toolbar handler) +- Read blade identity (`param`, `options`, `id`) or register close guards inside a blade +- Communicate between parent and child blades via `callParent` / `exposeToChildren` +- When NOT to use: for low-level stack manipulation or custom navigation plugins -- use the blade-navigation composables (`useBladeStack`, `useBladeMessaging`) directly + +## Quick Start + +```vue +<script setup lang="ts"> +import { useBlade } from "@vc-shell/framework"; + +// Inside a blade -- full API is available +const { openBlade, closeSelf, param, onBeforeClose } = useBlade(); + +// Open a child blade +await openBlade({ name: "OrderDetails", param: "order-123" }); + +// Read the parameter passed when this blade was opened +console.log(param.value); // "order-123" +</script> +``` + +```vue +<script setup lang="ts"> +import { useBlade } from "@vc-shell/framework"; + +// Outside a blade (e.g. dashboard widget) -- only navigation works +const { openBlade } = useBlade(); + +openBlade({ name: "OrderDetails", param: "order-123" }); +</script> +``` + +```vue +<script setup lang="ts"> +import { useBlade } from "@vc-shell/framework"; + +// Typed options — no manual casting needed +interface BladeOptions { + sellerProduct?: SellerProduct; +} +const { param, options, callParent } = useBlade<BladeOptions>(); + +console.log(options.value?.sellerProduct); // typed as SellerProduct | undefined +</script> +``` + +## API Reference + +### Import + +```typescript +import { useBlade } from "@vc-shell/framework"; + +const blade = useBlade(); +``` + +### Parameters + +`useBlade()` takes no parameters. Context is resolved automatically via Vue's provide/inject system. + +### Type Parameter + +`useBlade<TOptions>()` accepts an optional generic to type the `options` computed ref: + +```typescript +interface MyOptions { + productId: string; + mode: "edit" | "create"; +} +const { options } = useBlade<MyOptions>(); +// options.value is MyOptions | undefined — no manual casting needed +``` + +Without the generic, `options.value` defaults to `Record<string, unknown> | undefined`. + +### Returns: `UseBladeReturn` + +#### Identity Properties (blade context required) + +These are reactive `ComputedRef` values that reflect the current blade's state. Accessing them outside blade context throws a runtime error. + +| Property | Type | Description | +| ---------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `ComputedRef<string>` | The current blade's unique ID within the blade stack | +| `param` | `ComputedRef<string \| undefined>` | Route parameter passed when the blade was opened | +| `options` | `ComputedRef<TOptions \| undefined>` | Additional options object passed to the blade. Type is `Record<string, unknown>` by default; provide a generic to get a typed ref: `useBlade<MyOptions>()` | +| `query` | `ComputedRef<Record<string, string> \| undefined>` | URL query parameters scoped to this blade | +| `closable` | `ComputedRef<boolean>` | `true` when this blade has a parent (i.e., can be closed) | +| `expanded` | `ComputedRef<boolean>` | `true` when this blade is the active (rightmost) blade | +| `name` | `ComputedRef<string>` | The blade's registered component name | + +#### Navigation Methods (work everywhere) + +| Method | Signature | Description | +| ----------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| `openBlade` | `(event: BladeOpenEvent & { isWorkspace?: boolean }) => Promise<void>` | Open a blade as a child of the current blade, or as a workspace root if `isWorkspace: true` | + +#### Action Methods (blade context required) + +| Method | Signature | Description | +| --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| `closeSelf` | `() => Promise<boolean>` | Close the current blade. Returns `true` if a guard prevented closure. Respects `onBeforeClose` guards. | +| `closeChildren` | `() => Promise<void>` | Close all child blades of the current blade | +| `replaceWith` | `(event: BladeOpenEvent) => Promise<void>` | Replace the current blade with a different one in the same position (destroys the old blade) | +| `coverWith` | `(event: BladeOpenEvent) => Promise<void>` | Cover the current blade — hides it and opens a new blade on top. Closing the new blade reveals the hidden one. | + +#### Communication Methods (blade context required) + +| Method | Signature | Description | +| ------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------- | +| `callParent` | `<T = unknown>(method: string, args?: unknown) => Promise<T>` | Invoke a method exposed by the parent blade | +| `exposeToChildren` | `(methods: Record<string, (...args: unknown[]) => unknown>) => void` | Expose methods that child blades can call via `callParent` | + +#### Guards and Errors (blade context required) + +| Method | Signature | Description | +| --------------- | ----------------------------------------- | ----------------------------------------------- | +| `onBeforeClose` | `(guard: () => Promise<boolean>) => void` | Register a guard that can prevent blade closure | +| `setError` | `(error: unknown) => void` | Display an error banner on the blade | +| `clearError` | `() => void` | Clear the blade error banner | + +#### Banner Management (blade context required) + +| Method | Signature | Description | +| -------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- | +| `addBanner` | `(options: Omit<IBladeBanner, "id" \| "_system">) => string` | Add a custom banner to the blade. Returns the banner's unique ID. | +| `removeBanner` | `(id: string) => void` | Remove a specific banner by its ID | +| `clearBanners` | `() => void` | Remove all custom banners (system error/modified banners are preserved) | + +#### Lifecycle Hooks (blade context required) + +| Method | Signature | Description | +| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `onActivated` | `(callback: () => void) => void` | Register a callback fired when this blade becomes the active (rightmost) blade. Only fires on transitions, not on initial mount. | +| `onDeactivated` | `(callback: () => void) => void` | Register a callback fired when this blade loses active status (another blade opens on top). | + +> **Note:** Each hook can only be registered once per `useBlade()` call. A second registration logs a warning and is ignored. Use `onMounted` for initial-mount logic — `onActivated` only fires on subsequent activations. + +#### Deprecated + +| Method | Signature | Description | +| ------------------ | --------------------------------------------------- | --------------------------------------------------- | +| `provideBladeData` | `(data: MaybeRef<Record<string, unknown>>) => void` | **Deprecated.** Use `defineBladeContext()` instead. | + +### BladeOpenEvent + +The object passed to `openBlade`, `replaceWith`, and `coverWith`: + +```typescript +interface BladeOpenEvent { + /** Registered component name -- resolved via BladeRegistry */ + name: string; + /** Entity ID for the blade (e.g., order ID, product ID) */ + param?: string; + /** Small key-value pairs persisted in the URL query string */ + query?: Record<string, string>; + /** Large context data -- stored in history.state only, not in URL */ + options?: Record<string, unknown>; + /** Called after the blade finishes opening */ + onOpen?: () => void; + /** Called after the blade is closed */ + onClose?: () => void; +} +``` + +--- + +## Features + +### Opening Blades + +Use `openBlade` to navigate to a new blade. Inside a blade, the new blade opens as a child; outside, it opens relative to the currently active blade. + +```typescript +const { openBlade } = useBlade(); + +// Open by registered name with param +await openBlade({ name: "OrderDetails", param: "order-123" }); + +// With options and lifecycle callbacks +openBlade({ + name: "FulfillmentCenterDetails", + param: centerId, + options: { mode: "edit" }, + onOpen() { + selectedItemId.value = centerId; + }, + onClose() { + selectedItemId.value = undefined; + }, +}); + +// Open as workspace (replaces entire blade stack) +await openBlade({ name: "SettingsWorkspace", isWorkspace: true }); +``` + +### Closing Blades + +```vue +<script setup lang="ts"> +const { closeSelf, closeChildren } = useBlade(); + +// Close the current blade +await closeSelf(); + +// Close all children before doing something +await closeChildren(); +</script> +``` + +> **Tip:** `closeSelf()` returns `true` if a close guard prevented the blade from closing, and `false` if the blade was successfully closed. Always check the return value when you need to take action after closure. + +### Replacing the Current Blade + +Replace the current blade with a different one, keeping the same position in the stack: + +```vue +<script setup lang="ts"> +const { replaceWith, coverWith } = useBlade(); + +// Switch from "create" mode to "edit" mode after saving (destroys the old blade) +async function onSaveNew(createdId: string) { + await replaceWith({ + name: "ProductDetails", + param: createdId, + }); +} + +// Open a "preview" blade on top — closing it returns to the current blade +async function onPreview() { + await coverWith({ + name: "ProductPreview", + param: product.value.id, + }); +} +</script> +``` + +### Passing Data: `param` and `options` + +Blades receive data through two channels: + +- **`param`** -- A single string value, typically an entity ID. Appears in the URL for deep-linking support. +- **`options`** -- A key-value object for larger or structured data. Stored in `history.state`, not in the URL. + +```vue +<!-- Parent blade (list) --> +<script setup lang="ts"> +const { openBlade } = useBlade(); + +function onRowClick(orderId: string) { + openBlade({ + name: "OrderDetails", + param: orderId, + options: { preloadedName: "My Order" }, + }); +} +</script> +``` + +```vue +<!-- Child blade (details) --> +<script setup lang="ts"> +const { param, options } = useBlade(); + +onMounted(async () => { + // param.value === "order-123" + if (param.value) { + await loadOrder(param.value); + } + + // options.value === { preloadedName: "My Order" } + const preloaded = options.value?.preloadedName as string; +}); +</script> +``` + +### Parent-Child Communication + +The blade messaging system allows child blades to invoke methods exposed by their parent. This is the standard pattern for refreshing a list after saving in a details blade. + +**Parent blade -- expose methods:** + +```vue +<script setup lang="ts"> +const { exposeToChildren } = useBlade(); + +async function reload() { + await searchProducts(searchQuery.value); +} + +function onItemClick(item: Product) { + selectedItemId.value = item.id; +} + +// Expose methods to children +exposeToChildren({ reload, onItemClick }); +</script> +``` + +**Child blade -- call parent:** + +```vue +<script setup lang="ts"> +const { callParent, closeSelf } = useBlade(); + +async function onSave() { + await saveProduct(product.value); + + // Tell parent to refresh its list + await callParent("reload"); + + // Close self after successful save + await closeSelf(); +} +</script> +``` + +> **Tip:** `callParent` is generic. If the parent method returns a value, you can type it: +> +> ```typescript +> const count = await callParent<number>("getOffersCount"); +> ``` + +### Blade Guards and Lifecycle + +Register a guard that runs before the blade closes. Return `true` to **prevent** closure, `false` to **allow** it. + +```vue +<script setup lang="ts"> +import { useBlade, usePopup } from "@vc-shell/framework"; + +const { onBeforeClose } = useBlade(); +const { showConfirmation } = usePopup(); + +onBeforeClose(async () => { + if (isModified.value) { + // showConfirmation returns true if user confirms, false if cancelled + const confirmed = await showConfirmation("Discard unsaved changes?"); + return !confirmed; // true = prevent close, false = allow close + } + return false; // allow close +}); +</script> +``` + +> **Important:** The return value semantics are: `true` means "prevent closure" and `false` means "allow closure". This matches the convention used by Vue Router's `beforeRouteLeave`. + +### Blade Identity + +```typescript +const { id, name, param, expanded, closable, onActivated, onDeactivated } = useBlade(); + +useWidgets(id.value, widgetDefs); // blade ID for scoped operations + +// React to blade activation/deactivation (transitions only, not initial mount) +onActivated(() => { + // blade became the rightmost (active) blade — e.g., refresh data +}); + +onDeactivated(() => { + // another blade opened on top — e.g., pause polling +}); +``` + +### Error Management + +Display or clear error banners on the blade: + +```vue +<script setup lang="ts"> +const { setError, clearError } = useBlade(); + +async function loadData() { + try { + clearError(); + await fetchData(); + } catch (e) { + setError(e); // Shows error banner on the blade + } +} +</script> +``` + +### Banner Management + +Add custom banners (info, warning, danger, success) to the top of a blade. Banners appear between the header and toolbar, sorted by severity: danger > warning > info > success. + +```vue +<script setup lang="ts"> +import { h } from "vue"; +import { useBlade } from "@vc-shell/framework"; + +const { addBanner, removeBanner, clearBanners } = useBlade(); + +// Simple text banner +const bannerId = addBanner({ + variant: "info", + message: "This record is in read-only mode", +}); + +// Warning with dismiss button +addBanner({ + variant: "warning", + message: "License expires in 7 days", + dismissible: true, +}); + +// Banner with an action button +addBanner({ + variant: "success", + message: "Import completed (42 items)", + dismissible: true, + action: { + label: "View report", + handler: () => openReport(), + }, +}); + +// Banner with custom render function +addBanner({ + variant: "info", + render: () => h("span", ["Data synced from ", h("b", "Warehouse A"), " at 14:32"]), +}); + +// Remove a specific banner +removeBanner(bannerId); + +// Clear all custom banners (system error/modified banners are preserved) +clearBanners(); +</script> +``` + +#### IBladeBanner + +The options object passed to `addBanner`: + +| Property | Type | Default | Description | +| ------------- | ---------------------------------------------- | -------- | ---------------------------------------------------- | +| `variant` | `"danger" \| "warning" \| "info" \| "success"` | required | Color scheme and default icon | +| `message` | `string` | -- | Plain text message | +| `render` | `() => VNode` | -- | Custom render function (takes priority over message) | +| `dismissible` | `boolean` | `false` | Show a close button to dismiss the banner | +| `icon` | `string` | -- | Override the default variant icon (lucide icon name) | +| `action` | `{ label: string; handler: () => void }` | -- | Action button displayed on the right side | + +> **Note:** `addBanner` returns a unique string ID. Use it with `removeBanner(id)` to programmatically remove a specific banner. `clearBanners()` removes all custom banners but preserves system banners (error and unsaved changes). + +--- + +## Blade Context: defineBladeContext / injectBladeContext + +For sharing reactive data from a blade to its descendant widgets, extensions, and nested components, use the `defineBladeContext` / `injectBladeContext` pair. This replaces the deprecated `provideBladeData`. + +### defineBladeContext (in blade component) + +Call in a blade's `<script setup>` to expose reactive data to all descendant components: + +```vue +<script setup lang="ts"> +import { defineBladeContext } from "@vc-shell/framework"; + +const item = ref<Order | undefined>(); +const loading = ref(false); + +// Expose to widgets and nested components +defineBladeContext({ item, loading }); + +// Or selectively expose via computed +defineBladeContext(computed(() => ({ id: item.value?.id }))); +</script> +``` + +### injectBladeContext (in widget / nested component) + +```vue +<script setup lang="ts"> +import { injectBladeContext } from "@vc-shell/framework"; + +const ctx = injectBladeContext(); +// Returns ComputedRef<Record<string, unknown>> + +const orderId = computed(() => ctx.value.id as string); +const isLoading = computed(() => ctx.value.loading as boolean); +</script> +``` + +> **When to use which:** +> +> - `defineBladeContext` / `injectBladeContext` -- for sharing data with **child widgets and nested components** within the same blade's component tree (via provide/inject). +> - `callParent` / `exposeToChildren` -- for **cross-blade communication** between parent and child blades in the blade stack. + +--- + +## Recipes + +### Recipe 1: List-to-Details Navigation + +The most common pattern: a list workspace that opens a details blade on row click. + +```vue +<!-- ProductsList.vue --> +<script setup lang="ts"> +import { useBlade } from "@vc-shell/framework"; + +defineOptions({ name: "ProductsList", url: "/products", isWorkspace: true }); + +const { openBlade } = useBlade(); +const selectedItemId = ref<string>(); + +function onRowClick(event: { data: { id?: string } }) { + openBlade({ + name: "ProductDetails", + param: event.data.id, + onOpen() { + selectedItemId.value = event.data.id; + }, + onClose() { + selectedItemId.value = undefined; + }, + }); +} + +async function reload() { + await searchProducts(); +} + +// Expose reload so child blades can callParent("reload") +defineExpose({ reload, title: "Products" }); +</script> +``` + +### Recipe 2: Details Blade That Refreshes Parent on Save + +```vue +<!-- ProductDetails.vue --> +<script setup lang="ts"> +import { useBlade, usePopup } from "@vc-shell/framework"; + +defineOptions({ name: "ProductDetails", url: "/product-details" }); + +const { param, onBeforeClose, closeSelf, callParent } = useBlade(); +const { showConfirmation } = usePopup(); + +onMounted(async () => { + if (param.value) await loadProduct(param.value); +}); + +async function onSave() { + await saveProduct(product.value); + await callParent("reload"); + await closeSelf(); +} + +onBeforeClose(async () => { + if (isModified.value) { + return !(await showConfirmation("Discard unsaved changes?")); + } + return false; +}); + +defineExpose({ title }); +</script> +``` + +> **Note:** The key change vs. the old pattern is removing `defineProps<{ expanded?: boolean; closable?: boolean; param?: string }>()` and reading `param` from `useBlade()` instead. + +### Recipe 3: Multi-Level Blade Chain (List -> Details -> Sub-Details) + +A "middle" blade that is both a child (calls parent) and a parent (exposes methods to its own children): + +```vue +<!-- OrderDetails.vue --> +<script setup lang="ts"> +import { useBlade, defineBladeContext } from "@vc-shell/framework"; + +const { openBlade, callParent, exposeToChildren, closeSelf } = useBlade(); +const item = ref<Order>(); + +defineBladeContext({ item }); // share with widgets + +async function reload() { + await loadOrder(props.param!); +} +exposeToChildren({ reload }); // child ShipmentDetails can callParent("reload") + +function openShipment(id: string) { + openBlade({ name: "ShipmentDetails", param: id }); +} + +async function onDelete() { + await deleteOrder(props.param!); + await callParent("reload"); // tell grandparent list to refresh + await closeSelf(); +} +</script> +``` + +### Recipe 4: Toolbar Action and Dashboard Card + +```vue +<!-- Toolbar: opening blade from a toolbar button --> +<script setup lang="ts"> +const { openBlade } = useBlade(); + +const toolbar = ref<IBladeToolbar[]>([ + { + id: "addItem", + title: "Add Item", + icon: "lucide-plus", + clickHandler() { + openBlade({ name: "ItemDetails" }); // no param = create mode + }, + }, +]); +</script> +``` + +```vue +<!-- Dashboard card: no blade context, only openBlade works --> +<script setup lang="ts"> +const { openBlade } = useBlade(); + +function viewOrder(orderId: string) { + openBlade({ name: "OrderDetails", param: orderId }); +} + +function goToOrders() { + openBlade({ name: "OrdersList", isWorkspace: true }); +} +</script> +``` + +--- + +## Common Mistakes + +!!! warning "Blade-specific methods throw outside blade context" +Methods like `closeSelf`, `callParent`, `onBeforeClose`, and `setError` require a blade context (i.e., must be called from inside a blade component's `<script setup>`). Calling them from a dashboard card, a toolbar handler, or a plain composable throws a descriptive runtime error. Only `openBlade` works everywhere. + +### Calling blade-specific methods outside blade context + +```typescript +// BAD -- throws at runtime +const { closeSelf } = useBlade(); +// Called from a dashboard widget (no blade context) +closeSelf(); // Error: closeSelf() requires blade context +``` + +```typescript +// GOOD -- only use methods that work everywhere +const { openBlade } = useBlade(); +openBlade({ name: "OrderDetails", param: orderId }); +``` + +### Forgetting to expose reload to children + +```vue +<!-- BAD -- child calls callParent("reload") but parent never exposed it --> +<script setup lang="ts"> +async function reload() { + /* ... */ +} +// Missing: exposeToChildren({ reload }) +// or: defineExpose({ reload }) +</script> +``` + +```vue +<!-- GOOD -- explicitly expose methods for children --> +<script setup lang="ts"> +async function reload() { + /* ... */ +} +exposeToChildren({ reload }); +// Also expose title for breadcrumbs +defineExpose({ reload, title }); +</script> +``` + +### Wrong return value in onBeforeClose guard + +```typescript +// BAD -- returns true when you want to ALLOW closing +onBeforeClose(async () => { + if (isDirty.value) { + const userWantsToLeave = await showConfirmation("Discard?"); + return userWantsToLeave; // true means PREVENT close! + } + return true; // This prevents closing even when not dirty! +}); +``` + +```typescript +// GOOD -- return false to allow, true to prevent +onBeforeClose(async () => { + if (isDirty.value) { + const userWantsToLeave = await showConfirmation("Discard?"); + return !userWantsToLeave; // negate: true=prevent, false=allow + } + return false; // not dirty, allow close +}); +``` + +### Using provideBladeData instead of defineBladeContext + +```typescript +// BAD -- deprecated API +const { provideBladeData } = useBlade(); +provideBladeData({ item, loading }); +``` + +```typescript +// GOOD -- use the dedicated function +import { defineBladeContext } from "@vc-shell/framework"; +defineBladeContext({ item, loading }); +``` + +### Accessing identity properties reactively without .value + +```typescript +// BAD -- accesses the ComputedRef object, not the value +if (param) { + /* always truthy -- it's a ComputedRef object */ +} +``` + +```typescript +// GOOD -- access the reactive value +if (param.value) { + /* correct -- checks the actual string */ +} +``` + +--- + + + +--- + +## Related + +| Resource | Description | +| ------------------------------------------------------------------------- | ------------------------------------------------------------ | +| [`defineBladeContext` / `injectBladeContext`](../useBladeContext.docs.md) | Share reactive blade data with descendant widgets | +| [`useBladeRegistry`](./useBladeRegistry.md) | Look up registered blade components by name | +| [`VcBlade`](../../components/layout/vc-blade.md) | The blade UI shell component (header, toolbar, content area) | +| [`VcBladeNavigation`](../../../shared/components/blade-navigation/) | The container component that renders the blade stack | +| [`useToolbar`](../../../shared/composables/useToolbar/) | Dynamic toolbar management for blades | +| [`usePopup`](../../../shared/composables/usePopup/) | Confirmation dialogs, commonly used in close guards | diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeContext.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeContext.md new file mode 100644 index 0000000000..925a248af3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeContext.md @@ -0,0 +1,119 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/bladeContext/index.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBladeContext (defineBladeContext / injectBladeContext) + +Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state. + +The pattern follows a "define once, inject anywhere" approach: the blade component calls `defineBladeContext` during setup, and any descendant (no matter how deeply nested) can call `injectBladeContext` to read that data reactively. + +## When to Use + +- Share blade state (current entity, loading flags, disabled state) with child widgets without prop drilling +- Access parent blade data from an extension or widget component +- Expose selective fields to widgets (e.g., only the entity ID) via a computed getter +- When NOT to use: for cross-blade communication between sibling blades (use `useBlade` / blade messaging instead) + +## Basic Usage + +```typescript +// In a blade's <script setup> +import { defineBladeContext, injectBladeContext } from "@vc-shell/framework"; + +// Provide context — refs/computeds are auto-unwrapped for consumers +defineBladeContext({ item, disabled, loading }); + +// Or with a computed for selective exposure +defineBladeContext(computed(() => ({ id: item.value?.id }))); +``` + +```typescript +// In a widget or nested component +import { injectBladeContext } from "@vc-shell/framework"; + +const ctx = injectBladeContext(); +// Refs are already unwrapped — access values directly, no .value needed +const entityId = computed(() => ctx.value.id as string); +const item = computed(() => ctx.value.item as { id: string; name: string }); +``` + +## API + +### defineBladeContext + +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------- | -------- | -------------------------------------- | +| `data` | `MaybeRefOrGetter<Record<string, unknown>>` | Yes | Plain object, ref, or getter to expose | + +Returns `void`. Must be called in the blade's `<script setup>`. + +### injectBladeContext + +Takes no parameters. Returns `ComputedRef<Record<string, unknown>>`. + +Throws `InjectionError` if no ancestor blade has called `defineBladeContext`. + +## Recipe: Widget Consuming Blade Context + +A typical pattern is a sidebar widget that needs to load related data based on the current blade entity. The widget does not receive any props from the blade -- it reads the entity ID from the blade context: + +```vue +<script setup lang="ts"> +// widgets/RelatedOrdersWidget.vue +import { computed, watch } from "vue"; +import { injectBladeContext } from "@vc-shell/framework"; + +const ctx = injectBladeContext(); +const customerId = computed(() => ctx.value.id as string | undefined); + +// Reload orders whenever the customer changes +watch(customerId, async (id) => { + if (id) { + await loadOrders(id); + } +}); +</script> +``` + +```vue +<script setup lang="ts"> +// blades/CustomerDetailBlade.vue +import { ref, computed } from "vue"; +import { defineBladeContext } from "@vc-shell/framework"; + +const customer = ref({ id: "cust-1", name: "Acme Corp" }); +const loading = ref(false); + +// Expose the customer data to all descendant widgets +defineBladeContext( + computed(() => ({ + id: customer.value?.id, + name: customer.value?.name, + loading: loading.value, + })), +); +</script> +``` + +## Details + +- **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically. +- **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically. +- **Injection key**: Uses `BladeContextKey` (a framework-level Symbol), so there is no risk of key collision with application code. +- **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`. +- **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways. + +## Tips + +- Prefer exposing a computed getter rather than the full reactive object when only a subset of fields is needed. This minimizes unnecessary re-renders in consuming widgets. +- The context value is untyped (`Record<string, unknown>`). Use type assertions or a typed wrapper in your module if you need type safety (e.g., `ctx.value.id as string`). +- If a blade does not call `defineBladeContext`, any descendant calling `injectBladeContext` will throw. Make sure all blades that host widgets define their context. + +## Related + +- [`useBladeWidgets`](../useBladeWidgets/) -- widgets that consume blade context +- [`useBlade`](./useBlade.md) -- cross-blade communication via `callParent` / `exposeToChildren` + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeRegistry.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeRegistry.md new file mode 100644 index 0000000000..83e30fe17c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeRegistry.md @@ -0,0 +1,158 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBladeRegistry/useBladeRegistry.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBladeRegistry + +Provides read-only access to the blade registry -- a central map of all registered blade components, their routes, and metadata. + +## Overview + +The blade registry is the framework's central directory of all blade components available in the application. When a module is loaded, its blades are registered in this map along with their routes, permissions, and workspace flags. The registry enables runtime blade lookup by name, reverse lookup by URL route, and component resolution for dynamic blade navigation. + +The `useBladeRegistry()` composable provides the read-only consumer API. Blade registration happens automatically during module setup via `createBladeRegistry()` -- module developers do not register blades manually. + +Internally, the registry maintains a reactive `Map<string, IBladeRegistrationData>` and a reverse index from URL route segments to blade names. The reverse index enables O(1) route-to-blade lookups for deep linking and URL-based navigation. + +## When to Use + +- When you need to look up a blade component by name at runtime +- When resolving URL routes to blade components (deep linking) +- When inspecting which blades are registered (debugging, admin tools) +- Do NOT use for registering blades -- that happens automatically via module setup + +## Basic Usage + +```typescript +import { useBladeRegistry } from "@vc-shell/framework"; + +const { getBlade, getBladeComponent } = useBladeRegistry(); + +const data = getBlade("OrderDetails"); +const component = getBladeComponent("OrderDetails"); +``` + +## API + +### Returns + +| Property | Type | Description | +| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ | +| `registeredBladesMap` | `ComputedRef<ReadonlyMap<string, IBladeRegistrationData>>` | Reactive readonly map of all registered blades | +| `getBlade` | `(name: string) => IBladeRegistrationData \| undefined` | Get registration data (component, route, permissions) by blade name | +| `getBladeComponent` | `(name: string) => BladeInstanceConstructor \| undefined` | Get the Vue component for a blade name (falls back to global components) | +| `getBladeByRoute` | `(route: string) => { name, data } \| undefined` | Reverse lookup: find a blade by its URL route segment (O(1)) | + +### IBladeRegistrationData + +| Property | Type | Description | +| ------------- | -------------------------- | ------------------------------------------------ | +| `component` | `BladeInstanceConstructor` | The Vue component for the blade | +| `route` | `string?` | URL route segment (e.g. `"orders"`) | +| `isWorkspace` | `boolean?` | Whether this blade opens as a workspace root | +| `routable` | `boolean?` | Whether this blade supports URL-based navigation | +| `permissions` | `string \| string[]?` | Required permissions to access this blade | + +## Common Patterns + +### Conditional navigation based on registration + +```typescript +<script setup lang="ts"> +import { useBladeRegistry, useBlade } from "@vc-shell/framework"; + +const { getBlade } = useBladeRegistry(); +const { openBlade } = useBlade(); + +function navigateTo(bladeName: string, param?: string) { + const registration = getBlade(bladeName); + if (!registration) { + console.warn(`Blade "${bladeName}" is not registered`); + return; + } + openBlade({ name: bladeName, param }); +} +</script> +``` + +### Deep link resolution + +```typescript +import { useBladeRegistry } from "@vc-shell/framework"; + +const { getBladeByRoute } = useBladeRegistry(); + +// Resolve a URL segment to a blade +function resolveDeepLink(routeSegment: string) { + const result = getBladeByRoute(routeSegment); + if (result) { + console.log(`Route "${routeSegment}" maps to blade "${result.name}"`); + console.log(`Permissions required: ${result.data.permissions}`); + return result; + } + console.warn(`No blade registered for route "${routeSegment}"`); + return undefined; +} + +// Works with or without leading slash +resolveDeepLink("orders"); // { name: "OrdersList", data: { ... } } +resolveDeepLink("/orders"); // Same result +``` + +### Listing all registered blades + +```typescript +<script setup lang="ts"> +import { useBladeRegistry } from "@vc-shell/framework"; + +const { registeredBladesMap } = useBladeRegistry(); + +const bladeNames = computed(() => [...registeredBladesMap.value.keys()]); +const workspaceBlades = computed(() => + [...registeredBladesMap.value.entries()] + .filter(([, data]) => data.isWorkspace) + .map(([name]) => name), +); +</script> +``` + +### Checking permissions before navigation + +```typescript +import { useBladeRegistry, usePermissions } from "@vc-shell/framework"; + +const { getBlade } = useBladeRegistry(); +const { hasAccess } = usePermissions(); + +function canAccessBlade(bladeName: string): boolean { + const registration = getBlade(bladeName); + if (!registration) return false; + return hasAccess(registration.permissions); +} +``` + +## Notes + +- The composable must be called after the navigation plugin has initialized. Calling it too early (e.g., outside a setup function or before app bootstrap) throws an error. +- `getBladeComponent()` falls back to Vue's global component registry if the blade is not found in the framework registry. This supports legacy components registered via `app.component()`. +- The `registeredBladesMap` is a `ComputedRef` wrapping a `ReadonlyMap`, so it updates reactively when new modules are loaded. + +## Tip: Use getBlade for Validation + +Before opening a blade programmatically, always check that it exists in the registry. This catches typos and missing module dependencies at runtime with a clear error instead of a cryptic render failure: + +```typescript +const registration = getBlade("OderDetails"); // Typo: "Oder" instead of "Order" +if (!registration) { + notification.error('Blade "OderDetails" not found. Is the module loaded?'); + return; +} +``` + +## Related + +- [`useBlade`](./useBlade.md) -- opens and manages blades by name +- Dynamic Module Loading -- registers blades during module initialization + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeWidgets.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeWidgets.md new file mode 100644 index 0000000000..06e42da19e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/blade-navigation/useBladeWidgets.md @@ -0,0 +1,308 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBladeWidgets/index.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBladeWidgets / useWidgetTrigger + +Two composables for the widget system — one for the **blade side**, one for the **widget side**. + +| Composable | Called from | Purpose | +| ------------------ | ------------------------- | ---------------------------------------------------------------------- | +| `useBladeWidgets` | Blade component | Register headless widgets + get `refresh()` / `refreshAll()` | +| `useWidgetTrigger` | External widget component | Register trigger callbacks (`onRefresh`, `onClick`) via provide/inject | + +Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. External component-based widgets use `useWidgetTrigger` to register their refresh callbacks so the hosting blade can trigger them. + +## When to Use + +- **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete). +- **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them. +- When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead). + +## Basic Usage + +```typescript +import { useBladeWidgets } from "@vc-shell/framework"; + +const { refreshAll } = useBladeWidgets([ + { + id: "OffersWidget", + icon: "lucide-tag", + title: "OFFERS.TITLE", + badge: offersCount, + loading: offersLoading, + onClick: () => openBlade({ name: "OffersList" }), + onRefresh: () => reloadOffers(), + }, + { + id: "ReviewsWidget", + icon: "lucide-star", + title: "REVIEWS.TITLE", + badge: reviewsCount, + isVisible: computed(() => !!item.value?.id), + onClick: () => openBlade({ name: "ReviewsList" }), + }, +]); + +// After a save, refresh all widget data +await saveEntity(); +refreshAll(); +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| --------- | ----------------------------- | -------- | ---------------------------- | +| `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations | + +### HeadlessWidgetDeclaration + +| Field | Type | Required | Description | +| ----------- | --------------------------------- | -------- | ----------------------------------------- | +| `id` | `string` | Yes | Unique widget identifier | +| `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) | +| `title` | `string` | Yes | i18n key or display title | +| `badge` | `Ref<number \| string>` | No | Badge counter value | +| `loading` | `Ref<boolean>` | No | Show loading indicator | +| `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget | +| `isVisible` | `ComputedRef<boolean> \| boolean` | No | Toggle visibility | +| `onClick` | `() => void` | No | Action when widget is clicked | +| `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` | + +### Returns + +| Property | Type | Description | +| ------------ | ---------------------------- | ------------------------------------------------ | +| `refresh` | `(widgetId: string) => void` | Trigger `onRefresh` on a specific widget | +| `refreshAll` | `() => void` | Trigger `onRefresh` on all widgets that have one | + +## useWidgetTrigger + +Widget-side composable for external component-based widgets. Registers a trigger contract (`onRefresh`, `onClick`, `badge`) via provide/inject — no props, IDs, or service knowledge required. + +### Basic Usage + +```typescript +import { useWidgetTrigger } from "@vc-shell/framework"; + +// Inside an external widget component: +useWidgetTrigger({ onRefresh: loadData }); +``` + +### IWidgetTrigger + +| Field | Type | Required | Description | +| ----------- | ----------------------------- | -------- | ------------------------------------------------- | +| `icon` | `string` | No | Lucide icon name for dropdown rendering | +| `title` | `string` | No | Display title (fallback: widget's title) | +| `badge` | `Ref<number \| string>` | No | Reactive badge value | +| `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown | +| `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data | +| `disabled` | `Ref<boolean> \| boolean` | No | Disabled state | + +### How It Works + +1. `WidgetContainer` wraps each component-based widget in a `WidgetScope` provider +2. `WidgetScope` provides a `setTrigger` function scoped to the specific widget ID and blade ID +3. `useWidgetTrigger` injects this scope and calls `setTrigger` — no props or IDs needed +4. When the blade calls `refresh(widgetId)` or `refreshAll()`, the registered `onRefresh` is invoked + +## Recipe: External Widget with Refresh + +A complete example of an external widget that shows an unread message count and supports refresh from the blade: + +**1. Register the external widget (module index.ts):** + +```typescript +import { createAppModule, registerExternalWidget, BladeDescriptor } from "@vc-shell/framework"; +import { markRaw } from "vue"; +import { MessageWidget } from "./components/widgets"; + +registerExternalWidget({ + id: "MessageWidget", + component: markRaw(MessageWidget), + targetBlades: ["ProductDetails", "OrderDetails"], + isVisible: (blade?: BladeDescriptor) => !!blade?.param, +}); +``` + +**2. Widget component (message-widget.vue):** + +```vue +<template> + <VcWidget + v-loading:500="loading" + :title="$t('MESSENGER.WIDGET.TITLE')" + icon="lucide-message-circle" + :value="messageCount" + @click="openMessageBlade" + /> +</template> + +<script setup lang="ts"> +import { ref, computed, onMounted } from "vue"; +import { loading as vLoading, useBlade, injectBladeContext, useWidgetTrigger, VcWidget } from "@vc-shell/framework"; + +const ctx = injectBladeContext(); +const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? ""); + +const messageCount = ref(0); +const loading = ref(false); + +const loadData = async () => { + loading.value = true; + try { + messageCount.value = await api.getUnreadCount(entityId.value); + } finally { + loading.value = false; + } +}; + +// Register refresh callback — blade can call refreshAll() after save +useWidgetTrigger({ onRefresh: loadData }); + +onMounted(() => { + if (entityId.value) loadData(); +}); +</script> +``` + +**3. Blade refreshes widgets after save:** + +```vue +<script setup lang="ts"> +import { useBladeWidgets } from "@vc-shell/framework"; + +// Empty array — blade doesn't register headless widgets, +// but gets refresh/refreshAll for external widgets +const { refresh, refreshAll } = useBladeWidgets([]); + +async function save() { + await api.saveProduct(product.value); + refreshAll(); // refresh all widgets (including MessageWidget) + // or: refresh("MessageWidget"); // refresh a specific widget by ID +} +</script> +``` + +## Recipe: Product Detail Blade with Multiple Widgets + +```vue +<script setup lang="ts"> +import { ref, computed } from "vue"; +import { useBladeWidgets, defineBladeContext } from "@vc-shell/framework"; + +const product = ref({ id: "prod-1", name: "Widget A" }); +const offersCount = ref(0); +const reviewsCount = ref(0); +const offersLoading = ref(false); + +// Expose product data to widgets +defineBladeContext(computed(() => ({ id: product.value?.id }))); + +async function reloadOffers() { + offersLoading.value = true; + try { + const result = await api.searchOffers({ productId: product.value.id }); + offersCount.value = result.totalCount; + } finally { + offersLoading.value = false; + } +} + +const { refreshAll } = useBladeWidgets([ + { + id: "OffersWidget", + icon: "lucide-tag", + title: "PRODUCT.WIDGETS.OFFERS", + badge: offersCount, + loading: offersLoading, + isVisible: computed(() => !!product.value?.id), + onClick: () => openBlade({ name: "OffersList" }), + onRefresh: reloadOffers, + }, + { + id: "ReviewsWidget", + icon: "lucide-star", + title: "PRODUCT.WIDGETS.REVIEWS", + badge: reviewsCount, + isVisible: computed(() => !!product.value?.id), + onClick: () => openBlade({ name: "ReviewsList" }), + }, +]); + +async function save() { + await api.saveProduct(product.value); + // Refresh all widget counts after saving + refreshAll(); +} +</script> +``` + +## Prerequisites + +!!! warning "Call site requirements" +`useBladeWidgets` must be called inside a blade component's `<script setup>` — it requires blade context to be present. `useWidgetTrigger` must be called inside a widget component rendered by `WidgetContainer`. Calling either outside their required scope produces a runtime error or silent no-op respectively. + +**`useBladeWidgets`**: + +- Must be called inside a blade component's `<script setup>`. +- Widget service must be provided in the component tree (automatically available in vc-shell apps). +- Calling outside a blade context throws an error with a descriptive message. + +**`useWidgetTrigger`**: + +- Must be called inside a widget component rendered by `WidgetContainer`. +- If called outside a widget scope, logs a warning and does nothing (does not throw). + +## Details + +- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the widget service always reflects the currently visible blades. +- **Blade ID resolution**: The composable injects the blade descriptor to determine which blade the widgets belong to. Each blade has its own isolated widget list. +- **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped. + +## Tips + +- Use `refreshAll()` after any blade operation that might change widget badge counts (save, delete, import). +- The `badge` field accepts both numbers and strings. Use a string for non-numeric badges like "New" or "!". +- Keep widget IDs unique within a blade. Duplicate IDs will overwrite previous registrations. +- Combine with `defineBladeContext` to expose blade entity data that widget components (non-headless) can consume via `injectBladeContext`. + +## Common Mistakes + +### Calling useWidgetTrigger outside WidgetContainer scope + +```typescript +// Wrong — called in a standalone component, not rendered inside a blade widget slot +export default defineComponent({ + setup() { + useWidgetTrigger({ onRefresh: loadData }); // ⚠️ Logs warning, trigger not registered + }, +}); +``` + +```typescript +// Correct — called inside a widget component registered via registerExternalWidget +// and rendered by WidgetContainer within a blade +useWidgetTrigger({ onRefresh: loadData }); // ✓ WidgetScope provides context +``` + +### Forgetting to pass empty array to useBladeWidgets for refresh-only usage + +```typescript +// Wrong — useBladeWidgets requires an array argument +const { refreshAll } = useBladeWidgets(); // TS error + +// Correct — pass empty array when you only need refresh/refreshAll +const { refreshAll } = useBladeWidgets([]); +``` + +## Related + +- [`defineBladeContext` / `injectBladeContext`](../bladeContext/) -- expose/consume blade data in external widgets +- `registerExternalWidget` -- register a component-based widget globally for target blades + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/.pages new file mode 100644 index 0000000000..725de9148c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/.pages @@ -0,0 +1,12 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Data +nav: + - Table Composables: table-composables.md + - useApiClient: useApiClient.md + - useAssets: useAssets.md + - useAssetsManager: useAssetsManager.md + - useDataTablePagination: useDataTablePagination.md + - useDataTableSort: useDataTableSort.md + - useTableSelection: useTableSelection.md + - useTableSort: useTableSort.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/table-composables.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/table-composables.md new file mode 100644 index 0000000000..32a5515f52 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/table-composables.md @@ -0,0 +1,163 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/components/organisms/vc-data-table/composables/table-composables.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# VcTable Composables + +Composables that power VcDataTable's functionality. Each handles a single concern and is wired together by the table component. Module developers rarely use these directly -- they are consumed internally by `VcDataTable.vue`. + +## Overview + +The composables follow a PrimeVue-inspired pattern: each returns reactive state and handler functions that the table component binds to its template. They communicate via shared refs passed through options objects. + +## Composable Catalog + +### Data & State + +| Composable | Purpose | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `useDataTableState` | Persists column state (v2 schema: weights, order, hidden/shown IDs) to localStorage/sessionStorage. Auto-migrates v1 (pixel-based) state on first load. Key format: `VC_DATATABLE_{KEY}`. Debounced auto-save (150ms) with restore-on-mount. | +| `useTableColumns` | Column ordering, width management via `columnState` (weight store), computed pixel widths via `engineOutput`. Exposes `recompute()` to trigger a recalculation pass. Watches `visibleColumns` and appends new columns without dropping hidden ones. | +| `useColumnWidthEngine` | Pure functions for deterministic column width computation (see below). | +| `useDataProcessing` | Client-side sort pipeline (single/multi) and row grouping. Skipped when `lazy: true` (server-side). | +| `useTableContext` | Provides/injects table-level context for sub-components. | + +### Sorting & Filtering + +| Composable | Purpose | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `useTableSort` | Single and multi-sort with removable sort (asc -> desc -> none cycle). Ctrl+click for multi-sort. Syncs with external props. | +| `useFilterState` | Collects per-column filter values and builds flat backend payloads. Supports text, select, and dateRange filters. Tracks `hasActiveFilters` and `activeFilterCount`. | +| `useColumnFilter` | Declarative filter config utilities: type guards (`isSelectFilter`, `isDateRangeFilter`), field resolution, options extraction. | + +### Interaction + +| Composable | Purpose | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `useTableRowReorder` | Drag-and-drop row reordering with live-swap at 50% vertical threshold. Commits via `dragend` (always fires) with `drop` as preferred path. | +| `useTableColumnsReorder` | Drag-and-drop column reordering with 50% horizontal threshold. Returns `getReorderHeadProps()` for easy binding. | +| `useTableColumnsResize` | Weight-based resize: dragging adjusts the weights of the dragged column and its right neighbor without touching other columns. DOM-based px updates during drag for smooth 60fps; commits new weights to `columnState` on mouseup. No `ResizeObserver` scaling. | +| `useTableSelectionV2` | Row selection: single, multiple (checkbox), and row-click modes. Emits `RowSelectEvent` / `RowSelectAllEvent`. | +| `useTableSwipe` | Mobile swipe context (provide/inject). Tracks which row has an active swipe action. | + +### Editing + +| Composable | Purpose | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `useTableEditing` | Cell-level and row-level editing (PrimeVue-style). Stores editing copies in `editingMeta` so typing does not trigger re-renders on the original data. | +| `useTableInlineEdit` | Bulk inline editing mode (all rows editable simultaneously). Different from `useTableEditing`. | +| `useCellBase` | Base composable for editable cell components: blur handling, display formatting, empty-state detection. | +| `useCellRegistry` | Registry pattern for cell type components (text, number, money, date, status, etc.). Register custom cell types at runtime. | + +### Layout + +| Composable | Purpose | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `useVirtualScroll` | Windowed rendering for large datasets. Renders only visible rows + buffer. Supports lazy loading, scroll-to-index, and debounced scroll events. | +| `useTableExpansion` | Expandable rows with O(1) key-based lookup. Toggle, expand-all, collapse-all. | +| `useTableRowGrouping` | Groups rows by field and inserts group header rows. | +| `useMobileCardLayout` | Mobile card view layout logic for responsive table display. | + +## useColumnWidthEngine + +`useColumnWidthEngine` is a collection of **pure functions** (no reactive state) for deterministic column width computation. `useTableColumns` calls these internally on every render pass and on container resize. + +### Core functions + +#### `computeColumnWidths(input: EngineInput): EngineOutput` + +The central engine. Distributes `availableWidth` among visible columns according to their current weights, enforcing `minWidth` / `maxWidth` constraints. + +```ts +interface EngineInput { + visibleIds: string[]; // Ordered list of visible column IDs + specs: Record<string, ColumnSpec>; // Per-column: weight, minWidth, maxWidth + availableWidth: number; // Container width in px + fitMode: "gap" | "fit"; // "gap" leaves filler space, "fit" fills width +} + +interface EngineOutput { + widths: Record<string, number>; // Computed px width per column ID + totalWidth: number; // Sum of all computed widths + overflow: boolean; // true when sum(minWidth) > availableWidth +} +``` + +In crisis (`overflow: true`), each column receives its `minWidth` regardless of weight, and a console warning is emitted. + +#### `parseColumnWidth(value: string | number | undefined, availableWidth: number): ParsedWidth` + +Parses a `VcColumn` `width` prop into a concrete pixel value. + +```ts +type ParsedWidth = + | { type: "px"; value: number } // "200", 200, "200px" + | { type: "pct"; value: number } // "20%" → 0.2 * availableWidth + | { type: "auto"; value: undefined }; // undefined, "auto" +``` + +#### `buildInitialWeights(parsed: ParsedWidth[], availableWidth: number): Record<string, number>` + +Converts an array of `ParsedWidth` values (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns. + +```ts +// Example: three columns — 200px, 20%, auto — with 800px available +// px-column → weight 200 +// pct-column → weight 160 (20% of 800) +// auto-column→ weight 440 (800 - 200 - 160) +``` + +#### `normalizeWeights(specs: Record<string, ColumnSpec>, visibleIds: string[]): void` + +Mutates `specs` in place so that the weights of `visibleIds` sum to 1.0. Called before a `"fit"` mode computation pass. + +### When weights update + +| User action | Weight change | +| --------------------------- | --------------------------------------------------------------------------------------- | +| Column resize (drag border) | Dragged column and right neighbor exchange weight proportionally | +| Column show/hide | Hidden column's weight is preserved; shown column uses saved or initial weight | +| Reset columns | All weights rebuilt from declarative `width` props | +| Container resize | Weights unchanged; engine recomputes px widths from same weights × new `availableWidth` | + +## Usage + +These composables are consumed internally by VcDataTable. If you need to interact with them, use VcDataTable's props and events: + +```vue +<VcDataTable :items="items" state-key="my-table" sort-field="name" :sort-order="1" removable-sort resizable-columns reorderable-columns :virtual-scroll="true" :virtual-scroll-item-size="48" edit-mode="cell" @sort="onSort" @cell-edit-complete="onCellEdit" @row:reorder="onReorder"> + <VcColumn field="name" header="Name" sortable :filter="true" /> + <VcColumn field="status" header="Status" :filter="{ options: statusOptions }" /> +</VcDataTable> +``` + +### Registering custom cell types + +```typescript +import { useCellRegistry } from "@vc-shell/framework"; + +const { register } = useCellRegistry(); +register({ + type: "rating", + component: CellRating, + config: { editable: false }, +}); +``` + +## Tips + +- `useTableColumns` never removes entries from `columnState` — hidden columns preserve their weight and order for when they reappear. Use `engineOutput` (not `columnState` directly) to read computed pixel widths for rendering. +- Call `recompute()` (returned by `useTableColumns`) whenever the container width changes to force the engine to redistribute widths without altering weights. +- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It auto-migrates v1 state (pixel-based) on the first restore. +- `useColumnWidthEngine` functions are pure — pass immutable copies of `specs` when testing or previewing layouts without committing to state. +- `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning. + + + +## Related + +- [VcDataTable](../../components/data-display/vc-data-table.md) -- the main consumer of these composables +- [VcColumn](../../components/data-display/vc-data-table.md) -- declarative column definitions + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useApiClient.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useApiClient.md new file mode 100644 index 0000000000..7281aee973 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useApiClient.md @@ -0,0 +1,305 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useApiClient/useApiClient.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useApiClient + +Creates a typed API client instance for communicating with VirtoCommerce platform APIs. The composable accepts a generated client class constructor and returns an async factory function that produces a configured, authenticated client. Base URL resolution and authentication token injection are handled automatically. + +!!! tip "Always call getApiClient inside async functions" +`getApiClient` is async. Never call it at the top level of `<script setup>` — always call it inside the async function you pass to `useAsync`. Storing the client in a variable outside the function gives you a stale reference when tokens rotate. + +## When to Use + +- Instantiate a generated VirtoCommerce API client with automatic authentication and base-URL resolution +- Pair with `useAsync` for loading/error state on every API call in a blade or composable +- When NOT to use: for third-party or non-platform APIs that do not extend `AuthApiBase` -- use `fetch` or Axios directly + +## Quick Start + +```typescript +<script setup lang="ts"> +import { useApiClient } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; + +const { getApiClient } = useApiClient(OrderClient); + +async function loadOrder(orderId: string) { + const client = await getApiClient(); + const order = await client.getOrderById(orderId); + return order; +} +</script> +``` + +## The useApiClient + useAsync Pattern + +The standard pattern for API calls in blades combines `useApiClient` with `useAsync`. This gives you automatic loading state, error handling, and a clean async action: + +```typescript +<script setup lang="ts"> +import { useApiClient, useAsync } from "@vc-shell/framework"; +import { ProductClient, Product } from "@api/catalog"; + +const { getApiClient } = useApiClient(ProductClient); + +const product = ref<Product>(); + +const { loading, error, action: loadProduct } = useAsync(async (id: string) => { + const client = await getApiClient(); + product.value = await client.getProductById(id); +}); + +const { loading: saving, action: saveProduct } = useAsync(async () => { + const client = await getApiClient(); + await client.updateProduct(product.value); +}); + +// Load on mount +onMounted(() => loadProduct(props.param)); +</script> + +<template> + <VcBlade :loading="loading"> + <!-- blade content --> + <template #toolbar> + <VcButton :loading="saving" @click="saveProduct">Save</VcButton> + </template> + </VcBlade> +</template> +``` + +The `loading` ref is `true` while the request is in-flight. The `error` ref captures any thrown error. The `action` function is the wrapped async function you call to trigger the request. + +## Multiple API Clients in One Blade + +When a blade needs data from multiple platform modules, create multiple client instances using destructuring aliases: + +```typescript +<script setup lang="ts"> +import { useApiClient, useAsync } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; +import { CustomerClient } from "@api/customers"; +import { InventoryClient } from "@api/inventory"; + +const { getApiClient: getOrderClient } = useApiClient(OrderClient); +const { getApiClient: getCustomerClient } = useApiClient(CustomerClient); +const { getApiClient: getInventoryClient } = useApiClient(InventoryClient); + +const { action: loadOrderDetails } = useAsync(async (orderId: string) => { + const orderClient = await getOrderClient(); + const customerClient = await getCustomerClient(); + + const order = await orderClient.getOrderById(orderId); + const customer = await customerClient.getCustomerById(order.customerId); + + return { order, customer }; +}); +</script> +``` + +## Search and Pagination + +API clients generated from VirtoCommerce platform endpoints follow a consistent search pattern with `SearchCriteria` objects: + +```typescript +<script setup lang="ts"> +import { useApiClient, useAsync } from "@vc-shell/framework"; +import { OrderClient, OrderSearchCriteria, OrderSearchResult } from "@api/orders"; + +const { getApiClient } = useApiClient(OrderClient); +const searchResult = ref<OrderSearchResult>(); + +const { loading, action: searchOrders } = useAsync(async (keyword?: string) => { + const client = await getApiClient(); + searchResult.value = await client.searchOrders({ + keyword, + skip: 0, + take: 20, + sort: "createdDate:DESC", + } as OrderSearchCriteria); +}); + +// Trigger search +searchOrders(); +</script> +``` + +## CRUD Operations Pattern + +A complete CRUD composable for a domain entity: + +```typescript +<script setup lang="ts"> +import { ref, onMounted } from "vue"; +import { useApiClient, useAsync, useToolbar } from "@vc-shell/framework"; +import { ProductClient, Product } from "@api/catalog"; + +const props = defineProps<{ param: string }>(); + +const { getApiClient } = useApiClient(ProductClient); +const { registerToolbarItem, updateToolbarItem } = useToolbar(); +const product = ref<Product>(); + +// Load +const { loading, action: load } = useAsync(async () => { + const client = await getApiClient(); + product.value = await client.getProductById(props.param); +}); + +// Save +const { loading: saving, action: save } = useAsync(async () => { + const client = await getApiClient(); + product.value = await client.updateProduct(product.value); +}); + +// Delete +const { loading: deleting, action: remove } = useAsync(async () => { + const client = await getApiClient(); + await client.deleteProducts([props.param]); +}); + +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + priority: 100, +}); + +registerToolbarItem({ + id: "refresh", + title: "Refresh", + icon: "fas fa-sync", + clickHandler: () => load(), + priority: 50, +}); + +watch([saving, deleting, loading], ([s, d, l]) => { + updateToolbarItem("save", { disabled: s || d || l }); +}); + +onMounted(() => load()); +</script> +``` + +## Recipes + +### Parallel API Requests + +When you need data from multiple endpoints simultaneously, use `Promise.all`: + +```typescript +const { action: loadDashboardData } = useAsync(async () => { + const orderClient = await getOrderClient(); + const customerClient = await getCustomerClient(); + + const [orders, customers] = await Promise.all([orderClient.searchOrders({ take: 5, sort: "createdDate:DESC" }), customerClient.searchCustomers({ take: 5, sort: "createdDate:DESC" })]); + + recentOrders.value = orders.results ?? []; + recentCustomers.value = customers.results ?? []; +}); +``` + +### Error Handling with User Feedback + +```typescript +import { useApiClient, useAsync, useNotifications } from "@vc-shell/framework"; + +const { getApiClient } = useApiClient(OrderClient); +const notification = useNotifications(); + +const { action: save } = useAsync(async () => { + try { + const client = await getApiClient(); + await client.updateOrder(order.value); + notification.success("Order saved successfully"); + } catch (e) { + notification.error("Failed to save order"); + throw e; // re-throw so useAsync captures it in the error ref + } +}); +``` + +## Common Mistakes + +### Calling getApiClient at the top level + +```typescript +// Wrong -- getApiClient is async, cannot be awaited at module scope +const client = await getApiClient(); // breaks setup flow + +async function loadData() { + const result = await client.search(); // stale client reference +} + +// Correct -- call getApiClient inside each async function +async function loadData() { + const client = await getApiClient(); + const result = await client.search(); +} +``` + +### Forgetting to alias when using multiple clients + +```typescript +// Wrong -- second destructuring shadows the first +const { getApiClient } = useApiClient(OrderClient); +const { getApiClient } = useApiClient(CustomerClient); // shadows! + +// Correct -- use destructuring aliases +const { getApiClient: getOrderClient } = useApiClient(OrderClient); +const { getApiClient: getCustomerClient } = useApiClient(CustomerClient); +``` + +### Using useApiClient for non-platform APIs + +```typescript +// Wrong -- useApiClient expects the IAuthApiBase contract +import { ExternalWeatherService } from "./weather"; +const { getApiClient } = useApiClient(ExternalWeatherService); // type error + +// Correct -- use fetch or axios directly for third-party APIs +const response = await fetch("https://api.weather.com/forecast"); +``` + +## API Reference + +### Parameters + +| Parameter | Type | Required | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ | +| `c` | `new (baseUrl?: string, http?: { fetch(url: RequestInfo, init?: RequestInit): Promise<Response> }) => ApiClient` | Yes | API client constructor class. Must implement `IAuthApiBase`. | + +### Returns: `UseApiClientReturn<ApiClient>` + +| Property | Type | Description | +| -------------- | -------------------------- | ---------------------------------------------------------------------- | +| `getApiClient` | `() => Promise<ApiClient>` | Async factory that returns a configured, authenticated client instance | + +### IAuthApiBase Interface + +All generated API client classes implement this interface: + +| Property / Method | Type | Description | +| ----------------- | ------------------------------------------------- | ----------------------------- | +| `authToken` | `string` | Current authentication token | +| `setAuthToken` | `(token: string) => void` | Sets the authentication token | +| `getBaseUrl` | `(defaultUrl: string, baseUrl: string) => string` | Resolves the API base URL | + +### Generated Client Classes + +API clients are generated from Swagger/OpenAPI specs using the `@vc-shell/api-client-generator` CLI tool. Each generated class: + +- Extends the `IAuthApiBase` contract +- Provides typed methods matching the platform API endpoints +- Accepts a `baseUrl` and optional `http` client in the constructor +- Automatically serializes/deserializes request and response bodies + +## Related + +- [`useAsync`](../utilities/useAsync.md) -- wraps async API calls with loading/error state management +- CLI API Client Generator (`@vc-shell/api-client-generator`) -- generates typed client classes from Swagger specs +- [`useToolbar`](../services/useToolbar.md) -- disable toolbar buttons during API calls using the loading ref +- [`useNotifications`](../notifications/useNotifications.md) -- display success/error messages after API operations diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssets.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssets.md new file mode 100644 index 0000000000..676ff48ba3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssets.md @@ -0,0 +1,141 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAssets/useAssets.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useAssets + +Handles file upload, removal, and editing for `ICommonAsset` arrays (images, documents, etc.). This composable encapsulates the platform's asset storage API, handling multipart form upload with batched concurrency (max 4 simultaneous uploads), sort-order assignment, URL decoding, and immutable array operations for remove and edit. It returns a new array from every operation rather than mutating in place, which plays well with Vue's reactivity system and makes undo/redo patterns straightforward. + +## When to Use + +- Upload files to the platform asset storage and get back `ICommonAsset` objects with URLs, sizes, and sort orders +- Remove assets from a local array before saving the parent entity +- Update asset metadata (alt text, sort order) or reorder the entire asset list +- When NOT to use: for non-platform asset storage, custom upload endpoints, or binary blob handling outside the vc-shell asset API + +## Quick Start + +```vue +<script setup lang="ts"> +import { useAssets } from "@vc-shell/framework"; +import { ref } from "vue"; +import type { ICommonAsset } from "@vc-shell/framework"; + +const { upload, remove, edit, loading } = useAssets(); +const assets = ref<ICommonAsset[]>([]); + +async function onFilesSelected(fileList: FileList) { + const maxSort = Math.max(0, ...assets.value.map((a) => a.sortOrder ?? 0)); + const newAssets = await upload(fileList, "catalog/products/images", maxSort); + assets.value = [...assets.value, ...newAssets]; +} + +function onDeleteAssets(toDelete: ICommonAsset[]) { + assets.value = remove(toDelete, assets.value); +} + +function onUpdateAltText(asset: ICommonAsset, altText: string) { + assets.value = edit([{ ...asset, altText }], assets.value); +} +</script> + +<template> + <VcBlade + title="Product Images" + :loading="loading" + > + <VcGallery + :assets="assets" + @upload="onFilesSelected" + @delete="onDeleteAssets" + /> + </VcBlade> +</template> +``` + +## API + +### Returns + +| Property | Type | Description | +| --------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `upload` | `(files: FileList, uploadPath: string, startingSortOrder?: number) => Promise<ICommonAsset[]>` | Upload files in parallel batches (max 4 concurrent). Returns only successfully uploaded assets. Sort orders are assigned incrementally from `startingSortOrder + 1`. | +| `remove` | `(filesToDelete: ICommonAsset[], initialAssetArr: ICommonAsset[]) => ICommonAsset[]` | Return a new array with deleted items removed. Matching is done by `url` field. The original array is not mutated. | +| `edit` | `(updatedFiles: ICommonAsset[], initialAssetArr: ICommonAsset[]) => ICommonAsset[]` | Merge updated fields into existing assets (matched by `url`). If `updatedFiles.length === initialAssetArr.length`, the entire array is replaced (reorder mode). | +| `loading` | `ComputedRef<boolean>` | Whether an upload or remove operation is currently in progress. | + +## How It Works + +### Upload Batching + +Files are uploaded in batches of 4 (`MAX_CONCURRENT_UPLOADS`). For example, if you select 10 files, the first 4 upload in parallel, then the next 4, then the remaining 2. This prevents overwhelming the server while still being much faster than sequential uploads. Each file is POSTed as `multipart/form-data` to `/api/assets?folderUrl=/{uploadPath}`. + +### Edit Detection: Reorder vs. Patch + +The `edit` function uses a simple heuristic: if `updatedFiles.length === initialAssetArr.length`, it assumes a reorder operation and returns `updatedFiles` directly (preserving their order). If only a subset is passed, it patches matching items in the original array by `url`, keeping the original order intact. + +### Immutability + +Both `remove` and `edit` use `lodash-es` `cloneDeep` to create a new array, so the original `initialAssetArr` is never modified. This is important because Vue's reactivity relies on reference changes to detect updates. + +## Recipe: Drag-and-Drop Reorder with Sort Order Update + +```typescript +import { useAssets } from "@vc-shell/framework"; + +const { edit } = useAssets(); +const assets = ref<ICommonAsset[]>([]); + +function onDragEnd(reorderedList: ICommonAsset[]) { + // Assign new sort orders based on position + const withNewSortOrders = reorderedList.map((asset, index) => ({ + ...asset, + sortOrder: index + 1, + })); + + // Because length matches, edit() treats this as a full reorder + assets.value = edit(withNewSortOrders, assets.value); +} +``` + +## Recipe: Upload with Progress Feedback + +```vue +<script setup lang="ts"> +import { useAssets } from "@vc-shell/framework"; +import { ref, watch } from "vue"; + +const { upload, loading } = useAssets(); +const assets = ref<ICommonAsset[]>([]); +const statusMessage = ref(""); + +watch(loading, (isLoading) => { + statusMessage.value = isLoading ? "Uploading files..." : ""; +}); + +async function handleUpload(files: FileList) { + statusMessage.value = `Uploading ${files.length} file(s)...`; + try { + const uploaded = await upload(files, "catalog/products/images"); + assets.value = [...assets.value, ...uploaded]; + statusMessage.value = `Successfully uploaded ${uploaded.length} file(s)`; + } catch (err) { + statusMessage.value = "Upload failed. Please try again."; + } +} +</script> +``` + +## Tips + +- **Sort order starts from `startingSortOrder + 1`.** If you pass `startingSortOrder: 5` and upload 3 files, they get sort orders 6, 7, and 8. Pass `0` or omit it to start from 1. +- **Failed uploads are silently filtered.** If one file in a batch fails, the others still succeed. The returned array only contains successfully uploaded assets. Check the browser console for error logs from the `use-assets` logger. +- **`remove` matches by `url`, not by `id`.** Assets may not have stable IDs before they are saved to the server. The `url` field is used as the matching key because it is always present after upload. +- **Each `useAssets()` call creates an independent instance.** Unlike singleton composables, calling `useAssets()` twice gives you two separate `loading` states. This is useful if different parts of your blade upload to different paths. + +## Related + +- `ICommonAsset` -- type imported from `@vc-shell/framework` +- `VcGallery` / `VcImageTile` -- UI components that consume asset arrays +- [`useAssetsManager`](./useAssetsManager.md) -- higher-level composable that wraps `useAssets` with two-way sync diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssetsManager.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssetsManager.md new file mode 100644 index 0000000000..c0b330bf53 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useAssetsManager.md @@ -0,0 +1,158 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAssetsManager/useAssetsManager.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useAssetsManager + +High-level composable for managing asset arrays (images, documents, files). Wraps upload, remove, reorder, and metadata editing operations, mutating a reactive ref directly — no manual wiring needed. + +Replaces the low-level `useAssets()` composable which required building handler objects manually. + +## When to Use + +- Manage a list of images/assets on an entity (product, offer, user profile, seller) +- Need upload, remove, reorder, and edit-metadata on an asset array +- Want to bind directly to `VcGallery` events without boilerplate + +## API + +```typescript +import { useAssetsManager } from "@vc-shell/framework"; + +const assets = useAssetsManager(ref, options); +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `source` | `Ref<AssetLike[] \| undefined \| null>` | Reactive ref to the asset array. Accepts `ref()`, `toRef()`, or `computed({ get, set })`. `undefined`/`null` values are treated as empty array. The composable holds an internal copy and syncs both ways. | +| `options` | `UseAssetsManagerOptions` | Configuration (see below) | + +### Options + +| Option | Type | Required | Description | +| --------------- | ----------------------------------- | -------- | ----------------------------------------------------------------------- | +| `uploadPath` | `() => string` | Yes | Upload destination path (function — evaluated at upload time) | +| `confirmRemove` | `() => Promise<boolean> \| boolean` | No | Called before remove. Return `false` to cancel. Omit for silent remove. | +| `assetKey` | `string` | No | Key for matching items (default: `"url"`) | +| `concurrency` | `number` | No | Max concurrent uploads (default: 4) | + +### Return (`UseAssetsManagerReturn`) + +| Property | Type | Description | +| ------------ | ---------------------------------------------------------------- | -------------------------------------------------------------- | +| `items` | `Ref<AssetLike[]>` | Reactive asset array (internal ref, safe to bind to templates) | +| `upload` | `(files: FileList, startingSortOrder?: number) => Promise<void>` | Upload files, append to array | +| `remove` | `(item: AssetLike) => Promise<void>` | Remove single item (with confirmation if configured) | +| `removeMany` | `(items: AssetLike[]) => Promise<void>` | Remove multiple items (one confirmation for batch) | +| `reorder` | `(items: AssetLike[]) => void` | Replace array with new order | +| `updateItem` | `(item: AssetLike) => void` | Update single item metadata by `assetKey` | +| `loading` | `ComputedRef<boolean>` | True during upload | + +## Usage Examples + +### Basic — gallery with confirmation + +```typescript +import { useAssetsManager } from "@vc-shell/framework"; +import { toRef } from "vue"; + +const assets = useAssetsManager( + computed({ + get: () => offer.value.images ?? [], + set: (val) => { + offer.value.images = val; + }, + }), + { + uploadPath: () => `offers/${offer.value?.id ?? "new"}`, + confirmRemove: () => showConfirmation(t("OFFERS.ALERTS.IMAGE_DELETE")), + }, +); +``` + +```html +<VcGallery + :images="assets.items.value" + @upload="assets.upload" + @sort="assets.reorder" + @remove="assets.remove" + @edit="onGalleryItemEdit" +/> +``` + +### Single image (photo/logo) + +Wrap a single value in a computed array: + +```typescript +const photoAssets = computed({ + get: () => (user.value?.iconUrl ? [{ url: user.value.iconUrl }] : []), + set: (val) => { + user.value!.iconUrl = val[0]?.url; + }, +}); + +const photo = useAssetsManager(photoAssets, { + uploadPath: () => `users/${user.value?.id}`, +}); +``` + +### Passing to AssetsManager blade + +When passing `useAssetsManager` through blade options, **always wrap with `markRaw()`**: + +```typescript +import { markRaw } from "vue"; +import { useBlade, useAssetsManager } from "@vc-shell/framework"; + +const { openBlade } = useBlade(); + +const assets = useAssetsManager(productAssetsRef, { + uploadPath: () => `/catalog/${product.value?.id}`, + confirmRemove: () => showConfirmation("Delete selected assets?"), +}); + +openBlade({ + name: "AssetsManager", + options: { + manager: markRaw(assets), // IMPORTANT: prevents reactive proxy unwrap + disabled: !canEdit.value, + }, +}); +``` + +**Why `markRaw`?** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects — so `manager.items` would become a plain array instead of `Ref<AssetLike[]>`, breaking `.value` access. `markRaw()` tells Vue to skip this object, keeping Refs intact. + +## Reactivity Model + +The composable holds an **internal ref** (`_items`) that is the source of truth for the UI: + +1. **Source → internal**: A `watch` syncs changes from the source ref (e.g., when parent reloads data) +2. **Mutations → internal → source**: Every operation (`upload`, `remove`, `reorder`, `updateItem`) updates `_items` first, then writes back to the source via `_sync()` + +This two-way sync avoids reactivity issues when the source is a `WritableComputed` wrapping deeply nested properties (e.g., `item.value.productData.assets`). + +## Types + +### `AssetLike` + +Minimal structural contract compatible with any domain image type: + +```typescript +interface AssetLike { + url?: string; + name?: string; + sortOrder?: number; + [key: string]: any; // compatible with Image, ProductImage, Asset, etc. +} +``` + +## Related + +- `VcGallery` -- gallery component that integrates with `useAssetsManager` events +- [`useAssets`](./useAssets.md) -- lower-level composable for manual upload/remove operations + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTablePagination.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTablePagination.md new file mode 100644 index 0000000000..b3b0fa8a98 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTablePagination.md @@ -0,0 +1,169 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/composables/useDataTablePagination.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useDataTablePagination + +Manages page-level pagination state for `VcDataTable`. Derives `pages`, `skip`, `totalCount` from a reactive input, and fires an optional `onPageChange` callback when the page changes. Returns a `reactive()` object — all properties are plain values (no `.value` needed), and the object is directly passable as the VcDataTable `:pagination` prop. + +Follows the same event-callback pattern as VueUse's `useOffsetPagination`. + +## When to Use + +- You are using `VcDataTable` with `:pagination` prop and `@pagination-click` event +- You want to eliminate the `Math.ceil` / `Math.floor` pagination boilerplate from data composables +- You want a single object to bind as `:pagination`, `:total-count`, and `@pagination-click` + +## When NOT to Use + +- You are using infinite scroll (`infiniteScroll` prop) — no pagination needed +- The table is client-side only with all items loaded — VcDataTable handles display internally + +## Basic Usage + +```typescript +import { useDataTablePagination } from "@vc-shell/framework"; + +const pagination = useDataTablePagination({ + pageSize: 20, + totalCount: computed(() => searchResult.value?.totalCount ?? 0), + onPageChange: ({ skip }) => loadItems({ ...searchQuery.value, skip }), +}); +``` + +```vue +<VcDataTable :items="items" :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" /> +``` + +## API + +### Parameters (Options) + +| Option | Type | Default | Description | +| -------------- | ------------------------------------------------- | ----------- | ------------------------------------------------ | +| `totalCount` | `MaybeRefOrGetter<number>` | _required_ | Total item count from API response | +| `pageSize` | `MaybeRefOrGetter<number>` | `20` | Items per page | +| `onPageChange` | `(state: { page: number; skip: number }) => void` | `undefined` | Event callback fired when `goToPage()` is called | + +### Returns (`reactive()` object) + +| Property | Type | Description | +| ------------- | ------------------------ | --------------------------------------------- | +| `currentPage` | `number` | Current 1-based page number (writable) | +| `pages` | `number` (readonly) | Total number of pages | +| `skip` | `number` (readonly) | Current skip offset for API calls | +| `pageSize` | `number` (readonly) | Resolved page size | +| `totalCount` | `number` (readonly) | Resolved total item count | +| `goToPage` | `(page: number) => void` | Navigate to page; fires `onPageChange` | +| `reset` | `() => void` | Reset to page 1; does NOT fire `onPageChange` | + +All properties are auto-unwrapped by `reactive()` — no `.value` access needed in script or template. + +## Recipe: Server-Side Paginated Table + +```vue +<script setup lang="ts"> +import { ref, computed } from "vue"; +import { useDataTablePagination, useDataTableSort } from "@vc-shell/framework"; + +// Data layer +const searchResult = ref<{ results: Item[]; totalCount: number }>(); +const searchQuery = ref({ take: 20, skip: 0 }); + +async function loadItems(query?: Partial<typeof searchQuery.value>) { + searchQuery.value = { ...searchQuery.value, ...query }; + searchResult.value = await api.search(searchQuery.value); +} + +// Pagination state +const pagination = useDataTablePagination({ + pageSize: 20, + totalCount: computed(() => searchResult.value?.totalCount ?? 0), + onPageChange: ({ skip }) => loadItems({ skip }), +}); + +// Sort state +const { sortField, sortOrder, sortExpression } = useDataTableSort({ + initialField: "createdDate", + initialDirection: "DESC", +}); +</script> + +<template> + <VcDataTable + :items="searchResult?.results ?? []" + :total-count="pagination.totalCount" + :pagination="pagination" + @pagination-click="pagination.goToPage" + v-model:sort-field="sortField" + v-model:sort-order="sortOrder" + > + <VcColumn + id="name" + header="Name" + sortable + /> + <VcColumn + id="createdDate" + header="Created" + sortable + /> + </VcDataTable> +</template> +``` + +## Recipe: Inside a Data Composable + +```typescript +// useOffers.ts +export function useOffers() { + const searchResult = ref<SearchOffersResult>(); + const searchQuery = ref<SearchOffersQuery>({ take: 20 }); + + const { action: loadOffers } = useAsync(async (query) => { + searchQuery.value = { ...searchQuery.value, ...query }; + searchResult.value = await client.searchOffers(searchQuery.value); + }); + + const pagination = useDataTablePagination({ + pageSize: 20, + totalCount: computed(() => searchResult.value?.totalCount ?? 0), + onPageChange: ({ skip }) => loadOffers({ ...searchQuery.value, skip }), + }); + + return { + offers: computed(() => searchResult.value?.results ?? []), + pagination, + loadOffers, + }; +} +``` + +Blade then simply binds: + +```vue +<VcDataTable :total-count="pagination.totalCount" :pagination="pagination" @pagination-click="pagination.goToPage" /> +``` + +## Details + +- **`reactive()` return**: The composable wraps its return in `reactive()`, so all `Ref`/`ComputedRef` properties are auto-unwrapped. Access with `pagination.pages` (not `pagination.pages.value`). This allows the object to be passed directly as `:pagination` prop to VcDataTable without intermediate conversion. +- **Event callback, not load**: `onPageChange` is an event notification (like VueUse's `useOffsetPagination`). The composable does not know about data fetching — it just notifies. +- **No auto-clamp**: When `totalCount` decreases (e.g. after deletion), `currentPage` is NOT automatically clamped. Call `reset()` or `goToPage(1)` explicitly after mutations. +- **reset() is silent**: `reset()` sets `currentPage = 1` but does NOT fire `onPageChange`. This prevents accidental double-fetches when the consumer resets pagination during a reload. +- **Pure without callback**: Omit `onPageChange` and the composable works as pure state — useful for unit tests or when the consumer prefers to watch properties reactively. +- **Why `reactive()` and not `ref()`**: Pagination is a cohesive group of properties always used together (`pagination.xxx`). `reactive()` is the Vue-idiomatic choice for such objects. `useDataTableSort` returns `ref()`s because its properties are destructured and used with `v-model` individually. + +## Tips + +- Call `pagination.reset()` alongside search/filter changes to return to page 1. +- Pair with `useDataTableSort` for the complete table state management story. +- The `skip` property can be used directly in API queries when not using `onPageChange`. +- Do NOT destructure properties: `const { pages } = pagination` loses reactivity. Always access via `pagination.pages`. + +## Related + +- [`useDataTableSort`](./useDataTableSort.md) -- sort state composable for VcDataTable +- `VcDataTable` `:pagination` prop -- accepts `DataTablePagination` object +- `DataTablePagination` -- type exported from `@vc-shell/framework` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTableSort.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTableSort.md new file mode 100644 index 0000000000..d1b8363b7e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useDataTableSort.md @@ -0,0 +1,148 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/composables/useDataTableSort.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useDataTableSort + +Manages page-level sort state for `VcDataTable` using numeric sort order conventions (`1` = ASC, `-1` = DESC, `0` = none). Provides `sortField` and `sortOrder` refs for `v-model` binding directly on `VcDataTable`, plus a `sortExpression` computed string for API calls. + +Use this composable when working with `VcDataTable` directly. For legacy `VcTable` (or `VcTableAdapter`) with `@header-click`, use [`useTableSort`](./useTableSort.md) instead. + +The sort expression is formatted as `"field:DIRECTION"` (e.g., `"createdDate:DESC"`), which is the standard format expected by VirtoCommerce Platform API endpoints. + +## When to Use + +- You are using `VcDataTable` with `v-model:sort-field` / `v-model:sort-order` +- You need to pass a `sortExpression` string to an API query +- You want to eliminate the three-ref boilerplate (`sortField`, `sortOrder`, `sortExpression`) from list blade pages +- You need a `resetSort()` helper (e.g., when search filters are cleared) + +## When NOT to Use + +- You are using `VcTable` / `VcTableAdapter` with `@header-click` — use `useTableSort` instead +- The table handles sorting internally and you do not need external sort state + +## Basic Usage + +```typescript +import { useDataTableSort } from "@vc-shell/framework"; + +const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({ + initialField: "createdDate", + initialDirection: "DESC", +}); +``` + +```vue +<VcDataTable v-model:sort-field="sortField" v-model:sort-order="sortOrder" :items="items"> + <VcColumn id="name" header="Name" sortable /> + <VcColumn id="createdDate" header="Created" sortable /> +</VcDataTable> +``` + +## API + +### Parameters (Options) + +| Option | Type | Default | Description | +| ------------------ | ----------------- | ----------- | --------------------------------- | +| `initialField` | `string` | `undefined` | Column field to sort by initially | +| `initialDirection` | `"ASC" \| "DESC"` | `undefined` | Initial sort direction | + +### Returns + +| Property | Type | Description | +| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------- | +| `sortField` | `Ref<string \| undefined>` | Current sort field; bind with `v-model:sort-field` | +| `sortOrder` | `Ref<number>` | Numeric sort order: `1` = ASC, `-1` = DESC, `0` = none; bind with `v-model:sort-order` | +| `sortExpression` | `ComputedRef<string \| undefined>` | Formatted string (e.g., `"name:ASC"`) or `undefined` when no sort is active | +| `resetSort` | `() => void` | Reset to the initial field/direction passed to the composable | + +## Direction Mapping + +| `sortOrder` value | Direction | `sortExpression` | +| ----------------- | --------- | ---------------- | +| `1` | ASC | `"field:ASC"` | +| `-1` | DESC | `"field:DESC"` | +| `0` | none | `undefined` | + +When `sortOrder` is `0`, `sortExpression` returns `undefined` regardless of `sortField`. + +## Recipe: Server-Side Sorted Table + +```vue +<script setup lang="ts"> +import { ref, watch } from "vue"; +import { useDataTableSort } from "@vc-shell/framework"; + +const { sortField, sortOrder, sortExpression, resetSort } = useDataTableSort({ + initialField: "createdDate", + initialDirection: "DESC", +}); + +const items = ref([]); +const loading = ref(false); + +async function loadItems() { + loading.value = true; + try { + const response = await api.searchProducts({ + sort: sortExpression.value, // e.g. "createdDate:DESC" or undefined + skip: 0, + take: 20, + }); + items.value = response.results; + } finally { + loading.value = false; + } +} + +// Reload whenever sort changes; { immediate: true } loads data on mount +watch(sortExpression, () => loadItems(), { immediate: true }); +</script> + +<template> + <VcDataTable + v-model:sort-field="sortField" + v-model:sort-order="sortOrder" + :items="items" + :loading="loading" + > + <VcColumn + id="name" + header="Name" + sortable + /> + <VcColumn + id="createdDate" + header="Created" + sortable + /> + <VcColumn + id="price" + header="Price" + sortable + /> + </VcDataTable> +</template> +``` + +## Details + +- **Sort expression format**: `sortExpression` returns `"field:DIRECTION"` when both `sortField` and a non-zero `sortOrder` are set, otherwise `undefined`. This format is directly compatible with VirtoCommerce Platform search endpoints. +- **Reset behavior**: `resetSort()` restores `sortField` and `sortOrder` to the values passed at construction time. If no initial options were provided, both are cleared. +- **Numeric order convention**: `VcDataTable` uses PrimeVue's numeric sort order convention (`1`/`-1`/`0`). This composable encapsulates the mapping so call sites never need to handle the numeric values directly. +- **Stateless regarding data**: The composable only manages the sort field and direction. Combine it with your own data-fetching logic using `watch(sortExpression, ...)`. + +## Tips + +- Always mark columns as `sortable` in your `<VcColumn>` definitions for the sort indicator icon to appear. +- Use `{ immediate: true }` on the `watch(sortExpression, ...)` call to trigger the initial data load with the correct sort on mount. +- Call `resetSort()` alongside any "clear all filters" action to keep sort state consistent with the rest of the filter UI. + +## Related + +- [`useTableSort`](./useTableSort.md) — equivalent composable for legacy `VcTable` / `VcTableAdapter` with `@header-click` +- `VcDataTable` — table component that accepts `v-model:sort-field` / `v-model:sort-order` +- `VcTableAdapter` — backward-compatible wrapper; use `useTableSort` with this component diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSelection.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSelection.md new file mode 100644 index 0000000000..507942bf72 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSelection.md @@ -0,0 +1,162 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/composables/useTableSelection.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useTableSelection + +Manages table row selection state including multi-select, select-all, and programmatic selection. This composable provides a complete external selection API for VcDataTable, enabling bulk operations like delete, export, or status changes on selected rows. + +Selection state is tracked by item objects and their extracted IDs, making it easy to pass selected IDs to API calls while also having access to the full item data for display purposes. + +## When to Use + +- Handle selection logic for VcTable/VcDataTable outside the table component +- Need selected IDs for bulk operations (delete, export, status change) +- Implement toolbar buttons that act on selected rows +- When NOT to use: if VcTable's built-in selection events are sufficient without external state management + +## Basic Usage + +```typescript +import { useTableSelection } from "@vc-shell/framework"; + +interface Product { + id: string; + name: string; +} + +const { selectedItems, selectedIds, hasSelection, handleSelectionChange, handleSelectAll, resetSelection } = useTableSelection<Product>(); + +// Wire to VcTable events +// <VcTable @selection-changed="handleSelectionChange" @select:all="handleSelectAll" /> + +// Bulk delete +async function deleteSelected() { + await api.bulkDelete(selectedIds.value); + resetSelection(); +} +``` + +## API + +### Parameters (Options) + +| Option | Type | Default | Description | +| --------- | -------------------------------- | ------- | ------------------------------------- | +| `idField` | `keyof T \| (item: T) => string` | `"id"` | Field or function to extract item IDs | + +### Returns + +| Property | Type | Description | +| ----------------------- | ----------------------------- | --------------------------------------------- | +| `selectedItems` | `Ref<T[]>` | Currently selected item objects | +| `selectedIds` | `ComputedRef<string[]>` | IDs extracted from selected items | +| `allSelected` | `Ref<boolean>` | Whether "select all" (across pages) is active | +| `selectionCount` | `ComputedRef<number>` | Number of selected items | +| `hasSelection` | `ComputedRef<boolean>` | Whether any items are selected | +| `handleSelectionChange` | `(items: T[]) => void` | Handler for `@selection-changed` | +| `handleSelectAll` | `(selected: boolean) => void` | Handler for `@select:all` | +| `resetSelection` | `() => void` | Clear all selection state | +| `isSelected` | `(item: T) => boolean` | Check if a specific item is selected | +| `selectItems` | `(items: T[]) => void` | Programmatically select items | +| `deselectByIds` | `(ids: string[]) => void` | Remove items from selection by ID | + +## Recipe: Bulk Action Toolbar + +A common list blade pattern is showing a toolbar with bulk actions when items are selected: + +```vue +<script setup lang="ts"> +import { useTableSelection } from "@vc-shell/framework"; +import { notification } from "@vc-shell/framework"; + +interface Order { + id: string; + number: string; + status: string; +} + +const { selectedItems, selectedIds, hasSelection, selectionCount, handleSelectionChange, resetSelection } = useTableSelection<Order>(); + +async function bulkChangeStatus(newStatus: string) { + await api.bulkUpdateStatus(selectedIds.value, newStatus); + notification(`${selectionCount.value} orders updated to ${newStatus}.`); + resetSelection(); + await reload(); +} + +async function bulkExport() { + const blob = await api.exportOrders(selectedIds.value); + downloadFile(blob, "orders.csv"); +} +</script> + +<template> + <div + v-if="hasSelection" + class="tw-flex tw-gap-2 tw-p-2 tw-bg-blue-50" + > + <span>{{ selectionCount }} selected</span> + <button @click="bulkChangeStatus('Approved')">Approve</button> + <button @click="bulkExport">Export CSV</button> + <button @click="resetSelection">Clear</button> + </div> + + <VcTable + :items="orders" + multiselect + @selection-changed="handleSelectionChange" + > + <VcColumn + id="number" + header="Order #" + /> + <VcColumn + id="status" + header="Status" + /> + </VcTable> +</template> +``` + +## Recipe: Custom ID Field + +When items use a non-standard identifier field, pass a custom `idField` option: + +```typescript +interface LegacyItem { + code: string; + name: string; +} + +// Using a field name +const selection = useTableSelection<LegacyItem>({ idField: "code" }); + +// Using a function for composite keys +interface CompositeItem { + orgId: string; + itemId: string; +} + +const selection2 = useTableSelection<CompositeItem>({ + idField: (item) => `${item.orgId}:${item.itemId}`, +}); +``` + +## Details + +- **ID extraction**: Uses the `idField` option (default `"id"`) to extract string IDs from items. If the field value is not a string, the item is skipped in `selectedIds`. Use a function extractor for non-string or composite keys. +- **Select-all flag**: `allSelected` is a separate boolean that indicates cross-page selection. When `handleSelectAll(false)` is called, it also clears `selectedItems`. The flag is automatically cleared when `handleSelectionChange` receives an empty array. +- **ID lookup performance**: Internally uses a `Set` for `isSelected` checks, providing O(1) lookup per item even with large selections. + +## Tips + +- Always call `resetSelection()` after a successful bulk operation to clear stale selections. +- The `allSelected` flag is a hint for server-side "select all across pages" behavior. You still need to handle the actual API call differently when `allSelected` is true (e.g., pass a filter instead of IDs). +- Combine with `useTableSort` and reset selection when sort changes, since the visible rows will change. + +## Related + +- `VcDataTable` -- emits `selection-changed` and `select:all` events +- `useTableSort` -- often used alongside selection for list blade patterns diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSort.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSort.md new file mode 100644 index 0000000000..a086aabe3d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/data/useTableSort.md @@ -0,0 +1,153 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/composables/useTableSort.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useTableSort + +Manages table sort state with three-state cycling (ASC, DESC, none) and a formatted sort expression string. This composable externalizes the sort logic from VcDataTable, making it easy to drive server-side sorting, persist sort preferences, or share sort state across multiple components. + +The sort expression is formatted as `"property:DIRECTION"` (e.g., `"createdDate:DESC"`), which is the standard format expected by VirtoCommerce Platform API endpoints. + +## When to Use + +- Control table sorting externally (e.g., pass `sortExpression` to an API query) +- Need to persist or share sort state across components +- Implement server-side sorting where the API handles data ordering +- When NOT to use: if VcTable's internal sort handling is sufficient and you do not need external sort state + +## Basic Usage + +```typescript +import { useTableSort } from "@vc-shell/framework"; + +const { sortExpression, handleSortChange, resetSort } = useTableSort({ + initialProperty: "createdDate", + initialDirection: "DESC", +}); + +// Wire to VcTable +// <VcTable :sort-expression="sortExpression" @header-click="handleSortChange" /> + +// Use in API calls +watch(sortExpression, (sort) => { + loadItems({ sort }); // e.g., "createdDate:DESC" +}); +``` + +## API + +### Parameters (Options) + +| Option | Type | Default | Description | +| ------------------ | ----------------- | ------- | ------------------------------------ | +| `initialProperty` | `string` | `null` | Column property to sort by initially | +| `initialDirection` | `"ASC" \| "DESC"` | `null` | Initial sort direction | + +### Returns + +| Property | Type | Description | +| ------------------ | ------------------------------------- | ----------------------------------------------------------------- | +| `currentSort` | `WritableComputedRef<TableSortState>` | Current `{ property, direction }` state | +| `sortExpression` | `Ref<string \| undefined>` | Formatted string (e.g., `"name:ASC"`) or `undefined` when no sort | +| `handleSortChange` | `(sortParam: string) => void` | Handle column header click; accepts `"field"` or `"field:DIR"` | +| `resetSort` | `() => void` | Reset to initial sort options (or clear if none) | + +### TableSortState + +```typescript +interface TableSortState { + property: string | null; + direction: "ASC" | "DESC" | null; +} +``` + +## Sort Cycling + +When clicking the same column without an explicit direction: + +1. First click: `ASC` +2. Second click: `DESC` +3. Third click: sort cleared (`undefined`) + +When clicking a new column, defaults to `ASC`. + +When the sort parameter includes an explicit direction (e.g., `"name:DESC"`), the direction is applied directly without cycling. + +## Recipe: Server-Side Sorted Table with Loading State + +```vue +<script setup lang="ts"> +import { ref, watch } from "vue"; +import { useTableSort } from "@vc-shell/framework"; + +const { sortExpression, handleSortChange, resetSort } = useTableSort({ + initialProperty: "createdDate", + initialDirection: "DESC", +}); + +const items = ref([]); +const loading = ref(false); + +async function loadItems() { + loading.value = true; + try { + const response = await api.searchProducts({ + sort: sortExpression.value, // "createdDate:DESC" + skip: 0, + take: 20, + }); + items.value = response.results; + } finally { + loading.value = false; + } +} + +// Reload when sort changes +watch(sortExpression, () => loadItems(), { immediate: true }); +</script> + +<template> + <VcTable + :items="items" + :loading="loading" + :sort-expression="sortExpression" + @header-click="handleSortChange" + > + <VcColumn + id="name" + header="Name" + sortable + /> + <VcColumn + id="createdDate" + header="Created" + sortable + /> + <VcColumn + id="price" + header="Price" + sortable + /> + </VcTable> +</template> +``` + +## Details + +- **Sort expression format**: The `sortExpression` computed returns `"property:DIRECTION"` when active, or `undefined` when no sort is applied. This format is directly compatible with VirtoCommerce Platform search endpoints. +- **Writable computed**: `currentSort` is a `WritableComputedRef`, so you can set it programmatically: `currentSort.value = { property: "name", direction: "ASC" }`. +- **Reset behavior**: `resetSort()` returns to the initial options passed to the composable. If no initial options were provided, it clears the sort entirely. +- **handleSortChange format**: Accepts either `"fieldName"` (triggers cycling) or `"fieldName:DIR"` (sets explicit direction). VcDataTable's `@header-click` event emits in the latter format when the adapter encodes direction. + +## Tips + +- Always mark columns as `sortable` in your VcColumn definitions for the sort indicator icon to appear. +- When implementing server-side sorting, use `watch(sortExpression, ...)` with `{ immediate: true }` to load data with the initial sort on mount. +- The composable is stateless regarding the table data itself -- it only manages the sort property and direction. Combine with your own data-fetching logic. + +## Related + +- `VcDataTable` -- emits header-click events consumed by `handleSortChange` +- `VcTableAdapter` -- adapts legacy sort prop format +- `useTableSelection` -- often used alongside sort for list blade patterns diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/.pages new file mode 100644 index 0000000000..f742a9ec53 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/.pages @@ -0,0 +1,7 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Forms +nav: + - useBladeForm: useBladeForm.md + - useDynamicProperties: useDynamicProperties.md + - useModificationTracker: useModificationTracker.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useBladeForm.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useBladeForm.md new file mode 100644 index 0000000000..ea276020c8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useBladeForm.md @@ -0,0 +1,172 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBladeForm/useBladeForm.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBladeForm + +Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable. + +## Import + +```ts +import { useBladeForm } from "@vc-shell/framework"; +``` + +## Basic Usage + +```ts +const { item, loadItem, saveItem } = useItemData(); + +const form = useBladeForm({ data: item }); + +onMounted(async () => { + await loadItem({ id: param.value }); + form.setBaseline(); // snapshot current data as pristine +}); + +// Toolbar +const toolbar = ref<IBladeToolbar[]>([ + { + id: "save", + title: "Save", + icon: "lucide-save", + disabled: computed(() => !form.canSave.value), + async clickHandler() { + await saveItem(item.value); + form.setBaseline(); // snapshot after save + callParent("reload"); + }, + }, +]); +``` + +## API + +### Options + +| Option | Type | Default | Description | +| --------------------- | --------------------------------- | -------- | --------------------------------- | +| `data` | `Ref<T>` | required | Reactive data object for the form | +| `canSaveOverride` | `ComputedRef<boolean>` | — | Additional condition for canSave | +| `autoBeforeClose` | `boolean \| ComputedRef<boolean>` | `true` | Close guard behavior | +| `autoBeforeUnload` | `boolean` | `true` | Browser tab close guard | +| `closeConfirmMessage` | `MaybeRefOrGetter<string>` | — | Custom unsaved changes message | +| `onRevert` | `() => void \| Promise<void>` | — | Custom revert handler | + +### Returns + +| Property | Type | Description | +| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `setBaseline()` | `() => void` | Snapshot current data as pristine. Call after load and after save | +| `markReady()` | `() => void` | Mark form ready without resetting pristine snapshot. Computes modification state from current data vs setup-time snapshot | +| `revert()` | `() => void \| Promise<void>` | Revert data to pristine (or call onRevert) | +| `canSave` | `ComputedRef<boolean>` | `isReady && valid && modified && canSaveOverride` | +| `isModified` | `ComputedRef<boolean>` | Data differs from pristine (false until setBaseline) | +| `isReady` | `ComputedRef<boolean>` | setBaseline() called at least once | +| `formMeta` | vee-validate meta | Form validation state | +| `setFieldError` | function | Set field error programmatically | +| `errorBag` | Ref | All field errors | + +## Lifecycle + +### Standard (edit existing entity) + +``` +Mount → Load data → setBaseline() → User edits → Save → setBaseline() + └→ Cancel → revert() +``` + +### Pre-filled (create from template) + +``` +Mount → Pre-fill data → markReady() → canSave = true immediately + └→ Save → setBaseline() +``` + +## VcBlade Integration + +`useBladeForm` auto-provides form state to `VcBlade` via inject. No need to pass `:modified` prop: + +```vue +<!-- Before --> +<VcBlade :modified="isModified" :toolbar-items="toolbar"> + +<!-- After --> +<VcBlade :toolbar-items="toolbar"> +``` + +## Advanced: Readonly Blade + +```ts +const disabled = computed(() => !!param.value && !item.value?.canBeModified); + +const form = useBladeForm({ + data: item, + canSaveOverride: computed(() => !disabled.value), + autoBeforeClose: computed(() => !disabled.value), // no prompt when readonly +}); +``` + +## Advanced: Custom Revert + +```ts +const form = useBladeForm({ + data: item, + onRevert: () => loadItem({ id: param.value }), // reload from server +}); +``` + +## Advanced: Pre-filled Entity (markReady) + +When creating a new entity that is pre-populated from a parent (e.g. new offer from a product), the form should be immediately saveable. Use `markReady()` instead of `setBaseline()`: + +```ts +const form = useBladeForm({ data: item }); + +onMounted(async () => { + // Populate base fields + item.value.sku = generateSku(); + await addEmptyInventory(); + + const hasTemplate = !param.value && !!options.value?.templateId; + + if (hasTemplate) { + // Fill from template — data diverges from the setup-time snapshot + await fillFromTemplate(options.value.templateId); + // Mark ready: compares current data to setup-time snapshot → isModified = true + form.markReady(); + } else { + // Standard load — current state becomes the pristine baseline + await loadItem({ id: param.value }); + form.setBaseline(); + } +}); +``` + +### setBaseline vs markReady + +| | `setBaseline()` | `markReady()` | +| ------------------------------ | --------------------------------------- | --------------------------------------------------- | +| Sets `isReady` | yes | yes | +| Updates pristine snapshot | yes (current data → pristine) | no (keeps setup-time snapshot) | +| `trackerIsModified` after call | `false` | computed: `data !== pristineSnapshot` | +| Use case | Load / Save — "this is the clean state" | Pre-fill — "form is ready, changes are intentional" | + +### How it works + +At composable creation, `useBladeForm` takes a snapshot of `data` (the **setup-time snapshot**). When `markReady()` is called: + +1. `isReady` → `true` (gates `canSave` and subsequent edit tracking) +2. Modification state is computed by comparing the current data to the setup-time snapshot — since data was mutated during `onMounted`, `isModified` evaluates to `true` +3. Subsequent edits are tracked normally by the deep watcher + +After save, call `setBaseline()` as usual to capture the saved state as the new pristine snapshot. + +## Constraints + +- **Must be called from component `setup()`** (or `<script setup>`). Do NOT call from shared data-composables. +- Validation rules stay in template (`<Field rules="...">`). +- `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useDynamicProperties.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useDynamicProperties.md new file mode 100644 index 0000000000..175dc001f8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useDynamicProperties.md @@ -0,0 +1,165 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useDynamicProperties/useDynamicProperties.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useDynamicProperties + +Composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types. + +Internally uses a strategy pattern — each property type (regular, boolean, dictionary, measure, color) has a dedicated handler with `get`/`set` methods. + +## When to Use + +- In product, category, or any entity detail blades that display platform dynamic properties +- When properties are defined at runtime (not compile-time) and may be multilanguage or dictionary-based +- When you need to render and edit property values that can be text, boolean, number, datetime, dictionary selection, color picker, or measurement with units +- When NOT to use: for static, compile-time form fields, use standard Vue reactive state + +## Quick Start + +```typescript +import { useDynamicProperties } from "@vc-shell/framework"; + +const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements, loading } = useDynamicProperties({ + searchDictionary: (criteria) => api.searchPropertyDictionaryItems(criteria), + searchMeasurements: (measureId, locale) => api.searchMeasurements(measureId, locale), +}); +``` + +## API + +### Options + +| Option | Type | Required | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | +| `searchDictionary` | `(criteria: IBasePropertyDictionaryItemSearchCriteria) => Promise<IBasePropertyDictionaryItem[] \| undefined>` | Yes | API function to search dictionary items by property ID and keyword | +| `searchMeasurements` | `(measureId: string, locale?: string) => Promise<IBaseMeasurementDictionaryItem[] \| undefined>` | No | API function for loading measurement units. Only needed for measure-type properties | + +### Returns + +| Property | Type | Description | +| ------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `getPropertyValue` | `(property, locale) => PropertyDisplayValue` | Read display value for a property. Returns string, boolean, or array depending on type. Does NOT mutate the property. | +| `setPropertyValue` | `(params: SetPropertyValueParams) => void` | Write value to a property. Handles type-specific transformation and empty cleanup. | +| `loadDictionaries` | `(propertyId, keyword?, locale?) => Promise<...>` | Load dictionary items. If locale is provided, resolves localized values. | +| `loadMeasurements` | `(measureId, keyword?, locale?) => Promise<...>` | Load measurement units. No-op if `searchMeasurements` was not provided. | +| `loading` | `ComputedRef<boolean>` | Whether a dictionary lookup is in progress. | + +### SetPropertyValueParams + +| Field | Type | Description | +| ----------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| `property` | `IBaseProperty` | The property object to update. Modified in place. | +| `value` | `string \| IBasePropertyValue[] \| (IBasePropertyDictionaryItem & { value: string })[]` | The new value. Type depends on property configuration. | +| `dictionary` | `IBasePropertyDictionaryItem[]?` | Dictionary items. Required when setting a dictionary value. | +| `locale` | `string?` | Current locale for multilanguage properties. | +| `unitOfMeasureId` | `string?` | Unit of measure ID for measure-type properties. | +| `colorCode` | `string?` | Color hex code for color-type properties. | + +### PropertyDisplayValue + +```ts +type PropertyDisplayValue = string | IBasePropertyValue[] | boolean; +``` + +## How It Works + +### Strategy Resolution + +The composable resolves a strategy handler based on property flags: + +| Priority | Condition | Strategy | Handles | +| -------- | -------------------------------------- | ------------------ | ---------------------------------------------- | +| 1 | `valueType === "Measure"` | measureStrategy | Numeric input with unit dropdown | +| 2 | `valueType === "Color"` && !dictionary | colorStrategy | Color picker, multivalue colors | +| 3 | `valueType === "Boolean"` | booleanStrategy | Checkbox/switch | +| 4 | `dictionary === true` | dictionaryStrategy | Select dropdowns with localized options | +| 5 | (default) | regularStrategy | ShortText, LongText, Number, Integer, DateTime | + +### Value Getting + +Each strategy's `get()` reads from `property.values` without mutation: + +- **Multilanguage**: Finds value matching locale, falls back to value without languageCode +- **Multivalue**: Returns full array (filtered by locale for multilanguage) +- **Dictionary**: Returns `valueId` instead of `value` +- **Boolean**: Returns `false` (not `""`) when no value exists + +### Value Setting + +Each strategy's `set()` writes to `property.values`: + +- **Empty values are cleaned up automatically** via `cleanEmptyValues()`. When user clears a field, scaffolding objects are removed and `property.values` becomes `[]`. This prevents false modification detection in `useBladeForm`. +- **Multilanguage cleanup**: Only the value for the current locale is removed; other locales are preserved. +- **Dictionary**: Expands `localizedValues` into per-locale value entries. + +### Empty Value Cleanup (cleanEmptyValues) + +When `setPropertyValue` receives an empty value (`""`, `null`, `undefined`), it cleans up `property.values` instead of leaving scaffolding objects: + +``` +Before: values: [{ value: "", languageCode: "en", propertyId: "abc", ... }] +After: values: [] +``` + +This ensures that `useBladeForm`'s deep comparison correctly detects "no change" when user clears a field that was originally empty. + +## Recipe: With VcDynamicProperty + +```vue +<template> + <VcDynamicProperty + v-for="property in properties" + :key="property.id" + :property="property" + :model-value="getPropertyValue(property, currentLocale)" + :options-getter="loadDictionaries" + :measurements-getter="loadMeasurements" + :current-language="currentLocale" + :value-type="property.valueType ?? ''" + :dictionary="property.dictionary" + :multivalue="property.multivalue" + :multilanguage="property.multilanguage" + @update:model-value="(ev) => setPropertyValue({ property, ...ev })" + /> +</template> + +<script setup lang="ts"> +import { useDynamicProperties } from "@vc-shell/framework"; + +const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements } = useDynamicProperties({ + searchDictionary: searchDictionaryItems, + searchMeasurements: searchMeasurementItems, +}); +</script> +``` + +## Tips + +- **`setPropertyValue` mutates the property in place.** `property.values` is modified directly. This is by design because dynamic properties are typically part of a larger entity object saved as a whole. +- **Always pass `dictionary` when setting dictionary values.** Without dictionary items, the composable cannot resolve `valueId` to the correct alias and localized values. +- **Boolean properties always have a value entry.** Unlike other types where clearing removes the value, boolean properties maintain a value entry (`value: false`). This ensures checkboxes render correctly. +- **No class constructors needed.** Values are created as plain objects via `createValue()`. No factory classes required. + +## File Structure + +``` +useDynamicProperties/ + index.ts — composable entry point (~60 lines) + types.ts — all interfaces + utils.ts — isEmptyValue, createValue, cleanEmptyValues, type guards + strategies/ + index.ts — resolveStrategy() registry + types.ts — PropertyValueStrategy interface + regular.ts — ShortText, LongText, Number, Integer, DateTime + boolean.ts — Boolean + dictionary.ts — Dictionary (all multi/single × language/value) + measure.ts — Measure + color.ts — Color +``` + +## Related + +- [useBladeForm](./useBladeForm.md) — form state management that uses `semanticEqual` for modification detection. `cleanEmptyValues` ensures compatibility. +- [VcDynamicProperty](../../../../ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md) — UI component that renders dynamic properties diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useModificationTracker.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useModificationTracker.md new file mode 100644 index 0000000000..c73f96b3e0 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/forms/useModificationTracker.md @@ -0,0 +1,134 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useModificationTracker/useModificationTracker.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useModificationTracker + +Tracks deep changes to a value and reports whether it has been modified compared to its original (pristine) state. This is the core composable behind the "unsaved changes" detection pattern in vc-shell blades. It handles complex nested objects, arrays, and the common API quirk where `null`, `undefined`, and `""` should be treated as equivalent empty values. + +The composable maintains two copies of the data: the `pristineValue` (the clean baseline) and the `currentValue` (the working copy bound to form fields). Any deep difference between the two sets `isModified` to `true`. + +## When to Use + +- Detect unsaved changes in blade forms to enable/disable save buttons or show confirmation dialogs +- Track modifications to complex nested objects (arrays, nested properties) +- Pair with `useBeforeUnload` to prevent the browser tab from closing with unsaved changes +- When NOT to use: for simple boolean flags (a plain `ref` is sufficient) + +## Basic Usage + +```typescript +import { useModificationTracker } from "@vc-shell/framework"; + +// With a static initial value +const { currentValue, isModified, resetModificationState } = useModificationTracker({ name: "", price: 0 }); + +// With a reactive source (e.g., data loaded from API) +const { currentValue, isModified, resetModificationState } = useModificationTracker(apiData); +// currentValue updates automatically when apiData changes (if user hasn't modified it yet) + +// Bind to form +// <input v-model="currentValue.name" /> + +// After save +resetModificationState(); // currentValue becomes the new pristine baseline +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| ------------------ | ------------- | -------- | -------------------------------------- | +| `initialValueProp` | `T \| Ref<T>` | Yes | Initial value or reactive ref to track | + +### Returns + +| Property | Type | Description | +| ------------------------ | ------------------------------------- | ---------------------------------------------------------- | +| `currentValue` | `Ref<T>` | The working value (bind to v-model) | +| `pristineValue` | `Ref<T>` | The "clean" baseline value | +| `isModified` | `DeepReadonly<Ref<boolean>>` | `true` when `currentValue` differs from `pristineValue` | +| `resetModificationState` | `(newBaseline?: T \| Ref<T>) => void` | Reset modification tracking; optionally set a new baseline | + +## Recipe: Blade with Save/Discard and Unsaved Changes Guard + +```vue +<script setup lang="ts"> +import { ref, watch } from "vue"; +import { useModificationTracker } from "@vc-shell/framework"; +import { useBeforeUnload } from "@vueuse/core"; + +// Simulate API data loaded into a ref +const apiData = ref({ name: "Widget A", price: 19.99, tags: ["sale"] }); + +const { currentValue, isModified, resetModificationState } = useModificationTracker(apiData); + +// Prevent browser tab close when there are unsaved changes +useBeforeUnload(isModified); + +async function save() { + await api.update(currentValue.value); + // After a successful save, the current state becomes the new baseline + resetModificationState(); +} + +function discard() { + // Reset currentValue back to the pristine baseline + resetModificationState(apiData.value); +} +</script> + +<template> + <VcBlade title="Edit Widget"> + <input v-model="currentValue.name" /> + <input v-model.number="currentValue.price" /> + + <div class="tw-flex tw-gap-2"> + <button + :disabled="!isModified" + @click="save" + > + Save + </button> + <button + :disabled="!isModified" + @click="discard" + > + Discard + </button> + </div> + </VcBlade> +</template> +``` + +## Recipe: Reset to a New Baseline After Server Response + +When the server returns a transformed version of the saved entity (e.g., with computed fields populated), pass it to `resetModificationState` so the tracker uses the server response as the new clean state: + +```typescript +async function save() { + const saved = await api.update(currentValue.value); + // Use the server response as the new baseline, not the local currentValue + resetModificationState(saved); +} +``` + +## Details + +- **Semantic empty-value normalization**: `null`, `undefined`, and `""` are treated as equal during comparison. This prevents false positives when an API returns `null` for a field that the form initializes as `""` or `undefined`. +- **Reactive source tracking**: When `initialValueProp` is a `Ref` and changes externally, `pristineValue` updates automatically. If the user has not yet modified `currentValue`, it also updates to match. If the user has already made changes, only `pristineValue` updates (preserving the user's edits), and `isModified` remains `true`. +- **Deep cloning**: All values are deep-cloned via `lodash-es/cloneDeep` to prevent shared references between pristine and current copies. +- **Synchronous reset**: `resetModificationState` sets `isModified` to `false` synchronously in the same tick. This is important for `onBeforeClose` guards that check `isModified` immediately after calling reset. + +## Tips + +- Always bind form fields to `currentValue`, never to `pristineValue`. The pristine copy is read-only and represents the "last saved" state. +- When using with `useBeforeUnload`, pass `isModified` directly -- it is already a ref-compatible value. +- For arrays of items (e.g., order lines), edits to individual elements are detected because the watcher uses `{ deep: true }`. +- If your form has multiple independent sections, consider using separate `useModificationTracker` instances for each section, and combine their `isModified` flags with a computed. + +## Related + +- `useBeforeUnload` -- pair with `isModified` to prevent tab close on unsaved changes diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/.pages new file mode 100644 index 0000000000..597e2cfab8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/.pages @@ -0,0 +1,6 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Notifications +nav: + - useNotifications: useNotifications.md + - usePopup: usePopup.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/useNotifications.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/useNotifications.md new file mode 100644 index 0000000000..72ee21db02 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/useNotifications.md @@ -0,0 +1,159 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useNotifications/useNotifications.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useNotifications + +Provides access to the push-notification system: reading notification history, filtering by type, marking as read, and registering handlers for real-time notifications. This composable wraps the Pinia-based `useNotificationStore` and adds type-based filtering and subscription management. It subscribes to specific notification types via the store's pub/sub system and automatically unsubscribes when the component scope is disposed. + +**Deprecated**: Use `useBladeNotifications()` for blade-level subscriptions or `useNotificationStore()` for direct store access. This composable remains for backward compatibility but emits a deprecation warning in development mode. + +## When to Use + +- Legacy code that needs to subscribe to specific notification types and handle them with a callback +- Quick prototyping where you want to react to real-time notifications without the blade lifecycle +- When NOT to use: in new code, prefer `useBladeNotifications()` which integrates with blade lifecycle and provides automatic cleanup, or `useNotificationStore()` for direct Pinia access + +## Quick Start + +```typescript +import { useNotifications } from "@vc-shell/framework"; + +// Subscribe to specific notification types +const { notifications, moduleNotifications, loadFromHistory, markAsRead, markAllAsRead, setNotificationHandler } = useNotifications("OrderStatusChanged"); + +// Register a handler for real-time notifications +setNotificationHandler((notification) => { + console.log("Order status changed:", notification); + refreshOrderList(); +}); + +// Load historical notifications on mount +onMounted(() => loadFromHistory(50)); +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| ------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `notifyType` | `string \| string[]` | No | Notification type(s) to subscribe to (e.g., `'OrderStatusChanged'` or `['OrderCreated', 'OrderCancelled']`). Omit to receive all notifications. | + +### Returns + +| Property | Type | Description | +| ------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `notifications` | `ComputedRef<PushNotification[]>` | All notification history, sorted newest first. Includes both read and unread. | +| `moduleNotifications` | `ComputedRef<PushNotification[]>` | New real-time notifications matching the subscribed types. Only includes items where `isNew` is `true`. | +| `loadFromHistory` | `(take?: number) => Promise<void>` | Loads notification history from the server. `take` controls how many to fetch. | +| `addNotification` | `(message: PushNotification) => void` | Manually ingests a notification into the store (e.g., for testing or synthetic events). | +| `markAsRead` | `(message: PushNotification) => void` | Marks a single notification as read. | +| `markAllAsRead` | `() => void` | Marks all notifications as read. | +| `setNotificationHandler` | `(handler: (notification: PushNotification) => void) => void` | Registers a callback for incoming real-time notifications matching subscribed types. Only one handler per composable instance. | + +## How It Works + +1. **Subscription**: If `notifyType` is provided, the composable calls `store.subscribe({ types, handler })` to register for those notification types. The subscription returns an `unsub` function. + +2. **Handler dispatch**: When a real-time notification arrives that matches the subscribed types, the store calls the handler. The composable forwards this to whatever function was registered via `setNotificationHandler`. + +3. **Cleanup**: If the composable is called inside an effect scope (which it always is inside a component), `onScopeDispose` automatically calls the `unsub` function. + +4. **Module notifications**: The `moduleNotifications` computed filters the store's real-time queue for items that are new (`isNew: true`) and match the subscribed types. + +5. **History**: `loadFromHistory` delegates to the store, which fetches from the platform API and merges into the local history. + +## Recipe: Notification Panel with Real-Time Updates + +```vue +<script setup lang="ts"> +import { useNotifications } from "@vc-shell/framework"; +import { onMounted } from "vue"; + +const { notifications, moduleNotifications, loadFromHistory, markAsRead, markAllAsRead, setNotificationHandler } = useNotifications(["OrderCreated", "OrderStatusChanged", "OrderCancelled"]); + +// Play a sound on new notifications +setNotificationHandler((notification) => { + const audio = new Audio("/sounds/notification.mp3"); + audio.play().catch(() => {}); +}); + +onMounted(() => loadFromHistory(100)); +</script> + +<template> + <div class="notification-panel"> + <div class="tw-flex tw-justify-between tw-items-center tw-p-2"> + <span class="tw-font-semibold"> Notifications ({{ moduleNotifications.length }} new) </span> + <VcButton + size="sm" + variant="ghost" + @click="markAllAsRead" + > + Mark all read + </VcButton> + </div> + + <div + v-for="item in notifications" + :key="item.id" + class="tw-p-2 tw-border-b" + > + <div class="tw-flex tw-justify-between"> + <span :class="{ 'tw-font-bold': item.isNew }"> + {{ item.title }} + </span> + <VcButton + v-if="item.isNew" + size="xs" + variant="ghost" + @click="markAsRead(item)" + > + Mark read + </VcButton> + </div> + <p class="tw-text-sm tw-text-gray-500">{{ item.description }}</p> + </div> + </div> +</template> +``` + +## Recipe: Auto-Refresh Data on Notification + +```vue +<script setup lang="ts"> +import { useNotifications } from "@vc-shell/framework"; +import { onMounted } from "vue"; + +const { setNotificationHandler } = useNotifications("InventoryChanged"); + +const items = ref<InventoryItem[]>([]); + +async function refreshInventory() { + items.value = await api.getInventory(); +} + +// Automatically refresh when inventory changes +setNotificationHandler(() => { + refreshInventory(); +}); + +onMounted(refreshInventory); +</script> +``` + +## Tips + +- **Deprecation warning in dev mode.** When you call `useNotifications()`, a warning is logged in development mode pointing you to `useBladeNotifications()`. This is informational only and does not affect functionality. +- **Only one handler per instance.** Calling `setNotificationHandler` a second time replaces the previous handler. If you need multiple handlers, orchestrate them in a single callback function. +- **`moduleNotifications` only shows new items.** Once a notification is marked as read, it disappears from `moduleNotifications` but remains in `notifications` (the full history). +- **Type filtering is case-sensitive.** The `notifyType` string must exactly match the notification's `notifyType` field from the platform. Common types include `'OrderStatusChanged'`, `'IndexationProgress'`, etc. +- **No types means no `moduleNotifications`.** If you omit the `notifyType` parameter, `moduleNotifications` is always an empty array. Use `notifications` for the full unfiltered history. + +## Related + +- [useBladeNotifications](../useBladeNotifications/) -- preferred replacement with blade lifecycle integration +- `useNotificationStore()` -- direct Pinia-based store access for full control +- `MIGRATION_GUIDE.md#notifications` -- migration guide from useNotifications to useBladeNotifications diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/usePopup.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/usePopup.md new file mode 100644 index 0000000000..b49b380a1f --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/notifications/usePopup.md @@ -0,0 +1,211 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/usePopup/usePopup.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# usePopup + +Programmatic popup management for modal dialogs. Returns methods to open confirmation, error, and info dialogs, as well as fully custom popup components with typed props and emits. Popups are rendered in a dedicated container at the app root level, ensuring they overlay all other content including blades and sidebars. + +!!! tip "Always await showConfirmation" +`showConfirmation` returns a `Promise<boolean>`. Always `await` it before executing the guarded action, or the action will run before the user responds. + +## When to Use + +- Show confirmation dialogs before destructive actions (delete, discard, bulk operations) +- Display error or info messages in a modal overlay +- Open custom popup components with typed props and emits +- When NOT to use: for passive feedback (use `notification()` toast instead), for navigation flows (use blade navigation instead) + +## Quick Start + +```vue +<script setup lang="ts"> +import { usePopup } from "@vc-shell/framework"; + +const { showConfirmation, showError } = usePopup(); + +async function deleteProduct(id: string) { + const confirmed = await showConfirmation("Are you sure you want to delete this product?"); + if (!confirmed) return; + + try { + await api.deleteProduct(id); + } catch (error) { + showError(error.message || "Failed to delete product."); + } +} +</script> + +<template> + <VcBlade title="Product"> + <VcButton + variant="danger" + @click="deleteProduct(product.id)" + > + Delete + </VcButton> + </VcBlade> +</template> +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| --------- | ---------------------------- | -------- | --------------------------------------------------------------------------- | +| `options` | `MaybeRef<UsePopupProps<T>>` | No | Configuration for a custom popup component. Omit for built-in dialogs only. | + +#### `UsePopupProps<T>` + +| Field | Type | Required | Description | +| ----------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------- | +| `component` | `ComponentPublicInstanceConstructor` | Yes | The popup component to render | +| `props` | `RawProps<T>` | No | Props to pass to the component (typed from the component's `defineProps`) | +| `emits` | `RawEmits<T>` | No | Event handlers (typed from the component's `defineEmits`) | +| `slots` | `Record<string, string \| Component \| Slot>` | No | Named slots — strings render as text, components render as VNodes | + +### Returns (`IUsePopup`) + +| Method | Signature | Description | +| ------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| `open` | `() => void` | Push the popup onto the stack and render it | +| `close` | `() => void` | Remove the popup from the stack | +| `showConfirmation` | `(message: string \| Ref<string>) => Promise<boolean>` | Warning dialog with Confirm/Cancel buttons. Resolves `true` on confirm, `false` on cancel or close. | +| `showError` | `(message: string \| Ref<string>) => void` | Error-styled popup with a close button | +| `showInfo` | `(message: string \| Ref<string>) => void` | Info-styled popup with a close button | + +## How It Works + +`usePopup` is backed by the `VcPopupHandler` plugin, which maintains a reactive array of popup instances. When you call `open()` or `showConfirmation()`, a popup descriptor is pushed into this array. The `VcPopupContainer` component (mounted once at the app root) renders all active popups as an overlay stack. Calling `close()` removes the descriptor, and Vue reactivity handles the unmount. + +The plugin instance is resolved via `inject(PopupPluginKey)`. If called outside the component tree (e.g., in a utility function), it falls back to the singleton `popupPluginInstance`. + +Multiple popups can be open simultaneously — they stack with the most recent on top. + +## Recipe: Delete Confirmation with Notification + +```vue +<script setup lang="ts"> +import { usePopup, useBlade } from "@vc-shell/framework"; +import { useNotifications } from "@vc-shell/framework"; + +const { showConfirmation, showError } = usePopup(); +const { closeSelf } = useBlade(); + +async function deleteOrder(id: string) { + const confirmed = await showConfirmation("Are you sure you want to delete this order? This action cannot be undone."); + if (!confirmed) return; + + try { + await api.deleteOrder(id); + closeSelf(); + } catch (error) { + showError(error.message || "Failed to delete order."); + } +} +</script> +``` + +## Recipe: Custom Popup with Form + +For complex interactions beyond simple confirmation, create a custom popup component: + +```ts +import { usePopup } from "@vc-shell/framework"; +import AddNotePopup from "./AddNotePopup.vue"; + +const { open, close } = usePopup({ + component: AddNotePopup, + props: { entityId: "prod-1" }, + emits: { + onConfirm: async (note: string) => { + await api.addNote("prod-1", note); + close(); + }, + onCancel: () => close(), + }, +}); + +open(); +``` + +## Recipe: Reactive Options + +The `options` parameter accepts `MaybeRef`, so you can pass a computed or ref that updates the popup config dynamically: + +```ts +import { computed } from "vue"; +import { usePopup } from "@vc-shell/framework"; +import ConfirmPopup from "./ConfirmPopup.vue"; + +const selectedCount = ref(0); + +const { open, close } = usePopup( + computed(() => ({ + component: ConfirmPopup, + props: { message: `Delete ${selectedCount.value} items?` }, + emits: { + onConfirm: () => { + performDelete(); + close(); + }, + }, + })), +); +``` + +## Common Mistakes + +**Wrong: not awaiting showConfirmation** + +```ts +// The delete runs immediately — confirmation is ignored +showConfirmation("Delete?"); +await api.deleteProduct(id); // runs before user clicks! +``` + +**Correct: await the result** + +```ts +const confirmed = await showConfirmation("Delete?"); +if (!confirmed) return; +await api.deleteProduct(id); +``` + +--- + +**Wrong: nesting many popups** + +```ts +// 3+ deep popup stacks confuse users +const a = await showConfirmation("Step 1?"); +if (a) { + const b = await showConfirmation("Step 2?"); + if (b) { + const c = await showConfirmation("Step 3?"); + } +} +``` + +**Correct: use a blade for multi-step workflows** + +```ts +// Complex flows belong in blades, not popups +openBlade({ name: "WizardBlade", options: { step: 1 } }); +``` + +## Tips + +- **Always `await` showConfirmation** before proceeding with the destructive action. +- **Use `showConfirmation` for yes/no questions**, custom popups for forms or complex interactions. +- **Calling `usePopup()` without arguments** gives you only the built-in dialogs (`showConfirmation`, `showError`, `showInfo`). Pass `options` only when you need a custom component. +- **Avoid nesting popups more than 2 levels deep.** Consider blades for complex multi-step workflows. +- **The message parameter accepts `Ref<string>`** — useful for dynamic messages that update while the popup is open (e.g., progress messages). + +## Related + +- [VcPopup](../../components/feedback/vc-popup.md) — the default popup shell component (header, content, actions) +- [useBlade](../blade-navigation/useBlade.md) — for panel-based UI; use popups for modal interruptions only +- `notification()` — for passive, non-blocking feedback (toasts) diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/.pages new file mode 100644 index 0000000000..731831a389 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/.pages @@ -0,0 +1,12 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Services +nav: + - useAppBarMobileButtons: useAppBarMobileButtons.md + - useAppBarWidget: useAppBarWidget.md + - useDashboard: useDashboard.md + - useMenuService: useMenuService.md + - useSettings: useSettings.md + - useSettingsMenu: useSettingsMenu.md + - useToolbar: useToolbar.md + - useWidgets: useWidgets.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarMobileButtons.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarMobileButtons.md new file mode 100644 index 0000000000..3f5bf97552 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarMobileButtons.md @@ -0,0 +1,128 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useAppBarMobileButtons + +Manages custom action buttons in the mobile app bar. Uses provide/inject to share a singleton service across the component tree. This composable gives any blade or module the ability to register, update, and remove buttons that appear in the top app bar on mobile devices. Buttons are sorted by their `order` property and can include icons, custom Vue components, click handlers, badges, and reactive visibility toggles. The service is scoped to the VcApp tree and automatically cleans up when the scope is disposed. + +## When to Use + +- Register custom buttons (icons, components) in the mobile top bar from any blade or module +- Show notification badges, filter toggles, or action shortcuts in the mobile app bar +- Dynamically show/hide buttons based on blade state (e.g., only show a "filter" button when a list blade is active) +- When NOT to use: for desktop-only toolbar actions (use `useToolbar` instead); for buttons inside blade content (just use regular template markup) + +## Quick Start + +```vue +<script setup lang="ts"> +import { useAppBarMobileButtons } from "@vc-shell/framework"; +import { onUnmounted, computed, ref } from "vue"; + +const { register, unregister } = useAppBarMobileButtons(); +const unreadCount = ref(3); + +register({ + id: "notifications-btn", + icon: "fas fa-bell", + onClick: () => openNotificationsPanel(), + order: 10, + badge: computed(() => unreadCount.value > 0), + isVisible: computed(() => true), +}); + +// Always clean up when the component is destroyed +onUnmounted(() => unregister("notifications-btn")); +</script> +``` + +## API + +### Returns + +| Property | Type | Description | +| ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `registeredButtons` | `ComputedRef<AppBarButtonContent[]>` | All registered buttons (unfiltered, unsorted). Useful for debugging. | +| `register` | `(button: AppBarButtonContent) => void` | Add or update a button by `id`. If a button with the same ID already exists, it is replaced. | +| `unregister` | `(buttonId: string) => void` | Remove a button by `id`. No-op if the ID does not exist. | +| `getButton` | `(buttonId: string) => AppBarButtonContent \| undefined` | Look up a single button by ID. | +| `getButtons` | `ComputedRef<AppBarButtonContent[]>` | Visible buttons sorted by `order` (ascending). Filters out buttons where `isVisible` is `false`. | + +### AppBarButtonContent + +| Field | Type | Required | Description | +| ----------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | +| `id` | `string` | Yes | Unique identifier. Used for register/unregister/lookup. | +| `icon` | `Component \| string` | No | Icon component or CSS class string (e.g., `'fas fa-bell'`). | +| `component` | `Component` | No | Custom Vue component to render instead of a default icon button. | +| `props` | `Record<string, unknown>` | No | Props passed to the custom `component`. | +| `onClick` | `() => void` | No | Click handler for the default button rendering. | +| `onClose` | `() => void` | No | Close/dismiss handler (e.g., for popover-style buttons). | +| `order` | `number` | No | Sort priority. Lower values appear first. Defaults to 0 if omitted. | +| `isVisible` | `MaybeRef<boolean>` | No | Reactive visibility toggle. When `false`, the button is excluded from `getButtons`. Defaults to `true`. | +| `badge` | `MaybeRef<boolean>` | No | Show a small badge indicator on the button (e.g., for unread notifications). | + + + +## Recipe: Filter Toggle Button That Reflects Active State + +```vue +<script setup lang="ts"> +import { useAppBarMobileButtons } from "@vc-shell/framework"; +import { ref, computed, onUnmounted } from "vue"; + +const { register, unregister } = useAppBarMobileButtons(); +const isFilterActive = ref(false); + +register({ + id: "product-list-filter", + icon: computed(() => (isFilterActive.value ? "fas fa-filter" : "far fa-filter")), + onClick: () => { + isFilterActive.value = !isFilterActive.value; + // Open or close the filter panel + }, + order: 20, + badge: isFilterActive, +}); + +onUnmounted(() => unregister("product-list-filter")); +</script> +``` + +## Recipe: Custom Component Button + +If you need more than an icon and a click handler (e.g., a dropdown or popover), register a full Vue component: + +```vue +<script setup lang="ts"> +import { useAppBarMobileButtons } from "@vc-shell/framework"; +import { onUnmounted, markRaw } from "vue"; +import LanguageSwitcher from "./LanguageSwitcher.vue"; + +const { register, unregister } = useAppBarMobileButtons(); + +register({ + id: "language-switcher", + component: markRaw(LanguageSwitcher), + props: { position: "bottom-right" }, + order: 50, +}); + +onUnmounted(() => unregister("language-switcher")); +</script> +``` + +## Tips + +- **Always unregister on unmount.** Forgetting to call `unregister` means the button stays in the app bar even after the blade that registered it is closed. Use `onUnmounted` or `onBeforeUnmount` as a cleanup hook. +- **Use `markRaw` for component references.** When passing a Vue component to the `component` field, wrap it in `markRaw()` to avoid making it reactive (which triggers Vue warnings and unnecessary overhead). +- **Button IDs must be globally unique.** If two blades register buttons with the same ID, the second registration overwrites the first. Use a descriptive prefix like `'order-list-filter'` to avoid collisions. +- **Calling `useAppBarMobileButtons()` outside VcApp throws.** The service is injected via provide/inject. If the injection is missing, an `InjectionError` is thrown with a descriptive message. + +## Related + +- `useToolbar` -- desktop toolbar actions (different service, different UI placement) +- `framework/core/services/app-bar-mobile-buttons-service.ts` -- underlying service implementation +- `VcApp` -- provides the service via `provideAppBarMobileButtonsService()` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarWidget.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarWidget.md new file mode 100644 index 0000000000..dfceab425d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useAppBarWidget.md @@ -0,0 +1,190 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAppBarWidget/useAppBarWidget.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useAppBarWidget + +Provides access to the app bar widget service for registering custom widgets (buttons, icons, dropdowns) in the application's top navigation bar. Uses Vue's provide/inject system. + +Also exports `provideAppBarWidget()` for framework-level initialization. + +## Overview + +The vc-shell application header (app bar) contains a row of widget slots for global actions: notification bell, language picker, user menu, and more. Modules can add their own widgets to this bar -- for example, a "quick create" button, a sync status indicator, or a custom dropdown. + +The `useAppBarWidget()` composable provides the `IAppBarWidgetService` interface, which allows registering, unregistering, and listing app bar widgets. Widgets can be simple icon buttons with click handlers or fully custom Vue components. + +The service follows the same provide/inject singleton pattern as other framework services. The framework calls `provideAppBarWidget()` during bootstrap; modules consume it via `useAppBarWidget()`. + +## When to Use + +- To register a custom widget (notification bell, language picker, user avatar) in the app bar +- To list or manage currently registered app bar widgets +- When NOT to use: for blade-level toolbar actions, use `useToolbar()` instead + +## Basic Usage + +```typescript +import { useAppBarWidget } from "@vc-shell/framework"; + +const appBarService = useAppBarWidget(); + +const widgetId = appBarService.register({ + icon: "bell", + title: "Notifications", + order: 10, + onClick: () => openNotifications(), +}); +``` + +## API + +### Parameters + +None. + +### Returns (`IAppBarWidgetService`) + +| Property / Method | Type | Description | +| ----------------- | -------------------------------------------------- | ---------------------------------------------------------- | +| `register` | `(options: registerAppBarWidgetOptions) => string` | Registers a widget in the app bar, returns the assigned ID | +| `unregister` | `(id: string) => void` | Removes a widget from the app bar by ID | +| `items` | `ComputedRef<AppBarWidget[]>` | Reactive list of all registered app bar widgets | + +### registerAppBarWidgetOptions + +| Field | Type | Required | Description | +| ----------- | ------------------------- | -------- | ------------------------------------------------------------- | +| `id` | `string` | No | Custom ID; auto-generated if omitted | +| `order` | `number` | No | Sort order in the app bar (lower = further left) | +| `title` | `string` | No | Tooltip or label text | +| `icon` | `Component \| string` | No | Lucide icon name or a Vue component | +| `component` | `Component` | No | Custom Vue component to render instead of default icon button | +| `props` | `Record<string, unknown>` | No | Props to pass to the custom component | +| `onClick` | `() => void` | No | Click handler for the default icon button | +| `slot` | `string` | No | Named slot target for placement control | + +### Additional Exports + +| Export | Description | +| ----------------------- | ----------------------------------------------------------------------- | +| `provideAppBarWidget()` | Creates and provides the service. Flushes pre-registered items on init. | + +## Common Patterns + +### Simple icon button widget + +```typescript +import { useAppBarWidget } from "@vc-shell/framework"; + +const { register, unregister } = useAppBarWidget(); + +// Register a simple icon button +const id = register({ + icon: "lucide-refresh-cw", + title: "Sync Data", + order: 5, + onClick: () => syncAllData(), +}); +``` + +### Registering a custom component widget + +```typescript +import { useAppBarWidget } from "@vc-shell/framework"; +import { markRaw, onUnmounted } from "vue"; +import LanguagePicker from "./LanguagePicker.vue"; + +const { register, unregister } = useAppBarWidget(); + +const id = register({ + component: markRaw(LanguagePicker), + order: 20, + title: "Language", +}); + +onUnmounted(() => unregister(id)); +``` + +### Widget with dynamic props + +```typescript +import { useAppBarWidget } from "@vc-shell/framework"; +import { markRaw } from "vue"; +import SyncStatusIndicator from "./SyncStatusIndicator.vue"; + +const { register } = useAppBarWidget(); + +register({ + component: markRaw(SyncStatusIndicator), + props: { + status: syncStatus, // Can be reactive + lastSyncTime: lastSyncAt, // Will be passed as props to the component + }, + order: 1, +}); +``` + +### Listing all registered widgets + +```typescript +import { useAppBarWidget } from "@vc-shell/framework"; + +const { items } = useAppBarWidget(); + +// Iterate over all widgets (sorted by order) +watchEffect(() => { + console.log(`${items.value.length} widgets in app bar`); + items.value.forEach((w) => console.log(` - ${w.title ?? w.id}`)); +}); +``` + +### Pre-registration before service exists + +If your module code runs before the app bar service is provided (e.g., during module `install()`), use the `addAppBarWidget()` bus function. Items are automatically flushed when `provideAppBarWidget()` runs: + +```typescript +import { addAppBarWidget } from "@vc-shell/framework"; + +// Safe to call before provideAppBarWidget() +addAppBarWidget({ + id: "my-widget", + icon: "lucide-star", + order: 15, + onClick: () => doSomething(), +}); +``` + +## Tip: Always Clean Up in onUnmounted + +Widgets are not automatically removed when a component unmounts. If your module dynamically registers widgets during component setup, always unregister them in `onUnmounted` to avoid orphaned widgets: + +```typescript +const { register, unregister } = useAppBarWidget(); + +const id = register({ icon: "lucide-bell", onClick: handleClick }); + +onUnmounted(() => { + unregister(id); +}); +``` + +## Common Mistake + +Forgetting to use `markRaw()` when passing component references causes Vue to make the component object deeply reactive, which triggers warnings and degrades performance: + +```typescript +// Bad: triggers Vue reactivity warning +register({ component: MyWidget }); + +// Good: prevents unnecessary deep reactivity +register({ component: markRaw(MyWidget) }); +``` + +## Related + +- [useToolbar](./useToolbar.md) -- blade-level toolbar actions (different scope than app bar) +- [useWidgets](./useWidgets.md) -- blade widget registration system +- `framework/injection-keys.ts` -- `AppBarWidgetServiceKey` +- `framework/core/services/app-bar-menu-service.ts` -- the underlying service implementation diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useDashboard.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useDashboard.md new file mode 100644 index 0000000000..972745ddcb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useDashboard.md @@ -0,0 +1,405 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useDashboard/useDashboard.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Long page" +Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Widget Registration](#widget-registration), [Permission-Based Visibility](#permission-based-visibility), or [API Reference](#api-reference). + +# useDashboard + +Accesses the dashboard service for registering and managing dashboard widgets. Widgets are permission-aware, support layout positioning, and can be pre-registered during module setup before the service is initialized. + +## When to Use + +- Register dashboard widgets during module setup (use standalone `registerDashboardWidget`) +- Read or update widget layout at runtime inside a dashboard view component (use `useDashboard()`) +- When NOT to use: for sidebar navigation items -- use `useMenuService` / `addMenuItem`; for settings-page entries -- use `useSettingsMenu` + +## Quick Start + +```typescript +import { registerDashboardWidget } from "@vc-shell/framework"; +import OrdersSummary from "./components/OrdersSummary.vue"; + +// In a module's initialize function +registerDashboardWidget({ + id: "orders-summary", + name: "Orders Summary", + component: OrdersSummary, + size: { width: 2, height: 1 }, + permissions: ["order:read"], +}); +``` + +## Pre-Registration vs. Live Service + +Like the menu service, the dashboard supports two usage modes. + +### Pre-registration (module setup) + +Use the standalone `registerDashboardWidget` function during module plugin installation. Items are buffered and flushed when `provideDashboardService()` runs: + +```typescript +// modules/orders/index.ts +import { registerDashboardWidget } from "@vc-shell/framework"; +import OrdersSummary from "./widgets/OrdersSummary.vue"; +import RecentOrders from "./widgets/RecentOrders.vue"; + +export default { + install(app) { + registerDashboardWidget({ + id: "orders-summary", + name: "Orders Summary", + component: OrdersSummary, + size: { width: 2, height: 1 }, + permissions: ["order:read"], + }); + + registerDashboardWidget({ + id: "recent-orders", + name: "Recent Orders", + component: RecentOrders, + size: { width: 2, height: 2 }, + permissions: ["order:read"], + }); + }, +}; +``` + +### Live service (inside components) + +Use `useDashboard()` inside a component's `<script setup>` to access the live service: + +```typescript +<script setup lang="ts"> +import { computed } from "vue"; +import { useDashboard } from "@vc-shell/framework"; + +const dashboard = useDashboard(); +const widgets = computed(() => dashboard.getWidgets()); +</script> +``` + +> **Important:** Calling `useDashboard()` before `provideDashboardService()` has been called by an ancestor component throws an `InjectionError`. Module setup code should use the standalone `registerDashboardWidget()` function instead. + +## Widget Registration + +Each widget requires an `id`, `name`, `component`, and `size`. Additional properties control permissions, positioning, and custom props. + +```typescript +registerDashboardWidget({ + id: "sales-chart", + name: "Sales Overview", + component: SalesChart, + size: { width: 3, height: 2 }, + position: { x: 0, y: 0 }, + permissions: ["analytics:view"], + props: { + dateRange: "last30days", + currency: "USD", + }, +}); +``` + +### Widget size + +The `size` property defines the widget's grid dimensions: + +| Property | Type | Description | +| -------- | -------- | --------------------------------------- | +| `width` | `number` | Number of grid columns the widget spans | +| `height` | `number` | Number of grid rows the widget spans | + +### Widget position + +The optional `position` property sets the initial grid coordinates: + +| Property | Type | Description | +| -------- | -------- | ---------------------- | +| `x` | `number` | Column index (0-based) | +| `y` | `number` | Row index (0-based) | + +### Custom props + +The `props` object is passed directly to the widget component as its props: + +```typescript +// Widget registration +registerDashboardWidget({ + id: "inventory-alerts", + name: "Inventory Alerts", + component: InventoryAlerts, + size: { width: 1, height: 1 }, + props: { + threshold: 10, + showOutOfStock: true, + }, +}); + +// InventoryAlerts.vue receives these as component props +``` + +## Permission-Based Visibility + +Widgets accept a `permissions` array. When the dashboard renders, it filters widgets through the current user's permissions via `usePermissions().hasAccess()`: + +```typescript +// Only visible to users with analytics:view permission +registerDashboardWidget({ + id: "revenue-chart", + name: "Revenue", + component: RevenueChart, + size: { width: 2, height: 2 }, + permissions: ["analytics:view"], +}); + +// Visible to users with ANY of these permissions (OR logic) +registerDashboardWidget({ + id: "order-stats", + name: "Order Statistics", + component: OrderStats, + size: { width: 1, height: 1 }, + permissions: ["order:read", "analytics:view"], +}); + +// No permissions -- visible to everyone +registerDashboardWidget({ + id: "welcome-banner", + name: "Welcome", + component: WelcomeBanner, + size: { width: 3, height: 1 }, +}); +``` + +> **Note:** Administrator users always see all widgets, regardless of the `permissions` array. + +## Layout Management + +The dashboard service tracks widget positions. You can update positions at runtime (e.g., after a user drags a widget): + +```typescript +<script setup lang="ts"> +import { useDashboard } from "@vc-shell/framework"; + +const dashboard = useDashboard(); + +function onWidgetDrop(widgetId: string, newX: number, newY: number) { + dashboard.updateWidgetPosition(widgetId, { x: newX, y: newY }); +} + +// Read the full layout map +const layout = dashboard.getLayout(); +// layout is ReadonlyMap<string, DashboardWidgetPosition> +</script> +``` + +## Building a Dashboard View + +A complete dashboard view that renders all visible widgets: + +```typescript +<script setup lang="ts"> +import { computed } from "vue"; +import { useDashboard } from "@vc-shell/framework"; + +const dashboard = useDashboard(); +const widgets = computed(() => dashboard.getWidgets()); +</script> + +<template> + <div class="tw-grid tw-grid-cols-4 tw-gap-4 tw-p-4"> + <div + v-for="widget in widgets" + :key="widget.id" + :style="{ + gridColumn: `span ${widget.size.width}`, + gridRow: `span ${widget.size.height}`, + }" + > + <VcCard :header="widget.name"> + <component :is="widget.component" v-bind="widget.props" /> + </VcCard> + </div> + </div> +</template> +``` + +## Recipes + +### Module with Multiple Widgets + +```typescript +// modules/analytics/index.ts +import { registerDashboardWidget } from "@vc-shell/framework"; +import SalesChart from "./widgets/SalesChart.vue"; +import TopProducts from "./widgets/TopProducts.vue"; +import CustomerGrowth from "./widgets/CustomerGrowth.vue"; + +export function registerAnalyticsDashboard() { + registerDashboardWidget({ + id: "analytics-sales", + name: "Sales Overview", + component: SalesChart, + size: { width: 2, height: 2 }, + position: { x: 0, y: 0 }, + permissions: ["analytics:view"], + }); + + registerDashboardWidget({ + id: "analytics-top-products", + name: "Top Products", + component: TopProducts, + size: { width: 1, height: 2 }, + position: { x: 2, y: 0 }, + permissions: ["analytics:view", "catalog:read"], + }); + + registerDashboardWidget({ + id: "analytics-customers", + name: "Customer Growth", + component: CustomerGrowth, + size: { width: 1, height: 1 }, + position: { x: 3, y: 0 }, + permissions: ["analytics:view"], + }); +} +``` + +### Widget Component Template + +```typescript +<!-- widgets/OrdersSummary.vue --> +<script setup lang="ts"> +import { ref, onMounted } from "vue"; +import { useApiClient, useAsync } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; + +const { getApiClient } = useApiClient(OrderClient); +const stats = ref({ pending: 0, shipped: 0, completed: 0 }); + +const { loading, action: loadStats } = useAsync(async () => { + const client = await getApiClient(); + const pending = await client.searchOrders({ status: "Pending", take: 0 }); + const shipped = await client.searchOrders({ status: "Shipped", take: 0 }); + const completed = await client.searchOrders({ status: "Completed", take: 0 }); + stats.value = { + pending: pending.totalCount ?? 0, + shipped: shipped.totalCount ?? 0, + completed: completed.totalCount ?? 0, + }; +}); + +onMounted(() => loadStats()); +</script> + +<template> + <div v-if="!loading" class="tw-grid tw-grid-cols-3 tw-gap-4 tw-p-4"> + <div class="tw-text-center"> + <div class="tw-text-2xl tw-font-bold">{{ stats.pending }}</div> + <div class="tw-text-sm tw-text-gray-500">Pending</div> + </div> + <div class="tw-text-center"> + <div class="tw-text-2xl tw-font-bold">{{ stats.shipped }}</div> + <div class="tw-text-sm tw-text-gray-500">Shipped</div> + </div> + <div class="tw-text-center"> + <div class="tw-text-2xl tw-font-bold">{{ stats.completed }}</div> + <div class="tw-text-sm tw-text-gray-500">Completed</div> + </div> + </div> +</template> +``` + +## Common Mistakes + +### Registering duplicate widget IDs + +```typescript +// Wrong -- throws "Widget with id orders-summary already registered" +registerDashboardWidget({ id: "orders-summary", name: "A", component: CompA, size: { width: 1, height: 1 } }); +registerDashboardWidget({ id: "orders-summary", name: "B", component: CompB, size: { width: 1, height: 1 } }); + +// Correct -- use unique IDs for each widget +registerDashboardWidget({ id: "orders-summary", name: "Orders", component: CompA, size: { width: 1, height: 1 } }); +registerDashboardWidget({ id: "orders-detail", name: "Details", component: CompB, size: { width: 1, height: 1 } }); +``` + +### Calling useDashboard() during module setup + +```typescript +// Wrong -- service is not yet provided during plugin install +export default { + install(app) { + const dashboard = useDashboard(); // throws InjectionError + dashboard.registerWidget({ ... }); + }, +}; + +// Correct -- use the standalone function +export default { + install(app) { + registerDashboardWidget({ id: "widget", name: "W", component: Comp, size: { width: 1, height: 1 } }); + }, +}; +``` + +### Updating position for unregistered widget + +```typescript +// Wrong -- throws "Widget with id unknown-widget not found" +dashboard.updateWidgetPosition("unknown-widget", { x: 0, y: 0 }); + +// Correct -- verify the widget exists or use a known ID +const widgets = dashboard.getWidgets(); +if (widgets.some((w) => w.id === "my-widget")) { + dashboard.updateWidgetPosition("my-widget", { x: 0, y: 0 }); +} +``` + +## API Reference + +### useDashboard() + +Returns the injected `IDashboardService` instance. Throws `InjectionError` if the service has not been provided. + +#### IDashboardService Interface + +| Method | Type | Description | +| ---------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | +| `registerWidget` | `(widget: DashboardWidget) => void` | Register a widget (throws on duplicate ID) | +| `getWidgets` | `() => DashboardWidget[]` | Get all registered widgets filtered by current user's permissions | +| `updateWidgetPosition` | `(widgetId: string, position: DashboardWidgetPosition) => void` | Update a widget's grid position (throws if widget not found) | +| `getLayout` | `() => ReadonlyMap<string, DashboardWidgetPosition>` | Get the current layout map | + +### Standalone Exports + +| Function | Description | +| --------------------------------- | ------------------------------------------------------- | +| `registerDashboardWidget(widget)` | Pre-register a widget before the service is initialized | +| `provideDashboardService()` | Create and provide the service in a root component | + +### DashboardWidget + +| Property | Type | Required | Description | +| ------------- | ----------------------------------- | -------- | ---------------------------------------------- | +| `id` | `string` | Yes | Unique widget identifier | +| `name` | `string` | Yes | Display title | +| `component` | `Component` | Yes | Vue component to render | +| `size` | `{ width: number; height: number }` | Yes | Grid size (columns x rows) | +| `position` | `{ x: number; y: number }` | No | Initial grid position | +| `permissions` | `string[]` | No | Required permissions for visibility (OR logic) | +| `props` | `Record<string, unknown>` | No | Props passed to the widget component | + +### DashboardWidgetPosition + +| Property | Type | Description | +| -------- | -------- | ---------------------- | +| `x` | `number` | Column index (0-based) | +| `y` | `number` | Row index (0-based) | + +## Related + +- [usePermissions](../user/usePermissions.md) -- permission checks used for widget visibility filtering +- [useMenuService](./useMenuService.md) -- similar pre-registration pattern for navigation menu +- [useApiClient](../data/useApiClient.md) -- used within widget components to fetch data diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useMenuService.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useMenuService.md new file mode 100644 index 0000000000..3f48060119 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useMenuService.md @@ -0,0 +1,350 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useMenuService/useMenuService.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Long page" +Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Grouping Menu Items](#grouping-menu-items), [Badges and Indicators](#badges-and-indicators), or [API Reference](#api-reference). + +# useMenuService + +Accesses the navigation menu service for adding, removing, and badging menu items in the application sidebar. The service supports a pre-registration pattern that allows modules to declare menu items before the service is initialized, and a grouping system that organizes items into collapsible sections. + +## When to Use + +- Register sidebar navigation items during module setup (use standalone `addMenuItem`) +- Add, remove, or badge menu items at runtime inside components (use `useMenuService()`) +- When NOT to use: for dashboard widgets -- use `useDashboard` / `registerDashboardWidget`; for settings-page entries -- use `useSettingsMenu` + +## Quick Start + +```typescript +import { addMenuItem } from "@vc-shell/framework"; + +// In a module's initialize function (runs before service is available) +addMenuItem({ + title: "Orders", + icon: "fas fa-shopping-cart", + routeId: "OrdersList", + priority: 10, +}); +``` + +When the application shell calls `provideMenuService()`, all pre-registered items are flushed into the live service. + +## Pre-Registration vs. Live Service + +The menu system supports two usage modes depending on timing. + +### Pre-registration (module setup) + +Use the standalone `addMenuItem` function when registering menu items during module plugin installation. This runs before the Vue component tree is mounted: + +```typescript +// modules/orders/index.ts +import { addMenuItem } from "@vc-shell/framework"; + +export default { + install(app) { + addMenuItem({ + title: "Orders", + icon: "fas fa-shopping-cart", + routeId: "OrdersList", + priority: 10, + }); + + addMenuItem({ + title: "Returns", + icon: "fas fa-undo", + routeId: "ReturnsList", + priority: 20, + }); + }, +}; +``` + +### Live service (inside components) + +Use `useMenuService()` inside a component's `<script setup>` to access the live service instance after it has been provided: + +```typescript +<script setup lang="ts"> +import { useMenuService } from "@vc-shell/framework"; + +const menuService = useMenuService(); + +// Read all registered menu items reactively +const items = computed(() => menuService.menuItems.value); +</script> +``` + +> **Important:** Calling `useMenuService()` before `provideMenuService()` has been called by an ancestor component throws an `InjectionError`. Module setup code should always use the standalone `addMenuItem()` function instead. + +## Grouping Menu Items + +Menu items with a `group` or `groupConfig` property are grouped into collapsible sections in the sidebar. + +### Using groupConfig (recommended) + +```typescript +addMenuItem({ + title: "Products", + icon: "fas fa-box", + routeId: "ProductsList", + priority: 10, + groupConfig: { + id: "catalog", + title: "Catalog", + icon: "fas fa-folder", + priority: 5, + permissions: "catalog:read", + }, +}); + +addMenuItem({ + title: "Categories", + icon: "fas fa-tags", + routeId: "CategoriesList", + priority: 20, + groupConfig: { + id: "catalog", // same group ID -- items are grouped together + }, +}); +``` + +Both items appear under a single "Catalog" group. The group inherits properties from the first registration that provides them, and subsequent registrations with the same `id` can update the group's `title`, `icon`, `priority`, or `permissions`. + +### Using group (legacy) + +```typescript +addMenuItem({ + title: "Products", + icon: "fas fa-box", + routeId: "ProductsList", + priority: 10, + group: "Catalog", + groupIcon: "fas fa-folder", +}); +``` + +> **Note:** The `group` and `groupIcon` properties are deprecated. Use `groupConfig` for more precise control over group identity and display. + +## Badges and Indicators + +Badges display numeric counts or dot indicators on menu items. They can be set at any time, including before the service is initialized. + +### Setting a badge count + +```typescript +import { setMenuBadge } from "@vc-shell/framework"; + +// Show a count on the Orders menu item (identified by routeId) +setMenuBadge("OrdersList", { content: 5, variant: "danger" }); +``` + +### Shorthand badge values + +```typescript +import { setMenuBadge } from "@vc-shell/framework"; + +// Number shorthand +setMenuBadge("OrdersList", 12); + +// String shorthand +setMenuBadge("OrdersList", "New"); + +// Reactive ref +const pendingCount = ref(0); +setMenuBadge("OrdersList", pendingCount); + +// Computed value +const unread = computed(() => orders.value.filter((o) => !o.isRead).length); +setMenuBadge("OrdersList", unread); +``` + +### Dot indicator + +```typescript +setMenuBadge("SettingsPage", { isDot: true, variant: "warning" }); +``` + +### Removing a badge + +```typescript +import { removeMenuBadge } from "@vc-shell/framework"; + +removeMenuBadge("OrdersList"); +``` + +## Removing Menu Items + +Remove previously registered items using the standalone function or the live service. The item is matched by its identity (priority: `id` > `routeId` > `url` > `group+title`): + +```typescript +import { removeRegisteredMenuItem } from "@vc-shell/framework"; + +// Remove by routeId +removeRegisteredMenuItem({ routeId: "ReturnsList" } as MenuItem); +``` + +## Recipes + +### Dynamic Badge Based on API Data + +```typescript +<script setup lang="ts"> +import { onMounted, ref } from "vue"; +import { setMenuBadge, useApiClient } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; + +const { getApiClient } = useApiClient(OrderClient); +const pendingCount = ref(0); + +onMounted(async () => { + const client = await getApiClient(); + const result = await client.searchOrders({ status: "Pending", take: 0 }); + pendingCount.value = result.totalCount ?? 0; + setMenuBadge("OrdersList", { content: pendingCount.value, variant: "danger" }); +}); +</script> +``` + +### Conditional Menu Registration by Permissions + +```typescript +import { addMenuItem, usePermissions } from "@vc-shell/framework"; + +export function registerOrderMenuItems() { + addMenuItem({ + title: "Orders", + icon: "fas fa-shopping-cart", + routeId: "OrdersList", + priority: 10, + permissions: "order:read", // only visible to users with this permission + }); + + // Admin-only menu item + addMenuItem({ + title: "Order Settings", + icon: "fas fa-cog", + routeId: "OrderSettings", + priority: 90, + permissions: ["order:manage", "admin:settings"], + }); +} +``` + +## Common Mistakes + +### Calling useMenuService() during module setup + +```typescript +// Wrong -- service is not provided yet during plugin install +export default { + install(app) { + const menuService = useMenuService(); // throws InjectionError + menuService.addMenuItem({ ... }); + }, +}; + +// Correct -- use the standalone function +export default { + install(app) { + addMenuItem({ title: "Orders", icon: "fas fa-cart", routeId: "OrdersList", priority: 10 }); + }, +}; +``` + +### Duplicate menu items from missing identity + +```typescript +// Wrong -- no id or routeId, identity falls back to deep hash, may duplicate +addMenuItem({ title: "Orders", icon: "fas fa-cart", priority: 10 }); +addMenuItem({ title: "Orders", icon: "fas fa-cart", priority: 10 }); + +// Correct -- provide routeId for stable deduplication +addMenuItem({ title: "Orders", icon: "fas fa-cart", routeId: "OrdersList", priority: 10 }); +addMenuItem({ title: "Orders", icon: "fas fa-cart", routeId: "OrdersList", priority: 10 }); // deduped +``` + +### Setting badge on wrong identifier + +```typescript +// Wrong -- using the menu item title instead of routeId +setMenuBadge("Orders", 5); + +// Correct -- use routeId (the blade registration name) +setMenuBadge("OrdersList", 5); +``` + +## API Reference + +### useMenuService() + +Returns the injected `MenuService` instance. Throws `InjectionError` if the service has not been provided. + +#### MenuService Interface + +| Property | Type | Description | +| ---------------- | --------------------------------------- | ---------------------------------------------------------------- | +| `addMenuItem` | `(item: MenuItem) => void` | Add a menu item (deduplicates by identity) | +| `removeMenuItem` | `(item: MenuItem) => void` | Remove a menu item | +| `menuItems` | `Ref<MenuItem[]>` | Reactive array of all registered menu items (grouped and sorted) | +| `menuBadges` | `Ref<Map<string, MenuItemBadgeConfig>>` | Reactive map of badge configs keyed by routeId or groupId | + +### Standalone Exports + +| Function | Description | +| -------------------------------- | ------------------------------------------------------------------ | +| `addMenuItem(item)` | Pre-register a menu item before the service is initialized | +| `removeRegisteredMenuItem(item)` | Remove a pre-registered item (works before and after service init) | +| `setMenuBadge(id, config)` | Set a badge on a menu item by routeId or groupId | +| `getMenuBadge(id)` | Get badge config for a menu item | +| `removeMenuBadge(id)` | Remove a badge from a menu item | +| `getMenuBadges()` | Get the reactive badge registry map | +| `provideMenuService()` | Create and provide the service in a root component | + +### MenuItem Properties + +| Property | Type | Required | Description | +| ----------------- | --------------------- | -------- | ----------------------------------------------------------------------------- | +| `title` | `string` | Yes | Display text | +| `icon` | `string` | Yes | Icon class (e.g., `"fas fa-shopping-cart"`) | +| `priority` | `number` | Yes | Sort order (lower = higher in the list) | +| `routeId` | `string` | No | Blade route name (also used as identity key) | +| `url` | `string` | No | External URL | +| `id` | `string \| number` | No | Explicit identity key | +| `permissions` | `string \| string[]` | No | Required permissions for visibility | +| `group` | `string` | No | Group name (deprecated, use `groupConfig`) | +| `groupIcon` | `string` | No | Group icon (deprecated, use `groupConfig`) | +| `groupConfig` | `object` | No | Group configuration: `{ id, title?, icon?, priority?, permissions?, badge? }` | +| `inGroupPriority` | `number` | No | Sort order within a group (deprecated, use item's `priority`) | +| `badge` | `MenuItemBadgeConfig` | No | Inline badge configuration | +| `children` | `MenuItem[]` | No | Child items (populated automatically for groups) | + +### MenuItemBadgeConfig + +Accepts a full object or shorthand values: + +| Form | Example | Description | +| ------------------------------- | ------------------------------------------------- | ------------------ | +| `number` | `5` | Numeric count | +| `string` | `"New"` | Text label | +| `Ref<number \| string>` | `ref(3)` | Reactive value | +| `ComputedRef<number \| string>` | `computed(() => count.value)` | Computed value | +| `() => number \| string` | `() => items.length` | Getter function | +| `MenuItemBadge` | `{ content: 5, variant: "danger", isDot: false }` | Full config object | + +#### MenuItemBadge Properties + +| Property | Type | Default | Description | +| --------- | -------------------------------------------------------------------------- | ----------- | -------------------------------------------- | +| `content` | `string \| number \| Ref \| ComputedRef \| Function` | -- | Badge content | +| `variant` | `"primary" \| "success" \| "warning" \| "danger" \| "info" \| "secondary"` | `"primary"` | Color variant | +| `isDot` | `boolean` | `false` | Show as dot indicator only (ignores content) | + +## Related + +- [useSettingsMenu](./useSettingsMenu.md) -- similar pattern for the settings sidebar menu +- [useDashboard](./useDashboard.md) -- similar pre-registration pattern for dashboard widgets +- [usePermissions](../user/usePermissions.md) -- permission checks used for menu item visibility diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettings.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettings.md new file mode 100644 index 0000000000..11c0dd3e82 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettings.md @@ -0,0 +1,191 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useSettings/useSettings.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useSettings + +Loads and manages UI customization settings (logo, title, avatar) from the platform's Settings API. Supports overriding defaults with custom values. + +## Overview + +The vc-shell application header displays a logo, application title, and optionally a user avatar and role. These values can come from two sources: + +1. **Platform Settings API** -- the default. The composable fetches UI customization settings stored on the VirtoCommerce platform via `SettingClient.getUICustomizationSetting()`. +2. **Manual override** -- via `applySettings()`. When a module provides its own branding (logo, title), it calls `applySettings()` to set values directly, bypassing the API call entirely. + +The composable uses `useApiClient(SettingClient)` and `useAsync` internally, providing automatic loading state tracking. Settings are fetched lazily on component mount, but only if no custom settings have been applied. + +## When to Use + +- When displaying the application logo or title in the shell header +- When a module needs to apply custom branding (logo, title, user avatar) +- Do NOT use for general application configuration -- this is specifically for UI customization + +## Basic Usage + +```typescript +import { useSettings } from "@vc-shell/framework"; + +const { uiSettings, loading } = useSettings(); +// uiSettings.value.logo, uiSettings.value.title, etc. +``` + +## API + +### Returns + +| Property | Type | Description | +| --------------- | --------------------------------------------------- | --------------------------------------------------------- | +| `uiSettings` | `Ref<IUISetting>` | Reactive object with current UI customization values | +| `loading` | `ComputedRef<boolean>` | Whether settings are being fetched from the API | +| `applySettings` | `(args: { logo?, title?, avatar?, role? }) => void` | Override settings with custom values (prevents API fetch) | + +### IUISetting + +| Property | Type | Description | +| --------------- | --------- | ------------------------------------------ | +| `contrast_logo` | `string?` | Logo variant for dark/contrast backgrounds | +| `logo` | `string?` | Primary application logo URL | +| `title` | `string?` | Application title | +| `avatar` | `string?` | Current user avatar URL | +| `role` | `string?` | Current user role display name | + +## Common Patterns + +### Displaying the app logo + +```vue +<script setup lang="ts"> +import { useSettings } from "@vc-shell/framework"; + +const { uiSettings, loading } = useSettings(); +</script> + +<template> + <div + v-loading="loading" + class="tw-min-h-[40px]" + > + <img + v-if="uiSettings.logo" + :src="uiSettings.logo" + :alt="uiSettings.title ?? 'Application Logo'" + class="tw-h-10" + /> + <span + v-if="uiSettings.title" + class="tw-ml-2 tw-text-lg tw-font-semibold" + > + {{ uiSettings.title }} + </span> + </div> +</template> +``` + +### Applying custom branding from a module + +```typescript +<script setup lang="ts"> +import { useSettings } from "@vc-shell/framework"; + +const { applySettings } = useSettings(); + +// Override default platform settings with module-specific branding +applySettings({ + logo: "/modules/vendor-portal/logo.svg", + title: "Vendor Portal", +}); +</script> +``` + +### Showing user avatar and role + +```vue +<script setup lang="ts"> +import { useSettings } from "@vc-shell/framework"; +import { useUserManagement } from "@vc-shell/framework"; + +const { uiSettings } = useSettings(); +const { user } = useUserManagement(); + +// Apply user-specific settings after login +watch(user, (currentUser) => { + if (currentUser) { + applySettings({ + avatar: currentUser.photoUrl, + role: currentUser.roles?.[0]?.name, + }); + } +}); +</script> + +<template> + <div class="tw-flex tw-items-center tw-gap-2"> + <img + v-if="uiSettings.avatar" + :src="uiSettings.avatar" + alt="User avatar" + class="tw-w-8 tw-h-8 tw-rounded-full" + /> + <span + v-if="uiSettings.role" + class="tw-text-sm tw-text-gray-500" + > + {{ uiSettings.role }} + </span> + </div> +</template> +``` + +### Using contrast logo for dark backgrounds + +```vue +<template> + <!-- Use contrast_logo on dark sidebar, regular logo elsewhere --> + <img + :src="isDarkSidebar ? uiSettings.contrast_logo : uiSettings.logo" + alt="Logo" + /> +</template> +``` + +## Notes + +- Settings are fetched automatically on mount if not already loaded and `applySettings` hasn't been called. +- Calling `applySettings()` sets an internal `customSettingsApplied` flag that prevents the API fetch, making it suitable for fully custom apps that do not use platform settings. +- The composable uses `useApiClient(SettingClient)` and `useAsync` internally. +- If the API returns `null` or the settings have already been loaded, the fetch is a no-op. +- The `uiSettings` ref defaults to an empty object `{}` when no settings are loaded yet. + +## Tip: Call applySettings Early + +If your application always uses custom branding and never needs the platform's default settings, call `applySettings()` as early as possible (e.g., in the app's root component setup). This prevents an unnecessary API call on mount: + +```typescript +// In App.vue or root module setup +const { applySettings } = useSettings(); +applySettings({ + logo: "/my-app-logo.svg", + title: "My Custom App", +}); +// No API call will be made +``` + +## Common Mistake + +Each call to `applySettings()` replaces the entire settings object (spread merge). If you call it twice with partial values, earlier values not included in the second call will be lost: + +```typescript +applySettings({ logo: "/logo.svg", title: "My App" }); +applySettings({ avatar: "/avatar.jpg" }); // logo and title are now undefined! + +// Fix: spread existing settings +applySettings({ ...uiSettings.value, avatar: "/avatar.jpg" }); +``` + +## Related + +- [useApiClient](../data/useApiClient.md) -- used internally to fetch settings from the platform API +- [useAsync](../utilities/useAsync.md) -- wraps the settings API call with loading state +- `framework/core/api/platform.ts` -- `SettingClient` class diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettingsMenu.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettingsMenu.md new file mode 100644 index 0000000000..64bcae1def --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useSettingsMenu.md @@ -0,0 +1,179 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useSettingsMenu/useSettingsMenu.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useSettingsMenu + +Accesses the settings menu service for registering and managing items in the application settings sidebar. + +## Overview + +The vc-shell application includes a settings page where users can configure preferences such as theme, language, and notification settings. Modules can extend this settings page by registering their own menu items, each pointing to a settings blade or component. + +The `useSettingsMenu()` composable provides access to the `ISettingsMenuService` singleton, which manages the registration and lifecycle of settings menu items. It follows the same provide/inject service pattern used by other framework services like `useMenuService()` and `useDashboard()`. + +The service must be provided by an ancestor component (via `provideSettingsMenu()`) before any descendant calls `useSettingsMenu()`. The framework handles this provision during app bootstrap, so module developers can call `useSettingsMenu()` directly in their module setup code. + +## When to Use + +- When a module needs to add entries to the settings page +- When dynamically registering or removing settings menu items +- Do NOT call before `provideSettingsMenu()` has been called in an ancestor component + +## Basic Usage + +```typescript +import { useSettingsMenu } from "@vc-shell/framework"; + +const settingsMenu = useSettingsMenu(); +const items = settingsMenu.items.value; +``` + +## API + +### Returns (`ISettingsMenuService`) + +| Property | Type | Description | +| ------------ | ------------------------------------------------------ | ---------------------------------------------------- | +| `register` | `(options: RegisterSettingsMenuItemOptions) => string` | Register a settings menu item; returns the item ID | +| `unregister` | `(id: string) => void` | Remove a settings menu item by ID | +| `items` | `ComputedRef<ISettingsMenuItem[]>` | Reactive array of all registered settings menu items | + +### Related Exports + +| Export | Description | +| ----------------------- | -------------------------------------------------- | +| `provideSettingsMenu()` | Create and provide the service in a root component | + +## Common Patterns + +### Registering a settings page from a module + +```typescript +import { useSettingsMenu } from "@vc-shell/framework"; + +const settingsMenu = useSettingsMenu(); + +const itemId = settingsMenu.register({ + id: "notification-preferences", + title: "Notifications", + icon: "fas fa-bell", + component: NotificationSettingsPage, + group: "General", + priority: 10, +}); +``` + +### Registering multiple settings items with grouping + +```typescript +import { useSettingsMenu } from "@vc-shell/framework"; +import { markRaw } from "vue"; + +const settingsMenu = useSettingsMenu(); + +// Group related settings under a common section +settingsMenu.register({ + id: "catalog-general", + title: "General", + icon: "lucide-settings", + component: markRaw(CatalogGeneralSettings), + group: "Catalog", + priority: 1, +}); + +settingsMenu.register({ + id: "catalog-seo", + title: "SEO Settings", + icon: "lucide-search", + component: markRaw(CatalogSeoSettings), + group: "Catalog", + priority: 2, +}); + +settingsMenu.register({ + id: "catalog-import-export", + title: "Import / Export", + icon: "lucide-arrow-left-right", + component: markRaw(CatalogImportExportSettings), + group: "Catalog", + priority: 3, +}); +``` + +### Cleaning up on module unload + +```typescript +import { useSettingsMenu } from "@vc-shell/framework"; +import { onBeforeUnmount } from "vue"; + +const settingsMenu = useSettingsMenu(); +const itemId = settingsMenu.register({ + id: "my-settings", + title: "My Module Settings", + icon: "lucide-wrench", + component: markRaw(MySettingsPage), + group: "Modules", + priority: 10, +}); + +onBeforeUnmount(() => { + settingsMenu.unregister(itemId); +}); +``` + +### Conditional registration based on permissions + +```typescript +import { useSettingsMenu } from "@vc-shell/framework"; +import { usePermissions } from "@vc-shell/framework"; + +const settingsMenu = useSettingsMenu(); +const { hasAccess } = usePermissions(); + +if (hasAccess("catalog:manage")) { + settingsMenu.register({ + id: "catalog-advanced", + title: "Advanced Catalog Settings", + icon: "lucide-settings-2", + component: markRaw(AdvancedCatalogSettings), + group: "Catalog", + priority: 99, + }); +} +``` + +## Notes + +- Like other services, items can be pre-registered before the service exists using `addSettingsMenuItem()` from the settings-menu-service module. They are flushed when `provideSettingsMenu()` runs. +- The service is a singleton per provide scope -- `provideSettingsMenu()` reuses an existing service if already provided by an ancestor. +- The service disposes automatically when the providing component's scope is destroyed. +- If `useSettingsMenu()` is called without a provided service, it throws an `InjectionError` with a descriptive message. + +## Tip: Use markRaw for Component References + +When passing component references to `register()`, wrap them with `markRaw()` to prevent Vue from making them reactive. Reactive component objects can cause performance issues and unexpected behavior: + +```typescript +import { markRaw } from "vue"; + +// Good: prevents unnecessary reactivity +settingsMenu.register({ + component: markRaw(MySettingsPage), + // ... +}); + +// Bad: Vue makes the component object deeply reactive +settingsMenu.register({ + component: MySettingsPage, + // ... +}); +``` + +## Related + +- [useMenuService](./useMenuService.md) -- similar pattern for the main navigation menu +- [useDashboard](./useDashboard.md) -- similar service pattern for dashboard widgets +- `framework/core/services/settings-menu-service.ts` -- the underlying service implementation +- `framework/injection-keys.ts` -- `SettingsMenuServiceKey` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useToolbar.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useToolbar.md new file mode 100644 index 0000000000..d31e4b4d81 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useToolbar.md @@ -0,0 +1,374 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useToolbar/useToolbar.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! tip "Long page" +Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Updating Button State Dynamically](#updating-button-state-dynamically), [Visibility and Permissions](#visibility-and-permissions), or [API Reference](#api-reference). + +# useToolbar + +Manages toolbar buttons for blades. Each blade in the application has its own toolbar area at the top of the blade header. `useToolbar` provides a scoped API to register, update, and remove buttons within that toolbar. It automatically resolves the current blade context and cleans up registered items when the component unmounts. + +## When to Use + +- Add action buttons (Save, Delete, Refresh, Export) to a blade's toolbar header +- Dynamically update button state (disabled, visible, icon) in response to loading or form changes +- When NOT to use: for global app-bar actions -- use `useAppBarWidget`; for navigation links -- use `useMenuService` + +## Quick Start + +```typescript +<script setup lang="ts"> +import { useToolbar } from "@vc-shell/framework"; + +const { registerToolbarItem } = useToolbar(); + +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => saveData(), +}); +</script> +``` + +The button appears in the current blade's toolbar immediately. When the component unmounts, the button is automatically removed. + +## Registering Toolbar Buttons + +Every toolbar button requires a unique `id`. The remaining properties control appearance, behavior, and ordering. + +```typescript +<script setup lang="ts"> +import { useToolbar } from "@vc-shell/framework"; + +const { registerToolbarItem } = useToolbar(); + +// Primary action — highest priority, appears first +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + priority: 100, +}); + +// Secondary action — lower priority, appears after Save +registerToolbarItem({ + id: "refresh", + title: "Refresh", + icon: "fas fa-sync", + clickHandler: () => refresh(), + priority: 50, +}); + +// Destructive action with permission gate +registerToolbarItem({ + id: "delete", + title: "Delete", + icon: "fas fa-trash", + clickHandler: () => confirmDelete(), + priority: 10, + permissions: "order:delete", +}); +</script> +``` + +> **Note:** The `priority` field controls display order. Higher values appear first (leftmost). The default is `0`. + +## Updating Button State Dynamically + +Use `updateToolbarItem` to change any property of a registered button without re-registering it. This is the recommended pattern for toggling disabled state during async operations. + +```typescript +<script setup lang="ts"> +import { watch } from "vue"; +import { useToolbar, useAsync } from "@vc-shell/framework"; + +const { registerToolbarItem, updateToolbarItem } = useToolbar(); + +const { loading, action: save } = useAsync(async () => { + const client = await getApiClient(); + await client.saveOrder(order.value); +}); + +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + priority: 100, +}); + +// Disable the Save button while the request is in-flight +watch(loading, (isLoading) => { + updateToolbarItem("save", { disabled: isLoading }); +}); +</script> +``` + +You can update any subset of `IToolbarItem` properties: + +```typescript +// Change the icon and title after a state transition +updateToolbarItem("toggle-publish", { + title: isPublished.value ? "Unpublish" : "Publish", + icon: isPublished.value ? "fas fa-eye-slash" : "fas fa-eye", +}); +``` + +## Visibility and Permissions + +Toolbar items support both reactive visibility and permission-based access control. + +### Reactive visibility with `isVisible` + +The `isVisible` property accepts a boolean, a `Ref<boolean>`, a `ComputedRef<boolean>`, or a function: + +```typescript +import { computed } from "vue"; + +const hasChanges = computed(() => form.isDirty); + +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + isVisible: hasChanges, // button only appears when the form is dirty +}); +``` + +### Permission-based registration + +Use `usePermissions` alongside `useToolbar` to conditionally register buttons: + +```typescript +import { useToolbar, usePermissions } from "@vc-shell/framework"; + +const { registerToolbarItem } = useToolbar(); +const { hasAccess } = usePermissions(); + +if (hasAccess("order:delete")) { + registerToolbarItem({ + id: "delete", + title: "Delete", + icon: "fas fa-trash", + clickHandler: () => deleteOrder(), + }); +} +``` + +Alternatively, set the `permissions` property on the item itself. The toolbar renderer checks this before displaying the button: + +```typescript +registerToolbarItem({ + id: "delete", + title: "Delete", + icon: "fas fa-trash", + clickHandler: () => deleteOrder(), + permissions: ["order:delete"], +}); +``` + +## Cross-Blade Toolbar Management + +By default, all methods operate on the current blade. Pass an explicit `targetBladeId` to manage another blade's toolbar: + +```typescript +// Register a button on a specific child blade +registerToolbarItem({ id: "child-action", title: "Action", clickHandler: () => {} }, "ChildBlade"); + +// Clear another blade's toolbar +clearBladeToolbarItems("ChildBlade"); +``` + +## Auto-Cleanup Control + +By default, all toolbar items registered by a component are removed when that component unmounts (`autoCleanup: true`). Disable this for shared toolbar items that should persist: + +```typescript +const { registerToolbarItem } = useToolbar({ autoCleanup: false }); + +// These items survive the component's unmount cycle +registerToolbarItem({ + id: "global-help", + title: "Help", + icon: "fas fa-question-circle", + clickHandler: () => openHelp(), +}); +``` + +## Recipes + +### Complete Blade with Save / Delete / Refresh + +```typescript +<script setup lang="ts"> +import { watch } from "vue"; +import { useToolbar, useAsync, usePermissions, useApiClient } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; + +const { registerToolbarItem, updateToolbarItem } = useToolbar(); +const { hasAccess } = usePermissions(); +const { getApiClient } = useApiClient(OrderClient); + +const { loading: saving, action: save } = useAsync(async () => { + const client = await getApiClient(); + await client.updateOrder(order.value); +}); + +const { loading: refreshing, action: refresh } = useAsync(async () => { + const client = await getApiClient(); + order.value = await client.getOrderById(props.param); +}); + +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + priority: 100, +}); + +registerToolbarItem({ + id: "refresh", + title: "Refresh", + icon: "fas fa-sync", + clickHandler: () => refresh(), + priority: 50, +}); + +if (hasAccess("order:delete")) { + registerToolbarItem({ + id: "delete", + title: "Delete", + icon: "fas fa-trash", + clickHandler: () => confirmDelete(), + priority: 10, + }); +} + +// Disable all buttons while any operation is running +watch([saving, refreshing], ([s, r]) => { + const busy = s || r; + updateToolbarItem("save", { disabled: busy }); + updateToolbarItem("refresh", { disabled: busy }); +}); +</script> +``` + +### Visual Separator Between Button Groups + +Use the `separator` property to add a vertical divider: + +```typescript +registerToolbarItem({ + id: "export", + title: "Export", + icon: "fas fa-download", + clickHandler: () => exportData(), + separator: "left", // adds a divider to the left of this button + priority: 20, +}); +``` + +## Common Mistakes + +### Forgetting the `id` property + +```typescript +// Wrong -- id is required, registration silently fails without it +registerToolbarItem({ + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), +}); + +// Correct +registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), +}); +``` + +### Re-registering instead of updating + +```typescript +// Wrong -- creates duplicate entries on each loading state change +watch(loading, (isLoading) => { + registerToolbarItem({ + id: "save", + title: "Save", + disabled: isLoading, + clickHandler: () => save(), + }); +}); + +// Correct -- update the existing registration +watch(loading, (isLoading) => { + updateToolbarItem("save", { disabled: isLoading }); +}); +``` + +### Using useToolbar outside a component setup + +```typescript +// Wrong -- no component instance, autoCleanup will not work +function helperFunction() { + const { registerToolbarItem } = useToolbar(); + registerToolbarItem({ id: "test", title: "Test" }); +} + +// Correct -- call in <script setup> or within setup() +``` + +## API Reference + +### Parameters + +| Parameter | Type | Required | Default | Description | +| --------- | ------------------- | -------- | ------- | --------------------- | +| `options` | `UseToolbarOptions` | No | `{}` | Configuration options | + +#### UseToolbarOptions + +| Option | Type | Default | Description | +| ------------- | --------- | ------- | ------------------------------------------------------------------ | +| `autoCleanup` | `boolean` | `true` | Clear all toolbar items for the current blade on component unmount | + +### Returns: `UseToolbarReturn` + +| Property | Type | Description | +| ------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- | +| `registerToolbarItem` | `(item: IToolbarItem, targetBladeId?: string) => void` | Register a toolbar button (scoped to current blade by default) | +| `unregisterToolbarItem` | `(id: string, targetBladeId?: string) => void` | Remove a toolbar button by ID | +| `updateToolbarItem` | `(id: string, partial: Partial<IToolbarItem>, targetBladeId?: string) => void` | Update properties of an existing toolbar button | +| `getToolbarItems` | `(targetBladeId?: string) => IToolbarItem[]` | Get all toolbar items for a blade | +| `clearBladeToolbarItems` | `(targetBladeId?: string) => void` | Remove all toolbar items for a blade | +| `isToolbarItemRegistered` | `(id: string) => boolean` | Check if a toolbar item with the given ID exists | +| `registeredToolbarItems` | `IToolbarRegistration[]` | All registered toolbar items across all blades | + +### IToolbarItem + +| Property | Type | Required | Description | +| -------------- | -------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | +| `id` | `string` | Yes | Unique identifier for the button | +| `title` | `string \| Ref<string> \| ComputedRef<string>` | No | Button label (supports reactive values) | +| `icon` | `string \| (() => string)` | No | Icon class (e.g., `"fas fa-save"`) or a function returning one | +| `clickHandler` | `(app?) => void` | No | Click callback | +| `disabled` | `boolean \| ComputedRef<boolean>` | No | Whether the button is disabled | +| `isVisible` | `boolean \| Ref<boolean> \| ComputedRef<boolean> \| ((blade?) => boolean)` | No | Controls button visibility | +| `priority` | `number` | No | Sort order (higher = displayed first, default `0`) | +| `separator` | `"left" \| "right" \| "both"` | No | Adds a visual divider next to the button | +| `permissions` | `string \| string[]` | No | Required permission(s) to display the button | +| `bladeId` | `string` | No | Target blade ID (auto-resolved from context) | + +## Related + +- [useBlade](../blade-navigation/useBlade.md) -- blade context that toolbar items are scoped to +- [usePermissions](../user/usePermissions.md) -- conditionally register toolbar items based on permissions +- [useAsync](../utilities/useAsync.md) -- wraps async operations with loading state for disabling buttons diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useWidgets.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useWidgets.md new file mode 100644 index 0000000000..0f5ff620d9 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/services/useWidgets.md @@ -0,0 +1,143 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useWidgets/useWidgets.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useWidgets + +Provides access to the `IWidgetService` singleton for managing blade widget registrations, activation state, and external widgets. This is the low-level composable for direct widget service interaction. It exposes the full widget lifecycle API: registering widgets to specific blades, querying registered widgets, tracking active widget state, and managing external (cross-module) widget registrations. + +Also exports `provideWidgetService()` for framework-level initialization and `registerWidget()` / `registerExternalWidget()` for global pre-registration before the service is created. + +## When to Use + +- When you need low-level access to the widget service (register, unregister, query widgets) +- When building framework infrastructure that manages widget lifecycles +- When pre-registering widgets from a module's `install()` function before the component tree exists +- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use headless widgets. + +## Quick Start + +```typescript +import { useWidgets } from "@vc-shell/framework"; + +const widgetService = useWidgets(); + +// Query all widgets registered for a specific blade +const widgets = widgetService.getWidgets("order-details"); + +// Check if a widget is currently active (visible and expanded) +if (widgetService.isActiveWidget("order-status-widget")) { + // widget is currently in focus +} +``` + +## API + +### Parameters + +None. + +### Returns (`IWidgetService`) + +| Property / Method | Type | Description | +| ---------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| `registerWidget` | `(widget: IWidget, bladeId: string) => void` | Registers a widget for a specific blade. The widget will appear in that blade's widget area. | +| `unregisterWidget` | `(widgetId: string, bladeId: string) => void` | Removes a widget from a blade by ID. | +| `getWidgets` | `(bladeId: string) => IWidget[]` | Returns all widgets registered for a specific blade. | +| `clearBladeWidgets` | `(bladeId: string) => void` | Removes all widgets for a blade (used during blade teardown). | +| `registeredWidgets` | `IWidgetRegistration[]` | All widget registrations across all blades. | +| `isActiveWidget` | `(id: string) => boolean` | Checks if a widget is currently active (selected/expanded). | +| `setActiveWidget` | `(args) => void` | Sets a widget as active with its exposed instance. | +| `updateActiveWidget` | `() => void` | Triggers the active widget's update function. Deprecated -- use headless widgets instead. | +| `isWidgetRegistered` | `(id: string) => boolean` | Checks if a widget ID exists in any blade's registry. | +| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). | +| `resolveWidgetProps` | `(widget, bladeData) => Record<string, unknown>` | Resolves widget props from blade data. Deprecated. | +| `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules). | +| `getAllExternalWidgets` | `() => IExternalWidgetRegistration[]` | Gets all registered external widgets across all modules. | + +### Additional Exports + +| Export | Description | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `provideWidgetService()` | Creates and provides the widget service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. | +| `registerWidget(widget, bladeId)` | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`. | +| `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules. | + + + +## Recipe: Pre-Registering a Widget from a Module + +```typescript +// my-module/index.ts +import { registerWidget } from "@vc-shell/framework"; +import { markRaw } from "vue"; +import OrderStatusWidget from "./widgets/OrderStatusWidget.vue"; + +export default { + install() { + registerWidget( + { + id: "order-status", + title: "Order Status", + component: markRaw(OrderStatusWidget), + icon: "fas fa-clipboard-check", + }, + "order-details", // blade ID where this widget appears + ); + }, +}; +``` + +## Recipe: Cross-Module Widget Extension + +A shipping module can add a widget to the order module's detail blade: + +```typescript +// shipping-module/index.ts +import { registerExternalWidget } from "@vc-shell/framework"; +import { markRaw } from "vue"; +import ShippingTracker from "./widgets/ShippingTracker.vue"; + +export default { + install() { + registerExternalWidget({ + widgetId: "shipping-tracker", + bladeId: "order-details", // target blade from another module + component: markRaw(ShippingTracker), + title: "Shipping", + icon: "fas fa-truck", + }); + }, +}; +``` + +## Recipe: Listing All Widgets for a Blade + +```vue +<script setup lang="ts"> +import { useWidgets } from "@vc-shell/framework"; +import { computed } from "vue"; + +const props = defineProps<{ bladeId: string }>(); +const widgetService = useWidgets(); + +const bladeWidgets = computed(() => widgetService.getWidgets(props.bladeId)); +const externalWidgets = computed(() => widgetService.getExternalWidgetsForBlade(props.bladeId)); + +const allWidgets = computed(() => [...bladeWidgets.value, ...externalWidgets.value]); +</script> +``` + +## Tips + +- **Use `markRaw` for widget components.** Widget components stored in the registry should be wrapped with `markRaw()` to prevent Vue from making them reactive, which causes warnings and unnecessary overhead. +- **Prefer `useBladeWidgets()` for typical blade work.** It handles registration/unregistration tied to the blade lifecycle automatically. Only use `useWidgets()` when you need direct access to the global service. +- **`provideWidgetService()` is idempotent.** Calling it multiple times in the same component tree returns the same service instance. This is safe for nested module structures. +- **Widget IDs must be globally unique.** Since widgets can be registered from multiple modules targeting the same blade, use descriptive, namespaced IDs like `'shipping-tracker'` rather than generic names like `'status'`. + +## Related + +- [useWidget](../useWidget/useWidget.docs.md) -- widget-side composable for registering trigger contracts (badge, refresh) +- [useBladeWidgets](../useBladeWidgets/) -- lifecycle-managed widget registration for blades (preferred API) +- `framework/core/services/widget-service.ts` -- underlying service implementation diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/.pages new file mode 100644 index 0000000000..59990c9f4c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/.pages @@ -0,0 +1,14 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: UI State +nav: + - UI Composables: ui-composables-overview.md + - useBreadcrumbs: useBreadcrumbs.md + - useConnectionStatus: useConnectionStatus.md + - useKeyboardNavigation: useKeyboardNavigation.md + - useLoading: useLoading.md + - useMenuExpanded: useMenuExpanded.md + - useResponsive: useResponsive.md + - useSidebarState: useSidebarState.md + - useSlowNetworkDetection: useSlowNetworkDetection.md + - useTheme: useTheme.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/ui-composables-overview.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/ui-composables-overview.md new file mode 100644 index 0000000000..d51838d354 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/ui-composables-overview.md @@ -0,0 +1,105 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/composables/ui-composables.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# UI Composables + +Shared composables for the VC-Shell UI component library. These provide reusable logic for layout, positioning, form fields, and scroll behavior. + +## Overview + +All composables are exported from `framework/ui/composables/index.ts` and available via `@vc-shell/framework`. They are designed for use inside `<script setup>` components. + +## Exports + +| Composable | Purpose | +| --------------------- | ---------------------------------------------------------------------------------- | +| `useAdaptiveItems` | Measures and distributes items into visible/hidden groups based on container width | +| `useScrollArrows` | Tracks scroll overflow state and provides animated scroll-by-arrow controls | +| `useFloatingPosition` | Wrapper around `@floating-ui/vue` with sensible defaults for dropdowns/tooltips | +| `useTeleportTarget` | Resolves a consistent teleport target (explicit target, app root, or body) | +| `useFormField` | Shared form field logic: unique IDs, ARIA attributes, InputGroup integration | +| `useCollapsible` | Expand/collapse panel with measured content height and CSS transitions | + +## API Details + +### useAdaptiveItems + +Measures natural widths of child elements (marked with `data-item-key`) and splits items into `visibleItems` / `hiddenItems` arrays based on available container width. Handles a "more" button (marked with `data-more-button`) using a two-pass layout algorithm. + +```typescript +const { visibleItems, hiddenItems, showMoreButton, recalculate } = useAdaptiveItems({ + containerRef, + items: tabs, + getItemKey: (tab) => tab.id, + moreButtonWidth: 40, + calculationStrategy: "forward", // or "reverse" +}); +``` + +Options: `calculationStrategy: "reverse"` fills from the end (useful for right-aligned toolbars). A `ResizeObserver` tracks element width changes automatically. + +### useScrollArrows + +Provides `canScrollUp` / `canScrollDown` booleans and `startScroll(direction)` / `stopScroll()` methods for scroll-arrow UI. Uses `requestAnimationFrame` for smooth scrolling. + +```typescript +const { canScrollUp, canScrollDown, startScroll, stopScroll } = useScrollArrows(viewportRef, { + speed: 3, // pixels per frame, default: 2 +}); +``` + +### useFloatingPosition + +Wraps `@floating-ui/vue` with reactive placement, offset, flip, and shift middleware. Returns `floatingStyle` for direct binding. + +```typescript +const { floatingStyle, placement } = useFloatingPosition(referenceEl, floatingEl, { + placement: "bottom-start", + offset: { mainAxis: 4 }, + enableFlip: true, + enableShift: true, +}); +``` + +### useTeleportTarget + +Resolves teleport destination with priority: explicit `to` option, then injected `AppRootElementKey`, then `"body"`. + +```typescript +const { teleportTarget } = useTeleportTarget({ fallbackToBody: true }); +// <Teleport :to="teleportTarget"> +``` + +### useFormField + +Generates unique field/label/error/hint IDs and computes ARIA attributes. Integrates with `VcInputGroup` context for grouped disabled/invalid state. + +```typescript +const { fieldId, invalid, resolvedDisabled, ariaDescribedBy } = useFormField(props); +``` + +### useCollapsible + +Manages expand/collapse animation via measured `scrollHeight`. Returns `wrapperStyle` to bind on the overflow wrapper and `contentRef` to attach to the inner content. + +```typescript +const { isExpanded, toggle, wrapperStyle, contentRef, hasOverflow } = useCollapsible({ + collapsedHeight: 100, + maxExpandedHeight: 400, +}); +``` + +## Tips + +- `useAdaptiveItems` requires `data-item-key` attributes on rendered children and `data-more-button` on the overflow trigger for automatic measurement. +- `useFloatingPosition` enables flip and shift by default. Pass `enableFlip: false` to disable. +- `useFormField` auto-detects `InputGroupContext` via inject -- no extra wiring needed inside `VcInputGroup`. +- All composables clean up resources (observers, animation frames) in `onBeforeUnmount`. + +## Related + +- `framework/ui/components/molecules/vc-dropdown/` -- uses `useFloatingPosition` +- `framework/ui/components/molecules/vc-input/` -- uses `useFormField` +- `framework/shared/components/sidebar/` -- uses `useScrollArrows` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useBreadcrumbs.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useBreadcrumbs.md new file mode 100644 index 0000000000..9be21dff7a --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useBreadcrumbs.md @@ -0,0 +1,185 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBreadcrumbs/useBreadcrumbs.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBreadcrumbs + +Manages a reactive breadcrumb trail for blade navigation. Supports push, remove, and automatic trail trimming on click. + +## Overview + +In the vc-shell blade navigation paradigm, users often drill down through multiple levels: a list blade opens a detail blade, which opens a related entity blade, and so on. The breadcrumb trail provides a visual path showing where the user is in this hierarchy and allows jumping back to any previous level. + +The `useBreadcrumbs()` composable manages this trail as a reactive array. Each blade pushes its breadcrumb on mount and optionally removes it on unmount. When a user clicks a breadcrumb, the trail is automatically trimmed to that point -- all items after the clicked breadcrumb are removed. + +The composable uses `shallowRef` internally for performance, creating new array references only when the trail changes. Breadcrumbs with the same `id` are deduplicated: pushing a breadcrumb with an existing ID updates it in place rather than creating a duplicate. + +## When to Use + +- When building multi-level blade navigation with a visible breadcrumb trail +- When blades need to register their position in the navigation hierarchy +- Do NOT use for URL-based routing breadcrumbs -- this is for blade stack navigation only + +## Basic Usage + +```typescript +import { useBreadcrumbs } from "@vc-shell/framework"; + +const { breadcrumbs, push, remove } = useBreadcrumbs(); + +push({ + id: "orders", + title: "Orders", + clickHandler: (id) => navigateToOrders(), +}); +``` + +## API + +### Returns + +| Property | Type | Description | +| ------------- | ----------------------------------- | ------------------------------------------------------------------- | +| `breadcrumbs` | `ComputedRef<Breadcrumbs[]>` | Reactive array of current breadcrumb items | +| `push` | `(breadcrumb: Breadcrumbs) => void` | Add a breadcrumb (deduplicates by `id`, updates in place if exists) | +| `remove` | `(ids: string[]) => void` | Remove breadcrumbs by their IDs | + +### Breadcrumbs Interface + +| Property | Type | Required | Description | +| -------------- | ------------------------------------------------------------- | -------- | -------------------------------------------------------- | +| `id` | `string` | Yes | Unique identifier for the breadcrumb | +| `title` | `MaybeRef<string \| undefined>` | Yes | Display text (can be reactive) | +| `icon` | `string?` | No | Icon identifier | +| `clickHandler` | `(id: string) => void \| boolean \| Promise<void \| boolean>` | No | Click callback; return `false` to prevent trail trimming | + +## Common Patterns + +### Registering breadcrumbs in a blade + +```typescript +<script setup lang="ts"> +import { useBreadcrumbs, useBlade } from "@vc-shell/framework"; +import { computed } from "vue"; + +const { push } = useBreadcrumbs(); +const { openBlade, param } = useBlade(); + +push({ + id: `order-${param.value}`, + title: computed(() => `Order #${orderNumber.value}`), + clickHandler: () => { + openBlade({ name: "OrderDetails", param: param.value }); + }, +}); +</script> +``` + +### Multi-level breadcrumb trail + +```typescript +<script setup lang="ts"> +import { useBreadcrumbs, useBladeContext } from "@vc-shell/framework"; + +const { push } = useBreadcrumbs(); +const { openBlade } = useBladeContext(); + +// Level 1: Catalog +push({ + id: "catalog", + title: "Catalog", + icon: "lucide-package", + clickHandler: () => openBlade({ name: "CatalogList" }), +}); + +// Level 2: Category +push({ + id: `category-${categoryId.value}`, + title: computed(() => category.value?.name ?? "Category"), + clickHandler: () => openBlade({ name: "CategoryDetails", param: categoryId.value }), +}); + +// Level 3: Product (current blade -- no clickHandler needed) +push({ + id: `product-${productId.value}`, + title: computed(() => product.value?.name ?? "Product"), +}); +</script> +``` + +### Cleaning up on blade close + +```typescript +<script setup lang="ts"> +import { useBreadcrumbs } from "@vc-shell/framework"; +import { onBeforeUnmount } from "vue"; + +const { push, remove } = useBreadcrumbs(); +const crumbId = "my-blade"; + +push({ id: crumbId, title: "My Blade" }); + +onBeforeUnmount(() => { + remove([crumbId]); +}); +</script> +``` + +### Preventing automatic trail trimming + +If your breadcrumb click handler performs custom navigation logic (e.g., confirming unsaved changes before navigating), return `false` to prevent the composable from automatically trimming the trail: + +```typescript +push({ + id: "order-edit", + title: "Edit Order", + clickHandler: async (id) => { + if (hasUnsavedChanges.value) { + const confirmed = await confirmDialog("Discard unsaved changes?"); + if (!confirmed) { + return false; // Prevent trail trimming, stay on current blade + } + } + openBlade({ name: "OrderDetails", param: orderId.value }); + // Return void (or true) to allow trimming + }, +}); +``` + +## Notes + +- When a breadcrumb's `clickHandler` succeeds (returns `void` or `true`), the trail is automatically trimmed to that breadcrumb -- all items after it are removed. +- If `clickHandler` returns `false`, trimming is skipped, allowing custom navigation logic. +- Pushing a breadcrumb with an existing `id` updates it in place rather than adding a duplicate. +- If the `clickHandler` throws an error, it is caught and logged via the framework logger. The trail is not modified. +- The `title` property accepts `MaybeRef<string>`, meaning you can pass either a plain string or a `computed`/`ref` for dynamic titles that update reactively. + +## Tip: Use Blade Param in Breadcrumb ID + +Include the blade's param (e.g., entity ID) in the breadcrumb `id` to ensure uniqueness when the same blade type can appear at different positions in the trail: + +```typescript +// Good: unique per entity +push({ id: `order-${orderId.value}`, title: "Order #123" }); + +// Bad: same ID for all order blades -- will overwrite each other +push({ id: "order-details", title: "Order #123" }); +``` + +## Common Mistake + +Do not forget to clean up breadcrumbs when a blade is closed. Without cleanup, stale breadcrumbs accumulate in the trail and point to blades that no longer exist: + +```typescript +// Always pair push with remove on unmount +const crumbId = `product-${productId.value}`; +push({ id: crumbId, title: "Product" }); +onBeforeUnmount(() => remove([crumbId])); +``` + +## Related + +- [useBlade](../blade-navigation/useBlade.md) -- blade navigation composable +- [VcBlade](../../components/layout/vc-blade.md) -- blade component that displays breadcrumbs +- `framework/ui/types/form-field.ts` -- `Breadcrumbs` interface definition diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useConnectionStatus.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useConnectionStatus.md new file mode 100644 index 0000000000..6027bb0288 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useConnectionStatus.md @@ -0,0 +1,113 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useConnectionStatus/useConnectionStatus.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useConnectionStatus + +Monitors the browser's network connectivity and shows a persistent notification when the user goes offline. This composable wraps `@vueuse/core`'s `useNetwork()` and adds framework-specific behavior: it displays a warning notification via the vc-shell notification system, applies a `vc-offline` CSS class to `<html>` for global styling hooks, and logs state changes through the framework logger. The state is a module-level singleton, so only one set of event listeners is ever created regardless of how many components call the composable. + +## When to Use + +- Reactively check online/offline status anywhere in the app to disable buttons, show banners, or skip network requests +- Automatically notify users when they lose connectivity (happens out of the box) +- When NOT to use: for server-side health checks or API availability monitoring (this only detects browser-level network state via `navigator.onLine`) + +## Quick Start + +```vue +<script setup lang="ts"> +import { useConnectionStatus } from "@vc-shell/framework"; + +const { isOnline } = useConnectionStatus(); +</script> + +<template> + <VcBlade title="Order Details"> + <div + v-if="!isOnline" + class="tw-bg-yellow-100 tw-p-2 tw-rounded tw-mb-4" + > + You are offline. Changes will not be saved until connectivity is restored. + </div> + + <VcButton + :disabled="!isOnline" + @click="save" + >Save Order</VcButton + > + </VcBlade> +</template> +``` + +## API + +### Returns + +| Property | Type | Description | +| ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- | +| `isOnline` | `Readonly<Ref<boolean>>` | `true` when the browser has network connectivity, `false` when offline. Read-only to prevent external mutation. | + + + +## Recipe: Disabling Auto-Save While Offline + +```vue +<script setup lang="ts"> +import { useConnectionStatus } from "@vc-shell/framework"; +import { watch, ref } from "vue"; + +const { isOnline } = useConnectionStatus(); +const pendingSave = ref(false); +const formData = ref({ name: "" }); + +// Auto-save on changes, but only when online +watch( + formData, + () => { + if (isOnline.value) { + saveToServer(formData.value); + } else { + pendingSave.value = true; + } + }, + { deep: true }, +); + +// Flush pending save when connectivity returns +watch(isOnline, (online) => { + if (online && pendingSave.value) { + saveToServer(formData.value); + pendingSave.value = false; + } +}); + +async function saveToServer(data: typeof formData.value) { + await api.updateItem(data); +} +</script> +``` + +## Recipe: Custom Offline Styling with the CSS Class + +The composable adds `vc-offline` to `<html>` when offline. You can use this in your global styles: + +```scss +// In your app's global stylesheet +html.vc-offline { + .vc-app-bar { + border-bottom: 2px solid var(--warning-500); + } +} +``` + +## Tips + +- **Singleton by design.** You can call `useConnectionStatus()` in 50 different components and they all share the same underlying `useNetwork()` watcher and reactive state. There is zero overhead from multiple calls. +- **`navigator.onLine` has limitations.** The browser considers itself "online" if it has any network interface active, even if that interface cannot reach the internet. A connected WiFi with no gateway will still report `isOnline: true`. +- **The notification cannot be dismissed while offline.** Because it uses `timeout: false`, it stays visible until the `notification.remove()` call fires on reconnection. This is intentional -- users should always know they are offline. + +## Related + +- `@vueuse/core` `useNetwork` -- underlying browser API wrapper +- `notification` from `@shared/components/notifications` -- the notification system used to display the offline warning diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useKeyboardNavigation.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useKeyboardNavigation.md new file mode 100644 index 0000000000..d29f5ab8b4 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useKeyboardNavigation.md @@ -0,0 +1,172 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useKeyboardNavigation + +Implements keyboard navigation (Arrow keys, Tab, Enter, Escape) within a container of focusable elements. This composable provides full WAI-ARIA-style keyboard interaction for custom menus, dropdowns, autocomplete lists, and other composite widgets that are not natively keyboard-accessible. It manages a focused-item index, handles wrap-around (looping), and automatically attaches/detaches event listeners tied to the component lifecycle. + +The composable supports two attachment modes: **auto-attach** on mount via a CSS selector (for static containers), and **manual attach** via `initKeyboardNavigation(el)` (for dynamic or ref-based containers). + +## When to Use + +- Add accessible keyboard navigation to custom menus, dropdowns, or list components +- Implement roving tabindex patterns for composite widgets +- When NOT to use: for standard form tab order (native browser behavior is sufficient), or for simple lists where `tabindex` on each item already works + +## Quick Start + +```vue +<script setup lang="ts"> +import { useKeyboardNavigation } from "@vc-shell/framework"; +import { ref } from "vue"; + +const menuRef = ref<HTMLElement | null>(null); +const items = ref(["Dashboard", "Products", "Orders", "Settings"]); + +const { initKeyboardNavigation, focusFirstElement } = useKeyboardNavigation({ + itemSelector: '[role="menuitem"]', + onEnter: (el) => { + el.click(); + }, + onEscape: () => { + // Close menu or return focus to trigger + }, + loop: true, +}); + +function openMenu() { + // After the menu is shown, attach keyboard navigation and focus first item + nextTick(() => { + if (menuRef.value) { + initKeyboardNavigation(menuRef.value); + focusFirstElement(); + } + }); +} +</script> + +<template> + <div + ref="menuRef" + role="menu" + > + <div + v-for="item in items" + :key="item" + role="menuitem" + tabindex="0" + @click="selectItem(item)" + > + {{ item }} + </div> + </div> +</template> +``` + +## API + +### Parameters (Options Object) + +| Parameter | Type | Default | Description | +| ------------------- | --------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | +| `containerSelector` | `string` | `'[role="menu"]'` | CSS selector to auto-find the container on mount. Set to empty string to disable auto-attach. | +| `itemSelector` | `string` | `'[tabindex="0"]'` | CSS selector for focusable items inside the container. | +| `onEnter` | `(el: HTMLElement) => void` | `undefined` | Called when Enter or Space is pressed on a focused item. Falls back to `el.click()` if not provided. | +| `onEscape` | `() => void` | `undefined` | Called when Escape is pressed. Typically used to close the menu or popover. | +| `loop` | `boolean` | `true` | When `true`, pressing ArrowDown on the last item wraps to the first, and ArrowUp on the first wraps to the last. | + +### Returns + +| Property | Type | Description | +| --------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | +| `initKeyboardNavigation` | `(el: HTMLElement) => void` | Manually attach keyboard listener to an element. Cleans up any previous attachment first. | +| `cleanupKeyboardNavigation` | `() => void` | Remove listener and reset state. Called automatically on `onBeforeUnmount`. | +| `focusNextElement` | `() => void` | Move focus to the next item. Wraps if `loop` is `true`. | +| `focusPreviousElement` | `() => void` | Move focus to the previous item. Wraps if `loop` is `true`. | +| `focusFirstElement` | `() => void` | Focus the first matching item in the container. | +| `focusLastElement` | `() => void` | Focus the last matching item in the container. | +| `setFocusedIndex` | `(index: number) => void` | Set focus to a specific index. No-op if index is out of bounds. | +| `getFocusedIndex` | `() => number` | Get the currently focused index (`-1` if no item is focused). | + + + +## Recipe: Keyboard-Navigable Autocomplete Dropdown + +```vue +<script setup lang="ts"> +import { useKeyboardNavigation } from "@vc-shell/framework"; +import { ref, watch, nextTick } from "vue"; + +const dropdownRef = ref<HTMLElement | null>(null); +const isOpen = ref(false); +const suggestions = ref<string[]>([]); + +const { initKeyboardNavigation, cleanupKeyboardNavigation, focusFirstElement } = useKeyboardNavigation({ + containerSelector: "", // disable auto-attach + itemSelector: ".suggestion-item", + onEnter: (el) => { + selectSuggestion(el.dataset.value!); + isOpen.value = false; + }, + onEscape: () => { + isOpen.value = false; + }, + loop: true, +}); + +watch(isOpen, async (open) => { + if (open) { + await nextTick(); + if (dropdownRef.value) { + initKeyboardNavigation(dropdownRef.value); + focusFirstElement(); + } + } else { + cleanupKeyboardNavigation(); + } +}); + +function selectSuggestion(value: string) { + // handle selection +} +</script> + +<template> + <div> + <VcInput + @focus="isOpen = true" + @input="fetchSuggestions" + /> + <div + v-if="isOpen" + ref="dropdownRef" + class="suggestion-dropdown" + > + <div + v-for="item in suggestions" + :key="item" + :data-value="item" + class="suggestion-item" + tabindex="0" + > + {{ item }} + </div> + </div> + </div> +</template> +``` + +## Tips + +- **Use `nextTick` before attaching.** If the container is conditionally rendered (e.g., a `v-if` dropdown), the DOM element does not exist yet during the same tick. Always await `nextTick()` before calling `initKeyboardNavigation`. +- **Items are re-queried on every key press.** This means dynamically added or removed items are picked up automatically. You do not need to re-initialize after the list changes. +- **`loop: false` stops at boundaries.** When looping is disabled, pressing ArrowDown on the last item or ArrowUp on the first item does nothing. This is appropriate for linear navigation patterns. +- **Clean up if you manually init.** While auto-attached listeners are cleaned up on `onBeforeUnmount`, if you call `initKeyboardNavigation` on a dynamic element, call `cleanupKeyboardNavigation` when that element is removed. +- **Tab key is intercepted.** The composable handles Tab/Shift+Tab within the container, moving focus between items rather than leaving the container. This follows the WAI-ARIA composite widget pattern. + +## Related + +- WAI-ARIA Menu Pattern -- accessibility guidelines for keyboard-navigable menus +- WAI-ARIA Composite Widgets -- general pattern for roving tabindex diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useLoading.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useLoading.md new file mode 100644 index 0000000000..22ee288aec --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useLoading.md @@ -0,0 +1,122 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useLoading/useLoading.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useLoading + +Aggregates multiple reactive boolean loading refs into a single computed that is `true` when any source is loading. This is a minimal utility composable -- just one line of logic -- but it solves a very common problem in blade development: when a component depends on several async data sources, you need a single flag for the loading overlay. Instead of writing `computed(() => loadingA.value || loadingB.value || loadingC.value)` in every blade, `useLoading` provides a clean, readable shorthand that scales to any number of sources. + +## When to Use + +- When a component depends on several async data sources and needs a single loading indicator +- To merge loading states from multiple composables into one reactive flag for `VcBlade`'s `:loading` prop +- When NOT to use: for a single loading ref, just use it directly -- the composable adds no value with one argument + +## Quick Start + +```typescript +import { useLoading } from "@vc-shell/framework"; + +const combinedLoading = useLoading(loadingA, loadingB, loadingC); +// combinedLoading.value === true when ANY of the three is true +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| --------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `...args` | `Readonly<Ref<boolean>>[]` | Yes | One or more reactive boolean refs to aggregate. Accepts `Ref<boolean>`, `ComputedRef<boolean>`, or any `Readonly<Ref<boolean>>`. | + +### Returns + +| Type | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------ | +| `ComputedRef<boolean>` | `true` if any of the input refs is `true`, `false` otherwise. Re-evaluates whenever any input changes. | + + + +## Recipe: Blade with Multiple Data Sources + +```vue +<template> + <VcBlade + title="Order Details" + :loading="isLoading" + > + <div class="tw-grid tw-grid-cols-2 tw-gap-4"> + <VcCard title="Order Info"> + <p>{{ order?.number }}</p> + </VcCard> + <VcCard title="Customer"> + <p>{{ customer?.name }}</p> + </VcCard> + </div> + <VcDataTable + :items="lineItems" + :columns="columns" + /> + </VcBlade> +</template> + +<script setup lang="ts"> +import { useLoading } from "@vc-shell/framework"; +import { useOrder } from "../composables/useOrder"; +import { useCustomer } from "../composables/useCustomer"; +import { useLineItems } from "../composables/useLineItems"; + +const { order, loading: orderLoading } = useOrder(props.orderId); +const { customer, loading: customerLoading } = useCustomer(props.customerId); +const { lineItems, loading: lineItemsLoading } = useLineItems(props.orderId); + +// Single loading flag for the blade overlay +const isLoading = useLoading(orderLoading, customerLoading, lineItemsLoading); +</script> +``` + +## Recipe: Combining with useAsync + +```typescript +import { useLoading } from "@vc-shell/framework"; +import { useAsync } from "@vc-shell/framework"; + +const { loading: saveLoading, action: save } = useAsync(saveItem); +const { loading: deleteLoading, action: remove } = useAsync(deleteItem); +const { loading: validateLoading, action: validate } = useAsync(validateItem); + +// Disable all toolbar buttons while any operation is in progress +const isBusy = useLoading(saveLoading, deleteLoading, validateLoading); +``` + +## Recipe: Dynamic Loading Sources + +If you have a variable number of loading sources (e.g., loaded from a plugin system), collect them into an array and spread: + +```typescript +import { useLoading } from "@vc-shell/framework"; +import { Ref } from "vue"; + +const loadingRefs: Ref<boolean>[] = []; + +// Modules register their loading states +function registerLoadingSource(ref: Ref<boolean>) { + loadingRefs.push(ref); +} + +// Note: useLoading captures the refs at call time. +// Call it after all sources are registered. +const isAnyLoading = useLoading(...loadingRefs); +``` + +## Tips + +- **Order does not matter.** `useLoading(a, b, c)` and `useLoading(c, a, b)` produce identical behavior. The result is a logical OR. +- **Zero arguments return `false`.** Calling `useLoading()` with no arguments returns a computed that is always `false`. This is technically valid but pointless. +- **Works with any `Readonly<Ref<boolean>>`.** You can pass `ComputedRef<boolean>`, `Ref<boolean>`, `ShallowRef<boolean>`, or any other reactive boolean reference. +- **Each call creates a new computed.** Unlike singleton composables, `useLoading` returns a fresh `ComputedRef` each time. This is intentional -- different blades need independent loading aggregations. + +## Related + +- [useAsync](../utilities/useAsync.md) -- async action wrapper that produces a `loading` ref, commonly combined with `useLoading` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useMenuExpanded.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useMenuExpanded.md new file mode 100644 index 0000000000..7cf2a14d9b --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useMenuExpanded.md @@ -0,0 +1,83 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useMenuExpanded/index.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useMenuExpanded + +Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar). + +## When to Use + +- Low-level control over sidebar pin and hover state +- Building a custom sidebar component that needs expand/collapse persistence +- When NOT to use: prefer `useSidebarState` which wraps this composable and adds mobile menu support, derived `isExpanded` computed, and responsive breakpoint handling + +## Basic Usage + +```typescript +import { useMenuExpanded } from "@vc-shell/framework"; + +const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded(); + +// Toggle pin state (persisted to localStorage) +toggleExpanded(); + +// Hover expand with 200ms delay +toggleHoverExpanded(true); // opens after delay +toggleHoverExpanded(false); // closes immediately +``` + +## API + +### Returns + +| Property | Type | Description | +| --------------------- | ---------------------------------- | ---------------------------------------------------------------- | +| `isExpanded` | `Ref<boolean>` | Pinned state, persisted via `useLocalStorage` | +| `toggleExpanded` | `() => void` | Toggle the pinned state | +| `isHoverExpanded` | `Ref<boolean>` | Temporary hover expansion (not persisted) | +| `toggleHoverExpanded` | `(shouldExpand?: boolean) => void` | Set hover state; opening has a 200ms delay, closing is immediate | + +## Recipe: Custom Sidebar with Hover Expand + +A common pattern is binding mouse events on the sidebar rail so the menu previews its full width on hover, without permanently pinning it open: + +```vue +<script setup lang="ts"> +import { computed } from "vue"; +import { useMenuExpanded } from "@vc-shell/framework"; + +const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded(); + +// The sidebar is visually expanded if pinned OR hover-expanded +const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.value); +</script> + +<template> + <aside + :class="{ 'sidebar--expanded': isVisuallyExpanded }" + @mouseenter="toggleHoverExpanded(true)" + @mouseleave="toggleHoverExpanded(false)" + > + <nav> + <!-- menu items --> + </nav> + <button @click="toggleExpanded"> + {{ isExpanded ? "Unpin" : "Pin" }} + </button> + </aside> +</template> +``` + + + +## Tips + +- If you call `toggleHoverExpanded(true)` and then `toggleHoverExpanded(false)` within the 200ms window, the expansion is canceled -- the timeout is cleared before it fires. +- The composable does not handle mobile breakpoints. For responsive behavior, use `useSidebarState` instead, which combines `useMenuExpanded` with mobile detection. +- Each call to `useMenuExpanded()` creates a new instance with its own timeout tracking, but they share the same localStorage-backed `isExpanded` ref (via `useLocalStorage`). Multiple instances will stay in sync for the pinned state. + +## Related + +- `useSidebarState` -- higher-level composable that adds mobile menu and derived `isExpanded` computed diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useResponsive.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useResponsive.md new file mode 100644 index 0000000000..66ba85e5b8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useResponsive.md @@ -0,0 +1,200 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useResponsive/useResponsive.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useResponsive + +Reactive breakpoint state for building responsive blade UIs. Returns refs that indicate the current viewport category (phone, tablet, mobile, desktop) and whether the device supports touch input. Replaces the legacy `$isMobile.value` global properties in templates and `inject(IsMobileKey)` in script setup with a single, consistent API. + +## When to Use + +- Conditionally render desktop vs. mobile layouts in blade pages and components +- Apply responsive CSS classes based on viewport size +- Toggle behavior (e.g., disable drag-and-drop on touch devices, switch column visibility) +- When NOT to use: for CSS-only responsive changes, prefer Tailwind breakpoint prefixes (`md:`, `lg:`) instead of JavaScript-driven conditionals + +## Quick Start + +```vue +<script setup lang="ts"> +import { useResponsive } from "@vc-shell/framework"; + +const { isMobile, isDesktop } = useResponsive(); +</script> + +<template> + <VcBlade title="Orders"> + <!-- Vue auto-unwraps refs from script setup — no .value needed --> + <div + v-if="isDesktop" + class="tw-flex tw-gap-4" + > + <OrdersTable /> + <OrdersSummary /> + </div> + <OrdersTable v-else /> + </VcBlade> +</template> +``` + +## API + +### Parameters + +None. The composable reads breakpoint state from the framework's provide/inject context, which is set up automatically by `VcApp`. + +### Returns (`UseResponsiveReturn`) + +| Property | Type | Default | Description | +| ----------- | -------------- | ------- | --------------------------------------------------------------------- | +| `isMobile` | `Ref<boolean>` | `false` | `true` when viewport width < 1024px | +| `isDesktop` | `Ref<boolean>` | `true` | `true` when viewport width >= 1024px | +| `isPhone` | `Ref<boolean>` | `false` | `true` when viewport width < 480px | +| `isTablet` | `Ref<boolean>` | `false` | `true` when 480px <= viewport width < 1024px | +| `isTouch` | `boolean` | `false` | `true` on touch-capable devices (not reactive — set once at app init) | + +Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. These match the framework's `setupBreakpoints()` configuration. + +Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold. + + + +## Recipe: Responsive Blade with Mobile Card Layout + +```vue +<script setup lang="ts"> +import { useResponsive, useBlade } from "@vc-shell/framework"; + +const { isMobile, isDesktop } = useResponsive(); +const { openBlade } = useBlade(); +</script> + +<template> + <VcBlade title="Products"> + <VcDataTable + :items="products" + :total-count="totalCount" + @row-click="({ data }) => openBlade({ name: 'ProductDetails', param: data.id })" + > + <VcColumn + id="image" + title="" + type="image" + :width="60" + :always-visible="true" + mobile-role="image" + /> + <VcColumn + id="name" + :title="t('NAME')" + :sortable="true" + :always-visible="true" + mobile-role="title" + /> + <!-- Extra columns visible only on desktop --> + <VcColumn + id="sku" + :title="t('SKU')" + :sortable="true" + /> + <VcColumn + id="price" + :title="t('PRICE')" + type="money" + :sortable="true" + /> + <VcColumn + id="createdDate" + :title="t('DATE')" + type="date-ago" + :sortable="true" + /> + </VcDataTable> + </VcBlade> +</template> +``` + +## Recipe: Touch-Aware Drag and Drop + +```vue +<script setup lang="ts"> +import { useResponsive } from "@vc-shell/framework"; + +const { isTouch } = useResponsive(); +</script> + +<template> + <VcDataTable + :items="items" + :reorderable-rows="!isTouch" + @reorder="onReorder" + > + <!-- columns --> + </VcDataTable> +</template> +``` + +## Common Mistakes + +**Wrong: using `$isMobile.value` in template (deprecated)** + +```vue +<template> + <!-- $isMobile is a global property — requires .value, no auto-unwrap --> + <div v-if="$isMobile.value">Mobile</div> +</template> +``` + +**Correct: using `useResponsive()` destructure** + +```vue +<script setup lang="ts"> +import { useResponsive } from "@vc-shell/framework"; +const { isMobile } = useResponsive(); +</script> +<template> + <!-- Vue auto-unwraps refs from script setup — clean and type-safe --> + <div v-if="isMobile">Mobile</div> +</template> +``` + +--- + +**Wrong: using `inject(IsMobileKey)` directly** + +```vue +<script setup lang="ts"> +import { inject, ref } from "vue"; +import { IsMobileKey } from "@vc-shell/framework"; +// Verbose, requires importing both inject and the key +const isMobile = inject(IsMobileKey, ref(false)); +</script> +``` + +**Correct: using `useResponsive()`** + +```vue +<script setup lang="ts"> +import { useResponsive } from "@vc-shell/framework"; +// One import, one line, all breakpoints available +const { isMobile } = useResponsive(); +</script> +``` + +## Tips + +- **Destructure only what you need.** `const { isMobile } = useResponsive()` is fine — unused refs have no overhead since they already exist at the app level. +- **Prefer CSS breakpoints for styling.** Use `useResponsive()` for structural changes (different component trees), but for spacing/sizing tweaks use Tailwind responsive prefixes (`md:tw-px-4`). +- **`isTouch` is not reactive.** It's determined once at app startup based on `ontouchstart` / `maxTouchPoints`. It won't change if a user connects a mouse to a tablet mid-session. +- **Works in tests without providers.** Defaults to desktop mode (`isDesktop: true`, `isMobile: false`), so most component tests don't need to provide breakpoint keys unless testing mobile-specific behavior. + +## Migration + +See [migration guide #36](../../../../migration/36-use-responsive.md) for automated codemod and manual migration instructions. + +## Related + +- `VcApp` — provides the breakpoint refs that `useResponsive()` reads +- `VcBlade` — uses `isMobile` internally for mobile blade layout +- `VcDataTable` — uses `isMobile` for mobile card rendering and pull-to-refresh diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSidebarState.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSidebarState.md new file mode 100644 index 0000000000..18bbec27e1 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSidebarState.md @@ -0,0 +1,133 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useSidebarState/useSidebarState.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useSidebarState + +Controls the sidebar (left navigation panel) expansion, pinning, hover, and mobile menu state. This composable exposes a unified API for reading and toggling all sidebar states from any component within the VcApp tree. The sidebar has three independent dimensions: **pinned** (user explicitly locked it open, persisted to localStorage), **hover-expanded** (mouse is hovering over the collapsed sidebar on desktop), and **mobile menu** (overlay drawer on small screens). The derived `isExpanded` computed combines pinned and hover states for convenience. + +Internally, it delegates to `useMenuExpanded()` to share reactive state with other components like `UserDropdownButton` that also need to know the sidebar state. + +## When to Use + +- Toggle or read sidebar expanded/collapsed state from any component inside VcApp +- Control the mobile menu overlay programmatically (e.g., close it after a navigation action) +- Conditionally render content based on sidebar expansion (e.g., show labels only when expanded) +- When NOT to use: outside the VcApp component tree (will throw an error because the injection is missing) + +## Quick Start + +```vue +<script setup lang="ts"> +import { useSidebarState } from "@vc-shell/framework"; + +const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState(); +</script> + +<template> + <div class="tw-flex tw-items-center"> + <!-- Show full label when expanded, icon-only when collapsed --> + <VcIcon icon="fas fa-box" /> + <span + v-if="isExpanded" + class="tw-ml-2" + >Products</span + > + + <!-- Pin/unpin toggle button --> + <button + @click="togglePin" + class="tw-ml-auto" + > + <VcIcon :icon="isPinned ? 'fas fa-thumbtack' : 'fas fa-thumbtack tw-rotate-45'" /> + </button> + </div> +</template> +``` + +## API + +### Returns -- State + +| Property | Type | Description | +| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------ | --- | ------------------------------------------------------------------------------------ | +| `isPinned` | `Ref<boolean>` | Sidebar is pinned open by the user. Persisted to localStorage so it survives page reloads. | +| `isHoverExpanded` | `Ref<boolean>` | Sidebar is temporarily expanded because the mouse is hovering over it (desktop only). | +| `isMenuOpen` | `Ref<boolean>` | Mobile menu overlay is visible. | +| `isExpanded` | `ComputedRef<boolean>` | Derived: `isPinned | | isHoverExpanded`. Use this when you just need to know if sidebar content is visible. | + +### Returns -- Actions + +| Property | Type | Description | +| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `togglePin` | `() => void` | Toggle pinned state. Persists the new value to localStorage immediately. | +| `setHoverExpanded` | `(value: boolean) => void` | Set hover expansion. Opening has a 200ms delay to prevent flicker from brief mouse passes; closing is immediate. | +| `openMenu` | `() => void` | Show the mobile menu overlay. | +| `closeMenu` | `() => void` | Hide the mobile menu overlay. | + + + +## Recipe: Auto-Close Mobile Menu After Navigation + +```vue +<script setup lang="ts"> +import { useSidebarState } from "@vc-shell/framework"; +import { useBladeContext } from "@vc-shell/framework"; + +const { closeMenu, isMenuOpen } = useSidebarState(); +const { openBlade } = useBladeContext(); + +async function navigateToProducts() { + // Close the mobile menu first so it does not overlay the new blade + if (isMenuOpen.value) { + closeMenu(); + } + + await openBlade({ + component: ProductListBlade, + param: { catalogId: "default" }, + }); +} +</script> + +<template> + <button @click="navigateToProducts"> + <VcIcon icon="fas fa-box" /> + <span>Products</span> + </button> +</template> +``` + +## Recipe: Adjusting Content Width Based on Sidebar State + +```vue +<script setup lang="ts"> +import { useSidebarState } from "@vc-shell/framework"; +import { computed } from "vue"; + +const { isExpanded } = useSidebarState(); + +const contentClass = computed(() => (isExpanded.value ? "tw-ml-64" : "tw-ml-16")); +</script> + +<template> + <div + :class="contentClass" + class="tw-transition-all tw-duration-200" + > + <slot /> + </div> +</template> +``` + +## Tips + +- **Hover delay prevents flicker.** The 200ms delay on `setHoverExpanded(true)` means that quickly passing the mouse over the sidebar does not cause it to flash open. Closing is instant so the sidebar feels responsive. +- **`isPinned` is persisted to localStorage.** If a user pins the sidebar, it stays pinned across page reloads and browser sessions. The key is managed internally by `useMenuExpanded`. +- **Do not call outside VcApp.** If you call `useSidebarState()` in a component that is not a descendant of VcApp (e.g., in a standalone dialog or a separate Vue app instance), it will throw an error. + +## Related + +- `useMenuExpanded` -- lower-level composable that manages pinned/hover state and localStorage persistence +- `VcApp` -- the root component that calls `provideSidebarState()` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSlowNetworkDetection.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSlowNetworkDetection.md new file mode 100644 index 0000000000..cd7e884da4 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useSlowNetworkDetection.md @@ -0,0 +1,151 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useSlowNetworkDetection + +Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`. + +Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners. + +## When to Use + +- Reactively check `isSlowNetwork` to show skeleton loaders, disable auto-refresh, or display inline warnings +- The notification is automatic — no extra code needed beyond calling the composable once at app startup (already done in `framework/index.ts`) +- Use `trackRequest` / `untrackRequest` only if you have custom fetch logic outside the standard interceptor (the built-in fetch interceptor already tracks all `/api/*` requests) +- When NOT to use: for offline detection (use `useConnectionStatus` instead) or for measuring exact latency/bandwidth + +## Quick Start + +The composable is initialized automatically at app startup. To reactively read the slow-network state in a component: + +```vue +<script setup lang="ts"> +import { useSlowNetworkDetection } from "@vc-shell/framework"; + +const { isSlowNetwork } = useSlowNetworkDetection(); +</script> + +<template> + <VcBlade title="Products"> + <VcBanner + v-if="isSlowNetwork" + variant="warning" + icon="lucide-wifi" + > + <template #title>Slow connection</template> + Loading may take longer than usual. + </VcBanner> + + <!-- blade content --> + </VcBlade> +</template> +``` + +## API + +### Returns + +| Property | Type | Description | +| ---------------- | ------------------------ | ------------------------------------------------------------------------------- | +| `isSlowNetwork` | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only. | +| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 10 s, it counts as slow. | +| `untrackRequest` | `(id: string) => void` | Stop tracking a request. Cancels the timer or decrements the slow count. | + +### Constants + +| Name | Value | Purpose | +| --------------------------- | ------------------- | --------------------------------------------------- | +| `SLOW_REQUEST_THRESHOLD_MS` | `10000` | Time before a pending request is considered slow | +| `DISMISS_DELAY_MS` | `3000` | Delay before hiding the notification after recovery | +| `SLOW_EFFECTIVE_TYPES` | `["slow-2g", "2g"]` | Connection types flagged as slow | + + + +## Recipe: Custom Slow-Network Behavior in a Blade + +```vue +<script setup lang="ts"> +import { watch } from "vue"; +import { useSlowNetworkDetection } from "@vc-shell/framework"; + +const { isSlowNetwork } = useSlowNetworkDetection(); + +// Switch to a lightweight polling interval when the network is slow +const pollInterval = computed(() => (isSlowNetwork.value ? 30000 : 5000)); + +// Warn before navigating away during slow network + unsaved changes +watch(isSlowNetwork, (slow) => { + if (slow) { + console.info("Network is slow — consider disabling auto-refresh"); + } +}); +</script> +``` + +## Recipe: Tracking a Custom Request Outside the Interceptor + +If you bypass the standard fetch interceptor (e.g., direct `XMLHttpRequest` or third-party SDK), you can manually track the request: + +```ts +import { useSlowNetworkDetection } from "@vc-shell/framework"; + +const { trackRequest, untrackRequest } = useSlowNetworkDetection(); + +async function fetchFromExternalApi(url: string) { + const id = `custom-${Date.now()}`; + trackRequest(id); + try { + const response = await fetch(url); + return response.json(); + } finally { + untrackRequest(id); + } +} +``` + +## Tips + +- **Singleton by design.** Multiple calls to `useSlowNetworkDetection()` share the same state. No overhead from calling it in many components. +- **The notification cannot stack.** It uses a fixed `notificationId`, so even if multiple requests become slow simultaneously, only one notification is shown. +- **The 3-second dismiss delay prevents flicker.** Without it, a burst of requests completing one-by-one would cause the notification to flash on and off rapidly. +- **`navigator.connection` has limited support.** Only Chromium-based browsers support it. Firefox and Safari users will only get the request-timer channel, which is still effective. +- **The composable does not block requests.** Unlike the offline guard in the interceptor, slow-network detection is purely informational — it never prevents or delays a fetch. + +## Common Mistakes + +### Calling `trackRequest` without a matching `untrackRequest` + +```ts +// Wrong — if the request fails, untrackRequest never runs → permanent slow count +trackRequest(id); +const response = await fetch(url); +untrackRequest(id); + +// Correct — always untrack in finally +trackRequest(id); +try { + const response = await fetch(url); +} finally { + untrackRequest(id); +} +``` + +### Using the same ID for multiple requests + +```ts +// Wrong — second trackRequest overwrites the first timer +trackRequest("my-request"); +trackRequest("my-request"); + +// Correct — unique IDs +trackRequest("my-request-1"); +trackRequest("my-request-2"); +``` + +## Related + +- [`useConnectionStatus`](./useConnectionStatus.md) — offline detection (binary online/offline) +- [`registerInterceptors`](../../interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest` +- `notification` from `@shared/components/notifications` — the notification system used to display the warning diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useTheme.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useTheme.md new file mode 100644 index 0000000000..f72ad85aee --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/ui-state/useTheme.md @@ -0,0 +1,141 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useTheme/useTheme.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useTheme + +Manages color theme registration, switching, and persistence. Themes are applied via a `data-theme` attribute on `<html>`, and the active theme key is persisted to localStorage via `@vueuse/core`'s `useColorMode`. The composable maintains a global registry of theme definitions, supports runtime registration/unregistration from modules, and provides both explicit (`setTheme`) and sequential (`next`) theme switching. A default `"light"` theme is always registered out of the box. + +## When to Use + +- Switch between light/dark or custom themes at runtime +- Register module-specific themes dynamically (e.g., a "high-contrast" theme from an accessibility module) +- Build a theme picker UI with localized display names +- When NOT to use: for one-off color overrides (use CSS custom properties directly in your component styles) + +## Quick Start + +```vue +<script setup lang="ts"> +import { useTheme } from "@vc-shell/framework"; + +const { themes, currentThemeKey, currentLocalizedName, next, setTheme, register } = useTheme(); + +// Register a dark theme from your module +register({ key: "dark", localizationKey: "CORE.THEMES.DARK" }); + +// Switch to it explicitly +setTheme("dark"); + +// Or cycle through all registered themes (light -> dark -> light -> ...) +next(); +</script> + +<template> + <div> + <p>Current theme: {{ currentLocalizedName }} ({{ currentThemeKey }})</p> + <VcButton @click="next">Next Theme</VcButton> + </div> +</template> +``` + +## API + +### Returns + +| Property | Type | Description | +| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `themes` | `ComputedRef<DisplayTheme[]>` | All registered themes with their `key` and localized `name`. Reactive -- updates when themes are registered/unregistered. | +| `currentThemeKey` | `Ref<string>` | Active theme key (e.g., `"light"`, `"dark"`). Two-way reactive -- setting it switches the theme. | +| `currentLocalizedName` | `ComputedRef<string>` | Localized display name of the active theme (e.g., "Light", "Dark"). Falls back to capitalized key. | +| `next` | `() => void` | Cycle to the next registered theme in order. Wraps around at the end. | +| `setTheme` | `(themeKey: string) => void` | Switch to a specific registered theme. Logs a warning if the key is not registered. | +| `register` | `(themes: ThemeDefinition \| ThemeDefinition[]) => void` | Add one or more themes to the global registry. Duplicates (by key) are silently ignored. | +| `unregister` | `(keys: string \| string[]) => void` | Remove themes from the registry by key. | + +### ThemeDefinition + +| Field | Type | Required | Description | +| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| `key` | `string` | Yes | Unique theme identifier. Used as the `data-theme` attribute value on `<html>` and as the localStorage persistence key. | +| `localizationKey` | `string` | No | i18n key for the display name (e.g., `"CORE.THEMES.DARK"`). Falls back to the capitalized `key` (e.g., `"Dark"`). | + +### DisplayTheme + +| Field | Type | Description | +| ------ | -------- | ---------------------------------------------------------------------------- | +| `key` | `string` | Theme identifier | +| `name` | `string` | Localized display name, resolved from `localizationKey` or capitalized `key` | + + + +## Recipe: Module That Registers a Theme on Install + +```typescript +// my-module/index.ts +import type { App } from "vue"; +import { useTheme } from "@vc-shell/framework"; + +export default { + install(app: App) { + const { register } = useTheme(); + + register([ + { key: "ocean", localizationKey: "MY_MODULE.THEMES.OCEAN" }, + { key: "forest", localizationKey: "MY_MODULE.THEMES.FOREST" }, + ]); + }, +}; +``` + +Then define your theme's CSS variables scoped by the `data-theme` attribute: + +```scss +// my-module/styles/themes.scss +[data-theme="ocean"] { + --primary-500: #0077b6; + --primary-600: #005f8d; + --bg-surface: #e0f7fa; +} + +[data-theme="forest"] { + --primary-500: #2d6a4f; + --primary-600: #1b4332; + --bg-surface: #d8f3dc; +} +``` + +## Recipe: Theme Picker Dropdown + +```vue +<script setup lang="ts"> +import { useTheme } from "@vc-shell/framework"; + +const { themes, currentThemeKey, setTheme } = useTheme(); +</script> + +<template> + <VcSelect + :model-value="currentThemeKey" + :options="themes" + option-value="key" + option-label="name" + label="Theme" + @update:model-value="setTheme" + /> +</template> +``` + +## Tips + +- **The `"light"` theme is always registered.** You cannot unregister it without side effects. If you need to replace the default, register your custom theme and use `setTheme()` to switch away from light. +- **Theme persistence survives page reloads.** `useColorMode` writes to `localStorage` under the key `vueuse-color-scheme`. If a user selects "dark", it will be restored on the next visit. +- **Theme key becomes a CSS selector.** Since the key is set as `data-theme="yourKey"` on `<html>`, choose URL-safe, lowercase keys without spaces (e.g., `"high-contrast"`, not `"High Contrast"`). +- **`setTheme` with an unregistered key is a no-op.** It logs a warning but does not change the active theme. Always `register()` before calling `setTheme()`. + +## Related + +- `framework/assets/styles/theme/colors.scss` -- CSS custom property definitions for the default light theme +- `@vueuse/core` `useColorMode` -- underlying persistence and attribute management +- `@vueuse/core` `useCycleList` -- powers the `next()` cycling behavior diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/.pages new file mode 100644 index 0000000000..d1a5ed6ca3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/.pages @@ -0,0 +1,8 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: User +nav: + - useLanguages: useLanguages.md + - usePermissions: usePermissions.md + - usePlatformLocaleSync: usePlatformLocaleSync.md + - useUser: useUser.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useLanguages.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useLanguages.md new file mode 100644 index 0000000000..6af942deb3 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useLanguages.md @@ -0,0 +1,157 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useLanguages/useLanguages.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useLanguages + +Provides access to the language service for locale management: getting/setting the current locale, resolving locale tags, and fetching country flags. The service is created once via `provideLanguages()` at the framework level and shared through Vue's injection system. If called outside an injection context (e.g., during module initialization), a fallback singleton service is used so the composable never throws. + +Also exports `provideLanguages()` for framework-level initialization. + +## When to Use + +- To read or switch the current application locale programmatically +- To resolve locale tags (e.g., `en-US`) to display names or country codes for UI rendering +- To fetch flag images for language selector dropdowns +- When NOT to use: if you only need i18n translation strings, use Vue I18n's `useI18n()` directly -- it is lighter and does not require the language service + +## Quick Start + +```vue +<script setup lang="ts"> +import { useLanguages } from "@vc-shell/framework"; +import { ref, onMounted } from "vue"; + +const { currentLocale, setLocale, getFlag, getCountryCode } = useLanguages(); +const flagUrl = ref(""); + +onMounted(async () => { + flagUrl.value = await getFlag(currentLocale.value); +}); + +function switchToGerman() { + setLocale("de-DE"); +} +</script> + +<template> + <div class="tw-flex tw-items-center tw-gap-2"> + <img + v-if="flagUrl" + :src="flagUrl" + alt="flag" + class="tw-w-6 tw-h-4" + /> + <span>{{ currentLocale }}</span> + <VcButton + size="sm" + @click="switchToGerman" + >Deutsch</VcButton + > + </div> +</template> +``` + +## API + +### Parameters + +None. + +### Returns (`ILanguageService`) + +| Property / Method | Type | Description | +| ------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `currentLocale` | `ComputedRef<string>` | The currently active locale code (e.g., `"en-US"`, `"de-DE"`). | +| `setLocale` | `(locale: string) => void` | Switches the application locale. This updates `vue-i18n`'s locale and triggers re-rendering of all translated text. | +| `getLocaleByTag` | `(localeTag: string) => string \| undefined` | Resolves a locale tag to its display string (e.g., `"en-US"` to `"English (United States)"`). Returns `undefined` if the tag is not recognized. | +| `resolveCamelCaseLocale` | `(locale: string) => string` | Converts a locale code to camelCase format (e.g., `"en-US"` to `"enUs"`). Useful for dynamic property access on objects keyed by locale. | +| `getFlag` | `(language: string) => Promise<string>` | Fetches a flag image URL for the given language/locale. Returns a promise because flags may be loaded lazily. | +| `getCountryCode` | `(language: string) => string` | Extracts the country code from a language tag (e.g., `"en-US"` to `"US"`, `"de-DE"` to `"DE"`). | + +### Additional Exports + +| Export | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provideLanguages()` | Creates and provides the language service via Vue injection. Returns existing service if already provided in the current tree. Falls back to a module-level singleton if no injection context is available. | + +## How It Works + +The language service is a thin wrapper around Vue I18n's locale management with additional utilities for locale metadata. `provideLanguages()` creates the service and stores it via `provide()`. When `useLanguages()` is called: + +1. It checks for an injection context (`hasInjectionContext()`). +2. If inside a component, it `inject`s the service from the tree. +3. If no service is found, it throws an `InjectionError`. +4. If there is no injection context at all (called outside setup), it returns a fallback singleton service. + +The fallback behavior means `useLanguages()` is safe to call in module `install()` functions and other non-component contexts. + +## Recipe: Language Selector Dropdown + +```vue +<script setup lang="ts"> +import { useLanguages } from "@vc-shell/framework"; +import { ref, onMounted, watch } from "vue"; + +const { currentLocale, setLocale, getFlag } = useLanguages(); + +const availableLocales = ["en-US", "de-DE", "fr-FR", "es-ES"]; +const flags = ref<Record<string, string>>({}); + +onMounted(async () => { + // Pre-fetch all flags in parallel + const entries = await Promise.all(availableLocales.map(async (locale) => [locale, await getFlag(locale)] as const)); + flags.value = Object.fromEntries(entries); +}); + +function onLocaleChange(locale: string) { + setLocale(locale); +} +</script> + +<template> + <div class="language-picker"> + <div + v-for="locale in availableLocales" + :key="locale" + class="tw-flex tw-items-center tw-gap-2 tw-cursor-pointer tw-p-2" + :class="{ 'tw-bg-primary-50': locale === currentLocale }" + @click="onLocaleChange(locale)" + > + <img + v-if="flags[locale]" + :src="flags[locale]" + class="tw-w-6 tw-h-4" + /> + <span>{{ locale }}</span> + </div> + </div> +</template> +``` + +## Recipe: Locale-Aware Dynamic Property Display + +```typescript +import { useLanguages } from "@vc-shell/framework"; +import { useDynamicProperties } from "@vc-shell/framework"; + +const { currentLocale } = useLanguages(); +const { getPropertyValue } = useDynamicProperties(/* ... */); + +// Read a multilanguage property value for the current locale +const displayValue = computed(() => getPropertyValue(property.value, currentLocale.value)); +``` + +## Tips + +- **`setLocale` triggers a full re-render of translated text.** This is expected behavior from Vue I18n. If your app has many translated strings, the switch may cause a brief layout recalculation. There is no way to avoid this. +- **`getFlag` is async.** Flag images may be loaded from a CDN or bundled as lazy imports. Always await the result before using it in templates. +- **Fallback singleton is not reactive to injection changes.** If `provideLanguages()` is called after `useLanguages()` was already invoked outside an injection context, the fallback instance is not replaced. This is rarely an issue in practice since `provideLanguages()` runs before module installation. +- **`resolveCamelCaseLocale` is useful for object property access.** Platform API responses sometimes key multilanguage data by camelCase locale (e.g., `{ enUs: "Hello", deDe: "Hallo" }`). + +## Related + +- Vue I18n `useI18n()` -- for translation strings within components +- [useDynamicProperties](../forms/useDynamicProperties.md) -- uses locale for multilanguage property values +- `framework/core/services/language-service.ts` -- underlying service implementation diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePermissions.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePermissions.md new file mode 100644 index 0000000000..893a9c9137 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePermissions.md @@ -0,0 +1,288 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/usePermissions/usePermissions.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# usePermissions + +Checks whether the current user has specific platform permissions. This composable reads the authenticated user's permission list and provides a `hasAccess` function for conditional UI rendering and access control. It is client-side only -- it does not enforce server-side authorization. + +!!! warning "Client-side only" +`usePermissions` is a UI guard, not a security boundary. Always enforce authorization on the server side as well. + +## When to Use + +- Conditionally show or hide UI elements (buttons, toolbar items, sections) based on the current user's permissions +- Guard blade access or toolbar registration with client-side permission checks +- When NOT to use: as the sole authorization mechanism -- always pair with server-side enforcement; for checking authentication status -- use `useUser` instead + +## Quick Start + +```typescript +<script setup lang="ts"> +import { usePermissions } from "@vc-shell/framework"; + +const { hasAccess } = usePermissions(); + +if (hasAccess("order:update")) { + // user can edit orders +} +</script> +``` + +## How Permission Checking Works + +The `hasAccess` function evaluates permissions from the current user object (loaded via `useUserManagement`). The behavior depends on the input type and the user's role. + +| Input | Result | +| -------------------------------- | ------------------------------------------------------------------- | +| `undefined` | `true` -- no permission required, everyone has access | +| `"order:read"` | `true` if the user has this exact permission string | +| `["order:read", "order:update"]` | `true` if the user has **any** of the listed permissions (OR logic) | +| Any value, administrator user | Always `true` -- administrators bypass all checks | + +Permission strings follow the VirtoCommerce platform format: `"module:action"`. Common examples: + +| Permission | Meaning | +| ------------------- | ------------------------ | +| `"order:read"` | View orders | +| `"order:update"` | Edit orders | +| `"order:delete"` | Delete orders | +| `"catalog:create"` | Create catalog items | +| `"customer:manage"` | Full customer management | + +## Conditional Rendering in Templates + +Wrap permission checks in a `computed` to use them reactively in templates: + +```typescript +<script setup lang="ts"> +import { computed } from "vue"; +import { usePermissions } from "@vc-shell/framework"; + +const { hasAccess } = usePermissions(); + +const canEdit = computed(() => hasAccess("product:update")); +const canDelete = computed(() => hasAccess("product:delete")); +const canManage = computed(() => hasAccess(["product:update", "product:delete"])); +</script> + +<template> + <div class="tw-flex tw-gap-2"> + <VcButton v-if="canEdit" variant="primary" @click="onEdit"> + Edit Product + </VcButton> + <VcButton v-if="canDelete" variant="danger" @click="onDelete"> + Delete + </VcButton> + </div> +</template> +``` + +## Guarding Toolbar Actions + +A common pattern is to conditionally register toolbar buttons based on user permissions: + +```typescript +<script setup lang="ts"> +import { usePermissions, useToolbar } from "@vc-shell/framework"; + +const { hasAccess } = usePermissions(); +const { registerToolbarItem } = useToolbar(); + +// Always register view-only actions +registerToolbarItem({ + id: "refresh", + title: "Refresh", + icon: "fas fa-sync", + clickHandler: () => refresh(), + priority: 50, +}); + +// Only register edit actions if the user has permission +if (hasAccess("order:update")) { + registerToolbarItem({ + id: "save", + title: "Save", + icon: "fas fa-save", + clickHandler: () => save(), + priority: 100, + }); +} + +if (hasAccess("order:delete")) { + registerToolbarItem({ + id: "delete", + title: "Delete", + icon: "fas fa-trash", + clickHandler: () => confirmDelete(), + priority: 10, + }); +} +</script> +``` + +## Guarding Blade Access + +Use `hasAccess` in a blade component to redirect users who lack the required permissions: + +```typescript +<script setup lang="ts"> +import { usePermissions, useBladeContext } from "@vc-shell/framework"; + +const { hasAccess } = usePermissions(); +const { closeSelf } = useBladeContext(); + +if (!hasAccess("order:read")) { + closeSelf(); + return; +} +</script> +``` + +## Guarding Menu and Dashboard Registrations + +Both `addMenuItem` and `registerDashboardWidget` accept a `permissions` property. The menu service and dashboard service internally use the same permission-checking logic, so you often do not need to call `hasAccess` manually for these: + +```typescript +import { addMenuItem, registerDashboardWidget } from "@vc-shell/framework"; + +// Menu item only visible to users with order:read +addMenuItem({ + title: "Orders", + icon: "fas fa-shopping-cart", + routeId: "OrdersList", + priority: 10, + permissions: "order:read", +}); + +// Dashboard widget only visible to users with analytics:view +registerDashboardWidget({ + id: "sales-chart", + name: "Sales Chart", + component: SalesChartWidget, + size: { width: 2, height: 1 }, + permissions: ["analytics:view"], +}); +``` + +## Recipes + +### Multiple Permission Checks for Complex UI + +```typescript +<script setup lang="ts"> +import { computed } from "vue"; +import { usePermissions } from "@vc-shell/framework"; + +const { hasAccess } = usePermissions(); + +// Build a permission map for the template +const permissions = computed(() => ({ + canView: hasAccess("product:read"), + canEdit: hasAccess("product:update"), + canDelete: hasAccess("product:delete"), + canPublish: hasAccess("product:publish"), + canManageAny: hasAccess(["product:update", "product:delete", "product:publish"]), +})); +</script> + +<template> + <VcCard header="Product Actions"> + <div v-if="permissions.canManageAny" class="tw-flex tw-gap-2 tw-p-4"> + <VcButton v-if="permissions.canEdit" @click="edit">Edit</VcButton> + <VcButton v-if="permissions.canPublish" @click="publish">Publish</VcButton> + <VcButton v-if="permissions.canDelete" variant="danger" @click="remove">Delete</VcButton> + </div> + <p v-else class="tw-p-4 tw-text-gray-500">You do not have permission to manage this product.</p> + </VcCard> +</template> +``` + +### Reusable Permission Guard Composable + +```typescript +// composables/useOrderPermissions.ts +import { computed } from "vue"; +import { usePermissions } from "@vc-shell/framework"; + +export function useOrderPermissions() { + const { hasAccess } = usePermissions(); + + return { + canView: computed(() => hasAccess("order:read")), + canEdit: computed(() => hasAccess("order:update")), + canDelete: computed(() => hasAccess("order:delete")), + canRefund: computed(() => hasAccess("order:refund")), + }; +} +``` + +## Common Mistakes + +### Checking permissions without wrapping in computed + +```typescript +// Wrong -- evaluated once at setup, never updates if user changes +const canEdit = hasAccess("product:update"); + +// Correct -- reactive, re-evaluates when user data changes +const canEdit = computed(() => hasAccess("product:update")); +``` + +### Using AND logic instead of OR + +```typescript +// Wrong -- hasAccess with an array uses OR logic, not AND +// This returns true if the user has EITHER permission +const canFullyManage = hasAccess(["order:update", "order:delete"]); + +// Correct -- for AND logic, call hasAccess separately for each +const canFullyManage = hasAccess("order:update") && hasAccess("order:delete"); +``` + +### Assuming server-side enforcement + +```typescript +// Wrong -- relying only on client-side permission checks for security +if (hasAccess("order:delete")) { + await client.deleteOrder(orderId); // server must also verify! +} + +// Correct -- client-side check for UX, server enforces authorization +if (hasAccess("order:delete")) { + try { + await client.deleteOrder(orderId); + } catch (e) { + // Handle 403 Forbidden from server + } +} +``` + +## API Reference + +### Returns: `UsePermissionsReturn` + +| Property | Type | Description | +| ----------- | ----------------------------------------------------------- | -------------------------------------------------------- | +| `hasAccess` | `(permissions: string \| string[] \| undefined) => boolean` | Check if the current user has the required permission(s) | + +### hasAccess Parameters + +| Parameter | Type | Required | Description | +| ------------- | --------------------------------- | -------- | ---------------------------------------------------------------------------- | +| `permissions` | `string \| string[] \| undefined` | No | Permission string, array of strings (OR logic), or `undefined` (always true) | + +### Internal Behavior + +- Permissions are read from `useUserManagement().user.value.permissions` at composable initialization. +- If `user.value.isAdministrator` is `true`, `hasAccess` always returns `true` regardless of the input. +- An array input uses OR logic: the user needs at least one of the listed permissions. +- Passing `undefined` returns `true`, allowing unrestricted access by default. + +## Related + +- [useToolbar](../services/useToolbar.md) -- toolbar items can be conditionally registered based on permissions +- [useMenuService](../services/useMenuService.md) -- menu items accept a `permissions` property for visibility filtering +- [useDashboard](../services/useDashboard.md) -- dashboard widgets accept a `permissions` array for visibility filtering +- [useBlade](../blade-navigation/useBlade.md) -- blades can declare required permissions in their registration diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePlatformLocaleSync.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePlatformLocaleSync.md new file mode 100644 index 0000000000..7c8000fa1f --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/usePlatformLocaleSync.md @@ -0,0 +1,33 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# usePlatformLocaleSync + +One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service. + +Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used. + +## When to Use + +- Never call directly from feature code. This is a framework-internal sync primitive. +- It is invoked once per `VcApp` mount from `useShellBootstrap`. + +## Behaviour + +- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity. +- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`. +- On subsequent changes of the platform key, re-applies the value. +- Skips empty strings (platform clearing the key does not blank the shell locale). +- Skips values equal to `currentLocale` to avoid redundant re-configuration. + +## How It Works + +`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`. + +The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener. + +## Relationship to `VC_LANGUAGE_SETTINGS` + +The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useUser.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useUser.md new file mode 100644 index 0000000000..90fed2ccf1 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/user/useUser.md @@ -0,0 +1,177 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useUser/useUser.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useUser + +Shared composable providing read-only access to the current user's session state. Returns reactive user details, authentication status, and core session operations (load, sign out, get access token). This is the primary composable for user-related reads in regular blades and components. It deliberately exposes a narrow API surface -- no sign-in, password reset, or admin operations -- to encourage separation of concerns between user consumption and user management. + +Uses `createSharedComposable` from VueUse, so all callers across the entire application share the same state instance. This means calling `useUser()` in 20 different components does not create 20 separate API requests -- they all read from the same reactive refs. + +## When to Use + +- To read current user info (name, permissions, admin status) in any component +- To check authentication state for route guards or conditional rendering +- To sign out the current user +- To obtain an OAuth access token for manual API calls +- When NOT to use: for sign-in, password reset, token validation, or other management operations, use `useUserManagement()` instead + +## Quick Start + +```vue +<script setup lang="ts"> +import { useUser } from "@vc-shell/framework"; + +const { user, isAuthenticated, isAdministrator, loading } = useUser(); +</script> + +<template> + <div + v-if="loading" + class="tw-animate-pulse" + > + Loading user... + </div> + + <div v-else-if="isAuthenticated"> + <p>Welcome, {{ user?.userName }}</p> + <span + v-if="isAdministrator" + class="tw-badge tw-badge-primary" + >Admin</span + > + </div> + + <div v-else> + <p>Please sign in to continue.</p> + </div> +</template> +``` + +## API + +### Parameters + +None. + +### Returns + +| Property | Type | Description | +| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `user` | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, etc.), or `undefined` if not authenticated. | +| `loading` | `ComputedRef<boolean>` | Whether a user operation (loadUser, signOut) is in progress. | +| `isAuthenticated` | `ComputedRef<boolean>` | Whether a user session is active. Derived from `user.userName != null`. | +| `isAdministrator` | `ComputedRef<boolean \| undefined>` | Whether the current user has admin privileges. `undefined` if user is not loaded. | +| `loadUser` | `() => Promise<UserDetail>` | Loads/reloads user info from the server. Deduplicates concurrent calls -- if two components call `loadUser()` at the same time, only one API request is made. | +| `signOut` | `() => Promise<void>` | Signs out the current user, clears auth data from localStorage, and resets the user state. Handles both standard and external (SSO) sign-out flows. | +| `getAccessToken` | `() => Promise<string \| null>` | Returns the current OAuth access token. Automatically refreshes using the refresh token if the access token has expired or will expire within 60 seconds. Returns `null` if no auth data exists. | + +## How It Works + +The composable delegates to `_createInternalUserLogic()`, which manages: + +1. **Auth data persistence**: OAuth tokens (access token, refresh token, expiration) are stored in localStorage under `vc_auth_data`. On `loadUser()`, the stored auth data is read and the token is refreshed if needed. + +2. **Request deduplication**: `loadUser()` uses a shared promise (`loadUserPromise`). If called while a request is already in flight, it returns the existing promise rather than making a duplicate API call. + +3. **Token refresh**: `getAccessToken()` checks the expiration time with a 60-second buffer. If the token is expired or about to expire and a refresh token is available, it makes a `POST /connect/token` request with `grant_type: refresh_token`. + +4. **Shared state**: `createSharedComposable` from VueUse wraps `_createInternalUserLogic` so every call to `useUser()` or `useUserManagement()` reads from the same singleton internal logic. The `user` ref lives inside that singleton. App bootstrap registers `useUserManagement()` outside any component scope, which pins the singleton for the app lifetime — transient component mount/unmount cycles don't discard it. + +## Recipe: Route Guard Based on Authentication + +```typescript +import { useUser } from "@vc-shell/framework"; + +const router = createRouter({ + /* ... */ +}); + +router.beforeEach(async (to) => { + const { isAuthenticated, loadUser } = useUser(); + + // Ensure user is loaded before checking auth + if (!isAuthenticated.value) { + try { + await loadUser(); + } catch { + // loadUser failed -- user is not authenticated + } + } + + if (to.meta.requiresAuth && !isAuthenticated.value) { + return { name: "SignIn" }; + } +}); +``` + +## Recipe: Displaying User Info in a Header + +```vue +<template> + <div class="tw-flex tw-items-center tw-gap-2"> + <VcAvatar + :name="user?.userName" + size="sm" + /> + <div> + <p class="tw-text-sm tw-font-medium">{{ user?.userName }}</p> + <p class="tw-text-xs tw-text-gray-500">{{ user?.email }}</p> + </div> + <VcButton + size="sm" + variant="ghost" + @click="handleSignOut" + >Sign Out</VcButton + > + </div> +</template> + +<script setup lang="ts"> +import { useUser } from "@vc-shell/framework"; +import { useRouter } from "vue-router"; + +const { user, signOut } = useUser(); +const router = useRouter(); + +async function handleSignOut() { + await signOut(); + router.push({ name: "SignIn" }); +} +</script> +``` + +## Recipe: Adding Access Token to Custom API Calls + +```typescript +import { useUser } from "@vc-shell/framework"; + +const { getAccessToken } = useUser(); + +async function fetchCustomEndpoint(url: string) { + const token = await getAccessToken(); + + const response = await fetch(url, { + headers: { + Authorization: token ? `Bearer ${token}` : "", + }, + }); + + return response.json(); +} +``` + +## Tips + +- **`loadUser` deduplicates concurrent calls across composables.** If multiple blades call `loadUser()` simultaneously — or if `useUser()` and `useUserManagement()` are both used in the same flow — only one API request is made. `useUser` and `useUserManagement` share the singleton internal logic, so request deduplication works across both. +- **Token refresh is transparent.** `getAccessToken()` handles expiration checking and refresh internally. You never need to manually check token expiration or call a refresh endpoint. +- **`isAuthenticated` checks `userName`, not the token.** A user is considered authenticated if `user.value?.userName` is not null. This means the user could have an expired token but still appear "authenticated" until the next API call fails. +- **`signOut` clears localStorage.** After sign-out, the `vc_auth_data` key is removed from localStorage. Any cached tokens are gone permanently. +- **Shared state means shared loading.** If one component triggers `loadUser()`, `loading.value` becomes `true` in all components that use `useUser()`. Design your UI to handle this. + +## Related + +- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- extended API with sign-in, password reset, token validation (for auth pages) +- [usePermissions](./usePermissions.md) -- permission checks based on user roles +- `UserDetail` from `@core/api/platform` -- the user detail type returned by the API diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/.pages new file mode 100644 index 0000000000..75abc87276 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/.pages @@ -0,0 +1,10 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Utilities +nav: + - useAppInsights: useAppInsights.md + - useAsync: useAsync.md + - useBeforeUnload: useBeforeUnload.md + - useErrorHandler: useErrorHandler.md + - useFunctions: useFunctions.md + - useWebVitals: useWebVitals.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAppInsights.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAppInsights.md new file mode 100644 index 0000000000..823a059d62 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAppInsights.md @@ -0,0 +1,119 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAppInsights/useAppInsights.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useAppInsights + +Integrates Azure Application Insights page-view tracking with Vue Router and the current user context. This composable bridges the `vue3-application-insights` plugin with the vc-shell framework by automatically enriching every page-view event with the authenticated user's ID and name, generating fresh W3C trace IDs per navigation for distributed tracing, and optionally prefixing page names with the application name (e.g., `[Vendor Portal] Dashboard`). + +## When to Use + +- Track page views and navigation timing in production with Application Insights +- Send custom telemetry events via the raw `appInsights` instance +- When NOT to use: if your app does not use Azure Application Insights, or if you only need client-side analytics (consider a lighter solution) + +## Quick Start + +The typical setup happens once in your app's router configuration: + +```typescript +import { useAppInsights } from "@vc-shell/framework"; +import { createRouter, createWebHistory } from "vue-router"; + +const router = createRouter({ history: createWebHistory(), routes }); + +// Set up page-view tracking +const { setupPageTracking } = useAppInsights(); + +router.beforeEach((to) => { + setupPageTracking.beforeEach({ name: to.name as string }); +}); + +router.afterEach((to) => { + setupPageTracking.afterEach({ name: to.name as string, fullPath: to.fullPath }); +}); + +export default router; +``` + +## API + +### Returns + +| Property | Type | Description | +| ------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `setupPageTracking.beforeEach` | `(route: { name: string }) => void` | Call in router `beforeEach` to start page-view timing and generate a new trace ID | +| `setupPageTracking.afterEach` | `(route: { name: string; fullPath: string }) => void` | Call in router `afterEach` to stop page-view timing and flush the telemetry event | +| `appInsights` | `ApplicationInsights` | Raw Application Insights instance for custom telemetry (trackEvent, trackException, trackMetric, etc.) | + +### Injection Key + +| Key | Type | Description | +| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `AppInsightsOptionsKey` | `InjectionKey<AppInsightsPluginOptions>` | Optional. Provide this at app level with `{ appName: 'Vendor Portal' }` to prefix all page names. | + +## How It Works + +Each navigation goes through two phases: + +1. **beforeEach**: A new W3C trace ID is generated and set on `appInsights.context.telemetryTrace`. Then `startTrackPage(name)` begins a timer for the page view. The trace ID links this page view to any API calls made during the navigation, enabling end-to-end distributed tracing in Application Insights. + +2. **afterEach**: `stopTrackPage(name, url, properties)` finalizes the page-view event. The URL is reconstructed from `location.protocol + location.host + route.fullPath`. Custom properties include the current user's `id` and `userName` from `useUserManagement()`. + +If `AppInsightsOptionsKey` is provided with an `appName`, page names are formatted as `[AppName] RouteName` to distinguish multiple apps reporting to the same Application Insights resource. + +## Recipe: Tracking Custom Events Alongside Page Views + +```typescript +import { useAppInsights } from "@vc-shell/framework"; + +const { appInsights } = useAppInsights(); + +function trackOrderPlaced(orderId: string, total: number) { + appInsights.trackEvent({ + name: "OrderPlaced", + properties: { orderId }, + measurements: { orderTotal: total }, + }); +} + +function trackSearchPerformed(query: string, resultCount: number) { + appInsights.trackEvent({ + name: "SearchPerformed", + properties: { query }, + measurements: { resultCount }, + }); +} +``` + +## Recipe: Providing the App Name + +In your app's entry point, provide the options so page names are prefixed: + +```typescript +import { createApp, provide } from "vue"; +import { AppInsightsOptionsKey } from "@vc-shell/framework"; + +const app = createApp(App); + +app.provide(AppInsightsOptionsKey, { + appName: "Vendor Portal", + // ... other AppInsightsPluginOptions +}); +``` + +This results in page names like `[Vendor Portal] Dashboard` instead of just `Dashboard`. + +## Tips + +- **Call once per router.** The `setupPageTracking` methods are designed to be registered as router guards exactly once. Calling `useAppInsights()` multiple times is safe (it returns the same underlying instance), but do not register the guards twice. +- **User context may be undefined on first navigation.** If the user has not loaded yet (e.g., during the initial sign-in redirect), the `userId` and `userName` properties will be empty strings. This is expected and does not break tracking. +- **Use `appInsights.trackException` for error tracking.** The `useErrorHandler` composable already does this automatically, but you can also call it manually for errors caught in try/catch blocks. + +## Related + +- `vue3-application-insights` -- underlying plugin that initializes the Application Insights SDK +- [useUserManagement](../useUserManagement/useUserManagement.docs.md) -- provides current user context for telemetry enrichment +- [useErrorHandler](./useErrorHandler.md) -- automatically tracks exceptions to Application Insights +- [useWebVitals](./useWebVitals.md) -- Core Web Vitals can be piped to Application Insights via a custom callback diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAsync.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAsync.md new file mode 100644 index 0000000000..eedf094d04 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useAsync.md @@ -0,0 +1,422 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useAsync/useAsync.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +!!! note "Large reference" +This page is long. Use the section headings to navigate: [Quick Start](#quick-start), [API Reference](#api-reference), [Features](#features), [Recipes](#recipes), [Common Mistakes](#common-mistakes). + +# useAsync + +Wraps an asynchronous function with reactive `loading` state, reactive `error` state, and automatic error notifications. This is the standard way to handle API calls, saves, deletes, and other async operations throughout VC-Shell applications. + +When the returned `action` is called, `useAsync` automatically: + +1. Sets `loading` to `true` and clears any previous `error` +2. Executes your async function +3. On failure: parses the error into a `DisplayableError`, stores it in `error`, logs it, optionally shows a toast notification, and re-throws +4. Sets `loading` to `false` (success or failure) + +## When to Use + +- Wrap any async operation (API calls, saves, deletes) with reactive `loading` and `error` state +- Get automatic error parsing, toast notifications, and re-throw behavior for free +- Combine with `useLoading` when a blade has multiple independent async operations +- When NOT to use: for synchronous logic -- just use a regular function; for fire-and-forget operations where you do not need loading/error tracking + +## Quick Start + +```typescript +import { useAsync, useApiClient } from "@vc-shell/framework"; +import { OrderClient } from "@api/orders"; + +const { getApiClient } = useApiClient(OrderClient); + +const { + loading, + error, + action: loadOrder, +} = useAsync<string>(async (id) => { + const client = await getApiClient(); + return await client.getOrderById(id); +}); + +// In a blade's onMounted: +await loadOrder("order-123"); +// loading.value was true during the call, now false +// error.value is null on success, or a DisplayableError on failure +``` + +## API Reference + +### Import + +```typescript +import { useAsync } from "@vc-shell/framework"; +``` + +### Parameters + +| Parameter | Type | Required | Description | +| ------------- | ------------------------------ | -------- | ------------------------------- | +| `innerAction` | `AsyncAction<Payload, Result>` | Yes | The async function to wrap | +| `options` | `UseAsyncOptions` | No | Configuration for notifications | + +#### Type Aliases + +```typescript +type AsyncAction<Payload = void, Result = void> = (payload?: Payload, ...rest: any[]) => Promise<Result>; +``` + +#### UseAsyncOptions + +| Option | Type | Default | Description | +| --------------- | --------- | ------- | -------------------------------------------------------- | +| `notify` | `boolean` | `true` | Show an error toast notification on failure | +| `notifyTimeout` | `number` | `8000` | Duration in milliseconds before the toast auto-dismisses | + +### Returns: `UseAsyncReturn<Payload, Result>` + +| Property | Type | Description | +| --------- | --------------------------------------------- | -------------------------------------------------------------- | +| `loading` | `DeepReadonly<Ref<boolean>>` | Reactive loading state -- `true` while the action is executing | +| `error` | `DeepReadonly<Ref<DisplayableError \| null>>` | Reactive error -- set on failure, cleared on next invocation | +| `action` | `AsyncAction<Payload, Result>` | Wrapped function with the same signature as `innerAction` | + +### Type Parameters + +| Name | Default | Description | +| --------- | ------- | --------------------------------------------- | +| `Payload` | `void` | Type of the first argument passed to `action` | +| `Result` | `void` | Return type of the async operation | + +--- + +## Features + +### Basic Async Operation + +```typescript +const { loading, action: fetchItems } = useAsync(async () => { + const client = await getApiClient(); + items.value = await client.searchItems(query.value); +}); + +// Use in template: +// <VcDataTable :loading="loading" :items="items" /> +``` + +### With Typed Payload + +Pass a payload type to strongly type the first argument: + +```typescript +const { action: loadProduct } = useAsync<string>(async (id) => { + // id is typed as string | undefined + const client = await getApiClient(); + if (id) { + product.value = await client.getProductById(id); + } +}); + +await loadProduct("prod-42"); +``` + +### With Typed Payload and Result + +When the inner function returns a value, it becomes the resolved value of `action`: + +```typescript +const { action: validateSeller } = useAsync<Seller, ValidationFailure[]>(async (seller) => { + const client = await getApiClient(); + return await client.validateSeller(seller); +}); + +const failures = await validateSeller(sellerData); +// failures is typed as ValidationFailure[] +``` + +### Reactive Error State + +The `error` ref contains a parsed `DisplayableError` after a failure. It is automatically cleared on the next invocation. + +```vue +<template> + <VcAlert + v-if="error" + variant="error" + > + {{ error.message }} + </VcAlert> + <VcButton + :loading="loading" + @click="save" + >Save</VcButton + > +</template> + +<script setup lang="ts"> +const { + loading, + error, + action: save, +} = useAsync(async () => { + await saveOrder(order.value); +}); +</script> +``` + +### Error Notifications + +By default, `useAsync` shows a toast notification on failure. The notification is **deferred** via `setTimeout(0)` so that the `ErrorInterceptor` can cancel it when a blade error banner is already displayed -- this prevents duplicate toast + banner for the same error. + +```typescript +// Default: shows toast on error +const { action: save } = useAsync(async () => { + /* ... */ +}); + +// Explicit: custom timeout +const { action: save } = useAsync( + async () => { + /* ... */ + }, + { + notify: true, + notifyTimeout: 5000, + }, +); + +// Silent: no toast notification +const { action: silentRefresh } = useAsync( + async () => { + /* ... */ + }, + { + notify: false, + }, +); +``` + +### Combining with useApiClient + +The standard pattern for API operations in VC-Shell: + +```typescript +import { useAsync, useApiClient } from "@vc-shell/framework"; +import { VcmpSellerCatalogClient } from "@api/client"; + +const { getApiClient } = useApiClient(VcmpSellerCatalogClient); + +const { action: search, loading } = useAsync<SearchQuery>(async (query) => { + const client = await getApiClient(); + const result = await client.searchProducts(query); + items.value = result.results ?? []; + totalCount.value = result.totalCount ?? 0; +}); +``` + +### Combining with useLoading + +When a blade has multiple async operations, combine their loading states into one: + +```typescript +const { action: load, loading: loadLoading } = useAsync<string>(async (id) => { + /* ... */ +}); +const { action: save, loading: saveLoading } = useAsync<Product>(async (p) => { + /* ... */ +}); +const { action: remove, loading: deleteLoading } = useAsync<string>(async (id) => { + /* ... */ +}); + +// Single reactive boolean: true if ANY operation is running +const loading = useLoading(loadLoading, saveLoading, deleteLoading); +``` + +--- + +## Recipes + +### Recipe 1: CRUD Operations in a Composable + +The standard VC-Shell pattern: encapsulate all CRUD operations for an entity in a composable, using `useAsync` for each operation and `useLoading` for the combined state. + +```typescript +// composables/useFulfillmentCenter/index.ts +import { useApiClient, useAsync, useLoading } from "@vc-shell/framework"; +import { VcmpSellerCatalogClient, type FulfillmentCenter } from "@api/client"; + +export function useFulfillmentCenter() { + const { getApiClient } = useApiClient(VcmpSellerCatalogClient); + const details = ref<FulfillmentCenter>(); + + const { action: load, loading: loadLoading } = useAsync<string>(async (id) => { + const client = await getApiClient(); + details.value = await client.getFulfillmentCenterById(id!); + }); + + const { action: save, loading: saveLoading } = useAsync<FulfillmentCenter>(async (data) => { + const client = await getApiClient(); + await client.updateFulfillmentCenter({ fulfillmentCenter: data }); + }); + + const { action: remove, loading: deleteLoading } = useAsync<string>(async (id) => { + const client = await getApiClient(); + await client.deleteFulfillmentCenter([id!]); + }); + + return { + details, + load, + save, + remove, + loading: useLoading(loadLoading, saveLoading, deleteLoading), + }; +} +``` + +Usage in a blade: + +```vue +<script setup lang="ts"> +const { details, load, save, remove, loading } = useFulfillmentCenter(); + +onMounted(() => { + if (props.param) { + load(props.param); + } +}); +</script> +``` + +### Recipe 2: Separate Loading States for Parallel Operations + +```typescript +const { action: loadOrder, loading: mainLoading } = useAsync<string>(async (id) => { + order.value = await orderClient.getById(id!); +}); + +const { action: loadShipments, loading: shipmentsLoading } = useAsync<string>(async (orderId) => { + shipments.value = await shipmentClient.getByOrderId(orderId!); +}); + +// In template: <VcBlade :loading="mainLoading">, <VcDataTable :loading="shipmentsLoading"> +onMounted(() => Promise.all([loadOrder(props.param!), loadShipments(props.param!)])); +``` + +### Recipe 3: Error Handling with Try/Catch + +Since `useAsync` re-throws, you can catch for flow control while getting reactive `error` and toasts for free: + +```typescript +const { action: save, error } = useAsync<Order>(async (order) => { + const client = await getApiClient(); + return await client.updateOrder(order); +}); + +async function onSaveClick() { + try { + await save(order.value); + await callParent("reload"); + await closeSelf(); + } catch { + // error.value is set, toast shown -- just stay on blade for retry + } +} +``` + +--- + +## Common Mistakes + +### Wrapping synchronous code in useAsync + +```typescript +// BAD -- useAsync is for async operations, not sync +const { action } = useAsync(async () => { + items.value = items.value.filter((x) => x.active); +}); +``` + +```typescript +// GOOD -- just use a regular function +function filterActive() { + items.value = items.value.filter((x) => x.active); +} +``` + +### Forgetting that action re-throws + +```typescript +// BAD -- unhandled promise rejection +async function onSave() { + await save(data.value); + await closeSelf(); // never reached if save throws +} +``` + +```typescript +// GOOD -- wrap in try/catch when you have follow-up logic +async function onSave() { + try { + await save(data.value); + await closeSelf(); + } catch { + // error.value is already set, toast shown -- just stay on blade + } +} +``` + +### Creating useAsync inside a function instead of at setup time + +```typescript +// BAD -- creates a new loading ref each call, template never sees it +async function loadData() { + const { action, loading } = useAsync(async () => { + /* ... */ + }); + await action(); +} +``` + +```typescript +// GOOD -- create at setup time, call the action later +const { action: loadData, loading } = useAsync(async () => { + /* ... */ +}); + +onMounted(() => loadData()); +``` + +### Using the same useAsync instance for unrelated operations + +```typescript +// BAD -- loading/error state is shared, second call clears first error +const { action: doStuff, loading } = useAsync(async (type: string) => { + if (type === "load") await loadData(); + if (type === "save") await saveData(); +}); +``` + +```typescript +// GOOD -- separate instances for separate operations +const { action: load, loading: loadLoading } = useAsync(async () => loadData()); +const { action: save, loading: saveLoading } = useAsync(async () => saveData()); +``` + +--- + + + +--- + +## Related + +| Resource | Description | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| [`useApiClient`](../data/useApiClient.md) | Provides typed API client instances to pass into `useAsync` | +| [`useLoading`](../ui-state/useLoading.md) | Combines multiple `loading` refs into a single boolean | +| [`useModificationTracker`](../forms/useModificationTracker.md) | Tracks dirty state for forms -- often used alongside `useAsync` for save operations | +| [`notification`](../../../shared/components/notifications/) | The toast notification system used by `useAsync` for error display | diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useBeforeUnload.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useBeforeUnload.md new file mode 100644 index 0000000000..e2d3ebc48b --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useBeforeUnload.md @@ -0,0 +1,112 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useBeforeUnload/useBeforeUnload.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useBeforeUnload + +Prevents the browser tab from closing when unsaved changes exist by hooking into the native `beforeunload` event. This composable is the last line of defense against accidental data loss -- it triggers the browser's built-in "Leave site?" confirmation dialog whenever the user tries to close or refresh the tab while the `modified` flag is `true`. It complements in-app guards (like blade `onBeforeClose`) by covering the case where the user bypasses the application entirely via the browser chrome. + +## When to Use + +- Protect forms or blades with unsaved edits from accidental tab/window close or page refresh +- Pair with `useModificationTracker` to get a reactive `modified` flag automatically +- When NOT to use: for in-app navigation guards (use Vue Router `beforeRouteLeave` or blade `onBeforeClose` instead). This composable only handles the browser-level close/refresh event, not SPA route changes. + +## Quick Start + +```vue +<script setup lang="ts"> +import { useBeforeUnload } from "@vc-shell/framework"; +import { ref, computed } from "vue"; + +// Suppose your blade has a form with a "dirty" flag +const originalName = ref("Widget A"); +const currentName = ref("Widget A"); + +const isModified = computed(() => originalName.value !== currentName.value); + +// That is all you need -- the browser will now prompt on tab close when modified +useBeforeUnload(isModified); +</script> + +<template> + <VcBlade title="Edit Widget"> + <VcInput + v-model="currentName" + label="Name" + /> + <VcButton @click="save">Save</VcButton> + </VcBlade> +</template> +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| ---------- | ---------------------- | -------- | ---------------------------------------------------------------------------------- | +| `modified` | `ComputedRef<boolean>` | Yes | When `true`, the browser shows a leave-confirmation dialog on tab close or refresh | + +### Returns + +| Property | Type | Description | +| ---------- | ---------------------- | ----------------------------------------------------------------------- | +| `modified` | `ComputedRef<boolean>` | Pass-through of the input ref, useful for chaining or template bindings | + +## How It Works + +Internally, the composable registers a `beforeunload` event listener during `onBeforeMount` and removes it during `onBeforeUnmount`. Inside the listener, it calls `event.preventDefault()` only when `modified` is `true`. Modern browsers intercept `preventDefault()` on the `beforeunload` event to show their native confirmation dialog. The dialog text is always controlled by the browser and cannot be customized -- this is a deliberate security restriction to prevent phishing. + +Because the listener is added in `onBeforeMount` (not `setup`), it avoids attaching to the window during SSR or before the component is actually rendered. + +## Recipe: Combining with useModificationTracker in a Detail Blade + +```vue +<script setup lang="ts"> +import { useBeforeUnload } from "@vc-shell/framework"; +import { ref, computed, watch } from "vue"; + +const props = defineProps<{ productId: string }>(); + +const product = ref({ name: "", price: 0 }); +const snapshot = ref({ name: "", price: 0 }); + +// Load data and take a snapshot of the original state +async function load() { + const data = await api.getProduct(props.productId); + product.value = { ...data }; + snapshot.value = { ...data }; +} + +// Deep-compare current vs. snapshot +const isModified = computed(() => JSON.stringify(product.value) !== JSON.stringify(snapshot.value)); + +// Guard the browser tab +useBeforeUnload(isModified); + +// Also guard blade navigation (separate concern) +defineExpose({ + onBeforeClose: () => { + if (isModified.value) { + return confirm("You have unsaved changes. Discard?"); + } + return true; + }, +}); +</script> +``` + +This pattern separates two concerns: `useBeforeUnload` handles the browser tab close, while `onBeforeClose` handles in-app blade navigation. Together, they cover all data-loss scenarios. + +## Tips + +- **Always use a computed ref, not a plain ref.** Passing a plain `Ref<boolean>` works at runtime, but the TypeScript signature requires `ComputedRef<boolean>` to encourage derived state rather than manual toggling. +- **Reset your modified flag after saving.** If you forget to reset the source data that drives `isModified`, the dialog will keep appearing even after a successful save. +- **Do not rely on this for critical workflows.** Some browsers (especially mobile) do not reliably fire `beforeunload`. Treat it as a best-effort safety net, not a guarantee. + +## Related + +- `useModificationTracker` -- tracks whether a value has been modified (produces a `ComputedRef<boolean>` you can pass directly) +- Blade `onBeforeClose` -- in-app navigation guard for blade stack transitions diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useErrorHandler.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useErrorHandler.md new file mode 100644 index 0000000000..d9e7133b66 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useErrorHandler.md @@ -0,0 +1,168 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useErrorHandler/useErrorHandler.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useErrorHandler + +Captures and normalizes errors within a component's subtree using Vue's `onErrorCaptured` hook. This composable acts as an error boundary: it catches errors thrown by any child component, normalizes them into a `DisplayableError` with a user-friendly `message` and technical `details`, automatically reports them to Application Insights with user context, and emits events so parent components can react. It also includes re-entrancy protection to prevent infinite error loops when the error display itself triggers an error. + +## When to Use + +- In blade or container components to catch and display errors from child components without crashing the entire app +- When you want automatic Application Insights tracking of errors with user ID and name +- To create error boundary components that show a fallback UI when children fail +- When NOT to use: for manual try/catch error handling in composables or async functions -- use standard try/catch there and handle errors explicitly + +## Quick Start + +```vue +<script setup lang="ts"> +import { useErrorHandler } from "@vc-shell/framework"; + +// capture: true prevents the error from propagating further up the tree +const { error, reset } = useErrorHandler(true); +</script> + +<template> + <div + v-if="error" + class="tw-p-4 tw-bg-red-50 tw-border tw-border-red-200 tw-rounded" + > + <p class="tw-text-red-700 tw-font-semibold">{{ error.message }}</p> + <p class="tw-text-red-500 tw-text-sm tw-mt-1">{{ error.details }}</p> + <VcButton + class="tw-mt-2" + @click="reset" + >Dismiss</VcButton + > + </div> + <slot v-else /> +</template> +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| --------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `capture` | `boolean` | No | If `true`, prevents the error from propagating further up the component tree (the error is "swallowed" at this level). If `false` or `undefined`, the error continues propagating to parent error handlers. | + +### Returns + +| Property | Type | Description | +| -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `error` | `Ref<DisplayableError \| null>` | The most recently captured error, or `null` if no error has occurred or it has been reset. | +| `reset` | `() => void` | Clears the error state (sets `error` to `null`) and emits a `reset` event on the component instance. | + +### DisplayableError + +| Property | Type | Description | +| --------------- | --------- | ------------------------------------------------------------------- | +| `message` | `string` | Short, user-facing error message suitable for display in the UI. | +| `details` | `string` | Detailed technical description (stack trace, API error body, etc.). | +| `originalError` | `unknown` | The original thrown value, preserved for programmatic inspection. | + +### Emitted Events + +The composable emits events on the current component instance (accessible via `@error` and `@reset` in the parent template): + +- `error` -- emitted with the `DisplayableError` when an error is captured +- `reset` -- emitted when `reset()` is called + +## How It Works + +1. **Capture**: Vue's `onErrorCaptured` hook fires whenever a descendant component throws. The composable normalizes the thrown value via `parseError()` into a `DisplayableError`. + +2. **Re-entrancy guard**: An `isProcessing` ref prevents recursive error handling. If the error display template itself throws (e.g., a rendering bug), the inner error is not re-processed. The guard resets on `nextTick`. + +3. **Telemetry**: If Application Insights is available, the error is tracked via `appInsights.trackException()` with the current user's `id` and `userName` as custom properties. + +4. **Propagation**: The return value of `onErrorCaptured` controls propagation. When `capture` is `true`, the hook returns `false` (stop propagation). Otherwise, it returns `true` (continue propagation). + +## Recipe: Error Boundary Wrapper Component + +Create a reusable error boundary that wraps any blade content: + +```vue +<!-- ErrorBoundary.vue --> +<script setup lang="ts"> +import { useErrorHandler } from "@vc-shell/framework"; + +const props = defineProps<{ + fallbackMessage?: string; +}>(); + +const { error, reset } = useErrorHandler(true); +</script> + +<template> + <div + v-if="error" + class="tw-flex tw-flex-col tw-items-center tw-justify-center tw-p-8" + > + <VcIcon + icon="fas fa-exclamation-triangle" + class="tw-text-4xl tw-text-warning-500 tw-mb-4" + /> + <h3 class="tw-text-lg tw-font-semibold"> + {{ fallbackMessage ?? "Something went wrong" }} + </h3> + <p class="tw-text-sm tw-text-gray-500 tw-mt-2">{{ error.message }}</p> + <VcButton + class="tw-mt-4" + @click="reset" + >Try Again</VcButton + > + </div> + <slot v-else /> +</template> +``` + +Usage in a blade: + +```vue +<template> + <VcBlade title="Product Details"> + <ErrorBoundary fallback-message="Failed to load product"> + <ProductForm :product-id="productId" /> + </ErrorBoundary> + </VcBlade> +</template> +``` + +## Recipe: Listening to Error Events from a Parent + +```vue +<template> + <ChildBlade + @error="onChildError" + @reset="onChildReset" + /> +</template> + +<script setup lang="ts"> +function onChildError(error: DisplayableError) { + console.error("Child blade error:", error.message); + // Optionally show a notification or log to external service +} + +function onChildReset() { + console.log("Child blade error was dismissed"); +} +</script> +``` + +## Tips + +- **Use `capture: true` for top-level error boundaries.** Without it, the error propagates to Vue's global error handler and may be logged as an unhandled error in the console. +- **`reset()` does not retry the failed operation.** It only clears the error state. If you want retry behavior, combine `reset()` with re-fetching data or re-rendering the child component (e.g., via a `:key` change). +- **The re-entrancy guard resets on `nextTick`.** This means two errors thrown in the same synchronous microtask will only capture the first one. Errors in subsequent ticks are handled normally. +- **Application Insights must be configured.** If the `vue3-application-insights` plugin is not installed, `appInsights` will be `undefined` and telemetry is silently skipped. The composable still works for local error display. + +## Related + +- `DisplayableError` -- error class from `@core/utilities/error` +- [useAppInsights](./useAppInsights.md) -- Application Insights telemetry integration +- Vue `onErrorCaptured` -- the underlying Vue lifecycle hook diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useFunctions.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useFunctions.md new file mode 100644 index 0000000000..39a5846794 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useFunctions.md @@ -0,0 +1,119 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useFunctions/useFunctions.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useFunctions + +Provides lightweight utility functions for timing control: debounce, throttle, delay, and once. These are thin, dependency-free implementations that cover the most common use cases without pulling in lodash or other large utility libraries. The composable returns plain functions, not reactive wrappers, making them suitable for event handlers, API calls, and other imperative code paths where you do not need VueUse's reactive cancellation features. + +## When to Use + +- Need a simple debounce/throttle for search inputs, resize handlers, or scroll listeners +- Want a one-shot initializer that guarantees a function runs exactly once +- Need a quick fire-and-forget delayed execution +- When NOT to use: prefer `@vueuse/core` equivalents (`useDebounceFn`, `useThrottleFn`) when you need reactive integration, automatic cleanup on scope disposal, or cancellation support + +## Quick Start + +```typescript +import { useFunctions } from "@vc-shell/framework"; + +const { debounce, throttle, delay, once } = useFunctions(); + +// Debounce a search input handler +const debouncedSearch = debounce((query: string) => { + fetchResults(query); +}, 300); + +// Throttle a scroll handler to fire at most every 100ms +const throttledScroll = throttle(() => { + updateScrollPosition(); +}, 100); + +// Fire-and-forget delayed execution +delay(() => showTooltip(), 500); + +// Ensure a function runs only once (e.g., expensive initialization) +const initOnce = once(() => { + console.log("This runs exactly once"); + return expensiveSetup(); +}); +initOnce(); // runs and caches the result +initOnce(); // returns cached result immediately +initOnce(); // still returns cached result +``` + +## API + +### Returns + +| Property | Type | Description | +| ---------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | +| `debounce` | `(fn, delay: number) => (...args) => void` | Delays invocation until `delay` ms after the last call. Each new call resets the timer. | +| `throttle` | `(fn, delay: number) => (...args) => void` | Invokes at most once per `delay` ms on the leading edge. Subsequent calls within the window are ignored. | +| `delay` | `(fn, ms?: number) => void` | Runs `fn` after `ms` milliseconds (default 0, which defers to the next macrotask via `setTimeout`). | +| `once` | `(fn) => (...args) => unknown` | Ensures `fn` executes only once; subsequent calls return the cached result of the first invocation. | + +## How They Work + +- **debounce**: Uses `setTimeout` / `clearTimeout` internally. Each call clears the previous timeout and starts a new one. The function only fires when there is a pause of at least `delay` ms between calls. +- **throttle**: Uses a `Date.now()` timestamp check. The first call fires immediately and records the timestamp. Subsequent calls are silently dropped until enough time has passed. +- **delay**: A simple wrapper around `setTimeout`. Useful for readability when you want to express "do X after Y ms" without creating a raw timeout. +- **once**: Wraps the function with a boolean guard. After the first call, the result is cached and the original function reference is never called again. + +## Recipe: Debounced Search in a Blade Toolbar + +```vue +<script setup lang="ts"> +import { useFunctions } from "@vc-shell/framework"; +import { ref } from "vue"; + +const { debounce } = useFunctions(); +const searchQuery = ref(""); +const results = ref<Product[]>([]); + +const performSearch = debounce(async (query: string) => { + if (query.length < 2) { + results.value = []; + return; + } + results.value = await api.searchProducts({ keyword: query }); +}, 350); + +function onSearchInput(value: string) { + searchQuery.value = value; + performSearch(value); +} +</script> + +<template> + <VcBlade title="Products"> + <template #toolbar> + <VcInput + :model-value="searchQuery" + placeholder="Search products..." + @update:model-value="onSearchInput" + /> + </template> + <div + v-for="product in results" + :key="product.id" + > + {{ product.name }} + </div> + </VcBlade> +</template> +``` + +## Tips + +- **No cancellation API.** Unlike `@vueuse/core`'s `useDebounceFn`, the `debounce` here does not return a cancel method. If you need to cancel a pending debounce on component unmount, use VueUse instead or manually clear the timeout. +- **Throttle uses leading-edge firing.** The first call always executes immediately. If you need trailing-edge throttle (fire after the window closes), this implementation does not support it -- use lodash `throttle` with `{ trailing: true }` instead. +- **`once` caches even `undefined` results.** If the wrapped function returns `undefined`, subsequent calls still skip execution and return `undefined`. The guard is based on "has it been called", not "did it return a truthy value". +- **`delay(fn, 0)` is not the same as `nextTick`.** `delay` uses `setTimeout(fn, 0)`, which defers to the next macrotask. Vue's `nextTick` defers to the next microtask, which fires sooner. Use `nextTick` for DOM update timing. + +## Related + +- `@vueuse/core` `useDebounceFn`, `useThrottleFn` -- reactive alternatives with cancel support and automatic scope cleanup +- `lodash-es` `debounce`, `throttle` -- feature-rich alternatives with leading/trailing edge options diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useWebVitals.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useWebVitals.md new file mode 100644 index 0000000000..2a73ed3222 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/composables/utilities/useWebVitals.md @@ -0,0 +1,135 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/composables/useWebVitals/useWebVitals.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# useWebVitals + +Registers Core Web Vitals observers (FCP, LCP, CLS, INP, TTFB) and reports metrics via a callback. Core Web Vitals are Google's standardized set of real-user performance metrics that measure loading speed, interactivity, and visual stability. This composable wraps the `web-vitals` npm package and normalizes its output into a simple `{ name, value, rating }` shape. In development mode, metrics are logged to the console by default so you can catch performance regressions early without setting up external analytics. + +## When to Use + +- Monitor real-user performance metrics in production and send them to your analytics backend +- Pipe Web Vitals data to Application Insights, Google Analytics, or a custom endpoint +- Get quick performance feedback during development via console output +- When NOT to use: in unit tests or SSR environments (browser-only APIs), or when you need synthetic/lab metrics (use Lighthouse instead) + +## Quick Start + +```typescript +import { useWebVitals } from "@vc-shell/framework"; + +// Option 1: Default behavior -- logs to console.warn in dev mode, silent in production +useWebVitals(); + +// Option 2: Custom callback for production analytics +useWebVitals((metric) => { + analytics.track("web-vital", { + name: metric.name, // "FCP", "LCP", "CLS", "INP", or "TTFB" + value: metric.value, // milliseconds (or unitless for CLS) + rating: metric.rating, // "good", "needs-improvement", or "poor" + }); +}); +``` + +Call this once after `app.mount()` in your application entry point: + +```typescript +// main.ts +const app = createApp(App); +app.mount("#app"); + +// Register Web Vitals observers after mount +useWebVitals(); +``` + +## API + +### Parameters + +| Parameter | Type | Required | Description | +| ---------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- | +| `callback` | `(metric: IWebVitalsMetric) => void` | No | Custom handler for each metric. Defaults to `console.warn` formatted output in dev mode; no-op in production. | + +### IWebVitalsMetric + +| Field | Type | Description | +| -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | `string` | Metric name: `"FCP"` (First Contentful Paint), `"LCP"` (Largest Contentful Paint), `"CLS"` (Cumulative Layout Shift), `"INP"` (Interaction to Next Paint), `"TTFB"` (Time to First Byte) | +| `value` | `number` | Metric value in milliseconds for all metrics except CLS, which is a unitless score | +| `rating` | `"good" \| "needs-improvement" \| "poor"` | Performance rating based on Google's thresholds (e.g., LCP < 2500ms = "good") | + +### Returns + +This is a side-effect-only composable with no return value. + +## How It Works + +The composable registers five separate observers from the `web-vitals` library: `onFCP`, `onLCP`, `onCLS`, `onINP`, and `onTTFB`. Each observer fires once (or in the case of CLS, may fire multiple times as the page stabilizes) and calls the provided callback with the raw `Metric` object from `web-vitals`, which is mapped to the simpler `IWebVitalsMetric` shape. + +The default callback formats CLS values to 4 decimal places (since CLS is a dimensionless score typically between 0 and 1) and rounds all other values to whole milliseconds. Output looks like: + +``` +[web-vitals] FCP: 842ms (good) +[web-vitals] LCP: 1923ms (good) +[web-vitals] CLS: 0.0412 (good) +[web-vitals] INP: 156ms (needs-improvement) +[web-vitals] TTFB: 312ms (good) +``` + +## Recipe: Sending Web Vitals to Application Insights + +```typescript +import { useWebVitals, useAppInsights } from "@vc-shell/framework"; + +const { appInsights } = useAppInsights(); + +useWebVitals((metric) => { + appInsights.trackMetric({ + name: `WebVital_${metric.name}`, + average: metric.value, + properties: { + rating: metric.rating, + page: window.location.pathname, + }, + }); +}); +``` + +This sends each Web Vital as a custom metric to Application Insights, where you can build dashboards, set alerts on regressions, and segment by page. + +## Recipe: Conditional Reporting Based on Rating + +```typescript +import { useWebVitals } from "@vc-shell/framework"; + +useWebVitals((metric) => { + // Only report poor metrics to reduce noise + if (metric.rating === "poor") { + fetch("/api/telemetry/web-vitals", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + metric: metric.name, + value: metric.value, + url: window.location.href, + userAgent: navigator.userAgent, + timestamp: Date.now(), + }), + }); + } +}); +``` + +## Tips + +- **Call only once per app session.** Calling `useWebVitals()` multiple times registers duplicate observers, which means your callback fires twice for each metric. Place it in `main.ts` after `app.mount()`. +- **CLS may report multiple times.** The CLS observer can fire whenever a new layout shift occurs. Each call reports the cumulative score so far. The final value (reported when the page is hidden or unloaded) is the one that matters. +- **INP replaced FID.** As of March 2024, Google uses Interaction to Next Paint (INP) instead of First Input Delay (FID) as a Core Web Vital. This composable tracks INP, not FID. +- **Metrics are real-user only.** These are field metrics from actual users. They may differ significantly from lab metrics (Lighthouse). Both are valuable but measure different things. + +## Related + +- [web.dev/vitals](https://web.dev/vitals/) -- Core Web Vitals documentation and thresholds +- `web-vitals` npm package -- underlying measurement library +- [useAppInsights](./useAppInsights.md) -- Application Insights integration for sending metrics diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/.pages new file mode 100644 index 0000000000..33529be7e5 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/.pages @@ -0,0 +1,10 @@ +title: Concepts +nav: + - Blade Navigation: blade-navigation.md + - Modules: modules.md + - Extensions: extensions.md + - Layout: layout.md + - Permissions Model: permissions-model.md + - Localization: localization.md + - State Persistence: state-persistence.md + - API Clients: api-clients.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/api-clients.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/api-clients.md new file mode 100644 index 0000000000..991bd22d35 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/api-clients.md @@ -0,0 +1,3 @@ +# API Clients + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/blade-navigation.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/blade-navigation.md new file mode 100644 index 0000000000..bf99626f84 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/blade-navigation.md @@ -0,0 +1,3 @@ +# Blade Navigation + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/extensions.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/extensions.md new file mode 100644 index 0000000000..4008723d63 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/extensions.md @@ -0,0 +1,3 @@ +# Extensions + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/layout.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/layout.md new file mode 100644 index 0000000000..7de4f4685b --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/layout.md @@ -0,0 +1,3 @@ +# Layout + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/localization.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/localization.md new file mode 100644 index 0000000000..52c218f98a --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/localization.md @@ -0,0 +1,3 @@ +# Localization + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/modules.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/modules.md new file mode 100644 index 0000000000..f3a3b42dd7 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/modules.md @@ -0,0 +1,3 @@ +# Modules + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/permissions-model.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/permissions-model.md new file mode 100644 index 0000000000..ee07eae24e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/permissions-model.md @@ -0,0 +1,3 @@ +# Permissions Model + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/state-persistence.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/state-persistence.md new file mode 100644 index 0000000000..94d51d1e5c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/concepts/state-persistence.md @@ -0,0 +1,3 @@ +# State Persistence + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/.pages new file mode 100644 index 0000000000..5ac3da9968 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/.pages @@ -0,0 +1,7 @@ +title: Getting Started +nav: + - installation.md + - create-your-app.md + - project-structure.md + - connecting-to-platform.md + - first-blade.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/connecting-to-platform.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/connecting-to-platform.md new file mode 100644 index 0000000000..6bd46b901e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/connecting-to-platform.md @@ -0,0 +1,3 @@ +# Connecting To Platform + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/create-your-app.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/create-your-app.md new file mode 100644 index 0000000000..385195e45d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/create-your-app.md @@ -0,0 +1,3 @@ +# Create Your App + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/first-blade.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/first-blade.md new file mode 100644 index 0000000000..b39a75828c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/first-blade.md @@ -0,0 +1,3 @@ +# First Blade + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/installation.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/installation.md new file mode 100644 index 0000000000..7dbdc5b1b0 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/installation.md @@ -0,0 +1,3 @@ +# Installation + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/project-structure.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/project-structure.md new file mode 100644 index 0000000000..bde05f8ca7 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/getting-started/project-structure.md @@ -0,0 +1,3 @@ +# Project Structure + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/.pages new file mode 100644 index 0000000000..be5d40e45a --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/.pages @@ -0,0 +1,10 @@ +title: Guides +nav: + - Blades: blades/index.md + - Data: data/index.md + - Forms: forms/index.md + - UI: ui/index.md + - Modules and Extensions: modules-and-extensions/index.md + - Platform: platform/index.md + - Cookbook: cookbook/index.md + - Troubleshooting: troubleshooting/index.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/blades/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/blades/index.md new file mode 100644 index 0000000000..b887aee469 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/blades/index.md @@ -0,0 +1,3 @@ +# Blades + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/cookbook/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/cookbook/index.md new file mode 100644 index 0000000000..dc858af0c9 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/cookbook/index.md @@ -0,0 +1,3 @@ +# Cookbook + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/data/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/data/index.md new file mode 100644 index 0000000000..4bc18b98e4 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/data/index.md @@ -0,0 +1,3 @@ +# Data + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/forms/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/forms/index.md new file mode 100644 index 0000000000..6b0f991a05 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/forms/index.md @@ -0,0 +1,3 @@ +# Forms + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/modules-and-extensions/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/modules-and-extensions/index.md new file mode 100644 index 0000000000..153f0fa27e --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/modules-and-extensions/index.md @@ -0,0 +1,3 @@ +# Modules and Extensions + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/platform/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/platform/index.md new file mode 100644 index 0000000000..f57591e8fc --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/platform/index.md @@ -0,0 +1,3 @@ +# Platform + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/troubleshooting/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/troubleshooting/index.md new file mode 100644 index 0000000000..88ff0563cb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/troubleshooting/index.md @@ -0,0 +1,3 @@ +# Troubleshooting + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/ui/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/ui/index.md new file mode 100644 index 0000000000..c544f77228 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/guides/ui/index.md @@ -0,0 +1,3 @@ +# UI + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/.pages new file mode 100644 index 0000000000..57907950cb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/.pages @@ -0,0 +1,6 @@ +title: Introduction +nav: + - index.md + - what-is-vc-shell.md + - architecture-overview.md + - when-to-use.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/architecture-overview.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/architecture-overview.md new file mode 100644 index 0000000000..2c9daeb599 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/architecture-overview.md @@ -0,0 +1,3 @@ +# Architecture Overview + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/vc-shell-overview.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/index.md similarity index 89% rename from platform/developer-guide/docs/custom-apps-development/vc-shell/vc-shell-overview.md rename to platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/index.md index 9b1e0f42a5..7406187bad 100644 --- a/platform/developer-guide/docs/custom-apps-development/vc-shell/vc-shell-overview.md +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/index.md @@ -2,7 +2,7 @@ [VC-Shell Framework](https://github.com/VirtoCommerce/vc-shell) for specialized back-office applications is created to replace the current VC Platform manager concept. - + VC-Shell is a modern framework for building specialized back-office applications using Vue 3. It provides a set of reusable components, services, and utilities designed to simplify and speed up the development of custom business applications. @@ -44,7 +44,7 @@ The VC-Shell framework itself is organized into several key internal directories - **assets**: Static assets like base styles, images, and icons for the framework itself. - **locales**: Default internationalization resources for framework elements. -{: width="25"} [Application architecture best practices](Guides/application-architecture-best-practices.md) +{: width="25"} [What is VC-Shell?](what-is-vc-shell.md) -{: width="25"} [Creating Your First Custom Application](Getting-started/creating-first-custom-app.md) +{: width="25"} [Architecture Overview](architecture-overview.md) diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/what-is-vc-shell.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/what-is-vc-shell.md new file mode 100644 index 0000000000..39ced90c00 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/what-is-vc-shell.md @@ -0,0 +1,3 @@ +# What Is VC-Shell + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/when-to-use.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/when-to-use.md new file mode 100644 index 0000000000..cc3737bad8 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/introduction/when-to-use.md @@ -0,0 +1,3 @@ +# When To Use + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/.pages new file mode 100644 index 0000000000..6cb7e573c4 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/.pages @@ -0,0 +1,6 @@ +title: Reference +nav: + - CLI: cli + - API: api + - Modules: modules + - Migration: migration/index.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/.pages new file mode 100644 index 0000000000..4bff93cedb --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/.pages @@ -0,0 +1,12 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: API +nav: + - Core Types: types-core.md + - Date Utilities: date-utilities.md + - Injection Keys: injection-keys.md + - Platform Client: platform-client.md + - Shared Utilities: shared-utilities.md + - Thumbnail Utility: thumbnail.md + - UI Types: types-ui.md + - Utilities Overview: utilities-overview.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/date-utilities.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/date-utilities.md new file mode 100644 index 0000000000..59ebc83949 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/date-utilities.md @@ -0,0 +1,105 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/utilities/date/date-utilities.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Date Utilities + +Pure functions for date formatting, relative time display, and Moment.js-to-date-fns format conversion. Built on `date-fns` with locale-aware output. + +## Overview + +The framework migrated from Moment.js to `date-fns`. These utilities handle the conversion of legacy Moment format strings and provide consistent date formatting across the application. All functions accept flexible date input (`string | number | Date | null | undefined`). + +## Exports + +| Export | Description | +| ----------------------- | -------------------------------------------------------------------- | +| `formatDateRelative` | Formats a date as relative time (e.g., "3 hours ago", "2 days ago") | +| `formatDateWithPattern` | Formats a date using a Moment.js-compatible format string | +| `convertMomentFormat` | Converts a Moment.js format string to date-fns format | +| `resolveLocale` | Async: loads and caches a date-fns locale by code (e.g., "fr", "de") | +| `resolveLocaleSync` | Sync: returns cached locale or falls back to `enUS` while loading | + +## Usage + +### Relative dates + +```typescript +import { formatDateRelative } from "@vc-shell/framework"; + +formatDateRelative("2024-01-15T10:00:00Z"); +// => "3 months ago" + +formatDateRelative("2024-01-15T10:00:00Z", "fr"); +// => "il y a 3 mois" +``` + +### Pattern-based formatting + +```typescript +import { formatDateWithPattern } from "@vc-shell/framework"; + +// Accepts Moment.js format strings -- converted internally +formatDateWithPattern("2024-03-15T14:30:00Z", "YYYY-MM-DD"); +// => "2024-03-15" + +formatDateWithPattern("2024-03-15T14:30:00Z", "LLL", "de"); +// => "15. Marz 2024, 14:30" (localized) +``` + +### Moment format conversion + +```typescript +import { convertMomentFormat } from "@vc-shell/framework"; + +convertMomentFormat("YYYY-MM-DD"); // => "yyyy-MM-dd" +convertMomentFormat("DD/MM/YYYY"); // => "dd/MM/yyyy" +convertMomentFormat("LLL"); // => "PPp" +convertMomentFormat("dddd"); // => "EEEE" +``` + +### Token mapping reference + +| Moment | date-fns | Meaning | +| ------ | -------- | ---------------------------- | +| `YYYY` | `yyyy` | 4-digit year | +| `YY` | `yy` | 2-digit year | +| `DD` | `dd` | Day of month (zero-padded) | +| `D` | `d` | Day of month | +| `Do` | `do` | Day ordinal | +| `dddd` | `EEEE` | Weekday name | +| `ddd` | `EEE` | Weekday abbreviation | +| `A` | `a` | AM/PM | +| `L` | `P` | Localized date | +| `LL` | `PP` | Localized date (long) | +| `LLL` | `PPp` | Localized date + time | +| `LLLL` | `PPPp` | Localized date + time (full) | +| `LT` | `p` | Localized time | +| `LTS` | `pp` | Localized time with seconds | + +### Locale resolution + +```typescript +import { resolveLocale, resolveLocaleSync } from "@vc-shell/framework"; + +// Async -- loads locale dynamically, caches for subsequent calls +const locale = await resolveLocale("fr"); + +// Sync -- returns cached locale or enUS while the async load happens +const locale = resolveLocaleSync("de"); +``` + +The locale resolver tries the full code first (e.g., `pt-BR`), then the base language (`pt`), and falls back to `enUS` if neither is available. + +## Tips + +- `formatDateWithPattern` automatically calls `convertMomentFormat` internally -- pass Moment format strings directly. +- `resolveLocaleSync` triggers an async load in the background. On the first call for a new locale, output will use `enUS`; subsequent renders will use the correct locale once loaded. +- All formatting functions return an empty string for null/undefined/invalid date input. +- Locale objects are cached in a module-level `Map` -- no duplicate network requests for the same locale. + +## Related + +- `framework/ui/components/organisms/vc-table/components/cells/` -- cell renderers use these for date/datetime/date-ago columns +- `framework/shared/modules/assets-manager/` -- uses `formatDateRelative` for asset timestamps diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/.pages new file mode 100644 index 0000000000..506ad0081f --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/.pages @@ -0,0 +1,6 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Directives +nav: + - v-autofocus: v-autofocus.md + - v-loading: v-loading.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-autofocus.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-autofocus.md new file mode 100644 index 0000000000..80ab33e3f2 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-autofocus.md @@ -0,0 +1,130 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/directives/autofocus/autofocus.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# v-autofocus Directive + +Focuses an element when it is mounted, conditionally based on the binding value. + +## Overview + +When building blade-based interfaces, users often expect the primary input field to receive focus automatically as soon as a blade or dialog opens. Without auto-focus, users must manually click the first field every time, which slows down data entry workflows. + +The `v-autofocus` directive solves this by calling `el.focus()` on the element's `mounted` lifecycle hook whenever the bound value is truthy. It is a one-shot directive -- it only evaluates the condition at mount time and does not re-focus on subsequent updates or reactive changes. + +The directive is registered globally by the framework, so no manual import is needed in templates. + +## API + +| Binding | Type | Description | +| ------------------------- | --------- | --------------------------------------------------- | +| `v-autofocus="condition"` | `boolean` | Focus the element on mount if `condition` is truthy | + +The directive only acts on the `mounted` hook. It does not re-focus on updates. + +## Source + +```typescript +// framework/core/directives/autofocus/index.ts +import { Directive, DirectiveBinding } from "vue"; + +export const autofocus = { + mounted(el: HTMLElement, binding: DirectiveBinding): void { + if (binding.value) { + el.focus(); + } + }, +} as Directive; +``` + +## Usage Examples + +### Always focus on mount + +```vue +<template> + <!-- The search field gets focus as soon as the blade opens --> + <input + v-autofocus="true" + placeholder="Search orders..." + /> +</template> +``` + +### Conditionally focus based on blade mode + +```vue +<template> + <!-- Only auto-focus when the blade is in edit mode --> + <VcInput + v-autofocus="isEditMode" + v-model="product.name" + label="Product Name" + /> +</template> + +<script setup lang="ts"> +import { computed } from "vue"; + +const props = defineProps<{ param?: string }>(); +const isEditMode = computed(() => !!props.param); +</script> +``` + +### Focus inside a dialog + +```vue +<template> + <VcPopup + v-model:show="showDialog" + title="Rename Item" + > + <VcInput + v-autofocus="showDialog" + v-model="newName" + label="New name" + /> + </VcPopup> +</template> +``` + +### Using with VcInput vs native input + +The directive works on any HTML element that supports `.focus()`. For `VcInput` and other framework components, the directive is applied to the component's root element. If the root element is not focusable (e.g., a `<div>` wrapper), use the component's `autofocus` prop instead: + +```vue +<!-- Preferred for framework components: use the autofocus prop --> +<VcInput :autofocus="true" v-model="value" label="Name" /> + +<!-- Works on native elements directly --> +<input v-autofocus="true" /> +<textarea v-autofocus="true" /> +``` + +## Tip: Re-focusing on reactive changes + +Since `v-autofocus` only fires on mount, it will not re-focus if you toggle the condition later. If you need re-focus behavior (e.g., after a save operation returns to edit mode), use a template ref with `watch`: + +```typescript +import { ref, watch, nextTick } from "vue"; + +const inputRef = ref<HTMLInputElement>(); +const isEditMode = ref(false); + +watch(isEditMode, async (editing) => { + if (editing) { + await nextTick(); + inputRef.value?.focus(); + } +}); +``` + +## Common Mistake + +Do not bind `v-autofocus` to a reactive value expecting it to re-focus on changes. The directive only evaluates once at mount time. If you write `v-autofocus="isEditing"` and `isEditing` starts as `false` then becomes `true`, the element will not receive focus because the mounted hook already ran. + +## Related + +- `framework/ui/types/form-field.ts` -- `ITextFieldProps.autofocus` prop on form components +- `framework/core/directives/loading/` -- `v-loading` directive diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-loading.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-loading.md new file mode 100644 index 0000000000..cf0be6a039 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/directives/v-loading.md @@ -0,0 +1,178 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/directives/loading/loading.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# v-loading Directive + +Displays a loading overlay with a spinner on any element. Supports size variants, custom color, blur backdrop, fullscreen mode, and z-index control. + +## Overview + +Many blade and widget views need to indicate that data is being fetched or an operation is in progress. The `v-loading` directive provides a declarative way to show a spinner overlay on any DOM element without adding conditional rendering logic to your template. + +When the bound value is truthy, the directive adds CSS classes and custom properties that activate a spinner overlay rendered via CSS pseudo-elements. When the value becomes falsy, all loading state is cleanly removed. The visual styles are defined in `./styles.css` and imported automatically when the directive is used. + +The directive is registered globally by the framework, so no manual import is needed in templates. + +Unlike a standalone loading component, `v-loading` scopes the overlay to the element it is applied to, making it easy to show loading states on individual sections, cards, or panels without affecting the rest of the page. + +## API + +| Binding | Type | Description | +| ----------------------- | ---------------- | ------------------------------------ | +| `v-loading="true"` | `boolean` | Show/hide the loading overlay | +| `v-loading="options"` | `LoadingOptions` | Show with configuration (see below) | +| `v-loading:1000="true"` | `arg: string` | Set custom z-index (default: `9999`) | + +### LoadingOptions + +| Property | Type | Default | Description | +| ------------ | -------------------------------- | ------- | ------------------------------------------------------- | +| `size` | `"small" \| "medium" \| "large"` | -- | Spinner size via `data-loading-size` attribute | +| `color` | `string` | -- | Custom spinner color (sets `--v-loading-spinner-color`) | +| `blur` | `boolean` | `true` | Enable backdrop blur; `false` adds `v-loading--no-blur` | +| `fullscreen` | `boolean` | `false` | Fullscreen overlay via `v-loading--fullscreen` | + +## How It Works + +The directive manipulates CSS classes and custom properties on the target element: + +1. **Truthy value**: adds `v-loading` class, sets `--v-loading-z-index`, and optionally sets size/color/blur/fullscreen attributes. +2. **Falsy value**: removes all `v-loading` classes, attributes, and custom properties. +3. The CSS in `styles.css` uses `::before` and `::after` pseudo-elements on `.v-loading` to render the backdrop and spinner animation. + +Because the directive modifies the element directly (not through Vue reactivity), it works on both mount and update hooks. Toggling the bound value at any time updates the overlay immediately. + +## Usage Examples + +### Simple boolean toggle + +```vue +<template> + <div + v-loading="isLoading" + class="tw-min-h-[200px]" + > + <p>Order details will appear here</p> + </div> +</template> + +<script setup lang="ts"> +import { ref } from "vue"; + +const isLoading = ref(true); + +async function loadOrder() { + isLoading.value = true; + try { + // ... fetch data + } finally { + isLoading.value = false; + } +} +</script> +``` + +### With size and color options + +```vue +<template> + <!-- Small spinner with brand color, no blur --> + <div v-loading="{ size: 'small', color: 'var(--primary-500)', blur: false }"> + <img + :src="thumbnailUrl" + alt="Product thumbnail" + /> + </div> +</template> +``` + +### Fullscreen loading overlay + +```vue +<template> + <!-- Covers the entire viewport during initial app load --> + <div v-loading="{ fullscreen: true, size: 'large' }"> + <RouterView /> + </div> +</template> +``` + +### Custom z-index via directive argument + +```vue +<template> + <!-- Use a lower z-index so popups can render above the spinner --> + <div v-loading:500="isLoading">Content</div> + + <!-- Default z-index is 9999 --> + <div v-loading="isLoading">Content</div> +</template> +``` + +### Blade content area + +```vue +<template> + <VcBlade + title="Products" + :closable="true" + > + <div + v-loading="loading" + class="tw-p-4" + > + <VcDataTable + :items="products" + :columns="columns" + /> + </div> + </VcBlade> +</template> + +<script setup lang="ts"> +import { useAsync } from "@vc-shell/framework"; + +const { loading, action: loadProducts } = useAsync(async () => { + // fetch products... +}); +</script> +``` + +## Tip: Ensure the element has dimensions + +The loading overlay is positioned absolutely within the target element. If the element has no height (e.g., an empty `<div>`), the spinner will not be visible. Always ensure the loading container has a minimum height: + +```vue +<!-- Good: min-height ensures the spinner is visible even when content is empty --> +<div v-loading="isLoading" class="tw-min-h-[200px]">...</div> + +<!-- Bad: empty div collapses to 0px height, spinner invisible --> +<div v-loading="isLoading"></div> +``` + +## Common Mistake + +Passing an options object when you want to hide the spinner does not work as expected because an object is always truthy: + +```vue +<!-- Bug: this always shows the spinner because {} is truthy --> +<div v-loading="isLoading ? { size: 'small' } : {}">...</div> + +<!-- Fix: use false when not loading --> +<div v-loading="isLoading ? { size: 'small' } : false">...</div> +``` + +## CSS Classes Reference + +| Class | Applied When | Effect | +| ----------------------- | ------------------ | ---------------------------------- | +| `v-loading` | Value is truthy | Shows the spinner overlay | +| `v-loading--no-blur` | `blur: false` | Disables backdrop blur filter | +| `v-loading--fullscreen` | `fullscreen: true` | Overlay covers the entire viewport | + +## Related + +- `framework/core/directives/autofocus/` -- `v-autofocus` directive +- `framework/core/composables/useLoading/` -- composable for managing loading state reactively diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/index.md new file mode 100644 index 0000000000..8b88894796 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/index.md @@ -0,0 +1,3 @@ +# API + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/injection-keys.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/injection-keys.md new file mode 100644 index 0000000000..3a49dcb90c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/injection-keys.md @@ -0,0 +1,174 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: injection-keys.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Injection Keys + +Centralized Vue `InjectionKey` symbols for the vc-shell framework's provide/inject dependency injection system. All keys are typed via `InjectionKey<T>` for full TypeScript safety. + +## Overview + +The vc-shell framework uses Vue's provide/inject mechanism extensively to share services, navigation state, and configuration across the component tree. Instead of relying on global singletons or Pinia stores, the framework creates typed injection keys for each service, allowing components to declare their dependencies explicitly. + +All keys are defined in a single file (`framework/injection-keys.ts`) to avoid symbol duplication and ensure type safety. The app shell provides these values at the root during bootstrap; components and composables inject them using the corresponding key. + +This centralized approach has several advantages: + +- **Type safety**: `inject(MenuServiceKey)` returns `MenuService | undefined`, not `unknown` +- **No symbol collisions**: each key is a unique `Symbol`, preventing accidental overwrites +- **Testability**: services can be mocked by providing different values in test wrappers +- **Discoverability**: all injectable dependencies are listed in one place + +## Keys + +### Blade Navigation + +| Key | Type | Description | +| -------------------- | -------------------------------------- | -------------------------------------------- | +| `BladeDescriptorKey` | `ComputedRef<BladeDescriptor>` | Current blade descriptor metadata | +| `BladeBackButtonKey` | `Component \| undefined` | Custom back button component for a blade | +| `BladeDataKey` | _(from blade-navigation types)_ | Data passed between parent/child blades | +| `BladeContextKey` | `ComputedRef<Record<string, unknown>>` | Blade-exposed context for widgets/extensions | +| `BladeRoutesKey` | `BladeRoutesRecord[]` | Registered blade routes | +| `InternalRoutesKey` | `BladeRoutesRecord[]` | Internal framework routes | + +### Notifications + +| Key | Type | Description | +| ---------------------- | ------------------- | ----------------------------------- | +| `NotificationStoreKey` | `NotificationStore` | Shared notification store singleton | + +### Services + +| Key | Type | Description | +| ------------------------------- | ----------------------------- | ------------------------------ | +| `WidgetServiceKey` | `IWidgetService` | Widget registration and lookup | +| `DashboardServiceKey` | `IDashboardService` | Dashboard widget management | +| `MenuServiceKey` | `MenuService` | Main navigation menu | +| `SettingsMenuServiceKey` | `ISettingsMenuService` | Settings sidebar menu | +| `AppBarWidgetServiceKey` | `IAppBarWidgetService` | App bar widget slots | +| `AppBarMobileButtonsServiceKey` | `IAppBarMobileButtonsService` | Mobile app bar buttons | +| `LanguageServiceKey` | `ILanguageService` | Localization service | +| `ToolbarServiceKey` | `IToolbarService` | Blade toolbar actions | +| `AiAgentServiceKey` | `IAiAgentService` | AI agent integration | + +### Module System + +| Key | Type | Description | +| --------------------- | ------------------------------------ | ----------------------------------------------------------------------- | +| `DynamicModulesKey` | `DynamicModuleRegistry \| undefined` | Registry of loaded dynamic modules (extensible via declaration merging) | +| `ModulesReadyKey` | `Ref<boolean>` | Whether all modules have finished loading | +| `ModulesLoadErrorKey` | `Ref<boolean>` | Whether all modules failed to load | + +### UI State + +| Key | Type | Description | +| ---------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- | +| `WidgetScopeKey` | `IWidgetScope` | Widget scope (provided by WidgetContainer for component-based widgets via `WidgetScope.vue`) | +| `AppRootElementKey` | `Ref<HTMLElement \| undefined>` | App root element for scoped Teleport | +| `EmbeddedModeKey` | `boolean` | Whether the app runs in embedded mode | +| `ShellIndicatorsKey` | `ComputedRef<boolean>` | Unread indicator state for sidebar | +| `CloseSettingsMenuKey` | `() => void` | Callback to close the settings menu | + +### Breakpoints + +| Key | Type | Description | +| -------------- | -------------- | ---------------------- | +| `IsMobileKey` | `Ref<boolean>` | Mobile breakpoint | +| `IsDesktopKey` | `Ref<boolean>` | Desktop breakpoint | +| `IsPhoneKey` | `Ref<boolean>` | Phone breakpoint | +| `IsTabletKey` | `Ref<boolean>` | Tablet breakpoint | +| `IsTouchKey` | `boolean` | Touch device detection | + + + +## Usage Examples + +### Injecting a service in a component + +```typescript +import { inject } from "vue"; +import { MenuServiceKey, WidgetServiceKey } from "@vc-shell/framework"; + +// In component setup: +const menuService = inject(MenuServiceKey)!; +const widgetService = inject(WidgetServiceKey)!; +``` + +### Safe injection with fallback + +```typescript +import { inject } from "vue"; +import { IsMobileKey, IsDesktopKey } from "@vc-shell/framework"; + +// Provide a default value to avoid undefined checks +const isMobile = inject(IsMobileKey, ref(false)); +const isDesktop = inject(IsDesktopKey, ref(true)); +``` + +### Providing values in a test wrapper + +```typescript +import { mount } from "@vue/test-utils"; +import { MenuServiceKey, WidgetServiceKey } from "@vc-shell/framework"; + +const wrapper = mount(MyComponent, { + global: { + provide: { + [MenuServiceKey as symbol]: mockMenuService, + [WidgetServiceKey as symbol]: mockWidgetService, + }, + }, +}); +``` + +### Extending DynamicModuleRegistry via declaration merging + +```typescript +declare module "@vc-shell/framework" { + interface DynamicModuleRegistry { + orders: { refreshOrders: () => Promise<void>; orderCount: ComputedRef<number> }; + } +} + +const modules = inject(DynamicModulesKey); +const orderCount = modules?.orders.orderCount; // Typed as ComputedRef<number> +``` + +## Tip: Prefer Composables Over Direct Injection + +Most injection keys have a corresponding composable wrapper (e.g., `useMenuService()`, `useWidgets()`, `useToolbar()`) that handles injection, error reporting, and provides a cleaner API. Prefer using the composable unless you need low-level access to the raw service: + +```typescript +// Preferred: composable handles injection and error reporting +import { useMenuService } from "@vc-shell/framework"; +const menuService = useMenuService(); + +// Low-level: direct injection (you handle undefined checks) +import { inject } from "vue"; +import { MenuServiceKey } from "@vc-shell/framework"; +const menuService = inject(MenuServiceKey); +if (!menuService) throw new Error("MenuService not provided"); +``` + +## Common Mistake + +Do not create your own `Symbol` for an injection key that already exists in the framework. Two different symbols with the same description are not equal, so `inject()` will return `undefined`: + +```typescript +// Bad: new Symbol is a different key, inject will return undefined +const MyMenuKey = Symbol("MenuService"); +const service = inject(MyMenuKey); // undefined! + +// Good: use the framework's key +import { MenuServiceKey } from "@vc-shell/framework"; +const service = inject(MenuServiceKey); // MenuService instance +``` + +## Related + +- `framework/core/services/` -- Service implementations provided via these keys +- `framework/core/notifications/store.ts` -- NotificationStore provided via `NotificationStoreKey` +- `framework/shared/components/blade-navigation/types.ts` -- Blade types for navigation keys +- `framework/core/composables/` -- Composable wrappers for most injection keys diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/platform-client.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/platform-client.md new file mode 100644 index 0000000000..8a70dd5807 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/platform-client.md @@ -0,0 +1,173 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/api/platform.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Platform API Client + +Auto-generated TypeScript API client for the VirtoCommerce Platform REST API. Generated by NSwag from the platform's Swagger/OpenAPI specification. + +## Overview + +Communicating with the VirtoCommerce platform backend requires typed HTTP client classes that match the platform's REST endpoints. Rather than manually writing fetch calls or Axios requests, the framework provides auto-generated client classes that handle URL construction, request serialization, response deserialization, and authentication token injection. + +Each API client class extends `AuthApiBase`, which automatically attaches the Bearer token to every request. Data model types (DTOs, Commands, Queries) are generated as **interfaces** (not classes), so they cannot be instantiated with `new` -- use object literals with type annotations instead. The clients are generated by NSwag from the platform's Swagger/OpenAPI specification and should not be edited manually -- any manual changes will be overwritten during regeneration. + +**File:** `platform.ts` (auto-generated, do not edit manually) + +## When to Use + +- Call platform-level REST endpoints (security, settings, notifications, modules, dynamic properties) from typed TypeScript clients +- Access platform DTOs (`ApplicationUser`, `PushNotification`, `Role`, `Permission`, etc.) as typed interfaces +- Combine with `useApiClient` for automatic token management and caching +- When NOT to use: for domain-module APIs (orders, catalog, inventory) -- use their own generated clients instead; for third-party APIs -- use `fetch` or Axios directly + +## API Clients + +All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fetch implementation. + +| Client | Description | +| --------------------------- | -------------------------------------------------------- | +| `ExternalSignInClient` | External authentication provider sign-in | +| `AppsClient` | Application descriptor operations | +| `AuthorizationClient` | Permission and role checking | +| `ChangeLogClient` | Platform change log / audit trail | +| `DiagnosticsClient` | System diagnostics and health | +| `DynamicPropertiesClient` | Dynamic property CRUD and dictionary management | +| `JobsClient` | Background job management | +| `LocalizableSettingsClient` | Localizable setting values | +| `ModulesClient` | Platform module management (install, update, restart) | +| `OAuthAppsClient` | OAuth application registration | +| `PushNotificationClient` | Push notification search and mark-as-read | +| `SecurityClient` | User management, roles, permissions, password operations | +| `SettingClient` | Platform settings CRUD | + +## Key DTOs (Interfaces) + +| Interface | Description | +| -------------------------------- | --------------------------------------------------------------------------------- | +| `PushNotification` | Push notification payload: `id`, `title`, `notifyType`, `isNew`, `finished`, etc. | +| `PushNotificationSearchCriteria` | Search criteria for notification queries | +| `ApplicationUser` | Platform user with roles, permissions, logins | +| `Role` | Security role with permissions | +| `Permission` | Individual permission entry | +| `DynamicProperty` | Dynamic property definition | +| `DynamicObjectProperty` | Property value bound to an object | +| `ModuleDescriptor` | Module metadata (id, version, dependencies) | +| `ChangeLogSearchCriteria` | Audit log search parameters | +| `ChangeLogSearchResult` | Paginated audit log results | +| `ObjectSettingEntry` | Setting entry with value and metadata | +| `License` | Platform license information | + +## Base Class + +```typescript +export class AuthApiBase { + authToken: string; + setAuthToken(token: string): void; + protected getBaseUrl(defaultUrl: string, baseUrl: string): string; // always returns "" + protected transformOptions(options: RequestInit): Promise<RequestInit>; // injects Bearer token +} +``` + +The `getBaseUrl` method always returns an empty string, meaning API calls are relative to the current origin. This works because the vc-shell admin app is typically served from the same domain as the platform API (or uses a reverse proxy). + +## Usage Examples + +### Fetching push notifications + +```typescript +import { PushNotificationClient, PushNotificationSearchCriteria } from "@vc-shell/framework"; + +const client = new PushNotificationClient(); +const criteria: PushNotificationSearchCriteria = { take: 20, skip: 0 }; +const result = await client.searchPushNotification(criteria); + +console.log(`Found ${result.totalCount} notifications`); +for (const notification of result.results ?? []) { + console.log(`${notification.title} (${notification.notifyType})`); +} +``` + +### Getting the current user + +```typescript +import { SecurityClient } from "@vc-shell/framework"; + +const securityClient = new SecurityClient(); +const user = await securityClient.getCurrentUser(); + +console.log(`Logged in as: ${user.userName}`); +console.log(`Roles: ${user.roles?.map((r) => r.name).join(", ")}`); +console.log(`Is admin: ${user.isAdministrator}`); +``` + +### Using with useApiClient composable + +The recommended pattern in vc-shell is to use the `useApiClient` composable, which handles token management and provides a cached client instance: + +```typescript +import { useApiClient } from "@vc-shell/framework"; +import { SecurityClient } from "@vc-shell/framework"; + +const { getApiClient } = useApiClient(SecurityClient); + +async function loadUser() { + const client = await getApiClient(); + return await client.getCurrentUser(); +} +``` + +### Working with dynamic properties + +```typescript +import { DynamicPropertiesClient, DynamicObjectProperty } from "@vc-shell/framework"; + +const client = new DynamicPropertiesClient(); + +// Search for properties of a specific object type +const properties = await client.searchDynamicProperties({ + objectType: "VirtoCommerce.OrdersModule.Core.Model.CustomerOrder", + take: 50, +}); +``` + +### Managing platform settings + +```typescript +import { SettingClient, ObjectSettingEntry } from "@vc-shell/framework"; + +const client = new SettingClient(); + +// Read a specific setting +const settings = await client.getValues(["VirtoCommerce.Notifications.SendGrid.ApiKey"]); + +// Update a setting +const entry: ObjectSettingEntry = { + name: "MyModule.SomeSetting", + value: "new-value", +}; +await client.update([entry]); +``` + +## Tip: Token Management + +You do not need to manually set the auth token on client instances. The `useApiClient` composable and the framework's authentication system handle this automatically. If you create a client manually with `new SecurityClient()`, the token is injected via `AuthApiBase.transformOptions()` which reads from the shared auth store. + +## Common Mistake + +Do not import from the `platform.ts` file path directly. Always import from `@vc-shell/framework` to ensure proper module resolution and tree-shaking: + +```typescript +// Bad: direct file import +import { SecurityClient } from "@core/api/platform"; + +// Good: framework re-export +import { SecurityClient } from "@vc-shell/framework"; +``` + +## Related + +- `framework/core/notifications/` -- Notification system consuming `PushNotification` and `PushNotificationClient` +- `framework/core/composables/useApiClient/` -- composable for creating authenticated API client instances +- `cli/api-client-generator/` -- CLI tool for regenerating API clients from Swagger specs diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/shared-utilities.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/shared-utilities.md new file mode 100644 index 0000000000..104cc5fb6d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/shared-utilities.md @@ -0,0 +1,91 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/utilities/shared-utilities.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Shared Utilities + +Helper functions and TypeScript type utilities used across the shared layer of the framework. + +## Overview + +This directory provides small, focused utility modules for asset handling, color manipulation, badge formatting, and Vue component type extraction. + +## Exports + +| Export | Module | Description | +| ----------------------------- | --------------------- | --------------------------------------------------------------------------- | +| `isImage(name)` | `assets.ts` | Returns `true` if the file extension is an image (png, jpg, jpeg, svg, gif) | +| `getFileThumbnail(name)` | `assets.ts` | Returns a Bootstrap icon class for the file type (e.g., `bi-filetype-pdf`) | +| `readableSize(bytes)` | `assets.ts` | Formats byte count as human-readable string (e.g., `"1.5 MB"`) | +| `convertColorNameToHex(name)` | `colorUtils.ts` | Converts a CSS color name to hex using the Canvas API | +| `isValidHexColor(value)` | `colorUtils.ts` | Validates a 6-digit hex color string | +| `normalizeHexColor(hex)` | `colorUtils.ts` | Ensures hex string starts with `#` | +| `formatBadgeCount(value)` | `formatBadgeCount.ts` | Truncates numbers > 99 to `"99+"` for badge display | +| `ComponentProps<T>` | `vueUtils.ts` | Extracts props type from a Vue component | +| `ComponentSlots<T>` | `vueUtils.ts` | Extracts slots type from a Vue component | +| `ComponentEmit<T>` | `vueUtils.ts` | Extracts emit type from a Vue component | + +## Usage + +### Asset helpers + +```typescript +import { isImage, getFileThumbnail, readableSize } from "@vc-shell/framework"; + +isImage("photo.jpg"); // true +isImage("document.pdf"); // false + +getFileThumbnail("report.xlsx"); // "bi-filetype-xls" +getFileThumbnail("archive.zip"); // "bi-file-zip" +getFileThumbnail("unknown.abc"); // "bi-file-earmark" + +readableSize(1536); // "1.5 KB" +readableSize(0); // "0 Bytes" +``` + +### Color utilities + +```typescript +import { convertColorNameToHex, isValidHexColor, normalizeHexColor } from "@vc-shell/framework"; + +convertColorNameToHex("red"); // "#ff0000" +convertColorNameToHex("invalid"); // null + +isValidHexColor("#ff0000"); // true +isValidHexColor("ff0000"); // true (checks with/without #) +isValidHexColor("#fff"); // false (only 6-digit supported) + +normalizeHexColor("ff0000"); // "#ff0000" +``` + +### Badge formatting + +```typescript +import { formatBadgeCount } from "@vc-shell/framework"; + +formatBadgeCount(5); // "5" +formatBadgeCount(150); // "99+" +formatBadgeCount(undefined); // undefined +``` + +### Vue type utilities + +```typescript +import type { ComponentProps, ComponentSlots } from "@vc-shell/framework"; + +type MyProps = ComponentProps<typeof MyComponent>; +type MySlots = ComponentSlots<typeof MyComponent>; +``` + +## Tips + +- `convertColorNameToHex` creates a temporary Canvas element -- only use in browser context, not SSR. +- `readableSize` defaults to 2 decimal places; pass a second argument to change precision. +- `formatBadgeCount` is used by `VcWidget` and `WidgetDropdownItem` for consistent badge truncation. +- The `vueUtils.ts` types work with both `defineComponent` and `<script setup>` components. + +## Related + +- `framework/shared/modules/assets-manager/` -- uses asset helpers for file display +- `framework/ui/components/organisms/vc-table/components/` -- VcWidget uses `formatBadgeCount` diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/thumbnail.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/thumbnail.md new file mode 100644 index 0000000000..84ee891290 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/thumbnail.md @@ -0,0 +1,118 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/utilities/thumbnail/thumbnail.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Thumbnail URL Utility + +Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes. + +## When to Use + +- Use in any component that displays images at a known size smaller than the original +- Reduces bandwidth and improves page load time significantly +- Especially important for image lists (tables, galleries, cards) + +## Available Sizes + +### Named Presets + +| Preset | Use Case | +| ------ | ------------------------------------------- | +| `sm` | Small icons, table cells, avatar thumbnails | +| `md` | Medium previews, cards | +| `lg` | Large previews, hero images | + +### Pixel Sizes + +| Size | Pixels | Use Case | +| --------- | ------ | ---------------------------- | +| `64x64` | 64px | Table cells, tiny thumbnails | +| `128x128` | 128px | Small tiles, list items | +| `168x168` | 168px | Medium tiles | +| `216x216` | 216px | Gallery tiles (md) | +| `348x348` | 348px | Large gallery tiles | + +## API + +### `getThumbnailUrl(url, size?)` + +Transforms an image URL by inserting a size suffix before the file extension. + +```ts +import { getThumbnailUrl } from "@core/utilities/thumbnail"; + +getThumbnailUrl("https://cdn.example.com/photo.jpg", "sm"); +// → "https://cdn.example.com/photo_sm.jpg" + +getThumbnailUrl("https://cdn.example.com/photo.jpg", "128x128"); +// → "https://cdn.example.com/photo_128x128.jpg" + +getThumbnailUrl("https://cdn.example.com/photo.jpg"); +// → "https://cdn.example.com/photo.jpg" (unchanged) + +getThumbnailUrl(undefined, "sm"); +// → undefined +``` + +**Parameters:** + +- `url` — Original image URL (string or undefined) +- `size` — Thumbnail size preset or pixel dimensions (optional) + +**Returns:** Transformed URL, or original URL if size not specified + +### `getBestThumbnailSize(displaySize)` + +Maps a CSS pixel display size to the best-fit thumbnail preset. Picks the smallest thumbnail that is >= the display size. + +```ts +import { getBestThumbnailSize } from "@core/utilities/thumbnail"; + +getBestThumbnailSize(48); // → "64x64" +getBestThumbnailSize(96); // → "128x128" +getBestThumbnailSize(200); // → "216x216" +getBestThumbnailSize(500); // → "lg" +``` + +## Usage in Components + +### VcImage + +```vue +<VcImage :src="product.imgSrc" thumbnail-size="sm" size="s" /> +``` + +### VcGallery + +Gallery auto-maps `size` prop to thumbnail size. Override with `thumbnailSize`: + +```vue +<!-- Auto: sm→128x128, md→216x216, lg→348x348 --> +<VcGallery :images="images" size="md" /> + +<!-- Explicit override --> +<VcGallery :images="images" thumbnail-size="128x128" /> +``` + +Gallery preview uses `64x64` for the thumbnail strip and full-size for the main image automatically. + +### VcDataTable (CellImage) + +Table image cells use `sm` thumbnail by default — no action needed. + +## Types + +```ts +type ThumbnailPreset = "sm" | "md" | "lg"; +type ThumbnailPixelSize = "64x64" | "128x128" | "168x168" | "216x216" | "348x348"; +type ThumbnailSize = ThumbnailPreset | ThumbnailPixelSize; +``` + +## Notes + +- The utility only transforms the URL — the backend must have generated the thumbnail for the URL to resolve +- If a thumbnail doesn't exist on the server, the browser will show a broken image. Ensure your asset pipeline generates all required sizes. +- The suffix is inserted before the file extension: `photo.jpg` → `photo_sm.jpg` +- URLs without a file extension are returned unchanged +- Already-suffixed URLs are not double-transformed diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-core.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-core.md new file mode 100644 index 0000000000..cc4de7d337 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-core.md @@ -0,0 +1,191 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/types/types.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Core Types + +Shared TypeScript interfaces and types used across the vc-shell framework for validation, menus, toolbars, tables, assets, and service abstractions. + +## Overview + +These types form the contract between framework services, UI components, and consuming modules. They define the shape of data structures used throughout the application: how menu items are configured, how table columns are defined, what toolbar buttons look like, and how services communicate. + +All types are re-exported from `@vc-shell/framework`, so module developers import them directly from the framework package. + +**Files:** `index.ts`, `menu-types.ts`, `services.ts` + +## Key Interfaces + +### Validation + +| Type | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `IValidationRules` | Validation rule map for form fields. Supports `required`, `email`, `min`, `max`, `regex`, `between`, `confirmed`, `ext`, `mimes`, `dimensions`, `before`/`after` date comparison, and more. | + +### Menu System (`menu-types.ts`) + +| Type | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `MenuItemConfig` | Configuration for registering a menu item: `title`, `icon`, `priority`, `permissions`, `group`/`groupConfig`, `badge`. | +| `MenuItemBadge` | Badge display config: `content` (static, ref, computed, or function), `variant`, `isDot`. | +| `MenuItemBadgeConfig` | Union: full `MenuItemBadge` object or shorthand `number \| string \| Ref \| ComputedRef \| function`. | +| `MenuItem` | Runtime menu item extending `MenuItemConfig` with `routeId`, `url`, `children[]`, `groupIcon`, `groupId`. | + +### Toolbar + +| Type | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------ | +| `IBladeToolbar` | Toolbar button config: `id`, `icon`, `disabled`, `title`, `isVisible`, `clickHandler`, `separator`, `permissions`. | +| `ToolbarMenu<T>` | Generic toolbar menu item that infers component props from the provided component type. | + +### Table Columns + +| Type | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ITableColumnsBase` | Column definition: `id`, `title`, `width`, `field`, `type` (money, date, image, status, etc.), `sortable`, `editable`, `rules`, `filter`, `mobilePosition`, `mobileVisible`. | +| `ITableColumns` | Union of `ITableColumnsBase` with specialized image and money column variants. | +| `IColumnFilterConfig` | Column filter: `true` (text), `string` (custom field), `{ options }` (select), `{ range }` (date range). | +| `IFilterOption` | Select filter option: `{ value, label }`. | + +### Assets + +| Type | Description | +| ------------------ | ------------------------------------------------------------------------------------------ | +| `ICommonAsset` | Asset record: `url`, `relativeUrl`, `title`, `name`, `size`, `sortOrder`, `typeId`, dates. | +| `AssetsHandler<T>` | Asset operations: `upload()`, `edit()`, `remove()`, `loading` ref, `noRemoveConfirmation`. | + +### Service Abstractions (`services.ts`) + +| Type | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------- | +| `ServiceLifecycle<T>` | Service create/provide/cleanup lifecycle. | +| `PreregistrationQueue<T>` | Queue for items registered before a service initializes: `register()`, `flush()`, `clear()`. | +| `RegistryService<TKey, TItem>` | Generic registry: `register()`, `unregister()`, `get()`, `has()`, `getAll()`, `clear()`. | +| `ListService<T>` | Reactive list: `items` ref, `add()`, `remove()`, `find()`, `filter()`. | +| `OrderedListService<T>` | Extends `ListService` with `reorder()` and `getSorted()`. | +| `ObservableService<T>` | Subscribe/getValue pattern for change observation. | +| `ServiceResult<T>` | Async operation result: `success`, `data?`, `error?` with code/message/details. | +| `WidgetRegistration` | Widget entry: `id`, `component`, `props`, `order`, `isVisible`. | +| `MenuItemRegistration` | Menu item entry: `id`, `title`, `icon`, `priority`, `permissions`, `routeId`, `group`, `children`. | +| `ToolbarItemRegistration` | Toolbar item entry: `id`, `title`, `icon`, `order`, `disabled`, `clickHandler`, `permissions`. | + +### Other + +| Type | Description | +| --------------------------------- | --------------------------------------------------------------------------------------------- | +| `IBladeDropdownItem` | Blade dropdown option: `id`, `title`, `icon`, `clickHandler`. | +| `IMenuItem<T>` | Generic menu item with optional component slot. | +| `NotificationTemplateConstructor` | Component constructor with a `notifyType` static field. | +| `IActionBuilderResult<T>` | Row action definition: `icon`, `title`, `type` (danger/success/warning/info), `clickHandler`. | +| `RequestPasswordResult` | Password reset result: `succeeded`, `error`, `errorCode`. | + +## Usage Examples + +### Defining table columns + +```typescript +import type { ITableColumns } from "@vc-shell/framework"; + +const columns: ITableColumns[] = [ + { + id: "name", + title: "Product Name", + sortable: true, + type: "text", + }, + { + id: "price", + title: "Price", + type: "money", + sortable: true, + width: 120, + }, + { + id: "image", + title: "Image", + type: "image", + width: 80, + }, + { + id: "status", + title: "Status", + type: "status", + width: 100, + filter: { + options: [ + { value: "active", label: "Active" }, + { value: "draft", label: "Draft" }, + { value: "archived", label: "Archived" }, + ], + }, + }, + { + id: "createdDate", + title: "Created", + type: "date-time", + sortable: true, + width: 150, + }, +]; +``` + +### Configuring toolbar buttons + +```typescript +import type { IBladeToolbar } from "@vc-shell/framework"; + +const toolbarItems: IBladeToolbar[] = [ + { + id: "save", + title: "Save", + icon: "lucide-save", + clickHandler: async () => await saveProduct(), + permissions: "product:update", + }, + { + id: "delete", + title: "Delete", + icon: "lucide-trash", + clickHandler: () => confirmDelete(), + permissions: ["product:delete", "product:manage"], + isVisible: computed(() => !isNewProduct.value), + }, +]; +``` + +### Registering menu items + +```typescript +import type { MenuItemConfig } from "@vc-shell/framework"; + +const menuConfig: MenuItemConfig = { + title: "Orders", + icon: "lucide-shopping-cart", + priority: 10, + permissions: ["order:read"], + group: "Commerce", + badge: { + content: computed(() => pendingOrderCount.value), + variant: "warning", + }, +}; +``` + +## Tip: ITableColumnsBase type field + +The `type` field in `ITableColumnsBase` uses `"date-time"` (with hyphen), but the VcColumn component uses `"datetime"` (no hyphen). The VcTableAdapter handles this mapping automatically. If you use VcDataTable directly with VcColumn slot syntax, use `"datetime"`: + +```vue +<!-- VcColumn uses "datetime" --> +<VcColumn id="created" title="Created" type="datetime" /> + +<!-- ITableColumnsBase uses "date-time" --> +<!-- { id: "created", title: "Created", type: "date-time" } --> +``` + +## Related + +- `framework/ui/types/` -- UI-specific types (form fields, breadcrumbs) +- `framework/injection-keys.ts` -- Injection keys for framework services +- `framework/core/services/` -- Service implementations consuming these interfaces diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-ui.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-ui.md new file mode 100644 index 0000000000..434112f919 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/types-ui.md @@ -0,0 +1,181 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: ui/types/ui-types.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# UI Types + +TypeScript interfaces for UI component props shared across all form field components in the framework. + +## Overview + +Every form field component in the vc-shell framework -- whether it is a simple checkbox, a date picker, or a rich text editor -- needs a consistent set of base properties: labels, error states, disabled flags, and so on. These shared prop interfaces ensure that all form components behave uniformly and that consuming code can treat them polymorphically. + +The types are organized in two layers: + +- **`IFormFieldProps`** -- the minimal contract every form field implements (label, error, disabled, required) +- **`ITextFieldProps`** -- extends `IFormFieldProps` with text-input-specific features (placeholder, hint, clearable, loading, size) + +When building custom form field components, extending these interfaces ensures compatibility with the framework's form layout system, validation display, and accessibility patterns. + +**Files:** `index.ts`, `form-field.ts` + +## Interfaces + +### `IFormFieldProps` + +Base props shared by all form field components (VcCheckbox, VcSwitch, VcRadioButton, VcInput, VcTextarea, VcSelect, VcDatePicker, VcEditor, VcFileUpload, VcColorInput, etc.). + +| Prop | Type | Description | +| -------------- | ---------- | ------------------------------------------------------ | +| `label` | `string?` | Field label text | +| `tooltip` | `string?` | Tooltip shown on label hover | +| `disabled` | `boolean?` | Whether the field is disabled | +| `required` | `boolean?` | Whether the field is required | +| `name` | `string?` | Form field name attribute | +| `error` | `boolean?` | External error flag | +| `errorMessage` | `string?` | Error message text (also sets error state when truthy) | + +### `ITextFieldProps` + +Extended props for text-input-like components (VcInput, VcTextarea, VcSelect, VcDatePicker, VcColorInput). Extends `IFormFieldProps`. + +| Prop | Type | Description | +| ----------------- | ----------------------- | -------------------------------------------- | +| `placeholder` | `string?` | Placeholder text | +| `hint` | `string?` | Hint text shown below the field | +| `clearable` | `boolean?` | Show clear button | +| `loading` | `boolean?` | Show loading indicator | +| `autofocus` | `boolean?` | Auto-focus on mount | +| `size` | `"default" \| "small"?` | Field size variant | +| `multilanguage` | `boolean?` | Whether multilanguage mode is active | +| `currentLanguage` | `string?` | Current language code for multilanguage mode | + +### `Breadcrumbs` + +Breadcrumb navigation item used by blade headers. + +| Prop | Type | Description | +| -------------- | -------------------------------------------------------------- | ------------------------------ | +| `id` | `string` | Unique breadcrumb identifier | +| `title` | `MaybeRef<string \| undefined>` | Display text (can be reactive) | +| `icon` | `string?` | Icon identifier | +| `clickHandler` | `(id: string) => void \| boolean \| Promise<void \| boolean>?` | Navigation handler | + +## Usage Examples + +### Extending for a custom input component + +```typescript +import type { ITextFieldProps } from "@vc-shell/framework"; + +// Extend for a custom input with prefix/suffix support +interface IMyFieldProps extends ITextFieldProps { + prefix?: string; + suffix?: string; + inputMode?: "text" | "numeric" | "decimal" | "tel" | "email" | "url"; +} +``` + +### Using in a component definition + +```vue +<script setup lang="ts"> +import type { IFormFieldProps } from "@vc-shell/framework"; + +interface IMyToggleProps extends IFormFieldProps { + modelValue?: boolean; + onLabel?: string; + offLabel?: string; +} + +const props = withDefaults(defineProps<IMyToggleProps>(), { + modelValue: false, +}); + +const emit = defineEmits<{ + "update:modelValue": [value: boolean]; +}>(); +</script> + +<template> + <div + class="my-toggle" + :class="{ 'my-toggle--error': error || !!errorMessage }" + > + <VcLabel + v-if="label" + :tooltip="tooltip" + :required="required" + > + {{ label }} + </VcLabel> + <button + :disabled="disabled" + :aria-checked="modelValue" + role="switch" + @click="emit('update:modelValue', !modelValue)" + > + {{ modelValue ? (onLabel ?? "On") : (offLabel ?? "Off") }} + </button> + <span + v-if="errorMessage" + class="my-toggle__error" + >{{ errorMessage }}</span + > + </div> +</template> +``` + +### Typing a generic form field renderer + +```typescript +import type { IFormFieldProps, ITextFieldProps } from "@vc-shell/framework"; + +// A utility type for dynamic form generation +interface FormFieldDefinition { + component: string; // "VcInput" | "VcSelect" | "VcCheckbox" etc. + props: IFormFieldProps | ITextFieldProps; + modelKey: string; +} + +function renderFormFields(fields: FormFieldDefinition[]) { + // Dynamically render fields with consistent prop contracts +} +``` + +### Using Breadcrumbs type + +```typescript +import type { Breadcrumbs } from "@vc-shell/framework"; +import { computed } from "vue"; + +const crumb: Breadcrumbs = { + id: "order-123", + title: computed(() => `Order #${orderNumber.value}`), + icon: "lucide-shopping-cart", + clickHandler: async (id) => { + await navigateToOrder(id); + // Return false to prevent automatic trail trimming + return false; + }, +}; +``` + +## Tip: Error State Priority + +Both `error` (boolean) and `errorMessage` (string) can set error state. When both are provided, the component shows the error message. When only `error` is `true` without a message, the field highlights in red but shows no text. Prefer using `errorMessage` alone -- the error styling is applied automatically when the message is truthy: + +```vue +<!-- Preferred: errorMessage alone handles both styling and text --> +<VcInput :error-message="errors.name" label="Name" /> + +<!-- Also works but redundant: error flag is implied by errorMessage --> +<VcInput :error="!!errors.name" :error-message="errors.name" label="Name" /> +``` + +## Related + +- `framework/core/types/` -- Core types (validation rules, table columns, menus) +- `framework/ui/components/atoms/` -- Atom components implementing these props +- `framework/ui/components/molecules/` -- Molecule components extending these props diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/utilities-overview.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/utilities-overview.md new file mode 100644 index 0000000000..341b108f12 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/api/utilities-overview.md @@ -0,0 +1,187 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: core/utilities/utilities.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Framework Utilities + +Utility functions exported from `@vc-shell/framework` via `core/utilities/index.ts`. + +## Overview + +The utilities module provides a collection of commonly needed functions: string case conversion, date formatting, error parsing, ID generation, and structured logging. These are pure utility functions with no Vue reactivity dependencies (except the logger, which is a simple factory). All are re-exported from `@vc-shell/framework` for convenient access. + +## String Utilities + +| Function | Signature | Description | +| --------------- | ------------------------- | ----------------------------------------------------------------- | +| `camelToSnake` | `(str: string) => string` | Converts camelCase to snake_case | +| `camelize` | `(str: string) => string` | Converts delimited string to camelCase (splits on non-word chars) | +| `kebabToCamel` | `(str: string) => string` | Converts kebab-case to camelCase | +| `kebabToPascal` | `(str: string) => string` | Converts kebab-case to PascalCase | + +### String utility examples + +```typescript +import { camelToSnake, camelize, kebabToCamel, kebabToPascal } from "@vc-shell/framework"; + +camelToSnake("myPropName"); // "my_prop_name" +camelToSnake("backgroundColor"); // "background_color" + +camelize("some-prop-name"); // "somePropName" +camelize("SOME_CONSTANT"); // "sOMECONSTANT" (splits on non-word chars) + +kebabToCamel("vc-data-table"); // "vcDataTable" +kebabToCamel("my-component-name"); // "myComponentName" + +kebabToPascal("vc-data-table"); // "VcDataTable" +kebabToPascal("dashboard-widget"); // "DashboardWidget" +``` + +## Date Utilities + +Located in `date/`. Uses `date-fns` internally with lazy locale loading. + +| Function | Signature | Description | +| ----------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| `formatDateRelative` | `(value: DateInput, localeCode?: string) => string` | Formats date as relative time (e.g. "3 hours ago") via `formatDistanceToNow` | +| `formatDateWithPattern` | `(value: DateInput, momentFormatStr: string, localeCode?: string) => string` | Formats date using a Moment.js-style format string, auto-converted to date-fns tokens | +| `convertMomentFormat` | `(momentFormat: string) => string` | Converts a Moment.js format string to date-fns format (e.g. `YYYY` to `yyyy`, `DD` to `dd`) | +| `resolveLocale` | `(localeCode: string) => Promise<Locale>` | Async-loads a date-fns locale by code, with fallback to base language then `enUS` | +| `resolveLocaleSync` | `(localeCode: string) => Locale` | Returns cached locale synchronously; triggers async load if missing, returns `enUS` as fallback | + +`DateInput` is `string | number | Date | null | undefined`. + +### Date utility examples + +```typescript +import { formatDateRelative, formatDateWithPattern, convertMomentFormat } from "@vc-shell/framework"; + +// Relative time +formatDateRelative("2024-01-15"); // "about 2 years ago" +formatDateRelative(new Date(Date.now() - 3600000)); // "about 1 hour ago" +formatDateRelative("2024-01-15", "de"); // "vor etwa 2 Jahren" + +// Formatted dates using Moment.js-style patterns (auto-converted to date-fns) +formatDateWithPattern("2024-01-15", "LL"); // "January 15, 2024" +formatDateWithPattern("2024-06-01", "DD/MM/YYYY"); // "01/06/2024" +formatDateWithPattern("2024-01-15", "LL", "de"); // "15. Januar 2024" + +// Format conversion +convertMomentFormat("YYYY-MM-DD"); // "yyyy-MM-dd" +convertMomentFormat("DD/MM/YYYY"); // "dd/MM/yyyy" +convertMomentFormat("hh:mm A"); // "hh:mm a" +``` + +## Error Utilities + +### Display errors (`error.ts`) + +| Export | Signature | Description | +| ------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------- | +| `DisplayableError` | `class extends Error` | Normalized error with `details: string` and `originalError: unknown` properties | +| `parseError` | `(errorToParse: unknown) => DisplayableError` | Parses any error type (Axios, plain object, string, JSON) into a `DisplayableError` | + +### Typed framework errors (`errorTypes.ts`) + +| Class | Code | Constructor | +| ------------------- | -------------------- | --------------------------------------------------------- | +| `FrameworkError` | custom | `(message, code, context?)` -- base class with `toJSON()` | +| `ValidationError` | `VALIDATION_ERROR` | `(message, context?)` | +| `ServiceError` | `SERVICE_ERROR` | `(message, context?)` | +| `InjectionError` | `INJECTION_ERROR` | `(serviceName, context?)` | +| `RegistrationError` | `REGISTRATION_ERROR` | `(componentName, reason, context?)` | +| `BladeError` | `BLADE_ERROR` | `(message, bladeId?, context?)` | +| `ModuleLoadError` | `MODULE_LOAD_ERROR` | `(moduleId, reason, context?)` | + +| Function | Signature | Description | +| ------------------ | --------------------------------------------------- | ----------------------------------------------------------------- | +| `isFrameworkError` | `(error: unknown) => error is FrameworkError` | Type guard for `FrameworkError` instances | +| `wrapError` | `(error: unknown, code?: string) => FrameworkError` | Wraps any error into a `FrameworkError`, preserving existing ones | + +### Error utility examples + +```typescript +import { parseError, isFrameworkError, InjectionError } from "@vc-shell/framework"; + +try { + await apiClient.save(data); +} catch (err) { + const parsed = parseError(err); + console.log(parsed.message); // "Request failed with status 422" + console.log(parsed.details); // "Validation error: name is required" +} + +if (isFrameworkError(err)) { + console.log(err.code); // e.g. "INJECTION_ERROR" +} + +throw new InjectionError("WidgetService"); // "WidgetService is not provided. ..." +``` + +## ID Generation + +| Function | Signature | Description | +| ------------ | -------------- | --------------------------------------------------------------------------------- | +| `generateId` | `() => string` | Returns a random 7-character alphanumeric string via `Math.random().toString(36)` | + +```typescript +import { generateId } from "@vc-shell/framework"; + +const id = generateId(); // e.g. "k3x9f2a" +const widgetId = `widget-${generateId()}`; // e.g. "widget-m7p2x1b" +``` + +## Logger + +Factory-based logger with level filtering. Default level: `debug` in dev, `warn` in production. + +| Export | Type | Description | +| -------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| `createLogger` | `(context?: string) => Logger` | Creates a logger instance with `debug`, `info`, `warn`, `error`, `child`, `setLevel`, `setEnabled` methods | +| `logger` | `Logger` | Default logger instance (no context prefix) | +| `loggers` | `Record<string, Logger>` | Pre-configured loggers: `core`, `ui`, `shared`, `plugins`, `services`, `composables` | +| `LogLevel` | `type` | `"debug" \| "info" \| "warn" \| "error" \| "none"` | + +### Logger examples + +```typescript +import { createLogger, loggers } from "@vc-shell/framework"; + +const log = createLogger("OrdersModule"); +log.info("Module initialized"); // [OrdersModule] Module initialized +log.error("Failed to load orders", error); // [OrdersModule] Failed to load orders Error: ... + +const subLog = log.child("DataSync"); +subLog.debug("Syncing 50 records"); // [OrdersModule:DataSync] Syncing 50 records + +log.setLevel("error"); // Only errors will be logged +``` + +## Tip: Use createLogger Instead of console.log + +Framework loggers include context prefixes, respect log level settings, and can be disabled per-module. Using raw `console.log` bypasses these controls: + +```typescript +// Bad: no context, no level control +console.log("Order saved"); + +// Good: structured, filterable, respects log level +const log = createLogger("OrdersModule"); +log.info("Order saved", { orderId: order.id }); +``` + +## Common Mistake + +The `convertMomentFormat` function maps common Moment.js tokens to date-fns tokens, but does not cover every edge case. Uncommon tokens (like `X` for Unix timestamp) may need manual handling: + +```typescript +convertMomentFormat("YYYY-MM-DD"); // "yyyy-MM-dd" (correct) +convertMomentFormat("X"); // May not convert as expected +``` + +## Related + +- `framework/core/plugins/global-error-handler/` -- uses `parseError()` for global error catching +- `framework/core/plugins/i18n/` -- date formatting respects the active locale +- `framework/core/constants/` -- `UI_CONSTANTS.DEBOUNCE_DEFAULT_MS` for standard delays diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/.pages new file mode 100644 index 0000000000..572380abbc --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/.pages @@ -0,0 +1,4 @@ +title: CLI +nav: + - API Client Generator: api-client-generator.md + - create-vc-app: create-vc-app.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/api-client-generator.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/api-client-generator.md new file mode 100644 index 0000000000..09ad559aff --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/api-client-generator.md @@ -0,0 +1,3 @@ +# API Client Generator + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md new file mode 100644 index 0000000000..a8a77159c9 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/cli/create-vc-app.md @@ -0,0 +1,3 @@ +# create-vc-app + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/migration/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/migration/index.md new file mode 100644 index 0000000000..99b0da5222 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/migration/index.md @@ -0,0 +1,3 @@ +# Migration + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/.pages new file mode 100644 index 0000000000..e4d870299c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/.pages @@ -0,0 +1,6 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Modules +nav: + - Assets Manager: assets-manager.md + - Assets Module: assets.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets-manager.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets-manager.md new file mode 100644 index 0000000000..0ca81da97c --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets-manager.md @@ -0,0 +1,166 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: modules/assets-manager/assets-manager.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Assets Manager Module + +A built-in blade module for managing file assets (images, documents, archives). Provides upload, delete, reorder, and preview functionality via a table-based UI. + +## Overview + +The Assets Manager is registered as an app module via `defineAppModule` and opened as a child blade from any parent blade that needs asset management. The parent creates a `useAssetsManager` instance and passes it through `options.manager` -- the module handles the UI and delegates data mutations through the manager. + +## Module Registration + +```typescript +import { AssetsManagerModule } from "@vc-shell/framework"; + +// Registered automatically when the framework loads +// Exposes: AssetsManager blade component +``` + +The module exports `AssetsManagerModule` (a Vue plugin) and the `AssetsManager` component, which is declared as a global component. + +## Options (via `useBlade`) + +The blade reads its configuration from `options` via `useBlade<AssetsManagerOptions>()` (not props): + +| Option | Type | Description | +| -------------- | ------------------------ | ---------------------------------------------------------------------------------------- | +| `title` | `string?` | Custom blade title (defaults to i18n `ASSETS_MANAGER.TITLE`) | +| `manager` | `UseAssetsManagerReturn` | The asset manager instance from `useAssetsManager()`. **Must be wrapped in `markRaw()`** | +| `disabled` | `boolean?` | When true, hides upload/delete actions and disables reordering | +| `hiddenFields` | `string[]?` | Fields to hide in the detail view | + +> **Breaking change:** The old options (`assets`, `loading`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`) have been removed. Pass a single `manager` instance instead. See [migration guide #32](../../../migration/32-use-assets-manager.md). + +## Usage + +The canonical pattern is to bind the manager to a writable `computed` over a field of the parent entity, so that uploads/removes/reorders propagate back into the form. `confirmRemove` is wired to the framework's popup service rather than `window.confirm`. + +```typescript +import { computed, markRaw } from "vue"; +import { useBlade, useAssetsManager, usePopup } from "@vc-shell/framework"; + +const { openBlade } = useBlade(); +const { showConfirmation } = usePopup(); + +// Two-way binding: the manager mutates `productAssets.value`, which writes +// straight back to `item.value.productData.assets`. +const productAssets = computed({ + get: () => item.value?.productData?.assets ?? [], + set: (val) => { + if (item.value?.productData) item.value.productData.assets = val; + }, +}); + +const assetsManager = useAssetsManager(productAssets, { + uploadPath: () => `/catalog/${item.value?.id}`, + confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"), +}); + +openBlade({ + name: "AssetsManager", + options: { + // IMPORTANT: markRaw prevents Vue from wrapping the manager in a + // deep reactive proxy. Without it, blade options (stored in + // ref<BladeDescriptor[]>) auto-unwrap nested Refs, breaking + // manager.items.value and manager.loading.value access. + manager: markRaw(assetsManager), + disabled: !canEdit.value, + }, +}); +``` + +## Features + +- **Table view**: Displays assets with thumbnail, name, size, sort order, and creation date columns using `VcDataTable` with declarative `<VcColumn>` API. +- **Upload**: Via toolbar button or drag-and-drop onto the table. Handles duplicate filenames by appending `_1`, `_2`, etc. +- **Delete**: Toolbar delete button (requires selection) and per-row action button. +- **Reorder**: Drag-and-drop row reordering when not in readonly mode. +- **Detail view**: Clicking a row opens an `AssetsDetails` child blade for single-asset editing. +- **Non-image assets**: Files without an image extension render a colored badge with the uppercased extension (`PDF`, `DOCX`, `ZIP`, ...) instead of a thumbnail. +- **Empty state**: Shows upload prompt when no assets exist; the empty-state action button opens the file picker. + +## Toolbar + +| Button | Condition | Action | +| ------ | ------------------------------ | ------------------------------------------------ | +| Add | `!disabled` | Opens file picker for upload | +| Delete | `!disabled` and items selected | Calls `manager.removeMany()` with selected items | + +## Tips + +- **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive. +- The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`. +- The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder. +- Asset thumbnails use `isImage()` from `@core/utilities/assets` to decide between an image preview (`VcImage`) and a colored extension badge (`getExtensionColor` + `getExtensionLabel`). +- The module uses `useBlade()` internally to open the detail sub-blade. +- The `manager` instance can be reused as a `useBladeWidgets` badge source — its `items.value.length` updates reactively as uploads/removes happen inside the blade, so a parent widget showing the asset count refreshes without an extra round-trip. + +## Recipes + +### Open from a blade widget + +Most callers don't open `AssetsManager` directly — they expose it as one of the parent blade's widgets. The widget shows the asset count as a live badge and opens the manager on click. The manager is created once per parent blade and reused across openings. + +```typescript +import { computed, markRaw, type Ref, type ComputedRef } from "vue"; +import { useBlade, useBladeWidgets, useAssetsManager, usePopup } from "@vc-shell/framework"; + +interface Entity { + id?: string; + productData?: { assets?: Asset[] }; +} + +export function useEntityWidgets(opts: { item: Ref<Entity | undefined>; disabled: ComputedRef<boolean>; isVisible: ComputedRef<boolean> }) { + const { item, disabled, isVisible } = opts; + const { openBlade } = useBlade(); + const { showConfirmation } = usePopup(); + + const entityAssets = computed({ + get: () => item.value?.productData?.assets ?? [], + set: (val) => { + if (item.value?.productData) item.value.productData.assets = val; + }, + }); + + const assetsManager = useAssetsManager(entityAssets, { + uploadPath: () => `/catalog/${item.value?.id}`, + confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"), + }); + + const assetsCount = computed(() => entityAssets.value.length); + + return useBladeWidgets([ + { + id: "AssetsWidget", + icon: "lucide-file", + title: "WIDGETS.ASSETS", + badge: assetsCount, + isVisible, + onClick: () => + openBlade({ + name: "AssetsManager", + options: { + manager: markRaw(assetsManager), + disabled: disabled.value, + }, + }), + }, + ]); +} +``` + +Key points: + +- `useAssetsManager` is invoked once at widget-setup time, not inside `onClick`. Recreating it per click would lose pending state and break optimistic updates. +- `disabled.value` is unwrapped at click time. Passing the raw `ComputedRef` would work too, but the blade reads `options.value?.disabled` as a plain value. +- `assetsCount` reads from the source array (not from `assetsManager.items`), but both stay in sync because the manager mutates the same array via the setter. + +## Related + +- `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn` +- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel` +- `framework/modules/assets/components/assets-details/` -- `AssetsDetails` child blade opened on row click diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets.md new file mode 100644 index 0000000000..80c7303a90 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/assets.md @@ -0,0 +1,121 @@ +<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY --> +<!-- Source: modules/assets/assets-details.docs.md --> +<!-- To update: edit the source file in vc-shell, then run yarn docs:sync --> + + +# Assets Details Module + +A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing. + +## Overview + +The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means. + +The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`). + +## Module Registration + +```typescript +import { AssetsDetailsModule } from "@vc-shell/framework"; + +// Registered automatically when the framework loads +// Exposes: AssetsDetails blade component +``` + +## Options (via `useBlade`) + +The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props): + +| Option | Type | Description | +| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `asset` | `AssetLike` | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called. | +| `disabled` | `boolean?` | When true, every input is read-only and the toolbar Save/Delete buttons are disabled. | +| `hiddenFields` | `string[]?` | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. | +| `assetEditHandler` | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves. | +| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>` | Called by the toolbar Delete button. The blade closes itself after the handler resolves. | + +## Usage + +### Direct invocation + +```typescript +import { useBlade } from "@vc-shell/framework"; + +const { openBlade } = useBlade(); + +openBlade({ + name: "AssetsDetails", + options: { + asset: selectedAsset, + disabled: !canEdit.value, + hiddenFields: ["altText"], + assetEditHandler: async (edited) => { + await api.updateAsset(edited); + }, + assetRemoveHandler: async (asset) => { + await api.deleteAsset(asset.id); + }, + }, +}); +``` + +### Used by AssetsManager + +When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically: + +```typescript +// inside AssetsManager +openBlade({ + name: "AssetsDetails", + options: { + asset, + disabled: readonly.value, + hiddenFields: options.value?.hiddenFields, + assetEditHandler: (asset) => manager.updateItem(asset), + assetRemoveHandler: (asset) => manager.remove(asset), + }, +}); +``` + +## Header + +The header is always rendered above the editable form and is not configurable through `hiddenFields`: + +| Element | Source | +| ------------ | -------------------------------------------------------------------------------------------------- | +| Preview | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise | +| Size | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB` | +| Created date | `asset.createdDate` rendered with `type="date-ago"` | +| URL | `asset.url` displayed as a copyable link with `asset.name` as the visible label | + +## Form fields + +All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`. + +| Field | Visibility | Notes | +| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `name` | Hidden if `hiddenFields` includes `"name"` | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). | +| `altText` | Image assets only; hide via `"altText"` | Plain string. Shown only when `asset.typeId === "Image"`. | +| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea. | + +## Toolbar + +| Button | Disabled condition | Action | +| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| Save | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()` | +| Delete | `disabled === true` | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` | + +## Tips + +- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`. +- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes. +- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state. +- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness. +- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness. + +## Related + +- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click +- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition +- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel` +- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/index.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/index.md new file mode 100644 index 0000000000..f3a3b42dd7 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/reference/modules/index.md @@ -0,0 +1,3 @@ +# Modules + +Content coming soon — see [vc-shell repo](https://github.com/VirtoCommerce/vc-shell) until this section is filled out. diff --git a/platform/developer-guide/mkdocs.yml b/platform/developer-guide/mkdocs.yml index 7af006bb71..17caebb114 100644 --- a/platform/developer-guide/mkdocs.yml +++ b/platform/developer-guide/mkdocs.yml @@ -20,6 +20,7 @@ plugins: /1.1/ /2.0/ /latest/ + - awesome-pages - git-revision-date-localized - minify - include-markdown @@ -88,6 +89,7 @@ extra_css: - assets/stylesheets/main.css - assets/stylesheets/fonts.css - assets/stylesheets/version-selector.css + - assets/stylesheets/vc-shell-docs.css - assets/stylesheets/ai-overrides.css extra_javascript: @@ -916,138 +918,4 @@ nav: - Packaged Business Capabilities (PBCs) and PBCs Max: Updating-Virto-Commerce-Based-Project/pbcs.md - Outdated Strategy: Updating-Virto-Commerce-Based-Project/outdated-strategy.md - Useful Tips: Updating-Virto-Commerce-Based-Project/tips.md - - Custom Apps Development: - - Overview: custom-apps-development/overview.md - - Registering New App: custom-apps-development/how-to-register-new-app.md - - VC-Shell: - - Overview: custom-apps-development/vc-shell/vc-shell-overview.md - - Getting Started: - - Create First Custom App: custom-apps-development/vc-shell/Getting-started/creating-first-custom-app.md - - Blade Generator: custom-apps-development/vc-shell/Getting-started/blade-generator.md - - Guides: - - Application Architecture and Best Practices: custom-apps-development/vc-shell/Guides/application-architecture-best-practices.md - - Building, Deployment and Advanced Topics: custom-apps-development/vc-shell/Guides/building-deployment-advanced-topics.md - - Creating Custom VC-Shell Applications: custom-apps-development/vc-shell/Guides/creating-custom-applications.md - - Core Concepts for VC-Shell Applications: custom-apps-development/vc-shell/Guides/custom-application-core-concepts.md - - Developing Custom VC-Shell Modules: custom-apps-development/vc-shell/Guides/developing-custom-modules.md - - Integrating Framework Features: custom-apps-development/vc-shell/Guides/integrating-framework-features.md - - Internationalization: custom-apps-development/vc-shell/Guides/internationalization.md - - Routing Configuration: custom-apps-development/vc-shell/Guides/routing-configuration.md - - Essentials: - - Navigation: custom-apps-development/vc-shell/Essentials/navigation.md - - Understanding Application Layout: custom-apps-development/vc-shell/Essentials/understanding-application-layout.md - - API Client Integration: custom-apps-development/vc-shell/Essentials/API-Integration/api-client-integration.md - - Composables: - - useApiClient: custom-apps-development/vc-shell/Essentials/composables/useApiClient.md - - useAppBarWidget: custom-apps-development/vc-shell/Essentials/composables/useAppBarWidget.md - - useAppInsights: custom-apps-development/vc-shell/Essentials/composables/useAppInsights.md - - useAsync: custom-apps-development/vc-shell/Essentials/composables/useAsync.md - - useBeforeUnload: custom-apps-development/vc-shell/Essentials/composables/useBeforeUnload.md - - useBreadcrumbs: custom-apps-development/vc-shell/Essentials/composables/useBreadcrumbs.md - - useDashboard: custom-apps-development/vc-shell/Essentials/composables/useDashboard.md - - useDynamicProperties: custom-apps-development/vc-shell/Essentials/composables/useDynamicProperties.md - - useLanguages: custom-apps-development/vc-shell/Essentials/composables/useLanguages.md - - useLoading: custom-apps-development/vc-shell/Essentials/composables/useLoading.md - - useMenuService: custom-apps-development/vc-shell/Essentials/composables/useMenuService.md - - useNotifications: custom-apps-development/vc-shell/Essentials/composables/useNotifications.md - - usePermissions: custom-apps-development/vc-shell/Essentials/composables/usePermissions.md - - useSettings: custom-apps-development/vc-shell/Essentials/composables/useSettings.md - - useSettingsMenu: custom-apps-development/vc-shell/Essentials/composables/useSettingsMenu.md - - useTheme: custom-apps-development/vc-shell/Essentials/composables/useTheme.md - - useToolbar: custom-apps-development/vc-shell/Essentials/composables/useToolbar.md - - useUser: custom-apps-development/vc-shell/Essentials/composables/useUser.md - - useWidgets: custom-apps-development/vc-shell/Essentials/composables/useWidgets.md - - useExternalWidgets: custom-apps-development/vc-shell/Essentials/composables/useExternalWidgets.md - - useTableSort: custom-apps-development/vc-shell/Essentials/composables/useTableSort.md - - useTableSelection: custom-apps-development/vc-shell/Essentials/composables/useTableSelection.md - - useModificationTracker: custom-apps-development/vc-shell/Essentials/composables/useModificationTracker.md - - Usage Guides: - - Overview: custom-apps-development/vc-shell/Essentials/Usage-Guides/overview.md - - Adding App Bar Widgets with useAppBarWidget: custom-apps-development/vc-shell/Essentials/Usage-Guides/adding-app-bar-widgets-with-useappbarwidget.md - - Adding New Languages: custom-apps-development/vc-shell/Essentials/Usage-Guides/adding-new-languages.md - - Building Navigation Menus with useMenuService: custom-apps-development/vc-shell/Essentials/Usage-Guides/building-navigation-menus-with-usemenuservice.md - - Creating and Registering Widgets with useWidgets: custom-apps-development/vc-shell/Essentials/Usage-Guides/creating-and-registering-widgets-with-usewidgets.md - - Creating Interactive Dashboards with useDashboard: custom-apps-development/vc-shell/Essentials/Usage-Guides/creating-interactive-dashboards-with-usedashboard.md - - Customizing Application UI with useSettings: custom-apps-development/vc-shell/Essentials/Usage-Guides/customizing-application-ui-with-usesettings.md - - Customizing Notifications: custom-apps-development/vc-shell/Essentials/Usage-Guides/customizing-notifications.md - - Displaying Toast Notifications: custom-apps-development/vc-shell/Essentials/Usage-Guides/displaying-toast-notifications.md - - Error Handling in VC-Shell: custom-apps-development/vc-shell/Essentials/Usage-Guides/error-handling-in-vc-shell.md - - Implementing form Validation in Blades: custom-apps-development/vc-shell/Essentials/Usage-Guides/implementing-form-validation-in-blades.md - - Implementing Navigational Breadcrumbs with useBreadcrumbs: custom-apps-development/vc-shell/Essentials/Usage-Guides/implementing-navigational-breadcrumbs-with-usebreadcrumbs.md - - Implementing Role-Based Access Control with usePermissions: custom-apps-development/vc-shell/Essentials/Usage-Guides/implementing-role-based-access-control-with-usepermissions.md - - Implementing Telemetry with useAppInsights: custom-apps-development/vc-shell/Essentials/Usage-Guides/implementing-telemetry-with-useappinsights.md - - Integrating Shared Authentication Pages: custom-apps-development/vc-shell/Essentials/Usage-Guides/integrating-shared-authentication-pages.md - - Managing Async Operations with useAsync: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-async-operations-with-useasync.md - - Managing Blade Toolbars with useToolbar: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-blade-toolbars-with-usetoolbar.md - - Managing Dynamic Properties with useDynamicProperties: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-dynamic-properties-with-usedynamicproperties.md - - Managing Loading States with useLoading: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-loading-states-with-useloading.md - - Managing Popups with usePopup and vcPopup: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-popups-with-usepopup-and-vcpopup.md - - Managing Settings Menu with useSettingsMenu: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-settings-menu-with-usesettingsmenu.md - - Managing Themes with useTheme: custom-apps-development/vc-shell/Essentials/Usage-Guides/managing-themes-with-usetheme.md - - Preventing Data Loss with useBeforeUnload: custom-apps-development/vc-shell/Essentials/Usage-Guides/preventing-data-loss-with-usebeforeunload.md - - Understanding Blade Anatomy: custom-apps-development/vc-shell/Essentials/Usage-Guides/understanding-blade-anatomy.md - - Using API Clients with useApiClient: custom-apps-development/vc-shell/Essentials/Usage-Guides/using-api-clients-with-useapiclient.md - - Working with Blade Navigation in VC-Shell: custom-apps-development/vc-shell/Essentials/Usage-Guides/working-with-blade-navigation.md - - Working with Push Notifications Using useNotifications: custom-apps-development/vc-shell/Essentials/Usage-Guides/working-with-push-notifications-using-usenotifications.md - - Plugins: - - i18n: custom-apps-development/vc-shell/Essentials/plugins/i18n.md - - Modularity: custom-apps-development/vc-shell/Essentials/plugins/modularity.md - - Permissions: custom-apps-development/vc-shell/Essentials/plugins/permissions.md - - SignalR: custom-apps-development/vc-shell/Essentials/plugins/signalr.md - - Validation: custom-apps-development/vc-shell/Essentials/plugins/validation.md - - Shared: - - Components: - - Blade Navigation: custom-apps-development/vc-shell/Essentials/shared/components/blade-navigation.md - - Dashboard Widget Card: custom-apps-development/vc-shell/Essentials/shared/components/dashboard-widget-card.md - - Draggable Dashboard: custom-apps-development/vc-shell/Essentials/shared/components/draggable-dashboard.md - - Generic Dropdown: custom-apps-development/vc-shell/Essentials/shared/components/generic-dropdown.md - - Notifications: custom-apps-development/vc-shell/Essentials/shared/components/notifications.md - - Popup Handler: custom-apps-development/vc-shell/Essentials/shared/components/popup-handler.md - - Settings Menu Item: custom-apps-development/vc-shell/Essentials/shared/components/settings-menu-item.md - - Sidebar: custom-apps-development/vc-shell/Essentials/shared/components/sidebar.md - - UI Components: - - VcApp: custom-apps-development/vc-shell/Essentials/ui-components/vc-app.md - - VcBadge: custom-apps-development/vc-shell/Essentials/ui-components/vc-badge.md - - VcBlade: custom-apps-development/vc-shell/Essentials/ui-components/vc-blade.md - - VcBreadcrumbs: custom-apps-development/vc-shell/Essentials/ui-components/vc-breadcrumbs.md - - VcButton: custom-apps-development/vc-shell/Essentials/ui-components/vc-button.md - - VcCheckbox: custom-apps-development/vc-shell/Essentials/ui-components/vc-checkbox.md - - VcContainer: custom-apps-development/vc-shell/Essentials/ui-components/vc-container.md - - VcDynamicProperty: custom-apps-development/vc-shell/Essentials/ui-components/vc-dynamic-property.md - - VcEditor: custom-apps-development/vc-shell/Essentials/ui-components/vc-editor.md - - VcField: custom-apps-development/vc-shell/Essentials/ui-components/vc-field.md - - VcFileUpload: custom-apps-development/vc-shell/Essentials/ui-components/vc-file-upload.md - - VcForm: custom-apps-development/vc-shell/Essentials/ui-components/vc-form.md - - VcGallery: custom-apps-development/vc-shell/Essentials/ui-components/vc-gallery.md - - VcGrid: custom-apps-development/vc-shell/Essentials/ui-components/vc-grid.md - - VcHint: custom-apps-development/vc-shell/Essentials/ui-components/vc-hint.md - - VcIcon: custom-apps-development/vc-shell/Essentials/ui-components/vc-icon.md - - VcImage: custom-apps-development/vc-shell/Essentials/ui-components/vc-image.md - - VcInput: custom-apps-development/vc-shell/Essentials/ui-components/vc-input.md - - VcInputCurrency: custom-apps-development/vc-shell/Essentials/ui-components/vc-input-currency.md - - VcInputDropdown: custom-apps-development/vc-shell/Essentials/ui-components/vc-input-dropdown.md - - VcLabel: custom-apps-development/vc-shell/Essentials/ui-components/vc-label.md - - VcLink: custom-apps-development/vc-shell/Essentials/ui-components/vc-link.md - - VcLoginForm: custom-apps-development/vc-shell/Essentials/ui-components/vc-login-form.md - - VcMultivalue: custom-apps-development/vc-shell/Essentials/ui-components/vc-multivalue.md - - VcPagination: custom-apps-development/vc-shell/Essentials/ui-components/vc-pagination.md - - VcPopup: custom-apps-development/vc-shell/Essentials/ui-components/vc-popup.md - - VcProgress: custom-apps-development/vc-shell/Essentials/ui-components/vc-progress.md - - VcRadioButton: custom-apps-development/vc-shell/Essentials/ui-components/vc-radio-button.md - - VcRating: custom-apps-development/vc-shell/Essentials/ui-components/vc-rating.md - - VcSelect: custom-apps-development/vc-shell/Essentials/ui-components/vc-select.md - - VcSkeleton: custom-apps-development/vc-shell/Essentials/ui-components/vc-skeleton.md - - VcSlider: custom-apps-development/vc-shell/Essentials/ui-components/vc-slider.md - - VcStatus: custom-apps-development/vc-shell/Essentials/ui-components/vc-status.md - - VcStatusIcon: custom-apps-development/vc-shell/Essentials/ui-components/vc-status-icon.md - - VcSwitch: custom-apps-development/vc-shell/Essentials/ui-components/vc-switch.md - - VcTable: custom-apps-development/vc-shell/Essentials/ui-components/vc-table.md - - VcTextarea: custom-apps-development/vc-shell/Essentials/ui-components/vc-textarea.md - - VcToast: custom-apps-development/vc-shell/Essentials/ui-components/vc-toast.md - - VcVideo: custom-apps-development/vc-shell/Essentials/ui-components/vc-video.md - - VcWidget: custom-apps-development/vc-shell/Essentials/ui-components/vc-widget.md - - Extensibility: - - Modularity: custom-apps-development/vc-shell/Extensibility/modularity.md - - How-tos: - - Connecting to Platform: custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md - - Glossary: glossary.md \ No newline at end of file + - ... | regex=^custom-apps-development/.+\.md$
Your content here
This is a simple popup with a title and content.
Are you sure you want to archive 5 items?
This action cannot be undone.
{{ errorMessage }}
+ If the problem persists, contact support. +
The last transaction was declined. Please update your payment method.
About fulfillment
+ Includes priority support and advanced analytics +
Based on 128 reviews
Выбрано: {{ selectedTags.length }} тегов
No products found. Try a different search term.
)` | `[]` | Static array or async function | +| `optionValue` | `string \| ((opt: T) => string)` | `"id"` | Object property used as the value | +| `optionLabel` | `string \| ((opt: T) => string)` | `"title"` | Object property used for display | +| `multiple` | `boolean` | `false` | Multiple selection | +| `searchable` | `boolean` | `false` | Search through options | +| `emitValue` | `boolean` | `true` | `true` = emit the value, `false` = emit the full object | +| `clearable` | `boolean` | `true` | Clear button | +| `debounce` | `number \| string` | `500` | Search delay (ms) | +| `mapOptions` | `boolean` | `true` | Automatically look up label by value in the array | +| `placement` | `string` | `"bottom"` | Dropdown position (Floating UI placements) | +| `size` | `"default" \| "small"` | `"default"` | Field size | +| `outline` | `boolean` | `true` | Show border outline | +| `loading` | `boolean` | `false` | Loading state | +| `label` | `string` | — | Label text | +| `placeholder` | `string` | — | Placeholder | +| `required` | `boolean` | `false` | Required field (asterisk) | +| `disabled` | `boolean` | `false` | Disable the component | +| `error` | `boolean` | `false` | Error state | +| `errorMessage` | `string` | — | Error text | +| `hint` | `string` | — | Hint text below the field | +| `tooltip` | `string` | — | Tooltip next to the label | +| `prefix` | `string` | — | Prefix inside the field | +| `suffix` | `string` | — | Suffix inside the field | +| `multilanguage` | `boolean` | `false` | Multilanguage icon on the label | +| `currentLanguage` | `string` | — | Current language | +| `name` | `string` | `"Field"` | Field name for validation | + +## Events + +| Event | Payload | Description | +| ------------------- | ---------------------------------------- | ---------------------- | +| `update:modelValue` | `T \| T[] \| string \| string[] \| null` | Selected value changed | +| `search` | `string` | Search query changed | +| `close` | — | Dropdown closed | + +## Slots + +| Slot | Scope | Description | +| -------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ | +| `option` | `{ index, opt, selected, toggleOption }` | Custom option rendering. **You must call `toggleOption(opt)` on click.** | +| `selected-item` | `{ index, opt, selected, removeAtIndex }` | Custom rendering of selected chips (multiple) | +| `control` | `{ toggleHandler, isOpened }` | Full trigger replacement | +| `prepend` / `append` | — | Content outside the field | +| `prepend-inner` / `append-inner` | — | Content inside the field | +| `no-options` | — | Shown when there are no options | +| `error` / `hint` | — | Custom rendering of error/hint | + +## CSS Variables + +```css +:root { + --select-height: 36px; + --select-height-small: 28px; + --select-border-radius: 4px; + --select-border-color: var(--neutrals-300); + --select-border-color-focus: var(--primary-100); + --select-border-color-error: var(--danger-500); + --select-text-color: var(--neutrals-800); + --select-padding: 10px; + --select-background-color: var(--additional-50); + --select-background-color-disabled: var(--neutrals-200); + --select-placeholder-color: var(--neutrals-400); + --select-chevron-color: var(--primary-500); + --select-clear-color: var(--primary-500); + --select-dropdown-bg: var(--additional-50); + --select-option-background-color-hover: var(--accent-100); + --select-option-background-color-selected: var(--accent-200); +} +``` + +## Accessibility + +- **Role:** the trigger has `role="combobox"` with `aria-expanded` and `aria-haspopup="listbox"` +- **Listbox:** the dropdown has `role="listbox"` linked via `aria-controls` +- **Label:** connected via `aria-labelledby`; hint/error connected via `aria-describedby` +- **Keyboard:** Arrow Down/Up for navigation, Enter to select, Escape to close, Tab to move focus +- **Multiple:** chip remove buttons are focusable +- **Required:** `aria-required` is passed for screen readers + +## Related Components + +- [VcMultivalue](./vc-multivalue.md) — tags with free-form input (when options are created on the fly) +- [VcInputDropdown](./vc-input-dropdown.md) — text input + dropdown (number + unit of measurement) +- [VcInput](./vc-input.md) — simple text field +- [VcDatePicker](./vc-date-picker.md) — date selection +- [VcField](./vc-field.md) — wrapper with label/error/hint (read-only display) + +## Skeleton / Loading State + +When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed. + +This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor. + + diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md new file mode 100644 index 0000000000..ef90c1c420 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/form/vc-slider.md @@ -0,0 +1,150 @@ + + + + + +# VcSlider + +A content carousel component built on Swiper.js for displaying slides with optional navigation buttons. Renders any content via the default slot. + +
{{ slide.name }}
