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

package/USAGE.md

@@ -529,10 +529,20 @@ import { List } from "@roadlittledawn/docs-design-system-react";
 
 ### List.Item Props
 
-| Prop        | Type        | Default | Description            |
-| ----------- | ----------- | ------- | ---------------------- |
-| `children`  | `ReactNode` | —       | List item content      |
-| `className` | `string`    | `""`    | Additional CSS classes |
+| Prop         | Type        | Default | Description                                                                 |
+| ------------ | ----------- | ------- | --------------------------------------------------------------------------- |
+| `children`   | `ReactNode` | —       | List item content                                                           |
+| `className`  | `string`    | `""`    | Additional CSS classes                                                      |
+| `bulletIcon` | `ReactNode` | —       | Custom bullet icon for this item. Overrides the parent `List`'s `bulletIcon` |
+
+### CSS classes
+
+| Class | Element | Notes |
+| ----- | ------- | ----- |
+| `dds-list` | `<ol>` / `<ul>` | Root list element |
+| `dds-list-item` | `<li>` | Each list item |
+| `dds-list-item-content` | `<div>` | Wraps item children; target for content-level overrides |
+| `dds-list-item-icon` | `<span>` | Wrapper for custom `bulletIcon` SVG/node |
 
 ### Examples
 
@@ -1025,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/List.d.ts

@@ -16,7 +16,7 @@ export interface ListItemProps {
     children: ReactNode;
     /** Additional CSS classes */
     className?: string;
-    /** Internal: bullet icon injected by List parent for unordered lists */
+    /** Custom bullet icon (React node, e.g., SVG) for this item. Overrides the parent List's bulletIcon */
     bulletIcon?: ReactNode;
 }
 export declare function ListItem({ children, className, bulletIcon }: ListItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/List.js

@@ -15,12 +15,16 @@ function ListImpl(_a) {
     var children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b, _c = _a.ordered, ordered = _c === void 0 ? true : _c, bullet = _a.bullet, bulletIcon = _a.bulletIcon;
     var listClasses = ["dds-list", className].filter(Boolean).join(" ");
     var Element = ordered ? "ol" : "ul";
-    return (_jsx(Element, { className: listClasses, "data-ordered": ordered, "data-has-icon": !!bulletIcon && !ordered, style: bullet && !bulletIcon
+    return (_jsx(Element, { className: listClasses, "data-ordered": ordered, style: bullet && !bulletIcon
             ? { "--dds-list-bullet": JSON.stringify(bullet) }
             : undefined, children: bulletIcon && !ordered
             ? React.Children.map(children, function (child) {
+                var _a;
                 if (React.isValidElement(child) && child.type === ListItem) {
-                    return React.cloneElement(child, __assign(__assign({}, child.props), { bulletIcon: bulletIcon }));
+                    var childProps = child.props;
+                    return React.cloneElement(child, __assign(__assign({}, childProps), { 
+                        // Child's own bulletIcon takes precedence over the parent's
+                        bulletIcon: (_a = childProps.bulletIcon) !== null && _a !== void 0 ? _a : bulletIcon }));
                 }
                 return child;
             })
@@ -29,7 +33,7 @@ function ListImpl(_a) {
 export function ListItem(_a) {
     var children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b, bulletIcon = _a.bulletIcon;
     var itemClasses = ["dds-list-item", className].filter(Boolean).join(" ");
-    return (_jsxs("li", { className: itemClasses, children: [bulletIcon && (_jsx("span", { className: "dds-list-item-icon", "aria-hidden": "true", children: bulletIcon })), children] }));
+    return (_jsxs("li", { className: itemClasses, "data-has-icon": bulletIcon ? "true" : undefined, children: [bulletIcon && (_jsx("span", { className: "dds-list-item-icon", "aria-hidden": "true", children: bulletIcon })), _jsx("div", { className: "dds-list-item-content", children: children })] }));
 }
 export var List = Object.assign(ListImpl, {
     Item: ListItem,

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

@@ -1745,7 +1745,9 @@ a.no-text-decoration {
 .dds-list-item {
   counter-increment: list-counter;
   position: relative;
-  padding-inline-start: calc(var(--dds-list-badge-size) + 1rem);
+  display: flex;
+  align-items: flex-start;
+  gap: 1rem;
   margin-bottom: var(--dds-list-item-margin-bottom, 1.5rem);
   min-height: var(--dds-list-badge-size);
 }
@@ -1767,13 +1769,10 @@ a.no-text-decoration {
 /* Ordered list badges */
 .dds-list[data-ordered="true"] .dds-list-item::before {
   content: counter(list-counter);
-  position: absolute;
-  left: 0;
-  top: 0;
+  flex-shrink: 0;
   width: var(--dds-list-badge-size, 2.5rem);
   height: var(--dds-list-badge-size, 2.5rem);
   line-height: var(--dds-line-height-relaxed);
-  inset-inline-start: 0;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -1787,27 +1786,24 @@ a.no-text-decoration {
 /* Unordered list bullets */
 .dds-list[data-ordered="false"] .dds-list-item::before {
   content: var(--dds-list-bullet, "•");
-  position: absolute;
-  left: 0;
-  top: 0;
+  flex-shrink: 0;
   width: var(--dds-list-badge-size, 2.5rem);
   height: var(--dds-list-badge-size, 2.5rem);
-  inset-inline-start: 0;
   display: flex;
+  transform: translateY(var(--dds-list-bullet-offset, -0.1em));
   align-items: center;
   justify-content: center;
-  font-size: var(--dds-list-bullet-size, 1.5rem);
+  font-size: var(--dds-list-bullet-size, 1.25rem);
   color: var(--dds-list-badge-text);
 }
-/* Hide ::before when using custom icon */
-.dds-list[data-has-icon="true"] .dds-list-item::before {
+/* Hide ::before when item has a custom icon.
+   Specificity matches the show rules above (0-3-1) and comes after, so it wins. */
+.dds-list .dds-list-item[data-has-icon="true"]::before {
   display: none;
 }
 /* Custom icon bullet */
 .dds-list-item-icon {
-  position: absolute;
-  left: 0;
-  top: 0;
+  flex-shrink: 0;
   width: var(--dds-list-badge-size, 2.5rem);
   height: var(--dds-list-badge-size, 2.5rem);
   display: flex;
@@ -1819,6 +1815,27 @@ a.no-text-decoration {
   width: 1.25rem;
   height: 1.25rem;
 }
+/* Content wrapper — flex child that fills remaining space */
+.dds-list-item-content {
+  flex: 1;
+  min-width: 0;
+}
+/* Neutralize consuming-site typography margins that would misalign the badge.
+   The list item's own margin/padding controls spacing — not the children's. */
+.dds-list-item-content > :first-child {
+  margin-top: 0;
+}
+.dds-list-item-content > :last-child {
+  margin-bottom: 0;
+}
+/* For unordered lists, vertically center the content within the li so the first
+   text line's center aligns with the bullet/icon center.
+   margin-block: auto distributes remaining space evenly above and below the
+   content span, so its midpoint always lands at badge-size/2 — the same as the
+   bullet center — regardless of font-size or line-height. */
+.dds-list[data-ordered="false"] .dds-list-item-content {
+  margin-block: auto;
+}
 /* ==========================================================================
    Popover Component
    Uses the native Popover API for top-layer rendering.
@@ -1827,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;
@@ -1923,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
    ========================================================================== */
@@ -1934,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;
@@ -1941,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.1",
+  "version": "0.12.3",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {