@spscommerce/max 0.3.0 → 0.5.0

package/lib/MaxPanel.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import { FeatureFlagsTitles } from "./models/FeatureFlagsTitles";
 import { CurrentApp } from "./models/CurrentApp";
 import { CurrentUser } from "./models/CurrentUser";
+import type { AdditionalContextProvider } from "./models/AdditionalContext";
 export declare function MaxPanel({ token, currentUser, hideAgentPanel, isAgentPanelOpen, isInCustomerView, flags, env, currentApp, context, currentConversationId, locale, }: {
     token: string | null;
     currentUser: CurrentUser | undefined;
@@ -11,7 +12,7 @@ export declare function MaxPanel({ token, currentUser, hideAgentPanel, isAgentPa
     flags: FeatureFlagsTitles;
     env: string;
     currentApp: CurrentApp;
-    context: () => Record<any, any>;
+    context: AdditionalContextProvider;
     currentConversationId?: string | null;
     locale?: string;
 }): React.ReactNode;

package/lib/api-service.d.ts

@@ -1,4 +1,5 @@
 import { ConversationList, ConversationMessages } from "./models/Conversation";
+import type { AdditionalContext } from "./models/AdditionalContext";
 import type { UsageStatus } from "./models/UsageStatus";
 export declare class AgentApiService {
     private readonly url;
@@ -19,5 +20,5 @@ export declare class AgentApiService {
     deleteConversation: (conversationId: string) => Promise<void>;
     postFeedback: (messageId: string, score: string, comment: string) => Promise<void>;
     fetchUsageStatus: (userId: string) => Promise<UsageStatus>;
-    postChat(message: string, currentAppName: string, currentConversationId: string | null, agentContext: object, currentUrl: string, appInitiated: boolean, userTimezone: string | null): Promise<unknown>;
+    postChat(message: string, currentAppName: string, currentConversationId: string | null, agentContext: AdditionalContext, currentUrl: string, appInitiated: boolean, userTimezone: string | null): Promise<unknown>;
 }

package/lib/components/ChatLoadingStatus.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+type LoadingStatusProps = {
+    label: string;
+};
+export declare function OlderMessagesLoadingStatus({ label }: LoadingStatusProps): React.ReactNode;
+export declare function ConversationSwitchLoadingStatus({ label }: LoadingStatusProps): React.ReactNode;
+export {};

package/lib/components/MaxPanelHeaderActions.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+type MaxPanelHeaderActionsProps = {
+    isCompact: boolean;
+    showConversationList: boolean;
+    conversationToggleLabel: string;
+    newConversationLabel: string;
+    newConversationCompactTitle: string;
+    closePanelLabel: string;
+    onToggleConversationList: () => void;
+    onStartNewConversation: () => void;
+    onClosePanel: () => void;
+};
+export declare function MaxPanelHeaderActions({ isCompact, showConversationList, conversationToggleLabel, newConversationLabel, newConversationCompactTitle, closePanelLabel, onToggleConversationList, onStartNewConversation, onClosePanel, }: MaxPanelHeaderActionsProps): React.ReactNode;
+export {};

package/lib/components/index.d.ts

@@ -0,0 +1,2 @@
+export { ConversationSwitchLoadingStatus, OlderMessagesLoadingStatus } from "./ChatLoadingStatus";
+export { MaxPanelHeaderActions } from "./MaxPanelHeaderActions";

package/lib/hooks/scrollStateMachine.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Primary phase. Mutually exclusive — exactly one is active at any time.
+ *
+ * - `idle`            — No active conversation; landing surface.
+ * - `switch-pending`  — A conversation switch (or initial load with an
+ *                       existing conversation id) was requested. Waiting
+ *                       for the messages fetch to resolve.
+ * - `switch-settling` — Fetch resolved. Layout is settling; the controller
+ *                       is actively snapping the viewport to the bottom and
+ *                       waiting for late-arriving content (images, async
+ *                       markdown rendering, feedback widgets) to commit.
+ * - `ready`           — Steady state: pin, streaming follow, scroll-to-
+ *                       bottom button, and pagination all behave per their
+ *                       own side-channel state.
+ */
+export type ScrollPhase = "idle" | "switch-pending" | "switch-settling" | "ready";
+/**
+ * Active user-message anchor. Set when the user sends a message, cleared
+ * when a conversation switch begins or the message is replaced. The
+ * controller pins the referenced message near the top of the viewport.
+ *
+ * `expansionTargetTop` is the synthetic min-height target applied to
+ * `.conversation-section` when natural content does not provide enough
+ * scroll room to honor the pin. `null` means no expansion is active.
+ */
+export type UserPinAnchor = {
+    messageId: string;
+    expansionTargetTop: number | null;
+};
+/**
+ * Scroll position captured at the start of an older-messages load. Used
+ * after the prepend lands to restore the user's viewport so the visible
+ * messages do not appear to jump.
+ */
+export type OlderLoadCapture = {
+    savedScrollTop: number;
+    savedScrollHeight: number;
+};
+export type ScrollState = {
+    readonly phase: ScrollPhase;
+    readonly streamingFollowEngaged: boolean;
+    readonly userPin: UserPinAnchor | null;
+    readonly userPinApplied: boolean;
+    readonly olderLoad: OlderLoadCapture | null;
+    readonly programmaticLockActive: boolean;
+};
+export declare const initialScrollState: ScrollState;
+export type ScrollAction = {
+    type: "CONVERSATION_SWITCH_REQUESTED";
+} | {
+    type: "CONVERSATION_LOAD_RESOLVED";
+} | {
+    type: "SWITCH_SETTLE_COMPLETE";
+} | {
+    type: "USER_MESSAGE_ANCHORED";
+    messageId: string;
+} | {
+    type: "USER_PIN_APPLIED";
+    expansionTargetTop: number | null;
+} | {
+    type: "USER_PIN_EXPANSION_CLEARED";
+} | {
+    type: "USER_PIN_CLEARED";
+} | {
+    type: "STREAMING_FOLLOW_ENGAGED";
+} | {
+    type: "STREAMING_FOLLOW_DISENGAGED";
+} | {
+    type: "STREAMING_ENDED";
+} | {
+    type: "PROGRAMMATIC_LOCK_ENGAGED";
+} | {
+    type: "PROGRAMMATIC_LOCK_RELEASED";
+} | {
+    type: "OLDER_LOAD_STARTED";
+    savedScrollTop: number;
+    savedScrollHeight: number;
+} | {
+    type: "OLDER_LOAD_RESOLVED";
+};
+/**
+ * Apply an action to the state. Pure function — no I/O. Every transition is
+ * named; unreachable transitions return state unchanged.
+ *
+ * INVARIANT: `userPinApplied` only becomes true via `USER_PIN_APPLIED`, and
+ * is reset to false on every `USER_MESSAGE_ANCHORED` and switch lifecycle
+ * action. The controller relies on this for the "pin only once per
+ * message" guarantee.
+ */
+export declare function scrollReducer(state: ScrollState, action: ScrollAction): ScrollState;
+export type ChatSurfaceState = "initial-loading" | "switch-loading" | "ready";
+/**
+ * Externally observable scroll state value, emitted as `data-scroll-state`
+ * on the scroll wrapper. Order of precedence: switch lifecycle > interaction
+ * mode > steady. Stable string set documented for downstream consumers
+ * (tests, Playwright selectors, Clarity recordings).
+ */
+export type ScrollStateAttribute = "idle" | "switch-pending" | "switch-settling" | "streaming-follow" | "user-pin-active" | "ready";
+export declare function selectScrollStateAttribute(state: ScrollState): ScrollStateAttribute;
+export declare function selectChatSurfaceState(args: {
+    state: ScrollState;
+    loading: boolean;
+    isActiveChat: boolean;
+    showConversationList: boolean;
+}): ChatSurfaceState;
+/**
+ * Whether the scroll-to-bottom button should be visible. Pure: caller
+ * measures the DOM and passes the values in.
+ *
+ * Hidden during switch lifecycle (the user is transitioning conversations,
+ * showing the button would flash). Hidden while the only "distance to
+ * bottom" comes from synthetic pin expansion (not real new content).
+ * Otherwise visible iff `distanceToBottom > threshold`.
+ */
+export declare function selectShowScrollToBottom(args: {
+    state: ScrollState;
+    scrollHeight: number;
+    clientHeight: number;
+    scrollTop: number;
+    isStreaming: boolean;
+    threshold: number;
+}): boolean;
+/**
+ * Whether the controller is in the user-visible "transitioning" window
+ * (switch-pending or switch-settling). Used by the loading UI and to
+ * gate IntersectionObserver pagination triggers.
+ */
+export declare function selectIsTransitioning(state: ScrollState): boolean;

package/lib/hooks/useMaxChat.d.ts

@@ -1,12 +1,12 @@
 import { Chat } from "../models/Chat";
 import { Conversation, Message } from "../models/Conversation";
 import { AgentApiService } from "../api-service";
-export declare function useMaxChat(agentApi: AgentApiService, context: () => Record<any, any>): {
+import type { AdditionalContextProvider } from "../models/AdditionalContext";
+export declare function useMaxChat(agentApi: AgentApiService, context: AdditionalContextProvider): {
     error: boolean;
     loading: boolean;
     isAgentThinking: boolean;
     messages: Chat[];
-    displayedMessages: Chat[];
     hasMoreMessages: boolean;
     loadOlderMessages: () => Promise<void>;
     isLoadingOlderMessages: boolean;

package/lib/hooks/useMaxPanelScrollController.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+import { Chat } from "../models/Chat";
+import { ChatSurfaceState, ScrollAction, ScrollStateAttribute } from "./scrollStateMachine";
+type UseMaxPanelScrollControllerArgs = {
+    isAgentPanelOpen?: boolean;
+    currentConversationId: string | null | undefined;
+    showConversationList: boolean;
+    loading: boolean;
+    messages: Chat[];
+    messageHasBeenSent: boolean;
+    isAgentThinking: boolean;
+    streamingResponse?: string;
+    hasMoreMessages: boolean;
+    isLoadingOlderMessages: boolean;
+    loadOlderMessages: () => Promise<void>;
+};
+type UseMaxPanelScrollControllerResult = {
+    scrollWrapperRef: React.MutableRefObject<HTMLDivElement | null>;
+    sentinelRef: React.MutableRefObject<HTMLDivElement | null>;
+    showScrollToBottom: boolean;
+    isConversationTransitioning: boolean;
+    isStreaming: boolean;
+    isActiveChat: boolean;
+    chatSurfaceState: ChatSurfaceState;
+    scrollStateAttribute: ScrollStateAttribute;
+    prepareConversationSwitchSnap: () => void;
+    scrollToLatest: () => void;
+};
+export declare function useMaxPanelScrollController(args: UseMaxPanelScrollControllerArgs): UseMaxPanelScrollControllerResult;
+export type { ScrollAction };

package/lib/index.d.ts

@@ -1,3 +1,6 @@
 import "./max.scss";
 export * from "./icons";
 export * from "./MaxPanel";
+export type { AdditionalContext, AdditionalContextProvider } from "./models/AdditionalContext";
+export type { CurrentApp } from "./models/CurrentApp";
+export type { FeatureFlagsTitles } from "./models/FeatureFlagsTitles";