@underverse-ui/underverse 1.0.34 → 1.0.36

package/AGENTS.md

@@ -40,34 +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 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]`).
+- 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

@@ -2,6 +2,28 @@
 
 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

package/README.md

@@ -137,34 +137,36 @@ 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.
+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 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 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`.
 
 Provider props:
 
@@ -175,23 +177,30 @@ Provider props:
 - `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]`
+- `selector?: string` (deprecated, ignored; kept for backward compatibility)
 
-Custom selector mode example:
+Component-level enable flags:
 
-```tsx
-<OverlayScrollbarProvider
-  selector=".overflow-auto, .overflow-y-auto, .overflow-x-auto, [data-os-scrollbar]"
-/>
-```
+- `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
 
-Migration notes:
+When not to use:
 
-- 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.
+- Normal form fields
+- Short modal/dialog content
+- Full page root scrolling
 
 ### Standalone React (Vite, CRA, etc.)
 
@@ -253,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,13 +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-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": "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.34",
+  "version": "1.0.36",
   "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",