@perrylink/dsh-ticktick 0.1.2

package/src/client/TicktickAction.tsx

@@ -0,0 +1,356 @@
+/**
+ * The TickTick Session-header action: a button that opens the task panel
+ * popup. The panel browses lists, filters by list, toggles between undone
+ * and completed views, runs full-text search, adds tasks, completes,
+ * deletes, sets/clears due dates, and drag-reorders (undone, single-list
+ * views only — cross-list ordering has no TickTick semantics). All data
+ * flows through the injected {@link TicktickApi}; the panel holds no other
+ * RPC.
+ *
+ * @module dsh-ticktick/client/TicktickAction
+ */
+
+import { createElement as h, Fragment, useEffect, useRef, useState } from 'react'
+import type { ChangeEvent, DragEvent, ReactElement } from 'react'
+import type { TicktickApi } from './api.ts'
+import type { TicktickTaskWire } from '../wire.ts'
+import { formatDue } from './dates.ts'
+import { sortOrderAtEnd, sortOrderBefore } from './order.ts'
+import { en, type TicktickLocaleKey } from './locales.ts'
+
+/** Translator face (bound to this plugin's locale namespace by the renderer). */
+export type TicktickTranslator = (key: TicktickLocaleKey) => string
+
+/** Props the header-actions slot injects. */
+export interface TicktickActionInjected {
+  api: TicktickApi
+  /** Write the API token into the settings namespace (one-step panel setup). */
+  setToken: (token: string) => Promise<void>
+  t?: TicktickTranslator
+}
+
+/** One project for the filter dropdown. */
+interface ProjectOption {
+  id: string
+  name: string
+}
+
+/** All lists sentinel. */
+const ALL = '__all__'
+
+/** Panel view modes. */
+type ViewMode = 'undone' | 'completed'
+
+/**
+ * The header action component: button + popup panel.
+ * @param props - injected api and optional translator.
+ */
+export function TicktickAction(props: TicktickActionInjected): ReactElement {
+  const { api, setToken } = props
+  const t: TicktickTranslator = props.t ?? (key => en[key])
+  const [open, setOpen] = useState(false)
+  const [projects, setProjects] = useState<readonly ProjectOption[]>([])
+  const [tasks, setTasks] = useState<readonly TicktickTaskWire[]>([])
+  const [warnings, setWarnings] = useState<readonly string[]>([])
+  const [selected, setSelected] = useState<string>(ALL)
+  const [viewMode, setViewMode] = useState<ViewMode>('undone')
+  const [searchQuery, setSearchQuery] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [addTitle, setAddTitle] = useState('')
+  const [addDue, setAddDue] = useState('')
+  const [draggingId, setDraggingId] = useState<string | null>(null)
+  const [status, setStatus] = useState<{ configured: boolean, connected: boolean } | null>(null)
+  const [tokenInput, setTokenInput] = useState('')
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  const searching = searchQuery.trim() !== ''
+  const singleList = selected !== ALL
+  const editable = !searching && viewMode === 'undone'
+
+  const projectName = (id: string | null): string => {
+    if (id === null) return '?'
+    return projects.find(project => project.id === id)?.name ?? id
+  }
+
+  const refreshStatus = async (): Promise<void> => {
+    try {
+      const current = await api.status()
+      setStatus({ configured: current.configured, connected: current.connected })
+    } catch {
+      setStatus({ configured: false, connected: false })
+    }
+  }
+
+  const saveToken = async (): Promise<void> => {
+    const token = tokenInput.trim()
+    if (token === '') return
+    setBusy(true)
+    setError(null)
+    try {
+      await setToken(token)
+      setTokenInput('')
+      await refreshStatus()
+      await load()
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const load = async (): Promise<void> => {
+    setBusy(true)
+    setError(null)
+    try {
+      const projectId = selected === ALL ? undefined : selected
+      let taskResult
+      if (searching) {
+        taskResult = await api.search(searchQuery.trim())
+      } else if (viewMode === 'completed') {
+        taskResult = await api.completed(projectId, 30)
+      } else {
+        taskResult = await api.tasks(projectId)
+      }
+      const projectResult = await api.projects()
+      setProjects(projectResult.projects)
+      setTasks(taskResult.tasks)
+      setWarnings(taskResult.warnings)
+    } catch (cause) {
+      // The inline token setup explains the unconfigured state; keep other
+      // failures visible.
+      if (!/no-token|no token/i.test(cause instanceof Error ? cause.message : String(cause))) {
+        setError(cause instanceof Error ? cause.message : String(cause))
+      }
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  useEffect(() => {
+    if (!open) return
+    void load()
+    void refreshStatus()
+    const onPointerDown = (event: MouseEvent): void => {
+      if (panelRef.current !== null && event.target instanceof Node && !panelRef.current.contains(event.target)) {
+        setOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', onPointerDown)
+    return () => document.removeEventListener('mousedown', onPointerDown)
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- user actions reload explicitly.
+  }, [open])
+
+  const selectProject = async (value: string): Promise<void> => {
+    setSelected(value)
+    await load()
+  }
+
+  const switchView = async (mode: ViewMode): Promise<void> => {
+    setViewMode(mode)
+    setSearchQuery('')
+    await load()
+  }
+
+  const runSearch = async (query: string): Promise<void> => {
+    setSearchQuery(query)
+    if (query.trim() === '') {
+      await load()
+      return
+    }
+    setBusy(true)
+    setError(null)
+    try {
+      const result = await api.search(query.trim())
+      setTasks(result.tasks)
+      setWarnings(result.warnings)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const submitAdd = async (): Promise<void> => {
+    const title = addTitle.trim()
+    if (title === '') return
+    setBusy(true)
+    setError(null)
+    try {
+      await api.add(title, selected === ALL ? undefined : selected, addDue === '' ? undefined : addDue)
+      setAddTitle('')
+      setAddDue('')
+      await load()
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const runTask = async (action: () => Promise<void>): Promise<void> => {
+    setBusy(true)
+    setError(null)
+    try {
+      await action()
+      await load()
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const completeTask = (task: TicktickTaskWire): Promise<void> => runTask(async () => {
+    await api.complete(task.id, task.projectId ?? '')
+  })
+
+  const removeTask = (task: TicktickTaskWire): Promise<void> => runTask(async () => {
+    if (!window.confirm(t('confirmDelete'))) return
+    await api.remove(task.id, task.projectId ?? '')
+  })
+
+  const applyDue = (task: TicktickTaskWire, value: string): Promise<void> => runTask(async () => {
+    await api.setDue(task.id, task.projectId ?? undefined, value === '' ? undefined : value)
+  })
+
+  const clearDue = (task: TicktickTaskWire): Promise<void> => runTask(async () => {
+    await api.setDue(task.id, task.projectId ?? undefined)
+  })
+
+  const dropOnTask = (target: TicktickTaskWire): Promise<void> => {
+    if (draggingId === null || draggingId === target.id) return Promise.resolve()
+    const order = sortOrderBefore(target)
+    if (order === null) return Promise.resolve()
+    return runTask(async () => {
+      await api.reorder(draggingId, target.projectId ?? undefined, order)
+    }).then(() => { setDraggingId(null) })
+  }
+
+  const dropAtEnd = (): Promise<void> => {
+    if (draggingId === null) return Promise.resolve()
+    const order = sortOrderAtEnd(tasks)
+    if (order === null) return Promise.resolve()
+    const dragged = tasks.find(task => task.id === draggingId)
+    return runTask(async () => {
+      await api.reorder(draggingId, dragged?.projectId ?? undefined, order)
+    }).then(() => { setDraggingId(null) })
+  }
+
+  const viewToggle = (mode: ViewMode, label: string): ReactElement =>
+    h('button', {
+      className: 'tkt-iconbtn',
+      type: 'button',
+      disabled: busy,
+      style: viewMode === mode ? { fontWeight: 600, textDecoration: 'underline' } : undefined,
+      onClick: () => { void switchView(mode) },
+    }, label)
+
+  return h('div', { className: 'tkt-anchor' },
+    h('button', { className: 'tkt-button', type: 'button', title: t('open'), onClick: () => { setOpen(!open) } },
+      h('span', null, '☑'),
+      h('span', null, t('title'))),
+    open && h('div', { className: 'tkt-panel', ref: panelRef },
+      h('div', { className: 'tkt-row', style: { gap: '6px' } },
+        h('select', { className: 'tkt-select', value: selected, disabled: busy, onChange: (event: ChangeEvent<HTMLSelectElement>) => { void selectProject(event.target.value) } },
+          h('option', { value: ALL }, t('allLists')),
+          projects.map(project => h('option', { key: project.id, value: project.id }, project.name))),
+        viewToggle('undone', t('viewUndone')),
+        viewToggle('completed', t('viewCompleted')),
+        h('button', { className: 'tkt-iconbtn', type: 'button', title: t('refresh'), disabled: busy, onClick: () => { void load() } }, '↻'),
+        status !== null && h('span', {
+          className: `tkt-chip ${status.configured ? (status.connected ? 'today' : 'overdue') : 'later'}`,
+          title: status.configured ? (status.connected ? t('statusConnected') : t('statusNotConnected')) : t('statusUnconfigured'),
+        }, '●')),
+      h('div', { className: 'tkt-row', style: { gap: '6px' } },
+        h('input', {
+          className: 'tkt-input',
+          placeholder: t('searchPlaceholder'),
+          value: searchQuery,
+          onChange: (event: ChangeEvent<HTMLInputElement>) => { void runSearch(event.target.value) },
+        })),
+      status?.configured === false && h('div', { className: 'tkt-warning', style: { display: 'flex', flexDirection: 'column', gap: '6px' } },
+        h('div', null, t('panelTokenHint')),
+        h('div', { style: { display: 'flex', gap: '6px' } },
+          h('input', {
+            className: 'tkt-input',
+            type: 'password',
+            placeholder: t('panelTokenPlaceholder'),
+            value: tokenInput,
+            onChange: (event: ChangeEvent<HTMLInputElement>) => { setTokenInput(event.target.value) },
+            onKeyDown: event => { if (event.key === 'Enter') void saveToken() },
+          }),
+          h('button', { className: 'tkt-iconbtn', type: 'button', disabled: busy || tokenInput.trim() === '', onClick: () => { void saveToken() } }, t('panelTokenSave')))),
+      editable && h('div', { className: 'tkt-row', style: { gap: '6px' } },
+        h('input', {
+          className: 'tkt-input',
+          placeholder: t('addPlaceholder'),
+          value: addTitle,
+          onChange: (event: ChangeEvent<HTMLInputElement>) => { setAddTitle(event.target.value) },
+          onKeyDown: event => { if (event.key === 'Enter') void submitAdd() },
+        }),
+        h('input', {
+          className: 'tkt-date',
+          type: 'date',
+          value: addDue,
+          onChange: (event: ChangeEvent<HTMLInputElement>) => { setAddDue(event.target.value) },
+        }),
+        h('button', { className: 'tkt-iconbtn', type: 'button', disabled: busy || addTitle.trim() === '', onClick: () => { void submitAdd() } }, t('add'))),
+      error !== null && h('div', { className: 'tkt-error' }, t('loadError') + error),
+      warnings.map(warning => h('div', { key: warning, className: 'tkt-warning' }, `${t('warning')}: ${warning}`)),
+      tasks.length === 0 && !busy && h('div', { className: 'tkt-warning' }, searching ? t('searchEmpty') : t('empty')),
+      h('div', { className: 'tkt-list' },
+        tasks.map(task => {
+          const due = formatDue(task.dueDate)
+          const chipClass = due.kind === 'none' ? 'later' : due.kind
+          return h('div', {
+            key: task.id,
+            className: `tkt-row${draggingId === task.id ? ' dragging' : ''}`,
+            draggable: editable && singleList && !busy,
+            onDragStart: () => { setDraggingId(task.id) },
+            onDragOver: (event: DragEvent<HTMLDivElement>) => { event.preventDefault() },
+            onDrop: (event: DragEvent<HTMLDivElement>) => { event.preventDefault(); void dropOnTask(task) },
+          },
+            h('input', {
+              type: 'checkbox',
+              checked: task.done,
+              disabled: busy || !editable,
+              onChange: () => { void completeTask(task) },
+              title: t('complete'),
+            }),
+            h('span', { className: `tkt-title${task.done ? ' done' : ''}`, title: task.title }, task.title),
+            due.kind !== 'none' && h('span', { className: `tkt-chip ${chipClass}` }, due.text),
+            !singleList && h('span', { className: 'tkt-chip later' }, projectName(task.projectId)),
+            h(Fragment, { key: 'controls' },
+              editable && h('input', {
+                className: 'tkt-date',
+                type: 'date',
+                value: task.dueDate === null ? '' : task.dueDate.slice(0, 10),
+                disabled: busy,
+                onChange: (event: ChangeEvent<HTMLInputElement>) => { void applyDue(task, event.target.value) },
+                title: t('setDue'),
+              }),
+              editable && task.dueDate !== null && h('button', {
+                className: 'tkt-iconbtn',
+                type: 'button',
+                title: t('clearDue'),
+                disabled: busy,
+                onClick: () => { void clearDue(task) },
+              }, '✕'),
+              h('button', {
+                className: 'tkt-iconbtn',
+                type: 'button',
+                title: t('delete'),
+                disabled: busy,
+                onClick: () => { void removeTask(task) },
+              }, '🗑')),
+          )
+        })),
+      editable && singleList && tasks.length > 0 && h('div', {
+        className: 'tkt-row',
+        style: { minHeight: '14px', borderBottom: 'none' },
+        onDragOver: (event: DragEvent<HTMLDivElement>) => { event.preventDefault() },
+        onDrop: (event: DragEvent<HTMLDivElement>) => { event.preventDefault(); void dropAtEnd() },
+      })),
+  )
+}

package/src/client/TicktickSettingsCard.tsx

@@ -0,0 +1,182 @@
+/**
+ * The TickTick plugin settings card (`settings.plugin.item`, key
+ * `ticktick`). The card owns its own staging form — the shipped card-form
+ * helper is in-repo and cross-plugin value imports are rejected by the
+ * bundle-purity gate, so this card renders its fields directly over the
+ * bound `SettingsScope` and writes each field through `scope.set`.
+ *
+ * @module dsh-ticktick/client/TicktickSettingsCard
+ */
+
+import { createElement as h, useEffect, useState } from 'react'
+import type { ChangeEvent } from 'react'
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
+import { en, type TicktickLocaleKey } from './locales.ts'
+import type { TicktickProbeResult, TicktickSettings } from '../wire.ts'
+
+/** Translator face (bound to this plugin's locale namespace by the renderer). */
+export type TicktickSettingsTranslator = (key: TicktickLocaleKey) => string
+
+/** Props the settings card slot injects. */
+export interface TicktickSettingsCardInjected {
+  scope: SettingsScope<TicktickSettings>
+  probe: () => Promise<TicktickProbeResult>
+  t?: TicktickSettingsTranslator
+}
+
+/** Staged form values (strings only; the scope writes the typed values). */
+interface FormState {
+  token: string
+  tokenFile: string
+  mcpUrl: string
+  protectedTaskIds: string
+}
+
+/**
+ * The plugin configuration card: token (secret), token file, endpoint, and
+ * protected ids, staged locally and written field-by-field on Save.
+ * @param props - bound scope and optional translator.
+ */
+export function TicktickSettingsCard(props: TicktickSettingsCardInjected): React.ReactElement {
+  const { scope, probe } = props
+  const t: TicktickSettingsTranslator = props.t ?? (key => en[key])
+  const [form, setForm] = useState<FormState>({ token: '', tokenFile: '', mcpUrl: '', protectedTaskIds: '' })
+  const [saved, setSaved] = useState(false)
+  const [cleared, setCleared] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [probeResult, setProbeResult] = useState<TicktickProbeResult | null>(null)
+  const [probing, setProbing] = useState(false)
+
+  useEffect(() => scope.subscribe(() => {
+    const value = scope.getSnapshot().value
+    setForm(current => ({
+      token: current.token,
+      tokenFile: value?.tokenFile ?? '',
+      mcpUrl: value?.mcpUrl ?? '',
+      protectedTaskIds: (value?.protectedTaskIds ?? []).join(', '),
+    }))
+  }), [scope])
+
+  useEffect(() => {
+    const value = scope.getSnapshot().value
+    if (value === undefined) return
+    setForm({
+      token: value.token ?? '',
+      tokenFile: value.tokenFile ?? '',
+      mcpUrl: value.mcpUrl ?? '',
+      protectedTaskIds: (value.protectedTaskIds ?? []).join(', '),
+    })
+  }, [scope])
+
+  const save = async (): Promise<void> => {
+    setError(null)
+    setSaved(false)
+    setCleared(false)
+    try {
+      await scope.set('token', form.token.trim())
+      await scope.set('tokenFile', form.tokenFile.trim())
+      await scope.set('mcpUrl', form.mcpUrl.trim())
+      await scope.set('protectedTaskIds', form.protectedTaskIds.split(',').map(id => id.trim()).filter(id => id !== ''))
+      setSaved(true)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    }
+  }
+
+  const test = async (): Promise<void> => {
+    setProbing(true)
+    setProbeResult(null)
+    setError(null)
+    try {
+      const result = await probe()
+      setProbeResult(result)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setProbing(false)
+    }
+  }
+
+  const clear = async (): Promise<void> => {
+    setError(null)
+    setSaved(false)
+    try {
+      await scope.set('token', '')
+      await scope.set('tokenFile', '')
+      setForm({ ...form, token: '', tokenFile: '' })
+      setCleared(true)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    }
+  }
+
+  const field = (key: keyof FormState, label: string, hint: string, type = 'text', placeholder = ''): React.ReactElement =>
+    h('div', { style: { marginBottom: '8px' } },
+      h('label', { style: { display: 'block', fontSize: '12px', marginBottom: '3px' } }, label),
+      h('input', {
+        type,
+        placeholder,
+        style: { width: '100%', boxSizing: 'border-box', padding: '5px 7px', borderRadius: '5px', border: '1px solid #ccc' },
+        value: form[key],
+        onChange: event => { setForm({ ...form, [key]: event.target.value }) },
+      }),
+      h('div', { style: { fontSize: '11px', color: '#888', marginTop: '2px' } }, hint))
+
+  const presetOf = (url: string): 'cn' | 'intl' | 'custom' => {
+    if (url === 'https://mcp.dida365.com') return 'cn'
+    if (url === 'https://mcp.ticktick.com') return 'intl'
+    return 'custom'
+  }
+
+  const endpointField = h('div', { style: { marginBottom: '8px' } },
+    h('label', { style: { display: 'block', fontSize: '12px', marginBottom: '3px' } }, t('endpointPreset')),
+    h('select', {
+      style: { width: '100%', boxSizing: 'border-box', padding: '5px 7px', borderRadius: '5px', border: '1px solid #ccc' },
+      value: presetOf(form.mcpUrl),
+      onChange: (event: ChangeEvent<HTMLSelectElement>) => {
+        if (event.target.value === 'cn') setForm({ ...form, mcpUrl: 'https://mcp.dida365.com' })
+        else if (event.target.value === 'intl') setForm({ ...form, mcpUrl: 'https://mcp.ticktick.com' })
+      },
+    },
+      h('option', { value: 'cn' }, t('endpointCn')),
+      h('option', { value: 'intl' }, t('endpointIntl')),
+      h('option', { value: 'custom' }, t('endpointCustom'))),
+    h('input', {
+      type: 'text',
+      style: { width: '100%', boxSizing: 'border-box', padding: '5px 7px', borderRadius: '5px', border: '1px solid #ccc', marginTop: '4px' },
+      value: form.mcpUrl,
+      onChange: (event: ChangeEvent<HTMLInputElement>) => { setForm({ ...form, mcpUrl: event.target.value }) },
+    }),
+    h('div', { style: { fontSize: '11px', color: '#888', marginTop: '2px' } }, t('settingsMcpUrlHint')))
+
+  return h('div', { style: { padding: '10px 0' } },
+    h('div', { style: { fontSize: '14px', fontWeight: 600, marginBottom: '8px' } }, t('settingsName')),
+    field('token', t('settingsToken'), t('settingsTokenHint'), 'password'),
+    field('tokenFile', t('settingsTokenFile'), t('settingsTokenFileHint')),
+    endpointField,
+    field('protectedTaskIds', t('settingsProtected'), t('settingsProtectedHint')),
+    error !== null && h('div', { style: { color: '#c62828', fontSize: '12px', margin: '6px 0' } }, error),
+    saved && h('div', { style: { color: '#2e7d32', fontSize: '12px', margin: '6px 0' } }, t('settingsSaved')),
+    cleared && h('div', { style: { color: '#2e7d32', fontSize: '12px', margin: '6px 0' } }, t('settingsCleared')),
+    probeResult !== null && h('div', {
+      style: { color: probeResult.ok ? '#2e7d32' : '#c62828', fontSize: '12px', margin: '6px 0' },
+    }, probeResult.ok ? t('settingsTestOk').replace('N', String(probeResult.toolCount)) : t('settingsTestFail') + (probeResult.error ?? '')),
+    h('div', { style: { display: 'flex', gap: '8px' } },
+      h('button', {
+        type: 'button',
+        style: { padding: '6px 14px', borderRadius: '6px', border: '1px solid #ccc', cursor: 'pointer', background: '#f5f5f5' },
+        onClick: () => { void save() },
+      }, t('settingsSave')),
+      h('button', {
+        type: 'button',
+        disabled: probing,
+        style: { padding: '6px 14px', borderRadius: '6px', border: '1px solid #ccc', cursor: 'pointer', background: '#f5f5f5' },
+        onClick: () => { void test() },
+      }, t('settingsTest')),
+      h('button', {
+        type: 'button',
+        style: { padding: '6px 14px', borderRadius: '6px', border: '1px solid #ccc', cursor: 'pointer', background: '#fff3f3', color: '#c62828' },
+        onClick: () => { void clear() },
+      }, t('settingsClear'))),
+  )
+}

package/src/client/api.ts

@@ -0,0 +1,56 @@
+/**
+ * The TickTick panel API face the widget receives: typed wrappers over the
+ * `remote.ticktick` namespace that unwrap `RemoteResult` and throw the
+ * RemoteError for a failed invocation.
+ *
+ * @module dsh-ticktick/client/api
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { TicktickAddResult, TicktickProbeResult, TicktickStatus, TicktickTasksResult } from '../wire.ts'
+import type { TicktickBatchAddRow, TicktickProjectsResult } from './remote.ts'
+
+/** Widget-facing data contract (injected into the header action). */
+export interface TicktickApi {
+  status(): Promise<TicktickStatus>
+  projects(): Promise<TicktickProjectsResult>
+  tasks(projectId?: string): Promise<TicktickTasksResult>
+  add(title: string, projectId?: string, dueDate?: string): Promise<TicktickAddResult>
+  complete(id: string, projectId: string): Promise<void>
+  remove(id: string, projectId: string): Promise<void>
+  setDue(id: string, projectId: string | undefined, dueDate?: string): Promise<void>
+  reorder(id: string, projectId: string | undefined, sortOrder: number): Promise<void>
+  completed(projectId?: string, days?: number): Promise<TicktickTasksResult>
+  search(query: string): Promise<TicktickTasksResult>
+  batchAdd(tasks: readonly TicktickBatchAddRow[]): Promise<{ created: number }>
+  probe(): Promise<TicktickProbeResult>
+}
+
+/**
+ * Build the widget API over a scope carrying `remote.ticktick`.
+ * @param scope - client scope with the mounted Remote namespace.
+ * @returns the typed API.
+ */
+export function createTicktickApi(scope: Context): TicktickApi {
+  const unwrap = <T>(result: RemoteResult<T>, method: string): T => {
+    if (!result.ok) {
+      throw new Error(`ticktick.${method} failed: ${result.error.code}: ${result.error.message}`)
+    }
+    return result.value
+  }
+  return {
+    status: async () => unwrap(await scope.remote.ticktick.status(), 'status'),
+    projects: async () => unwrap(await scope.remote.ticktick.projects(), 'projects'),
+    tasks: async (projectId) => unwrap(await scope.remote.ticktick.tasks(projectId), 'tasks'),
+    add: async (title, projectId, dueDate) => unwrap(await scope.remote.ticktick.add(title, projectId, dueDate), 'add'),
+    complete: async (id, projectId) => { unwrap(await scope.remote.ticktick.complete(id, projectId), 'complete') },
+    remove: async (id, projectId) => { unwrap(await scope.remote.ticktick.remove(id, projectId), 'remove') },
+    setDue: async (id, projectId, dueDate) => { unwrap(await scope.remote.ticktick.setDue(id, projectId, dueDate), 'setDue') },
+    reorder: async (id, projectId, sortOrder) => { unwrap(await scope.remote.ticktick.reorder(id, projectId, sortOrder), 'reorder') },
+    completed: async (projectId, days) => unwrap(await scope.remote.ticktick.completed(projectId, days), 'completed'),
+    search: async (query) => unwrap(await scope.remote.ticktick.search(query), 'search'),
+    batchAdd: async (tasks) => unwrap(await scope.remote.ticktick.batchAdd([...tasks]), 'batchAdd'),
+    probe: async () => unwrap(await scope.remote.ticktick.probe(), 'probe'),
+  }
+}

package/src/client/dates.ts

@@ -0,0 +1,61 @@
+/**
+ * Due-date presentation helpers: today / tomorrow / overdue / "M月D日"
+ * (locale-neutral date formatting) plus the ISO date-only string sent to
+ * the bridge for date-picker values.
+ *
+ * @module dsh-ticktick/client/dates
+ */
+
+/** Presentation of one due date: the label plus its urgency kind. */
+export interface DueLabel {
+  readonly text: string
+  readonly kind: 'overdue' | 'today' | 'tomorrow' | 'later' | 'none'
+}
+
+/** Zero-pad a number to two digits. */
+function pad(value: number): string {
+  return String(value).padStart(2, '0')
+}
+
+/** Local date key (YYYY-MM-DD) for a Date. */
+export function dateKey(date: Date): string {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+}
+
+/** Local date key for today. */
+export function todayKey(): string {
+  return dateKey(new Date())
+}
+
+/** Local date key for tomorrow. */
+export function tomorrowKey(): string {
+  const tomorrow = new Date()
+  tomorrow.setDate(tomorrow.getDate() + 1)
+  return dateKey(tomorrow)
+}
+
+/** Parse the date-only prefix of an ISO due date as a local date key. */
+function keyOfIso(dueDate: string): string | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(dueDate)
+  if (match === null) return null
+  return `${match[1]}-${match[2]}-${match[3]}`
+}
+
+/**
+ * Format one ISO due date against today.
+ * @param dueDate - ISO date or date-time; `null`/empty = no due date.
+ * @param now - optional clock injection for tests (epoch ms).
+ * @returns the presentation.
+ */
+export function formatDue(dueDate: string | null, now: number = Date.now()): DueLabel {
+  if (dueDate === null || dueDate === '') return { text: '', kind: 'none' }
+  const key = keyOfIso(dueDate)
+  if (key === null) return { text: dueDate.slice(0, 10), kind: 'later' }
+  const today = dateKey(new Date(now))
+  if (key === today) return { text: 'today', kind: 'today' }
+  const tomorrow = new Date(now)
+  tomorrow.setDate(tomorrow.getDate() + 1)
+  if (key === dateKey(tomorrow)) return { text: 'tomorrow', kind: 'tomorrow' }
+  if (key < today) return { text: key, kind: 'overdue' }
+  return { text: key, kind: 'later' }
+}