@underverse-ui/underverse 1.0.32 → 1.0.33

package/AGENTS.md

@@ -51,13 +51,19 @@ import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
 export function App() {
   return (
     <>
-      <OverlayScrollbarProvider />
+      <OverlayScrollbarProvider enabled theme="os-theme-underverse" autoHide="leave" />
       {/* app */}
     </>
   );
 }
 ```
 
+Behavior:
+
+- Provider initializes only on `[data-os-scrollbar]`.
+- Underverse components already mark their internal scroll containers.
+- Use `data-os-ignore` on a node to opt out.
+
 ## i18n Notes
 
 - Components work without `next-intl` using fallback translations.

package/README.md

@@ -146,13 +146,31 @@ 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 **only** on elements marked with `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`.
+
+Migration notes:
+
+- Remove any local DOM-scanning scrollbar provider in your app.
+- Keep a single `OverlayScrollbarProvider` mounted once at app root.
+- If you have custom app-level scroll containers outside Underverse components, add `data-os-scrollbar` to those nodes.
+
 ### Standalone React (Vite, CRA, etc.)
 
 ```tsx

package/agent-recipes.json

@@ -26,7 +26,7 @@
     {
       "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": "api-discovery-order",
@@ -39,4 +39,3 @@
     }
   ]
 }
-

package/api-reference.json

@@ -1,8 +1,8 @@
 {
   "package": "@underverse-ui/underverse",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "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,15 @@ var Popover = ({
             children: /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
               "div",
               {
+                ...contentProps,
+                "data-os-scrollbar": contentScrollable ? true : void 0,
                 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
               }
             )
@@ -4222,6 +4227,7 @@ var Sheet = ({
           /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(
             "div",
             {
+              "data-os-scrollbar": true,
               className: "flex-1 overflow-auto p-4",
               style: {
                 opacity: open && !isAnimating ? 1 : 0,
@@ -4685,7 +4691,7 @@ var Tabs = ({
   );
   const activeTab = tabs.find((tab) => tab.value === active);
   return /* @__PURE__ */ (0, import_jsx_runtime23.jsxs)("div", { className: cn("w-full", orientation === "vertical" && "flex gap-6"), children: [
-    /* @__PURE__ */ (0, import_jsx_runtime23.jsxs)("div", { className: containerClasses, role: "tablist", "aria-orientation": orientation, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime23.jsxs)("div", { className: containerClasses, role: "tablist", "aria-orientation": orientation, "data-os-scrollbar": orientation === "horizontal" ? true : void 0, children: [
       tabs.map((tab, index) => {
         const isActive = active === tab.value;
         const Icon = tab.icon;
@@ -5235,7 +5241,7 @@ var Combobox = ({
             }
           )
         ] }) }),
-        /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: "overflow-y-auto overscroll-contain", style: { maxHeight }, children: /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: cn(size === "sm" ? "p-1" : size === "lg" ? "p-2" : "p-1.5"), children: loading2 ? /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime25.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { "data-os-scrollbar": true, className: "overflow-y-auto overscroll-contain", style: { maxHeight }, children: /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: cn(size === "sm" ? "p-1" : size === "lg" ? "p-2" : "p-1.5"), children: loading2 ? /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime25.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
           /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: "relative", children: /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("div", { className: "w-10 h-10 rounded-full border-2 border-primary/20 border-t-primary animate-spin" }) }),
           /* @__PURE__ */ (0, import_jsx_runtime25.jsx)("span", { className: "text-sm text-muted-foreground", children: loadingText })
         ] }) }) : filteredOptions.length > 0 ? groupedOptions ? (
@@ -6291,6 +6297,7 @@ var DatePicker = ({
           sizeStyles8[size].contentPadding,
           "animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-300"
         ),
+        contentScrollable: true,
         trigger: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)(
           "button",
           {
@@ -6646,6 +6653,7 @@ var DateRangePicker = ({ startDate, endDate, onChange, placeholder = "Select dat
         size === "sm" ? "p-3" : "p-5",
         "animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-300"
       ),
+      contentScrollable: true,
       trigger: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)(
         "button",
         {
@@ -7096,6 +7104,7 @@ function WheelColumn({
         "div",
         {
           ref: scrollRef,
+          "data-os-scrollbar": true,
           className: cn(
             "h-full overflow-y-auto overscroll-contain snap-y snap-mandatory",
             "select-none cursor-grab active:cursor-grabbing",
@@ -8519,6 +8528,7 @@ function WheelColumn2({
         "div",
         {
           ref: scrollRef,
+          "data-os-scrollbar": true,
           className: cn(
             "h-full overflow-y-auto overscroll-contain snap-y snap-mandatory",
             "select-none cursor-grab active:cursor-grabbing",
@@ -9466,6 +9476,7 @@ var DateTimePicker = ({
           // Keep the popover usable on small viewports
           "max-w-[calc(100vw-1rem)] max-h-[calc(100vh-6rem)] overflow-auto"
         ),
+        contentScrollable: true,
         placement: "bottom-end",
         children: [
           /* @__PURE__ */ (0, import_jsx_runtime33.jsxs)("div", { className: "flex flex-col lg:flex-row divide-y lg:divide-y-0 lg:divide-x divide-border", children: [
@@ -10137,7 +10148,7 @@ function CalendarTimelineHeader(props) {
               contentClassName: cn(
                 "w-auto p-0 rounded-2xl md:rounded-3xl overflow-hidden"
               ),
-              children: /* @__PURE__ */ (0, import_jsx_runtime35.jsxs)("div", { className: "max-w-[calc(100vw-1rem)] max-h-[calc(100vh-6rem)] overflow-auto", children: [
+              children: /* @__PURE__ */ (0, import_jsx_runtime35.jsxs)("div", { "data-os-scrollbar": true, className: "max-w-[calc(100vw-1rem)] max-h-[calc(100vh-6rem)] overflow-auto", children: [
                 /* @__PURE__ */ (0, import_jsx_runtime35.jsxs)("div", { className: "flex flex-col lg:flex-row divide-y lg:divide-y-0 lg:divide-x divide-border", children: [
                   /* @__PURE__ */ (0, import_jsx_runtime35.jsx)("div", { className: "p-2", children: /* @__PURE__ */ (0, import_jsx_runtime35.jsx)(
                     Calendar3,
@@ -10281,7 +10292,7 @@ function CalendarTimelineHeader(props) {
           ]
         }
       ) : null,
-      /* @__PURE__ */ (0, import_jsx_runtime35.jsx)("div", { ref: headerRef, className: "flex-1 min-w-0 overflow-x-auto overflow-y-hidden", children: slotHeaderNodes })
+      /* @__PURE__ */ (0, import_jsx_runtime35.jsx)("div", { ref: headerRef, "data-os-scrollbar": true, className: "flex-1 min-w-0 overflow-x-auto overflow-y-hidden", children: slotHeaderNodes })
     ] })
   ] });
 }
@@ -11872,6 +11883,7 @@ function CalendarTimeline({
             "div",
             {
               ref: leftRef,
+              "data-os-scrollbar": true,
               className: "shrink-0 overflow-y-auto overflow-x-hidden",
               style: { width: effectiveResourceColumnWidth, minWidth: effectiveResourceColumnWidth },
               children: [
@@ -12497,6 +12509,7 @@ var MultiCombobox = ({
         id: listboxId,
         role: "listbox",
         "aria-multiselectable": "true",
+        "data-os-scrollbar": true,
         style: { maxHeight },
         className: cn("overflow-y-auto p-1.5", size === "lg" ? "text-base" : size === "sm" ? "text-xs" : "text-sm"),
         children: loading2 ? /* @__PURE__ */ (0, import_jsx_runtime40.jsx)("li", { className: "px-3 py-8 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime40.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
@@ -15133,6 +15146,7 @@ function Carousel({
         showThumbnails && totalSlides > slidesToShow && /* @__PURE__ */ (0, import_jsx_runtime47.jsx)(
           "div",
           {
+            "data-os-scrollbar": true,
             className: cn(
               "absolute bottom-0 left-0 right-0 flex gap-2 p-4 bg-linear-to-t from-black/50 to-transparent overflow-x-auto",
               isHorizontal ? "flex-row" : "flex-col"
@@ -16024,6 +16038,7 @@ var TimelineRoot = React43.forwardRef(
       "div",
       {
         ref,
+        "data-os-scrollbar": mode === "horizontal" ? true : void 0,
         className: cn("relative", mode === "horizontal" && "flex gap-4 overflow-x-auto", mode === "vertical" && "space-y-0", className),
         ...rest,
         children: mode === "vertical" ? /* @__PURE__ */ (0, import_jsx_runtime51.jsx)("div", { className: "space-y-0", children: content }) : content
@@ -17019,7 +17034,7 @@ var MusicPlayer = ({
         }
       ) })
     ] }),
-    showPlaylist && /* @__PURE__ */ (0, import_jsx_runtime53.jsx)("div", { className: "bg-muted/50 backdrop-blur-sm max-h-96 overflow-y-auto border-t border-border", children: /* @__PURE__ */ (0, import_jsx_runtime53.jsxs)("div", { className: "p-4", children: [
+    showPlaylist && /* @__PURE__ */ (0, import_jsx_runtime53.jsx)("div", { "data-os-scrollbar": true, className: "bg-muted/50 backdrop-blur-sm max-h-96 overflow-y-auto border-t border-border", children: /* @__PURE__ */ (0, import_jsx_runtime53.jsxs)("div", { className: "p-4", children: [
       /* @__PURE__ */ (0, import_jsx_runtime53.jsxs)("h3", { className: "text-lg font-semibold text-foreground mb-3", children: [
         "Playlist (",
         playlist.length,
@@ -19018,44 +19033,56 @@ 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 SCROLLABLE_SELECTOR = "[data-os-scrollbar]";
 var PORTAL_EXCLUDE_SELECTOR = [
   "[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 shouldSkip(element) {
   if (element === document.body || element === document.documentElement) return true;
+  if (element.classList.contains("scrollbar-none")) return true;
   if (element.hasAttribute("data-os-ignore")) return true;
   if (element.hasAttribute("data-overlayscrollbars")) return true;
   if (element.closest(PORTAL_EXCLUDE_SELECTOR)) return true;
   return false;
 }
-function OverlayScrollbarProvider() {
+function OverlayScrollbarProvider({
+  enabled = true,
+  theme = "os-theme-underverse",
+  visibility = "auto",
+  autoHide = "leave",
+  autoHideDelay = 600,
+  dragScroll = true,
+  clickScroll = false
+} = {}) {
   (0, import_react33.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    if (!enabled) return;
+    const options = {
+      scrollbars: {
+        theme,
+        visibility,
+        autoHide,
+        autoHideDelay,
+        dragScroll,
+        clickScroll
+      }
+    };
     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));
+      instances.set(element, (0, import_overlayscrollbars.OverlayScrollbars)(element, options));
     };
     const scan = (root) => {
-      if (root instanceof HTMLElement && root.matches(EXPLICIT_SELECTOR)) {
+      if (root instanceof HTMLElement && root.matches(SCROLLABLE_SELECTOR)) {
         init(root);
       }
-      root.querySelectorAll(EXPLICIT_SELECTOR).forEach(init);
+      if (!("querySelectorAll" in root)) return;
+      root.querySelectorAll(SCROLLABLE_SELECTOR).forEach(init);
     };
     const cleanup = () => {
       instances.forEach((instance, element) => {
@@ -19092,7 +19119,7 @@ function OverlayScrollbarProvider() {
       instances.forEach((instance) => instance.destroy());
       instances.clear();
     };
-  }, []);
+  }, [enabled, theme, visibility, autoHide, autoHideDelay, dragScroll, clickScroll]);
   return null;
 }
 var OverlayScrollbarProvider_default = OverlayScrollbarProvider;
@@ -21645,7 +21672,7 @@ var CommandList = (0, import_react42.forwardRef)((props, ref) => {
   if (props.items.length === 0) {
     return /* @__PURE__ */ (0, import_jsx_runtime77.jsx)("div", { className: "w-72 p-4 text-center text-sm text-muted-foreground", children: "No results" });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime77.jsxs)("div", { ref: listRef, className: "w-72 max-h-80 overflow-y-auto bg-card border border-border rounded-2xl shadow-lg", children: [
+  return /* @__PURE__ */ (0, import_jsx_runtime77.jsxs)("div", { ref: listRef, "data-os-scrollbar": true, className: "w-72 max-h-80 overflow-y-auto bg-card border border-border rounded-2xl shadow-lg", children: [
     /* @__PURE__ */ (0, import_jsx_runtime77.jsx)("div", { className: "px-3 py-2 border-b", children: /* @__PURE__ */ (0, import_jsx_runtime77.jsx)("span", { className: "text-xs font-semibold text-muted-foreground uppercase tracking-wider", children: "Basic Blocks" }) }),
     /* @__PURE__ */ (0, import_jsx_runtime77.jsx)("div", { className: "p-1", children: props.items.map((item, index) => /* @__PURE__ */ (0, import_jsx_runtime77.jsxs)(
       "button",
@@ -22738,7 +22765,7 @@ var EmojiList = (0, import_react44.forwardRef)((props, ref) => {
   if (props.items.length === 0) {
     return /* @__PURE__ */ (0, import_jsx_runtime78.jsx)("div", { className: "w-80 p-4 text-center text-sm text-muted-foreground bg-card border border-border rounded-2xl shadow-lg", children: "No emoji found" });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime78.jsxs)("div", { className: "w-80 max-h-80 overflow-y-auto bg-card border border-border rounded-2xl shadow-lg", children: [
+  return /* @__PURE__ */ (0, import_jsx_runtime78.jsxs)("div", { "data-os-scrollbar": true, className: "w-80 max-h-80 overflow-y-auto bg-card border border-border rounded-2xl shadow-lg", children: [
     /* @__PURE__ */ (0, import_jsx_runtime78.jsx)("div", { className: "px-3 py-2 border-b bg-muted/30", children: /* @__PURE__ */ (0, import_jsx_runtime78.jsxs)("div", { className: "flex items-center gap-2", children: [
       /* @__PURE__ */ (0, import_jsx_runtime78.jsx)(import_lucide_react41.Smile, { className: "w-4 h-4 text-primary" }),
       /* @__PURE__ */ (0, import_jsx_runtime78.jsx)("span", { className: "text-xs font-semibold text-muted-foreground uppercase tracking-wider", children: "Emoji" })
@@ -23107,6 +23134,7 @@ function buildUEditorExtensions({
     import_extension_code_block_lowlight.default.configure({
       lowlight,
       HTMLAttributes: {
+        "data-os-scrollbar": "true",
         class: "rounded-lg bg-[#1e1e1e] p-4 font-mono text-sm overflow-x-auto"
       }
     }),
@@ -23437,6 +23465,7 @@ var EmojiPicker = ({ onSelect, onClose }) => {
       "div",
       {
         ref: scrollContainerRef,
+        "data-os-scrollbar": true,
         className: "overflow-y-auto px-3 py-2 shrink",
         style: { height: "20rem" },
         children: search ? (
@@ -24136,7 +24165,7 @@ var SlashCommandMenu = ({ editor, onClose, filterText = "" }) => {
   if (commands.length === 0) {
     return /* @__PURE__ */ (0, import_jsx_runtime84.jsx)("div", { className: "w-72 p-4 text-center text-muted-foreground text-sm", children: t("slashCommand.noResults") });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime84.jsxs)("div", { ref: menuRef, className: "w-72 max-h-80 overflow-y-auto", children: [
+  return /* @__PURE__ */ (0, import_jsx_runtime84.jsxs)("div", { ref: menuRef, "data-os-scrollbar": true, className: "w-72 max-h-80 overflow-y-auto", children: [
     /* @__PURE__ */ (0, import_jsx_runtime84.jsx)("div", { className: "px-3 py-2 border-b", children: /* @__PURE__ */ (0, import_jsx_runtime84.jsx)("span", { className: "text-xs font-semibold text-muted-foreground uppercase tracking-wider", children: t("slashCommand.basicBlocks") }) }),
     /* @__PURE__ */ (0, import_jsx_runtime84.jsx)("div", { className: "p-1", children: commands.map((cmd, index) => /* @__PURE__ */ (0, import_jsx_runtime84.jsxs)(
       "button",
@@ -24898,6 +24927,7 @@ var UEditor = import_react52.default.forwardRef(({
           import_react53.EditorContent,
           {
             editor,
+            "data-os-scrollbar": true,
             className: "flex-1 overflow-y-auto",
             style: {
               minHeight,