ngx-com 0.0.1 → 0.0.4

package/types/ngx-com-components-item.d.ts

@@ -0,0 +1,336 @@
+import * as i0 from '@angular/core';
+import { TemplateRef, InputSignal, InputSignalWithTransform, Signal } from '@angular/core';
+import { AvatarSize, AvatarColor } from 'ngx-com/components/avatar';
+import { IconSize } from 'ngx-com/components/icon';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Marker directive for projecting custom leading content into a com-item.
+ *
+ * When this directive is present, it completely replaces the default
+ * leading visual (which would otherwise be a com-avatar with an icon).
+ * Use this for custom avatars (with images or initials), bare icons,
+ * custom images, or any other leading visual.
+ *
+ * @example Custom avatar with image
+ * ```html
+ * <com-item title="Jane Doe" description="jane@example.com">
+ *   <ng-template comItemLeading>
+ *     <com-avatar src="/photos/jane.jpg" name="Jane Doe" size="sm" />
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Avatar stack
+ * ```html
+ * <com-item title="3 collaborators">
+ *   <ng-template comItemLeading>
+ *     <div class="flex -space-x-2">
+ *       <com-avatar name="A" size="xs" variant="outline" />
+ *       <com-avatar name="B" size="xs" variant="outline" />
+ *     </div>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ */
+declare class ComItemLeading {
+    readonly templateRef: TemplateRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItemLeading, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComItemLeading, "ng-template[comItemLeading]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marker directive for projecting custom title content into a com-item.
+ *
+ * When this directive is present, it replaces the `title` input with
+ * rich projected content. Use this when the title needs formatting,
+ * links, or other custom markup.
+ *
+ * @example Title with link
+ * ```html
+ * <com-item icon="link">
+ *   <ng-template comItemTitle>
+ *     <a href="/docs/api" class="hover:underline">API Documentation</a>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ */
+declare class ComItemTitle {
+    readonly templateRef: TemplateRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItemTitle, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComItemTitle, "ng-template[comItemTitle]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marker directive for projecting inline suffix content after the title.
+ *
+ * Content appears on the same line as the title, immediately after it.
+ * Use this for badges, tags, status indicators, or other inline metadata.
+ *
+ * @example Badge suffix
+ * ```html
+ * <com-item title="My BP datasource" description="View and manage configuration">
+ *   <ng-template comItemSuffix>
+ *     <span class="inline-flex items-center gap-1 rounded-pill border border-primary/30 bg-primary-subtle px-2 py-0.5 text-xs font-medium text-primary">
+ *       Bluetooth
+ *     </span>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ */
+declare class ComItemSuffix {
+    readonly templateRef: TemplateRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItemSuffix, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComItemSuffix, "ng-template[comItemSuffix]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marker directive for projecting custom description content into a com-item.
+ *
+ * When this directive is present, it replaces the `description` input
+ * with rich projected content. Use this when the description needs
+ * formatting, code snippets, or other custom markup.
+ *
+ * @example Description with code
+ * ```html
+ * <com-item title="API Key" icon="key">
+ *   <ng-template comItemDescription>
+ *     <code class="text-xs font-mono text-muted-foreground">sk-abc...xyz</code>
+ *     <span class="text-xs text-muted-foreground"> · Created 3 days ago</span>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ */
+declare class ComItemDescription {
+    readonly templateRef: TemplateRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItemDescription, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComItemDescription, "ng-template[comItemDescription]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marker directive for projecting trailing content into a com-item.
+ *
+ * Content appears at the far right edge of the item. Use this for
+ * action buttons, navigation chevrons, toggles, timestamps, or
+ * any other trailing content.
+ *
+ * @example Trailing chevron
+ * ```html
+ * <com-item title="Settings" icon="settings" [interactive]="true">
+ *   <ng-template comItemTrailing>
+ *     <com-icon name="chevron-right" size="sm" color="muted" />
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Trailing action button
+ * ```html
+ * <com-item title="API Key" icon="key">
+ *   <ng-template comItemTrailing>
+ *     <button class="text-sm text-primary hover:text-primary-hover">Revoke</button>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ */
+declare class ComItemTrailing {
+    readonly templateRef: TemplateRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItemTrailing, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComItemTrailing, "ng-template[comItemTrailing]", never, {}, {}, never, never, true, never>;
+}
+
+/** Item size variants. */
+type ItemSize = 'sm' | 'md' | 'lg';
+/** Item density variants. */
+type ItemDensity = 'compact' | 'default' | 'comfortable';
+/**
+ * CVA variants for the item container (host element).
+ *
+ * @tokens `--color-primary-subtle`, `--color-muted`, `--color-ring`
+ */
+declare const itemVariants: (props?: {
+    size?: ItemSize;
+    density?: ItemDensity;
+    interactive?: boolean;
+    active?: boolean;
+    disabled?: boolean;
+}) => string;
+/** Title classes keyed by item size. */
+declare const ITEM_TITLE_CLASSES: Record<ItemSize, string>;
+/** Description classes keyed by item size. */
+declare const ITEM_DESCRIPTION_CLASSES: Record<ItemSize, string>;
+/** Avatar size mapping keyed by item size. */
+declare const ITEM_AVATAR_SIZES: Record<ItemSize, AvatarSize>;
+/** Icon size mapping keyed by item size (for icon inside avatar). */
+declare const ITEM_ICON_SIZES: Record<ItemSize, IconSize>;
+type ItemVariants = VariantProps<typeof itemVariants>;
+
+/**
+ * Item component — a universal compound display element that shows a leading
+ * visual alongside a title, an optional description, and optional trailing content.
+ *
+ * Works in all these contexts:
+ * - List rows (device lists, settings menus, search results)
+ * - Page/section headers
+ * - Dropdown menu items
+ * - Table cells
+ * - Card headers
+ * - Nav items
+ *
+ * **Anatomy:**
+ * ```
+ * ┌─────────────────────────────────────────────────────────┐
+ * │  ┌───────┐                                              │
+ * │  │com-   │  Title text  ·  [inline suffix]   [TRAILING] │
+ * │  │avatar │  Description text (secondary)                │
+ * │  └───────┘                                              │
+ * └─────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * Five content zones:
+ * 1. **Leading visual** — optional. Default: `com-avatar` with `shape="rounded"` + `variant="soft"`.
+ *    Override via `comItemLeading` directive.
+ * 2. **Title** — primary text. Required (via input or projection).
+ * 3. **Inline suffix** — same line as title, after it. For badges, tags, status dots.
+ * 4. **Description** — secondary text below title. Optional.
+ * 5. **Trailing** — far-right aligned. Actions, chevrons, timestamps.
+ *
+ * @tokens `--color-primary-subtle`, `--color-muted`, `--color-muted-foreground`,
+ *         `--color-foreground`, `--color-ring`
+ *
+ * @example Simplest — text only, no icon
+ * ```html
+ * <com-item title="Select all" />
+ * ```
+ *
+ * @example Icon + title + description (most common)
+ * ```html
+ * <com-item
+ *   title="Dexcom G7"
+ *   description="109123c2d2194bffe519b03ceb51730d5064f9de46c54c4e..."
+ *   icon="smartphone"
+ * />
+ * ```
+ *
+ * @example Icon with different color
+ * ```html
+ * <com-item title="Warning detected" icon="alert-triangle" iconColor="warn" />
+ * <com-item title="Active" icon="check-circle" iconColor="accent" />
+ * ```
+ *
+ * @example Page header with badge suffix (size lg)
+ * ```html
+ * <com-item
+ *   title="My BP datasource"
+ *   description="View and manage datasource configuration"
+ *   size="lg"
+ * >
+ *   <ng-template comItemSuffix>
+ *     <span class="inline-flex items-center gap-1 rounded-pill border border-primary/30 bg-primary-subtle px-2 py-0.5 text-xs font-medium text-primary">
+ *       <com-icon name="bluetooth" size="xs" /> Bluetooth
+ *     </span>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Custom leading — user avatar with image
+ * ```html
+ * <com-item title="Jane Doe" description="jane@example.com">
+ *   <ng-template comItemLeading>
+ *     <com-avatar src="/photos/jane.jpg" name="Jane Doe" size="sm" />
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Interactive list item with trailing chevron
+ * ```html
+ * <com-item
+ *   title="Bluetooth Settings"
+ *   description="Manage paired devices"
+ *   icon="bluetooth"
+ *   [interactive]="true"
+ *   (click)="openSettings()"
+ * >
+ *   <ng-template comItemTrailing>
+ *     <com-icon name="chevron-right" size="sm" color="muted" />
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Compact density — dropdown menu
+ * ```html
+ * @for (option of options; track option.value) {
+ *   <com-item
+ *     [title]="option.label"
+ *     [icon]="option.icon"
+ *     density="compact"
+ *     [interactive]="true"
+ *     [active]="option.value === selected()"
+ *     (click)="select(option)"
+ *   />
+ * }
+ * ```
+ *
+ * @example Rich description via projection
+ * ```html
+ * <com-item title="API Key" icon="key">
+ *   <ng-template comItemDescription>
+ *     <code class="text-xs font-mono text-muted-foreground">sk-abc...xyz</code>
+ *     <span class="text-xs text-muted-foreground"> · Created 3 days ago</span>
+ *   </ng-template>
+ *   <ng-template comItemTrailing>
+ *     <button class="text-sm text-primary hover:text-primary-hover">Revoke</button>
+ *   </ng-template>
+ * </com-item>
+ * ```
+ *
+ * @example Disabled
+ * ```html
+ * <com-item
+ *   title="Enterprise Features"
+ *   description="Available on Enterprise plan"
+ *   icon="crown"
+ *   [disabled]="true"
+ * />
+ * ```
+ */
+declare class ComItem {
+    /** Primary text. Required unless using comItemTitle directive. */
+    readonly title: InputSignal<string | undefined>;
+    /** Secondary text below the title. */
+    readonly description: InputSignal<string | undefined>;
+    /** Lucide icon name — renders inside a com-avatar container. */
+    readonly icon: InputSignal<string | undefined>;
+    /** Color variant passed to the leading com-avatar. */
+    readonly iconColor: InputSignal<AvatarColor>;
+    /** Size variant affecting typography and spacing. */
+    readonly size: InputSignal<ItemSize>;
+    /** Density variant affecting vertical padding. */
+    readonly density: InputSignal<ItemDensity>;
+    /** Enables hover/active/focus states. */
+    readonly interactive: InputSignalWithTransform<boolean, unknown>;
+    /** Shows selected/active highlight. */
+    readonly active: InputSignalWithTransform<boolean, unknown>;
+    /** Dims and disables pointer events. */
+    readonly disabled: InputSignalWithTransform<boolean, unknown>;
+    /** Truncates title and description text. */
+    readonly truncate: InputSignalWithTransform<boolean, unknown>;
+    protected readonly leadingDirective: Signal<ComItemLeading | undefined>;
+    protected readonly titleDirective: Signal<ComItemTitle | undefined>;
+    protected readonly suffixDirective: Signal<ComItemSuffix | undefined>;
+    protected readonly descriptionDirective: Signal<ComItemDescription | undefined>;
+    protected readonly trailingDirective: Signal<ComItemTrailing | undefined>;
+    /** Resolved icon color (handles 'auto' → 'primary' for items since there's no name). */
+    protected readonly resolvedIconColor: Signal<AvatarColor>;
+    /** Avatar size mapped from item size. */
+    protected readonly avatarSize: Signal<AvatarSize>;
+    /** Icon size mapped from item size. */
+    protected readonly iconSize: Signal<IconSize>;
+    /** Title typography classes based on size. */
+    protected readonly titleClasses: Signal<string>;
+    /** Description typography classes based on size. */
+    protected readonly descriptionClasses: Signal<string>;
+    /** Host element classes from CVA. */
+    protected readonly hostClasses: Signal<string>;
+    protected onKeyboardActivate(event: Event): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComItem, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComItem, "com-item", ["comItem"], { "title": { "alias": "title"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconColor": { "alias": "iconColor"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "truncate": { "alias": "truncate"; "required": false; "isSignal": true; }; }, {}, ["leadingDirective", "titleDirective", "suffixDirective", "descriptionDirective", "trailingDirective"], never, true, never>;
+}
+
+export { ComItem, ComItemDescription, ComItemLeading, ComItemSuffix, ComItemTitle, ComItemTrailing, ITEM_AVATAR_SIZES, ITEM_DESCRIPTION_CLASSES, ITEM_ICON_SIZES, ITEM_TITLE_CLASSES, itemVariants };
+export type { ItemDensity, ItemSize, ItemVariants };