feat(plugin-detail): show Markdown plugin details on bundle and market entry pages
Plugins bundle pages and Discover entry pages show the plugin's long description first, as Markdown with images, in a height-limited region without its own heading. The document is the file locale meta.detail names, otherwise the package README, otherwise (market entries only) the declared repository's README. The new dsh-plugin-detail library selects documents and reads local package directories and npm file CDNs without state. plugin-manager reads installed and offered bundles through readBundleDetail; plugin-market reads market entries through readEntryDetail, single-file APIs, and a size-limited partial clone cache serialized across processes. Raw HTML is omitted, relative links stay text, and relative images load from Host routes with a sandbox CSP.
This commit is contained in:
1 parent
82a5ae1744
commit
9c8522bb64
111 files changed
+5057
-141
No files matched your search
@@ -0,0 +1,58 @@
|
||||
/** A bundle's long description on its page: the Markdown document the Host reads for it. */
|
||||
import { useEffect, useMemo, type ReactNode } from 'react'
|
||||
import { DetailDocument, detailDocumentState, useDetailDocumentLabels, type MarkdownPathImages } from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
|
||||
import { bundleDetailKey, type BundleDetailFailure, type BundleDetailsState } from './detail-store.ts'
|
||||
|
||||
type Translate = PropsLocale<'pluginManager'>['t']
|
||||
|
||||
const FAILURE_KEYS = {
|
||||
'too-large': 'detailTooLarge',
|
||||
'network': 'detailNetwork',
|
||||
'denied': 'detailFailed',
|
||||
'git-unavailable': 'detailFailed',
|
||||
'invalid': 'detailInvalid',
|
||||
'other': 'detailFailed',
|
||||
} as const satisfies Record<BundleDetailFailure, string>
|
||||
|
||||
/** What the section reads and calls; the page passes them from its injected face. */
|
||||
export interface BundleDetailSectionProps {
|
||||
readonly name: string
|
||||
readonly version: string | undefined
|
||||
/** Whether the bundle's files are unavailable, so the Host reads its offered version from the npm file CDNs. */
|
||||
readonly fromNpm: boolean
|
||||
readonly language: string
|
||||
readonly details: BundleDetailsState
|
||||
readonly t: Translate
|
||||
readonly load: (name: string, version: string | undefined, language: string, fromNpm: boolean) => void
|
||||
readonly retry: (name: string, version: string | undefined, language: string, fromNpm: boolean) => void
|
||||
readonly image: (name: string, document: string, destination: string, fromNpm: boolean) => string | undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Read and render a bundle's detail document in the active language; relative images load from the Host beside it.
|
||||
* @param props - the bundle, the language, the reads, and the page's callbacks.
|
||||
* @returns the section, or null when the bundle has no document.
|
||||
*/
|
||||
export function BundleDetailSection(props: BundleDetailSectionProps): ReactNode {
|
||||
const { name, version, fromNpm, language, details, t, load, retry, image } = props
|
||||
const key = bundleDetailKey(name, version, language)
|
||||
const state = details[key]
|
||||
// The key names the read completely; a read the controller forgot, after a profile change, starts again.
|
||||
const missing = state === undefined
|
||||
useEffect(() => { if (missing) load(name, version, language, fromNpm) }, [key, missing])
|
||||
const labels = useDetailDocumentLabels({
|
||||
title: t('detailTitle'), loading: t('detailLoading'), retry: t('retry'), copy: t('copy'), copied: t('copied'),
|
||||
codeBlock: t('codeBlock.title'), wrap: t('codeBlock.wrap'), unwrap: t('codeBlock.unwrap'), footnotes: t('detailFootnotes'),
|
||||
})
|
||||
const detail = state?.status === 'ready' ? state.detail : undefined
|
||||
const document = detail?.status === 'found' ? detail.path : undefined
|
||||
const images = useMemo<MarkdownPathImages | undefined>(
|
||||
() => document === undefined ? undefined : { resolve: value => image(name, document, value, fromNpm) },
|
||||
[name, document, fromNpm, image],
|
||||
)
|
||||
const shown = detailDocumentState(state?.status === 'error'
|
||||
? { status: 'error', message: t(FAILURE_KEYS[state.failure]) }
|
||||
: state === undefined || state.status === 'loading' ? state : { status: 'ready', markdown: detail?.status === 'found' ? detail.markdown : undefined })
|
||||
return <DetailDocument state={shown} labels={labels} images={images} onRetry={() => { retry(name, version, language, fromNpm) }} />
|
||||
}
|
||||
@@ -33,6 +33,7 @@ import { managementText, noticeText, packageText, registryText, restartText, row
|
||||
import type { PluginPackageRef, PluginRowRef, PluginsSubject } from './slot-contract.ts'
|
||||
import type { ConfigPageForm } from './slot-contract.ts'
|
||||
import { UpdateDialog, VersionSection } from './versions.tsx'
|
||||
import { BundleDetailSection } from './BundleDetailSection.tsx'
|
||||
import css from './PluginManagerPage.module.css'
|
||||
import badgeSkillPreview from './assets/badge-skill-preview.svg'
|
||||
import badgeSkillPreviewZh from './assets/badge-skill-preview.zh.svg'
|
||||
@@ -716,12 +717,14 @@ function RowDetail({ pkg, row, t, resolveText, onBack, renderSlot, form }: {
|
||||
* and configure controls; and where it comes from.
|
||||
*/
|
||||
function PackageDetail({
|
||||
pkg, t, resolveText, busy, rowBusy, configured, configure, renderSlot, inMore, versions,
|
||||
pkg, t, resolveText, busy, rowBusy, configured, configure, renderSlot, inMore, versions, detail,
|
||||
onBack, onSetEnabled, onUninstall, onUpdate, onSetRowEnabled, onEnsureVersions, onCheckVersions, onUpdateVersion,
|
||||
}: {
|
||||
readonly pkg: PackageView
|
||||
/** The package's version check, when one started. */
|
||||
readonly versions: VersionCheck | undefined
|
||||
/** The bundle's detail document section, shown first among the page's sections. */
|
||||
readonly detail: ReactNode
|
||||
readonly t: Translate
|
||||
readonly resolveText: ResolveText
|
||||
readonly busy: boolean
|
||||
@@ -808,6 +811,7 @@ function PackageDetail({
|
||||
{pkg.readOnlyReason === undefined ? null : <p className={css.reason} role="status">{managementText({ code: pkg.readOnlyReason }, t)}</p>}
|
||||
{preview === undefined ? null : <PackagePreview src={preview} title={title} t={t} />}
|
||||
<div className={css.detailSections}>
|
||||
{detail}
|
||||
{configured
|
||||
? (
|
||||
<section className={css.detailSection} data-plugin-config>
|
||||
@@ -1547,6 +1551,8 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
|
||||
// What is open; a package that leaves the list (uninstalled) drops back to the cards.
|
||||
const view = props.useStore(state => state.view), { setView, setTab } = props.actions
|
||||
const tabs = props.usePluginTabs(snapshot => snapshot)
|
||||
const bundleDetails = props.useBundleDetails(snapshot => snapshot)
|
||||
const language = props.useLocale(snapshot => snapshot.active)
|
||||
const selectedTab = props.useStore(state => state.tab)
|
||||
// A contributed tab that left the ledger falls back to Installed, and stays there when it returns.
|
||||
const tab = tabs.some(item => item.id === selectedTab) ? selectedTab : INSTALLED_TAB
|
||||
@@ -1769,6 +1775,11 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
|
||||
configure={configure(openPkg)}
|
||||
renderSlot={renderSlot}
|
||||
inMore={openPkgInMore}
|
||||
detail={(
|
||||
<BundleDetailSection name={openPkg.name} version={openPkg.version} fromNpm={openPkg.availability === 'missing'}
|
||||
language={language} details={bundleDetails} t={t}
|
||||
load={props.loadDetail} retry={props.retryDetail} image={props.detailImage} />
|
||||
)}
|
||||
onBack={() => { setView({ kind: openPkgInMore ? 'more' : 'list' }) }}
|
||||
onSetEnabled={(enabled) => { props.setEnabled(openPkg.name, enabled) }}
|
||||
onUninstall={() => { props.uninstall(openPkg.name) }}
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
/** Bundle detail reads: the long description of each bundle the page opens, read from the Host by name and language. */
|
||||
import type { Context as ClientContext } from '@deepseek-ai/cordis'
|
||||
import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
|
||||
import type { BundleDetail, RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
|
||||
import { NPMMIRROR_REGISTRY } from '@deepseek-ai/dsh-plugin-manager/registry'
|
||||
|
||||
/** Why a bundle detail read failed: the Host's `plugin-manager/detail-unavailable` reason, or `other`. */
|
||||
export type BundleDetailFailure = 'too-large' | 'network' | 'denied' | 'git-unavailable' | 'invalid' | 'other'
|
||||
|
||||
/** One bundle detail read. */
|
||||
export type BundleDetailState =
|
||||
| { readonly status: 'loading' }
|
||||
| { readonly status: 'ready'; readonly detail: BundleDetail }
|
||||
| { readonly status: 'error'; readonly failure: BundleDetailFailure }
|
||||
|
||||
/** Bundle detail reads by {@link bundleDetailKey}. */
|
||||
export type BundleDetailsState = Readonly<Record<string, BundleDetailState>>
|
||||
|
||||
/**
|
||||
* The identity of a bundle detail read: the bundle, its installed version, and the display language.
|
||||
* @param name - the bundle's package name.
|
||||
* @param version - the installed or offered version, so an updated bundle reads again.
|
||||
* @param language - the display language.
|
||||
* @returns the key of the read in {@link BundleDetailsState}.
|
||||
*/
|
||||
export function bundleDetailKey(name: string, version: string | undefined, language: string): string {
|
||||
return JSON.stringify([name, version ?? null, language])
|
||||
}
|
||||
|
||||
/** The Host route of images beside bundle detail documents, relative to the application base. */
|
||||
const DETAIL_FILE_ROUTE = 'api/plugin-manager/detail-file'
|
||||
|
||||
function failureOf(failure: RemoteFailure): BundleDetailFailure {
|
||||
return failure.code === 'plugin-manager/detail-unavailable' ? failure.details.reason : 'other'
|
||||
}
|
||||
|
||||
/** Reads bundle detail documents and publishes them to the page. */
|
||||
export class BundleDetailController {
|
||||
/** Detail reads published to the page. */
|
||||
readonly store: SnapshotStore<BundleDetailsState> = createSnapshotStore<BundleDetailsState>({})
|
||||
/** The latest read of each key, numbered across the controller's lifetime; an older read's answer is dropped. */
|
||||
private readonly reads = new Map<string, number>()
|
||||
private sequence = 0
|
||||
/** npm file CDNs to ask first, from the Host's latest registry comparison: npmmirror when its registry answered fastest. */
|
||||
private npmFileSources: 'npmmirror'[] = []
|
||||
private disposed = false
|
||||
|
||||
/**
|
||||
* @param ctx - the page plugin's context, whose `remote.pluginManager` namespace answers.
|
||||
* @param base - the application base URL that Host routes resolve against.
|
||||
*/
|
||||
constructor(private readonly ctx: ClientContext, private readonly base: () => string) {}
|
||||
|
||||
/**
|
||||
* Read a bundle's document unless the read already ran or runs.
|
||||
* @param name - the bundle's package name.
|
||||
* @param version - its installed or offered version.
|
||||
* @param language - the display language.
|
||||
* @param fromNpm - whether the bundle's files are unavailable, so the Host reads its offered version from the npm file CDNs.
|
||||
*/
|
||||
load(name: string, version: string | undefined, language: string, fromNpm: boolean): void {
|
||||
if (this.store.getSnapshot()[bundleDetailKey(name, version, language)] === undefined) void this.read(name, version, language, fromNpm)
|
||||
}
|
||||
|
||||
/**
|
||||
* Read a bundle's document again.
|
||||
* @param name - the bundle's package name.
|
||||
* @param version - its installed or offered version.
|
||||
* @param language - the display language.
|
||||
* @param fromNpm - whether the Host reads the bundle from the npm file CDNs.
|
||||
*/
|
||||
retry(name: string, version: string | undefined, language: string, fromNpm: boolean): void {
|
||||
void this.read(name, version, language, fromNpm)
|
||||
}
|
||||
|
||||
/**
|
||||
* The URL of an image beside a bundle's document.
|
||||
* @param name - the bundle's package name.
|
||||
* @param document - the document's path inside the bundle.
|
||||
* @param destination - the image destination as the document writes it.
|
||||
* @param fromNpm - whether the Host reads the bundle from the npm file CDNs.
|
||||
* @returns the authenticated Host URL, or undefined for an absolute, protocol-relative, or fragment destination.
|
||||
*/
|
||||
image(name: string, document: string, destination: string, fromNpm: boolean): string | undefined {
|
||||
if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/iu.test(destination)) return undefined
|
||||
const sources = fromNpm ? this.npmFileSources : []
|
||||
const query = new URLSearchParams({ bundle: name, document, path: destination, ...sources.length > 0 ? { sources: sources.join(',') } : {} })
|
||||
return new URL(`${DETAIL_FILE_ROUTE}?${query.toString()}`, this.base()).href
|
||||
}
|
||||
|
||||
/** Forget every read, so each shown bundle reads its document again; bundle files can change at any profile change. */
|
||||
reset(): void {
|
||||
this.reads.clear()
|
||||
this.store.set({})
|
||||
}
|
||||
|
||||
/** Stop publishing late settlements. */
|
||||
dispose(): void {
|
||||
this.disposed = true
|
||||
}
|
||||
|
||||
private async read(name: string, version: string | undefined, language: string, fromNpm: boolean): Promise<void> {
|
||||
const key = bundleDetailKey(name, version, language)
|
||||
const read = ++this.sequence
|
||||
this.reads.set(key, read)
|
||||
this.publish(key, { status: 'loading' })
|
||||
// The remote is captured before any wait: the plugin's context may be disposed while the comparison runs.
|
||||
const { remote } = this.ctx
|
||||
const current = (): boolean => !this.disposed && this.reads.get(key) === read
|
||||
// Only a bundle read from the CDNs waits for the registry comparison.
|
||||
if (fromNpm) {
|
||||
const fastest = await remote.pluginRegistryProbe.fastest()
|
||||
// A retry or reset started while the comparison ran settles the key instead.
|
||||
if (!current()) return
|
||||
this.npmFileSources = fastest.ok && fastest.value === NPMMIRROR_REGISTRY ? ['npmmirror'] : []
|
||||
}
|
||||
const answer = await remote.pluginManager.readBundleDetail(name, language, { npmFileSources: fromNpm ? this.npmFileSources : [] })
|
||||
if (current()) this.publish(key, answer.ok ? { status: 'ready', detail: answer.value } : { status: 'error', failure: failureOf(answer.error) })
|
||||
}
|
||||
|
||||
private publish(key: string, state: BundleDetailState): void {
|
||||
this.store.set({ ...this.store.getSnapshot(), [key]: state })
|
||||
}
|
||||
}
|
||||
@@ -84,6 +84,8 @@ export function apply(ctx: ClientContext): void {
|
||||
ctx.effect(() => {
|
||||
// A page never rendered holds no snapshot to refresh.
|
||||
const refresh = (): void => {
|
||||
// A profile change can replace a bundle's files, and a restarted Host is read afresh.
|
||||
controller.details.reset()
|
||||
if (controller.getSnapshot().status !== 'idle') void controller.load()
|
||||
}
|
||||
const disposers = [
|
||||
|
||||
@@ -286,6 +286,13 @@ export const zh = {
|
||||
reasonIncompatibleInstall: '请安装与当前 DSH 兼容的插件版本。',
|
||||
reasonIncompatibleInstalled: '请卸载后重新安装与当前 DSH 兼容的版本。',
|
||||
reasonOperationError: 'Host 报告了一个错误',
|
||||
detailTitle: '详细介绍',
|
||||
detailLoading: '正在读取详细介绍',
|
||||
detailTooLarge: '详细介绍超过大小限制,未加载',
|
||||
detailNetwork: '无法连接到详细介绍的来源',
|
||||
detailInvalid: '插件声明的详细介绍文件无效',
|
||||
detailFailed: '无法读取详细介绍',
|
||||
detailFootnotes: '脚注',
|
||||
} satisfies Record<string, string>
|
||||
|
||||
/** Plugin manager locale key union. */
|
||||
@@ -572,4 +579,11 @@ export const en = {
|
||||
reasonIncompatibleInstall: 'Install a plugin version compatible with this DSH.',
|
||||
reasonIncompatibleInstalled: 'Uninstall it and install a version compatible with this DSH.',
|
||||
reasonOperationError: 'The Host reported an error.',
|
||||
detailTitle: 'Details',
|
||||
detailLoading: 'Reading details',
|
||||
detailTooLarge: 'The details exceed the size limit and were not loaded.',
|
||||
detailNetwork: 'Could not reach the source of the details.',
|
||||
detailInvalid: 'The plugin declares an invalid details file.',
|
||||
detailFailed: 'Could not read the details.',
|
||||
detailFootnotes: 'Footnotes',
|
||||
} satisfies Record<PluginManagerLocaleKey, string>
|
||||
@@ -41,6 +41,8 @@ import type { ConfigLedger } from './config-ledger.ts'
|
||||
import type { PluginTabInstall } from './slot-contract.ts'
|
||||
import type { PluginTab } from './tab-ledger.ts'
|
||||
import { shortName } from './presentation.ts'
|
||||
import { BundleDetailController, type BundleDetailsState } from './detail-store.ts'
|
||||
import type { LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
|
||||
|
||||
/** The action a failed notice names. */
|
||||
export type FailedAction = 'enable' | 'disable' | 'uninstall' | 'rowEnable' | 'rowDisable'
|
||||
@@ -389,7 +391,17 @@ export interface PluginManagerFace {
|
||||
configLedger: HostObservable<ConfigLedger>
|
||||
/** Tabs other plugins contribute, bound by the renderer as usePluginTabs. */
|
||||
pluginTabs: HostObservable<readonly PluginTab[]>
|
||||
/** Bundle detail reads, bound by the renderer as useBundleDetails. */
|
||||
bundleDetails: SnapshotStore<BundleDetailsState>
|
||||
/** The active locale, bound as useLocale, for the language detail documents are read in. */
|
||||
locale: HostObservable<LocaleSnapshot>
|
||||
}
|
||||
/** Read a bundle's detail document unless the read already ran or runs. */
|
||||
loadDetail: BundleDetailController['load']
|
||||
/** Read a bundle's detail document again. */
|
||||
retryDetail: BundleDetailController['retry']
|
||||
/** The URL of an image beside a bundle's detail document, or undefined for a destination the page loads as written. */
|
||||
detailImage: BundleDetailController['image']
|
||||
/** Read the Host once the tab first renders. */
|
||||
ensure: () => void
|
||||
/** Read the Host again, then check every updatable package for newer versions. */
|
||||
@@ -631,6 +643,8 @@ export class PluginManagerController {
|
||||
private registryRead: RegistryRead | undefined
|
||||
/** A Discover entry chose the dialog's registry; that choice applies to this dialog only and is never remembered. */
|
||||
private transientRegistry = false
|
||||
/** Bundle detail documents the page shows. */
|
||||
readonly details: BundleDetailController
|
||||
/** The registry last used from this browser, kept across dialogs and page loads; null until one was used. */
|
||||
private readonly registryMemory: SnapshotStore<RegistryChoice | null> = createSnapshotStore<RegistryChoice | null>(null, {
|
||||
persist: { name: 'dsh.plugin-manager.install-registry' },
|
||||
@@ -642,6 +656,7 @@ export class PluginManagerController {
|
||||
constructor(
|
||||
private readonly ctx: ClientContext,
|
||||
) {
|
||||
this.details = new BundleDetailController(ctx, () => document.baseURI)
|
||||
this.store = createSnapshotStore<PluginManagerState>({
|
||||
status: 'idle', refreshStatus: 'idle', packages: [], busy: [], notice: null,
|
||||
install: IDLE_INSTALL, confirm: null, highlight: null, versions: {}, update: null,
|
||||
@@ -659,6 +674,7 @@ export class PluginManagerController {
|
||||
/** Stop publishing and drop every late settlement. */
|
||||
dispose(): void {
|
||||
this.disposed = true
|
||||
this.details.dispose()
|
||||
this.registryRead = undefined
|
||||
this.request = undefined
|
||||
this.generation += 1
|
||||
@@ -674,9 +690,16 @@ export class PluginManagerController {
|
||||
inject(
|
||||
configLedger: HostObservable<ConfigLedger>, pluginTabs: HostObservable<readonly PluginTab[]>, resolveText: PluginManagerFace['resolveText'],
|
||||
): PluginManagerFace {
|
||||
const details = this.details
|
||||
return {
|
||||
resolveText,
|
||||
hooks: { pluginManager: this.store, configLedger, pluginTabs, configurations: this.ctx.configForms.describe() },
|
||||
hooks: {
|
||||
pluginManager: this.store, configLedger, pluginTabs, configurations: this.ctx.configForms.describe(),
|
||||
bundleDetails: details.store, locale: this.ctx.locale,
|
||||
},
|
||||
loadDetail: (name, version, language, fromNpm) => { details.load(name, version, language, fromNpm) },
|
||||
retryDetail: (name, version, language, fromNpm) => { details.retry(name, version, language, fromNpm) },
|
||||
detailImage: (name, document, destination, fromNpm) => details.image(name, document, destination, fromNpm),
|
||||
configForm: id => this.ctx.configForms.get(id),
|
||||
ensure: () => { if (this.getSnapshot().status === 'idle') void this.load() },
|
||||
refresh: () => { void this.refresh() },
|
||||
|
||||
@@ -160,7 +160,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
|
||||
*/
|
||||
'plugins.detail.badge': { kind: 'list'; scope: 'root'; owner: PluginDetailProps }
|
||||
/**
|
||||
* Sections under a detail page's own content: after the rows on a bundle's
|
||||
* Sections under a detail page's own content: after the source on a bundle's
|
||||
* page, after the configuration on a row's or an official plugin's page.
|
||||
* An entry draws its own section chrome and renders null for a subject it
|
||||
* has nothing for.
|
||||
|
||||
Reference in new issue
Block a user