@rathnasgala2/template 3.1.0 → 3.2.1

package/src/modules/interactions/browser/gala-interactions.js

@@ -30,6 +30,22 @@
  * POSTs carry an `Idempotency-Key` that is reused while the same draft is
  * retried.
  *
+ * Appeals: a signed-in reader's thread read also carries that reader's own
+ * removed or held comments, each with an `own` object (`state` REMOVED or HELD,
+ * the `appeal` so far or null, and `canAppeal`) and no body. Such a comment is
+ * shown as "Removed by the site's moderators" (held: "Hidden while the
+ * moderators review it"), headed by a one-line context, "Your comment from
+ * <relative date>" (from `createdAt`), that tells the reader which comment it
+ * is; when `canAppeal` is true it offers an Appeal button that opens a note
+ * field (up to 1,000 characters) and posts `{note}` to
+ * `/v2/public/comments/{commentId}/appeals` with the bearer token. The
+ * appeal's state (pending, restored, kept removed) is written under the
+ * comment, and only there: sending an appeal updates the comment's state and
+ * redraws it, it never adds a sentence of its own, so "Appeal sent. ..." shows
+ * once, from the state, whether the reader has just sent it or the thread was
+ * read again. There is one appeal per removal; the moderators decide, never the
+ * script.
+ *
  * Not used, by design: iframes, popups (`window.open`), `postMessage`,
  * FedCM, cookies, third-party scripts or requests.
  *
@@ -116,6 +132,22 @@
     showMoreReplies: 'Show more replies',
     deletedTombstone: 'This comment was deleted.',
     removedTombstone: 'This comment was removed.',
+    ownFrom: 'Your comment from ',
+    removedOwn: "Removed by the site's moderators",
+    heldOwn: 'Hidden while the moderators review it',
+    appeal: 'Appeal',
+    appealAria: 'Appeal this decision',
+    appealLabel:
+      'Tell the moderators why this should be restored (up to 1,000 characters)',
+    appealSend: 'Send',
+    appealSent: 'Appeal sent. The moderators will look again.',
+    appealRestored: 'Restored after review',
+    appealDenied: 'Kept removed after review',
+    appealEmpty: 'Write why you are appealing first.',
+    appealTooLong: "That's longer than 1,000 characters.",
+    appealExists: 'You already appealed this decision.',
+    appealNotAllowed: "This comment can't be appealed.",
+    appealTooMany: "You've sent several appeals today. Try again tomorrow.",
     reportTitle: 'Report this comment',
     reportReason: 'Reason',
     reportNote: 'Details (optional)',
@@ -196,7 +228,9 @@
    * @typedef {{accessToken: string, expiresAt: string, reader: ReaderView}} Session
    * @typedef {{lowerBound: number, display: string, label: string}} PublicCount
    * @typedef {{isAuthor: boolean, canEdit: boolean, canDelete: boolean, canReply: boolean}} CommentViewer
-   * @typedef {{id: string, parentId: string | null, depth: number, state: 'VISIBLE' | 'REMOVED' | 'DELETED', author: ReaderView | null, body: string | null, createdAt: string, editedAt: string | null, replies: CommentView[], moreReplies: boolean, viewer: CommentViewer}} CommentView
+   * @typedef {{state: 'PENDING' | 'RESTORED' | 'DENIED', decidedAt?: string}} CommentAppeal
+   * @typedef {{state: 'REMOVED' | 'HELD', appeal: CommentAppeal | null, canAppeal: boolean}} CommentOwn
+   * @typedef {{id: string, parentId: string | null, depth: number, state: 'VISIBLE' | 'REMOVED' | 'DELETED' | 'HELD', author: ReaderView | null, body: string | null, createdAt: string, editedAt: string | null, replies: CommentView[], moreReplies: boolean, viewer: CommentViewer, own?: CommentOwn}} CommentView
    * @typedef {{items: CommentView[], nextCursor: string | null, count: PublicCount | null}} CommentPage
    * @typedef {{key: string, label: string, visual: {kind: string, token: string}, count: PublicCount | null, viewerActive: boolean}} ReactionItem
    * @typedef {{enabled: boolean, items: ReactionItem[]}} ReactionsBlock
@@ -219,9 +253,10 @@
   };
   const composers = new Set();
   let rootComposer = /** @type {Composer | null} */ (null);
-  let inline = /** @type {{composer: Composer, item: CommentItem} | null} */ (
-    null
-  );
+  let inline =
+    /** @type {{composer: Composer, item: CommentItem, trigger: HTMLElement | null} | null} */ (
+      null
+    );
   let loadToken = 0;
 
   // ------------------------------------------------------------------- helpers
@@ -261,6 +296,47 @@
     return node;
   }
 
+  /**
+   * One place for the disabled state: the native attribute (which blocks
+   * activation and focus) and `aria-disabled` together, so the base layer's
+   * `:disabled` / `[aria-disabled="true"]` rule and assistive technology agree.
+   *
+   * @param {HTMLElement} node
+   * @param {boolean} on
+   */
+  function setDisabled(node, on) {
+    /** @type {HTMLButtonElement} */ (node).disabled = on;
+    if (on) node.setAttribute('aria-disabled', 'true');
+    else node.removeAttribute('aria-disabled');
+  }
+
+  /**
+   * The working (pending) state: disabled for activation, but marked
+   * `aria-busy` so the base layer draws a spinner instead of the muted
+   * disabled look.
+   *
+   * @param {HTMLElement} node
+   * @param {boolean} on
+   */
+  function setBusy(node, on) {
+    setDisabled(node, on);
+    if (on) node.setAttribute('aria-busy', 'true');
+    else node.removeAttribute('aria-busy');
+  }
+
+  /**
+   * A trigger whose action is already in progress (its inline composer is
+   * open) stays focusable, so it is `aria-disabled` only, and ignores clicks.
+   *
+   * @param {HTMLElement | null} trigger
+   * @param {boolean} on
+   */
+  function holdTrigger(trigger, on) {
+    if (!trigger) return;
+    if (on) trigger.setAttribute('aria-disabled', 'true');
+    else trigger.removeAttribute('aria-disabled');
+  }
+
   let idCounter = 0;
   /**
    * @param {string} prefix
@@ -833,7 +909,7 @@
         continue;
       }
       node.hidden = false;
-      node.disabled = false;
+      setDisabled(node, false);
       setPressed(node, !!item.viewerActive);
       setCount(node, item.count, 'reactions');
     }
@@ -1006,6 +1082,22 @@
     }
   }
 
+  /**
+   * A comment's `<time>` element: the given text, the machine-readable date
+   * and the full date as its tooltip.
+   *
+   * @param {string} iso
+   * @param {string} text
+   * @returns {HTMLElement}
+   */
+  function timeElement(iso, text) {
+    const time = make('time', 'g-comment__time', text);
+    time.setAttribute('datetime', iso);
+    const title = fullDate(iso);
+    if (title) time.setAttribute('title', title);
+    return time;
+  }
+
   // ------------------------------------------------------------------ comments
   /**
    * @param {PublicCount|null|undefined} count
@@ -1023,13 +1115,65 @@
     }
   }
 
+  /**
+   * The state of the signed-in reader's own removed or held comment, which
+   * arrives with an `own` object and no body.
+   *
+   * @param {CommentView} comment
+   * @returns {CommentOwn | null}
+   */
+  function ownView(comment) {
+    const own = comment.own;
+    return own &&
+      typeof own === 'object' &&
+      (own.state === 'REMOVED' || own.state === 'HELD')
+      ? own
+      : null;
+  }
+
+  /**
+   * The one-line context of the reader's own removed or held comment, which
+   * arrives with no body: "Your comment from <relative date>". Null when the
+   * comment has no usable `createdAt`.
+   *
+   * @param {CommentView} comment
+   * @returns {HTMLElement | null}
+   */
+  function ownContext(comment) {
+    if (!Number.isFinite(Date.parse(comment.createdAt))) return null;
+    return timeElement(
+      comment.createdAt,
+      MESSAGES.ownFrom + timeLabel(comment.createdAt, false),
+    );
+  }
+
+  /**
+   * The line saying where the reader's appeal stands, if there is one.
+   *
+   * @param {CommentView} comment
+   * @returns {HTMLElement | null}
+   */
+  function appealResult(comment) {
+    const appeal = comment.own && comment.own.appeal;
+    const text = !appeal
+      ? ''
+      : appeal.state === 'PENDING'
+        ? MESSAGES.appealSent
+        : appeal.state === 'RESTORED'
+          ? MESSAGES.appealRestored
+          : appeal.state === 'DENIED'
+            ? MESSAGES.appealDenied
+            : '';
+    return text ? make('p', 'g-interactions__notice', text) : null;
+  }
+
   /**
    * @param {CommentView} comment
    * @returns {boolean}
    */
   function canReplyTo(comment) {
     if (!live.commentsOpen || !live.allowReplies) return false;
-    if (comment.state !== 'VISIBLE') return false;
+    if (comment.state !== 'VISIBLE' || ownView(comment)) return false;
     if (comment.depth >= live.maxDepth - 1) return false;
     if (session && comment.viewer && comment.viewer.canReply === false) {
       return false;
@@ -1061,31 +1205,49 @@
     const existingReplies = item.querySelector(':scope > .g-comment__replies');
     while (item.firstChild) item.removeChild(item.firstChild);
     item._comment = comment;
-    item.classList.toggle('g-comment--tombstone', comment.state !== 'VISIBLE');
+    const own = ownView(comment);
+    item.classList.toggle(
+      'g-comment--tombstone',
+      comment.state !== 'VISIBLE' || !!own,
+    );
     item.classList.toggle(
       'g-comment--mine',
-      !!(comment.viewer && comment.viewer.isAuthor),
+      !!own || !!(comment.viewer && comment.viewer.isAuthor),
     );
 
     const head = make('div', 'g-comment__head');
-    if (comment.state === 'VISIBLE' && comment.author) {
+    if (own) {
+      // No body comes back for these, so say which comment it is by its date.
+      const context = ownContext(comment);
+      if (context) item.appendChild(context);
+      item.appendChild(
+        make(
+          'p',
+          'g-comment__body',
+          own.state === 'HELD' ? MESSAGES.heldOwn : MESSAGES.removedOwn,
+        ),
+      );
+      const result = appealResult(comment);
+      if (result) item.appendChild(result);
+      if (own.canAppeal === true) item.appendChild(renderAppealAction(item));
+    } else if (comment.state === 'VISIBLE' && comment.author) {
       const avatar = make('span', 'g-comment__avatar', comment.author.initials);
       avatar.setAttribute('aria-hidden', 'true');
       head.appendChild(avatar);
       head.appendChild(
         make('span', 'g-comment__author', comment.author.displayName),
       );
-      const time = make(
-        'time',
-        'g-comment__time',
-        timeLabel(comment.createdAt, !!comment.editedAt),
+      head.appendChild(
+        timeElement(
+          comment.createdAt,
+          timeLabel(comment.createdAt, !!comment.editedAt),
+        ),
       );
-      time.setAttribute('datetime', comment.createdAt);
-      const title = fullDate(comment.createdAt);
-      if (title) time.setAttribute('title', title);
-      head.appendChild(time);
       item.appendChild(head);
       item.appendChild(renderBody(comment.body || ''));
+      // A comment restored on appeal says so.
+      const result = appealResult(comment);
+      if (result) item.appendChild(result);
       item.appendChild(renderActions(item, comment));
     } else {
       item.appendChild(
@@ -1147,7 +1309,7 @@
     let cursor = /** @type {string | null} */ (null);
     let first = true;
     more.addEventListener('click', async () => {
-      more.disabled = true;
+      setBusy(more, true);
       try {
         const query = new URLSearchParams({ parentId: comment.id });
         if (cursor) query.set('cursor', cursor);
@@ -1164,9 +1326,9 @@
           list.appendChild(renderComment(reply));
         cursor = page.nextCursor || null;
         if (!cursor) more.remove();
-        else more.disabled = false;
+        else setBusy(more, false);
       } catch (error) {
-        more.disabled = false;
+        setBusy(more, false);
         announce(failureMessage(error));
       }
     });
@@ -1187,9 +1349,10 @@
         MESSAGES.reply,
         MESSAGES.reply + ' to ' + name,
       );
-      reply.addEventListener('click', () =>
-        openInlineComposer(item, 'reply', reply),
-      );
+      reply.addEventListener('click', () => {
+        if (reply.getAttribute('aria-disabled') === 'true') return;
+        openInlineComposer(item, 'reply', reply);
+      });
       actions.appendChild(reply);
     }
     if (comment.viewer && comment.viewer.canEdit) {
@@ -1198,9 +1361,10 @@
         MESSAGES.edit,
         MESSAGES.edit + ' your comment',
       );
-      edit.addEventListener('click', () =>
-        openInlineComposer(item, 'edit', edit),
-      );
+      edit.addEventListener('click', () => {
+        if (edit.getAttribute('aria-disabled') === 'true') return;
+        openInlineComposer(item, 'edit', edit);
+      });
       actions.appendChild(edit);
     }
     if (comment.viewer && comment.viewer.canDelete) {
@@ -1256,8 +1420,8 @@
       }
     });
     yes.addEventListener('click', async () => {
-      yes.disabled = true;
-      no.disabled = true;
+      setBusy(yes, true);
+      setDisabled(no, true);
       try {
         await api(
           'DELETE',
@@ -1266,8 +1430,8 @@
         applyDeleted(item);
         announce(MESSAGES.deleted);
       } catch (error) {
-        yes.disabled = false;
-        no.disabled = false;
+        setBusy(yes, false);
+        setDisabled(no, false);
         announce(failureMessage(error));
       }
     });
@@ -1479,7 +1643,7 @@
         return;
       }
       composer.busy = true;
-      submit.disabled = true;
+      setDisabled(submit, true);
       submit.setAttribute('aria-busy', 'true');
       showError('');
       try {
@@ -1506,7 +1670,7 @@
         showError(failureMessage(failure));
       } finally {
         composer.busy = false;
-        submit.disabled = false;
+        setDisabled(submit, false);
         submit.removeAttribute('aria-busy');
       }
     });
@@ -1562,6 +1726,7 @@
   function closeInline() {
     if (inline) {
       inline.composer.close();
+      holdTrigger(inline.trigger, false);
       inline = null;
     }
   }
@@ -1577,6 +1742,7 @@
     const comment = item._comment;
     const done = (/** @type {any} */ result) => {
       /** @type {{composer: Composer}} */ (inline).composer.close();
+      holdTrigger(trigger, false);
       inline = null;
       if (mode === 'edit') {
         fillComment(item, result);
@@ -1593,12 +1759,14 @@
       body: mode === 'edit' ? comment.body || '' : presetBody || '',
       onDone: done,
       onCancel: () => {
+        holdTrigger(trigger, false);
         inline = null;
         if (trigger && trigger.isConnected) focusNode(trigger);
         else focusNode(item);
       },
     });
-    inline = { composer, item };
+    holdTrigger(trigger, true);
+    inline = { composer, item, trigger };
     const replies = item.querySelector(':scope > .g-comment__replies');
     if (replies) item.insertBefore(composer.element, replies);
     else item.appendChild(composer.element);
@@ -1685,7 +1853,7 @@
     });
     cancel.addEventListener('click', finish);
     send.addEventListener('click', async () => {
-      send.disabled = true;
+      setBusy(send, true);
       error.hidden = true;
       /** @type {{reasonCode: string, note?: string}} */
       const payload = { reasonCode: select.value };
@@ -1702,7 +1870,7 @@
         finish();
         announce(MESSAGES.reported);
       } catch (failure) {
-        send.disabled = false;
+        setBusy(send, false);
         error.textContent = failureMessage(failure);
         error.hidden = false;
       }
@@ -1721,6 +1889,171 @@
     focusNode(select);
   }
 
+  // -------------------------------------------------------------------- appeal
+  /**
+   * @param {CommentItem} item
+   * @returns {HTMLElement}
+   */
+  function renderAppealAction(item) {
+    const actions = make('div', 'g-comment__actions');
+    const appeal = button(
+      'g-comment__action',
+      MESSAGES.appeal,
+      MESSAGES.appealAria,
+    );
+    appeal.addEventListener('click', () => openAppeal(item, appeal));
+    actions.appendChild(appeal);
+    return actions;
+  }
+
+  /**
+   * The sentence for a failed appeal; the problems an appeal adds are named
+   * here, everything else is worded as for any other request.
+   *
+   * @param {unknown} error
+   * @returns {string}
+   */
+  function appealFailureMessage(error) {
+    if (error instanceof ApiError && error.kind === 'problem') {
+      if (error.code === 'APPEAL_EXISTS') return MESSAGES.appealExists;
+      if (error.code === 'APPEAL_NOT_ALLOWED') return MESSAGES.appealNotAllowed;
+      if (error.status === 429 || error.code === 'RATE_LIMITED') {
+        return MESSAGES.appealTooMany;
+      }
+    }
+    return failureMessage(error);
+  }
+
+  /**
+   * Show the new state of an appeal under its comment.
+   *
+   * @param {CommentItem} item
+   * @param {CommentAppeal | null} appeal
+   */
+  function applyAppeal(item, appeal) {
+    const comment = item._comment;
+    fillComment(
+      item,
+      Object.assign({}, comment, {
+        own: Object.assign({}, comment.own, { appeal, canAppeal: false }),
+      }),
+    );
+    focusNode(item);
+  }
+
+  /**
+   * @param {CommentItem} item
+   * @param {HTMLElement} trigger
+   */
+  function openAppeal(item, trigger) {
+    if (!session) {
+      startSignIn({ kind: 'signin' });
+      return;
+    }
+    const wrapper = make('div', 'g-composer');
+    const inputId = uniqueId('appeal');
+    const label = make('label', '', MESSAGES.appealLabel);
+    label.setAttribute('for', inputId);
+    const input = make('textarea', 'g-composer__input');
+    input.id = inputId;
+    input.rows = 3;
+    input.setAttribute('maxlength', String(NOTE_LIMIT));
+    const error = make('p', 'g-composer__error');
+    error.setAttribute('role', 'alert');
+    error.hidden = true;
+    const actions = make('div', 'g-composer__actions');
+    const send = button('g-composer__submit', MESSAGES.appealSend);
+    const cancel = button('g-composer__cancel', MESSAGES.cancel);
+    actions.appendChild(send);
+    actions.appendChild(cancel);
+    for (const node of [label, input, error, actions]) {
+      wrapper.appendChild(node);
+    }
+
+    /**
+     * @param {string} text
+     */
+    const showError = (text) => {
+      error.textContent = text;
+      error.hidden = !text;
+      if (text) announceNow(text);
+    };
+    const close = () => {
+      wrapper.remove();
+      trigger.hidden = false;
+    };
+    cancel.addEventListener('click', () => {
+      close();
+      focusNode(trigger);
+    });
+    input.addEventListener('input', () => showError(''));
+    input.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        cancel.click();
+      }
+    });
+    send.addEventListener('click', async () => {
+      if (!session) {
+        startSignIn({ kind: 'signin' });
+        return;
+      }
+      const note = input.value.trim();
+      if (!note) {
+        showError(MESSAGES.appealEmpty);
+        return;
+      }
+      if (codePoints(note) > NOTE_LIMIT) {
+        showError(MESSAGES.appealTooLong);
+        return;
+      }
+      setDisabled(send, true);
+      send.setAttribute('aria-busy', 'true');
+      showError('');
+      try {
+        await api(
+          'POST',
+          '/v2/public/comments/' +
+            encodeURIComponent(item._comment.id) +
+            '/appeals',
+          { body: { note } },
+        );
+        // "Appeal sent" is drawn by the redraw alone, under the comment where
+        // focus lands; the status line does not repeat it.
+        close();
+        applyAppeal(item, { state: 'PENDING' });
+      } catch (failure) {
+        const message = appealFailureMessage(failure);
+        if (
+          failure instanceof ApiError &&
+          (failure.code === 'APPEAL_EXISTS' ||
+            failure.code === 'APPEAL_NOT_ALLOWED')
+        ) {
+          // The server's answer is final for this removal: stop offering it.
+          close();
+          applyAppeal(
+            item,
+            failure.code === 'APPEAL_EXISTS'
+              ? item._comment.own?.appeal || { state: 'PENDING' }
+              : item._comment.own?.appeal || null,
+          );
+          announce(message);
+        } else {
+          setDisabled(send, false);
+          showError(message);
+        }
+      } finally {
+        send.removeAttribute('aria-busy');
+      }
+    });
+
+    trigger.hidden = true;
+    const replies = item.querySelector(':scope > .g-comment__replies');
+    if (replies) item.insertBefore(wrapper, replies);
+    else item.appendChild(wrapper);
+    focusNode(input);
+  }
+
   // ------------------------------------------------------------------- loading
   /**
    * @param {CommentPage} page
@@ -1803,7 +2136,7 @@
 
   async function loadMore() {
     if (!live.nextCursor || !moreEl) return;
-    moreEl.disabled = true;
+    setBusy(moreEl, true);
     try {
       const query = new URLSearchParams({ cursor: live.nextCursor });
       const page = await api(
@@ -1814,7 +2147,7 @@
     } catch (error) {
       announce(failureMessage(error));
     } finally {
-      moreEl.disabled = false;
+      setBusy(moreEl, false);
     }
   }
 

package/types/index.d.ts

@@ -54,10 +54,23 @@ export interface RenderableBody {
   renderPolicy: { name: string; version: string; digest: string };
 }
 
+/**
+ * A `contentEdition`-shaped object: which article a `kind: "edition"` document
+ * restates, at what depth, and where it came from. A stale edition never
+ * reaches the renderer, so `sourceDigest` is carried but not compared.
+ */
+export interface ContentEdition {
+  of: string;
+  kind: 'QUICK_READ' | 'STANDARD' | 'DEEP_DIVE';
+  sourceDigest: string;
+  generation: { provider: string; model: string; generationId: string };
+  approvedAt: string;
+}
+
 /** A `contentFrontmatterNormalized`-shaped record's fields this renderer reads. */
 export interface ContentFrontmatterNormalized {
   id: string;
-  kind: 'article' | 'page';
+  kind: 'article' | 'page' | 'edition';
   title: string;
   description?: string;
   language: string;
@@ -74,6 +87,20 @@ export interface ContentFrontmatterNormalized {
   hero?: ResolvedMediaRef;
   socialImage?: ResolvedFileRef;
   redirects: string[];
+  /** Present exactly when `kind` is `edition`. */
+  edition?: ContentEdition;
+}
+
+/**
+ * A `contentBuildMediaFile`-shaped entry: one repository file a document
+ * references. Every image the document's body references must be one of
+ * these (an image media type).
+ */
+export interface ContentBuildMediaFile {
+  path: string;
+  sourceDigest: string;
+  mediaType: string;
+  byteLength: number;
 }
 
 /** A `contentBuildRecord`-shaped record. */
@@ -87,6 +114,7 @@ export interface ContentBuildRecord {
   sourceRevision: string;
   sourceDigest: string;
   resolvedAuthorIds: string[];
+  media?: ContentBuildMediaFile[];
 }
 
 /** A `socialLink`-shaped reference. */
@@ -174,6 +202,8 @@ export interface AppearanceNormalized {
   fontAssets: ResolvedFileRef[];
   tokens: Record<string, never>;
   source: NormalizedSource;
+  /** The footer attribution switch; absent means the attribution shows. */
+  attribution?: { showMadeWith: boolean };
 }
 
 /** The subset of `build-input:2.0.0` this renderer reads. */