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

package/docs/STYLING.md

@@ -0,0 +1,156 @@
+# Styling Notes For AI
+
+This document explains how to read styling information in `v1-components` profiles.
+
+It exists to help AI agents reason about geometry, theming, and typography without treating
+internal selectors as a guaranteed public styling API.
+
+## Boundary
+
+- `.ui-v1-*` classes in profiles are primarily descriptive.
+- Use them for mental modeling, debugging, and understanding layout zones.
+- Prefer props and documented CSS custom properties over selector-based overrides.
+- If a profile marks a variable as internal, do not treat it as a stable extension theming hook.
+
+## Shared Stylesheet Map
+
+Most host component styles are built from the shared LESS files in
+[`assets/stylesheets`](../assets/stylesheets/).
+
+Use this map when a profile references shared tokens or mixins:
+
+- [`typography.less`](../assets/stylesheets/typography.less)
+  primary source for font family, type scale, and typography mixins such as `h2-accent`,
+  `text-regular`, `text-small-accent`, and `text-tiny`.
+- [`palette.less`](../assets/stylesheets/palette.less)
+  primary source for semantic color families such as `@blue-500`, `@grey-700`,
+  `@red-transparent`, and similar tokens.
+- [`geometry.less`](../assets/stylesheets/geometry.less)
+  primary source for radius tokens and reusable geometry mixins such as
+  `reset-box-sizing`, `square`, `circle`, `border-radius-start`, and `border-radius-end`.
+- [`variables.less`](../assets/stylesheets/variables.less)
+  primary source for shared spacing, drop shadows, and the common transition token used by
+  many components.
+- [`motion.less`](../assets/stylesheets/motion.less)
+  narrow motion helper that currently repeats the shared transition token shape.
+- [`layout.less`](../assets/stylesheets/layout.less)
+  legacy or narrow layout spacing aliases. Use with care and prefer `variables.less` when a
+  component already imports that file.
+
+## Component-Local Stylesheets
+
+Some components also have local `variables.less` files next to the component styles.
+Those files live in the source repository and are not part of the published package.
+
+Typical examples include button, link, and modal component tokens.
+
+These files usually define component-scale dimensions, icon sizes, or z-index-like local tokens.
+
+Guideline:
+
+- treat shared stylesheets as the primary design token layer;
+- treat component-local `variables.less` as component-specific implementation tokens;
+- mention local variables in a profile when they materially affect layout or generated markup decisions.
+
+## What To Read In A Profile
+
+When a task is about styling or layout, read the `styling` section of the component profile:
+
+- `root_classes`
+- `state_classes`
+- `zones`
+- `css_variables`
+- `typography`
+
+This is the fastest path for questions like:
+
+- which element actually owns the underline or border;
+- which CSS variable changes popper padding or textbox active color;
+- which typography scale is used by a given size variant;
+- whether a slot creates a separate visual segment or just inline content.
+
+## Typography Scale
+
+The shared type scale comes from [`../assets/stylesheets/typography.less`](../assets/stylesheets/typography.less).
+
+Base font family:
+
+- `-apple-system, BlinkMacSystemFont, "Segoe UI", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", "Roboto", sans-serif`
+
+Main sizes:
+
+- `h1`: `40px / 44px`
+- `h2`: `24px / 32px`
+- `h3`: `20px / 32px`
+- `h4`: `18px / 28px`
+- `text-regular`: `16px / 24px`
+- `text-small`: `14px / 20px`
+- `text-tiny`: `12px / 14px`
+
+Common weights:
+
+- normal: `400`
+- accent: `500`
+
+Notes:
+
+- some accent heading mixins use stronger weights than the shared `@font-weight-accent` token;
+- profiles should prefer recording the actual applied weight when it matters;
+- size props often switch both geometry and typography together.
+
+## Spacing, Radius, And Motion Tokens
+
+High-signal shared tokens:
+
+- spacing from [`variables.less`](../assets/stylesheets/variables.less):
+  `@spacing-xxs`, `@spacing-xs`, `@spacing-s`, `@spacing-m`, `@spacing-l`, `@spacing-xl`, `@spacing-xxl`
+- radius from [`geometry.less`](../assets/stylesheets/geometry.less):
+  `@border-radius-sm`, `@border-radius-md`, `@border-radius-lg`
+- transition from [`variables.less`](../assets/stylesheets/variables.less) and [`motion.less`](../assets/stylesheets/motion.less):
+  `@transition`
+
+When documenting a component profile:
+
+- mention these tokens when they directly shape slot zones, paddings, or component sizes;
+- avoid dumping every imported token if it does not affect component choice or layout reasoning.
+
+## CSS Variable Guidance
+
+Profiles split CSS variables into practical groups:
+
+- `public_theme_variables`
+  use these first when you need color, spacing, or popper-level theming.
+- `inherited_component_variables`
+  variables reused from neighboring components, such as `UiSelect` reusing textbox color variables.
+- `internal_layout_variables`
+  useful for reasoning and debugging, but not recommended as external override points.
+
+## Typical Safe Strategy
+
+For style-sensitive generation:
+
+1. choose the correct component and size prop first;
+2. use documented slots to create the right visual zones;
+3. use documented CSS variables if a theme override is needed;
+4. avoid relying on internal descendant selectors unless the profile says that is safe.
+
+## How To Mention Styles In Profiles
+
+A good `styling` section should answer:
+
+- which shared stylesheet family the component mostly depends on;
+- which root and state classes are useful for debugging;
+- which CSS variables are realistic override points;
+- which typography mixin or resulting type scale is active;
+- whether local component variables materially affect size or geometry.
+
+Do not try to mirror every imported token from LESS files. Keep only decision-making signal.
+
+## Reference Surface
+
+- `assets/stylesheets/typography.less`
+- `assets/stylesheets/palette.less`
+- `assets/stylesheets/geometry.less`
+- `assets/stylesheets/variables.less`
+- `assets/stylesheets/layout.less`
+- `assets/stylesheets/motion.less`

package/docs/profiles/UiAddButton.yml

@@ -0,0 +1,45 @@
+component: UiAddButton
+summary: >
+  UiAddButton is an action-first button for add or create flows. It is close to UiButton,
+  but tuned for "create another item" scenarios and supports small descriptive additions.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiAddButton
+
+related_components:
+  - UiButton
+  - UiToolbarButton
+
+use_when:
+  - You need a dedicated create or add action.
+  - You need a compact add CTA with optional extra description.
+
+avoid_when:
+  - You need a regular text link.
+  - You need a generic button without add semantics.
+
+api:
+  key_props:
+    - name: color
+    - name: small
+    - name: disabled
+    - name: height
+  slots:
+    - name: icon
+      zone: leading-icon
+      creates: Leading icon area for the add action.
+    - name: description
+      zone: secondary-copy
+      creates: Optional secondary description near the main label.
+
+behavior:
+  notes:
+    - Behaves like a clickable add action with standard button focus and click semantics.
+
+ai_notes:
+  do:
+    - Use for create and add flows rather than generic submit actions.
+  avoid:
+    - Do not replace a plain UiButton unless the add semantics are intentional.

package/docs/profiles/UiAlert.yml

@@ -0,0 +1,36 @@
+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
+
+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
+
+behavior:
+  notes:
+    - shown controls visibility.
+    - closable enables user dismissal.
+
+ai_notes:
+  do:
+    - Use UiAlert for inline feedback that should stay in normal layout flow.
+  avoid:
+    - Do not use it as a replacement for modal confirmation.

package/docs/profiles/UiAvatar.yml

@@ -0,0 +1,36 @@
+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
+
+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
+
+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.
+  avoid:
+    - Do not use it where UiImage is the better semantic fit.

package/docs/profiles/UiAvatarList.yml

@@ -0,0 +1,30 @@
+component: UiAvatarList
+summary: >
+  UiAvatarList renders a compact list of avatars with consistent sizing. It is useful for showing
+  several users or actors in a narrow area.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiAvatarList
+
+related_components:
+  - UiAvatar
+
+use_when:
+  - You need a short list of user avatars.
+  - You need a compact representation of several people.
+
+avoid_when:
+  - You need full profile cards or detailed user rows.
+
+api:
+  key_props:
+    - name: avatars
+    - name: size
+
+ai_notes:
+  do:
+    - Use for compact grouped identity display.
+  avoid:
+    - Do not use it as a replacement for a full people list.

package/docs/profiles/UiButton.yml

@@ -0,0 +1,221 @@
+component: UiButton
+summary: >
+  UiButton is the main action component in the library. It covers primary, secondary,
+  tertiary, and outlined use cases, can render as either a button or an anchor,
+  and adapts well to text-plus-icon and icon-only content.
+
+public_import:
+  from: '@retailcrm/embed-ui-v1-components/remote'
+  named:
+    - UiButton
+
+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.
+  - You need a clickable element that follows the standard visual language.
+  - You need a link that should read visually as a button.
+
+avoid_when:
+  - You need an inline text link in copy, use UiLink instead.
+  - You need toolbar-specific semantics, use UiToolbarButton or UiToolbarLink instead.
+  - You need a toggle with its own state model, not a simple action.
+
+api:
+  key_props:
+    - name: appearance
+      values:
+        - primary
+        - secondary
+        - tertiary
+        - outlined
+      notes: Defines visual priority.
+    - name: variant
+      values:
+        - default
+        - success
+        - danger
+      notes: Defines semantic color treatment.
+    - name: size
+      values:
+        - lg
+        - md
+        - sm
+        - xs
+      notes: Affects height and paddings.
+    - name: href
+      notes: If present, the root renders as an anchor.
+    - name: disabled
+      notes: Disables interaction and enables disabled styling.
+  props:
+    - name: type
+      notes: Native button type for button shape.
+    - name: active
+      notes: Enables pressed-like visual state.
+    - name: locked
+      notes: Separate locked state distinct from disabled.
+  slots:
+    - name: default
+      zone: content
+      creates: The full inner content of the button.
+      accepts:
+        recommended:
+          - text
+          - text plus one icon
+          - icon component
+          - svg
+        avoid:
+          - block layout containers
+          - nested buttons or links
+          - long rich markup trees
+      layout_effect: Text and icon nodes are normalized into inner spans; icon-only content can produce a square button.
+      notes: Main button content, usually text plus optional icons.
+  methods:
+    - name: click
+      notes: Triggers a click programmatically.
+    - name: focus
+      notes: Focuses the button or anchor root.
+    - name: blur
+      notes: Removes focus.
+
+rendered_structure:
+  descriptive_only: true
+  notes: >
+    This internal DOM description is useful for reasoning, not for styling against implementation details.
+  root:
+    button_shape: button.ui-v1-button
+    link_shape: a.ui-v1-button
+  zones:
+    - .ui-v1-button__content
+    - text span
+    - icon span(s)
+  state_classes:
+    - .ui-v1-button_active
+    - .ui-v1-button_disabled
+    - .ui-v1-button_locked
+
+geometry:
+  layout: inline-block
+  notes:
+    - Size controls dimensions and internal paddings.
+    - Icon-only content leads to a square-like layout through state classes.
+    - The component fits naturally into inline rows, header actions, and compact action zones.
+
+styling:
+  notes:
+    - Props like appearance, variant, size, active, locked, and disabled are the primary styling API.
+    - Internal classes are useful for reasoning and debugging, not a guaranteed selector contract.
+    - The component uses local CSS variables internally, but no dedicated external theme variable set is documented for consumers.
+  root_classes:
+    - .ui-v1-button
+  state_classes:
+    - .ui-v1-button_primary
+    - .ui-v1-button_secondary
+    - .ui-v1-button_tertiary
+    - .ui-v1-button_outlined
+    - .ui-v1-button_success
+    - .ui-v1-button_danger
+    - .ui-v1-button_active
+    - .ui-v1-button_disabled
+    - .ui-v1-button_locked
+    - .ui-v1-button_filled
+    - .ui-v1-button_square
+    - .ui-v1-button_has-leading-icon
+    - .ui-v1-button_has-trailing-icon
+    - .ui-v1-button_lg
+    - .ui-v1-button_md
+    - .ui-v1-button_sm
+    - .ui-v1-button_xs
+  zones:
+    - .ui-v1-button__content
+    - .ui-v1-button__icon
+    - .ui-v1-button__text
+  css_variables:
+    internal_layout_variables:
+      - name: --text-color
+        effect: Current text and icon color.
+      - name: --background-color
+        effect: Current background color for appearance variants.
+      - name: --background-color-active
+        effect: Active background color for variants that use it.
+      - name: --background-color-disabled
+        effect: Disabled background color for variants that use it.
+      - name: --background-image
+        effect: Gradient background for appearances that use it.
+      - name: --border-color-active
+        effect: Active border color in tertiary mode.
+      - name: --border-color-hover
+        effect: Hover border color in tertiary mode.
+      - name: --outlined-color-main
+        effect: Main outline and hover-fill color in outlined mode.
+      - name: --outlined-color-reverse
+        effect: Text color after outlined hover or active inversion.
+  typography:
+    size_variants:
+      - name: lg
+        mixin: h4-accent
+        size: 18px
+        line_height: 28px
+        weight: 500
+      - name: md
+        mixin: text-regular-accent
+        size: 16px
+        line_height: 24px
+        weight: 500
+      - name: sm
+        mixin: text-small-accent
+        size: 14px
+        line_height: 20px
+        weight: 500
+      - name: xs
+        mixin: text-tiny-accent
+        size: 12px
+        line_height: 14px
+        weight: 500
+    notes:
+      - Primary buttons explicitly use medium-like weight.
+      - Outlined buttons raise weight further for stronger label contrast.
+
+behavior:
+  states:
+    - name: appearance
+      notes: Selects the base visual priority.
+    - name: variant
+      notes: Changes semantic color without changing component type.
+    - name: active
+      notes: Enables pressed-like styling.
+    - name: disabled
+      notes: Disables interaction and native button behavior.
+    - name: locked
+      notes: Enables the separate locked state.
+  notes:
+    - If href is present, the component becomes a link-shaped action.
+
+accessibility:
+  notes:
+    - Button shape uses native button semantics.
+    - Anchor shape uses native anchor semantics.
+    - If icons are present, text labeling should remain understandable.
+
+composition:
+  works_well_with:
+    - UiPageHeader actions
+    - UiField
+    - 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:
+    - Start with appearance=primary for the main CTA.
+    - Use secondary or tertiary for neighboring actions near titles.
+  avoid:
+    - Do not replace UiButton with UiLink when the action should read as a button.
+    - Do not use UiButton for regular inline text navigation.

package/docs/profiles/UiCalendar.yml

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

package/docs/profiles/UiCheckbox.yml

@@ -0,0 +1,41 @@
+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
+
+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
+
+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.
+  avoid:
+    - Do not use for mutually exclusive options.

package/docs/profiles/UiCollapse.yml

@@ -0,0 +1,28 @@
+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
+
+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,39 @@
+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
+
+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,27 @@
+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
+
+ai_notes:
+  do:
+    - Use with UiCollapseBox when grouped expansion matters.