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

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

@@ -0,0 +1,128 @@
+import type { PlatformAssetSummary } from '../../../bridge/types.js'
+import type {
+  AssetLibraryFilter,
+  AssetLibrarySection,
+  AssetLibrarySortMode,
+} from './utils/assetLibraryUtils.js'
+
+/** App-owned mapping from collection asset → document editor (TipTap / HTML). */
+export interface CollectionAssetDocumentAdapter {
+  insertAsset(asset: PlatformAssetSummary): Promise<void>
+}
+
+export interface AssetLibraryDialogProps {
+  open: boolean
+  onClose: () => void
+  /** Writer workspace or `.document` package root. */
+  collectionPath: string
+  /** App document adapter for library insert actions. */
+  documentAdapter?: CollectionAssetDocumentAdapter
+  /** Document path relative to `collectionPath` (e.g. `notes.doc.html`). */
+  currentDocumentFile?: string | null
+  /** App-supplied paths for `assets.listScoped` (e.g. book chapters). */
+  documentFiles?: string[]
+  currentDocumentTitle?: string | null
+  collectionLabel?: string
+  insertTargetLabel?: string
+  inlineAssetScope?: 'all' | 'current-document'
+  /** Relative path under `collectionPath` for uploads. Default `assets/figures`. */
+  uploadRelativeDir?: string
+  /** Called after inline source is saved to disk (mermaid/table/math). */
+  onDocumentSourceSaved?: (info: {
+    sourceDocumentPath?: string
+    relativePath: string
+  }) => void
+}
+
+export interface AssetLibraryWorkspaceProps
+  extends Omit<AssetLibraryDialogProps, 'onClose'> {
+  fill?: boolean
+}
+
+export type AssetLibraryStatusTone = 'error' | 'info' | 'success'
+
+export type AssetLibraryBusyAction =
+  | 'uploading'
+  | 'saving'
+  | 'deleting'
+  | 'inserting'
+  | 'swapping'
+  | null
+
+export interface AssetLibraryStatus {
+  tone: AssetLibraryStatusTone
+  message: string
+}
+
+export interface AssetLibraryListModel {
+  assets: PlatformAssetSummary[]
+  filteredAssets: PlatformAssetSummary[]
+  sectionedAssets: AssetLibrarySection[]
+  selectedAsset: PlatformAssetSummary | null
+  loading: boolean
+  status: AssetLibraryStatus | null
+  query: string
+  filter: AssetLibraryFilter
+  sortMode: AssetLibrarySortMode
+  sortOptions: readonly { value: AssetLibrarySortMode; label: string }[]
+  setQuery: (query: string) => void
+  setFilter: (filter: AssetLibraryFilter) => void
+  setSortMode: (sortMode: AssetLibrarySortMode) => void
+  selectAsset: (assetId: string) => void
+}
+
+import type { InlineAssetKind } from './helpers.js'
+
+export interface AssetLibraryMetadataModel {
+  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 interface AssetLibraryActionsModel {
+  busy: AssetLibraryBusyAction
+  uploadAsset: () => Promise<void>
+  saveMetadata: () => Promise<void>
+  deleteSelected: () => Promise<void>
+  revealSelected: () => Promise<void>
+  insertSelected: () => Promise<void>
+  insertAsset: (asset: PlatformAssetSummary) => Promise<void>
+  canSaveMetadata: boolean
+  canDeleteSelected: boolean
+  canRevealSelected: boolean
+  canInsertSelected: boolean
+  canInsertAsset: (asset: PlatformAssetSummary) => boolean
+  insertTargetLabel: string
+}
+
+export interface AssetLibraryVersionsModel {
+  visible: boolean
+  versions: PlatformAssetSummary[]
+  selectedRelativePath: string | null
+  previewVersion: (assetId: string) => void
+  swapToVersion: (
+    target: PlatformAssetSummary,
+    scope: 'document' | 'collection',
+  ) => Promise<void>
+  busy: boolean
+  canSwapInDocument: boolean
+  collectionLabel: string
+  insertTargetLabel: string
+}
+
+export interface AssetLibraryUsageModel {
+  entries: PlatformAssetSummary['usedIn']
+  collectionLabel: string
+  insertTargetLabel: string
+}
+
+export type { AssetLibraryFilter, AssetLibrarySortMode, AssetLibrarySection }

package/src/components/assets/asset-library/utils/assetLibraryUtils.ts

@@ -0,0 +1,181 @@
+import type {
+  PlatformAssetKind,
+  PlatformAssetSummary,
+} from '../../../../bridge/types.js'
+
+export type AssetLibraryFilter = 'all' | PlatformAssetKind
+
+export type AssetLibrarySortMode = 'recent' | 'current-document' | 'used'
+
+export interface AssetLibrarySection {
+  key: string
+  label: string
+  assets: PlatformAssetSummary[]
+}
+
+export function kindLabel(kind: PlatformAssetKind): string {
+  switch (kind) {
+    case 'image':
+      return 'Image'
+    case 'vector':
+      return 'SVG'
+    case 'mermaid':
+      return 'Mermaid'
+    case 'table':
+      return 'Table'
+    case 'math':
+      return 'Math'
+    default:
+      return 'File'
+  }
+}
+
+export function inlineKindShortLabel(kind: PlatformAssetKind): string {
+  if (kind === 'mermaid') return 'mmd'
+  if (kind === 'table') return 'tbl'
+  if (kind === 'math') return 'tex'
+  return 'file'
+}
+
+export function isFileThumbnailAsset(asset: PlatformAssetSummary): boolean {
+  return asset.kind === 'image' || asset.kind === 'vector'
+}
+
+export function formatAssetBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+export function formatAssetTimeAgo(value: string): string {
+  const diffMs = Date.now() - new Date(value).getTime()
+  const minutes = Math.max(1, Math.round(diffMs / 60_000))
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.round(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.round(hours / 24)
+  return `${days}d ago`
+}
+
+export function filterCollectionAssets(
+  assets: readonly PlatformAssetSummary[],
+  options: {
+    query: string
+    filter: AssetLibraryFilter
+    currentDocumentFile?: string | null
+    inlineAssetScope?: 'all' | 'current-document'
+  },
+): PlatformAssetSummary[] {
+  const normalizedQuery = options.query.trim().toLowerCase()
+
+  return assets.filter(asset => {
+    if (
+      options.inlineAssetScope === 'current-document' &&
+      options.currentDocumentFile &&
+      asset.sourceType?.startsWith('inline-') &&
+      !asset.usedIn.some(
+        usage => usage.documentPath === options.currentDocumentFile,
+      )
+    ) {
+      return false
+    }
+    if (options.filter !== 'all' && asset.kind !== options.filter) {
+      return false
+    }
+    if (!normalizedQuery) return true
+    return (
+      asset.label.toLowerCase().includes(normalizedQuery) ||
+      asset.fileName.toLowerCase().includes(normalizedQuery) ||
+      asset.relativePath.toLowerCase().includes(normalizedQuery) ||
+      (asset.caption ?? '').toLowerCase().includes(normalizedQuery) ||
+      (asset.sourceCode ?? '').toLowerCase().includes(normalizedQuery)
+    )
+  })
+}
+
+export function sortCollectionAssets(
+  assets: readonly PlatformAssetSummary[],
+  sortMode: AssetLibrarySortMode,
+  currentDocumentFile?: string | null,
+): PlatformAssetSummary[] {
+  return [...assets].sort((left, right) => {
+    if (sortMode === 'current-document' && currentDocumentFile) {
+      const leftCurrent = left.usedIn.some(
+        usage => usage.documentPath === currentDocumentFile,
+      )
+      const rightCurrent = right.usedIn.some(
+        usage => usage.documentPath === currentDocumentFile,
+      )
+      if (leftCurrent !== rightCurrent) return leftCurrent ? -1 : 1
+    }
+    if (sortMode === 'used' || sortMode === 'current-document') {
+      const leftUsed = left.usedIn.length > 0
+      const rightUsed = right.usedIn.length > 0
+      if (leftUsed !== rightUsed) return leftUsed ? -1 : 1
+    }
+    const modifiedDiff = right.modifiedAt.localeCompare(left.modifiedAt)
+    if (modifiedDiff !== 0) return modifiedDiff
+    return left.label.localeCompare(right.label)
+  })
+}
+
+export function sectionCollectionAssets(
+  assets: readonly PlatformAssetSummary[],
+  sortMode: AssetLibrarySortMode,
+  currentDocumentFile?: string | null,
+): AssetLibrarySection[] {
+  if (sortMode === 'current-document' && currentDocumentFile) {
+    const inCurrentDocument = assets.filter(asset =>
+      asset.usedIn.some(usage => usage.documentPath === currentDocumentFile),
+    )
+    const usedElsewhere = assets.filter(
+      asset =>
+        !asset.usedIn.some(
+          usage => usage.documentPath === currentDocumentFile,
+        ) && asset.usedIn.length > 0,
+    )
+    const notPlaced = assets.filter(asset => asset.usedIn.length === 0)
+    return [
+      { key: 'current', label: 'In this document', assets: inCurrentDocument },
+      {
+        key: 'elsewhere',
+        label: 'Used elsewhere',
+        assets: usedElsewhere,
+      },
+      { key: 'unplaced', label: 'Not yet placed', assets: notPlaced },
+    ].filter(section => section.assets.length > 0)
+  }
+
+  if (sortMode === 'used') {
+    const used = assets.filter(asset => asset.usedIn.length > 0)
+    const notPlaced = assets.filter(asset => asset.usedIn.length === 0)
+    return [
+      { key: 'used', label: 'Used in collection', assets: used },
+      { key: 'unplaced', label: 'Not yet placed', assets: notPlaced },
+    ].filter(section => section.assets.length > 0)
+  }
+
+  return [{ key: 'all', label: '', assets: [...assets] }]
+}
+
+export const ASSET_KIND_FILTERS: readonly {
+  value: AssetLibraryFilter
+  label: string
+}[] = [
+  { value: 'all', label: 'All' },
+  { value: 'image', label: 'Images' },
+  { value: 'vector', label: 'SVG' },
+  { value: 'mermaid', label: 'Mermaid' },
+  { value: 'table', label: 'Tables' },
+  { value: 'math', label: 'Math' },
+  { value: 'other', label: 'Other' },
+]
+
+export const ASSET_SORT_OPTIONS: readonly {
+  value: AssetLibrarySortMode
+  label: string
+}[] = [
+  { value: 'recent', label: 'Recent' },
+  { value: 'current-document', label: 'This document' },
+  { value: 'used', label: 'Used' },
+]

package/src/components/assets/asset-library/utils/pathBasename.ts

@@ -0,0 +1,5 @@
+/** Basename without pulling in node:path in the UI bundle. */
+export function basename(filePath: string): string {
+  const normalized = filePath.replace(/\\/g, '/')
+  return normalized.split('/').filter(Boolean).pop() ?? filePath
+}

package/src/components/assets/asset-library/utils/sanitizeUploadFileName.ts

@@ -0,0 +1,7 @@
+export function sanitizeUploadFileName(name: string): string {
+  const trimmed = name.trim() || 'uploaded-image.png'
+  const normalized = trimmed
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+  return normalized.replace(/^-+|-+$/g, '') || 'uploaded-image.png'
+}

package/src/components/assets/asset-library/utils/uploadCollectionAsset.ts

@@ -0,0 +1,52 @@
+import { basename } from './pathBasename.js'
+import { DEFAULT_COLLECTION_FIGURES_DIR } from '../../../../bridge/collectionAssets.mjs'
+import {
+  createPlatformFolder,
+  readPlatformFileBinary,
+  writePlatformFileBinary,
+} from '../../../../bridge/fs.mjs'
+import { openPlatformImageDialog } from '../../../../bridge/dialog.mjs'
+import { sanitizeUploadFileName } from './sanitizeUploadFileName.js'
+
+/** @deprecated Use `DEFAULT_COLLECTION_FIGURES_DIR` from `@purescience/platform-ui/bridge/collectionAssets`. */
+export const DEFAULT_UPLOAD_RELATIVE_DIR = DEFAULT_COLLECTION_FIGURES_DIR
+
+export async function ensureCollectionSubdirs(
+  collectionPath: string,
+  relativeDir: string,
+): Promise<void> {
+  const root = collectionPath.replace(/\/+$/, '')
+  const parts = relativeDir.split('/').filter(Boolean)
+  let parent = root
+  for (const part of parts) {
+    try {
+      const created = await createPlatformFolder(parent, part)
+      parent = created.path
+    } catch {
+      parent = `${parent}/${part}`
+    }
+  }
+}
+
+export async function uploadCollectionAssetFromDialog(input: {
+  collectionPath: string
+  uploadRelativeDir?: string
+}): Promise<string | null> {
+  const picked = await openPlatformImageDialog()
+  if (!picked) return null
+
+  const uploadRelativeDir =
+    input.uploadRelativeDir ?? DEFAULT_COLLECTION_FIGURES_DIR
+  const binary = await readPlatformFileBinary(picked)
+  const fileName = sanitizeUploadFileName(basename(picked))
+  const relativePath = `${uploadRelativeDir.replace(/\/+$/, '')}/${fileName}`
+  const absolutePath = `${input.collectionPath.replace(
+    /\/+$/,
+    '',
+  )}/${relativePath}`
+
+  await ensureCollectionSubdirs(input.collectionPath, uploadRelativeDir)
+  await writePlatformFileBinary(absolutePath, binary.base64)
+
+  return relativePath
+}

package/src/components/chrome/OverlayActionCapsule.test.tsx

@@ -0,0 +1,82 @@
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { styled } from 'styled-components'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { PlatformIcon } from './PlatformIcon.js'
+import { X } from 'lucide-react'
+import {
+  OverlayActionCapsule,
+  OverlayActionCapsuleButton,
+  OverlayActionCapsuleCloseButton,
+} from './OverlayActionCapsule.js'
+import { ShellWindowControls } from './ShellWindowControls.js'
+
+const StyledCapsuleHost = styled.div`
+  display: flex;
+  align-items: stretch;
+  height: 38px;
+`
+
+const StyledTitlebarHost = styled.div`
+  display: flex;
+  align-items: stretch;
+  height: 30px;
+`
+
+function render(ui: React.ReactElement): {
+  container: HTMLDivElement
+  root: Root
+} {
+  const container = document.createElement('div')
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  act(() => {
+    root.render(ui)
+  })
+  return { container, root }
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('OverlayActionCapsule', () => {
+  it('renders custom actions and close control in one capsule', () => {
+    const onClose = vi.fn()
+    const { container } = render(
+      <StyledCapsuleHost>
+        <OverlayActionCapsule>
+          <OverlayActionCapsuleButton>Link</OverlayActionCapsuleButton>
+          <OverlayActionCapsuleCloseButton aria-label="Close" onClick={onClose}>
+            <PlatformIcon icon={X} size={14} strokeWidth={2} />
+          </OverlayActionCapsuleCloseButton>
+        </OverlayActionCapsule>
+      </StyledCapsuleHost>,
+    )
+
+    expect(container.querySelector('button')?.textContent).toContain('Link')
+    container
+      .querySelector('[aria-label="Close"]')
+      ?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    expect(onClose).toHaveBeenCalledOnce()
+  })
+})
+
+describe('ShellWindowControls', () => {
+  it('exposes minimize, maximize, and close inside a capsule', () => {
+    const { container } = render(
+      <StyledTitlebarHost>
+        <ShellWindowControls
+          onMinimize={() => undefined}
+          onMaximize={() => undefined}
+          onClose={() => undefined}
+        />
+      </StyledTitlebarHost>,
+    )
+
+    expect(container.querySelectorAll('button')).toHaveLength(3)
+    expect(container.querySelector('[aria-label="Minimize"]')).not.toBeNull()
+    expect(container.querySelector('[aria-label="Maximize"]')).not.toBeNull()
+    expect(container.querySelector('[aria-label="Close"]')).not.toBeNull()
+  })
+})

package/src/components/chrome/OverlayActionCapsule.tsx

@@ -0,0 +1,90 @@
+import type { ComponentPropsWithoutRef } from 'react'
+import { styled } from 'styled-components'
+import { CleanButton } from '../common/buttons/CleanButton.js'
+
+export type OverlayActionCapsuleProps = ComponentPropsWithoutRef<'div'>
+export type OverlayActionCapsuleButtonProps = ComponentPropsWithoutRef<
+  typeof StyledOverlayActionCapsuleButton
+>
+export type OverlayActionCapsuleIconButtonProps = ComponentPropsWithoutRef<
+  typeof StyledOverlayActionCapsuleIconButton
+>
+export type OverlayActionCapsuleCloseButtonProps = ComponentPropsWithoutRef<
+  typeof StyledOverlayActionCapsuleCloseButton
+>
+
+const capsuleButtonBase = styled(CleanButton)`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375em;
+  height: 100%;
+  min-height: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--platform-colors-text-secondary);
+  font: inherit;
+  font-size: inherit;
+  line-height: 1;
+  cursor: pointer;
+  transition: background var(--platform-transition-fast),
+    color var(--platform-transition-fast);
+
+  &:hover:not(:disabled) {
+    background: var(--platform-colors-elevated);
+    color: var(--platform-colors-text);
+  }
+
+  &:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+`
+
+export const StyledOverlayActionCapsule = styled.div`
+  display: inline-flex;
+  align-items: stretch;
+  height: 100%;
+  box-sizing: border-box;
+  gap: 0.1875em;
+  padding: 0.1875em;
+  border: 1px solid var(--platform-colors-border);
+  border-radius: 999px;
+  background: var(--platform-colors-surface);
+  box-shadow: var(--platform-shadow-sm);
+  width: fit-content;
+  font-size: var(--platform-typography-font-size-sm);
+  line-height: 1;
+`
+
+export const StyledOverlayActionCapsuleButton = styled(capsuleButtonBase)`
+  min-width: 2.125em;
+  padding: 0 0.625em;
+`
+
+export const StyledOverlayActionCapsuleIconButton = styled(capsuleButtonBase)`
+  aspect-ratio: 1;
+  width: auto;
+  min-width: 0;
+  padding: 0;
+`
+
+export const StyledOverlayActionCapsuleCloseButton = styled(
+  StyledOverlayActionCapsuleIconButton,
+)`
+  background: var(--platform-colors-accent-hover);
+  color: var(--platform-colors-text-inverse);
+
+  &:hover:not(:disabled) {
+    background: var(--platform-colors-danger);
+    color: var(--platform-colors-text-inverse);
+  }
+`
+
+export const OverlayActionCapsule = StyledOverlayActionCapsule
+export const OverlayActionCapsuleButton = StyledOverlayActionCapsuleButton
+export const OverlayActionCapsuleIconButton =
+  StyledOverlayActionCapsuleIconButton
+export const OverlayActionCapsuleCloseButton =
+  StyledOverlayActionCapsuleCloseButton

package/src/components/chrome/PanelTabStrip.tsx

@@ -0,0 +1,113 @@
+import { styled } from 'styled-components'
+
+export interface PanelTabItem<T extends string = string> {
+  id: T
+  label: React.ReactNode
+}
+
+export interface PanelTabStripProps<T extends string = string> {
+  items: readonly PanelTabItem<T>[]
+  activeId: T
+  onSelect: (id: T) => void
+  className?: string
+  'data-mode-count'?: number | string
+  'aria-label'?: string
+}
+
+const StyledStrip = styled.nav`
+  display: flex;
+  align-items: flex-end;
+  min-width: 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+`
+
+const StyledTab = styled.button`
+  position: relative;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 112px;
+  max-width: 240px;
+  height: 31px;
+  margin-bottom: -1px;
+  padding: 0 12px;
+  border: 1px solid transparent;
+  border-bottom-color: transparent;
+  border-radius: 11px 11px 0 0;
+  background: transparent;
+  color: var(--platform-colors-text-secondary);
+  font: inherit;
+  font-size: var(--platform-typography-font-size-xs, 13px);
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+  cursor: pointer;
+
+  &[aria-selected='true'] {
+    border-color: var(--platform-colors-border);
+    border-bottom-color: var(
+      --platform-panel-tab-surface,
+      var(--platform-colors-surface)
+    );
+    background: var(
+      --platform-panel-tab-surface,
+      var(--platform-colors-surface)
+    );
+    color: var(--platform-colors-text);
+    font-weight: 600;
+    box-shadow: 0 -1px 0 rgb(255 255 255 / 70%);
+  }
+
+  &:hover:not([aria-selected='true']) {
+    border-color: var(--platform-colors-border-soft);
+    background: var(--platform-colors-surface-hover);
+    color: var(--platform-colors-text);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--platform-colors-focus-ring);
+    outline-offset: 2px;
+  }
+`
+
+/** Compact local tab strip using the same visual scale as workspace tabs. */
+export function PanelTabStrip<T extends string = string>({
+  items,
+  activeId,
+  onSelect,
+  className,
+  'data-mode-count': dataModeCount,
+  'aria-label': ariaLabel,
+}: PanelTabStripProps<T>): React.ReactElement {
+  return (
+    <StyledStrip
+      className={className}
+      role="tablist"
+      aria-label={ariaLabel}
+      data-mode-count={dataModeCount}
+    >
+      {items.map(item => {
+        const active = item.id === activeId
+        return (
+          <StyledTab
+            key={item.id}
+            type="button"
+            role="tab"
+            tabIndex={active ? 0 : -1}
+            aria-selected={active}
+            onClick={() => onSelect(item.id)}
+          >
+            {item.label}
+          </StyledTab>
+        )
+      })}
+    </StyledStrip>
+  )
+}

package/src/components/chrome/PlatformIcon.tsx

@@ -0,0 +1,27 @@
+import type { LucideIcon } from 'lucide-react'
+
+export interface PlatformIconProps {
+  icon: LucideIcon
+  /** Pixel size (width and height). */
+  size?: number
+  strokeWidth?: number
+  className?: string
+}
+
+/** Lucide wrapper — uses `currentColor` from parent. */
+export function PlatformIcon({
+  icon: Icon,
+  size = 16,
+  strokeWidth = 1.75,
+  className,
+}: PlatformIconProps): React.ReactElement {
+  return (
+    <Icon
+      size={size}
+      strokeWidth={strokeWidth}
+      className={className}
+      aria-hidden
+      focusable={false}
+    />
+  )
+}