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

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

@@ -23,3 +23,15 @@ api:
     - 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

@@ -18,3 +18,15 @@ api:
     - 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

@@ -26,6 +26,18 @@ api:
     - 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

@@ -13,3 +13,15 @@ use_when:
 
 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

package/docs/profiles/UiYandexMap.yml

@@ -15,3 +15,15 @@ use_when:
 avoid_when:
   - You can solve the task without an embedded map and do not want to depend on an unstable component.
   - You only need text address output.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-yandex-map
+    tag: div
+  notes: The root is one map container that hosts the Yandex map instance.
+
+geometry:
+  layout: block-like map container
+  root_display: flex
+  width_behavior: stretches to container width by default

package/package.json

@@ -2,7 +2,7 @@
   "name": "@retailcrm/embed-ui-v1-components",
   "bin": "./bin/embed-ui-v1-components.mjs",
   "type": "module",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": "git@github.com:retailcrm/embed-ui.git",
@@ -83,7 +83,7 @@
     "@vitest/browser-playwright": "4.0.15",
     "@vue/compiler-sfc": "^3.5.25",
     "@vue/test-utils": "^2.4.6",
-    "@yandex/ymaps3-types": "^0.0.21",
+    "@yandex/ymaps3-types": "^1.0.19072130",
     "highlight.js": "^11.11.1",
     "less": "^4.4.2",
     "playwright": "1.58.2",