@dsh-plus/image-studio 0.1.0 → 0.1.2

package/src/client/panel/panel.tsx

@@ -0,0 +1,219 @@
+/**
+ * 图像工作室面板根组件：侧栏 footer 入口打开的 overlay 工作台。
+ * 三个标签（文生图/图生图/画廊）+ 底部任务条；两个生图表单常驻挂载
+ * （hidden 切换，保留各自表单态）。数据归口：providers 一次性加载，
+ * presets/gallery/tasks 面板打开时加载，任务 2s 轮询并侦测成功转移
+ * 自动刷画廊。
+ * 响应式：桌面居中模态（≤1100px），≤767px 全屏抽屉（见 styles.ts）。
+ * @module image-studio/client/panel/panel
+ */
+import { Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { NamespaceSettingsApi, Scope } from '@dsh-plus/shared/client'
+import { IconBrush, IconCloseOutline16, IconImage, IconSparkles } from '@dsh-plus/shared/client'
+import {
+  type ReactElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import type { PresetsWire, ProvidersWire, TaskWire } from '../../dto.ts'
+import type { GalleryItem } from '../../gallery/store.ts'
+import type { ParamEntry } from '../../params/catalog.ts'
+import { cancelTask, fetchGallery, fetchPresets, fetchProviders, fetchTasks } from '../api.ts'
+import type { Translate } from '../i18n.ts'
+import type { PanelController, StudioTab } from './controller.ts'
+import { GalleryView } from './gallery.tsx'
+import { GeneratorForm } from './generator.tsx'
+import { TasksBar } from './tasks.tsx'
+
+interface StudioPanelProps {
+  studio: PanelController
+  t: Translate
+  scope: Scope
+  api: NamespaceSettingsApi
+}
+
+const EMPTY_PRESETS: PresetsWire = { promptPresets: [], paramPresets: [], providerPresets: [] }
+
+export function StudioPanel(props: StudioPanelProps): ReactElement | null {
+  const { studio, t, scope, api } = props
+  const { open, tab, editSeed } = useSyncExternalStore(studio.subscribe, studio.getSnapshot)
+  const [providers, setProviders] = useState<ProvidersWire | null>(null)
+  const [presets, setPresets] = useState<PresetsWire>(EMPTY_PRESETS)
+  const [gallery, setGallery] = useState<GalleryItem[]>([])
+  const [galleryLoading, setGalleryLoading] = useState(false)
+  const [galleryFailed, setGalleryFailed] = useState(false)
+  const [tasks, setTasks] = useState<TaskWire[]>([])
+  const [detailId, setDetailId] = useState<string | null>(null)
+  /** 上一轮任务快照（成功转移侦测）。 */
+  const prevTasksRef = useRef<Map<string, TaskWire['state']>>(new Map())
+
+  const reloadGallery = useCallback((): void => {
+    setGalleryLoading(true)
+    fetchGallery()
+      .then((res) => {
+        setGallery(res.items)
+        setGalleryFailed(false)
+      })
+      .catch(() => setGalleryFailed(true))
+      .finally(() => setGalleryLoading(false))
+  }, [])
+
+  const reloadPresets = useCallback((): void => {
+    fetchPresets()
+      .then(setPresets)
+      .catch(() => {})
+  }, [])
+
+  const reloadTasks = useCallback((): void => {
+    fetchTasks()
+      .then((res) => setTasks(res.tasks))
+      .catch(() => {})
+  }, [])
+
+  // 打开时加载静态目录 + 三类数据；关闭时停止轮询（effect 清理）。
+  useEffect(() => {
+    if (!open) return
+    if (providers === null) {
+      fetchProviders()
+        .then(setProviders)
+        .catch(() => {})
+    }
+    reloadPresets()
+    reloadGallery()
+    reloadTasks()
+    const timer = setInterval(() => {
+      fetchTasks()
+        .then((res) => {
+          setTasks(res.tasks)
+          // 侦测新成功任务 → 刷画廊（含其它客户端/来源产生的成功）。
+          const prev = prevTasksRef.current
+          const next = new Map<string, TaskWire['state']>()
+          let succeeded = false
+          for (const task of res.tasks) {
+            next.set(task.id, task.state)
+            if (task.state === 'succeeded' && prev.get(task.id) !== 'succeeded') succeeded = true
+          }
+          prevTasksRef.current = next
+          if (succeeded) reloadGallery()
+        })
+        .catch(() => {})
+    }, 2000)
+    return () => clearInterval(timer)
+  }, [open, providers, reloadPresets, reloadGallery, reloadTasks])
+
+  // wire 的 params 与 ParamEntry 结构同源（kind 宽化为 string），边界处一次性窄化。
+  const catalog = (providers?.params ?? []) as unknown as readonly ParamEntry[]
+  const protocols = providers?.protocols ?? []
+
+  const tabs: Array<{ key: StudioTab; label: string; icon: ReactElement }> = [
+    { key: 'generation', label: t('tab.generation'), icon: <IconSparkles size={15} /> },
+    { key: 'edit', label: t('tab.edit'), icon: <IconBrush size={15} /> },
+    { key: 'gallery', label: t('tab.gallery'), icon: <IconImage size={15} /> },
+  ]
+
+  // 官方 Modal 承载：portal 到 body（z-index 1000，移动端层叠/开关与外壳一致），
+  // 遮罩点击与 Escape 关闭由 Modal 处理；headless 模式自绘头部标签条。
+  return (
+    <Modal
+      open={open}
+      onClose={() => studio.setOpen(false)}
+      title={t('panel.title')}
+      headless
+      className="ims-modal"
+    >
+      <div className="ims-panel">
+        <header className="ims-head">
+          <div className="ims-tabs" role="tablist" aria-label={t('panel.title')}>
+            {tabs.map((item) => (
+              <button
+                key={item.key}
+                type="button"
+                role="tab"
+                aria-selected={tab === item.key}
+                className={`ims-tab${tab === item.key ? ' ims-tabActive' : ''}`}
+                onClick={() => studio.setTab(item.key)}
+              >
+                {item.icon}
+                <span>{item.label}</span>
+              </button>
+            ))}
+          </div>
+          <button
+            type="button"
+            className="ims-iconBtn"
+            aria-label={t('common.close')}
+            onClick={() => studio.setOpen(false)}
+          >
+            <IconCloseOutline16 size={16} />
+          </button>
+        </header>
+
+        <div className="ims-body">
+          <GeneratorForm
+            t={t}
+            endpoint="generation"
+            catalog={catalog}
+            protocols={protocols}
+            presets={presets}
+            gallery={gallery}
+            scope={scope}
+            api={api}
+            editSeed={null}
+            onPresetSaved={reloadPresets}
+            onSubmitted={reloadTasks}
+            hidden={tab !== 'generation'}
+          />
+          <GeneratorForm
+            t={t}
+            endpoint="edit"
+            catalog={catalog}
+            protocols={protocols}
+            presets={presets}
+            gallery={gallery}
+            scope={scope}
+            api={api}
+            editSeed={editSeed}
+            onPresetSaved={reloadPresets}
+            onSubmitted={reloadTasks}
+            hidden={tab !== 'edit'}
+          />
+          <GalleryView
+            t={t}
+            items={gallery}
+            loading={galleryLoading}
+            failed={galleryFailed}
+            onRefresh={reloadGallery}
+            onEdit={(item) =>
+              studio.seedEdit({
+                sourceIds: [...item.imageIds],
+                prompt: item.prompt,
+                params: item.params,
+                providerPresetId: item.providerPresetId,
+              })
+            }
+            detailId={detailId}
+            onDetailChange={setDetailId}
+            hidden={tab !== 'gallery'}
+          />
+        </div>
+
+        <TasksBar
+          t={t}
+          tasks={tasks}
+          onCancel={(taskId) => {
+            cancelTask(taskId)
+              .then(reloadTasks)
+              .catch(() => {})
+          }}
+          onView={(galleryItemId) => {
+            studio.setTab('gallery')
+            setDetailId(galleryItemId)
+          }}
+        />
+      </div>
+    </Modal>
+  )
+}

package/src/client/panel/param-state.ts

@@ -0,0 +1,144 @@
+/**
+ * 参数表单状态纯函数：目录（ParamEntry）驱动的表单状态 ⇄ ParamSpecMap。
+ * - 表单值统一字符串/布尔（输入控件友好），提交时按 kind 解析回数值；
+ * - 画廊条目 params 回放、参数预设应用、预设另存均经此模块换算；
+ * - 纯函数零 DOM 依赖，可 node 单测。
+ * @module image-studio/client/panel/param-state
+ */
+import { isHostParam, type ParamEntry } from '../../params/catalog.ts'
+import type { ParamSpecMap } from '../../params/spec.ts'
+import type { ImageEndpoint } from '../../provider/types.ts'
+
+/** 表单字段值（integer/enum/string 用字符串承载，boolean 用布尔）。 */
+export type ParamFieldValue = string | boolean
+
+/** 单参数表单态。 */
+export interface ParamFieldState {
+  enabled: boolean
+  value: ParamFieldValue
+}
+
+/** 参数表单态（key → 字段态）。 */
+export type ParamFormState = Record<string, ParamFieldState>
+
+/** 各参数的顺手默认值（启用控件时的预填，非官方默认）。 */
+const DEFAULT_VALUES: Record<string, ParamFieldValue> = {
+  n: '1',
+  size: '1024x1024',
+  quality: 'auto',
+  background: 'auto',
+  output_format: 'png',
+  output_compression: '100',
+  moderation: 'auto',
+  response_format: 'url',
+  stream: false,
+  partial_images: '0',
+  user: '',
+  input_fidelity: 'high',
+  style: 'vivid',
+}
+
+/** 目录条目 → 表单默认值（enum 取首值兜底）。 */
+export function defaultValueFor(entry: ParamEntry): ParamFieldValue {
+  const known = DEFAULT_VALUES[entry.key]
+  if (known !== undefined) return known
+  if (entry.kind === 'enum') return entry.values?.[0] ?? ''
+  if (entry.kind === 'boolean') return false
+  return ''
+}
+
+/** 端点可用的目录条目（剔除 host 承载参数 model）。 */
+export function paramEntriesFor(
+  catalog: readonly ParamEntry[],
+  endpoint: ImageEndpoint,
+): ParamEntry[] {
+  return catalog.filter((entry) => entry.applies.includes(endpoint) && !isHostParam(entry.key))
+}
+
+/** 空表单（全部关闭 + 默认值）。 */
+export function emptyParamForm(
+  catalog: readonly ParamEntry[],
+  endpoint: ImageEndpoint,
+): ParamFormState {
+  const form: ParamFormState = {}
+  for (const entry of paramEntriesFor(catalog, endpoint)) {
+    form[entry.key] = { enabled: false, value: defaultValueFor(entry) }
+  }
+  return form
+}
+
+/** 表单值 ← 服务端参数值（按 kind 字符串化；未知键忽略）。 */
+function fieldValueOf(entry: ParamEntry, value: unknown): ParamFieldValue {
+  if (entry.kind === 'boolean') return value === true
+  if (typeof value === 'number') return String(value)
+  if (typeof value === 'string') return value
+  return defaultValueFor(entry)
+}
+
+/** 套用参数表（预设应用/画廊回放共用）：仅目录内且端点适用的键生效并启用。 */
+export function applyParams(
+  catalog: readonly ParamEntry[],
+  endpoint: ImageEndpoint,
+  params: Record<string, unknown>,
+): ParamFormState {
+  const form = emptyParamForm(catalog, endpoint)
+  for (const entry of paramEntriesFor(catalog, endpoint)) {
+    const value = params[entry.key]
+    if (value === undefined) continue
+    form[entry.key] = { enabled: true, value: fieldValueOf(entry, value) }
+  }
+  return form
+}
+
+/** 参数预设（ParamSpecMap 形态）套用到表单：enabled=false 的键显式关闭。 */
+export function applySpecs(
+  catalog: readonly ParamEntry[],
+  endpoint: ImageEndpoint,
+  specs: ParamSpecMap,
+): ParamFormState {
+  const form = emptyParamForm(catalog, endpoint)
+  for (const entry of paramEntriesFor(catalog, endpoint)) {
+    const spec = specs[entry.key]
+    if (spec === undefined) continue
+    form[entry.key] = {
+      enabled: spec.enabled,
+      value:
+        spec.enabled && spec.value !== undefined
+          ? fieldValueOf(entry, spec.value)
+          : defaultValueFor(entry),
+    }
+  }
+  return form
+}
+
+/**
+ * 表单 → ParamSpecMap（提交/另存预设共用）：仅导出启用项，integer 按数值解析；
+ * 空字符串 integer 视为未填（导出 {enabled:true} 无 value，交由边界校验报错）。
+ */
+export function formToSpecs(
+  catalog: readonly ParamEntry[],
+  endpoint: ImageEndpoint,
+  form: ParamFormState,
+): ParamSpecMap {
+  const specs: ParamSpecMap = {}
+  for (const entry of paramEntriesFor(catalog, endpoint)) {
+    const field = form[entry.key]
+    if (field === undefined || !field.enabled) continue
+    if (entry.kind === 'boolean') {
+      specs[entry.key] = { enabled: true, value: field.value === true }
+      continue
+    }
+    const text = String(field.value).trim()
+    if (entry.kind === 'integer') {
+      if (text === '') {
+        specs[entry.key] = { enabled: true }
+        continue
+      }
+      const parsed = Number(text)
+      specs[entry.key] = { enabled: true, value: Number.isNaN(parsed) ? text : parsed }
+      continue
+    }
+    specs[entry.key] = { enabled: true, value: text }
+  }
+  return specs
+}

package/src/client/panel/params-form.tsx

@@ -0,0 +1,136 @@
+/**
+ * 参数表单：按参数目录动态渲染（kind → 控件形态，advanced 折叠）。
+ * - boolean 参数的开关即取值（启用 = true）；
+ * - 其余参数：开关 + 值控件（enum 下拉 / integer 数字框 / string 文本框）；
+ * - 每项附中文说明与代际标记（GPT Image / dall-e-3 / dall-e-2）。
+ * @module image-studio/client/panel/params-form
+ */
+import type { ReactElement } from 'react'
+import type { ParamEntry } from '../../params/catalog.ts'
+import type { ImageEndpoint } from '../../provider/types.ts'
+import type { Translate } from '../i18n.ts'
+import { type ParamFormState, paramEntriesFor } from './param-state.ts'
+
+interface ParamsFormProps {
+  t: Translate
+  catalog: readonly ParamEntry[]
+  endpoint: ImageEndpoint
+  form: ParamFormState
+  onChange(next: ParamFormState): void
+}
+
+/** 单参数行：开关 + 名称/说明 + 值控件。 */
+function ParamRow(props: {
+  t: Translate
+  entry: ParamEntry
+  form: ParamFormState
+  onChange(next: ParamFormState): void
+}): ReactElement {
+  const { t, entry, form, onChange } = props
+  const field = form[entry.key] ?? { enabled: false, value: '' }
+  const patch = (next: Partial<typeof field>): void =>
+    onChange({ ...form, [entry.key]: { ...field, ...next } })
+
+  const control = (() => {
+    if (entry.kind === 'boolean') return null
+    if (entry.kind === 'enum') {
+      return (
+        <select
+          className="ims-input ims-paramControl"
+          value={String(field.value)}
+          disabled={!field.enabled}
+          onChange={(event) => patch({ value: event.target.value })}
+        >
+          {(entry.values ?? []).map((value) => (
+            <option key={value} value={value}>
+              {value}
+            </option>
+          ))}
+        </select>
+      )
+    }
+    if (entry.kind === 'integer') {
+      return (
+        <input
+          className="ims-input ims-paramControl"
+          type="number"
+          inputMode="numeric"
+          min={entry.min}
+          max={entry.max}
+          value={String(field.value)}
+          disabled={!field.enabled}
+          onChange={(event) => patch({ value: event.target.value })}
+        />
+      )
+    }
+    return (
+      <input
+        className="ims-input ims-paramControl"
+        type="text"
+        value={String(field.value)}
+        disabled={!field.enabled}
+        onChange={(event) => patch({ value: event.target.value })}
+      />
+    )
+  })()
+
+  return (
+    <div className={`ims-paramRow${field.enabled ? ' ims-paramRowOn' : ''}`}>
+      <label className="ims-switch" title={t('params.enabled')}>
+        <input
+          type="checkbox"
+          role="switch"
+          aria-label={`${entry.key} ${t('params.enabled')}`}
+          aria-checked={field.enabled}
+          checked={field.enabled}
+          onChange={(event) =>
+            entry.kind === 'boolean'
+              ? patch({ enabled: event.target.checked, value: event.target.checked })
+              : patch({ enabled: event.target.checked })
+          }
+        />
+        <span className="ims-switchTrack" aria-hidden="true" />
+      </label>
+      <div className="ims-paramText">
+        <span className="ims-paramKey">
+          {entry.key}
+          {entry.generation !== 'current' ? (
+            <span className="ims-paramGen">{entry.generation}</span>
+          ) : null}
+        </span>
+        <span className="ims-paramDesc">{entry.description}</span>
+      </div>
+      {control}
+    </div>
+  )
+}
+
+export function ParamsForm(props: ParamsFormProps): ReactElement {
+  const { t, catalog, endpoint, form, onChange } = props
+  const entries = paramEntriesFor(catalog, endpoint)
+  const basics = entries.filter((entry) => !entry.advanced)
+  const advanced = entries.filter((entry) => entry.advanced)
+  const advancedOn = advanced.filter((entry) => form[entry.key]?.enabled === true).length
+  return (
+    <div className="ims-params">
+      <div className="ims-paramGroup">
+        {basics.map((entry) => (
+          <ParamRow key={entry.key} t={t} entry={entry} form={form} onChange={onChange} />
+        ))}
+      </div>
+      {advanced.length > 0 ? (
+        <details className="ims-adv">
+          <summary className="ims-advSummary">
+            {t('params.advanced')}
+            {advancedOn > 0 ? <span className="ims-advCount">{advancedOn}</span> : null}
+          </summary>
+          <div className="ims-paramGroup">
+            {advanced.map((entry) => (
+              <ParamRow key={entry.key} t={t} entry={entry} form={form} onChange={onChange} />
+            ))}
+          </div>
+        </details>
+      ) : null}
+    </div>
+  )
+}

package/src/client/panel/picker.tsx

@@ -0,0 +1,111 @@
+/**
+ * 画廊图片选择器（模态）：源图多选（≤16）与遮罩单选共用。
+ * 扁平化全部画廊条目的图片，倒序排列；底部确认条显示已选数量。
+ * @module image-studio/client/panel/picker
+ */
+import { Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import { type ReactElement, useState } from 'react'
+import type { GalleryItem } from '../../gallery/store.ts'
+import { imageUrl } from '../api.ts'
+import type { Translate } from '../i18n.ts'
+
+/** 扁平化的可选图片（imageId + 归属条目提示词）。 */
+interface PickableImage {
+  imageId: string
+  prompt: string
+  createdAt: string
+}
+
+interface ImagePickerProps {
+  t: Translate
+  title: string
+  items: GalleryItem[]
+  /** 多选（源图）或单选（遮罩）。 */
+  multiple: boolean
+  /** 初始已选（源图回填）。 */
+  initial: string[]
+  onConfirm(ids: string[]): void
+  onClose(): void
+}
+
+export function flattenImages(items: GalleryItem[]): PickableImage[] {
+  const out: PickableImage[] = []
+  for (const item of [...items].reverse()) {
+    for (const imageId of item.imageIds) {
+      out.push({ imageId, prompt: item.prompt, createdAt: item.createdAt })
+    }
+  }
+  return out
+}
+
+export function ImagePicker(props: ImagePickerProps): ReactElement {
+  const { t, title, items, multiple, initial, onConfirm, onClose } = props
+  const [selected, setSelected] = useState<string[]>(initial)
+  const images = flattenImages(items)
+
+  const toggle = (imageId: string): void => {
+    if (multiple) {
+      setSelected((current) =>
+        current.includes(imageId)
+          ? current.filter((id) => id !== imageId)
+          : current.length >= 16
+            ? current
+            : [...current, imageId],
+      )
+      return
+    }
+    setSelected((current) => (current.includes(imageId) ? [] : [imageId]))
+  }
+
+  // 官方 Modal 承载（嵌套 portal：层级高于工作台，遮罩/Escape 由 Modal 处理）。
+  return (
+    <Modal open onClose={onClose} title={title} headless className="ims-pickerModal">
+      <div className="ims-sub">
+        <div className="ims-subHead">
+          <h3 className="ims-subTitle">{title}</h3>
+          <button type="button" className="ims-btn ims-btnGhost" onClick={onClose}>
+            {t('common.close')}
+          </button>
+        </div>
+        {images.length === 0 ? (
+          <p className="ims-empty">{t('picker.empty')}</p>
+        ) : (
+          <div className="ims-pickerGrid" role="listbox" aria-multiselectable={multiple}>
+            {images.map((image) => {
+              const on = selected.includes(image.imageId)
+              return (
+                <button
+                  key={image.imageId}
+                  type="button"
+                  role="option"
+                  aria-selected={on}
+                  className={`ims-pickerCell${on ? ' ims-pickerCellOn' : ''}`}
+                  title={image.prompt}
+                  onClick={() => toggle(image.imageId)}
+                >
+                  <img src={imageUrl(image.imageId)} alt={image.prompt} loading="lazy" />
+                  {on ? (
+                    <span className="ims-pickerMark">{selected.indexOf(image.imageId) + 1}</span>
+                  ) : null}
+                </button>
+              )
+            })}
+          </div>
+        )}
+        <div className="ims-subFoot">
+          <button
+            type="button"
+            className="ims-btn ims-btnPrimary"
+            disabled={selected.length === 0}
+            onClick={() => onConfirm(selected)}
+          >
+            {t('picker.confirm').replace('{n}', String(selected.length))}
+          </button>
+          <button type="button" className="ims-btn ims-btnGhost" onClick={onClose}>
+            {t('common.cancel')}
+          </button>
+        </div>
+      </div>
+    </Modal>
+  )
+}

package/src/client/panel/tasks.tsx

@@ -0,0 +1,72 @@
+/**
+ * 任务条：面板底部的横向任务流（最新在左）。
+ * 活跃任务（排队/生成中）带旋转标与取消按钮；已完成可一键跳画廊详情。
+ * 轮询由面板根组件负责，本组件纯渲染。
+ * @module image-studio/client/panel/tasks
+ */
+import { IconLoadingOutline16 } from '@dsh-plus/shared/client'
+import type { ReactElement } from 'react'
+import type { TaskWire } from '../../dto.ts'
+import type { Translate } from '../i18n.ts'
+
+interface TasksBarProps {
+  t: Translate
+  tasks: TaskWire[]
+  onCancel(taskId: string): void
+  onView(galleryItemId: string): void
+}
+
+const STATE_KEYS = {
+  queued: 'tasks.state.queued',
+  running: 'tasks.state.running',
+  succeeded: 'tasks.state.succeeded',
+  failed: 'tasks.state.failed',
+  cancelled: 'tasks.state.cancelled',
+} as const
+
+export function TasksBar(props: TasksBarProps): ReactElement | null {
+  const { t, tasks, onCancel, onView } = props
+  if (tasks.length === 0) return null
+  return (
+    <section className="ims-tasks" aria-label={t('tasks.title')}>
+      {tasks.slice(0, 20).map((task) => {
+        const active = task.state === 'queued' || task.state === 'running'
+        return (
+          <div key={task.id} className={`ims-task ims-task-${task.state}`}>
+            {active ? <IconLoadingOutline16 className="ims-spin" size={14} /> : null}
+            <span className={`ims-taskState ims-taskState-${task.state}`}>
+              {t(STATE_KEYS[task.state])}
+            </span>
+            <span className="ims-taskPrompt" title={task.promptPreview}>
+              {task.promptPreview}
+            </span>
+            <span className="ims-taskModel">{task.model}</span>
+            {active ? (
+              <button
+                type="button"
+                className="ims-btn ims-btnGhost ims-btnSmall"
+                onClick={() => onCancel(task.id)}
+              >
+                {t('common.cancel')}
+              </button>
+            ) : null}
+            {task.state === 'succeeded' && task.galleryItemId !== null ? (
+              <button
+                type="button"
+                className="ims-btn ims-btnGhost ims-btnSmall"
+                onClick={() => onView(task.galleryItemId as string)}
+              >
+                {t('tasks.view')}
+              </button>
+            ) : null}
+            {task.state === 'failed' && task.error !== null ? (
+              <span className="ims-taskError" title={task.error}>
+                {task.error}
+              </span>
+            ) : null}
+          </div>
+        )
+      })}
+    </section>
+  )
+}