@trixwell/ngx-parl 4.3.0 → 5.0.1

package/README.md

@@ -68,18 +68,22 @@ assets/ngx-parl/...
 
 ## Signal Data
 
-|       Name        |        Type        |                            Description                            |
-|:-----------------:|:------------------:|:-----------------------------------------------------------------:|
-|      header       |      boolean       |     Display the chat title with the name of the interlocutor      |
-|       theme       |       string       |     Choose a theme color   (```primary``` or ```secondary```)     |
-|     language      |       string       |       Set language (```uk``` or ```en```). Default ```en```       |
-|    messageList    |   ChatMessage[]    |              List of chat messages, user information              |
-|   messageUpdate   |    ChatMessage     | Incoming message from external source (signal/subject/observable) |
-|   messageAction   | MessageActionEvent |               Emits chat events: send, edit, delete               |
-|    loadHistory    |      boolean       |                    Use scroll for load history                    |
-|   incomingUser    |       string       |                     User writing in messenger                     |
-|   transportType   |       string       |               Transport type label (Telegram, etc.)               |
-| transportTypeIcon |       string       |         Path to transport icon (e.g. assets/ngx-parl/...)         |
+|         Name         |           Type            |                                          Description                                           |
+|:--------------------:|:-------------------------:|:----------------------------------------------------------------------------------------------:|
+|        header        |          boolean          |                    Display the chat title with the name of the interlocutor                    |
+|        theme         |          string           |                   Choose a theme color   (```primary``` or ```secondary```)                    |
+|       language       |          string           |                     Set language (```uk``` or ```en```). Default ```en```                      |
+|     messageList      |       ChatMessage[]       |                            List of chat messages, user information                             |
+|    messageUpdate     |        ChatMessage        |               Incoming message from external source (signal/subject/observable)                |
+|    messageAction     |    MessageActionEvent     |                             Emits chat events: send, edit, delete                              |
+|     loadHistory      |          boolean          |                                  Use scroll for load history                                   |
+|     incomingUser     |          string           |                                   User writing in messenger                                    |
+|    transportType     |          string           |                             Transport type label (Telegram, etc.)                              |
+|  transportTypeIcon   |          string           |                       Path to transport icon (e.g. assets/ngx-parl/...)                        |
+|      mobileMode      |          boolean          |                   Enables mobile UI behavior (e.g. outgoing avatar, layout)                    |
+| quickActionsResolver | ParlQuickActionsResolver  | Optional. Custom mapping; if omitted, `message.actions` uses `defaultParlQuickActionsResolver` |
+| quickActionsAutoSend |          boolean          |                      Auto-send quick action text on click. Default `true`                      |
+|   quickActionClick   | ParlQuickActionClickEvent |                      Emits when a quick action is clicked (two-way bind)                       |
 
 ## Scrolling to the Bottom
 
@@ -121,10 +125,17 @@ export interface ChatMessageDTO {
     file_list?: File[] | [] | null;
     checked?: boolean | null;
     pending?: boolean;
+    actions?: ChatQuickButton[] | null;
 }
 
 export type ChatMessageType = 'incoming' | 'outgoing';
 
+export interface ChatQuickButton {
+    id: number;
+    title: string;
+    value: string;
+}
+
 export interface MessageActionEvent {
     action: MessageActionType;
     chatMessageId?: number;
@@ -136,6 +147,74 @@ export interface MessageActionEvent {
 }
 ```
 
+## Quick actions
+
+If your `ChatMessage` contains `actions`, they are shown as quick action buttons for **outgoing** messages in both desktop and mobile layouts (`mobileMode` does not hide them).
+
+- If you omit `[quickActionsResolver]`, the library uses `defaultParlQuickActionsResolver`, which maps `message.actions` to buttons.
+- Provide a custom `[quickActionsResolver]` to filter, reorder, or replace actions; the context includes `isMobile` if you need different behavior per layout.
+- `ChatQuickButton.title` is the button text; `ChatQuickButton.value` is the text that will be sent.
+- Each action must include a stable `id`.
+- `quickActionsAutoSend` defaults to `true` (clicking a quick action triggers `sendMessage()`).
+
+### Types
+
+```
+export interface ParlQuickAction {
+    id: string;
+    title: string;
+    value: string;
+    disabled?: boolean;
+}
+
+export interface ParlQuickActionContext {
+    message: ChatMessage;
+    isMobile: boolean;
+}
+
+export interface ParlQuickActionClickEvent {
+    actionId: string;
+    messageId: number;
+    value: string;
+}
+
+export type ParlQuickActionsResolver = (context: ParlQuickActionContext) => ParlQuickAction[];
+
+export function defaultParlQuickActionsResolver(context: ParlQuickActionContext): ParlQuickAction[];
+```
+
+### Example resolver
+
+```
+public quickActionsResolver: ParlQuickActionsResolver = ({ message }) => {
+    if (message.type !== 'outgoing') {
+        return [];
+    }
+
+    const actions = message.actions ?? [];
+    return actions.map((a) => ({
+        id: String(a.id),
+        title: a.title,   // button text
+        value: a.value,   // sent text
+    }));
+};
+```
+
+## Mobile mode
+
+Set `[mobileMode]="true"` to enable mobile UI behavior:
+
+- Outgoing message avatars are hidden to save space.
+- Quick actions use the default resolver from `message.actions` when `[quickActionsResolver]` is omitted, or your custom resolver when set (desktop and mobile).
+- Quick actions are shown as a separate “buttons-only” outgoing message when the resolver returns actions for that message.
+
+To use quick actions:
+
+- Put `actions` on outgoing `ChatMessage` instances, and optionally omit `[quickActionsResolver]` to use the default mapping.
+- Or provide `[quickActionsResolver]` for full control.
+- Optionally bind `[(quickActionClick)]` to observe clicks (analytics/logging).
+- Keep `[quickActionsAutoSend]="true"` to send `action.value` on click (default).
+
 ## Template
 
 ```
@@ -143,6 +222,9 @@ export interface MessageActionEvent {
           [(messageList)]="messageList"
           [(messageUpdate)]="messageUpdate"
           [(messageAction)]="messageAction"
+          [quickActionsAutoSend]="true"
+          [mobileMode]="false"
+          [(quickActionClick)]="quickActionClick"
           [transportType]="transportType()"
           [transportTypeIcon]="transportTypeIcon()"
           [(isScrolledToTop)]="isScrolledToTop">