@roadlittledawn/docs-design-system-react 0.4.0 → 0.5.0

package/dist/components/CollapserGroup.stories.js

@@ -37,6 +37,13 @@ export var Basic = {
         spacing: '0.5rem',
         allowMultiple: true,
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup spacing=\"0.5rem\" allowMultiple>\n  <Collapser title=\"What is this documentation system?\">\n    <p>\n      This is a comprehensive documentation design system that provides\n      reusable components and guidelines for creating effective technical\n      documentation.\n    </p>\n  </Collapser>\n  <Collapser title=\"How do I get started?\">\n    <p>\n      Start by installing the component package, then explore the components\n      in Storybook to understand their usage and configuration options.\n    </p>\n  </Collapser>\n  <Collapser title=\"Can I customize the components?\">\n    <p>\n      Yes! All components accept a className prop for custom styling, and you\n      can override the default styles using CSS.\n    </p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "What is this documentation system?", children: _jsx("p", { children: "This is a comprehensive documentation design system that provides reusable components and guidelines for creating effective technical documentation." }) }), _jsx(Collapser, { title: "How do I get started?", children: _jsx("p", { children: "Start by installing the component package, then explore the components in Storybook to understand their usage and configuration options." }) }), _jsx(Collapser, { title: "Can I customize the components?", children: _jsx("p", { children: "Yes! All components accept a className prop for custom styling, and you can override the default styles using CSS." }) })] }))); },
 };
 /**
@@ -46,6 +53,13 @@ export var AccordionMode = {
     args: {
         allowMultiple: false,
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup allowMultiple={false}>\n  <Collapser title=\"Installation\">\n    <p>Install the package using npm or yarn:</p>\n    <pre>npm install @roadlittledawn/docs-design-system</pre>\n  </Collapser>\n  <Collapser title=\"Configuration\">\n    <p>Import the CSS and components in your application:</p>\n    <pre>import '@roadlittledawn/docs-design-system/dist/styles.css';</pre>\n  </Collapser>\n  <Collapser title=\"Usage\">\n    <p>Use the components in your React application:</p>\n    <pre>{'<Button variant=\"primary\">Click me</Button>'}</pre>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsxs(Collapser, { title: "Installation", children: [_jsx("p", { children: "Install the package using npm or yarn:" }), _jsx("pre", { children: "npm install @roadlittledawn/docs-design-system" })] }), _jsxs(Collapser, { title: "Configuration", children: [_jsx("p", { children: "Import the CSS and components in your application:" }), _jsx("pre", { children: "import '@roadlittledawn/docs-design-system/dist/styles.css';" })] }), _jsxs(Collapser, { title: "Usage", children: [_jsx("p", { children: "Use the components in your React application:" }), _jsx("pre", { children: '<Button variant="primary">Click me</Button>' })] })] }))); },
 };
 /**
@@ -55,6 +69,13 @@ export var CustomSpacing = {
     args: {
         spacing: '1.5rem',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup spacing=\"1.5rem\">\n  <Collapser title=\"Section 1\">\n    <p>Content with larger spacing between sections.</p>\n  </Collapser>\n  <Collapser title=\"Section 2\">\n    <p>This makes the layout more breathable.</p>\n  </Collapser>\n  <Collapser title=\"Section 3\">\n    <p>Useful for prominent content sections.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "Section 1", children: _jsx("p", { children: "Content with larger spacing between sections." }) }), _jsx(Collapser, { title: "Section 2", children: _jsx("p", { children: "This makes the layout more breathable." }) }), _jsx(Collapser, { title: "Section 3", children: _jsx("p", { children: "Useful for prominent content sections." }) })] }))); },
 };
 /**
@@ -64,6 +85,13 @@ export var DefaultOpen = {
     args: {
         defaultOpen: 0,
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup defaultOpen={0}>\n  <Collapser title=\"Getting Started\">\n    <p>This section is open by default.</p>\n  </Collapser>\n  <Collapser title=\"Advanced Topics\">\n    <p>This section starts closed.</p>\n  </Collapser>\n  <Collapser title=\"API Reference\">\n    <p>This section also starts closed.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "Getting Started", children: _jsx("p", { children: "This section is open by default." }) }), _jsx(Collapser, { title: "Advanced Topics", children: _jsx("p", { children: "This section starts closed." }) }), _jsx(Collapser, { title: "API Reference", children: _jsx("p", { children: "This section also starts closed." }) })] }))); },
 };
 /**
@@ -73,5 +101,12 @@ export var MultipleDefaultOpen = {
     args: {
         defaultOpen: [0, 2],
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup defaultOpen={[0, 2]}>\n  <Collapser title=\"Introduction\">\n    <p>This section is open by default.</p>\n  </Collapser>\n  <Collapser title=\"Installation\">\n    <p>This section starts closed.</p>\n  </Collapser>\n  <Collapser title=\"Quick Start\">\n    <p>This section is also open by default.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "Introduction", children: _jsx("p", { children: "This section is open by default." }) }), _jsx(Collapser, { title: "Installation", children: _jsx("p", { children: "This section starts closed." }) }), _jsx(Collapser, { title: "Quick Start", children: _jsx("p", { children: "This section is also open by default." }) })] }))); },
 };

package/dist/components/Heading.stories.js

@@ -24,6 +24,13 @@ export var Level1 = {
         level: 1,
         children: 'Page Title (H1)',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Heading level={1}>Page Title (H1)</Heading>",
+            },
+        },
+    },
 };
 /**
  * Level 2 heading (h2) - used for major sections.
@@ -33,6 +40,13 @@ export var Level2 = {
         level: 2,
         children: 'Section Title (H2)',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Heading level={2}>Section Title (H2)</Heading>",
+            },
+        },
+    },
 };
 /**
  * Level 3 heading (h3) - used for subsections.
@@ -42,6 +56,13 @@ export var Level3 = {
         level: 3,
         children: 'Subsection Title (H3)',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Heading level={3}>Subsection Title (H3)</Heading>",
+            },
+        },
+    },
 };
 /**
  * Level 4 heading (h4) - used for sub-subsections.
@@ -51,16 +72,37 @@ export var Level4 = {
         level: 4,
         children: 'Sub-subsection Title (H4)',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Heading level={4}>Sub-subsection Title (H4)</Heading>",
+            },
+        },
+    },
 };
 /**
  * All heading levels displayed together to show the hierarchy.
  */
 export var AllLevels = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<div>\n  <Heading level={1}>Level 1 - Main Page Title</Heading>\n  <p>Use h1 for the main page title. There should only be one h1 per page.</p>\n\n  <Heading level={2}>Level 2 - Major Section</Heading>\n  <p>Use h2 for major sections of your page.</p>\n\n  <Heading level={3}>Level 3 - Subsection</Heading>\n  <p>Use h3 for subsections within major sections.</p>\n\n  <Heading level={4}>Level 4 - Sub-subsection</Heading>\n  <p>Use h4 for sub-subsections. If you need deeper levels, reconsider your document structure.</p>\n</div>",
+            },
+        },
+    },
     render: function () { return (_jsxs("div", { children: [_jsx(Heading, { level: 1, children: "Level 1 - Main Page Title" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h1 for the main page title. There should only be one h1 per page." }), _jsx(Heading, { level: 2, children: "Level 2 - Major Section" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h2 for major sections of your page." }), _jsx(Heading, { level: 3, children: "Level 3 - Subsection" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h3 for subsections within major sections." }), _jsx(Heading, { level: 4, children: "Level 4 - Sub-subsection" }), _jsx("p", { style: { color: '#666' }, children: "Use h4 for sub-subsections. If you need deeper levels, reconsider your document structure." })] })); },
 };
 /**
  * Example of a properly structured document hierarchy.
  */
 export var DocumentStructure = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<div>\n  <Heading level={1}>Getting Started Guide</Heading>\n  <p>Introduction to the documentation system...</p>\n\n  <Heading level={2}>Installation</Heading>\n  <p>How to install the components...</p>\n\n  <Heading level={3}>Prerequisites</Heading>\n  <p>What you need before installing...</p>\n\n  <Heading level={3}>Installation Steps</Heading>\n  <p>Step-by-step installation instructions...</p>\n\n  <Heading level={2}>Configuration</Heading>\n  <p>How to configure the system...</p>\n\n  <Heading level={3}>Basic Configuration</Heading>\n  <p>Essential configuration options...</p>\n\n  <Heading level={4}>Environment Variables</Heading>\n  <p>Required environment variables...</p>\n</div>",
+            },
+        },
+    },
     render: function () { return (_jsxs("div", { children: [_jsx(Heading, { level: 1, children: "Getting Started Guide" }), _jsx("p", { children: "Introduction to the documentation system..." }), _jsx(Heading, { level: 2, children: "Installation" }), _jsx("p", { children: "How to install the components..." }), _jsx(Heading, { level: 3, children: "Prerequisites" }), _jsx("p", { children: "What you need before installing..." }), _jsx(Heading, { level: 3, children: "Installation Steps" }), _jsx("p", { children: "Step-by-step installation instructions..." }), _jsx(Heading, { level: 2, children: "Configuration" }), _jsx("p", { children: "How to configure the system..." }), _jsx(Heading, { level: 3, children: "Basic Configuration" }), _jsx("p", { children: "Essential configuration options..." }), _jsx(Heading, { level: 4, children: "Environment Variables" }), _jsx("p", { children: "Required environment variables..." })] })); },
 };

package/dist/components/Link.stories.js

@@ -24,6 +24,13 @@ export var Internal = {
         href: '/docs/components',
         children: 'View Components Documentation',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Link href=\"/docs/components\">View Components Documentation</Link>",
+            },
+        },
+    },
 };
 /**
  * External link (absolute URL) - opens in new tab with icon.
@@ -33,6 +40,13 @@ export var External = {
         href: 'https://github.com/your-repo/docs-design-system',
         children: 'View on GitHub',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Link href=\"https://github.com/your-repo/docs-design-system\">View on GitHub</Link>",
+            },
+        },
+    },
 };
 /**
  * Anchor link to a section on the same page.
@@ -42,22 +56,50 @@ export var AnchorLink = {
         href: '#installation',
         children: 'Jump to Installation',
     },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Link href=\"#installation\">Jump to Installation</Link>",
+            },
+        },
+    },
 };
 /**
  * Link within body text.
  */
 export var InlineLink = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<p>\n  For more information, check out the{' '}\n  <Link href=\"/docs/getting-started\">Getting Started guide</Link>\n  {' '}or visit our{' '}\n  <Link href=\"https://github.com\">GitHub repository</Link>.\n</p>",
+            },
+        },
+    },
     render: function () { return (_jsxs("p", { children: ["For more information, check out the", ' ', _jsx(Link, { href: "/docs/getting-started", children: "Getting Started guide" }), ' ', "or visit our", ' ', _jsx(Link, { href: "https://github.com", children: "GitHub repository" }), "."] })); },
 };
 /**
  * Multiple links in a list.
  */
 export var LinkList = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<ul style={{ listStyle: 'none', padding: 0, display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>\n  <li><Link href=\"/docs/introduction\">Introduction</Link></li>\n  <li><Link href=\"/docs/components\">Components</Link></li>\n  <li><Link href=\"/docs/best-practices\">Best Practices</Link></li>\n  <li><Link href=\"https://github.com\">GitHub</Link></li>\n  <li><Link href=\"https://npmjs.com\">NPM</Link></li>\n</ul>",
+            },
+        },
+    },
     render: function () { return (_jsxs("ul", { style: { listStyle: 'none', padding: 0, display: 'flex', flexDirection: 'column', gap: '0.5rem' }, children: [_jsx("li", { children: _jsx(Link, { href: "/docs/introduction", children: "Introduction" }) }), _jsx("li", { children: _jsx(Link, { href: "/docs/components", children: "Components" }) }), _jsx("li", { children: _jsx(Link, { href: "/docs/best-practices", children: "Best Practices" }) }), _jsx("li", { children: _jsx(Link, { href: "https://github.com", children: "GitHub" }) }), _jsx("li", { children: _jsx(Link, { href: "https://npmjs.com", children: "NPM" }) })] })); },
 };
 /**
  * Comparison of internal and external links.
  */
 export var InternalVsExternal = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>\n  <div>\n    <strong>Internal Link:</strong>\n    <br />\n    <Link href=\"/docs/components\">Components (internal)</Link>\n    <p style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }}>\n      Opens in the same tab, no icon\n    </p>\n  </div>\n  <div>\n    <strong>External Link:</strong>\n    <br />\n    <Link href=\"https://example.com\">Example.com (external)</Link>\n    <p style={{ fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }}>\n      Opens in new tab, includes external link icon\n    </p>\n  </div>\n</div>",
+            },
+        },
+    },
     render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsxs("div", { children: [_jsx("strong", { children: "Internal Link:" }), _jsx("br", {}), _jsx(Link, { href: "/docs/components", children: "Components (internal)" }), _jsx("p", { style: { fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }, children: "Opens in the same tab, no icon" })] }), _jsxs("div", { children: [_jsx("strong", { children: "External Link:" }), _jsx("br", {}), _jsx(Link, { href: "https://example.com", children: "Example.com (external)" }), _jsx("p", { style: { fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }, children: "Opens in new tab, includes external link icon" })] })] })); },
 };

package/dist/components/Popover.d.ts

@@ -0,0 +1,64 @@
+import { ReactNode } from "react";
+export interface GlossaryData {
+    /** The canonical term (used for semantic markup) */
+    term: string;
+    /** Display title shown in the popover header */
+    title: string;
+    /**
+     * Definition content. Accepts ReactNode so consumers can pre-render
+     * markdown (e.g. via react-markdown) or pass arbitrary JSX.
+     */
+    definition: ReactNode;
+}
+export interface PreviewData {
+    /** Page or article title */
+    title: string;
+    /** Short excerpt or summary */
+    excerpt?: ReactNode;
+    /** Optional featured image URL */
+    imageUrl?: string;
+    /** Optional URL to the full content */
+    href?: string;
+    /** Link text. Default: "Read more" */
+    linkText?: string;
+}
+export type PopoverPlacement = "auto" | "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end";
+export type PopoverSize = "sm" | "md" | "lg";
+export interface PopoverProps {
+    /**
+     * Arbitrary React content to render inside the popover.
+     * Use when built-in templates don't fit your use case.
+     */
+    content?: ReactNode;
+    /** Render a styled glossary definition popover */
+    glossary?: GlossaryData;
+    /** Render a styled content preview popover (Wikipedia-style) */
+    preview?: PreviewData;
+    /**
+     * Preferred placement relative to the trigger.
+     * "auto" detects available viewport space.
+     * @default "auto"
+     */
+    placement?: PopoverPlacement;
+    /**
+     * Popover width.
+     * sm = 240px, md = 320px, lg = 480px
+     * @default "md"
+     */
+    size?: PopoverSize;
+    /**
+     * Milliseconds to wait before showing the popover on hover.
+     * @default 200
+     */
+    showDelay?: number;
+    /**
+     * Milliseconds to wait before hiding the popover on hover-out.
+     * @default 150
+     */
+    hideDelay?: number;
+    /** The trigger element — the text or content that reveals the popover on hover/tap */
+    children: ReactNode;
+    /** Additional CSS classes on the trigger wrapper */
+    className?: string;
+}
+export declare function Popover({ content, glossary, preview, placement, size, showDelay, hideDelay, children, className, }: PopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Popover.js

@@ -0,0 +1,202 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef, useId, useCallback, useEffect, useState, } from "react";
+function GlossaryTemplate(_a) {
+    var data = _a.data;
+    return (_jsxs("div", { className: "dds-popover-glossary", children: [_jsx("span", { className: "dds-popover-eyebrow", children: "Glossary" }), _jsx("p", { className: "dds-popover-title", children: _jsx("dfn", { title: data.term, children: data.title }) }), _jsx("div", { className: "dds-popover-body", children: data.definition })] }));
+}
+function PreviewTemplate(_a) {
+    var _b;
+    var data = _a.data;
+    var _c = useState(false), imageError = _c[0], setImageError = _c[1];
+    return (_jsxs("div", { className: "dds-popover-preview", children: [data.imageUrl && !imageError && (_jsx("div", { className: "dds-popover-preview-image-wrap", children: _jsx("img", { className: "dds-popover-preview-image", src: data.imageUrl, alt: "", "aria-hidden": "true", onError: function () { return setImageError(true); } }) })), _jsxs("div", { className: "dds-popover-preview-body", children: [_jsx("p", { className: "dds-popover-title", children: data.title }), data.excerpt && (_jsx("div", { className: "dds-popover-body", children: data.excerpt })), data.href && (_jsxs("a", { className: "dds-popover-preview-link", href: data.href, target: "_blank", rel: "noopener noreferrer", children: [(_b = data.linkText) !== null && _b !== void 0 ? _b : "Read more", " \u2192"] }))] })] }));
+}
+/** Resolve the actual placement given preferred placement and available space */
+function resolvePlacement(triggerRect, preferred) {
+    if (preferred !== "auto")
+        return preferred;
+    var spaceAbove = triggerRect.top;
+    var spaceBelow = window.innerHeight - triggerRect.bottom;
+    // Prefer top if there's more space above (and at least 180px)
+    if (spaceAbove > spaceBelow && spaceAbove >= 180)
+        return "top";
+    return "bottom";
+}
+/** Compute pixel coordinates for the popover given trigger rect and placement */
+function computePosition(triggerRect, popoverEl, placement) {
+    var popoverWidth = popoverEl.offsetWidth;
+    var popoverHeight = popoverEl.offsetHeight;
+    var gap = 8; // px gap between trigger and popover
+    var viewportPad = 8; // min distance from viewport edges
+    var top = 0;
+    var left = 0;
+    var triggerCenterX = triggerRect.left + triggerRect.width / 2;
+    // Vertical
+    var isTop = placement.startsWith("top");
+    if (isTop) {
+        top = triggerRect.top - popoverHeight - gap;
+    }
+    else {
+        top = triggerRect.bottom + gap;
+    }
+    // Horizontal
+    if (placement.endsWith("-start")) {
+        left = triggerRect.left;
+    }
+    else if (placement.endsWith("-end")) {
+        left = triggerRect.right - popoverWidth;
+    }
+    else {
+        // center-aligned
+        left = triggerCenterX - popoverWidth / 2;
+    }
+    // Clamp to viewport horizontally
+    left = Math.max(viewportPad, Math.min(left, window.innerWidth - popoverWidth - viewportPad));
+    // Flip vertically if overflowing
+    if (isTop && top < viewportPad) {
+        top = triggerRect.bottom + gap;
+    }
+    else if (!isTop && top + popoverHeight > window.innerHeight - viewportPad) {
+        top = triggerRect.top - popoverHeight - gap;
+    }
+    return { top: top, left: left };
+}
+export function Popover(_a) {
+    var content = _a.content, glossary = _a.glossary, preview = _a.preview, _b = _a.placement, placement = _b === void 0 ? "auto" : _b, _c = _a.size, size = _c === void 0 ? "md" : _c, _d = _a.showDelay, showDelay = _d === void 0 ? 200 : _d, _e = _a.hideDelay, hideDelay = _e === void 0 ? 150 : _e, children = _a.children, _f = _a.className, className = _f === void 0 ? "" : _f;
+    var id = useId();
+    var popoverId = "dds-popover-".concat(id.replace(/:/g, ""));
+    var triggerRef = useRef(null);
+    var popoverRef = useRef(null);
+    var showTimerRef = useRef(null);
+    var hideTimerRef = useRef(null);
+    var clearTimers = useCallback(function () {
+        if (showTimerRef.current)
+            clearTimeout(showTimerRef.current);
+        if (hideTimerRef.current)
+            clearTimeout(hideTimerRef.current);
+    }, []);
+    var positionPopover = useCallback(function () {
+        var trigger = triggerRef.current;
+        var popover = popoverRef.current;
+        if (!trigger || !popover)
+            return;
+        // The Popover API renders in the top layer, outside the normal DOM tree,
+        // so it doesn't inherit class-based dark mode from ancestor elements.
+        // Mirror the theme onto the popover element itself.
+        var isDark = document.documentElement.classList.contains("dds-dark") ||
+            document.documentElement.dataset.ddsTheme === "dark" ||
+            document.body.classList.contains("dds-dark") ||
+            document.body.dataset.ddsTheme === "dark" ||
+            !!trigger.closest(".dds-dark, [data-dds-theme='dark']");
+        if (isDark) {
+            popover.setAttribute("data-dds-theme", "dark");
+        }
+        else {
+            popover.removeAttribute("data-dds-theme");
+        }
+        var triggerRect = trigger.getBoundingClientRect();
+        var resolved = resolvePlacement(triggerRect, placement);
+        var _a = computePosition(triggerRect, popover, resolved), top = _a.top, left = _a.left;
+        popover.style.top = "".concat(top, "px");
+        popover.style.left = "".concat(left, "px");
+        // Set placement data attribute for CSS arrow/animation direction
+        var baseDir = resolved.startsWith("top") ? "top" : "bottom";
+        popover.setAttribute("data-placement", baseDir);
+    }, [placement]);
+    var showPopover = useCallback(function () {
+        clearTimers();
+        showTimerRef.current = setTimeout(function () {
+            var popover = popoverRef.current;
+            if (!popover)
+                return;
+            // Position before showing so it doesn't flash in the wrong spot
+            popover.style.visibility = "hidden";
+            try {
+                popover.showPopover();
+            }
+            catch (_a) {
+                // Popover API not supported — fall back to display toggle
+                popover.style.display = "block";
+            }
+            positionPopover();
+            popover.style.visibility = "";
+        }, showDelay);
+    }, [clearTimers, showDelay, positionPopover]);
+    var hidePopover = useCallback(function () {
+        clearTimers();
+        hideTimerRef.current = setTimeout(function () {
+            var popover = popoverRef.current;
+            if (!popover)
+                return;
+            try {
+                popover.hidePopover();
+            }
+            catch (_a) {
+                popover.style.display = "none";
+            }
+        }, hideDelay);
+    }, [clearTimers, hideDelay]);
+    // Reposition on scroll/resize while open
+    useEffect(function () {
+        var handleReposition = function () {
+            var popover = popoverRef.current;
+            if (!popover)
+                return;
+            // Only reposition if visible (Popover API or display fallback)
+            if (popover.matches(":popover-open") ||
+                popover.style.display === "block") {
+                positionPopover();
+            }
+        };
+        window.addEventListener("scroll", handleReposition, { passive: true });
+        window.addEventListener("resize", handleReposition, { passive: true });
+        return function () {
+            window.removeEventListener("scroll", handleReposition);
+            window.removeEventListener("resize", handleReposition);
+        };
+    }, [positionPopover]);
+    // Cleanup timers on unmount
+    useEffect(function () { return function () { return clearTimers(); }; }, [clearTimers]);
+    var triggerClasses = ["dds-popover-trigger", className]
+        .filter(Boolean)
+        .join(" ");
+    var popoverClasses = [
+        "dds-popover",
+        "dds-popover-".concat(size),
+    ]
+        .filter(Boolean)
+        .join(" ");
+    // Resolve which content to render
+    var popoverContent = content !== null && content !== void 0 ? content : (glossary ? (_jsx(GlossaryTemplate, { data: glossary })) : preview ? (_jsx(PreviewTemplate, { data: preview })) : null);
+    if (!popoverContent)
+        return _jsx(_Fragment, { children: children });
+    return (_jsxs(_Fragment, { children: [_jsx("span", { ref: triggerRef, className: triggerClasses, onMouseEnter: showPopover, onMouseLeave: hidePopover, onFocus: showPopover, onBlur: hidePopover, 
+                // Touch: toggle on tap (clear any pending hover timers first)
+                onClick: function () {
+                    clearTimers();
+                    var popover = popoverRef.current;
+                    if (!popover)
+                        return;
+                    try {
+                        popover.togglePopover();
+                        if (popover.matches(":popover-open"))
+                            positionPopover();
+                    }
+                    catch (_a) {
+                        var isVisible = popover.style.display === "block";
+                        popover.style.display = isVisible ? "none" : "block";
+                        if (!isVisible)
+                            positionPopover();
+                    }
+                }, "aria-describedby": popoverId, tabIndex: 0, children: children }), _jsx("div", __assign({ ref: popoverRef, id: popoverId }, { popover: "auto" }, { className: popoverClasses, onMouseEnter: clearTimers, onMouseLeave: hidePopover, children: popoverContent }))] }));
+}

package/dist/components/Popover.stories.d.ts

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Popover } from "./Popover";
+declare const meta: Meta<typeof Popover>;
+export default meta;
+type Story = StoryObj<typeof Popover>;
+/**
+ * The glossary template renders a structured definition popover.
+ * The `definition` field accepts `ReactNode` — pre-render any markdown
+ * using your preferred renderer before passing it in.
+ */
+export declare const GlossaryDefinition: Story;
+/**
+ * The preview template renders a Wikipedia-style content preview with an
+ * optional featured image, excerpt, and "Read more" link.
+ */
+export declare const ContentPreview: Story;
+/**
+ * Pass any React element as the `content` prop when the built-in templates
+ * don't fit your use case.
+ */
+export declare const CustomContent: Story;
+/**
+ * Size variants — sm (240px), md (320px), lg (480px).
+ */
+export declare const Sizes: Story;
+/**
+ * Placement variants control which side of the trigger the popover appears on.
+ * "auto" (default) detects available viewport space.
+ */
+export declare const Placement: Story;
+/**
+ * Multiple popovers in a paragraph — only one can be open at a time
+ * (native Popover API `popover="auto"` behaviour).
+ */
+export declare const InlineParagraph: Story;