ropav 0.0.12 → 0.1.1

package/docs/public-floating-api.md

@@ -49,19 +49,30 @@ const { actualPlacement, arrowStyle, floatingStyle } = useFloatingPosition({
 
 The composable accepts plain values, refs, computed refs or getters for reactive options.
 
-| Option             | Default    | Description                                                    |
-| ------------------ | ---------- | -------------------------------------------------------------- |
-| `reference`        | required   | Element or virtual element used as the anchor.                 |
-| `floating`         | required   | Floating HTML element.                                         |
-| `arrow`            | —          | Optional arrow HTML element.                                   |
-| `open`             | `true`     | Suspends positioning and auto-updates when false.              |
-| `placement`        | `bottom`   | Preferred side and optional alignment.                         |
-| `strategy`         | `absolute` | CSS positioning strategy: `absolute` or `fixed`.               |
-| `offset`           | `8`        | Main/cross-axis distance from the reference.                   |
-| `flip`             | `true`     | Tries the opposite side when space is insufficient.            |
-| `shift`            | `true`     | Keeps the floating element inside the collision boundary.      |
-| `collisionPadding` | `8`        | Padding between the floating element and viewport boundary.    |
-| `restartKey`       | —          | Rebinds auto-update observers when its reactive value changes. |
+| Option                             | Default    | Description                                                            |
+| ---------------------------------- | ---------- | ---------------------------------------------------------------------- |
+| `reference`                        | required   | Element or virtual element used as the anchor.                         |
+| `floating`                         | required   | Floating HTML element.                                                 |
+| `arrow`                            | —          | Optional arrow HTML element.                                           |
+| `open`                             | `true`     | Suspends positioning and auto-updates when false.                      |
+| `placement`                        | `bottom`   | Preferred side and optional alignment.                                 |
+| `strategy`                         | `absolute` | CSS positioning strategy: `absolute` or `fixed`.                       |
+| `offset`                           | `8`        | Main/cross-axis distance from the reference.                           |
+| `flip`                             | `true`     | Tries the opposite side when space is insufficient.                    |
+| `flipOptions.fallbackStrategy`     | `bestFit`  | Chooses the best fit or preserves the initial placement when none fit. |
+| `shift`                            | `true`     | Keeps the floating element inside the collision boundary.              |
+| `collisionPadding`                 | `8`        | Padding between the floating element and viewport boundary.            |
+| `autoUpdateOptions.animationFrame` | `false`    | Tracks transform animations and detached nested floating contexts.     |
+| `restartKey`                       | —          | Rebinds auto-update observers when its reactive value changes.         |
+
+Use `autoUpdateOptions.animationFrame` sparingly. It checks the reference position every animation
+frame and is intended for references moving with CSS transforms or nested floating elements outside
+their ancestor's scrolling context. The animation-frame loop only runs while positioning is open.
+
+`Popover`, `Tooltip`, `DropdownMenu`, `DropdownMenuContent` and `DropdownMenuSubContent` accept the
+same `flipOptions` and `autoUpdateOptions` objects. On the data-driven `DropdownMenu`, the options
+also apply to its open submenus. Each open floating element using `animationFrame: true` runs its own
+animation-frame loop.
 
 The return value contains readonly `actualPlacement`, `floatingStyle`, `arrowStyle` and
 `isPositioned` refs, plus an async `update()` method for content-driven layout changes.

package/docs/public-overlay-layer-api.md

@@ -0,0 +1,65 @@
+# Overlay layer z-index API
+
+`OverlayLayerProvider` sets a shared z-index floor for Ropav portal surfaces in a Vue subtree.
+Component props take precedence over the nearest provider, and components outside a provider keep
+their existing defaults.
+
+```vue
+<template>
+  <OverlayLayerProvider :base-z-index="5000">
+    <AppShell />
+  </OverlayLayerProvider>
+</template>
+
+<script setup lang="ts">
+import { OverlayLayerProvider } from 'ropav/overlay';
+</script>
+```
+
+The provider follows the logical Vue component tree, including content rendered through
+`Teleport`. Providers can be nested to create a higher or lower floor for one subtree.
+
+## Component overrides
+
+`DialogRoot`, `Modal`, `Popover`, `DropdownMenu`, `DropdownMenuRoot`, `Tooltip` and `ToastViewport`
+accept `baseZIndex`. The resolution order is:
+
+1. The component's `baseZIndex` prop.
+2. The nearest `OverlayLayerProvider`.
+3. The component's legacy default.
+
+Dialog, Popover and Dropdown layers may end up above the resolved floor because active managed
+layers are ordered in two-unit steps. The unused plane immediately below a Dialog content layer is
+reserved for its overlay. A top-level Tooltip uses the resolved floor, while a Tooltip nested in a
+managed layer uses at least `parentZIndex + 1`. `ToastViewport` applies an offset of `1`.
+
+Without a provider or local override, Dropdown and Popover start at `100`, Dialog and Tooltip start
+at `1000`, and ToastViewport uses `1001`.
+
+## Custom portal surfaces
+
+`useOverlayZIndex()` lets custom portal content resolve the same policy without joining Ropav's
+focus, inert, dismissal or active-layer management.
+
+```vue
+<script setup lang="ts">
+import { useOverlayZIndex } from 'ropav/overlay';
+
+const props = defineProps<{ baseZIndex?: number }>();
+const zIndex = useOverlayZIndex({
+  baseZIndex: () => props.baseZIndex,
+  defaultBaseZIndex: 1000,
+  offset: 1,
+});
+</script>
+```
+
+| Option              | Default | Description                                                         |
+| ------------------- | ------- | ------------------------------------------------------------------- |
+| `baseZIndex`        | —       | Local value, ref or getter that overrides the provider.             |
+| `defaultBaseZIndex` | `1000`  | Fallback used when neither a local value nor provider is available. |
+| `offset`            | `0`     | Value, ref or getter added to the resolved base.                    |
+| `aboveParent`       | `true`  | Ensures the result is at least one plane above a parent layer.      |
+
+Set `aboveParent: false` when the custom surface only needs the resolved floor. The returned
+`ComputedRef<number>` updates when the local value, provider or parent layer changes.

package/docs/public-styles-api.md

@@ -26,7 +26,7 @@ Ropav does not expose a `vars` prop. Public CSS variables are set through CSS, t
 
 - Classes merge as internal classes, compatibility classes, `classNames`, then root `class` attributes.
 - Styles merge as internal styles, compatibility styles, `styles`, then root `style` attributes. Later stages win a duplicate property.
-- `Card.bodyClass`, `inputAttrs` styling and `thumbStyle` are compatibility stages. `Card.bodyClass` is deprecated; the other escape hatches remain because they also carry non-styling behavior.
+- `inputAttrs` styling and `thumbStyle` are compatibility stages because these escape hatches also carry non-styling behavior.
 - Attributes and native listeners are forwarded exactly once to the public root host. Internal native handlers run before consumer handlers.
 - Declared component events remain component events. Component-owned roles, ARIA and behavioral attributes remain authoritative.
 - Composite components do not copy root attributes into their child components. Teleported roots receive attributes on the rendered host, not on the virtual teleport node.
@@ -120,8 +120,6 @@ The layered stylesheet declares `ropav.tokens` before `ropav.components`. A laye
 
 Place global resets in `reset` and application overrides in `app`. Import order does not change precedence once the order is declared. Unlayered application rules still outrank named Ropav layers.
 
-Layer adoption changes cascade precedence. Consumers whose reset cannot yet be layered can temporarily import `ropav/legacy-unlayered.css` after that reset. The aggregate fallback is deprecated from its introduction and is intended only as a migration aid.
-
 ## Compatibility
 
 - Typed parts, state attributes, manifest entries, geometry variables and cascade layers form the current Public Styles API.
@@ -130,5 +128,3 @@ Layer adoption changes cascade precedence. Consumers whose reset cannot yet be l
 - `tokens:check` compares the current manifest with the latest reachable `v*` release tag that contains one. Until the first such release, it uses the immutable manifest from the initial Public Styles API commit (`f16e826`). Released variables cannot be removed, renamed or changed semantically; adding a variable requires incrementing the manifest's `contractVersion`.
 - Release tags must be available in the Git checkout that runs the check. `PUBLIC_STYLES_BASELINE_REF` can explicitly pin a commit or tag that contains a manifest.
 - Internal DOM, selectors and undocumented variables are outside the public contract.
-- `Card.bodyClass` is a deprecated compatibility escape hatch; prefer `classNames.body`.
-- The legacy unlayered stylesheet is a temporary migration fallback for consumers that cannot yet adopt cascade layers.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ropav",
-  "version": "0.0.12",
+  "version": "0.1.1",
+  "license": "MIT",
   "type": "module",
-  "packageManager": "pnpm@11.10.0",
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
   },
@@ -164,42 +164,10 @@
       "import": "./dist/components/tooltip/index.js"
     },
     "./base.css": "./dist/base.css",
-    "./legacy-unlayered.css": "./dist/legacy-unlayered.css",
     "./styles-manifest": "./src/styles/styles-manifest.json",
     "./styles-manifest.json": "./src/styles/styles-manifest.json",
     "./scss/*.scss": "./src/styles/*.scss"
   },
-  "scripts": {
-    "dev": "pnpm run storybook",
-    "tokens:build": "style-dictionary build --config scripts/tokens.config.mjs --silent",
-    "tokens:check": "node scripts/check-tokens.mjs",
-    "styles:manifest:bootstrap": "node scripts/bootstrap-public-styles-manifest.mjs",
-    "typecheck": "vue-tsc -b tsconfig.app.json tsconfig.node.json tsconfig.test.json",
-    "typecheck:storybook": "vue-tsc -p tsconfig.storybook.json --noEmit",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "test": "vitest run --project=unit",
-    "test:consumer-types": "pnpm run test:package",
-    "test:consumer-types:built": "tsc -p tests/fixtures/consumer-types/tsconfig.bundler.json && tsc -p tests/fixtures/consumer-types/tsconfig.nodenext.json",
-    "test:exports": "pnpm run test:package",
-    "test:exports:built": "node scripts/check-exports.mjs",
-    "test:consumer-fixture:built": "node tests/fixtures/consumer-app/check.mjs && vue-tsc -p tests/fixtures/consumer-app/tsconfig.json --noEmit && vite build --config tests/fixtures/consumer-app/vite.config.ts && node tests/fixtures/consumer-app/assertions.mjs",
-    "test:package": "pnpm run build && pnpm run test:exports:built && pnpm run test:consumer-types:built && pnpm run test:consumer-fixture:built",
-    "test:watch": "vitest --project=unit",
-    "test:typecheck": "vitest run --project=unit --typecheck",
-    "test:storybook": "vitest run --project=storybook",
-    "test:all": "pnpm run tokens:check && pnpm test && pnpm test:storybook",
-    "build": "pnpm run tokens:build && pnpm run tokens:check && pnpm run typecheck && vite build",
-    "prepublishOnly": "pnpm run test:package",
-    "preview": "vite preview",
-    "storybook": "pnpm run tokens:build && storybook dev -p 6006 --no-open",
-    "build-storybook": "pnpm run tokens:build && pnpm run tokens:check && pnpm run typecheck:storybook && storybook build",
-    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -o CHANGELOG.md",
-    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -o CHANGELOG.md -r 0",
-    "release": "pnpm run test:package && bumpp --git-check --all --commit \"chore(release): v%s\" --tag \"v%s\" --execute \"pnpm run changelog\""
-  },
   "peerDependencies": {
     "vue": "^3.6.0-beta.4"
   },
@@ -209,9 +177,9 @@
   },
   "devDependencies": {
     "@iconify-json/lucide": "^1.2.117",
-    "@storybook/addon-themes": "^10.5.0",
-    "@storybook/addon-vitest": "^10.5.0",
-    "@storybook/vue3-vite": "^10.5.0",
+    "@storybook/addon-themes": "^10.5.2",
+    "@storybook/addon-vitest": "^10.5.2",
+    "@storybook/vue3-vite": "^10.5.2",
     "@types/node": "^26.1.1",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitest/browser-playwright": "^4.1.10",
@@ -224,13 +192,12 @@
     "oxfmt": "^0.59.0",
     "oxlint": "^1.74.0",
     "playwright": "^1.61.1",
-    "postcss": "^8.5.19",
     "sass-embedded": "^1.100.0",
-    "storybook": "^10.5.0",
+    "storybook": "^10.5.2",
     "style-dictionary": "5.5.0",
     "typescript": "~6.0.3",
     "unplugin-icons": "^23.0.1",
-    "vite": "^8.1.4",
+    "vite": "^8.1.5",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10",
     "vue": "3.6.0-beta.17",
@@ -239,5 +206,35 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/daopk/ropav"
+  },
+  "scripts": {
+    "dev": "pnpm run storybook",
+    "tokens:build": "style-dictionary build --config scripts/tokens.config.mjs --silent",
+    "tokens:check": "node scripts/check-tokens.mjs",
+    "styles:manifest:bootstrap": "node scripts/bootstrap-public-styles-manifest.mjs",
+    "typecheck": "vue-tsc -b tsconfig.app.json tsconfig.node.json tsconfig.test.json",
+    "typecheck:storybook": "vue-tsc -p tsconfig.storybook.json --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "test": "vitest run --project=unit",
+    "test:consumer-types": "pnpm run test:package",
+    "test:consumer-types:built": "tsc -p tests/fixtures/consumer-types/tsconfig.bundler.json && tsc -p tests/fixtures/consumer-types/tsconfig.nodenext.json",
+    "test:exports": "pnpm run test:package",
+    "test:exports:built": "node scripts/check-exports.mjs",
+    "test:consumer-fixture:built": "node tests/fixtures/consumer-app/check.mjs && vue-tsc -p tests/fixtures/consumer-app/tsconfig.json --noEmit && vite build --config tests/fixtures/consumer-app/vite.config.ts && node tests/fixtures/consumer-app/assertions.mjs",
+    "test:package": "pnpm run build && pnpm run test:exports:built && pnpm run test:consumer-types:built && pnpm run test:consumer-fixture:built",
+    "test:watch": "vitest --project=unit",
+    "test:typecheck": "vitest run --project=unit --typecheck",
+    "test:storybook": "vitest run --project=storybook",
+    "test:all": "pnpm run tokens:check && pnpm test && pnpm test:storybook",
+    "build": "pnpm run tokens:build && pnpm run tokens:check && pnpm run typecheck && vite build",
+    "preview": "vite preview",
+    "storybook": "pnpm run tokens:build && storybook dev -p 6006 --no-open",
+    "build-storybook": "pnpm run tokens:build && pnpm run tokens:check && pnpm run typecheck:storybook && storybook build",
+    "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -o CHANGELOG.md",
+    "changelog:all": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -o CHANGELOG.md -r 0",
+    "release": "pnpm run test:package && bumpp --git-check --all --commit \"chore(release): v%s\" --tag \"v%s\" --execute \"pnpm run changelog\""
   }
-}
+}