Merge pull request #233 from graphieros/trunk

Trunk

Author: graphieros

README.md

@@ -1079,3 +1079,46 @@ Below is a table of the places where such line breaks can be used:
 ## PDF generation
 
 This package requires jspdf as a peer dependency. Please install it in your project if you intend on using the PDF printing feature.
+
+## `useObjectBindings`
+
+A composable that **flattens** a reactive object into a set of computed refs—one for each “leaf” property—so you can easily bind to deeply nested values by their string paths.
+
+### Why use it?
+
+- **Automatic reactivity**: Every nested property becomes a `ComputedRef`, with automatic getters/setters that keep your source object in sync.
+- **Flat API surface**: Access or update any nested field by its dot‑delimited path, without writing deep destructuring or `ref` plumbing.
+- **Dynamic path support**: New paths added at runtime are discovered automatically (and proxied), so you never lose reactivity when mutating the structure.
+
+```js
+import { useObjectBindings } from "vue-data-ui";
+import type { Ref, ComputedRef } from "vue";
+
+const config = ref({
+  customPalette: ["#CCCCCC", "#1A1A1A"],
+  style: {
+    chart: {
+      backgroundColor: "#FFFFFF",
+      color: "#1A1A1A",
+    },
+  },
+});
+
+const bindings = useObjectBindings(config);
+// Now `bindings` has computed refs for each leaf path:
+//   bindings["style.chart.backgroundColor"] → ComputedRef<string>
+//   bindings["style.chart.color"] → ComputedRef<string>
+//   bindings["customPalette"] → ComputedRef<boolean>
+//   // by default, arrays are skipped:
+//   // no "customPalette.0", unless you disable skipArrays
+```
+
+You can then use these in your template:
+
+```html
+<template>
+  <div>
+    <input type="color" v-model="bindings['style.chart.backgroundColor']" />
+  </div>
+</template>
+```

TestingArena/ArenaVueUiXy.vue

@@ -376,8 +376,8 @@ const model = ref([
     { key: 'useCanvas', def: false, type: 'checkbox' }, // DEPRECATED (removed)
     { key: 'useCssAnimation', def: true, type: 'checkbox', label: 'useCssAnimation', category: 'general' },
     { key: 'chart.fontFamily', def: 'inherit', type: 'text', label: 'fontFamily', category: 'general' },
-    { key: 'chart.backgroundColor', def: 'transparent', type: 'color', label: 'backgroundColor', category: 'general' },
-    { key: 'chart.color', def: '#FFFFFF', type: 'color', label: 'textColor', category: 'general' },
+    { key: 'chart.backgroundColor', def: '#FFF', type: 'color', label: 'backgroundColor', category: 'general' },
+    { key: 'chart.color', def: '#111', type: 'color', label: 'textColor', category: 'general' },
     { key: 'chart.height', def: 600, type: 'range', min: 300, max: 1000, label: 'height', category: 'general' },
     { key: 'chart.width', def: 1000, type: 'range', min: 300, max: 2000, label: 'width', category: 'general' },
     { key: 'chart.zoom.show', def: true, type: 'checkbox', label: 'zoom', category: 'general' },

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-data-ui",
   "private": false,
-  "version": "2.15.5",
+  "version": "2.15.6-beta.3",
   "type": "module",
   "description": "A user-empowering data visualization Vue 3 components library for eloquent data storytelling",
   "keywords": [

package.json

@@ -3,6 +3,7 @@ import getVueDataUiConfig from "./getVueDataUiConfig";
 import getThemeConfig from "./getThemeConfig";
 import { getPalette, createWordCloudDatasetFromPlainText, abbreviate, createTSpans, createStraightPath, createSmoothPath, getCumulativeAverage, getCumulativeMedian } from "./lib";
 import { lightenColor, darkenColor, shiftColorHue, mergeConfigs } from "./exposedLib";
+import { useObjectBindings } from "./useObjectBindings";
 
 export const Arrow = defineAsyncComponent(() => import("./atoms/Arrow.vue"))
 export const VueDataUi = defineAsyncComponent(() => import("./components/vue-data-ui.vue"))
@@ -85,4 +86,5 @@ export {
     lightenColor,
     mergeConfigs,
     shiftColorHue,
+    useObjectBindings
 }

src/index.js

@@ -393,19 +393,25 @@ export const opacity = ["00", "03", "05", "08", "0A", "0D", "0F", "12", "14", "1
 
 export function convertColorToHex(color) {
     const hexRegex = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i;
+    const shorthandRegex = /^#?([a-f\d])([a-f\d])([a-f\d])([a-f\d])?$/i;
     const rgbRegex = /^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)$/i;
     const hslRegex = /^hsla?\((\d+),\s*([\d.]+)%,\s*([\d.]+)%(?:,\s*([\d.]+))?\)$/i;
 
-    if ([undefined, null, NaN].includes(color)) {
+    if (color === undefined || color === null || (typeof color === 'number' && isNaN(color))) {
         return null;
     }
 
     color = convertNameColorToHex(color);
 
+
     if (color === 'transparent') {
         return "#FFFFFF00";
     }
 
+    color = color.replace(shorthandRegex, (_, r, g, b, a) => {
+        return `#${r}${r}${g}${g}${b}${b}${a ? a + a : ''}`;
+    });
+
     let match;
     let alpha = 1;
 
@@ -420,8 +426,8 @@ export function convertColorToHex(color) {
     } else if ((match = color.match(hslRegex))) {
         const [, h, s, l, a] = match;
         alpha = a ? parseFloat(a) : 1;
-        const rgb = hslToRgba(Number(h), Number(s), Number(l));
-        return `#${decimalToHex(rgb[0])}${decimalToHex(rgb[1])}${decimalToHex(rgb[2])}${decimalToHex(Math.round(alpha * 255))}`;
+        const [rr, gg, bb] = hslToRgba(Number(h), Number(s), Number(l));
+        return `#${decimalToHex(rr)}${decimalToHex(gg)}${decimalToHex(bb)}${decimalToHex(Math.round(alpha * 255))}`;
     }
 
     return null;

src/lib.js

@@ -5605,6 +5605,7 @@ export function useConfig() {
                                 buttons: {
                                     ...vue_ui_xy.chart.userOptions.buttons,
                                     pdf: false,
+                                    fullscreen: false,
                                 }
                             },
                             zoom: {
@@ -5836,4 +5837,4 @@ export function useConfig() {
         vue_ui_digits,
         vue_ui_circle_pack
     }
-}
+}

src/useConfig.js

@@ -0,0 +1,151 @@
+import { computed, isRef, markRaw, watch, watchEffect } from 'vue';
+
+/**
+ * Recursively extract all dot-paths to leaf values in an object.
+ * Skips arrays entirely when skipArrays = true.
+ *
+ * @param {unknown} obj
+ * @param {string[]} [current=[]]
+ * @param {boolean} [skipArrays=true]
+ * @returns {string[][]}
+ */
+export function extractAllPaths(obj, current = [], skipArrays = true) {
+    /** @type {string[][]} */
+    const paths = [];
+
+    if (obj && typeof obj === 'object') {
+        if (Array.isArray(obj) && skipArrays) {
+            return [];
+        }
+        for (const key of Object.keys(obj)) {
+            const val = /** @type {any} */ (obj)[key];
+            if (Array.isArray(val) && skipArrays) {
+                continue;
+            }
+            const next = current.concat(key);
+            if (val && typeof val === 'object') {
+                paths.push(...extractAllPaths(val, next, skipArrays));
+            } else {
+                paths.push(next);
+            }
+        }
+    }
+    return paths;
+}
+
+/**
+ * Get nested value by path.
+ * @param {any} obj
+ * @param {string[]} path
+ * @returns {any}
+ */
+export function getValue(obj, path) {
+    return path.reduce((o, k) => o?.[k], obj);
+}
+
+/**
+ * Set nested value by path, creating intermediate objects as needed.
+ * @param {any} obj
+ * @param {string[]} path
+ * @param {any} value
+ */
+export function setValue(obj, path, value) {
+    let target = isRef(obj) ? obj.value : obj;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        if (
+            !Object.prototype.hasOwnProperty.call(target, key) ||
+            typeof target[key] !== 'object'
+        ) {
+            target[key] = {};
+        }
+        target = target[key];
+    }
+    target[path[path.length - 1]] = value;
+}
+
+/**
+ * Set nested property on an object by a dot-delimited path, creating intermediate
+ * objects as needed. Similar to setValue but accepts a string path.
+ *
+ * @param {object} obj - The object to modify.
+ * @param {string} path - Dot-delimited string path.
+ * @param {*} value - The value to set at the target path.
+ * @param {string} delimiter - The delimiter used to split the path.
+ */
+function setPropertyByPath(obj, path, value, delimiter) {
+    const keys = path.split(delimiter);
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i += 1) {
+        const key = keys[i];
+        if (!current[key]) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[keys[keys.length - 1]] = value;
+}
+
+export function useObjectBindings(configRef, options) {
+    const { delimiter = '.', skipArrays = true } = options || {};
+    const bindings = {};
+
+    function build() {
+        Object.keys(bindings).forEach((k) => delete bindings[k]);
+        const paths = extractAllPaths(configRef.value, [], skipArrays);
+        for (const path of paths) {
+            const key = path.join(delimiter)
+            bindings[key] = computed({
+                get: () => getValue(configRef.value, path),
+                set: (val) => setValue(configRef.value, path, val),
+            });
+        }
+    }
+
+    watchEffect(build);
+    build();
+
+    const handler = {
+        get(target, prop) {
+            // let Vue's private props and symbols through
+            if (typeof prop === 'string' || prop.startsWith('__v_')) {
+                if (prop in target) {
+                    return Reflect.get(target, prop);
+                } else {
+                    // prop doesn't exist on target, add it and return
+                    setPropertyByPath(configRef.value, prop, undefined, delimiter);
+                    bindings[prop] = computed({
+                        get: () => getValue(configRef.value, prop),
+                        set: (val) => setValue(configRef.value, prop, val)
+                    });
+                    if (!prop.startsWith('__v_')) {
+                        console.warn(`Vue Data UI - useObjectBindings: no binding found for key "${prop}". Please verify you are binding to a property path which exists on the object.`);
+                    }
+                    return ''; // Signals to Vue there is something to be tracked, so to hand the computed on the next read
+                }
+            }
+            return true;
+        },
+        set(target, prop, value) {
+            if (typeof prop === 'string' || prop.startsWith('__v_')) {
+                if (prop in target) {
+                    return Reflect.set(target, prop, value);
+                } else {
+                    // prop doesn't exist on target, add it and return
+                    setPropertyByPath(configRef.value, prop, value, delimiter);
+                    bindings[prop] = computed({
+                        get: () => getValue(configRef.value, prop),
+                        set: (val) => setValue(configRef.value, prop, val)
+                    });
+                    if(!prop.startsWith('__v_')) {
+                        console.warn(`Vue Data UI - useObjectBindings: cannot set unknown binding "${prop}".`);
+                    }
+                    return true;
+                }
+            }
+            return true;
+        }
+    };
+
+    return markRaw(new Proxy(bindings, handler));
+}

src/useObjectBindings.js

@@ -399,6 +399,23 @@ describe("convertColorToHex", () => {
         const result = convertColorToHex("hsla(0, 100%, 50%, 0.5)");
         expect(result).toBe("#ff000080");
     });
+
+    test("returns HEX color format from shorthand hex codes (#RGB, #RGBA)", () => {
+        expect(convertColorToHex("#ABC")).toBe("#AABBCCff");
+        expect(convertColorToHex("ABC")).toBe("#AABBCCff");
+        expect(convertColorToHex("#abc")).toBe("#aabbccff");
+        expect(convertColorToHex("abc")).toBe("#aabbccff");
+        expect(convertColorToHex("#ABC8")).toBe("#AABBCC88");
+        expect(convertColorToHex("ABC8")).toBe("#AABBCC88");
+        expect(convertColorToHex("#abc8")).toBe("#aabbcc88");
+        expect(convertColorToHex("abc8")).toBe("#aabbcc88");
+    });
+
+    test("returns null for invalid or empty input", () => {
+        expect(convertColorToHex(null)).toBeNull();
+        expect(convertColorToHex(undefined)).toBeNull();
+        expect(convertColorToHex("not-a-color")).toBeNull();
+    });
 });
 
 describe("shiftHue", () => {