@page-component-object/adapter-storybook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Vega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { MockSession, HttpHandler } from '@page-component-object/msw';
+import { BaseViewTestObject } from '@page-component-object/react';
+import { ComponentTestObject } from '@page-component-object/queries';
+export { expect } from '@storybook/test';
+import * as msw_storybook_addon from 'msw-storybook-addon';
+import { initialize } from 'msw-storybook-addon';
+export { MswParameters } from 'msw-storybook-addon';
+
+declare function setupPCOStorybook(): void;
+
+type PcoViewConfig<T extends BaseViewTestObject = BaseViewTestObject> = {
+    view: ViewTestObjectClass$1<T>;
+    /** Runs after `setupMockData()` on the view instance. */
+    setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void;
+};
+type PcoStoryParameters = {
+    pco?: PcoViewConfig;
+};
+type ViewMockSession$1<T extends BaseViewTestObject> = MockSession<T> & {
+    view: T;
+};
+type ViewTestObjectClass$1<T extends BaseViewTestObject> = {
+    new (): T;
+    mockSession(setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void): ViewMockSession$1<T>;
+};
+/**
+ * Storybook loader: resolves `parameters.pco` into MSW handlers before render.
+ * No-op when `pco.view` is absent. Pair with `getStorybookMswPreviewConfig()`.
+ */
+declare function pcoViewLoader({ parameters, }: {
+    parameters: PcoStoryParameters;
+}): Promise<{
+    pco?: {
+        session: ViewMockSession$1<BaseViewTestObject>;
+    };
+}>;
+type ViewAssertionContext<T extends BaseViewTestObject> = {
+    view: T;
+    mocks: ReturnType<T['setupMockData']>;
+    canvasElement: HTMLElement;
+};
+/**
+ * Optional test-runner play that asserts against spies from `pcoViewLoader`.
+ */
+declare function createViewAssertionPlay<T extends BaseViewTestObject>(fn: (ctx: ViewAssertionContext<T>) => Promise<void> | void): ({ canvasElement, loaded, }: {
+    canvasElement: HTMLElement;
+    loaded: {
+        pco?: {
+            session: MockSession<T> & {
+                view: T;
+            };
+        };
+    };
+}) => Promise<void>;
+
+type StorybookMswPreviewOptions = Parameters<typeof initialize>[0] & {
+    /** When true (default), include `pcoViewLoader` before `mswLoader` for `parameters.pco.view`. */
+    pcoViewLoader?: boolean;
+};
+/**
+ * MSW wiring for `.storybook/preview.ts` when using `BaseViewTestObject.storyParameters` or `parameters.pco.view`.
+ *
+ * @example
+ * ```ts
+ * import { setupPCOStorybook, getStorybookMswPreviewConfig } from '@page-component-object/adapter-storybook';
+ *
+ * const msw = getStorybookMswPreviewConfig({ onUnhandledRequest: 'warn' });
+ * setupPCOStorybook();
+ * msw.initializeMsw();
+ *
+ * const preview: Preview = {
+ *   loaders: msw.loaders,
+ *   // …decorators, parameters
+ * };
+ * ```
+ */
+declare function getStorybookMswPreviewConfig(options?: StorybookMswPreviewOptions): {
+    /** Call once at module scope in preview (before exporting `preview`). */
+    initializeMsw(): void;
+    /** Spread onto `Preview.loaders` — required for `parameters.msw.handlers` and `parameters.pco.view`. */
+    loaders: readonly [typeof pcoViewLoader, (context: msw_storybook_addon.Context) => Promise<{}>] | readonly [(context: msw_storybook_addon.Context) => Promise<{}>];
+};
+
+type StoryPlayContext = {
+    canvasElement: HTMLElement;
+};
+type StoryPlayFn<T extends ComponentTestObject> = (view: T, context: StoryPlayContext) => Promise<void> | void;
+/**
+ * Binds a ViewTestObject to the Storybook canvas and runs play interactions.
+ * The story must render the same UI the ViewTestObject targets.
+ */
+declare function createStoryPlay<T extends ComponentTestObject>(createView: () => T, playFn: StoryPlayFn<T>): ({ canvasElement }: StoryPlayContext) => Promise<void>;
+type ViewMockSession<T extends BaseViewTestObject> = {
+    handlers: HttpHandler[];
+    view: T;
+    mocks: ReturnType<T['setupMockData']>;
+};
+type ViewTestObjectClass<T extends BaseViewTestObject> = {
+    new (): T;
+    mockSession(setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void): ViewMockSession<T>;
+};
+/**
+ * One-time mock session for a story: share handlers in `parameters.msw` and `mocks` in optional `play`.
+ * Call at module scope when defining the story (not inside `play`).
+ */
+declare function createViewMockSession<T extends BaseViewTestObject>(ViewClass: ViewTestObjectClass<T>, setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void): ViewMockSession<T>;
+type DefineViewStoryOptions<T extends BaseViewTestObject> = {
+    setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void;
+};
+/**
+ * Storybook helpers from a ViewTestObject class — parameters and session only (no bundled `play`).
+ */
+declare function defineViewStory<T extends BaseViewTestObject>(ViewClass: ViewTestObjectClass<T>, options?: DefineViewStoryOptions<T>): {
+    parameters: {
+        msw: {
+            handlers: HttpHandler[];
+        };
+    };
+    mocks: ReturnType<T["setupMockData"]>;
+    view: T;
+};
+
+export { type DefineViewStoryOptions, type PcoStoryParameters, type PcoViewConfig, type StoryPlayContext, type StoryPlayFn, type StorybookMswPreviewOptions, type ViewAssertionContext, type ViewMockSession, createStoryPlay, createViewAssertionPlay, createViewMockSession, defineViewStory, getStorybookMswPreviewConfig, pcoViewLoader, setupPCOStorybook };

package/dist/index.js

@@ -0,0 +1,95 @@
+// src/index.ts
+import { expect } from "@storybook/test";
+
+// src/setupPCOStorybook.ts
+import { fn, userEvent } from "@storybook/test";
+import { configureRuntime } from "@page-component-object/core";
+function setupPCOStorybook() {
+  configureRuntime({
+    spyFactory: { fn: (impl) => fn(impl) },
+    createUserAgent: () => userEvent
+  });
+}
+
+// src/getStorybookMswPreviewConfig.ts
+import {
+  initialize,
+  mswLoader
+} from "msw-storybook-addon";
+
+// src/pcoViewLoader.ts
+import { applyRequestHandlers } from "msw-storybook-addon";
+async function pcoViewLoader({
+  parameters
+}) {
+  const config = parameters.pco;
+  if (!config?.view) {
+    return {};
+  }
+  const session = config.view.mockSession(config.setupMocks);
+  await applyRequestHandlers({ handlers: session.handlers });
+  return { pco: { session } };
+}
+function createViewAssertionPlay(fn2) {
+  return async ({
+    canvasElement,
+    loaded
+  }) => {
+    const session = loaded.pco?.session;
+    if (!session) {
+      throw new Error(
+        "createViewAssertionPlay requires parameters.pco.view and pcoViewLoader in preview loaders"
+      );
+    }
+    session.view.bindToRoot(canvasElement);
+    await fn2({ view: session.view, mocks: session.mocks, canvasElement });
+  };
+}
+
+// src/getStorybookMswPreviewConfig.ts
+var mswInitialized = false;
+function getStorybookMswPreviewConfig(options = { onUnhandledRequest: "warn" }) {
+  const { pcoViewLoader: usePcoViewLoader = true, ...initializeOptions } = options;
+  return {
+    /** Call once at module scope in preview (before exporting `preview`). */
+    initializeMsw() {
+      if (!mswInitialized) {
+        initialize(initializeOptions);
+        mswInitialized = true;
+      }
+    },
+    /** Spread onto `Preview.loaders` — required for `parameters.msw.handlers` and `parameters.pco.view`. */
+    loaders: usePcoViewLoader ? [pcoViewLoader, mswLoader] : [mswLoader]
+  };
+}
+
+// src/index.ts
+function createStoryPlay(createView, playFn) {
+  return async ({ canvasElement }) => {
+    const view = createView();
+    view.bindToRoot(canvasElement);
+    await playFn(view, { canvasElement });
+  };
+}
+function createViewMockSession(ViewClass, setupMocks) {
+  return ViewClass.mockSession(setupMocks);
+}
+function defineViewStory(ViewClass, options = {}) {
+  const session = createViewMockSession(ViewClass, options.setupMocks);
+  return {
+    parameters: { msw: { handlers: session.handlers } },
+    mocks: session.mocks,
+    view: session.view
+  };
+}
+export {
+  createStoryPlay,
+  createViewAssertionPlay,
+  createViewMockSession,
+  defineViewStory,
+  expect,
+  getStorybookMswPreviewConfig,
+  pcoViewLoader,
+  setupPCOStorybook
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/setupPCOStorybook.ts","../src/getStorybookMswPreviewConfig.ts","../src/pcoViewLoader.ts"],"sourcesContent":["import type { HttpHandler } from '@page-component-object/msw';\r\nimport { BaseViewTestObject } from '@page-component-object/react';\r\nimport { ComponentTestObject } from '@page-component-object/queries';\r\n\r\nexport type StoryPlayContext = {\r\n  canvasElement: HTMLElement;\r\n};\r\n\r\nexport type StoryPlayFn<T extends ComponentTestObject> = (\r\n  view: T,\r\n  context: StoryPlayContext,\r\n) => Promise<void> | void;\r\n\r\n/**\r\n * Binds a ViewTestObject to the Storybook canvas and runs play interactions.\r\n * The story must render the same UI the ViewTestObject targets.\r\n */\r\nexport function createStoryPlay<T extends ComponentTestObject>(\r\n  createView: () => T,\r\n  playFn: StoryPlayFn<T>,\r\n) {\r\n  return async ({ canvasElement }: StoryPlayContext) => {\r\n    const view = createView();\r\n    view.bindToRoot(canvasElement);\r\n    await playFn(view, { canvasElement });\r\n  };\r\n}\r\n\r\nexport type ViewMockSession<T extends BaseViewTestObject> = {\r\n  handlers: HttpHandler[];\r\n  view: T;\r\n  mocks: ReturnType<T['setupMockData']>;\r\n};\r\n\r\ntype ViewTestObjectClass<T extends BaseViewTestObject> = {\r\n  new (): T;\r\n  mockSession(setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void): ViewMockSession<T>;\r\n};\r\n\r\n/**\r\n * One-time mock session for a story: share handlers in `parameters.msw` and `mocks` in optional `play`.\r\n * Call at module scope when defining the story (not inside `play`).\r\n */\r\nexport function createViewMockSession<T extends BaseViewTestObject>(\r\n  ViewClass: ViewTestObjectClass<T>,\r\n  setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void,\r\n): ViewMockSession<T> {\r\n  return ViewClass.mockSession(setupMocks);\r\n}\r\n\r\nexport type DefineViewStoryOptions<T extends BaseViewTestObject> = {\r\n  setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void;\r\n};\r\n\r\n/**\r\n * Storybook helpers from a ViewTestObject class — parameters and session only (no bundled `play`).\r\n */\r\nexport function defineViewStory<T extends BaseViewTestObject>(\r\n  ViewClass: ViewTestObjectClass<T>,\r\n  options: DefineViewStoryOptions<T> = {},\r\n) {\r\n  const session = createViewMockSession(ViewClass, options.setupMocks);\r\n\r\n  return {\r\n    parameters: { msw: { handlers: session.handlers } },\r\n    mocks: session.mocks,\r\n    view: session.view,\r\n  };\r\n}\r\n\r\n/** Re-export expect configured for Storybook test runner. */\r\nexport { expect } from '@storybook/test';\r\nexport { setupPCOStorybook } from './setupPCOStorybook';\r\nexport {\r\n  getStorybookMswPreviewConfig,\r\n  type StorybookMswPreviewOptions,\r\n  type MswParameters,\r\n} from './getStorybookMswPreviewConfig';\r\nexport {\r\n  pcoViewLoader,\r\n  createViewAssertionPlay,\r\n  type PcoViewConfig,\r\n  type PcoStoryParameters,\r\n  type ViewAssertionContext,\r\n} from './pcoViewLoader';\r\n","import { fn, userEvent } from '@storybook/test';\r\n\r\nimport { configureRuntime, type UserAgent } from '@page-component-object/core';\r\n\r\nexport function setupPCOStorybook(): void {\r\n  configureRuntime({\r\n    spyFactory: { fn: (impl) => fn(impl) as never },\r\n    createUserAgent: (): UserAgent => userEvent as unknown as UserAgent,\r\n  });\r\n}\r\n","import {\r\n  initialize,\r\n  mswLoader,\r\n  type MswParameters,\r\n} from 'msw-storybook-addon';\r\n\r\nimport { pcoViewLoader } from './pcoViewLoader';\r\n\r\nexport type StorybookMswPreviewOptions = Parameters<typeof initialize>[0] & {\r\n  /** When true (default), include `pcoViewLoader` before `mswLoader` for `parameters.pco.view`. */\r\n  pcoViewLoader?: boolean;\r\n};\r\n\r\nlet mswInitialized = false;\r\n\r\n/**\r\n * MSW wiring for `.storybook/preview.ts` when using `BaseViewTestObject.storyParameters` or `parameters.pco.view`.\r\n *\r\n * @example\r\n * ```ts\r\n * import { setupPCOStorybook, getStorybookMswPreviewConfig } from '@page-component-object/adapter-storybook';\r\n *\r\n * const msw = getStorybookMswPreviewConfig({ onUnhandledRequest: 'warn' });\r\n * setupPCOStorybook();\r\n * msw.initializeMsw();\r\n *\r\n * const preview: Preview = {\r\n *   loaders: msw.loaders,\r\n *   // …decorators, parameters\r\n * };\r\n * ```\r\n */\r\nexport function getStorybookMswPreviewConfig(\r\n  options: StorybookMswPreviewOptions = { onUnhandledRequest: 'warn' },\r\n) {\r\n  const { pcoViewLoader: usePcoViewLoader = true, ...initializeOptions } = options;\r\n\r\n  return {\r\n    /** Call once at module scope in preview (before exporting `preview`). */\r\n    initializeMsw() {\r\n      if (!mswInitialized) {\r\n        initialize(initializeOptions);\r\n        mswInitialized = true;\r\n      }\r\n    },\r\n    /** Spread onto `Preview.loaders` — required for `parameters.msw.handlers` and `parameters.pco.view`. */\r\n    loaders: usePcoViewLoader ? ([pcoViewLoader, mswLoader] as const) : ([mswLoader] as const),\r\n  };\r\n}\r\n\r\nexport type { MswParameters };\r\n","import { applyRequestHandlers } from 'msw-storybook-addon';\n\nimport type { MockSession } from '@page-component-object/msw';\nimport { BaseViewTestObject } from '@page-component-object/react';\n\nexport type PcoViewConfig<T extends BaseViewTestObject = BaseViewTestObject> = {\n  view: ViewTestObjectClass<T>;\n  /** Runs after `setupMockData()` on the view instance. */\n  setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void;\n};\n\nexport type PcoStoryParameters = {\n  pco?: PcoViewConfig;\n};\n\ntype ViewMockSession<T extends BaseViewTestObject> = MockSession<T> & { view: T };\n\ntype ViewTestObjectClass<T extends BaseViewTestObject> = {\n  new (): T;\n  mockSession(setupMocks?: (view: T, mocks: ReturnType<T['setupMockData']>) => void): ViewMockSession<T>;\n};\n\n/**\n * Storybook loader: resolves `parameters.pco` into MSW handlers before render.\n * No-op when `pco.view` is absent. Pair with `getStorybookMswPreviewConfig()`.\n */\nexport async function pcoViewLoader({\n  parameters,\n}: {\n  parameters: PcoStoryParameters;\n}): Promise<{ pco?: { session: ViewMockSession<BaseViewTestObject> } }> {\n  const config = parameters.pco;\n  if (!config?.view) {\n    return {};\n  }\n\n  const session = config.view.mockSession(config.setupMocks);\n  await applyRequestHandlers({ handlers: session.handlers });\n\n  return { pco: { session } };\n}\n\nexport type ViewAssertionContext<T extends BaseViewTestObject> = {\n  view: T;\n  mocks: ReturnType<T['setupMockData']>;\n  canvasElement: HTMLElement;\n};\n\n/**\n * Optional test-runner play that asserts against spies from `pcoViewLoader`.\n */\nexport function createViewAssertionPlay<T extends BaseViewTestObject>(\n  fn: (ctx: ViewAssertionContext<T>) => Promise<void> | void,\n) {\n  return async ({\n    canvasElement,\n    loaded,\n  }: {\n    canvasElement: HTMLElement;\n    loaded: { pco?: { session: MockSession<T> & { view: T } } };\n  }) => {\n    const session = loaded.pco?.session;\n    if (!session) {\n      throw new Error(\n        'createViewAssertionPlay requires parameters.pco.view and pcoViewLoader in preview loaders',\n      );\n    }\n    session.view.bindToRoot(canvasElement);\n    await fn({ view: session.view, mocks: session.mocks, canvasElement });\n  };\n}\n"],"mappings":";AAuEA,SAAS,cAAc;;;ACvEvB,SAAS,IAAI,iBAAiB;AAE9B,SAAS,wBAAwC;AAE1C,SAAS,oBAA0B;AACxC,mBAAiB;AAAA,IACf,YAAY,EAAE,IAAI,CAAC,SAAS,GAAG,IAAI,EAAW;AAAA,IAC9C,iBAAiB,MAAiB;AAAA,EACpC,CAAC;AACH;;;ACTA;AAAA,EACE;AAAA,EACA;AAAA,OAEK;;;ACJP,SAAS,4BAA4B;AA0BrC,eAAsB,cAAc;AAAA,EAClC;AACF,GAEwE;AACtE,QAAM,SAAS,WAAW;AAC1B,MAAI,CAAC,QAAQ,MAAM;AACjB,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,UAAU,OAAO,KAAK,YAAY,OAAO,UAAU;AACzD,QAAM,qBAAqB,EAAE,UAAU,QAAQ,SAAS,CAAC;AAEzD,SAAO,EAAE,KAAK,EAAE,QAAQ,EAAE;AAC5B;AAWO,SAAS,wBACdA,KACA;AACA,SAAO,OAAO;AAAA,IACZ;AAAA,IACA;AAAA,EACF,MAGM;AACJ,UAAM,UAAU,OAAO,KAAK;AAC5B,QAAI,CAAC,SAAS;AACZ,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,YAAQ,KAAK,WAAW,aAAa;AACrC,UAAMA,IAAG,EAAE,MAAM,QAAQ,MAAM,OAAO,QAAQ,OAAO,cAAc,CAAC;AAAA,EACtE;AACF;;;ADzDA,IAAI,iBAAiB;AAmBd,SAAS,6BACd,UAAsC,EAAE,oBAAoB,OAAO,GACnE;AACA,QAAM,EAAE,eAAe,mBAAmB,MAAM,GAAG,kBAAkB,IAAI;AAEzE,SAAO;AAAA;AAAA,IAEL,gBAAgB;AACd,UAAI,CAAC,gBAAgB;AACnB,mBAAW,iBAAiB;AAC5B,yBAAiB;AAAA,MACnB;AAAA,IACF;AAAA;AAAA,IAEA,SAAS,mBAAoB,CAAC,eAAe,SAAS,IAAe,CAAC,SAAS;AAAA,EACjF;AACF;;;AF/BO,SAAS,gBACd,YACA,QACA;AACA,SAAO,OAAO,EAAE,cAAc,MAAwB;AACpD,UAAM,OAAO,WAAW;AACxB,SAAK,WAAW,aAAa;AAC7B,UAAM,OAAO,MAAM,EAAE,cAAc,CAAC;AAAA,EACtC;AACF;AAiBO,SAAS,sBACd,WACA,YACoB;AACpB,SAAO,UAAU,YAAY,UAAU;AACzC;AASO,SAAS,gBACd,WACA,UAAqC,CAAC,GACtC;AACA,QAAM,UAAU,sBAAsB,WAAW,QAAQ,UAAU;AAEnE,SAAO;AAAA,IACL,YAAY,EAAE,KAAK,EAAE,UAAU,QAAQ,SAAS,EAAE;AAAA,IAClD,OAAO,QAAQ;AAAA,IACf,MAAM,QAAQ;AAAA,EAChB;AACF;","names":["fn"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@page-component-object/adapter-storybook",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@page-component-object/msw": "0.1.0",
+    "@page-component-object/core": "0.1.0",
+    "@page-component-object/react": "0.1.0",
+    "@page-component-object/queries": "0.1.0"
+  },
+  "peerDependencies": {
+    "@storybook/test": "^8.0.0 || ^9.0.0",
+    "@testing-library/react": "^16.0.0",
+    "msw": "^2.0.0",
+    "msw-storybook-addon": "^2.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.4.0 || ^7.0.0",
+    "storybook": "^8.0.0 || ^9.0.0"
+  },
+  "devDependencies": {
+    "@storybook/test": "^8.6.0",
+    "msw": "^2.7.0",
+    "msw-storybook-addon": "^2.0.4",
+    "rimraf": "^6.0.1",
+    "storybook": "^8.6.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dvegap95/page-component-test-object.git",
+    "directory": "packages/adapters/storybook"
+  },
+  "homepage": "https://github.com/dvegap95/page-component-test-object#readme",
+  "bugs": {
+    "url": "https://github.com/dvegap95/page-component-test-object/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}