@dxos/plugin-registry 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/containers/BaseRegistryArticle/BaseRegistryArticle.tsx

@@ -0,0 +1,163 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { type ReactNode, useCallback, useMemo, useState } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { useCapabilities, useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { AppCapabilities, LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { Input, Panel, ScrollArea, Toolbar, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+import { PluginList, type PluginListProps } from '#components';
+import { getPluginPath, meta } from '#meta';
+
+const matchesFilter = (plugin: Plugin.Plugin, query: string) => {
+  const haystack = `${plugin.meta.name ?? ''} ${plugin.meta.id}`.toLowerCase();
+  return haystack.includes(query);
+};
+
+export type BaseRegistryArticleProps = {
+  /** Article id used as the pivotId when opening a plugin's detail surface. */
+  id: string;
+  /** Plugins to display, pre-sorted by the caller. */
+  plugins: readonly Plugin.Plugin[];
+  /**
+   * Distinguishes the source of toggle events for observability
+   * (e.g. `'registry'` for the public registry surface).
+   */
+  source?: string;
+  /** Rendered in place of the list when no plugins match the current filter. */
+  empty?: ReactNode;
+} & Pick<
+  PluginListProps,
+  | 'installed'
+  | 'installing'
+  | 'updating'
+  | 'updateAvailableIds'
+  | 'extraTagsById'
+  | 'failuresById'
+  | 'onInstall'
+  | 'onUpdate'
+>;
+
+export const BaseRegistryArticle = composable<HTMLDivElement, BaseRegistryArticleProps>(
+  (
+    {
+      id,
+      plugins,
+      source,
+      empty,
+      installed,
+      installing,
+      updating,
+      updateAvailableIds,
+      extraTagsById,
+      failuresById,
+      onInstall,
+      onUpdate,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.id);
+    const manager = usePluginManager();
+    const { invoke, invokePromise } = useOperationInvoker();
+    const allSettings = useCapabilities(AppCapabilities.Settings);
+    const enabled = useAtomValue(manager.enabled);
+    const [filter, setFilter] = useState('');
+
+    const filtered = useMemo(() => {
+      const query = filter.trim().toLowerCase();
+      return query.length === 0 ? plugins : plugins.filter((plugin) => matchesFilter(plugin, query));
+    }, [plugins, filter]);
+
+    const handleChange = useCallback(
+      (pluginId: string, nextEnabled: boolean) =>
+        Effect.gen(function* () {
+          if (nextEnabled) {
+            yield* manager.enable(pluginId);
+          } else {
+            yield* manager.disable(pluginId);
+          }
+          yield* invoke(ObservabilityOperation.SendEvent, {
+            name: 'plugins.toggle',
+            properties: source
+              ? { plugin: pluginId, enabled: nextEnabled, source }
+              : { plugin: pluginId, enabled: nextEnabled },
+          });
+        }).pipe(runAndForwardErrors),
+      [invoke, manager, source],
+    );
+
+    const handleClick = useCallback(
+      (pluginId: string) =>
+        invokePromise(LayoutOperation.Open, {
+          subject: [getPluginPath(pluginId)],
+          pivotId: id,
+          positioning: 'end',
+        }),
+      [invokePromise, id],
+    );
+
+    const hasSettings = useCallback(
+      (pluginId: string) => allSettings.some((setting) => setting.prefix === pluginId),
+      [allSettings],
+    );
+
+    const handleSettings = useCallback(
+      (pluginId: string) => invokePromise(SettingsOperation.Open, { plugin: pluginId }),
+      [invokePromise],
+    );
+
+    return (
+      <Panel.Root {...composableProps(props)} ref={forwardedRef}>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <Input.Root>
+              <Input.Label srOnly>{t('filter.label')}</Input.Label>
+              <Input.TextInput
+                placeholder={t('filter.placeholder')}
+                value={filter}
+                onChange={(event) => setFilter(event.target.value)}
+              />
+            </Input.Root>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <ScrollArea.Root orientation='vertical'>
+            <ScrollArea.Viewport>
+              {filtered.length > 0 ? (
+                <PluginList
+                  plugins={filtered}
+                  enabled={enabled}
+                  installed={installed}
+                  installing={installing}
+                  updating={updating}
+                  updateAvailableIds={updateAvailableIds}
+                  extraTagsById={extraTagsById}
+                  failuresById={failuresById}
+                  onClick={handleClick}
+                  onChange={handleChange}
+                  onInstall={onInstall}
+                  onUpdate={onUpdate}
+                  hasSettings={hasSettings}
+                  onSettings={handleSettings}
+                />
+              ) : (
+                empty
+              )}
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+);
+
+BaseRegistryArticle.displayName = 'BaseRegistryArticle';

package/src/containers/BaseRegistryArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './BaseRegistryArticle';

package/src/containers/LoadPluginDialog/LoadPluginDialog.tsx

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useRef, useState } from 'react';
+
+import { usePluginManager } from '@dxos/app-framework/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+import { Button, Dialog, Input, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '../../meta';
+
+export const LOAD_PLUGIN_DIALOG = `${meta.id}.LoadPluginDialog`;
+
+export const LoadPluginDialog = () => {
+  const manager = usePluginManager();
+  const { t } = useTranslation(meta.id);
+  const [url, setUrl] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const closeRef = useRef<HTMLButtonElement | null>(null);
+
+  const handleLoad = useCallback(() => {
+    const trimmed = url.trim();
+    if (!trimmed) {
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    void Effect.gen(function* () {
+      const plugin = yield* manager.add(trimmed);
+      yield* manager.enable(plugin.meta.id);
+      closeRef.current?.click();
+    }).pipe(
+      Effect.catchAll((err) =>
+        Effect.sync(() => {
+          setError(String(err));
+        }),
+      ),
+      Effect.tap(() => Effect.sync(() => setLoading(false))),
+      runAndForwardErrors,
+    );
+  }, [url, manager]);
+
+  return (
+    <Dialog.Content>
+      <Dialog.Header>
+        <Dialog.Title>{t('load-by-url-dialog.title')}</Dialog.Title>
+        <Dialog.Close asChild>
+          <Dialog.CloseIconButton ref={closeRef} />
+        </Dialog.Close>
+      </Dialog.Header>
+      <Dialog.Body>
+        {/* TODO(burdon): Form section. */}
+        <div className='flex flex-col gap-4'>
+          <Input.Root validationValence={error ? 'error' : undefined}>
+            <Input.Label>{t('plugin-url.label')}</Input.Label>
+            <Input.TextInput
+              placeholder='https://example.com/manifest.json'
+              value={url}
+              onChange={(event) => {
+                setUrl(event.target.value);
+                setError(null);
+              }}
+              onKeyDown={(event) => {
+                if (event.key === 'Enter') {
+                  handleLoad();
+                }
+              }}
+              disabled={loading}
+              autoFocus
+            />
+            {error && <Input.DescriptionAndValidation>{error}</Input.DescriptionAndValidation>}
+          </Input.Root>
+          <div className='flex justify-end'>
+            <Button variant='primary' disabled={!url.trim() || loading} onClick={handleLoad}>
+              {loading ? t('loading.label') : t('load-plugin.label')}
+            </Button>
+          </div>
+        </div>
+      </Dialog.Body>
+    </Dialog.Content>
+  );
+};

package/src/containers/LoadPluginDialog/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { LoadPluginDialog as default } from './LoadPluginDialog';

package/src/containers/PluginArticle/PluginArticle.tsx

@@ -0,0 +1,336 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { type Dispatch, type SetStateAction, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type Plugin, type PluginManager, type Registry, UrlLoader } from '@dxos/app-framework';
+import { usePluginManager } from '@dxos/app-framework/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { PluginDetail } from '#components';
+
+import { useRegistryPluginProvider, useRegistryPlugins, useRemotePluginIds } from '../../hooks';
+
+// TODO(burdon): Convert to ECHO type.
+export type PluginArticleProps = { subject: Plugin.Plugin };
+
+export const PluginArticle = ({ subject: plugin }: PluginArticleProps) => {
+  const pluginId = plugin.meta.id;
+  const manager = usePluginManager();
+  const plugins = useAtomValue(manager.plugins);
+  const remotePluginIds = useRemotePluginIds();
+  const provider = useRegistryPluginProvider();
+
+  const { catalogEntry, moduleUrl, repo } = useCatalogEntry(pluginId);
+  const { installedVersionTag, syncInstalledVersion } = useInstalledVersionTag(pluginId, plugins);
+  const { pickerVersions, selectedVersionTag, setSelectedVersionTag } = useVersionPicker({
+    provider,
+    pluginId,
+    repo,
+    moduleUrl,
+    installedVersionTag,
+  });
+
+  const enabled = manager.getEnabled().includes(pluginId);
+  const failed = useAtomValue(manager.failed);
+  const failure = useMemo(() => failed.find((entry) => entry.id === pluginId), [failed, pluginId]);
+  const isInstalled = useMemo(() => plugins.some((candidate) => candidate.meta.id === pluginId), [plugins, pluginId]);
+  const isCore = manager.getCore().includes(pluginId);
+  const canUninstall = isInstalled && !isCore && remotePluginIds.has(pluginId);
+  const hasUpdate =
+    isInstalled && !!catalogEntry && !!installedVersionTag && installedVersionTag !== catalogEntry.version;
+
+  const actions = usePluginActions({
+    manager,
+    pluginId,
+    isInstalled,
+    moduleUrl,
+    catalogEntry,
+    pickerVersions,
+    selectedVersionTag,
+    syncInstalledVersion,
+  });
+
+  return (
+    <PluginDetail
+      plugin={plugin}
+      enabled={enabled}
+      onEnabledChange={actions.handleEnableChange}
+      onInstall={!isInstalled && moduleUrl ? actions.handleInstall : undefined}
+      installing={actions.installing}
+      onUpdate={hasUpdate ? actions.handleUpdate : undefined}
+      hasUpdate={hasUpdate}
+      updating={actions.updating}
+      onUninstall={canUninstall ? actions.handleUninstall : undefined}
+      versions={pickerVersions}
+      selectedVersionTag={selectedVersionTag}
+      onVersionChange={setSelectedVersionTag}
+      onInstallVersion={pickerVersions.length > 0 ? actions.handleInstallVersion : undefined}
+      installedVersionTag={installedVersionTag}
+      failure={failure}
+    />
+  );
+};
+
+//
+// Hooks
+//
+// Each of the hooks below isolates a self-contained slice of the article's
+// state machine. They're declared at module scope (rather than inline in
+// `PluginArticle`) to keep the component readable as a thin wiring layer over
+// `PluginDetail`.
+//
+
+/**
+ * Resolves the registry catalog entry for a plugin by id, plus the two fields
+ * (`moduleUrl`, `repo`) the rest of the article cares about.
+ */
+const useCatalogEntry = (
+  pluginId: string,
+): {
+  catalogEntry: Registry.Plugin | undefined;
+  moduleUrl: string | undefined;
+  repo: string | undefined;
+} => {
+  const { entries } = useRegistryPlugins();
+  const catalogEntry = useMemo(() => entries.find((entry) => entry.id === pluginId), [entries, pluginId]);
+  return { catalogEntry, moduleUrl: catalogEntry?.moduleUrl, repo: catalogEntry?.repo };
+};
+
+/**
+ * Tracks the per-plugin installed version (sourced from `UrlLoader` localStorage)
+ * as React state so post-install/update re-renders are deterministic — the value
+ * lives in component state rather than being read inline on every render.
+ *
+ * - Initialised from localStorage at mount.
+ * - Auto-resyncs when the plugin manager's plugin list changes (catches external
+ *   installs / removes triggered by the list view).
+ * - `syncInstalledVersion()` is the explicit handle install/update operations
+ *   call inside their `Effect.ensuring` so the post-mutation render sees both
+ *   the new version and the cleared `installing`/`updating` flag together.
+ */
+const useInstalledVersionTag = (
+  pluginId: string,
+  plugins: readonly Plugin.Plugin[],
+): {
+  installedVersionTag: string | undefined;
+  syncInstalledVersion: () => void;
+} => {
+  const [installedVersionTag, setInstalledVersionTag] = useState<string | undefined>(() =>
+    UrlLoader.getInstalledVersion(pluginId),
+  );
+
+  const syncInstalledVersion = useCallback(() => {
+    setInstalledVersionTag(UrlLoader.getInstalledVersion(pluginId));
+  }, [pluginId]);
+
+  useEffect(() => {
+    syncInstalledVersion();
+  }, [plugins, syncInstalledVersion]);
+
+  return { installedVersionTag, syncInstalledVersion };
+};
+
+/**
+ * Owns the version picker's state machine: fetches the available versions list
+ * from the provider, prepends the installed version when the catalog stub omits
+ * it, and keeps the selection clamped to whatever's currently in the list (so
+ * an external update doesn't strand the trigger on a tag that's no longer
+ * available).
+ */
+const useVersionPicker = ({
+  provider,
+  pluginId,
+  repo,
+  moduleUrl,
+  installedVersionTag,
+}: {
+  provider: Registry.Manager;
+  pluginId: string;
+  repo: string | undefined;
+  moduleUrl: string | undefined;
+  installedVersionTag: string | undefined;
+}): {
+  pickerVersions: readonly Registry.PluginVersion[];
+  selectedVersionTag: string | undefined;
+  setSelectedVersionTag: Dispatch<SetStateAction<string | undefined>>;
+} => {
+  const [versions, setVersions] = useState<readonly Registry.PluginVersion[]>([]);
+  const [selectedVersionTag, setSelectedVersionTag] = useState<string | undefined>();
+
+  // Load version list once the catalog entry's repo is known.
+  useEffect(() => {
+    if (!repo) {
+      return;
+    }
+    void provider.listVersions(repo).pipe(
+      Effect.match({
+        onSuccess: (vs) => {
+          setVersions(vs);
+          // Default selection: the currently installed version, or the latest.
+          const installedVersion = UrlLoader.getInstalledVersion(pluginId);
+          setSelectedVersionTag(installedVersion ?? vs[0]?.tag);
+        },
+        onFailure: () => {
+          // Non-critical; version picker stays empty.
+        },
+      }),
+      runAndForwardErrors,
+    );
+  }, [provider, repo, pluginId]);
+
+  // Make sure the picker always lists the installed version, even if the catalog
+  // hasn't surfaced it (the current `listVersions` stub only returns latest).
+  const pickerVersions = useMemo<readonly Registry.PluginVersion[]>(() => {
+    if (!installedVersionTag) {
+      return versions;
+    }
+    if (versions.some((entry) => entry.tag === installedVersionTag)) {
+      return versions;
+    }
+    const installedEntry: Registry.PluginVersion = {
+      tag: installedVersionTag,
+      // Picker won't be re-installing this entry unless the user selects + clicks Install,
+      // and the catalog moduleUrl is the closest stand-in we have.
+      moduleUrl: moduleUrl ?? '',
+    };
+    return [installedEntry, ...versions];
+  }, [versions, installedVersionTag, moduleUrl]);
+
+  // Keep `selectedVersionTag` in sync when picker contents change (e.g. the user
+  // updated the plugin from the list view — installed version moved, picker
+  // shrunk, prior selection is no longer in the list).
+  useEffect(() => {
+    if (pickerVersions.length === 0) {
+      return;
+    }
+    if (selectedVersionTag && pickerVersions.some((entry) => entry.tag === selectedVersionTag)) {
+      return;
+    }
+    setSelectedVersionTag(installedVersionTag ?? pickerVersions[0]?.tag);
+  }, [pickerVersions, selectedVersionTag, installedVersionTag]);
+
+  return { pickerVersions, selectedVersionTag, setSelectedVersionTag };
+};
+
+/**
+ * The five user-facing actions the article exposes — enable/disable, uninstall,
+ * install (latest), update (to latest catalog version), and install-from-picker —
+ * plus the `installing`/`updating` flags they drive. Each handler ends with a
+ * `syncInstalledVersion()` call inside its `Effect.ensuring` so the cached
+ * installed version snaps to the freshly-written localStorage value in the same
+ * render that clears the in-flight flag.
+ */
+const usePluginActions = ({
+  manager,
+  pluginId,
+  isInstalled,
+  moduleUrl,
+  catalogEntry,
+  pickerVersions,
+  selectedVersionTag,
+  syncInstalledVersion,
+}: {
+  manager: PluginManager.PluginManager;
+  pluginId: string;
+  isInstalled: boolean;
+  moduleUrl: string | undefined;
+  catalogEntry: Registry.Plugin | undefined;
+  pickerVersions: readonly Registry.PluginVersion[];
+  selectedVersionTag: string | undefined;
+  syncInstalledVersion: () => void;
+}) => {
+  const [installing, setInstalling] = useState(false);
+  const [updating, setUpdating] = useState(false);
+
+  const handleEnableChange = useCallback(
+    (enabled: boolean) =>
+      enabled ? runAndForwardErrors(manager.enable(pluginId)) : runAndForwardErrors(manager.disable(pluginId)),
+    [manager, pluginId],
+  );
+
+  const handleUninstall = useCallback(() => {
+    void runAndForwardErrors(manager.remove(pluginId));
+  }, [manager, pluginId]);
+
+  const handleInstall = useCallback(() => {
+    if (!moduleUrl) {
+      return;
+    }
+    setInstalling(true);
+    void Effect.gen(function* () {
+      const added = yield* manager.add(moduleUrl);
+      yield* manager.enable(added.meta.id);
+      if (catalogEntry) {
+        UrlLoader.setInstalledVersion(added.meta.id, catalogEntry.version);
+      }
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setInstalling(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, moduleUrl, catalogEntry, syncInstalledVersion]);
+
+  const handleUpdate = useCallback(() => {
+    if (!moduleUrl || !catalogEntry) {
+      return;
+    }
+    setUpdating(true);
+    void Effect.gen(function* () {
+      yield* manager.remove(pluginId);
+      const added = yield* manager.add(moduleUrl);
+      yield* manager.enable(added.meta.id);
+      UrlLoader.setInstalledVersion(added.meta.id, catalogEntry.version);
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setUpdating(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, pluginId, moduleUrl, catalogEntry, syncInstalledVersion]);
+
+  const handleInstallVersion = useCallback(() => {
+    const version = pickerVersions.find((candidate) => candidate.tag === selectedVersionTag);
+    if (!version || !version.moduleUrl) {
+      return;
+    }
+    setInstalling(true);
+    void Effect.gen(function* () {
+      // Remove existing version before installing a different one.
+      if (isInstalled) {
+        yield* manager.remove(pluginId);
+      }
+      const added = yield* manager.add(version.moduleUrl);
+      yield* manager.enable(added.meta.id);
+      UrlLoader.setInstalledVersion(added.meta.id, version.tag);
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setInstalling(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, pluginId, isInstalled, selectedVersionTag, pickerVersions, syncInstalledVersion]);
+
+  return {
+    installing,
+    updating,
+    handleEnableChange,
+    handleUninstall,
+    handleInstall,
+    handleUpdate,
+    handleInstallVersion,
+  };
+};

package/src/containers/PluginArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { PluginArticle as default } from './PluginArticle';