web/src/customer-grid/ScriptViewPanel.tsx

// ---------------------------------------------------------------------------
// customer-grid / ScriptViewPanel.tsx — owner item 6's renderer (W36-T04, contract C3).
//
// ⛔ ITS OWN MODULE, AND THAT IS A HARNESS FACT AS WELL AS A TIDINESS ONE. It began inside
// `viewModes.tsx`, where the other display modes live — and that module `require`s `./cells`,
// which imports glide-data-grid, whose CJS build cannot load under this repo's node harness. So
// putting it there made the whole component untestable: the ONE thing this surface must prove is
// that a hostile spec is rendered as text, and that claim can only be made by RENDERING. Here the
// import graph is `react` + `./scriptViews` and nothing else, so `gridUx.test.ts` renders it for
// real and asserts on the HTML a person would receive.
// ⚠ The stylesheet is imported by `CustomerGrid.tsx` (the mount) for the same reason: tsc
// preserves a side-effect CSS import into the emitted CommonJS and node dies on it.
// ---------------------------------------------------------------------------

import { memo, useEffect, useRef, useState } from "react";
import { barScale, renderableSpec, specKindName } from "./scriptViews";
import type { DrawableSpec, ScriptRun, ScriptView as ScriptViewRecord } from "./scriptViews";

// ═══════════════════════════════════════════════════════════════════════════════════════════
// ⭐⭐ W36-T04 (owner item 6 · rulings R3/R10 · contract C3) — THE CODE-SCRIPT VIEW
//
// Owner, verbatim: *"Add code script as an interface (database View) so a user can build whatever
// they want through the Agent chat interface. be able to create any dashboard they want. User
// should have the ability to see the code AND the dashboard output of course."* Both halves are
// on screen at once, which is the whole of that sentence.
//
// ⛔⛔ NO BRANCH OF THIS RENDERER EXECUTES A STRING, AND THAT IS THE TICKET'S OWN `done-when`.
// R10 runs the Python in a SERVER sandbox exactly so the browser never has to trust the result;
// a renderer that then evaluated one would hand back everything the sandbox contains. So there is
// no `dangerouslySetInnerHTML`, no `new Function`, no `eval`, no `href`/`src` taken from a spec,
// and no `style` built from spec data anywhere below. Every value reaching the DOM is a SCALAR
// that `renderableSpec` admitted, rendered as TEXT — the one exception being a bar's width, which
// is a number clamped to a percentage here and never a string from the wire.
//
// ⛔ AN UNKNOWN `kind` IS A SENTENCE, NOT A BLANK. `spec` is whatever the script emitted (E's C3
// note 1: there is no fixed vocabulary, deliberately), so a view whose author invented
// `kind: "sankey"` is a legitimate thing this build cannot draw. Saying so, by name, is the
// difference between "this build does not know that shape yet" and "your script is broken".
//
// ⚠ `ok: false` IS A 200. A script that timed out or divided by zero asked a well-formed question
// whose ANSWER is that no view was produced; it is rendered beside the code, never thrown, and
// never a toast that disappears while the reader is looking at the line that caused it.
// ═══════════════════════════════════════════════════════════════════════════════════════════

function SpecTable({ spec }: { spec: DrawableSpec }) {
  return (
    <table className="cg-script-table">

      <thead>

        <tr>{(spec.columns ?? []).map((c, i) => <th key={`${c}:${i}`} scope="col">{c}</th>)}</tr>

      </thead>

      <tbody>

        {(spec.rows ?? []).map((row, r) => (

          <tr key={r}>{row.map((cell, c) => <td key={c}>{cell}</td>)}</tr>

        ))}

      </tbody>

    </table>
  );
}

function SpecMetrics({ spec }: { spec: DrawableSpec }) {
  return (
    <div className="cg-script-metrics">

      {(spec.items ?? []).map((item, i) => (

        <div className="cg-script-metric" key={`${item.label}:${i}`}>

          <div className="cg-script-metric-label">{item.label}</div>

          <div className="cg-script-metric-value">{item.value}</div>

          {item.note ? <div className="cg-script-metric-note">{item.note}</div> : null}

        </div>

      ))}

    </div>
  );
}

function SpecBars({ spec }: { spec: DrawableSpec }) {
  const series = spec.series ?? [];
  const scale = barScale(series);
  return (
    <div className="cg-script-bars">

      {series.map((s, i) => (

        <div className="cg-script-bar" key={`${s.label}:${i}`}>

          <span>{s.label}</span>

          <span className="cg-script-bar-track">

            {/* ⚠ The ONE computed style on this surface, and it is arithmetic on a NUMBER the

                spec reader already validated as finite, clamped here. Never a string from the

                wire, which is what would make this an injection point. */}

            <span

              className="cg-script-bar-fill"

              style={{ width: `${Math.min(100, Math.round((Math.abs(s.value) / scale) * 100))}%` }}

            />

          </span>

          <span className="cg-script-bar-value">{s.display}</span>

        </div>

      ))}

    </div>
  );
}

/** The refusal, and the four limit fields PRINTED rather than re-worded (C3 note 2). */
function ScriptRefusal({ run }: { run: ScriptRun }) {
  return (
    <div className="cg-script-refusal" role="status">

      <h4>This script did not produce a view</h4>

      <p>{run.error ?? "The run ended without emitting anything."}</p>

      <dl>

        <dt>Reason</dt>

        <dd>{run.code}</dd>

        {run.limit ? <><dt>Subject</dt><dd>{run.limit.subject}</dd></> : null}

        {run.limit ? <><dt>Effect</dt><dd>{run.limit.effect}</dd></> : null}
        {run.limit ? <><dt>Cause</dt><dd>{run.limit.cause}</dd></> : null}
        {run.limit ? <><dt>What to do</dt><dd>{run.limit.recommendation}</dd></> : null}
      </dl>
    </div>
  );
}

/**

 * ⭐⭐ W37-T41 — THE SHAPE OF A SCRIPT, SHOWN AS A PLACEHOLDER RATHER THAN PREFILLED.

 *

 * Picking Custom View mints a view with an EMPTY source (verified: `script_sandbox.check_source("")`

 * accepts it, which is why "mint on pick" was safe to hand lane C in mailbox E-7). Without this, the

 * person who has just created one meets a blank box and a Run button, which is not an invitation.

 *

 * ⛔ A PLACEHOLDER, NEVER A PREFILLED `value`. Prefilling would make the view DIRTY the moment it

 * opened, arm Save on code nobody wrote, and put a version nobody asked for into a 40-deep history.

 * A placeholder vanishes on the first keystroke and is never stored.

 * ⚠ It is the two lines the sandbox's own fixture uses, so the example a person is shown is the

 * example the gate proves runs [[test-double-built-from-the-producer]].

 */
const SCRIPT_STARTER =
  "rows = scoped_table()\nemit({'kind': 'kpi', 'label': 'Records', 'value': len(rows)})";


export function ScriptOutput({ run }: { run: ScriptRun | null }) {
  if (run === null)
    return <p className="cg-script-empty">Run the script to see what it draws.</p>;
  const drawable = run.ok ? renderableSpec(run.spec) : null;
  const claimed = specKindName(run.spec);
  return (
    <>

      {!run.ok ? <ScriptRefusal run={run} /> : null}

      {run.ok && drawable === null ? (

        <div className="cg-script-refusal" role="status">

          <h4>This build cannot draw that shape yet</h4>

          <p>

            {claimed

              ? `The script emitted a view of kind "${claimed}", which this version does not

                 render. It knows table, metrics, bars and text.`

              : `The script emitted a view with no recognisable kind. This version renders

                 table, metrics, bars and text.`}

          </p>

        </div>

      ) : null}

      {drawable !== null ? (

        <>

          {drawable.title ? <h3 className="cg-script-title">{drawable.title}</h3> : null}

          {drawable.kind === "table" ? <SpecTable spec={drawable} /> : null}

          {drawable.kind === "metrics" ? <SpecMetrics spec={drawable} /> : null}

          {drawable.kind === "bars" ? <SpecBars spec={drawable} /> : null}

          {drawable.kind === "text" ? <p className="cg-script-text">{drawable.body}</p> : null}

        </>
      ) : null}
      {run.stdout ? (
        <pre className="cg-script-stdout">

          {run.stdout}

          {run.truncated ? "\n[output truncated]" : ""}

        </pre>
      ) : null}
    </>
  );
}

/**

 * The whole View: the source on the left, what it drew on the right.

 *

 * ⚠ A DRAFT RUN NEEDS NO SAVE (C3 note 3), which is what makes this usable: type, run, save when

 * it works. The Save button is separate and deliberately not automatic, because a PUT is a NEW

 * VERSION and an autosaving editor would fill the 40-deep history with keystrokes.

 */
export const ScriptView = memo(function ScriptView({

  view,

  running,

  run,

  saving,

  readOnly = false,

  loading = false,

  reverting = false,

  onRun,

  onSave,

  onRevert,

}: {

  view: ScriptViewRecord | null;

  running: boolean;

  run: ScriptRun | null;

  saving?: boolean;

  readOnly?: boolean;

  /** ⚠ The host knows whether a fetch is outstanding; the panel cannot tell that from a null view.

   *  Defaulted so no existing caller breaks, which is safe HERE because the default is the older,

   *  more pessimistic sentence rather than a silently disabled feature. */

  loading?: boolean;

  reverting?: boolean;

  onRun: (draft: string) => void;

  onSave?: (source: string) => void;

  /**

   * ⭐ W37-T46 / D-338. Optional for the SAME reason `onSave` is: a read-only reader gets the

   * editor without the controls, and a caller that cannot revert simply does not pass this. The

   * control is not rendered at all when it is absent, rather than rendered and refused

   * [[permitted-is-not-answerable]].

   */

  onRevert?: (version: number) => void;

}) {
  const [draft, setDraft] = useState(view?.source ?? "");
  const loadedId = useRef<string | null>(null);
  useEffect(() => {
    // Re-seed only when a DIFFERENT view is opened. Re-seeding on every `view` identity would
    // discard what somebody is typing the moment the list refreshes underneath them.
    if (!view || loadedId.current === view.id) return;
    loadedId.current = view.id;
    setDraft(view.source);
  }, [view]);
  const dirty = view !== null && draft !== view.source;
  // ⛔ W37-T41: "STILL LOADING" AND "COULD NOT BE OPENED" ARE DIFFERENT FACTS AND USED TO SHARE A
  // SENTENCE. With mint-on-pick (E-7) the normal path now passes through `view === null` for as
  // long as the fetch takes, so the old copy told every person who created a Custom View that it
  // was broken, for a moment, every time. A state that renames itself is exactly what cost this
  // product a QA pass one wave ago [[a-store-outage-renames-itself-at-every-layer]].
  if (view === null)
    return (
      <div className="cg-script">

        <p className="cg-script-empty cg-script-empty--pad">

          {loading === true ? "Opening this view." : "This script view could not be opened."}

        </p>

      </div>
    );
  return (
    <div className="cg-script">

      <div className="cg-script-body">

        <section className="cg-script-pane" aria-label="Script source">

          <div className="cg-script-pane-head">

            <span>Code</span>

            <span className="cg-script-meta">

              {`v${view.version}`}

              {/* ⚠ "v5" alone cannot tell a roll-back from a coincidence of matching code. This is

                  the sentence that makes the history read as what happened. */}

              {view.restoredFrom ? `, restored from v${view.restoredFrom}` : ""}

              {dirty ? ", unsaved changes" : ""}

            </span>

            <span className="cg-script-spacer" />

            <button

              type="button"

              className="cg-script-ghost"

              disabled={!dirty || saving === true || readOnly || onSave === undefined}

              onClick={() => onSave?.(draft)}

            >

              {saving === true ? "Saving" : "Save version"}

            </button>

            <button

              type="button"

              className="cg-script-run"

              disabled={running}

              onClick={() => onRun(draft)}

            >

              {running ? "Running" : "Run"}

            </button>

          </div>

          {/* ⭐⭐ W37-T41 — THE PLACEHOLDER IS THE CREATE FLOW'S WHOLE EMPTY STATE, and it is the

              half that made item 10 worth reopening. Picking Custom View mints a view with an

              EMPTY source (verified: `script_sandbox.check_source("")` accepts it, which is why

              "mint on pick" was safe to hand lane C in mailbox E-7). Without this the person who

              just created one meets a blank box and a Run button, which is not an invitation, it

              is a puzzle.

              ⛔ A PLACEHOLDER, NOT A PREFILLED `value`. Prefilling would make the view DIRTY the

              moment it opened, arm Save on code nobody wrote, and put a version nobody asked for

              into a 40-deep history. It vanishes on the first keystroke and is never saved. */}

          {/* ⭐⭐ W37-T46 / D-338 — THE CONTROL THAT WAS MISSING. The API already returned

              `history` newest-first and the header already showed `v<n>`; there was simply no way

              to go back, which is the whole of D-338. It matters more now that a chat writes the

              code (R2): generation without roll-back means one bad answer costs somebody their

              view, and the person cannot tell in advance which answer that will be.

              ⛔ THE STRIP IS ABSENT, NOT DISABLED, WHEN THERE IS NOTHING TO GO BACK TO. A first

              version has no history, and a row of dead controls reads as a broken feature rather

              than as an empty one.

              ⚠ `trimmed` is PRINTED when it is non-zero. A history capped at 40 that silently

              showed 40 would let a reader conclude the view was only ever saved 40 times; saying

              how many were dropped is the difference between a partial record and a wrong one. */}

          {(view.history?.length ?? 0) > 0 ? (

            <div className="cg-script-history" aria-label="Earlier versions">

              <span className="cg-script-history-lead">Earlier</span>

              {[...(view.history ?? [])].map((h) => (

                <button

                  type="button"

                  key={h.version}

                  className="cg-script-history-item"

                  disabled={readOnly || reverting || onRevert === undefined}

                  title={`Go back to version ${h.version}, saved by ${h.author || "somebody"}`}

                  onClick={() => onRevert?.(h.version)}

                >

                  {`v${h.version}`}

                </button>

              ))}

              {view.trimmed > 0 ? (

                <span className="cg-script-history-trimmed">

                  {`${view.trimmed} older ${view.trimmed === 1 ? "version" : "versions"} dropped`}

                </span>

              ) : null}

              {reverting ? <span className="cg-script-history-trimmed">Going back</span> : null}

            </div>

          ) : null}

          <textarea

            className="cg-script-code"

            value={draft}

            spellCheck={false}

            readOnly={readOnly}

            placeholder={SCRIPT_STARTER}

            aria-label="Script source"

            onChange={(e) => setDraft(e.target.value)}

          />

        </section>

        <section className="cg-script-pane" aria-label="Script output">

          <div className="cg-script-pane-head">

            <span>Output</span>

            <span className="cg-script-spacer" />

            {run !== null ? (

              <span className="cg-script-meta">

                {run.ms > 0 ? `${run.ms} ms` : ""}

              </span>

            ) : null}

          </div>

          <div className="cg-script-out">

            <ScriptOutput run={run} />

          </div>

        </section>

      </div>

    </div>

  );

});