@aceshooting/lyra-ui 4.1.0 → 5.0.0

package/dist/components/conversation/chat-message/chat-message.class.d.ts

@@ -0,0 +1,206 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../../internal/lyra-element.js';
+import '../../utility/live-region/live-region.class.js';
+export type ChatMessageRole = 'user' | 'assistant' | 'system';
+export type ChatMessageStatus = 'sending' | 'sent' | 'failed' | 'streaming';
+export interface LyraChatMessageEventMap {
+    'lr-retry': CustomEvent<{
+        messageId?: string;
+    }>;
+    'lr-collapse-toggle': CustomEvent<boolean>;
+}
+/**
+ * `<lr-chat-message>` — a role-based message bubble *shell* for a chat/
+ * agent conversation surface. It renders none of the message content itself:
+ * the default slot carries whatever a consumer wants to display (plain
+ * text, a `<lr-markdown>`, a custom template, anything at all) and this
+ * component only supplies the surrounding chrome — alignment/coloring by
+ * `role`, an avatar/badges header row, an optional collapse toggle, an
+ * attachments strip, and a status-aware footer (a live-updating status dot +
+ * text, the formatted `timestamp`, a built-in retry affordance for
+ * `status="failed"`, and an `actions` slot for everything else).
+ *
+ * No built-in copy button is rendered. Deciding what "the copyable text" of
+ * an arbitrary slotted message even means (plain text? the rendered
+ * markdown source? something else?) is exactly the kind of content
+ * interpretation this shell deliberately stays out of — slot a copy control
+ * into `actions` instead. Firing `lr-copy` (`detail: { text }`) from that
+ * control keeps the event name consistent with `<lr-json-viewer>`'s own
+ * copy affordance, for anything listening at the conversation-surface level.
+ *
+ * Accessibility of `status`: the current status is always available as
+ * plain visible text (`[part="status-text"]`), never color alone. A
+ * transition *to* `"failed"`, or *from* `"streaming"` to `"sent"` (a stream
+ * finishing), is additionally announced through an internal
+ * `<lr-live-region>` (see that component's header for the throttled-
+ * announcement wiring this composes) so a screen-reader user who isn't
+ * currently focused on this message still learns about it — *unless* the
+ * `failure` slot has content, in which case this internal announcement is
+ * skipped: the host's own `role="alert"` failure content is expected to
+ * announce itself, and firing both would double-announce the same failure
+ * with two different (and differently specific) messages. This differs
+ * from `<lr-typing-indicator>`'s deliberately simpler `role="status"`
+ * approach — that component only ever has one thing to announce (its own
+ * mount); this one has a `status` that can flip between several values
+ * across a single element's lifetime, which is exactly the coalescing job
+ * `<lr-live-region>` exists for.
+ *
+ * `role` is a message-author role (`user`/`assistant`/`system`, matching
+ * the vocabulary of every chat/completion API), *not* a WAI-ARIA role, so
+ * it reflects to a `data-role` attribute rather than the bare `role`
+ * attribute — `role="user"` would collide with `Element`'s own ARIA `role`
+ * accessor and is not a valid ARIA role token to begin with.
+ *
+ * `actionsOutsideBubble` allows the `actions` slot to render as a sibling
+ * immediately after the message bubble instead of nested inside the footer —
+ * useful for consumers whose action row (e.g., a hover-reveal copy button)
+ * must sit visually outside the bubble's chrome.
+ *
+ * @customElement lr-chat-message
+ * @slot - The message body.
+ * @slot avatar - An avatar/icon for the message author.
+ * @slot badges - Small status/metric chips (e.g. token count, latency, model name) — entirely app-supplied; this component computes none of that itself.
+ * @slot actions - Action controls (e.g. copy, retry), rendered at the end of the footer.
+ * @slot attachments - File/image attachment chips, rendered below the message body by default; see `attachments-position`.
+ * @slot failure - Only ever rendered while `status="failed"`. Empty (the default), the footer keeps
+ *   its built-in `[part="status-text"]`/`[part="retry-button"]` exactly as before. The moment this
+ *   slot has assigned content, that built-in status text and retry button are suppressed — the host
+ *   is now fully responsible for presenting its own failure UI, and the built-in `chatFailedAnnounce`
+ *   live-region announcement is suppressed too (see `@event lr-retry` below for the effect on that
+ *   event, and the "Accessibility of `status`" paragraph above for the built-in announcement this
+ *   replaces). Content assigned here should carry `role="alert"` itself when it represents an
+ *   actionable send failure — this component does not add that role on the host's behalf, since it
+ *   has no way to know what markup the host puts in this slot. This mirrors `lr-flow-node`'s `header`
+ *   slot, which replaces that component's own built-in heading row the same way.
+ * @event lr-retry - Fired by the built-in retry button, only rendered when `status="failed"` and the
+ *   `failure` slot is empty. `detail: { messageId?: string }` includes this element's stable
+ *   `messageId` when supplied, so a conversation surface can identify the message without a
+ *   closure around each row. A host using the `failure` slot owns its own retry control and is not
+ *   required to use this event at all — but nothing stops that control from dispatching its own
+ *   `new CustomEvent('lr-retry', { bubbles: true, composed: true })` to stay consistent with the
+ *   same event contract a listener further up a conversation surface already relies on for every
+ *   other message.
+ * @event lr-collapse-toggle - `detail: boolean` (the new `collapsed` state) — fired when the user activates the built-in collapse button.
+ * @csspart bubble - The message bubble root. Programmatically focusable (`tabindex="-1"`) so focus has a stable place to land when the built-in retry button is removed (e.g. a `lr-retry` listener flipping `status` away from `"failed"`).
+ * @csspart header - The row above the message body — avatar, badges, and the collapse toggle. Hidden entirely when none of those have anything to show.
+ * @csspart avatar - The wrapper around the `avatar` slot.
+ * @csspart badges - The wrapper around the `badges` slot.
+ * @csspart collapse-button - The built-in collapse/expand toggle (only rendered when `collapsible`).
+ * @csspart body - The wrapper around the default slot (the message content). Hidden while `collapsed`.
+ * @csspart attachments - The wrapper around the `attachments` slot.
+ * @csspart failure - The `failure` slot itself (`display: contents` — it contributes no box of its
+ *   own, so the host's own content lays out exactly as if it were a direct child of `bubble`, with no
+ *   `::part(failure)` override needed to get there). Only present in the DOM while `status="failed"`.
+ * @csspart footer - The row below the message body — status, timestamp, retry, and actions. Hidden entirely when none of those have anything to show.
+ * @csspart status-indicator - A small decorative (`aria-hidden`) dot reflecting `status`; absent while `status="sent"`.
+ * @csspart status-text - The visible text twin of `status-indicator` — carries the state in text, not just color.
+ * @csspart timestamp - The formatted `timestamp`, rendered in a `<time>` element.
+ * @csspart retry-button - The built-in retry button (only rendered when `status="failed"`).
+ * @csspart actions - The wrapper around the `actions` slot. Rendered inside the footer by default; a sibling immediately after `bubble` when `actionsOutsideBubble` is set.
+ * @cssprop [--lr-chat-message-max-width=80%] - Maximum inline size of the message bubble.
+ * @cssprop [--lr-transition-ambient=1.8s ease-in-out] - Streaming-indicator animation duration
+ *   and timing function.
+ */
+export declare class LyraChatMessage extends LyraElement<LyraChatMessageEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        status: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+    };
+    /** Who authored the message. Reflects to `data-role` — see the class doc. */
+    role: ChatMessageRole;
+    /** Optional stable application-defined identifier for this message. Included in `lr-retry`
+     *  detail when set. */
+    messageId: string;
+    /** When the message was sent/received. Accepts a `Date` or anything
+     *  `new Date()` can parse (e.g. an ISO 8601 string); invalid input is
+     *  treated the same as unset (no timestamp rendered). */
+    timestamp?: Date | string;
+    /** Overrides the default `hour:minute` rendering of `timestamp` — this
+     *  library has no i18n system of its own, so an overridable formatter is
+     *  the established way to hand locale-sensitive display back to the
+     *  consumer (mirrors `lr-heatmap`'s `cellText`). */
+    formatTimestamp?: (date: Date) => string;
+    /** Shows the built-in collapse/expand toggle in the header. */
+    collapsible: boolean;
+    /** Whether the message body is currently hidden. Effective whenever set,
+     *  independent of `collapsible` — `collapsible` only controls whether the
+     *  built-in toggle button is rendered, mirroring `lr-widget`'s identical
+     *  `collapsible`/`collapsed` pair. */
+    collapsed: boolean;
+    /** Where the `attachments` slot renders relative to the message body.
+     *  `'after'` (the default) reproduces today's exact DOM order. `'before'`
+     *  renders attachments immediately above the body -- both DOM and visual
+     *  order move together (no CSS `order` trick), so reading/focus order
+     *  always matches what's on screen. */
+    attachmentsPosition: 'before' | 'after';
+    /** Renders the `actions` slot's content as a sibling immediately after `[part="bubble"]` instead of
+     *  nested inside `[part="footer"]`'s own padding/background box — for a consumer whose action row
+     *  (e.g. a hover-reveal copy button) must sit visually outside the bubble's chrome. `false` (the
+     *  default) keeps today's exact DOM: actions render inside the footer, inside the bubble. */
+    actionsOutsideBubble: boolean;
+    private hasAvatarSlot;
+    private hasBadgesSlot;
+    private hasAttachmentsSlot;
+    private hasActionsSlot;
+    /** Whether the `failure` slot currently has assigned content. Only meaningful while
+     *  `status === "failed"` -- that's the only time the slot itself is even in the render (see
+     *  `render()`), mirroring `lr-flow-node`'s identical `hasHeaderSlot` flag for its own
+     *  entirely-replaces-the-built-in-UI `header` slot. */
+    private hasFailureSlot;
+    private liveRegion?;
+    private bubbleEl?;
+    private readonly bodyId;
+    private _status;
+    /** The value `status` held immediately before its current one, recorded
+     *  at the point of assignment in the setter below -- *not* derived from
+     *  Lit's `changed`/`changedProperties`, which only ever remembers the
+     *  single oldest value seen since the last completed update. Without this,
+     *  setting `status` to `"streaming"` and then immediately overwriting it
+     *  (e.g. to `"sent"`) within the same task, with no render in between,
+     *  would silently lose the `"streaming"` intermediate value before
+     *  `announceStatusChange` ever gets to see it. */
+    private previousStatus;
+    /** True only until the component's first completed update -- gates the
+     *  status-change announcement below so a message never announces
+     *  whatever status it happens to mount with (mirrors the same "not on
+     *  first paint" intent `willUpdate`'s `!this.hasUpdated` check has for the
+     *  slot-presence flags, except `this.hasUpdated` itself is already `true`
+     *  by the time `updated()` runs for the first time, so it can't be reused
+     *  here). */
+    private isMounting;
+    /** Delivery/generation state. Drives the footer's status dot/text and,
+     *  for `"failed"`, the bubble's danger treatment and the built-in retry
+     *  button. Declared via `static properties` above with a hand-written
+     *  accessor (see `previousStatus`). */
+    get status(): ChatMessageStatus;
+    set status(value: ChatMessageStatus);
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    private hasSlotted;
+    /** Whether `document.activeElement` is (or is inside) one of this host's `slot="failure"`
+     *  children. Slotting doesn't move an element out of the light DOM -- `document.activeElement`
+     *  reports the actual focused node regardless of where Shadow DOM projects it for rendering --
+     *  so this walks the host's real children, same as `hasSlotted` above, rather than anything
+     *  shadow-root-relative. */
+    private isFocusWithinFailureSlot;
+    private get normalizedTimestamp();
+    private get statusText();
+    private announceStatusChange;
+    private onAvatarSlotChange;
+    private onBadgesSlotChange;
+    private onAttachmentsSlotChange;
+    private onActionsSlotChange;
+    private onFailureSlotChange;
+    private toggleCollapsed;
+    private onRetryClick;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-chat-message': LyraChatMessage;
+    }
+}
+//# sourceMappingURL=chat-message.class.d.ts.map

package/dist/components/conversation/chat-message/chat-message.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-message.class.d.ts","sourceRoot":"","sources":["../../../../src/components/conversation/chat-message/chat-message.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,cAAc,EAA0B,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE3G,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAKhE,OAAO,gDAAgD,CAAC;AAGxD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAkD5E,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,WAAW,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,oBAAoB,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC5C;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,qBAAa,eAAgB,SAAQ,WAAW,CAAC,uBAAuB,CAAC;IACvE,MAAM,CAAC,MAAM,iCAAgC;IAO7C,MAAM,CAAC,UAAU;QACf,MAAM;YAAI,OAAO;YAAQ,UAAU;;MACnC;IAEF,6EAA6E;IACxB,IAAI,EAAE,eAAe,CAAe;IAEzF;2BACuB;IAC+B,SAAS,SAAM;IAErE;;6DAEyD;IACzB,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAE1D;;;wDAGoD;IACpB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IAEzE,+DAA+D;IACnB,WAAW,UAAS;IAEhE;;;0CAGsC;IACM,SAAS,UAAS;IAE9D;;;;2CAIuC;IACU,mBAAmB,EAAE,QAAQ,GAAG,OAAO,CAAW;IAEnG;;;iGAG6F;IACZ,oBAAoB,UAAS;IAErG,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,cAAc,CAAS;IACxC;;;2DAGuD;IAC9C,OAAO,CAAC,cAAc,CAAS;IAEf,OAAO,CAAC,UAAU,CAAC,CAAiB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAc;IAEzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IAEtD,OAAO,CAAC,OAAO,CAA6B;IAE5C;;;;;;;sDAOkD;IAClD,OAAO,CAAC,cAAc,CAA6B;IAEnD;;;;;;iBAMa;IACb,OAAO,CAAC,UAAU,CAAQ;IAE1B;;;2CAGuC;IACvC,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,iBAAiB,EAMlC;IAED,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CA+BlD;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAM/C;IAED,OAAO,CAAC,UAAU;IAIlB;;;;gCAI4B;IAC5B,OAAO,CAAC,wBAAwB;IAMhC,OAAO,KAAK,mBAAmB,GAI9B;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,CAAC,oBAAoB;IAiB5B,OAAO,CAAC,kBAAkB,CAExB;IAEF,OAAO,CAAC,kBAAkB,CAExB;IAEF,OAAO,CAAC,uBAAuB,CAE7B;IAEF,OAAO,CAAC,mBAAmB,CAEzB;IAEF,OAAO,CAAC,mBAAmB,CAEzB;IAEF,OAAO,CAAC,eAAe,CAGrB;IAEF,OAAO,CAAC,YAAY,CAQlB;IAEF,MAAM,IAAI,cAAc,CAmEvB;CACF;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,eAAe,CAAC;KACpC;CACF"}