@linktr.ee/messaging-react 3.1.3 → 3.1.4-rc-1780636753

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-BQf4WkPC.cjs");exports.ActionButton=e.ActionButton;exports.Avatar=e.Avatar;exports.ChannelEmptyState=e.ChannelEmptyState;exports.ChannelList=e.ChannelList;exports.ChannelView=e.ChannelView;exports.CustomMessageProvider=e.CustomMessageProvider;exports.FaqList=e.FaqList;exports.FaqListItem=e.FaqListItem;exports.LinkAttachment=e.LinkAttachment;exports.LockedAttachment=e.LockedAttachment;exports.MediaMessage=e.MediaMessage;exports.MessageAttachment=e.MessageAttachment;exports.MessageVoteButtons=e.MessageVoteButtons;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.buildCompactMetaLabel=e.buildCompactMetaLabel;exports.formatFileSize=e.formatFileSize;exports.formatRelativeTime=e.formatRelativeTime;exports.getFileExtensionLabel=e.getFileExtensionLabel;exports.getMessageDisplayText=e.getMessageDisplayText;exports.isLinkAttachment=e.isLinkAttachment;exports.isUuidLike=e.isUuidLike;exports.messageAttachmentGroupPositionFromStream=e.bubbleGroupPositionFromStream;exports.normalizeLanguageCode=e.normalizeLanguageCode;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useCustomMessage=e.useCustomMessage;exports.useMessageVote=e.useMessageVote;exports.useMessaging=e.useMessaging;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-D4Dse1Lu.cjs");exports.ActionButton=e.ActionButton;exports.Avatar=e.Avatar;exports.ChannelEmptyState=e.ChannelEmptyState;exports.ChannelList=e.ChannelList;exports.ChannelView=e.ChannelView;exports.CustomMessageProvider=e.CustomMessageProvider;exports.FaqList=e.FaqList;exports.FaqListItem=e.FaqListItem;exports.LinkAttachment=e.LinkAttachment;exports.LockedAttachment=e.LockedAttachment;exports.MediaMessage=e.MediaMessage;exports.MessageAttachment=e.MessageAttachment;exports.MessageVoteButtons=e.MessageVoteButtons;exports.MessagingProvider=e.MessagingProvider;exports.MessagingShell=e.MessagingShell;exports.buildCompactMetaLabel=e.buildCompactMetaLabel;exports.formatFileSize=e.formatFileSize;exports.formatRelativeTime=e.formatRelativeTime;exports.getFileExtensionLabel=e.getFileExtensionLabel;exports.getMessageDisplayText=e.getMessageDisplayText;exports.isLinkAttachment=e.isLinkAttachment;exports.isUuidLike=e.isUuidLike;exports.messageAttachmentGroupPositionFromStream=e.bubbleGroupPositionFromStream;exports.normalizeLanguageCode=e.normalizeLanguageCode;exports.resolveLinkAttachment=e.resolveLinkAttachment;exports.resolveMediaFromMessage=e.resolveMediaFromMessage;exports.resolveParticipantDisplayName=e.resolveParticipantDisplayName;exports.useCustomMessage=e.useCustomMessage;exports.useMessageVote=e.useMessageVote;exports.useMessaging=e.useMessaging;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -95,6 +95,36 @@ export declare const ChannelEmptyState: default_2.FC;
  */
 export declare const ChannelList: default_2.NamedExoticComponent<ChannelListProps>;
 
+/**
+ * Derived state reported by the mounted ChannelList instance.
+ *
+ * This reflects the currently loaded list data only. It does not guarantee
+ * complete server-side truth for channels outside the mounted list's current
+ * query window or cache.
+ */
+export declare interface ChannelListDerivedState {
+    /**
+     * Whether the mounted list has completed its first channel-resolution pass.
+     */
+    isInitialLoadSettled: boolean;
+    /**
+     * Visible channels after `channelRenderFilterFn` is applied.
+     */
+    channels: Channel[];
+    /**
+     * Raw channels received from Stream before client-side filtering.
+     */
+    rawChannels: Channel[];
+    /**
+     * Convenience flag for empty-state consumers. Mirrors `channels.length > 0`.
+     */
+    hasChannels: boolean;
+    /**
+     * Number of visible channels with at least one unread message.
+     */
+    unreadCount: number;
+}
+
 /**
  * ChannelList component props
  */
@@ -137,6 +167,14 @@ export declare interface ChannelListProps {
      * Falls back to message.text when no matching translation exists.
      */
     viewerLanguage?: string;
+    /**
+     * Reports derived state from the mounted Stream ChannelList instance.
+     *
+     * This callback is driven by currently loaded list data only. Use it for
+     * cache/list-derived UI state such as empty-state confirmation or visible
+     * unread badges; do not assume it represents complete server-side truth.
+     */
+    onStateChange?: (state: ChannelListDerivedState) => void;
 }
 
 /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as e, b as t, C as i, c as n, d as o, e as m, F as g, f as l, L as r, h as M, M as u, i as L, j as c, k as h, l as d, m as p, n as v, o as A, p as C, q as F, s as k, t as b, u as f, v as x, w as y, x as P, y as S, z as q, B as z, D as B } from "./index-CnOvDQIp.js";
+import { a as e, b as t, C as i, c as n, d as o, e as m, F as g, f as l, L as r, h as M, M as u, i as L, j as c, k as h, l as d, m as p, n as v, o as A, p as C, q as F, s as k, t as b, u as f, v as x, w as y, x as P, y as S, z as q, B as z, D as B } from "./index-CO975B6P.js";
 export {
   e as ActionButton,
   t as Avatar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/messaging-react",
-  "version": "3.1.3",
+  "version": "3.1.4-rc-1780636753",
   "description": "React messaging components built on messaging-core for web applications",
   "type": "module",
   "main": "dist/index.cjs",

package/src/components/ChannelList/index.test.tsx

@@ -1,3 +1,4 @@
+import { act, waitFor } from '@testing-library/react'
 import React from 'react'
 import type { Channel } from 'stream-chat'
 import { describe, expect, it, vi, beforeEach } from 'vitest'
@@ -56,7 +57,7 @@ describe('ChannelList', () => {
     })
   })
 
-  it('wraps channelRenderFilterFn to restore pending messages and delegates to consumer filter', () => {
+  it('wraps channelRenderFilterFn to restore pending messages and delegates to consumer filter', async () => {
     const filterFn = vi.fn((channels: Channel[]) => channels)
 
     renderWithProviders(
@@ -77,9 +78,156 @@ describe('ChannelList', () => {
 
     // When the wrapper is called, it should delegate to the consumer's filter
     const mockChannels = [
-      { cid: 'ch-1', state: { pending_messages: [], addMessageSorted: vi.fn() } },
+      {
+        cid: 'ch-1',
+        countUnread: () => 0,
+        state: { pending_messages: [], addMessageSorted: vi.fn() },
+      },
     ]
-    streamProps.channelRenderFilterFn!(mockChannels)
+    await act(async () => {
+      streamProps.channelRenderFilterFn!(mockChannels)
+      await Promise.resolve()
+    })
     expect(filterFn).toHaveBeenCalledWith(mockChannels)
   })
+
+  it('notifies hosts with derived visible-channel state', async () => {
+    const onStateChange = vi.fn()
+    const visibleChannel = {
+      cid: 'ch-visible',
+      countUnread: () => 2,
+      state: { pending_messages: [], addMessageSorted: vi.fn() },
+    }
+    const hiddenChannel = {
+      cid: 'ch-hidden',
+      countUnread: () => 7,
+      state: { pending_messages: [], addMessageSorted: vi.fn() },
+    }
+    const filterFn = vi.fn((channels: Channel[]) => channels.slice(0, 1))
+
+    renderWithProviders(
+      React.createElement(ChannelList, {
+        ...defaultProps,
+        channelRenderFilterFn: filterFn,
+        onStateChange,
+      } as never)
+    )
+
+    const streamProps = streamChannelListMock.mock.calls[0][0] as {
+      channelRenderFilterFn?: (channels: Channel[]) => Channel[]
+    }
+
+    await act(async () => {
+      streamProps.channelRenderFilterFn!([
+        visibleChannel as unknown as Channel,
+        hiddenChannel as unknown as Channel,
+      ])
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(onStateChange).toHaveBeenLastCalledWith({
+        isInitialLoadSettled: true,
+        channels: [visibleChannel],
+        rawChannels: [visibleChannel, hiddenChannel],
+        hasChannels: true,
+        unreadCount: 1,
+      })
+    })
+  })
+
+  it('reports a settled empty state when no visible channels remain', async () => {
+    const onStateChange = vi.fn()
+    const filterFn = vi.fn(() => [])
+    const hiddenChannel = {
+      cid: 'ch-hidden',
+      countUnread: () => 3,
+      state: { pending_messages: [], addMessageSorted: vi.fn() },
+    }
+
+    renderWithProviders(
+      React.createElement(ChannelList, {
+        ...defaultProps,
+        channelRenderFilterFn: filterFn,
+        onStateChange,
+      } as never)
+    )
+
+    const streamProps = streamChannelListMock.mock.calls[0][0] as {
+      channelRenderFilterFn?: (channels: Channel[]) => Channel[]
+    }
+
+    await act(async () => {
+      streamProps.channelRenderFilterFn!([hiddenChannel as unknown as Channel])
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(onStateChange).toHaveBeenLastCalledWith({
+        isInitialLoadSettled: true,
+        channels: [],
+        rawChannels: [hiddenChannel],
+        hasChannels: false,
+        unreadCount: 0,
+      })
+    })
+  })
+
+  it('resets derived state when filters change before the new list resolves', async () => {
+    const onStateChange = vi.fn()
+    const firstChannel = {
+      cid: 'ch-first',
+      countUnread: () => 1,
+      state: { pending_messages: [], addMessageSorted: vi.fn() },
+    }
+
+    const { rerender } = renderWithProviders(
+      React.createElement(ChannelList, {
+        ...defaultProps,
+        onStateChange,
+      } as never)
+    )
+
+    let streamProps = streamChannelListMock.mock.calls.at(-1)?.[0] as {
+      channelRenderFilterFn?: (channels: Channel[]) => Channel[]
+    }
+
+    await act(async () => {
+      streamProps.channelRenderFilterFn!([firstChannel as unknown as Channel])
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(onStateChange).toHaveBeenLastCalledWith({
+        isInitialLoadSettled: true,
+        channels: [firstChannel],
+        rawChannels: [firstChannel],
+        hasChannels: true,
+        unreadCount: 1,
+      })
+    })
+
+    rerender(
+      React.createElement(ChannelList, {
+        ...defaultProps,
+        filters: { type: 'messaging', frozen: true },
+        onStateChange,
+      } as never)
+    )
+
+    streamProps = streamChannelListMock.mock.calls.at(-1)?.[0] as {
+      channelRenderFilterFn?: (channels: Channel[]) => Channel[]
+    }
+    expect(typeof streamProps.channelRenderFilterFn).toBe('function')
+
+    await waitFor(() => {
+      expect(onStateChange).toHaveBeenLastCalledWith({
+        isInitialLoadSettled: false,
+        channels: [],
+        rawChannels: [],
+        hasChannels: false,
+        unreadCount: 0,
+      })
+    })
+  })
 })

package/src/components/ChannelList/index.tsx

@@ -5,13 +5,21 @@ import { ChannelList as StreamChannelList } from 'stream-chat-react'
 
 import { restorePendingMessages } from '../../hooks/useRestorePendingMessages'
 import { useMessagingContext } from '../../providers/MessagingProvider'
-import type { ChannelListProps } from '../../types'
+import type { ChannelListDerivedState, ChannelListProps } from '../../types'
 
 import { ChannelListProvider } from './ChannelListContext'
 import CustomChannelPreview from './CustomChannelPreview'
 
 const DEFAULT_SORT = { last_message_at: -1 } as const
 
+const EMPTY_DERIVED_STATE: ChannelListDerivedState = {
+  isInitialLoadSettled: false,
+  channels: [],
+  rawChannels: [],
+  hasChannels: false,
+  unreadCount: 0,
+}
+
 /**
  * Channel list component with customizable header and actions
  */
@@ -27,6 +35,7 @@ export const ChannelList = React.memo<ChannelListProps>(
     customEmptyStateIndicator,
     renderMessagePreview,
     viewerLanguage,
+    onStateChange,
   }) => {
     // Track renders
     const renderCountRef = React.useRef(0)
@@ -34,6 +43,42 @@ export const ChannelList = React.memo<ChannelListProps>(
 
     // Get debug flag from context
     const { debug = false } = useMessagingContext()
+    const [derivedState, setDerivedState] = React.useState<ChannelListDerivedState>(
+      EMPTY_DERIVED_STATE
+    )
+    const listIdentityKey = React.useMemo(
+      () => `${JSON.stringify(filters)}:${JSON.stringify(sort)}`,
+      [filters, sort]
+    )
+    const pendingDerivedStateRef = React.useRef<ChannelListDerivedState>(
+      EMPTY_DERIVED_STATE
+    )
+    const publishScheduledRef = React.useRef(false)
+    const listVersionRef = React.useRef(0)
+
+    const publishDerivedState = React.useCallback(
+      (nextState: ChannelListDerivedState) => {
+        const publishVersion = listVersionRef.current
+        pendingDerivedStateRef.current = nextState
+        if (publishScheduledRef.current) {
+          return
+        }
+
+        publishScheduledRef.current = true
+        queueMicrotask(() => {
+          if (publishVersion !== listVersionRef.current) {
+            publishScheduledRef.current = false
+            return
+          }
+          publishScheduledRef.current = false
+          setDerivedState((currentState) => {
+            const pendingState = pendingDerivedStateRef.current
+            return currentState === pendingState ? currentState : pendingState
+          })
+        })
+      },
+      []
+    )
 
     // Wrap channelRenderFilterFn to restore pending messages for all channels
     // as soon as they are loaded, without waiting for the user to click into each one.
@@ -42,11 +87,23 @@ export const ChannelList = React.memo<ChannelListProps>(
         for (const channel of channels) {
           restorePendingMessages(channel)
         }
-        return channelRenderFilterFn
+
+        const visibleChannels = channelRenderFilterFn
           ? channelRenderFilterFn(channels)
           : channels
+
+        publishDerivedState({
+          isInitialLoadSettled: true,
+          channels: visibleChannels,
+          rawChannels: channels,
+          hasChannels: visibleChannels.length > 0,
+          unreadCount: visibleChannels.filter((channel) => channel.countUnread() > 0)
+            .length,
+        })
+
+        return visibleChannels
       },
-      [channelRenderFilterFn]
+      [channelRenderFilterFn, publishDerivedState]
     )
 
     if (debug) {
@@ -74,6 +131,17 @@ export const ChannelList = React.memo<ChannelListProps>(
       ]
     )
 
+    React.useEffect(() => {
+      listVersionRef.current += 1
+      pendingDerivedStateRef.current = EMPTY_DERIVED_STATE
+      publishScheduledRef.current = false
+      setDerivedState(EMPTY_DERIVED_STATE)
+    }, [listIdentityKey])
+
+    React.useEffect(() => {
+      onStateChange?.(derivedState)
+    }, [derivedState, onStateChange])
+
     return (
       <div
         className={classNames(
@@ -85,7 +153,7 @@ export const ChannelList = React.memo<ChannelListProps>(
         <div className="flex-1 overflow-hidden min-w-0">
           <ChannelListProvider value={contextValue}>
             <StreamChannelList
-              key={`${JSON.stringify(filters)}:${JSON.stringify(sort)}`}
+              key={listIdentityKey}
               filters={filters}
               sort={sort}
               options={{ limit: 30 }}

package/src/index.ts

@@ -48,6 +48,7 @@ export type { ParticipantDisplayUser } from './utils/resolveParticipantDisplayNa
 
 // Types
 export type {
+  ChannelListDerivedState,
   MessagingShellProps,
   ChannelListProps,
   ChannelViewProps,

package/src/types.ts

@@ -52,6 +52,36 @@ export interface MessagingCapabilities {
   showDeleteConversation?: boolean
 }
 
+/**
+ * Derived state reported by the mounted ChannelList instance.
+ *
+ * This reflects the currently loaded list data only. It does not guarantee
+ * complete server-side truth for channels outside the mounted list's current
+ * query window or cache.
+ */
+export interface ChannelListDerivedState {
+  /**
+   * Whether the mounted list has completed its first channel-resolution pass.
+   */
+  isInitialLoadSettled: boolean
+  /**
+   * Visible channels after `channelRenderFilterFn` is applied.
+   */
+  channels: Channel[]
+  /**
+   * Raw channels received from Stream before client-side filtering.
+   */
+  rawChannels: Channel[]
+  /**
+   * Convenience flag for empty-state consumers. Mirrors `channels.length > 0`.
+   */
+  hasChannels: boolean
+  /**
+   * Number of visible channels with at least one unread message.
+   */
+  unreadCount: number
+}
+
 /**
  * ChannelList component props
  */
@@ -97,6 +127,14 @@ export interface ChannelListProps {
    * Falls back to message.text when no matching translation exists.
    */
   viewerLanguage?: string
+  /**
+   * Reports derived state from the mounted Stream ChannelList instance.
+   *
+   * This callback is driven by currently loaded list data only. Use it for
+   * cache/list-derived UI state such as empty-state confirmation or visible
+   * unread badges; do not assume it represents complete server-side truth.
+   */
+  onStateChange?: (state: ChannelListDerivedState) => void
 }
 
 /**