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

package/docs/profiles/UiCopyButton.yml

@@ -0,0 +1,40 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCopyButton
+
+related_components:
+  - UiTooltip
+  - UiButton
+
+use_when:
+  - You need a copy-to-clipboard action for a value.
+  - You need built-in hint and copied-state tooltip text.
+
+avoid_when:
+  - You need a generic button with no copy semantics.
+
+api:
+  key_props:
+    - name: text
+    - name: size
+    - name: tooltipOptions
+  slots:
+    - name: trigger
+      zone: trigger
+      creates: Visible trigger content.
+    - name: hint
+      zone: tooltip
+      creates: Default tooltip content.
+    - name: hint-copied
+      zone: tooltip
+      creates: Tooltip content after copy succeeds.
+
+ai_notes:
+  do:
+    - Use for copy-specific flows instead of recreating copy state manually.

package/docs/profiles/UiDate.yml

@@ -0,0 +1,26 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiDate
+
+use_when:
+  - You need to display a date value.
+  - You need optional time display with locale-aware formatting.
+
+avoid_when:
+  - You need editable date input.
+
+api:
+  key_props:
+    - name: date
+    - name: withTime
+    - name: locale
+
+ai_notes:
+  do:
+    - Use UiDate for formatted output and UiDatePicker for input.

package/docs/profiles/UiDatePicker.yml

@@ -0,0 +1,47 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiDatePicker
+
+related_components:
+  - UiCalendar
+  - UiTextbox
+  - UiPopper
+
+use_when:
+  - You need editable date input.
+  - You need date-range selection through a textbox-plus-popup flow.
+
+avoid_when:
+  - You need always-visible inline calendar selection only.
+
+api:
+  key_props:
+    - name: value
+    - name: type
+    - name: minDate
+    - name: maxDate
+    - name: nullable
+    - name: synchronization
+    - name: quickOptions
+    - name: textboxOptions
+  methods:
+    - name: open
+    - name: close
+    - name: toggle
+
+behavior:
+  notes:
+    - Supports single-date and range flows.
+    - synchronization controls instant versus confirmed behavior.
+
+ai_notes:
+  do:
+    - Prefer UiDatePicker for typed or popup date input.
+  avoid:
+    - Do not use UiCalendar directly if a textbox trigger is expected.

package/docs/profiles/UiError.yml

@@ -0,0 +1,20 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiError
+
+use_when:
+  - You need a compact error block.
+  - You need inline error text with standard styling.
+
+avoid_when:
+  - You need a richer feedback block, use UiAlert or UiInfobox instead.
+
+ai_notes:
+  do:
+    - Use for compact error presentation.

package/docs/profiles/UiField.yml

@@ -0,0 +1,229 @@
+component: UiField
+summary: >
+  UiField is a remote-only form field wrapper. It connects a label and an inner control through
+  id and ARIA data, supports a hint tooltip near the label, and exposes an addon zone on the
+  right side of the headline.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiField
+
+related_components:
+  - UiTextbox
+  - UiSelect
+  - UiCheckbox
+  - UiDatePicker
+
+use_when:
+  - You need a labeled form control with consistent field semantics.
+  - You need to pass id, aria-labelledby, and aria-invalid into an inner control.
+  - You need a hint tooltip near the field label.
+  - You want required, invalid, disabled, or readonly state at the field level.
+
+avoid_when:
+  - You need a standalone control without label semantics.
+  - You need a generic layout container.
+  - You need to wrap several unrelated controls under one visual block.
+
+api:
+  key_props:
+    - name: id
+      required: true
+      notes: Required identifier used to connect label and control.
+    - name: label
+      notes: Field label text.
+    - name: hint
+      notes: Hint tooltip text near the label.
+    - name: invalid
+      notes: Affects label styling and slot prop ariaInvalid.
+    - name: required
+      notes: Adds an asterisk to the label and is forwarded through slot props.
+  props:
+    - name: hintAriaLabel
+      notes: aria-label for the hint trigger.
+    - name: disabled
+      notes: Visually dims the field and is forwarded through slot props.
+    - name: readonly
+      notes: Forwarded through slot props to the inner control.
+  slots:
+    - name: default
+      zone: control
+      creates: The main control area of the field.
+      provides:
+        - id
+        - required
+        - disabled
+        - readonly
+        - invalid
+        - ariaLabelledby
+        - ariaInvalid
+      accepts:
+        recommended:
+          - one form control
+          - UiTextbox
+          - UiSelect
+          - UiDatePicker
+        avoid:
+          - several unrelated controls
+          - decorative layout only
+          - raw content without using slot props
+      layout_effect: The control sits below the headline and inherits field-level semantics through slot props.
+      notes: >
+        Place the actual form control here. In most cases, slot props should be forwarded into the control.
+    - name: label
+      zone: headline-label
+      creates: The label area inside the headline row.
+      accepts:
+        recommended:
+          - plain text
+          - short inline markup
+          - span
+        avoid:
+          - nested form controls
+          - large block layout
+      layout_effect: Replaces the default text label but stays in the label position.
+      notes: Custom label content.
+    - name: hint
+      zone: hint-tooltip
+      creates: Tooltip content for the hint trigger.
+      accepts:
+        recommended:
+          - plain text
+          - short helper markup
+          - compact rich content
+        avoid:
+          - interactive forms
+          - large composite layouts
+      layout_effect: Does not change field layout; only changes tooltip body content.
+      notes: Custom tooltip content instead of plain hint text.
+    - name: addon
+      zone: headline-addon
+      creates: An inline addon area on the right side of the headline.
+      accepts:
+        recommended:
+          - short text
+          - UiLink
+          - UiButton
+          - compact status badge
+        avoid:
+          - full form groups
+          - wide content blocks
+      layout_effect: Lives in the headline row and is pushed to the right.
+      notes: Extra inline content on the right side of the headline.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    This is a debugging and reasoning model, not a public styling contract.
+  root: .ui-v1-field
+  zones:
+    - .ui-v1-field__headline
+    - .ui-v1-field__label
+    - hint trigger and tooltip
+    - .ui-v1-field__addon
+    - .ui-v1-field__control
+
+geometry:
+  layout: grid
+  width: 100%
+  min_width: 0
+  notes:
+    - Root uses grid with a 4px gap.
+    - The headline is a flex row.
+    - The addon is pushed to the right with margin-left auto.
+    - The control zone keeps min-width 0 and shrinks correctly in flex and grid layouts.
+
+styling:
+  notes:
+    - UiField styling mostly affects label, hint, and headline layout around the inner control.
+    - The inner control keeps its own styling system; UiField does not restyle it deeply.
+    - Classes are descriptive and should not be treated as a stable selector contract.
+  root_classes:
+    - .ui-v1-field
+  state_classes:
+    - .ui-v1-field_disabled
+    - .ui-v1-field_invalid
+  zones:
+    - .ui-v1-field__headline
+    - .ui-v1-field__label
+    - .ui-v1-field__required-mark
+    - .ui-v1-field__hint
+    - .ui-v1-field__hint-trigger
+    - .ui-v1-field__hint-icon
+    - .ui-v1-field__hint-tooltip
+    - .ui-v1-field__addon
+    - .ui-v1-field__control
+  css_variables:
+    public_theme_variables:
+      - name: --ui-v1-popper-background
+        effect: Hint tooltip background.
+      - name: --ui-v1-popper-padding
+        effect: Hint tooltip padding.
+      - name: --ui-v1-popper-roundings
+        effect: Hint tooltip corner radius.
+  typography:
+    label:
+      mixin: text-small-accent
+      size: 14px
+      line_height: 20px
+      weight: 500
+    addon:
+      mixin: text-small
+      size: 14px
+      line_height: 20px
+      weight: 400
+
+behavior:
+  states:
+    - name: required
+      notes: Adds an asterisk to the label.
+    - name: invalid
+      notes: Tints the label and exposes ariaInvalid in slot props.
+    - name: disabled
+      notes: Visually dims the field.
+    - name: readonly
+      notes: Is forwarded to the inner control through slot props.
+  notes:
+    - If label is missing, ariaLabelledby in slot props is undefined.
+    - The hint is shown on hover and focus.
+
+accessibility:
+  notes:
+    - The component does not render a control itself, so ARIA wiring must be completed in the default slot.
+    - A common pattern is field.id -> control id and field.ariaLabelledby or field.ariaInvalid -> input attributes.
+    - The hint trigger renders with role=button and tabindex=0.
+
+composition:
+  works_well_with:
+    - UiTextbox
+    - UiSelect
+    - UiDatePicker
+    - UiTimePicker
+  patterns:
+    - title: Safe field wiring
+      notes: Use slot props for semantics, not just for visual wrapping.
+
+examples:
+  - title: Text field with propagated semantics
+    goal: Build a text field with correct ARIA wiring.
+    code: |
+      <UiField id="comment" label="Comment" hint="Visible to managers">
+        <template #default="field">
+          <UiTextbox
+            :id="field.id"
+            :input-attributes="{
+              'aria-labelledby': field.ariaLabelledby,
+              'aria-invalid': field.ariaInvalid,
+            }"
+          />
+        </template>
+      </UiField>
+
+ai_notes:
+  do:
+    - Forward slot props into the actual control in most form scenarios.
+    - Use UiField as a semantic wrapper for a single control.
+  avoid:
+    - Do not use UiField as a generic visual container without control semantics.
+    - Do not ignore id and ariaLabelledby when accessibility matters.

package/docs/profiles/UiImage.yml

@@ -0,0 +1,27 @@
+component: UiImage
+summary: >
+  UiImage is a generic image display component with optional resize and crop hints.
+  Use it for regular visual content rather than identity avatars.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiImage
+
+use_when:
+  - You need to render an image asset.
+  - You need resize or crop hints for image output.
+
+avoid_when:
+  - You need identity-focused avatar UI.
+
+api:
+  key_props:
+    - name: src
+    - name: alt
+    - name: resize
+    - name: crop
+
+ai_notes:
+  do:
+    - Use UiImage for general media and UiAvatar for people or identity.

package/docs/profiles/UiInfobox.yml

@@ -0,0 +1,33 @@
+component: UiInfobox
+summary: >
+  UiInfobox is a richer explanatory block for inline product, warning, or helper content.
+  It can be closable and expandable.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiInfobox
+
+use_when:
+  - You need a highlighted explanatory block.
+  - You need closable or expandable helper content.
+
+avoid_when:
+  - You need a one-line alert only.
+
+api:
+  key_props:
+    - name: title
+    - name: shown
+    - name: expanded
+    - name: expandable
+    - name: closable
+    - name: warning
+  methods:
+    - name: show
+    - name: hide
+    - name: toggle
+
+ai_notes:
+  do:
+    - Use UiInfobox for richer guidance blocks, not tiny alerts.

package/docs/profiles/UiLink.yml

@@ -0,0 +1,39 @@
+component: UiLink
+summary: >
+  UiLink is the main text-link component for inline navigation and inline actions that should
+  still read as links rather than buttons.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiLink
+
+use_when:
+  - You need inline navigation or linked text.
+  - You need a compact action that should still read as a link.
+
+avoid_when:
+  - You need button semantics, use UiButton instead.
+
+api:
+  key_props:
+    - name: href
+    - name: external
+    - name: appearance
+    - name: size
+    - name: accent
+    - name: ellipsis
+  slots:
+    - name: icon
+      zone: inline-icon
+      creates: Optional icon zone inside the link.
+  emits:
+    - name: click
+    - name: focus
+    - name: blur
+
+ai_notes:
+  do:
+    - Use UiLink for real link semantics and inline navigation.
+  avoid:
+    - Do not use UiLink where the action should read as a button.

package/docs/profiles/UiLoader.yml

@@ -0,0 +1,26 @@
+component: UiLoader
+summary: >
+  UiLoader displays loading progress or waiting state. It can be used inline or as an overlay.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiLoader
+
+use_when:
+  - You need a visible loading indicator.
+  - You need inline or overlay loading state.
+
+avoid_when:
+  - You need skeleton content rather than a spinner-like loader.
+
+api:
+  key_props:
+    - name: diameter
+    - name: thickness
+    - name: fixed
+    - name: overlay
+
+ai_notes:
+  do:
+    - Use overlay or fixed only when the loader should escape normal inline flow.

package/docs/profiles/UiMenuItem.yml

@@ -0,0 +1,45 @@
+component: UiMenuItem
+summary: >
+  UiMenuItem is a structured menu row component with support for icons, avatar, description,
+  counters, and active or danger styling.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiMenuItem
+
+use_when:
+  - You need a menu row with structured content zones.
+  - You need icon, avatar, description, or counter inside one menu item.
+
+avoid_when:
+  - You need a plain inline link.
+
+api:
+  key_props:
+    - name: description
+    - name: counter
+    - name: active
+    - name: danger
+    - name: disabled
+    - name: size
+  slots:
+    - name: default
+      zone: main-label
+      creates: Main visible label area.
+    - name: avatar
+      zone: leading-avatar
+      creates: Leading avatar zone.
+    - name: leading-icon
+      zone: leading-icon
+      creates: Leading icon zone.
+    - name: description
+      zone: secondary-copy
+      creates: Secondary description area.
+    - name: trailing-icon
+      zone: trailing-icon
+      creates: Trailing icon zone.
+
+ai_notes:
+  do:
+    - Use structured slots instead of custom wrappers inside menu rows.

package/docs/profiles/UiMenuItemGroup.yml

@@ -0,0 +1,38 @@
+component: UiMenuItemGroup
+summary: >
+  UiMenuItemGroup groups related menu items and exposes dedicated zones for group label
+  and quantity metadata.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiMenuItemGroup
+
+related_components:
+  - UiMenuItem
+
+use_when:
+  - You need several menu items under one group heading.
+  - You need group label or quantity metadata.
+
+avoid_when:
+  - You have only one item and no group semantics.
+
+api:
+  slots:
+    - name: default
+      zone: group-body
+      creates: Main group content.
+    - name: option
+      zone: option-list
+      creates: Explicit option area for grouped items.
+    - name: label
+      zone: group-label
+      creates: Group heading area.
+    - name: quantity
+      zone: group-meta
+      creates: Group quantity or meta area.
+
+ai_notes:
+  do:
+    - Use for grouped menu structure instead of manual heading-plus-list markup.

package/docs/profiles/UiModalSidebar.yml

@@ -0,0 +1,34 @@
+component: UiModalSidebar
+summary: >
+  UiModalSidebar is a side-docked modal surface with open state, direction, size, and
+  scrolling control. Use it when the UI should slide from an edge instead of opening as a centered dialog.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalSidebar
+
+use_when:
+  - You need side-panel modal UI.
+  - You need left or right docked modal content.
+
+avoid_when:
+  - You need a centered dialog.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: direction
+    - name: size
+    - name: scrolling
+    - name: fixed
+
+behavior:
+  notes:
+    - opened controls visibility.
+    - direction controls which side the sidebar comes from.
+
+ai_notes:
+  do:
+    - Use UiModalSidebar when page context should stay visually connected to the modal content.

package/docs/profiles/UiModalWindow.yml

@@ -0,0 +1,32 @@
+component: UiModalWindow
+summary: >
+  UiModalWindow is the main centered modal container. It supports open state, closability,
+  appearance variants, fullscreen and responsive behavior, and dialog roles.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalWindow
+
+related_components:
+  - UiModalWindowSurface
+
+use_when:
+  - You need a centered dialog.
+  - You need modal interaction with standard dialog semantics.
+
+avoid_when:
+  - You need a side-docked modal, use UiModalSidebar instead.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: appearance
+    - name: fullscreen
+    - name: responsive
+    - name: scrolling
+    - name: role
+  methods:
+    - name: open
+    - name: close

package/docs/profiles/UiModalWindowSurface.yml

@@ -0,0 +1,29 @@
+component: UiModalWindowSurface
+summary: >
+  UiModalWindowSurface is the lower-level modal surface API behind modal window flows.
+  Use it when you need modal surface behavior with more explicit composition control.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiModalWindowSurface
+
+related_components:
+  - UiModalWindow
+
+use_when:
+  - You need explicit modal surface composition.
+  - You need modal surface behavior without the higher-level modal wrapper.
+
+avoid_when:
+  - You just need the regular centered modal API, use UiModalWindow instead.
+
+api:
+  key_props:
+    - name: opened
+    - name: closable
+    - name: appearance
+    - name: fullscreen
+    - name: responsive
+    - name: scrolling
+    - name: role