responsive-media 1.0.7 → 1.2.0

package/dist/react-responsive.js

@@ -0,0 +1,95 @@
+import { useSyncExternalStore, useEffect, useRef, useState } from 'react';
+import { responsiveState } from './create-responsive';
+import { subscribeMediaQuery } from './media-query';
+import { createContainerState } from './container-state';
+// ---------------------------------------------------------------------------
+// useResponsive
+// ---------------------------------------------------------------------------
+/**
+ * Returns the current responsive state. Re-renders only when state changes.
+ * Requires React 18+. Generic `T` narrows the type for custom configs.
+ *
+ * @example
+ * type MyState = { sm: boolean; lg: boolean };
+ * const { sm, lg } = useResponsive<MyState>();
+ */
+export function useResponsive() {
+    return useSyncExternalStore((onChange) => responsiveState.subscribe(() => onChange()), () => responsiveState.getState(), () => responsiveState.getState());
+}
+/**
+ * Returns ordered breakpoint helpers. Re-renders when the responsive state
+ * changes, so all helpers always reflect the current breakpoint.
+ *
+ * Requires a breakpoint `order` set via `setResponsiveConfig` or
+ * `createResponsiveState`. Falls back to config key insertion order.
+ *
+ * @example
+ * const { current, isAbove, isBelow, between } = useBreakpoints();
+ * return isAbove('sm') ? <DesktopNav /> : <MobileNav />;
+ */
+export function useBreakpoints() {
+    // Subscribe to state so the component re-renders on changes
+    useResponsive();
+    return {
+        current: responsiveState.current,
+        isAbove: (key) => responsiveState.isAbove(key),
+        isBelow: (key) => responsiveState.isBelow(key),
+        between: (from, to) => responsiveState.between(from, to),
+    };
+}
+// ---------------------------------------------------------------------------
+// useMediaQuery
+// ---------------------------------------------------------------------------
+/**
+ * Returns a boolean that tracks a raw CSS media query string.
+ * Compatible with React 18+ SSR (returns `false` on the server).
+ *
+ * @example
+ * const isDark   = useMediaQuery('(prefers-color-scheme: dark)');
+ * const canHover = useMediaQuery('(hover: hover)');
+ */
+export function useMediaQuery(query) {
+    const queryRef = useRef(query);
+    queryRef.current = query;
+    const [matches, setMatches] = useState(false);
+    useEffect(() => subscribeMediaQuery(queryRef.current, setMatches), [query]);
+    return matches;
+}
+// ---------------------------------------------------------------------------
+// useContainerState
+// ---------------------------------------------------------------------------
+/**
+ * Tracks an element's dimensions with `ResizeObserver` and evaluates
+ * breakpoint conditions in JavaScript (Container Queries).
+ *
+ * Pass a `ref` created with `useRef<Element>(null)` — the hook sets up the
+ * observer after mount and cleans up on unmount.
+ *
+ * @example
+ * function Card() {
+ *   const ref = useRef<HTMLDivElement>(null);
+ *   const { compact, wide } = useContainerState(ref, {
+ *     compact: [{ type: 'max-width', value: 300 }],
+ *     wide:    [{ type: 'min-width', value: 600 }],
+ *   });
+ *   return (
+ *     <div ref={ref}>
+ *       {compact ? <CompactLayout /> : wide ? <WideLayout /> : <DefaultLayout />}
+ *     </div>
+ *   );
+ * }
+ */
+export function useContainerState(ref, config, options) {
+    const [state, setState] = useState({});
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const cs = createContainerState(el, config, options);
+        const off = cs.subscribe((s) => setState({ ...s }));
+        return () => { off(); cs.destroy(); };
+        // config / options are treated as static after mount; memoize if needed
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return state;
+}

package/dist/responsive.enum.d.ts

@@ -1,7 +1,63 @@
 export type Breakpoint = 'mobile' | 'tablet' | 'desktop';
 export interface MediaQueryCondition {
-    type: 'width' | 'min-width' | 'max-width' | 'height' | 'min-height' | 'max-height' | 'aspect-ratio' | 'min-aspect-ratio' | 'max-aspect-ratio' | 'orientation' | 'resolution' | 'min-resolution' | 'max-resolution' | 'color' | 'min-color' | 'max-color' | 'color-index' | 'min-color-index' | 'max-color-index' | 'monochrome' | 'min-monochrome' | 'max-monochrome' | 'scan' | 'grid';
+    type: 'width' | 'min-width' | 'max-width' | 'height' | 'min-height' | 'max-height' | 'aspect-ratio' | 'min-aspect-ratio' | 'max-aspect-ratio' | 'orientation' | 'resolution' | 'min-resolution' | 'max-resolution' | 'color' | 'min-color' | 'max-color' | 'color-index' | 'min-color-index' | 'max-color-index' | 'monochrome' | 'min-monochrome' | 'max-monochrome' | 'scan' | 'grid' | 'prefers-color-scheme' | 'prefers-reduced-motion' | 'prefers-contrast' | 'hover' | 'any-hover' | 'pointer' | 'any-pointer' | 'forced-colors' | 'display-mode' | 'update'
+    /**
+     * Inserts the value verbatim into the media query string without wrapping
+     * it in parentheses. Use for media types (`print`, `screen`, `all`) or
+     * any raw token not covered by the typed conditions above.
+     *
+     * @example
+     * // Match only print media
+     * { type: 'raw', value: 'print' }
+     * // → window.matchMedia('print')
+     *
+     * @example
+     * // Restrict a condition to screen media
+     * [{ type: 'raw', value: 'screen' }, { type: 'max-width', value: 600 }]
+     * // → window.matchMedia('screen and (max-width: 600px)')
+     */
+     | 'raw';
     value: number | string;
 }
-export type MediaQueryConfig = MediaQueryCondition[];
+/**
+ * A flat array of conditions joined with `and`.
+ * Example: [min-width: 600, max-width: 960] → (min-width: 600px) and (max-width: 960px)
+ */
+export type MediaQueryAndGroup = MediaQueryCondition[];
+/**
+ * A config entry for a single breakpoint.
+ *
+ * - Flat array  → all conditions joined with `and`
+ * - Nested array → inner arrays joined with `and`, outer arrays joined with `,` (or)
+ *
+ * @example AND only
+ * [{ type: 'min-width', value: 601 }, { type: 'max-width', value: 960 }]
+ *
+ * @example OR between groups
+ * [
+ *   [{ type: 'max-width', value: 600 }],
+ *   [{ type: 'orientation', value: 'portrait' }, { type: 'max-width', value: 1024 }],
+ * ]
+ */
+export type MediaQueryConfig = MediaQueryCondition[] | MediaQueryCondition[][];
+/**
+ * Derives a boolean-state shape from a breakpoint config object.
+ *
+ * @example
+ * const config = {
+ *   sm: [{ type: 'max-width', value: 640 }],
+ *   lg: [{ type: 'min-width', value: 1024 }],
+ * } satisfies Record<string, MediaQueryConfig>;
+ *
+ * type MyState = ConfigToState<typeof config>; // { sm: boolean; lg: boolean }
+ */
+export type ConfigToState<T extends Record<string, MediaQueryConfig>> = {
+    [K in keyof T]: boolean;
+};
+/**
+ * Default breakpoint config. Mutually exclusive:
+ * - mobile:  ≤ 600px
+ * - tablet:  601px – 960px
+ * - desktop: ≥ 961px
+ */
 export declare const ResponsiveConfig: Record<Breakpoint, MediaQueryConfig>;

package/dist/responsive.enum.js

@@ -1,11 +1,11 @@
+/**
+ * Default breakpoint config. Mutually exclusive:
+ * - mobile:  ≤ 600px
+ * - tablet:  601px – 960px
+ * - desktop: ≥ 961px
+ */
 export const ResponsiveConfig = {
-    mobile: [
-        { type: 'max-width', value: 600 },
-    ],
-    tablet: [
-        { type: 'max-width', value: 960 },
-    ],
-    desktop: [
-        { type: 'min-width', value: 961 },
-    ],
+    mobile: [{ type: 'max-width', value: 600 }],
+    tablet: [{ type: 'min-width', value: 601 }, { type: 'max-width', value: 960 }],
+    desktop: [{ type: 'min-width', value: 961 }],
 };

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare const isSSR: () => boolean;
+export declare const hasMatchMedia: () => boolean;
+export declare const hasResizeObserver: () => boolean;

package/dist/utils.js

@@ -0,0 +1,3 @@
+export const isSSR = () => typeof window === 'undefined';
+export const hasMatchMedia = () => !isSSR() && typeof window.matchMedia === 'function';
+export const hasResizeObserver = () => !isSSR() && typeof ResizeObserver === 'function';

package/dist/vue-responsive.d.ts

@@ -1,8 +1,82 @@
-import type { App } from '@vue/runtime-core';
-import type { MediaQueryConfig } from './create-responsive';
-export declare function useResponsive(): any;
-type ResponsiveConfigType = Record<string, MediaQueryConfig>;
+import type { App, Ref, ComputedRef } from '@vue/runtime-core';
+import type { MediaQueryConfig, ResponsiveState, SetConfigOptions } from './create-responsive';
+/**
+ * Returns the reactive responsive state.
+ * Generic `T` narrows the type for custom configs.
+ *
+ * @example
+ * type MyState = { sm: boolean; lg: boolean };
+ * const state = useResponsive<MyState>();
+ */
+export declare function useResponsive<T extends Record<string, boolean> = Record<string, boolean>>(): T;
+export interface BreakpointHelpers {
+    /** First active breakpoint key, or `null`. Reactive computed. */
+    current: ComputedRef<string | null>;
+    /** `true` when the current breakpoint is after `key` in the order. Reactive in templates. */
+    isAbove: (key: string) => boolean;
+    /** `true` when the current breakpoint is before `key` in the order. Reactive in templates. */
+    isBelow: (key: string) => boolean;
+    /** `true` when the current breakpoint is between `from` and `to` (inclusive). Reactive in templates. */
+    between: (from: string, to: string) => boolean;
+}
+/**
+ * Returns ordered breakpoint helpers that are **reactive in Vue templates
+ * and computed properties** — they read from the Vue reactive state and
+ * re-evaluate automatically on viewport changes.
+ *
+ * Requires a breakpoint `order` to be set via `setConfig` or `createResponsiveState`.
+ * Falls back to config key insertion order if none is provided.
+ *
+ * @example
+ * const { current, isAbove, isBelow, between } = useBreakpoints();
+ *
+ * // In template:
+ * // <DesktopNav v-if="isAbove('sm')" />
+ * // <span>{{ current }}</span>
+ */
+export declare function useBreakpoints(): BreakpointHelpers;
+/**
+ * Reactive composable for a single raw CSS media query string.
+ * Returns a `Ref<boolean>`. Cleans up automatically on `onUnmounted`.
+ *
+ * @example
+ * const isDark   = useMediaQuery('(prefers-color-scheme: dark)');
+ * const canHover = useMediaQuery('(hover: hover)');
+ */
+export declare function useMediaQuery(query: string): Ref<boolean>;
+/**
+ * Reactive composable that tracks an element's dimensions with `ResizeObserver`
+ * and evaluates breakpoint conditions in JavaScript (Container Queries).
+ *
+ * Accepts a `Ref<Element | null>` (e.g. from `useTemplateRef`) — automatically
+ * sets up and tears down the observer as the element mounts / unmounts.
+ *
+ * @example
+ * <script setup>
+ * const cardRef = useTemplateRef('card');
+ * const cardState = useContainerState(cardRef, {
+ *   compact: [{ type: 'max-width', value: 300 }],
+ *   wide:    [{ type: 'min-width', value: 600 }],
+ * });
+ * </script>
+ *
+ * <template>
+ *   <div ref="card">
+ *     <CompactLayout v-if="cardState.compact" />
+ *     <WideLayout v-else-if="cardState.wide" />
+ *   </div>
+ * </template>
+ */
+export declare function useContainerState(elementRef: Ref<Element | null>, config: Record<string, MediaQueryConfig>, options?: SetConfigOptions): ResponsiveState;
+/**
+ * Vue plugin that registers the responsive state via `provide`.
+ *
+ * @example
+ * app.use(ResponsivePlugin, {
+ *   sm: [{ type: 'max-width', value: 640 }],
+ *   lg: [{ type: 'min-width', value: 1024 }],
+ * });
+ */
 export declare const ResponsivePlugin: {
-    install(app: App, config?: ResponsiveConfigType): void;
+    install(app: App, config?: Record<string, MediaQueryConfig>): void;
 };
-export {};

package/dist/vue-responsive.js

@@ -1,36 +1,171 @@
-import { inject, reactive } from '@vue/runtime-core';
+import { inject, reactive, ref, computed, watchEffect, onUnmounted, getCurrentInstance, } from '@vue/runtime-core';
 import { responsiveState, setResponsiveConfig } from './create-responsive';
+import { subscribeMediaQuery } from './media-query';
+import { createContainerState } from './container-state';
+// ---------------------------------------------------------------------------
+// Shared Vue reactive state (singleton per Vue app)
+// ---------------------------------------------------------------------------
 const RESPONSIVE_KEY = Symbol('responsiveState');
 let vueReactiveState = null;
+function ensureVueState() {
+    if (vueReactiveState)
+        return vueReactiveState;
+    vueReactiveState = reactive({ ...responsiveState.getState() });
+    responsiveState.subscribe((state) => {
+        Object.keys(vueReactiveState).forEach(key => {
+            if (!(key in state))
+                delete vueReactiveState[key];
+        });
+        Object.assign(vueReactiveState, state);
+    });
+    return vueReactiveState;
+}
+// ---------------------------------------------------------------------------
+// useResponsive
+// ---------------------------------------------------------------------------
+/**
+ * Returns the reactive responsive state.
+ * Generic `T` narrows the type for custom configs.
+ *
+ * @example
+ * type MyState = { sm: boolean; lg: boolean };
+ * const state = useResponsive<MyState>();
+ */
 export function useResponsive() {
-    const injected = inject(RESPONSIVE_KEY);
-    if (injected)
+    const injected = inject(RESPONSIVE_KEY, null);
+    if (injected !== null)
         return injected;
-    if (!vueReactiveState) {
-        vueReactiveState = reactive({ ...responsiveState.proxy });
-        responsiveState.subscribe((state) => {
-            Object.keys(state).forEach(key => {
-                // @ts-ignore
-                vueReactiveState[key] = state[key];
-            });
-        });
+    return ensureVueState();
+}
+/**
+ * Returns ordered breakpoint helpers that are **reactive in Vue templates
+ * and computed properties** — they read from the Vue reactive state and
+ * re-evaluate automatically on viewport changes.
+ *
+ * Requires a breakpoint `order` to be set via `setConfig` or `createResponsiveState`.
+ * Falls back to config key insertion order if none is provided.
+ *
+ * @example
+ * const { current, isAbove, isBelow, between } = useBreakpoints();
+ *
+ * // In template:
+ * // <DesktopNav v-if="isAbove('sm')" />
+ * // <span>{{ current }}</span>
+ */
+export function useBreakpoints() {
+    const state = ensureVueState();
+    // Reads from Vue reactive state → Vue tracks these as dependencies
+    function getCurrent() {
+        var _a;
+        const order = responsiveState.getOrder();
+        const keys = order.length ? order : Object.keys(state);
+        return (_a = keys.find(k => state[k])) !== null && _a !== void 0 ? _a : null;
     }
-    return vueReactiveState;
+    function getOrder() {
+        const order = responsiveState.getOrder();
+        return order.length ? order : Object.keys(state);
+    }
+    return {
+        current: computed(getCurrent),
+        isAbove(key) {
+            const ord = getOrder();
+            const cur = getCurrent();
+            return ord.indexOf(cur !== null && cur !== void 0 ? cur : '') > ord.indexOf(key);
+        },
+        isBelow(key) {
+            const ord = getOrder();
+            const cur = getCurrent();
+            const curIdx = ord.indexOf(cur !== null && cur !== void 0 ? cur : '');
+            const keyIdx = ord.indexOf(key);
+            return curIdx !== -1 && curIdx < keyIdx;
+        },
+        between(from, to) {
+            var _a;
+            const ord = getOrder();
+            const idx = ord.indexOf((_a = getCurrent()) !== null && _a !== void 0 ? _a : '');
+            return idx !== -1 && idx >= ord.indexOf(from) && idx <= ord.indexOf(to);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// useMediaQuery
+// ---------------------------------------------------------------------------
+/**
+ * Reactive composable for a single raw CSS media query string.
+ * Returns a `Ref<boolean>`. Cleans up automatically on `onUnmounted`.
+ *
+ * @example
+ * const isDark   = useMediaQuery('(prefers-color-scheme: dark)');
+ * const canHover = useMediaQuery('(hover: hover)');
+ */
+export function useMediaQuery(query) {
+    const matches = ref(false);
+    const off = subscribeMediaQuery(query, (v) => { matches.value = v; });
+    if (getCurrentInstance())
+        onUnmounted(off);
+    return matches;
+}
+// ---------------------------------------------------------------------------
+// useContainerState
+// ---------------------------------------------------------------------------
+/**
+ * Reactive composable that tracks an element's dimensions with `ResizeObserver`
+ * and evaluates breakpoint conditions in JavaScript (Container Queries).
+ *
+ * Accepts a `Ref<Element | null>` (e.g. from `useTemplateRef`) — automatically
+ * sets up and tears down the observer as the element mounts / unmounts.
+ *
+ * @example
+ * <script setup>
+ * const cardRef = useTemplateRef('card');
+ * const cardState = useContainerState(cardRef, {
+ *   compact: [{ type: 'max-width', value: 300 }],
+ *   wide:    [{ type: 'min-width', value: 600 }],
+ * });
+ * </script>
+ *
+ * <template>
+ *   <div ref="card">
+ *     <CompactLayout v-if="cardState.compact" />
+ *     <WideLayout v-else-if="cardState.wide" />
+ *   </div>
+ * </template>
+ */
+export function useContainerState(elementRef, config, options) {
+    const state = reactive({});
+    watchEffect((cleanup) => {
+        const el = elementRef.value;
+        if (!el)
+            return;
+        const cs = createContainerState(el, config, options);
+        const off = cs.subscribe((s) => {
+            Object.keys(state).forEach(k => { if (!(k in s))
+                delete state[k]; });
+            Object.assign(state, s);
+        });
+        cleanup(() => {
+            off();
+            cs.destroy();
+        });
+    });
+    return state;
 }
+// ---------------------------------------------------------------------------
+// ResponsivePlugin
+// ---------------------------------------------------------------------------
+/**
+ * Vue plugin that registers the responsive state via `provide`.
+ *
+ * @example
+ * app.use(ResponsivePlugin, {
+ *   sm: [{ type: 'max-width', value: 640 }],
+ *   lg: [{ type: 'min-width', value: 1024 }],
+ * });
+ */
 export const ResponsivePlugin = {
     install(app, config) {
-        if (config) {
+        if (config)
             setResponsiveConfig(config);
-        }
-        if (!vueReactiveState) {
-            vueReactiveState = reactive({ ...responsiveState.proxy });
-            responsiveState.subscribe((state) => {
-                Object.keys(state).forEach(key => {
-                    // @ts-ignore
-                    vueReactiveState[key] = state[key];
-                });
-            });
-        }
-        app.provide(RESPONSIVE_KEY, vueReactiveState);
+        app.provide(RESPONSIVE_KEY, ensureVueState());
     },
 };

package/package.json

@@ -1,49 +1,82 @@
-{
-  "name": "responsive-media",
-  "version": "1.0.7",
-  "description": "A utility for reactive state based on CSS media queries. Includes integration with Vue 3 (Composition API).",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/macrulezru/responsive-media.git"
-  },
-  "homepage": "https://macrulez.ru/#/en",
-  "bugs": {
-    "url": "https://github.com/macrulezru/responsive-media/issues"
-  },
-  "keywords": [
-    "responsive",
-    "media-query",
-    "typescript",
-    "reactive",
-    "utility"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/vue": "^1.0.31",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "eslint": "^9.39.2",
-    "eslint-plugin-vue": "^10.7.0",
-    "typescript": "^5.9.3"
-  },
-  "peerDependencies": {
-    "vue": "^3.5.27"
-  }
-}
+{
+  "name": "responsive-media",
+  "version": "1.2.0",
+  "description": "A utility for reactive state based on CSS media queries. Includes integration with Vue 3 (Composition API) and React 18+.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react-responsive.d.ts",
+      "import": "./dist/react-responsive.js",
+      "require": "./dist/react-responsive.js"
+    },
+    "./presets": {
+      "types": "./dist/presets.d.ts",
+      "import": "./dist/presets.js",
+      "require": "./dist/presets.js"
+    },
+    "./container": {
+      "types": "./dist/container-state.d.ts",
+      "import": "./dist/container-state.js",
+      "require": "./dist/container-state.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/macrulezru/responsive-media.git"
+  },
+  "homepage": "https://macrulez.ru/#/en",
+  "bugs": {
+    "url": "https://github.com/macrulezru/responsive-media/issues"
+  },
+  "keywords": [
+    "responsive",
+    "media-query",
+    "typescript",
+    "reactive",
+    "utility",
+    "vue",
+    "react"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/vue": "^1.0.31",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-vue": "^10.7.0",
+    "jsdom": "^26.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "vue": "^3.5.27"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}