@usefragments/core 1.9.1 → 1.10.1

package/dist/preview-runtime.d.ts

@@ -0,0 +1,48 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { V as VariantRenderOptions, a as VariantLoader } from './governance-CLk_wkP9.js';
+import 'zod';
+import './topology/index.js';
+import './types-xJ2xyp_G.js';
+
+/**
+ * Minimal contract for rendering a preview variant.
+ * Compatible with fragment variants and Storybook-adapted variants.
+ */
+interface PreviewVariantLike {
+    render: (options?: VariantRenderOptions) => ReactNode;
+    loaders?: VariantLoader[];
+}
+interface PreviewRuntimeState {
+    content: ReactNode | null;
+    isLoading: boolean;
+    error: Error | null;
+    loadedData?: Record<string, unknown>;
+}
+interface PreviewRuntimeOptions {
+    variant?: PreviewVariantLike | null;
+    loadedData?: Record<string, unknown>;
+}
+/**
+ * Execute all variant loaders and merge their payloads.
+ * `loadedData` is applied last so host-level overrides win.
+ */
+declare function executeVariantLoaders(loaders: VariantLoader[] | undefined, loadedData?: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+/**
+ * Resolve a full runtime state (loader execution + render) in one async call.
+ * This is useful for testing and for hook/component orchestration.
+ */
+declare function resolvePreviewRuntimeState(options: PreviewRuntimeOptions): Promise<PreviewRuntimeState>;
+/**
+ * Hook for rendering a preview variant with loader support.
+ */
+declare function usePreviewVariantRuntime(options: PreviewRuntimeOptions): PreviewRuntimeState;
+interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {
+    children: (state: PreviewRuntimeState) => ReactNode;
+}
+/**
+ * Render-prop component wrapper around `usePreviewVariantRuntime`.
+ */
+declare function PreviewVariantRuntime({ variant, loadedData, children, }: PreviewVariantRuntimeProps): react_jsx_runtime.JSX.Element;
+
+export { type PreviewRuntimeOptions, type PreviewRuntimeState, type PreviewVariantLike, PreviewVariantRuntime, executeVariantLoaders, resolvePreviewRuntimeState, usePreviewVariantRuntime };

package/dist/preview-runtime.js

@@ -0,0 +1,91 @@
+// src/preview-runtime.tsx
+import { useEffect, useState } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+var EMPTY_STATE = {
+  content: null,
+  isLoading: false,
+  error: null,
+  loadedData: void 0
+};
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+async function executeVariantLoaders(loaders, loadedData) {
+  const hasLoaders = !!loaders && loaders.length > 0;
+  if (!hasLoaders) {
+    return loadedData;
+  }
+  const results = await Promise.all(loaders.map((loader) => loader()));
+  const mergedFromLoaders = results.reduce(
+    (acc, result) => ({ ...acc, ...result }),
+    {}
+  );
+  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
+}
+async function resolvePreviewRuntimeState(options) {
+  const { variant, loadedData } = options;
+  if (!variant) {
+    return EMPTY_STATE;
+  }
+  try {
+    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);
+    const content = variant.render({ loadedData: mergedLoadedData });
+    return {
+      content,
+      isLoading: false,
+      error: null,
+      loadedData: mergedLoadedData
+    };
+  } catch (error) {
+    return {
+      content: null,
+      isLoading: false,
+      error: toError(error),
+      loadedData: void 0
+    };
+  }
+}
+function usePreviewVariantRuntime(options) {
+  const { variant, loadedData } = options;
+  const [state, setState] = useState(EMPTY_STATE);
+  useEffect(() => {
+    let cancelled = false;
+    if (!variant) {
+      setState(EMPTY_STATE);
+      return () => {
+        cancelled = true;
+      };
+    }
+    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
+    setState({
+      content: null,
+      isLoading: hasLoaders,
+      error: null,
+      loadedData: void 0
+    });
+    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
+      if (!cancelled) {
+        setState(nextState);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, loadedData]);
+  return state;
+}
+function PreviewVariantRuntime({
+  variant,
+  loadedData,
+  children
+}) {
+  const state = usePreviewVariantRuntime({ variant, loadedData });
+  return /* @__PURE__ */ jsx(Fragment, { children: children(state) });
+}
+export {
+  PreviewVariantRuntime,
+  executeVariantLoaders,
+  resolvePreviewRuntimeState,
+  usePreviewVariantRuntime
+};
+//# sourceMappingURL=preview-runtime.js.map

package/dist/preview-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/preview-runtime.tsx"],"sourcesContent":["import { useEffect, useState, type ReactNode } from \"react\";\nimport type { VariantLoader, VariantRenderOptions } from \"./types.js\";\n\n/**\n * Minimal contract for rendering a preview variant.\n * Compatible with fragment variants and Storybook-adapted variants.\n */\nexport interface PreviewVariantLike {\n  render: (options?: VariantRenderOptions) => ReactNode;\n  loaders?: VariantLoader[];\n}\n\nexport interface PreviewRuntimeState {\n  content: ReactNode | null;\n  isLoading: boolean;\n  error: Error | null;\n  loadedData?: Record<string, unknown>;\n}\n\nexport interface PreviewRuntimeOptions {\n  variant?: PreviewVariantLike | null;\n  loadedData?: Record<string, unknown>;\n}\n\nconst EMPTY_STATE: PreviewRuntimeState = {\n  content: null,\n  isLoading: false,\n  error: null,\n  loadedData: undefined,\n};\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\n/**\n * Execute all variant loaders and merge their payloads.\n * `loadedData` is applied last so host-level overrides win.\n */\nexport async function executeVariantLoaders(\n  loaders: VariantLoader[] | undefined,\n  loadedData?: Record<string, unknown>,\n): Promise<Record<string, unknown> | undefined> {\n  const hasLoaders = !!loaders && loaders.length > 0;\n  if (!hasLoaders) {\n    return loadedData;\n  }\n\n  const results = await Promise.all(loaders.map((loader) => loader()));\n  const mergedFromLoaders = results.reduce<Record<string, unknown>>(\n    (acc, result) => ({ ...acc, ...result }),\n    {},\n  );\n\n  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;\n}\n\n/**\n * Resolve a full runtime state (loader execution + render) in one async call.\n * This is useful for testing and for hook/component orchestration.\n */\nexport async function resolvePreviewRuntimeState(\n  options: PreviewRuntimeOptions,\n): Promise<PreviewRuntimeState> {\n  const { variant, loadedData } = options;\n  if (!variant) {\n    return EMPTY_STATE;\n  }\n\n  try {\n    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);\n    const content = variant.render({ loadedData: mergedLoadedData });\n    return {\n      content,\n      isLoading: false,\n      error: null,\n      loadedData: mergedLoadedData,\n    };\n  } catch (error) {\n    return {\n      content: null,\n      isLoading: false,\n      error: toError(error),\n      loadedData: undefined,\n    };\n  }\n}\n\n/**\n * Hook for rendering a preview variant with loader support.\n */\nexport function usePreviewVariantRuntime(\n  options: PreviewRuntimeOptions,\n): PreviewRuntimeState {\n  const { variant, loadedData } = options;\n  const [state, setState] = useState<PreviewRuntimeState>(EMPTY_STATE);\n\n  useEffect(() => {\n    let cancelled = false;\n\n    if (!variant) {\n      setState(EMPTY_STATE);\n      return () => {\n        cancelled = true;\n      };\n    }\n\n    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;\n    setState({\n      content: null,\n      isLoading: hasLoaders,\n      error: null,\n      loadedData: undefined,\n    });\n\n    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {\n      if (!cancelled) {\n        setState(nextState);\n      }\n    });\n\n    return () => {\n      cancelled = true;\n    };\n  }, [variant, loadedData]);\n\n  return state;\n}\n\ninterface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {\n  children: (state: PreviewRuntimeState) => ReactNode;\n}\n\n/**\n * Render-prop component wrapper around `usePreviewVariantRuntime`.\n */\nexport function PreviewVariantRuntime({\n  variant,\n  loadedData,\n  children,\n}: PreviewVariantRuntimeProps) {\n  const state = usePreviewVariantRuntime({ variant, loadedData });\n  return <>{children(state)}</>;\n}\n"],"mappings":";AAAA,SAAS,WAAW,gBAAgC;AA8I3C;AAtHT,IAAM,cAAmC;AAAA,EACvC,SAAS;AAAA,EACT,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd;AAEA,SAAS,QAAQ,OAAuB;AACtC,SAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AACjE;AAMA,eAAsB,sBACpB,SACA,YAC8C;AAC9C,QAAM,aAAa,CAAC,CAAC,WAAW,QAAQ,SAAS;AACjD,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,MAAM,QAAQ,IAAI,QAAQ,IAAI,CAAC,WAAW,OAAO,CAAC,CAAC;AACnE,QAAM,oBAAoB,QAAQ;AAAA,IAChC,CAAC,KAAK,YAAY,EAAE,GAAG,KAAK,GAAG,OAAO;AAAA,IACtC,CAAC;AAAA,EACH;AAEA,SAAO,aAAa,EAAE,GAAG,mBAAmB,GAAG,WAAW,IAAI;AAChE;AAMA,eAAsB,2BACpB,SAC8B;AAC9B,QAAM,EAAE,SAAS,WAAW,IAAI;AAChC,MAAI,CAAC,SAAS;AACZ,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,mBAAmB,MAAM,sBAAsB,QAAQ,SAAS,UAAU;AAChF,UAAM,UAAU,QAAQ,OAAO,EAAE,YAAY,iBAAiB,CAAC;AAC/D,WAAO;AAAA,MACL;AAAA,MACA,WAAW;AAAA,MACX,OAAO;AAAA,MACP,YAAY;AAAA,IACd;AAAA,EACF,SAAS,OAAO;AACd,WAAO;AAAA,MACL,SAAS;AAAA,MACT,WAAW;AAAA,MACX,OAAO,QAAQ,KAAK;AAAA,MACpB,YAAY;AAAA,IACd;AAAA,EACF;AACF;AAKO,SAAS,yBACd,SACqB;AACrB,QAAM,EAAE,SAAS,WAAW,IAAI;AAChC,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA8B,WAAW;AAEnE,YAAU,MAAM;AACd,QAAI,YAAY;AAEhB,QAAI,CAAC,SAAS;AACZ,eAAS,WAAW;AACpB,aAAO,MAAM;AACX,oBAAY;AAAA,MACd;AAAA,IACF;AAEA,UAAM,aAAa,CAAC,CAAC,QAAQ,WAAW,QAAQ,QAAQ,SAAS;AACjE,aAAS;AAAA,MACP,SAAS;AAAA,MACT,WAAW;AAAA,MACX,OAAO;AAAA,MACP,YAAY;AAAA,IACd,CAAC;AAED,+BAA2B,EAAE,SAAS,WAAW,CAAC,EAAE,KAAK,CAAC,cAAc;AACtE,UAAI,CAAC,WAAW;AACd,iBAAS,SAAS;AAAA,MACpB;AAAA,IACF,CAAC;AAED,WAAO,MAAM;AACX,kBAAY;AAAA,IACd;AAAA,EACF,GAAG,CAAC,SAAS,UAAU,CAAC;AAExB,SAAO;AACT;AASO,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AACF,GAA+B;AAC7B,QAAM,QAAQ,yBAAyB,EAAE,SAAS,WAAW,CAAC;AAC9D,SAAO,gCAAG,mBAAS,KAAK,GAAE;AAC5B;","names":[]}

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-eEzCyfes.js';
+export { F as FragmentDefinition, b as FragmentDefinitionV2 } from './governance-CLk_wkP9.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';
@@ -9,7 +9,8 @@ import './types-xJ2xyp_G.js';
  *
  * Import from '@usefragments/core/react' when you need React-typed
  * component definitions. The main '@usefragments/core' entrypoint
- * works without React installed.
+ * works without React installed — story and preview-runtime APIs live on
+ * `@usefragments/core/story` and `@usefragments/core/preview-runtime`.
  */
 
 /**

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-DGHZQTLH.js";
+} from "../chunk-XN3LSDPY.js";
 import "../chunk-JNBFJ34I.js";
 import "../chunk-EIYNNS77.js";
 import {

package/dist/storyAdapter.d.ts

@@ -0,0 +1,187 @@
+import { ReactNode, ComponentType } from 'react';
+import { isExportStory as isExportStory$1, storyNameFromExport as storyNameFromExport$1, toId as toId$1 } from '@storybook/csf';
+import { F as FragmentDefinition } from './governance-CLk_wkP9.js';
+import 'zod';
+import './topology/index.js';
+import './types-xJ2xyp_G.js';
+
+declare const toId: typeof toId$1;
+declare const storyNameFromExport: typeof storyNameFromExport$1;
+declare const isExportStory: typeof isExportStory$1;
+
+/**
+ * Runtime adapter for converting Storybook CSF modules to Fragment definitions.
+ *
+ * This operates on IMPORTED modules at runtime, not source code parsing.
+ * By leveraging Vite's module system, we get 100% accurate render functions
+ * without any regex or AST parsing complexity.
+ *
+ * Supports Storybook 8.x with both CSF2 (Template.bind) and CSF3 (object stories).
+ */
+
+/**
+ * Storybook decorator function signature
+ */
+type Decorator = (Story: () => ReactNode, context: StoryContext) => ReactNode;
+/**
+ * Storybook loader function signature
+ */
+type Loader = (context: StoryContext) => Promise<Record<string, unknown>>;
+/**
+ * Storybook play function signature (internal, extends StoryContext)
+ */
+type StorybookPlayFunction = (context: StorybookPlayFunctionContext) => Promise<void>;
+/**
+ * Context passed to Storybook play functions (extends StoryContext for compatibility)
+ */
+interface StorybookPlayFunctionContext extends StoryContext {
+    canvasElement: HTMLElement;
+    step: (name: string, fn: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Context passed to decorators and render functions
+ */
+interface StoryContext {
+    args: Record<string, unknown>;
+    argTypes: Record<string, StoryArgType>;
+    globals: Record<string, unknown>;
+    parameters: Record<string, unknown>;
+    id: string;
+    kind: string;
+    name: string;
+    story: string;
+    viewMode: "story" | "docs";
+    loaded: Record<string, unknown>;
+    abortSignal: AbortSignal;
+    componentId: string;
+    title: string;
+}
+/**
+ * Storybook Meta (default export)
+ */
+interface StoryMeta {
+    title?: string;
+    component?: ComponentType<unknown>;
+    subcomponents?: Record<string, ComponentType<unknown>>;
+    tags?: string[];
+    parameters?: Record<string, unknown> & {
+        docs?: {
+            description?: {
+                component?: string;
+            };
+        };
+    };
+    argTypes?: Record<string, StoryArgType>;
+    args?: Record<string, unknown>;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    render?: (args: Record<string, unknown>, context?: StoryContext) => ReactNode;
+    includeStories?: string[] | RegExp;
+    excludeStories?: string[] | RegExp;
+}
+/**
+ * Storybook argType definition
+ */
+interface StoryArgType {
+    control?: string | false | {
+        type: string;
+        min?: number;
+        max?: number;
+        step?: number;
+        presetColors?: string[];
+    };
+    options?: string[];
+    description?: string;
+    table?: {
+        defaultValue?: {
+            summary: string;
+        };
+        type?: {
+            summary: string;
+        };
+        category?: string;
+        subcategory?: string;
+        disable?: boolean;
+    };
+    type?: {
+        name: string;
+        required?: boolean;
+    };
+    name?: string;
+    defaultValue?: unknown;
+    if?: {
+        arg?: string;
+        exists?: boolean;
+    };
+    mapping?: Record<string, unknown>;
+    action?: string;
+}
+/**
+ * Storybook Story export (CSF3)
+ */
+interface Story {
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    render?: (args: Record<string, unknown>, context?: StoryContext) => ReactNode;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    play?: StorybookPlayFunction;
+    parameters?: Record<string, unknown> & {
+        docs?: {
+            description?: {
+                story?: string;
+            };
+        };
+    };
+    name?: string;
+    storyName?: string;
+    tags?: string[];
+}
+/**
+ * CSF2 story function (from Template.bind({})) with args attached
+ */
+type CSF2Story = ((args: Record<string, unknown>) => ReactNode) & {
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    decorators?: Decorator[];
+    loaders?: Loader[];
+    play?: StorybookPlayFunction;
+    parameters?: Record<string, unknown>;
+    storyName?: string;
+};
+/**
+ * A complete Storybook module with default meta and named story exports
+ */
+interface StoryModule {
+    default: StoryMeta;
+    [exportName: string]: Story | CSF2Story | StoryMeta | unknown;
+}
+/**
+ * Global configuration from preview.tsx
+ */
+interface PreviewConfig {
+    decorators?: Decorator[];
+    parameters?: Record<string, unknown>;
+    globalTypes?: Record<string, unknown>;
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, StoryArgType>;
+    loaders?: Loader[];
+}
+/**
+ * Set the global preview configuration loaded from .storybook/preview.tsx
+ */
+declare function setPreviewConfig(config: PreviewConfig): void;
+/**
+ * Get the current global preview configuration
+ */
+declare function getPreviewConfig(): PreviewConfig;
+/**
+ * Convert a Storybook module to a Fragment definition at runtime.
+ *
+ * @param storyModule - The imported Storybook module
+ * @param filePath - File path for metadata extraction
+ * @returns A complete FragmentDefinition ready for the viewer
+ */
+declare function storyModuleToFragment(storyModule: StoryModule, filePath: string): FragmentDefinition | null;
+
+export { type CSF2Story, type Decorator, type Loader, type PreviewConfig, type Story, type StoryArgType, type StoryContext, type StoryMeta, type StoryModule, getPreviewConfig, isExportStory, setPreviewConfig, storyModuleToFragment, storyNameFromExport, toId };