@dxos/plugin-presenter 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/PresenterSettings/PresenterSettings.stories.tsx

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { PresenterSettings } from './PresenterSettings';
+
+const meta = {
+  title: 'plugins/plugin-presenter/components/PresenterSettings',
+  component: PresenterSettings,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  tags: ['settings'],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof PresenterSettings>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    settings: { presentCollections: true },
+  },
+};

package/src/components/PresenterSettings/PresenterSettings.tsx

@@ -0,0 +1,31 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { Settings } from '#types';
+
+export type PresenterSettingsProps = AppSurface.SettingsArticleProps<Settings.Settings>;
+
+export const PresenterSettings = ({ settings, onSettingsChange }: PresenterSettingsProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+        <SettingsForm.FieldSet
+          readonly={!onSettingsChange}
+          schema={Settings.Settings}
+          values={settings}
+          onValuesChanged={(values) => onSettingsChange?.(() => values)}
+        />
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
+  );
+};

package/src/components/PresenterSettings/index.ts

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

package/src/components/RevealPlayer/RevealPlayer.stories.tsx

@@ -2,13 +2,13 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta } from '@storybook/react-vite';
 
-import CONTENT from '../../../testing/deck.md?raw';
-import { translations } from '../../translations';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
 
+import CONTENT from '../../../testing/deck.md?raw';
 import { RevealPlayer } from './RevealPlayer';
 
 // https://revealjs.com/markdown
@@ -19,14 +19,15 @@ import { RevealPlayer } from './RevealPlayer';
 // https://fontsource.org/fonts
 // https://fonts.google.com
 
-const meta: Meta<typeof RevealPlayer> = {
-  title: 'plugins/plugin-presenter/RevealPlayer',
+const meta = {
+  title: 'plugins/plugin-presenter/components/RevealPlayer',
   component: RevealPlayer,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
     translations,
   },
-};
+} satisfies Meta<typeof RevealPlayer>;
 
 export default meta;
 

package/src/components/RevealPlayer/RevealPlayer.tsx

@@ -2,24 +2,21 @@
 // Copyright 2024 DXOS.org
 //
 
-// eslint-disable-next-line no-restricted-imports
 import 'reveal.js/dist/reveal.css';
-// eslint-disable-next-line no-restricted-imports
 import 'reveal.js/dist/theme/black.css';
-
 // https://github.com/highlightjs/highlight.js/tree/main/src/styles
 // import 'highlight.js/styles/github-dark.css';
 import 'highlight.js/styles/tokyo-night-dark.css';
 
 import hljs from 'highlight.js';
 import typescript from 'highlight.js/lib/languages/typescript';
-import React, { useEffect, useRef } from 'react';
+import React, { useRef } from 'react';
 import Reveal from 'reveal.js';
 import RevealHighlight from 'reveal.js/plugin/highlight/highlight';
 import RevealMarkdown from 'reveal.js/plugin/markdown/plugin.js';
 
-import { type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { useAsyncEffect } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
 
 const styles = `
 <style type="text/css">
@@ -62,25 +59,26 @@ const styles = `
 </style>
 `;
 
-export type RevealProps = ThemedClassName<{
+export type RevealProps = {
   content: string;
   slide?: number;
   fullscreen?: boolean;
   onExit?: () => void;
-}>;
+};
 
-export const RevealPlayer = ({ classNames, content, slide, fullscreen = true, onExit }: RevealProps) => {
-  const deckDivRef = useRef<HTMLDivElement>(null);
-  const deckRef = useRef<Reveal.Api | null>(null);
-  useEffect(() => {
-    if (deckRef.current) {
-      return;
-    }
+export const RevealPlayer = composable<HTMLDivElement, RevealProps>(
+  ({ content, slide, fullscreen = true, onExit, children, ...props }, forwardedRef) => {
+    const deckDivRef = useRef<HTMLDivElement>(null);
+    const deckRef = useRef<Reveal.Api | null>(null);
 
-    // Required for syntax highlighting.
-    hljs.registerLanguage('typescript', typescript);
+    useAsyncEffect(async () => {
+      if (deckRef.current) {
+        return;
+      }
+
+      // Required for syntax highlighting.
+      hljs.registerLanguage('typescript', typescript);
 
-    const t = setTimeout(async () => {
       // https://revealjs.com/react
       // https://revealjs.com/config
       // https://github.com/hakimel/reveal.js
@@ -92,6 +90,9 @@ export const RevealPlayer = ({ classNames, content, slide, fullscreen = true, on
         slideNumber: false,
         embedded: true,
 
+        // Disable autoplay to prevent errors in headless environments (e.g., CI).
+        autoPlayMedia: false,
+
         // TODO(burdon): Speaker view requires server to serve popout window.
         // https://revealjs.com/speaker-view
         showNotes: false,
@@ -130,42 +131,47 @@ export const RevealPlayer = ({ classNames, content, slide, fullscreen = true, on
       deckRef.current.addKeyBinding({ keyCode: 27, key: 'Escape', description: 'Exit full screen' }, () => {
         onExit?.();
       });
-    });
 
-    return () => {
-      try {
-        clearTimeout(t);
-        if (deckRef.current) {
-          deckRef.current.destroy();
-          deckRef.current = null;
+      return () => {
+        try {
+          if (deckRef.current) {
+            deckRef.current.destroy();
+            deckRef.current = null;
+          }
+        } catch {
+          // Ignore.
         }
-      } catch (err) {
-        // Ignore.
-      }
-    };
-  });
-
-  return (
-    <div className={mx('absolute flex h-full w-full items-center justify-center', fullscreen && 'inset-0', classNames)}>
-      <div className='relative aspect-video w-full'>
-        <div ref={deckDivRef} className='reveal'>
-          {/* TODO(burdon): Must be in head. */}
-          <style>
-            <link rel='preconnect' href='https://fonts.googleapis.com' />
-            <link rel='preconnect' href='https://fonts.gstatic.com' {...{ crossOrigin: '' }} />
-            <link
-              rel='stylesheet'
-              href='https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,100..900;1,100..900&display=swap'
-            />
-          </style>
-          <div className='slides'>
-            <div className='!text-center' />
-            <section {...{ 'data-markdown': [] }}>
-              <textarea {...{ 'data-template': true }} defaultValue={[styles, content].join('\n')}></textarea>
-            </section>
+      };
+    });
+
+    // TOOD(burdon): Trap cursor keys (otherwise tabster grabs focus.)
+    return (
+      <div
+        {...composableProps(props, {
+          classNames: ['dx-container grid place-items-center bg-black', fullscreen && 'absolute inset-0'],
+        })}
+        ref={forwardedRef}
+      >
+        <div className='relative aspect-video h-full w-full h-auto max-h-full overflow-hidden'>
+          <div ref={deckDivRef} className='absolute inset-0 reveal'>
+            {/* NOTE: Must be in head. */}
+            <style>
+              <link rel='preconnect' href='https://fonts.googleapis.com' />
+              <link rel='preconnect' href='https://fonts.gstatic.com' {...{ crossOrigin: '' }} />
+              <link
+                rel='stylesheet'
+                href='https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,100..900;1,100..900&display=swap'
+              />
+            </style>
+            <div className='slides'>
+              <div className='text-center!' />
+              <section {...{ 'data-markdown': [] }}>
+                <textarea {...{ 'data-template': true }} defaultValue={[styles, content].join('\n')}></textarea>
+              </section>
+            </div>
           </div>
         </div>
       </div>
-    </div>
-  );
-};
+    );
+  },
+);

package/src/components/index.ts

@@ -2,10 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
-import { lazy } from 'react';
+import { type ComponentType, lazy } from 'react';
 
-export * from './PresenterSettings';
+export * from './Markdown';
+export * from './Presenter';
+export * from './RevealPlayer';
 
-export const MarkdownSlide = lazy(() => import('./MarkdownSlide'));
-export const DocumentPresenterContainer = lazy(() => import('./DocumentPresenterContainer'));
-export const CollectionPresenterContainer = lazy(() => import('./CollectionPresenterContainer'));
+export const PresenterSettings: ComponentType<any> = lazy(() => import('./PresenterSettings'));

package/src/containers/CollectionPresenterArticle/CollectionPresenterArticle.tsx

@@ -0,0 +1,50 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { useContext, useState } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { type Collection, Obj } from '@dxos/echo';
+import { Panel } from '@dxos/react-ui';
+
+import { PageNumber, Pager, Layout as PresenterLayout } from '#components';
+import { PresenterContext } from '#types';
+
+import { useExitPresenter } from '../../useExitPresenter';
+
+export type CollectionPresenterArticleProps = AppSurface.ObjectArticleProps<Collection.Collection>;
+
+export const CollectionPresenterArticle = ({ role, subject: collection }: CollectionPresenterArticleProps) => {
+  const [slide, setSlide] = useState(0);
+  const { running } = useContext(PresenterContext);
+  const handleExit = useExitPresenter(collection);
+
+  return (
+    <Panel.Root role={role} classNames='relative'>
+      <Panel.Content asChild>
+        <PresenterLayout
+          bottomRight={<PageNumber index={slide} count={collection.objects.length} />}
+          bottomLeft={
+            <Pager
+              index={slide}
+              count={collection.objects.length}
+              keys={running}
+              onChange={setSlide}
+              onExit={handleExit}
+            />
+          }
+        >
+          <Surface.Surface
+            type={AppSurface.Slide}
+            data={{
+              subject: collection.objects[slide],
+              attendableId: Obj.getURI(collection),
+            }}
+          />
+        </PresenterLayout>
+      </Panel.Content>
+    </Panel.Root>
+  );
+};

package/src/containers/CollectionPresenterArticle/index.ts

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

package/src/containers/DocumentPresenterContainer/DocumentPresenterContainer.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type FC } from 'react';
+
+import { type Markdown } from '@dxos/plugin-markdown';
+import { Panel } from '@dxos/react-ui';
+
+import { RevealPlayer } from '#components';
+
+import { useExitPresenter } from '../../useExitPresenter';
+
+export const DocumentPresenterContainer: FC<{ document: Markdown.Document }> = ({ document }) => {
+  const handleExit = useExitPresenter(document);
+
+  return (
+    <Panel.Root classNames='relative'>
+      <Panel.Content asChild>
+        <RevealPlayer content={document.content.target?.content ?? ''} onExit={handleExit} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};

package/src/containers/DocumentPresenterContainer/index.ts

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

package/src/containers/MarkdownSlide/MarkdownSlide.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { type Markdown } from '@dxos/plugin-markdown';
+
+import { Panel, Slide } from '#components';
+
+type MarkdownSlideProps = {
+  document: Markdown.Document;
+};
+
+export const MarkdownSlide = ({ document }: MarkdownSlideProps) => {
+  const content = document.content.target?.content;
+  if (!content) {
+    return null;
+  }
+
+  return (
+    <Panel>
+      <Slide content={content} />
+    </Panel>
+  );
+};

package/src/containers/MarkdownSlide/index.ts

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

package/src/containers/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const CollectionPresenterArticle: ComponentType<any> = lazy(() => import('./CollectionPresenterArticle'));
+export const DocumentPresenterContainer: ComponentType<any> = lazy(() => import('./DocumentPresenterContainer'));
+export const MarkdownSlide: ComponentType<any> = lazy(() => import('./MarkdownSlide'));

package/src/index.ts

@@ -2,7 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './components';
-
 export * from './meta';
-export * from './PresenterPlugin';
+export * from './types';

package/src/meta.ts

@@ -2,14 +2,36 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const PRESENTER_PLUGIN = 'dxos.org/plugin/presenter';
-
-export const meta: PluginMeta = {
-  id: PRESENTER_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.presenter'),
   name: 'Presenter',
-  description: 'Present documents as slideshows.',
+  author: 'DXOS',
+  description: trim`
+    Transform existing workspace objects into interactive presentation slideshows without
+    duplicating content. Markdown documents are split into slides on horizontal \`---\`
+    separators and rendered with Reveal.js, giving authors a familiar authoring surface
+    with full Markdown syntax. Collections can optionally be presented slide-by-slide,
+    with each member object rendered by its own plugin surface.
+
+    Activate presentation mode for any supported object via the action menu or the
+    Shift+Cmd+P (macOS) / Shift+Alt+P (Windows/Linux) keyboard shortcut. The presenter
+    opens in a solo fullscreen layout managed by the Deck plugin, keeping the rest of the
+    workspace undisturbed.
+
+    Navigation controls and a page-number indicator are shown during collection
+    slideshows. Pressing Escape exits fullscreen and returns to the originating document
+    or collection view. All navigation is keyboard-accessible.
+
+    Collaboration is inherent: because slides are backed by live ECHO objects, edits made
+    by any peer in the workspace are immediately reflected in an open presentation without
+    any manual refresh.
+  `,
   icon: 'ph--presentation--regular',
+  iconHue: 'indigo',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-presenter',
-};
+  spec: 'PLUGIN.mdl',
+});

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const PresenterPlugin = Plugin.lazy(meta, () => import('#plugin'));

package/src/testing.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 
 type SlideOptions = {
   text?: string;
@@ -26,21 +26,21 @@ export const createSlide = (options: SlideOptions = {}) => {
 
   const list = (length = 3) =>
     Array.from({ length })
-      .map(() => `- ${faker.lorem.sentence(3)}`)
+      .map(() => `- ${random.lorem.sentence(3)}`)
       .join('\n');
 
   const ordered = (length = 3) =>
     Array.from({ length })
-      .map((_, i) => `${i + 1}. ${faker.lorem.sentence(3)}`)
+      .map((_, i) => `${i + 1}. ${random.lorem.sentence(3)}`)
       .join('\n');
 
   return [
-    `# ${num}${faker.lorem.sentence(3)}`,
-    options.text && faker.lorem.sentences(),
+    `# ${num}${random.lorem.sentence(3)}`,
+    options.text && random.lorem.sentences(),
     options.code && code(),
     options.list && list(options.list),
     options.ordered && ordered(options.ordered),
-    faker.lorem.sentences(),
+    random.lorem.sentences(),
   ]
     .filter(Boolean)
     .join('\n\r');

package/src/translations.ts

@@ -4,15 +4,15 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Presenter',
-        'toggle presentation label': 'Present',
-        'present collections label': 'Present collections (experimental)',
+        'plugin.name': 'Presenter',
+        'settings.title': 'Presenter settings',
+        'toggle-presentation.label': 'Present',
       },
     },
   },

package/src/types/PresenterCapabilities.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom } from '@effect-atom/atom-react';
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+// Inline import to avoid `Settings` namespace alias colliding with the
+// `Settings` capability export below.
+export const Settings = Capability.make<Atom.Writable<import('./Settings').Settings>>(`${meta.id}.capability.settings`);

package/src/types/PresenterOperation.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { Collection, Type, DXN } from '@dxos/echo';
+import { Markdown } from '@dxos/plugin-markdown';
+
+import { meta } from '#meta';
+
+const makeKey = (name: string) => DXN.make(`${meta.id}.operation.${name}`);
+
+// TODO(wittjosiah): This appears to be unused.
+export const TogglePresentation = Operation.make({
+  meta: {
+    key: makeKey('togglePresentation'),
+    name: 'Toggle Presentation',
+    icon: 'ph--presentation--regular',
+  },
+  input: Schema.Struct({
+    object: Schema.Union(Type.getSchema(Markdown.Document), Type.getSchema(Collection.Collection)),
+    state: Schema.optional(Schema.Boolean),
+  }),
+  output: Schema.Void,
+});

package/src/types/Settings.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+export const Settings = Schema.mutable(
+  Schema.Struct({
+    presentCollections: Schema.optional(
+      Schema.Boolean.annotations({
+        title: 'Present collections (experimental)',
+        description: 'Enable presenting collections of documents as a slideshow.',
+      }),
+    ),
+  }),
+);
+
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}

package/src/types/index.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+
+export type PresenterContextType = {
+  running: boolean;
+  start: () => void;
+  stop: () => void;
+};
+
+export const PresenterContext: Context<PresenterContextType> = createContext<PresenterContextType>({
+  running: false,
+  start: () => {},
+  stop: () => {},
+});
+
+export * as PresenterCapabilities from './PresenterCapabilities';
+export * as PresenterOperation from './PresenterOperation';
+export * as Settings from './Settings';