@remit/ui 0.0.1

package/src/components/app-shell-slotted.tsx

@@ -0,0 +1,267 @@
+import { createContext, type ReactNode, useContext, useState } from "react";
+import {
+	type PaneLayout,
+	resolvePaneLayout,
+	useContainerWidth,
+} from "./app-shell-types.js";
+import { Dialog } from "./dialog.js";
+import {
+	ResizableHandle,
+	ResizablePanel,
+	ResizablePanelGroup,
+} from "./resizable.js";
+
+/* ------------------------------------------------------------------ */
+/* Slot-based shell: the same responsive 4-pane arrangement as        */
+/* AppShell but with ReactNode render slots instead of data props.     */
+/* The web-client passes live data-bound children; the kit preview     */
+/* passes its own static components via the data-driven AppShell.     */
+/* ------------------------------------------------------------------ */
+
+export interface AppShellSlottedProps {
+	/**
+	 * Nav sidebar content. Rendered as a persistent pane ≥1024px or as a
+	 * dismissible slide-over below that. Required — the shell always has a nav.
+	 */
+	nav: ReactNode;
+	/**
+	 * List pane content: the message list, daily brief, outbox list, etc.
+	 * Always visible at all widths (the single pane on narrow layouts).
+	 */
+	list: ReactNode;
+	/**
+	 * Reading pane content: the conversation view + toolbar. Appears ≥1024px.
+	 * When absent the reading panel is not shown even if width allows.
+	 */
+	reading?: ReactNode;
+	/**
+	 * Intelligence rail content. Appears ≥1280px when `intelligenceOpen` is true.
+	 * When absent the intelligence panel is not shown even if width allows.
+	 */
+	intelligence?: ReactNode;
+	/** Show the intelligence pane (user preference). Defaults to true. */
+	intelligenceOpen?: boolean;
+	/**
+	 * Guards the intelligence rail against showing with no open thread. The rail
+	 * needs both width AND a thread; pass false to keep it closed even when wide
+	 * and `intelligenceOpen` (an edge state). Defaults to true (caller asserts a
+	 * thread, e.g. the live app only opens the rail with a selected message).
+	 */
+	hasThread?: boolean;
+	/**
+	 * List density. "compact" widens the list pane's default split (denser rows
+	 * read better with more horizontal room); "comfortable" (default) uses the
+	 * standard split. Only affects the two-pane (list + reading) default size.
+	 */
+	density?: "comfortable" | "compact";
+	/**
+	 * Header rendered only on narrow (< 1024px) widths — the mobile top bar.
+	 * The web-client injects the app-specific bar (hamburger / title / search).
+	 */
+	header?: ReactNode;
+	/**
+	 * Content rendered outside the pane group (e.g., the compose FAB). Floats
+	 * over the layout regardless of width.
+	 */
+	overlay?: ReactNode;
+	/**
+	 * Cold-load placeholder. Shown instead of the normal layout while `isLoading`
+	 * is true.
+	 */
+	skeleton?: ReactNode;
+	/** When true, shows `skeleton` instead of the panel layout. Defaults to false. */
+	isLoading?: boolean;
+	/**
+	 * Seed width (px) for the container-query reflow before the first
+	 * ResizeObserver measure (SSR / pre-mount).
+	 */
+	initialWidth?: number;
+	/**
+	 * Externally controlled nav-open state (narrow widths). When absent the
+	 * shell manages it internally.
+	 */
+	navOpen?: boolean;
+	/** Called when the nav slide-over should open. */
+	onOpenNav?: () => void;
+	/** Called when the nav slide-over should close. */
+	onCloseNav?: () => void;
+}
+
+/* ------------------------------------------------------------------ */
+/* Pane-layout context                                                  */
+/* ------------------------------------------------------------------ */
+
+/** Published by `AppShellSlotted`; consumed by `useAppShellLayout`. */
+export interface AppShellLayoutContext {
+	/** Current pane visibility derived from the shell's own-width. */
+	panes: PaneLayout;
+	/** Own-width in px; null before the first ResizeObserver measure. */
+	containerWidth: number | null;
+	/** True when the nav is a persistent pane (not a slide-over). */
+	showNavPane: boolean;
+	/** Open the nav slide-over. Call from list-header "folders" buttons. */
+	openNav: () => void;
+	/** True when the reading pane is active (width ≥ 1024px). */
+	showReadingPane: boolean;
+	/** True when the intelligence rail can show (width ≥ 1280px). */
+	showIntelligencePane: boolean;
+}
+
+const AppShellLayoutCtx = createContext<AppShellLayoutContext | null>(null);
+
+/**
+ * Read the enclosing `AppShellSlotted`'s pane layout.
+ * Returns null outside of an `AppShellSlotted` (tests / Storybook).
+ */
+export function useAppShellLayout(): AppShellLayoutContext | null {
+	return useContext(AppShellLayoutCtx);
+}
+
+/* ------------------------------------------------------------------ */
+/* AppShellSlotted                                                      */
+/* ------------------------------------------------------------------ */
+
+export function AppShellSlotted({
+	nav,
+	list,
+	reading,
+	intelligence,
+	intelligenceOpen = true,
+	hasThread = true,
+	density = "comfortable",
+	header,
+	overlay,
+	skeleton,
+	isLoading = false,
+	initialWidth,
+	navOpen: navOpenProp,
+	onOpenNav,
+	onCloseNav,
+}: AppShellSlottedProps) {
+	const [containerRef, containerWidth] = useContainerWidth(initialWidth);
+	const panes = resolvePaneLayout(containerWidth ?? 0);
+	const showNavPane = panes.nav;
+	const showReadingPane = panes.reading && Boolean(reading);
+	const isWide = panes.intelligence;
+
+	const [navOpenInternal, setNavOpenInternal] = useState(false);
+	const controlled = navOpenProp !== undefined;
+	const navOpen = controlled ? navOpenProp : navOpenInternal;
+	const openNav = () => {
+		if (!controlled) setNavOpenInternal(true);
+		onOpenNav?.();
+	};
+	const closeNav = () => {
+		if (!controlled) setNavOpenInternal(false);
+		onCloseNav?.();
+	};
+
+	const showIntelligencePanel =
+		isWide && intelligenceOpen && hasThread && Boolean(intelligence);
+
+	const layoutCtx: AppShellLayoutContext = {
+		panes,
+		containerWidth,
+		showNavPane,
+		openNav,
+		showReadingPane,
+		showIntelligencePane: isWide,
+	};
+
+	return (
+		<AppShellLayoutCtx.Provider value={layoutCtx}>
+			<div
+				ref={containerRef}
+				className="@container flex h-dvh w-full flex-col overflow-hidden bg-canvas font-sans text-fg"
+			>
+				{isLoading && skeleton ? (
+					skeleton
+				) : (
+					<>
+						{/* Narrow top bar: rendered only when the nav is a slide-over
+						    (< 1024px). Desktop has no slim bar. */}
+						{!showNavPane && header && <div className="shrink-0">{header}</div>}
+
+						<ResizablePanelGroup
+							direction="horizontal"
+							className="min-h-0 flex-1"
+						>
+							{showNavPane && (
+								<>
+									<ResizablePanel
+										id="nav"
+										order={1}
+										defaultSize={17}
+										minSize={12}
+										maxSize={24}
+										className="min-w-0"
+									>
+										{nav}
+									</ResizablePanel>
+									<ResizableHandle />
+								</>
+							)}
+
+							<ResizablePanel
+								id="list"
+								order={2}
+								defaultSize={
+									showReadingPane ? (density === "compact" ? 36 : 27) : 83
+								}
+								minSize={18}
+								maxSize={showReadingPane ? 48 : 88}
+								className="min-w-0"
+							>
+								{list}
+							</ResizablePanel>
+
+							{showReadingPane && (
+								<>
+									<ResizableHandle />
+									<ResizablePanel
+										id="reading"
+										order={3}
+										minSize={24}
+										className="min-w-0"
+									>
+										{reading}
+									</ResizablePanel>
+								</>
+							)}
+
+							{showIntelligencePanel && (
+								<>
+									<ResizableHandle />
+									<ResizablePanel
+										id="intelligence"
+										order={4}
+										defaultSize={21}
+										minSize={15}
+										maxSize={32}
+										className="min-w-0"
+									>
+										{intelligence}
+									</ResizablePanel>
+								</>
+							)}
+						</ResizablePanelGroup>
+
+						{/* Narrow nav: dismissible slide-over (#784). */}
+						{!showNavPane && (
+							<Dialog
+								open={navOpen}
+								onClose={closeNav}
+								title="Folders"
+								anchor="left"
+							>
+								{nav}
+							</Dialog>
+						)}
+
+						{overlay}
+					</>
+				)}
+			</div>
+		</AppShellLayoutCtx.Provider>
+	);
+}

package/src/components/app-shell-types.ts

@@ -0,0 +1,328 @@
+import {
+	type ReactElement,
+	type ReactNode,
+	type RefObject,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+import type {
+	IntelligenceData,
+	SenderTrustLevel,
+} from "./intelligence-panel.js";
+import type { ListState } from "./message-list-state.js";
+
+/** Pane-count thresholds, aligned to Tailwind `lg`/`xl`. The whole shell reflows
+ *  by its own width: a single responsive surface, not per-device variants.
+ *    < 1024px (below `lg`)          → list pane only        (phone + tablet portrait)
+ *    1024–1279px (`lg`)            → list + reading pane     (two-pane)
+ *    ≥ 1280px (`xl`)               → + intelligence rail     (three-pane, when present)
+ */
+export const READING_PANE_MIN_WIDTH = 1024;
+export const INTELLIGENCE_MIN_WIDTH = 1280;
+
+/** Which panes the shell shows at a given viewport width. Pure (no DOM) so the
+ *  pane-count-by-width rule is testable. `intelligence` is gated additionally on
+ *  there being intelligence data + an open thread at render time; this is the
+ *  width ceiling only. */
+export interface PaneLayout {
+	nav: boolean;
+	reading: boolean;
+	intelligence: boolean;
+}
+
+/**
+ * The single source of truth for the reflow rule:
+ *   < readingPaneMinWidth → list alone (phone + tablet PORTRAIT) — no reading pane
+ *   readingPaneMinWidth–intelligenceMinWidth → list + reading (tablet landscape / desktop)
+ *   ≥ intelligenceMinWidth → + intelligence rail (widest)
+ * The persistent nav pane shares the reading-pane boundary; below it the nav is
+ * a slide-over, not a column.
+ *
+ * Both thresholds are configurable so a consumer can pass the desired pixel
+ * values without forking the layout logic. The kit `AppShell` uses the
+ * module-level defaults (1024 / 1280).
+ */
+export function resolvePaneLayout(
+	width: number,
+	readingPaneMinWidth = READING_PANE_MIN_WIDTH,
+	intelligenceMinWidth = INTELLIGENCE_MIN_WIDTH,
+): PaneLayout {
+	const reading = width >= readingPaneMinWidth;
+	return {
+		nav: reading,
+		reading,
+		intelligence: width >= intelligenceMinWidth,
+	};
+}
+
+export type NarrowView = "list" | "message";
+
+/** Seeds the narrow touch list's interaction state for stories / SSR, so it can
+ *  render selection mode or a swipe-peeked row without a live gesture. */
+export type TouchSeed = "selection" | "peek-trailing" | "peek-leading";
+
+/**
+ * Measures an element's OWN width via ResizeObserver — a container query, not a
+ * viewport one. The shell reflows by the space it actually occupies (so it works
+ * embedded at any width, not just full-screen), and the pane count is derived
+ * from this with `resolvePaneLayout`. Returns [ref, width]; width is `null`
+ * until the first measure (SSR / pre-mount), where the shell renders list-only.
+ */
+export function useContainerWidth(
+	seed?: number,
+): [RefObject<HTMLDivElement | null>, number | null] {
+	const ref = useRef<HTMLDivElement | null>(null);
+	const [width, setWidth] = useState<number | null>(seed ?? null);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el || typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (entry) setWidth(entry.contentRect.width);
+		});
+		observer.observe(el);
+		setWidth(el.getBoundingClientRect().width);
+		return () => observer.disconnect();
+	}, []);
+	return [ref, width];
+}
+
+/**
+ * System-folder role for a sidebar mailbox, resolved by the web-client adapter —
+ * the single detection path (see `mailbox-order.ts`). Absent = a custom user
+ * folder. The kit pins, orders, and icons system folders purely by this role and
+ * never inspects raw IMAP SPECIAL-USE strings itself. "inbox" is included even
+ * though INBOX carries no SPECIAL-USE attribute (it is matched by name).
+ */
+export type NavMailboxRole =
+	| "inbox"
+	| "flagged"
+	| "drafts"
+	| "sent"
+	| "archive"
+	| "all"
+	| "junk"
+	| "trash";
+
+export interface NavMailbox {
+	id: string;
+	name: string;
+	unseen?: number;
+	/** System-folder role (adapter-computed). Absent = a custom user folder. */
+	role?: NavMailboxRole;
+	/**
+	 * Full mailbox path, surfaced as the row's `title` tooltip so a truncated or
+	 * localized leaf name still reveals where it lives. Defaults to `name`.
+	 */
+	fullPath?: string;
+}
+
+/** Per-account mailbox-load status, so the nav can show loading/error inline. */
+export type NavAccountStatus = "loading" | "error" | "ready";
+
+export interface NavAccount {
+	id: string;
+	label: string;
+	email: string;
+	/** Muted: excluded from unified views, still syncing. Rendered dimmed. */
+	muted?: boolean;
+	mailboxes: NavMailbox[];
+	/**
+	 * Number of outbox messages pending send. When provided, an Outbox entry
+	 * appears below the system mailbox list for this account.
+	 */
+	outboxPending?: number;
+	/**
+	 * Mailbox-load status. "ready" (default) renders the mailbox list; "loading"
+	 * shows a placeholder; "error" shows a retry affordance via `onRetry`.
+	 */
+	status?: NavAccountStatus;
+	/** Retry handler for the error state. */
+	onRetry?: () => void;
+}
+
+/**
+ * Renders a navigation entry as a real anchor so middle-click / open-in-new-tab
+ * / deep-linking / screen-reader link semantics all work. The web-client passes
+ * a router `<Link>` builder; when omitted, NavItem falls back to a button with
+ * programmatic `onSelectNav` (used by static stories / the AppShell preview).
+ */
+export interface NavLinkRenderProps {
+	/** The nav id this entry targets ("brief", "outbox", or a mailbox id). */
+	navId: string;
+	className: string;
+	ariaLabel?: string;
+	title?: string;
+	children: ReactNode;
+	onClick?: () => void;
+}
+
+export type NavLinkComponent = (props: NavLinkRenderProps) => ReactElement;
+
+export type ThreadCategory =
+	| "personal"
+	| "newsletter"
+	| "marketing"
+	| "automated"
+	| "transactional"
+	| "social";
+
+/** "all" (no category narrowing) plus every content-type category. */
+export type BriefCategoryFilter = ThreadCategory | "all";
+
+/**
+ * Ordered content-type categories for the brief expando. Mirrors the generated
+ * `MessageCategory` enum (@remit/domain-enums); swap this local list for the
+ * generated enum's values once that package is importable from the UI build.
+ */
+export const briefCategories: ReadonlyArray<{
+	id: BriefCategoryFilter;
+	label: string;
+}> = [
+	{ id: "all", label: "All" },
+	{ id: "personal", label: "Personal" },
+	{ id: "newsletter", label: "Newsletters" },
+	{ id: "marketing", label: "Marketing" },
+	{ id: "automated", label: "Automated" },
+	{ id: "transactional", label: "Transactional" },
+	{ id: "social", label: "Social" },
+];
+
+export interface ThreadRowData {
+	id: string;
+	accountId: string;
+	/** Owning mailbox — used by the `in:` search-token filter. */
+	mailboxId?: string;
+	fromName: string;
+	fromEmail: string;
+	subject: string;
+	snippet: string;
+	timeLabel: string;
+	/** Unix epoch ms — used by the "Today" brief filter; absent in fixture rows. */
+	sentDate?: number;
+	isRead?: boolean;
+	hasAttachment?: boolean;
+	starred?: boolean;
+	trust?: SenderTrustLevel;
+	category?: ThreadCategory;
+	/** Number of messages when the row is a thread. */
+	messageCount?: number;
+	/** Authenticity heuristics flagged this row (DKIM/From mismatch). */
+	suspicious?: boolean;
+}
+
+export interface ThreadSection {
+	id: string;
+	/** Section label; omit for a flat list. */
+	label?: string;
+	threads: ThreadRowData[];
+}
+
+export interface ThreadMessageData {
+	id: string;
+	fromName: string;
+	fromEmail: string;
+	toLabel: string;
+	dateLabel: string;
+	snippet: string;
+	bodyHtml: string;
+	expanded?: boolean;
+	/**
+	 * Designed HTML mail (newsletters/marketing): render the body inside a
+	 * hairline content frame that hugs left. The email keeps its own colors
+	 * inside the frame (never dark-inverted); the frame contains the
+	 * brightness so a white 600px blast doesn't glow to the pane edge.
+	 */
+	framed?: boolean;
+}
+
+export interface ThreadData {
+	subject: string;
+	messages: ThreadMessageData[];
+	/** Danger banner above the body (authenticity verdicts only). */
+	warning?: string;
+}
+
+export type Density = "comfortable" | "compact";
+
+export interface AppShellProps {
+	accounts: NavAccount[];
+	/**
+	 * Seed width (px) for the container-query reflow before the first
+	 * ResizeObserver measure. Lets SSR / tests render the correct pane count
+	 * without a live layout pass; once mounted, the observed own-width takes over.
+	 */
+	initialWidth?: number;
+	/** "brief" or a mailbox id. */
+	selectedNavId: string;
+	briefUnseen?: number;
+	listTitle: string;
+	listMeta?: string;
+	sections: ThreadSection[];
+	/** Brief mode: collapsible section headers + a composable filter chip bar. */
+	briefFilters?: boolean;
+	/**
+	 * Flat plain-mailbox list (no section labels, no chip bar) — the shape the
+	 * live `$mailboxId` MessageList renders. Defaults to the sectioned brief.
+	 */
+	flatList?: boolean;
+	/**
+	 * Drives the list pane's state. "ready" (default) renders rows; the other
+	 * states render the loading skeleton / empty / error surfaces in place of
+	 * the rows, mirroring the live MessageList.
+	 */
+	listState?: ListState;
+	/** Active search query — switches the empty state to its search variant. */
+	searchQuery?: string;
+	/**
+	 * Specific failure detail for the error state. Surfaced verbatim under the
+	 * generic headline so the failure is readable (ux.md fail-loud), not a bare
+	 * "something went wrong". Omit to fall back to the generic copy.
+	 */
+	errorMessage?: string;
+	/** Retry handler for the error state. */
+	onRetry?: () => void;
+	/** Report handler for the error state (the failure goes somewhere). */
+	onReportError?: () => void;
+	/**
+	 * Content-type category filter for the brief (a separate axis from the
+	 * in-list chips). Selecting one narrows the brief to that category.
+	 */
+	briefCategory?: BriefCategoryFilter;
+	onSelectBriefCategory?: (category: BriefCategoryFilter) => void;
+	selectedThreadId?: string;
+	thread?: ThreadData;
+	/**
+	 * Seed for the narrow single-pane view (the list, or the dedicated message
+	 * view). Lets a story / SSR open straight to a thread without a click. Only
+	 * meaningful below the reading boundary; ignored once the reading pane fits.
+	 */
+	initialNarrowView?: NarrowView;
+	/**
+	 * Seed the narrow touch list directly in selection mode or with a
+	 * swipe-peeked row, so a story / SSR can show those triage states statically.
+	 * Only meaningful below the reading boundary; ignored once the reading pane
+	 * fits or when the message view is showing.
+	 */
+	initialTouchState?: TouchSeed;
+	intelligence?: IntelligenceData;
+	/** Pane 4 visible. Defaults to true when intelligence is present. */
+	intelligenceOpen?: boolean;
+	density?: Density;
+	onSelectNav?: (id: string) => void;
+	onSelectThread?: (id: string) => void;
+	onToggleIntelligence?: () => void;
+}
+
+export const categoryTone: Record<
+	ThreadCategory,
+	"neutral" | "accent" | "positive" | "warning"
+> = {
+	personal: "accent",
+	newsletter: "neutral",
+	marketing: "neutral",
+	automated: "neutral",
+	transactional: "positive",
+	social: "warning",
+};