@dxos/plugin-preview 0.8.4-main.d05673bc65 → 0.8.4-main.d9fc60f731

package/src/cards/FormCard.tsx

@@ -2,47 +2,114 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Schema from 'effect/Schema';
 import React, { useCallback, useMemo } from 'react';
 
-import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
-import { Obj } from '@dxos/echo';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj, Type } from '@dxos/echo';
+import { useType } from '@dxos/echo-react';
+import { type AnyProperties } from '@dxos/echo/internal';
 import { type JsonPath, splitJsonPath } from '@dxos/effect';
 import { Card, useTranslation } from '@dxos/react-ui';
-import { Form, omitId } from '@dxos/react-ui-form';
+import { Form, type FormUpdateMeta, type Presentation, getFormProperties, omitId } from '@dxos/react-ui-form';
 import { type ProjectionModel } from '@dxos/schema';
-import { descriptionMessage, mx } from '@dxos/ui-theme';
 
-import { meta } from '../meta';
+import { meta } from '#meta';
 
-export const FormCard = ({ subject, projection }: SurfaceComponentProps & { projection?: ProjectionModel }) => {
+export type FormCardProps = AppSurface.ObjectCardProps & {
+  projection?: ProjectionModel;
+  readonly?: boolean;
+  layout?: Presentation;
+};
+
+/**
+ * Default/fallback card for any ECHO object.
+ * Renders a `Form` against the object's schema — either the static schema
+ * from `Obj.getSchema` or, for runtime/mutable schemas, the reactive
+ * schema looked up via `useType`.
+ */
+export const FormCard = ({ subject, projection, readonly = true, layout }: FormCardProps) => {
   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.change(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>;
+  // Readonly cards default to the `static` presentation — plain DOM, undefined values
+  // omitted — which reads as a preview rather than a form. Editable cards keep the
+  // `compact` form layout. Callers can override either via the explicit `layout` prop.
+  const resolvedLayout: Presentation = layout ?? (readonly ? 'static' : 'compact');
+
+  // Try the static schema first; fall back to the runtime/database schema for
+  // dynamic types whose schema isn't reachable via `Obj.getSchema` (DXN mismatch).
+  const staticType = Obj.getType(subject);
+  const db = Obj.getDatabase(subject);
+  const typename = Obj.getTypename(subject);
+  const runtimeType = useType(db, staticType ? undefined : typename);
+  const schema = useMemo((): Schema.Schema.AnyNoContext | undefined => {
+    const resolvedType = runtimeType ?? staticType;
+    return resolvedType ? omitId(Type.getSchema(resolvedType)) : undefined;
+  }, [runtimeType, staticType]);
+
+  // Predict whether the form would render anything visible. Without this guard,
+  // readonly + compact mode produces an empty scrollarea when every form-renderable
+  // field is unset (e.g., a Table object whose `view`/`sizes` are FormInput-hidden
+  // and whose `name` is undefined).
+  //
+  // - In editable mode (`!readonly`), the form renders empty fields, so we only
+  //   bail when there are no form-renderable properties at all.
+  // - In readonly mode, the form hides fields with null/undefined values, so we
+  //   bail when no form-renderable property has a non-null value.
+  const hasRenderableContent = useMemo(() => {
+    if (!schema) {
+      return false;
+    }
+    const properties = getFormProperties(schema.ast);
+    if (properties.length === 0) {
+      return false;
+    }
+    if (!readonly) {
+      return true;
+    }
+    return properties.some((prop) => (subject as any)?.[prop.name] != null);
+  }, [schema, subject, readonly]);
+
+  const handleSave = useCallback(
+    (values: AnyProperties, { changed }: FormUpdateMeta<AnyProperties>) => {
+      const paths = (Object.keys(changed) as JsonPath[]).filter((path) => changed[path]);
+      Obj.update(subject, () => {
+        for (const path of paths) {
+          const parts = splitJsonPath(path);
+          const value = Obj.getValue(values as any, parts);
+          Obj.setValue(subject, parts, value);
+        }
+      });
+    },
+    [subject],
+  );
+
+  if (!schema || !hasRenderableContent) {
+    return (
+      <Card.Body>
+        <Card.Row>
+          <Card.Text variant='description'>{t('unable-to-create-preview.message')}</Card.Text>
+        </Card.Row>
+      </Card.Body>
+    );
   }
 
   return (
-    <Card.Content>
-      <Form.Root schema={schema} projection={projection} values={subject} autoSave onSave={handleSave}>
+    <Card.Body>
+      <Form.Root
+        schema={schema}
+        projection={projection}
+        values={subject}
+        readonly={readonly}
+        layout={resolvedLayout}
+        autoSave
+        onSave={handleSave}
+      >
         <Form.Viewport>
           <Form.Content>
             <Form.FieldSet />
           </Form.Content>
         </Form.Viewport>
       </Form.Root>
-    </Card.Content>
+    </Card.Body>
   );
 };

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.Body>
+      <span />
+      {/* TODO(wittjosiah): Span whole row. */}
+      <JsonHighlighter data={data} />
+      <span />
+    </Card.Body>
+  );
+};

package/src/cards/OrganizationCard.tsx

@@ -4,15 +4,15 @@
 
 import React from 'react';
 
-import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
 import { Card } from '@dxos/react-ui';
 import { type Organization } from '@dxos/types';
 
-export const OrganizationCard = ({ subject }: SurfaceComponentProps<Organization.Organization>) => {
-  const { image, description, website } = subject;
+export const OrganizationCard = ({ subject }: AppSurface.ObjectCardProps<Organization.Organization>) => {
+  const { name, image, description, website } = subject;
 
   return (
-    <Card.Content>
+    <Card.Body>
       <Card.Poster
         alt={name ?? ''}
         {...(image ? { image } : { icon: 'ph--building-office--regular' })}
@@ -24,6 +24,6 @@ export const OrganizationCard = ({ subject }: SurfaceComponentProps<Organization
         </Card.Row>
       )}
       {website && <Card.Link label={website} href={website} />}
-    </Card.Content>
+    </Card.Body>
   );
 };

package/src/cards/PersonCard.tsx

@@ -2,25 +2,47 @@
 // Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
 
-import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
+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 }: SurfaceComponentProps<Person.Person>) => {
+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>
+    <Card.Body>
       <Avatar.Root>
         {image && (
           <Card.Row className='py-1'>
             <Avatar.Content
               imgSrc={image}
               icon='ph--user--regular'
-              size={16}
+              size={20}
               classNames={!image && 'opacity-50'}
               hue='neutral'
               variant='square'
@@ -28,11 +50,7 @@ export const PersonCard = ({ subject }: SurfaceComponentProps<Person.Person>) =>
           </Card.Row>
         )}
         {organization?.name && (
-          <Card.Action
-            icon='ph--buildings--regular'
-            label={organization.name}
-            // onClick={onSelect ? () => onSelect(organization) : undefined}
-          />
+          <Card.Action icon='ph--buildings--regular' label={organization.name} onClick={handleOrganizationClick} />
         )}
         {emails.map(({ value }) => (
           <Card.Row key={value} icon='ph--at--regular'>
@@ -42,6 +60,6 @@ export const PersonCard = ({ subject }: SurfaceComponentProps<Person.Person>) =>
           </Card.Row>
         ))}
       </Avatar.Root>
-    </Card.Content>
+    </Card.Body>
   );
 };

package/src/cards/ProjectCard.tsx

@@ -4,19 +4,19 @@
 
 import React from 'react';
 
-import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
+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 }: SurfaceComponentProps<Pipeline.Pipeline>) => {
+export const ProjectCard = ({ subject }: AppSurface.ObjectCardProps<Pipeline.Pipeline>) => {
   const { image, description } = subject;
 
   return (
-    <Card.Content>
+    <Card.Body>
       {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>
+    </Card.Body>
   );
 };

package/src/cards/TaskCard.tsx

@@ -5,36 +5,41 @@
 import * as SchemaAST from 'effect/SchemaAST';
 import React from 'react';
 
-import { type SurfaceComponentProps } from '@dxos/app-toolkit/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Type } from '@dxos/echo';
 import { type PropertyMetaAnnotation, PropertyMetaAnnotationId } from '@dxos/echo/internal';
 import { Card } from '@dxos/react-ui';
 import { Task } from '@dxos/types';
 
-export const TaskCard = ({ subject }: SurfaceComponentProps<Task.Task>) => {
+export const TaskCard = ({ subject }: AppSurface.ObjectCardProps<Task.Task>) => {
   const { title, status } = subject;
   const statusOption = getActiveStatusOption(status);
 
   return (
-    <Card.Content>
-      <Card.Heading classNames='min-w-0 flex-1 truncate'>{title}</Card.Heading>
-      {statusOption && (
-        <span className='dx-tag' data-hue={statusOption.color}>
-          {statusOption.title}
-        </span>
-      )}
-    </Card.Content>
+    <Card.Body>
+      <Card.Row>
+        {statusOption && (
+          <div>
+            <span className='dx-tag' data-hue={statusOption.color}>
+              {statusOption.title}
+            </span>
+          </div>
+        )}
+      </Card.Row>
+    </Card.Body>
   );
 };
 
 // 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 properties = SchemaAST.getPropertySignatures(Type.getSchema(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)(
-    // TODO(thure): Typescript asserts `.type` doesn’t have `.types`, but in runtime it does.
     (statusProperty!.type as any).types[0],
   );
-  const options = // TODO(thure): Typescript asserts `statusMeta` doesn’t have `.value`, but in runtime it does.
-    (statusMeta as any).value.singleSelect.options as { id: string; title: string; color: string }[];
+
+  // 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

@@ -2,7 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './ExpandoCard';
 export * from './FormCard';
+export * from './JsonCard';
 export * from './OrganizationCard';
 export * from './PersonCard';
 export * from './ProjectCard';

package/src/index.ts

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

package/src/meta.ts

@@ -2,16 +2,19 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
-export const meta: Plugin.Meta = {
-  id: 'org.dxos.plugin.preview',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.preview'),
   name: 'Preview',
+  author: 'DXOS',
   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',
-};
+  tags: ['system'],
+});

package/src/plugin.ts

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

package/src/stories/Card.stories.tsx

@@ -3,24 +3,41 @@
 //
 
 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 { faker } from '@dxos/random';
+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 { FormCard, OrganizationCard, PersonCard, ProjectCard, TaskCard } from '../cards';
-import { translations } from '../translations';
+import { translations } from '#translations';
 
-import { DefaultStory, createOrganization, createPerson, createProject, createTask } from './testing';
+import { ExpandoCard, FormCard, JsonCard, OrganizationCard, PersonCard, ProjectCard, TaskCard } from '../cards';
+import {
+  DefaultStory,
+  createExpando,
+  createOrganization,
+  createPerson,
+  createPersonEmpty,
+  createProject,
+  createTableEmpty,
+  createTask,
+  createUnknown,
+} from './testing';
 
-faker.seed(999);
+random.seed(999);
 
 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.
@@ -43,6 +60,52 @@ export const _Form: StoryObj<typeof DefaultStory<Person.Person>> = {
   },
 };
 
+export const _FormEditable: StoryObj<typeof DefaultStory<Person.Person>> = {
+  args: {
+    Component: FormCard,
+    createObject: createPerson,
+    image: true,
+    componentProps: { readonly: false, layout: 'full' },
+  },
+};
+
+/**
+ * Empty-state variant: the subject has no resolvable schema so `FormCard` renders
+ * `<Card.Body><Card.Row><Card.Text variant='description'>No preview</Card.Text></Card.Row></Card.Body>`.
+ * Use this story to verify the empty message lands in the card's center column.
+ */
+export const _FormEmpty: StoryObj<typeof DefaultStory> = {
+  args: {
+    Component: FormCard,
+    createObject: createUnknown,
+  },
+};
+
+/**
+ * No-values variant: the subject has a valid schema (Person) but no populated
+ * fields, so `FormCard` falls through to the same empty state instead of
+ * rendering an empty scrollarea.
+ */
+export const _FormNoValues: StoryObj<typeof DefaultStory<Person.Person>> = {
+  args: {
+    Component: FormCard,
+    createObject: createPersonEmpty,
+  },
+};
+
+/**
+ * Table-like variant: the subject has values only in form-hidden fields
+ * (`view`, `sizes` annotated `FormInputAnnotation.set(false)`). `FormCard`
+ * must consult the schema's form-input annotations — not just `Object.keys` —
+ * to recognize this case and fall through to the empty state.
+ */
+export const _FormTableEmpty: StoryObj<typeof DefaultStory<any>> = {
+  args: {
+    Component: FormCard,
+    createObject: createTableEmpty,
+  },
+};
+
 export const _Person: StoryObj<typeof DefaultStory<Person.Person>> = {
   args: {
     Component: PersonCard,
@@ -74,3 +137,41 @@ export const _Task: StoryObj<typeof DefaultStory<Task.Task>> = {
     image: true,
   },
 };
+
+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.Header>
+              <Card.IconBlock />
+              <Card.Title>JSON</Card.Title>
+            </Card.Header>
+            <JsonCard data={data} />
+          </Card.Root>
+        </div>
+      </div>
+    );
+  },
+};