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

package/src/cards/ExpandoCard.tsx

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import React, { useCallback, useMemo } from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { type JsonPath, splitJsonPath } from '@dxos/effect';
+import { Card } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+const schemaForValue = (value: unknown): Schema.Schema.AnyNoContext | undefined => {
+  switch (typeof value) {
+    case 'string':
+      return Schema.String;
+    case 'number':
+      return Schema.Number;
+    case 'boolean':
+      return Schema.Boolean;
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Reserved keys: `id`, plus any `~`-prefixed key (ECHO uses `~`-prefixed
+ * string keys to brand entity instances and schemas — KindId,
+ * SchemaKindId, SnapshotKindId, etc. — and the `~` namespace is reserved
+ * for that purpose). They show up in `Object.keys` but aren't user data.
+ */
+const isInternalKey = (key: string) => key === 'id' || key.startsWith('~');
+
+export const ExpandoCard = ({ subject, ignorePaths }: AppSurface.ObjectCardProps) => {
+  const schema = useMemo(() => {
+    const ignored = new Set(ignorePaths ?? []);
+    const fields: Record<string, Schema.Schema.AnyNoContext> = {};
+    for (const key of Object.keys(subject)) {
+      if (isInternalKey(key) || ignored.has(key)) {
+        continue;
+      }
+      const fieldSchema = schemaForValue((subject as any)[key]);
+      if (fieldSchema) {
+        fields[key] = fieldSchema;
+      }
+    }
+    return Schema.Struct(fields);
+  }, [subject, ignorePaths]);
+
+  const handleSave = useCallback(
+    (values: any, { changed }: { changed: Record<string, boolean> }) => {
+      const paths = Object.keys(changed).filter((path) => changed[path]);
+      Obj.update(subject, () => {
+        for (const path of paths) {
+          const value = values[path];
+          const parts = splitJsonPath(path as JsonPath);
+          Obj.setValue(subject, parts, value);
+        }
+      });
+    },
+    [subject],
+  );
+
+  return (
+    <Card.Content>
+      <Form.Root schema={schema} values={subject} autoSave onSave={handleSave}>
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </Card.Content>
+  );
+};

package/src/cards/FormCard.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { type JsonPath, splitJsonPath } from '@dxos/effect';
+import { Card, useTranslation } from '@dxos/react-ui';
+import { Form, omitId } from '@dxos/react-ui-form';
+import { type ProjectionModel } from '@dxos/schema';
+import { descriptionMessage, mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+export const FormCard = ({ subject, projection }: AppSurface.ObjectCardProps & { projection?: ProjectionModel }) => {
+  const { t } = useTranslation(meta.id);
+  const echoSchema = Obj.getSchema(subject);
+  const schema = useMemo(() => echoSchema && omitId(echoSchema), [echoSchema]);
+
+  const handleSave = useCallback((values: any, { changed }: { changed: Record<string, boolean> }) => {
+    const paths = Object.keys(changed).filter((path) => changed[path]);
+    Obj.update(subject, () => {
+      for (const path of paths) {
+        const value = values[path];
+        const parts = splitJsonPath(path as JsonPath);
+        Obj.setValue(subject, parts, value);
+      }
+    });
+  }, []);
+
+  if (!schema) {
+    return <p className={mx(descriptionMessage)}>{t('unable-to-create-preview.message')}</p>;
+  }
+
+  return (
+    <Card.Content>
+      <Form.Root schema={schema} projection={projection} values={subject} autoSave onSave={handleSave}>
+        <Form.Viewport>
+          <Form.Content>
+            <Form.FieldSet />
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    </Card.Content>
+  );
+};

package/src/cards/JsonCard.tsx

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Card } from '@dxos/react-ui';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+
+export const JsonCard = ({ data }: { data: unknown }) => {
+  return (
+    <Card.Content>
+      <span />
+      {/* TODO(wittjosiah): Span whole row. */}
+      <JsonHighlighter data={data} />
+      <span />
+    </Card.Content>
+  );
+};

package/src/cards/OrganizationCard.tsx

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Card } from '@dxos/react-ui';
+import { type Organization } from '@dxos/types';
+
+export const OrganizationCard = ({ subject }: AppSurface.ObjectCardProps<Organization.Organization>) => {
+  const { name, image, description, website } = subject;
+
+  return (
+    <Card.Content>
+      <Card.Poster
+        alt={name ?? ''}
+        {...(image ? { image } : { icon: 'ph--building-office--regular' })}
+        classNames={!image && 'opacity-50'}
+      />
+      {description && (
+        <Card.Row>
+          <Card.Text variant='description'>{description}</Card.Text>
+        </Card.Row>
+      )}
+      {website && <Card.Link label={website} href={website} />}
+    </Card.Content>
+  );
+};

package/src/cards/PersonCard.tsx

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation, getObjectPathFromObject, getSpacePath } from '@dxos/app-toolkit';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { runAndForwardErrors } from '@dxos/effect';
+import { Avatar } from '@dxos/react-ui';
+import { Card } from '@dxos/react-ui';
+import { type Person } from '@dxos/types';
+
+export const PersonCard = ({ subject }: AppSurface.ObjectCardProps<Person.Person>) => {
+  const { invoke } = useOperationInvoker();
+  const { image, organization: { target: organization } = {}, emails = [] } = subject;
+
+  const handleOrganizationClick = useCallback(() => {
+    if (!organization) {
+      return;
+    }
+
+    return Effect.gen(function* () {
+      const organizationPath = getObjectPathFromObject(organization);
+      const db = Obj.getDatabase(organization);
+      yield* invoke(LayoutOperation.UpdatePopover, { state: false, anchorId: '' });
+      yield* invoke(LayoutOperation.Open, {
+        subject: [organizationPath],
+        workspace: db ? getSpacePath(db.spaceId) : undefined,
+      });
+    }).pipe(runAndForwardErrors);
+  }, [invoke, organization]);
+
+  return (
+    <Card.Content>
+      <Avatar.Root>
+        {image && (
+          <Card.Row className='py-1'>
+            <Avatar.Content
+              imgSrc={image}
+              icon='ph--user--regular'
+              size={20}
+              classNames={!image && 'opacity-50'}
+              hue='neutral'
+              variant='square'
+            />
+          </Card.Row>
+        )}
+        {organization?.name && (
+          <Card.Action icon='ph--buildings--regular' label={organization.name} onClick={handleOrganizationClick} />
+        )}
+        {emails.map(({ value }) => (
+          <Card.Row key={value} icon='ph--at--regular'>
+            <Card.Text truncate className='text-primary-text'>
+              {value}
+            </Card.Text>
+          </Card.Row>
+        ))}
+      </Avatar.Root>
+    </Card.Content>
+  );
+};

package/src/cards/ProjectCard.tsx

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { Card } from '@dxos/react-ui';
+import { type Pipeline } from '@dxos/types';
+
+export const ProjectCard = ({ subject }: AppSurface.ObjectCardProps<Pipeline.Pipeline>) => {
+  const { image, description } = subject;
+
+  return (
+    <Card.Content>
+      {image && <Card.Poster image={image} alt={Obj.getLabel(subject) ?? ''} aspect='auto' />}
+      {/* <CardHeader label={name} subject={subject} db={db} /> */}
+      {description && <Card.Text variant='description'>{description}</Card.Text>}
+    </Card.Content>
+  );
+};

package/src/cards/TaskCard.tsx

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SchemaAST from 'effect/SchemaAST';
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { type PropertyMetaAnnotation, PropertyMetaAnnotationId } from '@dxos/echo/internal';
+import { Card } from '@dxos/react-ui';
+import { Task } from '@dxos/types';
+
+export const TaskCard = ({ subject }: AppSurface.ObjectCardProps<Task.Task>) => {
+  const { title, status } = subject;
+  const statusOption = getActiveStatusOption(status);
+
+  return (
+    <Card.Content>
+      <Card.Row>
+        {statusOption && (
+          <div>
+            <span className='dx-tag' data-hue={statusOption.color}>
+              {statusOption.title}
+            </span>
+          </div>
+        )}
+      </Card.Row>
+    </Card.Content>
+  );
+};
+
+// TODO(thure): Should this move upstream as a helper? Is there an easier way to get options?
+const getActiveStatusOption = (status?: string) => {
+  const properties = SchemaAST.getPropertySignatures(Task.Task.ast);
+  const statusProperty = properties.find((p) => p.name === 'status');
+  // TODO(thure): Typescript asserts `.type` doesn’t have `.types`, but in runtime it does.
+  const statusMeta = SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(
+    (statusProperty!.type as any).types[0],
+  );
+
+  // TODO(thure): Typescript asserts `statusMeta` doesn’t have `.value`, but in runtime it does.
+  const options = (statusMeta as any).value.singleSelect.options as { id: string; title: string; color: string }[];
+  return options.find(({ id }) => id === status);
+};

package/src/cards/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ExpandoCard';
+export * from './FormCard';
+export * from './JsonCard';
+export * from './OrganizationCard';
+export * from './PersonCard';
+export * from './ProjectCard';
+export * from './TaskCard';

package/src/index.ts

@@ -3,6 +3,5 @@
 //
 
 export * from './meta';
-export type * from './types';
 
 export * from './PreviewPlugin';

package/src/meta.ts

@@ -2,13 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const PREVIEW_PLUGIN = 'dxos.org/plugin/preview';
-
-export const meta: PluginMeta = {
-  id: PREVIEW_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.preview',
   name: 'Preview',
+  description: trim`
+    Rich preview panel for viewing object content without opening full editors.
+    Quick peek at documents, images, and data with inline rendering.
+  `,
   icon: 'ph--eye--regular',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-preview',
 };

package/src/stories/Card.stories.tsx

@@ -2,52 +2,120 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { Card } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type Expando } from '@dxos/schema';
+import { type Organization, type Person, type Pipeline, type Task } from '@dxos/types';
 
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { translations } from '#translations';
 
-import { translations } from '../translations';
+import { ExpandoCard, FormCard, JsonCard, OrganizationCard, PersonCard, ProjectCard, TaskCard } from '../cards';
+import { DefaultStory, createExpando, createOrganization, createPerson, createProject, createTask } from './testing';
 
-import { Defaultstory, type DefaultstoryProps, createCards } from './testing';
+random.seed(999);
 
-const meta: Meta<DefaultstoryProps> = {
-  title: 'plugins/plugin-preview/Card',
-  render: Defaultstory,
-  decorators: [withTheme, withLayout({ fullscreen: true, classNames: 'flex flex-col justify-center' })],
-  parameters: { translations },
+const meta = {
+  title: 'plugins/plugin-preview/cards/Card',
+  render: DefaultStory,
+  decorators: [
+    // `Card` and its descendants in `@dxos/react-ui` consume `ThemeContext`
+    // for tx-token resolution; without this the stories trip the surface's
+    // `ErrorBoundary` with "Missing ThemeContext" and the storybook test
+    // assert-no-error fails.
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    // TODO(wittjosiah): Try to write story which does not depend on plugin manager.
+    withPluginManager({ plugins: corePlugins() }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
   tags: ['cards'],
-};
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-type Story = StoryObj<DefaultstoryProps>;
+export const _Form: StoryObj<typeof DefaultStory<Person.Person>> = {
+  args: {
+    Component: FormCard,
+    createObject: createPerson,
+    image: true,
+  },
+};
 
-export const Popover = {
+export const _Person: StoryObj<typeof DefaultStory<Person.Person>> = {
   args: {
-    role: 'card--popover',
-    cards: createCards(),
+    Component: PersonCard,
+    createObject: createPerson,
+    image: true,
   },
-} satisfies Story;
+};
 
-export const Intrinsic = {
+export const _Organization: StoryObj<typeof DefaultStory<Organization.Organization>> = {
   args: {
-    role: 'card--intrinsic',
-    cards: createCards(),
+    Component: OrganizationCard,
+    createObject: createOrganization,
+    image: true,
   },
-} satisfies Story;
+};
 
-export const Extrinsic = {
+export const _Project: StoryObj<typeof DefaultStory<Pipeline.Pipeline>> = {
   args: {
-    role: 'card--extrinsic',
-    cards: createCards(),
+    Component: ProjectCard,
+    createObject: createProject,
+    image: true,
   },
-} satisfies Story;
+};
 
-export const ExtrinsicNoImage = {
+export const _Task: StoryObj<typeof DefaultStory<Task.Task>> = {
   args: {
-    role: 'card--extrinsic',
-    cards: createCards(false),
+    Component: TaskCard,
+    createObject: createTask,
+    image: true,
   },
-} satisfies Story;
+};
+
+export const _Expando: StoryObj<typeof DefaultStory<Expando.Expando>> = {
+  args: {
+    Component: ExpandoCard,
+    createObject: createExpando,
+  },
+};
+
+export const _Json = {
+  render: () => {
+    const data = {
+      subject: {
+        id: random.string.uuid(),
+        name: random.person.fullName(),
+        email: random.internet.email(),
+        tags: [random.lorem.word(), random.lorem.word(), random.lorem.word()],
+        nested: {
+          count: random.number.int({ max: 100 }),
+          active: random.datatype.boolean(),
+        },
+      },
+    };
+
+    return (
+      <div className='flex justify-center p-16'>
+        <div className='dx-card-min-width dx-card-max-width'>
+          <Card.Root>
+            <Card.Toolbar>
+              <Card.IconBlock />
+              <Card.Title>JSON</Card.Title>
+            </Card.Toolbar>
+            <JsonCard data={data} />
+          </Card.Root>
+        </div>
+      </div>
+    );
+  },
+};

package/src/stories/testing.tsx

@@ -2,39 +2,43 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { Meta } from '@storybook/react-vite';
-import React, { type FC } from 'react';
+import React, { type FC, useMemo } from 'react';
 
+import { type AppSurface } from '@dxos/app-toolkit/ui';
 import { Obj, Ref } from '@dxos/echo';
-import { faker } from '@dxos/random';
-import { CardContainer } from '@dxos/react-ui-stack/testing';
-import { DataType } from '@dxos/schema';
+import { random } from '@dxos/random';
+import { Card } from '@dxos/react-ui';
+import { CardContainer, type CardContainerProps } from '@dxos/react-ui-mosaic/testing';
+import { Expando } from '@dxos/schema';
+import { Organization, Person, Pipeline, Task } from '@dxos/types';
 
-import { ContactCard, OrganizationCard, ProjectCard } from '../components';
-import { type PreviewProps } from '../types';
-
-faker.seed(1234);
-
-type CardProps<T extends object> = {
-  Component: FC<PreviewProps<T>>;
-  subject: T;
-  icon?: string;
+export type DefaultStoryProps<T extends Obj.Any> = {
+  Component: FC<AppSurface.ObjectCardProps<T>>;
+  createObject: () => T;
   image?: boolean;
 };
 
-export type DefaultstoryProps = {
-  role: 'card--popover' | 'card--intrinsic' | 'card--extrinsic' | 'card--transclusion';
-  cards: CardProps<any>[];
-};
+export const DefaultStory = <T extends Obj.Any>({ Component, createObject, image }: DefaultStoryProps<T>) => {
+  const object = useMemo(() => createObject(), [createObject]);
+  const roles: CardContainerProps['role'][] = ['intrinsic', 'popover'];
 
-export const Defaultstory: Meta<DefaultstoryProps>['render'] = ({ role, cards }) => {
   return (
-    <div className='grid grid-cols-3'>
-      {cards.map(({ Component, icon, image, subject }, i) => (
-        <div key={i} className='flex justify-center'>
-          <CardContainer icon={icon} role={role}>
-            <Component role={role} subject={image ? subject : omitImage(subject)} />
-          </CardContainer>
+    <div className='h-full w-full grid grid-cols-2 py-16 gap-8'>
+      {roles.map((role, i) => (
+        <div key={i} className='flex h-full justify-center overflow-hidden'>
+          <div className='flex flex-col gap-4 w-full items-center'>
+            <span className='text-sm text-description'>{role}</span>
+            <CardContainer role={role}>
+              <Card.Root border={false}>
+                <Card.Toolbar>
+                  <Card.DragHandle />
+                  <Card.Title>{Obj.getLabel(object)}</Card.Title>
+                  <Card.Menu />
+                </Card.Toolbar>
+                <Component role={role ?? 'card--content'} subject={image ? object : omitImage(object)} />
+              </Card.Root>
+            </CardContainer>
+          </div>
         </div>
       ))}
     </div>
@@ -43,61 +47,55 @@ export const Defaultstory: Meta<DefaultstoryProps>['render'] = ({ role, cards })
 
 export const omitImage = ({ image: _, ...rest }: any) => rest;
 
-// TODO(burdon): Test data should exercise the standard data generators.
-export const createCards = (image = true): CardProps<any>[] => {
-  const organization = Obj.make(DataType.Organization, {
-    name: faker.company.name(),
+/**
+ * Factory functions for creating test objects at render time.
+ */
+export const createOrganization = (): Organization.Organization => {
+  return Obj.make(Organization.Organization, {
+    name: random.company.name(),
     image:
       'https://plus.unsplash.com/premium_photo-1672116452571-896980a801c8?q=80&w=2671&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
-    website: faker.internet.url(),
-    description: faker.lorem.paragraph(),
+    website: random.internet.url(),
+    description: random.lorem.paragraph(),
   });
+};
 
-  const contact = Obj.make(DataType.Person, {
-    fullName: faker.person.fullName(),
+export const createPerson = (): Person.Person => {
+  const organization = createOrganization();
+  return Obj.make(Person.Person, {
+    fullName: random.person.fullName(),
     image:
       'https://plus.unsplash.com/premium_photo-1664536392779-049ba8fde933?q=80&w=2574&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
     organization: Ref.make(organization),
     emails: [
-      {
-        label: 'Work',
-        value: faker.internet.email(),
-      },
-      {
-        label: 'Work',
-        value: faker.internet.email(),
-      },
-      {
-        label: 'Work',
-        value: faker.internet.email(),
-      },
+      { label: 'Work', value: random.internet.email() },
+      { label: 'Work', value: random.internet.email() },
+      { label: 'Work', value: random.internet.email() },
     ],
   });
+};
 
-  const project = Obj.make(DataType.Project, {
-    name: faker.person.fullName(),
+export const createProject = (): Pipeline.Pipeline => {
+  return Obj.make(Pipeline.Pipeline, {
+    name: random.person.fullName(),
     image: 'https://dxos.network/dxos-logotype-blue.png',
-    description: faker.lorem.paragraph(),
+    description: random.lorem.paragraph(),
+    columns: [],
   });
+};
 
-  return [
-    {
-      Component: OrganizationCard,
-      subject: organization,
-      icon: 'ph--building-office--regular',
-      image,
-    },
-    {
-      Component: ContactCard,
-      subject: contact,
-      icon: 'ph--user--regular',
-      image,
-    },
-    {
-      Component: ProjectCard,
-      subject: project,
-      icon: 'ph--building--regular',
-      image,
-    },
-  ];
+export const createTask = (): Task.Task => {
+  return Obj.make(Task.Task, {
+    title: random.lorem.sentence(),
+    status: random.helpers.arrayElement(['todo', 'in-progress', 'done'] as const),
+  });
+};
+
+export const createExpando = (): Expando.Expando => {
+  return Expando.make({
+    name: random.person.fullName(),
+    email: random.internet.email(),
+    age: random.number.int({ min: 18, max: 80 }),
+    active: random.datatype.boolean(),
+  });
 };