@retailcrm/embed-ui-v1-components 0.9.18 → 0.9.21

package/docs/profiles/UiRadio.yml

@@ -2,6 +2,7 @@ component: UiRadio
 summary: >
   UiRadio is the single-choice selection control for exclusive option sets.
   It is the radio-style counterpart to UiCheckbox.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradio--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -36,3 +37,42 @@ geometry:
   layout: inline radio control
   root_display: inline-flex
   width_behavior: content-sized by default
+
+behavior:
+  notes:
+    - Use several UiRadio controls with the same model to represent one exclusive group.
+    - The selected value comes from the option value, not from the label text.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiRadioSwitch
+  patterns:
+    - title: Simple exclusive choice
+      notes: Use UiRadio for compact vertical or inline lists of mutually exclusive values.
+    - title: Rich segmented choice
+      notes: Use UiRadioSwitch instead when the options should look like a segmented control or rich section cards.
+
+ai_notes:
+  do:
+    - Use for plain mutually exclusive options.
+    - Keep all options in one visible group with clear labels.
+  avoid:
+    - Do not use for multiple independent selections; use UiCheckbox or UiToggleGroup.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-radio

package/docs/profiles/UiRadioSwitch.yml

@@ -4,6 +4,7 @@ summary: >
   a compact inline switch and a richer section-card layout. It is useful when the
   choice set is small and always visible. For richer per-option content, compose it
   with UiRadioSwitchOption instead of relying only on the options array.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradioswitch--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -188,38 +189,6 @@ composition:
     - title: Section cards
       notes: Use UiRadioSwitchOption when each choice needs icon, description, or custom checkmark.
 
-examples:
-  - title: Simple options array
-    goal: Build a compact single-choice segmented control.
-    code: |
-      <UiRadioSwitch
-        v-model:value="mode"
-        :options="[
-          { label: 'Auto', value: 'auto' },
-          { label: 'Manual', value: 'manual' },
-        ]"
-      />
-  - title: Rich card options
-    goal: Render section cards with object values and descriptions.
-    code: |
-      <UiRadioSwitch
-        v-model:value="mode"
-        appearance="section"
-        rubber
-        :equal-fn="(a, b) => a?.key === b?.key"
-      >
-        <UiRadioSwitchOption
-          label="Auto"
-          :value="{ key: 'auto' }"
-          description="Automatic mode"
-        />
-
-        <UiRadioSwitchOption
-          label="Manual"
-          :value="{ key: 'manual' }"
-          description="Manual setup"
-        />
-      </UiRadioSwitch>
 
 ai_notes:
   do:

package/docs/profiles/UiRadioSwitchOption.yml

@@ -3,6 +3,7 @@ summary: >
   UiRadioSwitchOption is the declarative option child of UiRadioSwitch. It is the
   richer alternative to the plain options array and is used when one option needs
   custom icon, label, description, or selected-state checkmark content.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiradioswitch--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -99,19 +100,6 @@ composition:
     - title: Rich switch option
       notes: Use when one option needs icon, label, description, and custom selected state.
 
-examples:
-  - title: Section option
-    goal: Define one rich option inside a radio switch.
-    code: |
-      <UiRadioSwitchOption
-        label="Manual"
-        :value="{ key: 'manual' }"
-        description="Manual setup"
-      >
-        <template #icon>
-          <IconStar />
-        </template>
-      </UiRadioSwitchOption>
 
 ai_notes:
   do:
@@ -119,3 +107,11 @@ ai_notes:
     - Prefer label and description props for simple content and slots for richer custom markup.
   avoid:
     - Do not use it as a standalone control outside UiRadioSwitch.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-radio-switch-option

package/docs/profiles/UiScrollBox.yml

@@ -2,6 +2,7 @@ component: UiScrollBox
 summary: >
   UiScrollBox is a scrollable container for constrained content areas. Use it when content
   should remain inside a dedicated scrolling region instead of growing the whole page.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiscrollbox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -29,3 +30,36 @@ geometry:
   layout: scroll container
   root_display: block
   width_behavior: stretches to the size of its layout context
+
+behavior:
+  notes:
+    - Use only when a bounded region should scroll independently.
+    - The parent layout must provide meaningful height or width constraints.
+
+composition:
+  works_well_with:
+    - UiModalWindow
+    - UiModalSidebar
+    - UiTable
+  patterns:
+    - title: Modal body scrolling
+      notes: Use when modal content is long but header and footer should remain accessible.
+    - title: Constrained list
+      notes: Use for long menu or panel content when full page scrolling is undesirable.
+
+ai_notes:
+  do:
+    - Give the surrounding layout a stable height before relying on scrolling.
+  avoid:
+    - Do not wrap normal page content in a scroll container by default.
+
+accessibility:
+  notes:
+    - Keep visible labels and slot content meaningful.
+    - Prefer documented props and slots over custom DOM replacements so host-side accessibility behavior is preserved.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.

package/docs/profiles/UiSelect.yml

@@ -3,6 +3,7 @@ summary: >
   UiSelect is a dropdown component for single-select and multi-select flows. It combines
   a textbox-like trigger with a popper-based option layer. For a correct mental model,
   read it together with UiPopper, UiPopperConnector, and UiPopperTarget.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -271,50 +272,6 @@ composition:
     - title: Popper mental model
       notes: Think of UiSelect as target plus floating dropdown, not as a single inline control.
 
-examples:
-  - title: Standard select in a field
-    goal: Build a labeled select with field semantics.
-    code: |
-      <UiField id="assignee" label="Assignee">
-        <template #default="field">
-          <UiSelect
-            :id="field.id"
-            :invalid="field.invalid"
-            :placeholder="'Select assignee'"
-            v-model:value="assignee"
-          >
-            <UiSelectOption value="kyle" label="Kyle Simmons" />
-            <UiSelectOption value="eduardo" label="Eduardo Henry" />
-          </UiSelect>
-        </template>
-      </UiField>
-  - title: Grouped options
-    goal: Build a grouped option tree through the safe child components.
-    code: |
-      <UiSelect placeholder="Employee">
-        <UiSelectOptionGroup label="Sales">
-          <UiSelectOption value="kyle" label="Kyle Simmons" />
-        </UiSelectOptionGroup>
-
-        <UiSelectOptionGroup label="Support">
-          <UiSelectOption value="philip" label="Philip Williamson" />
-        </UiSelectOptionGroup>
-      </UiSelect>
-  - title: Object values with equalsFn
-    goal: Avoid object comparison by reference.
-    code: |
-      <UiSelect
-        v-model:value="selectedUser"
-        :equals-fn="(left, right) => left?.id === right?.id"
-        placeholder="Employee"
-      >
-        <UiSelectOption
-          v-for="user in users"
-          :key="user.id"
-          :value="user"
-          :label="user.name"
-        />
-      </UiSelect>
 
 ai_notes:
   do:

package/docs/profiles/UiSelectOption.yml

@@ -2,6 +2,7 @@ component: UiSelectOption
 summary: >
   UiSelectOption is the base selectable child of UiSelect. It represents one option node
   in the select option tree.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -42,3 +43,34 @@ geometry:
 ai_notes:
   do:
     - Use as the default child node of UiSelect.
+    - Provide stable value and human-readable label.
+    - Use description for secondary explanation, not for long help text.
+  avoid:
+    - Do not put arbitrary controls inside options.
+
+behavior:
+  notes:
+    - disabled prevents selection while keeping the option visible.
+    - counter and accent help scan dense option lists.
+    - In filterable selects, label and description participate in matching.
+
+composition:
+  works_well_with:
+    - UiSelect
+    - UiSelectOptionGroup
+  patterns:
+    - title: Status filter option
+      notes: Use concise labels that match the visible table status names.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-select-option

package/docs/profiles/UiSelectOptionGroup.yml

@@ -1,6 +1,7 @@
 component: UiSelectOptionGroup
 summary: >
   UiSelectOptionGroup groups related UiSelectOption nodes under a shared label.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiselect--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -36,3 +37,32 @@ geometry:
 ai_notes:
   do:
     - Use to structure large option lists inside UiSelect.
+    - Keep group labels short and categorical.
+  avoid:
+    - Do not use groups for two or three obvious flat options.
+
+behavior:
+  notes:
+    - Group visibility can change when the parent select is filterable.
+    - The group itself is not selectable; child UiSelectOption nodes provide selection.
+
+composition:
+  works_well_with:
+    - UiSelect
+    - UiSelectOption
+  patterns:
+    - title: Large grouped select
+      notes: Use for managers by team, statuses by category, or locations by region.
+
+accessibility:
+  notes:
+    - This component is normally used inside its parent composition; accessibility behavior is completed by the parent component.
+    - Keep labels and visible text meaningful because parent keyboard and screen-reader behavior depends on child content.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-select-option-group

package/docs/profiles/UiSkeleton.yml

@@ -2,6 +2,7 @@ component: UiSkeleton
 summary: >
   UiSkeleton displays a placeholder block for loading content. It supports text,
   rectangle and circle appearances with pulse or shimmer animation.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiskeleton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -39,3 +40,34 @@ ai_notes:
     - Use text appearance for line placeholders.
     - Use circle appearance for avatar placeholders.
     - Override width or height only when the preset size is not enough.
+  avoid:
+    - Do not use for errors or empty states; skeletons mean content is still expected.
+
+behavior:
+  notes:
+    - appearance should approximate the eventual content shape.
+    - animation communicates loading; avoid excessive animated skeletons in dense screens.
+
+composition:
+  works_well_with:
+    - UiAvatar
+    - UiTable
+    - UiLoader
+  patterns:
+    - title: Loading rows
+      notes: Use text or rectangle skeletons where table or list rows will appear.
+    - title: Loading identity
+      notes: Use circle skeletons where avatars will appear.
+
+accessibility:
+  notes:
+    - Keep rendered text concise and meaningful for screen-reader users.
+    - Do not use this component as the only carrier of critical state if the state also needs form-level validation or focus management.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-skeleton

package/docs/profiles/UiSlider.yml

@@ -2,6 +2,7 @@ component: UiSlider
 summary: >
   UiSlider is a range-selection control for single values or ranges on a numeric track.
   It supports single-handle and range-handle modes.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uislider--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -36,3 +37,42 @@ geometry:
   layout: horizontal slider track
   root_display: flex
   width_behavior: stretches to container width by default
+
+behavior:
+  notes:
+    - Use when approximate adjustment is acceptable.
+    - For exact numeric input, prefer UiTextbox with numeric inputmode or UiNumberStepper.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiNumberStepper
+  patterns:
+    - title: Bounded adjustment
+      notes: Wrap in UiField and show min, max, or current value nearby when precision matters.
+    - title: Slider plus exact value
+      notes: Pair with UiNumberStepper when users need both quick dragging and exact entry.
+
+ai_notes:
+  do:
+    - Use only for bounded numeric ranges.
+    - Make the current value visible when the slider affects important settings.
+  avoid:
+    - Do not use for open-ended numbers, money amounts, or identifiers.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-slider

package/docs/profiles/UiSwitch.yml

@@ -2,6 +2,7 @@ component: UiSwitch
 summary: >
   UiSwitch is a compact boolean toggle control. It is the most concise choice for on or off state
   when checkbox semantics would feel visually heavy.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uiswitch--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -35,3 +36,40 @@ geometry:
   layout: inline switch control
   root_display: inline-block
   width_behavior: content-sized by default
+
+behavior:
+  notes:
+    - Best for immediate boolean settings, not for long-form confirmation choices.
+    - Disabled blocks interaction while preserving the current state visually.
+
+composition:
+  works_well_with:
+    - UiField
+  patterns:
+    - title: Settings row
+      notes: Pair with a visible label and optional description so the on or off state is unambiguous.
+  avoid:
+    - Do not use without a nearby label; the switch alone does not explain what will change.
+
+ai_notes:
+  do:
+    - Use for compact feature toggles and enable or disable settings.
+  avoid:
+    - Do not use for multi-select lists or legal acknowledgements; use UiCheckbox.
+
+accessibility:
+  notes:
+    - Prefer visible text labels for interactive controls.
+    - For icon-only or custom visual content, provide an accessible name through the supported label, title, or ARIA attributes exposed by the component.
+    - Preserve native keyboard semantics by using the component root instead of recreating the control with arbitrary markup.
+  keyboard:
+    - Tab moves focus to the control when it is focusable.
+    - Enter or Space activates native button-like controls when the host implementation renders a button.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
+  root_classes:
+    - .ui-v1-switch

package/docs/profiles/UiTab.yml

@@ -3,6 +3,7 @@ summary: >
   UiTab is a declarative child node for UiTabGroup. It does not render meaningful
   standalone UI by itself; instead, UiTabGroup consumes its props and slots to build
   tab buttons, overflow menu items, and optional tab panel content.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitab--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -93,22 +94,6 @@ composition:
     - title: Rich tab declaration
       notes: Keep icon, counter, and content close to the tab declaration inside UiTabGroup.
 
-examples:
-  - title: Rich tab child
-    goal: Declare one tab with custom icon and panel content.
-    code: |
-      <UiTab id="overview" label="Overview" counter="8">
-        <template #icon>
-          <IconStar />
-        </template>
-
-        <template #content>
-          <section>
-            <h4>Overview</h4>
-            <p>Panel content for the active tab.</p>
-          </section>
-        </template>
-      </UiTab>
 
 ai_notes:
   do:
@@ -117,3 +102,9 @@ ai_notes:
   avoid:
     - Do not expect UiTab to render useful DOM outside a group.
     - Do not rely on an undocumented default slot for header rendering.
+
+styling:
+  notes:
+    - Use documented props and slots as the primary styling API.
+    - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.

package/docs/profiles/UiTabGroup.yml

@@ -3,6 +3,7 @@ summary: >
   UiTabGroup is the navigation container for UiTab children or simple tab items.
   It manages active tab selection by string id, keyboard navigation, optional overflow
   into a dropdown menu, and optional tabpanel rendering from the active UiTab content slot.
+usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitab--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -197,36 +198,6 @@ composition:
     - title: Rich tabs from UiTab
       notes: Use UiTab children when tabs need icon, custom label, counter, or tabpanel content.
 
-examples:
-  - title: Data-driven tabs
-    goal: Render a compact tab header from plain items.
-    code: |
-      <UiTabGroup
-        v-model:active-id="activeId"
-        :items="[
-          { id: 'overview', label: 'Overview', counter: '8' },
-          { id: 'orders', label: 'Orders', counter: '12' },
-        ]"
-        overflowing
-      />
-  - title: Tabs with panel content
-    goal: Render active tabpanel content from UiTab child declarations.
-    code: |
-      <UiTabGroup
-        v-model:active-id="activeId"
-        overflowing
-      >
-        <UiTab id="overview" label="Overview">
-          <template #content>
-            <section>
-              <h4>Overview</h4>
-              <p>Visible only when this tab is active.</p>
-            </section>
-          </template>
-        </UiTab>
-
-        <UiTab id="orders" label="Orders" />
-      </UiTabGroup>
 
 ai_notes:
   do: