@dxos/plugin-preview 0.8.2-main.10c050d

package/src/capabilities/preview-popover.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, LayoutAction, contributes, createIntent, type PluginContext } from '@dxos/app-framework';
+import { addEventListener } from '@dxos/async';
+import { type Client, resolveRef } from '@dxos/client';
+import { parseId, type Space } from '@dxos/client/echo';
+import { DXN } from '@dxos/keys';
+import { type DxRefTagActivate } from '@dxos/lit-ui';
+import { log } from '@dxos/log';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { type PreviewLinkRef, type PreviewLinkTarget } from '@dxos/react-ui-editor';
+
+const customEventOptions = { capture: true, passive: false };
+
+const handlePreviewLookup = async (
+  client: Client,
+  defaultSpace: Space,
+  { ref, label }: PreviewLinkRef,
+): Promise<PreviewLinkTarget | null> => {
+  const dxn = DXN.parse(ref);
+  if (!dxn) {
+    return null;
+  }
+
+  const object = await resolveRef(client, dxn, defaultSpace);
+  return { label, object };
+};
+
+export default (context: PluginContext) => {
+  // TODO(wittjosiah): Factor out lookup handlers to other plugins to make not ECHO-specific.
+  const handleDxRefTagActivate = async ({ refId, label, trigger }: DxRefTagActivate) => {
+    const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
+    const client = context.getCapability(ClientCapabilities.Client);
+    const [layout] = context.getCapabilities(Capabilities.Layout);
+    const { spaceId } = parseId(layout.workspace);
+    const space = (spaceId && client.spaces.get(spaceId)) ?? client.spaces.default;
+    const result = await handlePreviewLookup(client, space, { ref: refId, label });
+    if (!result) {
+      return;
+    }
+
+    await dispatch(
+      createIntent(LayoutAction.UpdatePopover, {
+        part: 'popover',
+        subject: result.object,
+        options: {
+          state: true,
+          variant: 'virtual',
+          anchor: trigger,
+        },
+      }),
+    );
+  };
+
+  let cleanup: () => void;
+  if (document.defaultView) {
+    cleanup = addEventListener(document.defaultView, 'dx-ref-tag-activate', handleDxRefTagActivate, customEventOptions);
+  } else {
+    log.warn('No default view found');
+  }
+
+  return contributes(Capabilities.Null, null, () => cleanup());
+};

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,126 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import {
+  Capabilities,
+  LayoutAction,
+  Surface,
+  contributes,
+  createIntent,
+  createSurface,
+  useIntentDispatcher,
+} from '@dxos/app-framework';
+import { Filter, fullyQualifiedId, getSchema, getSpace, isEchoObject, type AnyLiveObject } from '@dxos/client/echo';
+import { isInstanceOf, type JsonPath, setValue } from '@dxos/echo-schema';
+import { useTranslation } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+import { TableType } from '@dxos/react-ui-table';
+import { descriptionMessage } from '@dxos/react-ui-theme';
+import { DataType } from '@dxos/schema';
+
+import { ContactCard, OrganizationCard, ProjectCard } from '../components';
+import { PREVIEW_PLUGIN } from '../meta';
+import { kanbanCardWithoutPoster } from '../types';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, [
+    //
+    // Specific schema types.
+    //
+    createSurface({
+      id: `${PREVIEW_PLUGIN}/schema-popover--contact`,
+      role: ['popover', 'card--kanban', 'card'],
+      filter: (data): data is { subject: DataType.Person } => isInstanceOf(DataType.Person, data.subject),
+      component: ({ data, role }) => {
+        const { dispatchPromise: dispatch } = useIntentDispatcher();
+        const handleOrgClick = useCallback(
+          async (org: DataType.Organization) => {
+            const space = getSpace(org);
+            const tablesQuery = await space?.db.query(Filter.type(TableType)).run();
+            const currentSpaceOrgTable = tablesQuery?.objects.find((table) => {
+              return table.view?.target?.query?.typename === DataType.Organization.typename;
+            });
+            await dispatch(
+              createIntent(LayoutAction.UpdatePopover, {
+                part: 'popover',
+                options: {
+                  state: false,
+                  anchorId: '',
+                },
+              }),
+            );
+            if (currentSpaceOrgTable) {
+              return dispatch(
+                createIntent(LayoutAction.Open, {
+                  part: 'main',
+                  subject: [fullyQualifiedId(currentSpaceOrgTable)],
+                  options: { workspace: space?.id },
+                }),
+              );
+            }
+          },
+          [dispatch],
+        );
+        return (
+          <ContactCard subject={data.subject} onOrgClick={handleOrgClick} role={role}>
+            {role === 'popover' && <Surface role='related' data={data} />}
+          </ContactCard>
+        );
+      },
+    }),
+    createSurface({
+      id: `${PREVIEW_PLUGIN}/schema-popover--organization`,
+      role: ['popover', 'card--kanban', 'card'],
+      filter: (data): data is { subject: DataType.Organization } => isInstanceOf(DataType.Organization, data.subject),
+      component: ({ data, role }) => (
+        <OrganizationCard subject={data.subject} role={role}>
+          {role === 'popover' && <Surface role='related' data={data} />}
+        </OrganizationCard>
+      ),
+    }),
+    createSurface({
+      id: `${PREVIEW_PLUGIN}/schema-popover--project`,
+      role: ['popover', 'card--kanban', 'card'],
+      filter: (data): data is { subject: DataType.Project } => isInstanceOf(DataType.Project, data.subject),
+      component: ({ data, role }) => <ProjectCard subject={data.subject} role={role} />,
+    }),
+
+    //
+    // Fallback for any object.
+    //
+    createSurface({
+      id: `${PREVIEW_PLUGIN}/fallback-popover`,
+      role: ['popover', 'card--kanban', 'card'],
+      position: 'fallback',
+      filter: (data): data is { subject: AnyLiveObject<any> } => isEchoObject(data.subject),
+      component: ({ data, role }) => {
+        const schema = getSchema(data.subject);
+        const { t } = useTranslation(PREVIEW_PLUGIN);
+        if (!schema) {
+          return <p className={descriptionMessage}>{t('unable to create preview message')}</p>;
+        }
+
+        const handleSave = useCallback((values: any, { changed }: { changed: Record<string, boolean> }) => {
+          const changedPaths = Object.keys(changed).filter((path) => changed[path]);
+          for (const path of changedPaths) {
+            const value = values[path];
+            setValue(data.subject, path as JsonPath, value);
+          }
+        }, []);
+
+        return (
+          <Form
+            schema={schema}
+            values={data.subject}
+            readonly={role === 'popover'}
+            onSave={handleSave}
+            autoSave
+            {...(role === 'card--kanban' && { classNames: kanbanCardWithoutPoster })}
+          />
+        );
+      },
+    }),
+  ]);

package/src/components/ContactCard.tsx

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { Fragment } from 'react';
+
+import { Icon, Avatar, Button } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+import { type DataType } from '@dxos/schema';
+
+import { type PreviewProps, popoverCard, previewTitle, previewProse, previewChrome, defaultCard } from '../types';
+
+export const ContactCard = ({
+  children,
+  classNames,
+  role,
+  subject: { fullName, image, organization, emails },
+  onOrgClick,
+}: PreviewProps<DataType.Person> & { onOrgClick?: (org: DataType.Organization) => void }) => {
+  const organizationName = organization && typeof organization === 'object' ? organization.target?.name : organization;
+  return (
+    <div role='none' className={mx(role === 'popover' ? popoverCard : defaultCard, classNames)}>
+      <Avatar.Root>
+        <div role='group' className={mx(previewProse, 'grid gap-3 grid-cols-[min-content_1fr]')}>
+          <Avatar.Content imgSrc={image} icon='ph--user--regular' size={16} hue='neutral' />
+          <div role='none' className='bs-min self-center'>
+            <Avatar.Label asChild>
+              <h2 className={previewTitle}>{fullName}</h2>
+            </Avatar.Label>
+          </div>
+        </div>
+      </Avatar.Root>
+      {organizationName && (
+        <div role='none' className={previewChrome}>
+          {typeof organization === 'object' && onOrgClick ? (
+            <Button variant='ghost' classNames='gap-2 text-start' onClick={() => onOrgClick(organization.target!)}>
+              <Icon icon='ph--buildings--regular' size={5} classNames='text-subdued' />
+              <span className='min-is-0 flex-1 truncate'>{organizationName}</span>
+              <Icon icon='ph--arrow-right--regular' />
+            </Button>
+          ) : (
+            <p className='dx-button gap-2' data-variant='ghost'>
+              <Icon icon='ph--buildings--regular' size={5} classNames='text-subdued' />
+              <span className='min-is-0 flex-1 truncate'>{organizationName}</span>
+            </p>
+          )}
+        </div>
+      )}
+      <dl
+        className={mx(
+          previewProse,
+          'grid gap-2 grid-cols-[min-content_1fr] [&_dt]:text-subdued [&_dt]:pbs-0.5 [&_dd]:min-is-0',
+        )}
+      >
+        {emails?.length &&
+          emails.map(({ label, value }) => (
+            <Fragment key={value}>
+              <dt>
+                <Icon icon='ph--at--regular' size={5} />
+              </dt>
+              <dd key={value} className='break-words'>
+                {value}
+              </dd>
+            </Fragment>
+          ))}
+      </dl>
+      {children}
+    </div>
+  );
+};

package/src/components/OrganizationCard.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Icon } from '@dxos/react-ui';
+import { mx } from '@dxos/react-ui-theme';
+import { type DataType } from '@dxos/schema';
+
+import { type PreviewProps, popoverCard, previewTitle, previewProse, previewChrome, defaultCard } from '../types';
+
+export const OrganizationCard = ({
+  children,
+  classNames,
+  subject: { name, image, description, website },
+  role,
+}: PreviewProps<DataType.Organization>) => {
+  return (
+    <div role='none' className={mx(role === 'popover' ? popoverCard : defaultCard, classNames)}>
+      {image ? (
+        <img className='aspect-video object-cover is-full bs-auto' src={image} alt={name} />
+      ) : (
+        <div role='image' className='grid aspect-video place-items-center bg-inputSurface text-subdued'>
+          <Icon icon='ph--building-office--regular' size={10} />
+        </div>
+      )}
+      <h2 className={mx(previewTitle, previewProse)}>{name}</h2>
+      {description && <p className={mx(previewProse, 'line-clamp-2')}>{description}</p>}
+      {website && (
+        <div role='none' className={previewChrome}>
+          <a
+            className='dx-button dx-focus-ring gap-2'
+            data-variant='ghost'
+            href={website}
+            target='_blank'
+            rel='noreferrer'
+          >
+            <Icon icon='ph--link--regular' size={5} classNames='text-subdued' />
+            <span className='grow'>{website}</span>
+            <Icon icon='ph--arrow-square-out--regular' />
+          </a>
+        </div>
+      )}
+      {children}
+    </div>
+  );
+};

package/src/components/ProjectCard.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { mx } from '@dxos/react-ui-theme';
+import { type DataType } from '@dxos/schema';
+
+import { type PreviewProps, popoverCard, previewTitle, defaultCard } from '../types';
+
+export const ProjectCard = ({
+  classNames,
+  role,
+  subject: { name, image, description },
+}: PreviewProps<DataType.Project>) => {
+  return (
+    <div role='none' className={mx(role === 'popover' ? popoverCard : defaultCard, classNames)}>
+      {image && <img className='is-full bs-auto' src={image} alt={name} />}
+      <h2 className={mx(previewTitle, 'pli-3 mlb-3')}>{name}</h2>
+      {description && <p className='pli-3 line-clamp-2 mlb-3'>{description}</p>}
+    </div>
+  );
+};

package/src/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ContactCard';
+export * from './OrganizationCard';
+export * from './ProjectCard';

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './meta';
+export * from './types';
+
+export * from './PreviewPlugin';

package/src/meta.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type PluginMeta } from '@dxos/app-framework';
+
+export const PREVIEW_PLUGIN = 'dxos.org/plugin/preview';
+
+export const meta: PluginMeta = {
+  id: PREVIEW_PLUGIN,
+  name: 'Preview',
+  icon: 'ph--eye--regular',
+  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-preview',
+};

package/src/translations.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { PREVIEW_PLUGIN } from './meta';
+
+export default [
+  {
+    'en-US': {
+      [PREVIEW_PLUGIN]: {
+        'unable to create preview message': 'No preview',
+      },
+    },
+  },
+];

package/src/types.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type PropsWithChildren } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+
+// TODO(burdon): Better place for these defs?
+export type PreviewProps<T extends object> = PropsWithChildren<
+  ThemedClassName<{
+    subject: T;
+    role: string;
+  }>
+>;
+
+// TODO(burdon): Update react-ui-card (to use grid) and re-use here.
+// - See https://dxos-storybook.pages.dev/?path=/story/ui-react-ui-card-card--draggable
+// - Standardize Header, actions, image, body, etc.
+// - Support different grid layouts (e.g., image to the side, on top, etc.)
+// - Should co-exist naturally with react-ui-form (e.g., as main content).
+// - Considerations for drag-and-drop.
+/**
+ * <Card.Root>
+ *   <Card.Header>
+ *     <Card.Title>
+ *     <Card.Action>
+ *   </Card.Header>
+ *   <Card.Body>
+ *     <Card.Image>
+ *     <Form />
+ *   </Card.Body>
+ * </Card.Root>
+ */
+export const popoverCard = 'popover-card-width rounded-lg overflow-hidden';
+export const defaultCard = '';
+export const kanbanCardWithoutPoster = 'pbs-[--rail-action]';
+export const previewTitle = 'text-lg font-medium line-clamp-2';
+export const previewProse = 'pli-3 mlb-3';
+export const previewChrome = 'pli-1.5 mlb-1.5 [&_.dx-button]:pli-1.5 [&_.dx-button]:text-start [&_.dx-button]:is-full';