@dxos/plugin-registry 0.8.4-main.b97322e → 0.8.4-main.bc2380dfbc

package/src/components/PluginDetail/PluginDetail.tsx

@@ -0,0 +1,272 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin, type PluginManager, type Registry } from '@dxos/app-framework';
+import { Button, Icon, Input, Link, ScrollArea, Select, Tag, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps, getStyles, mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { PluginFailureBadge } from '../PluginFailureBadge';
+
+export type PluginDetailProps = {
+  plugin: Plugin.Plugin;
+  enabled?: boolean;
+  /** True while an in-flight install is running. Disables the install button. */
+  installing?: boolean;
+  /** True while an in-flight update is running. Disables the update button. */
+  updating?: boolean;
+  /** True when the catalog has a newer version than the one installed. */
+  hasUpdate?: boolean;
+  /** Currently installed version tag (used to mark the matching select option). */
+  installedVersionTag?: string;
+  /** Currently selected version tag in the picker. */
+  selectedVersionTag?: string;
+  /** Available versions of this plugin from the catalog. When non-empty, a version picker is shown. */
+  versions?: readonly Registry.PluginVersion[];
+  /**
+   * Ids of plugins this plugin declares as dependencies (direct only). Rendered
+   * under a "Requires" heading so the user can see what enabling this plugin
+   * will auto-enable.
+   */
+  dependencies?: readonly string[];
+  /**
+   * Ids of plugins that declare this plugin as a dependency (direct only).
+   * Rendered under a "Required by" heading so the user understands the
+   * downstream impact of disabling this plugin.
+   */
+  dependents?: readonly string[];
+  /**
+   * Failure record for this plugin, if any. When present a warning badge is
+   * rendered next to the plugin name in the header.
+   */
+  failure?: PluginManager.PluginFailure;
+  onEnabledChange?: (enabled: boolean) => void;
+  /**
+   * When provided, the plugin is not installed and an Install button is shown
+   * in place of the enable Switch.
+   */
+  onInstall?: () => void;
+  /** Called when the user clicks Install on the version picker. */
+  onInstallVersion?: () => void;
+  /**
+   * Called when the user activates a dependency / dependent chip. When
+   * provided, chips are rendered as buttons that fire this handler with the
+   * target plugin id; when omitted, chips are non-interactive labels.
+   */
+  onNavigateToPlugin?: (pluginId: string) => void;
+  /**
+   * Resolves a plugin id to its display name for dependency / dependent
+   * chip labels. The component delegates the lookup to the parent so each
+   * surface can decide how to source names (e.g. `Plugin.Meta.name` from the
+   * registered plugin set). When omitted, chips render the raw id.
+   */
+  onResolvePluginName?: (pluginId: string) => string;
+  /**
+   * When provided, an Uninstall button is rendered. Leave undefined for core
+   * or non-removable plugins.
+   */
+  onUninstall?: () => void;
+  /**
+   * When provided and the plugin is installed with a newer catalog version available,
+   * an Update button is shown in place of the enable Switch.
+   */
+  onUpdate?: () => void;
+  /** Called when the user selects a different version in the picker. */
+  onVersionChange?: (tag: string) => void;
+};
+
+export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
+  (
+    {
+      plugin,
+      enabled,
+      installing,
+      updating,
+      hasUpdate,
+      installedVersionTag,
+      selectedVersionTag,
+      versions,
+      dependencies,
+      dependents,
+      failure,
+      onEnabledChange,
+      onInstall,
+      onInstallVersion,
+      onNavigateToPlugin,
+      onResolvePluginName,
+      onUninstall,
+      onUpdate,
+      onVersionChange,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.id);
+    const {
+      id,
+      name,
+      description,
+      homePage,
+      source,
+      screenshots,
+      icon = 'ph--circle--regular',
+      iconHue = 'neutral',
+    } = plugin.meta;
+    const styles = getStyles(iconHue);
+
+    return (
+      <ScrollArea.Root {...composableProps(props)} orientation='vertical' ref={forwardedRef}>
+        <ScrollArea.Viewport>
+          <div className='dx-document grid grid-cols-[min-content_1fr] gap-4 p-4'>
+            <div>
+              <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.foreground)} icon={icon} size={14} />
+            </div>
+            <div className='flex flex-col gap-6'>
+              <div className='grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
+                <div className='flex items-center gap-2'>
+                  <h2 className='text-xl'>{name}</h2>
+                  {failure && <PluginFailureBadge failure={failure} size={5} />}
+                </div>
+                {onInstall ? (
+                  <Button density='fine' variant='primary' disabled={installing} onClick={onInstall}>
+                    {installing ? t('installing.label') : t('install.label')}
+                  </Button>
+                ) : (
+                  <Input.Root>
+                    <Input.Switch classNames='self-center' checked={enabled} onCheckedChange={onEnabledChange} />
+                  </Input.Root>
+                )}
+                <p className='pt-0.5 text-sm text-description'>{id}</p>
+              </div>
+              <div>
+                <p className='text-description'>{description}</p>
+              </div>
+              {screenshots && screenshots.length > 0 && (
+                <div className='flex flex-col gap-2'>
+                  <h2>Preview</h2>
+                  <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
+                </div>
+              )}
+              <div className='flex flex-col gap-2'>
+                <h2>Resources</h2>
+                <div className='flex gap-2'>
+                  {homePage && (
+                    <Link href={homePage} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
+                      {t('home-page.label')}
+                      <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
+                    </Link>
+                  )}
+
+                  {source && (
+                    <Link href={source} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
+                      {t('source.label')}
+                      <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
+                    </Link>
+                  )}
+                </div>
+              </div>
+              {((dependencies && dependencies.length > 0) || (dependents && dependents.length > 0)) && (
+                <div className='flex flex-col gap-2'>
+                  {dependencies && dependencies.length > 0 && (
+                    <>
+                      <h2>{t('dependencies.label')}</h2>
+                      <div className='flex flex-wrap gap-1'>
+                        {dependencies.map((depId) => (
+                          <PluginChip
+                            key={depId}
+                            id={depId}
+                            name={onResolvePluginName?.(depId) ?? depId}
+                            onClick={onNavigateToPlugin}
+                          />
+                        ))}
+                      </div>
+                    </>
+                  )}
+                  {dependents && dependents.length > 0 && (
+                    <>
+                      <h2>{t('dependents.label')}</h2>
+                      <div className='flex flex-wrap gap-1'>
+                        {dependents.map((dependentId) => (
+                          <PluginChip
+                            key={dependentId}
+                            id={dependentId}
+                            name={onResolvePluginName?.(dependentId) ?? dependentId}
+                            onClick={onNavigateToPlugin}
+                          />
+                        ))}
+                      </div>
+                    </>
+                  )}
+                </div>
+              )}
+              {versions && versions.length > 0 && (
+                <div className='flex flex-col gap-2'>
+                  <h2>{t('versions.label')}</h2>
+                  <div className='flex gap-2 items-center'>
+                    <Select.Root value={selectedVersionTag} onValueChange={onVersionChange}>
+                      <Select.TriggerButton classNames='min-w-32' />
+                      <Select.Portal>
+                        <Select.Content>
+                          <Select.Viewport>
+                            {versions.map((versionEntry) => (
+                              <Select.Option key={versionEntry.tag} value={versionEntry.tag}>
+                                {versionEntry.tag}
+                                {installedVersionTag === versionEntry.tag ? ` (${t('installed.label')})` : ''}
+                              </Select.Option>
+                            ))}
+                          </Select.Viewport>
+                        </Select.Content>
+                      </Select.Portal>
+                    </Select.Root>
+                    {onInstallVersion && (
+                      <Button
+                        density='fine'
+                        variant='primary'
+                        disabled={installing || selectedVersionTag === installedVersionTag}
+                        onClick={onInstallVersion}
+                      >
+                        {installing ? t('installing.label') : t('install-version.label')}
+                      </Button>
+                    )}
+                  </div>
+                </div>
+              )}
+              {(onUninstall || (hasUpdate && onUpdate) || updating) && (
+                <div className='flex gap-2'>
+                  {updating ? (
+                    <Button variant='primary' disabled>
+                      {t('updating.label')}
+                    </Button>
+                  ) : hasUpdate && onUpdate ? (
+                    <Button variant='primary' onClick={onUpdate}>
+                      {t('update.label')}
+                    </Button>
+                  ) : null}
+                  {onUninstall && <Button onClick={onUninstall}>{t('uninstall.label')}</Button>}
+                </div>
+              )}
+            </div>
+          </div>
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    );
+  },
+);
+
+PluginDetail.displayName = 'PluginDetail';
+
+/**
+ * Renders a single dependency / dependent reference using the shared `Tag`
+ * primitive. When `onClick` is provided the chip fires the handler with the
+ * canonical plugin id; the id is also surfaced via `title` so it stays one
+ * hover away even when the chip shows the friendlier `name`.
+ */
+const PluginChip = ({ id, name, onClick }: { id: string; name: string; onClick?: (pluginId: string) => void }) => (
+  <Tag title={id} onClick={onClick ? () => onClick(id) : undefined}>
+    {name}
+  </Tag>
+);

package/src/components/PluginDetail/index.ts

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

package/src/components/PluginFailureBadge/PluginFailureBadge.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { type PluginManager } from '@dxos/app-framework';
+import { IconButton, Popover, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+// Mirrors react-ui `Icon`'s `size` prop literal subset; kept inline so we don't
+// have to add `@dxos/ui-types` as a dep just for one type alias.
+type IconSize = 4 | 5 | 6 | 8;
+
+export type PluginFailureBadgeProps = {
+  failure: PluginManager.PluginFailure;
+  /** Optional override for the trigger icon's tailwind classes. */
+  iconClassNames?: string;
+  /** Visual size of the warning icon (passed through to react-ui `<Icon />`). */
+  size?: IconSize;
+};
+
+/**
+ * Compact warning glyph rendered next to a plugin's name when it has failed
+ * to load or activate. Clicking the icon opens a popover that names the phase
+ * (load / activation), the reason (timeout / error), and the underlying error
+ * message — enough for an operator to tell "remote host is offline" apart
+ * from "the plugin crashed".
+ */
+export const PluginFailureBadge = ({ failure, iconClassNames, size = 4 }: PluginFailureBadgeProps) => {
+  const { t } = useTranslation(meta.id);
+
+  const phaseLabel = failure.phase === 'load' ? t('failure-phase-load.label') : t('failure-phase-activation.label');
+  const reasonLabel =
+    failure.reason === 'timeout' ? t('failure-reason-timeout.label') : t('failure-reason-error.label');
+
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <IconButton
+          variant='ghost'
+          iconOnly
+          noTooltip
+          icon='ph--warning--bold'
+          size={size}
+          iconClassNames={iconClassNames}
+          label={t('failure-badge.label')}
+          data-testid={`pluginFailureBadge.${failure.id}`}
+          // Don't bubble up to row click handlers (e.g. the card's `onClick`
+          // that opens the details pane). The popover is the action here.
+          onClick={(event) => event.stopPropagation()}
+        />
+      </Popover.Trigger>
+      <Popover.Content>
+        <Popover.Viewport>
+          <div className='px-3 py-2 min-w-[18rem] max-w-[28rem] flex flex-col gap-1'>
+            <p className='font-medium text-sm'>
+              {t('failure-title.label', { phase: phaseLabel, reason: reasonLabel })}
+            </p>
+            <p className='text-description text-sm break-words'>{failure.error.message}</p>
+          </div>
+        </Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+    </Popover.Root>
+  );
+};

package/src/components/PluginFailureBadge/index.ts

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

package/src/components/PluginList/PluginItem.tsx

@@ -0,0 +1,226 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type MouseEvent, useCallback, useMemo } from 'react';
+
+import { type Plugin, type PluginManager } 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';
+
+import { PluginFailureBadge } from '../PluginFailureBadge';
+
+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. `registry`, `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;
+  /**
+   * When true and plugin is installed, shows an Update button instead of the enable switch.
+   */
+  hasUpdate?: boolean;
+  /** Called when the user clicks the Update button. */
+  onUpdate?: (id: string) => void;
+  /** Ids of plugins whose update is currently in flight. */
+  updating?: readonly string[];
+  hasSettings?: (id: string) => boolean;
+  onSettings?: (id: string) => void;
+  /**
+   * Failure record for this plugin, if any. When present a warning badge is
+   * rendered next to the plugin name; clicking it opens a popover with the
+   * phase, reason, and error message.
+   */
+  failure?: PluginManager.PluginFailure;
+};
+
+export const PluginItem = ({
+  plugin,
+  installed,
+  installing,
+  enabled = [],
+  extraTags,
+  onClick,
+  onChange,
+  onInstall,
+  hasUpdate,
+  onUpdate,
+  updating,
+  hasSettings: hasSettingsProp,
+  onSettings,
+  failure,
+}: 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 isUpdating = updating?.includes(id) ?? false;
+  const showInstallButton = !!onInstall && !isInstalled;
+  const showUpdateButton = !!onUpdate && isInstalled && !!hasUpdate;
+  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 handleUpdate = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      onUpdate?.(id);
+    },
+    [id, onUpdate],
+  );
+
+  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.foreground)}
+          icon={icon}
+          size={14}
+          onClick={handleClick}
+        />
+      </div>
+
+      <div className={mx(gridRows)}>
+        <div className='flex items-center gap-2 overflow-hidden cursor-pointer' onClick={handleClick}>
+          <span className='text-lg truncate'>{name ?? id}</span>
+          {failure && <PluginFailureBadge failure={failure} />}
+        </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'>
+            {isUpdating ? (
+              <Button aria-describedby={descriptionId} density='fine' variant='primary' disabled>
+                {t('updating.label')}
+              </Button>
+            ) : showUpdateButton ? (
+              <Button aria-describedby={descriptionId} density='fine' variant='primary' onClick={handleUpdate}>
+                {t('update.label')}
+              </Button>
+            ) : 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',
+  registry: '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',
+  },
+};