@adcops/autocore-react 3.0.39 → 3.1.1

package/src/core/AutoCoreTagTypes.ts

@@ -0,0 +1,202 @@
+/*
+ * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2025-09-05 07:57:49
+ * -----
+ * Last Modified: 2025-09-10 10:22:18
+ * -----
+ *
+ */
+
+/**
+ * @module core/AutoCoreTagTypes
+ *
+ * Core type system for AutoCore's tag layer:
+ * - Strongly-typed tag values (boolean/number/string/json)
+ * - Optional **scales** for numeric unit conversion (e.g., mm ⇄ in)
+ * - Optional **codecs** to present richer client-side types (Date/Map) while
+ *   keeping pure JSON across the wire (serde_json::Value on the server)
+ */
+
+export type PrimitiveKind = "boolean" | "number" | "string" | "json";
+
+/** Strict JSON value (mirrors serde_json::Value) */
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+  | JsonPrimitive
+  | { [key: string]: JsonValue }
+  | JsonValue[];
+
+/**
+ * Extended client-side value you *may* choose to present in the UI.
+ * Use codecs to round-trip these as pure JSON to the server.
+ */
+export type ExtendedJsonValue = JsonValue | Date | Map<string, JsonValue>;
+
+/**
+ * Map a tag's declared primitive kind to the app-visible type.
+ * - "json" becomes ExtendedJsonValue so UIs can work with Date/Map when desired.
+ */
+export type TagValueOf<K extends PrimitiveKind> =
+  K extends "boolean" ? boolean :
+  K extends "number"  ? number  :
+  K extends "string"  ? string  :
+  ExtendedJsonValue;
+
+/**
+ * Runtime binding for a single tag, as returned by hooks like `useAutoCoreTag`.
+ * - `value` is app-visible (already scaled/decoded)
+ * - `rawValue` is the last **unscaled, un-decoded** controller value received (server JSON)
+ * - `write` expects app-visible value (provider will inverse-scale/encode)
+ * - `tap` is typically for boolean momentaries (provider may pulse true→false)
+ */
+export type TagBinding<T> = Readonly<{
+  /** App-visible value (scaled/decoded). */
+  value: T | undefined;
+  /** Last raw value from the server (pre-scale, pre-codec). */
+  rawValue: unknown | undefined;
+  /** Write a new app-visible value (provider will inverse-scale/encode). */
+  write: (displayValue: T) => Promise<void>;
+  /** Momentary action; typically boolean true→false pulse. */
+  tap: () => Promise<void>;
+  /** True while initial read/bootstrapping is in progress. */
+  isLoading: boolean;
+}>;
+
+/**
+ * Configuration for a named scale group.
+ * Apply by setting `scale: "<name>"` on numeric tags.
+ */
+export interface ScaleConfig {
+  /** Unique name for this scale group (e.g., "position", "load") */
+  name: string;
+  /** Current scale factor — incoming values ×= scale; outgoing values /= scale */
+  scale: number;
+  /** Units/label for display (e.g., "mm", "in", "lbs") */
+  label: string;
+  /** Optional description for debugging/documentation */
+  description?: string;
+  /**
+   * Optional server tag that provides the scale dynamically.
+   * (If used, your provider should subscribe and update `scale` when it changes.)
+   */
+  serverTag?: {
+    domain: string;
+    symbolName: string;
+  };
+}
+
+/**
+ * A codec lets a tag expose a richer client-side type while staying JSON on the wire.
+ * Common examples:
+ * - Date values: ISO string ⇄ Date
+ * - Map-like blobs: object ⇄ Map<string, JsonValue>
+ */
+export type TagCodec<TIn = unknown, TOut extends JsonValue = JsonValue> = {
+  /** raw JSON (from server) → app-visible value */
+  fromServer?: (raw: unknown) => TIn;
+  /** app-visible value → pure JSON (to server) */
+  toServer?: (value: TIn) => TOut;
+};
+
+/**
+ * Tag configuration descriptor used to build a typed spec.
+ *
+ * @typeParam K - Literal tag name (use `as const` on your spec array)
+ * @typeParam T - Primitive kind for type mapping (boolean/number/string/json)
+ */
+export type TagConfig<
+  K extends string = string,
+  T extends PrimitiveKind = PrimitiveKind
+> = {
+  /** Local key used by UI/consumers (unique within your spec) */
+  tagName: K;
+  /** Domain for the symbol (e.g., "ADS", "MEMORYSTORE") */
+  domain: string;
+  /** Server symbol/topic name (as used by your backend invoke API) */
+  symbolName: string;
+  /** Declared primitive kind for typing and DevPanel rendering */
+  valueType: T;
+
+  /** Optional initial **raw** value before first server update */
+  initialValue?: TagValueOf<T>;
+  /** Optional per-tag hook/config options (e.g., cycle time, debounce) */
+  options?: Record<string, unknown>;
+
+  /**
+   * Optional scale group for numeric tags.
+   * If present, provider will:
+   * - Multiply incoming numbers by the group's `scale`
+   * - Divide outgoing numbers by the group's `scale`
+   */
+  scale?: string;
+
+  /**
+   * Optional codec to present richer UI types while keeping JSON on the wire.
+   * Only commonly used with `valueType: "json"`.
+   */
+  codec?: TagCodec;
+};
+
+/** Extract the tag config for a particular tag name `K` from a `Spec` */
+export type ExtractByTag<
+  Spec extends readonly TagConfig[],
+  K
+> = Extract<Spec[number], { tagName: K }>;
+
+/**
+ * Build a strongly-typed map of tagName → app-visible value type.
+ * Use with `as const` specs to preserve literal tag names.
+ */
+export type TagValueMap<Spec extends readonly TagConfig[]> = {
+  [K in Spec[number]["tagName"]]: TagValueOf<ExtractByTag<Spec, K>["valueType"]>;
+};
+
+/**
+ * Helper: binding type for a specific tag name from a spec.
+ */
+export type BindingOf<
+  Spec extends readonly TagConfig[],
+  K extends Spec[number]["tagName"]
+> = TagBinding<TagValueMap<Spec>[K]>;
+
+/**
+ * Enhanced context value with scale management.
+ * Providers should:
+ * - Buffer **raw** values in `rawValues` (pre-scale, pre-codec)
+ * - Populate `values` from `rawValues` using current scales/codecs
+ * - Inverse-scale/encode on write(t) before invoking backend
+ */
+export interface BaseContextValue<VMap extends Record<string, any>> {
+  /** Current app-visible tag values (already scaled/decoded). */
+  values: Partial<VMap>;
+
+  /** Last raw (controller) values, as received (pre-scale, pre-codec). */
+  rawValues: Record<string, unknown>;
+
+  /** Whether initial reads are pending. */
+  isLoading: boolean;
+
+  /**
+   * Write a single tag value (app-visible → provider will inverse-scale/encode).
+   * Strongly typed by tag name when used with a typed Context.
+   */
+  write: <K extends keyof VMap & string>(tagName: K, value: VMap[K]) => Promise<void>;
+
+  /**
+   * Trigger a momentary/toggle action for a tag.
+   * Typically used for boolean "request" bits.
+   */
+  tap: <K extends keyof VMap & string>(tagName: K) => Promise<void>;
+
+  /** Current scale configurations by name. */
+  scales: Record<string, ScaleConfig>;
+
+  /**
+   * Update a scale group (factor and label). Providers should recompute affected tags from **raw**.
+   *
+   * @param scaleName - Name of the scale group (e.g., "position")
+   * @param newScale  - New scale factor (display = raw * newScale)
+   * @param newLabel  - New units label (e.g., "inches")
+   */
+  updateScale: (scaleName: string, newScale: number, newLabel: string) => Promise<void>;
+}