npm - @vc-shell/vc-app-skill - Versions diffs - 2.0.3 → 2.0.4 - Mend

@vc-shell/vc-app-skill 2.0.3 → 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (155) hide show

package/runtime/knowledge/docs/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md CHANGED Viewed

@@ -1,9 +1,17 @@
+---
+title: VcTooltip
+category: components
+group: feedback
+---
 # 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
+::storybook id="overlay-vctooltip--default"
 ```vue
 <template>
   <VcTooltip>
@@ -55,6 +63,8 @@ The `start` and `end` variants align the tooltip to the beginning or end of the
 ## Variants
+::storybook id="overlay-vctooltip--variants"
 Three visual themes control the tooltip's appearance.
 ```vue
@@ -172,7 +182,8 @@ The `#tooltip` slot accepts any HTML or Vue components, not just text:
 </VcTooltip>
 ```
-> **Caution:** Tooltips should not contain interactive content (buttons, links, inputs). If you need interactive content in a floating panel, use a popover or dropdown component instead.
+!!! 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
@@ -330,3 +341,16 @@ const actions = [
 - [VcHint](../vc-hint/) -- inline hint text below form fields (always visible)
 - [VcLabel](../vc-label/) -- label component with built-in tooltip support via its own `#tooltip` slot
 - [VcIcon](../vc-icon/) -- commonly used as a tooltip trigger for info indicators
+<!-- internal:start -->
+## Architecture notes
+- VcTooltip uses `@floating-ui/vue` (`useFloating`, `autoUpdate`, `flip`, `shift`, `arrow`, `offset` middleware).
+- The tooltip content is teleported to `<body>` via Vue's `<Teleport>` to escape stacking contexts.
+- Show/hide state is managed with a single `isVisible` ref toggled by `mouseenter`/`mouseleave` and `focusin`/`focusout` on the trigger slot wrapper.
+- The delay timer is stored in a `timeoutId` ref and cleared on `mouseleave` to cancel pending show.
+- Arrow positioning is handled by the `arrowEl` template ref passed to the `arrow` middleware; position is applied via `:style` on the arrow element.
+- Source: `framework/ui/components/atoms/vc-tooltip/vc-tooltip.vue`
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-video/vc-video.docs.md CHANGED Viewed

@@ -1,7 +1,15 @@
+---
+title: VcVideo
+category: components
+group: media
+---
 # 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.
+::storybook id="data-display-vcvideo--default"
 ## When to Use
 - Embed product or tutorial videos in blade detail views
@@ -32,6 +40,8 @@ import { VcVideo } from "@vc-shell/framework";
 | `label`   | `string` | --      | Label text displayed above the video               |
 | `tooltip` | `string` | --      | Tooltip text shown on the label's info icon        |
+::storybook id="data-display-vcvideo--with-tooltip" height="400"
 ## Common Patterns
 ### Video with Label and Tooltip
@@ -111,8 +121,23 @@ When `source` is not provided, VcVideo renders a centered film icon placeholder
 - `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](../vc-label/) -- used internally for the label with tooltip
 - [VcIcon](../vc-icon/) -- renders the placeholder film icon
 - [VcRow](../vc-row/) / [VcCol](../vc-col/) -- layout primitives for placing video alongside other content
+<!-- internal:start -->
+## Architecture notes
+- VcVideo lives in `framework/ui/components/atoms/vc-video/`.
+- The component is a thin wrapper around a native `<iframe>` — no custom video controls are implemented.
+- The `sandbox` attribute is hardcoded to `allow-scripts allow-same-origin allow-presentation allow-popups`. Apps that need additional iframe permissions must wrap the component or use a plain `<iframe>`.
+- The label is rendered via `VcLabel` (internal atom) with the `tooltip` prop forwarded as the VcLabel tooltip slot content.
+- Placeholder state (`source` is falsy) swaps the iframe for a `<div>` with `role="img"` containing a `VcIcon` with `lucide-film`.
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/atoms/vc-widget/vc-widget.docs.md CHANGED Viewed

@@ -1,7 +1,15 @@
+---
+title: VcWidget
+category: components
+group: misc
+---
 # 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.
+::storybook id="data-display-vcwidget--default"
 ## When to Use
 - Build widget panels in blade sidebars (e.g., "Orders", "Reviews", "Notifications")
@@ -49,6 +57,8 @@ function openNotifications() {
 | ------- | ------- | ------------------------------------------------------------- |
 | `click` | none    | Fired when the widget is clicked (suppressed when `disabled`) |
+::storybook id="data-display-vcwidget--sidebar-layout" height="350"
 ## Common Patterns
 ### Sidebar Widget Panel
@@ -112,3 +122,15 @@ Badge values above 99 are automatically displayed as "99+".
 - [VcBadge](../vc-badge/) -- used internally for the count badge overlay
 - [VcIcon](../vc-icon/) -- used internally for the widget icon
 - [VcButton](../vc-button/) -- for standard action buttons
+<!-- internal:start -->
+## Architecture notes
+- VcWidget lives in `framework/ui/components/atoms/vc-widget/`.
+- The badge overlay is rendered by embedding `VcBadge` with `isDot`/`content` derived from the `value` prop; values above 99 are truncated to `"99+"` in the component template.
+- `isExpanded` applies `.vc-widget--expanded` modifier; used by the shell sidebar to visually distinguish active navigation state.
+- `horizontal` applies `.vc-widget--horizontal` modifier which switches the internal flex direction from `column` to `row`.
+- The widget registers as a keyboard-interactive element (`role="button"`, Enter/Space handlers) rather than using a `<button>` to allow embedding arbitrary icon components without nesting interactive elements.
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md CHANGED Viewed

@@ -1,3 +1,9 @@
+---
+title: MultilanguageSelector
+category: components
+group: form
+---
 # 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.
@@ -10,6 +16,8 @@ Compact circular flag button that opens a dropdown for selecting a content langu
 ## Basic Usage
+::storybook id="shared-multilanguageselector--interactive"
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
@@ -41,6 +49,8 @@ const languages = [
 Each `LanguageOption` has: `{ value: string; label: string; flag?: string }`.
+::storybook id="shared-multilanguageselector--disabled"
 ## 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:

package/runtime/knowledge/docs/ui/components/molecules/vc-accordion/vc-accordion.docs.md CHANGED Viewed

@@ -1,3 +1,9 @@
+---
+title: VcAccordion
+category: components
+group: data-display
+---
 # VcAccordion
 Collapsible content sections with smooth CSS grid animations, customizable collapsed heights with fade-out preview, and four visual variants. Supports both data-driven rendering via `items` array and slot-based composition with `VcAccordionItem`.
@@ -17,6 +23,8 @@ When NOT to use:
 ## Quick Start
+::storybook id="action-vcaccordion--default"
 ```vue
 <template>
   <VcAccordion
@@ -38,6 +46,9 @@ const faqItems = [
 ## Features
+!!! tip "Use v-model to control initial open state"
+Without `v-model`, no items are expanded on mount. Pass an initial value to pre-open a specific item.
 ### Visual Variants
 Four variants control the visual grouping and spacing of accordion items.
@@ -78,6 +89,8 @@ const items = [
 </script>
 ```
+::storybook id="action-vcaccordion--bordered-variant"
 ### Multiple Open Items
 Set `multiple` to `true` to allow expanding several items simultaneously. The `v-model` value becomes an array.
@@ -86,6 +99,8 @@ Set `multiple` to `true` to allow expanding several items simultaneously. The `v
 <VcAccordion v-model="openItems" :items="items" :multiple="true" />
 ```
+::storybook id="action-vcaccordion--multiple-open"
 ### Partial Content Preview (collapsedHeight)
 When `collapsedHeight` > 0, collapsed items show that many pixels of content with a fade-out gradient. The chevron only appears when content overflows.
@@ -262,6 +277,8 @@ interface AccordionItem {
 - [VcAccordionItem](./_internal/vc-accordion-item/) -- individual accordion panel (used internally and available via the default slot)
+::storybook id="action-vcaccordion--skeleton"
 ## 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.

package/runtime/knowledge/docs/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md CHANGED Viewed

@@ -1,7 +1,18 @@
+---
+title: VcBreadcrumbs
+category: components
+group: navigation
+---
+!!! 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.
+::storybook id="navigation-vcbreadcrumbs--default"
 ## When to Use
 - Showing the user's current position in a blade navigation hierarchy
@@ -51,6 +62,8 @@ interface Breadcrumbs {
 ## Adaptive Overflow
+::storybook id="navigation-vcbreadcrumbs--many-items"
 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.
@@ -64,6 +77,8 @@ The collapse algorithm uses a reverse strategy -- it hides items starting from t
 ## Separated Style
+::storybook id="navigation-vcbreadcrumbs--separated"
 Enable slash separators between items with the `separated` prop:
 ```vue
@@ -275,3 +290,15 @@ clickHandler: () => { navigate(); return true; }
 - [VcDropdown](../vc-dropdown/) -- Used internally to render the overflow menu
 - [VcBreadcrumbsItem](./_internal/vc-breadcrumbs-item/) -- Internal sub-component for individual breadcrumb rendering
 - [VcButton](../../atoms/vc-button/) -- Can be used inside the `trigger` slot for a styled overflow button
+<!-- internal:start -->
+## Architecture Notes
+- Overflow detection uses `useAdaptiveItems` composable with `calculationStrategy: "reverse"` — items are hidden starting from the second item (left side), keeping the last item (current page) always visible.
+- `MORE_BUTTON_WIDTH = 36` and `INITIAL_ITEM_WIDTH = 60` are conservative estimates used in the initial layout pass before DOM measurement.
+- The `VcDropdown` instance for the overflow menu uses `floating` and `placement="bottom-start"`.
+- `VcBreadcrumbsItem` is an internal sub-component in `_internal/vc-breadcrumbs-item/` — not exported from the index.
+- The `useBreadcrumbs` composable lives in `framework/core/composables/useBreadcrumbs/`.
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md CHANGED Viewed

@@ -1,7 +1,18 @@
+---
+title: VcCheckbox
+category: components
+group: form
+---
 # 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).
+::storybook id="form-vccheckbox--basic"
 ## When to Use
 - Single boolean toggle with an inline label (e.g., "I agree to terms")
@@ -69,6 +80,8 @@ const selected = ref<string[]>([]);
 ### Size Variants
+::storybook id="form-vccheckbox--sizes"
 Three sizes are available via the `size` prop:
 | Size   | Value           | Pixel dimension |
@@ -85,6 +98,8 @@ Three sizes are available via the `size` prop:
 ### Indeterminate State (Select All)
+::storybook id="form-vccheckbox--indeterminate"
 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
@@ -355,3 +370,15 @@ const selected = ref<string[]>([]);
 ## 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.
+<!-- internal:start -->
+## Architecture Notes
+- VcCheckbox uses a visually hidden native `<input type="checkbox">` for full keyboard and screen reader support. The custom visual (`vc-checkbox__custom-input`) mirrors its state via CSS sibling selectors (`:checked + .vc-checkbox__custom-input`).
+- Indeterminate state is set imperatively (`checkboxRef.value.indeterminate = val`) since HTML does not support `indeterminate` as an attribute — a watcher syncs the prop to the DOM property.
+- Check/uncheck icons use Vue `<Transition name="vc-checkbox-check">` with `@keyframes` animations for the scale/opacity effect.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-checkbox/vc-checkbox.vue`
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md CHANGED Viewed

@@ -1,7 +1,15 @@
+---
+title: VcCheckboxGroup
+category: components
+group: form
+---
 # VcCheckboxGroup
 Accessible checkbox group that wraps multiple checkboxes in a semantic fieldset with shared label, hint, error state, and layout control.
+::storybook id="form-vccheckboxgroup--default"
 ## When to Use
 - Selecting multiple options from a set (e.g., notification channels, feature flags)
@@ -75,6 +83,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 ### Horizontal Layout
+::storybook id="form-vccheckboxgroup--horizontal"
 ```vue
 <VcCheckboxGroup
   v-model="permissions"
@@ -90,6 +100,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 ### With Disabled Option
+::storybook id="form-vccheckboxgroup--with-disabled-option"
 ```vue
 <VcCheckboxGroup
   v-model="selected"
@@ -135,3 +147,14 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 ## 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.
+<!-- internal:start -->
+## Architecture Notes
+- VcCheckboxGroup delegates rendering to `VcInputGroup` (semantic fieldset wrapper) and renders `VcCheckbox` items from the `options` array, or passes through the default slot for custom layouts.
+- The group generates a unique `name` attribute via `useId()` when none is provided, ensuring native radio group behavior.
+- `normalizedModelValue` guards against non-array `modelValue` to avoid runtime errors when the parent passes `undefined`.
+- Source file: `framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.vue`
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-color-input/vc-color-input.docs.md CHANGED Viewed

@@ -1,7 +1,18 @@
+---
+title: VcColorInput
+category: components
+group: form
+---
+!!! 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.
+::storybook id="form-vccolorinput--default"
 ## 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 `<input type="color">` provides a color picker but lacks text entry, validation, and consistent styling.
@@ -53,6 +64,8 @@ const color = ref<string | null>(null);
 ### With Validation
+::storybook id="form-vccolorinput--with-error"
 ```vue
 <template>
   <VcColorInput
@@ -198,3 +211,14 @@ The native color picker does not support alpha/transparency. If you need RGBA co
 ## 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.
+<!-- internal:start -->
+## Architecture Notes
+- The swatch button is a native `<button type="button">` that triggers a hidden `<input type="color">` via programmatic `.click()`. The native color picker is not visible — only the swatch button is.
+- Color synchronization: typing in the text field updates `modelValue` directly; selecting from the native picker emits the new hex value and also updates the text field.
+- The component does NOT validate hex format — any string is accepted as-is and the swatch will display whatever color the browser interprets.
+- Source file: `framework/ui/components/molecules/vc-color-input/vc-color-input.vue`
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md CHANGED Viewed

@@ -1,7 +1,18 @@
+---
+title: VcDatePicker
+category: components
+group: form
+---
+!!! 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.
+::storybook id="form-vcdatepicker--default"
 ## When to Use
 - Selecting a single date value (e.g., delivery date, publication date)
@@ -39,6 +50,8 @@ const date = ref<Date | null>(null);
 ### Date vs. DateTime Mode
+::storybook id="form-vcdatepicker--date-time"
 The `type` prop controls whether the picker shows a date-only calendar or includes an inline time picker.
 ```vue
@@ -130,6 +143,8 @@ const form = reactive({
 ### States
+::storybook id="form-vcdatepicker--with-error"
 ```vue
 <!-- Required -->
 <VcDatePicker v-model="date" label="Due date" required />
@@ -345,3 +360,15 @@ Uses the same `--input-*` variables as VcInput for consistent styling across all
 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.
+<!-- internal:start -->
+## Architecture Notes
+- Wraps the third-party `VueDatePicker` component. The underlying library is `@vuepic/vue-datepicker`.
+- 12h/24h auto-detection uses the `Intl.DateTimeFormat` API with a sentinel date (midnight on 2023-01-01) to check if the locale's time representation contains "AM" or "PM".
+- The `datePickerOptions` prop is spread onto `<VueDatePicker>` via `v-bind`. Props explicitly set on `VcDatePicker` take precedence over `datePickerOptions` entries of the same name.
+- The `maxDate` for date-only mode is capped at `9999-12-31` to prevent the underlying library from crashing on out-of-range dates.
+- Source file: `framework/ui/components/molecules/vc-date-picker/vc-date-picker.vue`
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md CHANGED Viewed

@@ -1,3 +1,12 @@
+---
+title: VcDropdown
+category: components
+group: navigation
+---
+!!! 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.
@@ -17,6 +26,8 @@ When NOT to use:
 ## Quick Start
+::storybook id="overlay-vcdropdown--action-menu"
 ```vue
 <template>
   <VcDropdown
@@ -97,6 +108,8 @@ Build rich action menus by customizing the `#item` slot with icons, labels, and
 ### Listbox Mode (Selection Switcher)
+::storybook id="overlay-vcdropdown--workspace-switcher"
 Use `role="listbox"` for option-selection patterns. Combine with `isItemActive` to highlight the current selection and `aria-selected` is set automatically.
 ```vue
@@ -369,3 +382,17 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 - [VcDropdownPanel](../vc-dropdown-panel/) -- floating panel with header, footer, and scrollable content
 - [VcSelect](../vc-select/) -- form field dropdown for selecting values with label and validation
 - [VcMenu](../vc-menu/) -- sidebar navigation menu
+<!-- internal:start -->
+## Architecture Notes
+- `VcDropdown` is a generic component (`generic="T"`). TypeScript infers `T` from the `items` prop, giving type-safe `item-click` payloads and slot props.
+- Floating positioning uses `useFloatingPosition` (a thin wrapper around `@floating-ui/vue`) with `autoUpdate: true` when `floating` is enabled — the panel recalculates its position on scroll/resize.
+- Teleport target is determined by `useTeleportTarget`. When `floating` is `true`, the panel is teleported to avoid z-index stacking context issues.
+- Keyboard navigation (`ArrowDown`, `ArrowUp`, `Home`, `End`, `Enter`/`Space`, `Escape`) is handled in `onPanelKeydown`. Escape also attaches a document-level listener when the dropdown is open to catch events that bubble past the panel.
+- `syncFocusedIndex` is called on open to pre-focus the active item (via `isItemActive`) or the first item.
+- The `VcDropdownItem` internal sub-component (in `_internal/VcDropdownItem.vue`) is used by `VcBreadcrumbs` for its overflow menu items.
+- Default `zIndex` is `9300` (matches the CSS custom property `--z-critical-dropdown`).
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md CHANGED Viewed

@@ -1,7 +1,15 @@
+---
+title: VcDropdownPanel
+category: components
+group: navigation
+---
 # VcDropdownPanel
 Floating dropdown panel positioned relative to an anchor element, with header, scrollable content, and optional footer. Built on `@floating-ui/vue`.
+::storybook id="overlay-vcdropdownpanel--default"
 ## When to Use
 - Rich dropdown content with a title bar and action buttons (e.g., filter panels, settings popovers)
@@ -70,6 +78,8 @@ const open = ref(false);
 ## Common Patterns
+::storybook id="overlay-vcdropdownpanel--with-footer"
 ### Filter Panel with Footer Actions
 ```vue
@@ -142,3 +152,15 @@ const open = ref(false);
 - [VcDropdown](../vc-dropdown/) — headless dropdown for simple item lists
 - [VcSelect](../vc-select/) — form field selection dropdown
+<!-- internal:start -->
+## Architecture Notes
+- Click-outside detection uses a `pointerdown` listener on `document` rather than a backdrop overlay. This ensures clicks on high-z-index siblings (sidebar, other teleported panels) are still caught.
+- `panelAnchorRegistry` (`panel-anchor-registry.ts`) is a `WeakMap<Element, HTMLElement | null>` that maps each open panel's DOM element to its anchor. This is used to distinguish child panels (whose anchor lives inside this panel) from sibling/parent panels when deciding whether to close on outside click.
+- Nested VcSelect dropdowns teleported to `<body>` are exempt from click-outside via an ARIA `aria-controls` check: if the clicked `.vc-select__dropdown` has an `id` that matches an `aria-controls` attribute inside this panel, the close is suppressed.
+- The panel exposes a `close()` method via `defineExpose` for use with template refs.
+- `useTeleportTarget` resolves the teleport destination (typically `body`) respecting any custom portal container.
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-editor/vc-editor.docs.md CHANGED Viewed

@@ -1,3 +1,9 @@
+---
+title: VcEditor
+category: components
+group: form
+---
 # 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.
@@ -17,6 +23,8 @@ When NOT to use:
 ## Quick Start
+::storybook id="form-vceditor--default" height="500"
 ```vue
 <template>
   <VcEditor
@@ -50,6 +58,9 @@ The editor header provides four view modes plus a fullscreen toggle:
 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:
@@ -80,6 +91,8 @@ When `assetsFolder` is provided, the image toolbar button becomes functional. Cl
 Multiple images can be selected at once. The upload accepts any image file type (`image/*`).
+::storybook id="form-vceditor--custom-toolbar" height="500"
 ### 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.
@@ -133,6 +146,8 @@ Pass extra TipTap extensions via the `extensions` prop to augment the built-in s
 <VcEditor v-model="content" :extensions="[Highlight.configure({ multicolor: true })]" />
 ```
+::storybook id="form-vceditor--with-custom-buttons" height="500"
 ### Validation with vee-validate Field
 Integrate with vee-validate's `Field` component for form-level validation.
@@ -283,6 +298,8 @@ const content = ref("<h1>Title</h1>");
 - [VcTextarea](../vc-textarea/) -- plain multi-line text input (no formatting)
 - [VcInput](../vc-input/) -- single-line text input
+::storybook id="form-vceditor--skeleton"
 ## 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.

package/runtime/knowledge/docs/ui/components/molecules/vc-field/vc-field.docs.md CHANGED Viewed

@@ -1,3 +1,9 @@
+---
+title: VcField
+category: components
+group: form
+---
 # VcField
 Read-only display component for labeled information, supporting various content types like text, dates, links, and emails.
@@ -18,6 +24,8 @@ The component uses a vertical layout by default (label above value), but support
 ## Basic Usage
+::storybook id="form-vcfield--default"
 ```vue
 <template>
   <VcField
@@ -31,6 +39,9 @@ import { VcField } from "@vc-shell/framework";
 </script>
 ```
+!!! 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                                               |
@@ -91,6 +102,8 @@ Each `type` value renders the content differently:
 </template>
 ```
+::storybook id="form-vcfield--link" height="300"
 ### 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:
@@ -121,6 +134,8 @@ Use horizontal layout for compact key-value displays where the label and value s
 </template>
 ```
+::storybook id="form-vcfield--horizontal"
 ### Copyable ID Fields
 The copy button provides visual feedback (checkmark icon for 1 second) after a successful copy:
@@ -211,6 +226,8 @@ In `orientation="horizontal"` the component reserves the `aspectRatio[0]` track
 - [VcLabel](../../atoms/vc-label/) -- standalone label atom used internally
 - [VcCol](../../atoms/vc-col/) -- column layout atom used for aspect ratio
+::storybook id="form-vcfield--skeleton"
 ## 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.