@dxos/storybook-utils 0.8.3 → 0.8.4-main.2e9d522

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/storybook-utils",
-  "version": "0.8.3",
+  "version": "0.8.4-main.2e9d522",
   "description": "Utilities for DXOS UI Storybooks.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -24,15 +24,14 @@
     "src"
   ],
   "dependencies": {
-    "@storybook/manager-api": "^8.3.6",
-    "@storybook/preview-api": "^8.3.6",
+    "@radix-ui/react-use-controllable-state": "^1.0.0",
     "lodash.defaultsdeep": "^4.6.1",
-    "storybook-dark-mode": "^4.0.2",
-    "@dxos/echo-signals": "0.8.3",
-    "@dxos/lit-theme-editor": "0.8.3",
-    "@dxos/lit-ui": "0.8.3",
-    "@dxos/log": "0.8.3",
-    "@dxos/theme-editor-addon": "0.8.3"
+    "storybook": "^9.0.18",
+    "@dxos/echo-signals": "0.8.4-main.2e9d522",
+    "@dxos/lit-theme-editor": "0.8.4-main.2e9d522",
+    "@dxos/lit-ui": "0.8.4-main.2e9d522",
+    "@dxos/log": "0.8.4-main.2e9d522",
+    "@dxos/react-ui-dnd": "0.8.4-main.2e9d522"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
@@ -40,14 +39,16 @@
     "@types/react-dom": "~18.2.0",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "storybook": "^8.3.6",
-    "@dxos/react-ui": "0.8.3",
-    "@dxos/react-ui-theme": "0.8.3"
+    "@dxos/react-ui": "0.8.4-main.2e9d522",
+    "@dxos/react-ui-theme": "0.8.4-main.2e9d522"
   },
   "peerDependencies": {
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.3",
-    "@dxos/react-ui-theme": "0.8.3"
+    "@dxos/react-ui": "0.8.4-main.2e9d522",
+    "@dxos/react-ui-theme": "0.8.4-main.2e9d522"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/components/CardContainers/ExtrinsicCardContainer.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, { type PropsWithChildren } from 'react';
+
+import { ResizeHandle, resizeAttributes, sizeStyle, type Size } from '@dxos/react-ui-dnd';
+
+// Default size in rem
+const DEFAULT_INLINE_SIZE = 24;
+const MIN_INLINE_SIZE = 8;
+const DEFAULT_BLOCK_SIZE = 24;
+const MIN_BLOCK_SIZE = 8;
+
+export type ExtrinsicCardContainerProps = PropsWithChildren<{
+  defaultInlineSize?: Size;
+  inlineSize?: Size;
+  defaultBlockSize?: Size;
+  blockSize?: Size;
+  onInlineSizeChange?: (size: Size, commit?: boolean) => void;
+  onBlockSizeChange?: (size: Size, commit?: boolean) => void;
+}>;
+
+export const ExtrinsicCardContainer = ({
+  children,
+  defaultInlineSize,
+  inlineSize: propInlineSize,
+  defaultBlockSize,
+  blockSize: propBlockSize,
+  onInlineSizeChange,
+  onBlockSizeChange,
+}: ExtrinsicCardContainerProps) => {
+  const [inlineSize = DEFAULT_INLINE_SIZE, setInlineSize] = useControllableState<Size>({
+    prop: propInlineSize,
+    defaultProp: defaultInlineSize,
+    onChange: onInlineSizeChange,
+  });
+
+  const [blockSize = DEFAULT_BLOCK_SIZE, setBlockSize] = useControllableState<Size>({
+    prop: propBlockSize,
+    defaultProp: defaultBlockSize,
+    onChange: onBlockSizeChange,
+  });
+
+  return (
+    <div
+      className='grid relative border border-dashed border-subduedSeparator p-4 rounded-lg overflow-hidden contain-layout'
+      style={{
+        ...sizeStyle(inlineSize, 'horizontal'),
+        ...sizeStyle(blockSize, 'vertical'),
+      }}
+      {...resizeAttributes}
+    >
+      {children}
+      <ResizeHandle
+        side='inline-end'
+        fallbackSize={DEFAULT_INLINE_SIZE}
+        minSize={MIN_INLINE_SIZE}
+        size={inlineSize}
+        onSizeChange={setInlineSize}
+      />
+      <ResizeHandle
+        side='block-end'
+        fallbackSize={DEFAULT_BLOCK_SIZE}
+        minSize={MIN_BLOCK_SIZE}
+        size={blockSize}
+        onSizeChange={setBlockSize}
+      />
+    </div>
+  );
+};

package/src/components/CardContainers/IntrinsicCardContainer.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, { type PropsWithChildren } from 'react';
+
+import { ResizeHandle, resizeAttributes, sizeStyle, type Size } from '@dxos/react-ui-dnd';
+
+// Default size in rem
+const DEFAULT_SIZE = 24;
+const MIN_SIZE = 8;
+
+export type IntrinsicCardContainerProps = PropsWithChildren<{
+  defaultSize?: Size;
+  size?: Size;
+  onSizeChange?: (size: Size, commit?: boolean) => void;
+}>;
+
+export const IntrinsicCardContainer = ({
+  children,
+  defaultSize,
+  size: propSize,
+  onSizeChange,
+}: IntrinsicCardContainerProps) => {
+  const [size = DEFAULT_SIZE, setSize] = useControllableState<Size>({
+    prop: propSize,
+    defaultProp: defaultSize,
+    onChange: onSizeChange,
+  });
+
+  return (
+    <div
+      className='relative border border-dashed border-subduedSeparator p-4 rounded-lg'
+      style={sizeStyle(size, 'horizontal')}
+      {...resizeAttributes}
+    >
+      {children}
+      <ResizeHandle
+        side='inline-end'
+        fallbackSize={DEFAULT_SIZE}
+        minSize={MIN_SIZE}
+        size={size}
+        onSizeChange={setSize}
+      />
+    </div>
+  );
+};

package/src/components/CardContainers/PopoverCardContainer.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren } from 'react';
+
+import { Icon, Popover } from '@dxos/react-ui';
+
+export const PopoverCardContainer = ({
+  children,
+  icon = 'ph--placeholder--regular',
+}: PropsWithChildren<{ icon: string }>) => {
+  return (
+    <Popover.Root open>
+      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
+        <Popover.Viewport>{children}</Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+      <Popover.Trigger>
+        <Icon icon={icon} size={5} />
+      </Popover.Trigger>
+    </Popover.Root>
+  );
+};

package/src/components/CardContainers/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ExtrinsicCardContainer';
+export * from './IntrinsicCardContainer';
+export * from './PopoverCardContainer';

package/src/components/DocsContainer.tsx

@@ -0,0 +1,18 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+// TODO(wittjosiah): Not compatible with storybook 9.0.
+// import { DocsContainer as BaseContainer, type DocsContainerProps } from '@storybook/blocks';
+// import React, { type PropsWithChildren } from 'react';
+
+/**
+ * https://storybook.js.org/docs/writing-docs/doc-blocks
+ */
+// export const DocsContainer = ({ children, context, theme }: PropsWithChildren<DocsContainerProps>) => {
+//   return (
+//     <BaseContainer context={context} theme={theme}>
+//       {children}
+//     </BaseContainer>
+//   );
+// };

package/src/components/ThemeEditor.tsx

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { memo } from 'react';
+
+import { DxThemeEditor as NaturalDxThemeEditor } from '@dxos/lit-theme-editor';
+import { createComponent } from '@dxos/lit-ui/react';
+
+import '@dxos/lit-theme-editor/dx-theme-editor.pcss';
+
+const DxThemeEditor = createComponent({
+  tagName: 'dx-theme-editor',
+  elementClass: NaturalDxThemeEditor,
+  react: React,
+});
+
+export const ThemeEditor = memo(DxThemeEditor);

package/src/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+// export * from './DocsContainer';
+export * from './ThemeEditor';
+export * from './CardContainers';

package/src/decorators/index.ts

@@ -3,5 +3,5 @@
 //
 
 export * from './withLayout';
-export * from './withSignals';
 export * from './withTheme';
+export * from './withThemeEditor';

package/src/decorators/withLayout.tsx

@@ -36,7 +36,7 @@ export type WithLayoutProps = ThemedClassName<ProviderOptions & { Container?: FC
 export const withLayout = ({
   classNames,
   fullscreen,
-  Container = fullscreen ? FixedContainer : DefaultContainer,
+  Container = fullscreen ? FullscreenContainer : DefaultContainer,
   ...providedOptions
 }: WithLayoutProps = {}): Decorator => {
   // TODO(burdon): Inspect "fullscreen" parameter in context.
@@ -52,7 +52,10 @@ export const withLayout = ({
   };
 };
 
-export const DefaultContainer: FC<ContainerProps> = ({ children, classNames }) => {
+// TODO(burdon): Use consistently.
+export const layoutCentered = 'bg-deckSurface justify-center overflow-y-auto';
+
+export const DefaultContainer = ({ children, classNames }: ContainerProps) => {
   return (
     <div role='none' className={mx(classNames)}>
       {children}
@@ -60,7 +63,7 @@ export const DefaultContainer: FC<ContainerProps> = ({ children, classNames }) =
   );
 };
 
-export const FixedContainer: FC<ContainerProps> = ({ children, classNames }) => {
+export const FullscreenContainer = ({ children, classNames }: ContainerProps) => {
   return (
     <div role='none' className={mx('fixed inset-0 flex overflow-hidden', classNames)}>
       {children}
@@ -68,12 +71,12 @@ export const FixedContainer: FC<ContainerProps> = ({ children, classNames }) =>
   );
 };
 
-export const ColumnContainer: FC<ContainerProps> = ({ children, classNames = 'w-[30rem]', ...props }) => {
+export const ColumnContainer = ({ children, classNames = 'w-[30rem]', ...props }: ContainerProps) => {
   return (
-    <FixedContainer classNames='justify-center bg-modalSurface' {...props}>
+    <FullscreenContainer classNames='justify-center bg-modalSurface' {...props}>
       <div role='none' className={mx('flex flex-col h-full overflow-y-auto bg-baseSurface', classNames)}>
         {children}
       </div>
-    </FixedContainer>
+    </FullscreenContainer>
   );
 };

package/src/decorators/withTheme.tsx

@@ -2,82 +2,28 @@
 // Copyright 2023 DXOS.org
 //
 
-import { addons } from '@storybook/preview-api';
 import { type Decorator } from '@storybook/react';
-import React, { memo, useCallback, useEffect, useState } from 'react';
-import { DARK_MODE_EVENT_NAME } from 'storybook-dark-mode';
+import React, { memo } from 'react';
 
-import { DxThemeEditor as NaturalDxThemeEditor } from '@dxos/lit-theme-editor';
-import '@dxos/lit-theme-editor/dx-theme-editor.pcss';
-import { createComponent } from '@dxos/lit-ui/react';
-import { type ThemeMode, ThemeProvider, Tooltip, Dialog, IconButton } from '@dxos/react-ui';
+import { type ThemeMode, ThemeProvider, Tooltip } from '@dxos/react-ui';
 import { defaultTx } from '@dxos/react-ui-theme';
-import { PARAM_KEY } from '@dxos/theme-editor-addon';
-
-const DxThemeEditor = createComponent({
-  tagName: 'dx-theme-editor',
-  elementClass: NaturalDxThemeEditor,
-  react: React,
-});
 
 /**
- * Changes theme based on storybook toolbar toggle.
+ * Adds theme decorator.
  */
 export const withTheme: Decorator = (Story, context) => {
+  const {
+    globals: { theme },
+    parameters: { translations },
+  } = context;
+
   // Prevent re-rendering of the story.
   const MemoizedStory = memo(Story);
-  const [themeMode, setThemeMode] = useState<ThemeMode>('dark');
-  const [editorOpen, setEditorOpen] = useState(false);
-
-  const handleOpenChange = useCallback((nextOpen: boolean) => {
-    setEditorOpen(nextOpen);
-  }, []);
-
-  // https://www.npmjs.com/package/storybook-dark-mode
-  // NOTE: The `useDarkMode` hook causes the story to continually re-render.
-  // NOTE: Changing the theme will cause the story to remount.
-  useEffect(() => {
-    const handleDarkModeUpdate = (darkMode: boolean) => setThemeMode(darkMode ? 'dark' : 'light');
-    addons.getChannel().on(DARK_MODE_EVENT_NAME, handleDarkModeUpdate);
-    return () => addons.getChannel().off(DARK_MODE_EVENT_NAME, handleDarkModeUpdate);
-  }, []);
-
-  useEffect(() => {
-    const openEditor = () => {
-      handleOpenChange(true);
-    };
-    addons.getChannel().on(PARAM_KEY, openEditor);
-    return () => addons.getChannel().off(PARAM_KEY, openEditor);
-  }, []);
 
   return (
-    <ThemeProvider tx={defaultTx} themeMode={themeMode} resourceExtensions={context?.parameters?.translations} noCache>
+    <ThemeProvider tx={defaultTx} themeMode={theme as ThemeMode} resourceExtensions={translations} noCache>
       <Tooltip.Provider>
         <MemoizedStory />
-        <Dialog.Root open={editorOpen} onOpenChange={handleOpenChange} modal={false}>
-          <div
-            role='none'
-            className='dx-dialog__overlay bg-transparent pointer-events-none'
-            style={{ placeContent: 'end' }}
-          >
-            <Dialog.Content
-              classNames='relative box-content py-0 px-2 md:is-[35rem] md:max-is-none overflow-y-auto layout-contain pointer-events-auto'
-              style={{ maxBlockSize: '50dvh' }}
-              onInteractOutside={(event) => event.preventDefault()}
-            >
-              <Dialog.Title srOnly>Theme Editor</Dialog.Title>
-              {editorOpen && <DxThemeEditor />}
-              <Dialog.Close asChild>
-                <IconButton
-                  iconOnly
-                  icon='ph--x--regular'
-                  label='Close'
-                  classNames='absolute block-start-2 inline-end-2'
-                />
-              </Dialog.Close>
-            </Dialog.Content>
-          </div>
-        </Dialog.Root>
       </Tooltip.Provider>
     </ThemeProvider>
   );

package/src/decorators/withThemeEditor.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Decorator } from '@storybook/react';
+import React, { memo } from 'react';
+
+import { ThemeEditor } from '../components';
+
+/**
+ * Show theme editor.
+ */
+// TODO(burdon): Ideally move to storybook-addon-theme, but this has a build issue since the addon would depend on the vite theme plugin.
+export const withThemeEditor: Decorator = (Story, context) => {
+  // Prevent re-rendering of the story.
+  const MemoizedStory = memo(Story);
+
+  return (
+    <>
+      <MemoizedStory />
+      <div className='absolute top-4 bottom-4 right-4 z-10'>
+        <div className='h-full is-[35rem] overflow-auto bg-baseSurface border border-separator rounded'>
+          <ThemeEditor />
+        </div>
+      </div>
+    </>
+  );
+};

package/src/index.ts

@@ -6,6 +6,7 @@ import { registerSignalsRuntime } from '@dxos/echo-signals/react';
 
 export { type Meta } from '@storybook/react';
 
+export * from './components';
 export * from './decorators';
 export * from './util';
 

package/src/stories/test/Test.stories.tsx

@@ -0,0 +1,62 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { log } from '@dxos/log';
+import { withTheme } from '@dxos/storybook-utils';
+
+import { TEST_ID, Test, type TestProps } from './Test';
+
+/**
+ * Storybook sanity test.
+ */
+const meta: Meta<TestProps> = {
+  title: 'devtools/storybook-utils/Test',
+  component: Test,
+  render: (args) => <Test {...{ 'data-testid': TEST_ID }} {...args} />,
+  decorators: [withTheme],
+};
+
+export default meta;
+
+type Story = StoryObj<TestProps>;
+
+export const Default: Story = {
+  // Interactions tab.
+  // https://storybook.js.org/docs/writing-stories/play-function?renderer=react#writing-stories-with-the-play-function
+  play: async ({ args, canvasElement }: any) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button'));
+    await expect(args.onClick).toHaveBeenCalled();
+    await expect(canvas.getByText(args.label)).toBeInTheDocument();
+  },
+  args: {
+    variant: 'primary',
+    icon: 'ph--rocket-launch--regular',
+    label: 'Composer',
+    onClick: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: 'A basic button component.',
+      },
+    },
+  },
+};
+
+export const WithLog: Story = {
+  args: {
+    icon: 'ph--rocket-launch--regular',
+    label: 'Test',
+    onClick: () => {
+      log.info('Hello, world!');
+    },
+  },
+};

package/src/stories/test/Test.test.tsx

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { composeStories } from '@storybook/react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ThemeProvider } from '@dxos/react-ui';
+
+import { TEST_ID, Test } from './Test';
+import * as stories from './Test.stories';
+
+const { Default } = composeStories(stories);
+
+/**
+ * Vitest sanity test (should be visible in the storybook).
+ * https://storybook.js.org/docs/writing-tests/integrations/vitest-addon
+ */
+// TODO(burdon): Not working.
+describe('Test', () => {
+  it('should render', async () => {
+    await Default.run();
+    expect(screen.getByTestId(TEST_ID)).to.exist;
+  });
+
+  it('calls onClick when clicked', () => {
+    const handleClick = vi.fn();
+    const { container } = render(
+      <ThemeProvider>
+        <Test id='test' icon='ph--x--regular' label='Test' onClick={handleClick} />
+      </ThemeProvider>,
+    );
+
+    fireEvent.click(container.querySelector('#test')!);
+    expect(handleClick).toHaveBeenCalledTimes(1);
+    expect(screen.debug()).toMatchSnapshot();
+  });
+});

package/src/stories/test/Test.tsx

@@ -0,0 +1,15 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { IconButton, type IconButtonProps } from '@dxos/react-ui';
+
+export const TEST_ID = 'test';
+
+export type TestProps = IconButtonProps;
+
+export const Test = (props: TestProps) => {
+  return <IconButton size={4} {...props} />;
+};

package/src/stories/test/__snapshots__/Test.test.tsx.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Test > calls onClick when clicked 1`] = `undefined`;

package/src/stories/test/index.mdx

@@ -0,0 +1,14 @@
+{/* Copyright 2023 DXOS.org */}
+
+import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
+import * as TestStories from './Test.stories';
+
+<Meta title='MDX/Test' of={TestStories} />
+
+# Test
+
+Test `MDX` for the `Test` component.
+
+<Canvas>
+  <Story of={TestStories} />
+</Canvas>

package/src/vitest-setup.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// https://github.com/testing-library/jest-dom#with-vitest
+import '@testing-library/jest-dom/vitest';
+
+// https://github.com/jsdom/jsdom/issues/3368#issuecomment-1396749033
+import ResizeObserver from 'resize-observer-polyfill';
+
+global.ResizeObserver = ResizeObserver;

package/README.yml

@@ -1 +0,0 @@
-guideUrl: https://docs.dxos.org/guide/react/aurora/