@underverse-ui/underverse 1.0.33 → 1.0.35

package/AGENTS.md

@@ -40,30 +40,36 @@ export function Example() {
 }
 ```
 
-## Overlay Scrollbars (recommended)
+## Overlay Scrollbars (opt-in)
 
-Use the exported provider to enable overlay scrollbars (no layout width loss):
+Underverse uses component-level overlay scrollbars. No global selector scan and no app-wide MutationObserver.
 
 ```tsx
 import "overlayscrollbars/overlayscrollbars.css";
-import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
+import { OverlayScrollbarProvider, ScrollArea, DataTable } from "@underverse-ui/underverse";
 
 export function App() {
   return (
-    <>
-      <OverlayScrollbarProvider enabled theme="os-theme-underverse" autoHide="leave" />
-      {/* app */}
-    </>
+    <OverlayScrollbarProvider theme="os-theme-underverse" autoHide="leave">
+      <ScrollArea className="h-56" useOverlayScrollbar />
+      <DataTable columns={columns} data={rows} useOverlayScrollbar />
+    </OverlayScrollbarProvider>
   );
 }
 ```
 
 Behavior:
 
-- Provider initializes only on `[data-os-scrollbar]`.
-- Underverse components already mark their internal scroll containers.
+- Provider is config-only (context defaults), not an auto-mount global scanner.
+- Enable per component via `useOverlayScrollbar`.
+- Hard skip: `html`, `body`, `[data-radix-portal]`, `[role="dialog"]`, `[aria-modal="true"]`, `[data-sonner-toaster]`.
 - Use `data-os-ignore` on a node to opt out.
 
+Useful APIs:
+
+- `OverlayScrollArea` (dedicated heavy-scroll wrapper)
+- `useOverlayScrollbarTarget(ref, options)` for custom component internals
+
 ## i18n Notes
 
 - Components work without `next-intl` using fallback translations.

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to `@underverse-ui/underverse` are documented in this file.
+
+## [1.0.34] - 2026-02-24
+
+### Changed
+
+- Switched OverlayScrollbars architecture to strict component-level opt-in.
+- `OverlayScrollbarProvider` is now config-only (no global DOM scan, no global MutationObserver).
+- Added dedicated `OverlayScrollArea` wrapper for heavy scroll zones.
+- Added `useOverlayScrollbar?: boolean` (default `false`) on:
+  - `ScrollArea`
+  - `Table`
+  - `DataTable`
+  - `Combobox`
+  - `MultiCombobox`
+  - `CategoryTreeSelect`
+- Hard skip safety kept for:
+  - `html`, `body`
+  - `[data-radix-portal]`
+  - `[role=\"dialog\"]`
+  - `[aria-modal=\"true\"]`
+  - `[data-sonner-toaster]`
+- Removed global selector behavior from docs/recipes and marked `selector` prop deprecated (ignored).
+
+## [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

@@ -137,39 +137,70 @@ 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.
+Underverse now uses **opt-in, component-level** OverlayScrollbars.
+There is no global DOM scanning, no default global mount, and no app-wide MutationObserver.
 
 ```tsx
 import "overlayscrollbars/overlayscrollbars.css";
-import { OverlayScrollbarProvider } from "@underverse-ui/underverse";
+import { OverlayScrollbarProvider, ScrollArea, DataTable } from "@underverse-ui/underverse";
 
 function App() {
   return (
-    <>
-      <OverlayScrollbarProvider
-        enabled
-        theme="os-theme-underverse"
-        autoHide="leave"
-        autoHideDelay={600}
+    <OverlayScrollbarProvider theme="os-theme-underverse" autoHide="leave">
+      <ScrollArea className="h-56" useOverlayScrollbar>
+        {/* long content */}
+      </ScrollArea>
+
+      <DataTable
+        columns={columns}
+        data={rows}
+        useOverlayScrollbar
       />
-      {/* your app */}
-    </>
+    </OverlayScrollbarProvider>
   );
 }
 ```
 
 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`.
+- Provider is **configuration only** (theme/options context).
+- Scrollbars initialize only on components explicitly enabled via `useOverlayScrollbar`.
+- Hard skip targets: `html`, `body`, `[data-radix-portal]`, `[role="dialog"]`, `[aria-modal="true"]`, `[data-sonner-toaster]`.
+- Per-node opt-out remains available via `data-os-ignore`.
 
-Migration notes:
+Provider props:
 
-- 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.
+- `enabled?: boolean`
+- `theme?: string`
+- `visibility?: "visible" | "hidden" | "auto"`
+- `autoHide?: "never" | "scroll" | "leave" | "move"`
+- `autoHideDelay?: number`
+- `dragScroll?: boolean`
+- `clickScroll?: boolean`
+- `exclude?: string` default: `html, body, [data-os-ignore], [data-radix-portal], [role='dialog'], [aria-modal='true'], [data-sonner-toaster]`
+- `selector?: string` (deprecated, ignored; kept for backward compatibility)
+
+Component-level enable flags:
+
+- `ScrollArea`: `useOverlayScrollbar?: boolean` (default `false`)
+- `Table`: `useOverlayScrollbar?: boolean` (default `false`)
+- `DataTable`: `useOverlayScrollbar?: boolean` (default `false`)
+- `Combobox`: `useOverlayScrollbar?: boolean` (default `false`)
+- `MultiCombobox`: `useOverlayScrollbar?: boolean` (default `false`)
+- `CategoryTreeSelect`: `useOverlayScrollbar?: boolean` (default `false`)
+- `Textarea`: `useOverlayScrollbar?: boolean` (default `false`)
+- `OverlayScrollArea`: dedicated wrapper for heavy scroll zones (`enabled` default `true`)
+
+When to use:
+
+- Long virtualized/table/list panels
+- Fixed-height navigation panels and log viewers
+
+When not to use:
+
+- Normal form fields
+- Short modal/dialog content
+- Full page root scrolling
 
 ### Standalone React (Vite, CRA, etc.)
 
@@ -231,7 +262,7 @@ function App() {
 
 ### Navigation & Structure
 
-- `Breadcrumb`, `Tabs` (includes `SimpleTabs`, `PillTabs`, `VerticalTabs`), `DropdownMenu`, `Pagination`, `Section`, `ScrollArea`
+- `Breadcrumb`, `Tabs` (includes `SimpleTabs`, `PillTabs`, `VerticalTabs`), `DropdownMenu`, `Pagination`, `Section`, `ScrollArea`, `OverlayScrollArea`
 
 ### Data Display
 

package/agent-recipes.json

@@ -25,8 +25,13 @@
     },
     {
       "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 enabled theme=\"os-theme-underverse\" autoHide=\"leave\" />{/* app */}</>;\n}\n"
+      "title": "Enable overlay scrollbars (opt-in)",
+      "code": "import \"overlayscrollbars/overlayscrollbars.css\";\nimport { OverlayScrollbarProvider, ScrollArea } from \"@underverse-ui/underverse\";\n\nexport function App(){\n  return (\n    <OverlayScrollbarProvider theme=\"os-theme-underverse\" autoHide=\"leave\">\n      <ScrollArea className=\"h-56\" useOverlayScrollbar>{/* content */}</ScrollArea>\n    </OverlayScrollbarProvider>\n  );\n}\n"
+    },
+    {
+      "id": "overlay-scrollbar-custom-component",
+      "title": "Custom component with overlay scrollbar hook",
+      "code": "import { useRef } from \"react\";\nimport { useOverlayScrollbarTarget } from \"@underverse-ui/underverse\";\n\nexport function LogPanel(){\n  const ref = useRef<HTMLDivElement>(null);\n  useOverlayScrollbarTarget(ref, { enabled: true });\n\n  return <div ref={ref} className=\"h-64 overflow-y-auto\">...</div>;\n}\n"
     },
     {
       "id": "api-discovery-order",

package/api-reference.json

@@ -1,8 +1,8 @@
 {
   "package": "@underverse-ui/underverse",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "sourceEntry": "src/index.ts",
-  "totalExports": 207,
+  "totalExports": 211,
   "exports": [
     {
       "name": "*",
@@ -854,6 +854,20 @@
       "local": false,
       "aliasOf": "default"
     },
+    {
+      "name": "OverlayScrollArea",
+      "kind": "value",
+      "source": "../../../components/ui/OverlayScrollArea",
+      "reexport": true,
+      "local": false
+    },
+    {
+      "name": "OverlayScrollAreaProps",
+      "kind": "type",
+      "source": "../../../components/ui/OverlayScrollArea",
+      "reexport": true,
+      "local": false
+    },
     {
       "name": "OverlayScrollbarProvider",
       "kind": "value",
@@ -1408,6 +1422,20 @@
       "reexport": true,
       "local": false
     },
+    {
+      "name": "useOverlayScrollbarTarget",
+      "kind": "value",
+      "source": "../../../components/ui/OverlayScrollbarProvider",
+      "reexport": true,
+      "local": false
+    },
+    {
+      "name": "UseOverlayScrollbarTargetOptions",
+      "kind": "type",
+      "source": "../../../components/ui/OverlayScrollbarProvider",
+      "reexport": true,
+      "local": false
+    },
     {
       "name": "useShadCNAnimations",
       "kind": "value",