@dxos/app-framework 0.10.0 → 0.11.0

package/src/ui/components/HomeSection/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './HomeSection';

package/src/ui/components/NamePopover/NamePopover.tsx

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, useState } from 'react';
+
+import { Button, Input, Popover } from '@dxos/react-ui';
+
+export type NamePopoverProps = PropsWithChildren<{
+  open: boolean;
+  placeholder: string;
+  /** Translated label for the submit button (e.g. "Create"). */
+  submitLabel: string;
+  onSubmit: (name: string) => void;
+  onCancel: () => void;
+}>;
+
+/**
+ * Name-entry popover anchored to its trigger (mirrors the object rename popover UX).
+ * Enter or the submit button commits — an empty name is allowed; Escape or dismissal cancels.
+ */
+export const NamePopover = ({ children, open, placeholder, submitLabel, onSubmit, onCancel }: NamePopoverProps) => {
+  const [value, setValue] = useState('');
+
+  const submit = () => {
+    onSubmit(value);
+    setValue('');
+  };
+
+  const cancel = () => {
+    onCancel();
+    setValue('');
+  };
+
+  return (
+    <Popover.Root open={open} onOpenChange={(next) => !next && cancel()}>
+      <Popover.Trigger asChild>{children}</Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content>
+          <div className='flex items-center gap-1 p-2'>
+            <Input.Root>
+              <Input.Label srOnly>{placeholder}</Input.Label>
+              <Input.TextInput
+                autoFocus
+                placeholder={placeholder}
+                value={value}
+                onChange={(event) => setValue(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter') {
+                    submit();
+                  } else if (event.key === 'Escape') {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    cancel();
+                  }
+                }}
+              />
+            </Input.Root>
+            <Button variant='primary' onClick={submit}>
+              {submitLabel}
+            </Button>
+          </div>
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+};
+
+NamePopover.displayName = 'NamePopover';

package/src/ui/components/NamePopover/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './NamePopover';

package/src/ui/components/Surface/DESIGN.md

@@ -0,0 +1,136 @@
+# Surface
+
+A Surface is a named region of the UI that is populated dynamically by plugins.
+The consumer declares _what kind_ of region it is (a role) and _what data_ it
+carries; the framework resolves which plugin-contributed component(s) render there.
+This decouples the shell/layout from the plugins that fill it.
+
+## Concepts
+
+- **RoleToken** (`makeType<TData>(nsid)`) — a typed dispatch key. Carries a role
+  NSID (e.g. `org.dxos.role.article`) plus a phantom `TData` so consumers
+  (`type={Token}`) and providers (`makeFilter(Token, guard)`) share one
+  type-level contract. Identity is structural: same `role` string ⇒ interchangeable.
+- **SurfaceFilter** (`makeFilter(token, guard?)`) — one or more `(role, guard)`
+  bindings. The guard validates the data shape at dispatch time; omitting it
+  matches any data at the role.
+- **Definition** — a registered contribution: `{ kind, id, role, position?, filter, … }`.
+  `kind: 'react'` carries a `component`; `kind: 'web-component'` carries a `tagName`.
+  Authored via `create` / `createWeb`; registered as the `Capabilities.ReactSurface`
+  capability.
+
+## Dispatch pipeline
+
+```text
+<Surface type={Token} data={…} limit?={n} />
+  └─ useSurfaces()            → role-indexed, position-sorted candidate map
+  └─ findCandidates(role,data)→ candidates for role, then data guard filter
+  └─ Suspense
+       └─ SurfaceContextProvider (per candidate)   ← ErrorBoundary + SurfaceContext
+            └─ React component  | WebComponentWrapper
+```
+
+- **Indexing.** A per-manager derived atom builds a `Map<role, Definition[]>`
+  once per contribution change with candidates already sorted by
+  `Position.compare`. Per-render work is therefore just the data-dependent guard
+  filter over one role's bucket — no full scan or re-sort on every render. The
+  data guard is intentionally _not_ memoized so a Surface re-dispatches when
+  reactive `data` changes. `indexByRole` itself is a pure group-and-sort; the
+  `SurfaceManager` instance filters out definitions with an invalid local id
+  before indexing (warning once per id via instance state, not a module global —
+  so distinct manager instances, e.g. across tests, don't share warning state).
+- **Per-role subscription.** Each Surface subscribes to a derived atom for _its
+  role only_ (`getCandidatesAtom`). The atom wraps the role's bucket with
+  `Data.array`, so the atom registry compares results structurally (`Equal.equals`)
+  and a contribution to another role recomputes to an equal value and is dropped —
+  that role's subscribers never re-render. Re-renders therefore scale with the
+  _affected role's_ surface count, not the total mounted fleet.
+
+  Quantified (`SurfaceComponent.test.tsx`, 100 surfaces across 10 roles, one
+  contribution per role): the old global subscription re-renders the whole fleet
+  on every contribution (100/contribution); per-role re-renders only the affected
+  role (20/contribution — one role's surfaces ×2 store commit phases) → **5×
+  fewer re-renders**, and the ratio grows with the number of roles. A second case
+  confirms 50 unrelated contributions cause 0 re-renders of an unaffected role.
+
+- **`limit`.** Caps how many resolved candidates render (e.g. `limit={1}` for
+  single-component regions).
+- **`useIsSurfaceAvailable`.** Same matching logic, exposed as `Surface.useIsAvailable`.
+  The hook captures the surface manager via context and returns a plain, stable
+  function — safe to store and call later (e.g. inside another callback such as
+  a render-prop or event handler) since the returned function calls no hooks
+  itself — used to probe whether a region would render without mounting it.
+
+## Boundaries
+
+Each matched candidate is wrapped in:
+
+- **ErrorBoundary** (`name='surface'`, `resetKeys={[data]}`) — a failing surface
+  is contained and shown via the `fallback` component; sibling surfaces survive.
+- **SurfaceContext** — exposes `{ id, role, data }` to descendants via
+  `useSurface()`. This is the supported way to read surface identity; the shell
+  must not reach _into_ a surface.
+
+A single `Suspense` (the consumer's `placeholder`) wraps all candidates.
+
+### No `ref`
+
+A Surface is a boundary, not a handle. It may resolve to zero, one, or many
+components, so a forwarded `ref` has no well-defined target. The component does
+not accept or forward a `ref`; consumers that need an element should own one
+inside their contributed component.
+
+### Production vs. debug DOM
+
+In production a React candidate renders directly inside its context provider —
+no wrapper element — so a Surface adds no layout box of its own. Debug builds
+wrap each candidate in a `<dx-surface>` element (see below) that carries
+`data-id` / `data-role` and provides a measurable boundary for overlays.
+
+## Web Components
+
+`createWeb({ tagName, … })` contributes a custom element instead of a React
+component. `WebComponentWrapper` imperatively creates the element once, assigns
+surface props as element properties, keeps them in sync, and removes the element
+on unmount. The same props (`id`, `role`, `data`, `limit`, …) are passed as for
+React surfaces.
+
+## Debugging
+
+Enabled when `VITE_DEBUG` is set (build-time) or the runtime flag is toggled
+(no rebuild). When on:
+
+- Each React candidate is wrapped in a `<dx-surface data-role data-id>` element —
+  named, inspectable in DevTools, and queryable
+  (`document.querySelectorAll('dx-surface')`).
+- A single centralized overlay manager draws boundary highlights and an info
+  affordance, instead of every surface mounting its own portal and observers.
+- The React `Profiler` is attached per surface; `SurfaceProfiler*` collect
+  render counts and durations for an in-app perf panel.
+
+### Dev metrics
+
+`SurfaceMetrics` (a module singleton, so the out-of-tree overlay and the in-app
+devtools panel share one source) records, keyed by `surface/<id>/<role>`:
+
+- **`dataUnstable` / `dataChurn`** — the consumer's `data` prop identity churns
+  across renders without its value changing. This is the most common Surface
+  footgun (see Performance notes) and nothing else detects it.
+- **`candidates` / `truncated`** — candidates matched on the last dispatch, and
+  whether `limit` dropped some. Diagnoses "nothing renders" (0) and "two things
+  render" (ambiguous match).
+- **`dispatches`** — how often the dispatcher re-resolved (the count the per-role
+  subscription minimizes).
+- **`errors`** — error-boundary trips for this surface.
+- **`mounts` / `unmounts`** — mount churn (often a thrashing upstream `key`).
+
+Recording is gated on the debug flag (zero production cost). Surfaced two ways:
+the `dx-surface` overlay badge (turns ⚠/red on a concern; full metrics on
+expand) and the devtools `SurfaceProfilerPanel` (joined onto render-timing by id).
+`Surface.useMetrics()` / `Surface.clearMetrics()` expose the data.
+
+## Performance notes
+
+- Keep `data` referentially stable across renders — it is a memo/`resetKeys`
+  dependency. Unstable `data` defeats candidate stability and trips error-boundary
+  resets.

package/src/ui/components/Surface/SurfaceComponent.stories.tsx

@@ -3,21 +3,23 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 
 import { random } from '@dxos/random';
-import { Panel, Toolbar } from '@dxos/react-ui';
+import { Input, Panel, Toolbar } from '@dxos/react-ui';
 import { Listbox } from '@dxos/react-ui-list';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
 import { Capabilities } from '../../../common';
+import * as Role from '../../../common/Role';
 import { withPluginManager } from '../../../testing';
 import { usePluginManager } from '../PluginManager';
 import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
-import { create, makeFilter, makeType } from './types';
+import { isSurfaceDebugEnabled, setSurfaceDebug } from './SurfaceDebug';
+import { create, makeFilter } from './types';
 
-const ItemRole = makeType<{ id: string }>('org.dxos.test.role.item');
+const ItemRole = Role.make<{ id: string }>('org.dxos.test.role.item');
 
 type TestComponentProps = {
   id: string;
@@ -26,19 +28,61 @@ type TestComponentProps = {
 
 const TestComponent = ({ styles, id }: TestComponentProps) => {
   return (
-    <div className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}>
-      <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
+    <div className={mx('flex justify-center items-center border rounded-sm', styles.bg, styles.border)}>
+      <span className={mx('dx-tag font-mono text-lg', styles.fg)}>{id}</span>
     </div>
   );
 };
 
-const DefaultStory = () => {
+const ErrorComponent = () => {
+  const [count, setCount] = useState(3);
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setCount((count) => {
+        if (count <= 1) {
+          clearInterval(interval);
+        }
+
+        return count - 1;
+      });
+    }, 1_000);
+    return () => clearInterval(interval);
+  }, []);
+
+  if (count <= 0) {
+    throw new Error('BANG!');
+  }
+
+  return (
+    <div className='flex justify-center items-center border border-rose-bg rounded-sm'>
+      <span className='font-mono'>Ticking... {count}</span>
+    </div>
+  );
+};
+
+type StoryProps = {
+  debug?: boolean;
+};
+
+const DefaultStory = ({ debug: debugProp }: StoryProps) => {
   const manager = usePluginManager();
   const surfaces = useSurfaces();
   const [selected, setSelected] = useState<string | undefined>();
+  const [debug, setDebug] = useState(debugProp ?? isSurfaceDebugEnabled());
+
+  // Restore the global debug flag on unmount so other stories don't inherit it.
+  useEffect(() => {
+    const previous = debugProp ?? isSurfaceDebugEnabled();
+    return () => setSurfaceDebug(previous);
+  }, []);
+
+  const handleToggleDebug = useCallback((next: boolean) => {
+    setSurfaceDebug(next);
+    setDebug(next);
+  }, []);
 
   const handleAdd = useCallback(() => {
-    const id = `test-${random.number.int({ min: 0, max: 1_000 })}`;
+    const id = `test${random.number.int({ min: 0, max: 1_000 })}`;
     const styles = getHashStyles(id);
 
     manager.capabilities.contribute({
@@ -65,42 +109,13 @@ const DefaultStory = () => {
       implementation: create({
         id: 'error',
         filter: makeFilter(ItemRole, (data) => data.id === 'error'),
-        component: () => {
-          const [count, setCount] = useState(3);
-          useEffect(() => {
-            const interval = setInterval(() => {
-              setCount((count) => {
-                if (count <= 1) {
-                  clearInterval(interval);
-                }
-
-                return count - 1;
-              });
-            }, 1_000);
-            return () => clearInterval(interval);
-          }, []);
-
-          if (count <= 0) {
-            throw new Error('BANG!');
-          }
-
-          return (
-            <div className='flex justify-center items-center border border-rose-bg rounded-sm'>
-              <span className='font-mono'>Ticking... {count}</span>
-            </div>
-          );
-        },
+        component: ErrorComponent,
       }),
     });
 
     setSelected('error');
   }, [manager]);
 
-  const ref = useRef<HTMLElement>(null);
-  useEffect(() => {
-    console.log(ref.current);
-  }, [ref]);
-
   return (
     <Panel.Root>
       <Panel.Toolbar asChild>
@@ -108,10 +123,20 @@ const DefaultStory = () => {
           <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
           <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
           <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
+          <Toolbar.Separator />
+          <Input.Root>
+            <Input.Label classNames='pr-1'>Debug</Input.Label>
+            <Input.Switch checked={debug} onCheckedChange={handleToggleDebug} />
+          </Input.Root>
         </Toolbar.Root>
       </Panel.Toolbar>
-      <Panel.Content className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
-        <SurfaceComponent type={ItemRole} data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
+      <Panel.Content classNames='grid grid-cols-2 h-full gap-4 overflow-hidden'>
+        <SurfaceComponent
+          key={debug ? 'debug' : 'prod'}
+          type={ItemRole}
+          data={selected ? { id: selected } : undefined}
+          limit={1}
+        />
         <div className='overflow-y-auto h-full'>
           <Listbox.Root>
             <Listbox.Content aria-label='Surfaces'>
@@ -141,4 +166,8 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-export const Default: Story = {};
+export const Default: Story = {
+  args: {
+    debug: true,
+  },
+};