Add a surface

By the end of this page a link has a view, where a person can edit its title, address and note, and see whether they have read it.

Background

A surface is a named place in an app’s UI, such as the main article area, a card or the status bar. Plugins fill surfaces by contributing a component and a filter that says which data the component can render. When Composer opens a link in the article area, it asks for every component that matches the article role and a link, and renders the best one. Surfaces explains the matching.

Steps

1. Write the component. The article surface passes the object as subject. useObject returns a snapshot of it and re-renders the component when it changes, whether the change came from this tab, another device or the assistant. Writes go through Obj.update, like any ECHO write.

   src/containers/StashedLinkArticle.tsx

   import type * as AppSurface from '@dxos/app-toolkit/AppSurface';
   import { Obj } from '@dxos/echo';
   import { useObject } from '@dxos/echo-react';
   import * as Input from '@dxos/react-ui/Input';
   import * as Layout from '@dxos/react-ui/Layout';
   import * as Panel from '@dxos/react-ui/Panel';
   
   import { type StashedLink } from '../types/StashedLink.ts';
   
   export type StashedLinkArticleProps =
     AppSurface.ObjectArticleProps<StashedLink>;
   
   export const StashedLinkArticle = ({
     role,
     subject,
   }: StashedLinkArticleProps) => {
     // A snapshot that re-renders the component when the object changes, here or
     // on another peer.
     const [link] = useObject(subject);
   
     return (
       <Panel.Root role={role}>
         <Panel.Body asChild>
           <Layout.Flex column gap='sm' classNames='p-2'>
             <Input.Root
               placeholder='Title'
               value={link.title ?? ''}
               onChange={(event) =>
                 Obj.update(subject, (subject) => {
                   subject.title = event.target.value;
                 })
               }
             />
             <Input.Root
               placeholder='https://'
               value={link.url ?? ''}
               onChange={(event) =>
                 Obj.update(subject, (subject) => {
                   subject.url = event.target.value;
                 })
               }
             />
             <Input.Textarea
               placeholder='Why is this worth keeping?'
               value={link.note ?? ''}
               onChange={(event) =>
                 Obj.update(subject, (subject) => {
                   subject.note = event.target.value;
                 })
               }
             />
             <p className='text-description'>
               {link.read ? 'Read' : 'Not read yet'}
             </p>
           </Layout.Flex>
         </Panel.Body>
       </Panel.Root>
     );
   };
   
   

   Panel.Root with the surface’s role gives the view the standard article layout.

2. Contribute the surface. AppSurface.object(AppSurface.Article, StashedLink) matches the article role when the subject is a link. props maps the surface’s data onto the component’s props, and is type-checked against the filter.

   src/capabilities/react-surface.ts

   import * as Effect from 'effect/Effect';
   
   import * as Capabilities from '@dxos/app-framework/Capabilities';
   import * as Capability from '@dxos/app-framework/Capability';
   import * as Surface from '@dxos/app-framework/Surface';
   import * as AppSurface from '@dxos/app-toolkit/AppSurface';
   
   import { StashedLinkArticle } from '../containers/StashedLinkArticle.tsx';
   import { StashedLink } from '../types/StashedLink.ts';
   
   export default Capability.makeModule(() =>
     Effect.succeed(
       Capability.contribute(
         Capabilities.ReactSurface,
         Surface.create({
           id: 'article',
           filter: AppSurface.object(AppSurface.Article, StashedLink),
           component: StashedLinkArticle,
           props: ({ role, data: { subject, attendableId } }) => ({
             role,
             subject,
             attendableId,
           }),
         }),
       ),
     ),
   );
   
   

3. Add the module to the manifest. The roles list lets the plugin manager load the module only when it first needs an article surface.

   dx.config.ts

   import * as AppCapability from '@dxos/app-toolkit/AppCapability';
   import * as AppSurface from '@dxos/app-toolkit/AppSurface';
   import * as SpaceCapability from '@dxos/plugin-space/SpaceCapability';
   
   import { StashNamespace } from './src/namespace.ts';
   
   const config: Plugin.PluginConfig = Plugin.config({
     plugin: {
       key: StashNamespace.key,
       name: 'Stash',
       author: 'Example',
       description:
         'A reading list: save links with a note, and mark them as read.',
       icon: { key: 'ph--tray-arrow-down--regular', hue: 'indigo' },
       tags: ['labs'],
     },
     modules: [
       AppCapability.translations(
         () => import('./src/translations.ts', { with: { type: 'module-url' } }),
       ),
       AppCapability.schema(
         () =>
           import('./src/capabilities/schema.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.operationHandler(
         () =>
           import('./src/capabilities/operation-handler.ts', {
             with: { type: 'module-url' },
           }),
       ),
       SpaceCapability.createObject(
         () =>
           import('./src/capabilities/create-object.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.appGraphBuilder(
         () =>
           import('./src/capabilities/app-graph-builder.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.surface(
         () =>
           import('./src/capabilities/react-surface.ts', {
             with: { type: 'module-url' },
           }),
         {
           roles: [AppSurface.Article],
         },
       ),
   
   

4. See the view. Load or reload your plugin below, click New in the header to create a sample link, and select Surface. The inspector renders each of the module’s surfaces whose filter accepts the sample: here, the article.

   Edit the title in the article’s input, and the name in the header changes as you type. In Composer the same view fills the main area when a person opens a link.

What you can do now

• Read an object reactively in a component and write it with Obj.update.
• Contribute an article surface for a type.
• Load a surface module only when its role is needed.

Run it in Composer loads the plugin into Composer from your machine, and gives the assistant Mark as read.