@underverse-ui/underverse 1.0.32 → 1.0.34

package/AGENTS.md

@@ -51,13 +51,23 @@ import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
 export function App() {
   return (
     <>
-      <OverlayScrollbarProvider />
+      <OverlayScrollbarProvider
+        enabled
+        theme="os-theme-underverse"
+        autoHide="leave"
+      />
       {/* app */}
     </>
   );
 }
 ```
 
+Behavior:
+
+- Provider initializes globally by default on common scroll selectors (`.overflow-*`, `textarea`) and `[data-os-scrollbar]`.
+- Provider can run globally via custom `selector` (for example: `.overflow-auto, .overflow-y-auto, .overflow-x-auto, [data-os-scrollbar]`).
+- Use `data-os-ignore` on a node to opt out.
+
 ## i18n Notes
 
 - Components work without `next-intl` using fallback translations.

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `@underverse-ui/underverse` are documented in this file.
+
+## [1.0.32] - 2026-02-24
+
+### Changed
+
+- Standardized OverlayScrollbars initialization to explicit marker targeting only:
+  - Provider now initializes only on `[data-os-scrollbar]`.
+  - Removed generic overflow class scanning (`.overflow-*`).
+- Hardened provider behavior for production:
+  - No initialization on `document.body` / `document.documentElement`.
+  - Excludes portal / modal / toast trees:
+    - `[data-radix-portal]`
+    - `[role="dialog"]`
+    - `[aria-modal="true"]`
+    - `[data-sonner-toaster]`
+  - Supports node-level opt-out with `data-os-ignore`.
+- Added provider configuration props:
+  - `enabled` (default `true`)
+  - `theme` (default `os-theme-underverse`)
+  - `visibility`
+  - `autoHide`
+  - `autoHideDelay`
+  - `dragScroll`
+  - `clickScroll`
+  - `selector` (default `.overflow-auto, .overflow-y-auto, .overflow-x-auto, .overflow-scroll, .overflow-y-scroll, .overflow-x-scroll, textarea, [data-os-scrollbar]`)
+  - `exclude` (default `html, body, [data-os-ignore], [data-radix-portal], [role='dialog'], [aria-modal='true'], [data-sonner-toaster]`)
+- Exported provider prop type:
+  - `OverlayScrollbarProviderProps`
+
+### Updated Components
+
+- Provider now covers common scrollable surfaces by default via global selector, so Underverse components do not require per-component manual marker wiring.
+
+### Internal
+
+- `Popover` now sets `role="dialog"` only when `modal=true`, avoiding accidental exclusion for non-modal popovers.
+- Moved to default global selector behavior, so apps no longer need to add `data-os-scrollbar` manually to each Underverse component.
+
+### Testing
+
+- Added controller-level tests for:
+  - selector initialization
+  - exclude behavior
+  - dynamic add/remove cleanup
+  - portal safety with wide selectors
+  - destroy cleanup (memory leak prevention)
+
+### Migration
+
+- Mount a single `OverlayScrollbarProvider` from the package at app root.
+- Remove app-local DOM-scanning scrollbar providers.
+- Keep `overlayscrollbars/overlayscrollbars.css` imported globally.
+- Default is already global selector mode. Override `selector` only if you need custom scope.
+- For app-specific opt-out nodes, use `data-os-ignore`.

package/README.md

@@ -138,6 +138,7 @@ import { Form, FormField, FormItem, FormLabel, FormMessage } from "@underverse-u
 ### Overlay Scrollbars (Optional, Recommended)
 
 Use `OverlayScrollbarProvider` to get overlay scrollbars (no layout space taken) across your app and Underverse components.
+See release notes in `CHANGELOG.md` for migration details by version.
 
 ```tsx
 import "overlayscrollbars/overlayscrollbars.css";
@@ -146,13 +147,52 @@ import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
 function App() {
   return (
     <>
-      <OverlayScrollbarProvider />
+      <OverlayScrollbarProvider
+        enabled
+        theme="os-theme-underverse"
+        autoHide="leave"
+        autoHideDelay={600}
+      />
       {/* your app */}
     </>
   );
 }
 ```
 
+Provider behavior:
+
+- Initializes globally by default on common scroll containers (`.overflow-*`, `textarea`) and `[data-os-scrollbar]`.
+- Does **not** initialize on `document.body` / `document.documentElement`.
+- Skips portal/dialog trees (`[data-radix-portal]`, `[role="dialog"]`, `[aria-modal="true"]`, `[data-sonner-toaster]`).
+- Per-node opt-out is available via `data-os-ignore`.
+
+Provider props:
+
+- `enabled?: boolean`
+- `theme?: string`
+- `visibility?: "visible" | "hidden" | "auto"`
+- `autoHide?: "never" | "scroll" | "leave" | "move"`
+- `autoHideDelay?: number`
+- `dragScroll?: boolean`
+- `clickScroll?: boolean`
+- `selector?: string` default: `.overflow-auto, .overflow-y-auto, .overflow-x-auto, .overflow-scroll, .overflow-y-scroll, .overflow-x-scroll, textarea, [data-os-scrollbar]`
+- `exclude?: string` default: `html, body, [data-os-ignore], [data-radix-portal], [role='dialog'], [aria-modal='true'], [data-sonner-toaster]`
+
+Custom selector mode example:
+
+```tsx
+<OverlayScrollbarProvider
+  selector=".overflow-auto, .overflow-y-auto, .overflow-x-auto, [data-os-scrollbar]"
+/>
+```
+
+Migration notes:
+
+- Remove any local DOM-scanning scrollbar provider in your app.
+- Keep a single `OverlayScrollbarProvider` mounted once at app root.
+- You no longer need to add `data-os-scrollbar` to every Underverse component manually.
+- Use `data-os-scrollbar` only for custom scroll nodes that are not covered by your selector.
+
 ### Standalone React (Vite, CRA, etc.)
 
 ```tsx

package/agent-recipes.json

@@ -26,7 +26,12 @@
     {
       "id": "overlay-scrollbar-provider",
       "title": "Enable overlay scrollbars",
-      "code": "import \"overlayscrollbars/overlayscrollbars.css\";\nimport { OverlayScrollbarProvider } from \"@underverse-ui/underverse\";\n\nexport function App(){\n  return <><OverlayScrollbarProvider />{/* app */}</>;\n}\n"
+      "code": "import \"overlayscrollbars/overlayscrollbars.css\";\nimport { OverlayScrollbarProvider } from \"@underverse-ui/underverse\";\n\nexport function App(){\n  return <><OverlayScrollbarProvider enabled theme=\"os-theme-underverse\" autoHide=\"leave\" />{/* app */}</>;\n}\n"
+    },
+    {
+      "id": "overlay-scrollbar-global-selector",
+      "title": "Enable global selector mode",
+      "code": "import \"overlayscrollbars/overlayscrollbars.css\";\nimport { OverlayScrollbarProvider } from \"@underverse-ui/underverse\";\n\nexport function App(){\n  return <><OverlayScrollbarProvider selector=\".overflow-auto, .overflow-y-auto, .overflow-x-auto, [data-os-scrollbar]\" />{/* app */}</>;\n}\n"
     },
     {
       "id": "api-discovery-order",
@@ -39,4 +44,3 @@
     }
   ]
 }
-

package/api-reference.json

@@ -1,8 +1,8 @@
 {
   "package": "@underverse-ui/underverse",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "sourceEntry": "src/index.ts",
-  "totalExports": 206,
+  "totalExports": 207,
   "exports": [
     {
       "name": "*",
@@ -862,6 +862,13 @@
       "local": false,
       "aliasOf": "default"
     },
+    {
+      "name": "OverlayScrollbarProviderProps",
+      "kind": "type",
+      "source": "../../../components/ui/OverlayScrollbarProvider",
+      "reexport": true,
+      "local": false
+    },
     {
       "name": "PageLoading",
       "kind": "value",

package/dist/index.cjs

@@ -3820,6 +3820,8 @@ var Popover = ({
   children,
   className,
   contentClassName,
+  contentProps,
+  contentScrollable = false,
   placement = "bottom",
   modal = false,
   disabled = false,
@@ -3991,7 +3993,7 @@ var Popover = ({
           {
             ref: panelRef,
             "data-state": "open",
-            role: "dialog",
+            role: modal ? "dialog" : void 0,
             "aria-modal": modal || void 0,
             style: {
               transformOrigin: getTransformOrigin2(initialPlacement.side, initialPlacement.align)
@@ -4004,12 +4006,14 @@ var Popover = ({
             children: /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
               "div",
               {
+                ...contentProps,
                 className: cn(
                   "rounded-2xl md:rounded-3xl border bg-popover text-popover-foreground shadow-md",
                   "backdrop-blur-sm bg-popover/95 border-border/60 p-4",
+                  contentProps?.className,
                   contentClassName
                 ),
-                tabIndex: -1,
+                tabIndex: contentProps?.tabIndex ?? -1,
                 children
               }
             )
@@ -5828,7 +5832,7 @@ var ScrollArea = (0, import_react14.forwardRef)(
           className
         ),
         ...props,
-        children: /* @__PURE__ */ (0, import_jsx_runtime28.jsx)("div", { className: cn("h-full w-full overflow-y-auto scroll-area-viewport custom-scrollbar", contentClassName), "data-os-scrollbar": true, children })
+        children: /* @__PURE__ */ (0, import_jsx_runtime28.jsx)("div", { className: cn("h-full w-full overflow-y-auto scroll-area-viewport custom-scrollbar", contentClassName), children })
       }
     );
   }
@@ -11903,7 +11907,6 @@ function CalendarTimeline({
             {
               ref: bodyRef,
               className: "relative flex-1 overflow-auto custom-scrollbar",
-              "data-os-scrollbar": true,
               onPointerMove,
               onPointerUp,
               onPointerLeave: () => setHoverCell(null),
@@ -14122,7 +14125,6 @@ function CategoryTreeSelect(props) {
             "p-2",
             "animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-300"
           ),
-          "data-os-scrollbar": true,
           children: [
             renderSearch(),
             renderTreeContent()
@@ -19018,81 +19020,161 @@ var LoadingBar = ({
 // ../../components/ui/OverlayScrollbarProvider.tsx
 var import_react33 = require("react");
 var import_overlayscrollbars = require("overlayscrollbars");
-var EXPLICIT_SELECTOR = [".thin-scrollbar", ".scrollbar-thin", ".custom-scrollbar", "[data-os-scrollbar]"].join(", ");
-var PORTAL_EXCLUDE_SELECTOR = [
+
+// ../../components/ui/overlay-scrollbar-controller.ts
+var DEFAULT_OVERLAY_SCROLLBAR_SELECTOR = [
+  ".overflow-auto",
+  ".overflow-y-auto",
+  ".overflow-x-auto",
+  ".overflow-scroll",
+  ".overflow-y-scroll",
+  ".overflow-x-scroll",
+  "textarea",
+  "[data-os-scrollbar]"
+].join(", ");
+var DEFAULT_OVERLAY_SCROLLBAR_EXCLUDE = [
+  "html",
+  "body",
+  "[data-os-ignore]",
   "[data-radix-portal]",
   "[role='dialog']",
   "[aria-modal='true']",
   "[data-sonner-toaster]"
 ].join(", ");
-var OPTIONS = {
-  scrollbars: {
-    theme: "os-theme-underverse",
-    visibility: "auto",
-    autoHide: "leave",
-    autoHideDelay: 600,
-    dragScroll: true,
-    clickScroll: false
+function splitSelectorList(selectorList) {
+  return selectorList.split(",").map((part) => part.trim()).filter(Boolean);
+}
+function safeMatches(element, selector) {
+  try {
+    return element.matches(selector);
+  } catch {
+    return false;
   }
-};
-function shouldSkip(element) {
-  if (element === document.body || element === document.documentElement) return true;
-  if (element.hasAttribute("data-os-ignore")) return true;
+}
+function safeClosest(element, selector) {
+  try {
+    return element.closest(selector);
+  } catch {
+    return null;
+  }
+}
+function shouldSkipElement(element, excludeSelectors, ancestorExcludeSelectors) {
+  const tagName = element.tagName?.toLowerCase?.() ?? "";
+  if (tagName === "body" || tagName === "html") return true;
+  if (element.classList.contains("scrollbar-none")) return true;
   if (element.hasAttribute("data-overlayscrollbars")) return true;
-  if (element.closest(PORTAL_EXCLUDE_SELECTOR)) return true;
+  if (excludeSelectors.some((selector) => safeMatches(element, selector))) return true;
+  if (ancestorExcludeSelectors.some((selector) => safeClosest(element, selector))) return true;
   return false;
 }
-function OverlayScrollbarProvider() {
-  (0, import_react33.useEffect)(() => {
-    const instances = /* @__PURE__ */ new Map();
-    let rafId = 0;
-    const init = (element) => {
-      if (shouldSkip(element)) return;
-      if (instances.has(element)) return;
-      instances.set(element, (0, import_overlayscrollbars.OverlayScrollbars)(element, OPTIONS));
-    };
-    const scan = (root) => {
-      if (root instanceof HTMLElement && root.matches(EXPLICIT_SELECTOR)) {
-        init(root);
+function createOverlayScrollbarController({
+  selector,
+  exclude,
+  options,
+  createInstance,
+  root = document.body,
+  createObserver,
+  requestAnimationFrameImpl = requestAnimationFrame,
+  cancelAnimationFrameImpl = cancelAnimationFrame
+}) {
+  const instances = /* @__PURE__ */ new Map();
+  const excludeSelectors = splitSelectorList(exclude);
+  const ancestorExcludeSelectors = excludeSelectors.filter((item) => item !== "html" && item !== "body");
+  let rafId = 0;
+  const init = (element) => {
+    if (shouldSkipElement(element, excludeSelectors, ancestorExcludeSelectors)) return;
+    if (instances.has(element)) return;
+    instances.set(element, createInstance(element, options));
+  };
+  const scan = (root2) => {
+    if (root2 instanceof HTMLElement && safeMatches(root2, selector)) {
+      init(root2);
+    }
+    if (!("querySelectorAll" in root2)) return;
+    try {
+      root2.querySelectorAll(selector).forEach(init);
+    } catch {
+    }
+  };
+  const cleanup = () => {
+    instances.forEach((instance, element) => {
+      if (!element.isConnected) {
+        instance.destroy();
+        instances.delete(element);
       }
-      root.querySelectorAll(EXPLICIT_SELECTOR).forEach(init);
-    };
-    const cleanup = () => {
-      instances.forEach((instance, element) => {
-        if (!element.isConnected) {
-          instance.destroy();
-          instances.delete(element);
+    });
+  };
+  scan(root);
+  const onMutations = (mutations) => {
+    if (rafId) return;
+    rafId = requestAnimationFrameImpl(() => {
+      rafId = 0;
+      const roots = /* @__PURE__ */ new Set();
+      mutations.forEach((mutation) => {
+        if (mutation.target && (typeof mutation.target.querySelectorAll === "function" || mutation.target instanceof HTMLElement)) {
+          roots.add(mutation.target);
         }
-      });
-    };
-    scan(document.body);
-    const observer = new MutationObserver((mutations) => {
-      if (rafId) return;
-      rafId = requestAnimationFrame(() => {
-        rafId = 0;
-        const scanRoots = /* @__PURE__ */ new Set();
-        mutations.forEach((mutation) => {
-          if (mutation.target instanceof HTMLElement || mutation.target instanceof Document || mutation.target instanceof DocumentFragment) {
-            scanRoots.add(mutation.target);
+        Array.from(mutation.addedNodes).forEach((node) => {
+          if (node instanceof HTMLElement) {
+            roots.add(node);
           }
-          mutation.addedNodes.forEach((node) => {
-            if (node instanceof HTMLElement) {
-              scanRoots.add(node);
-            }
-          });
         });
-        scanRoots.forEach(scan);
-        cleanup();
       });
+      roots.forEach(scan);
+      cleanup();
+    });
+  };
+  const observer = createObserver ? createObserver(onMutations) : new MutationObserver(onMutations);
+  observer.observe(root, { childList: true, subtree: true, attributes: true });
+  const destroy = () => {
+    if (rafId) cancelAnimationFrameImpl(rafId);
+    observer.disconnect();
+    instances.forEach((instance) => instance.destroy());
+    instances.clear();
+  };
+  return {
+    destroy,
+    scan,
+    cleanup,
+    getInstanceCount: () => instances.size
+  };
+}
+
+// ../../components/ui/OverlayScrollbarProvider.tsx
+function OverlayScrollbarProvider({
+  enabled = true,
+  theme = "os-theme-underverse",
+  visibility = "auto",
+  autoHide = "leave",
+  autoHideDelay = 600,
+  dragScroll = true,
+  clickScroll = false,
+  selector = DEFAULT_OVERLAY_SCROLLBAR_SELECTOR,
+  exclude = DEFAULT_OVERLAY_SCROLLBAR_EXCLUDE
+} = {}) {
+  (0, import_react33.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    if (!enabled) return;
+    const options = {
+      scrollbars: {
+        theme,
+        visibility,
+        autoHide,
+        autoHideDelay,
+        dragScroll,
+        clickScroll
+      }
+    };
+    const controller = createOverlayScrollbarController({
+      selector,
+      exclude,
+      options,
+      createInstance: (element, instanceOptions) => (0, import_overlayscrollbars.OverlayScrollbars)(element, instanceOptions)
     });
-    observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["class"] });
     return () => {
-      if (rafId) cancelAnimationFrame(rafId);
-      observer.disconnect();
-      instances.forEach((instance) => instance.destroy());
-      instances.clear();
+      controller.destroy();
     };
-  }, []);
+  }, [enabled, theme, visibility, autoHide, autoHideDelay, dragScroll, clickScroll, selector, exclude]);
   return null;
 }
 var OverlayScrollbarProvider_default = OverlayScrollbarProvider;
@@ -19114,7 +19196,6 @@ var Table = import_react34.default.forwardRef(({ className, containerClassName,
         "backdrop-blur-sm transition-all duration-300",
         containerClassName
       ),
-      "data-os-scrollbar": true,
       children: /* @__PURE__ */ (0, import_jsx_runtime65.jsx)("table", { ref, className: cn("w-full caption-bottom text-sm", className), ...props })
     }
   );
@@ -20046,13 +20127,8 @@ function DataTable({
         children: /* @__PURE__ */ (0, import_jsx_runtime68.jsx)(
           "div",
           {
-            className: "custom-scrollbar w-full",
-            "data-os-scrollbar": true,
-            style: stickyHeader ? {
-              maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight,
-              overflowY: "auto",
-              overflowX: "auto"
-            } : { overflowX: "auto" },
+            className: cn("w-full overflow-x-auto", stickyHeader && "overflow-y-auto"),
+            style: stickyHeader ? { maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight } : void 0,
             children: /* @__PURE__ */ (0, import_jsx_runtime68.jsxs)(
               Table,
               {