@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-avatar-group.d.ts

@@ -0,0 +1,119 @@
+import * as _angular_core from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvAvatarSize, MlvAvatarShape } from '@malva-ui/core/avatar';
+
+/**
+ * Represents a single member in the avatar group.
+ * Provides enough data to render a `mlv-avatar` for each member.
+ */
+interface MlvAvatarGroupMember {
+    /** Full display name — used for initials derivation, popup label, and aria-label. */
+    name: string;
+    /** Optional image URL. Falls back to initials or color on error. */
+    src?: string | null;
+    /** Explicit initials string; overrides name-derived initials. */
+    initials?: string;
+    /** CSS color for the avatar background. Defaults to a deterministic color from name. */
+    color?: string;
+}
+/**
+ * Avatar group component rendering a horizontal stack of overlapping `mlv-avatar` instances.
+ *
+ * The visible count is calculated automatically based on the component's container width —
+ * no manual `max` input is needed. When members overflow, an avatar-styled `+N` counter
+ * is appended. Hovering or focusing the counter opens a popup listing every member.
+ * Clicking anywhere on the host emits `groupClick`; clicking the `+N` counter also
+ * emits `overflowClick`.
+ *
+ * The component fills its parent (uses `width: 100%` flex layout). Set a width or
+ * `max-width` on the host to constrain the visible count.
+ *
+ * @example
+ * ```html
+ * <mlv-avatar-group
+ *   [members]="team"
+ *   size="m"
+ *   (groupClick)="openMembersPanel($event)"
+ *   style="max-width: 200px"
+ * />
+ * ```
+ */
+declare class MlvAvatarGroup {
+    /**
+     * The full list of members to represent.
+     * How many are visible is determined automatically by the container width.
+     */
+    readonly members: _angular_core.InputSignal<MlvAvatarGroupMember[]>;
+    /**
+     * Size variant applied to all avatars (including the overflow counter avatar).
+     * Matches `MlvAvatarSize`: `'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl'`.
+     * Defaults to `'m'`.
+     */
+    readonly size: _angular_core.InputSignal<MlvAvatarSize>;
+    /**
+     * Shape applied to all avatars in the group.
+     * Defaults to `'circle'`.
+     */
+    readonly shape: _angular_core.InputSignal<MlvAvatarShape>;
+    /**
+     * When `true`, the group is exposed as a keyboard-operable button.
+     */
+    readonly interactive: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Emits the full member array when the user clicks anywhere on the group host.
+     */
+    readonly groupClick: _angular_core.OutputEmitterRef<MlvAvatarGroupMember[]>;
+    /**
+     * Emits the hidden (overflow) members when the user clicks the `+N` counter avatar.
+     * Event propagation is stopped before the host `groupClick` fires separately.
+     */
+    readonly overflowClick: _angular_core.OutputEmitterRef<MlvAvatarGroupMember[]>;
+    /** @private Host element ref, observed for width to auto-calculate the visible count. */
+    private readonly _el;
+    /** @private Shared resize-observer service used to track the host width. */
+    private readonly _resizeService;
+    /** @private Localised avatar-group messages. */
+    private readonly _i18n;
+    /** @private ICU resolver for count-aware accessible labels. */
+    private readonly _resolver;
+    /** Measured width of the host element in pixels. 0 = not yet measured. */
+    private readonly _containerWidth;
+    /** Avatar size in pixels for the current `size()` input. */
+    private readonly _avatarSizePx;
+    /**
+     * Maximum total avatars (visible + overflow) that fit in the current container.
+     * Returns `Infinity` before the first ResizeObserver measurement so that
+     * all members are shown during the initial render pass.
+     */
+    private readonly _maxFit;
+    /** Members within the auto-calculated visible limit — rendered as individual avatars. */
+    protected readonly _visibleMembers: _angular_core.Signal<MlvAvatarGroupMember[]>;
+    /** Members beyond the visible limit — shown in the overflow popup. */
+    protected readonly _hiddenMembers: _angular_core.Signal<MlvAvatarGroupMember[]>;
+    /** Number of hidden members. */
+    protected readonly _overflowCount: _angular_core.Signal<number>;
+    /** Whether the overflow counter avatar should render. */
+    protected readonly _hasOverflow: _angular_core.Signal<boolean>;
+    /** Label shown inside the overflow counter avatar, e.g. `"+5"`. */
+    protected readonly _overflowLabel: _angular_core.Signal<string>;
+    /** Accessible label for the group host element. */
+    protected readonly _hostAriaLabel: _angular_core.Signal<string>;
+    /** Localised label for the overflow trigger. */
+    protected readonly _overflowAriaLabel: _angular_core.Signal<string>;
+    /** Localised label for the complete member list. */
+    protected readonly _allMembersLabel: _angular_core.Signal<string>;
+    constructor();
+    /** Handles click on the overflow counter avatar. */
+    protected _onOverflowClick(event: MouseEvent): void;
+    /** Handles keydown on the overflow counter avatar. */
+    protected _onOverflowKeydown(event: KeyboardEvent): void;
+    /** Handles click on the group host. */
+    protected _onHostClick(): void;
+    /** Activates an interactive group with the standard button keys. */
+    protected _onHostKeydown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvAvatarGroup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvAvatarGroup, "mlv-avatar-group", never, { "members": { "alias": "members"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; }, { "groupClick": "groupClick"; "overflowClick": "overflowClick"; }, never, never, true, never>;
+}
+
+export { MlvAvatarGroup };
+export type { MlvAvatarGroupMember };

package/types/malva-ui-core-avatar.d.ts

@@ -0,0 +1,156 @@
+import * as _angular_core from '@angular/core';
+import { PipeTransform } from '@angular/core';
+
+/** Available size variants for the avatar component. */
+type MlvAvatarSize = 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl';
+/** Available shape variants for the avatar component. */
+type MlvAvatarShape = 'circle' | 'square';
+/**
+ * Derives initials from a name string.
+ * Takes the first letter of each space-separated part, max 2.
+ *
+ * @example
+ * deriveInitials('John Doe')         // 'JD'
+ * deriveInitials('Alice')            // 'A'
+ * deriveInitials('John Michael Doe') // 'JD'
+ * deriveInitials('')                 // ''
+ */
+declare function deriveInitials(name: string): string;
+/**
+ * Avatar component displaying a user or entity representation.
+ *
+ * Supports image URLs, text initials (explicit or derived from a name),
+ * arbitrary projected content (e.g. icons), and an optional label below.
+ *
+ * Content priority: `src` image > `initials`/`name` > `ng-content`.
+ *
+ * @example
+ * ```html
+ * <mlv-avatar name="John Doe" [color]="'John Doe' | mlvColorFromText" />
+ * <mlv-avatar src="https://example.com/avatar.jpg" label="John Doe" />
+ * <mlv-avatar size="xl" shape="square" initials="JD" color="#5770cb" />
+ * ```
+ */
+declare class MlvAvatar {
+    /**
+     * The size variant of the avatar.
+     * Maps to predefined width/height and font-size values.
+     */
+    readonly size: _angular_core.InputSignal<MlvAvatarSize>;
+    /**
+     * The shape of the avatar visual container.
+     * `circle` is fully rounded; `square` uses `--mlv-radius-2` (8px).
+     */
+    readonly shape: _angular_core.InputSignal<MlvAvatarShape>;
+    /**
+     * Optional image URL. When provided, the avatar displays an image.
+     * A loading skeleton is shown while the image loads.
+     * On error, falls back to initials or projected content.
+     */
+    readonly src: _angular_core.InputSignal<string | null>;
+    /**
+     * A name string from which initials are automatically derived.
+     * Takes the first character of each space-separated word, up to 2 characters.
+     * E.g. "John Doe" → "JD", "Alice" → "A", "John Michael Doe" → "JD".
+     * Ignored when `initials` is explicitly set.
+     */
+    readonly name: _angular_core.InputSignal<string>;
+    /**
+     * Explicit initials string. When provided, overrides initials derived from `name`.
+     */
+    readonly initials: _angular_core.InputSignal<string>;
+    /**
+     * CSS color value for the avatar background.
+     * Accepts any valid CSS color: hex, rgb, hsl, CSS custom property reference.
+     * Defaults to `var(--mlv-text-secondary)`.
+     */
+    readonly color: _angular_core.InputSignal<string>;
+    /**
+     * Optional label text displayed below the avatar.
+     * Long text is gracefully faded at the edges using `MlvFade`.
+     */
+    readonly label: _angular_core.InputSignal<string>;
+    /**
+     * @internal Whether the image has successfully loaded.
+     */
+    protected readonly _imageLoaded: _angular_core.WritableSignal<boolean>;
+    /**
+     * @internal Whether the image encountered a load error.
+     */
+    protected readonly _imageError: _angular_core.WritableSignal<boolean>;
+    /**
+     * @internal Computed background color style value.
+     * Returns the `color` input if set, otherwise the default CSS variable.
+     */
+    protected readonly _backgroundColor: _angular_core.Signal<string>;
+    /**
+     * @internal Resolved initials to display.
+     * Uses explicit `initials` input first, then derives from `name`.
+     */
+    protected readonly _resolvedInitials: _angular_core.Signal<string>;
+    /**
+     * @internal Accessible name for the avatar as a whole.
+     * Prefers the display `name`, falling back to the `label`. Returns `null`
+     * when neither is set so the host stays role-less (see host bindings).
+     */
+    protected readonly _accessibleName: _angular_core.Signal<string | null>;
+    /**
+     * @internal Whether to show the image element (src provided and no error).
+     */
+    protected readonly _showImage: _angular_core.Signal<boolean>;
+    /**
+     * @internal Whether to show the loading skeleton.
+     */
+    protected readonly _showSkeleton: _angular_core.Signal<boolean>;
+    /**
+     * @internal Whether to show initials (no valid image, and initials are available).
+     */
+    protected readonly _showInitials: _angular_core.Signal<boolean>;
+    /**
+     * @internal Whether to show projected ng-content (no valid image and no initials).
+     */
+    protected readonly _showContent: _angular_core.Signal<boolean>;
+    /**
+     * @internal Label words split for individual MlvFade wrapping.
+     */
+    protected readonly _labelWords: _angular_core.Signal<string[]>;
+    /**
+     * @internal Handles the image load event.
+     */
+    protected _onImageLoad(): void;
+    /**
+     * @internal Handles the image error event.
+     */
+    protected _onImageError(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvAvatar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvAvatar, "mlv-avatar", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "shape": { "alias": "shape"; "required": false; "isSignal": true; }; "src": { "alias": "src"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "initials": { "alias": "initials"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Converts a string to an HSL CSS color by hashing the string characters into a hue (0–360).
+ *
+ * Hue is the only thing the name controls. Saturation stays near 60% and lightness
+ * near 80% so every derived color is a **pale tint** that carries dark text at AA
+ * — per AB-R6 of the 2026-08 visual language spec, a name-derived avatar is a quiet
+ * identity marker, not an accent-carrying mark competing for the view's accent budget.
+ * Callers that want no identity hue at all simply omit `[color]`; `mlv-avatar` then
+ * falls back to `--mlv-text-secondary`.
+ *
+ * @example
+ * {{ 'John Doe' | mlvColorFromText }}  // 'hsl(147,58%,78%)'
+ * {{ 'Alice' | mlvColorFromText }}     // 'hsl(88,63%,83%)'
+ */
+declare class MlvColorFromTextPipe implements PipeTransform {
+    /**
+     * Transforms a string into a deterministic HSL color value.
+     *
+     * @param value - The string to convert. Returns a default color for empty strings.
+     * @returns A CSS `hsl(...)` string.
+     */
+    transform(value: string | null | undefined): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvColorFromTextPipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<MlvColorFromTextPipe, "mlvColorFromText", true>;
+}
+
+export { MlvAvatar, MlvColorFromTextPipe, deriveInitials };
+export type { MlvAvatarShape, MlvAvatarSize };

package/types/malva-ui-core-badge.d.ts

@@ -0,0 +1,97 @@
+import * as _angular_core from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvTone } from '@malva-ui/cdk/utils';
+import * as i1 from '@malva-ui/cdk/density';
+
+/** Which side of the badge label a `[mlvBadgeIcon]` renders on. */
+type MlvBadgeIconPosition = 'start' | 'end';
+/**
+ * Marks a projected element as the badge's icon slot. The badge sizes it from
+ * its own density-driven font size and adds the label gap, so consumers do not
+ * have to hand-tune `width`/`height` per density.
+ *
+ * The icon is decorative by default (`aria-hidden="true"`): a badge normally
+ * repeats the icon's meaning in its label. When the icon is the badge's only
+ * content, give the badge itself an accessible name.
+ *
+ * @example
+ * ```html
+ * <mlv-badge tone="success" muted>
+ *   <svg lucideCheck mlvBadgeIcon />
+ *   Published
+ * </mlv-badge>
+ *
+ * <mlv-badge tone="info">
+ *   Syncing
+ *   <svg lucideRefreshCw mlvBadgeIcon position="end" />
+ * </mlv-badge>
+ * ```
+ */
+declare class MlvBadgeIcon {
+    /**
+     * Where the icon sits relative to the badge label. `'start'` (the default)
+     * keeps it leading; `'end'` moves it after the label. Both are reordered by
+     * CSS, so the icon can stay wherever it reads best in the template.
+     */
+    readonly position: _angular_core.InputSignal<MlvBadgeIconPosition>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvBadgeIcon, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvBadgeIcon, "[mlvBadgeIcon]", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Available tone variants for the badge component.
+ * Extends the shared {@link MlvTone} semantic vocabulary with neutral and
+ * brand options, mapping to color tokens in the design system.
+ */
+type MlvBadgeTone = MlvTone | 'default' | 'primary' | 'secondary' | 'accent';
+/**
+ * Badge component for displaying short status labels, counts, or tags.
+ * Supports solid and muted color modes across all semantic tone variants,
+ * with full density system integration.
+ *
+ * A projected `[mlvBadgeIcon]` is sized and spaced by the badge itself and can
+ * be moved to either side with the directive's `position` input.
+ *
+ * @example
+ * ```html
+ * <mlv-badge tone="success">Active</mlv-badge>
+ * <mlv-badge tone="danger" muted>Deprecated</mlv-badge>
+ * <mlv-badge tone="primary" mlvDensity="compact">New</mlv-badge>
+ * <mlv-badge tone="success" muted>
+ *   <svg lucideCheck mlvBadgeIcon />
+ *   Published
+ * </mlv-badge>
+ * ```
+ */
+declare class MlvBadge {
+    /**
+     * The semantic tone of the badge.
+     * Determines the background and text colors.
+     * Defaults to `'default'` (neutral).
+     */
+    readonly tone: _angular_core.InputSignal<MlvBadgeTone>;
+    /**
+     * @deprecated No-op. Badges always render with fully rounded (pill)
+     * corners via `--mlv-radius-full`; this input has never affected the
+     * rendered radius and is kept only so existing `[rounded]` bindings keep
+     * compiling. Override `border-radius` on `.mlv-badge` if you need a
+     * different shape.
+     */
+    readonly rounded: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * When `true`, uses muted surface/text tokens instead of solid fill colors.
+     * Muted badges are less visually prominent and suit inline or decorative contexts.
+     * Supports attribute usage: `<mlv-badge muted>` or `<mlv-badge [muted]="true">`.
+     */
+    readonly muted: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * @protected Projected `[mlvBadgeIcon]`, if any. Only its presence is used —
+     * it adds the label gap, so a badge without an icon keeps its former spacing.
+     */
+    protected readonly _iconRef: _angular_core.Signal<MlvBadgeIcon | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvBadge, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvBadge, "mlv-badge", never, { "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "muted": { "alias": "muted"; "required": false; "isSignal": true; }; }, {}, ["_iconRef"], ["[mlvBadgeIcon]", "*"], true, [{ directive: typeof i1.MlvDensityDirective; inputs: { "mlvDensity": "mlvDensity"; }; outputs: {}; }]>;
+}
+
+export { MlvBadge, MlvBadgeIcon };
+export type { MlvBadgeIconPosition, MlvBadgeTone };

package/types/malva-ui-core-bottom-nav.d.ts

@@ -0,0 +1,104 @@
+import * as _angular_core from '@angular/core';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { MlvNavItem } from '@malva-ui/cdk/utils';
+
+/** MlvLayout direction for icon and label within each navigation item. */
+type MlvBottomNavStacking = 'vertical' | 'horizontal';
+/** Controls when item labels are visible. */
+type MlvBottomNavLabelVisibility = 'always' | 'active-only';
+/**
+ * Fixed bottom navigation bar for mobile contexts.
+ * Renders up to 5 items; overflows into a synthetic "More" item
+ * that opens a menu with the hidden items.
+ *
+ * Supports two activation modes:
+ * - **Router mode** (default): active state is driven by `routerLinkActive`.
+ *   Items are rendered as `<a>` elements with `routerLink`.
+ * - **Managed mode**: when `activeIndex` is provided, active state is
+ *   controlled by the consumer. Items are rendered as `<button>` elements
+ *   and clicks emit on the `itemClick` output.
+ *
+ * Also supports vertical/horizontal stacking, active-only label visibility,
+ * and per-item disabled state.
+ *
+ * @example
+ * <mlv-bottom-nav *mlvBreakpointDown="'md'" [items]="navItems" />
+ *
+ * @example
+ * <mlv-bottom-nav [items]="navItems" [activeIndex]="selected" (itemClick)="selected = $event" />
+ */
+declare class MlvBottomNav {
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvBottomNavI18n>;
+    /**
+     * Navigation items to display.
+     * Up to 5 items are shown; if more than 5 are provided,
+     * the first 4 are rendered and a "More" button opens a menu with the overflow items.
+     */
+    readonly items: _angular_core.InputSignal<MlvNavItem[]>;
+    /** Accessible label for the nav landmark. */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * MlvLayout direction for icon and label within each item.
+     * - `'vertical'` (default): icon on top, label below.
+     * - `'horizontal'`: icon on the left, label on the right, vertically centered.
+     */
+    readonly stacking: _angular_core.InputSignal<MlvBottomNavStacking>;
+    /**
+     * Controls when item labels are visible.
+     * - `'always'` (default): labels are always shown on all items.
+     * - `'active-only'`: labels are hidden by default and smoothly revealed
+     *   only on the active (current route) item. The "More" button label
+     *   is always visible regardless of this setting.
+     */
+    readonly labelVisibility: _angular_core.InputSignal<MlvBottomNavLabelVisibility>;
+    /**
+     * Index of the active item in managed mode.
+     * When provided (even as `0`), the component switches to managed mode:
+     * items render as `<button>` elements instead of `<a routerLink>` and
+     * the active class is driven by this index rather than the router.
+     */
+    readonly activeIndex: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Emits the index of the clicked item in managed mode.
+     * Not emitted for disabled items or in router mode.
+     */
+    readonly itemClick: _angular_core.OutputEmitterRef<number>;
+    /** @private Router for programmatic navigation from overflow menu items. */
+    private readonly _router;
+    /**
+     * @protected Whether the component is in managed (non-router) mode.
+     * True when `activeIndex` has been explicitly provided.
+     */
+    protected readonly _isManaged: _angular_core.Signal<boolean>;
+    /**
+     * @protected Items displayed as direct nav links in the bar.
+     * All items if total <= MAX_VISIBLE, otherwise the first (MAX_VISIBLE - 1).
+     */
+    protected readonly _displayItems: _angular_core.Signal<MlvNavItem[]>;
+    /**
+     * @protected Items that overflow into the "More" menu.
+     * Empty if total <= MAX_VISIBLE.
+     */
+    protected readonly _overflowItems: _angular_core.Signal<MlvNavItem[]>;
+    /**
+     * @protected Whether the bar has overflow items requiring a "More" button.
+     */
+    protected readonly _hasOverflow: _angular_core.Signal<boolean>;
+    /**
+     * @protected Handles click on a visible item in managed mode.
+     * Emits the item's index on `itemClick`.
+     */
+    protected _onItemClick(index: number): void;
+    /**
+     * @protected Handles click on an overflow menu item.
+     * In managed mode, emits the global index on `itemClick`.
+     * In router mode, navigates to the item's route.
+     */
+    protected _onOverflowItemClick(overflowIndex: number): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvBottomNav, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvBottomNav, "mlv-bottom-nav", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "stacking": { "alias": "stacking"; "required": false; "isSignal": true; }; "labelVisibility": { "alias": "labelVisibility"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, never, true, never>;
+}
+
+export { MlvBottomNav };
+export type { MlvBottomNavLabelVisibility, MlvBottomNavStacking };