@dxos/plugin-registry 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/cli/storage.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as FileSystem from '@effect/platform/FileSystem';
+import * as Path from '@effect/platform/Path';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { DX_CONFIG, getProfilePath } from '@dxos/client-protocol';
+
+// TODO(wittjosiah): Factor out to app-framework?
+
+const PLUGINS_FILE = 'plugins.json';
+
+const PluginsSchema = Schema.Array(Schema.String);
+
+/**
+ * Get the path to the plugins configuration file for a profile.
+ */
+const getPluginsPath = (profile: string): Effect.Effect<string, never, Path.Path> =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    return path.join(getProfilePath(DX_CONFIG, profile), PLUGINS_FILE);
+  });
+
+/**
+ * Load enabled plugins from profile storage.
+ * Returns the list of enabled plugin IDs, or an empty array if the file doesn't exist.
+ */
+export const loadEnabledPlugins = Effect.fn(function* ({ profile }: { profile: string }) {
+  const fs = yield* FileSystem.FileSystem;
+  const pluginsPath = yield* getPluginsPath(profile);
+
+  const content = yield* fs
+    .readFileString(pluginsPath)
+    .pipe(Effect.catchTag('SystemError', () => Effect.succeed('[]')));
+
+  const parsed = yield* Schema.decodeUnknown(Schema.parseJson(PluginsSchema))(content).pipe(
+    Effect.catchAll(() => Effect.succeed([] as string[])),
+  );
+
+  return parsed;
+});
+
+/**
+ * Save enabled plugins to profile storage.
+ */
+export const saveEnabledPlugins = Effect.fn(function* ({ profile, enabled }: { profile: string; enabled: string[] }) {
+  const fs = yield* FileSystem.FileSystem;
+  const pluginsPath = yield* getPluginsPath(profile);
+  const profileDir = getProfilePath(DX_CONFIG, profile);
+
+  yield* fs.makeDirectory(profileDir, { recursive: true });
+  const encoded = Schema.encodeSync(Schema.parseJson(PluginsSchema))(enabled);
+  yield* fs.writeFileString(pluginsPath, encoded + '\n');
+});

package/src/components/PluginDetail/PluginDetail.stories.tsx

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { Plugin } from '@dxos/app-framework';
+import { faker } from '@dxos/random';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '../../translations';
+
+import { PluginDetail } from './PluginDetail';
+
+const meta = {
+  title: 'plugins/plugin-registry/components/PluginDetail',
+  component: PluginDetail,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof PluginDetail>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    plugin: Plugin.define({
+      id: 'example.com/plugin/test-plugin',
+      name: 'Test Plugin',
+      description: faker.lorem.paragraphs(2),
+      icon: 'ph--bug--regular',
+      iconHue: 'sky',
+      homePage: 'https://example.com',
+      source: 'https://github.com/example/test-plugin',
+      screenshots: [
+        'https://media.gcflearnfree.org/content/55e073de7dd48174331f51b3_01_17_2014/getting_started_interactive2.png',
+      ],
+    }).pipe(Plugin.make)(),
+  },
+};

package/src/components/PluginDetail/PluginDetail.tsx

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { Icon, Input, Link, useTranslation } from '@dxos/react-ui';
+import { ScrollArea } from '@dxos/react-ui';
+import { getStyles, mx } from '@dxos/ui-theme';
+
+import { meta } from '../../meta';
+
+export type PluginDetailProps = {
+  plugin: Plugin.Plugin;
+  enabled?: boolean;
+  onEnabledChange?: (enabled: boolean) => void;
+};
+
+export const PluginDetail = ({ plugin, enabled, onEnabledChange }: PluginDetailProps) => {
+  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 orientation='vertical'>
+      <ScrollArea.Viewport>
+        <div role='none' className='dx-article grid grid-cols-[min-content_1fr] gap-4 p-4'>
+          <div role='none'>
+            <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.surfaceText)} icon={icon} size={14} />
+          </div>
+          <div role='none' className='flex flex-col gap-6'>
+            <div role='none' className='grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
+              <h2 className='text-xl'>{name}</h2>
+              <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 role='none'>
+              <p className='text-description'>{description}</p>
+            </div>
+            {screenshots && screenshots.length > 0 && (
+              <div role='none' className='flex flex-col gap-2'>
+                <h2>Preview</h2>
+                <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
+              </div>
+            )}
+            <div role='none' 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>
+          </div>
+        </div>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};

package/src/components/PluginDetail/index.ts

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

package/src/components/PluginList/PluginItem.tsx

@@ -0,0 +1,124 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type MouseEvent, useCallback } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { type ChromaticPalette, Icon, IconButton, Input, Link, ListItem, 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;
+  installed?: readonly string[];
+  enabled?: readonly string[];
+  onClick?: (id: string) => void;
+  onChange?: (id: string, enabled: boolean) => void;
+  hasSettings?: (id: string) => boolean;
+  onSettings?: (id: string) => void;
+};
+
+export const PluginItem = ({
+  plugin,
+  enabled = [],
+  onClick,
+  onChange,
+  hasSettings: hasSettingsProp,
+  onSettings,
+}: PluginItemProps) => {
+  const { t } = useTranslation(meta.id);
+  const { id, name, description, tags, icon = 'ph--circle--regular', iconHue = 'neutral' } = plugin.meta;
+  const isEnabled = enabled.includes(id);
+  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 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-[12rem] 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'>
+          {tags?.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('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'>
+            <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> = {
+  new: 'rose',
+  beta: 'teal',
+  labs: 'blue',
+  popular: 'green',
+  featured: 'pink',
+  experimental: 'amber',
+};

package/src/components/{PluginList.stories.tsx → PluginList/PluginList.stories.tsx}

@@ -5,13 +5,14 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
-import { type Plugin, definePlugin } from '@dxos/app-framework';
+import { type Plugin, Plugin as PluginNS } from '@dxos/app-framework';
 import { faker } from '@dxos/random';
-import { type ThemedClassName } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
-import { mx } from '@dxos/react-ui-theme';
+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 { translations } from '../../translations';
+import { RegistryTagType } from '../../types';
 
 import { PluginList } from './PluginList';
 
@@ -26,24 +27,21 @@ const icons = [
   'ph--github-logo--regular',
 ];
 
-const DefaultStory = ({ classNames }: ThemedClassName<{}>) => {
-  const [plugins] = useState<Plugin[]>(
+const DefaultStory = () => {
+  const [plugins] = useState<Plugin.Plugin[]>(
     faker.helpers.multiple(
-      definePlugin(
-        {
+      () =>
+        PluginNS.define({
           id: `dxos.org/plugin/plugin-${faker.string.uuid()}`,
           name: `${faker.commerce.productName()}`,
           description: faker.lorem.sentences(Math.ceil(Math.random() * 3)),
-          tags: faker.datatype.boolean({ probability: 0.6 })
-            ? [faker.helpers.arrayElement(['labs', 'beta', 'alpha', 'stable', 'new', '新発売'])]
-            : undefined,
+          tags: faker.helpers.uniqueArray(RegistryTagType.literals as any, Math.floor(Math.random() * 3)),
           icon: faker.helpers.arrayElement(icons),
+          iconHue: getHashHue(faker.string.uuid()),
           homePage: faker.datatype.boolean({ probability: 0.5 }) ? faker.internet.url() : undefined,
           source: faker.internet.url(),
-        },
-        () => [],
-      ),
-      { count: 16 },
+        }).pipe(PluginNS.make)(),
+      { count: 32 },
     ),
   );
   const [enabled, setEnabled] = useState<string[]>([]);
@@ -53,19 +51,19 @@ const DefaultStory = ({ classNames }: ThemedClassName<{}>) => {
   };
 
   return (
-    <div className={mx('flex overflow-hidden', classNames)}>
-      <PluginList plugins={plugins} enabled={enabled} onChange={handleChange} hasSettings={() => true} />
-    </div>
+    <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/PluginList',
+  title: 'plugins/plugin-registry/components/PluginList',
   component: PluginList,
   render: DefaultStory,
-  decorators: [withTheme],
   parameters: {
-    layout: 'column',
     translations,
   },
 } satisfies Meta<typeof PluginList>;
@@ -74,10 +72,13 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = {};
+export const Default: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+};
 
-export const Column: Story = {
-  args: {
-    classNames: 'w-[30rem]',
+export const FullScreen: Story = {
+  decorators: [withTheme(), withLayout({ scroll: true })],
+  parameters: {
+    layout: 'fullscreen',
   },
 };

package/src/components/{PluginList.tsx → PluginList/PluginList.tsx}

@@ -10,16 +10,14 @@ import { List } from '@dxos/react-ui';
 import { PluginItem, type PluginItemProps } from './PluginItem';
 
 export type PluginListProps = Omit<PluginItemProps, 'plugin'> & {
-  plugins?: readonly Plugin[];
+  plugins?: readonly Plugin.Plugin[];
 };
 
 export const PluginList = ({ plugins = [], ...props }: PluginListProps) => {
   return (
-    <List classNames='grid grid-cols-[repeat(auto-fill,minmax(280px,1fr))] auto-rows-[12rem] gap-3 p-3'>
+    <List classNames='grid grid-cols-[repeat(auto-fill,minmax(18rem,1fr))] auto-rows-[max-content] gap-4 p-4'>
       {plugins.map((plugin) => (
-        <div key={plugin.meta.id} className='flex'>
-          <PluginItem plugin={plugin} {...props} />
-        </div>
+        <PluginItem key={plugin.meta.id} plugin={plugin} {...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/PluginArticle/PluginArticle.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } 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';
+
+// TODO(burdon): Convert to ECHO type.
+export type PluginArticleProps = { subject: Plugin.Plugin };
+
+export const PluginArticle = ({ subject: plugin }: PluginArticleProps) => {
+  const manager = usePluginManager();
+  const enabled = manager.getEnabled().includes(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],
+  );
+
+  return <PluginDetail plugin={plugin} enabled={enabled} onEnabledChange={handleEnableChange} />;
+};

package/src/containers/PluginArticle/index.ts

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

package/src/containers/PluginRegistry/PluginRegistry.tsx

@@ -0,0 +1,86 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo } 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/types';
+import { ScrollArea } from '@dxos/react-ui';
+
+import { PluginList } from '../../components';
+
+const sortByPluginMeta = ({ meta: { name: a = '' } }: Plugin.Plugin, { meta: { name: b = '' } }: Plugin.Plugin) =>
+  a.localeCompare(b);
+
+export type PluginRegistryProps = {
+  id: string;
+  plugins: Plugin.Plugin[];
+};
+
+export const PluginRegistry = ({ id, plugins: pluginsProp }: PluginRegistryProps) => {
+  const manager = usePluginManager();
+  const { invoke, invokePromise } = useOperationInvoker();
+  const plugins = useMemo(() => pluginsProp.sort(sortByPluginMeta), [pluginsProp]);
+  const enabled = useAtomValue(manager.enabled);
+  const allSettings = useCapabilities(AppCapabilities.Settings);
+
+  // TODO(wittjosiah): Factor out to an intent?
+  const handleChange = useCallback(
+    (id: string, enabled: boolean) =>
+      Effect.gen(function* () {
+        if (enabled) {
+          yield* manager.enable(id);
+        } else {
+          yield* manager.disable(id);
+        }
+
+        yield* invoke(ObservabilityOperation.SendEvent, {
+          name: 'plugins.toggle',
+          properties: {
+            plugin: id,
+            enabled,
+          },
+        });
+      }).pipe(runAndForwardErrors),
+    [invoke, manager],
+  );
+
+  const handleClick = useCallback(
+    (pluginId: string) =>
+      invokePromise(LayoutOperation.Open, {
+        // TODO(wittjosiah): `/` currently is not supported in ids.
+        subject: [pluginId.replaceAll('/', ':')],
+        pivotId: id,
+        positioning: 'end',
+      }),
+    [invokePromise, id],
+  );
+
+  const hasSettings = useCallback((pluginId: string) => allSettings.some((s) => s.prefix === pluginId), [allSettings]);
+
+  const handleSettings = useCallback(
+    (pluginId: string) => invokePromise(SettingsOperation.Open, { plugin: pluginId }),
+    [invokePromise],
+  );
+
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport>
+        <PluginList
+          plugins={plugins}
+          enabled={enabled}
+          onClick={handleClick}
+          onChange={handleChange}
+          hasSettings={hasSettings}
+          onSettings={handleSettings}
+        />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};

package/src/containers/PluginRegistry/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { PluginRegistry } from './PluginRegistry';
+
+export default PluginRegistry;

package/src/containers/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const PluginArticle: ComponentType<any> = lazy(() => import('./PluginArticle'));
+export const PluginRegistry: ComponentType<any> = lazy(() => import('./PluginRegistry'));

package/src/meta.ts

@@ -2,7 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
 // TODO(wittjosiah): Deck does not currently support `/` in ids.
 // TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
@@ -10,7 +11,11 @@ import { type PluginMeta } from '@dxos/app-framework';
 export const REGISTRY_ID = '!dxos:plugin-registry';
 export const REGISTRY_KEY = 'plugin-registry';
 
-export const meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/plugin/registry',
   name: 'Plugins',
+  description: trim`
+    Plugin management system for discovering, installing, and configuring workspace extensions.
+    Browse available plugins and customize your workspace capabilities.
+  `,
 };

package/src/types.ts

@@ -11,3 +11,7 @@ export const RegistrySettingsSchema = Schema.mutable(
 );
 
 export type RegistrySettings = Schema.Schema.Type<typeof RegistrySettingsSchema>;
+
+export const RegistryTagType = Schema.Literal('new', 'beta', 'labs', 'popular', 'featured', 'experimental');
+
+export type RegistryTagType = Schema.Schema.Type<typeof RegistryTagType>;