@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/components/assets/asset-library/detail/AssetLibraryMetadataFields.tsx

@@ -0,0 +1,34 @@
+import { FormField } from '../../../common/inputs/FormField.js'
+import { TextAreaField } from '../../../common/inputs/TextAreaField.js'
+import { TextField } from '../../../common/inputs/TextField.js'
+import type { AssetLibraryMetadataModel } from '../types.js'
+import { StyledAssetLibraryFieldShell } from '../shared/fieldStyles.js'
+
+export interface AssetLibraryMetadataFieldsProps {
+  metadata: AssetLibraryMetadataModel
+}
+
+export function AssetLibraryMetadataFields({
+  metadata,
+}: AssetLibraryMetadataFieldsProps): React.ReactElement {
+  return (
+    <StyledAssetLibraryFieldShell>
+      <FormField label="Label">
+        <TextField
+          type="text"
+          value={metadata.labelDraft}
+          disabled={!metadata.canEdit}
+          onChange={event => metadata.setLabelDraft(event.target.value)}
+        />
+      </FormField>
+      <FormField label="Caption">
+        <TextAreaField
+          value={metadata.captionDraft}
+          disabled={!metadata.canEdit}
+          onChange={event => metadata.setCaptionDraft(event.target.value)}
+          rows={2}
+        />
+      </FormField>
+    </StyledAssetLibraryFieldShell>
+  )
+}

package/src/components/assets/asset-library/detail/AssetLibraryUsagePanel.tsx

@@ -0,0 +1,46 @@
+import {
+  StyledAssetLibrarySidePanel,
+  StyledAssetLibrarySidePanelEmpty,
+  StyledAssetLibrarySidePanelHeading,
+  StyledAssetLibraryUsageItem,
+  StyledAssetLibraryUsageList,
+  StyledAssetLibraryUsagePath,
+  StyledAssetLibraryUsageTitle,
+} from '../layout/assetLibraryLayout.js'
+import type { AssetLibraryUsageModel } from '../types.js'
+
+export interface AssetLibraryUsagePanelProps {
+  usage: AssetLibraryUsageModel
+}
+
+export function AssetLibraryUsagePanel({
+  usage,
+}: AssetLibraryUsagePanelProps): React.ReactElement {
+  return (
+    <StyledAssetLibrarySidePanel>
+      <StyledAssetLibrarySidePanelHeading>
+        Used in this {usage.collectionLabel}
+      </StyledAssetLibrarySidePanelHeading>
+      {usage.entries.length === 0 ? (
+        <StyledAssetLibrarySidePanelEmpty>
+          This asset has not been placed in the {usage.collectionLabel} yet.
+        </StyledAssetLibrarySidePanelEmpty>
+      ) : (
+        <StyledAssetLibraryUsageList>
+          {usage.entries.map(entry => (
+            <StyledAssetLibraryUsageItem
+              key={`${entry.documentPath}-${entry.title}`}
+            >
+              <StyledAssetLibraryUsageTitle>
+                {entry.title || entry.documentPath}
+              </StyledAssetLibraryUsageTitle>
+              <StyledAssetLibraryUsagePath>
+                {entry.documentPath}
+              </StyledAssetLibraryUsagePath>
+            </StyledAssetLibraryUsageItem>
+          ))}
+        </StyledAssetLibraryUsageList>
+      )}
+    </StyledAssetLibrarySidePanel>
+  )
+}

package/src/components/assets/asset-library/detail/AssetLibraryVersionsPanel.tsx

@@ -0,0 +1,145 @@
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+import { Button } from '../../../common/buttons/Button.js'
+import {
+  StyledAssetLibrarySidePanel,
+  StyledAssetLibrarySidePanelEmpty,
+  StyledAssetLibrarySidePanelHeading,
+  StyledAssetLibraryVersionActions,
+  StyledAssetLibraryVersionBadge,
+  StyledAssetLibraryVersionItem,
+  StyledAssetLibraryVersionLabel,
+  StyledAssetLibraryVersionList,
+  StyledAssetLibraryVersionMeta,
+  StyledAssetLibraryVersionPrompt,
+  StyledAssetLibraryVersionSub,
+  StyledAssetLibraryVersionTitle,
+} from '../layout/assetLibraryLayout.js'
+import type {
+  AssetLibraryActionsModel,
+  AssetLibraryVersionsModel,
+} from '../types.js'
+import { formatAssetTimeAgo } from '../utils/assetLibraryUtils.js'
+
+export interface AssetLibraryVersionsPanelProps {
+  versions: AssetLibraryVersionsModel
+  actions: AssetLibraryActionsModel
+}
+
+export function AssetLibraryVersionsPanel({
+  versions,
+  actions,
+}: AssetLibraryVersionsPanelProps): React.ReactElement {
+  const panelBusy = versions.busy || Boolean(actions.busy)
+
+  return (
+    <StyledAssetLibrarySidePanel>
+      <StyledAssetLibrarySidePanelHeading>
+        Versions
+      </StyledAssetLibrarySidePanelHeading>
+      {versions.versions.length <= 1 ? (
+        <StyledAssetLibrarySidePanelEmpty>
+          No alternate versions yet. New file versions appear here when you or
+          an agent create a variation of this asset.
+        </StyledAssetLibrarySidePanelEmpty>
+      ) : (
+        <StyledAssetLibraryVersionList>
+          {versions.versions.map(asset => (
+            <VersionRow
+              key={asset.relativePath}
+              asset={asset}
+              actions={actions}
+              versions={versions}
+              panelBusy={panelBusy}
+            />
+          ))}
+        </StyledAssetLibraryVersionList>
+      )}
+    </StyledAssetLibrarySidePanel>
+  )
+}
+
+interface VersionRowProps {
+  asset: PlatformAssetSummary
+  actions: AssetLibraryActionsModel
+  versions: AssetLibraryVersionsModel
+  panelBusy: boolean
+}
+
+function VersionRow({
+  asset,
+  actions,
+  versions,
+  panelBusy,
+}: VersionRowProps): React.ReactElement {
+  const isCurrent = asset.relativePath === versions.selectedRelativePath
+
+  return (
+    <StyledAssetLibraryVersionItem>
+      <StyledAssetLibraryVersionMeta>
+        <StyledAssetLibraryVersionTitle>
+          <StyledAssetLibraryVersionLabel>
+            {asset.label}
+          </StyledAssetLibraryVersionLabel>
+          <StyledAssetLibraryVersionSub>
+            v{asset.versionNumber} · {formatAssetTimeAgo(asset.modifiedAt)}
+          </StyledAssetLibraryVersionSub>
+        </StyledAssetLibraryVersionTitle>
+        {isCurrent ? (
+          <StyledAssetLibraryVersionBadge>
+            Current
+          </StyledAssetLibraryVersionBadge>
+        ) : null}
+      </StyledAssetLibraryVersionMeta>
+      {asset.transformationPrompt ? (
+        <StyledAssetLibraryVersionPrompt>
+          {asset.transformationPrompt}
+        </StyledAssetLibraryVersionPrompt>
+      ) : null}
+      <StyledAssetLibraryVersionActions>
+        <Button
+          type="button"
+          variant={isCurrent ? 'subtle' : 'ghost'}
+          size="sm"
+          disabled={panelBusy}
+          onClick={() => versions.previewVersion(asset.id)}
+        >
+          {isCurrent ? 'Viewing' : 'Preview'}
+        </Button>
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          disabled={!actions.canInsertAsset(asset) || panelBusy}
+          loading={actions.busy === 'inserting'}
+          onClick={() => void actions.insertAsset(asset)}
+        >
+          Insert
+        </Button>
+        {!isCurrent ? (
+          <>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              disabled={!versions.canSwapInDocument || panelBusy}
+              loading={versions.busy}
+              onClick={() => void versions.swapToVersion(asset, 'document')}
+            >
+              Use in {versions.insertTargetLabel}
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              disabled={panelBusy}
+              loading={versions.busy}
+              onClick={() => void versions.swapToVersion(asset, 'collection')}
+            >
+              Use in {versions.collectionLabel}
+            </Button>
+          </>
+        ) : null}
+      </StyledAssetLibraryVersionActions>
+    </StyledAssetLibraryVersionItem>
+  )
+}

package/src/components/assets/asset-library/helpers/assetKind.ts

@@ -0,0 +1,74 @@
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+
+export type InlineAssetKind = 'mermaid' | 'table' | 'math'
+
+export function inlineAssetKind(
+  asset: PlatformAssetSummary,
+): InlineAssetKind | null {
+  if (
+    asset.kind === 'mermaid' ||
+    asset.kind === 'table' ||
+    asset.kind === 'math'
+  ) {
+    return asset.kind
+  }
+  return null
+}
+
+export function canEditInlineSource(asset: PlatformAssetSummary): boolean {
+  return (
+    isInlineCollectionAsset(asset) &&
+    inlineAssetKind(asset) !== null &&
+    Boolean(asset.sourceNodeId?.trim())
+  )
+}
+
+export function canEditAssetMetadata(asset: PlatformAssetSummary): boolean {
+  return isFileCollectionAsset(asset) || canEditInlineSource(asset)
+}
+
+export function isInlineCollectionAsset(asset: PlatformAssetSummary): boolean {
+  return Boolean(asset.sourceType?.startsWith('inline-'))
+}
+
+export function isFileCollectionAsset(asset: PlatformAssetSummary): boolean {
+  return !isInlineCollectionAsset(asset)
+}
+
+export function canRevealCollectionAsset(asset: PlatformAssetSummary): boolean {
+  return isFileCollectionAsset(asset) && Boolean(asset.absolutePath?.trim())
+}
+
+export function canDeleteCollectionAsset(asset: PlatformAssetSummary): boolean {
+  return isFileCollectionAsset(asset)
+}
+
+const INSERTABLE_ASSET_KINDS = new Set<PlatformAssetSummary['kind']>([
+  'image',
+  'vector',
+  'mermaid',
+  'table',
+  'math',
+])
+
+export function isInsertableCollectionAsset(
+  asset: PlatformAssetSummary,
+): boolean {
+  return INSERTABLE_ASSET_KINDS.has(asset.kind)
+}
+
+/** @deprecated Use {@link canEditAssetMetadata} with file check */
+export function canEditFileMetadata(asset: PlatformAssetSummary): boolean {
+  return isFileCollectionAsset(asset)
+}
+
+export function defaultInlineSourcePlaceholder(kind: InlineAssetKind): string {
+  switch (kind) {
+    case 'mermaid':
+      return 'flowchart TD\n  A[Start] --> B[End]'
+    case 'math':
+      return '\\text{Empty equation}'
+    case 'table':
+      return '<table><tbody><tr><td></td></tr></tbody></table>'
+  }
+}

package/src/components/assets/asset-library/helpers.ts

@@ -0,0 +1,41 @@
+import type { PlatformAssetSummary } from '../../../bridge/types.js'
+
+export function messageForError(error: unknown): string {
+  return error instanceof Error ? error.message : 'Something went wrong.'
+}
+
+export function formatDocumentHint(input: {
+  currentDocumentFile?: string | null
+  currentDocumentTitle?: string | null
+}): string | null {
+  const { currentDocumentFile, currentDocumentTitle } = input
+  if (currentDocumentFile && currentDocumentTitle) {
+    return `${currentDocumentTitle} · ${currentDocumentFile}`
+  }
+  return currentDocumentFile ?? null
+}
+
+export function formatAssetUsageHint(
+  asset: PlatformAssetSummary,
+  insertTargetLabel: string,
+): string {
+  if (asset.usedIn.length === 0) return 'Not yet placed'
+  const count = asset.usedIn.length
+  return `Used in ${count} ${
+    count === 1 ? insertTargetLabel : `${insertTargetLabel}s`
+  }`
+}
+
+export {
+  canDeleteCollectionAsset,
+  canEditAssetMetadata,
+  canEditFileMetadata,
+  canEditInlineSource,
+  canRevealCollectionAsset,
+  defaultInlineSourcePlaceholder,
+  inlineAssetKind,
+  isFileCollectionAsset,
+  isInlineCollectionAsset,
+  isInsertableCollectionAsset,
+  type InlineAssetKind,
+} from './helpers/assetKind.js'

package/src/components/assets/asset-library/hooks/useAssetDetailDraft.ts

@@ -0,0 +1,81 @@
+import { useEffect, useMemo, useState } from 'react'
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+import {
+  canEditAssetMetadata,
+  canEditInlineSource,
+  inlineAssetKind,
+  type InlineAssetKind,
+} from '../helpers.js'
+
+export interface UseAssetDetailDraftResult {
+  labelDraft: string
+  captionDraft: string
+  sourceDraft: string
+  setLabelDraft: (value: string) => void
+  setCaptionDraft: (value: string) => void
+  setSourceDraft: (value: string) => void
+  metadataDirty: boolean
+  sourceDirty: boolean
+  isDirty: boolean
+  canEdit: boolean
+  showSourceEditor: boolean
+  inlineKind: InlineAssetKind | null
+}
+
+export function useAssetDetailDraft(
+  selectedAsset: PlatformAssetSummary | null,
+): UseAssetDetailDraftResult {
+  const [labelDraft, setLabelDraft] = useState('')
+  const [captionDraft, setCaptionDraft] = useState('')
+  const [sourceDraft, setSourceDraft] = useState('')
+
+  const inlineKind = selectedAsset ? inlineAssetKind(selectedAsset) : null
+  const showSourceEditor = selectedAsset
+    ? canEditInlineSource(selectedAsset)
+    : false
+
+  useEffect(() => {
+    if (!selectedAsset) {
+      setLabelDraft('')
+      setCaptionDraft('')
+      setSourceDraft('')
+      return
+    }
+    setLabelDraft(selectedAsset.label)
+    setCaptionDraft(selectedAsset.caption ?? '')
+    setSourceDraft(selectedAsset.sourceCode ?? '')
+  }, [
+    selectedAsset?.id,
+    selectedAsset?.caption,
+    selectedAsset?.label,
+    selectedAsset?.sourceCode,
+  ])
+
+  const metadataDirty = useMemo(() => {
+    if (!selectedAsset || !canEditAssetMetadata(selectedAsset)) return false
+    return (
+      labelDraft !== selectedAsset.label ||
+      captionDraft !== (selectedAsset.caption ?? '')
+    )
+  }, [captionDraft, labelDraft, selectedAsset])
+
+  const sourceDirty = useMemo(() => {
+    if (!selectedAsset || !showSourceEditor) return false
+    return sourceDraft !== (selectedAsset.sourceCode ?? '')
+  }, [selectedAsset, showSourceEditor, sourceDraft])
+
+  return {
+    labelDraft,
+    captionDraft,
+    sourceDraft,
+    setLabelDraft,
+    setCaptionDraft,
+    setSourceDraft,
+    metadataDirty,
+    sourceDirty,
+    isDirty: metadataDirty || sourceDirty,
+    canEdit: selectedAsset ? canEditAssetMetadata(selectedAsset) : false,
+    showSourceEditor,
+    inlineKind,
+  }
+}

package/src/components/assets/asset-library/hooks/useAssetLibraryDialog.ts

@@ -0,0 +1,233 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  listCollectionAssets,
+  listScopedCollectionAssets,
+} from '../../../../bridge/assets.mjs'
+import type { PlatformAssetSummary } from '../../../../bridge/types.js'
+import { messageForError } from '../helpers.js'
+import type {
+  AssetLibraryActionsModel,
+  CollectionAssetDocumentAdapter,
+  AssetLibraryListModel,
+  AssetLibraryMetadataModel,
+  AssetLibraryStatus,
+  AssetLibraryUsageModel,
+  AssetLibraryVersionsModel,
+} from '../types.js'
+import {
+  ASSET_SORT_OPTIONS,
+  filterCollectionAssets,
+  sectionCollectionAssets,
+  sortCollectionAssets,
+  type AssetLibraryFilter,
+  type AssetLibrarySortMode,
+} from '../utils/assetLibraryUtils.js'
+import { useAssetDetailDraft } from './useAssetDetailDraft.js'
+import { useAssetLibraryMutations } from './useAssetLibraryMutations.js'
+import { useAssetLibrarySelectionSync } from './useAssetLibrarySelectionSync.js'
+import { useAssetLibraryVersions } from './useAssetLibraryVersions.js'
+
+export interface UseAssetLibraryDialogOptions {
+  open: boolean
+  collectionPath: string
+  /** When set, list via `assets.listScoped` (app-supplied document paths). */
+  documentFiles?: string[]
+  currentDocumentFile?: string | null
+  inlineAssetScope?: 'all' | 'current-document'
+  collectionLabel?: string
+  insertTargetLabel?: string
+  uploadRelativeDir?: string
+  documentAdapter?: CollectionAssetDocumentAdapter
+  onDocumentSourceSaved?: (info: {
+    sourceDocumentPath?: string
+    relativePath: string
+  }) => void
+}
+
+export interface UseAssetLibraryDialogResult {
+  list: AssetLibraryListModel
+  metadata: AssetLibraryMetadataModel
+  actions: AssetLibraryActionsModel
+  usage: AssetLibraryUsageModel
+  versions: AssetLibraryVersionsModel
+}
+
+export function useAssetLibraryDialog({
+  open,
+  collectionPath,
+  documentFiles,
+  currentDocumentFile,
+  inlineAssetScope = 'all',
+  collectionLabel = 'collection',
+  insertTargetLabel = 'document',
+  uploadRelativeDir,
+  documentAdapter,
+  onDocumentSourceSaved,
+}: UseAssetLibraryDialogOptions): UseAssetLibraryDialogResult {
+  const insertAssetHandler = documentAdapter?.insertAsset
+  const [assets, setAssets] = useState<PlatformAssetSummary[]>([])
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [query, setQuery] = useState('')
+  const [filter, setFilter] = useState<AssetLibraryFilter>('all')
+  const [sortMode, setSortMode] = useState<AssetLibrarySortMode>('recent')
+  const [loading, setLoading] = useState(false)
+  const [status, setStatus] = useState<AssetLibraryStatus | null>(null)
+
+  const refreshAssets = useCallback(
+    async (preferredId?: string | null): Promise<void> => {
+      const nextAssets =
+        documentFiles && documentFiles.length > 0
+          ? await listScopedCollectionAssets({
+              collectionPath,
+              documentFiles,
+            })
+          : await listCollectionAssets(collectionPath)
+      setAssets(nextAssets)
+      setSelectedId(current => {
+        const preferred = preferredId ?? current
+        return preferred && nextAssets.some(asset => asset.id === preferred)
+          ? preferred
+          : nextAssets[0]?.id ?? null
+      })
+    },
+    [collectionPath, documentFiles],
+  )
+
+  useEffect(() => {
+    if (!open) {
+      setQuery('')
+      setFilter('all')
+      setStatus(null)
+      return
+    }
+    setSortMode(currentDocumentFile ? 'current-document' : 'recent')
+  }, [currentDocumentFile, open])
+
+  useEffect(() => {
+    if (!open) return
+    let cancelled = false
+    setLoading(true)
+    setStatus(null)
+
+    void refreshAssets()
+      .catch(error => {
+        if (!cancelled) {
+          setStatus({ tone: 'error', message: messageForError(error) })
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [open, refreshAssets])
+
+  const filteredAssets = useMemo(() => {
+    const matching = filterCollectionAssets(assets, {
+      query,
+      filter,
+      currentDocumentFile,
+      inlineAssetScope,
+    })
+    return sortCollectionAssets(matching, sortMode, currentDocumentFile)
+  }, [assets, currentDocumentFile, filter, inlineAssetScope, query, sortMode])
+
+  const selectedAsset = useMemo(
+    () =>
+      assets.find(asset => asset.id === selectedId) ??
+      filteredAssets[0] ??
+      null,
+    [assets, filteredAssets, selectedId],
+  )
+
+  const sectionedAssets = useMemo(
+    () =>
+      sectionCollectionAssets(filteredAssets, sortMode, currentDocumentFile),
+    [currentDocumentFile, filteredAssets, sortMode],
+  )
+
+  useEffect(() => {
+    if (!selectedAsset) return
+    if (filteredAssets.some(asset => asset.id === selectedAsset.id)) return
+    setSelectedId(filteredAssets[0]?.id ?? selectedAsset.id)
+  }, [filteredAssets, selectedAsset])
+
+  const sortOptions = useMemo(
+    () =>
+      currentDocumentFile
+        ? ASSET_SORT_OPTIONS
+        : ASSET_SORT_OPTIONS.filter(
+            option => option.value !== 'current-document',
+          ),
+    [currentDocumentFile],
+  )
+
+  useAssetLibrarySelectionSync(
+    open,
+    collectionPath,
+    selectedAsset?.relativePath,
+  )
+
+  const draft = useAssetDetailDraft(selectedAsset)
+
+  const actions = useAssetLibraryMutations({
+    collectionPath,
+    documentFiles,
+    collectionLabel,
+    insertTargetLabel,
+    uploadRelativeDir,
+    insertAssetHandler,
+    onDocumentSourceSaved,
+    selectedAsset,
+    draft,
+    refreshAssets,
+    setStatus,
+  })
+
+  const versions = useAssetLibraryVersions({
+    collectionPath,
+    documentFiles,
+    assets,
+    selectedAsset,
+    currentDocumentFile,
+    collectionLabel,
+    insertTargetLabel,
+    selectAsset: setSelectedId,
+    refreshAssets,
+    setStatus,
+  })
+
+  const usage = useMemo<AssetLibraryUsageModel>(
+    () => ({
+      entries: selectedAsset?.usedIn ?? [],
+      collectionLabel,
+      insertTargetLabel,
+    }),
+    [collectionLabel, insertTargetLabel, selectedAsset?.usedIn],
+  )
+
+  return {
+    list: {
+      assets,
+      filteredAssets,
+      sectionedAssets,
+      selectedAsset,
+      loading,
+      status,
+      query,
+      filter,
+      sortMode,
+      sortOptions,
+      setQuery,
+      setFilter,
+      setSortMode,
+      selectAsset: setSelectedId,
+    },
+    metadata: draft,
+    actions,
+    usage,
+    versions,
+  }
+}