@octanejs/vaul 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Emil Kowalski
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,14 @@
1
+ # @octanejs/vaul
2
+
3
+ The Octane migration target for `vaul@1.1.2`.
4
+
5
+ ```ts
6
+ import { Drawer } from '@octanejs/vaul';
7
+ import '@octanejs/vaul/style.css';
8
+ ```
9
+
10
+ The binding preserves Vaul's drawer component names, controlled and
11
+ uncontrolled state, directions, drag behavior, snap points, nested drawers,
12
+ portal/focus semantics, and `data-vaul-*` styling contract.
13
+
14
+ See [UPSTREAM.md](./UPSTREAM.md) for the immutable source and license evidence.
package/UPSTREAM.md ADDED
@@ -0,0 +1,75 @@
1
+ # Upstream provenance
2
+
3
+ This binding targets `vaul@1.1.2` from
4
+ [`emilkowalski/vaul`](https://github.com/emilkowalski/vaul), tag `v1.1.2`, commit
5
+ `73d06cdd3fd990bf4b83214cfe240c246908af0d`.
6
+
7
+ The exact React source, complete Playwright test boundary (Next demo app, specs,
8
+ Playwright config, workspace metadata), package metadata, README, stylesheet, and
9
+ MIT license used for the port are retained under `upstream/`, vendored from the
10
+ tagged git repository. Byte inventory is locked by `upstream/SHA256SUMS`. The npm
11
+ tarball SHA-256 is `d062e21bae0c864c3559707c0451edabc0aac32a22eda239064a3faa7c9f1b21`
12
+ (published package surface only). Run `pnpm --dir packages/vaul upstream:check` to
13
+ verify the vendored evidence.
14
+
15
+ ## Source boundary
16
+
17
+ Upstream's React drawer implementation under `upstream/src` is re-authored in
18
+ `packages/vaul/src/index.tsrx` against `@octanejs/radix` Dialog primitives and
19
+ Octane hooks. The published stylesheet is reused as `src/style.css`.
20
+
21
+ ## Test-suite disposition
22
+
23
+ Upstream ships a Playwright suite (`package.json` script `test`: `playwright test`)
24
+ whose specs live under `test/tests/` and depend on the Next.js demo app under
25
+ `test/`. The complete tagged repository test boundary is vendored under
26
+ `upstream/` (source, demo app, specs, `playwright.config.ts`, workspace files).
27
+ A pristine-upstream lane (`vaul-pristine-upstream`) runs that suite unchanged
28
+ against published React `vaul@1.1.2` through the shared lockfile-backed
29
+ Playwright runner. Adapted Vitest / real-browser lanes remain the Octane-side
30
+ executable evidence in `audit/react-parity.json`. Port-authored test
31
+ classifications live in `audit/test-classifications.json`.
32
+
33
+ | Upstream artifact | Disposition |
34
+ | --- | --- |
35
+ | `test/tests/base.spec.ts` | **Adapted (partial).** Open/close through trigger and `Drawer.Close`: `tests/drawer.test.ts` (`// Per …:10`, `:27`). Controlled prop close via external `controlled-close` button: same file (`// Per …:35`), waiting the exit interval before asserting `[data-vaul-drawer]` is gone. Open-state semantic snapshot vs published React Vaul: `tests/differential/react-oracle.test.ts` (`// Per …:10`). Browser lane covers open/close focus/styles/cleanup. Upstream drag-down close (`:49`) remains a gap; the unpaired snap-point mid-drag-stays-open contract lives in ordinary `vaul-browser-conformance`, not parity evidence. `defaultOpen` and context-menu-cancel drag remain gaps. |
36
+ | `test/tests/controlled.spec.ts` | **Gap.** Overlay dismiss with `open` + `onOpenChange` (`:20-29`) is not yet re-authored: `tests/drawer.test.ts` only exercises the external `controlled-close` button from `base.spec.ts:35`, and the browser lane closes through `Drawer.Close`. Overlay non-dismiss when only `open` is passed also remains a gap. |
37
+ | `test/tests/initial-snap.spec.ts` | **Adapted (partial).** Initially-open fixture uses pinned snap values `[0, '148px', '355px', 1]` at `'148px'` and asserts active snap index `1`: `tests/browser/vaul.browser.test.ts` (`// Per …:24`). Upstream's commented drag-snap cases stay unported. |
38
+ | `test/tests/with-handle.spec.ts` | **Adapted.** Handle click cycles pinned `['148px', '355px']` from index `0` to `1`: `tests/browser/vaul.browser.test.ts` (`// Per …:9`). |
39
+ | `test/tests/nested.spec.ts` | **Out of scope for current lanes.** Nested drawer open/close is not yet re-authored; tracked as a surface gap, not counted as parity evidence. |
40
+ | `test/tests/non-dismissible.spec.ts` | **Out of scope for current lanes.** `dismissible={false}` overlay/drag refusal is not yet re-authored; tracked as a surface gap. |
41
+ | `test/tests/with-redirect.spec.ts` | **Out of scope.** Asserts body scroll-lock restore across a Next.js client navigation that this package does not host in adapted lanes (covered by the pristine Playwright lane). |
42
+ | `test/tests/with-scaled-background.spec.ts` | **Out of scope for current lanes.** Scaled-background CSS transform under drag is not yet re-authored. |
43
+ | `test/tests/without-scaled-background.spec.ts` | **Out of scope for current lanes.** Negative scaled-background assert is not yet re-authored. |
44
+ | `test/tests/helpers.ts`, `test/tests/constants.ts` | Support only; not executable cases. |
45
+
46
+ ## Port-authored test classification
47
+
48
+ | File | Classification | Pairing |
49
+ | --- | --- | --- |
50
+ | `tests/drawer.test.ts` | adapted upstream | cites `upstream/test/tests/base.spec.ts` open/close cases |
51
+ | `tests/differential/react-oracle.test.ts` | React/Octane differential | same open-drawer scenario against published `vaul@1.1.2` on React and `@octanejs/vaul`; also cites `base.spec.ts:10`; owned by `vaul-differential` |
52
+ | `tests/exports.test.ts` | Octane-only framework contract | root/`Drawer` export keys match pinned `vaul@1.1.2`; ordinary `vaul` shard only — not react-parity ownership |
53
+ | `tests/ssr/server.test.ts` | Octane-only framework contract | unpaired — upstream ships no SSR suite; closed trigger must render without browser globals. Runs in ordinary Vitest shards; not React-parity evidence. |
54
+ | `tests/browser/vaul.browser.test.ts` | adapted upstream (real browser) | cites base open/close, initial-snap load, and with-handle cycle; executes in the `vaul-real-browser` lane |
55
+ | `tests/browser-conformance/snap-drag.browser.test.ts` | Octane-only browser contract | unpaired snap-point mid-drag release stays open; `vaul-browser-conformance` project, not React-parity evidence |
56
+ | `tests/types/public-api.ts` | Octane-only framework contract | optional package-conformance declaration probes; not required parity evidence (no structural inventories/controls yet) |
57
+ | `scripts/react-parity/vaul-*-lib.test.mjs` | audit-verifier | classification / structural / upstream negative controls; not React-parity evidence |
58
+
59
+ ## Registered parity lanes
60
+
61
+ | Lane id | Kind | Project | Notes |
62
+ | --- | --- | --- | --- |
63
+ | `vaul-pristine-upstream` | pristine-upstream | `vaul-pristine-playwright` | vendored Playwright suite vs published React Vaul |
64
+ | `vaul-pristine-types` | pristine-types (optional) | `vaul-pristine-types` | package-conformance `tsc` probes; not required evidence |
65
+ | `vaul-adapted-types` | adapted-types (optional) | `vaul-types` | package-conformance `tsrx-tsc` probes; not required evidence |
66
+ | `vaul-adapted-full-suite` | adapted-octane | `vaul` | adapted drawer inventory + structural crosswalk (`testExecution.include` mixed ownership) |
67
+ | `vaul-differential` | adapted-octane (differential) | `vaul-differential` | React/Octane oracle inventory; wholly react-parity owned |
68
+ | `vaul-real-browser` | adapted-octane (real browser) | `vaul-browser` | headless Chromium inventory + structural crosswalk |
69
+
70
+ Upstream ships no type-test suite at `v1.1.2`. The type lanes remain optional
71
+ package-conformance probes until structural inventories and controls exist. The
72
+ `vaul` Vitest project is mixed: react-parity owns only `tests/drawer.test.ts`.
73
+ The React oracle lives in the dedicated `vaul-differential` project. The
74
+ `vaul-ssr` and `vaul-browser-conformance` Vitest projects stay outside parity
75
+ ownership.
package/package.json ADDED
@@ -0,0 +1,64 @@
1
+ {
2
+ "name": "@octanejs/vaul",
3
+ "version": "0.0.1",
4
+ "description": "Octane binding for Vaul drawers",
5
+ "type": "module",
6
+ "engines": {
7
+ "node": ">=22.22.2"
8
+ },
9
+ "octane": {
10
+ "hookSlots": {
11
+ "manual": [
12
+ "src"
13
+ ]
14
+ }
15
+ },
16
+ "author": "Emil Kowalski <e@emilkowal.ski>",
17
+ "publishConfig": {
18
+ "access": "public"
19
+ },
20
+ "sideEffects": [
21
+ "./src/style.css"
22
+ ],
23
+ "exports": {
24
+ ".": "./src/index.tsrx",
25
+ "./style.css": "./src/style.css",
26
+ "./package.json": "./package.json"
27
+ },
28
+ "files": [
29
+ "src",
30
+ "LICENSE",
31
+ "README.md",
32
+ "UPSTREAM.md",
33
+ "status.json"
34
+ ],
35
+ "dependencies": {
36
+ "@types/react": "^19.2.17",
37
+ "@octanejs/radix": "0.1.34"
38
+ },
39
+ "peerDependencies": {
40
+ "octane": "0.1.35"
41
+ },
42
+ "devDependencies": {
43
+ "@types/react-dom": "^19.2.3",
44
+ "playwright": "^1.61.1",
45
+ "react": "^19.2.7",
46
+ "react-dom": "^19.2.7",
47
+ "vaul": "1.1.2",
48
+ "vite": "^8.1.5",
49
+ "vitest": "^4.1.10",
50
+ "octane": "0.1.35"
51
+ },
52
+ "license": "MIT",
53
+ "repository": {
54
+ "type": "git",
55
+ "url": "https://github.com/octanejs/octane.git",
56
+ "directory": "packages/vaul"
57
+ },
58
+ "scripts": {
59
+ "test": "pnpm upstream:check && vitest run --root ../.. --project vaul --project vaul-differential --project vaul-ssr --project vaul-browser --project vaul-browser-conformance",
60
+ "parity:inventory": "node ../../scripts/react-parity/vaul-runtime-inventory.mjs",
61
+ "upstream:check": "node audit/check-upstream.mjs",
62
+ "typecheck": "tsrx-tsc --noEmit -p tsconfig.json"
63
+ }
64
+ }
package/src/browser.ts ADDED
@@ -0,0 +1,38 @@
1
+ export function isMobileFirefox(): boolean | undefined {
2
+ const userAgent = navigator.userAgent;
3
+ return (
4
+ typeof window !== 'undefined' &&
5
+ ((/Firefox/.test(userAgent) && /Mobile/.test(userAgent)) || // Android Firefox
6
+ /FxiOS/.test(userAgent)) // iOS Firefox
7
+ );
8
+ }
9
+
10
+ export function isMac(): boolean | undefined {
11
+ return testPlatform(/^Mac/);
12
+ }
13
+
14
+ export function isIPhone(): boolean | undefined {
15
+ return testPlatform(/^iPhone/);
16
+ }
17
+
18
+ export function isSafari(): boolean | undefined {
19
+ return /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
20
+ }
21
+
22
+ export function isIPad(): boolean | undefined {
23
+ return (
24
+ testPlatform(/^iPad/) ||
25
+ // iPadOS 13 lies and says it's a Mac, but we can distinguish by detecting touch support.
26
+ (isMac() && navigator.maxTouchPoints > 1)
27
+ );
28
+ }
29
+
30
+ export function isIOS(): boolean | undefined {
31
+ return isIPhone() || isIPad();
32
+ }
33
+
34
+ export function testPlatform(re: RegExp): boolean | undefined {
35
+ return typeof window !== 'undefined' && window.navigator != null
36
+ ? re.test(window.navigator.platform)
37
+ : undefined;
38
+ }
@@ -0,0 +1,18 @@
1
+ export const TRANSITIONS = {
2
+ DURATION: 0.5,
3
+ EASE: [0.32, 0.72, 0, 1],
4
+ };
5
+
6
+ export const VELOCITY_THRESHOLD = 0.4;
7
+
8
+ export const CLOSE_THRESHOLD = 0.25;
9
+
10
+ export const SCROLL_LOCK_TIMEOUT = 100;
11
+
12
+ export const BORDER_RADIUS = 8;
13
+
14
+ export const NESTED_DISPLACEMENT = 16;
15
+
16
+ export const WINDOW_TOP_OFFSET = 26;
17
+
18
+ export const DRAG_CLASS = 'vaul-dragging';
package/src/context.ts ADDED
@@ -0,0 +1,73 @@
1
+ import { createContext, useContext } from 'octane';
2
+ import type React from 'react';
3
+ import type { DrawerDirection } from './types';
4
+
5
+ export interface DrawerContextValue {
6
+ drawerRef: React.RefObject<HTMLDivElement | null>;
7
+ overlayRef: React.RefObject<HTMLDivElement | null>;
8
+ onPress: (event: React.PointerEvent<HTMLDivElement>) => void;
9
+ onRelease: (event: React.PointerEvent<HTMLDivElement> | null) => void;
10
+ onDrag: (event: React.PointerEvent<HTMLDivElement>) => void;
11
+ onNestedDrag: (event: React.PointerEvent<HTMLDivElement>, percentageDragged: number) => void;
12
+ onNestedOpenChange: (open: boolean) => void;
13
+ onNestedRelease: (event: React.PointerEvent<HTMLDivElement>, open: boolean) => void;
14
+ dismissible: boolean;
15
+ isOpen: boolean;
16
+ isDragging: boolean;
17
+ keyboardIsOpen: React.MutableRefObject<boolean>;
18
+ snapPointsOffset: number[] | null;
19
+ snapPoints?: (number | string)[] | null;
20
+ activeSnapPointIndex?: number | null;
21
+ modal: boolean;
22
+ shouldFade: boolean;
23
+ activeSnapPoint?: number | string | null;
24
+ setActiveSnapPoint: (value: number | string | null) => void;
25
+ closeDrawer: () => void;
26
+ openProp?: boolean;
27
+ onOpenChange?: (open: boolean) => void;
28
+ direction: DrawerDirection;
29
+ shouldScaleBackground: boolean;
30
+ setBackgroundColorOnScale: boolean;
31
+ noBodyStyles: boolean;
32
+ handleOnly?: boolean;
33
+ container?: HTMLElement | null;
34
+ autoFocus?: boolean;
35
+ shouldAnimate?: React.RefObject<boolean>;
36
+ }
37
+
38
+ export const DrawerContext = createContext<DrawerContextValue>({
39
+ drawerRef: { current: null },
40
+ overlayRef: { current: null },
41
+ onPress: () => {},
42
+ onRelease: () => {},
43
+ onDrag: () => {},
44
+ onNestedDrag: () => {},
45
+ onNestedOpenChange: () => {},
46
+ onNestedRelease: () => {},
47
+ openProp: undefined,
48
+ dismissible: false,
49
+ isOpen: false,
50
+ isDragging: false,
51
+ keyboardIsOpen: { current: false },
52
+ snapPointsOffset: null,
53
+ snapPoints: null,
54
+ handleOnly: false,
55
+ modal: false,
56
+ shouldFade: false,
57
+ activeSnapPoint: null,
58
+ onOpenChange: () => {},
59
+ setActiveSnapPoint: () => {},
60
+ closeDrawer: () => {},
61
+ direction: 'bottom',
62
+ shouldAnimate: { current: true },
63
+ shouldScaleBackground: false,
64
+ setBackgroundColorOnScale: true,
65
+ noBodyStyles: false,
66
+ container: null,
67
+ autoFocus: false,
68
+ });
69
+
70
+ // Plain-TS hooks pass a compiler-injected slot; context reads do not consume it.
71
+ export function useDrawerContext(_slot?: symbol) {
72
+ return useContext(DrawerContext);
73
+ }
package/src/helpers.ts ADDED
@@ -0,0 +1,124 @@
1
+ import type { AnyFunction, DrawerDirection } from './types';
2
+
3
+ interface Style {
4
+ [key: string]: string;
5
+ }
6
+
7
+ const cache = new WeakMap();
8
+
9
+ export function isInView(el: HTMLElement): boolean {
10
+ const rect = el.getBoundingClientRect();
11
+
12
+ if (!window.visualViewport) return false;
13
+
14
+ return (
15
+ rect.top >= 0 &&
16
+ rect.left >= 0 &&
17
+ // Need + 40 for safari detection
18
+ rect.bottom <= window.visualViewport.height - 40 &&
19
+ rect.right <= window.visualViewport.width
20
+ );
21
+ }
22
+
23
+ export function set(
24
+ el: Element | HTMLElement | null | undefined,
25
+ styles: Style,
26
+ ignoreCache = false,
27
+ ) {
28
+ if (!el || !(el instanceof HTMLElement)) return;
29
+ let originalStyles: Style = {};
30
+
31
+ Object.entries(styles).forEach(([key, value]: [string, string]) => {
32
+ if (key.startsWith('--')) {
33
+ el.style.setProperty(key, value);
34
+ return;
35
+ }
36
+
37
+ originalStyles[key] = (el.style as any)[key];
38
+ (el.style as any)[key] = value;
39
+ });
40
+
41
+ if (ignoreCache) return;
42
+
43
+ cache.set(el, originalStyles);
44
+ }
45
+
46
+ export function reset(el: Element | HTMLElement | null, prop?: string) {
47
+ if (!el || !(el instanceof HTMLElement)) return;
48
+ let originalStyles = cache.get(el);
49
+
50
+ if (!originalStyles) {
51
+ return;
52
+ }
53
+
54
+ if (prop) {
55
+ (el.style as any)[prop] = originalStyles[prop];
56
+ } else {
57
+ Object.entries(originalStyles).forEach(([key, value]) => {
58
+ (el.style as any)[key] = value;
59
+ });
60
+ }
61
+ }
62
+
63
+ export const isVertical = (direction: DrawerDirection) => {
64
+ switch (direction) {
65
+ case 'top':
66
+ case 'bottom':
67
+ return true;
68
+ case 'left':
69
+ case 'right':
70
+ return false;
71
+ default:
72
+ return direction satisfies never;
73
+ }
74
+ };
75
+
76
+ export function getTranslate(element: HTMLElement, direction: DrawerDirection): number | null {
77
+ if (!element) {
78
+ return null;
79
+ }
80
+ const style = window.getComputedStyle(element);
81
+ const transform =
82
+ // @ts-ignore
83
+ style.transform || style.webkitTransform || style.mozTransform;
84
+ let mat = transform.match(/^matrix3d\((.+)\)$/);
85
+ if (mat) {
86
+ // https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix3d
87
+ return parseFloat(mat[1].split(', ')[isVertical(direction) ? 13 : 12]);
88
+ }
89
+ // https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix
90
+ mat = transform.match(/^matrix\((.+)\)$/);
91
+ return mat ? parseFloat(mat[1].split(', ')[isVertical(direction) ? 5 : 4]) : null;
92
+ }
93
+
94
+ export function dampenValue(v: number) {
95
+ return 8 * (Math.log(v + 1) - 2);
96
+ }
97
+
98
+ export function assignStyle(
99
+ element: HTMLElement | null | undefined,
100
+ style: Partial<CSSStyleDeclaration>,
101
+ ) {
102
+ if (!element) return () => {};
103
+
104
+ const prevStyle = element.style.cssText;
105
+ Object.assign(element.style, style);
106
+
107
+ return () => {
108
+ element.style.cssText = prevStyle;
109
+ };
110
+ }
111
+
112
+ /**
113
+ * Receives functions as arguments and returns a new function that calls all.
114
+ */
115
+ export function chain<T>(...fns: T[]) {
116
+ return (...args: T extends AnyFunction ? Parameters<T> : never) => {
117
+ for (const fn of fns) {
118
+ if (typeof fn === 'function') {
119
+ // @ts-ignore
120
+ fn(...args);
121
+ }
122
+ }
123
+ };
124
+ }