@retailcrm/embed-ui-v1-components 0.9.14 → 0.9.16

package/docs/profiles/UiToggleButton.yml

@@ -0,0 +1,211 @@
+component: UiToggleButton
+summary: >
+  UiToggleButton is a stateful button primitive for toggle-like interactions. It keeps
+  native button shape and methods, but the pressed state is controlled externally and
+  can be used either for a standalone toggle or as the visual basis of segmented groups
+  such as UiToggleGroup.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToggleButton
+
+related_components:
+  - UiToggleGroup
+  - UiCheckbox
+  - UiSwitch
+
+use_when:
+  - You need a button-looking control with externally managed pressed state.
+  - You need a primitive for segmented controls or compact filter chips.
+  - You need button methods like focus, blur, and click together with toggle styling.
+
+avoid_when:
+  - You need checkbox or radio semantics without custom composition.
+  - You need a plain action button without persistent state, use UiButton instead.
+  - You need a ready multi-select segmented group, use UiToggleGroup instead.
+
+api:
+  key_props:
+    - name: pressed
+      notes: Enables the selected visual state.
+    - name: size
+      values:
+        - lg
+        - md
+        - sm
+        - xs
+      notes: Controls height, horizontal padding, icon size, and radius.
+    - name: disabled
+      notes: Disables native interaction and applies disabled styling.
+    - name: grouped
+      notes: Enables segmented-group geometry for adjacent toggle buttons.
+  props:
+    - name: id
+      notes: Optional id passed to the native button root.
+    - name: type
+      notes: Native button type, defaults to button.
+    - name: focused
+      notes: Forces the focus-ring styling; used internally by keyboard-managed groups.
+  slots:
+    - name: default
+      zone: button content
+      creates: Inner content layout for label and optional icons.
+      accepts:
+        recommended:
+          - text
+          - text plus icon
+          - icon component
+          - svg
+        avoid:
+          - nested interactive elements
+          - large block layout wrappers
+      layout_effect: Text and icon nodes are normalized into separate inner spans.
+      notes: Main content slot for standalone or grouped toggles.
+  methods:
+    - name: click
+      notes: Triggers a click programmatically.
+    - name: focus
+      notes: Focuses the native button root.
+    - name: blur
+      notes: Removes focus from the native button root.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiToggleButton currently renders one native button root with normalized inner content.
+    This structure is useful for reasoning and debugging, not as a stable styling API.
+  root:
+    shape: button.ui-v1-toggle-button
+    tag: button
+  zones:
+    - .ui-v1-toggle-button__content
+    - .ui-v1-toggle-button__icon
+    - .ui-v1-toggle-button__text
+  state_classes:
+    - .ui-v1-toggle-button_pressed
+    - .ui-v1-toggle-button_disabled
+    - .ui-v1-toggle-button_focused
+    - .ui-v1-toggle-button_grouped
+
+geometry:
+  layout: inline-flex button root
+  root_display: inline-flex
+  width_behavior: content-sized by default
+  notes:
+    - Fits into inline rows and compact filter bars without forcing a new line.
+    - grouped keeps each button inline-sized while allowing adjacent segments to merge visually.
+    - Size controls height, min-width, horizontal padding, content gap, and radius.
+    - grouped removes standalone radii and lets adjacent buttons visually merge into a segmented row.
+    - The component stays content-sized by default and fits naturally into inline rows and compact filter areas.
+
+styling:
+  notes:
+    - Props like pressed, disabled, grouped, and size are the main styling API.
+    - Internal classes and CSS variables describe the current implementation and are most useful for debugging.
+  root_classes:
+    - .ui-v1-toggle-button
+  state_classes:
+    - .ui-v1-toggle-button_pressed
+    - .ui-v1-toggle-button_disabled
+    - .ui-v1-toggle-button_focused
+    - .ui-v1-toggle-button_grouped
+    - .ui-v1-toggle-button_lg
+    - .ui-v1-toggle-button_md
+    - .ui-v1-toggle-button_sm
+    - .ui-v1-toggle-button_xs
+  zones:
+    - .ui-v1-toggle-button__content
+    - .ui-v1-toggle-button__icon
+    - .ui-v1-toggle-button__text
+  css_variables:
+    internal_layout_variables:
+      - name: --ui-v1-toggle-button-height
+        effect: Current control height for the selected size.
+      - name: --ui-v1-toggle-button-min-width
+        effect: Minimum width for the current size.
+      - name: --ui-v1-toggle-button-padding-x
+        effect: Horizontal padding of the button content.
+      - name: --ui-v1-toggle-button-radius
+        effect: Border radius for standalone and grouped edge segments.
+      - name: --ui-v1-toggle-button-icon-size
+        effect: Size of normalized icon nodes.
+      - name: --ui-v1-toggle-button-content-gap
+        effect: Gap between icon and text.
+      - name: --ui-v1-toggle-button-focus-color
+        effect: Color of the box-shadow based focus ring.
+  typography:
+    size_variants:
+      - name: lg
+        mixin: h4-accent
+        size: 18px
+        line_height: 28px
+        weight: 500
+      - name: md
+        mixin: text-regular-accent
+        size: 16px
+        line_height: 24px
+        weight: 500
+      - name: sm
+        mixin: text-small-accent
+        size: 14px
+        line_height: 20px
+        weight: 500
+      - name: xs
+        mixin: text-tiny-accent
+        size: 12px
+        line_height: 14px
+        weight: 500
+
+behavior:
+  states:
+    - name: pressed
+      notes: Changes only the visual selected state; external code owns the actual model.
+    - name: disabled
+      notes: Disables interaction and applies disabled styling.
+    - name: grouped
+      notes: Enables segmented adjacency behavior for use in button rows and groups.
+    - name: focused
+      notes: Forces focus-ring styling for keyboard-managed composition scenarios.
+  notes:
+    - The component does not manage its own on or off state.
+    - Click handling and value updates are owned by the parent screen or group component.
+
+accessibility:
+  notes:
+    - The root is a native button.
+    - The component does not add toggle ARIA semantics automatically.
+    - For standalone toggle usage, the caller should provide the appropriate state attribute such as aria-pressed.
+    - In grouped multi-select composition, the caller may apply group-specific role and checked semantics.
+
+composition:
+  works_well_with:
+    - UiToggleGroup
+    - UiField
+    - compact filter bars
+  patterns:
+    - title: Standalone filter toggle
+      notes: Use one button with external pressed state for compact show or hide controls.
+    - title: Segmented multi-select primitive
+      notes: Use grouped buttons when composing a custom segmented row or when extending UiToggleGroup behavior.
+
+examples:
+  - title: Standalone pressed state
+    goal: Build a toggleable filter button.
+    code: |
+      <UiToggleButton
+        :pressed="filtersOpened"
+        :aria-pressed="filtersOpened"
+        @click="filtersOpened = !filtersOpened"
+      >
+        Filters
+      </UiToggleButton>
+
+ai_notes:
+  do:
+    - Treat pressed as a controlled visual state.
+    - Prefer UiToggleGroup when the task is multi-select segmented choice rather than a single primitive.
+    - Add explicit ARIA state when the button represents a semantic toggle.
+  avoid:
+    - Do not assume pressed updates automatically on click.
+    - Do not use UiToggleButton instead of UiButton for ordinary stateless actions.

package/docs/profiles/UiToggleGroup.yml

@@ -0,0 +1,211 @@
+component: UiToggleGroup
+summary: >
+  UiToggleGroup is a segmented multi-select control built from toggle buttons. It is
+  designed for short always-visible choice sets such as weekdays, filters, or compact
+  mode flags where classic checkboxes would feel visually heavy. For richer option
+  markup, compose it with UiToggleGroupOption instead of relying only on the options array.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToggleGroup
+    - UiToggleGroupOption
+
+related_components:
+  - UiToggleButton
+  - UiCheckbox
+  - UiRadioSwitch
+
+use_when:
+  - You need multiple independent selections from a short fixed set.
+  - You want checkbox-like semantics with segmented button visuals.
+  - You need a compact weekday picker, filter strip, or channel selector.
+  - You need object values and must compare them through equalFn.
+
+avoid_when:
+  - You need exactly one selected value, use UiRadioSwitch or UiRadio instead.
+  - You need long lists, search, or popper-based selection, use UiSelect instead.
+  - You need classic visible checkbox affordances rather than segmented buttons.
+
+api:
+  key_props:
+    - name: model
+      notes: Array of selected values.
+    - name: options
+      notes: Quick array-based declaration for simple label and value pairs.
+    - name: equalFn
+      notes: Important when option values are objects or other non-primitives.
+    - name: size
+      values:
+        - lg
+        - md
+        - sm
+        - xs
+      notes: Controls segment geometry through UiToggleButton sizing.
+    - name: rubber
+      notes: Keeps the root content-sized instead of stretching.
+    - name: disabled
+      notes: Disables the whole group.
+  props:
+    - name: ariaLabel
+      notes: Accessible name for the group root.
+    - name: ariaLabelledby
+      notes: External label reference for the group root.
+    - name: ariaDescribedby
+      notes: External description reference for the group root.
+    - name: ariaOrientation
+      values:
+        - horizontal
+        - vertical
+      notes: Orientation hint exposed on the root, defaults to horizontal.
+  child_components:
+    - name: UiToggleGroupOption
+      key_props:
+        - value
+        - label
+        - disabled
+      notes: Use it for manual option declaration, per-option slots, or richer values.
+  slots:
+    - name: default
+      zone: option tree
+      creates: Replaces array-based options with manually declared UiToggleGroupOption nodes.
+      accepts:
+        recommended:
+          - UiToggleGroupOption
+        avoid:
+          - arbitrary interactive descendants
+          - unrelated wrappers
+      notes: Use for richer per-option composition than the plain options array allows.
+    - name: icon
+      zone: shared option icon in options mode
+      notes: Used only when the options array mode renders generated options.
+  emits:
+    - name: change
+      payload: unknown[]
+      notes: Fired when the selected model changes.
+    - name: update:model
+      payload: unknown[]
+      notes: Main v-model channel for selected values.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiToggleGroup currently renders one span root and a list of button-based option
+    shells. This section is for reasoning and debugging, not as a stable selector contract.
+  composition:
+    - span.ui-v1-toggle-group with role=toolbar by default
+    - UiToggleGroupOption children rendered as button roots with grouped toggle-button styling
+    - each option exposes checkbox-like role and checked state
+  root:
+    shape: span.ui-v1-toggle-group
+    tag: span
+  classes:
+    - .ui-v1-toggle-group
+    - .ui-v1-toggle-group_rubber
+    - .ui-v1-toggle-group_disabled
+    - .ui-v1-toggle-group_lg
+    - .ui-v1-toggle-group_md
+    - .ui-v1-toggle-group_sm
+    - .ui-v1-toggle-group_xs
+
+geometry:
+  layout: inline-flex capable segmented row
+  root_display:
+    default: flex
+    rubber: inline-flex
+  width_behavior: stretches by default, content-sized with rubber
+  notes:
+    - The root uses a span tag, but its computed layout is flex-based rather than text-like.
+    - The root is flex-based and keeps adjacent segments visually merged.
+    - rubber keeps the group content-sized.
+    - Without rubber, the root behaves like a stretchable flex container.
+    - Size is shared across all segments through root-level CSS variables.
+
+styling:
+  notes:
+    - Prefer size, rubber, disabled, and option-level props over selector overrides.
+    - The group root mainly controls shared sizing variables; per-segment visuals live in UiToggleButton.
+  root_classes:
+    - .ui-v1-toggle-group
+  state_classes:
+    - .ui-v1-toggle-group_rubber
+    - .ui-v1-toggle-group_disabled
+    - .ui-v1-toggle-group_lg
+    - .ui-v1-toggle-group_md
+    - .ui-v1-toggle-group_sm
+    - .ui-v1-toggle-group_xs
+  css_variables:
+    shared_segment_variables:
+      - name: --ui-v1-toggle-button-height
+        effect: Shared segment height for the selected group size.
+      - name: --ui-v1-toggle-button-min-width
+        effect: Shared segment minimum width.
+      - name: --ui-v1-toggle-button-padding-x
+        effect: Shared horizontal padding of each segment.
+      - name: --ui-v1-toggle-button-radius
+        effect: Shared edge radius for the grouped row.
+      - name: --ui-v1-toggle-button-icon-size
+        effect: Shared icon size of group options.
+      - name: --ui-v1-toggle-button-content-gap
+        effect: Shared gap between option icon and label.
+
+behavior:
+  states:
+    - name: disabled
+      notes: Disables the whole group and all options.
+    - name: rubber
+      notes: Keeps the group sized to content.
+    - name: option disabled
+      notes: Individual disabled options stay visible but are not interactive.
+  selection_and_matching:
+    - The component is always multi-select.
+    - Clicking an enabled option toggles its presence in model.
+    - update:model and change are emitted together on every toggle.
+    - equalFn should usually be provided when values are objects.
+    - In options mode the component generates UiToggleGroupOption nodes internally.
+  keyboard:
+    - One tab stop is used for the whole group through roving tabindex.
+    - ArrowLeft, ArrowRight, ArrowUp, and ArrowDown move focus across enabled options.
+    - Home and End jump to the first or last enabled option.
+    - Space and Enter toggle the currently focused option.
+    - Disabled options are skipped by keyboard navigation.
+
+accessibility:
+  notes:
+    - The root exposes role=toolbar by default and supports aria-label, aria-labelledby, aria-describedby, and aria-orientation.
+    - Each option exposes role=checkbox together with aria-checked and aria-disabled.
+    - The current implementation uses roving tabindex so only one option is tabbable at a time.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiToggleGroupOption
+    - compact filter rows
+  patterns:
+    - title: Weekday picker
+      notes: Use a short visible set of seven options with multi-select model.
+    - title: Filter chips with icon
+      notes: Use manual option composition or the shared icon slot for compact filters.
+
+examples:
+  - title: Weekday selection
+    goal: Build a segmented multi-select weekday picker.
+    code: |
+      <UiToggleGroup
+        v-model:model="days"
+        aria-label="Weekdays"
+        rubber
+      >
+        <UiToggleGroupOption label="Mon" value="monday" />
+        <UiToggleGroupOption label="Tue" value="tuesday" />
+        <UiToggleGroupOption label="Wed" value="wednesday" />
+      </UiToggleGroup>
+
+ai_notes:
+  do:
+    - Prefer options for simple text-only sets.
+    - Switch to UiToggleGroupOption when an option needs icon, custom label, or richer value handling.
+    - Add an accessible name through ariaLabel or ariaLabelledby.
+  avoid:
+    - Do not use UiToggleGroup for single-select flows.
+    - Do not treat internal .ui-v1-* classes as a stable extension styling API.

package/docs/profiles/UiToggleGroupOption.yml

@@ -0,0 +1,116 @@
+component: UiToggleGroupOption
+summary: >
+  UiToggleGroupOption is the declarative option child of UiToggleGroup. It is the
+  richer alternative to the plain options array and is used when one segment needs
+  custom icon, custom label markup, or a non-trivial value.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToggleGroupOption
+    - UiToggleGroup
+
+related_components:
+  - UiToggleGroup
+  - UiToggleButton
+
+use_when:
+  - You need one manually declared option inside UiToggleGroup.
+  - One option needs icon slot or custom label markup.
+  - You need explicit per-option disabled state or rich values.
+
+avoid_when:
+  - A simple options array on UiToggleGroup is enough.
+  - You need a standalone checkbox-like control outside UiToggleGroup.
+
+api:
+  key_props:
+    - name: value
+      notes: Required option value.
+    - name: label
+      notes: Plain-text fallback label.
+    - name: disabled
+      notes: Marks this option as non-interactive.
+  props:
+    - name: id
+      notes: Optional explicit id, otherwise generated automatically.
+    - name: value
+      notes: Required and toggled in the parent group model.
+    - name: label
+      notes: Optional when label slot is used.
+    - name: disabled
+      notes: Excluded from toggling and keyboard navigation.
+  slots:
+    - name: default
+      zone: full option content
+      notes: Replaces the default icon plus label composition.
+    - name: icon
+      zone: leading icon
+      notes: Adds a custom icon before the label.
+    - name: label
+      zone: main label
+      notes: Overrides the plain label prop.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    UiToggleGroupOption does not own the selection model. It is rendered inside
+    UiToggleGroup and becomes one grouped UiToggleButton with checkbox-like semantics.
+  root:
+    shape: button.ui-v1-toggle-button.ui-v1-toggle-button_grouped
+    tag: button
+
+geometry:
+  layout: inline-flex grouped segment inside a flex row
+  root_display: inline-flex
+  width_behavior: flexible within the parent group row
+  notes:
+    - The option is not intended as a standalone layout primitive.
+    - Final width and edge radii are defined by the parent group composition.
+
+behavior:
+  states:
+    - name: disabled
+      notes: Cannot be toggled and is skipped by keyboard navigation.
+    - name: checked
+      notes: Managed by the parent UiToggleGroup.
+    - name: focused
+      notes: Managed through the parent roving tabindex logic.
+  notes:
+    - Click toggles the option through the parent group.
+    - Space and Enter toggle the focused option.
+    - Arrow keys, Home, and End delegate focus movement through the parent group.
+
+accessibility:
+  notes:
+    - The rendered option uses a native button root.
+    - The parent composition applies role=checkbox together with aria-checked and aria-disabled.
+    - The current implementation participates in roving tabindex managed by UiToggleGroup.
+
+composition:
+  works_well_with:
+    - UiToggleGroup
+  patterns:
+    - title: Icon segment
+      notes: Use icon slot when one segment needs an icon before the label.
+    - title: Custom label content
+      notes: Use label or default slot when the option needs richer inline markup.
+
+examples:
+  - title: Icon option inside a group
+    goal: Define one rich segmented option with icon content.
+    code: |
+      <UiToggleGroup v-model:model="filters" aria-label="Filters">
+        <UiToggleGroupOption label="Files" value="files">
+          <template #icon>
+            <IconFile />
+          </template>
+        </UiToggleGroupOption>
+      </UiToggleGroup>
+
+ai_notes:
+  do:
+    - Use inside UiToggleGroup when one option needs richer content than the options array allows.
+    - Prefer label prop for plain text and slots for richer content.
+  avoid:
+    - Do not use it as a standalone control outside UiToggleGroup.

package/docs/profiles/UiToolbarButton.yml

@@ -0,0 +1,37 @@
+component: UiToolbarButton
+summary: >
+  UiToolbarButton is a compact button for toolbar zones. It shares action semantics with buttons
+  but is tuned for dense toolbar layouts.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToolbarButton
+
+use_when:
+  - You need a compact button in a toolbar or action strip.
+
+avoid_when:
+  - You need the full visual weight of UiButton.
+
+api:
+  emits:
+    - name: click
+    - name: focus
+    - name: blur
+  methods:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: button.ui-v1-button or a.ui-v1-button via UiButton
+    tag: button or a
+  notes: The component delegates its actual root element and layout behavior to UiButton.
+
+geometry:
+  layout: compact toolbar action
+  root_display: inline-block
+  width_behavior: content-sized by default

package/docs/profiles/UiToolbarLink.yml

@@ -0,0 +1,32 @@
+component: UiToolbarLink
+summary: >
+  UiToolbarLink is a compact toolbar-oriented link. It is the link counterpart to UiToolbarButton.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiToolbarLink
+
+use_when:
+  - You need a compact link in a toolbar area.
+
+avoid_when:
+  - You need a regular inline content link.
+
+api:
+  emits:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: a.ui-v1-link via UiLink
+    tag: a
+  notes: The component delegates its actual root element and layout behavior to UiLink.
+
+geometry:
+  layout: compact toolbar link
+  root_display: inline-flex
+  width_behavior: content-sized by default

package/docs/profiles/UiTooltip.yml

@@ -0,0 +1,43 @@
+component: UiTooltip
+summary: >
+  UiTooltip is the tooltip-specialized floating layer built on top of popper mechanics.
+  Use it for compact helper content anchored to one target.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTooltip
+
+related_components:
+  - UiPopper
+  - UiPopperConnector
+  - UiPopperTarget
+
+use_when:
+  - You need compact helper text or tooltip content.
+
+avoid_when:
+  - You need a dropdown or rich popup layout.
+
+api:
+  key_props:
+    - name: visible
+    - name: placement
+    - name: targetTriggers
+    - name: popperTriggers
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-popper via UiPopper
+    tag: div
+  notes: The component delegates the actual floating root to UiPopper and renders its content inside the popper body.
+
+geometry:
+  layout: floating tooltip layer outside normal document flow
+  root_display: block
+  width_behavior: content-sized by tooltip content
+
+ai_notes:
+  do:
+    - Use UiTooltip for tooltip semantics and UiPopper for lower-level floating behavior.

package/docs/profiles/UiTransition.yml

@@ -0,0 +1,27 @@
+component: UiTransition
+summary: >
+  UiTransition is a transition wrapper for animated mount, unmount, and visibility flows.
+  Use it to express motion without switching to raw transition markup.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiTransition
+
+use_when:
+  - You need transition behavior around content.
+
+avoid_when:
+  - You need static content with no transition behavior.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: no persistent DOM root
+    tag: none
+  notes: The component is a thin wrapper around the native Vue transition and forwards its slot content.
+
+geometry:
+  layout: no standalone layout of its own
+  root_display: none
+  width_behavior: defined entirely by the transitioned child