@usefragments/core 1.10.2 → 2.0.0

package/src/storyAdapter.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, it, expect, beforeEach } from "vitest";
-import { createElement, type ComponentType } from "react";
+import { createElement, type ComponentType, type ReactNode } from "react";
 import {
   storyModuleToFragment,
   setPreviewConfig,
@@ -94,8 +94,7 @@ describe("storyModuleToFragment", () => {
   describe("CSF2 Template.bind() pattern", () => {
     it("should handle CSF2 story functions", () => {
       // Simulate Template.bind({}) pattern
-      const Template: CSF2Story = (args) =>
-        createElement(MockComponent, args);
+      const Template: CSF2Story = (args) => createElement(MockComponent, args);
 
       const Primary: CSF2Story = Template.bind({});
       Primary.args = { label: "Primary Button" };
@@ -120,8 +119,7 @@ describe("storyModuleToFragment", () => {
     });
 
     it("should use storyName when provided on CSF2 story", () => {
-      const Template: CSF2Story = (args) =>
-        createElement(MockComponent, args);
+      const Template: CSF2Story = (args) => createElement(MockComponent, args);
 
       const MyStory: CSF2Story = Template.bind({});
       MyStory.args = { label: "Test" };
@@ -142,6 +140,22 @@ describe("storyModuleToFragment", () => {
   });
 
   describe("CSF3 object stories", () => {
+    it("retains a minimal empty story", () => {
+      const storyModule: StoryModule = {
+        default: {
+          title: "Components/Button",
+          component: MockComponent,
+        },
+        Default: {} as Story,
+      };
+
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
+
+      expect(fragment!.variants).toHaveLength(1);
+      expect(fragment!.variants[0].name).toBe("Default");
+      expect(fragment!.variants[0].args).toBeUndefined();
+    });
+
     it("should handle CSF3 story objects with args", () => {
       const storyModule: StoryModule = {
         default: {
@@ -320,6 +334,40 @@ describe("storyModuleToFragment", () => {
   });
 
   describe("decorators", () => {
+    it("preserves Storybook's declared decorator composition order", () => {
+      const calls: string[] = [];
+      const decorator =
+        (name: string) =>
+        (Story: () => ReactNode): ReactNode => {
+          calls.push(name);
+          return Story();
+        };
+
+      setPreviewConfig({ decorators: [decorator("global-first"), decorator("global-last")] });
+      const storyModule: StoryModule = {
+        default: {
+          title: "Components/Button",
+          component: MockComponent,
+          decorators: [decorator("meta-first"), decorator("meta-last")],
+        },
+        Default: {
+          decorators: [decorator("story-first"), decorator("story-last")],
+        } as Story,
+      };
+
+      const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
+      fragment!.variants[0].render();
+
+      expect(calls).toEqual([
+        "story-last",
+        "story-first",
+        "meta-last",
+        "meta-first",
+        "global-last",
+        "global-first",
+      ]);
+    });
+
     it("should apply story decorators", () => {
       let decoratorCalled = false;
 
@@ -455,7 +503,8 @@ describe("storyModuleToFragment", () => {
   });
 
   describe("loaders", () => {
-    it("should collect loaders from story", () => {
+    it("reports Storybook loader presence without executing with a fabricated context", () => {
+      let calls = 0;
       const storyModule: StoryModule = {
         default: {
           title: "Components/Button",
@@ -463,17 +512,24 @@ describe("storyModuleToFragment", () => {
         },
         WithLoader: {
           args: { label: "Test" },
-          loaders: [async () => ({ data: "loaded" })],
+          loaders: [
+            async () => {
+              calls++;
+              return { data: "loaded" };
+            },
+          ],
         } as Story,
       };
 
       const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      expect(fragment!.variants[0].loaders).toBeDefined();
-      expect(fragment!.variants[0].loaders).toHaveLength(1);
+      expect(fragment!.variants[0].hasUnsupportedStorybookLoaders).toBe(true);
+      expect(fragment!.variants[0].loaders).toBeUndefined();
+      expect(calls).toBe(0);
     });
 
-    it("should collect loaders from meta and story", () => {
+    it("reports preview and meta loaders without replaying them", () => {
+      setPreviewConfig({ loaders: [async () => ({ globalData: "global" })] });
       const storyModule: StoryModule = {
         default: {
           title: "Components/Button",
@@ -488,8 +544,8 @@ describe("storyModuleToFragment", () => {
 
       const fragment = storyModuleToFragment(storyModule, "Button.stories.tsx");
 
-      // Should have both meta and story loaders
-      expect(fragment!.variants[0].loaders).toHaveLength(2);
+      expect(fragment!.variants[0].hasUnsupportedStorybookLoaders).toBe(true);
+      expect(fragment!.variants[0].loaders).toBeUndefined();
     });
   });
 

package/src/storyAdapter.ts

@@ -8,9 +8,8 @@
  * Supports Storybook 8.x with both CSF2 (Template.bind) and CSF3 (object stories).
  */
 
-import type { ComponentType, ReactNode } from "react";
+import { createElement, type ComponentType, type ReactNode } from "react";
 import { toId, storyNameFromExport, isExportStory } from "./storybook-csf.js";
-import { getCreateElement } from "./react-create-element.js";
 import type {
   FragmentDefinition,
   FragmentMeta,
@@ -18,7 +17,6 @@ import type {
   PropDefinition,
   FragmentVariant,
   ControlType,
-  VariantLoader,
   PlayFunction,
   PlayFunctionContext,
   VariantRenderOptions,
@@ -30,10 +28,7 @@ export { toId, storyNameFromExport, isExportStory };
 /**
  * Storybook decorator function signature
  */
-export type Decorator = (
-  Story: () => ReactNode,
-  context: StoryContext
-) => ReactNode;
+export type Decorator = (Story: () => ReactNode, context: StoryContext) => ReactNode;
 
 /**
  * Storybook loader function signature
@@ -223,9 +218,7 @@ export function storyModuleToFragment(
 
   const fragmentMeta: FragmentMeta = {
     name: componentName,
-    description:
-      meta.parameters?.docs?.description?.component ??
-      `${componentName} component`,
+    description: meta.parameters?.docs?.description?.component ?? `${componentName} component`,
     category,
     tags: meta.tags?.filter((t) => t !== "autodocs"),
     status: "stable",
@@ -360,14 +353,24 @@ function extractControlInfo(argType: StoryArgType): {
     return {};
   }
 
-  const control = typeof argType.control === "string"
-    ? { type: argType.control }
-    : argType.control;
+  const control = typeof argType.control === "string" ? { type: argType.control } : argType.control;
 
   // Map control type string to ControlType
   const validControlTypes: ControlType[] = [
-    "text", "number", "range", "boolean", "select", "multi-select",
-    "radio", "inline-radio", "check", "inline-check", "object", "file", "color", "date"
+    "text",
+    "number",
+    "range",
+    "boolean",
+    "select",
+    "multi-select",
+    "radio",
+    "inline-radio",
+    "check",
+    "inline-check",
+    "object",
+    "file",
+    "color",
+    "date",
   ];
 
   const controlType = validControlTypes.includes(control.type as ControlType)
@@ -461,10 +464,11 @@ function inferPropType(argType: StoryArgType): PropDefinition["type"] {
  * Handles both CSF 3 (objects) and CSF 2 (functions from Template.bind({}))
  */
 function isStory(value: unknown): value is Story | CSF2Story {
-  // CSF 3: Story is an object with args/render/play
-  if (typeof value === "object" && value !== null) {
-    const obj = value as Record<string, unknown>;
-    if ("args" in obj || "render" in obj || "play" in obj) return true;
+  // CSF 3 permits a minimal empty object. Storybook's native
+  // includeStories/excludeStories decision runs before this check, so do not
+  // silently discard `{}` after that filter has accepted its export name.
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return true;
   }
 
   // CSF 2: Story is a function (from Template.bind({})) with args attached
@@ -544,8 +548,10 @@ function extractVariants(
     // Get story tags
     const storyTags = typeof story === "object" ? story.tags : undefined;
 
-    // Collect loaders from global, meta, and story (in order)
-    const loaders = collectLoaders(meta, story);
+    // Fragment loaders do not receive Storybook's original context. Preserve
+    // presence only; replaying a Storybook loader with a manufactured context
+    // is misleading and can change its behaviour.
+    const hasUnsupportedStorybookLoaders = hasStorybookLoaders(meta, story);
 
     // Compute the merged args for this variant (for code generation)
     const variantArgs = {
@@ -566,7 +572,7 @@ function extractVariants(
       ...(wrappedPlay && { play: wrappedPlay }),
       ...(storyId && { storyId }),
       ...(storyTags && { tags: storyTags }),
-      ...(loaders.length > 0 && { loaders }),
+      ...(hasUnsupportedStorybookLoaders && { hasUnsupportedStorybookLoaders: true }),
       ...(hasArgs && { args: variantArgs }),
     });
   }
@@ -574,47 +580,13 @@ function extractVariants(
   return variants;
 }
 
-/**
- * Collect loaders from global, meta, and story levels
- * Returns wrapped loader functions that execute with context
- */
-function collectLoaders(
-  meta: StoryMeta,
-  story: Story | CSF2Story
-): VariantLoader[] {
-  const allLoaders: Loader[] = [
-    ...(globalPreviewConfig.loaders ?? []),
-    ...(meta.loaders ?? []),
-    ...(typeof story === "function" ? story.loaders ?? [] : story.loaders ?? []),
-  ];
-
-  if (allLoaders.length === 0) {
-    return [];
-  }
-
-  // Wrap each loader to execute without requiring context at call time
-  // The actual context will be built when the loader is executed
-  return allLoaders.map((loader) => {
-    return async (): Promise<Record<string, unknown>> => {
-      // Create a minimal context for loader execution
-      const minimalContext: StoryContext = {
-        args: {},
-        argTypes: {},
-        globals: {},
-        parameters: {},
-        id: "",
-        kind: meta.title || "Unknown",
-        name: "",
-        story: "",
-        viewMode: "story",
-        loaded: {},
-        abortSignal: new AbortController().signal,
-        componentId: "",
-        title: meta.title || "Unknown",
-      };
-      return loader(minimalContext);
-    };
-  });
+/** Report loader presence without fabricating a Storybook context. */
+function hasStorybookLoaders(meta: StoryMeta, story: Story | CSF2Story): boolean {
+  return (
+    (globalPreviewConfig.loaders?.length ?? 0) > 0 ||
+    (meta.loaders?.length ?? 0) > 0 ||
+    (story.loaders?.length ?? 0) > 0
+  );
 }
 
 /**
@@ -683,7 +655,7 @@ function createRenderFunction(
       ...globalPreviewConfig.args,
       ...meta.args,
       ...(typeof story === "function" ? story.args : story.args),
-      ...options?.args,  // Runtime overrides from viewer props panel
+      ...options?.args, // Runtime overrides from viewer props panel
     };
 
     const loadedData = options?.loadedData;
@@ -701,27 +673,24 @@ function createRenderFunction(
       // CSF 3: Story has custom render function
       // Support both render(args) and render(args, context) signatures
       renderFn = () =>
-        story.render!.length >= 2
-          ? story.render!(args, context)
-          : story.render!(args);
+        story.render!.length >= 2 ? story.render!(args, context) : story.render!(args);
     } else if (meta.render) {
       // CSF 3: Meta has default render function
       renderFn = () =>
-        meta.render!.length >= 2
-          ? meta.render!(args, context)
-          : meta.render!(args);
+        meta.render!.length >= 2 ? meta.render!(args, context) : meta.render!(args);
     } else {
       // Default: render component with args
-      renderFn = () => getCreateElement()(component, args);
+      renderFn = () => createElement(component, args);
     }
 
-    // Collect decorators in Storybook order
-    // story → meta → global, then reverse to apply innermost first
+    // Storybook composes declared decorators in sequence. Keeping that
+    // sequence makes the last declaration outermost instead of reversing
+    // every global, meta, and story-level decorator list.
     const allDecorators = [
       ...(globalPreviewConfig.decorators ?? []),
       ...(meta.decorators ?? []),
-      ...(typeof story === "function" ? story.decorators ?? [] : story.decorators ?? []),
-    ].reverse();
+      ...(typeof story === "function" ? (story.decorators ?? []) : (story.decorators ?? [])),
+    ];
 
     // Apply decorators if any
     if (allDecorators.length > 0) {

package/src/topology/resolve-area.ts

@@ -6,7 +6,7 @@
  * preview, cross-repo reconciliation) import it; none reimplements glob/area
  * logic. Pure and browser-safe — no Node, no parser deps.
  *
- * See `apps/cloud/docs/topology/01-architecture.md §1`.
+ * See `docs/fragments-v1/ARCHITECTURE.md §1`.
  */
 
 export type AreaCriticality = "low" | "medium" | "high" | "revenue" | "regulated";