Structured Text Format

Copyexport function serialize(value: unknown): string {
  return stringify(value);
}
 
export function deserialize(value: string): unknown {
  return parse(value);
}

Copyfunction isSerializedPageTree(v: unknown): v is SerializedPageTree {
  return (
    typeof v === 'object' &&
    v !== null &&
    '$fumadocs_loader' in v &&
    v.$fumadocs_loader === 'page-tree'
  );
}

Copyexport function deserializePageTree(serialized: SerializedPageTree): PageTree.Root {
  const root = serialized.data as PageTree.Root;
  visit(root, (item) => {
    if ('icon' in item && typeof item.icon === 'string') {
      item.icon = (
        <span
          dangerouslySetInnerHTML={{
            __html: item.icon,
          }}
        />
      );
    }
    if (typeof item.name === 'string') {
      item.name = (
        <span
          className="fd-page-tree-item-name"
          dangerouslySetInnerHTML={{
            __html: item.name,
          }}
        />
      );
    }
  });
 
  return root;
}

Copyexport function useFumadocsLoader<V>(serialized: V): Serialized<V> {
  return useMemo(() => {
    const out: Record<string, unknown> = {};
    for (const k in serialized) {
      const v = serialized[k];
      if (isSerializedPageTree(v)) {
        out[k] = deserializePageTree(v);
      } else {
        out[k] = v;
      }
    }
    return out as Serialized<V>;
  }, [serialized]);
}

Copyexport async function renderPlaceholder(
  text: string,
  renderers: Record<string, (data: PlaceholderData) => Awaitable<string>>,
): Promise<string> {
  let out = '';
  let idx = 0;
 
  for (const match of text.matchAll(regex)) {
    out += text.slice(idx, match.index);
    const inner = match[1];
    try {
      const data = JSON.parse(inner) as PlaceholderData;
      const renderer = data.name && renderers[data.name];
      if (data.children.trim()) {
        data.children = await renderPlaceholder(data.children, renderers);
      }
 
      if (renderer) {
        out += await renderer(data);
      } else {
        out += data.children;
      }
    } catch {
      out += match[0];
    }
 
    idx = match.index + match[0].length;
  }
  out += text.slice(idx);
 
  return out;

Copyexport function remarkDocGen({ generators = [] }: RemarkDocGenOptions): Transformer<Root, Root> {
  return async (tree, file) => {
    generators.forEach((gen) => gen.onFile?.(tree, file));
    const queue: Promise<void>[] = [];
 
    visit(tree, 'code', (code, _, parent) => {
      if (code.lang !== 'json' || !code.meta || !parent) return;
 
      const matches = metaRegex.exec(code.meta);
      if (!matches) return;
 
      const name = matches[1];
      const gen = generators.find((g) => g.name === name);
 
      const run = async (): Promise<void> => {
        const result = await gen?.run(JSON.parse(code.value), {
          cwd: file.cwd,
          path: file.path,
          node: code,
        });
        const index = parent.children.findIndex((c) => c === code);
 
        if (result && index !== -1) {
          const items = Array.isArray(result)
            ? (result as BlockContent[])
            : [result as BlockContent];
 
          parent.children.splice(index, 1, ...items);
        }
      };
 
      queue.push(run());
    });
 
    await Promise.all(queue);
  };

Copyconst Context = createContext<Stf | null>(null);
 
export interface Stf {
  dataEngine: DataEngine;
}
 
export function StfProvider({ value, children }: { value: Stf; children: ReactNode }) {
  return <Context value={value}>{children}</Context>;
}
 
export function useStf(options: {
  /**
   * Note: the passed object will be modified in place, use `structuredClone()` to keep the original object unchanged.
   */
  defaultValues?: DefaultValue<Record<string, unknown>>;
}): Stf {
  const optionsRef = useRef(options);
  optionsRef.current = options;
 
  return useMemo(
    () => ({
      dataEngine: new DataEngine(optionsRef.current.defaultValues),
    }),
    [],
  );
}
 
export function useDataEngine(instance?: Stf | DataEngine) {
  if (instance instanceof DataEngine) return instance;
  if (instance) return instance.dataEngine;
  return use(Context)!.dataEngine;
}

Copyexport function useDataEngine(instance?: Stf | DataEngine) {
  if (instance instanceof DataEngine) return instance;
  if (instance) return instance.dataEngine;
  return use(Context)!.dataEngine;
}

Copyexport function useFieldValue<V = unknown>(
  key: FieldKey,
  options: {
    stf?: Stf | DataEngine;
    defaultValue?: DefaultValue;
 
    /**
     * compute value from the actual field value.
     *
     * to re-compute on in-place updates (may happen on objects, arrays), you should clone the object here.
     */
    compute?: (currentValue: unknown) => V;
    /** determine whether the value/computed value is changed */
    isChanged?: (prev: V, next: V) => boolean;
  } = {},
) {
  const { stf, compute = (v) => v as V, defaultValue, isChanged = (a, b) => a !== b } = options;
  const engine = useDataEngine(stf);
  const [value, setValue] = useState<V>(() =>
    compute(defaultValue === undefined ? engine.get(key) : engine.init(key, defaultValue)),
  );
  const prevEngineRef = useRef(engine);
 
  if (prevEngineRef.current !== engine) {
    setValue(
      compute(defaultValue === undefined ? engine.get(key) : engine.init(key, defaultValue)),
    );
    prevEngineRef.current = engine;
  }
 
  function onUpdate() {
    const computed = compute(engine.get(key));
    setValue((prev) => (isChanged(prev, computed) ? computed : prev));
  }
 
  useListener({
    field: key,
    stf,
    onInit: onUpdate,
    onUpdate: onUpdate,
    onDelete() {
      const computed = compute(undefined);
      setValue((prev) => (isChanged(prev, computed) ? computed : prev));
    },
  });
 
  return [value, (newValue: unknown) => engine.update(key, newValue)] as const;
}

Copyexport function useArray(
  field: FieldKey,
  options: { defaultValue?: DefaultValue<unknown[]> } = {},
) {
  const engine = useDataEngine();
  const { defaultValue } = options;
  const [items] = useFieldValue(field, {
    defaultValue,
    compute(value) {
      const items: ArrayItemInfo[] = [];
      if (!Array.isArray(value)) return items;
 
      for (let i = 0; i < value.length; i++) {
        items.push({
          field: [...field, i],
          index: i,
        });
      }
      return items;
    },
    isChanged(prev, next) {
      return prev.length !== next.length;
    },
  });
 
  return {
    items,
    insertItem(itemValue?: unknown) {
      const value = engine.get(field);
      const idx = Array.isArray(value) ? value.length : 0;
      engine.init([...field, idx], itemValue);
    },
    removeItem(index: number) {
      engine.delete([...field, index]);
    },
  };
}

Copyexport function useObject<T>(
  field: FieldKey,
  options: {
    defaultValue?: DefaultValue<object>;
    /** ignore fixed properties unless defined  */
    lazy?: boolean;
    properties: Record<string, T>;
    patternProperties?: Record<string, T>;
    fallback?: T;
  },
) {
  const {
    properties: definedProps,
    patternProperties: definedPatternProps = {},
    defaultValue,
    fallback,
    lazy,
  } = options;
  const engine = useDataEngine();
  const [objectKeys] = useFieldValue(field, {
    defaultValue,
    compute(currentValue) {
      return isPlainObject(currentValue) ? Object.keys(currentValue) : [];
    },
    isChanged(prev, next) {
      return !deepEqual(prev, next);
    },
  });
 
  const properties = useMemo(() => {
    const properties: PropertyItemInfo<T>[] = [];
    const unknownKeys = new Set(objectKeys);
    for (const [key, prop] of Object.entries(definedProps)) {
      if (lazy && !unknownKeys.has(key)) continue;
      unknownKeys.delete(key);
 
      properties.push({
        kind: 'fixed',
        field: [...field, key],
        key,
        info: prop,
      });
    }
 
    for (const [pattern, prop] of Object.entries(definedPatternProps)) {
      const regex = RegExp(pattern);
 
      for (const key of unknownKeys) {
        if (!key.match(regex)) continue;
        unknownKeys.delete(key);
        properties.push({
          kind: 'pattern',
          info: prop,
          key,
          pattern,
          field: [...field, key],
        });
      }
    }
 
    if (fallback) {
      for (const key of unknownKeys) {
        properties.push({
          kind: 'fallback',
          field: [...field, key],
          key,
          info: fallback,
        });
      }
    }
 
    return properties;
  }, [definedPatternProps, definedProps, fallback, field, lazy, objectKeys]);
 
  return {
    properties,
    _objectKeys: objectKeys,
    onAppend(name: string, value?: unknown) {
      name = name.trim();
      if (name.length === 0) return;

Copyconst processor = remark()
  .use(remarkPlugins)
  .use(remarkRehype, remarkRehypeOptions)
  .use(rehypePlugins);

Copy  return (cachedInstance ??= createTwoslasher({
    ...twoslashOptions,
    compilerOptions: {
      moduleResolution: 100 satisfies ModuleResolutionKind.Bundler,
      baseUrl: undefined,
      ...twoslashOptions.compilerOptions,
    },
  }));
}