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

package/docs/profiles/components/UiCalendar.yml

@@ -0,0 +1,190 @@
+component: UiCalendar
+summary: >
+  UiCalendar is the date selection primitive behind date and date-range flows. It supports
+  single and range selection, multiple visual appearances, and locale-sensitive behavior.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCalendar
+
+examples:
+  - title: Basic calendar
+    code: |
+      <template>
+        <UiCalendar v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+  - title: Date range
+    code: |
+      <template>
+        <UiCalendar v-model:value="value" type="range" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date[]>([
+        new Date('2024-11-10'),
+        new Date('2024-11-19'),
+      ])
+      </script>
+  - title: Reset value (`nullable`)
+    code: |
+      <template>
+        <UiCalendar v-model:value="value" nullable />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+  - title: Two months at once (`appearance="double"`)
+    code: |
+      <template>
+        <UiCalendar
+          v-model:value="value"
+          type="range"
+          appearance="double"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date[]>([
+        new Date('2024-11-10'),
+        new Date('2024-11-19'),
+      ])
+      </script>
+  - title: Available date limit
+    code: |
+      <template>
+        <UiCalendar
+          v-model:value="value"
+          type="range"
+          :min-date="new Date('2024-11-05')"
+          :max-date="new Date('2024-11-25')"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date[]>([
+        new Date('2024-11-10'),
+        new Date('2024-11-19'),
+      ])
+      </script>
+  - title: Locale and first day of week
+    code: |
+      <template>
+        <UiCalendar
+          v-model:value="value"
+          locale="en-GB"
+          :first-day-of-week="1"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+  - title: Controlled value and change event
+    code: |
+      <template>
+        <UiCalendar
+          :value="value"
+          @update:value="value = $event"
+          @change="onCalendarChange"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCalendar } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+
+      const onCalendarChange = (nextValue: Date | null) => {
+        value.value = nextValue
+      }
+      </script>
+use_when:
+  - You need inline date selection.
+  - You need single-date or date-range picking without a textbox wrapper.
+
+avoid_when:
+  - You need the full textbox-plus-popper date picker flow.
+
+api:
+  key_props:
+    - name: value
+    - name: type
+    - name: appearance
+    - name: minDate
+    - name: maxDate
+    - name: locale
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-calendar
+    tag: div
+  notes: The root contains header controls, weekday labels, and the date grid.
+
+geometry:
+  layout: block-like calendar panel
+  root_display: flex
+  width_behavior: stretches to container width by default
+
+behavior:
+  notes:
+    - Supports single and range selection.
+    - minDate and maxDate constrain selection.
+
+ai_notes:
+  do:
+    - Use UiCalendar when inline calendar selection is the actual UI.
+  avoid:
+    - Use UiDatePicker instead if users expect textbox plus popup behavior.
+
+composition:
+  works_well_with:
+    - UiDatePicker
+    - UiField
+  patterns:
+    - title: Inline calendar panel
+      notes: Use in dashboards or popover content when the calendar itself should remain visible.
+    - title: Date input
+      notes: Prefer UiDatePicker for normal forms and filters because it provides the textbox trigger and popper behavior.
+
+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-calendar

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

@@ -2,13 +2,40 @@ component: UiCheckbox
 summary: >
   UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
   as well as model-plus-value patterns for checkbox groups.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicheckbox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiCheckbox
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiCheckbox id="notifications" v-model:model="enabled" />
+        <label for="notifications">Notifications</label>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCheckbox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const enabled = ref(false)
+      </script>
+  - title: Multiple selection
+    code: |
+      <template>
+        <UiCheckbox v-model:model="channels" value="email" />
+        <UiCheckbox v-model:model="channels" value="sms" />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCheckbox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const channels = ref<string[]>([])
+      </script>
 use_when:
   - You need a yes or no control.
   - You need one value inside a checkbox group model.
@@ -80,6 +107,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-checkbox

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

@@ -2,13 +2,69 @@ component: UiCollapse
 summary: >
   UiCollapse is a low-level show and hide container for expandable content. It controls
   whether content is hidden or disposed and how the transition behaves.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapse--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiCollapse
 
+examples:
+  - title: Basic collapse
+    code: |
+      <template>
+        <UiCollapse :expanded="opened">
+          <div>Collapsible content</div>
+        </UiCollapse>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapse } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      </script>
+  - title: Dispose collapsed content
+    code: |
+      <template>
+        <UiCollapse
+          :expanded="opened"
+          collapse-behaviour="dispose"
+        >
+          <div>Disposed content</div>
+        </UiCollapse>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapse } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      </script>
+  - title: Transition events
+    code: |
+      <template>
+        <UiCollapse
+          :expanded="opened"
+          @expanded="onExpanded"
+          @collapsed="onCollapsed"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapse } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+
+      const onExpanded = () => {
+        console.log('Expanded')
+      }
+
+      const onCollapsed = () => {
+        console.log('Collapsed')
+      }
+      </script>
 use_when:
   - You need conditional expandable content.
   - You need to choose between hidden and disposed collapsed states.
@@ -69,6 +125,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-collapse

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

@@ -2,7 +2,6 @@ component: UiCollapseBox
 summary: >
   UiCollapseBox is a structured expandable container with built-in header, state handling,
   and visual treatment. It is a higher-level companion to UiCollapse.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapsebox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -13,6 +12,70 @@ related_components:
   - UiCollapse
   - UiCollapseGroup
 
+examples:
+  - title: Basic collapse box
+    code: |
+      <template>
+        <UiCollapseBox v-model:expanded="expanded">
+          <template #title>Section title</template>
+          <template #body-content>Section content</template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const expanded = ref(false)
+      </script>
+  - title: Grouped collapse boxes
+    code: |
+      <template>
+        <UiCollapseGroup v-model:activeBoxId="activeBoxId">
+          <UiCollapseBox id="one">
+            <template #title>One</template>
+            <template #body-content>...</template>
+          </UiCollapseBox>
+
+          <UiCollapseBox id="two">
+            <template #title>Two</template>
+            <template #body-content>...</template>
+          </UiCollapseBox>
+        </UiCollapseGroup>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiCollapseBox, UiCollapseGroup } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const activeBoxId = ref('one')
+      </script>
+  - title: Disabled
+    code: |
+      <template>
+        <UiCollapseBox disabled>
+          <template #title>Disabled section</template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Custom icon through a slot
+    code: |
+      <template>
+        <UiCollapseBox>
+          <template #icon>
+            <MyCustomIcon />
+          </template>
+        </UiCollapseBox>
+
+      </template>
+
+      <script lang="ts" setup>
+      import MyCustomIcon from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/info.svg'
+      import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
 use_when:
   - You need a ready-to-use collapsible box.
   - You need grouped expandable sections with consistent visuals.
@@ -76,6 +139,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-collapse-box

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

@@ -2,7 +2,6 @@ component: UiCollapseGroup
 summary: >
   UiCollapseGroup coordinates several collapse boxes and tracks which box is active.
   It is useful when multiple disclosures should behave as one grouped unit.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicollapsebox--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -62,4 +61,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/{UiCopyButton.yml → components/UiCopyButton.yml}

@@ -2,7 +2,6 @@ component: UiCopyButton
 summary: >
   UiCopyButton is an action component for copying text values with tooltip feedback.
   It wraps copy behavior and copied-state hinting into one compact UI.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uicopybutton--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -13,6 +12,25 @@ related_components:
   - UiTooltip
   - UiButton
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiCopyButton text="Text to copy" size="sm">
+          <template #hint>
+            Copy
+          </template>
+
+          <template #hint-copied>
+            Copied
+          </template>
+        </UiCopyButton>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiCopyButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need a copy-to-clipboard action for a value.
   - You need built-in hint and copied-state tooltip text.
@@ -82,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-copy-button

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

@@ -2,13 +2,32 @@ component: UiDate
 summary: >
   UiDate is a display component for formatted date or date-time output. It is for presenting
   date values, not for editing them.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uidate--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiDate
 
+examples:
+  - title: Standard usage
+    code: |
+      <template>
+          <UiDate :date="new Date()" locale="en-GB" />
+      </template>
+
+      <script setup>
+      import { UiDate } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: With time display
+    code: |
+      <template>
+          <UiDate :date="new Date()" locale="en-GB" with-time />
+      </template>
+
+      <script setup>
+      import { UiDate } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need to display a date value.
   - You need optional time display with locale-aware formatting.
@@ -63,4 +82,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/{UiDatePicker.yml → components/UiDatePicker.yml}

@@ -2,7 +2,6 @@ component: UiDatePicker
 summary: >
   UiDatePicker combines textbox-like date display, popper behavior, and calendar selection.
   It supports single-date and range flows, constraints, and quick options.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uidatepicker--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -14,6 +13,57 @@ related_components:
   - UiTextbox
   - UiPopper
 
+examples:
+  - title: Example
+    code: |
+      <template>
+        <UiDatePicker v-model:value="value" />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
+  - title: Range selection
+    code: |
+      <template>
+        <UiDatePicker
+          v-model:value="value"
+          type="range"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date[]>([
+        new Date('2024-11-10'),
+        new Date('2024-11-19'),
+      ])
+      </script>
+  - title: Quick presets (`quickOptions`)
+    code: |
+      <template>
+        <UiDatePicker
+          v-model:value="value"
+          synchronization="confirmed"
+          :quick-options="[
+            { label: 'Today', value: new Date() },
+            { label: 'This week', value: [new Date('2024-11-18'), new Date('2024-11-24')] },
+          ]"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+      import { UiDatePicker } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const value = ref<Date | null>(new Date())
+      </script>
 use_when:
   - You need editable date input.
   - You need date-range selection through a textbox-plus-popup flow.
@@ -84,6 +134,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-date-picker

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

@@ -2,13 +2,60 @@ component: UiError
 summary: >
   UiError is a compact error-state component for short error messages or fallback states.
   It is intended for concise inline error display rather than large alert copy.
-usage: https://retailcrm.github.io/embed-ui/v1-components/0.9.18/?path=/docs/components-uierror--docs
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
   named:
     - UiError
 
+examples:
+  - title: Example
+    code: |
+      <template>
+          <UiError v-bind="$attrs" :class="$style['container']">
+              <template v-if="useSlot">
+                  <div :class="$style['content']">
+                      <IconError :class="$style['icon']" />
+                      Error message with icon
+                  </div>
+              </template>
+          </UiError>
+      </template>
+
+      <script lang="ts" setup>
+      import { UiError } from '@retailcrm/embed-ui-v1-components/remote'
+
+      import IconError from '@retailcrm/embed-ui-v1-components/assets/sprites/alerts/error.svg'
+
+      defineProps({
+        useSlot: {
+          type: Boolean,
+          default: false,
+        },
+      })
+      </script>
+
+      <style lang="less" module>
+
+      .container {
+        padding: 8px;
+        background: #FFF;
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+      }
+
+      .content {
+        display: flex;
+        align-items: center;
+        gap: 4px;
+      }
+
+      .icon {
+        width: 16px;
+        height: 16px;
+      }
+      </style>
+
 use_when:
   - You need a compact error block.
   - You need inline error text with standard styling.
@@ -72,6 +119,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-error