@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/clarity-ui.tsx

@@ -0,0 +1,454 @@
+import {
+  Fragment,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from "react";
+import { checkClarity } from "./api.js";
+import {
+  answerRoom,
+  askClarity,
+  canSendAsIs,
+  CLARITY_MAX_ROUNDS,
+  CLARITY_WORDS,
+  clarityAfterCheck,
+  clarityAnnouncement,
+  clarityBody,
+  clarityChecks,
+  clarityGroups,
+  clarityReader,
+  clarityStep,
+  openQuestions,
+  passMark,
+  whoWouldAsk,
+  withAnswer,
+  type ClarityFacts,
+  type ClarityHold,
+  type ClarityMode,
+  type ClarityQuestion,
+  type ClaritySend,
+} from "./clarity-model.js";
+import type { DictationDeps } from "./dictation-engine.js";
+import { DictateButton, isDictationKey, useDictation } from "./dictation-ui.js";
+import type { Session } from "./session.js";
+
+/** What Send does next: post this text, or wait (the questions are on screen). */
+export type ClaritySent = { readonly post: true; readonly body: string } | { readonly post: false };
+
+export type ClarityControl = ReturnType<typeof useClarity>;
+
+/**
+ * The clarity check for one composer (`./clarity-model.ts` decides; this holds the state). `send` is what the
+ * composer's submit asks before it posts a new comment. It always resolves, within the model's wait, and
+ * never rejects: when the check can't answer, the comment is posted as it would have been without it.
+ */
+export function useClarity(
+  session: Session | null,
+  member: string | null,
+  mode: ClarityMode | null,
+) {
+  const [hold, setHold] = useState<ClarityHold | null>(null);
+  const [checking, setChecking] = useState(false);
+  /** `require`, and Send was pressed with nothing added: the hint says what to do. */
+  const [stayed, setStayed] = useState(false);
+  /** Counts the times questions arrived or stayed, so focus goes to the first one each time. */
+  const [arrived, setArrived] = useState(0);
+  const [dictating, setDictating] = useState<readonly string[]>([]);
+  // What `send` reads: it runs across an await, and a re-render must not be what it waits for.
+  const latest = useRef<ClarityHold | null>(null);
+  const passed = useRef<string | null>(null);
+  const asIs = useRef(false);
+
+  const put = useCallback((next: ClarityHold | null) => {
+    latest.current = next;
+    setHold(next);
+  }, []);
+
+  /** A new draft, or none: nothing is held and nothing was asked. */
+  const reset = useCallback(() => {
+    put(null);
+    passed.current = null;
+    asIs.current = false;
+    setStayed(false);
+    setDictating([]);
+  }, [put]);
+
+  /** A draft picked up from storage, with the questions and answers it was put away with. */
+  const restore = useCallback(
+    (found: ClarityHold | null) => {
+      put(found);
+      passed.current = null;
+      asIs.current = false;
+      setStayed(false);
+    },
+    [put],
+  );
+
+  const answer = useCallback(
+    (questionId: string, text: string) => {
+      if (!latest.current) return;
+      put(withAnswer(latest.current, questionId, text));
+      setStayed(false);
+    },
+    [put],
+  );
+
+  const noteDictating = useCallback((questionId: string, on: boolean) => {
+    setDictating((current) => {
+      const has = current.includes(questionId);
+      if (on === has) return current;
+      return on ? [...current, questionId] : current.filter((id) => id !== questionId);
+    });
+  }, []);
+
+  /** "Send as is" was pressed: the submit that follows posts without asking again. */
+  const chooseAsIs = useCallback(() => {
+    asIs.current = true;
+  }, []);
+  /** How this submit was asked for. Read once per submit, first thing, so a submit that bails clears it. */
+  const takeSend = useCallback((): ClaritySend => {
+    const send = asIs.current ? "as-is" : "send";
+    asIs.current = false;
+    return send;
+  }, []);
+
+  const send = useCallback(
+    async (facts: ClarityFacts, how: ClaritySend): Promise<ClaritySent> => {
+      const before = latest.current;
+      const go = (): ClaritySent => ({ post: true, body: clarityBody(facts.body, before) });
+      const step = clarityStep({
+        mode,
+        hold: before,
+        draft: facts,
+        send: how,
+        passed: passed.current,
+      });
+      switch (step.kind) {
+        case "post":
+          return go();
+        case "stay":
+          setStayed(true);
+          setArrived((count) => count + 1);
+          return { post: false };
+        case "check": {
+          if (!session || !member) return go();
+          setChecking(true);
+          const outcome = await askClarity((signal) =>
+            checkClarity(session, member, step.request, signal),
+          );
+          setChecking(false);
+          const next = clarityAfterCheck(before, facts, step.request, outcome);
+          if (!next) {
+            // If the post itself fails, pressing Send again posts; it does not ask a second time.
+            passed.current = passMark(facts, before);
+            return go();
+          }
+          put(next);
+          setStayed(false);
+          setArrived((count) => count + 1);
+          return { post: false };
+        }
+        default: {
+          const never: never = step;
+          return never;
+        }
+      }
+    },
+    [member, mode, put, session],
+  );
+
+  return useMemo(
+    () => ({
+      hold,
+      /** The service is being asked: Send shows it is working. */
+      checking,
+      stayed,
+      arrived,
+      /** An answer is still being dictated: sending now would lose words. */
+      dictating: dictating.length > 0,
+      send,
+      takeSend,
+      chooseAsIs,
+      answer,
+      noteDictating,
+      reset,
+      restore,
+    }),
+    [
+      answer,
+      arrived,
+      checking,
+      chooseAsIs,
+      dictating,
+      hold,
+      noteDictating,
+      reset,
+      restore,
+      send,
+      stayed,
+      takeSend,
+    ],
+  );
+}
+
+type AnswerKeys = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
+
+type Voice = {
+  readonly transcribe: DictationDeps["transcribe"];
+  /** People who may be named, so they are spelled right. */
+  readonly names: readonly string[];
+  readonly onNote: (note: string) => void;
+  /** Dictation can't start now (a post or a screen recording is running). */
+  readonly off: boolean;
+};
+
+function ClarityAnswerBox({
+  question,
+  value,
+  note,
+  room,
+  locked,
+  voice,
+  onChange,
+  onDictating,
+  onKeyDown,
+}: {
+  question: ClarityQuestion;
+  value: string;
+  note: string | undefined;
+  /** The longest this answer may be (`answerRoom`). */
+  room: number;
+  /** The service is reading the answers: they are not changed under it. */
+  locked: boolean;
+  voice: Voice;
+  onChange: (text: string) => void;
+  onDictating: (questionId: string, on: boolean) => void;
+  onKeyDown: AnswerKeys;
+}) {
+  const id = useId();
+  const field = `clarity-answer-${question.id}`;
+  // The composer's own dictation, pointed at this box. No voice file is kept: the words are the answer.
+  const dictation = useDictation({
+    transcribe: voice.transcribe,
+    value,
+    onChange,
+    names: voice.names,
+    onNote: voice.onNote,
+  });
+  const writing = dictation.busy;
+  useEffect(() => {
+    onDictating(question.id, writing);
+  }, [onDictating, question.id, writing]);
+  useEffect(() => () => onDictating(question.id, false), [onDictating, question.id]);
+  // Also when there was never any room: a box that takes nothing says why.
+  const full = value.length >= room;
+  const described = [
+    question.why ? `${id}-why` : null,
+    note ? `${id}-note` : null,
+    full ? `${id}-full` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <li className="cs-clarity-item" data-cs-ui="clarity-question" data-question-id={question.id}>
+      <label className="cs-clarity-ask" htmlFor={id}>
+        {question.ask}
+      </label>
+      {question.why ? (
+        <span className="cs-clarity-why" id={`${id}-why`}>
+          {question.why}
+        </span>
+      ) : null}
+      <div className="cs-clarity-answer">
+        <textarea
+          id={id}
+          data-cs-ui={field}
+          data-question-id={question.id}
+          rows={1}
+          placeholder={CLARITY_WORDS.placeholder}
+          value={value}
+          maxLength={room}
+          readOnly={locked}
+          aria-describedby={described || undefined}
+          onChange={(event) => onChange(event.target.value)}
+          onKeyDown={(event) => {
+            if (isDictationKey(event)) {
+              event.preventDefault();
+              if (!voice.off && !locked) dictation.toggle(event.currentTarget);
+              return;
+            }
+            if (event.key === "Escape" && dictation.listening) {
+              // Escape ends the take, as it does in the comment box; it does not close the composer.
+              event.preventDefault();
+              event.stopPropagation();
+              dictation.stop();
+              return;
+            }
+            onKeyDown(event);
+          }}
+        />
+        <DictateButton dictation={dictation} field={field} disabled={voice.off || locked} compact />
+      </div>
+      {note ? (
+        <p className="cs-clarity-note" id={`${id}-note`} data-cs-ui="clarity-note">
+          {note}
+        </p>
+      ) : null}
+      {full ? (
+        <p className="cs-clarity-full" id={`${id}-full`} data-cs-ui="clarity-full">
+          {CLARITY_WORDS.full}
+        </p>
+      ) : null}
+    </li>
+  );
+}
+
+/** What the check took as given instead of asking. Shown so a wrong one is seen; never asked about. */
+function TakenAsGiven({ assumed }: { assumed: readonly string[] }) {
+  const id = useId();
+  return (
+    <div className="cs-clarity-given" data-cs-ui="clarity-assumed">
+      <p className="cs-clarity-given-head" id={id}>
+        {CLARITY_WORDS.assumed}
+      </p>
+      <ul aria-labelledby={id}>
+        {assumed.map((sentence) => (
+          <li key={sentence}>{sentence}</li>
+        ))}
+      </ul>
+      <p className="cs-clarity-given-note">{CLARITY_WORDS.assumedNote}</p>
+    </div>
+  );
+}
+
+/**
+ * What the composer shows under the comment while the check holds it: what a reader takes from the comment,
+ * what the check took as given, each open question with why a reader needs it and its own answer box, grouped
+ * by who would ask when a developer and whoever tests the fix both would, and "Send as is" when skipping is
+ * allowed. Focus goes to the first question when they arrive, and a polite live region says they are there.
+ *
+ * Renders nothing at all where the service has no check, so nothing about those composers changes.
+ */
+export function ClarityQuestions({
+  clarity,
+  mode,
+  body,
+  busy,
+  voice,
+  onKeyDown,
+}: {
+  clarity: ClarityControl;
+  mode: ClarityMode | null;
+  /** The comment's text as it stands, for how much room each answer has. */
+  body: string;
+  /** A post or a check is running. */
+  busy: boolean;
+  voice: Voice;
+  /** The comment box's own key rules (Cmd+Enter sends), so the answer boxes follow them. */
+  onKeyDown: AnswerKeys;
+}) {
+  const { hold, arrived, stayed, answer, chooseAsIs, noteDictating } = clarity;
+  const panel = useRef<HTMLElement>(null);
+  const leadId = useId();
+  // Only when questions arrive (or stay) under an open composer. A draft opened with questions already on it
+  // (from the dock, after a reload) keeps the focus every draft opens with.
+  const focused = useRef(arrived);
+  useEffect(() => {
+    if (arrived === focused.current) return;
+    focused.current = arrived;
+    panel.current?.querySelector<HTMLTextAreaElement>("textarea")?.focus();
+  }, [arrived]);
+  if (!hold && !clarityChecks(mode)) return null;
+  const open = hold ? openQuestions(hold) : [];
+  const groups = clarityGroups(open);
+  const grouped = groups.length > 1;
+  return (
+    <>
+      {hold ? (
+        <section
+          ref={panel}
+          className="cs-clarity"
+          data-cs-ui="clarity"
+          data-cs-round={hold.round}
+          aria-label={CLARITY_WORDS.region}
+        >
+          {hold.understood ? (
+            <p className="cs-clarity-read" data-cs-ui="clarity-understood">
+              <span>{CLARITY_WORDS.understood}</span> {hold.understood}
+            </p>
+          ) : null}
+          {hold.assumed?.length ? <TakenAsGiven assumed={hold.assumed} /> : null}
+          <p className="cs-clarity-lead" id={leadId} data-cs-ui="clarity-lead">
+            {`${whoWouldAsk(open)} would still have to ask:`}
+          </p>
+          {groups.map((group) => (
+            <Fragment key={group.audience}>
+              {grouped ? (
+                <p
+                  className="cs-clarity-group"
+                  id={`${leadId}-${group.audience}`}
+                  data-cs-ui="clarity-group"
+                >
+                  {`${clarityReader(group.audience)} would ask`}
+                </p>
+              ) : null}
+              <ol
+                className="cs-clarity-list"
+                data-audience={group.audience}
+                aria-labelledby={grouped ? `${leadId}-${group.audience}` : leadId}
+              >
+                {group.questions.map((question) => (
+                  <ClarityAnswerBox
+                    key={question.id}
+                    question={question}
+                    value={hold.answers[question.id] ?? ""}
+                    note={hold.notes[question.id]}
+                    room={answerRoom(body, hold, question.id)}
+                    locked={busy}
+                    voice={voice}
+                    onChange={(text) => answer(question.id, text)}
+                    onDictating={noteDictating}
+                    onKeyDown={onKeyDown}
+                  />
+                ))}
+              </ol>
+            </Fragment>
+          ))}
+          <div className="cs-clarity-foot">
+            <span className="cs-clarity-hint" data-cs-ui="clarity-hint">
+              {stayed
+                ? CLARITY_WORDS.stay
+                : hold.round >= CLARITY_MAX_ROUNDS
+                  ? CLARITY_WORDS.free
+                  : CLARITY_WORDS.hint}
+            </span>
+            {canSendAsIs(hold) ? (
+              <button
+                // Not a submit button: Enter in one of the form's fields must keep pressing Send, not this.
+                type="button"
+                className="cs-clarity-skip"
+                data-cs-ui="clarity-send-as-is"
+                disabled={busy}
+                onClick={(event) => {
+                  chooseAsIs();
+                  event.currentTarget.form?.requestSubmit();
+                }}
+              >
+                {CLARITY_WORDS.sendAsIs}
+              </button>
+            ) : null}
+          </div>
+        </section>
+      ) : null}
+      {/* Always in the composer, empty until there is something to say: a live region is only heard when it
+          was there before its words. */}
+      <p className="cs-clarity-live" role="status" aria-live="polite" data-cs-ui="clarity-live">
+        {clarityAnnouncement(hold, stayed, whoWouldAsk(open))}
+      </p>
+    </>
+  );
+}

package/src/runtime/client.ts

@@ -0,0 +1,151 @@
+/**
+ * The comment service client for the web toolbar: the DOM-free API (`./api.ts`) plus what only a browser page
+ * has — `localStorage` member tokens, and the sign-in window's relay back to this page.
+ */
+import {
+  base64Url,
+  memberIsCurrent,
+  msfAuthorizeUrl,
+  msfHandoffFrom,
+  storageKey,
+  type MsfHandoff,
+} from "./api.js";
+import { readJwt, type Session } from "./session.js";
+
+export * from "./api.js";
+
+const storagePrefix = "devaccel.comment.";
+
+/**
+ * When the comment service moves to a new URL, the saved sign-in is under the old URL's key. Copy the newest current
+ * one for this project and environment to the new key, and leave the old key in place so going back also works.
+ */
+export function adoptStoredMember(
+  session: Pick<Session, "apiUrl" | "project" | "environment">,
+  storage: Storage = localStorage,
+) {
+  const key = storageKey(session);
+  if (storage.getItem(key)) return;
+  const suffix = `.${session.project}.${session.environment}`;
+  let best: { key: string; token: string; exp: number } | null = null;
+  for (let index = 0; index < storage.length; index++) {
+    const candidate = storage.key(index);
+    if (
+      !candidate ||
+      candidate === key ||
+      !candidate.startsWith(storagePrefix) ||
+      !candidate.endsWith(suffix)
+    )
+      continue;
+    const apiUrl = candidate.slice(storagePrefix.length, candidate.length - suffix.length);
+    if (!/^https?:\/\/[^/]+$/.test(apiUrl)) continue;
+    const token = storage.getItem(candidate);
+    if (!token || !memberIsCurrent(token)) continue;
+    const exp = readJwt(token)?.exp ?? 0;
+    if (!best || exp > best.exp) best = { key: candidate, token, exp };
+  }
+  if (!best) return;
+  storage.setItem(key, best.token);
+}
+
+function randomUrlSafe(bytes: number) {
+  return base64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+
+/**
+ * An OAuth 2.0 authorization request with PKCE (S256). The verifier never leaves this page. The sign-in window
+ * comes back to `returnTo` (this page, on this origin) with the code, so a code only ever reaches the app it
+ * was issued for.
+ */
+export async function msfAuthorization(authorizeUrl: string, returnTo: string) {
+  const state = randomUrlSafe(32);
+  const verifier = randomUrlSafe(48);
+  const challenge = base64Url(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))),
+  );
+  const page = new URL(returnTo);
+  page.hash = "";
+  return { url: msfAuthorizeUrl(authorizeUrl, page.toString(), state, challenge), state, verifier };
+}
+
+const msfHandoffKey = "devaccel.comment.msf-handoff";
+const msfChannel = "devaccel-comments-msf";
+
+/**
+ * The sign-in window ends on this app's page with the result in the address hash (when it couldn't message the
+ * page that opened it). Pass it to that page through same-origin storage and a broadcast, and clean the address.
+ */
+export function relayMsfHandoff(): boolean {
+  if (typeof window === "undefined") return false;
+  const hash = new URLSearchParams(window.location.hash.slice(1));
+  const handoff = msfHandoffFrom(window.location.hash);
+  if (!handoff) return false;
+  try {
+    localStorage.setItem(msfHandoffKey, JSON.stringify(handoff));
+  } catch {
+    // storage unavailable: the broadcast below still reaches open tabs
+  }
+  try {
+    const channel = new BroadcastChannel(msfChannel);
+    channel.postMessage(handoff);
+    channel.close();
+  } catch {
+    // no BroadcastChannel
+  }
+  for (const name of ["cs-msf-state", "cs-msf-code", "cs-msf-error"]) hash.delete(name);
+  const url = new URL(window.location.href);
+  url.hash = hash.toString();
+  history.replaceState(history.state, "", url);
+  return true;
+}
+
+/** Calls `onHandoff` when a sign-in window hands a result back, by message, broadcast or storage. */
+export function listenForMsfHandoff(apiOrigin: string, onHandoff: (handoff: MsfHandoff) => void) {
+  const fromMessage = (event: MessageEvent) => {
+    const data = event.data as {
+      type?: string;
+      state?: string;
+      code?: string;
+      error?: string;
+    } | null;
+    if (
+      event.origin !== apiOrigin ||
+      data?.type !== "devaccel-comments:msf-sign-in" ||
+      typeof data.state !== "string"
+    )
+      return;
+    onHandoff({
+      state: data.state,
+      ...(data.code ? { code: data.code } : {}),
+      ...(data.error ? { error: data.error } : {}),
+      at: Date.now(),
+    });
+  };
+  const fromStorage = (event: StorageEvent) => {
+    if (event.key !== msfHandoffKey || !event.newValue) return;
+    try {
+      onHandoff(JSON.parse(event.newValue) as MsfHandoff);
+    } catch {
+      // ignore malformed
+    }
+  };
+  let channel: BroadcastChannel | null = null;
+  try {
+    channel = new BroadcastChannel(msfChannel);
+    channel.onmessage = (event) => onHandoff(event.data as MsfHandoff);
+  } catch {
+    channel = null;
+  }
+  window.addEventListener("message", fromMessage);
+  window.addEventListener("storage", fromStorage);
+  return () => {
+    window.removeEventListener("message", fromMessage);
+    window.removeEventListener("storage", fromStorage);
+    channel?.close();
+    try {
+      localStorage.removeItem(msfHandoffKey);
+    } catch {
+      // ignore
+    }
+  };
+}