yukit-web 0.0.14 → 0.0.16

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yukit-web",
   "description": "Angular UI component library for Yurest web applications.",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "author": {
     "name": "Yurest Solutions",
     "email": "develop@yurest.com"

package/src/lib/theme/components/button-group.css

@@ -0,0 +1,36 @@
+yuw-button-group > yuw-button > :is(button, a) {
+  border-radius: 0;
+}
+
+yuw-button-group[data-orientation='vertical'] > yuw-button,
+yuw-button-group[data-orientation='vertical'] > yuw-button > :is(button, a) {
+  width: 100%;
+}
+
+yuw-button-group[data-orientation='horizontal'] > yuw-button:not(:first-child) > :is(button, a) {
+  border-inline-start-width: 0;
+}
+
+yuw-button-group[data-orientation='vertical'] > yuw-button:not(:first-child) > :is(button, a) {
+  border-block-start-width: 0;
+}
+
+yuw-button-group[data-orientation='horizontal'] > yuw-button:first-child > :is(button, a) {
+  border-start-start-radius: var(--radius);
+  border-end-start-radius: var(--radius);
+}
+
+yuw-button-group[data-orientation='horizontal'] > yuw-button:last-child > :is(button, a) {
+  border-start-end-radius: var(--radius);
+  border-end-end-radius: var(--radius);
+}
+
+yuw-button-group[data-orientation='vertical'] > yuw-button:first-child > :is(button, a) {
+  border-start-start-radius: var(--radius);
+  border-start-end-radius: var(--radius);
+}
+
+yuw-button-group[data-orientation='vertical'] > yuw-button:last-child > :is(button, a) {
+  border-end-start-radius: var(--radius);
+  border-end-end-radius: var(--radius);
+}

package/src/lib/theme/components/button.css

@@ -0,0 +1,4 @@
+yuw-button[data-yuw-variant='outline'] > :is(button, a):not(:hover) {
+  background-color: transparent;
+  color: var(--foreground);
+}

package/src/lib/theme/theme.css

@@ -9,10 +9,11 @@
 /**
  * Spartan css overwrites
  */
+@import './components/button.css';
+@import './components/button-group.css';
 @import './spartan-overwrites/accordion.css';
 
 @layer base {
-
   *,
   ::after,
   ::before {
@@ -30,12 +31,12 @@
   }
 
   button:not(:disabled),
-  [role="button"]:not(:disabled) {
+  [role='button']:not(:disabled) {
     cursor: pointer;
   }
 
   button:disabled,
-  [role="button"]:disabled {
+  [role='button']:disabled {
     cursor: not-allowed;
   }
 

package/types/yukit-web.d.ts

@@ -106,63 +106,10 @@ interface YuwTextFieldContract {
 type YuwColorDto = 'primary' | 'secondary' | 'destructive' | 'success' | 'warning' | 'info' | 'muted' | 'violet';
 
 /**
- * A single entry in `<yuw-button>`'s `buttons` input, which turns it into a welded button group.
+ * A single action button, rendered as a `<button>` or, when `href` is set, an `<a>`.
  *
- * variant`, `size` and `color` are optional and fall back to the component-level inputs of the
- * same name, so a uniform row stays `{id, label}` entries plus one `variant`, and only the odd
- * one out carries its own.
- *
- * `label` is data the parent supplies, not a component-owned default — the same i18n rule
- * `YuwBreadcrumbItemDto` and `YuwSelectOptionDto` follow.
- */
-interface YuwButtonGroupItemDto {
-    id: string;
-    label: string;
-    kind?: 'button';
-    variant?: ButtonVariants['variant'];
-    size?: ButtonVariants['size'];
-    color?: YuwColorDto;
-    disabled?: boolean;
-    href?: string;
-    target?: string;
-    type?: 'button' | 'submit' | 'reset';
-    ariaLabel?: string;
-    yuwDropdownMenuTrigger?: TemplateRef<unknown> | undefined;
-    transparent?: boolean;
-}
-/**
- * A static, non-interactive segment welded into the same row as the buttons — a leading caption, a
- * trailing unit, a checkbox that applies to the whole group.
- *
- * A separate type rather than optional fields on `YuwButtonGroupItemDto`: a text segment honors none
- * of that interface's button surface, and merging them would hand consumers fields that silently do
- * nothing on half the entries.
- *
- * `label` renders as-is. For content a string can't express (a `yuw-checkbox`, custom markup),
- * declare an `<ng-template yuwButtonGroupText="<id>">` whose id matches this entry; the template
- * wins over `label` when both are present.
- */
-interface YuwButtonGroupTextDto {
-    id: string;
-    kind: 'text';
-    label?: string;
-}
-/**
- * What `<yuw-button>`'s `buttons` input accepts: buttons, text segments, in whatever order the
- * consumer lists them.
- *
- * `kind` is optional on the button variant, so existing `{id, label}` arrays keep working: an entry
- * without `kind` is a button.
- */
-type YuwButtonGroupEntryDto = YuwButtonGroupItemDto | YuwButtonGroupTextDto;
-/** What `<yuw-button>` emits from `buttonClicked` in the group form. */
-interface YuwButtonGroupClickDto {
-    id: string;
-    event: MouseEvent;
-}
-
-/**
- * Button component supporting single action button or grouped button options.
+ * For a welded row of buttons driven by data, use `<yuw-button-group>`, which renders one of these
+ * per entry.
  *
  * Inputs:
  * - `variant`: Button style variant (`'default'`, `'secondary'`, `'outline'`, `'destructive'`, `'ghost'`, `'link'`). Default is `'default'`.
@@ -173,60 +120,34 @@ interface YuwButtonGroupClickDto {
  * - `href`: Renders button as an anchor tag navigating to specified URL.
  * - `target`: Target attribute for link button (e.g. `'_blank'`).
  * - `transparent`: Removes background and border styling.
- * - `class`: Extra CSS classes merged onto the inner button/anchor (single and link mode); merged last, so they win over the component's own classes.
+ * - `class`: Extra CSS classes merged onto the inner button/anchor; merged last, so they win over the component's own classes.
  * - `yuwDropdownMenuTrigger`: Optional dropdown menu template reference to trigger.
  * - `ariaLabel`: Accessible label for screen readers.
- * - `buttons`: Array of group entries (`YuwButtonGroupEntryDto[]`) to render as a welded button group.
- *   A `kind: 'text'` entry renders a static, non-interactive segment instead of a button; give it an
- *   `<ng-template yuwButtonGroupText="<id>">` to fill it with markup rather than a plain `label`.
- * - `orientation`: Group layout orientation (`'horizontal'` or `'vertical'`). Default is `'horizontal'`.
- * - `groupAriaLabel`: Accessible name for button group container.
  *
  * Outputs:
- * - `clicked`: Emits MouseEvent on single button click.
- * - `buttonClicked`: Emits object containing clicked button `id` and `event` in group mode.
+ * - `clicked`: Emits MouseEvent on click.
  *
  * `_btnClass` merges our variant layer with the consumer's `class`, which goes last so it wins.
  *
- * `_resolved` gives each group entry everything its branch of the template needs. A text entry has
- * no variant/size/color to fall back to, so it takes its own path rather than being run through the
- * button resolver, which would invent fields its DTO doesn't declare. Its content template is looked
- * up through a `Map` rather than a per-entry `.find()`, which would make an n-entry group cost n².
- *
  * The host carries `inline-flex` so it is a real box rather than an inline one: an overlay trigger
  * directive composed onto `<yuw-button>` (see `YuwPopoverTriggerDirective`) anchors its panel to the
  * host element, and an inline host reports a rect that misses the button's own box. Elements that
  * need to be positioned — an overlay's close button, for instance — get a positioned wrapper around
  * `<yuw-button>` rather than relying on the host's own display.
  *
- * Single Button Usage:
+ * Usage:
  * ```html
  * <yuw-button variant="outline" color="primary" (clicked)="onSave()">Save</yuw-button>
  * <yuw-button href="/dashboard">Navigate</yuw-button>
  * ```
- *
- * Button Group Usage:
- * ```html
- * <yuw-button [buttons]="actionList" (buttonClicked)="onAction($event)" />
- *
- * <yuw-button [buttons]="[{id: 'caption', kind: 'text', label: 'Sort by'}, ...sortActions]">
- *   <ng-template yuwButtonGroupText="select-all">
- *     <yuw-checkbox [(checked)]="allSelected" />
- *   </ng-template>
- * </yuw-button>
- * ```
  */
 declare class YuwButtonComponent {
     private readonly _host;
-    private readonly _texts;
     readonly animationDisabled: _angular_core.InputSignal<boolean>;
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    readonly buttons: _angular_core.InputSignal<YuwButtonGroupEntryDto[] | undefined>;
     readonly color: _angular_core.InputSignal<YuwColorDto>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    readonly groupAriaLabel: _angular_core.InputSignal<string | undefined>;
     readonly href: _angular_core.InputSignal<string | undefined>;
-    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
     readonly size: _angular_core.InputSignal<"default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined>;
     readonly target: _angular_core.InputSignal<string | undefined>;
     readonly transparent: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -234,63 +155,173 @@ declare class YuwButtonComponent {
     readonly userClass: _angular_core.InputSignal<string>;
     readonly variant: _angular_core.InputSignal<"default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined>;
     readonly yuwDropdownMenuTrigger: _angular_core.InputSignal<TemplateRef<unknown> | undefined>;
-    readonly buttonClicked: _angular_core.OutputEmitterRef<YuwButtonGroupClickDto>;
     readonly clicked: _angular_core.OutputEmitterRef<MouseEvent>;
-    protected readonly _textClass = "bg-transparent text-foreground border-border dark:border-input";
     protected readonly _animationDisabled: _angular_core.Signal<boolean>;
-    protected readonly _effectiveVariant: _angular_core.Signal<"default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined>;
     protected readonly _btnClass: _angular_core.Signal<string>;
-    protected readonly _isGroup: _angular_core.Signal<boolean>;
-    protected readonly _resolved: _angular_core.Signal<({
-        template: TemplateRef<unknown> | undefined;
-        id: string;
-        kind: "text";
-        label?: string;
-    } | {
+    protected readonly _effectiveVariant: _angular_core.Signal<"default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined>;
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwButtonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<YuwButtonComponent, "yuw-button", never, { "animationDisabled": { "alias": "animationDisabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "href": { "alias": "href"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "target": { "alias": "target"; "required": false; "isSignal": true; }; "transparent": { "alias": "transparent"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "yuwDropdownMenuTrigger": { "alias": "yuwDropdownMenuTrigger"; "required": false; "isSignal": true; }; }, { "clicked": "clicked"; }, never, ["[yuwButtonIcon]", "*", "[yuwButtonIcon]", "*"], true, never>;
+}
+
+/**
+ * A single button in `<yuw-button-group>`'s `buttons` input.
+ *
+ * Every field mirrors the `<yuw-button>` input of the same name. A field declared here wins over the
+ * group-level input of the same name — the group sets the row's base, an entry states its specific
+ * case — so a uniform row is `{id, label}` entries plus one group-level `variant`, and only the odd
+ * one out carries its own.
+ *
+ * `label` renders as plain text. For markup a string can't express, declare an
+ * `<ng-template yuwButtonGroupContent="<id>">` whose id matches this entry; the template wins over
+ * `label` when both are present. `label` is data the parent supplies, not a component-owned
+ * default, so the consuming app owns translation.
+ *
+ * `interactive: false` renders the entry as inert chrome — transparent, no hover, no click, not
+ * focusable — for a caption or a unit welded into the row.
+ *
+ * `selected` marks the entry as the active one in a segmented row, so the parent flips one boolean
+ * rather than rewriting appearance across the array on every click. It resolves most-specific
+ * first: this entry's `selectedColor`, then its `color`, then the group's `selectedColor`, then the
+ * group's `color`. An entry declaring `selectedColor` therefore keeps it even in a group that sets
+ * its own, which is the point — the entry is the specific case.
+ */
+interface YuwButtonGroupItemDto {
+    id: string;
+    label?: string;
+    variant?: ButtonVariants['variant'];
+    size?: ButtonVariants['size'];
+    color?: YuwColorDto;
+    transparent?: boolean;
+    selected?: boolean;
+    selectedVariant?: ButtonVariants['variant'];
+    selectedColor?: YuwColorDto;
+    interactive?: boolean;
+    disabled?: boolean;
+    href?: string;
+    target?: string;
+    type?: 'button' | 'submit' | 'reset';
+    ariaLabel?: string;
+    yuwDropdownMenuTrigger?: TemplateRef<unknown>;
+}
+/** What `<yuw-button-group>` emits from `buttonClicked`. */
+interface YuwButtonGroupClickDto {
+    id: string;
+    event: MouseEvent;
+}
+
+/**
+ * A welded row of buttons driven by data.
+ *
+ * Each entry renders a real `<yuw-button>`, so every button input — `variant`, `color`, `size`,
+ * `transparent`, `href`, the dropdown trigger — behaves inside the group exactly as it does on a
+ * standalone button, and the theme's `data-yuw-color` layer applies unchanged. The group only owns
+ * what a row adds: which corners stay rounded and which side draws each seam.
+ *
+ * Inputs:
+ * - `buttons`: The entries to render (`YuwButtonGroupItemDto[]`), in order.
+ * - `variant`, `size`, `color`: The row's base appearance. An entry that declares its own wins,
+ *   since a per-entry value is by definition the specific case.
+ * - `selectedVariant`, `selectedColor`: The row's appearance for an entry marked `selected`,
+ *   mirroring `variant`/`color`. Unset by default, in which case a selected entry keeps the row's
+ *   `variant`/`color` unless it states its own.
+ * - `orientation`: Layout direction (`'horizontal'`, `'vertical'`). Default is `'horizontal'`.
+ *   The seams rotate with it: a vertical group's entries own their bottom border and round only
+ *   their top (first) or bottom (last) corners.
+ * - `ariaLabel`: Accessible name for the `role="group"` container. User-facing text the consuming
+ *   app is responsible for translating.
+ *
+ * Outputs:
+ * - `buttonClicked`: Emits the clicked entry's `id` and the `MouseEvent`. An entry with
+ *   `interactive: false` is inert chrome and never emits.
+ *
+ * An entry's content is its `label`, or an `<ng-template yuwButtonGroupContent="<id>">` when it
+ * needs markup instead of a string.
+ *
+ * `_resolved` walks the entries once, resolving each value most-specific-first: the entry's
+ * state-matching field, then the entry's base field, then the group's state-matching input, then
+ * the group's base. An entry always outranks the group, so an entry carrying `selectedColor` keeps
+ * it in a row that sets its own — the entry is the specific case by definition. Every step is
+ * `undefined` until someone sets it, so no level can be shadowed by a hardcoded default.
+ * Content templates are read from a `Map` rather than a per-entry `.find()`, which would make an
+ * n-entry group cost n².
+ *
+ * Seams are pure CSS (`theme/components/button-group.css`), not classes. The helm's base `border`
+ * sets all four sides and re-applies its own radius at runtime through `classes()`, and tailwind-
+ * merge cannot drop a side from `border` — `border-y border-e` only re-asserts widths, leaving the
+ * leading border in place, which is what made each entry draw its own left edge and tint the seam
+ * with the wrong entry's color. The stylesheet zeroes the leading border width and owns the corners,
+ * where no utility class can displace it.
+ *
+ * Usage:
+ * ```html
+ * <yuw-button-group [buttons]="alignActions" (buttonClicked)="onAction($event)" />
+ *
+ * <yuw-button-group [buttons]="entries" variant="outline" color="primary">
+ *   <ng-template yuwButtonGroupContent="count">
+ *     <yuw-badge>{{ total() }}</yuw-badge>
+ *   </ng-template>
+ * </yuw-button-group>
+ * ```
+ */
+declare class YuwButtonGroupComponent {
+    private readonly _contents;
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    readonly buttons: _angular_core.InputSignal<readonly YuwButtonGroupItemDto[]>;
+    readonly color: _angular_core.InputSignal<YuwColorDto>;
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    readonly selectedColor: _angular_core.InputSignal<YuwColorDto | undefined>;
+    readonly selectedVariant: _angular_core.InputSignal<"default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined>;
+    readonly size: _angular_core.InputSignal<"default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined>;
+    readonly variant: _angular_core.InputSignal<"default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined>;
+    readonly buttonClicked: _angular_core.OutputEmitterRef<YuwButtonGroupClickDto>;
+    protected readonly _resolved: _angular_core.Signal<{
+        interactive: boolean;
+        template: _angular_core.TemplateRef<unknown> | undefined;
         variant: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | null | undefined;
         size: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
         color: YuwColorDto;
+        transparent: boolean;
         disabled: boolean;
         type: "button" | "submit" | "reset";
         class: string;
         id: string;
-        label: string;
-        kind?: "button";
+        label?: string;
+        selected?: boolean;
+        selectedVariant?: ButtonVariants["variant"];
+        selectedColor?: YuwColorDto;
         href?: string;
         target?: string;
         ariaLabel?: string;
-        yuwDropdownMenuTrigger?: TemplateRef<unknown> | undefined;
-        transparent?: boolean;
-    })[]>;
-    protected onClick(event: MouseEvent): void;
-    protected onGroupClick(button: YuwButtonGroupItemDto, event: MouseEvent): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwButtonComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<YuwButtonComponent, "yuw-button", never, { "animationDisabled": { "alias": "animationDisabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "buttons": { "alias": "buttons"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "groupAriaLabel": { "alias": "groupAriaLabel"; "required": false; "isSignal": true; }; "href": { "alias": "href"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "target": { "alias": "target"; "required": false; "isSignal": true; }; "transparent": { "alias": "transparent"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "yuwDropdownMenuTrigger": { "alias": "yuwDropdownMenuTrigger"; "required": false; "isSignal": true; }; }, { "buttonClicked": "buttonClicked"; "clicked": "clicked"; }, ["_texts"], ["[yuwButtonIcon]", "*", "[yuwButtonIcon]", "*"], true, never>;
+        yuwDropdownMenuTrigger?: _angular_core.TemplateRef<unknown>;
+    }[]>;
+    protected onClick(entry: YuwButtonGroupItemDto, event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwButtonGroupComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<YuwButtonGroupComponent, "yuw-button-group", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "buttons": { "alias": "buttons"; "required": true; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "selectedColor": { "alias": "selectedColor"; "required": false; "isSignal": true; }; "selectedVariant": { "alias": "selectedVariant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; }, { "buttonClicked": "buttonClicked"; }, ["_contents"], never, true, never>;
 }
 
 /**
- * Declares the content of a single text segment inside `<yuw-button>`'s button group. Apply it to
- * an `<ng-template>` and pass the id of the `kind: 'text'` entry it belongs to, matching an entry
- * in the `buttons` input.
+ * Declares the content of a single entry inside `<yuw-button-group>`. Apply it to an
+ * `<ng-template>` and pass the id of the entry it belongs to.
  *
- * Exists because a text segment often isn't text — a checkbox, a badge, an icon with a count — and a
- * component cannot travel through a data array. An entry whose id has no matching template falls
- * back to its `label`, so the plain-string case needs no template at all.
+ * Exists because an entry's content often isn't a string — an icon with a count, a checkbox, a
+ * badge — and markup cannot travel through a data array. An entry whose id has no matching
+ * template falls back to its `label`, so the plain-string case needs no template at all.
  *
  * Usage:
  * ```html
- * <yuw-button [buttons]="entries">
- *   <ng-template yuwButtonGroupText="select-all">
+ * <yuw-button-group [buttons]="entries">
+ *   <ng-template yuwButtonGroupContent="select-all">
  *     <yuw-checkbox [(checked)]="allSelected" />
  *   </ng-template>
- * </yuw-button>
+ * </yuw-button-group>
  * ```
  */
-declare class YuwButtonGroupTextDirective {
+declare class YuwButtonGroupContentDirective {
     readonly templateRef: TemplateRef<unknown>;
     readonly entryId: _angular_core.InputSignal<string>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwButtonGroupTextDirective, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<YuwButtonGroupTextDirective, "ng-template[yuwButtonGroupText]", never, { "entryId": { "alias": "yuwButtonGroupText"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwButtonGroupContentDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<YuwButtonGroupContentDirective, "ng-template[yuwButtonGroupContent]", never, { "entryId": { "alias": "yuwButtonGroupContent"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -2645,6 +2676,18 @@ declare class YuwSidebarRailService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<YuwSidebarRailService>;
 }
 
+/**
+ * - `src`: image URL. Omit to show `fallback` alone, which is also what a failed load falls back to.
+ * - `alt`: accessible name of the image, supplied already translated. Set it to `''` when `label`
+ *   already names the same thing, so a screen reader does not read the name twice.
+ * - `fallback`: initials shown while the image loads, fails, or is absent. Not optional: an avatar
+ *   with no `src` and no `fallback` is an empty circle.
+ */
+interface YuwSidebarAvatarDto {
+    alt: string;
+    fallback: string;
+    src?: string;
+}
 /**
  * Where a sidebar entry points.
  *
@@ -2697,6 +2740,10 @@ interface YuwSidebarSubItemDto extends YuwSidebarNavigationDto {
  * navigates and toggles.
  *
  * - `label`: text of the entry, supplied already translated — the sidebar owns no user-facing copy.
+ * - `avatar`: image identifying a person or entity, rendered in place of `icon` at 40px. An entry
+ *   with one is taller than an icon entry — the avatar is what sets the row height, expanded and on
+ *   the rail alike. `icon` is ignored when both are given, since they compete for the one leading
+ *   slot; pass whichever the entry actually is rather than both.
  * - `icon`: name of a registered `@ng-icons` icon. Because the *consumer* chooses this name, the
  *   consuming app is responsible for `provideIcons()`-ing it; `provideIcons` is a component-level
  *   provider, so a name registered on the component hosting the sidebar resolves here through the
@@ -2712,6 +2759,7 @@ interface YuwSidebarSubItemDto extends YuwSidebarNavigationDto {
 interface YuwSidebarItemDto extends YuwSidebarNavigationDto {
     id: string;
     label: string;
+    avatar?: YuwSidebarAvatarDto;
     icon?: string;
     badge?: string;
     tooltip?: string;
@@ -2814,7 +2862,10 @@ declare class YuwSidebarSubmenuService {
  *   button that reports through `itemClicked`. An item with `children` gets a submenu that follows
  *   the sidebar's own state: an accordion while the panel is open, and a sheet sliding out beside the
  *   rail once it is collapsed to icons, so nested entries stay reachable there. Its `expanded`
- *   field seeds the accordion; the item holding the active route opens on its own.
+ *   field seeds the accordion; the item holding the active route opens on its own. An item may lead
+ *   with an `avatar` instead of an `icon` — a user account or a venue — which renders at 40px and
+ *   makes that row taller than an icon row in both states, and combines with `children` like any
+ *   other entry.
  * - `footer`: The same, rendered into the footer region.
  *
  * Outputs:
@@ -3125,6 +3176,36 @@ declare class YuwSidebarMenuButtonDirective {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwSidebarMenuButtonDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<YuwSidebarMenuButtonDirective, "button[yuwSidebarMenuButton], a[yuwSidebarMenuButton]", never, {}, {}, never, never, true, [{ directive: typeof i1$d.HlmSidebarMenuButton; inputs: { "variant": "variant"; "size": "size"; "isActive": "isActive"; "closeMobileSidebarOnClick": "closeMobileSidebarOnClick"; }; outputs: {}; }]>;
 }
+/**
+ * Applied alongside `[yuwSidebarMenuButton]` on an entry whose leading slot is a 40px avatar rather
+ * than a 16px icon, carrying {@link yuwSidebarMenuAvatarButtonClass}.
+ *
+ * A directive rather than a `[class]` binding on the button, because a binding cannot win this
+ * merge. `classes()` (helm/utils) applies its registered *sources* in registration order and then
+ * appends the element's `baseClasses` — captured from the static `class` host attribute — last. An
+ * Angular `[class]` binding is neither: it writes the `class` attribute directly, races the
+ * `className` assignment `classes()` makes for its own sources, and is reclassified by the library's
+ * MutationObserver only after the fact. The observed result was the helm's `h-8` surviving and the
+ * override being dropped, leaving the 40px avatar clipped inside a 32px `overflow-hidden` button.
+ * Registering as another source puts this class after both the helm's and
+ * `[yuwSidebarMenuButton]`'s, which is the ordering `twMerge` needs to displace them.
+ *
+ * Separate from `[yuwSidebarMenuButton]` rather than an input on it, because the two are not the same
+ * role: this is the geometry of one kind of entry, and an entry either leads with an avatar or it does
+ * not. Hand-written markup applies it bare (`<a yuwSidebarMenuButton yuwSidebarMenuAvatarButton>`)
+ * next to its own `<yuw-avatar>`.
+ *
+ * It carries a value because `YuwSidebarNavComponent` renders every entry through the same three
+ * branches and cannot attach a directive conditionally — an attribute selector matches on presence, so
+ * the nav applies it to every entry and passes whether that entry actually has an avatar. Its default
+ * is `true` so the bare, hand-written form needs no value.
+ */
+declare class YuwSidebarMenuAvatarButtonDirective {
+    readonly enabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwSidebarMenuAvatarButtonDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<YuwSidebarMenuAvatarButtonDirective, "[yuwSidebarMenuAvatarButton]", never, { "enabled": { "alias": "yuwSidebarMenuAvatarButton"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
 /** Trailing count or status badge of a sidebar menu item. */
 declare class YuwSidebarMenuBadgeDirective {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<YuwSidebarMenuBadgeDirective, never>;
@@ -3180,5 +3261,5 @@ declare const YUW_SIDEBAR_RAIL_PADDING = "22px";
 declare const YUW_SIDEBAR_RAIL_ICON_SIZE = "20px";
 declare const YUW_SIDEBAR_RAIL_WIDTH = "78px";
 
-export { DATATABLE_ALIGN_CLASS, YUW_PASSWORD_REVEAL_STATES, YUW_SIDEBAR_RAIL_ICON_SIZE, YUW_SIDEBAR_RAIL_PADDING, YUW_SIDEBAR_RAIL_WIDTH, YuwAccordion, YuwAccordionContentComponent, YuwAccordionImports, YuwAccordionItem, YuwAccordionTriggerComponent, YuwAlertActionDirective, YuwAlertComponent, YuwAlertDescriptionDirective, YuwAlertDialogComponent, YuwAlertDialogMediaDirective, YuwAlertDialogTriggerDirective, YuwAlertImports, YuwAlertTitleDirective, YuwAttachmentActionDirective, YuwAttachmentActionsDirective, YuwAttachmentContentDirective, YuwAttachmentDescriptionDirective, YuwAttachmentDirective, YuwAttachmentGroupDirective, YuwAttachmentMediaDirective, YuwAttachmentTitleDirective, YuwAttachmentTriggerDirective, YuwAvatarComponent, YuwBadgeComponent, YuwBreadcrumbComponent, YuwButtonComponent, YuwButtonGroupTextDirective, YuwCaptionDirective, YuwCardActionDirective, YuwCardContentDirective, YuwCardDescriptionDirective, YuwCardDirective, YuwCardFooterDirective, YuwCardHeaderDirective, YuwCardImports, YuwCardTitleDirective, YuwCheckboxComponent, YuwComboboxComponent, YuwComboboxItemDirective, YuwContextMenuCheckboxDirective, YuwContextMenuCheckboxIndicatorComponent, YuwContextMenuDirective, YuwContextMenuGroupDirective, YuwContextMenuImports, YuwContextMenuItemDirective, YuwContextMenuLabelDirective, YuwContextMenuRadioDirective, YuwContextMenuRadioIndicatorComponent, YuwContextMenuSeparatorDirective, YuwContextMenuShortcutDirective, YuwContextMenuSubDirective, YuwContextMenuSubIndicatorComponent, YuwContextMenuSubTriggerDirective, YuwContextMenuTriggerDirective, YuwDatatableComponent, YuwDatatablePaginationDirective, YuwDatatableRowSelect, YuwDatepickerComponent, YuwDialogCloseDirective, YuwDialogComponent, YuwDialogFooterDirective, YuwDialogImports, YuwDialogTriggerDirective, YuwEmptyContentDirective, YuwEmptyDescriptionDirective, YuwEmptyDirective, YuwEmptyHeaderDirective, YuwEmptyImports, YuwEmptyMediaDirective, YuwEmptyTitleDirective, YuwInputAddonImports, YuwInputComponent, YuwInputOtpComponent, YuwItemActionsDirective, YuwItemContentDirective, YuwItemDescriptionDirective, YuwItemDirective, YuwItemFooterDirective, YuwItemGroupDirective, YuwItemHeaderDirective, YuwItemImports, YuwItemMediaDirective, YuwItemSeparatorDirective, YuwItemTitleDirective, YuwLabel, YuwLeftAddonDirective, YuwPaginationComponent, YuwPasswordInputComponent, YuwPopoverComponent, YuwPopoverTriggerDirective, YuwRadioGroupComponent, YuwRightAddonDirective, YuwSearchInputComponent, YuwSheetCloseDirective, YuwSheetComponent, YuwSheetFooterDirective, YuwSheetImports, YuwSheetTriggerDirective, YuwSidebarComponent, YuwSidebarContentDirective, YuwSidebarContentExtraDirective, YuwSidebarFooterDirective, YuwSidebarFooterExtraDirective, YuwSidebarGroupContentDirective, YuwSidebarGroupDirective, YuwSidebarGroupLabelDirective, YuwSidebarHeaderDirective, YuwSidebarInsetDirective, YuwSidebarMenuBadgeDirective, YuwSidebarMenuButtonDirective, YuwSidebarMenuDirective, YuwSidebarMenuItemDirective, YuwSidebarMenuSubButtonDirective, YuwSidebarMenuSubDirective, YuwSidebarMenuSubItemDirective, YuwSidebarRailDirective, YuwSidebarRailService, YuwSidebarSeparatorDirective, YuwSidebarSubmenuService, YuwSidebarTriggerComponent, YuwSidebarWrapperDirective, YuwSkeletonDirective, YuwSpinnerComponent, YuwSwitchComponent, YuwTBodyDirective, YuwTFootDirective, YuwTHeadDirective, YuwTabPanelDirective, YuwTableContainerDirective, YuwTableDirective, YuwTableImports, YuwTabsComponent, YuwTdDirective, YuwTextareaComponent, YuwThDirective, YuwToasterComponent, YuwTooltipDirective, YuwTrDirective, YuwValueAccessorBase, buildInputOtpGroups, cn, datatableCellVariants, datatableContainerVariants, datatableHeadVariants, datatableHeaderCellVariants, datatableRowVariants, getPaginationRange, provideValueAccessor, totalInputOtpLength };
-export type { YuwAlertDialogSizeDto, YuwAlertVariantDto, YuwAvatarGroupItemDto, YuwAvatarSizeDto, YuwBreadcrumbItemDto, YuwButtonGroupClickDto, YuwButtonGroupEntryDto, YuwButtonGroupItemDto, YuwButtonGroupTextDto, YuwColorDto, YuwComboboxItemContext, YuwComboboxOptionDto, YuwComboboxValue, YuwDatatableAlign, YuwDatatableAppearanceDto, YuwDatatableColumnDef, YuwDatepickerModeDto, YuwDatepickerValue, YuwFieldSizeDto, YuwInputModeDto, YuwInputOtpGroupDto, YuwInputOtpModeDto, YuwInputTypeDto, YuwPaginationRangeItem, YuwPaginationSizeDto, YuwPasswordRevealStateDto, YuwPopoverAlignDto, YuwRadioOptionDto, YuwSearchInputCollapseFromDto, YuwSheetScrollStrategyDto, YuwSheetSideDto, YuwSidebarCollapsibleDto, YuwSidebarContentDto, YuwSidebarGroupDto, YuwSidebarItemClickDto, YuwSidebarItemDto, YuwSidebarSideDto, YuwSidebarSubItemDto, YuwSidebarVariantDto, YuwSwitchSizeDto, YuwTabItemDto, YuwTabsActivationModeDto, YuwTabsOrientationDto, YuwTabsVariantDto, YuwTextFieldContract, YuwToasterPositionDto, YuwToasterThemeDto, YuwTooltipPositionDto };
+export { DATATABLE_ALIGN_CLASS, YUW_PASSWORD_REVEAL_STATES, YUW_SIDEBAR_RAIL_ICON_SIZE, YUW_SIDEBAR_RAIL_PADDING, YUW_SIDEBAR_RAIL_WIDTH, YuwAccordion, YuwAccordionContentComponent, YuwAccordionImports, YuwAccordionItem, YuwAccordionTriggerComponent, YuwAlertActionDirective, YuwAlertComponent, YuwAlertDescriptionDirective, YuwAlertDialogComponent, YuwAlertDialogMediaDirective, YuwAlertDialogTriggerDirective, YuwAlertImports, YuwAlertTitleDirective, YuwAttachmentActionDirective, YuwAttachmentActionsDirective, YuwAttachmentContentDirective, YuwAttachmentDescriptionDirective, YuwAttachmentDirective, YuwAttachmentGroupDirective, YuwAttachmentMediaDirective, YuwAttachmentTitleDirective, YuwAttachmentTriggerDirective, YuwAvatarComponent, YuwBadgeComponent, YuwBreadcrumbComponent, YuwButtonComponent, YuwButtonGroupComponent, YuwButtonGroupContentDirective, YuwCaptionDirective, YuwCardActionDirective, YuwCardContentDirective, YuwCardDescriptionDirective, YuwCardDirective, YuwCardFooterDirective, YuwCardHeaderDirective, YuwCardImports, YuwCardTitleDirective, YuwCheckboxComponent, YuwComboboxComponent, YuwComboboxItemDirective, YuwContextMenuCheckboxDirective, YuwContextMenuCheckboxIndicatorComponent, YuwContextMenuDirective, YuwContextMenuGroupDirective, YuwContextMenuImports, YuwContextMenuItemDirective, YuwContextMenuLabelDirective, YuwContextMenuRadioDirective, YuwContextMenuRadioIndicatorComponent, YuwContextMenuSeparatorDirective, YuwContextMenuShortcutDirective, YuwContextMenuSubDirective, YuwContextMenuSubIndicatorComponent, YuwContextMenuSubTriggerDirective, YuwContextMenuTriggerDirective, YuwDatatableComponent, YuwDatatablePaginationDirective, YuwDatatableRowSelect, YuwDatepickerComponent, YuwDialogCloseDirective, YuwDialogComponent, YuwDialogFooterDirective, YuwDialogImports, YuwDialogTriggerDirective, YuwEmptyContentDirective, YuwEmptyDescriptionDirective, YuwEmptyDirective, YuwEmptyHeaderDirective, YuwEmptyImports, YuwEmptyMediaDirective, YuwEmptyTitleDirective, YuwInputAddonImports, YuwInputComponent, YuwInputOtpComponent, YuwItemActionsDirective, YuwItemContentDirective, YuwItemDescriptionDirective, YuwItemDirective, YuwItemFooterDirective, YuwItemGroupDirective, YuwItemHeaderDirective, YuwItemImports, YuwItemMediaDirective, YuwItemSeparatorDirective, YuwItemTitleDirective, YuwLabel, YuwLeftAddonDirective, YuwPaginationComponent, YuwPasswordInputComponent, YuwPopoverComponent, YuwPopoverTriggerDirective, YuwRadioGroupComponent, YuwRightAddonDirective, YuwSearchInputComponent, YuwSheetCloseDirective, YuwSheetComponent, YuwSheetFooterDirective, YuwSheetImports, YuwSheetTriggerDirective, YuwSidebarComponent, YuwSidebarContentDirective, YuwSidebarContentExtraDirective, YuwSidebarFooterDirective, YuwSidebarFooterExtraDirective, YuwSidebarGroupContentDirective, YuwSidebarGroupDirective, YuwSidebarGroupLabelDirective, YuwSidebarHeaderDirective, YuwSidebarInsetDirective, YuwSidebarMenuAvatarButtonDirective, YuwSidebarMenuBadgeDirective, YuwSidebarMenuButtonDirective, YuwSidebarMenuDirective, YuwSidebarMenuItemDirective, YuwSidebarMenuSubButtonDirective, YuwSidebarMenuSubDirective, YuwSidebarMenuSubItemDirective, YuwSidebarRailDirective, YuwSidebarRailService, YuwSidebarSeparatorDirective, YuwSidebarSubmenuService, YuwSidebarTriggerComponent, YuwSidebarWrapperDirective, YuwSkeletonDirective, YuwSpinnerComponent, YuwSwitchComponent, YuwTBodyDirective, YuwTFootDirective, YuwTHeadDirective, YuwTabPanelDirective, YuwTableContainerDirective, YuwTableDirective, YuwTableImports, YuwTabsComponent, YuwTdDirective, YuwTextareaComponent, YuwThDirective, YuwToasterComponent, YuwTooltipDirective, YuwTrDirective, YuwValueAccessorBase, buildInputOtpGroups, cn, datatableCellVariants, datatableContainerVariants, datatableHeadVariants, datatableHeaderCellVariants, datatableRowVariants, getPaginationRange, provideValueAccessor, totalInputOtpLength };
+export type { YuwAlertDialogSizeDto, YuwAlertVariantDto, YuwAvatarGroupItemDto, YuwAvatarSizeDto, YuwBreadcrumbItemDto, YuwButtonGroupClickDto, YuwButtonGroupItemDto, YuwColorDto, YuwComboboxItemContext, YuwComboboxOptionDto, YuwComboboxValue, YuwDatatableAlign, YuwDatatableAppearanceDto, YuwDatatableColumnDef, YuwDatepickerModeDto, YuwDatepickerValue, YuwFieldSizeDto, YuwInputModeDto, YuwInputOtpGroupDto, YuwInputOtpModeDto, YuwInputTypeDto, YuwPaginationRangeItem, YuwPaginationSizeDto, YuwPasswordRevealStateDto, YuwPopoverAlignDto, YuwRadioOptionDto, YuwSearchInputCollapseFromDto, YuwSheetScrollStrategyDto, YuwSheetSideDto, YuwSidebarAvatarDto, YuwSidebarCollapsibleDto, YuwSidebarContentDto, YuwSidebarGroupDto, YuwSidebarItemClickDto, YuwSidebarItemDto, YuwSidebarSideDto, YuwSidebarSubItemDto, YuwSidebarVariantDto, YuwSwitchSizeDto, YuwTabItemDto, YuwTabsActivationModeDto, YuwTabsOrientationDto, YuwTabsVariantDto, YuwTextFieldContract, YuwToasterPositionDto, YuwToasterThemeDto, YuwTooltipPositionDto };