@mdxui/zero 6.0.0

package/README.md

@@ -0,0 +1,205 @@
+# @mdxui/zero
+
+AI-powered email client components for mdxui. Provides a complete email application UI including mail lists, thread display, composition, and dashboard layouts.
+
+## Installation
+
+```bash
+pnpm add @mdxui/zero
+```
+
+## Quick Start
+
+```tsx
+import { MailZeroPage } from '@mdxui/zero'
+
+function App() {
+  return (
+    <MailZeroPage
+      initialThreads={threads}
+      initialFolders={folders}
+      initialLabels={labels}
+      user={{ name: 'John', email: 'john@example.com.ai' }}
+    />
+  )
+}
+```
+
+## Package Structure
+
+```
+@mdxui/zero
+├── /mail          # Core mail components
+│   ├── MailList       # Thread list with selection
+│   ├── MailItem       # Individual thread item
+│   ├── ThreadDisplay  # Full thread view
+│   └── MessageView    # Single message display
+├── /compose       # Email composition
+│   └── EmailComposer  # Full compose UI with toolbar
+├── /dashboard     # Layout components
+│   ├── MailShell      # Three-panel resizable layout
+│   └── MailSidebar    # Folder/label navigation
+├── /landing       # Landing page components
+└── /pages         # Complete page compositions
+    └── MailZeroPage   # Full email app with state
+```
+
+## Components
+
+### MailZeroPage
+
+Complete email application with internal state management. Use this for a full email experience.
+
+```tsx
+import { MailZeroPage } from '@mdxui/zero'
+
+<MailZeroPage
+  initialThreads={threads}
+  initialFolders={folders}
+  initialLabels={labels}
+  initialFolderId="inbox"
+  user={{ name: 'John Doe', email: 'john@example.com.ai' }}
+/>
+```
+
+All interactions (reply, archive, delete, etc.) are handled internally. Check the browser console for action logs.
+
+### MailShell
+
+Three-panel resizable layout combining sidebar, mail list, and thread display. Use when you need custom state management.
+
+```tsx
+import { MailShell } from '@mdxui/zero/dashboard'
+
+<MailShell
+  // Sidebar props
+  folders={folders}
+  activeFolderId="inbox"
+  onFolderClick={(folderId) => setActiveFolder(folderId)}
+
+  // List props
+  threads={threads}
+  onThreadClick={(thread) => setActiveThread(thread)}
+
+  // Thread display props
+  activeThread={activeThread}
+  onReply={(messageId) => openComposer({ replyTo: messageId })}
+  onArchive={() => archiveThread(activeThread.id)}
+/>
+```
+
+### MailList
+
+Thread list with selection, virtualization, and keyboard navigation.
+
+```tsx
+import { MailList } from '@mdxui/zero/mail'
+
+<MailList
+  threads={threads}
+  selectedIds={selectedIds}
+  activeId={activeId}
+  selectionMode="multiple"
+  displayMode="comfortable"
+  onThreadClick={(thread) => setActiveThread(thread)}
+  onSelectionChange={(ids) => setSelectedIds(ids)}
+/>
+```
+
+### ThreadDisplay
+
+Full thread view with message list and actions.
+
+```tsx
+import { ThreadDisplay } from '@mdxui/zero/mail'
+
+<ThreadDisplay
+  thread={thread}
+  onReply={(messageId) => openComposer({ replyTo: messageId })}
+  onReplyAll={(messageId) => openComposer({ replyAllTo: messageId })}
+  onForward={(messageId) => openComposer({ forward: messageId })}
+  onSnooze={(isoDate) => snoozeThread(thread.id, isoDate)}
+  onMove={(folderId) => moveThread(thread.id, folderId)}
+  onLabel={(labelIds) => labelThread(thread.id, labelIds)}
+/>
+```
+
+### EmailComposer
+
+Rich email composition with toolbar, recipient input, and AI assistance.
+
+```tsx
+import { EmailComposer } from '@mdxui/zero/compose'
+
+<EmailComposer
+  mode="compose"
+  initialDraft={{ to: [], subject: '', body: '' }}
+  onSend={(draft) => sendEmail(draft)}
+  onSaveDraft={(draft) => saveDraft(draft)}
+  onDiscard={() => closeComposer()}
+/>
+```
+
+## Callback Signatures
+
+All callbacks receive appropriate context:
+
+| Callback | Signature | Context |
+|----------|-----------|---------|
+| `onReply` | `(messageId: string) => void` | Reply to specific message |
+| `onReplyAll` | `(messageId: string) => void` | Reply-all to specific message |
+| `onForward` | `(messageId: string) => void` | Forward specific message |
+| `onSnooze` | `(isoDate: string) => void` | Snooze until date |
+| `onMove` | `(folderId: string) => void` | Move to folder |
+| `onLabel` | `(labelIds: string[]) => void` | Toggle labels |
+| `onThreadClick` | `(thread: Thread) => void` | Thread object |
+| `onFolderClick` | `(folderId: string) => void` | Folder ID |
+
+Thread-level actions (archive, delete, spam, star, print) are void callbacks - the parent tracks the active thread.
+
+## Types
+
+Types are defined in `mdxui` package:
+
+```tsx
+import type {
+  MailThread as Thread,
+  MailMessage as Message,
+  Folder,
+  MailLabel as Label,
+  MailShellProps,
+  ThreadDisplayProps,
+  MailListProps,
+} from 'mdxui'
+```
+
+## Development
+
+```bash
+# Type check
+pnpm --filter @mdxui/zero typecheck
+
+# Run Storybook
+pnpm storybook
+
+# Visual regression tests (requires Storybook running)
+pnpm --filter @mdxui/zero test:visual
+
+# Update visual baselines
+pnpm --filter @mdxui/zero test:visual:update
+```
+
+## Current Limitations
+
+This package currently provides **UI components only**. It lacks the full app infrastructure found in [Mail-0/Zero](https://github.com/Mail-0/Zero):
+
+- No react-router integration
+- No state management (jotai/react-query)
+- No data layer / API integration
+- No proper page routing
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the target architecture and implementation plan.
+
+## Credits
+
+Components ported from [Mail-0/Zero](https://github.com/Mail-0/Zero), an AI-powered email client.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mdxui/zero",
+  "version": "6.0.0",
+  "description": "Zero Email components for mdxui - AI-powered email client UI",
+  "sideEffects": false,
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./mail": "./src/mail/index.ts",
+    "./compose": "./src/compose/index.ts",
+    "./landing": "./src/landing/index.ts",
+    "./dashboard": "./src/dashboard/index.ts",
+    "./components": "./src/components/index.ts"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "5.9.3",
+    "@mdxui/typescript-config": "6.0.0"
+  },
+  "dependencies": {
+    "lucide-react": "^0.561.0",
+    "motion": "^12.23.26",
+    "react": "^19.2.3",
+    "zod": "^4.3.5",
+    "@mdxui/primitives": "6.0.0",
+    "mdxui": "6.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf .turbo node_modules",
+    "test:visual": "playwright test",
+    "test:visual:update": "playwright test --update-snapshots",
+    "test:visual:ui": "playwright test --ui"
+  }
+}

package/playwright.config.ts

@@ -0,0 +1,55 @@
+import { defineConfig, devices } from '@playwright/test'
+import { visualTestDefaults } from '../../playwright.base.config'
+
+/**
+ * Playwright Visual Regression Test Configuration for @mdxui/zero
+ *
+ * These tests compare our Zero components against the original Mail-0/Zero design.
+ * Extends visualTestDefaults from base config.
+ */
+export default defineConfig({
+  testDir: './tests/visual',
+  snapshotDir: './tests/visual/snapshots',
+  snapshotPathTemplate: '{snapshotDir}/{testFilePath}/{arg}{ext}',
+
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+
+  reporter: [
+    ['html', { outputFolder: './tests/visual/report' }],
+    ['list'],
+  ],
+
+  // Standard visual comparison settings
+  ...visualTestDefaults,
+
+  use: {
+    baseURL: 'http://localhost:6006',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 800 } },
+    },
+    {
+      name: 'chromium-wide',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1920, height: 1080 } },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: 'pnpm storybook',
+    url: 'http://localhost:6006',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+})

package/src/components/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared Components
+ *
+ * Reusable UI components used across Zero:
+ * - PricingCard: Pricing tier card
+ * - PricingSwitch: Monthly/annual toggle
+ * - SnoozeDialog: Email snooze picker
+ * - AttachmentDialog: Attachment viewer
+ * - LabelBadge: Email label badge
+ */
+
+// Components will be added as they are ported from Zero
+// export { PricingCard } from './pricing-card'
+// export { PricingSwitch } from './pricing-switch'
+// export { SnoozeDialog } from './snooze-dialog'
+// export { AttachmentDialog } from './attachment-dialog'
+// export { LabelBadge } from './label-badge'
+
+// Placeholder export to make this a valid module
+export {};

package/src/compose/email-composer.stories.tsx

@@ -0,0 +1,219 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { DraftState } from "mdxui";
+import { EditorToolbar, EmailComposer, RecipientInput } from "./email-composer";
+
+const sampleDraft: DraftState = {
+	to: [{ address: "alex@startup.io", name: "Alex Rivera" }],
+	cc: [],
+	bcc: [],
+	subject: "Quick follow-up on our call",
+	body: "Hi Alex,\n\nJust wanted to follow up on our conversation earlier today about the product roadmap.\n\nLet me know if you have any questions!\n\nBest,\nMe",
+	attachments: [],
+};
+
+const replyToMessage = {
+	id: "m1",
+	threadId: "t1",
+	subject: "Re: Product Launch Strategy",
+	from: { address: "alex@startup.io", name: "Alex Rivera" },
+	to: [{ address: "me@company.com", name: "Me" }],
+	date: new Date().toISOString(),
+	snippet: "Thanks for the update! Looking forward to the launch.",
+	textBody: "Thanks for the update! Looking forward to the launch.",
+	attachments: [],
+	labels: [],
+	isRead: true,
+	isStarred: false,
+	isImportant: false,
+	isDraft: false,
+};
+
+const meta: Meta<typeof EmailComposer> = {
+	title: "Zero/Compose/EmailComposer",
+	component: EmailComposer,
+	parameters: {
+		layout: "fullscreen",
+	},
+	tags: ["autodocs"],
+	decorators: [
+		(Story) => (
+			<div className="h-screen w-full max-w-4xl mx-auto p-4 bg-background">
+				<Story />
+			</div>
+		),
+	],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * New email composition.
+ * Matches the original Zero compose interface.
+ */
+export const Default: Story = {
+	args: {
+		mode: "new",
+		showCcBcc: false,
+		enableAI: true,
+		enableShortcuts: true,
+	},
+};
+
+/**
+ * With draft content pre-filled.
+ */
+export const WithDraft: Story = {
+	args: {
+		mode: "new",
+		initialDraft: sampleDraft,
+		showCcBcc: false,
+		enableAI: true,
+	},
+};
+
+/**
+ * Reply mode with quoted message.
+ */
+export const Reply: Story = {
+	args: {
+		mode: "reply",
+		replyTo: replyToMessage,
+		showCcBcc: false,
+		enableAI: true,
+	},
+};
+
+/**
+ * Reply-all mode.
+ */
+export const ReplyAll: Story = {
+	args: {
+		mode: "reply-all",
+		replyTo: replyToMessage,
+		showCcBcc: true,
+		enableAI: true,
+	},
+};
+
+/**
+ * Forward mode.
+ */
+export const Forward: Story = {
+	args: {
+		mode: "forward",
+		replyTo: replyToMessage,
+		showCcBcc: false,
+		enableAI: true,
+	},
+};
+
+/**
+ * Maximized view.
+ */
+export const Maximized: Story = {
+	args: {
+		mode: "new",
+		isMaximized: true,
+		showCcBcc: true,
+		enableAI: true,
+	},
+};
+
+/**
+ * With CC/BCC fields visible.
+ */
+export const WithCcBcc: Story = {
+	args: {
+		mode: "new",
+		showCcBcc: true,
+		enableAI: true,
+	},
+};
+
+/**
+ * Sending state.
+ */
+export const Sending: Story = {
+	args: {
+		mode: "new",
+		initialDraft: sampleDraft,
+		isSending: true,
+		enableAI: true,
+	},
+};
+
+/**
+ * Without AI features.
+ */
+export const NoAI: Story = {
+	args: {
+		mode: "new",
+		showCcBcc: false,
+		enableAI: false,
+	},
+};
+
+/**
+ * With email signature.
+ */
+export const WithSignature: Story = {
+	args: {
+		mode: "new",
+		showCcBcc: false,
+		enableAI: true,
+		enableSignature: true,
+		signature: "\n\n--\nJohn Doe\nProduct Manager\nAcme Inc.",
+	},
+};
+
+// RecipientInput story
+export const RecipientInputDefault: StoryObj<typeof RecipientInput> = {
+	render: () => (
+		<div className="max-w-2xl p-4 bg-background">
+			<RecipientInput
+				field="to"
+				value={[
+					{ address: "alex@example.com.ai", name: "Alex Rivera" },
+					{ address: "sarah@example.com.ai", name: "Sarah Chen" },
+				]}
+				onChange={() => {}}
+				placeholder="Add recipients"
+				showAvatars={true}
+				disabled={false}
+				autoFocus={false}
+				allowFreeEntry={true}
+			/>
+		</div>
+	),
+};
+
+// EditorToolbar story
+export const ToolbarDefault: StoryObj<typeof EditorToolbar> = {
+	render: () => (
+		<div className="max-w-2xl p-4 bg-background border rounded-lg">
+			<EditorToolbar
+				onAction={() => {}}
+				showAI={true}
+				disabled={false}
+				compact={false}
+				sticky={false}
+			/>
+		</div>
+	),
+};
+
+// EditorToolbar compact
+export const ToolbarCompact: StoryObj<typeof EditorToolbar> = {
+	render: () => (
+		<div className="max-w-xl p-4 bg-background border rounded-lg">
+			<EditorToolbar
+				onAction={() => {}}
+				showAI={true}
+				disabled={false}
+				compact={true}
+				sticky={false}
+			/>
+		</div>
+	),
+};