@puredesktop/puredesktop-ui-bridge 2.1.7 → 2.1.8

package/src/bridge/react/useDocumentLifecycle.tsx

@@ -0,0 +1,359 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  autosavePlatformDocument,
+  createPlatformDraft,
+  duplicatePlatformDocument,
+  promotePlatformDocument,
+  renamePlatformDocument,
+  touchPlatformRecentDocument,
+  type PlatformDocumentFilePayload,
+} from '../documents.mjs'
+import { bridge } from '../client.mjs'
+import { PLATFORM_BRIDGE_METHODS } from '../methods.mjs'
+
+export type DocumentLifecycleStatus = 'none' | 'draft' | 'filed'
+
+export interface DocumentLifecycleDoc {
+  path: string | null
+  title: string
+  status: DocumentLifecycleStatus
+  savedAt: string | null
+  saving: boolean
+  error: string | null
+}
+
+export interface UseDocumentLifecycleOptions {
+  appSlug: string
+  /** Document suffix, e.g. `.research`. */
+  suffix: string
+  kind: 'package' | 'file'
+  /** Called at flush time; returns the document's current file contents. */
+  serialize: () => PlatformDocumentFilePayload[]
+  /** Prefill for the naming dialog (e.g. an AI-generated title). */
+  suggestedTitle?: string
+  debounceMs?: number
+}
+
+export interface DocumentLifecycle {
+  doc: DocumentLifecycleDoc
+  /** Create the durable draft if none exists yet; returns the path. */
+  ensureDraft: () => Promise<string | null>
+  /** Note a content change: lazily creates the draft, debounces an autosave. */
+  markDirty: () => void
+  /** Immediate save of the current serialize() output. */
+  flush: () => Promise<void>
+  /** Name + file the document (move out of drafts). */
+  promote: (title: string, targetDir?: string) => Promise<void>
+  rename: (title: string) => Promise<void>
+  duplicate: () => Promise<string | null>
+  revealInFinder: () => Promise<void>
+  openInFiles: () => Promise<void>
+  /** Bind an existing on-disk document (opened from PureFiles/recents). */
+  adopt: (path: string, opts?: { title?: string }) => void
+  /** Detach — back to `none` (⌘N / new document). */
+  reset: () => void
+}
+
+function titleFromPath(path: string, suffix: string): string {
+  const name = path.split('/').pop() ?? path
+  return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name
+}
+
+function statusForPath(path: string): DocumentLifecycleStatus {
+  return path.includes('/PureDrafts/') ? 'draft' : 'filed'
+}
+
+export function useDocumentLifecycle(
+  options: UseDocumentLifecycleOptions,
+): DocumentLifecycle {
+  const { appSlug, suffix, kind, suggestedTitle } = options
+  const debounceMs = options.debounceMs ?? 1500
+  const serializeRef = useRef(options.serialize)
+  serializeRef.current = options.serialize
+
+  const [doc, setDoc] = useState<DocumentLifecycleDoc>({
+    path: null,
+    title: suggestedTitle ?? '',
+    status: 'none',
+    savedAt: null,
+    saving: false,
+    error: null,
+  })
+  const pathRef = useRef<string | null>(null)
+  const timerRef = useRef<number | null>(null)
+  // Serialize all writes for one document through a promise chain — never two
+  // concurrent autosaves, and flush() awaits everything queued before it.
+  const writeChainRef = useRef<Promise<void>>(Promise.resolve())
+  const creatingRef = useRef<Promise<string | null> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) window.clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  const queueWrite = useCallback(
+    (work: () => Promise<void>): Promise<void> => {
+      const next = writeChainRef.current.then(work, work)
+      writeChainRef.current = next.catch(() => undefined)
+      return next
+    },
+    [],
+  )
+
+  const saveNow = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    setDoc(current => ({ ...current, saving: true }))
+    try {
+      const { savedAt } = await autosavePlatformDocument({
+        path,
+        files: serializeRef.current(),
+      })
+      setDoc(current => ({ ...current, saving: false, savedAt, error: null }))
+    } catch (error) {
+      setDoc(current => ({
+        ...current,
+        saving: false,
+        error: error instanceof Error ? error.message : 'Could not save.',
+      }))
+    }
+  }, [])
+
+  const ensureDraft = useCallback(async (): Promise<string | null> => {
+    if (pathRef.current) return pathRef.current
+    if (creatingRef.current) return creatingRef.current
+    creatingRef.current = (async () => {
+      try {
+        const { path } = await createPlatformDraft({
+          appSlug,
+          suffix,
+          kind,
+          files: serializeRef.current(),
+        })
+        pathRef.current = path
+        setDoc(current => ({
+          ...current,
+          path,
+          title: current.title || titleFromPath(path, suffix),
+          status: 'draft',
+          savedAt: new Date().toISOString(),
+          error: null,
+        }))
+        void touchPlatformRecentDocument({
+          appSlug,
+          path,
+          title: titleFromPath(path, suffix),
+        }).catch(() => undefined)
+        return path
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error:
+            error instanceof Error ? error.message : 'Could not create draft.',
+        }))
+        return null
+      } finally {
+        creatingRef.current = null
+      }
+    })()
+    return creatingRef.current
+  }, [appSlug, kind, suffix])
+
+  const markDirty = useCallback((): void => {
+    void (async () => {
+      if (!pathRef.current) {
+        const created = await ensureDraft()
+        if (!created) return
+      }
+      if (timerRef.current !== null) window.clearTimeout(timerRef.current)
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        void queueWrite(saveNow)
+      }, debounceMs)
+    })()
+  }, [debounceMs, ensureDraft, queueWrite, saveNow])
+
+  const flush = useCallback(async (): Promise<void> => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+    if (!pathRef.current) return
+    await queueWrite(saveNow)
+  }, [queueWrite, saveNow])
+
+  // Last-chance flush when the app tab hides or unloads.
+  useEffect(() => {
+    const onHidden = (): void => {
+      if (document.visibilityState === 'hidden') void flush()
+    }
+    window.addEventListener('beforeunload', onHidden)
+    document.addEventListener('visibilitychange', onHidden)
+    return () => {
+      window.removeEventListener('beforeunload', onHidden)
+      document.removeEventListener('visibilitychange', onHidden)
+    }
+  }, [flush])
+
+  const promote = useCallback(
+    async (title: string, targetDir?: string): Promise<void> => {
+      const path = pathRef.current ?? (await ensureDraft())
+      if (!path) return
+      await flush()
+      try {
+        const result = await promotePlatformDocument({
+          path,
+          title,
+          targetDir,
+          suffix,
+          appSlug,
+        })
+        pathRef.current = result.path
+        setDoc(current => ({
+          ...current,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+          status: statusForPath(result.path),
+          error: null,
+        }))
+        void touchPlatformRecentDocument({
+          appSlug,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+        }).catch(() => undefined)
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error: error instanceof Error ? error.message : 'Could not file.',
+        }))
+      }
+    },
+    [appSlug, ensureDraft, flush, suffix],
+  )
+
+  const rename = useCallback(
+    async (title: string): Promise<void> => {
+      const path = pathRef.current
+      if (!path) {
+        setDoc(current => ({ ...current, title }))
+        return
+      }
+      await flush()
+      try {
+        const result = await renamePlatformDocument({
+          path,
+          title,
+          suffix,
+          appSlug,
+        })
+        pathRef.current = result.path
+        setDoc(current => ({
+          ...current,
+          path: result.path,
+          title: titleFromPath(result.path, suffix),
+          status: statusForPath(result.path),
+          error: null,
+        }))
+      } catch (error) {
+        setDoc(current => ({
+          ...current,
+          error: error instanceof Error ? error.message : 'Could not rename.',
+        }))
+      }
+    },
+    [appSlug, flush, suffix],
+  )
+
+  const duplicate = useCallback(async (): Promise<string | null> => {
+    const path = pathRef.current
+    if (!path) return null
+    await flush()
+    try {
+      const result = await duplicatePlatformDocument({ path, suffix })
+      return result.path
+    } catch {
+      return null
+    }
+  }, [flush, suffix])
+
+  const revealInFinder = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    await bridge.call(PLATFORM_BRIDGE_METHODS.OS_REVEAL, [path])
+  }, [])
+
+  const openInFiles = useCallback(async (): Promise<void> => {
+    const path = pathRef.current
+    if (!path) return
+    await bridge.call(PLATFORM_BRIDGE_METHODS.CATALOG_OPEN, [
+      { path, appSlug: 'purefiles' },
+    ])
+  }, [])
+
+  const adopt = useCallback(
+    (path: string, opts: { title?: string } = {}): void => {
+      pathRef.current = path
+      setDoc({
+        path,
+        title: opts.title ?? titleFromPath(path, suffix),
+        status: statusForPath(path),
+        savedAt: null,
+        saving: false,
+        error: null,
+      })
+      void touchPlatformRecentDocument({
+        appSlug,
+        path,
+        title: opts.title ?? titleFromPath(path, suffix),
+      }).catch(() => undefined)
+    },
+    [appSlug, suffix],
+  )
+
+  const reset = useCallback((): void => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+    pathRef.current = null
+    setDoc({
+      path: null,
+      title: '',
+      status: 'none',
+      savedAt: null,
+      saving: false,
+      error: null,
+    })
+  }, [])
+
+  return useMemo(
+    () => ({
+      doc,
+      ensureDraft,
+      markDirty,
+      flush,
+      promote,
+      rename,
+      duplicate,
+      revealInFinder,
+      openInFiles,
+      adopt,
+      reset,
+    }),
+    [
+      doc,
+      ensureDraft,
+      markDirty,
+      flush,
+      promote,
+      rename,
+      duplicate,
+      revealInFinder,
+      openInFiles,
+      adopt,
+      reset,
+    ],
+  )
+}

package/src/bridge/react/usePlatformAppSettings.test.tsx

@@ -0,0 +1,105 @@
+// @vitest-environment happy-dom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import { usePlatformAppSettings } from './usePlatformAppSettings.js'
+
+type ReactActGlobal = typeof globalThis & {
+  IS_REACT_ACT_ENVIRONMENT?: boolean
+}
+
+type Settings = Record<string, unknown> & {
+  view: 'list' | 'board'
+}
+
+const appSettingsMock = vi.hoisted(() => ({
+  getPlatformAppSettings: vi.fn(),
+  updatePlatformAppSettings: vi.fn(),
+}))
+
+vi.mock('../appSettings.mjs', () => appSettingsMock)
+
+let latest:
+  | ReturnType<typeof usePlatformAppSettings<Settings>>
+  | null = null
+
+function parseSettings(raw: Record<string, unknown>): Settings {
+  return {
+    view: raw.view === 'board' ? 'board' : 'list',
+  }
+}
+
+function Probe(): React.ReactElement {
+  latest = usePlatformAppSettings<Settings>({
+    appSlug: 'tasks',
+    parse: parseSettings,
+    initialSettings: { view: 'list' },
+  })
+  return <div />
+}
+
+async function flushEffects(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+describe('usePlatformAppSettings', () => {
+  let host: HTMLDivElement
+  let root: Root
+
+  beforeAll(() => {
+    ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  beforeEach(() => {
+    latest = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    appSettingsMock.getPlatformAppSettings.mockResolvedValue({ view: 'board' })
+    appSettingsMock.updatePlatformAppSettings.mockResolvedValue({ view: 'list' })
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    host.remove()
+    vi.clearAllMocks()
+  })
+
+  it('loads and normalizes app settings for one app slug', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    expect(appSettingsMock.getPlatformAppSettings).toHaveBeenCalledWith('tasks')
+    expect(latest?.settings).toEqual({ view: 'board' })
+  })
+
+  it('patches app settings through settings.app.update', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      await latest?.patchSettings({ view: 'list' })
+    })
+
+    expect(appSettingsMock.updatePlatformAppSettings).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      patch: { view: 'list' },
+    })
+    expect(latest?.settings).toEqual({ view: 'list' })
+  })
+})

package/src/bridge/react/usePlatformAppSettings.tsx

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+  getPlatformAppSettings,
+  updatePlatformAppSettings,
+} from '../appSettings.mjs'
+
+export interface UsePlatformAppSettingsOptions<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+> {
+  appSlug: string | null
+  /** Wait for bridge ready before loading (default: true when appSlug exists). */
+  enabled?: boolean
+  /** Normalize stored settings into the app-owned settings shape. */
+  parse?: (value: Record<string, unknown>) => TSettings
+  initialSettings?: TSettings
+}
+
+export interface UsePlatformAppSettingsResult<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+> {
+  settings: TSettings
+  loading: boolean
+  error: Error | null
+  /** Shallow-merge a patch through shell `settings.app.update`. */
+  patchSettings: (patch: Record<string, unknown>) => Promise<TSettings>
+  reload: () => void
+}
+
+function defaultParse<TSettings extends Record<string, unknown>>(
+  value: Record<string, unknown>,
+): TSettings {
+  return value as TSettings
+}
+
+/**
+ * Load and update the current app's settings through `settings.app.*`.
+ * App settings are small per-app preferences, not user-visible documents.
+ */
+export function usePlatformAppSettings<
+  TSettings extends Record<string, unknown> = Record<string, unknown>,
+>({
+  appSlug,
+  enabled = Boolean(appSlug),
+  parse = defaultParse<TSettings>,
+  initialSettings = {} as TSettings,
+}: UsePlatformAppSettingsOptions<TSettings>): UsePlatformAppSettingsResult<TSettings> {
+  const [settings, setSettings] = useState<TSettings>(initialSettings)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+  const [reloadToken, setReloadToken] = useState(0)
+
+  const reload = useCallback(() => {
+    setReloadToken(token => token + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled || !appSlug) return
+
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    void getPlatformAppSettings(appSlug)
+      .then(raw => {
+        if (!cancelled) setSettings(parse(raw))
+      })
+      .catch((cause: unknown) => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause : new Error(String(cause)))
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [appSlug, enabled, parse, reloadToken])
+
+  const patchSettings = useCallback(
+    async (patch: Record<string, unknown>): Promise<TSettings> => {
+      if (!appSlug) throw new Error('appSlug is required to update app settings')
+      try {
+        const next = parse(
+          await updatePlatformAppSettings({
+            appSlug,
+            patch,
+          }),
+        )
+        setSettings(next)
+        setError(null)
+        return next
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause))
+        setError(error)
+        throw error
+      }
+    },
+    [appSlug, parse],
+  )
+
+  return { settings, loading, error, patchSettings, reload }
+}

package/src/bridge/react/usePlatformJsonStore.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest'
+import { usePlatformJsonStore } from './usePlatformJsonStore.js'
+
+type ReactActGlobal = typeof globalThis & {
+  IS_REACT_ACT_ENVIRONMENT?: boolean
+}
+
+interface Store {
+  items: string[]
+}
+
+const storageMock = vi.hoisted(() => ({
+  readPlatformStorageJson: vi.fn(),
+  writePlatformStorageJson: vi.fn(),
+}))
+
+vi.mock('../storage.mjs', () => storageMock)
+
+let latest: ReturnType<typeof usePlatformJsonStore<Store>> | null = null
+
+const EMPTY_STORE: Store = { items: [] }
+
+function parseStore(value: unknown): Store {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return EMPTY_STORE
+  }
+  const record = value as Record<string, unknown>
+  return {
+    items: Array.isArray(record.items)
+      ? record.items.filter((item): item is string => typeof item === 'string')
+      : [],
+  }
+}
+
+function Probe(): React.ReactElement {
+  latest = usePlatformJsonStore<Store>({
+    appSlug: 'tasks',
+    fileName: 'tasks-items.json',
+    initialValue: EMPTY_STORE,
+    parse: parseStore,
+  })
+  return <div />
+}
+
+async function flushEffects(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+describe('usePlatformJsonStore', () => {
+  let host: HTMLDivElement
+  let root: Root
+
+  beforeAll(() => {
+    ;(globalThis as ReactActGlobal).IS_REACT_ACT_ENVIRONMENT = true
+  })
+
+  beforeEach(() => {
+    latest = null
+    host = document.createElement('div')
+    document.body.appendChild(host)
+    root = createRoot(host)
+    storageMock.readPlatformStorageJson.mockResolvedValue({
+      path: '/data/tasks-items.json',
+      value: { items: ['one', 2, 'two'] },
+    })
+    storageMock.writePlatformStorageJson.mockResolvedValue({
+      path: '/data/tasks-items.json',
+      ok: true,
+    })
+  })
+
+  afterEach(() => {
+    act(() => root.unmount())
+    host.remove()
+    vi.clearAllMocks()
+  })
+
+  it('loads and normalizes a JSON store file', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    expect(storageMock.readPlatformStorageJson).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+    })
+    expect(latest?.value).toEqual({ items: ['one', 'two'] })
+    expect(latest?.path).toBe('/data/tasks-items.json')
+  })
+
+  it('saves the complete next JSON store value', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      await latest?.saveValue({ items: ['next'] })
+    })
+
+    expect(storageMock.writePlatformStorageJson).toHaveBeenCalledWith({
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['next'] },
+    })
+    expect(latest?.value).toEqual({ items: ['next'] })
+  })
+
+  it('applies queued updates to the latest saved value', async () => {
+    act(() => {
+      root.render(<Probe />)
+    })
+    await flushEffects()
+
+    await act(async () => {
+      const first = latest?.updateValue(current => ({
+        items: [...current.items, 'three'],
+      }))
+      const second = latest?.updateValue(current => ({
+        items: [...current.items, 'four'],
+      }))
+      await Promise.all([first, second])
+    })
+
+    expect(storageMock.writePlatformStorageJson).toHaveBeenNthCalledWith(1, {
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['one', 'two', 'three'] },
+    })
+    expect(storageMock.writePlatformStorageJson).toHaveBeenNthCalledWith(2, {
+      appSlug: 'tasks',
+      fileName: 'tasks-items.json',
+      value: { items: ['one', 'two', 'three', 'four'] },
+    })
+    expect(latest?.value).toEqual({ items: ['one', 'two', 'three', 'four'] })
+  })
+})