React

import * as Hooks from '@dxos/app-framework/Hooks';

A plugin’s components read capabilities, invoke operations and read settings through hooks. They work in any component under the app’s plugin manager, which every surface is.

Read capabilities from a component

useCapability returns a singleton capability, and useCapabilities every contribution to a multi capability. Both re-render when contributions change. useOptionalCapability returns undefined when no plugin provides it.

import * as Capabilities from '@dxos/app-framework/Capabilities';
import * as Hooks from '@dxos/app-framework/Hooks';

export const SurfaceCount = () => {
  // Every contribution to a multi capability, re-rendering when plugins add or
  // remove one.
  const surfaces = Hooks.useCapabilities(Capabilities.ReactSurface);
  return <span>{surfaces.length}</span>;
};

Invoke operations from a component

useOperation binds an operation to a callback; its argument maps the callback’s arguments to the operation’s input. useOperationInvoker returns the invoker, whose invokePromise returns the operation’s output.

import { useCallback } from 'react';
import * as Hooks from '@dxos/app-framework/Hooks';
import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
import * as Button from '@dxos/react-ui/Button';

export const OpenButton = ({ path }: { path: string }) => {
  const open = Hooks.useOperation(LayoutOperation.Open, () => ({
    subject: [path],
  }));
  return <Button.Root onClick={() => open()}>Open</Button.Root>;
};

export const OpenTwice = ({ path }: { path: string }) => {
  const { invokePromise } = Hooks.useOperationInvoker();
  const handleClick = useCallback(async () => {
    await invokePromise(LayoutOperation.Open, { subject: [path] });
  }, [invokePromise, path]);
  return <Button.Root onClick={handleClick}>Open</Button.Root>;
};

Read plugin settings and translations

useAtomCapability reads an atom capability, such as a plugin’s settings, and re-renders when it changes. useAtomCapabilityState also returns a setter. useTranslation from @dxos/react-ui/Hooks takes the plugin’s namespace.

import * as Hooks from '@dxos/app-framework/Hooks';
import * as Button from '@dxos/react-ui/Button';
import * as UiHooks from '@dxos/react-ui/Hooks';

export const CompactToggle = () => {
  const [settings, setSettings] = Hooks.useAtomCapabilityState(Settings);
  const { t } = UiHooks.useTranslation('com.example.plugin.notes');
  return (
    <Button.Root
      onClick={() =>
        setSettings((current) => ({ ...current, compact: !current.compact }))
      }
    >
      {settings.compact ? t('expand.label') : t('compact.label')}
    </Button.Root>
  );
};

@dxos/app-toolkit/Hooks adds hooks for app state, such as useActiveSpace, useAppGraph and useLayout.

The reactivity rules

• Reading an ECHO object’s field in render does not subscribe the component. Use useObject for a snapshot that does, and useQuery for a list. See the ECHO React guide.
• Write objects inside Obj.update, from an event handler or an operation, never during render.
• A component never assumes it is the only view of an object. The same object can be open in another plank, on another device, or in the assistant’s hands.

import { useCallback } from 'react';
import * as ToolkitHooks from '@dxos/app-toolkit/Hooks';
import { Obj } from '@dxos/echo';
import { useObject } from '@dxos/echo-react';
import * as Button from '@dxos/react-ui/Button';

export const NoteTitle = ({ note }: { note: Note }) => {
  // Reading `note.title` in render does not subscribe. `useObject` returns a
  // snapshot that does.
  const [snapshot] = useObject(note);
  const space = ToolkitHooks.useActiveSpace();
  const rename = useCallback(
    () => Obj.update(note, (note) => (note.title = 'Renamed')),
    [note],
  );
  return (
    <Button.Root onClick={rename} data-testid={space?.id}>
      {snapshot.title}
    </Button.Root>
  );
};

Related

Page	What it covers
Surface	Where these components render.
Operation	Defining the operations a component invokes.