orphic-cypress/dist/storybook/story-code.d.ts

Set of utilities and typescript transformers to cover storybook stories with cypress component tests

import type { LocationsMap } from "@storybook/source-loader";
import type { StoryContext } from "@storybook/types";
/**
 * Remove lines with @skip, after @skip-next or between @skip-start and
 * @skip-end, all starting with `// story-code `
 *
 * @private
 */
export declare const removeSkips: (codeLines: string[]) => string[];
/**
 * Story context augmented by storysource addon
 */
export type StoryContextStorySource = StoryContext & {
    /** parameters extension */
    parameters: {
        /** what's added by storysource */
        storySource: {
            /** full file as a single string */
            source: string;
            /** start/end locations of stories in above source */
            locationsMap: LocationsMap;
        };
    };
};
/** Options available for story-code's `transformSource` */
export type TransformSourceOptions = {
    /**
     * storysource doesn't handle ComponentStoryObj syntax well, failing to provide a
     * location. Passing in `true` here will mean the code block in the story docs
     * will attempt to include the object itself, overcomming that issue.
     */
    includeObjects?: boolean;
};
/**
 * Add comment directives that will enable transforming the story source code
 * into the code snippet for the story.
 *
 * Relies on storysource addon
 *
 * Notable issues:
 * * if a story is all object syntax, then it won't have
 *   a storySource at all. That's likely a limitation of source-loader.
 * * If a story name is very long, story-loader's handling can get weird
 *
 * TODO: some notable naive approaches here. Could parse AST to get
 * the default export, to automatically include assignments to stories, or
 * to better parse story objects.
 *
 * TODO: Some of this might be suitable contribution to storysource, but
 * the goals there often different, e.g. to show how to use a component
 * whereas here we're showing how to build stories.
 *
 * TODO: ideas include-render, include-template, include-region
 *
 * All comments start with `// story-code` or with `/*` or `/**` style
 * single line comments. So `// story-code @end SomeComponent @include-default`
 * for example.
 *
 * ## Available commands:
 * * `@end`: end the previous story's code block. Note, this is works across
 *   stories such that any story which does not specify its end which begins
 *   before this use will end at this point. Use named end's if you need specificity
 *   ```ts
 *   const SomeStory: ComponentStory<typeof Comp> = (args) => <Comp {...args} />;
 *   SomeStory.args = { prop: 1 };
 *   // story-code @end
 *   ```
 * * `@end SomeComponent`: same as above, but only mark the end for the given component
 *   ```ts
 *   const SomeStory: ComponentStory<typeof Comp> = (args) => <Comp {...args} />;
 *   const OtherStory: ComponentStory<typeof Comp> = (args) => <Comp {...args} />;
 *   OtherStory.args = { prop: 1 };
 *   // story-code @end OtherStory
 *   ```
 * * `@include-default`: include the default code export. Can occur in an `@end` line
 *   or on the line following a natural or designated end.
 *   ```ts
 *   const SomeStory: ComponentStory<typeof Comp> = (args) => <Comp {...args} />;
 *   SomeStory.args = { prop: 1 };
 *   // story-code @end @include-default
 *   ```
 * * `@include-start`: include from the top of the file through to the default code export.
 *   Can occur in an `@end` line or on the line following a natural or designated end.
 *   ```ts
 *   const SomeStory: ComponentStory<typeof Comp> = (args) => <Comp {...args} />;
 *   // story-code @include-start
 *   ```
 * * `@skip`: Skip the current line
 *   ```ts
 *   const somethingToIgnore = 1; // story-code @skip
 *   ```
 * * `@skip-next`: Skip the next line
 *   ```ts
 *   // story-code @skip-next
 *   const somethingToIgnore = 1;
 *   ```
 * * `@skip-start` and `@skip-end`: Skip a block of text, e.g.
 *   ```ts
 *   // story-code @skip-start
 *   const hideThis = 1;
 *   const andThis = 2;
 *   // story-code @skip-end
 *   ```
 *   There's nothing enforcing that you have to have a @skip-end if you have a @skip-start
 */
export declare const transformSource: (opts?: TransformSourceOptions) => (snippet: string, storyContext: StoryContextStorySource) => string;