boltdocs 1.0.0

package/src/client/theme/components/mdx/Admonition.tsx

@@ -0,0 +1,80 @@
+import React from "react";
+import {
+  Info,
+  Lightbulb,
+  AlertTriangle,
+  ShieldAlert,
+  Bookmark,
+} from "lucide-react";
+
+const ICON_MAP: Record<string, React.ReactNode> = {
+  note: <Bookmark size={18} />,
+  tip: <Lightbulb size={18} />,
+  info: <Info size={18} />,
+  warning: <AlertTriangle size={18} />,
+  danger: <ShieldAlert size={18} />,
+};
+
+const LABEL_MAP: Record<string, string> = {
+  note: "Note",
+  tip: "Tip",
+  info: "Info",
+  warning: "Warning",
+  danger: "Danger",
+};
+
+export interface AdmonitionProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Admonition type — controls color and icon */
+  type?: "note" | "tip" | "info" | "warning" | "danger";
+  /** Override the default title */
+  title?: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Callout / admonition box for notes, warnings, etc.
+ *
+ * ```mdx
+ * <Admonition type="warning" title="Breaking Change">
+ *   This API has changed in v2.
+ * </Admonition>
+ * ```
+ */
+export function Admonition({
+  type = "note",
+  title,
+  children,
+  className = "",
+  ...rest
+}: AdmonitionProps) {
+  return (
+    <div
+      className={`ld-admonition ld-admonition--${type} ${className}`.trim()}
+      role={type === "warning" || type === "danger" ? "alert" : "note"}
+      {...rest}
+    >
+      <div className="ld-admonition__header">
+        <span className="ld-admonition__icon">{ICON_MAP[type]}</span>
+        <span className="ld-admonition__title">{title || LABEL_MAP[type]}</span>
+      </div>
+      <div className="ld-admonition__body">{children}</div>
+    </div>
+  );
+}
+
+/* ─── Convenience aliases ─────────────────────────────────── */
+export const Note = (props: Omit<AdmonitionProps, "type">) => (
+  <Admonition type="note" {...props} />
+);
+export const Tip = (props: Omit<AdmonitionProps, "type">) => (
+  <Admonition type="tip" {...props} />
+);
+export const Warning = (props: Omit<AdmonitionProps, "type">) => (
+  <Admonition type="warning" {...props} />
+);
+export const Danger = (props: Omit<AdmonitionProps, "type">) => (
+  <Admonition type="danger" {...props} />
+);
+export const InfoBox = (props: Omit<AdmonitionProps, "type">) => (
+  <Admonition type="info" {...props} />
+);

package/src/client/theme/components/mdx/Badge.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Color variant */
+  variant?: "default" | "primary" | "success" | "warning" | "danger" | "info";
+  children: React.ReactNode;
+}
+
+/**
+ * Inline badge / pill for labels, statuses, or tags.
+ *
+ * ```mdx
+ * <Badge variant="success">Stable</Badge>
+ * <Badge variant="warning">Beta</Badge>
+ * ```
+ */
+export function Badge({
+  variant = "default",
+  children,
+  className = "",
+  ...rest
+}: BadgeProps) {
+  return (
+    <span
+      className={`ld-badge ld-badge--${variant} ${className}`.trim()}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+}

package/src/client/theme/components/mdx/Button.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+
+export type ButtonProps = React.AnchorHTMLAttributes<HTMLAnchorElement> &
+  React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    /** Visual variant */
+    variant?: "primary" | "secondary" | "outline" | "ghost";
+    /** Size */
+    size?: "sm" | "md" | "lg";
+    /** If provided, renders as a link */
+    href?: string;
+    children: React.ReactNode;
+  };
+
+/**
+ * A versatile button/link component for use in MDX pages and the home page.
+ *
+ * ```mdx
+ * <Button variant="primary" href="/docs/getting-started">Get Started →</Button>
+ * <Button variant="secondary" href="https://github.com">GitHub</Button>
+ * ```
+ */
+export function Button({
+  variant = "primary",
+  size = "md",
+  href,
+  children,
+  className = "",
+  ...rest
+}: ButtonProps) {
+  const cls = `ld-btn ld-btn--${variant} ld-btn--${size} ${className}`.trim();
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        style={{ textDecoration: "none" }}
+        className={cls}
+        {...(rest as any)}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <button className={cls} {...(rest as any)}>
+      {children}
+    </button>
+  );
+}

package/src/client/theme/components/mdx/Card.tsx

@@ -0,0 +1,80 @@
+import React from "react";
+
+/* ─── Cards (grid container) ─────────────────────────────── */
+export interface CardsProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Number of columns (defaults to 3) */
+  cols?: 1 | 2 | 3 | 4;
+  children: React.ReactNode;
+}
+
+/**
+ * Grid wrapper for `<Card>` components.
+ *
+ * ```mdx
+ * <Cards cols={3}>
+ *   <Card title="Fast" icon="⚡">Instant HMR.</Card>
+ *   <Card title="Simple" icon="📁">File-system routing.</Card>
+ * </Cards>
+ * ```
+ */
+export function Cards({
+  cols = 3,
+  children,
+  className = "",
+  ...rest
+}: CardsProps) {
+  return (
+    <div className={`ld-cards ld-cards--${cols} ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/* ─── Card ─────────────────────────────────────────────────── */
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Card heading */
+  title?: string;
+  /** Emoji or icon string displayed above the title */
+  icon?: React.ReactNode;
+  /** If provided, the entire card becomes a link */
+  href?: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * Individual feature/info card.
+ */
+export function Card({
+  title,
+  icon,
+  href,
+  children,
+  className = "",
+  ...rest
+}: CardProps) {
+  const inner = (
+    <>
+      {icon && <span className="ld-card__icon">{icon}</span>}
+      {title && <h3 className="ld-card__title">{title}</h3>}
+      {children && <div className="ld-card__body">{children}</div>}
+    </>
+  );
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        className={`ld-card ld-card--link ${className}`.trim()}
+        {...(rest as any)}
+      >
+        {inner}
+      </a>
+    );
+  }
+
+  return (
+    <div className={`ld-card ${className}`.trim()} {...rest}>
+      {inner}
+    </div>
+  );
+}

package/src/client/theme/components/mdx/List.tsx

@@ -0,0 +1,57 @@
+import React, { Children } from "react";
+import { Check, ChevronRight } from "lucide-react";
+
+export interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
+  /** Visual variant */
+  variant?: "checked" | "arrow" | "default";
+  children: React.ReactNode;
+}
+
+const ICON_MAP: Record<string, React.ReactNode> = {
+  checked: <Check size={14} className="ld-list__icon" />,
+  arrow: <ChevronRight size={14} className="ld-list__icon" />,
+};
+
+/**
+ * Enhanced list component with icon variants.
+ *
+ * ```mdx
+ * <List variant="checked">
+ *   <li>File-system routing</li>
+ *   <li>MDX support</li>
+ *   <li>Syntax highlighting</li>
+ * </List>
+ * ```
+ */
+export function List({
+  variant = "default",
+  children,
+  className = "",
+  ...rest
+}: ListProps) {
+  if (variant === "default") {
+    return (
+      <ul className={`ld-list ${className}`.trim()} {...rest}>
+        {children}
+      </ul>
+    );
+  }
+
+  const icon = ICON_MAP[variant];
+
+  return (
+    <ul className={`ld-list ld-list--${variant} ${className}`.trim()} {...rest}>
+      {Children.map(children, (child) => {
+        if (!React.isValidElement(child)) return child;
+        return (
+          <li className="ld-list__item">
+            {icon}
+            <span className="ld-list__text">
+              {(child as React.ReactElement<any>).props.children}
+            </span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/client/theme/components/mdx/Tabs.tsx

@@ -0,0 +1,94 @@
+import React, { useState, Children, isValidElement, useRef } from "react";
+
+/* ─── Tab (individual panel) ──────────────────────────────── */
+export interface TabProps {
+  /** The label shown in the tab bar */
+  label: string;
+  children: React.ReactNode;
+}
+
+/**
+ * A single tab panel. Must be used inside `<Tabs>`.
+ *
+ * ```mdx
+ * <Tab label="npm">npm install boltdocs</Tab>
+ * ```
+ */
+export function Tab({ children }: TabProps) {
+  return <div className="ld-tab-panel">{children}</div>;
+}
+
+/* ─── Tabs (container) ────────────────────────────────────── */
+export interface TabsProps {
+  /** Which tab index is initially active (0-based, default 0) */
+  defaultIndex?: number;
+  children: React.ReactNode;
+}
+
+/**
+ * Tab container that manages active state.
+ *
+ * ```mdx
+ * <Tabs>
+ *   <Tab label="npm">npm install boltdocs</Tab>
+ *   <Tab label="pnpm">pnpm add boltdocs</Tab>
+ *   <Tab label="yarn">yarn add boltdocs</Tab>
+ * </Tabs>
+ * ```
+ */
+export function Tabs({ defaultIndex = 0, children }: TabsProps) {
+  const [active, setActive] = useState(defaultIndex);
+  const tabRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  // Extract Tab children
+  const tabs = Children.toArray(children).filter(
+    (child) => isValidElement(child) && (child as any).props?.label,
+  );
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    let newIndex = active;
+    if (e.key === "ArrowRight") {
+      newIndex = (active + 1) % tabs.length;
+    } else if (e.key === "ArrowLeft") {
+      newIndex = (active - 1 + tabs.length) % tabs.length;
+    }
+
+    if (newIndex !== active) {
+      setActive(newIndex);
+      tabRefs.current[newIndex]?.focus();
+    }
+  };
+
+  return (
+    <div className="ld-tabs">
+      <div className="ld-tabs__bar" role="tablist" onKeyDown={handleKeyDown}>
+        {tabs.map((child, i) => {
+          const label = (child as React.ReactElement<TabProps>).props.label;
+          return (
+            <button
+              key={i}
+              role="tab"
+              aria-selected={i === active}
+              aria-controls={`tabpanel-${i}`}
+              id={`tab-${i}`}
+              tabIndex={i === active ? 0 : -1}
+              ref={(el) => { tabRefs.current[i] = el; }}
+              className={`ld-tabs__trigger ${i === active ? "ld-tabs__trigger--active" : ""}`}
+              onClick={() => setActive(i)}
+            >
+              {label}
+            </button>
+          );
+        })}
+      </div>
+      <div
+        className="ld-tabs__content"
+        role="tabpanel"
+        id={`tabpanel-${active}`}
+        aria-labelledby={`tab-${active}`}
+      >
+        {tabs[active]}
+      </div>
+    </div>
+  );
+}

package/src/client/theme/components/mdx/index.ts

@@ -0,0 +1,18 @@
+// MDX UI Components — barrel export
+export { Button } from "./Button";
+export type { ButtonProps } from "./Button";
+
+export { Badge } from "./Badge";
+export type { BadgeProps } from "./Badge";
+
+export { Card, Cards } from "./Card";
+export type { CardProps, CardsProps } from "./Card";
+
+export { Tabs, Tab } from "./Tabs";
+export type { TabsProps, TabProps } from "./Tabs";
+
+export { Admonition, Note, Tip, Warning, Danger, InfoBox } from "./Admonition";
+export type { AdmonitionProps } from "./Admonition";
+
+export { List } from "./List";
+export type { ListProps } from "./List";