@aussieljk/forkbook 0.0.0-stage → 0.0.1-2

package/dist/docs-tools/index.d.ts

@@ -0,0 +1,197 @@
+import { ArgTypes, Args, DocgenPayload, Parameters, Renderer, StoryContextForEnhancers, StoryId, StrictArgTypes } from "@aussieljk/forkbook/internal/types";
+
+//#region .dts-emit/code/core/src/docs-tools/argTypes/types.d.ts
+type Component = any;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgen/PropDef.d.ts
+interface JsDocParam {
+  name: string | undefined | null;
+  description?: string | null;
+}
+interface JsDocReturns {
+  description?: string | null;
+}
+interface JsDocTags {
+  params?: JsDocParam[] | null;
+  returns?: JsDocReturns | null;
+}
+interface PropSummaryValue {
+  summary?: string | undefined;
+  detail?: string | undefined;
+}
+type PropType = PropSummaryValue;
+type PropDefaultValue = PropSummaryValue;
+interface PropDef {
+  name: string;
+  type: PropType | null;
+  sbType?: any;
+  required: boolean;
+  description?: string;
+  defaultValue?: PropDefaultValue | null;
+  jsDocTags?: JsDocTags;
+}
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgen/types.d.ts
+type ArgTypesExtractor = (component: Component) => StrictArgTypes | null;
+interface DocgenType {
+  name: string;
+  raw?: string;
+  /** For `enum`: the source text of each literal, for example `[{ value: '"small"' }]`. */
+  value?: any;
+}
+interface DocgenPropDefaultValue {
+  value: string;
+}
+interface DocgenInfo {
+  type: DocgenType;
+  required: boolean;
+  description: string;
+  defaultValue: DocgenPropDefaultValue | null;
+}
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgen/utils/string.d.ts
+declare const str: (obj: any) => string;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgen/utils/docgenInfo.d.ts
+declare function hasDocgen<T = any>(component: Component): component is object & {
+  __docgenInfo: T;
+};
+declare function getDocgenSection(component: Component, section: string): any;
+declare function getDocgenDescription(component: Component): string;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/jsdocParser.d.ts
+interface ExtractedJsDocParam extends JsDocParam {
+  type?: any;
+  getPrettyName: () => string | undefined;
+  getTypeName: () => string | null;
+}
+interface ExtractedJsDocReturns extends JsDocReturns {
+  type?: any;
+  getTypeName: () => string | null;
+}
+interface ExtractedJsDoc {
+  params?: ExtractedJsDocParam[] | null;
+  deprecated?: string | null;
+  returns?: ExtractedJsDocReturns | null;
+  ignore: boolean;
+}
+interface JsDocParsingOptions {
+  tags?: string[];
+}
+interface JsDocParsingResult {
+  includesJsDoc: boolean;
+  ignore: boolean;
+  description?: string;
+  extractedTags?: ExtractedJsDoc;
+}
+type ParseJsDoc = (value: string | null, options?: JsDocParsingOptions) => JsDocParsingResult;
+declare const parseJsDoc: ParseJsDoc;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgen/extractDocgenProps.d.ts
+interface ExtractedProp {
+  propDef: PropDef;
+  docgenInfo: DocgenInfo;
+  jsDocTags?: ExtractedJsDoc;
+}
+/** Gets the props of `component.__docgenInfo[section]`, without the props marked `@ignore`. */
+declare function extractComponentProps(component: Component, section: string): ExtractedProp[];
+declare function extractComponentDescription(component?: Component): string;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/utils.d.ts
+declare const MAX_TYPE_SUMMARY_LENGTH = 90;
+declare const MAX_DEFAULT_VALUE_SUMMARY_LENGTH = 50;
+declare function isTooLongForTypeSummary(value: string): boolean;
+declare function isTooLongForDefaultValueSummary(value: string): boolean;
+declare function createSummaryValue(summary?: string, detail?: string): PropSummaryValue;
+declare const normalizeNewlines: (string: string) => string;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/enhanceArgTypes.d.ts
+declare const enhanceArgTypes: <TRenderer extends Renderer>(context: StoryContextForEnhancers<TRenderer>) => Parameters;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/argTypes/docgenServiceArgTypes.d.ts
+/**
+ * Builds the Controls/ArgTypes table shape from server docgen and custom argTypes.
+ *
+ * Mirrors the legacy `prepareStory` enhancer chain when `docgenServer` is enabled:
+ * server docgen stands in for `enhanceArgTypes`, user annotations from `customArgTypes` layer on
+ * top, then `inferArgTypes` and `inferControls` run the second pass that `prepareStory` skips.
+ *
+ * Callers source custom argTypes from the prepared meta/story they already hold — the docs blocks
+ * resolve it locally through `useOf` (as `StrictArgTypes`), the manager Controls panel reads it
+ * from the `STORY_PREPARED` channel via `useArgTypes` (as the looser `ArgTypes`); both are
+ * accepted here and normalized by the inference passes below.
+ */
+declare function mergeServiceArgTypes({
+  payload,
+  storyId,
+  parameters,
+  initialArgs,
+  customArgTypes
+}: {
+  /** Undefined when docgen has nothing for the component, e.g. a story file without `component`. */payload: DocgenPayload | undefined;
+  storyId: StoryId; /** May be undefined when the manager renders before the preview reports `storyPrepared`. */
+  parameters?: Parameters;
+  initialArgs?: Args;
+  customArgTypes?: ArgTypes;
+}): StrictArgTypes;
+/** Returns subcomponent argTypes that were converted by the renderer provider at write time. */
+declare function getServiceSubcomponentArgTypes(payload: DocgenPayload): Record<string, StrictArgTypes>;
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/shared.d.ts
+declare const ADDON_ID = "@aussieljk/forkbook/docs";
+declare const PANEL_ID = "@aussieljk/forkbook/docs/panel";
+declare const PARAM_KEY = "docs";
+/** DOM id of the wrapper element the `Anchor` doc block renders around each story in a docs page. */
+declare const anchorBlockIdFromId: (storyId: string) => string;
+declare const SNIPPET_RENDERED = "@aussieljk/forkbook/docs/snippet-rendered";
+declare enum SourceType {
+  /**
+   * AUTO is the default
+   *
+   * Use the CODE logic if:
+   *
+   * - The user has set a custom source snippet in `docs.source.code` story parameter
+   * - The story is not an args-based story
+   *
+   * Use the DYNAMIC rendered snippet if the story is an args story
+   */
+  AUTO = "auto",
+  /** Render the code extracted by csf-plugin */
+  CODE = "code",
+  /** Render dynamically-rendered source snippet from the story's virtual DOM (currently React only) */
+  DYNAMIC = "dynamic"
+}
+//#endregion
+//#region .dts-emit/code/core/src/docs-tools/storyDocsCodePanel.d.ts
+type StoryDocsCodePanelParameters = {
+  __isArgsStory?: boolean;
+  __isPortableStory?: boolean;
+  docs?: {
+    source?: {
+      code?: string;
+      type?: SourceType;
+    };
+  };
+};
+/**
+ * Whether the preview story-docs hook should skip emitting a snippet to the manager Code panel.
+ *
+ * The args/source shape logic mirrors {@link skipJsxRender} in the React `jsxDecorator`, so static
+ * service snippets replace dynamic JSX rendering under the same conditions. It additionally skips
+ * portable stories (vitest, playwright/jest portable): those have no manager Code panel and no OSA
+ * server peer, so the `extractStoryDocs` remote command has no handler and would reject after the
+ * ack timeout — there is nothing to emit to.
+ */
+declare function shouldSkipStoryDocsEmit(parameters?: StoryDocsCodePanelParameters): boolean;
+/**
+ * Whether the Code panel should keep rendering blank while it waits for a story-docs service snippet
+ * instead of falling back to raw CSF (`originalSource`).
+ *
+ * True while the docgen server might still emit a snippet for the current story: either the story is
+ * known to emit one, or it is not prepared yet so the emit decision — which depends on prepared
+ * parameters like `__isArgsStory` — is still unknown in the manager. Holding the fallback during
+ * that window prevents flashing raw CSF before the service snippet arrives for newly opened stories.
+ */
+declare function shouldWaitForServiceSnippet(parameters: StoryDocsCodePanelParameters | undefined, storyPrepared: boolean | undefined): boolean;
+//#endregion
+export { ADDON_ID, ArgTypesExtractor, Component, DocgenInfo, DocgenPropDefaultValue, DocgenType, ExtractedJsDoc, ExtractedJsDocParam, ExtractedJsDocReturns, ExtractedProp, JsDocParam, JsDocParsingOptions, JsDocParsingResult, JsDocReturns, JsDocTags, MAX_DEFAULT_VALUE_SUMMARY_LENGTH, MAX_TYPE_SUMMARY_LENGTH, PANEL_ID, PARAM_KEY, ParseJsDoc, PropDef, PropDefaultValue, PropSummaryValue, PropType, SNIPPET_RENDERED, SourceType, StoryDocsCodePanelParameters, anchorBlockIdFromId, createSummaryValue, enhanceArgTypes, extractComponentDescription, extractComponentProps, getDocgenDescription, getDocgenSection, getServiceSubcomponentArgTypes, hasDocgen, isTooLongForDefaultValueSummary, isTooLongForTypeSummary, mergeServiceArgTypes, normalizeNewlines, parseJsDoc, shouldSkipStoryDocsEmit, shouldWaitForServiceSnippet, str };

package/dist/docs-tools/index.js

@@ -0,0 +1,61 @@
+import {
+  ADDON_ID,
+  MAX_DEFAULT_VALUE_SUMMARY_LENGTH,
+  MAX_TYPE_SUMMARY_LENGTH,
+  PANEL_ID,
+  PARAM_KEY,
+  SNIPPET_RENDERED,
+  SourceType,
+  anchorBlockIdFromId,
+  createSummaryValue,
+  enhanceArgTypes,
+  extractComponentDescription,
+  extractComponentProps,
+  getDocgenDescription,
+  getDocgenSection,
+  hasDocgen,
+  isTooLongForDefaultValueSummary,
+  isTooLongForTypeSummary,
+  normalizeNewlines,
+  parseJsDoc,
+  shouldSkipStoryDocsEmit,
+  shouldWaitForServiceSnippet,
+  str
+} from "../_browser-chunks/chunk-66OCZ54D.js";
+import {
+  getServiceSubcomponentArgTypes,
+  mergeServiceArgTypes
+} from "../_browser-chunks/chunk-ODVJ3XZJ.js";
+import "../_browser-chunks/chunk-2JDQ35OA.js";
+import "../_browser-chunks/chunk-IE4ULIOQ.js";
+import "../_browser-chunks/chunk-B4AUNNU4.js";
+import "../_browser-chunks/chunk-NZMVUW5T.js";
+import "../_browser-chunks/chunk-JWSKPMPC.js";
+import "../_browser-chunks/chunk-JPUOQJUI.js";
+import "../_browser-chunks/chunk-IMSF75WX.js";
+export {
+  ADDON_ID,
+  MAX_DEFAULT_VALUE_SUMMARY_LENGTH,
+  MAX_TYPE_SUMMARY_LENGTH,
+  PANEL_ID,
+  PARAM_KEY,
+  SNIPPET_RENDERED,
+  SourceType,
+  anchorBlockIdFromId,
+  createSummaryValue,
+  enhanceArgTypes,
+  extractComponentDescription,
+  extractComponentProps,
+  getDocgenDescription,
+  getDocgenSection,
+  getServiceSubcomponentArgTypes,
+  hasDocgen,
+  isTooLongForDefaultValueSummary,
+  isTooLongForTypeSummary,
+  mergeServiceArgTypes,
+  normalizeNewlines,
+  parseJsDoc,
+  shouldSkipStoryDocsEmit,
+  shouldWaitForServiceSnippet,
+  str
+};

package/dist/highlight/index.d.ts

@@ -0,0 +1,10 @@
+import { n as HighlightMenuItem, r as HighlightOptions, t as ClickEventDetails } from "../chunk-DzuY9DXg.js";
+
+//#region .dts-emit/code/core/src/highlight/constants.d.ts
+declare const HIGHLIGHT = "@aussieljk/forkbook/highlight/add";
+declare const REMOVE_HIGHLIGHT = "@aussieljk/forkbook/highlight/remove";
+declare const RESET_HIGHLIGHT = "@aussieljk/forkbook/highlight/reset";
+declare const SCROLL_INTO_VIEW = "@aussieljk/forkbook/highlight/scroll-into-view";
+declare const HIGHLIGHT_MENU_CLICK = "@aussieljk/forkbook/highlight/menu-click";
+//#endregion
+export { type ClickEventDetails, HIGHLIGHT, HIGHLIGHT_MENU_CLICK, type HighlightMenuItem, type HighlightOptions, REMOVE_HIGHLIGHT, RESET_HIGHLIGHT, SCROLL_INTO_VIEW };

package/dist/highlight/index.js

@@ -0,0 +1,15 @@
+import {
+  HIGHLIGHT,
+  HIGHLIGHT_MENU_CLICK,
+  REMOVE_HIGHLIGHT,
+  RESET_HIGHLIGHT,
+  SCROLL_INTO_VIEW
+} from "../_browser-chunks/chunk-WOSOWBCA.js";
+import "../_browser-chunks/chunk-IMSF75WX.js";
+export {
+  HIGHLIGHT,
+  HIGHLIGHT_MENU_CLICK,
+  REMOVE_HIGHLIGHT,
+  RESET_HIGHLIGHT,
+  SCROLL_INTO_VIEW
+};

package/dist/instrumenter/index.d.ts

@@ -0,0 +1,113 @@
+import { t as RenderPhase } from "../chunk-Bpi2tz-6.js";
+import { Channel } from "@aussieljk/forkbook/internal/channels";
+import { StoryId } from "@aussieljk/forkbook/internal/types";
+
+//#region .dts-emit/code/core/src/instrumenter/types.d.ts
+interface Call {
+  id: string;
+  cursor: number;
+  storyId: StoryId;
+  ancestors: Call['id'][];
+  path: Array<string | CallRef>;
+  method: string;
+  args: any[];
+  interceptable: boolean;
+  retain: boolean;
+  status?: CallStates.DONE | CallStates.ERROR | CallStates.ACTIVE | CallStates.WAITING;
+  exception?: {
+    name: Error['name'];
+    message: Error['message'];
+    stack: Error['stack'];
+    callId: Call['id'];
+    showDiff?: boolean;
+    diff?: string;
+    actual?: unknown;
+    expected?: unknown;
+  };
+}
+declare enum CallStates {
+  DONE = "done",
+  ERROR = "error",
+  ACTIVE = "active",
+  WAITING = "waiting"
+}
+interface CallRef {
+  __callId__: Call['id'];
+}
+interface ElementRef {
+  __element__: {
+    prefix?: string;
+    localName: string;
+    id?: string;
+    classNames?: string[];
+    innerText?: string;
+  };
+}
+interface ControlStates {
+  detached: boolean;
+  start: boolean;
+  back: boolean;
+  goto: boolean;
+  next: boolean;
+  end: boolean;
+}
+interface LogItem {
+  callId: Call['id'];
+  status: Call['status'];
+  ancestors: Call['id'][];
+}
+interface SyncPayload {
+  /** Absent when the whole log is reset, and in payloads from composed Storybooks that predate it. */
+  storyId?: StoryId;
+  controlStates: ControlStates;
+  logItems: LogItem[];
+  pausedAt?: Call['id'];
+}
+interface State {
+  renderPhase: RenderPhase;
+  isDebugging: boolean;
+  isPlaying: boolean;
+  isLocked: boolean;
+  cursor: number;
+  calls: Call[];
+  shadowCalls: Call[];
+  callRefsByResult: Map<any, CallRef & {
+    retain: boolean;
+  }>;
+  chainedCallIds: Set<Call['id']>;
+  ancestors: Call['id'][];
+  playUntil?: Call['id'];
+  resolvers: Record<Call['id'], Function>;
+  syncTimeout?: ReturnType<typeof setTimeout>;
+  forwardedException?: Error;
+}
+interface Options {
+  intercept?: boolean | ((method: string, path: Array<string | CallRef>) => boolean);
+  retain?: boolean;
+  mutate?: boolean;
+  path?: Array<string | CallRef>;
+  getArgs?: (call: Call, state: State) => Call['args'];
+  getKeys?: (originalObject: Record<string, unknown>, depth: number) => string[];
+}
+//#endregion
+//#region .dts-emit/code/core/src/instrumenter/instrumenter.d.ts
+/**
+ * Instruments an object or module by traversing its properties, patching any functions (methods) to
+ * enable debugging. Patched functions will emit a `call` event when invoked. When intercept = true,
+ * patched functions will return a Promise when the debugger stops before this function. As such,
+ * "interceptable" functions will have to be `await`-ed.
+ */
+declare function instrument<TObj extends Record<string, any>>(obj: TObj, options?: Options): TObj;
+//#endregion
+//#region .dts-emit/code/core/src/instrumenter/EVENTS.d.ts
+declare const EVENTS: {
+  CALL: string;
+  SYNC: string;
+  START: string;
+  BACK: string;
+  GOTO: string;
+  NEXT: string;
+  END: string;
+};
+//#endregion
+export { Call, CallRef, CallStates, ControlStates, EVENTS, ElementRef, LogItem, Options, type RenderPhase, State, SyncPayload, instrument };