@q9labsai/chalk-react-native 4.1.17 → 5.0.1

package/src/sheets/people-chat/PhotoViewer.tsx

@@ -0,0 +1,132 @@
+import type { ChatAttachment } from "@q9labsai/chalk-client";
+import { useEffect, useRef, type RefObject } from "react";
+import { AccessibilityInfo, findNodeHandle, Image, Pressable, StyleSheet, View } from "react-native";
+import Animated, { ReduceMotion, withTiming, type EntryExitAnimationFunction } from "react-native-reanimated";
+import { useBackHandler } from "../../frame/back-handler";
+import { useDeviceLayout } from "../../frame/device-layout";
+import { Portal } from "../../frame/portal";
+import { Icon, type IconName } from "../../icons/Icon";
+import { usePressAnimation } from "../../motion/press";
+import { announce } from "../../primitives/announce";
+import { ChalkText } from "../../primitives/ChalkText";
+import { durations, easings, fontFamilies, viewer } from "../../theme/tokens";
+import { useAttachmentSource, useDownload } from "./attachments";
+
+export type ViewedPhotos = {
+  readonly photos: readonly ChatAttachment[];
+  readonly index: number;
+  /** "You" or the sender's name, then the time: the viewer's second line. */
+  readonly from: string;
+};
+
+type PhotoViewerProps = {
+  readonly viewing: ViewedPhotos;
+  readonly onChange: (index: number) => void;
+  readonly onClose: () => void;
+};
+
+/**
+ * The photo viewer (`.lbw`): dark in both themes, above the sheets. The name, sender and place in
+ * the set sit at the top with Download and Close; Previous and Next sit at the bottom.
+ */
+export function PhotoViewer({ viewing, onChange, onClose }: PhotoViewerProps): React.JSX.Element | null {
+  const layout = useDeviceLayout();
+  const download = useDownload();
+  const closeRef = useRef<View>(null);
+  const { photos, index, from } = viewing;
+  const photo = photos[index] ?? photos[0];
+  const count = photos.length;
+  useBackHandler(true, onClose);
+  useEffect(() => {
+    const node = closeRef.current && findNodeHandle(closeRef.current);
+    if (node) AccessibilityInfo.setAccessibilityFocus(node);
+  }, []);
+  const go = (step: number) => {
+    const next = (index + step + count) % count;
+    onChange(next);
+    announce(`Image ${next + 1} of ${count}`);
+  };
+  if (!photo) return null;
+  return (
+    <Portal layer="menus">
+      <Animated.View accessibilityLabel="Image viewer" accessibilityViewIsModal entering={fadeIn} exiting={fadeOut} onAccessibilityEscape={onClose} style={[StyleSheet.absoluteFill, styles.root]} testID="chat.viewer">
+        <View style={[styles.top, { paddingTop: Math.max(52, layout.insets.top), paddingLeft: 16 + layout.insets.left, paddingRight: 8 + layout.insets.right }]}>
+          <View style={styles.title}>
+            <ChalkText color={viewer.text} numberOfLines={1} variant="bodyStrong">
+              {photo.fileName}
+            </ChalkText>
+            <ChalkText color={viewer.textMuted} style={styles.detail} variant="label">
+              {count > 1 ? `${from} · ${index + 1} of ${count}` : from}
+            </ChalkText>
+          </View>
+          <ViewerButton icon="dl" label={`Download ${photo.fileName}`} onPress={() => download(photo)} testID="chat.viewer.download" />
+          <ViewerButton icon="x" label="Close" buttonRef={closeRef} onPress={onClose} testID="chat.viewer.close" />
+        </View>
+        <Pressable accessible={false} onPress={onClose} style={styles.stage}>
+          <Photo attachment={photo} />
+          {count > 1 ? (
+            <View style={styles.arrows}>
+              <ViewerButton icon="left" label="Previous image" onPress={() => go(-1)} testID="chat.viewer.previous" />
+              <ViewerButton icon="right" label="Next image" onPress={() => go(1)} testID="chat.viewer.next" />
+            </View>
+          ) : null}
+        </Pressable>
+      </Animated.View>
+    </Portal>
+  );
+}
+
+function Photo({ attachment }: { readonly attachment: ChatAttachment }): React.JSX.Element {
+  const source = useAttachmentSource(attachment);
+  return (
+    <View pointerEvents="none" style={styles.photoBox}>
+      {source.state === "ready" ? <Image accessibilityLabel={attachment.fileName} resizeMode="contain" source={{ uri: source.uri }} style={styles.photo} /> : <Icon color={viewer.textMuted} name="img" size={24} />}
+    </View>
+  );
+}
+
+type ViewerButtonProps = {
+  readonly icon: IconName;
+  readonly label: string;
+  readonly onPress: () => void;
+  readonly testID: string;
+  readonly buttonRef?: RefObject<View | null>;
+};
+
+/** `.lbb` on the phone: 44 pt, a faint white disc that brightens while pressed. */
+function ViewerButton({ icon, label, onPress, testID, buttonRef }: ViewerButtonProps): React.JSX.Element {
+  const press = usePressAnimation("round");
+  return (
+    <Pressable accessibilityLabel={label} accessibilityRole="button" onPress={onPress} onPressIn={press.onPressIn} onPressOut={press.onPressOut} ref={buttonRef} testID={testID}>
+      {({ pressed }) => (
+        <Animated.View style={[styles.button, { backgroundColor: pressed ? viewer.buttonPressed : viewer.button }, press.scaleStyle]}>
+          <Icon color={viewer.text} name={icon} size={20} />
+        </Animated.View>
+      )}
+    </Pressable>
+  );
+}
+
+// `.lbw`: opacity over 180 ms, ease-out.
+const fade = { duration: durations.menu, easing: easings.easeOut, reduceMotion: ReduceMotion.System } as const;
+const fadeIn: EntryExitAnimationFunction = () => {
+  "worklet";
+  return { initialValues: { opacity: 0 }, animations: { opacity: withTiming(1, fade) } };
+};
+const fadeOut: EntryExitAnimationFunction = () => {
+  "worklet";
+  return { initialValues: { opacity: 1 }, animations: { opacity: withTiming(0, fade) } };
+};
+
+const styles = StyleSheet.create({
+  root: { backgroundColor: viewer.backdrop },
+  top: { flexDirection: "row", alignItems: "center", gap: 8, paddingBottom: 8 },
+  title: { flex: 1, minWidth: 0 },
+  detail: { fontFamily: fontFamilies[400] },
+  stage: { flex: 1 },
+  // `.phone .lbs img`: the full width, 108 pt kept free under it for the arrows.
+  photoBox: { position: "absolute", top: 0, left: 0, right: 0, bottom: 108, alignItems: "center", justifyContent: "center" },
+  photo: { width: "100%", height: "100%" },
+  arrows: { position: "absolute", left: 0, right: 0, bottom: 40, flexDirection: "row", justifyContent: "center", gap: 32 },
+  button: { width: 44, height: 44, borderRadius: 22, alignItems: "center", justifyContent: "center" },
+});

package/src/sheets/people-chat/TextField.tsx

@@ -0,0 +1,14 @@
+import { forwardRef } from "react";
+import { StyleSheet, TextInput, type TextInputProps } from "react-native";
+import { useTheme } from "../../theme/theme";
+import { type } from "../../theme/tokens";
+
+/** The text input inside a field (`input` in the mockup): the body type, no chrome of its own. */
+export const TextField = forwardRef<TextInput, TextInputProps>(function TextField({ style, ...rest }, ref) {
+  const { colors } = useTheme();
+  return <TextInput {...rest} cursorColor={colors.text} placeholderTextColor={colors.textMuted} ref={ref} selectionColor={colors.textMuted} style={[styles.input, { color: colors.text }, style]} />;
+});
+
+const styles = StyleSheet.create({
+  input: { flex: 1, minWidth: 0, height: "100%", padding: 0, fontFamily: type.body.fontFamily, fontSize: type.body.fontSize },
+});

package/src/sheets/people-chat/attachments.tsx

@@ -0,0 +1,183 @@
+import type { ChatAttachment, SpaceClient } from "@q9labsai/chalk-client";
+import { memo, useEffect, useState } from "react";
+import { Image, Linking, Pressable, StyleSheet, View } from "react-native";
+import { useSpaceClient } from "../../context/space-client-context";
+import { Icon } from "../../icons/Icon";
+import { ChalkText } from "../../primitives/ChalkText";
+import { IconButton } from "../../primitives/IconButton";
+import { useToasts } from "../../primitives/toast/ToastStack";
+import { useTheme } from "../../theme/theme";
+import { chatOverlays, fileKindColors, fixed, fontFamilies } from "../../theme/tokens";
+import { FILE_BADGE, fileKind, formatSize, thumbnailLayout } from "./chat-model";
+
+/** Download links for this session, so a photo scrolled back into view doesn't ask the server again. */
+const urls = new Map<string, Promise<string>>();
+
+function resolveUrl(client: SpaceClient, attachment: ChatAttachment): Promise<string> {
+  let url = urls.get(attachment.attachmentId);
+  if (!url) {
+    url = client.chat.files.resolveUrl(attachment);
+    urls.set(attachment.attachmentId, url);
+    url.catch(() => urls.delete(attachment.attachmentId));
+  }
+  return url;
+}
+
+export type AttachmentSource = { readonly state: "loading" } | { readonly state: "ready"; readonly uri: string; readonly aspect: number } | { readonly state: "failed" };
+
+/** The download link of a photo and its shape, once both are known. */
+export function useAttachmentSource(attachment: ChatAttachment): AttachmentSource {
+  const client = useSpaceClient();
+  const [source, setSource] = useState<AttachmentSource>({ state: "loading" });
+  useEffect(() => {
+    let live = true;
+    resolveUrl(client, attachment)
+      .then((uri) => {
+        Image.getSize(
+          uri,
+          (width, height) => live && setSource({ state: "ready", uri, aspect: width / height }),
+          () => live && setSource({ state: "ready", uri, aspect: 4 / 3 }),
+        );
+      })
+      .catch(() => live && setSource({ state: "failed" }));
+    return () => {
+      live = false;
+    };
+  }, [attachment, client]);
+  return source;
+}
+
+/** Opens a file in the system viewer, which offers saving and sharing. */
+export function useDownload(): (attachment: ChatAttachment) => void {
+  const client = useSpaceClient();
+  const toasts = useToasts();
+  return (attachment) => {
+    resolveUrl(client, attachment)
+      .then((uri) => Linking.openURL(uri))
+      .catch(() => toasts.show({ kind: "error", dismissible: true, message: `Couldn't download ${attachment.fileName}.` }));
+  };
+}
+
+type ThumbnailsProps = {
+  readonly photos: readonly ChatAttachment[];
+  readonly disabled: boolean;
+  readonly onOpen: (index: number) => void;
+};
+
+/** A message's photos (`.ths`): one at its own shape, or a grid of up to four with "+N" on the last. */
+export const Thumbnails = memo(function Thumbnails({ photos, disabled, onOpen }: ThumbnailsProps): React.JSX.Element {
+  const { shown, more } = thumbnailLayout(photos.length);
+  const count = photos.length;
+  return (
+    <View style={[styles.grid, count > 1 ? styles.gridMany : null]}>
+      {photos.slice(0, shown).map((photo, index) => (
+        <Thumbnail
+          attachment={photo}
+          disabled={disabled}
+          key={photo.attachmentId}
+          label={`Open ${photo.fileName}${count > 1 ? `, ${index + 1} of ${count}` : ""}${index === 3 && more > 0 ? `, and ${more} more` : ""}`}
+          layout={count === 1 ? "one" : count === 3 && index === 2 ? "wide" : "square"}
+          more={index === 3 ? more : 0}
+          onPress={() => onOpen(index)}
+        />
+      ))}
+    </View>
+  );
+});
+
+type ThumbnailProps = {
+  readonly attachment: ChatAttachment;
+  readonly layout: "one" | "square" | "wide";
+  readonly more: number;
+  readonly label: string;
+  readonly disabled: boolean;
+  readonly onPress: () => void;
+};
+
+function Thumbnail({ attachment, layout, more, label, disabled, onPress }: ThumbnailProps): React.JSX.Element {
+  const { colors } = useTheme();
+  const source = useAttachmentSource(attachment);
+  const aspectRatio = layout === "one" ? (source.state === "ready" ? Math.min(1.78, Math.max(0.75, source.aspect)) : 4 / 3) : layout === "wide" ? 2 : 1;
+  const style = [styles.thumb, layout === "one" ? styles.thumbOne : layout === "wide" ? styles.thumbWide : styles.thumbSquare, { aspectRatio, backgroundColor: colors.raised }];
+  if (source.state !== "ready") {
+    return (
+      <View accessibilityLabel={source.state === "loading" ? `Loading ${attachment.fileName}` : `Couldn't load ${attachment.fileName}`} accessibilityRole="image" accessible style={[style, styles.centered]}>
+        <Icon color={colors.textMuted} name="img" size={18} />
+      </View>
+    );
+  }
+  return (
+    <Pressable accessibilityLabel={label} accessibilityRole="imagebutton" accessibilityState={{ disabled }} disabled={disabled} onPress={onPress} style={style} testID={`chat.photo.${attachment.attachmentId}`}>
+      <Image source={{ uri: source.uri }} style={StyleSheet.absoluteFill} />
+      <View pointerEvents="none" style={[StyleSheet.absoluteFill, { borderRadius: layout === "one" ? 14 : 3, boxShadow: `inset 0px 0px 0px 1px ${colors.line}` }]} />
+      {more > 0 ? (
+        <View style={[StyleSheet.absoluteFill, styles.centered, styles.moreShade]}>
+          <ChalkText color={fixed.overlayText} style={styles.moreText} variant="sheetTitle">
+            {`+${more}`}
+          </ChalkText>
+        </View>
+      ) : null}
+    </Pressable>
+  );
+}
+
+/** A file's coloured badge (`.fi`): its kind in two to four letters, or a photo icon. */
+export function FileBadge({ mimeType, size = 36 }: { readonly mimeType: string; readonly size?: 32 | 36 }): React.JSX.Element {
+  const { colors } = useTheme();
+  const kind = fileKind(mimeType);
+  const box = { width: size, height: size, borderRadius: size === 36 ? 9 : 7 };
+  if (kind === "image") {
+    return (
+      <View style={[styles.badge, box, { backgroundColor: colors.hover }]}>
+        <Icon color={colors.textMuted} name="img" size={18} />
+      </View>
+    );
+  }
+  const color = kind === "txt" ? fileKindColors.other : fileKindColors[kind];
+  return (
+    <View style={[styles.badge, box, { backgroundColor: color }]}>
+      <ChalkText color={fixed.overlayText} style={[styles.badgeText, size === 32 ? styles.badgeTextSmall : null]} variant="caption">
+        {FILE_BADGE[kind]}
+      </ChalkText>
+    </View>
+  );
+}
+
+/** A file in a message (`.fcard`) with its name, size and a download button. */
+export const FileCard = memo(function FileCard({ attachment, sent }: { readonly attachment: ChatAttachment; readonly sent: boolean }): React.JSX.Element {
+  const { colors } = useTheme();
+  const download = useDownload();
+  return (
+    <View style={[styles.file, { backgroundColor: colors.raised, borderColor: colors.line }]} testID={`chat.file.${attachment.attachmentId}`}>
+      <FileBadge mimeType={attachment.mimeType} />
+      <View style={styles.fileText}>
+        <ChalkText numberOfLines={1} variant="button">
+          {attachment.fileName}
+        </ChalkText>
+        <ChalkText style={styles.fileSize} tone="textMuted" variant="label">
+          {formatSize(attachment.byteLength)}
+        </ChalkText>
+      </View>
+      {sent ? <IconButton accessibilityLabel={`Download ${attachment.fileName}`} icon="dl" onPress={() => download(attachment)} size={36} testID={`chat.download.${attachment.attachmentId}`} tone="ghost" /> : null}
+    </View>
+  );
+});
+
+const styles = StyleSheet.create({
+  grid: { width: 240, maxWidth: "100%", borderRadius: 14, overflow: "hidden" },
+  gridMany: { flexDirection: "row", flexWrap: "wrap", gap: 2 },
+  thumb: { overflow: "hidden" },
+  thumbOne: { width: "100%", borderRadius: 14 },
+  thumbSquare: { width: 119, borderRadius: 3 },
+  thumbWide: { width: "100%", borderRadius: 3 },
+  centered: { alignItems: "center", justifyContent: "center" },
+  moreShade: { backgroundColor: chatOverlays.photoMore },
+  moreText: { fontSize: 20, lineHeight: 28 },
+  badge: { alignItems: "center", justifyContent: "center" },
+  // `.fi`: 10 pt bold capitals with 0.04 em tracking.
+  badgeText: { fontFamily: fontFamilies[700], fontSize: 10, lineHeight: 10, letterSpacing: 0.4 },
+  badgeTextSmall: { fontSize: 9, lineHeight: 9, letterSpacing: 0.36 },
+  file: { flexDirection: "row", alignItems: "center", gap: 10, width: 240, maxWidth: "100%", minHeight: 56, paddingTop: 8, paddingRight: 6, paddingBottom: 8, paddingLeft: 10, borderRadius: 14, borderWidth: 1 },
+  fileText: { flex: 1, minWidth: 0, gap: 1 },
+  fileSize: { fontFamily: fontFamilies[400], lineHeight: 15 },
+});

package/src/sheets/people-chat/chat-model.ts

@@ -0,0 +1,157 @@
+import { CHALK_CHAT_ATTACHMENT_LIMITS, CHALK_CHAT_ATTACHMENT_MIME_TYPES, type ChatAttachment, type ChatMessage, type ChatUploadFile, type PendingChatSend } from "@q9labsai/chalk-client";
+
+export type FileKind = "image" | "pdf" | "doc" | "xls" | "ppt" | "txt" | "other";
+
+const KIND_BY_MIME: Readonly<Record<string, FileKind>> = {
+  "image/png": "image",
+  "image/jpeg": "image",
+  "image/gif": "image",
+  "image/webp": "image",
+  "application/pdf": "pdf",
+  "text/plain": "txt",
+  "application/msword": "doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "doc",
+  "application/vnd.oasis.opendocument.text": "doc",
+  "application/vnd.ms-excel": "xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xls",
+  "application/vnd.oasis.opendocument.spreadsheet": "xls",
+  "application/vnd.ms-powerpoint": "ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "ppt",
+  "application/vnd.oasis.opendocument.presentation": "ppt",
+};
+
+export function fileKind(mimeType: string): FileKind {
+  return KIND_BY_MIME[mimeType] ?? "other";
+}
+
+const MIME_BY_EXTENSION: Readonly<Record<string, string>> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  odt: "application/vnd.oasis.opendocument.text",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  odp: "application/vnd.oasis.opendocument.presentation",
+};
+
+/** The MIME type a picked file reports, or the one its extension implies when the picker reports none. */
+export function mimeTypeOf(name: string, reported: string | undefined): string {
+  if (reported) return reported;
+  const dot = name.lastIndexOf(".");
+  return (dot > 0 && MIME_BY_EXTENSION[name.slice(dot + 1).toLowerCase()]) || "application/octet-stream";
+}
+
+/** The two or three letters on a file badge (`.fi`). */
+export const FILE_BADGE: Readonly<Record<Exclude<FileKind, "image">, string>> = { pdf: "PDF", doc: "DOC", xls: "XLS", ppt: "PPT", txt: "TXT", other: "FILE" };
+
+const MB = 1024 * 1024;
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < MB) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / MB).toFixed(bytes < 10 * MB ? 1 : 0)} MB`;
+}
+
+/** What a message row shows for a sent, waiting or failed message. */
+export type EntryState = "sent" | "queued" | "sending" | "failed";
+
+export type ChatEntry = {
+  readonly key: string;
+  readonly text: string;
+  readonly attachments: readonly ChatAttachment[];
+  readonly state: EntryState;
+  /** Set on pending sends, so a failed one can be sent again. */
+  readonly clientMessageId: string | null;
+};
+
+export type MessageGroup = {
+  readonly key: string;
+  readonly participantId: string;
+  readonly displayName: string;
+  readonly mine: boolean;
+  readonly time: string;
+  readonly entries: readonly ChatEntry[];
+};
+
+export function formatTime(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? "" : date.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+}
+
+/** Whether a message with only attachments should read as "Sent a photo" and so on, for announcements and labels. */
+export function messageSummary(text: string, attachments: readonly ChatAttachment[]): string {
+  if (text) return text;
+  const count = attachments.length;
+  if (count === 0) return "";
+  const photos = attachments.filter((attachment) => fileKind(attachment.mimeType) === "image").length;
+  if (photos === count) return count > 1 ? `Sent ${count} photos` : "Sent a photo";
+  return count > 1 ? `Sent ${count} files` : "Sent a file";
+}
+
+/**
+ * Turns the client's confirmed messages and your waiting sends into rows, oldest first: consecutive
+ * messages from one person share a header (`.mg`). A send you retried leaves its failed copy in the
+ * client, so `retried` hides those.
+ */
+export function groupMessages(messages: readonly ChatMessage[], pending: readonly PendingChatSend[], self: { readonly participantId: string | null; readonly displayName: string | null }, retried: ReadonlySet<string>): readonly MessageGroup[] {
+  const groups: MessageGroup[] = [];
+  const add = (participantId: string, displayName: string, time: string, entry: ChatEntry) => {
+    const last = groups[groups.length - 1];
+    if (last && last.participantId === participantId) {
+      groups[groups.length - 1] = { ...last, entries: [...last.entries, entry] };
+      return;
+    }
+    groups.push({ key: entry.key, participantId, displayName, mine: participantId === self.participantId, time, entries: [entry] });
+  };
+  for (const message of messages) {
+    add(message.participantId, message.displayName, formatTime(message.createdAt), { key: message.messageId, text: message.text, attachments: message.attachments, state: "sent", clientMessageId: null });
+  }
+  for (const send of pending) {
+    if (retried.has(send.clientMessageId)) continue;
+    add(self.participantId ?? "self", self.displayName ?? "You", "Now", { key: send.clientMessageId, text: send.text, attachments: send.attachments, state: send.status === "failed" ? "failed" : send.status === "queued" ? "queued" : "sending", clientMessageId: send.clientMessageId });
+  }
+  return groups;
+}
+
+/** A file the person picked, on its way to being sent. */
+export type StagedFile = {
+  readonly id: number;
+  readonly name: string;
+  readonly size: number;
+  readonly mimeType: string;
+  readonly source: ChatUploadFile;
+  /** The local photo to show in the chip, before it's uploaded. */
+  readonly previewUri: string | null;
+  readonly state: "uploading" | "ready" | "error";
+  readonly attachment: ChatAttachment | null;
+  readonly error: string | null;
+};
+
+export type UploadFacts = { readonly name: string; readonly mimeType: string; readonly size: number };
+
+const allowedMimeTypes = new Set<string>(CHALK_CHAT_ATTACHMENT_MIME_TYPES);
+
+/** The reason a file can't be sent, or null. `accepted` counts the files already accepted in this message. */
+export function stagingError(facts: UploadFacts, accepted: number): string | null {
+  if (!allowedMimeTypes.has(facts.mimeType)) {
+    const dot = facts.name.lastIndexOf(".");
+    return dot > 0 && dot < facts.name.length - 1 ? `Can’t send .${facts.name.slice(dot + 1).toLowerCase()} files` : "Can’t send this type of file";
+  }
+  if (facts.size > CHALK_CHAT_ATTACHMENT_LIMITS.maximumByteLength) return "Over the 25 MB limit";
+  if (accepted >= CHALK_CHAT_ATTACHMENT_LIMITS.maximumPerMessage) return `Only ${CHALK_CHAT_ATTACHMENT_LIMITS.maximumPerMessage} files per message`;
+  return null;
+}
+
+/** How many photos of a message the thumbnail grid draws, and how many are left over for "+N". */
+export function thumbnailLayout(count: number): { readonly shown: number; readonly more: number } {
+  return { shown: Math.min(count, 4), more: Math.max(0, count - 4) };
+}

package/src/sheets/people-chat/people-chat-model.test.ts

@@ -0,0 +1,98 @@
+import type { ChatMessage, Participant, PendingChatSend } from "@q9labsai/chalk-client";
+import { describe, expect, it } from "vitest";
+import { groupMessages, messageSummary, mimeTypeOf, stagingError } from "./chat-model";
+import { nextHandOrder, peopleRows } from "./people-model";
+
+function person(participantId: string, displayName: string, handRaised = false): Participant {
+  return {
+    participantId,
+    displayName,
+    role: "participant",
+    eligibleRoles: [],
+    capabilities: [],
+    handRaised,
+    media: { microphone: "active", camera: "inactive", screenShare: "inactive" },
+    presence: { state: "connected", speaking: false, activeSpeaker: false },
+  } as const satisfies Participant;
+}
+
+function message(messageId: string, participantId: string, text: string): ChatMessage {
+  return { messageId, clientMessageId: `c-${messageId}`, sequence: messageId, participantId, displayName: participantId, text, createdAt: "2026-10-18T10:00:00Z", attachments: [] };
+}
+
+const photo = { attachmentId: "a", fileName: "IMG_0412.jpg", mimeType: "image/jpeg", byteLength: 10 } as const;
+const pdf = { attachmentId: "b", fileName: "Q4 plan.pdf", mimeType: "application/pdf", byteLength: 10 } as const;
+
+describe("peopleRows", () => {
+  const roster = [person("me", "Hasan"), person("n", "Nora", true), person("s", "Sam", true), person("k", "Kai")];
+
+  it("puts the raised-hands queue in the order hands went up, above everyone, once two hands are up", () => {
+    const rows = peopleRows({ roster, waiting: [], handOrder: ["s", "n"], query: "" });
+    expect(rows.map((row) => row.key)).toEqual(["section.hands", "hand.s", "hand.n", "section.call", "person.me", "person.n", "person.s", "person.k"]);
+    expect(rows.find((row) => row.key === "person.n")).toMatchObject({ handNumber: 2 });
+  });
+
+  it("numbers nothing and shows no queue for a single raised hand", () => {
+    const rows = peopleRows({ roster: [person("me", "Hasan"), person("n", "Nora", true)], waiting: [], handOrder: ["n"], query: "" });
+    expect(rows.map((row) => row.kind)).toEqual(["person", "person"]);
+    expect(rows[1]).toMatchObject({ handNumber: null });
+  });
+
+  it("filters by name and says when no one matches", () => {
+    expect(peopleRows({ roster, waiting: [], handOrder: ["s", "n"], query: "no" }).map((row) => row.key)).toEqual(["person.n"]);
+    expect(peopleRows({ roster, waiting: [], handOrder: [], query: "zed" })).toEqual([{ kind: "none", key: "none", query: "zed" }]);
+  });
+
+  it("keeps the first-raised hand at the front as others raise and lower", () => {
+    const first = nextHandOrder([], [person("n", "Nora", true)]);
+    const second = nextHandOrder(first, [person("n", "Nora", true), person("s", "Sam", true)]);
+    expect(second).toEqual(["n", "s"]);
+    expect(nextHandOrder(second, [person("n", "Nora"), person("s", "Sam", true)])).toEqual(["s"]);
+    expect(nextHandOrder(second, [person("n", "Nora", true), person("s", "Sam", true)])).toBe(second);
+  });
+});
+
+describe("groupMessages", () => {
+  const self = { participantId: "me", displayName: "Hasan" };
+
+  it("groups consecutive messages from one person and marks yours", () => {
+    const groups = groupMessages([message("1", "n", "Hi"), message("2", "n", "Ready?"), message("3", "me", "Yes")], [], self, new Set());
+    expect(groups.map((group) => [group.participantId, group.mine, group.entries.length])).toEqual([
+      ["n", false, 2],
+      ["me", true, 1],
+    ]);
+  });
+
+  it("adds your waiting sends after the confirmed messages and hides ones you retried", () => {
+    const failed: PendingChatSend = { clientMessageId: "p1", text: "Lost", attachments: [], status: "failed", error: null };
+    const sending: PendingChatSend = { clientMessageId: "p2", text: "Again", attachments: [], status: "sending", error: null };
+    const groups = groupMessages([message("1", "me", "First")], [failed, sending], self, new Set(["p1"]));
+    expect(groups).toHaveLength(1);
+    expect(groups[0]?.entries.map((entry) => [entry.text, entry.state])).toEqual([
+      ["First", "sent"],
+      ["Again", "sending"],
+    ]);
+  });
+});
+
+describe("chat files", () => {
+  it("says what a message with only attachments sent", () => {
+    expect(messageSummary("", [photo])).toBe("Sent a photo");
+    expect(messageSummary("", [photo, photo])).toBe("Sent 2 photos");
+    expect(messageSummary("", [photo, pdf])).toBe("Sent 2 files");
+    expect(messageSummary("Look", [photo])).toBe("Look");
+  });
+
+  it("refuses unknown types, files over 25 MB and a sixth file", () => {
+    expect(stagingError({ name: "Demo.mov", mimeType: "video/quicktime", size: 10 }, 0)).toBe("Can’t send .mov files");
+    expect(stagingError({ name: "Site photos.pdf", mimeType: "application/pdf", size: 31 * 1024 * 1024 }, 0)).toBe("Over the 25 MB limit");
+    expect(stagingError({ name: "Agenda.pdf", mimeType: "application/pdf", size: 10 }, 5)).toBe("Only 5 files per message");
+    expect(stagingError({ name: "Agenda.pdf", mimeType: "application/pdf", size: 10 }, 4)).toBeNull();
+  });
+
+  it("falls back to the extension when the picker reports no type", () => {
+    expect(mimeTypeOf("Budget 2027.XLSX", undefined)).toBe("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
+    expect(mimeTypeOf("notes", undefined)).toBe("application/octet-stream");
+    expect(mimeTypeOf("a.png", "image/png")).toBe("image/png");
+  });
+});

package/src/sheets/people-chat/people-model.ts

@@ -0,0 +1,68 @@
+import type { AdmissionRequest, Participant } from "@q9labsai/chalk-client";
+
+export type PeopleRow =
+  | { readonly kind: "section"; readonly key: string; readonly label: string }
+  | { readonly kind: "waiting"; readonly key: string; readonly request: AdmissionRequest }
+  | { readonly kind: "hand"; readonly key: string; readonly participant: Participant; readonly order: number }
+  | { readonly kind: "person"; readonly key: string; readonly participant: Participant; /** Place in the raised-hands queue; set only while two or more hands are up. */ readonly handNumber: number | null }
+  | { readonly kind: "none"; readonly key: string; readonly query: string };
+
+export type PeopleInput = {
+  readonly roster: readonly Participant[];
+  /** People waiting to join; empty for anyone who can't let people in. */
+  readonly waiting: readonly AdmissionRequest[];
+  /** Participant ids with a raised hand, the one raised first at the front. */
+  readonly handOrder: readonly string[];
+  readonly query: string;
+};
+
+/**
+ * The People list, top to bottom: people waiting, the raised-hands queue (only once two hands are up,
+ * since one hand needs no order), then everyone in the call. A search hides the queue.
+ */
+export function peopleRows({ roster, waiting, handOrder, query }: PeopleInput): readonly PeopleRow[] {
+  const q = query.trim().toLowerCase();
+  const rows: PeopleRow[] = [];
+  const byId = new Map(roster.map((participant) => [participant.participantId, participant]));
+  const raised = handOrder.filter((id) => byId.get(id)?.handRaised);
+  const numbered = raised.length > 1;
+  let headed = false;
+  const headInTheCall = () => {
+    if (headed) return;
+    headed = true;
+    rows.push({ kind: "section", key: "section.call", label: "In the call" });
+  };
+
+  if (waiting.length > 0) {
+    rows.push({ kind: "section", key: "section.waiting", label: "Waiting" });
+    for (const request of waiting) rows.push({ kind: "waiting", key: `waiting.${request.requestId}`, request });
+    headInTheCall();
+  }
+  if (!q && numbered) {
+    rows.push({ kind: "section", key: "section.hands", label: "Raised hands" });
+    raised.forEach((id, index) => {
+      const participant = byId.get(id);
+      if (participant) rows.push({ kind: "hand", key: `hand.${id}`, participant, order: index + 1 });
+    });
+    headInTheCall();
+  }
+
+  const people = roster.filter((participant) => !q || participant.displayName.toLowerCase().includes(q));
+  if (people.length === 0) rows.push({ kind: "none", key: "none", query: query.trim() });
+  for (const participant of people) {
+    const index = raised.indexOf(participant.participantId);
+    rows.push({ kind: "person", key: `person.${participant.participantId}`, participant, handNumber: numbered && index >= 0 ? index + 1 : null });
+  }
+  return rows;
+}
+
+/**
+ * Who raised a hand first. The client only says whether a hand is up, so this remembers the order
+ * the lists saw hands go up in; people who join with a hand already raised count from when they appear.
+ */
+export function nextHandOrder(previous: readonly string[], roster: readonly Participant[]): readonly string[] {
+  const raised = new Set(roster.filter((participant) => participant.handRaised).map((participant) => participant.participantId));
+  const kept = previous.filter((id) => raised.has(id));
+  const added = [...raised].filter((id) => !kept.includes(id));
+  return added.length === 0 && kept.length === previous.length ? previous : [...kept, ...added];
+}