@haruhimemoe/ui 0.8.0 → 0.9.0

package/dist/components/mdx/MdxPre.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @file src/components/mdx/MdxPre.tsx
+ * @desc react-markdown/MDX's `pre` override: a fenced code block (a `<pre>` wrapping a single
+ *       child with a `language-*` class, a `data-meta` prop, or the literal `code` element type)
+ *       is handed to CodeBlock with its parsed meta; detecting the fence by the child's props
+ *       rather than only `child.type === "code"` means an app that overrides the `code` component
+ *       (through `mdxComponents`' own map or MDX's `useMDXComponents`) still gets highlighting.
+ *       Anything else renders as a plain, focusable `<pre>`. Drops the `node` prop react-markdown
+ *       passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { Children, isValidElement } from "react";
+import { CodeBlock } from "./CodeBlock.js";
+import { parseCodeMeta } from "./parseCodeMeta.js";
+import { textOf } from "./textOf.js";
+/**
+ * @function MdxPre
+ * @param props {MdxPreProps} native pre props; a single `code` child carries the language class
+ *        and the fence's meta string in `data-meta`
+ * @returns {JSX.Element} a CodeBlock for a fenced `code` child, otherwise a plain, focusable pre
+ */
+export function MdxPre({ node: _node, children, ...props }) {
+    const [child] = Children.toArray(children);
+    const isFence = isValidElement(child) &&
+        (child.type === "code" ||
+            /(?:^|\s)language-/.test(child.props.className ?? "") ||
+            child.props["data-meta"] !== undefined);
+    if (!isFence || !isValidElement(child)) {
+        return (_jsx("pre", { 
+            // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+            tabIndex: 0, ...props, children: children }));
+    }
+    const lang = /(?:^|\s)language-(\S+)/.exec(child.props.className ?? "")?.[1];
+    const { title, highlight } = parseCodeMeta(child.props["data-meta"]);
+    return (_jsx(CodeBlock, { code: textOf(child.props.children), lang: lang, title: title, highlight: highlight }));
+}

package/dist/components/mdx/MdxTable.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/components/mdx/MdxTable.tsx
+ * @desc react-markdown/MDX's `table` override: wraps the table in a named, focusable scroll
+ *       region (a table can overflow its column on narrow screens), named by its caption when
+ *       one is given. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ComponentProps } from "react";
+/** Every native `<table>` prop, plus the `node` react-markdown passes (dropped). */
+export type MdxTableProps = ComponentProps<"table"> & {
+    node?: unknown;
+};
+/**
+ * @function MdxTable
+ * @param props {MdxTableProps} native table props; a `caption` child names the scroll region
+ * @returns {JSX.Element} a horizontally scrollable, focusable, labelled region wrapping the table
+ */
+export declare function MdxTable({ node: _node, children, ...props }: MdxTableProps): import("react").JSX.Element;

package/dist/components/mdx/MdxTable.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @file src/components/mdx/MdxTable.tsx
+ * @desc react-markdown/MDX's `table` override: wraps the table in a named, focusable scroll
+ *       region (a table can overflow its column on narrow screens), named by its caption when
+ *       one is given. Drops the `node` prop react-markdown passes to every component.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { Children, isValidElement } from "react";
+import { textOf } from "./textOf.js";
+/**
+ * @function MdxTable
+ * @param props {MdxTableProps} native table props; a `caption` child names the scroll region
+ * @returns {JSX.Element} a horizontally scrollable, focusable, labelled region wrapping the table
+ */
+export function MdxTable({ node: _node, children, ...props }) {
+    const caption = Children.toArray(children).find((child) => isValidElement(child) && child.type === "caption");
+    return (_jsx("div", { role: "group", "aria-label": textOf(caption) || "Table", 
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region needs keyboard focus
+        tabIndex: 0, className: "overflow-x-auto", children: _jsx("table", { ...props, children: children }) }));
+}

package/dist/components/mdx/highlighter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file src/components/mdx/highlighter.ts
+ * @desc The highlighter CodeBlock asks for. Nothing here names Shiki outside `import type`, so
+ *       an app without Shiki builds: `@haruhimemoe/ui/shiki` (src/shiki.ts) registers the real
+ *       loader when an app imports it. The loader lives in a `globalThis` slot keyed by
+ *       `Symbol.for`, so it survives duplicate copies of this module. The first highlighter is
+ *       cached; with no loader registered, or a loader that rejects, code renders plain (warned
+ *       once, outside production) rather than throwing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { HighlighterCore } from "shiki/core";
+/** The Shiki CSS-variables theme name CodeBlock renders with. */
+export declare const THEME = "haruhime";
+/** Loads a Shiki highlighter: what `@haruhimemoe/ui/shiki` registers. */
+export type HighlighterLoader = () => Promise<HighlighterCore>;
+/**
+ * @function setHighlighterLoader
+ * @param loader {HighlighterLoader} loads the Shiki highlighter; replaces any earlier one
+ * @returns {void} registers the loader in the global slot and drops the cached highlighter
+ */
+export declare const setHighlighterLoader: (loader: HighlighterLoader) => void;
+/**
+ * @function getHighlighter
+ * @param loader {HighlighterLoader | undefined} loads the highlighter; defaults to the registered
+ *        one, overridable in tests
+ * @returns {Promise<HighlighterCore | null>} the cached highlighter, or null when no loader is
+ *          registered or it failed to load
+ */
+export declare const getHighlighter: (loader?: HighlighterLoader | undefined) => Promise<HighlighterCore | null>;
+/**
+ * @function resetHighlighter
+ * @returns {void} clears the registered loader, the cached highlighter and the warned flag
+ *          (tests only)
+ */
+export declare const resetHighlighter: () => void;

package/dist/components/mdx/highlighter.js

@@ -0,0 +1,66 @@
+/**
+ * @file src/components/mdx/highlighter.ts
+ * @desc The highlighter CodeBlock asks for. Nothing here names Shiki outside `import type`, so
+ *       an app without Shiki builds: `@haruhimemoe/ui/shiki` (src/shiki.ts) registers the real
+ *       loader when an app imports it. The loader lives in a `globalThis` slot keyed by
+ *       `Symbol.for`, so it survives duplicate copies of this module. The first highlighter is
+ *       cached; with no loader registered, or a loader that rejects, code renders plain (warned
+ *       once, outside production) rather than throwing.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** The Shiki CSS-variables theme name CodeBlock renders with. */
+export const THEME = "haruhime";
+const SLOT = Symbol.for("@haruhimemoe/ui/highlighter");
+// No node types in the build (tsconfig.build.json "types": []), so read process through globalThis.
+const isProduction = () => globalThis.process?.env
+    ?.NODE_ENV === "production";
+let cached;
+let warned = false;
+const warnOnce = (message, error) => {
+    if (warned || isProduction())
+        return;
+    warned = true;
+    if (error === undefined)
+        console.warn(message);
+    else
+        console.warn(message, error);
+};
+/**
+ * @function setHighlighterLoader
+ * @param loader {HighlighterLoader} loads the Shiki highlighter; replaces any earlier one
+ * @returns {void} registers the loader in the global slot and drops the cached highlighter
+ */
+export const setHighlighterLoader = (loader) => {
+    globalThis[SLOT] = loader;
+    cached = undefined;
+};
+/**
+ * @function getHighlighter
+ * @param loader {HighlighterLoader | undefined} loads the highlighter; defaults to the registered
+ *        one, overridable in tests
+ * @returns {Promise<HighlighterCore | null>} the cached highlighter, or null when no loader is
+ *          registered or it failed to load
+ */
+export const getHighlighter = (loader = globalThis[SLOT]) => {
+    if (!loader) {
+        warnOnce('@haruhimemoe/ui: code blocks aren\'t highlighted. Install shiki and add `import "@haruhimemoe/ui/shiki";` once, e.g. in mdx-components.tsx.');
+        return Promise.resolve(null);
+    }
+    cached ??= loader().catch((error) => {
+        warnOnce("@haruhimemoe/ui: Shiki didn't load, so code blocks aren't highlighted.", error);
+        return null;
+    });
+    return cached;
+};
+/**
+ * @function resetHighlighter
+ * @returns {void} clears the registered loader, the cached highlighter and the warned flag
+ *          (tests only)
+ */
+export const resetHighlighter = () => {
+    globalThis[SLOT] = undefined;
+    cached = undefined;
+    warned = false;
+};

package/dist/components/mdx/mdxComponents.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/mdxComponents.ts
+ * @desc The element override map for @next/mdx's `useMDXComponents` and react-markdown's
+ *       `components` prop: links, headings (h2/h3), fenced code, tables and callout blockquotes.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { MdxBlockquote } from "./MdxBlockquote.js";
+import { MdxLink } from "./MdxLink.js";
+import { MdxPre } from "./MdxPre.js";
+import { MdxTable } from "./MdxTable.js";
+/** The element overrides for @next/mdx's useMDXComponents and react-markdown's `components`. */
+export declare const mdxComponents: {
+    a: typeof MdxLink;
+    blockquote: typeof MdxBlockquote;
+    h2: ({ node: _node, id, children, ...props }: import("./MdxHeading.js").MdxHeadingProps) => import("react").JSX.Element;
+    h3: ({ node: _node, id, children, ...props }: import("./MdxHeading.js").MdxHeadingProps) => import("react").JSX.Element;
+    pre: typeof MdxPre;
+    table: typeof MdxTable;
+};

package/dist/components/mdx/mdxComponents.js

@@ -0,0 +1,22 @@
+/**
+ * @file src/components/mdx/mdxComponents.ts
+ * @desc The element override map for @next/mdx's `useMDXComponents` and react-markdown's
+ *       `components` prop: links, headings (h2/h3), fenced code, tables and callout blockquotes.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { MdxBlockquote } from "./MdxBlockquote.js";
+import { MdxH2, MdxH3 } from "./MdxHeading.js";
+import { MdxLink } from "./MdxLink.js";
+import { MdxPre } from "./MdxPre.js";
+import { MdxTable } from "./MdxTable.js";
+/** The element overrides for @next/mdx's useMDXComponents and react-markdown's `components`. */
+export const mdxComponents = {
+    a: MdxLink,
+    blockquote: MdxBlockquote,
+    h2: MdxH2,
+    h3: MdxH3,
+    pre: MdxPre,
+    table: MdxTable,
+};

package/dist/components/mdx/parseCodeMeta.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file src/components/mdx/parseCodeMeta.ts
+ * @desc Parses a fenced code block's meta string (the text after the language on ```ts fences)
+ *       into a title (`title="..."` or `title='...'`) and a sorted, deduped list of highlighted
+ *       line numbers (`{1,3-5}`), capped at 10000 lines so a huge or malicious range can't hang
+ *       the render.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+/** A parsed code fence meta string. */
+export type CodeMeta = {
+    title?: string;
+    highlight: number[];
+};
+/**
+ * @function parseCodeMeta
+ * @param meta {string | null | undefined} the code fence's meta string, if any
+ * @returns {CodeMeta} the title (when present) and the sorted, deduped, capped highlight lines
+ */
+export declare const parseCodeMeta: (meta?: string | null) => CodeMeta;

package/dist/components/mdx/parseCodeMeta.js

@@ -0,0 +1,40 @@
+/**
+ * @file src/components/mdx/parseCodeMeta.ts
+ * @desc Parses a fenced code block's meta string (the text after the language on ```ts fences)
+ *       into a title (`title="..."` or `title='...'`) and a sorted, deduped list of highlighted
+ *       line numbers (`{1,3-5}`), capped at 10000 lines so a huge or malicious range can't hang
+ *       the render.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+const TITLE = /\btitle=(?:"([^"]*)"|'([^']*)')/;
+const RANGES = /\{([^}]*)\}/;
+const MAX_LINES = 10000;
+/**
+ * @function parseCodeMeta
+ * @param meta {string | null | undefined} the code fence's meta string, if any
+ * @returns {CodeMeta} the title (when present) and the sorted, deduped, capped highlight lines
+ */
+export const parseCodeMeta = (meta) => {
+    const text = meta ?? "";
+    const lines = new Set();
+    for (const part of RANGES.exec(text)?.[1]?.split(",") ?? []) {
+        const match = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+        if (!match)
+            continue;
+        let from = Number(match[1]);
+        let to = match[2] === undefined ? from : Number(match[2]);
+        if (from > to)
+            [from, to] = [to, from];
+        from = Math.max(from, 1);
+        for (let line = from; line <= to && lines.size < MAX_LINES; line++)
+            lines.add(line);
+    }
+    const title = TITLE.exec(text);
+    const result = { highlight: [...lines].sort((a, b) => a - b) };
+    const name = title?.[1] ?? title?.[2];
+    if (name)
+        result.title = name;
+    return result;
+};

package/dist/components/mdx/textOf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/components/mdx/textOf.ts
+ * @desc Flattens a ReactNode tree to plain text: strings and numbers pass through, arrays and
+ *       element children are recursively joined, and null/undefined/boolean contribute nothing.
+ *       Used to get a code block's plain text for Shiki and the copy button, since react-markdown
+ *       hands components React children, not a string.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type ReactNode } from "react";
+/**
+ * @function textOf
+ * @param node {ReactNode} the node (or tree of nodes) to flatten
+ * @returns {string} the concatenated text content
+ */
+export declare const textOf: (node: ReactNode) => string;

package/dist/components/mdx/textOf.js

@@ -0,0 +1,28 @@
+/**
+ * @file src/components/mdx/textOf.ts
+ * @desc Flattens a ReactNode tree to plain text: strings and numbers pass through, arrays and
+ *       element children are recursively joined, and null/undefined/boolean contribute nothing.
+ *       Used to get a code block's plain text for Shiki and the copy button, since react-markdown
+ *       hands components React children, not a string.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { isValidElement } from "react";
+/**
+ * @function textOf
+ * @param node {ReactNode} the node (or tree of nodes) to flatten
+ * @returns {string} the concatenated text content
+ */
+export const textOf = (node) => {
+    if (node === null || node === undefined || typeof node === "boolean")
+        return "";
+    if (typeof node === "string" || typeof node === "number" || typeof node === "bigint") {
+        return String(node);
+    }
+    if (Array.isArray(node))
+        return node.map(textOf).join("");
+    if (isValidElement(node))
+        return textOf(node.props.children);
+    return "";
+};

package/dist/mdx.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/mdx.ts
+ * @desc The `@haruhimemoe/ui/mdx` subpath: MDX element overrides and the pieces apps wire them
+ *       up with. Every export here is a server component or a plain server-safe function; the
+ *       only client code (CodeCopyButton) is rendered internally by CodeBlock, never exported.
+ *       `CodeBlock` colorizes code only when the app installs `shiki` (an optional peer
+ *       dependency) and imports `@haruhimemoe/ui/shiki` once; otherwise code renders as plain,
+ *       unstyled text.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+export { Callout, type CalloutProps, type CalloutType } from "./components/mdx/Callout.js";
+export { CodeBlock, type CodeBlockProps } from "./components/mdx/CodeBlock.js";
+export { mdxComponents } from "./components/mdx/mdxComponents.js";
+export { type CodeMeta, parseCodeMeta } from "./components/mdx/parseCodeMeta.js";
+export { slugify } from "./remark/slugify.js";

package/dist/mdx.js

@@ -0,0 +1,17 @@
+/**
+ * @file src/mdx.ts
+ * @desc The `@haruhimemoe/ui/mdx` subpath: MDX element overrides and the pieces apps wire them
+ *       up with. Every export here is a server component or a plain server-safe function; the
+ *       only client code (CodeCopyButton) is rendered internally by CodeBlock, never exported.
+ *       `CodeBlock` colorizes code only when the app installs `shiki` (an optional peer
+ *       dependency) and imports `@haruhimemoe/ui/shiki` once; otherwise code renders as plain,
+ *       unstyled text.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+export { Callout } from "./components/mdx/Callout.js";
+export { CodeBlock } from "./components/mdx/CodeBlock.js";
+export { mdxComponents } from "./components/mdx/mdxComponents.js";
+export { parseCodeMeta } from "./components/mdx/parseCodeMeta.js";
+export { slugify } from "./remark/slugify.js";

package/dist/remark/callouts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/remark/callouts.ts
+ * @desc A remark plugin for GitHub-style callouts: a blockquote whose first paragraph starts
+ *       with `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` (case-insensitive)
+ *       gets `data.hProperties.dataCallout` set to one of three rendered types, and the marker
+ *       text is stripped from the paragraph (the paragraph itself is dropped if the marker was
+ *       its only content).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type MdNode } from "./mdast.js";
+/** The three callout types this plugin renders. */
+export type CalloutType = "note" | "tip" | "warning";
+/**
+ * @function remarkCallouts
+ * @returns {(tree: MdNode) => void} a remark transformer that types matching blockquotes and
+ *          strips their marker text
+ */
+export declare const remarkCallouts: () => (tree: MdNode) => void;

package/dist/remark/callouts.js

@@ -0,0 +1,58 @@
+/**
+ * @file src/remark/callouts.ts
+ * @desc A remark plugin for GitHub-style callouts: a blockquote whose first paragraph starts
+ *       with `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` (case-insensitive)
+ *       gets `data.hProperties.dataCallout` set to one of three rendered types, and the marker
+ *       text is stripped from the paragraph (the paragraph itself is dropped if the marker was
+ *       its only content).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { setProperty, walk } from "./mdast.js";
+const TYPES = {
+    note: "note",
+    tip: "tip",
+    important: "tip",
+    warning: "warning",
+    caution: "warning",
+};
+const MARKER = /^\[!(note|tip|important|warning|caution)\][ \t]*(?:\r?\n)?/i;
+/**
+ * @function remarkCallouts
+ * @returns {(tree: MdNode) => void} a remark transformer that types matching blockquotes and
+ *          strips their marker text
+ */
+export const remarkCallouts = () => (tree) => {
+    walk(tree, (node) => {
+        if (node.type !== "blockquote")
+            return;
+        const paragraph = node.children?.[0];
+        if (paragraph?.type !== "paragraph" || !paragraph.children)
+            return;
+        // A parser may split "[!NOTE]" over several text nodes: join the leading run first.
+        let end = 0;
+        while (paragraph.children[end]?.type === "text")
+            end++;
+        if (end === 0)
+            return;
+        const text = paragraph.children
+            .slice(0, end)
+            .map((child) => child.value ?? "")
+            .join("");
+        const match = MARKER.exec(text);
+        if (!match)
+            return;
+        const key = match[1].toLowerCase();
+        const calloutType = TYPES[key];
+        if (!calloutType)
+            return;
+        setProperty(node, "dataCallout", calloutType);
+        const rest = text.slice(match[0].length);
+        paragraph.children.splice(0, end, ...(rest ? [{ type: "text", value: rest }] : []));
+        if (paragraph.children[0]?.type === "break")
+            paragraph.children.shift();
+        if (paragraph.children.length === 0)
+            node.children?.shift();
+    });
+};

package/dist/remark/codeMeta.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/remark/codeMeta.ts
+ * @desc A remark plugin that copies a fenced code block's meta string (the text after the
+ *       language on the opening fence, e.g. `title="a.ts" {2}`) onto the node as
+ *       `data.hProperties.dataMeta`, so mdast-util-to-hast renders it as `data-meta` and
+ *       CodeBlock can read it client-side.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type MdNode } from "./mdast.js";
+/**
+ * @function remarkCodeMeta
+ * @returns {(tree: MdNode) => void} a remark transformer that sets `dataMeta` on every code node
+ *          that has a non-empty `meta` string
+ */
+export declare const remarkCodeMeta: () => (tree: MdNode) => void;

package/dist/remark/codeMeta.js

@@ -0,0 +1,22 @@
+/**
+ * @file src/remark/codeMeta.ts
+ * @desc A remark plugin that copies a fenced code block's meta string (the text after the
+ *       language on the opening fence, e.g. `title="a.ts" {2}`) onto the node as
+ *       `data.hProperties.dataMeta`, so mdast-util-to-hast renders it as `data-meta` and
+ *       CodeBlock can read it client-side.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { setProperty, walk } from "./mdast.js";
+/**
+ * @function remarkCodeMeta
+ * @returns {(tree: MdNode) => void} a remark transformer that sets `dataMeta` on every code node
+ *          that has a non-empty `meta` string
+ */
+export const remarkCodeMeta = () => (tree) => {
+    walk(tree, (node) => {
+        if (node.type === "code" && node.meta)
+            setProperty(node, "dataMeta", node.meta);
+    });
+};

package/dist/remark/headingIds.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file src/remark/headingIds.ts
+ * @desc A remark plugin that gives every depth-2 and depth-3 heading a GitHub-style id slugged
+ *       from its text, deduplicated across the document. A heading that already has an id
+ *       (`data.hProperties.id`) keeps it, and a heading whose text slugs to an empty string gets
+ *       no id at all.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { type MdNode } from "./mdast.js";
+/**
+ * @function remarkHeadingIds
+ * @returns {(tree: MdNode) => void} a remark transformer that ids depth-2/3 headings
+ */
+export declare const remarkHeadingIds: () => (tree: MdNode) => void;

package/dist/remark/headingIds.js

@@ -0,0 +1,28 @@
+/**
+ * @file src/remark/headingIds.ts
+ * @desc A remark plugin that gives every depth-2 and depth-3 heading a GitHub-style id slugged
+ *       from its text, deduplicated across the document. A heading that already has an id
+ *       (`data.hProperties.id`) keeps it, and a heading whose text slugs to an empty string gets
+ *       no id at all.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { setProperty, textContent, walk } from "./mdast.js";
+import { createSlugger } from "./slugify.js";
+/**
+ * @function remarkHeadingIds
+ * @returns {(tree: MdNode) => void} a remark transformer that ids depth-2/3 headings
+ */
+export const remarkHeadingIds = () => (tree) => {
+    const slug = createSlugger();
+    walk(tree, (node) => {
+        if (node.type !== "heading" || (node.depth !== 2 && node.depth !== 3))
+            return;
+        if (node.data?.hProperties?.id)
+            return;
+        const id = slug(textContent(node));
+        if (id)
+            setProperty(node, "id", id);
+    });
+};

package/dist/remark/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file src/remark/index.ts
+ * @desc The public entry point for `@haruhimemoe/ui/remark`: one remark plugin for MDX and
+ *       react-markdown that combines code meta, callouts and heading ids, plus the individual
+ *       plugins and the slug helpers for callers who want only one piece.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import type { MdNode } from "./mdast.js";
+export type { CalloutType } from "./callouts.js";
+export { remarkCallouts } from "./callouts.js";
+export { remarkCodeMeta } from "./codeMeta.js";
+export { remarkHeadingIds } from "./headingIds.js";
+export { createSlugger, slugify } from "./slugify.js";
+/** Which of the three plugins `remarkHaruhime` runs; each defaults to on. */
+export type RemarkHaruhimeOptions = {
+    codeMeta?: boolean;
+    callouts?: boolean;
+    headingIds?: boolean;
+};
+/**
+ * @function remarkHaruhime
+ * @param options {RemarkHaruhimeOptions} per-plugin opt-outs; omit to run all three
+ * @returns {(tree: MdNode) => void} a remark transformer running code meta, callouts and heading
+ *          ids over one tree. A default export, because Turbopack only takes MDX plugins by
+ *          module name: `remarkPlugins: ["@haruhimemoe/ui/remark"]`.
+ */
+export default function remarkHaruhime(options?: RemarkHaruhimeOptions): (tree: MdNode) => void;

package/dist/remark/index.js

@@ -0,0 +1,33 @@
+/**
+ * @file src/remark/index.ts
+ * @desc The public entry point for `@haruhimemoe/ui/remark`: one remark plugin for MDX and
+ *       react-markdown that combines code meta, callouts and heading ids, plus the individual
+ *       plugins and the slug helpers for callers who want only one piece.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sat Oct 3, 2026
+ * @modified Sat Oct 3, 2026
+ */
+import { remarkCallouts } from "./callouts.js";
+import { remarkCodeMeta } from "./codeMeta.js";
+import { remarkHeadingIds } from "./headingIds.js";
+export { remarkCallouts } from "./callouts.js";
+export { remarkCodeMeta } from "./codeMeta.js";
+export { remarkHeadingIds } from "./headingIds.js";
+export { createSlugger, slugify } from "./slugify.js";
+/**
+ * @function remarkHaruhime
+ * @param options {RemarkHaruhimeOptions} per-plugin opt-outs; omit to run all three
+ * @returns {(tree: MdNode) => void} a remark transformer running code meta, callouts and heading
+ *          ids over one tree. A default export, because Turbopack only takes MDX plugins by
+ *          module name: `remarkPlugins: ["@haruhimemoe/ui/remark"]`.
+ */
+export default function remarkHaruhime(options = {}) {
+    return (tree) => {
+        if (options.codeMeta !== false)
+            remarkCodeMeta()(tree);
+        if (options.callouts !== false)
+            remarkCallouts()(tree);
+        if (options.headingIds !== false)
+            remarkHeadingIds()(tree);
+    };
+}