@roadlittledawn/docs-design-system-react 0.12.2 → 0.12.3

package/USAGE.md

@@ -1035,7 +1035,15 @@ A hover/tap-activated floating panel for enriching inline documentation content.
 
 ### Mobile behavior
 
-On screens ≤ 640px, the popover renders as a **bottom sheet** instead of a floating panel. Hover doesn't apply on touch devices; the popover toggles on tap.
+On screens ≤ 640px, the popover renders as a **bottom sheet** instead of a floating panel. Hover doesn't apply on touch devices; the popover opens on tap.
+
+### Closing the popover
+
+The popover can be closed in three ways:
+
+- **Close button** — the × button in the upper-right corner of the panel
+- **Click / tap outside** — native light-dismiss provided by `popover="auto"`
+- **Escape key** — handled automatically by the Popover API
 
 ### Content modes (choose one)
 

package/dist/components/Popover.js

@@ -80,6 +80,14 @@ export function Popover(_a) {
     var popoverRef = useRef(null);
     var showTimerRef = useRef(null);
     var hideTimerRef = useRef(null);
+    // Tracks when the popover was last shown automatically (hover/focus).
+    // Used to prevent the click handler from immediately closing a popover that
+    // was just opened by the hover timer (fixes the first-tap flicker on touch).
+    // On touch devices the synthetic `click` arrives ~300 ms after touch-start;
+    // the guard window must exceed showDelay (200 ms default) + that browser
+    // delay, so 400 ms is a safe minimum.
+    var FLICKER_GUARD_MS = 400;
+    var lastAutoShowTimeRef = useRef(0);
     var clearTimers = useCallback(function () {
         if (showTimerRef.current)
             clearTimeout(showTimerRef.current);
@@ -131,6 +139,8 @@ export function Popover(_a) {
             }
             positionPopover();
             popover.style.visibility = "";
+            // Record the time so the click handler knows the popover was auto-shown
+            lastAutoShowTimeRef.current = Date.now();
         }, showDelay);
     }, [clearTimers, showDelay, positionPopover]);
     var hidePopover = useCallback(function () {
@@ -188,6 +198,15 @@ export function Popover(_a) {
                     var popover = popoverRef.current;
                     if (!popover)
                         return;
+                    var isOpen = popover.matches(":popover-open") ||
+                        popover.style.display === "block";
+                    // Flicker guard: if the popover was just shown automatically by the
+                    // hover/focus timer within the last 400 ms, a tap's synthetic click
+                    // would arrive and toggle it closed. Instead, keep it open so the
+                    // first tap reliably shows the popover.
+                    if (isOpen && Date.now() - lastAutoShowTimeRef.current < FLICKER_GUARD_MS) {
+                        return;
+                    }
                     try {
                         popover.togglePopover();
                         if (popover.matches(":popover-open"))
@@ -199,5 +218,17 @@ export function Popover(_a) {
                         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 }))] }));
+                }, "aria-describedby": popoverId, tabIndex: 0, children: children }), _jsxs("div", __assign({ ref: popoverRef, id: popoverId }, { popover: "auto" }, { className: popoverClasses, onMouseEnter: clearTimers, onMouseLeave: hidePopover, children: [_jsx("button", { className: "dds-popover-close", "aria-label": "Close", onClick: function (e) {
+                            e.stopPropagation();
+                            clearTimers();
+                            var popover = popoverRef.current;
+                            if (!popover)
+                                return;
+                            try {
+                                popover.hidePopover();
+                            }
+                            catch (_a) {
+                                popover.style.display = "none";
+                            }
+                        }, children: "\u00D7" }), popoverContent] }))] }));
 }

package/dist/components/Popover.stories.js

@@ -64,7 +64,7 @@ var meta = {
         layout: "centered",
         docs: {
             description: {
-                component: "\nA hover/tap-activated popover for enriching inline content in documentation.\nBuilt on the native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) for reliable top-layer rendering \u2014 no z-index wars, no overflow clipping.\n\nCommon use cases include glossary term definitions and Wikipedia-style content previews.\n\n## Content modes\n\nThe `Popover` supports three mutually exclusive content modes, checked in this order:\n\n1. **`content`** \u2014 arbitrary `ReactNode`; you control everything\n2. **`glossary`** \u2014 structured `{ term, title, definition }` template\n3. **`preview`** \u2014 structured `{ title, excerpt, imageUrl, href }` template\n\n## When to Use\n\n- Inline term definitions that would interrupt reading flow if expanded in-place\n- Link previews that let users get context without navigating away\n- Any contextual content that benefits from being on-demand rather than always visible\n\n## When Not to Use\n\n- For critical information users must read \u2014 use a `Callout` instead\n- As a primary navigation mechanism\n- For content that needs persistent visibility\n\n## Mobile behavior\n\nOn screens \u2264 640 px the popover renders as a bottom sheet instead of a floating panel.\nHover events don't apply; the popover toggles on tap.\n\n## Accessibility\n\n- Trigger has `tabIndex={0}` and shows the popover on focus (keyboard accessible)\n- Popover panel has `role=\"tooltip\"` and is linked via `aria-describedby`\n- The native Popover API handles Escape-key dismissal automatically\n- Light-dismiss (click outside) is provided by `popover=\"auto\"`\n        ",
+                component: "\nA hover/tap-activated popover for enriching inline content in documentation.\nBuilt on the native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) for reliable top-layer rendering \u2014 no z-index wars, no overflow clipping.\n\nCommon use cases include glossary term definitions and Wikipedia-style content previews.\n\n## Content modes\n\nThe `Popover` supports three mutually exclusive content modes, checked in this order:\n\n1. **`content`** \u2014 arbitrary `ReactNode`; you control everything\n2. **`glossary`** \u2014 structured `{ term, title, definition }` template\n3. **`preview`** \u2014 structured `{ title, excerpt, imageUrl, href }` template\n\n## When to Use\n\n- Inline term definitions that would interrupt reading flow if expanded in-place\n- Link previews that let users get context without navigating away\n- Any contextual content that benefits from being on-demand rather than always visible\n\n## When Not to Use\n\n- For critical information users must read \u2014 use a `Callout` instead\n- As a primary navigation mechanism\n- For content that needs persistent visibility\n\n## Mobile behavior\n\nOn screens \u2264 640 px the popover renders as a bottom sheet instead of a floating panel.\nHover events don't apply; the popover opens on tap.\n\n## Closing the popover\n\nThe popover can be closed in three ways:\n- **Close button** \u2014 the \u00D7 button in the upper-right corner of the panel\n- **Click / tap outside** \u2014 native light-dismiss provided by `popover=\"auto\"`\n- **Escape key** \u2014 handled automatically by the Popover API\n\n## Accessibility\n\n- Trigger has `tabIndex={0}` and shows the popover on focus (keyboard accessible)\n- Popover panel has `role=\"tooltip\"` and is linked via `aria-describedby`\n- The native Popover API handles Escape-key dismissal automatically\n- Light-dismiss (click outside) is provided by `popover=\"auto\"`\n        ",
             },
         },
     },

package/dist/styles.css

@@ -1844,7 +1844,7 @@ a.no-text-decoration {
 /* Trigger */
 .dds-popover-trigger {
   display: inline;
-  cursor: default;
+  cursor: help;
   text-decoration-line: underline;
   text-decoration-style: dotted;
   text-decoration-color: currentColor;
@@ -1940,6 +1940,38 @@ a.no-text-decoration {
 .dds-popover-lg {
   width: var(--dds-popover-width-lg);
 }
+/* ==========================================================================
+   Close button — sits in the upper-right corner of the popover panel
+   ========================================================================== */
+.dds-popover-close {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  color: var(--dds-popover-eyebrow-color);
+  font-size: 1.125rem;
+  line-height: 1;
+  transition:
+    background 120ms,
+    color 120ms;
+}
+.dds-popover-close:hover {
+  background: var(--dds-popover-border);
+  color: var(--dds-popover-text);
+}
+.dds-popover-close:focus-visible {
+  outline: 2px solid var(--dds-link-color);
+  outline-offset: 2px;
+}
 /* ==========================================================================
    Shared inner elements
    ========================================================================== */
@@ -1951,6 +1983,7 @@ a.no-text-decoration {
   text-transform: uppercase;
   color: var(--dds-popover-eyebrow-color);
   margin-bottom: 0.25rem;
+  padding-right: 1.75rem; /* leave room for the close button */
 }
 .dds-popover-title {
   margin: 0 0 0.5rem;
@@ -1958,6 +1991,7 @@ a.no-text-decoration {
   font-weight: var(--dds-font-semibold);
   color: var(--dds-popover-title-color);
   line-height: var(--dds-line-height-tight);
+  padding-right: 1.75rem; /* leave room for the close button */
 }
 .dds-popover-title dfn {
   font-style: normal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {