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

package/docs/profiles/components/UiAlert.yml

@@ -0,0 +1,105 @@
+component: UiAlert
+summary: >
+  UiAlert is a compact contextual message block for status, warning, success, and danger feedback.
+  It can be shown inline in normal page flow and can be closable.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiAlert
+
+examples:
+  - title: Basic alert
+    code: |
+      <template>
+        <UiAlert text="Basic alert" />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Warning alert
+    code: |
+      <template>
+        <UiAlert variant="warning" text="Warning alert" />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+  - title: Closable alert
+    code: |
+      <template>
+        <UiAlert
+          closable
+          text="You can close this alert manually"
+        />
+
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAlert } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+use_when:
+  - You need inline status feedback.
+  - You need dismissible page-level or section-level notice content.
+
+avoid_when:
+  - You need a blocking modal message.
+  - You need a tiny field-level validation hint.
+
+api:
+  key_props:
+    - name: variant
+    - name: text
+    - name: shown
+    - name: closable
+    - name: fluid
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-alert
+    tag: div
+  notes: Current alert body is wrapped in UiTransition and uses one flex row for icon, content, and optional closer.
+
+geometry:
+  layout: block-like feedback row
+  root_display: flex
+  width_behavior: stretches to container width by default
+
+behavior:
+  notes:
+    - shown controls visibility.
+    - closable enables user dismissal.
+
+ai_notes:
+  do:
+    - Use UiAlert for inline feedback that should stay in normal layout flow.
+    - Keep the message close to the section or form it describes.
+  avoid:
+    - Do not use it as a replacement for modal confirmation.
+    - Do not use for field-level validation when UiField or UiError is more precise.
+
+composition:
+  works_well_with:
+    - UiButton
+    - UiInfobox
+    - UiError
+  patterns:
+    - title: Section-level feedback
+      notes: Place above or inside the affected section, not at the page top by default.
+    - title: Recoverable error
+      notes: Pair with a retry or fix action when the user can recover immediately.
+
+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.
+  root_classes:
+    - .ui-v1-alert

package/docs/profiles/components/UiAvatar.yml

@@ -0,0 +1,88 @@
+component: UiAvatar
+summary: >
+  UiAvatar renders a user or entity avatar with optional name, status, and link semantics.
+  It is meant for compact identity display rather than generic image rendering.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiAvatar
+
+examples:
+  - title: Basic avatar
+    code: |
+      <template>
+        <UiAvatar
+          name="Anna Smith"
+          src="https://example.com/avatar.jpg"
+          size="sm"
+          status="none"
+        />
+      </template>
+
+      <script lang="ts" setup>
+      import { UiAvatar } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
+use_when:
+  - You need a compact identity marker for a user or contact.
+  - You need avatar display with optional status.
+
+avoid_when:
+  - You need a generic content image.
+  - You need a large media block.
+
+api:
+  key_props:
+    - name: src
+    - name: name
+    - name: status
+    - name: size
+    - name: href
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-avatar or a.ui-v1-avatar
+    tag: div or a
+  notes: The root switches to anchor when href is provided.
+
+geometry:
+  layout: avatar frame
+  root_display: inline-block
+  width_behavior: content-sized by size
+
+behavior:
+  notes:
+    - Can render linked avatar behavior when href is provided.
+    - Name is useful as fallback identity information.
+
+ai_notes:
+  do:
+    - Use UiAvatar for identity display, not for general media.
+    - Provide name whenever possible so fallback identity stays meaningful.
+  avoid:
+    - Do not use it for generic content images or large media blocks.
+
+composition:
+  works_well_with:
+    - UiAvatarList
+    - UiTable
+    - UiMenuItem
+  patterns:
+    - title: Table identity cell
+      notes: Pair with UiLink size="small" when an avatar appears next to a linked user or customer name.
+    - title: Menu identity row
+      notes: Use in UiMenuItem avatar slot for users, customers, or accounts.
+
+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.
+  root_classes:
+    - .ui-v1-avatar

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

@@ -38,5 +38,31 @@ geometry:
 ai_notes:
   do:
     - Use for compact grouped identity display.
+    - Keep the list short enough to scan.
   avoid:
     - Do not use it as a replacement for a full people list.
+
+behavior:
+  notes:
+    - avatars prop should contain concise identity data, not full profile records.
+    - size should match the density of the surrounding table, menu, or card.
+
+composition:
+  works_well_with:
+    - UiAvatar
+    - UiTooltip
+  patterns:
+    - title: Compact collaborators
+      notes: Use when several actors must be shown in a narrow table or header area.
+
+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.
+  root_classes:
+    - .ui-v1-avatar-list

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

@@ -9,6 +9,20 @@ public_import:
   named:
     - UiButton
 
+examples:
+  - title: States
+    code: |
+      <template>
+          <UiButton variant="danger">
+              <IconDelete /> Delete
+          </UiButton>
+      </template>
+
+      <script lang="ts" setup>
+      import IconDelete from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/delete-outlined.svg'
+      import { UiButton } from '@retailcrm/embed-ui-v1-components/remote'
+      </script>
+
 use_when:
   - You need a primary or secondary action in a form or screen.
   - You need an inline action in a header, modal, infobox, or toolbar-like area.
@@ -211,14 +225,6 @@ composition:
     - UiInfobox
     - modal actions
 
-examples:
-  - title: Dangerous secondary action
-    goal: Build a secondary destructive action.
-    code: |
-      <UiButton appearance="secondary" variant="danger">
-        <IconDelete aria-hidden="true" />
-        Delete
-      </UiButton>
 
 ai_notes:
   do:

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/components/UiCheckbox.yml

@@ -0,0 +1,111 @@
+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.
+
+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.
+
+avoid_when:
+  - You need exclusive single choice, use UiRadio instead.
+  - You need a more compact toggle-like control, use UiSwitch instead.
+
+api:
+  key_props:
+    - name: model
+    - name: value
+    - name: indeterminate
+    - name: valueOfTruthy
+    - name: valueOfFalsy
+    - name: disabled
+  methods:
+    - name: click
+    - name: focus
+    - name: blur
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-checkbox
+    tag: span
+  notes: One inline wrapper around the visual checkbox control and label content.
+
+geometry:
+  layout: inline checkbox control
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
+behavior:
+  notes:
+    - model plus value supports group-style selection.
+    - indeterminate is useful for partial selection states.
+
+ai_notes:
+  do:
+    - Use for boolean choice or checkbox-group membership.
+    - Use indeterminate for parent selection such as "select all visible rows".
+  avoid:
+    - Do not use for mutually exclusive options.
+
+composition:
+  works_well_with:
+    - UiField
+    - UiTable
+    - UiTableColumn
+  patterns:
+    - title: Form boolean
+      notes: Wrap in UiField when the checkbox needs a persistent label, hint, or validation text.
+    - title: Table row selection
+      notes: Use in the first narrow UiTableColumn for row selection; use indeterminate in the header checkbox for partial selection.
+  avoid:
+    - Do not use as a visual switch replacement when the action is an immediate on or off setting.
+
+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-checkbox

package/docs/profiles/components/UiCollapse.yml

@@ -0,0 +1,129 @@
+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.
+
+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.
+
+avoid_when:
+  - You need a ready-to-use disclosure box with header UI, use UiCollapseBox instead.
+
+api:
+  key_props:
+    - name: expanded
+    - name: collapseBehaviour
+    - name: duration
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-collapse
+    tag: div
+  notes: The animated container is wrapped in a native transition and exists only while shown or expanded.
+
+geometry:
+  layout: block-like animated container
+  root_display: block
+  width_behavior: stretches to container width by default
+
+ai_notes:
+  do:
+    - Use UiCollapse as a primitive for expandable content regions.
+  avoid:
+    - Do not use it when a full disclosure component is the actual need.
+
+behavior:
+  notes:
+    - expanded controls visibility.
+    - collapseBehaviour controls whether collapsed content stays mounted or is disposed.
+    - duration controls transition timing.
+
+composition:
+  works_well_with:
+    - UiCollapseBox
+    - UiCollapseGroup
+  patterns:
+    - title: Custom disclosure
+      notes: Use UiCollapse when the trigger and header are custom and only the body transition is needed.
+    - title: Standard disclosure box
+      notes: Use UiCollapseBox when the screen needs built-in header, icon, and box chrome.
+
+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-collapse