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

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

@@ -16,6 +16,31 @@ related_components:
   - UiCheckbox
   - UiRadioSwitch
 
+examples:
+  - title: Weekday selection
+    code: |
+      <template>
+        <UiToggleGroup v-model:model="days" rubber>
+          <UiToggleGroupOption label="Mon" value="monday" />
+          <UiToggleGroupOption label="Tue" value="tuesday" />
+          <UiToggleGroupOption label="Wed" value="wednesday" />
+          <UiToggleGroupOption label="Thu" value="thursday" />
+          <UiToggleGroupOption label="Fri" value="friday" />
+          <UiToggleGroupOption label="Sat" value="saturday" />
+          <UiToggleGroupOption label="Sun" value="sunday" />
+        </UiToggleGroup>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import {
+        UiToggleGroup,
+        UiToggleGroupOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const days = ref(['monday', 'wednesday', 'friday'])
+      </script>
+
 use_when:
   - You need multiple independent selections from a short fixed set.
   - You want checkbox-like semantics with segmented button visuals.
@@ -187,19 +212,6 @@ composition:
     - 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:

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

@@ -96,17 +96,6 @@ composition:
     - 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:
@@ -114,3 +103,10 @@ ai_notes:
     - Prefer label prop for plain text and slots for richer content.
   avoid:
     - Do not use it as a standalone control outside UiToggleGroup.
+
+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-toggle-button

package/docs/profiles/components/UiToolbarButton.yml

@@ -0,0 +1,87 @@
+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
+
+examples:
+  - title: Toolbar action
+    code: |
+      <template>
+        <UiToolbarButton>
+          <IconAdd aria-hidden="true" />
+          Create
+        </UiToolbarButton>
+      </template>
+
+      <script lang="ts" setup>
+      import IconAdd from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/add.svg'
+      import { UiToolbarButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+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
+
+behavior:
+  notes:
+    - Delegates button semantics to UiButton.
+    - Use for dense repeated toolbar actions, not primary form submission.
+
+composition:
+  works_well_with:
+    - UiToolbarLink
+    - UiButton
+  patterns:
+    - title: Compact action strip
+      notes: Use for secondary actions near tables, editors, or filter bars.
+
+ai_notes:
+  do:
+    - Use in toolbar zones where UiButton would be too visually heavy.
+  avoid:
+    - Do not use for the main page CTA; use UiButton.
+
+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-button

package/docs/profiles/components/UiToolbarLink.yml

@@ -0,0 +1,80 @@
+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
+
+examples:
+  - title: Toolbar link
+    code: |
+      <template>
+        <UiToolbarLink href="https://example.com">
+          Hyperlink
+        </UiToolbarLink>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiToolbarLink } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+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
+
+behavior:
+  notes:
+    - Delegates link semantics to UiLink.
+    - Use only for real navigation or link-shaped actions in dense toolbar areas.
+
+composition:
+  works_well_with:
+    - UiToolbarButton
+    - UiLink
+  patterns:
+    - title: Toolbar navigation
+      notes: Use for compact links next to toolbar buttons when the action navigates.
+
+ai_notes:
+  do:
+    - Use in toolbar zones when a compact real link is needed.
+  avoid:
+    - Do not use for ordinary inline content links; use UiLink.
+
+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-link

package/docs/profiles/components/UiTooltip.yml

@@ -0,0 +1,97 @@
+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
+
+examples:
+  - title: Usage
+    code: |
+      <template>
+          <UiPopperConnector>
+              <UiButton disabled>
+                  Save
+              </UiButton>
+
+              <UiTooltip>
+                  Complete all required fields before saving
+              </UiTooltip>
+          </UiPopperConnector>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiButton, UiPopperConnector, UiTooltip } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+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.
+    - Keep tooltip content short and non-essential.
+  avoid:
+    - Do not put forms, tables, or multi-step interactions in tooltips.
+
+behavior:
+  notes:
+    - visible can control display explicitly.
+    - targetTriggers and popperTriggers define how the tooltip opens and closes.
+    - placement controls the preferred floating position.
+
+composition:
+  works_well_with:
+    - UiPopperConnector
+    - UiPopperTarget
+    - UiButton
+  patterns:
+    - title: Icon helper
+      notes: Pair with an icon-only or compact control when a short explanation is needed.
+    - title: Truncated text hint
+      notes: Use to reveal full text only when the visible cell or label is intentionally truncated.
+
+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-popper

package/docs/profiles/components/UiTransition.yml

@@ -0,0 +1,62 @@
+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
+
+api:
+  key_props:
+    - name: name
+    - name: appear
+
+behavior:
+  notes:
+    - Adds transition semantics around the slotted child.
+    - Does not create layout or styling by itself.
+
+composition:
+  works_well_with:
+    - UiAlert
+    - UiCollapse
+    - UiModalWindow
+  patterns:
+    - title: Animated presence
+      notes: Use when content should mount or unmount with the shared transition behavior.
+
+ai_notes:
+  do:
+    - Use around one logical child whose own layout should remain responsible for size.
+  avoid:
+    - Do not use as a layout wrapper or visual container.
+
+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.

package/docs/profiles/components/UiYandexMap.yml

@@ -0,0 +1,104 @@
+component: UiYandexMap
+summary: >
+  UiYandexMap is the Yandex map component for map display and related location scenarios.
+  Treat it as unstable for now and avoid it unless the screen explicitly requires a map surface.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiYandexMap
+
+examples:
+  - title: Address picker map
+    code: |
+      <template>
+        <div style="width: 640px; max-width: 100%;">
+          <UiYandexMap
+            v-model:address="address"
+            api-key="YOUR_YANDEX_MAPS_API_KEY"
+            :plugins="plugins"
+          />
+        </div>
+
+        <p>Selected address:</p>
+        {{ address }}
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiYandexMap } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const address = ref('')
+      const plugins = []
+      </script>
+
+use_when:
+  - You need a Yandex map view.
+  - You need location display inside extension UI.
+
+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
+
+api:
+  key_props:
+    - name: apiKey
+      notes: Required Yandex Maps API key.
+    - name: address
+      notes: Address string used by the map and update channel.
+    - name: plugins
+      notes: Optional map plugins such as locator integration.
+  emits:
+    - name: update:address
+    - name: change
+
+behavior:
+  notes:
+    - Depends on Yandex map runtime availability.
+    - Should be treated as a specialized surface, not a generic layout block.
+    - The current public API is address-oriented rather than marker-list oriented.
+
+composition:
+  works_well_with:
+    - UiLoader
+    - UiAlert
+  patterns:
+    - title: Location display
+      notes: Use only when map interaction or spatial context is essential.
+    - title: Address-only view
+      notes: Prefer text address output when a map does not add actionable value.
+
+ai_notes:
+  do:
+    - Use only for explicit map requirements.
+    - Provide a non-map fallback or error state when the map runtime can fail.
+  avoid:
+    - Do not add maps as decorative content.
+
+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-yandex-map

package/docs/profiles/pages/CardSettingsPage.yml

@@ -0,0 +1,58 @@
+page_profile: CardSettingsPage
+summary: >
+  Settings page or entity card pattern for screens made mostly from forms and local actions.
+
+use_when:
+  - You need to edit an entity.
+  - You need a settings form.
+  - You need a white content surface with fields and local controls.
+
+examples_from_design:
+  - tracked event page
+  - sending limit settings
+  - email template settings
+  - trigger page
+
+expected_structure:
+  - UiPageHeader with a page title.
+  - The title can be editable via an inline-edit pattern when the product flow requires it.
+  - One or more 48px header buttons on the right.
+  - Header actions can be accompanied by text information or status labels.
+  - Optional top tabs.
+  - Main content sits on a white content surface.
+  - Content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
+  - A bottom save panel is optional.
+
+recommended_components:
+  - name: UiPageHeader
+    profile: ../components/UiPageHeader.yml
+  - name: UiButton
+    profile: ../components/UiButton.yml
+  - name: UiField
+    profile: ../components/UiField.yml
+  - name: UiTextbox
+    profile: ../components/UiTextbox.yml
+  - name: UiSelect
+    profile: ../components/UiSelect.yml
+  - name: UiCheckbox
+    profile: ../components/UiCheckbox.yml
+  - name: UiRadio
+    profile: ../components/UiRadio.yml
+  - name: UiRadioSwitch
+    profile: ../components/UiRadioSwitch.yml
+  - name: UiSwitch
+    profile: ../components/UiSwitch.yml
+  - name: UiTabGroup
+    profile: ../components/UiTabGroup.yml
+  - name: UiTab
+    profile: ../components/UiTab.yml
+  - name: UiTag
+    profile: ../components/UiTag.yml
+
+ai_notes:
+  do:
+    - Keep form controls grouped by task or semantic section.
+    - Use UiField around labelled form controls.
+    - Use tabs only when they reduce visible complexity without hiding required work.
+  avoid:
+    - Do not create a decorative landing page for operational settings.

package/docs/profiles/pages/CollapseBlockPage.yml

@@ -0,0 +1,46 @@
+page_profile: CollapseBlockPage
+summary: >
+  Settings page pattern for content split into independent collapsible semantic groups.
+
+use_when:
+  - You need settings split into semantic groups.
+  - You need optional or advanced sections that can collapse independently.
+
+examples_from_design:
+  - product editing
+  - mailing editing
+  - Double Opt-In settings
+
+expected_structure:
+  - Multiple collapsible blocks with their own content and local actions.
+  - If the page contains only collapse blocks, the white page surface is not needed.
+  - If every collapse block has its own save action, the bottom save panel is not needed.
+  - Collapse blocks can contain text, buttons, fields, controls, and small tables.
+
+avoid_inside_blocks:
+  - complex tables
+  - nested collapse blocks
+  - two-column content split across separate surfaces
+
+recommended_components:
+  - name: UiCollapse
+    profile: ../components/UiCollapse.yml
+  - name: UiCollapseBox
+    profile: ../components/UiCollapseBox.yml
+  - name: UiCollapseGroup
+    profile: ../components/UiCollapseGroup.yml
+  - name: UiButton
+    profile: ../components/UiButton.yml
+  - name: UiField
+    profile: ../components/UiField.yml
+  - name: UiTable
+    profile: ../components/UiTable.yml
+    notes: Use only for small, simple tables.
+
+ai_notes:
+  do:
+    - Use collapses for optional or separable sections.
+    - Keep required critical actions visible enough for the workflow.
+  avoid:
+    - Do not nest collapses inside collapses.
+    - Do not hide complex tables inside collapse blocks.

package/docs/profiles/pages/EntityListPage.yml

@@ -0,0 +1,66 @@
+page_profile: EntityListPage
+summary: >
+  Separate page pattern for listing entities with filtering, sorting, table data, pagination,
+  and a primary create action.
+
+use_when:
+  - You need a searchable, filterable registry.
+  - You need an order list, customer list, mailing list, task list, catalog, journal, or search-result page.
+
+examples_from_design:
+  - order list
+  - customer list
+  - mailing list
+  - task list
+
+expected_structure:
+  - UiPageHeader with a page title.
+  - One or more 48px page buttons on the right side of the header.
+  - If there are multiple header buttons, one should be primary and the rest can be secondary or tertiary.
+  - The main primary button usually creates a new entity for the list.
+  - Filters above the table, built from controls such as select, textbox, and combobox-like selection components.
+  - Filter controls should run in rows of roughly 4-5 fields, then wrap to the next row.
+  - Filters can be collapsible.
+  - Filter apply action uses a default secondary 36px text button.
+  - Filter reset action uses a danger secondary 36px icon button.
+  - Entity data is shown in a table.
+  - The table may scroll and may support export.
+
+recommended_components:
+  - name: UiPageHeader
+    profile: ../components/UiPageHeader.yml
+  - name: UiButton
+    profile: ../components/UiButton.yml
+  - name: UiField
+    profile: ../components/UiField.yml
+  - name: UiTextbox
+    profile: ../components/UiTextbox.yml
+  - name: UiSelect
+    profile: ../components/UiSelect.yml
+  - name: UiTable
+    profile: ../components/UiTable.yml
+  - name: UiTableColumn
+    profile: ../components/UiTableColumn.yml
+  - name: UiTableSorter
+    profile: ../components/UiTableSorter.yml
+  - name: UiTableFooterSection
+    profile: ../components/UiTableFooterSection.yml
+  - name: UiTableFooterButton
+    profile: ../components/UiTableFooterButton.yml
+
+table_footer_rules:
+  - Use UiTableFooterSection and UiTableFooterButton for table footer pagination.
+  - Do not replace table footer pagination controls with regular UiButton.
+  - Use chevron icon assets for arrow controls, not text glyphs.
+  - Keep footer styling scoped to a local table root class.
+  - Override the internal footer button class together with the local class when changing pagination text, active page, or arrow colours.
+  - "Reference Vue and CSS footer pattern: ../components/UiTable.yml"
+
+ai_notes:
+  do:
+    - Keep filters and table controls directly above the table.
+    - Persist filters, sorting, page, and page size in query parameters when routing is available.
+    - Reset page to 1 when filters or sorting change.
+  avoid:
+    - Do not hide filters in page header actions.
+    - Do not put pagination only in local state when the result set is routable.