@adcops/autocore-react 3.5.9 → 3.5.11

package/src/components/varpick/tisCatalogs.ts

@@ -0,0 +1,235 @@
+/**
+ * The catalogs the TIS method editor's pickers offer.
+ *
+ * Each field wants a different list, spelled differently, and getting either
+ * wrong fails SILENTLY:
+ *
+ *  - a `config_fields` **Source** is written by the Test Setup form, so a
+ *    hardware-owned variable there would have the operator's entry overwritten
+ *    by the module on the next scan;
+ *  - a **bound** is `${gm.…}` and an unresolvable one means NO bound — the
+ *    field is simply unlimited, with nothing on screen to say so;
+ *  - a `cycle_fields` **Source** has two possible producers and the editor used
+ *    to show neither.
+ *
+ * Which is why the spelling and the filter live here, next to each other, rather
+ * than at each call site.
+ */
+
+import {
+    gmCatalog,
+    type Catalog,
+    type CatalogGroup,
+    type GmVariable,
+    type VariableEntry,
+} from '@adcops/autocore-varpick';
+
+export interface TisCatalogContext {
+    /** From `gm.get_variables` (or the tag-spec fallback). */
+    variables: GmVariable[];
+    /** Unit label for a quantity, from the machine's resolved units.json. */
+    unitFor?: (quantity: string) => string | undefined;
+    /** Current value, formatted, by FQDN. */
+    liveFor?: (fqdn: string) => string | undefined;
+}
+
+/**
+ * Variables a form field may WRITE — a `config_fields` source.
+ *
+ * `TestSetupForm` writes the operator's entry straight to this tag, so a
+ * variable produced by a module is not a candidate: the write would land and
+ * then be overwritten before anything read it.
+ */
+export function configSourceCatalog(ctx: TisCatalogContext): Catalog {
+    return gmCatalog(ctx.variables, {
+        spelling: 'fqdn',
+        writableOnly: true,
+        unitFor: ctx.unitFor,
+        liveFor: ctx.liveFor,
+    });
+}
+
+/** Variables a bound (`min`/`max`) or a token default may READ. */
+export function boundCatalog(ctx: TisCatalogContext): Catalog {
+    return gmCatalog(ctx.variables, {
+        spelling: 'token',
+        unitFor: ctx.unitFor,
+        liveFor: ctx.liveFor,
+    });
+}
+
+/**
+ * Where a **cycle field's** value comes from.
+ *
+ * The one catalog that is not just a variable list, because a cycle field has
+ * two possible producers and picking the wrong kind is invisible:
+ *
+ *  1. `source: "gm.<var>"` — the generated `add_cycle()` reads the tag.
+ *  2. `source: null` — whoever records the row supplies it by NAME. On gen4_ac
+ *     that is the sequencer: a `store_value` step fills a row buffer keyed by
+ *     name, and `tis.add_cycle` writes `cycle_data` verbatim without checking it
+ *     against `cycle_fields`. So a declared column with no producer is blank on
+ *     every row, forever, and nothing says why.
+ *
+ * Offering only FQDNs — which is what a plain variable picker would do — lets an
+ * author wire a binding that never fills. So the sequence's own `store_value`
+ * names are offered as a first-class group, and choosing one CLEARS the source
+ * (its `insert` is the empty string) rather than setting a binding.
+ */
+export function cycleSourceCatalog(
+    ctx: TisCatalogContext,
+    opts: {
+        /** `store_value` names in this method's `.seq.json`, if the host read it. */
+        producedNames?: string[];
+        /** The cycle field being edited, so its own name can be highlighted. */
+        fieldName?: string;
+    },
+): Catalog {
+    const groups: CatalogGroup[] = [];
+
+    const produced = opts.producedNames ?? [];
+    if (produced.length > 0) {
+        const entries: VariableEntry[] = produced.map(name => ({
+            id: `seq:${name}`,
+            // Choosing a sequence-produced value means there is NO source: the
+            // row arrives carrying this name.
+            insert: '',
+            name,
+            kind: 'column',
+            description:
+                name === opts.fieldName
+                    ? 'The sequence stores this name every cycle, and it matches this column. Nothing else is needed — leave Source empty.'
+                    : `The sequence stores this name every cycle. It only lands in this column if the column is called "${name}" too.`,
+            note:
+                name === opts.fieldName
+                    ? undefined
+                    : `Rename this field to "${name}", or the value is recorded with no column to show it in.`,
+            keywords: ['sequence', 'store_value'],
+        }));
+        groups.push({
+            id: 'sequence',
+            title: 'Recorded by the sequence',
+            hint: 'Matched by NAME, not by binding. Picking one clears Source — that is correct, and is how gen4_ac records every column.',
+            entries,
+        });
+    }
+
+    // Reading a GM tag at record time is the other legitimate producer, so the
+    // variables are still offered — below the sequence, because on a machine
+    // with a sequencer they are the less likely answer.
+    groups.push(
+        ...gmCatalog(ctx.variables, {
+            spelling: 'fqdn',
+            unitFor: ctx.unitFor,
+            liveFor: ctx.liveFor,
+        }),
+    );
+
+    return groups;
+}
+
+/**
+ * Columns a chart axis or series may plot.
+ *
+ * A chart naming a column that does not exist renders an empty plot with no
+ * error, which reads as "the machine recorded nothing".
+ */
+export function chartFieldCatalog(opts: {
+    cycleFields?: string[];
+    resultsFields?: string[];
+    rawColumns?: string[];
+    /** Project/config fields — one value for the whole test. */
+    testFields?: string[];
+    /** `raw_trace` views plot raw columns; `cycle_scatter` plots cycle fields. */
+    viewType?: string;
+}): Catalog {
+    const groups: CatalogGroup[] = [];
+    const toEntries = (names: string[], kind: string): VariableEntry[] =>
+        names.map(name => ({ id: `${kind}:${name}`, insert: name, name, kind: 'column' as const }));
+
+    const raw = opts.rawColumns ?? [];
+    const cycle = opts.cycleFields ?? [];
+    const results = opts.resultsFields ?? [];
+
+    // The view's own type decides which list is the likely answer, so it goes
+    // first — but neither list is hidden, because a method can legitimately
+    // chart across both.
+    const rawFirst = opts.viewType === 'raw_trace';
+    const rawGroup: CatalogGroup = {
+        id: 'raw',
+        title: 'Raw trace columns',
+        hint: 'Per-cycle trace columns declared under Raw Data.',
+        entries: toEntries(raw, 'raw'),
+    };
+    const cycleGroup: CatalogGroup = {
+        id: 'cycle',
+        title: 'Cycle Data columns',
+        hint: 'One value per cycle.',
+        entries: toEntries(cycle, 'cycle'),
+    };
+
+    if (rawFirst) groups.push(rawGroup, cycleGroup);
+    else groups.push(cycleGroup, rawGroup);
+
+    groups.push({
+        id: 'results',
+        title: 'Results',
+        hint: 'One value per test.',
+        entries: toEntries(results, 'result'),
+    });
+    groups.push({
+        id: 'test',
+        title: 'Test setup values',
+        hint: 'Entered once per test, so they plot as a constant across cycles.',
+        entries: toEntries(opts.testFields ?? [], 'test'),
+    });
+
+    return groups.filter(g => g.entries.length > 0);
+}
+
+/**
+ * Sources a raw-data column may read.
+ *
+ * `time` and `derived` are the two the server always understands; everything
+ * else is a module channel FQDN. The channel list is not modelled here — the
+ * editor has no NI catalog — so the two known values are offered by name and
+ * the field stays free text for the rest.
+ */
+export function rawSourceCatalog(channels?: string[]): Catalog {
+    const groups: CatalogGroup[] = [
+        {
+            id: 'builtin',
+            title: 'Built-in',
+            entries: [
+                {
+                    id: 'src:time',
+                    insert: 'time',
+                    name: 'time',
+                    kind: 'column',
+                    description: 'Sample timestamp, seconds from the start of the cycle.',
+                },
+                {
+                    id: 'src:derived',
+                    insert: 'derived',
+                    name: 'derived',
+                    kind: 'column',
+                    description: 'Computed from the other columns by this column’s Formula.',
+                },
+            ],
+        },
+    ];
+    if (channels && channels.length > 0) {
+        groups.push({
+            id: 'channels',
+            title: 'DAQ channels',
+            hint: 'Published by the acquisition module.',
+            entries: channels.map(c => ({
+                id: `chan:${c}`,
+                insert: c,
+                name: c,
+                kind: 'column' as const,
+            })),
+        });
+    }
+    return groups;
+}

package/src/components/varpick/varpick.css

@@ -0,0 +1,167 @@
+/*
+ * Variable picker.
+ *
+ * Colours come from the PrimeReact theme's variables so the dialog matches
+ * whatever theme the machine is running, light or dark. Every value has a
+ * literal fallback: an un-themed host (the playground, a test harness) must
+ * still render legible text rather than black on black.
+ */
+
+.ac-varpick__input {
+    display: flex;
+    align-items: stretch;
+    gap: 0;
+    min-width: 0;
+}
+
+.ac-varpick__input .p-inputtext {
+    flex: 1 1 auto;
+    min-width: 0;
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+}
+
+/* Sized to the full control height, not shrunk to fit: these screens are
+ * touchscreens, and a button an operator has to aim at is one they mis-tap. */
+.ac-varpick__input > .p-button {
+    flex: 0 0 auto;
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+    margin-left: -1px;
+}
+
+.ac-varpick__hint {
+    font-size: 0.8125rem;
+    color: var(--text-color-secondary, #6b7280);
+    margin-bottom: 0.75rem;
+    line-height: 1.4;
+}
+
+.ac-varpick__search { width: 100%; }
+
+.ac-varpick__empty {
+    padding: 1.5rem 0.25rem;
+    color: var(--text-color-secondary, #6b7280);
+    font-size: 0.875rem;
+}
+
+.ac-varpick__list {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    margin-top: 0.75rem;
+    /* Bounded so the search box and the footer stay put while the list moves. */
+    max-height: 55vh;
+    overflow-y: auto;
+}
+
+.ac-varpick__group { display: flex; flex-direction: column; gap: 2px; }
+
+.ac-varpick__grouphead {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 0.5rem;
+    padding-bottom: 0.25rem;
+    margin-bottom: 0.25rem;
+    border-bottom: 1px solid var(--surface-border, rgba(127, 127, 127, 0.25));
+    position: sticky;
+    top: 0;
+    background: var(--surface-overlay, #ffffff);
+    z-index: 1;
+}
+
+.ac-varpick__grouptitle {
+    font-size: 0.75rem;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--text-color-secondary, #6b7280);
+}
+
+.ac-varpick__grouphint {
+    font-size: 0.75rem;
+    color: var(--text-color-secondary, #8b95a1);
+}
+
+/*
+ * Two lines by design — the identifier, then what it MEANS. A one-line list of
+ * identifiers is the problem this dialog exists to solve, so the description is
+ * never truncated and never hidden behind a hover: there is no hover on a
+ * touchscreen.
+ */
+.ac-varpick__row {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+    width: 100%;
+    text-align: left;
+    min-height: 2.25rem;
+    padding: 0.375rem 0.75rem;
+    border: 1px solid transparent;
+    border-radius: 3px;
+    background: transparent;
+    color: var(--text-color, #111827);
+    font: inherit;
+    cursor: pointer;
+}
+
+.ac-varpick__row:hover { background: var(--surface-hover, rgba(127, 127, 127, 0.08)); }
+
+.ac-varpick__row:focus-visible {
+    outline: 2px solid var(--primary-color, #2563eb);
+    outline-offset: -2px;
+}
+
+.ac-varpick__row--on {
+    background: var(--highlight-bg, rgba(37, 99, 235, 0.14));
+    border-color: var(--primary-color, #2563eb);
+}
+
+.ac-varpick__row--off { opacity: 0.55; cursor: default; }
+
+.ac-varpick__line {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: 0.5rem;
+    min-width: 0;
+}
+
+.ac-varpick__name {
+    font-family: var(--font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+    font-weight: 600;
+}
+
+.ac-varpick__label { font-size: 0.875rem; }
+
+.ac-varpick__chip {
+    font-size: 0.75rem;
+    padding: 0 6px;
+    border-radius: 999px;
+    background: var(--surface-100, rgba(127, 127, 127, 0.12));
+    border: 1px solid var(--surface-border, rgba(127, 127, 127, 0.25));
+    color: var(--text-color-secondary, #6b7280);
+    /* A unit symbol's case is meaningful: "mm/s", "N", "MPa". */
+    text-transform: none;
+}
+
+/* The current reading. Nothing turns an unfamiliar name into an obvious one
+ * faster than seeing what it says right now. */
+.ac-varpick__live {
+    font-family: var(--font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+    font-size: 0.75rem;
+    color: var(--green-600, #15803d);
+}
+
+.ac-varpick__desc {
+    font-size: 0.8125rem;
+    color: var(--text-color-secondary, #6b7280);
+    line-height: 1.35;
+}
+
+.ac-varpick__why { font-size: 0.8125rem; color: var(--orange-600, #b45309); }
+.ac-varpick__note { font-size: 0.8125rem; color: var(--blue-600, #0369a1); }
+
+.ac-varpick__foot { display: flex; justify-content: flex-end; gap: 0.5rem; }

package/src/core/AutoCoreTagContext.tsx

@@ -112,6 +112,7 @@ export const AutoCoreTagContext = createContext<BaseContextValue<VMapRuntime>>({
     scales: {},
     updateScale: async () => { },
     findTagByFqdn: () => undefined,
+    tags: [],
 });
 
 /**
@@ -912,12 +913,13 @@ export const AutoCoreTagProvider: React.FC<{
             scales: scaleValues,
             updateScale,
             findTagByFqdn,
+            tags,
             units,
             activeSystem,
             setUnitSystem,
             formatQuantity,
             }), [values, rawValues, isLoading, write, tap, press, release, scaleValues,
-                 updateScale, findTagByFqdn, units, activeSystem, setUnitSystem, formatQuantity]);
+                 updateScale, findTagByFqdn, tags, units, activeSystem, setUnitSystem, formatQuantity]);
 
 
     return (

package/src/core/AutoCoreTagTypes.ts

@@ -435,4 +435,18 @@ export interface BaseContextValue<VMap extends Record<string, any>> {
      * if no tag is registered for the given FQDN.
      */
     findTagByFqdn: (fqdn: string) => TagConfig | undefined;
+
+    /**
+     * The tag spec this provider was built with.
+     *
+     * Exposed so a consumer can enumerate what the HMI knows about rather than
+     * having every host thread `acTagSpec` down by hand. The variable picker
+     * uses it as its fallback catalog when the server is an older build with no
+     * `gm.get_variables` — names and types, no descriptions.
+     *
+     * It is NOT the machine's full variable table: `acctl codegen-tags` emits
+     * only variables marked `ux: true`. Treat it as a floor, never as the
+     * authoritative list.
+     */
+    tags: readonly TagConfig[];
 }

package/src/hooks/index.ts

@@ -11,3 +11,14 @@
 export {useAdsRegisterSymbols, useAdsWriteValue, useAdsTapValue} from "./adsHooks";
 export {useScaledValue, kMillimeters2Inches } from './useScaledValue';
 export * from './useServeletData';
+
+// The machine's GM variable table, described — the catalog behind the
+// variable picker. Degrades to the generated tag spec on a server too old to
+// answer `gm.get_variables`.
+export { useGmVariables } from './useGmVariables';
+export type { UseGmVariablesResult, UseGmVariablesOptions, GmIpcInvoker } from './useGmVariables';
+
+// The `store_value` names a method's sequence records — the other producer of
+// a TIS cycle column, and the one nothing used to check.
+export { useSequenceProducers, collectStoredNames } from './useSequenceProducers';
+export type { UseSequenceProducersResult, UseSequenceProducersOptions } from './useSequenceProducers';

package/src/hooks/useGmVariables.ts

@@ -0,0 +1,142 @@
+/**
+ * useGmVariables — the machine's GM variable table, for the variable picker.
+ *
+ * Reads `gm.get_variables`: `gm.get_catalog` with the metadata attached — type,
+ * description, quantity, and whether a UI may write the variable. Everything it
+ * returns already lives in project.json; the verb exists because a catalog of
+ * bare FQDN strings cannot tell an author what a name means, which is why every
+ * field that asks for one has been a text box.
+ *
+ * ## Degrading on an older server
+ *
+ * `gm.get_variables` was added alongside the picker, so a machine running an
+ * older `autocore_server` answers with an error. That is not a failure worth
+ * showing an operator: the picker still works, it just lists names without
+ * descriptions. So the hook falls back to the generated tag spec the HMI
+ * already has (`acTagSpec`), which carries FQDN, type and quantity but no prose,
+ * and reports the degradation through `partial` rather than through `error`.
+ *
+ * The fallback covers strictly less: `acctl codegen-tags` only emits variables
+ * marked `ux: true`, and a `${gm.…}` bound may legitimately name one that is
+ * not. Hence `partial` — a caller can say so on screen instead of quietly
+ * offering an incomplete list.
+ */
+
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import type { GmVariable } from '@adcops/autocore-varpick';
+import { EventEmitterContext } from '../core/EventEmitterContext';
+import { MessageType } from '../hub/CommandMessage';
+import type { TagConfig } from '../core/AutoCoreTagTypes';
+
+export interface GmIpcInvoker {
+    (topic: string, payload: object): Promise<{
+        success: boolean;
+        data?: any;
+        error_message?: string;
+    }>;
+}
+
+export interface UseGmVariablesOptions {
+    invoker?: GmIpcInvoker;
+    /**
+     * The HMI's generated tag spec, used when the server cannot describe its
+     * own variables. Without it, an old server yields an empty picker.
+     */
+    fallbackTags?: readonly TagConfig[];
+    /** Skip the read entirely (e.g. while a dialog is closed). */
+    enabled?: boolean;
+}
+
+export interface UseGmVariablesResult {
+    variables: GmVariable[];
+    loading: boolean;
+    /**
+     * True when the list came from the generated tag spec rather than the
+     * server — names and types, no descriptions, and `ux: true` variables only.
+     */
+    partial: boolean;
+    /** Set only when there is nothing to show at all. */
+    error: string | null;
+    refresh: () => Promise<void>;
+}
+
+/** Derive what a tag spec can honestly say about a variable, and nothing more. */
+function fromTagSpec(tags: readonly TagConfig[]): GmVariable[] {
+    return tags
+        .filter(t => typeof t.fqdn === 'string' && t.fqdn.toLowerCase().startsWith('gm.'))
+        .map(t => ({
+            fqdn: t.fqdn,
+            name: t.fqdn.slice(3),
+            type: String(t.valueType ?? ''),
+            description: '',
+            quantity: t.quantity ?? t.scale,
+            // Everything in the tag spec is there BECAUSE it is ux-exposed.
+            ux: true,
+            nonvolatile: false,
+            // The tag spec does not record a link, and guessing "writable"
+            // wrong in this direction is the safe one: the picker shows the
+            // variable and the machine refuses a pointless write, rather than
+            // the variable vanishing from a list with no explanation.
+            writable: true,
+            is_signal: false,
+        }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function useGmVariables(options?: UseGmVariablesOptions): UseGmVariablesResult {
+    const ctx = useContext(EventEmitterContext);
+    const enabled = options?.enabled !== false;
+
+    const invoker: GmIpcInvoker = options?.invoker
+        ?? (async (topic, payload) => await ctx.invoke(topic as any, MessageType.Request, payload as any));
+
+    // Same stability trick as useTisConfig: a caller that builds its invoker
+    // inline would otherwise change it every render and re-trigger the effect
+    // in a loop.
+    const invokerRef = useRef(invoker);
+    invokerRef.current = invoker;
+    const fallbackRef = useRef(options?.fallbackTags);
+    fallbackRef.current = options?.fallbackTags;
+
+    const [variables, setVariables] = useState<GmVariable[]>([]);
+    const [loading, setLoading] = useState<boolean>(enabled);
+    const [partial, setPartial] = useState<boolean>(false);
+    const [error, setError] = useState<string | null>(null);
+
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        try {
+            const res = await invokerRef.current('gm.get_variables', {});
+            const list = res?.data?.variables;
+            if (res?.success && Array.isArray(list)) {
+                setVariables(list as GmVariable[]);
+                setPartial(false);
+                setError(null);
+                return;
+            }
+            throw new Error(res?.error_message || 'gm.get_variables returned no variables');
+        } catch (e: any) {
+            const tags = fallbackRef.current;
+            if (tags && tags.length > 0) {
+                setVariables(fromTagSpec(tags));
+                setPartial(true);
+                setError(null);
+            } else {
+                setVariables([]);
+                setPartial(false);
+                setError(String(e?.message ?? e));
+            }
+        } finally {
+            setLoading(false);
+        }
+    }, []);
+
+    useEffect(() => {
+        if (!enabled) { setLoading(false); return; }
+        void refresh();
+    }, [enabled, refresh]);
+
+    return { variables, loading, partial, error, refresh };
+}
+
+export default useGmVariables;