Interactive Component Playground

Copyexport interface StoryOptions<C extends FC<any>> {
  /**
   * the export name of story, necessary for TypeScript Compiler.
   *
   * @defaultValue `story`
   */
  name?: string;
  displayName?: string;
  Component: C;
 
  /**
   * story arguments, you can pass an array of options for multiple presets.
   */
  args?: ArgsOptions<C> | (ArgsOptions<C> & VariantInfo)[];
}
 
export interface ArgsOptions<C extends FC<any> = FC<any>> {
  /**
   * the default values of arguments.
   */
  initial?: ComponentPropsWithoutRef<C> | (() => Awaitable<ComponentPropsWithoutRef<C>>);
  /**
   * fixed values for arguments, will disable the relevant controls.
   */
  fixed?:
    | Partial<ComponentPropsWithoutRef<C>>
    | (() => Awaitable<Partial<ComponentPropsWithoutRef<C>>>);
  /**
   * customize the generated controls, by default generated from component props using TypeScript compiler.
   */
  controls?:
    | {
        node: TypeNode;
      }
    | {
        /** modify generated node */
        transform?: (node: TypeNode) => TypeNode;
      };
}
 
export { type Cache } from './cache';
export { createFileSystemCache } from './cache/fs';
 
export interface Story<C extends FC<any> = FC<any>> {
  /** render as a server component (require RSC). */
  WithControl: FC;
  _private_: {
    component?: C;
  };
}
 
export interface StoryFactoryOptions {
  cache?: Cache | false;
 
  tsc?: {
    /** default to `tsconfig.json` under cwd */
    tsconfigPath?: string;
  };
}
 
export interface StoryFactory {
  defineStory: <C extends FC<any>>(urlOrPath: URL | string, options: StoryOptions<C>) => Story<C>;
}

Copyexport function defineStoryFactory(factoryOptions: StoryFactoryOptions = {}): StoryFactory {
  let _project: ReturnType<typeof createControlsProject> | undefined;
  const { cache = false } = factoryOptions;
  const propsDeepmerge = deepmerge({
    mergeArray: () => (_target, source) => source,
  });
 
  function initProject() {
    const { tsconfigPath = './tsconfig.json' } = factoryOptions.tsc ?? {};
    return (_project ??= createControlsProject(tsconfigPath));
  }
 
  async function generateControlsCached(filePath: string, name: string): Promise<TypeNode> {
    const fileContent = await fs.readFile(filePath, 'utf-8');
 
    return cached(cache, getHash(`controls:${filePath}:${name}:${fileContent}`), async () => {
      const project = await initProject();
      return generateControls('@fumadocs/story/next/client', project, filePath, name, fileContent);
    });
  }
 
  return {
    defineStory(urlOrPath, { Component, name = 'story', displayName, args = {} }) {
      const filePath =
        urlOrPath instanceof URL || urlOrPath.startsWith('file:///')
          ? fileURLToPath(urlOrPath)
          : urlOrPath;
 
      async function getProps(): Promise<WithControlProps> {
        const normalized = Array.isArray(args) ? args : [{ ...args, variant: 'default' }];
 
        return {
          Component,
          displayName,
          presets: await Promise.all(
            normalized.map(async (preset): Promise<WithControlProps['presets'][number]> => {
              const fixedValues =
                typeof preset.fixed === 'function' ? await preset.fixed() : preset.fixed;
              const initial =
                typeof preset.initial === 'function' ? await preset.initial() : preset.initial;
              let controls: TypeNode;
 
              if (preset.controls && 'node' in preset.controls) {
                controls = preset.controls.node;
              } else {
                controls = await generateControlsCached(filePath, name);
 
                if (preset.controls?.transform) controls = preset.controls.transform(controls);
                if (fixedValues) controls = collapse(controls, fixedValues);
              }
 
              return {
                variant: preset.variant,
                description: preset.description,
                controls,
                defaultValues: (fixedValues
                  ? propsDeepmerge(initial, fixedValues)
                  : initial) as Record<string, unknown>,
              };
            }),
          ),
        };
      }
 
      return {
        _private_: {
          component: Component,
        },
        async WithControl() {
          const { WithControl } = await import('./client/with-control');
          return <WithControl {...await getProps()} />;
        },
      };
    },
  };
}

Copyexport async function createControlsProject(tsconfigPath: string): Promise<Project> {
  const { Project } = await import('ts-morph');
 
  return new Project({
    tsConfigFilePath: tsconfigPath,
    skipAddingFilesFromTsConfig: true,
  });
}

Copyexport function generateControls(
  mode: Mode,
  project: Project,
  filePath: string,
  exportName: string,
  content: string,
): TypeNode {
  const aliasName = `_StoryProps_${exportName}_`;
  const sourceFile =
    project.getSourceFile(filePath) ??
    project.createSourceFile(filePath, content, {
      overwrite: true,
    });
 
  if (!sourceFile.getTypeAlias(aliasName)) {
    sourceFile.addTypeAlias({
      isExported: true,
      name: aliasName,
      type: `import('${mode}').GetProps<typeof ${exportName}>`,
    });
  }
 
  const declarations = sourceFile.getExportedDeclarations();
  const declaration = declarations.get(aliasName)?.[0];
  if (!declaration || !declarations.get(exportName)) {
    throw new Error(`Export "${exportName}" not found in file "${filePath}"`);
  }
 
  return createTypeTreeBuilder(project, [literalEnumHandler]).typeToNode(
    declaration.getType(),
    declaration,
  );

Copyif (fixedValues) controls = collapse(controls, fixedValues);

Copyasync function generateControlsCached(filePath: string, name: string): Promise<TypeNode> {
  const fileContent = await fs.readFile(filePath, 'utf-8');
 
  return cached(cache, getHash(`controls:${filePath}:${name}:${fileContent}`), async () => {
    const project = await initProject();
    return generateControls('@fumadocs/story/next/client', project, filePath, name, fileContent);
  });
}

Copyexport interface StoryPluginOptions {
  /**
   * Path to `tsconfig.json`.
   *
   * @default "tsconfig.json"
   */
  tsconfigPath?: string;
 
  /**
   * Filter story files to transform by id (regex)
   *
   * @default `/\.story\.(js|jsx|ts|tsx)$/`
   */
  filter?: RegExp;
}

Copyreturn {
  name: 'fumadocs:story',
  enforce: 'pre',
  configResolved(resolved) {
    tsconfigPath = pluginOptions.tsconfigPath ?? path.join(resolved.root, 'tsconfig.json');
  },

Copyexport interface StoryLoaderOptions {
  /**
   * Path to `tsconfig.json`.
   *
   * @default "tsconfig.json"
   */
  tsconfigPath?: string;
}
 
let projectPromise: Promise<Project> | undefined;
 
const loader: LoaderDefinitionFunction<StoryLoaderOptions> = function (source) {
  const callback = this.async();
  const options = this.getOptions();
  this.cacheable(true);
 

Copyconst run = async () => {
  if (!projectPromise) {
    const resolvedTsconfig = options.tsconfigPath ?? path.join(this.rootContext, 'tsconfig.json');
    projectPromise = createControlsProject(resolvedTsconfig);
  }
 
  try {
    const transformed = transformStoryFile(
      '@fumadocs/story/next/client',
      source,
      this.resourcePath,
      await projectPromise!,
    );

Copyexport function transformStoryFile(
  mode: Mode,
  code: string,
  id: string,
  project: Project,
): string | undefined {
  const sourceFile = project.createSourceFile(id, code, { overwrite: true });
  const calls = findDefineStoryCalls(sourceFile);
  if (calls.length === 0) return;

Copy 
for (const parsed of calls) {
  const args = parsed.call.getArguments();
  // invalid structure
  if (args.length !== 1) continue;
 
  const controls = generateControls(mode, project, id, parsed.exportName, code);
  injectControls(parsed, controls);
}
 
return sourceFile.getFullText();

Copyexport function defineStoryFactory(): StoryFactory {
  const propsDeepmerge = deepmerge({
    mergeArray: () => (_target, source) => source,
  });
 

Copyfunction getProps(): WithControlProps {
  const normalized = Array.isArray(args) ? args : [{ ...args, variant: 'default' }];
 
  return {
    Component,
    displayName,
    presets: normalized.map((preset) => {
      const fixedValues = typeof preset.fixed === 'function' ? preset.fixed() : preset.fixed;
      const initial =
        typeof preset.initial === 'function' ? preset.initial() : preset.initial;
      let controls: TypeNode;
 
      if (preset.controls && 'node' in preset.controls) {
        controls = preset.controls.node;
      } else if (_generated) {
        generatedControls ??= deserialize(_generated.controls) as TypeNode;
        controls = generatedControls;
      } else {
        throw new Error(
          `[@fumadocs/story] No generated data for story, make sure the Vite plugin or Turbopack loader is configured correctly`,
        );
      }
 
      return {
        variant: preset.variant,
        description: preset.description,
        controls,
        defaultValues: (fixedValues
          ? propsDeepmerge(initial, fixedValues)
          : initial) as Record<string, unknown>,
      };
    }),
  };
}

Copyexport function WithControl({ presets, displayName, Component }: WithControlProps) {
  const t = useTranslations({ note: 'story controls' });
  const [variant, setVariant] = useState(presets[0].variant);
  const preset = presets.find((preset) => preset.variant === variant);
  const stf = useStf({
    defaultValues: preset?.defaultValues,
  });
 
  return (
    <StfProvider value={stf}>

Copy{presets.length > 1 && (
  <Select
    value={variant}
    onValueChange={(value) => {
      const preset = presets.find((preset) => preset.variant === value);
      if (preset) {
        setVariant(value);
        stf.dataEngine.reset(preset.defaultValues ?? {});
      }
    }}
  >
    <SelectTrigger
      variant="ghost"
      className="w-fit ms-auto text-fd-muted-foreground text-xs font-medium"
    >
      <SelectValue placeholder={t('No Variant')}>{preset?.variant}</SelectValue>
    </SelectTrigger>
    <SelectContent>
      {presets.map((item) => (
        <SelectItem key={item.variant} value={item.variant}>
          <p className="text-xs font-medium">{item.variant}</p>
          <p className="text-xs text-fd-muted-foreground">{item.description}</p>
        </SelectItem>
      ))}
    </SelectContent>
  </Select>
)}

Copy{preset && (
  <FieldSet
    field={preset.controls}
    fieldName={[]}
    name={t('Props')}
    className="max-h-[600px] overflow-auto"
  />
)}

Copyfunction StoryComponent({ Component }: { Component: FC }) {
  const t = useTranslations({ note: 'story error boundary' });
  const engine = useDataEngine();
  const timerRef = useRef(0);
  const [args, setArgs] = useState(() => engine.getData());
  const deferredArgs = useDeferredValue(args);
  useListener({
    onUpdate() {
      if (timerRef.current) window.clearTimeout(timerRef.current);
      timerRef.current = window.setTimeout(() => setArgs({ ...engine.getData() }), 100);
    },
  });

Copyreturn (
  <ErrorBoundary
    fallbackRender={({ error, resetErrorBoundary }) => (
      <div className="p-3 border rounded-lg bg-fd-card text-fd-card-foreground text-sm">
        <p className="inline-flex items-center gap-2 font-medium mb-2">
          <AlertCircle className="text-fd-error size-4" />
          {t('Encountered error when rendering the component.')}
        </p>
        <p className="text-fd-muted-foreground mb-2">{String(error)}</p>
        <button
          className={cn(buttonVariants({ variant: 'primary', size: 'sm' }))}
          onClick={() => resetErrorBoundary()}
        >
          {t('Reset')}
        </button>
      </div>
    )}
  >
    <Suspense>
      <Component {...deferredArgs} key={undefined} />
    </Suspense>
  </ErrorBoundary>
);

Copyexport function ObjectInput({
  field: node,
  fieldName,
  ...props
}: {
  field: ObjectNode;
  fieldName: FieldKey;
} & ComponentProps<'div'>) {
  const { properties } = useObject(fieldName, {
    defaultValue: () => getDefaultValue(node) as object,
    properties: Object.fromEntries(node.properties.map((prop) => [prop.name, prop.type])),
  });
 
  return (
    <div {...props} className={cn('grid grid-cols-1 gap-4 @md:grid-cols-2', props.className)}>
      {properties.map((child) => {
        const prop = node.properties.find((p) => p.name === child.key);
        if (!prop) return null;
 
        return (
          <FieldSet
            key={child.key}
            name={child.key}
            field={prop.type}
            fieldName={child.field}
            isRequired={prop.required}
          />
        );
      })}
    </div>
  );
}

Copyexport function FieldInput({
  field,
  fieldName,
  isRequired,
  ...props
}: HTMLAttributes<HTMLElement> & {
  field: TypeNode;
  isRequired?: boolean;
  fieldName: FieldKey;
}) {
  const engine = useDataEngine();
  const t = useTranslations({ note: 'story arguments form' });
  const [value, setValue] = useFieldValue(fieldName);
  const id = stringifyFieldKey(fieldName);
 
  function renderUnset(children: ReactNode) {
    return (
      <div {...props} className={cn('flex flex-row gap-2', props.className)}>
        {children}
        {value !== undefined && !isRequired && (
          <button
            type="button"
            onClick={() => engine.delete(fieldName)}
            className="text-fd-muted-foreground"
          >
            <X className="size-4" />
          </button>
        )}
      </div>
    );
  }
 
  if (
    field.type === 'null' ||
    field.type === 'undefined' ||
    field.type === 'never' ||
    field.type === 'unknown' ||
    field.type === 'literal'
  ) {
    return null;
  }
 
  if (field.type === 'enum') {
    const idx = field.members.findIndex((m) => m.value === value);
 
    return (
      <Select
        value={idx >= 0 ? String(idx) : '-1'}
        onValueChange={(v: string) => {
          const index = Number(v);
          if (index >= 0 && index < field.members.length) {
            setValue(field.members[index]!.value);
          } else {
            setValue(undefined);
          }
        }}
      >
        <SelectTrigger id={id} {...props}>
          <SelectValue />
        </SelectTrigger>
        <SelectContent>
          {field.members.map((member, i) => (
            <SelectItem key={i} value={String(i)}>
              {member.label}
            </SelectItem>
          ))}
          {!isRequired && (
            <SelectItem value="-1">
              <span className="text-fd-muted-foreground">{t('Unset')}</span>
            </SelectItem>
          )}
        </SelectContent>
      </Select>
    );
  }

Copyif (field.type === 'boolean') {
  return (
    <Select
      value={String(value)}
      onValueChange={(val: string) => setValue(val === 'undefined' ? undefined : val === 'true')}
    >
      <SelectTrigger id={id} {...props}>
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="true">{t('True')}</SelectItem>
        <SelectItem value="false">{t('False')}</SelectItem>
        {!isRequired && (
          <SelectItem value="undefined">
            <span className="text-fd-muted-foreground">{t('Unset')}</span>
          </SelectItem>
        )}
      </SelectContent>
    </Select>
  );
}
if (field.type === 'date') {
  return renderUnset(
    <Input
      id={id}
      placeholder={t('Enter date')}
      type="date"

Copyexport function JsonInput({ fieldName }: { fieldName: FieldKey }) {
  const engine = useDataEngine();
  const [error, setError] = useState<string | null>(null);
  const [value, setValue] = useState(() => JSON.stringify(engine.init(fieldName, {}), null, 2));
 

Copy  <div className="flex flex-col bg-fd-secondary text-fd-secondary-foreground overflow-hidden border rounded-lg">
    <textarea
      value={value}
      className="p-2 h-[240px] text-sm font-mono resize-none focus-visible:outline-none"
      onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => {
        setValue(e.target.value);
        try {
          engine.update(fieldName, JSON.parse(e.target.value));
          setError(null);
        } catch (err) {
          if (err instanceof Error) setError(err.message);
        }
      }}
    />
    <p className="p-2 text-xs font-mono border-t text-red-400 empty:hidden">{error}</p>
  </div>
);