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

package/docs/profiles/UiCollapse.yml

@@ -0,0 +1,40 @@
+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
+
+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.

package/docs/profiles/UiCollapseBox.yml

@@ -0,0 +1,51 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCollapseBox
+
+related_components:
+  - UiCollapse
+  - UiCollapseGroup
+
+use_when:
+  - You need a ready-to-use collapsible box.
+  - You need grouped expandable sections with consistent visuals.
+
+avoid_when:
+  - You need a bare collapse primitive without box chrome.
+
+api:
+  key_props:
+    - name: expanded
+    - name: expandable
+    - name: collapsible
+    - name: toggleable
+    - name: disabled
+    - name: color
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: section.ui-v1-collapse-box
+    tag: section
+  notes: Renders one section root with a header button and a collapsible body region.
+
+geometry:
+  layout: block-like collapsible section
+  root_display: flex
+  width_behavior: stretches to container width by default
+
+behavior:
+  notes:
+    - Supports controlled expanded state and grouped interaction.
+
+ai_notes:
+  do:
+    - Use UiCollapseBox for structured disclosure UI.
+  avoid:
+    - Do not rebuild collapse header UI manually when this component already fits.

package/docs/profiles/UiCollapseGroup.yml

@@ -0,0 +1,39 @@
+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.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiCollapseGroup
+
+related_components:
+  - UiCollapseBox
+
+use_when:
+  - You need several collapse boxes to coordinate state.
+  - You need one active box pattern.
+
+avoid_when:
+  - You only have one collapsible section.
+
+api:
+  key_props:
+    - name: activeBoxId
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div
+    tag: div
+  notes: Current implementation is an unstyled wrapper that coordinates child UiCollapseBox nodes.
+
+geometry:
+  layout: block wrapper for stacked collapse boxes
+  root_display: block
+  width_behavior: stretches to container width by default
+
+ai_notes:
+  do:
+    - Use with UiCollapseBox when grouped expansion matters.

package/docs/profiles/UiCopyButton.yml

@@ -0,0 +1,52 @@
+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.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-copy-button
+    tag: div
+  notes: The root wraps the trigger, tooltip, and fallback input for clipboard support.
+
+geometry:
+  layout: inline trigger wrapper
+  root_display: inline-block
+  width_behavior: content-sized by default
+
+ai_notes:
+  do:
+    - Use for copy-specific flows instead of recreating copy state manually.

package/docs/profiles/UiDate.yml

@@ -0,0 +1,38 @@
+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
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: time
+    tag: time
+  notes: Renders one semantic time element with formatted date text.
+
+geometry:
+  layout: inline date text
+  root_display: inline
+  width_behavior: content-sized by content
+
+ai_notes:
+  do:
+    - Use UiDate for formatted output and UiDatePicker for input.

package/docs/profiles/UiDatePicker.yml

@@ -0,0 +1,59 @@
+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
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: span.ui-v1-date-picker
+    tag: span
+  notes: The visible trigger behaves like an inline date control that opens a floating calendar.
+
+geometry:
+  layout: inline date input trigger
+  root_display: inline-block
+  width_behavior: content-sized by default
+
+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,32 @@
+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.
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-error
+    tag: div
+  notes: Renders one text container for error content.
+
+geometry:
+  layout: block-like error text container
+  root_display: block
+  width_behavior: stretches to container width by default
+
+ai_notes:
+  do:
+    - Use for compact error presentation.

package/docs/profiles/UiField.yml

@@ -0,0 +1,233 @@
+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:
+    shape: div.ui-v1-field
+    tag: div
+  zones:
+    - .ui-v1-field__headline
+    - .ui-v1-field__label
+    - hint trigger and tooltip
+    - .ui-v1-field__addon
+    - .ui-v1-field__control
+
+geometry:
+  layout: grid
+  root_display: grid
+  width: 100%
+  min_width: 0
+  width_behavior: stretches to container width by default
+  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,39 @@
+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
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: img
+    tag: img
+  notes: The component renders a single image element.
+
+geometry:
+  layout: replaced media element
+  root_display: inline-block
+  width_behavior: intrinsic by image source or explicit dimensions
+
+ai_notes:
+  do:
+    - Use UiImage for general media and UiAvatar for people or identity.

package/docs/profiles/UiInfobox.yml

@@ -0,0 +1,45 @@
+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
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: div.ui-v1-infobox
+    tag: div
+  notes: The visible infobox body is wrapped in UiTransition and uses one flex row for media, content, and optional closer.
+
+geometry:
+  layout: block-like message panel
+  root_display: flex
+  width_behavior: stretches to container width by default
+
+ai_notes:
+  do:
+    - Use UiInfobox for richer guidance blocks, not tiny alerts.

package/docs/profiles/UiLink.yml

@@ -0,0 +1,51 @@
+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
+
+rendered_structure:
+  descriptive_only: true
+  root:
+    shape: a.ui-v1-link
+    tag: a
+  notes: The root is one anchor element with inline icon and text zones.
+
+geometry:
+  layout: inline link root
+  root_display: inline-flex
+  width_behavior: content-sized by default
+
+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.