@adcops/autocore-react 3.3.115 → 3.3.116

package/src/components/index.ts

@@ -15,6 +15,7 @@ export {
     useTisSelection,
     useTisRuns,
     useTisRun,
+    useTisCycleConfig,
 } from './tis/TisProvider';
 export type {
     TisProviderProps,
@@ -25,6 +26,7 @@ export type {
     TisRunCacheEntry,
     SchemaRegistry,
     TisMethodSchema,
+    TisCycleConfigState,
 } from './tis/TisProvider';
 
 export { ProjectSelector }     from './tis/ProjectSelector';
@@ -36,6 +38,18 @@ export type { TestSetupFormProps } from './tis/TestSetupForm';
 export { TestSetupView }       from './tis/TestSetupView';
 export type { TestSetupViewProps } from './tis/TestSetupView';
 
+export { TestFieldRow }        from './tis/TestFieldRow';
+export type { TestFieldRowProps, CycleConfigScope } from './tis/TestFieldRow';
+
+export { CycleConfigForm, cycleConfigSummary } from './tis/CycleConfigForm';
+export type { CycleConfigFormProps } from './tis/CycleConfigForm';
+
+export { CycleConfigDialog, useCycleConfigGate } from './tis/CycleConfigDialog';
+export type { CycleConfigDialogProps, CycleConfigGate } from './tis/CycleConfigDialog';
+
+export { CycleStatusStrip }    from './tis/CycleStatusStrip';
+export type { CycleStatusStripProps } from './tis/CycleStatusStrip';
+
 export { ProjectInfoDialog }   from './tis/ProjectInfoDialog';
 export type { ProjectInfoDialogProps, ProjectInfoMode } from './tis/ProjectInfoDialog';
 

package/src/components/tis/CycleConfigDialog.tsx

@@ -0,0 +1,173 @@
+/*
+ * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
+ *
+ * <CycleConfigDialog> — the `prompt_before_cycle` entry dialog.
+ *
+ * Some methods can't tolerate a mislabelled row: getting the position
+ * wrong means re-running the sample. Those declare
+ * `prompt_before_cycle: true`, and this dialog puts the entry in front of
+ * the operator at the boundary instead of trusting them to have filled
+ * the Cycle tab. It opens on the server-computed `prompt_due` edge — a
+ * boundary reached with nothing latched — so the scope rules stay in one
+ * place (the server) rather than being re-derived here.
+ *
+ * Two ways to use it:
+ *
+ *   1. Mounted plainly, it opens by itself whenever a prompt comes due:
+ *
+ *          <CycleConfigDialog />
+ *
+ *   2. Driven from your Start handler, so the press itself opens it when
+ *      the annotation is missing and runs the start when it isn't:
+ *
+ *          const gate = useCycleConfigGate();
+ *          <Button label="Start" onClick={() => gate.run(startTest)} />
+ *          <CycleConfigDialog controller={gate} />
+ *
+ * The second form is the one to reach for on a machine whose Start lives
+ * in the footer: the press is never silently swallowed — it either starts
+ * the test or explains, in a dialog, exactly what is missing.
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Button } from 'primereact/button';
+import { Dialog } from 'primereact/dialog';
+import { useTis } from './TisProvider';
+import { CycleConfigForm } from './CycleConfigForm';
+import { labelOf } from './TestFieldRow';
+
+/** Handle returned by [`useCycleConfigGate`]. */
+export interface CycleConfigGate {
+    /** True while the dialog should be open. */
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    /**
+     * Gate an action on the annotation being complete. When the entry is
+     * ready, `action` runs immediately. When it isn't, the dialog opens
+     * instead and `action` is held until the operator completes the fields
+     * and confirms — so a Start press is deferred, never dropped.
+     */
+    run: (action: () => void) => void;
+    /** Run the held action and close. Called by the dialog's confirm. */
+    confirm: () => void;
+    /** Drop the held action and close. */
+    cancel: () => void;
+    /** True when the gate is blocking (required fields empty). */
+    blocked: boolean;
+}
+
+/**
+ * Wire a Start affordance to the Cycle Configuration gate.
+ *
+ * Deliberately does NOT return a `disabled` flag for Start. A greyed-out
+ * Start in the corner of a touchscreen reads as "the machine is broken"
+ * and the operator's next move is a phone call; a press that opens a
+ * dialog naming the missing field teaches the workflow in one go.
+ */
+export const useCycleConfigGate = (): CycleConfigGate => {
+    const tis = useTis();
+    const [open, setOpen] = useState(false);
+    // Held across the dialog's lifetime rather than kept in state: it is
+    // never rendered, and re-rendering on every Start press would reopen
+    // the question of whether the action is stale.
+    const held = useRef<(() => void) | null>(null);
+    const blocked = tis.cycleConfigFields.length > 0 && !tis.cycleConfig.ready;
+
+    const run = useCallback((action: () => void) => {
+        const needsEntry = tis.cycleConfigFields.length > 0
+            && (!tis.cycleConfig.ready || tis.cycleConfig.promptDue);
+        if (!needsEntry) { action(); return; }
+        held.current = action;
+        setOpen(true);
+    }, [tis.cycleConfigFields.length, tis.cycleConfig.ready, tis.cycleConfig.promptDue]);
+
+    const confirm = useCallback(() => {
+        const action = held.current;
+        held.current = null;
+        setOpen(false);
+        action?.();
+    }, []);
+
+    const cancel = useCallback(() => {
+        held.current = null;
+        setOpen(false);
+    }, []);
+
+    return { open, setOpen, run, confirm, cancel, blocked };
+};
+
+export interface CycleConfigDialogProps {
+    /** Gate handle from [`useCycleConfigGate`]. Omit to let the dialog
+     *  open itself on the server's `prompt_due` edge. */
+    controller?: CycleConfigGate;
+    /** Label on the confirm button. Default "Continue". Set it to
+     *  "Start" when the dialog is gating a Start press. */
+    confirmLabel?: string;
+}
+
+export const CycleConfigDialog: React.FC<CycleConfigDialogProps> = ({
+    controller, confirmLabel = 'Continue',
+}) => {
+    const tis = useTis();
+    const cfg = tis.cycleConfig;
+    const fields = tis.cycleConfigFields;
+
+    const [selfOpen, setSelfOpen] = useState(false);
+    const open = controller ? controller.open : selfOpen;
+
+    // Self-opening mode: follow the server's prompt_due edge. Rising edge
+    // only — an operator who dismisses the dialog isn't re-prompted until
+    // the next boundary, and the `tis.cycle_ready` gate still stops the
+    // machine in the meantime.
+    const prevPromptDue = useRef(false);
+    useEffect(() => {
+        if (controller) return;
+        const due = cfg.promptBeforeCycle && cfg.promptDue && fields.length > 0;
+        if (due && !prevPromptDue.current) setSelfOpen(true);
+        prevPromptDue.current = due;
+    }, [controller, cfg.promptBeforeCycle, cfg.promptDue, fields.length]);
+
+    // With a controller, confirming releases the held action (the Start
+    // press that was deferred). Self-opening, there's nothing to release.
+    const confirm = () => (controller ? controller.confirm() : setSelfOpen(false));
+    const cancel  = () => (controller ? controller.cancel()  : setSelfOpen(false));
+
+    const missingLabels = cfg.missing
+        .map(n => fields.find(f => f.name === n))
+        .filter((f): f is NonNullable<typeof f> => !!f)
+        .map(labelOf);
+
+    return (
+        <Dialog
+            header="Cycle Configuration"
+            visible={open}
+            onHide={cancel}
+            style={{ width: '34rem', maxWidth: '95vw' }}
+            modal
+            footer={
+                <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '1rem' }}>
+                    <span style={{ color: 'var(--text-secondary-color)', textAlign: 'left' }}>
+                        {cfg.ready
+                            ? 'Recorded on the next cycle.'
+                            : `Still required: ${missingLabels.join(', ')}`}
+                    </span>
+                    <span>
+                        <Button label="Cancel" text onClick={cancel} />
+                        <Button
+                            label={confirmLabel}
+                            icon="pi pi-check"
+                            // The only place a disabled control is right:
+                            // this button *is* the start, and starting with
+                            // the entry incomplete is what we're preventing.
+                            // The reason is spelled out beside it.
+                            disabled={!cfg.ready}
+                            onClick={confirm}
+                        />
+                    </span>
+                </div>
+            }
+        >
+            <CycleConfigForm compact />
+        </Dialog>
+    );
+};

package/src/components/tis/CycleConfigForm.tsx

@@ -0,0 +1,192 @@
+/*
+ * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
+ *
+ * <CycleConfigForm> — the Cycle tab. Operator-entered annotation that is
+ * recorded onto each cycle row: "which of the six positions is this?"
+ *
+ * Renders the selected method's `cycle_config_fields` with the same field
+ * rendering, unit handling and validation rules as Test Configuration (see
+ * TestFieldRow.tsx). What differs is the commit path and the lifecycle:
+ *
+ *   - Every edit round-trips through `tis.set_cycle_config` immediately.
+ *     There is no local draft: the value the operator sees must be the
+ *     value the server would stamp on the next row, because that is what
+ *     the `tis.cycle_ready` gate is computed from.
+ *   - While a cycle is running its annotation is LATCHED. The fields stay
+ *     visible but read-only, with a note saying edits apply to the next
+ *     cycle — an edit that silently relabelled the row being measured
+ *     would be worse than not being able to type at all.
+ *   - Under `cycle` scope the values clear after each recorded row
+ *     (`autoclear`), the gate re-arms, and the operator annotates again.
+ */
+
+import React, { useContext, useState } from 'react';
+import { Button } from 'primereact/button';
+import { Dialog } from 'primereact/dialog';
+import { Message } from 'primereact/message';
+import { useTis } from './TisProvider';
+import { TestFieldRow, labelOf, type TestFieldDef } from './TestFieldRow';
+import { EventEmitterContext } from '../../core/EventEmitterContext';
+
+export interface CycleConfigFormProps {
+    /** Extra class names applied to the root element. */
+    className?: string;
+    /** Inline style merged onto the root element. */
+    style?: React.CSSProperties;
+    /** Hide the explanatory header (used inside the prompt dialog, where
+     *  the dialog title already says what this is). */
+    compact?: boolean;
+    /** Called after each accepted edit — the dialog uses it to know the
+     *  operator has engaged with the form. */
+    onValueCommitted?: (field: TestFieldDef, raw: any) => void;
+}
+
+/**
+ * One-line summary of what the next recorded row will be labelled with.
+ * Shared by the Cycle tab header and <CycleStatusStrip> so the two can't
+ * describe the same state differently.
+ */
+export const cycleConfigSummary = (
+    fields: TestFieldDef[],
+    values: Record<string, any>,
+): string => {
+    if (fields.length === 0) return '';
+    return fields
+        .map(f => {
+            const v = values?.[f.name];
+            const shown = v === undefined || v === null || v === '' ? '—' : String(v);
+            return `${f.label ?? f.name}: ${shown}`;
+        })
+        .join('   ');
+};
+
+export const CycleConfigForm: React.FC<CycleConfigFormProps> = ({
+    className, style, compact, onValueCommitted,
+}) => {
+    const tis = useTis();
+    const { write } = useContext(EventEmitterContext);
+    const cfg = tis.cycleConfig;
+    const fields = tis.cycleConfigFields;
+    const [infoField, setInfoField] = useState<TestFieldDef | null>(null);
+
+    // A latch exists exactly while a cycle is running against these values.
+    const locked = cfg.latched !== null;
+
+    const commit = async (field: TestFieldDef, raw: any) => {
+        await tis.setCycleConfigValues({ [field.name]: raw ?? null });
+        // A `source`-bound annotation also drives the machine (e.g. the
+        // position the fixture should move to), so mirror it to GM the way
+        // Test Configuration does. Storage on both sides stays RAW.
+        if (field.source) {
+            try { await write(field.source, raw); }
+            catch (e) { console.error('[CycleConfigForm] failed to write source:', e); }
+        }
+        onValueCommitted?.(field, raw);
+    };
+
+    if (fields.length === 0) {
+        return (
+            <div className={className} style={{ padding: '1.25rem', ...style }}>
+                <h3 className="ac-form-section">No Cycle Configuration</h3>
+                <p style={{ color: 'var(--text-secondary-color)', marginTop: '0.5rem' }}>
+                    This test method records no operator-entered columns. Cycle rows
+                    are written entirely from measured values.
+                </p>
+            </div>
+        );
+    }
+
+    const gridStyle: React.CSSProperties = {
+        padding: '1.25rem',
+        gridTemplateColumns: 'auto 1fr 1.75rem 1.75rem',
+    };
+
+    return (
+        <div className={className} style={style}>
+            {!compact && (
+                <div style={{ padding: '1.25rem 1.25rem 0' }}>
+                    <h3 className="ac-form-section" style={{ display: 'flex', alignItems: 'center', gap: '10px' }}>
+                        Cycle Configuration
+                        {/* Status is stated in full by the messages below;
+                            this is the at-a-glance marker beside the title. */}
+                        <i
+                            className={cfg.ready ? 'pi pi-check-circle' : 'pi pi-exclamation-circle'}
+                            style={{ color: cfg.ready ? 'var(--green-500)' : 'var(--red-500)' }}
+                            aria-label={cfg.ready ? 'Cycle Configuration complete' : 'Cycle Configuration incomplete'}
+                        />
+                    </h3>
+                    <p style={{ color: 'var(--text-secondary-color)', margin: '0.25rem 0 0' }}>
+                        {cfg.scope === 'cycle'
+                            ? 'Recorded on the next cycle. Entered again for every cycle.'
+                            : 'Recorded on every cycle of this run.'}
+                    </p>
+                </div>
+            )}
+
+            {locked && (
+                <div style={{ padding: '0.75rem 1.25rem 0' }}>
+                    <Message
+                        severity="info"
+                        text="A cycle is running with these values. Edits apply to the next cycle."
+                    />
+                </div>
+            )}
+
+            {!cfg.ready && !locked && (
+                <div style={{ padding: '0.75rem 1.25rem 0' }}>
+                    <Message
+                        severity="warn"
+                        text={
+                            'Required: ' +
+                            cfg.missing
+                                .map(n => fields.find(f => f.name === n))
+                                .map((f, i) => (f ? labelOf(f) : cfg.missing[i]))
+                                .join(', ') +
+                            '. The machine will not start until these are filled in.'
+                        }
+                    />
+                </div>
+            )}
+
+            <div className="ac-form-grid" style={gridStyle}>
+                {fields.map(field => (
+                    <TestFieldRow
+                        key={field.name}
+                        field={field}
+                        // While latched, show what the running cycle is
+                        // actually recording rather than the pending entry.
+                        value={locked ? cfg.latched?.[field.name] : cfg.values?.[field.name]}
+                        disabled={locked}
+                        onChange={(raw) => { void commit(field, raw); }}
+                        onInfo={(f) => setInfoField(f)}
+                    />
+                ))}
+            </div>
+
+            {!compact && (
+                <div style={{ padding: '0 1.25rem 1.25rem' }}>
+                    <Button
+                        label="Clear"
+                        icon="pi pi-eraser"
+                        text
+                        disabled={locked}
+                        onClick={() => { void tis.clearCycleConfig(); }}
+                        tooltip="Clear every entry, including fields that don't autoclear"
+                        tooltipOptions={{ position: 'top' }}
+                    />
+                </div>
+            )}
+
+            <Dialog
+                header={infoField ? labelOf(infoField) : ''}
+                visible={infoField !== null}
+                onHide={() => setInfoField(null)}
+                style={{ width: '32rem', maxWidth: '90vw' }}
+                modal
+                dismissableMask
+            >
+                <p style={{ margin: 0, whiteSpace: 'pre-wrap' }}>{infoField?.description}</p>
+            </Dialog>
+        </div>
+    );
+};

package/src/components/tis/CycleStatusStrip.tsx

@@ -0,0 +1,84 @@
+/*
+ * Copyright (C) 2026 Automated Design Corp. All Rights Reserved.
+ *
+ * <CycleStatusStrip> — the Cycle Configuration state, rendered where the
+ * operator is already looking: next to the Start button.
+ *
+ * The Cycle tab is three panes away from the run screen. An operator
+ * about to press Start is looking at the lower-right corner of the
+ * footer, not at a tab they may never open, so the annotation that is
+ * about to be written onto the row has to be visible from there. This is
+ * the same idea as the specimen number Bluehill keeps beside its run
+ * control.
+ *
+ * Drop it into the footer beside Start:
+ *
+ *   <div className="footer">
+ *     <CycleStatusStrip />
+ *     <Button label="Start" onClick={...} />
+ *   </div>
+ *
+ * Clicking it opens the entry form in a dialog, so the operator can fill
+ * the fields in without leaving the run screen.
+ */
+
+import React, { useState } from 'react';
+import { Button } from 'primereact/button';
+import { Dialog } from 'primereact/dialog';
+import { useTis } from './TisProvider';
+import { CycleConfigForm, cycleConfigSummary } from './CycleConfigForm';
+
+export interface CycleStatusStripProps {
+    className?: string;
+    style?: React.CSSProperties;
+    /** Render nothing when the method declares no annotation columns.
+     *  Default true — an empty chip beside Start is just noise. */
+    hideWhenUnused?: boolean;
+}
+
+export const CycleStatusStrip: React.FC<CycleStatusStripProps> = ({
+    className, style, hideWhenUnused = true,
+}) => {
+    const tis = useTis();
+    const [open, setOpen] = useState(false);
+    const cfg = tis.cycleConfig;
+    const fields = tis.cycleConfigFields;
+
+    if (fields.length === 0 && hideWhenUnused) return null;
+
+    // Latched values are what the running cycle will actually record;
+    // pending values are what the next one will get.
+    const shown = cfg.latched ?? cfg.values;
+    const summary = cycleConfigSummary(fields, shown);
+    const incomplete = !cfg.ready;
+
+    return (
+        <>
+            <Button
+                className={className}
+                style={style}
+                text
+                severity={incomplete ? 'danger' : undefined}
+                icon={incomplete ? 'pi pi-exclamation-triangle' : 'pi pi-tag'}
+                // Not disabled and not silent: the operator can always open
+                // it, and when something is missing the chip says so in
+                // words rather than making them hunt for a red field.
+                label={incomplete
+                    ? `${summary}  — entry required`
+                    : summary}
+                aria-label="Cycle Configuration"
+                onClick={() => setOpen(true)}
+            />
+            <Dialog
+                header="Cycle Configuration"
+                visible={open}
+                onHide={() => setOpen(false)}
+                style={{ width: '34rem', maxWidth: '95vw' }}
+                modal
+                dismissableMask
+            >
+                <CycleConfigForm />
+            </Dialog>
+        </>
+    );
+};

package/src/components/tis/TestDataView.tsx

@@ -169,6 +169,10 @@ export interface TestMethod {
      * optional so the compiler demands a `?? []` at every use. */
     project_fields?: TestFieldDef[];
     config_fields?:  TestFieldDef[];
+    /** Operator-entered per-row annotation. Recorded onto each cycle row
+     *  by the server and rendered as the first Cycle Data columns after
+     *  the row index, in declared order. */
+    cycle_config_fields?: TestFieldDef[];
     cycle_fields?:   TestFieldDef[];
     results_fields?: TestFieldDef[];
     raw_data?:       RawDataShape | null;
@@ -799,13 +803,25 @@ export const TestDataView: React.FC<TestDataViewProps> = (props) => {
                 // valid and arrives with the key absent. Without the guard the
                 // `.map` throws inside render and React unmounts the whole
                 // app — the operator sees a blank page, not a missing table.
-                const cycleColumns: ScienceColumn[] = (schema.cycle_fields ?? []).map(f => ({
+                // Operator-entered annotation leads, right after the row
+                // index, then the measured columns — the same order the
+                // server writes into every CSV export. Annotation columns
+                // are always editable: they're the operator's own note, so
+                // correcting a mistyped one is the intended workflow (the
+                // server accepts cycle_config_fields on tis.update_cycle
+                // without an `editable` flag), while measured columns still
+                // have to opt in.
+                const toColumn = (f: TestFieldDef, editable: boolean): ScienceColumn => ({
                     field: f.name,
                     label: f.name,
                     units: f.units,
-                    editable: f.editable,
+                    editable,
                     body: (row) => formatCell(row[f.name], f.type, f.scale),
-                }));
+                });
+                const cycleColumns: ScienceColumn[] = [
+                    ...(schema.cycle_config_fields ?? []).map(f => toColumn(f, true)),
+                    ...(schema.cycle_fields ?? []).map(f => toColumn(f, !!f.editable)),
+                ];
                 return (
                     <ScienceTable
                         title={`Cycle Data (${cycles.length})`}