orio-ui 1.15.0 → 1.16.0

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0 || ^4.0.0"
   },
-  "version": "1.15.0",
+  "version": "1.16.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/useUrlSync.d.ts

@@ -0,0 +1,38 @@
+import { Ref } from "vue";
+/**
+ * Syncs a reactive object's keys to/from URL query params.
+ *
+ * Behaviour:
+ * - **On call (synchronous)**: reads current URL params and pre-populates the
+ *   state so child components see the correct values before they mount.
+ * - **Reactive**: watches the state and updates the URL whenever synced keys
+ *   change (via `router.replace` — no new history entry).
+ *
+ * SSR-safe: initial population uses `route.query` (available on the server),
+ * so the server renders the same HTML as the client hydrates — no mismatches.
+ * Reactive URL writes use `useUrlSearchParams` (client-only, via window).
+ *
+ * Value handling:
+ * - Nested objects  → dot notation    (`filters.category=shirts`)
+ * - Arrays          → bracket notation (`tags[0]=cats&tags[1]=dogs`)
+ * - Combinations    → mixed           (`items[0].name=John`)
+ * - File / Blob     → silently skipped (not serialisable)
+ * - Empty strings   → removed from URL
+ *
+ * @param state  Reactive object to sync
+ * @param keys   Explicit list of top-level keys to sync.
+ *               When omitted, ALL top-level keys currently in the URL are
+ *               used for initial population, and ALL keys in the state are
+ *               watched going forward.
+ *
+ * @example
+ * // Sync specific keys (recommended — avoids accidentally syncing private state)
+ * const properties = ref<Record<string, string | File[]>>({})
+ * useUrlSync(properties, ['variant', 'size', 'product-color'])
+ *
+ * @example
+ * // Sync all — useful when state IS the URL state
+ * const filters = ref({ category: '', sort: 'newest' })
+ * useUrlSync(filters)
+ */
+export declare function useUrlSync(state: Ref<Record<string, unknown>>, keys?: string[]): void;

package/dist/runtime/composables/useUrlSync.js

@@ -0,0 +1,37 @@
+import { useUrlSearchParams } from "@vueuse/core";
+import {
+  flattenParams,
+  unflattenParams,
+  topLevelKeys
+} from "../utils/urlParams.js";
+import { computed, watch } from "vue";
+export function useUrlSync(state, keys) {
+  const routeQuery = useRoute().query;
+  const initKeys = keys ?? topLevelKeys(routeQuery);
+  for (const key of initKeys) {
+    const flat = {};
+    for (const [k, v] of Object.entries(routeQuery)) {
+      if (v !== null && (k === key || k.startsWith(`${key}.`) || k.startsWith(`${key}[`))) {
+        flat[k] = v;
+      }
+    }
+    if (Object.keys(flat).length === 0) continue;
+    const reconstructed = unflattenParams(flat);
+    if (key in reconstructed) state.value[key] = reconstructed[key];
+  }
+  const urlParams = useUrlSearchParams("history");
+  const syncKeys = computed(() => keys ?? Object.keys(state.value));
+  watch(
+    () => syncKeys.value.map((k) => JSON.stringify(flattenParams(state.value[k], k))).join("|"),
+    () => {
+      for (const key of syncKeys.value) {
+        for (const k of Object.keys(urlParams)) {
+          if (k === key || k.startsWith(`${key}.`) || k.startsWith(`${key}[`)) {
+            delete urlParams[k];
+          }
+        }
+        Object.assign(urlParams, flattenParams(state.value[key], key));
+      }
+    }
+  );
+}

package/dist/runtime/index.d.ts

@@ -38,3 +38,5 @@ export { usePressAndHold } from "./composables/usePressAndHold.js";
 export { useSound, type SoundOptions } from "./composables/useSound.js";
 export { useValidation, isFilled, isEmail, type ValidationRule, } from "./composables/useValidation.js";
 export { iconRegistry, type IconName } from "./utils/icon-registry.js";
+export { flattenParams, unflattenParams, parsePath, topLevelKeys, } from "./utils/urlParams.js";
+export { useUrlSync } from "./composables/useUrlSync.js";

package/dist/runtime/index.js

@@ -50,3 +50,10 @@ export {
   isEmail
 } from "./composables/useValidation.js";
 export { iconRegistry } from "./utils/icon-registry.js";
+export {
+  flattenParams,
+  unflattenParams,
+  parsePath,
+  topLevelKeys
+} from "./utils/urlParams.js";
+export { useUrlSync } from "./composables/useUrlSync.js";

package/dist/runtime/utils/urlParams.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Utilities for serialising/deserialising nested values to/from flat URL query params.
+ *
+ * Encoding conventions:
+ *   Object keys  →  dot notation      e.g.  filters.category=shirts
+ *   Array items  →  bracket notation  e.g.  tags[0]=cats&tags[1]=dogs
+ *   Combined     →                    e.g.  items[0].name=John
+ *
+ * Non-serialisable values (File, Blob, null, undefined) are silently skipped.
+ * Empty strings produce no URL entry.
+ */
+/**
+ * Recursively flattens a value to flat URL-compatible key-value pairs.
+ *
+ * @param value   The value to flatten (any depth)
+ * @param prefix  URL param prefix / key name (e.g. "filters", "items[0]")
+ *
+ * @example
+ * flattenParams({ category: 'shirts', tags: ['a', 'b'] }, 'filters')
+ * // → { 'filters.category': 'shirts', 'filters.tags[0]': 'a', 'filters.tags[1]': 'b' }
+ */
+export declare function flattenParams(value: unknown, prefix: string): Record<string, string>;
+/**
+ * Reconstructs a nested object from flat URL query params.
+ * Handles dot notation (obj.key) and bracket notation (arr[0]), and combinations.
+ *
+ * When a URL param has multiple values (string[]) only the first is used.
+ *
+ * @example
+ * unflattenParams({ 'filters.category': 'shirts', 'tags[0]': 'cats', 'tags[1]': 'dogs' })
+ * // → { filters: { category: 'shirts' }, tags: ['cats', 'dogs'] }
+ */
+export declare function unflattenParams(flat: Record<string, string | string[]>): Record<string, unknown>;
+/**
+ * Parses a flat URL param key into path segments.
+ *
+ * Supports dot notation and bracket notation, including keys with hyphens.
+ *
+ * @example
+ * parsePath('a.b.c')          // ['a', 'b', 'c']
+ * parsePath('product-color')  // ['product-color']
+ * parsePath('items[0].name')  // ['items', 0, 'name']
+ * parsePath('a[0][1].c')      // ['a', 0, 1, 'c']
+ */
+export declare function parsePath(path: string): (string | number)[];
+/**
+ * Extracts the distinct top-level keys from a flat params record.
+ *
+ * @example
+ * topLevelKeys({ 'a': '1', 'b.c': '2', 'd[0]': '3' }) // ['a', 'b', 'd']
+ */
+export declare function topLevelKeys(flat: Record<string, unknown>): string[];

package/dist/runtime/utils/urlParams.js

@@ -0,0 +1,67 @@
+export function flattenParams(value, prefix) {
+  const result = {};
+  _flatten(value, prefix, result);
+  return result;
+}
+function _flatten(value, key, out) {
+  if (value === null || value === void 0) return;
+  if (value instanceof File || value instanceof Blob) return;
+  if (typeof value === "string") {
+    if (value !== "") out[key] = value;
+    return;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    out[key] = String(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const [i, item] of value.entries()) {
+      _flatten(item, `${key}[${i}]`, out);
+    }
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) {
+      _flatten(v, `${key}.${k}`, out);
+    }
+  }
+}
+export function unflattenParams(flat) {
+  const result = {};
+  for (const [key, raw] of Object.entries(flat)) {
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (value === void 0 || value === "") continue;
+    _setByPath(result, parsePath(key), value);
+  }
+  return result;
+}
+function _setByPath(root, path, value) {
+  if (path.length === 0) return;
+  let current = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const seg = path[i];
+    const nextSeg = path[i + 1];
+    const parent = current;
+    if (parent[seg] == null || typeof parent[seg] !== "object") {
+      parent[seg] = typeof nextSeg === "number" ? [] : {};
+    }
+    current = parent[seg];
+  }
+  const lastSeg = path[path.length - 1];
+  current[lastSeg] = value;
+}
+export function parsePath(path) {
+  const segments = [];
+  for (const match of path.matchAll(/([^.[]+)|\[(\d+)\]/g)) {
+    segments.push(match[1] !== void 0 ? match[1] : parseInt(match[2], 10));
+  }
+  return segments;
+}
+export function topLevelKeys(flat) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const k of Object.keys(flat)) {
+    const match = k.match(/^([^.[]+)/);
+    if (match) keys.add(match[1]);
+  }
+  return [...keys];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orio-ui",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Modern Nuxt component library with theme support",
   "type": "module",
   "main": "./dist/module.mjs",