@adcops/autocore-react 3.0.39 → 3.1.1

package/readme.md

@@ -15,26 +15,202 @@ PrimeReact to supply almost all but the most obscure controls, and adds a wrappe
 signals from the backend to the common controls. This allows autocore-react to focus on the additional
 features needed for machine-control user interfaces, while PrimeReact excels at development of components.
 
-## Hub
+## Installation
 
-Whether running in a browser or within a Tauri application, the user interface of a web app needs to 
-communicate with a backed. The Hub abstracts this by defining a common base class, then automatically
-selecting the proper pipeline based upon the environment. If the Tauri environment is detected, HubTauri 
-is loaded. For a browser instance, a socket.io connection is used. When running in a development environment,
-a simulated backend that simply echoes responses is used.
+Install from NPM.
 
-When writing the main application or developing components, you only need to focus on the Hub class. Because the
-backend is selected automatically, the web application does not need to be modified for each individual environment.
+```
+npm install --save @adcops/autocore-react
+```
 
+## Quick Start
 
-## Installation
+### 1. Define Your Tags
 
-Install from NPM.
+Create `AutoCoreTags.ts` to define all the tags your application will use:
 
+```typescript
+import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acTagSpec = [
+  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
+  { "tagName": "motorSpeed", "domain": "ADS", "symbolName": "MAIN.ctx.motor.fSpeed", "valueType": "number" },
+  { "tagName": "isAutoCycleRunning", "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
+  { "tagName": "positionScalar", "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number", "initialValue": 1.0 }
+] as const satisfies readonly TagConfig[];
+
+export default acTagSpec;
 ```
-npm install --save @adcops/autocore-react
+
+### 2. Create Typed Hooks
+
+Create `AutoCore.ts` to generate strongly-typed hooks:
+
+```typescript
+import { acTagSpec } from "./AutoCoreTags";
+import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
+
+export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
+```
+
+
+#### Define Scales (Optional)
+For applications that need unit conversion, create `AutoCoreScales.ts` with server-driven scaling:
+
+
+```tsx
+import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acScales = {
+  position: { 
+    name: "position", 
+    scale: 1.0, 
+    label: "mm",
+    serverTag: { domain: "GNV", symbolName: "position_scalar" }
+  },
+  load: { 
+    name: "load", 
+    scale: 1.0, 
+    label: "N",
+    serverTag: { domain: "GNV", symbolName: "load_scalar" }
+  }
+} as const satisfies Record<string, ScaleConfig>;
+```
+
+Note: Server tags now store both scale factor and label as a JSON object: `{ scale: 1.0, label: "mm" }`. Legacy numeric-only values are supported for backward compatibility.
+
+Next, reference scales in your tag definitions.
+
+```tsx
+// In AutoCoreTags.ts - add scale property to numeric tags
+{ "tagName": "pressPosition", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number", "scale": "position" },
+{ "tagName": "pressLoad", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number", "scale": "load" }
+```
+
+### 3. Wrap Your App
+
+Update your `App.tsx` to provide the contexts:
+
+```typescript
+import React from 'react';
+import { PrimeReactProvider } from 'primereact/api';
+import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext";
+import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { acTagSpec } from "./AutoCoreTags";
+import { acScales } from "./AutoCoreScales";
+
+function App() {
+  return (
+    <EventEmitterProvider>
+      <PrimeReactProvider>
+        <AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
+          <div className="app-wrapper">
+            <main className="main-wrapper">
+              <YourMainContent />
+            </main>
+          </div>
+        </AutoCoreTagProvider>
+      </PrimeReactProvider>
+    </EventEmitterProvider>
+  );
+}
+
+export default App;
 ```
 
+### 4. Use Tags in Components
+
+Import your typed hooks and use them in any component:
+
+```typescript
+import React from 'react';
+import { Button } from 'primereact/button';
+import { AutoCoreHooks } from './AutoCore';
+
+export const ControlPanel: React.FC = () => {
+  // Single tag access
+  const { value: powerOk, write: setPowerOk } = AutoCoreHooks.useAutoCoreTag("isControlPowerOk");
+  const { value: motorSpeed, write: setMotorSpeed } = AutoCoreHooks.useAutoCoreTag("motorSpeed");
+  
+  // Multiple tag access
+  const { values } = AutoCoreHooks.useAutoCoreTags(["isControlPowerOk", "isAutoCycleRunning"]);
+  
+  // Computed state
+  const { selected: canStart } = AutoCoreHooks.useAutoCoreSelect(v =>
+    !!v["isControlPowerOk"] && !v["isAutoCycleRunning"]
+  );
+
+  return (
+    <div>
+      <div>Power OK: {powerOk ? "Yes" : "No"}</div>
+      <div>Motor Speed: {motorSpeed} RPM</div>
+      
+      <Button 
+        label="Start Motor" 
+        disabled={!canStart}
+        onClick={() => setMotorSpeed(1000)}
+      />
+      
+      <Button 
+        label="Emergency Stop" 
+        severity="danger"
+        onClick={() => setPowerOk(false)}
+      />
+    </div>
+  );
+};
+```
+
+### 5. Development Panel (Optional)
+
+Add a debugging panel for development:
+
+```typescript
+import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+import { acTagSpec } from "./AutoCoreTags";
+
+// In your App component:
+{process.env.NODE_ENV === 'development' && (
+  <AutoCoreDevPanel 
+    tags={acTagSpec} 
+    className="fixed bottom-4 right-4 bg-white shadow-lg" 
+  />
+)}
+```
+
+## AutoCoreTagContext Features
+
+- **Strongly-typed**: Full TypeScript support with IntelliSense for tag names and value types
+- **Global state**: Share tag values across your entire application
+- **Real-time updates**: Automatic subscription to server data changes
+- **No optimistic updates**: UI always reflects true server state
+- **Error handling**: Proper async/await patterns with error feedback
+- **Development tools**: Built-in debugging panel for testing
+
+## Architecture
+
+### Hub (Internal)
+
+The Hub is an internal abstraction that handles communication with the backend. It automatically
+selects the proper pipeline based on the environment: HubTauri for Tauri applications, socket.io 
+for browser instances, and a simulated backend for development environments.
+
+**Important**: Applications should not interact with the Hub directly. Instead, use the higher-level 
+abstractions described below.
+
+### EventEmitterContext
+
+The EventEmitterContext provides a global event system for component communication and backend 
+interaction through `invoke()`, `subscribe()`, and `dispatch()` methods. This is automatically 
+available when you wrap your app with `<EventEmitterProvider>`.
+
+### AutoCoreTagContext (Recommended)
+
+For most backend data interactions, use the AutoCoreTagContext system with strongly-typed hooks.
+This provides the cleanest, most maintainable approach for managing server state in your components.
+See the Quick Start section above for setup and usage.
+
 ## Development
 
 We typically have an external Tauri project designed to import and test the autocore-react library. We find that
@@ -56,14 +232,12 @@ npm publish --tag staging --access=public
 
 Note that we have to specify that the access is public because the tag makes this "scoped," which are private by default.
 
-
 In the test project, simply install the 'staging' tag version.
 
 ```
 npm install @adcops/autocore-react@staging
 ```
 
-
 ### npm link
 
 In the root of the autocore-react project, initiate npm link:
@@ -131,10 +305,6 @@ overwrite existing .tsx files. If you need to update a pre-existing .tsx file, d
 Possible options for SVGR:
 https://react-svgr.com/docs/options/
 
-
-
-
-
 ## Documentation
 
 To generate documentation:
@@ -144,29 +314,30 @@ npm run generate-docs
 
 Publishing the package will also regenerate the documentation.
 
-
-
 ## Additional Documentation
 
 Beyond doc-comments in the code, we provide additional documentation in the additional-docs folder.
 
+- AutoCoreTagContext Manual: [AutoCoreTagContext Manual](../additional-docs/AutoCoreTagContext.md).
 - Button API Specs: [Button API Specs](../additional-docs/ButtonApiSpecs.md).
 - Global Event Emitter: [Global Event Emitter](../additional-docs/GlobalEventEmitter.md).
 
-
 ## Acknowledgements
 
-Beyond the obvious, inherent React libraries, autocore-react greatly appreciates the works of
+Beyond the obvious, inherent React and TypeScript libraries, autocore-react greatly appreciates the works of
 these additional libraries.
 
 - PrimeReact and PrimeIcons
 - numerable
 - Simple Keyboard (https://github.com/hodgef/simple-keyboard)
 - - We customize Simple Keyboard for cleaner physical keyboard integration.
+- Monaco editor
+- socket-io
+- Tauri
 
 ## Copyright
 
-(C) Copyright 2021-2024 Automated Design Corp. All Rights Reserved.
+(C) Copyright 2021-2025 Automated Design Corp. All Rights Reserved.
 
 ## License
 

package/src/components/AutoCoreDevPanel.tsx

@@ -0,0 +1,411 @@
+/*
+ * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2025-09-05 08:06:09
+ * -----
+ * Last Modified: 2025-09-10 11:15:10
+ * -----
+ * 
+ */
+
+/**
+ * @module components/AutoCoreDevPanel
+ * 
+ * @summary
+ * 
+ * A development and debugging panel for monitoring and manually interacting with AutoCore tags.
+ * This component provides real-time visibility into tag values and allows direct manipulation
+ * for testing and debugging purposes.
+ * 
+ * @remarks
+ * 
+ * The AutoCoreDevPanel is designed to be used during development to:
+ * - Monitor live tag values in real-time
+ * - Test write operations manually 
+ * - Debug tag behavior and connectivity
+ * - Perform tap operations on boolean tags
+ * - Validate tag configurations
+ * 
+ * The panel automatically connects to the global AutoCoreTagContext and displays all
+ * tags passed to it. No additional setup or factory functions are required.
+ * 
+ * @example Basic Usage
+ * ```tsx
+ * import React from 'react';
+ * import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+ * import { acTagSpec } from "./AutoCoreTags";
+ * 
+ * function App() {
+ *   return (
+ *     <div>
+ *       <main>
+ *         <YourMainContent />
+ *       </main>
+ *       
+ *       {process.env.NODE_ENV === 'development' && (
+ *         <AutoCoreDevPanel 
+ *           tags={acTagSpec} 
+ *           className="fixed bottom-4 right-4 bg-white shadow-lg" 
+ *         />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Styled Panel
+ * ```tsx
+ * import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+ * import { acTagSpec } from "./AutoCoreTags";
+ * 
+ * // Custom styled panel
+ * <AutoCoreDevPanel 
+ *   tags={acTagSpec}
+ *   title="Machine Status Monitor"
+ *   className="
+ *     fixed top-4 left-4 
+ *     bg-gray-900 text-white 
+ *     border border-gray-700 
+ *     shadow-2xl rounded-lg
+ *     max-w-md
+ *   "
+ * />
+ * ```
+ * 
+ * @example Filtered Tags
+ * ```tsx
+ * import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+ * import { acTagSpec } from "./AutoCoreTags";
+ * 
+ * // Show only specific tags for focused debugging
+ * const motorTags = acTagSpec.filter(tag => 
+ *   tag.tagName.includes('motor') || tag.tagName.includes('axis')
+ * );
+ * 
+ * <AutoCoreDevPanel 
+ *   tags={motorTags}
+ *   title="Motor Control Debug"
+ *   className="debug-panel"
+ * />
+ * ```
+ */
+
+import React, { useContext, useMemo, useState, useCallback } from "react";
+import type { TagConfig } from "../core/AutoCoreTagTypes";
+import { AutoCoreTagContext } from "../core/AutoCoreTagContext";
+
+/**
+ * Props for the AutoCoreDevPanel component.
+ */
+interface AutoCoreDevPanelProps {
+  /** 
+   * Array of tag configurations to display in the panel.
+   * Each tag will show its current value and provide controls for writing new values.
+   */
+  tags: readonly TagConfig[];
+  
+  /** 
+   * Optional title for the panel header. 
+   * @defaultValue "AutoCore Dev Panel"
+   */
+  title?: string;
+  
+  /** 
+   * Optional CSS class names for custom styling.
+   * The panel has default styling but can be customized with Tailwind or custom CSS.
+   */
+  className?: string;
+}
+
+/**
+ * AutoCoreDevPanel - Development and debugging panel for AutoCore tags.
+ * 
+ * This component provides a real-time debugging interface for monitoring and manipulating
+ * AutoCore tags during development. It displays current tag values, provides input controls
+ * for writing new values, and includes tap functionality for boolean tags.
+ * 
+ * ## Features
+ * 
+ * - **Real-time monitoring**: Shows live tag values as they update from the server
+ * - **Direct writes**: Input controls to write new values directly to tags
+ * - **Type-aware inputs**: Automatically provides appropriate input types (checkbox for boolean, number input for numeric, etc.)
+ * - **Tap functionality**: Special "TAP" buttons for boolean tags that send momentary true→false signals
+ * - **Error handling**: Visual feedback for write failures and validation errors
+ * - **Live status**: Indicator showing whether the system is loading or live
+ * - **JSON support**: Proper formatting and editing for JSON-type tags
+ * 
+ * ## Input Types
+ * 
+ * - **Boolean tags**: Checkbox for direct true/false setting + TAP button for momentary signals
+ * - **Number tags**: Number input with validation
+ * - **String tags**: Text input
+ * - **JSON tags**: Text input with JSON validation and pretty-printing
+ * 
+ * ## Keyboard Shortcuts
+ * 
+ * - **Enter key**: In text/number inputs, immediately sends the value to the server
+ * - **Tab navigation**: Navigate between inputs using standard keyboard navigation
+ * 
+ * ## Error Handling
+ * 
+ * Write operations that fail will show error messages below the input field.
+ * Common errors include:
+ * - Invalid number formats
+ * - Malformed JSON
+ * - Network/server errors
+ * - Tag not found errors
+ */
+export const AutoCoreDevPanel: React.FC<AutoCoreDevPanelProps> = ({
+  tags,
+  title = "AutoCore Dev Panel",
+  className = "",
+}) => {
+  const { values, rawValues, isLoading, write, tap, scales } = useContext(AutoCoreTagContext);
+
+  /** Local editable buffers & errors keyed by tagName */
+  const [editBuf, setEditBuf] = useState<Record<string, string>>({});
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const rows = useMemo(() => {
+    return tags.map((tag) => {
+      const display = values[tag.tagName];
+      const raw = rawValues[tag.tagName];
+      const scaleName = tag.scale ?? "";
+      const s = scaleName ? scales[scaleName] : undefined;
+      return {
+        tag,
+        display,
+        raw,
+        scaleName,
+        factor: s?.scale,
+        label: s?.label,
+      };
+    });
+  }, [tags, values, rawValues, scales]);
+
+  const setBuf = useCallback((tagName: string, v: string) => {
+    setEditBuf((prev) => ({ ...prev, [tagName]: v }));
+    setErrors((prev) => ({ ...prev, [tagName]: "" }));
+  }, []);
+
+  const setErr = useCallback((tagName: string, msg: string) => {
+    setErrors((prev) => ({ ...prev, [tagName]: msg }));
+  }, []);
+
+  const commit = useCallback(async (tag: TagConfig) => {
+    const tagName = tag.tagName;
+    const buf = editBuf[tagName];
+
+    try {
+      if (tag.valueType === "boolean") {
+        // Toggle to the buffer value if explicitly provided, else flip current
+        const desired =
+          buf === "true" ? true :
+          buf === "false" ? false :
+          !(values[tagName] as boolean);
+        await write(tagName as any, desired as any);
+        setBuf(tagName, "");
+        return;
+      }
+
+      if (tag.valueType === "number") {
+        if (buf == null || buf.trim() === "") {
+          setErr(tagName, "Enter a number.");
+          return;
+        }
+        const n = Number(buf);
+        if (Number.isNaN(n)) {
+          setErr(tagName, "Invalid number.");
+          return;
+        }
+        await write(tagName as any, n as any);
+        setBuf(tagName, "");
+        return;
+      }
+
+      if (tag.valueType === "string") {
+        await write(tagName as any, (buf ?? "") as any);
+        setBuf(tagName, "");
+        return;
+      }
+
+      // json
+      try {
+        const parsed = buf?.trim() ? JSON.parse(buf) : null;
+        await write(tagName as any, parsed as any);
+        setBuf(tagName, "");
+      } catch (e: any) {
+        setErr(tagName, "Invalid JSON.");
+      }
+    } catch (e: any) {
+      setErr(tagName, e?.message ?? String(e));
+    }
+  }, [editBuf, setBuf, setErr, write, values]);
+
+  const onKeyDownCommit = (ev: React.KeyboardEvent, tag: TagConfig) => {
+    if (ev.key === "Enter" && !ev.shiftKey) {
+      ev.preventDefault();
+      void commit(tag);
+    }
+  };
+
+  return (
+    <div className={`rounded-md border border-gray-200 bg-white text-sm ${className}`} style={{ minWidth: 680 }}>
+      <div className="flex items-center justify-between px-3 py-2" style={{ borderBottom: "1px solid #eee" }}>
+        <div className="flex items-center gap-2">
+          <strong>{title}</strong>
+          <span
+            title={isLoading ? "Loading" : "Live"}
+            style={{
+              width: 8, height: 8, borderRadius: 999,
+              background: isLoading ? "#aaa" : "#22c55e",
+              display: "inline-block"
+            }}
+          />
+        </div>
+      </div>
+
+      <div style={{ overflowX: "auto" }}>
+        <table style={{ borderCollapse: "collapse", width: "100%" }}>
+          <thead>
+            <tr>
+              <Th>Tag</Th>
+              <Th>Kind</Th>
+              <Th>Domain</Th>
+              <Th>Symbol</Th>
+              <Th>Display</Th>
+              <Th>Raw</Th>
+              <Th>Scale</Th>
+              <Th>Units</Th>
+              <Th>Input</Th>
+              <Th>Actions</Th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map(({ tag, display, raw, scaleName, factor, label }) => {
+              const buf = editBuf[tag.tagName] ?? "";
+              const err = errors[tag.tagName];
+
+              return (
+                <tr key={tag.tagName}>
+                  <Td mono>{tag.tagName}</Td>
+                  <Td mono>{tag.valueType}</Td>
+                  <Td mono>{tag.domain}</Td>
+                  <Td mono>{tag.symbolName}</Td>
+                  <Td mono>{fmt(display)}</Td>
+                  <Td mono>{fmt(raw)}</Td>
+                  <Td mono>{scaleName ? `${scaleName} ×${factor ?? 1}` : "—"}</Td>
+                  <Td mono>{scaleName ? (label ?? "") : "—"}</Td>
+                  <Td>
+                    <InputForTag
+                      tag={tag}
+                      buf={buf}
+                      setBuf={(v) => setBuf(tag.tagName, v)}
+                      onKeyDown={(e) => onKeyDownCommit(e, tag)}
+                    />
+                    {err && <div style={{ color: "#dc2626", marginTop: 4 }}>{err}</div>}
+                  </Td>
+                  <Td>
+                    <div style={{ display: "flex", gap: 6 }}>
+                      <button onClick={() => commit(tag)}>Write</button>
+                      {tag.valueType === "boolean" && (
+                        <button onClick={() => tap(tag.tagName as any)}>TAP</button>
+                      )}
+                    </div>
+                  </Td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+/** ---------- helpers ---------- */
+
+const Th: React.FC<React.PropsWithChildren<{}>> = ({ children }) => (
+  <th style={{
+    textAlign: "left",
+    borderBottom: "1px solid #ddd",
+    padding: "6px 8px",
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace"
+  }}>{children}</th>
+);
+
+const Td: React.FC<React.PropsWithChildren<{ mono?: boolean }>> = ({ children, mono }) => (
+  <td style={{
+    borderBottom: "1px solid #eee",
+    padding: "6px 8px",
+    whiteSpace: "nowrap",
+    fontFamily: mono ? "ui-monospace, SFMono-Regular, Menlo, monospace" : "inherit"
+  }}>{children}</td>
+);
+
+const InputForTag: React.FC<{
+  tag: TagConfig;
+  buf: string;
+  setBuf: (v: string) => void;
+  onKeyDown: (e: React.KeyboardEvent) => void;
+}> = ({ tag, buf, setBuf, onKeyDown }) => {
+  if (tag.valueType === "boolean") {
+    // Boolean: checkbox controls direct true/false (buffer mirrors state as string)
+    return (
+      <label style={{ display: "inline-flex", alignItems: "center", gap: 6 }}>
+        <input
+          type="checkbox"
+          checked={buf ? buf === "true" : (Boolean as any)}
+          onChange={(e) => setBuf(e.target.checked ? "true" : "false")}
+          onKeyDown={onKeyDown}
+        />
+        <span>set</span>
+      </label>
+    );
+  }
+
+  if (tag.valueType === "number") {
+    return (
+      <input
+        type="number"
+        step="any"
+        value={buf}
+        onChange={(e) => setBuf(e.target.value)}
+        onKeyDown={onKeyDown}
+        style={{ width: 140 }}
+        placeholder="number…"
+      />
+    );
+  }
+
+  if (tag.valueType === "string") {
+    return (
+      <input
+        type="text"
+        value={buf}
+        onChange={(e) => setBuf(e.target.value)}
+        onKeyDown={onKeyDown}
+        style={{ width: 180 }}
+        placeholder="text…"
+      />
+    );
+  }
+
+  // json
+  return (
+    <textarea
+      value={buf}
+      onChange={(e) => setBuf(e.target.value)}
+      onKeyDown={onKeyDown}
+      rows={2}
+      style={{ width: 260, fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }}
+      placeholder='{"foo": 42}'
+    />
+  );
+};
+
+function fmt(v: unknown) {
+  if (v === null || v === undefined) return "—";
+  if (typeof v === "number") return Number.isFinite(v) ? v.toString() : String(v);
+  if (typeof v === "string") return v;
+  try { return JSON.stringify(v); } catch { return String(v); }
+}

package/src/components/CodeEditor.tsx

@@ -2,7 +2,7 @@
  * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
  * Created Date: 2024-03-17 08:43:02
  * -----
- * Last Modified: 2024-03-18 11:29:08
+ * Last Modified: 2025-09-05 14:52:18
  * -----
  * 
  */
@@ -12,7 +12,7 @@
 import * as React from 'react';
 import { editor } from 'monaco-editor';
 //import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';
-import Editor, { Monaco } from '@monaco-editor/react';
+import Editor, { type Monaco } from '@monaco-editor/react';
 
 
 interface CodeEditorProps {