flexdesk 0.16.1 → 0.17.0

package/src/charts/series_transforms.js

@@ -0,0 +1,206 @@
+/**
+ * series_transforms.js — derived series an embedder supplies: a trend, a moving
+ * average, a decomposition. @flexdesk/charts ships none of its own.
+ *
+ * A transform is a description plus an async function:
+ *
+ *     const seriesTransforms = {
+ *         movingAverage: {
+ *             label: 'Moving average',
+ *             params: { window: { label: 'Window', default: 5, min: 1, step: 1 } },
+ *             outputs: {
+ *                 mean: { label: 'Mean', suffix: ' (MA)', lineStyle: 'dashed' },
+ *             },
+ *             run: async (y, params) => ({ mean: rollingMean(y, params.window) }),
+ *         },
+ *     };
+ *
+ * `run(y, params)` resolves `{ [output]: number[] }`. It is called ONCE per
+ * eligible trace (a 2-D line/scatter trace) for each transform with at least one
+ * output switched on, and every switched-on output it returns is drawn as an
+ * extra trace in the source trace's colour, named `<source name><suffix>`, with
+ * the output's `lineStyle` (solid | dashed | dotted) and `lineWidth`.
+ *
+ * What is switched on lives in the subplot, under `subplot.transforms`:
+ *
+ *     subplot.transforms = { movingAverage: { outputs: { mean: true }, params: { window: 7 } } }
+ *
+ * A transform that throws, rejects or resolves something that is not an object
+ * is skipped for that trace; the figure is drawn without it.
+ */
+
+import { buildTrace } from './chart_types.js';
+
+/** A transform's parameter values: its declared defaults under the subplot's own. */
+function resolveParams(transform, state) {
+    const params = {};
+    for (const [name, spec] of Object.entries(transform.params ?? {})) {
+        params[name] = spec?.default;
+    }
+    return { ...params, ...(state?.params ?? {}) };
+}
+
+/** The output names of `transform` that `state` switches on, in declared order. */
+function enabledOutputs(transform, state) {
+    return Object.keys(transform.outputs ?? {}).filter((name) => state?.outputs?.[name] === true);
+}
+
+/** A trace a transform may run on: 2-D, line or scatter, with a y array. */
+function isEligible(trace) {
+    const type = trace.type ?? 'scatter';
+    return (type === 'scatter' || type === 'scattergl') && Array.isArray(trace.y);
+}
+
+/**
+ * The derived traces for one subplot's figure.
+ *
+ * @param {Object[]} traces - The figure's Plotly traces so far (not modified).
+ * @param {Object} subplot - The subplot config; reads `subplot.transforms`.
+ * @param {Object|null} seriesTransforms - `{ [id]: transform }`, or null for none.
+ * @param {Object} [options]
+ * @param {Function} [options.onError] - `({ transformId, traceName, error })`,
+ *        called for each skipped run.
+ * @returns {Promise<Object[]>} The extra traces, in transform then trace order.
+ */
+async function deriveSeriesTraces(traces, subplot, seriesTransforms, { onError } = {}) {
+    const derived = [];
+    if (!seriesTransforms) return derived;
+    const sources = traces.filter(isEligible);
+
+    for (const [transformId, transform] of Object.entries(seriesTransforms)) {
+        const state = subplot?.transforms?.[transformId];
+        const outputs = enabledOutputs(transform, state);
+        if (!outputs.length || typeof transform?.run !== 'function') continue;
+        const params = resolveParams(transform, state);
+
+        for (const source of sources) {
+            let result;
+            try {
+                result = await transform.run(source.y, params);
+            } catch (error) {
+                onError?.({ transformId, traceName: source.name, error });
+                continue;
+            }
+            if (!result || typeof result !== 'object') {
+                onError?.({ transformId, traceName: source.name,
+                            error: new Error(`transform "${transformId}" resolved no outputs`) });
+                continue;
+            }
+            const color = source.line?.color || source.marker?.color;
+            for (const name of outputs) {
+                const y = result[name];
+                if (!Array.isArray(y)) continue;
+                const spec = transform.outputs[name];
+                derived.push({
+                    ...buildTrace({
+                        chartType: 'line',
+                        x: source.x,
+                        y,
+                        name: `${source.name}${spec.suffix ?? ` (${spec.label ?? name})`}`,
+                        color,
+                        lineWidth: spec.lineWidth ?? 2,
+                        lineStyle: spec.lineStyle ?? 'solid',
+                        yAxisId: source.yaxis || 'y',
+                    }),
+                    showlegend: true,
+                });
+            }
+        }
+    }
+    return derived;
+}
+
+/**
+ * The controls for `seriesTransforms` in a subplot's config: per transform, a
+ * toggle for each output and a number field for each parameter. They edit
+ * `subplot.transforms` in place and call `onChange()` after every edit. With no
+ * transforms (null or `{}`) nothing is rendered.
+ *
+ * @param {HTMLElement} container
+ * @param {Object} subplot
+ * @param {Object|null} seriesTransforms
+ * @param {Object} [options]
+ * @param {Function} [options.onChange]
+ * @returns {{ dispose: Function }}
+ */
+function renderSeriesTransformControls(container, subplot, seriesTransforms, { onChange } = {}) {
+    const entries = Object.entries(seriesTransforms ?? {});
+    if (!entries.length) return { dispose() {} };
+
+    const root = document.createElement('div');
+    root.className = 'twm-series-transforms';
+
+    const stateOf = (transformId) => {
+        subplot.transforms ??= {};
+        subplot.transforms[transformId] ??= {};
+        return subplot.transforms[transformId];
+    };
+
+    for (const [transformId, transform] of entries) {
+        const group = document.createElement('fieldset');
+        group.className = 'twm-series-transforms__group';
+        const legend = document.createElement('legend');
+        legend.className = 'twm-series-transforms__label';
+        legend.textContent = transform.label ?? transformId;
+        group.appendChild(legend);
+
+        const paramInputs = [];
+        const syncDisabled = () => {
+            const on = enabledOutputs(transform, subplot.transforms?.[transformId]).length > 0;
+            for (const input of paramInputs) input.disabled = !on;
+        };
+
+        for (const [name, spec] of Object.entries(transform.outputs ?? {})) {
+            const row = document.createElement('label');
+            row.className = 'twm-series-transforms__row';
+            const box = document.createElement('input');
+            box.type = 'checkbox';
+            box.checked = subplot.transforms?.[transformId]?.outputs?.[name] === true;
+            box.addEventListener('change', () => {
+                const state = stateOf(transformId);
+                state.outputs = { ...(state.outputs ?? {}), [name]: box.checked };
+                syncDisabled();
+                onChange?.();
+            });
+            const text = document.createElement('span');
+            text.textContent = spec?.label ?? name;
+            row.append(box, text);
+            group.appendChild(row);
+        }
+
+        for (const [name, spec] of Object.entries(transform.params ?? {})) {
+            const row = document.createElement('label');
+            row.className = 'twm-series-transforms__row';
+            const text = document.createElement('span');
+            text.textContent = spec?.label ?? name;
+            const input = document.createElement('input');
+            input.type = 'number';
+            input.className = 'twm-series-transforms__param';
+            for (const attr of ['min', 'max', 'step']) {
+                if (spec?.[attr] != null) input[attr] = String(spec[attr]);
+            }
+            const current = subplot.transforms?.[transformId]?.params?.[name] ?? spec?.default;
+            input.value = current == null ? '' : String(current);
+            input.addEventListener('change', () => {
+                const value = parseFloat(input.value);
+                const state = stateOf(transformId);
+                const params = { ...(state.params ?? {}) };
+                if (Number.isFinite(value)) params[name] = value;
+                else delete params[name];
+                state.params = params;
+                onChange?.();
+            });
+            paramInputs.push(input);
+            row.append(text, input);
+            group.appendChild(row);
+        }
+
+        syncDisabled();
+        root.appendChild(group);
+    }
+
+    container.appendChild(root);
+    return { dispose() { root.remove(); } };
+}
+
+export { deriveSeriesTraces, renderSeriesTransformControls };

package/src/core/logging.js

@@ -26,7 +26,7 @@ const QUIET_MODE_LEVEL = 'warn';
 
 export class LoggingService {
     constructor({
-        name = 'ecosim',
+        name = 'flexdesk',
         eventBus = null,
         minLevel = 'info',
         historyLimit = 500,

package/src/core/settings.js

@@ -7,7 +7,8 @@
  * SCHEMA. The store knows nothing about any particular application's settings:
  * it ships the *shell's* own namespaces (workspace, window, logging, data,
  * notebook, ai, …) and an embedder PUSHES its own namespace in at boot with
- * `registerSettings()`. The Settings page renders whatever is in the schema.
+ * `registerSettings()`. The settings page — `SettingsView` in
+ * `src/ui/components/settings_view.js` — renders whatever is in the schema.
  *
  * Two doors, on purpose
  * ---------------------
@@ -18,8 +19,9 @@
  *   getSetting() / setSetting() / registerSettings() / …
  *       A thin binding over ONE instance of that primitive for THIS document.
  *       The cardinality is correct, not merely convenient: the store has a
- *       single physical backing key (`localStorage['ecosim.settings.v1']`), so
- *       two live stores in one document would be two writers to one key.
+ *       single physical backing key (`localStorage['flexdesk.settings.v1']`
+ *       unless `configureSettings({ storageKey })` names another), so two
+ *       live stores in one document would be two writers to one key.
  *
  * Usage
  * -----
@@ -300,7 +302,7 @@ const SCHEMA = Object.freeze({
         label: 'Projects directory',
         description: 'Default directory for new projects and bundled demos. Leave empty for OS default.',
         defaultValue: null,
-        placeholder: 'OS default (%APPDATA%/EcoSim/projects)',
+        placeholder: 'OS default',
     },
 
     // ── AI Assistant ────────────────────────────────────────────────────────
@@ -387,7 +389,10 @@ const CATEGORIES = Object.freeze([
     { id: 'advanced',   label: 'Advanced',     icon: 'code',         description: 'Debug and developer settings',              order: 80 },
 ]);
 
-const STORAGE_KEY = 'ecosim.settings.v1';
+/** The binding's localStorage key when the embedder names none. An embedder
+ *  that stored settings under another key keeps them by passing that key to
+ *  `configureSettings({ storageKey })` before anything reads a setting. */
+export const DEFAULT_SETTINGS_STORAGE_KEY = 'flexdesk.settings.v1';
 
 // ─── Path / value helpers ────────────────────────────────────────────────────
 
@@ -494,8 +499,9 @@ export function createSettingsStore({
     const _defaults = _clone(defaults) ?? {};
     const _schema = { ...schema };
     let _categories = categories.map(c => ({ ...c }));
-    const _values = _clone(defaults) ?? {};
+    let _values = _clone(defaults) ?? {};
     let _bus = eventBus;
+    let _storageKey = storageKey;
 
     const _sortCategories = () => {
         // Array#sort is stable, so equal `order` keeps registration order.
@@ -513,8 +519,8 @@ export function createSettingsStore({
      */
     const _load = () => {
         try {
-            if (!storageKey || typeof localStorage === 'undefined') return;
-            const raw = localStorage.getItem(storageKey);
+            if (!_storageKey || typeof localStorage === 'undefined') return;
+            const raw = localStorage.getItem(_storageKey);
             if (!raw) return;
             const saved = JSON.parse(raw);
             for (const path of Object.keys(_schema)) {
@@ -532,7 +538,7 @@ export function createSettingsStore({
     /** Persist values that differ from their defaults (sparse storage). */
     const _save = () => {
         try {
-            if (!storageKey || typeof localStorage === 'undefined') return;
+            if (!_storageKey || typeof localStorage === 'undefined') return;
             const sparse = {};
             for (const path of Object.keys(_schema)) {
                 const parts = path.split('.');
@@ -543,9 +549,9 @@ export function createSettingsStore({
                 }
             }
             if (Object.keys(sparse).length === 0) {
-                localStorage.removeItem(storageKey);
+                localStorage.removeItem(_storageKey);
             } else {
-                localStorage.setItem(storageKey, JSON.stringify(sparse));
+                localStorage.setItem(_storageKey, JSON.stringify(sparse));
             }
         } catch (err) {
             console.warn('[Settings] Failed to persist settings', err);
@@ -569,19 +575,43 @@ export function createSettingsStore({
      * namespace is registered would garbage-collect that namespace's saved
      * values. Registering at the top of bootstrap satisfies this trivially.
      *
+     * Listeners hear `settings:registered` with `{ paths, categories }` — the
+     * slice's schema paths and the ids of the categories it added — so a view
+     * that is already open (the settings view) can draw the new rows.
+     *
      * @param {SettingsSlice} slice
      */
     const extend = ({ defaults: d = {}, schema: s = {}, categories: c = [] } = {}) => {
         _deepMerge(_defaults, d);
         _deepMerge(_values, d);
         Object.assign(_schema, s);
+        const added = [];
         for (const cat of c) {
             if (!cat?.id) continue;
             if (_categories.some(x => x.id === cat.id)) continue;
             _categories.push({ ...cat });
+            added.push(cat.id);
         }
         _sortCategories();
         _load();   // idempotent: overlays only paths it finds in storage
+        if (_bus) _bus.emit('settings:registered', { paths: Object.keys(s), categories: added });
+    };
+
+    /**
+     * Move the store onto another localStorage key: every value goes back to
+     * its default and is then overlaid from the NEW key only. Nothing is
+     * written, so the key the store leaves keeps whatever it held. Listeners
+     * hear one `settings:changed` with a null path, as after a reset.
+     *
+     * @param {string|null} key  localStorage key; null -> no persistence.
+     * @param {object} [opts]
+     * @param {boolean} [opts.notify=true]  false -> emit nothing.
+     */
+    const setStorageKey = (key, { notify = true } = {}) => {
+        _storageKey = key || null;
+        _values = _clone(_defaults) ?? {};
+        _load();
+        if (notify && _bus) _bus.emit('settings:changed', { path: null });
     };
 
     const get = (path, defaultValue = undefined) => {
@@ -683,6 +713,8 @@ export function createSettingsStore({
         getCategories: () => Object.freeze(_categories.slice()),
         getByCategory,
         setEventBus: (bus) => { _bus = bus; },
+        setStorageKey,
+        getStorageKey: () => _storageKey,
     });
 }
 
@@ -691,7 +723,8 @@ export function createSettingsStore({
 // A capability *port* (the host bridge) may have many implementations at once,
 // so a singleton there is a category error. A *value store* with a single
 // physical backing key has cardinality one by construction: two live stores in
-// one document would be two writers to `localStorage[STORAGE_KEY]`. The
+// one document would be two writers to the one key `configureSettings()`
+// names (default `DEFAULT_SETTINGS_STORAGE_KEY`). The
 // singleton is the correct cardinality, not a shortcut — and the factory above
 // is the primitive, so tests and a standalone demo never touch this binding.
 
@@ -699,9 +732,62 @@ const _store = createSettingsStore({
     defaults: DEFAULTS,
     schema: SCHEMA,
     categories: CATEGORIES,
-    storageKey: STORAGE_KEY,
+    storageKey: null,
 });
 
+// The binding reads its key LAZILY — on the first call that reads, writes or
+// resets a VALUE — so an embedder that calls `configureSettings({ storageKey })`
+// at boot never has the default key read at all, and importing this module
+// touches no storage. registerSettings(), registerSettingsEventBus() and the
+// schema/category/default getters do not attach it: they may come before or
+// after configureSettings().
+let _bindingKey = DEFAULT_SETTINGS_STORAGE_KEY;
+let _bound = false;
+
+/** The binding's store, attached to its key on first use. */
+function _binding() {
+    if (!_bound) {
+        _bound = true;
+        _store.setStorageKey(_bindingKey, { notify: false });
+    }
+    return _store;
+}
+
+/**
+ * The app-global binding's store itself — the handle `createSettingsStore()`
+ * returns — for code that takes a store, such as the settings view
+ * (`new SettingsView({ store: getSettingsStore(), eventBus })`). Its `set` is
+ * the one `setSetting()` calls. Like `getSetting()`, it attaches the binding
+ * to its storage key, so call `configureSettings()` first.
+ *
+ * @returns {object}
+ */
+export function getSettingsStore() {
+    return _binding();
+}
+
+/**
+ * Choose the localStorage key the app-global binding reads and writes.
+ * Call it at boot, before the first getSetting/setSetting/reset*: from then on
+ * the binding touches only `storageKey`.
+ *
+ * Called later, the binding moves: values return to their defaults, are
+ * reloaded from the new key, and a `settings:changed` (path null) is emitted.
+ * The old key is left as it was.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.storageKey=DEFAULT_SETTINGS_STORAGE_KEY]
+ */
+export function configureSettings({ storageKey = DEFAULT_SETTINGS_STORAGE_KEY } = {}) {
+    _bindingKey = storageKey;
+    if (_bound) _store.setStorageKey(storageKey);
+}
+
+/** @returns {string} The localStorage key the app-global binding uses. */
+export function getSettingsStorageKey() {
+    return _bindingKey;
+}
+
 /**
  * Push an embedder's settings namespace into the app-global store.
  *
@@ -733,7 +819,7 @@ export function registerSettingsEventBus(eventBus) {
  * @returns {*} The setting value or defaultValue
  */
 export function getSetting(path, defaultValue = undefined) {
-    return _store.get(path, defaultValue);
+    return _binding().get(path, defaultValue);
 }
 
 /**
@@ -743,7 +829,7 @@ export function getSetting(path, defaultValue = undefined) {
  * @returns {boolean} True if set successfully
  */
 export function setSetting(path, value) {
-    return _store.set(path, value);
+    return _binding().set(path, value);
 }
 
 /**
@@ -761,7 +847,7 @@ export function getDefaultValue(path) {
  * @returns {boolean} True if reset successfully
  */
 export function resetSetting(path) {
-    return _store.resetOne(path);
+    return _binding().resetOne(path);
 }
 
 /**
@@ -769,12 +855,12 @@ export function resetSetting(path) {
  * @param {string} categoryId
  */
 export function resetCategory(categoryId) {
-    _store.resetCategory(categoryId);
+    _binding().resetCategory(categoryId);
 }
 
 /** Reset all settings to their defaults. */
 export function resetAllSettings() {
-    _store.resetAll();
+    _binding().resetAll();
 }
 
 /**
@@ -782,7 +868,7 @@ export function resetAllSettings() {
  * @returns {object} Deep copy of current settings
  */
 export function getAllSettings() {
-    return _store.getAll();
+    return _binding().getAll();
 }
 
 // ─── Schema / Category API (for Settings page UI) ───────────────────────────