@retailcrm/embed-ui-v1-components 0.9.19 → 0.9.22-alpha.1

package/docs/profiles/{UiPopperTarget.yml → components/UiPopperTarget.yml}

@@ -83,31 +83,6 @@ composition:
     - title: Not always needed
       notes: Connector-only composition is enough when the trigger already exposes its root element.
 
-examples:
-  - title: Tooltip anchor
-    goal: Anchor a floating layer to a specific title or button wrapper.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget tag="span">
-          <span>Title</span>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Tooltip
-        </UiPopper>
-      </UiPopperConnector>
-  - title: Explicit title-only anchor
-    goal: Bind the floating layer to a title wrapper instead of the whole row.
-    code: |
-      <UiPopperConnector>
-        <UiPopperTarget tag="span">
-          <span class="header-title">Title</span>
-        </UiPopperTarget>
-
-        <UiPopper :visible="open">
-          Tooltip
-        </UiPopper>
-      </UiPopperConnector>
 
 ai_notes:
   do:
@@ -116,3 +91,8 @@ ai_notes:
   avoid:
     - Do not treat the wrapper as decorative only; it affects what the floating layer anchors to.
     - Do not wrap every UiButton or similar trigger with UiPopperTarget if connector already gives the correct anchor.
+
+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.

package/docs/profiles/components/UiRadio.yml

@@ -0,0 +1,91 @@
+component: UiRadio
+summary: >
+  UiRadio is the single-choice selection control for exclusive option sets.
+  It is the radio-style counterpart to UiCheckbox.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiRadio
+
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiRadio id="delivery-courier" v-model:model="deliveryType" value="courier" name="delivery-type" />
+        <label for="delivery-courier">Courier</label>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiRadio } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const deliveryType = ref('courier')
+      </script>
+
+use_when:
+  - You need one selected value from a fixed set.
+
+avoid_when:
+  - You need multiple independent selections, use UiCheckbox instead.
+
+api:
+  key_props:
+    - name: model
+    - name: value
+    - name: required
+    - name: disabled
+  methods:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-radio
+    tag: span
+  notes: One inline wrapper around the visual radio control and label content.
+
+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.
+  root_classes:
+    - .ui-v1-radio

package/docs/profiles/{UiRadioSwitch.yml → components/UiRadioSwitch.yml}

@@ -16,6 +16,61 @@ related_components:
   - UiField
   - UiRadioSwitchOption
 
+examples:
+  - title: Basic switcher
+    code: |
+      <template>
+        <UiRadioSwitch
+          v-model:value="mode"
+          :options="options"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiRadioSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const mode = ref({ key: 'auto' })
+
+      const options = [
+        { label: 'Auto', value: { key: 'auto' } },
+        { label: 'Manual', value: { key: 'manual' } },
+      ]
+      </script>
+  - title: Cards with descriptions
+    code: |
+      <template>
+        <UiRadioSwitch
+          v-model:value="mode"
+          appearance="section"
+          rubber
+          :equal-fn="equalFn"
+        >
+          <UiRadioSwitchOption
+            label="Auto"
+            :value="{ key: 'auto' }"
+            description="Automatic mode"
+          />
+
+          <UiRadioSwitchOption
+            label="Manual"
+            :value="{ key: 'manual' }"
+            description="Manual setup"
+          />
+        </UiRadioSwitch>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import {
+        UiRadioSwitch,
+        UiRadioSwitchOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const mode = ref({ key: 'auto' })
+      const equalFn = (a?: { key: string }, b?: { key: string }) => a?.key === b?.key
+      </script>
+
 use_when:
   - You need one selected value from a small fixed set.
   - You want a segmented control instead of classic radio circles.
@@ -188,38 +243,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 → components/UiRadioSwitchOption.yml}

@@ -99,19 +99,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 +106,10 @@ 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.
+  root_classes:
+    - .ui-v1-radio-switch-option

package/docs/profiles/components/UiScrollBox.yml

@@ -0,0 +1,108 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiScrollBox
+
+examples:
+  - title: Example
+    code: |
+      <template>
+          <div :class="$style['wrapper']">
+              <UiScrollBox v-bind="$attrs" :class="$style['block']">
+                  <div :class="[$style['content'], $style['content_tall']]" />
+              </UiScrollBox>
+
+              <UiScrollBox v-bind="$attrs" :class="$style['block']">
+                  <div :class="[$style['content'], $style['content_wide']]" />
+              </UiScrollBox>
+          </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiScrollBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+      <style lang="less" module>
+
+      .wrapper {
+        display: flex;
+      }
+
+      .block {
+        width: 120px;
+        height: 147px;
+        border: 1px solid rgba(30, 34, 72, 0.16);
+        border-radius: 8px;
+
+        &:not(:last-child) {
+          margin-right: 8px;
+        }
+      }
+
+      .content {
+        width: 100%;
+        height: 100%;
+
+        &_wide { width: 300px; }
+        &_tall { height: 300px; }
+      }
+      </style>
+
+use_when:
+  - You need a bounded scroll area.
+  - You need long content inside a fixed-height or fixed-width region.
+
+avoid_when:
+  - You need normal page scrolling.
+
+api:
+  key_props: []
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: configurable wrapper tag or PerfectScrollbar root
+    tag: configurable, div by default
+  notes: The root depends on native mode and tag prop, but behaves as a scroll container rather than a visual primitive.
+
+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.

package/docs/profiles/{UiSelect.yml → components/UiSelect.yml}

@@ -18,6 +18,139 @@ related_components:
   - UiPopperConnector
   - UiPopperTarget
 
+examples:
+  - title: Basic selection
+    code: |
+      <template>
+          <UiSelect placeholder="Assignee">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiSelect,
+        UiSelectOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Multiple selection with clearing
+    code: |
+      <template>
+          <UiSelect
+              v-model:value="value"
+              multiple
+              clearable
+              placeholder="Assignees"
+          >
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<string[]>([])
+      </script>
+  - title: Option search
+    code: |
+      <template>
+          <UiSelect filterable placeholder="Find a user">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              <UiSelectOption value="philip" label="Philip Williamson" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Error state (`invalid`)
+    code: |
+      <template>
+          <UiSelect
+              v-model:value="value"
+              invalid
+              placeholder="User"
+          >
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('eduardo')
+      </script>
+  - title: "`readonly` mode"
+    code: |
+      <template>
+          <UiSelect readonly placeholder="User">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: "`disabled` mode"
+    code: |
+      <template>
+          <UiSelect disabled placeholder="User">
+              <UiSelectOption value="kyle" label="Kyle Simmons" />
+              <UiSelectOption value="eduardo" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Object options
+    code: |
+      <template>
+          <UiSelect
+              :value="{ id: 2, name: 'Eduardo Henry' }"
+              :equals-fn="(a, b) => a?.id === b?.id"
+              placeholder="User"
+          >
+              <UiSelectOption :value="{ id: 1, name: 'Kyle Simmons' }" label="Kyle Simmons" />
+              <UiSelectOption :value="{ id: 2, name: 'Eduardo Henry' }" label="Eduardo Henry" />
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiSelect, UiSelectOption } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Grouped options
+    code: |
+      <template>
+          <UiSelect placeholder="Employee">
+              <UiSelectOptionGroup label="Sales department">
+                  <UiSelectOption value="kyle" label="Kyle Simmons" />
+                  <UiSelectOption value="eduardo" label="Eduardo Henry" />
+              </UiSelectOptionGroup>
+
+              <UiSelectOptionGroup label="Support">
+                  <UiSelectOption value="philip" label="Philip Williamson" />
+              </UiSelectOptionGroup>
+          </UiSelect>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiSelect,
+        UiSelectOption,
+        UiSelectOptionGroup,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need to choose one value from a list.
   - You need multi-select behavior.
@@ -271,50 +404,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/components/UiSelectOption.yml

@@ -0,0 +1,74 @@
+component: UiSelectOption
+summary: >
+  UiSelectOption is the base selectable child of UiSelect. It represents one option node
+  in the select option tree.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSelectOption
+
+related_components:
+  - UiSelect
+  - UiSelectOptionGroup
+
+use_when:
+  - You need one option inside UiSelect.
+
+avoid_when:
+  - You need free layout content inside a select dropdown.
+
+api:
+  key_props:
+    - name: value
+    - name: label
+    - name: description
+    - name: disabled
+    - name: counter
+    - name: accent
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-select-option
+    tag: div
+  notes: Renders one option wrapper that usually contains a UiMenuItem row.
+
+geometry:
+  layout: listbox option row
+  root_display: block
+  width_behavior: stretches to available dropdown width
+
+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.
+  root_classes:
+    - .ui-v1-select-option

package/docs/profiles/components/UiSelectOptionGroup.yml

@@ -0,0 +1,66 @@
+component: UiSelectOptionGroup
+summary: >
+  UiSelectOptionGroup groups related UiSelectOption nodes under a shared label.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSelectOptionGroup
+
+related_components:
+  - UiSelect
+  - UiSelectOption
+
+use_when:
+  - You need grouped select options.
+
+avoid_when:
+  - You only have a flat list of options.
+
+api:
+  key_props:
+    - name: label
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-select-option-group
+    tag: div
+  notes: Renders one structural group wrapper around a heading area and nested option content.
+
+geometry:
+  layout: block-like option group wrapper
+  root_display: block
+  width_behavior: stretches to available dropdown width
+
+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.
+  root_classes:
+    - .ui-v1-select-option-group