cabbage-react 1.0.0 → 1.0.2

package/README.md

@@ -20,8 +20,10 @@ npm install cabbage-react
 
 Synchronize a parameter with Cabbage. This hook:
 
-- Listens for value updates from Cabbage.
-- Sends local changes (e.g., via sliders, knobs) back to Cabbage.
+- Identifies and sets the default value defined in Cabbage to the state.
+- Handles initialization when opening an existing session, or reopening the plugin window.
+- Listens for value updates from the host (DAW), or from Csound.
+- Sends changes back to Cabbage when using the provided value-setter.
 
 ### useCabbageProperties
 
@@ -33,21 +35,28 @@ This hook:
 
 ## Usage
 
-```jsx
+```tsx
 import { InputHTMLAttributes } from "react";
 import { useCabbageProperties, useCabbageState } from "cabbage-react";
 
 const HorizontalSlider = ({
-	channel,
-	paramIdx,
+	channelId,
+	parameterIndex,
 	inputProps,
 }: {
-	channel: string,
-	paramIdx: number,
-	inputProps?: InputHTMLAttributes<HTMLInputElement>,
+	channelId: string;
+	parameterIndex: number;
+	inputProps?: InputHTMLAttributes<HTMLInputElement>;
 }) => {
-	const { properties } = useCabbageProperties(channel);
-	const { value, setValue } = useCabbageState < number > (channel, paramIdx);
+	const { properties } = useCabbageProperties(channelId);
+	const channelProperties = properties?.channels.find(
+		(c: any) => c.id === channelId
+	);
+
+	const { value, setValue } = useCabbageState<number>(
+		channelId,
+		parameterIndex
+	);
 
 	return (
 		<div>
@@ -56,9 +65,9 @@ const HorizontalSlider = ({
 
 			<input
 				type="range"
-				min={properties?.range?.min ?? 0}
-				max={properties?.range?.max ?? 1}
-				step={properties?.range?.increment ?? 0.01}
+				min={channelProperties?.range?.min ?? 0}
+				max={channelProperties?.range?.max ?? 1}
+				step={channelProperties?.range?.increment ?? 0.01}
 				value={value}
 				onChange={(e) => setValue(e.target.valueAsNumber)}
 				{...inputProps}

package/dist/cabbage/cabbage.d.ts

@@ -1,9 +1,25 @@
 export class Cabbage {
+    /**
+     * Main entry point for sending any data from UI widgets to the Cabbage backend.
+     * This function automatically routes messages to the appropriate backend function
+     * based on the automatable flag:
+     *
+     * - automatable=1: Routes to sendParameterUpdate for real-time parameter control /
+     *                              this also sends the value as channel data to Csound
+     *
+     * - automatable=0: Routes to sendChannelData for string/numeric data transmission
+     *
+     * All widget interactions should use this function instead of calling the lower-level
+     * sendParameterUpdate or sendChannelData functions directly.
+     */
+    static sendChannelUpdate(message: any, vscode?: null, automatable?: number): void;
     static sendParameterUpdate(message: any, vscode?: null): void;
     static sendCustomCommand(command: any, vscode?: null): void;
     static sendWidgetUpdate(widget: any, vscode?: null): void;
     static sendMidiMessageFromUI(statusByte: any, dataByte1: any, dataByte2: any, vscode?: null): void;
+    static sendChannelData(channel: any, data: any, vscode?: null): void;
     static MidiMessageFromHost(statusByte: any, dataByte1: any, dataByte2: any): void;
-    static triggerFileOpenDialog(vscode: any, channel: any): void;
+    static triggerFileOpenDialog(vscode: any, channel: any, options?: {}): void;
+    static openUrl(vscode: any, url: any, file: any): void;
 }
 //# sourceMappingURL=cabbage.d.ts.map

package/dist/cabbage/cabbage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cabbage.d.ts","sourceRoot":"","sources":["../../src/cabbage/cabbage.js"],"names":[],"mappings":"AAMA;IAEE,8DAYC;IAED,4DAYC;IAED,0DAYC;IAED,mGAmBC;IAED,kFAEC;IAED,8DAeC;CAGF"}
+{"version":3,"file":"cabbage.d.ts","sourceRoot":"","sources":["../../src/cabbage/cabbage.js"],"names":[],"mappings":"AAMA;IAEE;;;;;;;;;;;;OAYG;IACH,kFASC;IAED,8DAcC;IAED,4DAYC;IAED,0DAYC;IAED,mGAmBC;IAED,qEA2BC;IAED,kFAEC;IAED,4EAkBC;IAED,uDAgBC;CAGF"}

package/dist/hooks/useCabbageProperties.d.ts

@@ -3,7 +3,7 @@
  * This hook listens for updates to parameter properties via Cabbage and updates the local state
  * whenever new data is received.
  */
-export declare const useCabbageProperties: (channel: string) => {
+export declare const useCabbageProperties: (channelId: string) => {
     properties: Record<string, any> | undefined;
 };
 //# sourceMappingURL=useCabbageProperties.d.ts.map

package/dist/hooks/useCabbageProperties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCabbageProperties.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageProperties.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAa,MAAM;;CAgCnD,CAAC"}
+{"version":3,"file":"useCabbageProperties.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageProperties.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,cAAe,MAAM;;CAgCrD,CAAC"}

package/dist/hooks/useCabbageState.d.ts

@@ -3,7 +3,7 @@
  * This hook listens for updates to a parameter value from Cabbage and
  * sends updates to Cabbage when the parameter value changes locally (e.g., through a UI slider).
  */
-export declare const useCabbageState: <T>(channel: string, paramIdx: number) => {
+export declare const useCabbageState: <T>(channelId: string, parameterIndex: number) => {
     value: T | undefined;
     setValue: (newValue: T) => void;
 };

package/dist/hooks/useCabbageState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCabbageState.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageState.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,WAAW,MAAM,YAAY,MAAM;;yBAM9B,CAAC;CAwFtC,CAAC"}
+{"version":3,"file":"useCabbageState.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageState.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,aACrB,MAAM,kBACD,MAAM;;yBAMe,CAAC;CA6EtC,CAAC"}

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("react");console.log("Cabbage: loading cabbage.js");class p{static sendParameterUpdate(n,e=null){const a={command:"parameterChange",obj:JSON.stringify(n)};e!==null?e.postMessage(a):(console.log("Cabbage: sending parameter change from UI",a),window.sendMessageFromUI(a))}static sendCustomCommand(n,e=null){const a={command:n,text:JSON.stringify({})};console.log("Cabbage: sending custom command from UI",a),e!==null?e.postMessage(a):window.sendMessageFromUI(a)}static sendWidgetUpdate(n,e=null){console.log("Cabbage: sending widget update from UI",n.props);const a={command:"widgetStateUpdate",obj:JSON.stringify(n.props)};e!==null?e.postMessage(a):window.sendMessageFromUI(a)}static sendMidiMessageFromUI(n,e,a,t=null){var r={statusByte:n,dataByte1:e,dataByte2:a};const o={command:"midiMessage",obj:JSON.stringify(r)};console.log("Cabbage: sending midi message from UI",r),t!==null?t.postMessage(o):window.sendMessageFromUI(o)}static MidiMessageFromHost(n,e,a){console.log("Cabbage: Got MIDI Message"+n+":"+e+":"+a)}static triggerFileOpenDialog(n,e){var a={channel:e};const t={command:"fileOpen",obj:JSON.stringify(a)};n!==null?n.postMessage(t):window.sendMessageFromUI(t)}}const C=l=>{const[n,e]=d.useState();return d.useEffect(()=>{const a=t=>{const{channel:r,data:o,command:f}=t.data;if(r===l&&o&&f==="widgetUpdate"){const m=JSON.parse(o);console.log(`[Cabbage-React] ${f}: Received properties for channel: ${r}`,m),e(m)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{properties:n}},h=(l,n)=>{const{properties:e}=C(l),[a,t]=d.useState(),[r,o]=d.useState(),f=s=>{t(s);const i={paramIdx:n,channelType:r,channel:l,value:s};p.sendParameterUpdate(i,null)},m=s=>{if(typeof s=="number")return"number";if(typeof s=="string")return"string"};return d.useEffect(()=>{var i;if((e==null?void 0:e.channel)!==l)return;const s=(i=e==null?void 0:e.range)==null?void 0:i.defaultValue;if(a===void 0&&s!==void 0){console.log(`[Cabbage-React]: Received default value for channel "${e==null?void 0:e.channel}"`,s),t(s);const c=m(s);c&&o(c)}},[e]),d.useEffect(()=>{const s=i=>{const{command:c}=i.data;if(c==="widgetUpdate"){const{channel:u,value:g}=i.data;if(u!==l)return;if(console.log(`[Cabbage-React] ${c}: Received initial value for channel "${u}"`,g),g!==void 0){t(g);const b=m(g);b&&o(b)}}if(c==="parameterChange"){const{paramIdx:u,value:g}=i.data.data||{};u===n&&g!==void 0&&(console.log(`[Cabbage-React] ${c}: Received value change for paramIdx: ${u}`,g),t(g))}};return window.addEventListener("message",s),()=>{window.removeEventListener("message",s)}},[]),{value:a,setValue:f}};exports.Cabbage=p;exports.useCabbageProperties=C;exports.useCabbageState=h;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("react");console.log("Cabbage: loading cabbage.js");class c{static sendChannelUpdate(n,e=null,a=0){if(a===1)c.sendParameterUpdate(n,e);else{const s=n.value!==void 0?n.value:n.stringData||n.floatData;c.sendChannelData(n.channel,s,e)}}static sendParameterUpdate(n,e=null){const a={command:"parameterChange",...n};console.log("Cabbage.sendParameterUpdate:",n,"vscode:",e,"msg:",a),e!==null?(console.log("Sending via vscode.postMessage"),e.postMessage(a)):(console.log("Sending via window.sendMessageFromUI"),window.sendMessageFromUI(a))}static sendCustomCommand(n,e=null){const a={command:n,text:JSON.stringify({})};console.log("Cabbage: sending custom command from UI",a),e!==null?e.postMessage(a):window.sendMessageFromUI(a)}static sendWidgetUpdate(n,e=null){console.log("Cabbage: sending widget update from UI",n.props);const a={command:"widgetStateUpdate",obj:JSON.stringify(CabbageUtils.sanitizeForEditor(n))};e!==null?e.postMessage(a):window.sendMessageFromUI(a)}static sendMidiMessageFromUI(n,e,a,s=null){var t={statusByte:n,dataByte1:e,dataByte2:a};const o={command:"midiMessage",obj:JSON.stringify(t)};console.log("Cabbage: sending midi message from UI",t),s!==null?s.postMessage(o):window.sendMessageFromUI(o)}static sendChannelData(n,e,a=null){var s={channel:n};if(typeof e=="string")s.stringData=e;else if(typeof e=="number")s.floatData=e;else{console.warn("Cabbage: sendChannelData received unsupported data type:",typeof e);return}const t={command:"channelData",obj:JSON.stringify(s)};console.log("Cabbage: sending channel data from UI",s),a!==null?a.postMessage(t):window.sendMessageFromUI(t)}static MidiMessageFromHost(n,e,a){console.log("Cabbage: Got MIDI Message"+n+":"+e+":"+a)}static triggerFileOpenDialog(n,e,a={}){var s={channel:e,directory:a.directory||"",filters:a.filters||"*",openAtLastKnownLocation:a.openAtLastKnownLocation!==void 0?a.openAtLastKnownLocation:!0};const t={command:"fileOpen",obj:JSON.stringify(s)};n!==null?n.postMessage(t):window.sendMessageFromUI(t)}static openUrl(n,e,a){var s={url:e,file:a};const t={command:"openUrl",obj:JSON.stringify(s)};n!==null?n.postMessage(t):window.sendMessageFromUI(t)}}const u=r=>{const[n,e]=g.useState();return g.useEffect(()=>{const a=s=>{const{id:t,widgetJson:o,command:l}=s.data;if(t===r&&o&&l==="widgetUpdate"){const i=JSON.parse(o);console.log(`[Cabbage-React] Received properties for channelId ${t}`,i),e(i)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{properties:n}},f=(r,n)=>{const{properties:e}=u(r),[a,s]=g.useState(),t=o=>{s(o);const l={paramIdx:n,channel:r,value:o};c.sendParameterUpdate(l,null)};return g.useEffect(()=>{var d;const o=e==null?void 0:e.value;if(o!=null){console.log(`[Cabbage-React] Received initial value for channelId "${r}"`,o),s(o);return}const l=e==null?void 0:e.channels.find(m=>m.id===r);if(!l)return;const i=(d=l.range)==null?void 0:d.defaultValue;a===void 0&&i!==void 0&&(console.log(`[Cabbage-React] Received default value for channelId "${l.id}"`,i),s(i))},[e]),g.useEffect(()=>{const o=l=>{const{command:i}=l.data;if(i==="parameterChange"){const{value:d,paramIdx:m}=l.data;if(m!==n||d===null)return;console.log(`[Cabbage-React] Received value change for parameterIndex ${m}`,d),s(d)}};return window.addEventListener("message",o),()=>{window.removeEventListener("message",o)}},[]),{value:a,setValue:t}};exports.Cabbage=c;exports.useCabbageProperties=u;exports.useCabbageState=f;

package/dist/index.mjs

@@ -1,132 +1,177 @@
-import { useState as f, useEffect as b } from "react";
+import { useState as u, useEffect as m } from "react";
 console.log("Cabbage: loading cabbage.js");
-class C {
-  static sendParameterUpdate(n, e = null) {
-    const a = {
+class c {
+  /**
+   * Main entry point for sending any data from UI widgets to the Cabbage backend.
+   * This function automatically routes messages to the appropriate backend function
+   * based on the automatable flag:
+   * 
+   * - automatable=1: Routes to sendParameterUpdate for real-time parameter control /
+   *                              this also sends the value as channel data to Csound
+   * 
+   * - automatable=0: Routes to sendChannelData for string/numeric data transmission
+   * 
+   * All widget interactions should use this function instead of calling the lower-level
+   * sendParameterUpdate or sendChannelData functions directly.
+   */
+  static sendChannelUpdate(a, e = null, n = 0) {
+    if (n === 1)
+      c.sendParameterUpdate(a, e);
+    else {
+      const s = a.value !== void 0 ? a.value : a.stringData || a.floatData;
+      c.sendChannelData(a.channel, s, e);
+    }
+  }
+  static sendParameterUpdate(a, e = null) {
+    const n = {
       command: "parameterChange",
-      obj: JSON.stringify(n)
+      ...a
     };
-    e !== null ? e.postMessage(a) : (console.log("Cabbage: sending parameter change from UI", a), window.sendMessageFromUI(a));
+    console.log("Cabbage.sendParameterUpdate:", a, "vscode:", e, "msg:", n), e !== null ? (console.log("Sending via vscode.postMessage"), e.postMessage(n)) : (console.log("Sending via window.sendMessageFromUI"), window.sendMessageFromUI(n));
   }
-  static sendCustomCommand(n, e = null) {
-    const a = {
-      command: n,
+  static sendCustomCommand(a, e = null) {
+    const n = {
+      command: a,
       text: JSON.stringify({})
     };
-    console.log("Cabbage: sending custom command from UI", a), e !== null ? e.postMessage(a) : window.sendMessageFromUI(a);
+    console.log("Cabbage: sending custom command from UI", n), e !== null ? e.postMessage(n) : window.sendMessageFromUI(n);
   }
-  static sendWidgetUpdate(n, e = null) {
-    console.log("Cabbage: sending widget update from UI", n.props);
-    const a = {
+  static sendWidgetUpdate(a, e = null) {
+    console.log("Cabbage: sending widget update from UI", a.props);
+    const n = {
       command: "widgetStateUpdate",
-      obj: JSON.stringify(n.props)
+      obj: JSON.stringify(CabbageUtils.sanitizeForEditor(a))
     };
-    e !== null ? e.postMessage(a) : window.sendMessageFromUI(a);
+    e !== null ? e.postMessage(n) : window.sendMessageFromUI(n);
   }
-  static sendMidiMessageFromUI(n, e, a, t = null) {
-    var d = {
-      statusByte: n,
+  static sendMidiMessageFromUI(a, e, n, s = null) {
+    var t = {
+      statusByte: a,
       dataByte1: e,
-      dataByte2: a
+      dataByte2: n
     };
     const o = {
       command: "midiMessage",
-      obj: JSON.stringify(d)
+      obj: JSON.stringify(t)
+    };
+    console.log("Cabbage: sending midi message from UI", t), s !== null ? s.postMessage(o) : window.sendMessageFromUI(o);
+  }
+  static sendChannelData(a, e, n = null) {
+    var s = {
+      channel: a
+    };
+    if (typeof e == "string")
+      s.stringData = e;
+    else if (typeof e == "number")
+      s.floatData = e;
+    else {
+      console.warn("Cabbage: sendChannelData received unsupported data type:", typeof e);
+      return;
+    }
+    const t = {
+      command: "channelData",
+      obj: JSON.stringify(s)
     };
-    console.log("Cabbage: sending midi message from UI", d), t !== null ? t.postMessage(o) : window.sendMessageFromUI(o);
+    console.log("Cabbage: sending channel data from UI", s), n !== null ? n.postMessage(t) : window.sendMessageFromUI(t);
   }
-  static MidiMessageFromHost(n, e, a) {
-    console.log("Cabbage: Got MIDI Message" + n + ":" + e + ":" + a);
+  static MidiMessageFromHost(a, e, n) {
+    console.log("Cabbage: Got MIDI Message" + a + ":" + e + ":" + n);
   }
-  static triggerFileOpenDialog(n, e) {
-    var a = {
-      channel: e
+  static triggerFileOpenDialog(a, e, n = {}) {
+    var s = {
+      channel: e,
+      directory: n.directory || "",
+      filters: n.filters || "*",
+      openAtLastKnownLocation: n.openAtLastKnownLocation !== void 0 ? n.openAtLastKnownLocation : !0
     };
     const t = {
       command: "fileOpen",
-      obj: JSON.stringify(a)
+      obj: JSON.stringify(s)
     };
-    n !== null ? n.postMessage(t) : window.sendMessageFromUI(t);
+    a !== null ? a.postMessage(t) : window.sendMessageFromUI(t);
+  }
+  static openUrl(a, e, n) {
+    var s = {
+      url: e,
+      file: n
+    };
+    const t = {
+      command: "openUrl",
+      obj: JSON.stringify(s)
+    };
+    a !== null ? a.postMessage(t) : window.sendMessageFromUI(t);
   }
 }
-const h = (l) => {
-  const [n, e] = f();
-  return b(() => {
-    const a = (t) => {
-      const { channel: d, data: o, command: u } = t.data;
-      if (d === l && o && u === "widgetUpdate") {
-        const c = JSON.parse(o);
+const f = (r) => {
+  const [a, e] = u();
+  return m(() => {
+    const n = (s) => {
+      const { id: t, widgetJson: o, command: l } = s.data;
+      if (t === r && o && l === "widgetUpdate") {
+        const i = JSON.parse(o);
         console.log(
-          `[Cabbage-React] ${u}: Received properties for channel: ${d}`,
-          c
-        ), e(c);
+          `[Cabbage-React] Received properties for channelId ${t}`,
+          i
+        ), e(i);
       }
     };
-    return window.addEventListener("message", a), () => {
-      window.removeEventListener("message", a);
+    return window.addEventListener("message", n), () => {
+      window.removeEventListener("message", n);
     };
   }, []), {
-    properties: n
+    properties: a
   };
-}, M = (l, n) => {
-  const { properties: e } = h(l), [a, t] = f(), [d, o] = f(), u = (s) => {
-    t(s);
-    const i = {
-      paramIdx: n,
-      channelType: d,
-      channel: l,
-      value: s
-    };
-    C.sendParameterUpdate(i, null);
-  }, c = (s) => {
-    if (typeof s == "number") return "number";
-    if (typeof s == "string") return "string";
+}, b = (r, a) => {
+  const { properties: e } = f(r), [n, s] = u(), t = (o) => {
+    s(o);
+    const l = {
+      paramIdx: a,
+      channel: r,
+      value: o
+    };
+    c.sendParameterUpdate(l, null);
   };
-  return b(() => {
-    var i;
-    if ((e == null ? void 0 : e.channel) !== l) return;
-    const s = (i = e == null ? void 0 : e.range) == null ? void 0 : i.defaultValue;
-    if (a === void 0 && s !== void 0) {
+  return m(() => {
+    var d;
+    const o = e == null ? void 0 : e.value;
+    if (o != null) {
       console.log(
-        `[Cabbage-React]: Received default value for channel "${e == null ? void 0 : e.channel}"`,
-        s
-      ), t(s);
-      const r = c(s);
-      r && o(r);
+        `[Cabbage-React] Received initial value for channelId "${r}"`,
+        o
+      ), s(o);
+      return;
     }
-  }, [e]), b(() => {
-    const s = (i) => {
-      const { command: r } = i.data;
-      if (r === "widgetUpdate") {
-        const { channel: m, value: g } = i.data;
-        if (m !== l) return;
-        if (console.log(
-          `[Cabbage-React] ${r}: Received initial value for channel "${m}"`,
-          g
-        ), g !== void 0) {
-          t(g);
-          const p = c(g);
-          p && o(p);
-        }
-      }
-      if (r === "parameterChange") {
-        const { paramIdx: m, value: g } = i.data.data || {};
-        m === n && g !== void 0 && (console.log(
-          `[Cabbage-React] ${r}: Received value change for paramIdx: ${m}`,
-          g
-        ), t(g));
+    const l = e == null ? void 0 : e.channels.find(
+      (g) => g.id === r
+    );
+    if (!l) return;
+    const i = (d = l.range) == null ? void 0 : d.defaultValue;
+    n === void 0 && i !== void 0 && (console.log(
+      `[Cabbage-React] Received default value for channelId "${l.id}"`,
+      i
+    ), s(i));
+  }, [e]), m(() => {
+    const o = (l) => {
+      const { command: i } = l.data;
+      if (i === "parameterChange") {
+        const { value: d, paramIdx: g } = l.data;
+        if (g !== a || d === null) return;
+        console.log(
+          `[Cabbage-React] Received value change for parameterIndex ${g}`,
+          d
+        ), s(d);
       }
     };
-    return window.addEventListener("message", s), () => {
-      window.removeEventListener("message", s);
+    return window.addEventListener("message", o), () => {
+      window.removeEventListener("message", o);
     };
   }, []), {
-    value: a,
-    setValue: u
+    value: n,
+    setValue: t
   };
 };
 export {
-  C as Cabbage,
-  h as useCabbageProperties,
-  M as useCabbageState
+  c as Cabbage,
+  f as useCabbageProperties,
+  b as useCabbageState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cabbage-react",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"type": "module",
 	"keywords": [
 		"cabbage",