@stapel/chat-react 0.1.0

package/src/default/ConversationListPanel.tsx

@@ -0,0 +1,163 @@
+/**
+ * `<ConversationListPanel/>` — the default skin for the inbox, and the screen
+ * this pair's nav manifest mounts (`chat.conversations`, member surface).
+ *
+ * Built entirely on the headless `<ConversationList>`: this file makes visual
+ * decisions and nothing else.
+ */
+import type { ReactElement } from "react";
+import { Badge, Button, Card, Empty, List, Space, Spin, Typography } from "antd";
+import { matchList, useErrorDisplay, useI18n, useT } from "@stapel/core";
+import type { Conversation } from "../api/types.js";
+import { ConversationList } from "../headless/ConversationList.js";
+import { CHAT_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+const KIND_KEYS: Record<string, string> = {
+  direct: CHAT_I18N_KEYS.kindDirect,
+  group: CHAT_I18N_KEYS.kindGroup,
+  support: CHAT_I18N_KEYS.kindSupport,
+};
+
+export interface ConversationListPanelProps {
+  /** Page size for the underlying list. */
+  limit?: number;
+  /**
+   * Where a row leads, as an href — the SSR-friendly half. A storefront
+   * renders real links so a conversation is right-clickable and indexable by
+   * the browser's own history, not only by a click handler.
+   */
+  openHref?: (conversationId: string) => string;
+  /** Where a row leads, in a SPA. Used when `openHref` is not given. */
+  onOpen?: (conversationId: string) => void;
+}
+
+function relativeTime(locale: string, iso: string): string {
+  // A timestamp is data, not copy: `Intl` localizes it from the host's own
+  // locale, so it needs no i18n key and cannot go stale in a catalogue.
+  const parsed = Date.parse(iso);
+  if (Number.isNaN(parsed)) return "";
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "short",
+    timeStyle: "short",
+  }).format(parsed);
+}
+
+export function ConversationListPanel(
+  props: ConversationListPanelProps = {}
+): ReactElement {
+  const t = useT();
+  const { locale } = useI18n();
+  // Never the raw `.message` — for a response with no error envelope that is
+  // the transport's own "Request failed with status 500".
+  const errorDisplay = useErrorDisplay(CHAT_I18N_KEYS.unknownError);
+  const { openHref, onOpen } = props;
+
+  const renderRow = (row: Conversation): ReactElement => {
+    const kindKey = KIND_KEYS[row.kind] ?? CHAT_I18N_KEYS.kindDirect;
+    const title = t(kindKey);
+    return (
+      <List.Item
+        data-testid="chat-conversation-row"
+        extra={
+          row.unread_count > 0 ? (
+            <Badge
+              count={row.unread_count}
+              // The badge is a number; the accessible sentence is the key.
+              title={t(CHAT_I18N_KEYS.listUnread, { count: row.unread_count })}
+            />
+          ) : null
+        }
+      >
+        <List.Item.Meta
+          title={
+            openHref ? (
+              <Typography.Link href={openHref(row.id)}>{title}</Typography.Link>
+            ) : onOpen ? (
+              <Button
+                type="link"
+                style={{ padding: 0 }}
+                onClick={() => onOpen(row.id)}
+                data-analytics="none"
+                data-analytics-reason="navigation into a thread — the host app wraps this with its own tracked(); pairs carry no @stapel/analytics runtime dependency by architecture"
+              >
+                {title}
+              </Button>
+            ) : (
+              // Neither route given: a title, not a control that goes
+              // nowhere. A dead affordance is worse than none.
+              <Typography.Text strong>{title}</Typography.Text>
+            )
+          }
+          description={
+            <Typography.Text type="secondary">
+              {relativeTime(locale, row.updated_at)}
+            </Typography.Text>
+          }
+        />
+      </List.Item>
+    );
+  };
+
+  return (
+    <ConversationList {...(props.limit !== undefined ? { limit: props.limit } : {})}>
+      {({ state, hasNextPage, isFetchingNextPage, fetchNextPage, refetch }) => (
+        <Card data-testid="chat-conversation-list">
+          <Typography.Title level={4} style={{ marginTop: 0 }}>
+            {t(CHAT_I18N_KEYS.listTitle)}
+          </Typography.Title>
+
+          {matchList(state, {
+            loading: () => <Spin style={{ marginTop: 16 }} />,
+            // One arm owns the failure; the empty copy is unreachable from
+            // here, so an outage can never render as "no conversations yet".
+            failed: (error) => (
+              <div style={{ marginTop: 16 }} data-testid="chat-conversation-list-error">
+                <ErrorAlert error={errorDisplay(error)} />
+                <Button
+                  style={{ marginTop: 12 }}
+                  onClick={refetch}
+                  data-analytics="none"
+                  data-analytics-reason="recovery affordance for a failed read — host app wraps with its own tracked()"
+                >
+                  {t(CHAT_I18N_KEYS.listRetry)}
+                </Button>
+              </div>
+            ),
+            empty: () => (
+              <Empty
+                style={{ marginTop: 16 }}
+                data-testid="chat-conversation-list-empty"
+                description={t(CHAT_I18N_KEYS.listEmpty)}
+              />
+            ),
+            ready: (rows) => (
+              <Space direction="vertical" style={{ width: "100%" }}>
+                <List<Conversation>
+                  style={{ marginTop: 16 }}
+                  dataSource={[...rows]}
+                  rowKey={(row) => row.id}
+                  renderItem={renderRow}
+                />
+                {hasNextPage ? (
+                  <Button
+                    loading={isFetchingNextPage}
+                    onClick={() => fetchNextPage()}
+                    data-analytics="none"
+                    data-analytics-reason="business action — host app wraps with its own tracked()"
+                  >
+                    {t(CHAT_I18N_KEYS.listLoadMore)}
+                  </Button>
+                ) : (
+                  <Typography.Text type="secondary">
+                    {t(CHAT_I18N_KEYS.listEnd)}
+                  </Typography.Text>
+                )}
+              </Space>
+            ),
+          })}
+        </Card>
+      )}
+    </ConversationList>
+  );
+}

package/src/default/ConversationThreadPanel.tsx

@@ -0,0 +1,245 @@
+/**
+ * `<ConversationThreadPanel/>` — the default skin for one thread: the messages,
+ * the "show earlier" control, a live/polling indicator, and the composer.
+ *
+ * The transport indicator is the ONLY place a person is told how freshness
+ * arrives, and it is a label, never a behaviour: nothing else on this screen
+ * branches on it. That is the seam holding — the same component renders a
+ * socket-fed thread and a polled one.
+ */
+import type { CSSProperties, ReactElement } from "react";
+import { Button, Card, Empty, Flex, Input, Space, Spin, Tag, Typography } from "antd";
+import {
+  matchList,
+  useActionGate,
+  useErrorDisplay,
+  useI18n,
+  useT,
+} from "@stapel/core";
+import type { ChatMessage } from "../api/types.js";
+import { ConversationThread } from "../headless/ConversationThread.js";
+import { MessageComposer } from "../headless/MessageComposer.js";
+import type { ChatTransport } from "../flows/freshness.js";
+import { CHAT_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+const TRANSPORT_KEYS: Record<ChatTransport, string> = {
+  socket: CHAT_I18N_KEYS.transportLive,
+  polling: CHAT_I18N_KEYS.transportPolling,
+  idle: CHAT_I18N_KEYS.transportIdle,
+};
+
+export interface ConversationThreadPanelProps {
+  conversationId: string;
+  /** The reader, when the host knows them — used only to align their own
+   * lines. Absent, every message is rendered the same way rather than
+   * guessed at. */
+  viewerId?: string | null;
+  limit?: number;
+  maxLength?: number;
+}
+
+function MessageRow(props: {
+  message: ChatMessage;
+  viewerId: string | null | undefined;
+  locale: string;
+}): ReactElement {
+  const t = useT();
+  const { message, viewerId, locale } = props;
+  const isSystem = message.kind === "system";
+  const isOwn =
+    !isSystem && viewerId != null && message.sender_id === viewerId;
+  const bubble: CSSProperties = {
+    alignSelf: isOwn ? "flex-end" : "flex-start",
+    maxWidth: "42rem",
+  };
+  const stamp = Number.isNaN(Date.parse(message.created_at))
+    ? ""
+    : new Intl.DateTimeFormat(locale, { timeStyle: "short" }).format(
+        Date.parse(message.created_at)
+      );
+  return (
+    <div style={bubble} data-testid="chat-message" data-seq={message.seq}>
+      {isSystem ? (
+        <Typography.Text type="secondary">
+          {t(CHAT_I18N_KEYS.threadSystem)}
+        </Typography.Text>
+      ) : null}
+      <Typography.Paragraph style={{ marginBottom: 0 }}>
+        {message.body}
+      </Typography.Paragraph>
+      <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+        {stamp}
+      </Typography.Text>
+    </div>
+  );
+}
+
+function Composer(props: {
+  conversationId: string;
+  maxLength: number | undefined;
+}): ReactElement {
+  const t = useT();
+  const errorDisplay = useErrorDisplay(CHAT_I18N_KEYS.unknownError);
+  return (
+    <MessageComposer
+      conversationId={props.conversationId}
+      {...(props.maxLength !== undefined ? { maxLength: props.maxLength } : {})}
+    >
+      {({ value, setValue, availability, isSending, error, send, maxLength, length }) => (
+        <ComposerBody
+          value={value}
+          setValue={setValue}
+          isSending={isSending}
+          send={send}
+          maxLength={maxLength}
+          length={length}
+          availability={availability}
+          errorNode={<ErrorAlert error={errorDisplay(error)} />}
+          t={t}
+        />
+      )}
+    </MessageComposer>
+  );
+}
+
+/** Split out so `useActionGate` is called from a component, not a callback. */
+function ComposerBody(props: {
+  value: string;
+  setValue: (next: string) => void;
+  isSending: boolean;
+  send: () => void;
+  maxLength: number;
+  length: number;
+  availability: Parameters<typeof useActionGate>[0];
+  errorNode: ReactElement | null;
+  t: (key: string, params?: Readonly<Record<string, unknown>>) => string;
+}): ReactElement {
+  const gate = useActionGate(props.availability);
+  const { t } = props;
+  return (
+    <Space direction="vertical" style={{ width: "100%" }}>
+      {props.errorNode}
+      <Input.TextArea
+        value={props.value}
+        onChange={(event) => props.setValue(event.target.value)}
+        placeholder={t(CHAT_I18N_KEYS.composerPlaceholder)}
+        autoSize={{ minRows: 2, maxRows: 6 }}
+        data-testid="chat-composer-input"
+      />
+      <Flex align="center" gap={12} wrap="wrap">
+        <Button
+          type="primary"
+          disabled={gate.disabled}
+          loading={props.isSending}
+          onClick={props.send}
+          data-testid="chat-composer-send"
+          data-analytics="none"
+          data-analytics-reason="business action — host app wraps with its own tracked()"
+        >
+          {props.isSending
+            ? t(CHAT_I18N_KEYS.composerSending)
+            : t(CHAT_I18N_KEYS.composerSend)}
+        </Button>
+        {/* A switched-off control states its reason as TEXT: a disabled
+            button takes no pointer events, so a tooltip would be a reason
+            nobody can read. */}
+        {gate.reason ? (
+          <Typography.Text type="secondary" data-testid="chat-composer-blocked">
+            {gate.reason}
+          </Typography.Text>
+        ) : null}
+        <Typography.Text type="secondary" style={{ marginLeft: "auto" }}>
+          {`${props.length}/${props.maxLength}`}
+        </Typography.Text>
+      </Flex>
+    </Space>
+  );
+}
+
+export function ConversationThreadPanel(
+  props: ConversationThreadPanelProps
+): ReactElement {
+  const t = useT();
+  const { locale } = useI18n();
+  const errorDisplay = useErrorDisplay(CHAT_I18N_KEYS.unknownError);
+
+  return (
+    <ConversationThread
+      conversationId={props.conversationId}
+      {...(props.limit !== undefined ? { limit: props.limit } : {})}
+    >
+      {({ state, hasOlder, isLoadingOlder, loadOlder, refetch, transport }) => (
+        <Card data-testid="chat-thread">
+          <Flex justify="space-between" align="center" style={{ marginBottom: 12 }}>
+            <Typography.Title level={4} style={{ margin: 0 }}>
+              {t(CHAT_I18N_KEYS.listTitle)}
+            </Typography.Title>
+            <Tag data-testid="chat-transport" data-transport={transport}>
+              {t(TRANSPORT_KEYS[transport])}
+            </Tag>
+          </Flex>
+
+          {matchList(state, {
+            loading: () => <Spin />,
+            failed: (error) => (
+              <div data-testid="chat-thread-error">
+                <ErrorAlert error={errorDisplay(error)} />
+                <Button
+                  style={{ marginTop: 12 }}
+                  onClick={refetch}
+                  data-analytics="none"
+                  data-analytics-reason="recovery affordance for a failed read — host app wraps with its own tracked()"
+                >
+                  {t(CHAT_I18N_KEYS.threadRetry)}
+                </Button>
+              </div>
+            ),
+            empty: () => (
+              <Empty
+                data-testid="chat-thread-empty"
+                description={t(CHAT_I18N_KEYS.threadEmpty)}
+              />
+            ),
+            ready: (messages) => (
+              <Space direction="vertical" style={{ width: "100%" }}>
+                {hasOlder ? (
+                  <Button
+                    loading={isLoadingOlder}
+                    onClick={loadOlder}
+                    data-testid="chat-thread-older"
+                    data-analytics="none"
+                    data-analytics-reason="business action — host app wraps with its own tracked()"
+                  >
+                    {t(CHAT_I18N_KEYS.threadLoadOlder)}
+                  </Button>
+                ) : (
+                  <Typography.Text type="secondary">
+                    {t(CHAT_I18N_KEYS.threadBeginning)}
+                  </Typography.Text>
+                )}
+                <Flex vertical gap={8} style={{ width: "100%" }}>
+                  {messages.map((message) => (
+                    <MessageRow
+                      key={message.id}
+                      message={message}
+                      viewerId={props.viewerId}
+                      locale={locale}
+                    />
+                  ))}
+                </Flex>
+              </Space>
+            ),
+          })}
+
+          <div style={{ marginTop: 16 }}>
+            <Composer
+              conversationId={props.conversationId}
+              maxLength={props.maxLength}
+            />
+          </div>
+        </Card>
+      )}
+    </ConversationThread>
+  );
+}

package/src/default/ErrorAlert.tsx

@@ -0,0 +1,43 @@
+/**
+ * The one error surface this pair's default skins render, so the split copy
+ * core produces reaches a screen the same way everywhere.
+ *
+ * Core's `describeFlowError` splits a failure into the sentence a person reads
+ * and the technical detail a support agent quotes. The split is only worth
+ * anything if a skin renders both halves at their own weights: `message` at
+ * normal weight, `detail` muted and small, where an eye skips it and a support
+ * agent finds it.
+ *
+ * `undefined` in — including a `detail` core left `undefined` because there
+ * was nothing worth quoting — renders nothing rather than an empty muted line.
+ */
+import { Alert, Typography } from "antd";
+import type { CSSProperties, ReactElement } from "react";
+import type { FlowErrorDisplay } from "@stapel/core";
+
+export function ErrorAlert(props: {
+  error: FlowErrorDisplay | undefined;
+  style?: CSSProperties | undefined;
+  testId?: string | undefined;
+}): ReactElement | null {
+  const { error } = props;
+  if (!error) return null;
+  return (
+    <Alert
+      type="error"
+      showIcon
+      {...(props.style ? { style: props.style } : {})}
+      {...(props.testId ? { "data-testid": props.testId } : {})}
+      message={error.message}
+      {...(error.detail
+        ? {
+            description: (
+              <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+                {error.detail}
+              </Typography.Text>
+            ),
+          }
+        : {})}
+    />
+  );
+}

package/src/default/StartChatButton.tsx

@@ -0,0 +1,78 @@
+/**
+ * `<StartChatButton/>` — "message the seller" on a listing card, skinned.
+ *
+ * The control is either pressable or switched off WITH a sentence beside it
+ * (no seller on the listing; the listing is your own). It never renders as a
+ * grey rectangle with no explanation.
+ */
+import type { ReactElement } from "react";
+import { Button, Space, Typography } from "antd";
+import { useActionGate, useErrorDisplay, useT } from "@stapel/core";
+import type { ActionAvailability } from "@stapel/core";
+import type { Conversation } from "../api/types.js";
+import { StartDirectChat } from "../headless/StartDirectChat.js";
+import { CHAT_I18N_KEYS } from "../i18n/keys.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export interface StartChatButtonProps {
+  sellerId: string | null | undefined;
+  viewerId?: string | null;
+  onOpened?: (conversation: Conversation) => void;
+  block?: boolean;
+}
+
+function StartChatBody(props: {
+  availability: ActionAvailability;
+  isStarting: boolean;
+  error: unknown;
+  start: () => void;
+  block: boolean | undefined;
+}): ReactElement {
+  const t = useT();
+  const gate = useActionGate(props.availability);
+  const errorDisplay = useErrorDisplay(CHAT_I18N_KEYS.unknownError);
+  return (
+    <Space direction="vertical" style={{ width: props.block ? "100%" : undefined }}>
+      <Button
+        type="primary"
+        block={props.block ?? false}
+        disabled={gate.disabled}
+        loading={props.isStarting}
+        onClick={props.start}
+        data-testid="chat-start-button"
+        data-analytics="none"
+        data-analytics-reason="business action — host app wraps with its own tracked()"
+      >
+        {props.isStarting
+          ? t(CHAT_I18N_KEYS.startStarting)
+          : t(CHAT_I18N_KEYS.startButton)}
+      </Button>
+      {gate.reason ? (
+        <Typography.Text type="secondary" data-testid="chat-start-blocked">
+          {gate.reason}
+        </Typography.Text>
+      ) : null}
+      <ErrorAlert error={errorDisplay(props.error)} />
+    </Space>
+  );
+}
+
+export function StartChatButton(props: StartChatButtonProps): ReactElement {
+  return (
+    <StartDirectChat
+      sellerId={props.sellerId}
+      {...(props.viewerId !== undefined ? { viewerId: props.viewerId } : {})}
+      {...(props.onOpened !== undefined ? { onOpened: props.onOpened } : {})}
+    >
+      {({ availability, isStarting, error, start }) => (
+        <StartChatBody
+          availability={availability}
+          isStarting={isStarting}
+          error={error}
+          start={start}
+          block={props.block}
+        />
+      )}
+    </StartDirectChat>
+  );
+}

package/src/default/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@stapel/chat-react/default` — the opt-in antd skin for this pair (mirrors
+ * auth-react's `/default` split, §54): a separate entry point so consumers who
+ * bring their own visuals never pull `antd` into their bundle; importing this
+ * subpath is the opt-in.
+ *
+ * ```tsx
+ * import {
+ *   ConversationListPanel,
+ *   ConversationThreadPanel,
+ *   StartChatButton,
+ * } from "@stapel/chat-react/default";
+ * ```
+ */
+export { ConversationListPanel } from "./ConversationListPanel.js";
+export type { ConversationListPanelProps } from "./ConversationListPanel.js";
+export { ConversationThreadPanel } from "./ConversationThreadPanel.js";
+export type { ConversationThreadPanelProps } from "./ConversationThreadPanel.js";
+export { StartChatButton } from "./StartChatButton.js";
+export type { StartChatButtonProps } from "./StartChatButton.js";

package/src/flows/errors.ts

@@ -0,0 +1,16 @@
+import { toFlowError as coreToFlowError } from "@stapel/core";
+import type { FlowError } from "@stapel/core";
+
+export type { FlowError } from "@stapel/core";
+export { isErrorCode } from "@stapel/core";
+
+/**
+ * Fold any thrown value into a {@link FlowError} using this pair's own
+ * module-scoped fallback key (`chat.error.unknown`, an en string in
+ * `chatI18nBundleEn`) so a non-`StapelApiError` fault still renders real copy
+ * rather than a raw key. The primitive lives in `@stapel/core`
+ * (frontend-core-architecture §4b); this wrapper only pins the fallback.
+ */
+export function toFlowError(error: unknown): FlowError {
+  return coreToFlowError(error, "chat.error.unknown");
+}