@dxos/plugin-deck 0.8.4-main.e8ec1fe → 0.8.4-main.effb148878

package/src/components/DeckSettings/DeckSettings.stories.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { DeckSettings } from './DeckSettings';
+
+const meta = {
+  title: 'plugins/plugin-deck/components/DeckSettings',
+  tags: ['settings'],
+  component: DeckSettings,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DeckSettings>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    settings: {
+      enableDeck: true,
+      encapsulatedPlanks: false,
+      showHints: true,
+      enableNativeRedirect: false,
+    },
+  },
+};

package/src/components/DeckSettings/DeckSettings.tsx

@@ -4,100 +4,31 @@
 
 import React from 'react';
 
-import { Input, Select, useTranslation } from '@dxos/react-ui';
-import { ControlGroup, ControlItemInput, ControlPage, ControlSection } from '@dxos/react-ui-form';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
 
-import { meta } from '../../meta';
-import {
-  type DeckSettingsProps,
-  type NewPlankPositioning,
-  NewPlankPositions,
-  type Overscroll,
-  OverscrollOptions,
-} from '../../types';
+import { meta } from '#meta';
+import { Settings } from '#types';
 
 const isSocket = !!(globalThis as any).__args;
 
-export const DeckSettings = ({ settings }: { settings: DeckSettingsProps }) => {
+export type DeckSettingsProps = AppSurface.SettingsArticleProps<Settings.Settings>;
+
+export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsProps) => {
   const { t } = useTranslation(meta.id);
 
   return (
-    <ControlPage>
-      <ControlSection title={t('settings title', { ns: meta.id })}>
-        <ControlGroup>
-          <ControlItemInput title={t('settings enable deck label')}>
-            <Input.Switch
-              checked={settings.enableDeck}
-              onCheckedChange={(checked) => (settings.enableDeck = checked)}
-            />
-          </ControlItemInput>
-          <ControlItemInput title={t('settings encapsulated planks label')}>
-            <Input.Switch
-              checked={settings.encapsulatedPlanks ?? false}
-              onCheckedChange={(checked) => (settings.encapsulatedPlanks = checked)}
-            />
-          </ControlItemInput>
-          <ControlItemInput title={t('select new plank positioning label')}>
-            <Select.Root
-              disabled={!settings.enableDeck}
-              value={settings.newPlankPositioning ?? 'start'}
-              onValueChange={(value) => (settings.newPlankPositioning = value as NewPlankPositioning)}
-            >
-              <Select.TriggerButton placeholder={t('select new plank positioning placeholder')} />
-              <Select.Portal>
-                <Select.Content>
-                  <Select.Viewport>
-                    {NewPlankPositions.map((position) => (
-                      <Select.Option key={position} value={position}>
-                        {t(`settings new plank position ${position} label`)}
-                      </Select.Option>
-                    ))}
-                  </Select.Viewport>
-                  <Select.Arrow />
-                </Select.Content>
-              </Select.Portal>
-            </Select.Root>
-          </ControlItemInput>
-          <ControlItemInput title={t('settings overscroll label')}>
-            <Select.Root
-              disabled={!settings.enableDeck}
-              value={settings.overscroll ?? 'none'}
-              onValueChange={(value) => (settings.overscroll = value as Overscroll)}
-            >
-              <Select.TriggerButton placeholder={t('select overscroll placeholder')} />
-              <Select.Portal>
-                <Select.Content>
-                  <Select.Viewport>
-                    {OverscrollOptions.map((option) => (
-                      <Select.Option key={option} value={option}>
-                        {t(`settings overscroll ${option} label`)}
-                      </Select.Option>
-                    ))}
-                  </Select.Viewport>
-                  <Select.Arrow />
-                </Select.Content>
-              </Select.Portal>
-            </Select.Root>
-          </ControlItemInput>
-          <ControlItemInput title={t('settings enable statusbar label')}>
-            <Input.Switch
-              checked={settings.enableStatusbar}
-              onCheckedChange={(checked) => (settings.enableStatusbar = checked)}
-            />
-          </ControlItemInput>
-          <ControlItemInput title={t('settings show hints label')}>
-            <Input.Switch checked={settings.showHints} onCheckedChange={(checked) => (settings.showHints = checked)} />
-          </ControlItemInput>
-          {!isSocket && (
-            <ControlItemInput title={t('settings native redirect label')}>
-              <Input.Switch
-                checked={settings.enableNativeRedirect}
-                onCheckedChange={(checked) => (settings.enableNativeRedirect = checked)}
-              />
-            </ControlItemInput>
-          )}
-        </ControlGroup>
-      </ControlSection>
-    </ControlPage>
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+        <SettingsForm.FieldSet
+          readonly={!onSettingsChange}
+          schema={Settings.Settings}
+          visible={(path) => path !== 'enableNativeRedirect' || !isSocket}
+          values={settings}
+          onValuesChanged={(values) => onSettingsChange?.(() => values)}
+        />
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
   );
 };

package/src/components/DeckSettings/index.ts

@@ -1,5 +1,5 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2024 DXOS.org
 //
 
-export * from './DeckSettings';
+export { DeckSettings as default } from './DeckSettings';

package/src/components/Matrix/Matrix.stories.tsx

@@ -0,0 +1,220 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
+import { Graph } from '@dxos/app-graph';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Obj } from '@dxos/echo';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { Focus, Panel, Toolbar } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { type MosaicTileProps, Mosaic } from '@dxos/react-ui-mosaic';
+import { StackContext } from '@dxos/react-ui-stack';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+import { Organization, Person } from '@dxos/types';
+
+import { DeckState, OperationHandler } from '#capabilities';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+
+import { Plank } from '../../containers/Plank';
+import { Matrix, type MatrixController, type MatrixRootProps } from './Matrix';
+
+random.seed(123);
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  AppPlugin.addOperationHandlerModule({
+    activate: OperationHandler,
+  }),
+  Plugin.make,
+);
+
+/**
+ * Simple tile with JSON display and attention tracking.
+ */
+const StoryTile = (props: MosaicTileProps<Obj.Any>) => {
+  const attentionAttrs = useAttentionAttributes(props.data.id);
+  return (
+    <Mosaic.Tile {...props} asChild>
+      <Focus.Item asChild border current={props.current}>
+        <Panel.Root classNames='dx-current dx-hover w-full md:w-[50rem] snap-start shrink-0' {...attentionAttrs}>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <p>{Obj.getLabel(props.data)}</p>
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Syntax.Root data={props.data}>
+            <Panel.Content asChild>
+              <Syntax.Content>
+                <Syntax.Viewport>
+                  <Syntax.Code />
+                </Syntax.Viewport>
+              </Syntax.Content>
+            </Panel.Content>
+          </Syntax.Root>
+        </Panel.Root>
+      </Focus.Item>
+    </Mosaic.Tile>
+  );
+};
+
+/**
+ * Tile that wraps a Plank for content rendering.
+ */
+const PlankTile = (props: MosaicTileProps<Obj.Any>) => {
+  const graph = useMemo(() => Graph.make(), []);
+  return (
+    <StackContext.Provider value={{ orientation: 'horizontal', size: 'contain', rail: true }}>
+      <Plank.Root layoutMode='multi' part='multi' graph={graph}>
+        <Mosaic.Tile {...props} asChild>
+          <Plank.Content solo={false} companion={false} encapsulate={false}>
+            <Plank.Component
+              id={props.data.id}
+              part='multi'
+              node={{
+                id: props.data.id,
+                data: props.data,
+                type: 'test',
+                properties: {},
+              }}
+            />
+          </Plank.Content>
+        </Mosaic.Tile>
+      </Plank.Root>
+    </StackContext.Provider>
+  );
+};
+
+const TestExtension = Capability.contributes(
+  Capabilities.ReactSurface,
+  Surface.create({
+    id: 'story-article',
+    role: 'article',
+    component: ({ data: { subject } }) => {
+      if (!subject) {
+        return <Loading />;
+      }
+
+      return (
+        <Syntax.Root data={subject}>
+          <Syntax.Content>
+            <Syntax.Viewport>
+              <Syntax.Code />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
+      );
+    },
+  }),
+);
+
+type DefaultStoryProps = Pick<MatrixRootProps, 'Tile'>;
+
+const DefaultStory = ({ Tile }: DefaultStoryProps) => {
+  const items = useMemo(
+    () => [
+      Organization.make({ name: random.company.name() }),
+      Person.make({ fullName: random.person.fullName() }),
+      Text.make({ name: 'Bio', content: random.lorem.paragraphs(10) }),
+      Text.make({ name: 'Companion', content: 'Companion panel for Bio' }),
+    ],
+    [],
+  );
+
+  const controller = useRef<MatrixController>(null);
+  const [current, setCurrent] = useState<string | undefined>(items[0]?.id);
+
+  const handleCurrentChange = useCallback((id: string | undefined) => {
+    setCurrent(id);
+  }, []);
+
+  const handlePrev = useCallback(() => {
+    const index = items.findIndex((item) => item.id === current);
+    const prev = items[Math.max(0, index - 1)];
+    if (prev) {
+      controller.current?.scrollTo(prev.id);
+    }
+  }, [items, current]);
+
+  const handleNext = useCallback(() => {
+    const index = items.findIndex((item) => item.id === current);
+    const next = items[Math.min(items.length - 1, index + 1)];
+    if (next) {
+      controller.current?.scrollTo(next.id);
+    }
+  }, [items, current]);
+
+  const currentIndex = items.findIndex((item) => item.id === current);
+
+  return (
+    <Mosaic.Root>
+      <Matrix.Root Tile={Tile} items={items} current={current} onCurrentChange={handleCurrentChange} ref={controller}>
+        <Panel.Root>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <Toolbar.IconButton icon='ph--caret-left--regular' iconOnly label='Back' onClick={handlePrev} />
+              <Toolbar.IconButton icon='ph--caret-right--regular' iconOnly label='Forward' onClick={handleNext} />
+              <Toolbar.Text>
+                {currentIndex + 1} / {items.length}
+              </Toolbar.Text>
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Panel.Content asChild>
+            <Matrix.Content>
+              <Matrix.Viewport />
+            </Matrix.Content>
+          </Panel.Content>
+        </Panel.Root>
+      </Matrix.Root>
+    </Mosaic.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-deck/components/Matrix',
+  component: DefaultStory,
+  decorators: [withTheme(), withAttention(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<MatrixRootProps>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    Tile: StoryTile,
+  },
+};
+
+export const WithPlank: Story = {
+  decorators: [
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+      capabilities: [TestExtension],
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+  args: {
+    Tile: PlankTile,
+  },
+};

package/src/components/Matrix/Matrix.tsx

@@ -0,0 +1,205 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useFocusFinders } from '@fluentui/react-tabster';
+import { createContext } from '@radix-ui/react-context';
+import React, { forwardRef, type PropsWithChildren, useCallback, useEffect, useImperativeHandle, useRef } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { ScrollArea } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { useAttended } from '@dxos/react-ui-attention';
+import { type MosaicStackTileComponent, Mosaic } from '@dxos/react-ui-mosaic';
+import { type ComposableProps } from '@dxos/ui-types';
+
+//
+// Context
+//
+
+const MATRIX_NAME = 'Matrix';
+
+type MatrixContextValue = {
+  /** Items to render. */
+  items: Obj.Any[];
+  /** Tile component to render for each item. */
+  Tile: MosaicStackTileComponent<Obj.Any>;
+  /** Currently attended tile ID. */
+  current?: Obj.ID;
+  /** Callback when the attended tile changes. */
+  onCurrentChange?: (id: Obj.ID | undefined) => void;
+  /** Register the viewport element for scroll operations. */
+  registerViewport: (element: HTMLElement | null) => void;
+};
+
+const [MatrixProvider, useMatrixContext] = createContext<MatrixContextValue>(MATRIX_NAME);
+
+//
+// Controller
+//
+
+interface MatrixController {
+  scrollTo: (id: Obj.ID) => void;
+}
+
+//
+// Root
+//
+
+const MATRIX_ROOT_NAME = 'Matrix.Root';
+
+type MatrixRootProps = PropsWithChildren<{
+  /** Items to render. */
+  items?: Obj.Any[];
+  /** Tile component to render for each item. */
+  Tile: MosaicStackTileComponent<Obj.Any>;
+  /** Currently attended tile ID. */
+  current?: Obj.ID;
+  /** Callback when the attended tile changes. */
+  onCurrentChange?: (id: Obj.ID | undefined) => void;
+}>;
+
+/**
+ * Headless root that provides matrix context.
+ * Syncs the attention system with `onCurrentChange` — when a tile gains attention, the callback fires.
+ */
+const MatrixRoot = forwardRef<MatrixController, MatrixRootProps>(
+  ({ children, items = [], Tile, current, onCurrentChange }, forwardedRef) => {
+    const viewportRef = useRef<HTMLElement | null>(null);
+    const registerViewport = useCallback((element: HTMLElement | null) => {
+      viewportRef.current = element;
+    }, []);
+
+    const { findFirstFocusable } = useFocusFinders();
+    const findFirstFocusableRef = useRef(findFirstFocusable);
+    findFirstFocusableRef.current = findFirstFocusable;
+
+    // Sync attention system with current tile.
+    const attended = useAttended();
+    const itemIds = useRef(new Set<string>());
+    useEffect(() => {
+      itemIds.current = new Set(items.map((item) => item.id));
+    }, [items]);
+
+    useEffect(() => {
+      // Find the first attended ID that matches an item.
+      const matchedId = attended.find((id) => itemIds.current.has(id));
+      if (matchedId !== current) {
+        onCurrentChange?.(matchedId);
+      }
+    }, [attended, current, onCurrentChange]);
+
+    useImperativeHandle(forwardedRef, () => ({
+      scrollTo: (id) => {
+        const viewport = viewportRef.current;
+        if (!viewport) {
+          return;
+        }
+
+        const tile = viewport.querySelector<HTMLElement>(`[data-object-id="${CSS.escape(id)}"]`);
+        if (!tile) {
+          return;
+        }
+
+        // Focus first focusable element so attention updates immediately, then scroll.
+        const focusable = findFirstFocusableRef.current(tile);
+        (focusable ?? tile).focus({ preventScroll: true });
+
+        const tileRect = tile.getBoundingClientRect();
+        const viewportRect = viewport.getBoundingClientRect();
+        const offset = tileRect.left - viewportRect.left + viewport.scrollLeft;
+        if (Math.abs(offset - viewport.scrollLeft) > 1) {
+          viewport.scrollTo({ left: offset, behavior: 'smooth' });
+        }
+      },
+    }));
+
+    return (
+      <MatrixProvider
+        items={items}
+        Tile={Tile}
+        current={current}
+        onCurrentChange={onCurrentChange}
+        registerViewport={registerViewport}
+      >
+        {children}
+      </MatrixProvider>
+    );
+  },
+);
+
+MatrixRoot.displayName = MATRIX_ROOT_NAME;
+
+//
+// Content
+//
+
+const MATRIX_CONTENT_NAME = 'Matrix.Content';
+
+type MatrixContentProps = ComposableProps;
+
+/**
+ * Styled container wrapping Mosaic.Container for drag-and-drop support.
+ */
+const MatrixContent = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props);
+  return (
+    <Mosaic.Container ref={forwardedRef} classNames={className} orientation='horizontal' {...rest}>
+      {children}
+    </Mosaic.Container>
+  );
+});
+
+MatrixContent.displayName = MATRIX_CONTENT_NAME;
+
+//
+// Viewport
+//
+
+const MATRIX_VIEWPORT_NAME = 'Matrix.Viewport';
+
+type MatrixViewportProps = ComposableProps;
+
+const getId = (item: Obj.Any) => item.id;
+
+/**
+ * Horizontally scrollable viewport that renders tiles from context.
+ */
+const MatrixViewport = composable<HTMLDivElement>(({ ...props }, forwardedRef) => {
+  const { items, Tile, registerViewport } = useMatrixContext(MATRIX_VIEWPORT_NAME);
+  const viewportRef = useCallback(
+    (element: HTMLElement | null) => {
+      registerViewport(element);
+    },
+    [registerViewport],
+  );
+
+  return (
+    <ScrollArea.Root orientation='horizontal' padding snap {...composableProps(props)} ref={forwardedRef}>
+      <ScrollArea.Viewport ref={viewportRef}>
+        <Mosaic.Stack
+          orientation='horizontal'
+          classNames='snap-x snap-mandatory gap-2'
+          getId={getId}
+          items={items}
+          Tile={Tile}
+          draggable={false}
+        />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+});
+
+MatrixViewport.displayName = MATRIX_VIEWPORT_NAME;
+
+//
+// Matrix
+//
+
+export const Matrix = {
+  Root: MatrixRoot,
+  Content: MatrixContent,
+  Viewport: MatrixViewport,
+};
+
+export type { MatrixController, MatrixRootProps, MatrixContentProps, MatrixViewportProps };