ninchat-embed 2.8.0 → 2.9.0-alpha

package/README.md

@@ -61,11 +61,12 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `environment` | `string[]` |  List of environment keys. 'default' is always used, and can be omited. |
 | `targetOrigin` | `string` | Target origin for iframe communication |
 | `version` | `string` | Version to be send with each API request |
+| `restoredStorage` | `Record<string, string>` | React Native WebView storage snapshot to restore before initializing the session |
 | `config` | `object` | Config used to override subset of the keys obtained via configKey and others.  See Config Properties in table below |
 | `configUrls` | `string[]` | List of URL addresses for self-hosted configs. |
 | `containerId` | `string` | DOM element id for where the chat container is placed.| 
 | `postConfigUrls` | `string[]` | List of URL addresses for self-hosted configs loaded via POST request. |
-| `variant` | `'live' \| 'stage'` | Application variant override |
+| `variant` | `'live' \| 'stage' \| 'unstable'` | Application variant override |
 
 ### Config Common properties
 
@@ -98,6 +99,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 
 | Key | Type | Description |
 |-----|------|-------------|
+| `useSkeletonLoader`| `boolean` | Replace default spinner loader with skeleton loader |
 | `reverseEmbedHeroContentOrdering` | `boolean`| Reverse order of elements in hero, rotating spinner will be the last |
 | `scheduleAccessKey` | `string` | Access key for scheduled appointments |
 | `channelId` | `string` | Channel id for variant "channel" |
@@ -630,12 +632,32 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `colors.floatingEmbedHeaderButton` | `string` | Floating embed header button color |
 | `colors.floatingEmbedHeaderButtonIcon` | `string` | Floating embed header button icon color |
 | `colors.floatingEmbedHeaderButtonHover` | `string` | Floating embed header button hover color |
-| `colors.floatingEmbedHeaderButtonIconHiver` | `string` | Floating embed header button icon hover color |
+| `colors.floatingEmbedHeaderButtonIconHover` | `string` | Floating embed header button icon hover color |
 | `colors.floatingEmbedHeaderButtonBackground` | `string` | Floating embed header button background color |
 | `colors.floatingEmbedHeaderButtonBorder` | `string` | Floating embed header button border color |
 | `colors.floatingEmbedHeaderButtonHoverBackground` | `string` | Floating embed header button background (hover) |
 | `colors.floatingEmbedHeaderButtonFocusBackground` | `string` | Floating embed header button background (focus) |
 | `colors.floatingEmbedHeaderButtonActiveOutline` | `string` | Floating embed header button outline (active) |
+| `colors.floatingEmbedHeaderTitleButtonTitle` | `string` | Floating embed header title button color |
+| `colors.floatingEmbedHeaderTitleButtonSubtitle` | `string` | Floating embed header subtitle button color |
+| `colors.floatingEmbedHeaderTitleButtonTitleHover` | `string` | Floating embed header title button hover color |
+| `colors.floatingEmbedHeaderTitleButtonSubtitleHover` | `string` | Floating embed header subtitle button hover color |
+| `colors.floatingEmbedHeaderTitleButtonIcon` | `string` | Floating embed header title button icon color |
+| `colors.floatingEmbedHeaderTitleButtonIconHover` | `string` | Floating embed header title button icon hover color |
+| `colors.floatingEmbedHeaderTitleButtonBackground` | `string` | Floating embed header title button background color |
+| `colors.floatingEmbedHeaderTitleButtonBorder` | `string` | Floating embed header title button border color |
+| `colors.floatingEmbedHeaderTitleButtonHoverBackground` | `string` | Floating embed header title button background (hover) |
+| `colors.floatingEmbedHeaderTitleButtonFocusBackground` | `string` | Floating embed header title button background (focus) |
+| `colors.floatingEmbedHeaderTitleButtonActiveOutline` | `string` | Floating embed header title button outline (active) |
+| `colors.floatingEmbedHeaderCloseButton` | `string` | Floating embed header close button color |
+| `colors.floatingEmbedHeaderCloseButtonIcon` | `string` | Floating embed header close button icon color |
+| `colors.floatingEmbedHeaderCloseButtonHover` | `string` | Floating embed header close button hover color |
+| `colors.floatingEmbedHeaderCloseButtonIconHover` | `string` | Floating embed header close button icon hover color |
+| `colors.floatingEmbedHeaderCloseButtonBackground` | `string` | Floating embed header close button background color |
+| `colors.floatingEmbedHeaderCloseButtonBorder` | `string` | Floating embed header close button border color |
+| `colors.floatingEmbedHeaderCloseButtonHoverBackground` | `string` | Floating embed header close button background (hover) |
+| `colors.floatingEmbedHeaderCloseButtonFocusBackground` | `string` | Floating embed header close button background (focus) |
+| `colors.floatingEmbedHeaderCloseButtonActiveOutline` | `string` | Floating embed header close button outline (active) |
 | `colors.floatingEmbedHeaderAvatar` | `string` | Floating embed header avatar text color |
 | `colors.floatingEmbedHeaderAvatarBackground` | `string` | Floating embed header avatar background color |
 | `colors.floatingEmbedHeaderAvatarBorder` | `string` | Floating embed header avatar border color |
@@ -660,6 +682,27 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `colors.containerEmbedHeaderButtonHoverBackground` | `string` | Container embed header button background (hover) |
 | `colors.containerEmbedHeaderButtonFocusBackground` | `string` | Container embed header button background (focus) |
 | `colors.containerEmbedHeaderButtonActiveOutline` | `string` | Container embed header button outline (active) |
+| `colors.containerEmbedHeaderTitleButtonTitle` | `string` | Container embed header button title color |
+| `colors.containerEmbedHeaderTitleButtonSubtitle` | `string` | Container embed header button subtitle color |
+| `colors.containerEmbedHeaderTitleButtonTitleHover` | `string` | Container embed header title button hover color |
+| `colors.containerEmbedHeaderTitleButtonSubtitleHover` | `string` | Container embed header subtitle button hover color |
+| `colors.containerEmbedHeaderTitleButtonBackground` | `string` | Container embed header title button background color |
+| `colors.containerEmbedHeaderTitleButtonBorder` | `string` | Container embed header title button border color |
+| `colors.containerEmbedHeaderTitleButtonHoverBackground` | `string` | Container embed header title button background (hover) |
+| `colors.containerEmbedHeaderTitleButtonFocusBackground` | `string` | Container embed header title button background (focus) |
+| `colors.containerEmbedHeaderTitleButtonActiveOutline` | `string` | Container embed header title button outline (active) |
+| `colors.containerEmbedHeaderCloseButton` | `string` | Container embed header close button color |
+| `colors.containerEmbedHeaderCloseButtonIcon` | `string` | Container embed header close button icon color |
+| `colors.containerEmbedHeaderCloseButtonHover` | `string` | Container embed header close button hover color |
+| `colors.containerEmbedHeaderCloseButtonIconHover` | `string` | Container embed header close button icon hover color |
+| `colors.containerEmbedHeaderCloseButtonBackground` | `string` | Container embed header close button background color |
+| `colors.containerEmbedHeaderCloseButtonBorder` | `string` | Container embed header close button border color |
+| `colors.containerEmbedHeaderCloseButtonHoverBackground` | `string` | Container embed header close button background (hover) |
+| `colors.containerEmbedHeaderCloseButtonFocusBackground` | `string` | Container embed header close button background (focus) |
+| `colors.containerEmbedHeaderCloseButtonActiveOutline` | `string` | Container embed header close button outline (active) |
+| `colors.containerEmbedHeaderAvatar` | `string` | Container embed header avatar text color |
+| `colors.containerEmbedHeaderAvatarBackground` | `string` | Container embed header avatar background color |
+| `colors.containerEmbedHeaderAvatarBorder` | `string` | Container embed header avatar border color |
 | `colors.embedBody` | `string` | Embed body text color |
 | `colors.embedBodyHeading1` | `string` | Embed body heading 1 color |
 | `colors.embedBodyHeading2` | `string` | Embed body heading 2 color |
@@ -686,6 +729,8 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `colors.embedQueuePosition` | `string` | Embed queue position text color |
 | `colors.embedQueueSpinner` | `string` | Embed queue spinner color |
 | `colors.embedModalHeader` | `string` | Embed modal header color |
+| `colors.embedModalIcon` | `string` | Embed modal icon color |
+| `colors.questionnaireBackground` | `string` | Embed questionnaire background |
 | `colors.questionnaireErrorTitle` | `string` | Embed error title color |
 | `colors.questionnaireNavigation` | `string` | Questionnaire navigation color |
 | `colors.questionnaireNavigationBorder` | `string` | Questionnaire navigation bordercolor |
@@ -738,9 +783,21 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `colors.messageSpeechBubbleOtherLinkHover` | `string` | Other user speech bubble link color (hover) |
 | `colors.messageSpeechBubbleOperatorModeratorTimestamp` | `string` | Operator/moderator timestamp color |
 | `colors.messageSpeechBubbleOtherTimestamp` | `string` | Other user timestamp color |
+| `colors.skeletonLoader` | `string` | Cusrtom skeleton loader text color |
+| `colors.skeletonLoaderBackground` | `string` | Custom skeleton loader background color |
+| `colors.skeletonLoaderProgress` | `string` | Custom skeleton loader progress bar color |
+| `backgroundSizes.questionnaire` | `string` | Questionnaire background image size |
+| `backgroundSizes.embedHero` | `string` | Embed Hero background image size |
+| `backgroundSizes.chatBacklog` | `string` | Chat backlog background image size |
 | `borderStyles.embedHero` | `string` | Embed hero border style |
 | `borderStyles.floatingEmbedHeaderBorder` | `string` | Floating embed header border style |
 | `borderStyles.containerEmbedHeaderBorder` | `string` | Container embed header border style |
+| `borderStyles.floatingEmbedHeaderButton` | `string` | Floating embed header button border style |
+| `borderStyles.containerEmbedHeaderButton` | `string` | Container embed header button border style |
+| `borderStyles.floatingEmbedHeaderTitleButton` | `string` | Floating embed header title button border style |
+| `borderStyles.containerEmbedHeaderTitleButton` | `string` | Container embed header title button border style |
+| `borderStyles.floatingEmbedHeaderCloseButton` | `string` | Floating embed header close button border style |
+| `borderStyles.containerEmbedHeaderCloseButton` | `string` | Container embed header close button border style |
 | `borderStyles.buttonFilled` | `string` | Filled button border style |
 | `borderStyles.button` | `string` | Button border style |
 | `borderStyles.buttonText` | `string` | Text button border style |
@@ -763,6 +820,12 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `borderWidths.embedHero` | `string` | Embed hero border width |
 | `borderWidths.floatingEmbedHeaderBorder` | `string` | Floating embed header border width |
 | `borderWidths.containerEmbedHeaderBorder` | `string` | Container embed header border width |
+| `borderWidths.floatingEmbedHeaderButton` | `string` | Floating embed header button border width |
+| `borderWidths.containerEmbedHeaderButton` | `string` | Container embed header button border width |
+| `borderWidths.floatingEmbedHeaderTitleButton` | `string` | Floating embed header title button border width |
+| `borderWidths.containerEmbedHeaderTitleButton` | `string` | Container embed header title button border width |
+| `borderWidths.floatingEmbedHeaderCloseButton` | `string` | Floating embed header button border width |
+| `borderWidths.containerEmbedHeaderCloseButton` | `string` | Container embed header button border width |
 | `borderWidths.buttonFilled` | `string` | Filled button border width |
 | `borderWidths.button` | `string` | Button border width |
 | `borderWidths.buttonText` | `string` | Text button border width |
@@ -869,7 +932,8 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `fontSizes.questionnaireLightBotBubble` | `string` | Questionnaire light bot bubble font size |
 | `fontSizes.questionnaireLightBotAnswerBubble` | `string` | Questionnaire light bot answer bubble font size|
 | `fontSizes.floatingEmbedHeaderInQueueLoader` | `string` | Floating Embed Header in queue loader position font size |
-| `fontSizez.floatingEmbedHeaderAvatar` | `string` | Floating Embed header Avatar font size |
+| `fontSizes.floatingEmbedHeaderAvatar` | `string` | Floating Embed header Avatar font size |
+| `fontSizes.skeletonLoader` | `string` | Custom skeleton loader font size |
 | `fontStyle.embedBody` | `string` | Embed body font style |
 | `fontStyle.embedBodyHeading1` | `string` | Embed body heading 1 font style |
 | `fontStyle.embedBodyHeading2` | `string` | Embed body heading 2 font style |
@@ -979,6 +1043,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `fontWeights.messageSpeechBubbleOther` | `string` | Other user speech bubble font weight |
 | `fontWeights.questionnaireLightBotBubble` | `string` | Questionnaire light bot bubble font weight |
 | `fontWeights.questionnaireLightBotAnswerBubble` | `string` | Questionnaire light bot answer bubble font weight |
+| `fontWeights.skeletonLoader` | `string` | Custom skeleton loader font weight |
 | `maxWidths.questionnaire` | `string` | Questionnaire maximum width |
 | `maxWidths.questionnaireNavigation` | `string` | Questionnaire navigation maximum width |
 | `sizes.embedQueueSpinner` | `string` | In Queue Spinner size |
@@ -1009,6 +1074,10 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `space.inputModal` | `string` | Embed input modal padding |
 | `space.floatingEmbedHeaderButton` | `string` | Floating Embed header button padding |
 | `space.containerEmbedHeaderButton` | `string` | Container Embed header button padding |
+| `space.floatingEmbedHeaderTitleButton` | `string` | Floating Embed header title button padding |
+| `space.containerEmbedHeaderTitleButton` | `string` | Container Embed header title button padding |
+| `space.floatingEmbedHeaderCloseButton` | `string` | Floating Embed header close button padding |
+| `space.containerEmbedHeaderCloseButton` | `string` | Container Embed header close button padding |
 | `space.floatingEmbedHeader` | `string` | Floating Embed header padding (fixed width and height still will be in use) |
 | `space.containerEmbedHeader` | `string` | Container Embed headerpadding (fixed width and height still will be in use) |
 | `space.floatingEmbedBall` | `string` | Floating embed ball padding |
@@ -1022,6 +1091,10 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `radii.floatingEmbedPromoBubble` | `string` | Floating embed promo bubble border radius |
 | `radii.floatingEmbedHeaderButton` | `string` | Floating embed header button border radius |
 | `radii.containerEmbedHeaderButton` | `string` | Container embed header button border radius |
+| `radii.floatingEmbedHeaderTitleButton` | `string` | Floating embed header title button border radius |
+| `radii.containerEmbedHeaderTitleButton` | `string` | Container embed header title button border radius |
+| `radii.floatingEmbedHeaderCloseButton` | `string` | Floating embed header close button border radius |
+| `radii.containerEmbedHeaderCloseButton` | `string` | Container embed header close button border radius |
 | `radii.embedHero` | `string` | Embed hero border radius |
 | `radii.buttonFilled` | `string` | Filled button border radius |
 | `radii.button` | `string` | Button border radius |
@@ -1090,6 +1163,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `navigation` | `object` | Navigation configuration for the view |
 | `navigation.fixed` | `boolean` | Whether navigation use fixed position istead of static |
 | `navigation.position` | `'top' \| 'bottom'` | Position of navigation bar |
+| `navigation.enableMobileStacking` | `boolean` | Make primary buttons on top and full width when there is no enought space | 
 | `navigation.elements` | `array` | Array of questionnaire elements for navigation |
 | **Item: Logic - Queues Closed** | | |
 | `type` | `'logic-queues-closed'` | Logic item to check if all queues from list are closed |
@@ -1101,6 +1175,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `type` | `'logic'` | Logic item for conditional flow control |
 | `id` | `string` | Unique identifier |
 | `conditions` | `array` | Array of condition objects |
+| `conditions[].$value` | `string` | Field or queue context key whose value is used by following `$gt`, `$gte`, `$lt`, or `$lte` operators |
 | `conditions[].$and` | `array` | AND operator - all conditions must be true |
 | `conditions[].$or` | `array` | OR operator - at least one condition must be true |
 | `conditions[].$nor` | `array` | NOR operator - none of conditions can be true |
@@ -1154,7 +1229,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | **Element: Button** | | |
 | `element` | `'button'` | Button element type |
 | `text` | `string` | Button text |
-| `variant` | `'primary'` | Button variant style |
+| `variant` | `'primary' | 'secondary' | 'tertiary'` | Button variant style |
 | `target` | `string` | Target view ID |
 | `align` | `'center' \| 'right' \| 'left'` | Button alignment |
 | `clearAfter` | `boolean` | Clear float after current element |
@@ -1190,6 +1265,13 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `padding` | `string` | Padding around button |
 | `margin` | `string` | Margin around element |
 | `hide` | `boolean` | Whether element is hidden by default |
+| `variant` | `'primary' | 'secondary' | 'tertiary'` | Queue button variant style |
+| `iconLeft` | `object` | Left icon configuration |
+| `iconLeft.src` | `string` | Icon image URL |
+| `iconLeft.svg` | `string` | Inline SVG for icon |
+| `iconRight` | `object` | Right icon configuration |
+| `iconRight.src` | `string` | Icon image URL |
+| `iconRight.svg` | `string` | Inline SVG for icon |
 | `logic` | `object` | Conditional logic for element |
 | `logic.conditions` | `array` | Array of condition objects (same as Logic Item conditions) |
 | `logic.result.hide` | `boolean` | Whether to hide element when condition is met |
@@ -1292,6 +1374,7 @@ install using `npm i ninchat-embed` or link main directly from ninchat.com:
 | `value` | `string` | Value when radio is selected |
 | `groupName` | `string` | Group name for organizing fields |
 | `readableName` | `string` | Human-readable name for metadata |
+| `clearAfter` | `boolean` | Clear float after current element |
 | `text` | `string` | Radio button label text |
 | `inline` | `boolean` | Whether radio is displayed inline |
 | `target` | `string` | Target view ID when selected |
@@ -1448,8 +1531,8 @@ Ninchat.route(Route)
 | ActivityCount | activity_count | `activity`: number, `highlights`: number | Typical use case for `ActivityCount` is to display activity as a number in host sites favicon. `activity` property contains the total activity including `highlights`. `highlights` are activity which has importance based on users settings or their role. Eg. highlight can be a name mention or a visitor requesting an audience. |
 | AudienceEnded | audience_eneded | `audience_id`: string | Emitted when an audience session ends |
 | AudienceClosed | audience_closed | `audience_id`: string | Emitted when the chat is closed |
-| SessionCreated | session_created | `user_queues?`: {[queue_id]: {`delivery_time`, `queue_time`, `unassigned_registered_time`, `realm_id`, `queue_attrs`: {`name`, `length`, `group_id`, `is_group`, `unassigned_registered`}}}, `user_channels?`: {[channel_id]: {`channel_attrs`, `channel_status?`, `realm_id?`}} | Emitted when a user session is created with queue and channel information |
-| QueueUpdated | queue_updated | `queue_id`: string, `queue_attrs`: {`name`, `length`, `group_id`, `is_group`, `unassigned_registered`}, `queue_time?`: number, `unassigned_registered_time?`: number, `realm_id?`: string | Emitted when queue information is updated |
+| SessionCreated | session_created | `user_queues?`: {[queue_id]: {`delivery_time`, `queue_time`, `unassigned_registered_time`, `realm_id`, `queue_attrs`: {`name`, `length`, `group_id`, `is_group`, `unassigned_registered`}, `queue_requests?`: QueueRequest[]}}, `user_channels?`: {[channel_id]: {`channel_attrs`, `channel_status?`, `realm_id?`}} | Emitted when a user session is created with queue and channel information |
+| QueueUpdated | queue_updated | `queue_id`: string, `queue_attrs`: {`name`, `length`, `group_id`, `is_group`, `unassigned_registered`}, `queue_time?`: number, `unassigned_registered_time?`: number, `realm_id?`: string, `queue_request?`: QueueRequest | Emitted when queue information is updated |
 | ChannelUpdated | channel_updated | `channel_id`: string, `channel_attrs`: {`audience_id`, `queue_id`, `name`, `closed`}, `channel_status?`: string, `realm_id?`: string | Emitted when channel information is updated |
 | MembersUpdated | members_updated | `channel_id`: string, `members`: [{`id`: string, `presence`: `'online'`\|`'idle'`\|`'offline'`, `name?`: string}] | Emitted when a channel member's presence (online/idle/offline) changes. Only fires for audience channels. Members list excludes the current user. |
 | ContainerInitialized | container_initialized | - | Emitted when the embed container is initialized |
@@ -1526,6 +1609,26 @@ the `route.name` property is one of the following:
 
 ## Examples
 
+### React Native session restoration
+
+The React Native wrapper can restore an Embed session after its WebView reloads. It persists storage snapshots received through the internal `embed_storage_dump` event and passes the latest snapshot back to `Ninchat.init()` as `restoredStorage`.
+
+`embed_storage_dump` is emitted through the WebView-only `all_events` callback when storage changes. The snapshot should be removed when the conversation is intentionally closed so that the next launch starts a new session.
+
+### Queue request metadata
+
+When the backend queue setting `share_audience_info` is enabled, waiting requests are included in the initial `session_created` event and new requests are included in `queue_updated` events. When the setting is disabled, the backend omits `queue_requests` and `queue_request`. Each queue request has the following shape:
+
+```typescript
+{
+    audience_id: string
+    request_time: number
+    metadata?: Record<string, unknown>[]
+}
+```
+
+`audience_id` and `request_time` are included in every queue request received from the backend. `metadata` contains only shared secure data allowed for the embed parent origin. It is omitted when shared data is absent or the parent origin is not allowed. Other audience metadata is never forwarded.
+
 ### Metadata 
 
 `metadata` array contains secure metadata which is exposed to the parent on purpose. Array is used here, since in conversation can be multiple users with metadata.
@@ -1645,6 +1748,13 @@ Ninchat.route(route)
 
 ## Release history
 
+### v2.9.0-alpha
+
+- Expanded [Embed UI theming](#theme-overrides) and [questionnaire customization](#questionnaires), including responsive layouts, header controls, backgrounds, skeleton loading, and queue button variants.
+- Improved [questionnaire metadata handling](#metadata) and added [secure queue request metadata](#queue-request-metadata) to session and queue events.
+- Added [session restoration support for React Native embeds](#react-native-session-restoration).
+- Added the [unstable frontend variant](#top-level-options) for versioned pre-release deployments.
+
 ### v2.8.0
 
 - expose MembersUpdated event to indicate if other channel members go offline / idle