@retailcrm/embed-ui-v1-components 0.9.13 → 0.9.15

package/docs/profiles/UiRadio.yml

@@ -0,0 +1,26 @@
+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
+
+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

package/docs/profiles/UiRadioSwitch.yml

@@ -0,0 +1,224 @@
+component: UiRadioSwitch
+summary: >
+  UiRadioSwitch is a single-choice segmented control with two practical modes:
+  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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiRadioSwitch
+    - UiRadioSwitchOption
+
+related_components:
+  - UiRadio
+  - UiField
+  - UiRadioSwitchOption
+
+use_when:
+  - You need one selected value from a small fixed set.
+  - You want a segmented control instead of classic radio circles.
+  - You need a card-like section switch with descriptions.
+  - You need object values and must compare them through equalFn.
+
+avoid_when:
+  - You need multiple independent selections.
+  - You need dozens of options or searchable choice, use UiSelect instead.
+  - You need free-form content unrelated to a single-choice switch.
+
+api:
+  key_props:
+    - name: value
+      notes: Current selected value.
+    - name: options
+      notes: Quick array-based way to declare simple options.
+    - name: equalFn
+      notes: Important when option values are objects or other non-primitives.
+    - name: appearance
+      notes: Switches between default inline mode and section card mode.
+    - name: size
+      notes: Controls option height and icon sizing in default mode.
+    - name: rubber
+      notes: Makes the root behave like inline-flex instead of stretching full width.
+  props:
+    - name: value
+      notes: Works as the single selected model value.
+    - name: options
+      notes: Expects array items shaped as { label, value, disabled }.
+    - name: equalFn
+      notes: Defaults to strict equality.
+    - name: appearance
+      notes: Supports default and section.
+    - name: size
+      notes: Supports sm, md, lg.
+    - name: rubber
+      notes: Useful when the switch should size to content.
+  child_components:
+    - name: UiRadioSwitchOption
+      key_props:
+        - value
+        - label
+        - description
+        - disabled
+      notes: >
+        Use it when an option needs description, custom icon, custom label, or
+        custom checkmark content.
+  slots:
+    - name: default
+      zone: option tree
+      creates: Replaces array-based options with manually declared UiRadioSwitchOption nodes.
+      accepts:
+        recommended:
+          - UiRadioSwitchOption
+        avoid:
+          - arbitrary interactive controls
+          - unrelated wrappers
+      notes: >
+        The simplest path is options for plain labels, and default slot for richer
+        option markup.
+    - name: icon
+      zone: shared option icon in options mode
+      notes: >
+        Used only when options array mode renders generated options. For per-option
+        rich composition, use UiRadioSwitchOption slots instead.
+  emits:
+    - name: change
+      payload: unknown
+      notes: Fired when the selected value changes.
+    - name: update:value
+      payload: unknown
+      notes: Main v-model channel.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    The component renders as one radiogroup root and a list of option shells with
+    radio semantics. This section is for mental modeling and debugging, not as a
+    stable styling contract.
+  composition:
+    - UiRadioSwitch root with role=radiogroup
+    - UiRadioSwitchOption shells with role=radio
+    - section mode can add description and selected-state checkmark
+  classes:
+    - .ui-v1-radio-switch
+    - .ui-v1-radio-switch_borderless
+    - .ui-v1-radio-switch_rubber
+    - .ui-v1-radio-switch-option
+    - .ui-v1-radio-switch-option_default
+    - .ui-v1-radio-switch-option_standalone
+    - .ui-v1-radio-switch-option_active
+    - .ui-v1-radio-switch-option_disabled
+
+geometry:
+  layout: flex row for default mode, wrapping card row for section mode
+  notes:
+    - Default appearance behaves like a segmented control with adjacent options.
+    - Section appearance removes the outer border and lets cards wrap to a new line.
+    - rubber makes the root inline-sized instead of full-width.
+    - In section mode each option has a large minimum width and card-like padding.
+
+styling:
+  notes:
+    - Current classes describe host DOM structure and states.
+    - Prefer appearance, size, and rubber over selector-level customization.
+  root_classes:
+    - .ui-v1-radio-switch
+    - .ui-v1-radio-switch-option
+  state_classes:
+    - .ui-v1-radio-switch_borderless
+    - .ui-v1-radio-switch_rubber
+    - .ui-v1-radio-switch-option_default
+    - .ui-v1-radio-switch-option_standalone
+    - .ui-v1-radio-switch-option_active
+    - .ui-v1-radio-switch-option_disabled
+  zones:
+    - .ui-v1-radio-switch-option__head
+    - .ui-v1-radio-switch-option__icon
+    - .ui-v1-radio-switch-option__label
+    - .ui-v1-radio-switch-option__description
+    - .ui-v1-radio-switch-option__done
+  typography:
+    default:
+      notes:
+        - Default mode uses regular text sizing.
+        - Section mode uses accent heading-like styling for the main label.
+
+behavior:
+  states:
+    - name: appearance=default
+      notes: Renders a compact segmented control.
+    - name: appearance=section
+      notes: Renders standalone cards with optional description and selected checkmark.
+    - name: disabled
+      notes: Disabled options cannot be selected or focused by keyboard navigation.
+    - name: rubber
+      notes: Keeps the root content-sized.
+  selection_and_matching:
+    - The component is always single-select.
+    - update:value and change are emitted together on selection change.
+    - equalFn should usually be provided when values are objects.
+    - In options mode the component generates UiRadioSwitchOption nodes internally.
+  keyboard:
+    - One tab stop is used for the whole group.
+    - ArrowLeft, ArrowRight, ArrowUp, and ArrowDown move focus and selection across enabled options.
+    - Home and End jump to the first or last enabled option.
+    - Space and Enter select the currently focused option.
+
+accessibility:
+  notes:
+    - The root acts as radiogroup.
+    - Each option acts as radio and exposes aria-checked and aria-disabled.
+    - The current implementation uses roving tabindex so only one option is tabbable.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiRadioSwitchOption
+  patterns:
+    - title: Simple mode switch
+      notes: Use options for a small plain-text set such as view or status mode.
+    - 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:
+    - Use options for simple text-only cases.
+    - Switch to UiRadioSwitchOption when a choice needs richer content.
+    - Provide equalFn for object values instead of relying on reference equality.
+  avoid:
+    - Do not use it for multi-select flows.
+    - Do not treat internal .ui-v1-* classes as a stable extension styling API.

package/docs/profiles/UiRadioSwitchOption.yml

@@ -0,0 +1,113 @@
+component: UiRadioSwitchOption
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiRadioSwitchOption
+    - UiRadioSwitch
+
+related_components:
+  - UiRadioSwitch
+
+use_when:
+  - You need one manually declared option inside UiRadioSwitch.
+  - One option needs description or custom slot content.
+  - You need per-option icon or custom selected-state mark.
+
+avoid_when:
+  - A simple options array on UiRadioSwitch is enough.
+  - You need standalone radio semantics outside UiRadioSwitch.
+
+api:
+  key_props:
+    - name: value
+      notes: Required option value.
+    - name: label
+      notes: Plain-text fallback label.
+    - name: description
+      notes: Secondary copy for section appearance.
+    - name: disabled
+      notes: Marks this option as non-interactive.
+  props:
+    - name: id
+      notes: Optional explicit id, otherwise generated automatically.
+    - name: value
+      notes: Required and passed back through UiRadioSwitch selection updates.
+    - name: label
+      notes: Optional when label slot is used.
+    - name: description
+      notes: Primarily useful for appearance=section.
+    - name: disabled
+      notes: Excluded from selection and keyboard navigation.
+  slots:
+    - name: default
+      zone: full option body
+      notes: Replaces the whole internal option layout.
+    - name: icon
+      zone: leading icon
+      notes: Custom leading icon for the option header.
+    - name: label
+      zone: main label
+      notes: Overrides the plain label prop.
+    - name: description
+      zone: secondary description
+      notes: Used mainly in section mode.
+    - name: checkmark
+      zone: selected-state indicator
+      notes: Replaces the default selected-state icon in section mode.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiRadioSwitchOption does not own the whole selection model. It is rendered inside
+    UiRadioSwitch and becomes one radio node within the parent radiogroup.
+
+behavior:
+  states:
+    - name: disabled
+      notes: Cannot be selected and is skipped by keyboard navigation.
+    - name: checked
+      notes: Managed by the parent UiRadioSwitch.
+    - name: appearance=section
+      notes: Can show description and selected-state checkmark.
+  notes:
+    - Click selects the option through the parent group.
+    - Space and Enter select the focused option.
+    - Arrow keys delegate focus and selection movement through the parent group.
+
+accessibility:
+  notes:
+    - The parent group applies radio semantics to the option shell.
+    - The current implementation participates in roving tabindex managed by UiRadioSwitch.
+
+composition:
+  works_well_with:
+    - UiRadioSwitch
+  patterns:
+    - 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:
+    - Use inside UiRadioSwitch when one option needs richer content than the options array allows.
+    - 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.

package/docs/profiles/UiScrollBox.yml

@@ -0,0 +1,19 @@
+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
+
+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: []

package/docs/profiles/UiSelect.yml

@@ -0,0 +1,318 @@
+component: UiSelect
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiSelect
+    - UiSelectOption
+    - UiSelectOptionGroup
+
+related_components:
+  - UiField
+  - UiTextbox
+  - UiPopper
+  - UiPopperConnector
+  - UiPopperTarget
+
+use_when:
+  - You need to choose one value from a list.
+  - You need multi-select behavior.
+  - You need filtering over option labels or descriptions.
+  - You need grouped options.
+  - You need field semantics plus a dropdown selector.
+
+avoid_when:
+  - You need free-form text input.
+  - You need a button menu without a value model.
+  - You need a custom async-search UX outside the documented select flow.
+
+api:
+  key_props:
+    - name: value
+      notes: Selected value or array of values in multiple mode.
+    - name: placeholder
+      notes: Trigger text for empty state.
+    - name: multiple
+      notes: Switches to an array-based value model.
+    - name: filterable
+      notes: Enables typed filtering.
+    - name: clearable
+      notes: Enables a clear action for selection or filter text.
+    - name: equalsFn
+      notes: Critical for object values.
+    - name: placement
+      notes: Controls where the popper is positioned.
+    - name: popperFitTrigger
+      notes: Keeps the dropdown at least as wide as the trigger.
+    - name: expanded
+      notes: Lets the parent control open state.
+  props:
+    - name: invalid
+      notes: Enables error state on the textbox-like trigger.
+    - name: readonly
+      notes: Keeps the current value visible but blocks changes.
+    - name: disabled
+      notes: Disables both trigger and dropdown interaction.
+    - name: placeholderOnly
+      notes: Forces the trigger to show only placeholder text.
+    - name: textboxSize
+      notes: Controls the trigger size.
+    - name: targetTriggers
+      notes: Popper trigger rules on the target side.
+    - name: popperTriggers
+      notes: Popper trigger rules on the dropdown side.
+    - name: popperClass
+      notes: Extra class for the dropdown layer.
+    - name: popperOptions
+      notes: Low-level floating behavior options.
+    - name: ticker
+      notes: Technical signal for relayout or selection updates.
+  child_components:
+    - name: UiSelectOption
+      key_props:
+        - value
+        - label
+        - description
+        - disabled
+        - counter
+        - accent
+      notes: Base selectable option node.
+    - name: UiSelectOptionGroup
+      key_props:
+        - label
+      notes: Groups related options together.
+  slots:
+    - name: default
+      zone: option tree inside popper content
+      creates: The option registry and the visible option tree inside the dropdown.
+      accepts:
+        recommended:
+          - UiSelectOption
+          - UiSelectOptionGroup
+        avoid:
+          - arbitrary div wrappers
+          - form controls
+          - unrelated custom layout
+      layout_effect: Child nodes become dropdown content and participate in selection, filtering, and keyboard navigation.
+      notes: >
+        The safe path is to build the option tree from UiSelectOption and UiSelectOptionGroup.
+        Arbitrary children can break selection, keyboard navigation, and active-option flow.
+  emits:
+    - name: update:value
+      payload: unknown
+      notes: Main selection update channel.
+    - name: input
+      payload: Event
+      notes: Comes from the textbox-like trigger.
+    - name: focus
+      payload: FocusEvent
+      notes: Trigger focus.
+    - name: blur
+      payload: FocusEvent
+      notes: Trigger blur.
+    - name: clear
+      payload: undefined
+      notes: Fired when the clear action is used.
+    - name: update:expanded
+      payload: boolean
+      notes: Open-state update channel.
+    - name: keydown
+      payload: KeyboardEvent
+      notes: Main keyboard navigation channel.
+    - name: show
+      payload: undefined
+      notes: The dropdown starts opening.
+    - name: hide
+      payload: undefined
+      notes: The dropdown starts closing.
+    - name: shown
+      payload: undefined
+      notes: The dropdown is open.
+    - name: hidden
+      payload: undefined
+      notes: The dropdown is closed.
+    - name: dispose
+      payload: undefined
+      notes: The dropdown layer is disposed.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    Select is not a single DOM node in practice. Trigger and dropdown live in separate layers.
+  composition:
+    - UiPopperConnector as shared context
+    - UiSelectTrigger as textbox-like trigger
+    - UiSelectPopper as dropdown layer
+    - no-results text when filterable and no match exists
+    - default slot with the option tree
+  classes:
+    - .ui-v1-select for trigger root
+    - .ui-v1-select__popper for dropdown root
+    - .ui-v1-select-option for option root
+    - .ui-v1-select-option-group for option group
+
+geometry:
+  trigger_layout: textbox-like, fit-content, max-width 100%
+  dropdown_layout: popper layer outside normal document flow
+  notes:
+    - The trigger behaves visually like a textbox.
+    - The dropdown is rendered in a popper layer outside normal flow.
+    - The dropdown content has max-height and internal scrolling.
+    - popperFitTrigger is useful when the dropdown should not be narrower than the trigger.
+    - In multiple mode the trigger may collapse into a summary label when selected labels do not fit.
+
+styling:
+  notes:
+    - The trigger reuses the textbox visual model.
+    - The dropdown reuses popper variables for padding, radius, and floating surface geometry.
+    - Classes are descriptive implementation hooks, not a stable external styling contract.
+  root_classes:
+    - .ui-v1-select
+    - .ui-v1-select__trigger
+    - .ui-v1-select__touchstone
+    - .ui-v1-select__input
+    - .ui-v1-select__popper
+    - .ui-v1-select__content
+    - .ui-v1-select__no-results-text
+    - .ui-v1-select-option
+    - .ui-v1-select-option-group
+  state_classes:
+    - .ui-v1-select_active
+    - .ui-v1-select_filterable
+    - .ui-v1-select__content_locked
+    - .ui-v1-select-option_hidden
+    - .ui-v1-select-option-group_hidden
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-popper-padding
+        effect: Dropdown content padding.
+      - name: --ui-v1-popper-roundings
+        effect: Dropdown surface corner radius.
+    inherited_component_variables:
+      - name: --ui-v1-textbox-primary-color
+        effect: Active trigger underline and caret color.
+    internal_layout_variables:
+      - name: --border-color
+        effect: Trigger border or underline color inherited from UiTextbox.
+      - name: --active-color
+        effect: Trigger active color inherited from UiTextbox.
+  typography:
+    trigger:
+      notes:
+        - Trigger typography follows UiTextbox and therefore depends on textboxSize.
+        - The default trigger size is the textbox default size unless textboxSize changes it.
+    dropdown:
+      font_family: shared ui font family
+      notes:
+        - No-results text uses the dropdown text styling rather than heading typography.
+        - Option and group rows should be treated as compact list content, not heading-scale content.
+
+behavior:
+  states:
+    - name: multiple
+      notes: Switches the value model to an array and enables multi-selection.
+    - name: filterable
+      notes: Enables typed filtering by label or description.
+    - name: clearable
+      notes: Enables a clear action for selection or filter text.
+    - name: readonly
+      notes: Prevents changes while keeping display intact.
+    - name: disabled
+      notes: Disables both trigger and dropdown interaction.
+    - name: invalid
+      notes: Enables error styling on the trigger.
+    - name: placeholderOnly
+      notes: Forces placeholder display instead of selected labels.
+  selection_and_matching:
+    - If option values are objects, equalsFn is usually required.
+    - In single-select mode the dropdown closes after selecting an option.
+    - In multiple mode values are toggled inside the array model.
+    - Filtering matches option labels and descriptions.
+    - If nothing matches, a no-result block is shown.
+  keyboard:
+    - Arrow keys move the active highlight.
+    - Escape closes the dropdown.
+    - Tab closes the dropdown and lets focus move on.
+    - The active option is auto-scrolled into view when needed.
+
+accessibility:
+  notes:
+    - The trigger uses role=combobox.
+    - The trigger manages aria-expanded, aria-controls, aria-haspopup, and aria-activedescendant.
+    - The dropdown acts as a listbox-like layer.
+    - In multiple mode it is marked as aria-multiselectable=true.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiSelectOption
+    - UiSelectOptionGroup
+    - UiPopper
+    - UiPopperConnector
+    - UiPopperTarget
+  patterns:
+    - title: Form field select
+      notes: Put UiSelect inside UiField for labeled required choices.
+    - title: Object value selection
+      notes: Use equalsFn explicitly for object values.
+    - 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:
+    - Set equalsFn for object values in most cases.
+    - Use only UiSelectOption and UiSelectOptionGroup in the default slot.
+    - Read this profile together with UiPopper, UiPopperConnector, and UiPopperTarget.
+  avoid:
+    - Do not place arbitrary div wrappers inside the option tree.
+    - Do not choose UiSelect when free text input is the real need.
+    - Do not assume the dropdown lives in normal document flow next to the trigger.