@mdxui/zero 6.0.0

package/.storybook/preview.ts

@@ -0,0 +1,20 @@
+import type { Preview } from '@storybook/react'
+
+/**
+ * Zero (Email client) preview configuration
+ *
+ * Zero is an email client interface that needs:
+ * - Fullscreen layout for complete email UI
+ * - Support for both light and dark themes
+ * - Email-specific context (threads, messages, folders)
+ */
+const preview: Preview = {
+  parameters: {
+    layout: 'fullscreen',
+    backgrounds: {
+      default: 'light',
+    },
+  },
+}
+
+export default preview

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,5 @@
+
+
+> @mdxui/zero@5.0.2 typecheck /Users/chrisrisner/Workspace/dot-do/ui/packages/zero
+> tsc --noEmit
+

package/ARCHITECTURE.md

@@ -0,0 +1,415 @@
+# @mdxui/zero Architecture Plan
+
+> This document outlines the target architecture for @mdxui/zero, based on analysis of [Mail-0/Zero](https://github.com/Mail-0/Zero) and our own patterns in `@mdxui/cockpit` (developer dashboard) and `@mdxui/widgets` (onboarding wizard).
+
+## Current State
+
+The package currently has UI components only - no routing, state management, or data layer:
+
+```
+zero/
+├── components/       # Shared UI components
+├── compose/          # EmailComposer (UI only)
+├── dashboard/        # MailShell, MailSidebar (UI only)
+├── landing/          # Landing page components
+├── mail/             # MailList, ThreadDisplay, MessageView (UI only)
+└── pages/            # MailZeroPage (dumb wrapper with local state)
+```
+
+**What's missing:**
+- Router integration (react-router)
+- Context/state management
+- Data layer / API integration
+- Proper page components that work with routes
+- Hooks for data fetching and actions
+- Standalone components for embedding
+
+## Target Architecture
+
+Based on Mail-0/Zero and cockpit/developer patterns:
+
+```
+zero/
+├── context/
+│   ├── zero-context.tsx        # ZeroProvider, useZero, useMailState
+│   └── compose-context.tsx     # ComposeProvider, useCompose
+├── data-layer/
+│   ├── api.ts                  # MailAPI interface
+│   ├── types.ts                # API request/response types
+│   └── mock-api.ts             # Mock implementation for demos
+├── hooks/
+│   ├── use-threads.ts          # Thread fetching, pagination, search
+│   ├── use-thread.ts           # Single thread by ID
+│   ├── use-folders.ts          # Folder list with counts
+│   ├── use-labels.ts           # Labels CRUD
+│   ├── use-compose.ts          # Compose state, draft management
+│   ├── use-mail-actions.ts     # archive, delete, star, move, label
+│   ├── use-mail-navigation.ts  # Keyboard nav, folder switching
+│   ├── use-optimistic.ts       # Optimistic updates
+│   └── use-undo.ts             # Undo actions
+├── pages/
+│   ├── mail-page.tsx           # /mail - redirects to inbox
+│   ├── folder-page.tsx         # /mail/:folder - inbox, sent, drafts, etc.
+│   ├── thread-page.tsx         # /mail/:folder/:threadId
+│   ├── compose-page.tsx        # /mail/compose
+│   └── settings-page.tsx       # /settings/*
+├── router.tsx                  # ZeroRouter + ZeroRoutes
+├── standalone/
+│   ├── index.ts
+│   ├── standalone-provider.tsx # Minimal provider for embedding
+│   ├── standalone-inbox.tsx    # Embeddable inbox
+│   ├── standalone-compose.tsx  # Embeddable composer
+│   └── standalone-thread.tsx   # Embeddable thread view
+├── types/
+│   ├── config.ts               # ZeroConfig, ZeroRoutes
+│   └── api.ts                  # API types
+├── mail/                       # (existing) UI components
+├── compose/                    # (existing) UI components
+├── dashboard/                  # (existing) UI components
+└── index.ts                    # Main exports
+```
+
+## Route Structure
+
+Based on Mail-0/Zero's `routes.ts`, using React Router's `Outlet` for nested layouts:
+
+```typescript
+// Primary mail routes
+/mail                     → Redirects to /mail/inbox
+/mail/:folder             → FolderPage (inbox, sent, drafts, spam, trash, starred, snoozed)
+/mail/:folder/:threadId   → ThreadPage (thread detail view)
+/mail/compose             → ComposePage (new email)
+/mail/compose?reply=:id   → ComposePage (reply mode)
+/mail/compose?forward=:id → ComposePage (forward mode)
+
+// Settings routes
+/settings                 → SettingsPage (redirects to /settings/general)
+/settings/general         → General settings
+/settings/labels          → Label management
+/settings/appearance      → Theme settings
+/settings/notifications   → Notification preferences
+/settings/connections     → Email account connections
+```
+
+### Router Implementation
+
+Using `Outlet` for nested layouts (similar to cockpit/developer):
+
+```tsx
+// router.tsx
+import { Outlet, Route, Routes, Navigate } from 'react-router-dom'
+
+function MailLayout() {
+  return (
+    <div className="flex h-screen">
+      <MailSidebar />
+      <div className="flex-1">
+        <Outlet /> {/* Child routes render here */}
+      </div>
+    </div>
+  )
+}
+
+export function ZeroRoutes() {
+  return (
+    <Routes>
+      <Route element={<MailLayout />}>
+        <Route index element={<Navigate to="inbox" replace />} />
+        <Route path=":folder" element={<FolderPage />} />
+        <Route path=":folder/:threadId" element={<ThreadPage />} />
+        <Route path="compose" element={<ComposePage />} />
+      </Route>
+      <Route path="settings" element={<SettingsLayout />}>
+        <Route index element={<Navigate to="general" replace />} />
+        <Route path="general" element={<SettingsGeneralPage />} />
+        <Route path="labels" element={<SettingsLabelsPage />} />
+        <Route path="appearance" element={<SettingsAppearancePage />} />
+      </Route>
+    </Routes>
+  )
+}
+```
+
+This mirrors the pattern in `packages/cockpit/src/developer/router.tsx`.
+
+## Hooks Reference
+
+Based on Mail-0/Zero's hooks directory:
+
+### Data Hooks
+| Hook | Purpose |
+|------|---------|
+| `useThreads(folder, options)` | Fetch threads for a folder with pagination |
+| `useThread(threadId)` | Fetch single thread with messages |
+| `useFolders()` | Fetch folders with unread counts |
+| `useLabels()` | Fetch/create/update/delete labels |
+| `useDrafts()` | Draft management |
+| `useAttachments()` | Attachment upload/download |
+| `useStats()` | Email statistics |
+
+### Action Hooks
+| Hook | Purpose |
+|------|---------|
+| `useMailActions()` | archive, delete, star, spam, move, label |
+| `useOptimisticActions()` | Wrap actions with optimistic updates |
+| `useUndoSend()` | Undo recently sent emails |
+| `useCompose()` | Compose state, send, save draft |
+
+### Navigation Hooks
+| Hook | Purpose |
+|------|---------|
+| `useMailNavigation()` | Keyboard shortcuts, folder navigation |
+| `useHotKey(key, callback)` | Register keyboard shortcuts |
+
+### UI Hooks
+| Hook | Purpose |
+|------|---------|
+| `useMediaQuery(query)` | Responsive breakpoints |
+| `useMobile()` | Mobile detection |
+| `useAnimations()` | Animation preferences |
+| `useCopyToClipboard()` | Copy text utility |
+
+## Context Structure
+
+### ZeroProvider
+
+With react-router, navigation state comes from URL params - context only holds non-URL state:
+
+```typescript
+interface ZeroContextValue {
+  // API client
+  api: MailAPI
+
+  // User & auth
+  user: User | null
+
+  // Settings
+  settings: MailSettings
+  updateSettings: (updates: Partial<MailSettings>) => void
+
+  // Multi-select state (not in URL)
+  selectedThreadIds: string[]
+  selectThreads: (ids: string[]) => void
+  clearSelection: () => void
+
+  // Compose modal state
+  composeOpen: boolean
+  composeMode: 'new' | 'reply' | 'reply-all' | 'forward' | null
+  composeContext: { threadId?: string; messageId?: string } | null
+  openCompose: (mode: ComposeMode, context?: ComposeContext) => void
+  closeCompose: () => void
+}
+
+// Navigation comes from react-router, not context
+// Use useParams() for folder/threadId
+// Use useNavigate() for navigation
+```
+
+### Usage
+
+Similar to DeveloperDashboard, the user gets a single component that handles everything internally:
+
+```tsx
+// Simple usage - ZeroMail handles provider, router, routes internally
+<ZeroMail
+  api={mailApi}
+  user={user}
+  basePath="/mail"
+/>
+
+// Or mount in existing router
+<Route path="/mail/*" element={
+  <ZeroMail api={mailApi} user={user} />
+} />
+
+// With configuration
+<ZeroMail
+  api={mailApi}
+  user={user}
+  basePath="/mail"
+  config={{
+    routes: {
+      inbox: true,
+      sent: true,
+      drafts: true,
+      settings: true,
+    },
+    features: {
+      compose: true,
+      search: true,
+      labels: true,
+    },
+  }}
+/>
+```
+
+Internally, ZeroMail composes:
+```tsx
+function ZeroMail({ api, user, basePath, config }: ZeroMailProps) {
+  return (
+    <ZeroProvider api={api} user={user} config={config}>
+      <ZeroRouter basePath={basePath}>
+        <ZeroRoutes />
+      </ZeroRouter>
+    </ZeroProvider>
+  )
+}
+```
+
+### URL-Derived State (via react-router)
+
+```typescript
+// In FolderPage.tsx
+function FolderPage() {
+  const { folder } = useParams<{ folder: string }>()
+  const { data: threads } = useThreads(folder)
+  // ...
+}
+
+// In ThreadPage.tsx
+function ThreadPage() {
+  const { folder, threadId } = useParams<{ folder: string; threadId: string }>()
+  const { data: thread } = useThread(threadId)
+  const navigate = useNavigate()
+
+  const handleClose = () => navigate(`/mail/${folder}`)
+  const handleNext = (nextId: string) => navigate(`/mail/${folder}/${nextId}`)
+  // ...
+}
+```
+
+### ComposeProvider
+
+```typescript
+interface ComposeContextValue {
+  // Draft state
+  draft: DraftState
+  updateDraft: (updates: Partial<DraftState>) => void
+
+  // Mode
+  mode: 'compose' | 'reply' | 'reply-all' | 'forward'
+  replyTo: Message | null
+
+  // Actions
+  send: () => Promise<void>
+  saveDraft: () => Promise<void>
+  discard: () => void
+
+  // Attachments
+  attachments: Attachment[]
+  addAttachment: (file: File) => Promise<void>
+  removeAttachment: (id: string) => void
+
+  // State
+  isSending: boolean
+  isSaving: boolean
+}
+```
+
+## API Interface
+
+```typescript
+interface MailAPI {
+  // Threads
+  getThreads(folder: string, options?: ThreadsOptions): Promise<ThreadsResponse>
+  getThread(threadId: string): Promise<Thread>
+
+  // Messages
+  getMessage(messageId: string): Promise<Message>
+  sendMessage(draft: DraftState): Promise<Message>
+
+  // Actions
+  archiveThreads(threadIds: string[]): Promise<void>
+  deleteThreads(threadIds: string[]): Promise<void>
+  starThreads(threadIds: string[], starred: boolean): Promise<void>
+  markAsSpam(threadIds: string[]): Promise<void>
+  moveThreads(threadIds: string[], folderId: string): Promise<void>
+  labelThreads(threadIds: string[], labelIds: string[], action: 'add' | 'remove'): Promise<void>
+  snoozeThreads(threadIds: string[], until: string): Promise<void>
+
+  // Folders
+  getFolders(): Promise<Folder[]>
+
+  // Labels
+  getLabels(): Promise<Label[]>
+  createLabel(label: CreateLabelInput): Promise<Label>
+  updateLabel(id: string, label: UpdateLabelInput): Promise<Label>
+  deleteLabel(id: string): Promise<void>
+
+  // Drafts
+  saveDraft(draft: DraftState): Promise<Draft>
+  getDrafts(): Promise<Draft[]>
+  deleteDraft(draftId: string): Promise<void>
+
+  // Attachments
+  uploadAttachment(file: File): Promise<Attachment>
+
+  // Search
+  searchThreads(query: string, options?: SearchOptions): Promise<ThreadsResponse>
+}
+```
+
+## Implementation Order
+
+### Phase 1: Core Infrastructure
+1. [ ] `types/config.ts` - Configuration types
+2. [ ] `types/api.ts` - API types
+3. [ ] `data-layer/api.ts` - API interface
+4. [ ] `data-layer/mock-api.ts` - Mock implementation
+5. [ ] `context/zero-context.tsx` - Main provider
+
+### Phase 2: Hooks
+1. [ ] `hooks/use-threads.ts`
+2. [ ] `hooks/use-thread.ts`
+3. [ ] `hooks/use-folders.ts`
+4. [ ] `hooks/use-mail-actions.ts`
+5. [ ] `hooks/use-compose.ts`
+6. [ ] `hooks/use-mail-navigation.ts`
+
+### Phase 3: Router & Pages
+1. [ ] `router.tsx` - Router setup
+2. [ ] `pages/folder-page.tsx`
+3. [ ] `pages/thread-page.tsx`
+4. [ ] `pages/compose-page.tsx`
+
+### Phase 4: Standalone Components
+1. [ ] `standalone/standalone-provider.tsx`
+2. [ ] `standalone/standalone-inbox.tsx`
+3. [ ] `standalone/standalone-compose.tsx`
+
+### Phase 5: Polish
+1. [ ] Keyboard shortcuts
+2. [ ] Optimistic updates
+3. [ ] Undo functionality
+4. [ ] Settings pages
+
+## Dependencies to Add
+
+```json
+{
+  "dependencies": {
+    "react-router-dom": "^7.0.0",
+    "jotai": "^2.12.0",
+    "@tanstack/react-query": "^5.74.0"
+  }
+}
+```
+
+## References
+
+- [Mail-0/Zero GitHub](https://github.com/Mail-0/Zero)
+- [Zero routes.ts](https://github.com/Mail-0/Zero/blob/staging/apps/mail/app/routes.ts)
+- [Zero hooks](https://github.com/Mail-0/Zero/tree/staging/apps/mail/hooks)
+- Internal: `packages/cockpit/src/developer/` - Similar architecture
+- Internal: `packages/widgets/src/onboarding/` - Wizard pattern
+
+## Lessons Learned
+
+Building UI components first without considering the app architecture leads to:
+1. Components that don't integrate well with routing
+2. Props that don't match real data flow patterns
+3. Missing context for state that needs to be shared
+4. No clear integration path for real APIs
+5. Significant refactoring needed later
+
+**For future packages:** Start with the provider/context/router architecture first, then build components that consume that infrastructure.

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# @mdxui/zero
+
+## 6.0.0
+
+### Patch Changes
+
+- @mdxui/primitives@6.0.0
+- mdxui@6.0.0
+
+## 5.0.2
+
+### Patch Changes
+
+- @mdxui/primitives@5.0.2
+- mdxui@5.0.2
+
+## 5.0.1
+
+### Patch Changes
+
+- @mdxui/primitives@5.0.1
+- mdxui@5.0.1
+
+## 5.0.0
+
+### Patch Changes
+
+- @mdxui/primitives@5.0.0
+- mdxui@5.0.0
+
+## 4.0.0
+
+### Patch Changes
+
+- @mdxui/primitives@4.0.0
+- mdxui@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- @mdxui/primitives@3.0.1
+- mdxui@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- @mdxui/primitives@3.0.0
+- mdxui@3.0.0
+
+## 2.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - mdxui@2.1.1
+  - @mdxui/primitives@2.1.1
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies [8101194]
+  - mdxui@2.0.0
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies [defc863]
+  - mdxui@1.0.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [4d0d1a0]
+  - mdxui@0.4.1
+  - @mdxui/primitives@0.4.1