@retailcrm/embed-ui-v1-components 0.9.21 → 0.9.22-alpha.2

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

@@ -2,7 +2,6 @@ component: UiTableSorter
 summary: >
   UiTableSorter is a compact sort control primitive for custom table head content.
   Use it when header rendering is composed manually and sorting state must be shown explicitly.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitable--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -69,6 +68,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-table

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

@@ -1,13 +1,25 @@
 component: UiTag
 summary: >
   UiTag is a compact label or status pill. It can be interactive, removable, pinned, or visually saturated.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitag--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiTag
 
+examples:
+  - title: Slots
+    code: |
+      <template>
+          <UiTag background="#FEA530" saturated>
+              VIP
+          </UiTag>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiTag } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need a short status or label pill.
   - You need removable or interactive tags.
@@ -74,6 +86,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-tag-wrapper

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

@@ -2,7 +2,6 @@ component: UiTextbox
 summary: >
   UiTextbox is the base text and numeric input component. It covers single-line input,
   textarea mode, numeric and decimal input, plus prefix, suffix, icon zones, and a clear action.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitextbox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -14,6 +13,26 @@ related_components:
   - UiPageHeader
   - UiSelect
 
+examples:
+  - title: Slots
+    code: |
+      <template>
+          <UiTextbox v-model:value="term">
+              <template #leading-icon>
+                  <IconSearch aria-hidden="true" />
+              </template>
+          </UiTextbox>
+      </template>
+
+      <script lang="ts" setup>
+      import IconSearch from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/search.svg'
+      import { UiTextbox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      import { ref } from 'vue'
+
+      const term = ref('')
+      </script>
+
 use_when:
   - You need a standard text input.
   - You need search, email, phone, url, or password input.

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

@@ -2,7 +2,6 @@ component: UiTimePicker
 summary: >
   UiTimePicker is a time input component that combines textbox-like entry with a list of
   normalized time variants and bounds.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitimepicker--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -13,6 +12,66 @@ related_components:
   - UiTextbox
   - UiPopper
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiTimePicker v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Option interval (`interval`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :interval="15"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Range limit (`minTime` / `maxTime`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :min-time="[9, 30]"
+          :max-time="[18, 0]"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
+  - title: Custom options (`timeVariants`)
+    code: |
+      <template>
+        <UiTimePicker
+          v-model:value="value"
+          :time-variants="['09:00', '09:30', '12:25', '16:00']"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiTimePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref('10:30')
+      </script>
 use_when:
   - You need editable time input.
   - You need bounded time variants or interval-based time selection.
@@ -81,6 +140,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-time-picker

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

@@ -4,7 +4,6 @@ summary: >
   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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitogglebutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -16,6 +15,22 @@ related_components:
   - UiCheckbox
   - UiSwitch
 
+examples:
+  - title: Single toggle
+    code: |
+      <template>
+        <UiToggleButton :pressed="opened" @click="opened = !opened">
+          Filters
+        </UiToggleButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiToggleButton } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      </script>
+
 use_when:
   - You need a button-looking control with externally managed pressed state.
   - You need a primitive for segmented controls or compact filter chips.

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

@@ -4,7 +4,6 @@ summary: >
   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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitogglegroup--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -17,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.

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

@@ -3,7 +3,6 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitogglegroup--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -109,6 +108,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-toggle-button

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

@@ -2,13 +2,27 @@ component: UiToolbarButton
 summary: >
   UiToolbarButton is a compact button for toolbar zones. It shares action semantics with buttons
   but is tuned for dense toolbar layouts.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitoolbarbutton--docs
 
 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.
 
@@ -69,6 +83,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-button

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

@@ -1,13 +1,25 @@
 component: UiToolbarLink
 summary: >
   UiToolbarLink is a compact toolbar-oriented link. It is the link counterpart to UiToolbarButton.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitoolbarlink--docs
 
 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.
 
@@ -64,6 +76,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-link

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

@@ -2,7 +2,6 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uitooltip--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -14,6 +13,24 @@ related_components:
   - 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.
 
@@ -76,6 +93,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   root_classes:
     - .ui-v1-popper

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

@@ -2,7 +2,6 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uialert--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -61,4 +60,3 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.

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

@@ -2,13 +2,36 @@ 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.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/experimental-uiyandexmap--docs
 
 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.
@@ -77,6 +100,5 @@ 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.
-    - Use Storybook from the usage link to verify visual variants before generating custom layout around the component.
   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.