@docubook/mdx 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,32 @@
 
 Framework-agnostic MDX components for React with adapter entrypoints.
 
+## Install
+
+Install from npm registry:
+
+```bash
+npm install @docubook/mdx
+```
+
+```bash
+pnpm add @docubook/mdx
+```
+
+```bash
+yarn add @docubook/mdx
+```
+
+```bash
+bun add @docubook/mdx
+```
+
+If you are using a pnpm workspace/monorepo and want to add it to a specific app package, run the command from that app directory, or use filter:
+
+```bash
+pnpm --filter <your-app-package-name> add @docubook/mdx
+```
+
 ## Entrypoints
 
 - `@docubook/mdx`: server-safe convenience export (alias to subset `core/server`).
@@ -106,6 +132,101 @@ Use this as practical guidance for helper imports:
 | NextImageMdx   | Adapter (Next.js) | `@docubook/mdx/next`        | For `img` mapping in Next App Router.                          |
 | NextLinkMdx    | Adapter (Next.js) | `@docubook/mdx/next`        | For `a` mapping in Next App Router.                            |
 
+## Styling Override (Backward Compatible)
+
+Default styling in `core` follows the same base look as the `nextjs-vercel` markdown components for backward compatibility.
+
+Best practice: override styles globally using the built-in semantic hooks (`data-docubook` and `dbk-*` classes) in your app stylesheet, so you do not need to add `className` in MDX content.
+
+### Global Override Example (recommended)
+
+Use in `styles/globals.css` or `styles/override.css`:
+
+```css
+/* Accordion */
+[data-docubook="accordion-button"] {
+	@apply bg-blue-50 hover:bg-blue-100;
+}
+
+[data-docubook="accordion-title"] {
+	@apply text-blue-900 font-semibold;
+}
+
+/* Note */
+[data-docubook="note"][data-variant="warning"] {
+	@apply border-amber-400/50 bg-amber-50 text-amber-900;
+}
+
+/* Tooltip */
+[data-docubook="tooltip-content"] {
+	@apply w-80 text-xs;
+}
+
+/* File tree */
+[data-docubook="file-tree"] {
+	@apply border-blue-200;
+}
+
+[data-docubook="file-tree-folder-button"] {
+	@apply py-2;
+}
+```
+
+### Selector Table For Override
+
+Use `data-docubook` selectors as the primary (stable) target, and use `dbk-*` classes as a fallback when needed.
+
+| Component | Target Element | Stable Selector (`data-docubook`) | Class Hook (`dbk-*`) |
+| --- | --- | --- | --- |
+| Accordion | Root | `[data-docubook="accordion"]` | `.dbk-accordion` |
+| Accordion | Trigger Button | `[data-docubook="accordion-button"]` | `.dbk-accordion__button` |
+| Accordion | Chevron | `[data-docubook="accordion-chevron"]` | `.dbk-accordion__chevron` |
+| Accordion | Title | `[data-docubook="accordion-title"]` | `.dbk-accordion__title` |
+| Accordion | Content Body | `[data-docubook="accordion-content-body"]` | `.dbk-accordion__content-body` |
+| AccordionGroup | Root | `[data-docubook="accordion-group"]` | `.dbk-accordion-group` |
+| Note | Root | `[data-docubook="note"]` | `.dbk-note` |
+| Note | Variant Warning | `[data-docubook="note"][data-variant="warning"]` | `.dbk-note[data-variant="warning"]` |
+| Note | Title | `[data-docubook="note-title"]` | `.dbk-note__title` |
+| Stepper | Root | `[data-docubook="stepper"]` | `.dbk-stepper` |
+| Stepper | Item | `[data-docubook="stepper-item"]` | `.dbk-stepper__item` |
+| Stepper | Number | `[data-docubook="stepper-number"]` | `.dbk-stepper__number` |
+| StepperItem | Title | `[data-docubook="stepper-item-title"]` | `.dbk-stepper-item__title` |
+| Tooltip | Root | `[data-docubook="tooltip"]` | `.dbk-tooltip` |
+| Tooltip | Trigger | `[data-docubook="tooltip-trigger"]` | `.dbk-tooltip__trigger` |
+| Tooltip | Content | `[data-docubook="tooltip-content"]` | `.dbk-tooltip__content` |
+| FileTree | Root | `[data-docubook="file-tree"]` | `.dbk-file-tree` |
+| FileTree | Folder Button | `[data-docubook="file-tree-folder-button"]` | `.dbk-file-tree__folder-button` |
+| FileTree | Folder Children | `[data-docubook="file-tree-folder-children"]` | `.dbk-file-tree__folder-children` |
+| FileTree | File Row | `[data-docubook="file-tree-file"]` | `.dbk-file-tree__file` |
+| Card | Root | `[data-docubook="card"]` | `.dbk-card` |
+| Card | Link Wrapper | `[data-docubook="card-link"]` | `.dbk-card__link` |
+| Card | Title | `[data-docubook="card-title"]` | `.dbk-card__title` |
+| Copy | Button | `[data-docubook="copy-button"]` | `.dbk-copy` |
+| Copy | Icon | `[data-docubook="copy-icon"]` | `.dbk-copy__icon` |
+| Keyboard (Kbd) | Root | `[data-docubook="kbd"]` | `.dbk-kbd` |
+| Release | Root | `[data-docubook="release"]` | `.dbk-release` |
+| Release | Version Badge | `[data-docubook="release-version"]` | `.dbk-release__version` |
+| Release | Title | `[data-docubook="release-title"]` | `.dbk-release__title` |
+| Changes | Root | `[data-docubook="release-changes"]` | `.dbk-release-changes` |
+| Changes | Badge | `[data-docubook="release-changes-badge"]` | `.dbk-release-changes__badge` |
+| Changes | Item | `[data-docubook="release-changes-item"]` | `.dbk-release-changes__item` |
+
+Quick example:
+
+```css
+[data-docubook="card-title"] {
+	@apply text-blue-700;
+}
+
+[data-docubook="copy-button"] {
+	@apply rounded-lg border-blue-300;
+}
+
+[data-docubook="release-changes"][data-type="improved"] [data-docubook="release-changes-badge"] {
+	@apply bg-sky-100 text-sky-700;
+}
+```
+
 ## Loading Strategy (Helper)
 
 - Prefer static import for high-frequency primitives: `a`, `img`, `pre`.

package/dist/{Stepper-B7xt0Dyr.d.cts → Stepper-I9nywkZb.d.cts}

@@ -45,7 +45,7 @@ interface ChangesProps extends PropsWithChildren {
 }
 declare function Changes({ type, children }: ChangesProps): react_jsx_runtime.JSX.Element;
 
-declare function Stepper({ children }: PropsWithChildren): react_jsx_runtime.JSX.Element;
+declare function Stepper({ children, }: PropsWithChildren): react_jsx_runtime.JSX.Element;
 declare function StepperItem({ children, title, }: PropsWithChildren & {
     title?: string;
 }): react_jsx_runtime.JSX.Element;

package/dist/{Stepper-B7xt0Dyr.d.ts → Stepper-I9nywkZb.d.ts}

@@ -45,7 +45,7 @@ interface ChangesProps extends PropsWithChildren {
 }
 declare function Changes({ type, children }: ChangesProps): react_jsx_runtime.JSX.Element;
 
-declare function Stepper({ children }: PropsWithChildren): react_jsx_runtime.JSX.Element;
+declare function Stepper({ children, }: PropsWithChildren): react_jsx_runtime.JSX.Element;
 declare function StepperItem({ children, title, }: PropsWithChildren & {
     title?: string;
 }): react_jsx_runtime.JSX.Element;

package/dist/adapters/next/index.cjs

@@ -110,6 +110,7 @@ function Card({
     "div",
     {
       className: (0, import_clsx.default)(
+        "dbk-card",
         "border rounded-lg shadow-sm p-4 transition-all duration-200",
         "bg-card text-card-foreground border-border",
         "hover:bg-accent/5 hover:border-accent/30",
@@ -117,20 +118,21 @@ function Card({
         horizontal ? "flex-row items-start gap-1" : "flex-col space-y-1",
         className
       ),
+      "data-docubook": "card",
       children: [
-        Icon && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Icon, { className: (0, import_clsx.default)("w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5") }),
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "flex-1 min-w-0", children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "text-base font-semibold text-foreground leading-6", children: title }),
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "text-sm text-muted-foreground -mt-3", children })
+        Icon && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Icon, { className: (0, import_clsx.default)("dbk-card__icon", "w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5"), "data-docubook": "card-icon" }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "dbk-card__body flex-1 min-w-0", "data-docubook": "card-body", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "dbk-card__title text-base font-semibold text-foreground leading-6", "data-docubook": "card-title", children: title }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "dbk-card__content text-sm text-muted-foreground -mt-3", "data-docubook": "card-content", children })
         ] })
       ]
     }
   );
   if (!href) return content;
   if (LinkComponent) {
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LinkComponent, { href, className: "no-underline block", children: content });
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LinkComponent, { href, className: "dbk-card__link no-underline block", "data-docubook": "card-link", children: content });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("a", { className: "no-underline block", href, children: content });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("a", { className: "dbk-card__link no-underline block", href, "data-docubook": "card-link", children: content });
 }
 
 // src/adapters/next/index.tsx

package/dist/adapters/next/index.js

@@ -73,6 +73,7 @@ function Card({
     "div",
     {
       className: clsx(
+        "dbk-card",
         "border rounded-lg shadow-sm p-4 transition-all duration-200",
         "bg-card text-card-foreground border-border",
         "hover:bg-accent/5 hover:border-accent/30",
@@ -80,20 +81,21 @@ function Card({
         horizontal ? "flex-row items-start gap-1" : "flex-col space-y-1",
         className
       ),
+      "data-docubook": "card",
       children: [
-        Icon && /* @__PURE__ */ jsx2(Icon, { className: clsx("w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5") }),
-        /* @__PURE__ */ jsxs2("div", { className: "flex-1 min-w-0", children: [
-          /* @__PURE__ */ jsx2("div", { className: "text-base font-semibold text-foreground leading-6", children: title }),
-          /* @__PURE__ */ jsx2("div", { className: "text-sm text-muted-foreground -mt-3", children })
+        Icon && /* @__PURE__ */ jsx2(Icon, { className: clsx("dbk-card__icon", "w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5"), "data-docubook": "card-icon" }),
+        /* @__PURE__ */ jsxs2("div", { className: "dbk-card__body flex-1 min-w-0", "data-docubook": "card-body", children: [
+          /* @__PURE__ */ jsx2("div", { className: "dbk-card__title text-base font-semibold text-foreground leading-6", "data-docubook": "card-title", children: title }),
+          /* @__PURE__ */ jsx2("div", { className: "dbk-card__content text-sm text-muted-foreground -mt-3", "data-docubook": "card-content", children })
         ] })
       ]
     }
   );
   if (!href) return content;
   if (LinkComponent) {
-    return /* @__PURE__ */ jsx2(LinkComponent, { href, className: "no-underline block", children: content });
+    return /* @__PURE__ */ jsx2(LinkComponent, { href, className: "dbk-card__link no-underline block", "data-docubook": "card-link", children: content });
   }
-  return /* @__PURE__ */ jsx2("a", { className: "no-underline block", href, children: content });
+  return /* @__PURE__ */ jsx2("a", { className: "dbk-card__link no-underline block", href, "data-docubook": "card-link", children: content });
 }
 
 // src/adapters/next/index.tsx

package/dist/adapters/react-router/index.cjs

@@ -109,6 +109,7 @@ function Card({
     "div",
     {
       className: (0, import_clsx.default)(
+        "dbk-card",
         "border rounded-lg shadow-sm p-4 transition-all duration-200",
         "bg-card text-card-foreground border-border",
         "hover:bg-accent/5 hover:border-accent/30",
@@ -116,20 +117,21 @@ function Card({
         horizontal ? "flex-row items-start gap-1" : "flex-col space-y-1",
         className
       ),
+      "data-docubook": "card",
       children: [
-        Icon && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Icon, { className: (0, import_clsx.default)("w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5") }),
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "flex-1 min-w-0", children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "text-base font-semibold text-foreground leading-6", children: title }),
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "text-sm text-muted-foreground -mt-3", children })
+        Icon && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Icon, { className: (0, import_clsx.default)("dbk-card__icon", "w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5"), "data-docubook": "card-icon" }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "dbk-card__body flex-1 min-w-0", "data-docubook": "card-body", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "dbk-card__title text-base font-semibold text-foreground leading-6", "data-docubook": "card-title", children: title }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "dbk-card__content text-sm text-muted-foreground -mt-3", "data-docubook": "card-content", children })
         ] })
       ]
     }
   );
   if (!href) return content;
   if (LinkComponent) {
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LinkComponent, { href, className: "no-underline block", children: content });
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LinkComponent, { href, className: "dbk-card__link no-underline block", "data-docubook": "card-link", children: content });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("a", { className: "no-underline block", href, children: content });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("a", { className: "dbk-card__link no-underline block", href, "data-docubook": "card-link", children: content });
 }
 
 // src/core/components/Image.tsx

package/dist/adapters/react-router/index.js

@@ -72,6 +72,7 @@ function Card({
     "div",
     {
       className: clsx(
+        "dbk-card",
         "border rounded-lg shadow-sm p-4 transition-all duration-200",
         "bg-card text-card-foreground border-border",
         "hover:bg-accent/5 hover:border-accent/30",
@@ -79,20 +80,21 @@ function Card({
         horizontal ? "flex-row items-start gap-1" : "flex-col space-y-1",
         className
       ),
+      "data-docubook": "card",
       children: [
-        Icon && /* @__PURE__ */ jsx2(Icon, { className: clsx("w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5") }),
-        /* @__PURE__ */ jsxs2("div", { className: "flex-1 min-w-0", children: [
-          /* @__PURE__ */ jsx2("div", { className: "text-base font-semibold text-foreground leading-6", children: title }),
-          /* @__PURE__ */ jsx2("div", { className: "text-sm text-muted-foreground -mt-3", children })
+        Icon && /* @__PURE__ */ jsx2(Icon, { className: clsx("dbk-card__icon", "w-5 h-5 text-primary shrink-0", horizontal && "mt-0.5"), "data-docubook": "card-icon" }),
+        /* @__PURE__ */ jsxs2("div", { className: "dbk-card__body flex-1 min-w-0", "data-docubook": "card-body", children: [
+          /* @__PURE__ */ jsx2("div", { className: "dbk-card__title text-base font-semibold text-foreground leading-6", "data-docubook": "card-title", children: title }),
+          /* @__PURE__ */ jsx2("div", { className: "dbk-card__content text-sm text-muted-foreground -mt-3", "data-docubook": "card-content", children })
         ] })
       ]
     }
   );
   if (!href) return content;
   if (LinkComponent) {
-    return /* @__PURE__ */ jsx2(LinkComponent, { href, className: "no-underline block", children: content });
+    return /* @__PURE__ */ jsx2(LinkComponent, { href, className: "dbk-card__link no-underline block", "data-docubook": "card-link", children: content });
   }
-  return /* @__PURE__ */ jsx2("a", { className: "no-underline block", href, children: content });
+  return /* @__PURE__ */ jsx2("a", { className: "dbk-card__link no-underline block", href, "data-docubook": "card-link", children: content });
 }
 
 // src/core/components/Image.tsx