@dxos/plugin-registry 0.8.4-main.f5c0578 → 0.8.4-main.fcc0d83b33

package/src/components/PluginList/PluginItem.tsx

@@ -0,0 +1,187 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type MouseEvent, useCallback, useMemo } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import {
+  Button,
+  type ChromaticPalette,
+  Icon,
+  IconButton,
+  Input,
+  Link,
+  ListItem,
+  type NeutralPalette,
+  Tag,
+  useTranslation,
+} from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { getStyles } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+import { type RegistryTagType } from '#types';
+
+export type PluginItemProps = {
+  plugin: Plugin.Plugin;
+  /** Ids of plugins currently installed (loaded into the manager). */
+  installed?: readonly string[];
+  /** Ids of plugins whose install is in flight. */
+  installing?: readonly string[];
+  enabled?: readonly string[];
+  /**
+   * Derived tags (e.g. `community`, `local`) to display alongside the plugin's own meta.tags.
+   * Not persisted to plugin meta; computed per-render by the container.
+   */
+  extraTags?: readonly string[];
+  onClick?: (id: string) => void;
+  onChange?: (id: string, enabled: boolean) => void;
+  /**
+   * Install handler. When provided and the plugin is not installed, an Install button
+   * is rendered in place of the enable switch.
+   */
+  onInstall?: (id: string) => void;
+  hasSettings?: (id: string) => boolean;
+  onSettings?: (id: string) => void;
+};
+
+export const PluginItem = ({
+  plugin,
+  installed,
+  installing,
+  enabled = [],
+  extraTags,
+  onClick,
+  onChange,
+  onInstall,
+  hasSettings: hasSettingsProp,
+  onSettings,
+}: PluginItemProps) => {
+  const { t } = useTranslation(meta.id);
+  const { id, name, description, tags, icon = 'ph--circle--regular', iconHue = 'neutral' } = plugin.meta;
+  const displayTags = useMemo(() => {
+    if (!extraTags || extraTags.length === 0) {
+      return tags ?? [];
+    }
+    const set = new Set<string>(tags ?? []);
+    for (const tag of extraTags) {
+      set.add(tag);
+    }
+    return Array.from(set);
+  }, [tags, extraTags]);
+  const isEnabled = enabled.includes(id);
+  const isInstalled = installed ? installed.includes(id) : true;
+  const isInstalling = installing?.includes(id) ?? false;
+  const showInstallButton = !!onInstall && !isInstalled;
+  const inputId = `${id}-input`;
+  const labelId = `${id}-label`;
+  const descriptionId = `${id}-description`;
+  const handleClick = useCallback(() => onClick?.(id), [id, onClick]);
+
+  const handleChange = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onChange?.(id, !isEnabled);
+    },
+    [id, isEnabled, onChange],
+  );
+
+  const handleInstall = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onInstall?.(id);
+    },
+    [id, onInstall],
+  );
+
+  const hasSettings = hasSettingsProp?.(id) ?? false;
+  const handleSettings = useCallback(() => onSettings?.(id), [id, onSettings]);
+  const styles = getStyles(iconHue);
+  const gridCols = 'grid grid-cols-[5rem_1fr]';
+  const gridRows = 'grid grid-rows-[40px_1fr_min-content_40px]';
+
+  return (
+    <ListItem.Root
+      key={id}
+      labelId={labelId}
+      data-testid={`pluginList.${id}`}
+      aria-describedby={descriptionId}
+      classNames={mx(gridCols, 'h-[14rem] w-full gap-3 pe-2 bg-modal-surface rounded-md overflow-hidden')}
+    >
+      <div className={mx(gridRows, 'justify-center rounded-l-md', styles.surface)}>
+        <Icon
+          classNames={mx('row-start-2 cursor-pointer', styles.surfaceText)}
+          icon={icon}
+          size={14}
+          onClick={handleClick}
+        />
+      </div>
+
+      <div className={mx(gridRows)}>
+        <div className='flex items-center overflow-hidden cursor-pointer' onClick={handleClick}>
+          <span className='text-lg truncate'>{name ?? id}</span>
+        </div>
+
+        <div>
+          <p className={mx('text-description', 'line-clamp-4 min-w-0')}>{description}</p>
+        </div>
+
+        <div className='flex -ms-0.5 overflow-x-auto scrollbar-none'>
+          {displayTags.map((tag) => (
+            <Tag key={tag} palette={tagColors[tag as RegistryTagType]} classNames='text-xs uppercase font-thin'>
+              {tag}
+            </Tag>
+          ))}
+        </div>
+
+        <div className='flex gap-2 items-center text-sm'>
+          <IconButton
+            aria-describedby={descriptionId}
+            classNames='cursor-pointer'
+            icon='ph--gear--regular'
+            label={t('plugin-settings.label')}
+            iconOnly
+            size={4}
+            onClick={handleSettings}
+            disabled={!hasSettings}
+          />
+
+          <Link aria-describedby={descriptionId} classNames='text-description cursor-pointer' onClick={handleClick}>
+            {t('details.label')}
+          </Link>
+
+          <div className='grow' />
+          <div className='pe-1'>
+            {showInstallButton ? (
+              <Button
+                aria-describedby={descriptionId}
+                density='fine'
+                variant='primary'
+                disabled={isInstalling}
+                onClick={handleInstall}
+              >
+                {isInstalling ? t('installing.label') : t('install.label')}
+              </Button>
+            ) : (
+              <Input.Root id={inputId}>
+                <Input.Switch classNames='self-center' checked={isEnabled} onClick={handleChange} />
+              </Input.Root>
+            )}
+          </div>
+        </div>
+      </div>
+    </ListItem.Root>
+  );
+};
+
+const tagColors: Record<RegistryTagType, ChromaticPalette | NeutralPalette> = {
+  new: 'rose',
+  beta: 'teal',
+  labs: 'blue',
+  popular: 'green',
+  featured: 'pink',
+  experimental: 'amber',
+  community: 'indigo',
+  local: 'neutral',
+};

package/src/components/PluginList/PluginList.stories.tsx

@@ -0,0 +1,87 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { type Plugin, Plugin as PluginNS } from '@dxos/app-framework';
+import { random } from '@dxos/random';
+import { ScrollArea } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { getHashHue } from '@dxos/ui-theme';
+
+import { translations } from '#translations';
+import { RegistryTagType } from '#types';
+
+import { PluginList } from './PluginList';
+
+random.seed(1);
+
+const icons = [
+  'ph--bug--regular',
+  'ph--compass--regular',
+  'ph--kanban--regular',
+  'ph--table--regular',
+  'ph--gear--regular',
+  'ph--github-logo--regular',
+];
+
+const DefaultStory = () => {
+  const [plugins] = useState<Plugin.Plugin[]>(
+    random.helpers.multiple(
+      () =>
+        PluginNS.define({
+          id: `org.dxos.plugin.plugin-${random.string.uuid()}`,
+          name: `${random.commerce.productName()}`,
+          description: random.lorem.sentences(Math.ceil(Math.random() * 3)),
+          tags: random.helpers.uniqueArray(RegistryTagType.literals as any, Math.floor(Math.random() * 3)),
+          icon: random.helpers.arrayElement(icons),
+          iconHue: getHashHue(random.string.uuid()),
+          homePage: random.datatype.boolean({ probability: 0.5 }) ? random.internet.url() : undefined,
+          source: random.internet.url(),
+        }).pipe(PluginNS.make)(),
+      { count: 32 },
+    ),
+  );
+  const [enabled, setEnabled] = useState<string[]>([]);
+
+  const handleChange = (id: string, enabled: boolean) => {
+    setEnabled((plugins) => (enabled ? [...plugins, id] : plugins.filter((plugin) => plugin === id)));
+  };
+
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport>
+        <PluginList plugins={plugins} enabled={enabled} onChange={handleChange} hasSettings={() => true} />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-registry/components/PluginList',
+  component: PluginList,
+  render: DefaultStory,
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof PluginList>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'bg-deck-surface' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export const FullScreen: Story = {
+  decorators: [withTheme(), withLayout({ scroll: true })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};

package/src/components/PluginList/PluginList.tsx

@@ -0,0 +1,29 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { List } from '@dxos/react-ui';
+
+import { PluginItem, type PluginItemProps } from './PluginItem';
+
+export type PluginListProps = Omit<PluginItemProps, 'plugin' | 'extraTags'> & {
+  plugins?: readonly Plugin.Plugin[];
+  /**
+   * Map from plugin id → extra tags to display (e.g. `community`, `local`).
+   * Computed by the container; not persisted to plugin meta.
+   */
+  extraTagsById?: Record<string, readonly string[]>;
+};
+
+export const PluginList = ({ plugins = [], extraTagsById, ...props }: PluginListProps) => {
+  return (
+    <List classNames='grid grid-cols-[repeat(auto-fill,minmax(18rem,1fr))] auto-rows-[max-content] gap-4 p-4'>
+      {plugins.map((plugin) => (
+        <PluginItem key={plugin.meta.id} plugin={plugin} extraTags={extraTagsById?.[plugin.meta.id]} {...props} />
+      ))}
+    </List>
+  );
+};

package/src/components/PluginList/index.ts

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

package/src/components/index.ts

@@ -4,4 +4,3 @@
 
 export * from './PluginDetail';
 export * from './PluginList';
-export * from './RegistryContainer';

package/src/containers/CommunityRegistry/CommunityRegistry.tsx

@@ -0,0 +1,181 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { Plugin, UrlLoader } 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/operations';
+import { type PluginEntry } from '@dxos/protocols';
+import { ScrollArea, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+import { PluginList } from '#components';
+import { getPluginPath, meta } from '#meta';
+
+import { useAutoTags, useCommunityPlugins } from '../../hooks';
+
+const sortEntries = (a: PluginEntry, b: PluginEntry) =>
+  (a.meta.name ?? a.meta.id).localeCompare(b.meta.name ?? b.meta.id);
+
+const sortPlugins = (a: Plugin.Plugin, b: Plugin.Plugin) =>
+  (a.meta.name ?? a.meta.id).localeCompare(b.meta.name ?? b.meta.id);
+
+/**
+ * Turns a community manifest entry into a minimal Plugin object so we can reuse
+ * {@link PluginList} for rendering. The synthesized plugin has no modules — it
+ * exists only for display until the user installs it.
+ */
+const toDisplayPlugin = (entry: PluginEntry): Plugin.Plugin =>
+  ({
+    [Plugin.PluginTypeId]: Plugin.PluginTypeId,
+    meta: entry.meta,
+    modules: [],
+  }) as Plugin.Plugin;
+
+export type CommunityRegistryProps = {
+  id: string;
+};
+
+export const CommunityRegistry = composable<HTMLDivElement, CommunityRegistryProps>(
+  ({ id, ...props }, forwardedRef) => {
+    const { t } = useTranslation(meta.id);
+    const manager = usePluginManager();
+    const { invoke, invokePromise } = useOperationInvoker();
+    const { entries, loading, error } = useCommunityPlugins();
+    const enabled = useAtomValue(manager.enabled);
+    const plugins = useAtomValue(manager.plugins);
+    const installedIds = useMemo(() => plugins.map((plugin) => plugin.meta.id), [plugins]);
+    const allSettings = useCapabilities(AppCapabilities.Settings);
+    const extraTagsById = useAutoTags(entries);
+
+    // Snapshot of installed plugin ids at mount time. Used to sort installed
+    // plugins to the top without having newly-installed rows jump up mid-session.
+    const [installedSnapshot] = useState<ReadonlySet<string>>(
+      () => new Set(manager.getPlugins().map((plugin) => plugin.meta.id)),
+    );
+
+    const [installingIds, setInstallingIds] = useState<readonly string[]>([]);
+
+    const sortedEntries = useMemo(() => [...entries].sort(sortEntries), [entries]);
+    const moduleUrlById = useMemo(() => {
+      const map: Record<string, string> = {};
+      for (const entry of sortedEntries) {
+        map[entry.meta.id] = entry.moduleUrl;
+      }
+      return map;
+    }, [sortedEntries]);
+
+    // Single list with installed-at-mount plugins sorted to the top. Sort order
+    // is based on the mount-time snapshot so rows don't jump as the user
+    // installs plugins during the session.
+    const items = useMemo(() => {
+      const catalogIds = new Set(sortedEntries.map((entry) => entry.meta.id));
+      const remoteIds = new Set(UrlLoader.getRemoteEntries().map((entry) => entry.id));
+      const fromCatalog = sortedEntries.map(toDisplayPlugin);
+      const fromUrlOnly = plugins.filter((plugin) => remoteIds.has(plugin.meta.id) && !catalogIds.has(plugin.meta.id));
+      const installedFirst = [...fromCatalog, ...fromUrlOnly].sort((a, b) => {
+        const aInstalled = installedSnapshot.has(a.meta.id);
+        const bInstalled = installedSnapshot.has(b.meta.id);
+        if (aInstalled !== bInstalled) {
+          return aInstalled ? -1 : 1;
+        }
+        return sortPlugins(a, b);
+      });
+      return installedFirst;
+    }, [sortedEntries, installedSnapshot, plugins]);
+
+    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: { plugin: pluginId, enabled: nextEnabled, source: 'community' },
+          });
+        }).pipe(runAndForwardErrors),
+      [invoke, manager],
+    );
+
+    const handleInstall = useCallback(
+      (pluginId: string) => {
+        const moduleUrl = moduleUrlById[pluginId];
+        if (!moduleUrl) {
+          return;
+        }
+        setInstallingIds((prev) => (prev.includes(pluginId) ? prev : [...prev, pluginId]));
+        void void Effect.gen(function* () {
+          const plugin = yield* manager.add(moduleUrl);
+          yield* manager.enable(plugin.meta.id);
+          yield* invoke(ObservabilityOperation.SendEvent, {
+            name: 'plugins.install',
+            properties: { plugin: plugin.meta.id, source: 'community' },
+          });
+        }).pipe(
+          Effect.ensuring(Effect.sync(() => setInstallingIds((prev) => prev.filter((pid) => pid !== pluginId)))),
+          runAndForwardErrors,
+        );
+      },
+      [invoke, manager, moduleUrlById],
+    );
+
+    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 (
+      <ScrollArea.Root {...composableProps(props)} orientation='vertical' ref={forwardedRef}>
+        <ScrollArea.Viewport>
+          {items.length > 0 ? (
+            <PluginList
+              plugins={items}
+              installed={installedIds}
+              installing={installingIds}
+              enabled={enabled}
+              extraTagsById={extraTagsById}
+              onClick={handleClick}
+              onChange={handleChange}
+              onInstall={handleInstall}
+              hasSettings={hasSettings}
+              onSettings={handleSettings}
+            />
+          ) : error ? (
+            <div className='p-4 text-description'>Failed to load community plugins: {error.message}</div>
+          ) : loading ? (
+            <div className='p-4 text-description'>{t('loading.label')}</div>
+          ) : (
+            <div className='p-4 text-description'>No community plugins available.</div>
+          )}
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    );
+  },
+);
+
+CommunityRegistry.displayName = 'CommunityRegistry';

package/src/containers/CommunityRegistry/index.ts

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

package/src/containers/LoadPluginDialog/LoadPluginDialog.tsx

@@ -0,0 +1,86 @@
+//
+// 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(() => {
+    if (!url.trim()) {
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    void Effect.gen(function* () {
+      const plugin = yield* manager.add(url.trim());
+      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/plugin.mjs'
+              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,73 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { usePluginManager } from '@dxos/app-framework/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { PluginDetail } from '#components';
+
+import { useCommunityPlugins, useRemotePluginIds } from '../../hooks';
+
+// TODO(burdon): Convert to ECHO type.
+export type PluginArticleProps = { subject: Plugin.Plugin };
+
+export const PluginArticle = ({ subject: plugin }: PluginArticleProps) => {
+  const manager = usePluginManager();
+  const plugins = useAtomValue(manager.plugins);
+  const { entries } = useCommunityPlugins();
+  const remotePluginIds = useRemotePluginIds();
+  const [installing, setInstalling] = useState(false);
+
+  const enabled = manager.getEnabled().includes(plugin.meta.id);
+  const isInstalled = useMemo(
+    () => plugins.some((candidate) => candidate.meta.id === plugin.meta.id),
+    [plugins, plugin.meta.id],
+  );
+  const isCore = manager.getCore().includes(plugin.meta.id);
+  const canUninstall = isInstalled && !isCore && remotePluginIds.has(plugin.meta.id);
+
+  const moduleUrl = useMemo(
+    () => entries.find((entry) => entry.meta.id === plugin.meta.id)?.moduleUrl,
+    [entries, plugin.meta.id],
+  );
+
+  const handleEnableChange = useCallback(
+    (enabled: boolean) =>
+      enabled
+        ? runAndForwardErrors(manager.enable(plugin.meta.id))
+        : runAndForwardErrors(manager.disable(plugin.meta.id)),
+    [manager, plugin.meta.id],
+  );
+
+  const handleUninstall = useCallback(() => {
+    void runAndForwardErrors(manager.remove(plugin.meta.id));
+  }, [manager, plugin.meta.id]);
+
+  const handleInstall = useCallback(() => {
+    if (!moduleUrl) {
+      return;
+    }
+    setInstalling(true);
+    void Effect.gen(function* () {
+      const added = yield* manager.add(moduleUrl);
+      yield* manager.enable(added.meta.id);
+    }).pipe(Effect.ensuring(Effect.sync(() => setInstalling(false))), runAndForwardErrors);
+  }, [manager, moduleUrl]);
+
+  return (
+    <PluginDetail
+      plugin={plugin}
+      enabled={enabled}
+      onEnabledChange={handleEnableChange}
+      onInstall={!isInstalled && moduleUrl ? handleInstall : undefined}
+      installing={installing}
+      onUninstall={canUninstall ? handleUninstall : undefined}
+    />
+  );
+};

package/src/containers/PluginArticle/index.ts

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