@chatwarden/player-react 0.0.0-stage → 0.1.3

package/src/ReportDialog.tsx

@@ -0,0 +1,319 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import type { FormEvent, ReactNode } from 'react';
+import type { PlayerReporting, ReportDetailResult, ReportRefusal, ReportResult } from '@chatwarden/core';
+import { NOTE_MAX } from './constants.js';
+import { PlayerError } from './client.js';
+import { Dialog } from './Dialog.js';
+import type { PlayerText } from './i18n.js';
+import { groupReasons, readReporting } from './reporting.js';
+import { errorText, Portal, Root, useUi } from './ui.js';
+import type { DialogHostProps, PlayerUiProps } from './ui.js';
+
+/**
+ * What the player filled in. Your server adds the room and the seats and calls `cw.reports.submit({ ...draft, roomId, reporterSeat,
+ * targetSeat })`. The dialog sends `reason` (an id from the studio's `reporting` list, or nothing) and `note` in the one report. A
+ * reason is only a hint: the moderators decide what a report really is.
+ */
+export interface ReportDraft {
+  /** The reason the player chose: an id from `reporting.reasons`. Left out when none was chosen. */
+  reason?: string;
+  /** The note, trimmed; left out when blank. */
+  note?: string;
+}
+
+/**
+ * A reason and a note added to a report after it was filed (`cw.reports.addDetail`). The dialog no longer has a follow-up step (the
+ * reason and the note go in the one report), so this is only the shape a follow-up of your own may take.
+ */
+export interface ReportFollowUp {
+  reason?: string;
+  note?: string;
+}
+
+export interface ReportDialogProps extends PlayerUiProps, DialogHostProps {
+  /**
+   * Sends the report: your server calls `cw.reports.submit({ ...draft, roomId, reporterSeat, targetSeat })` and returns its
+   * `ReportResult`. A refusal is a result, not an error; reject only when no answer arrived.
+   */
+  onSubmit: (draft: ReportDraft) => Promise<ReportResult>;
+  /**
+   * @deprecated The dialog is one step now: the reason and the note go in the single `onSubmit`, so this is accepted but never
+   * called. Remove it. (`cw.reports.addDetail` is still there for a follow-up of your own.)
+   */
+  onAddDetail?: (reportId: string, detail: ReportFollowUp) => Promise<ReportDetailResult>;
+  /** Called on Escape, Cancel and Close. Unmount the dialog in answer. */
+  onClose: () => void;
+  /**
+   * How reporting works here: `(await createPlayerClient.rules()).reporting`, the `reporting` part of `GET /rules`. It gives the
+   * reasons (grouped, with hints), whether a reason is required, and the thank-you. Without it the dialog has no reasons to offer:
+   * one press files the report, with the dialog's own words, the same as when `GET /rules` cannot be loaded.
+   */
+  reporting?: PlayerReporting;
+  /** Who is being reported, as the player knows them (a handle). Shown as text in the heading. */
+  targetName?: string;
+  /** The message being reported. Shown as quoted text (cut if very long) so the player sees what they are reporting. */
+  line?: string;
+  /**
+   * @experimental Your own controls, placed inside the form under the reason and the note and above Report and Cancel (for example
+   * an "Also mute this player" checkbox and a line about false reports). You own their state; the dialog only places them, adds no
+   * styling beyond the spacing, and keeps their focusable controls in its Tab order (reason, note, yours, Report, Cancel) and its
+   * focus trap. They are not shown once the report is sent. They sit inside the dialog's form, so give your buttons `type="button"`:
+   * a plain button, or Enter in a text field of yours, sends the report.
+   */
+  extra?: ReactNode;
+}
+
+// One plain message for each refusal the kit has. Anything else (a refusal a newer kit adds) gets the last one.
+const REFUSED_TEXT: Readonly<Record<ReportRefusal, PlayerText>> = {
+  duplicate: 'player.report.refused.duplicate',
+  rate: 'player.report.refused.rate',
+  self: 'player.report.refused.self',
+  not_player: 'player.report.refused.not_player',
+  off: 'player.report.refused.off',
+  suspended: 'player.report.refused.suspended',
+  reason_required: 'player.report.refused.reason_required',
+  reason_unknown: 'player.report.refused.reason_unknown',
+};
+
+/** How much of the reported message is quoted on the screen. */
+const LINE_MAX = 280;
+
+/** A failure to send as an error the components can word: anything that is not already a PlayerError is a dropped connection. */
+const failureOf = (e: unknown): PlayerError =>
+  e instanceof PlayerError ? e : new PlayerError({ status: 0, code: 'network', message: 'Could not reach the server.' });
+
+/** Anything that is not a result object (undefined, null, a string) is not a success and not a crash: it reads as an unknown refusal. */
+const resultOf = <T,>(answer: unknown, unknown: T): T => (typeof answer === 'object' && answer !== null && !Array.isArray(answer) ? (answer as T) : unknown);
+
+const quoted = (line: string | undefined): string => {
+  const plain = (line ?? '').replace(/\s+/g, ' ').trim();
+  return plain.length > LINE_MAX ? `${plain.slice(0, LINE_MAX).trimEnd()}…` : plain;
+};
+
+/**
+ * A dialog for reporting a message or a player, in one step: "Report this message?", the quoted line, an optional "Why?" (one
+ * select, the reasons in groups) and a Report button. A note is behind "Add a note", or shown when the chosen reason asks for one.
+ * Report sends the reason and the note together (`onSubmit`); the dialog then says "Report sent" and the thank-you. The studio's
+ * `reporting` setting decides whether the reason is required (`reason_required`: the select is required, and Report without a
+ * reason asks for one and sends nothing), what the reasons are, and the thank-you. The reason is only a hint for the moderators.
+ * Every refusal the kit can give has its own plain message. Render it when the player chooses to report, and unmount it in `onClose`.
+ */
+export function ReportDialog(props: ReportDialogProps) {
+  const { onSubmit, onClose, targetName, line, theme, className, container, returnFocusTo, extra } = props;
+  const ui = useUi(props);
+  const { t } = ui;
+  const heading = useRef<HTMLHeadingElement>(null);
+  const select = useRef<HTMLSelectElement>(null);
+  const noteField = useRef<HTMLTextAreaElement>(null);
+  // One report on its way at a time: a second click, or a second Enter, does nothing.
+  const sending = useRef(false);
+  const titleId = useId();
+  const reasonId = useId();
+  const noteId = useId();
+  const noteHintId = useId();
+  const reasonHintId = useId();
+  const missingId = useId();
+  const [reason, setReason] = useState('');
+  const [note, setNote] = useState('');
+  // The note is shown once it was asked for (the "Add a note" button, or a reason that asks for one) and then stays.
+  const [noteOpen, setNoteOpen] = useState(false);
+  const [focusNote, setFocusNote] = useState(false);
+  const [missing, setMissing] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<PlayerError | null>(null);
+  const [result, setResult] = useState<ReportResult | null>(null);
+
+  // No `reporting` (or something that is not the payload): no reasons to offer, as when `GET /rules` cannot be loaded.
+  const read = readReporting(props.reporting) ?? { flow: 'one_tap' as const, reasons: [], thanks: '' };
+  const thanks = read.thanks.trim();
+  const hasReasons = read.reasons.length > 0;
+  // A flow that asks for a reason has nothing to ask with when the list is empty.
+  const required = hasReasons && read.flow === 'reason_required';
+  const groups = groupReasons(read.reasons);
+  const named = groups.filter((g) => g.name !== '');
+  const bare = groups.filter((g) => g.name === '').flatMap((g) => g.items);
+  // The reason is read from the CURRENT list: if `reporting` changes while the dialog is open and the id the player chose is gone, the
+  // select shows the placeholder, and this is undefined, so nothing stale is sent (and a required reason is asked for again).
+  const chosen = read.reasons.find((r) => r.id === reason);
+  const reasonValue = chosen === undefined ? '' : chosen.id;
+  const hint = chosen !== undefined && chosen.hint !== '' ? chosen.hint : null;
+  const noteShown = hasReasons && noteOpen;
+
+  // The form is gone once there is an answer: focus goes back to the heading, so the answer is read and focus is not lost.
+  useEffect(() => {
+    if (result !== null) heading.current?.focus();
+  }, [result]);
+  // "Add a note" is replaced by the field: focus follows it.
+  useEffect(() => {
+    if (focusNote) {
+      noteField.current?.focus();
+      setFocusNote(false);
+    }
+  }, [focusNote]);
+
+  const send = async (draft: ReportDraft): Promise<void> => {
+    sending.current = true;
+    setBusy(true);
+    setFailure(null);
+    try {
+      setResult(resultOf<ReportResult>(await onSubmit(draft), { ok: false, refused: 'unknown' } as unknown as ReportResult));
+    } catch (error) {
+      setFailure(failureOf(error));
+    } finally {
+      sending.current = false;
+      setBusy(false);
+    }
+  };
+
+  const trimmed = note.trim();
+  const submit = (e: FormEvent): void => {
+    e.preventDefault();
+    if (sending.current) return;
+    if (required && reasonValue === '') {
+      setMissing(true);
+      select.current?.focus();
+      return;
+    }
+    const draft: ReportDraft = {};
+    if (reasonValue !== '') draft.reason = reasonValue;
+    if (noteShown && trimmed !== '') draft.note = trimmed;
+    void send(draft);
+  };
+
+  const quote = quoted(line);
+  const title = quote !== '' ? t('player.report.titleOneTap') : targetName === undefined ? t('player.report.titleOneTapPlayer') : t('player.report.titleOneTapNamed', { name: targetName });
+  const taken = result?.ok === true;
+  const refusal = result !== null && !taken ? result : null;
+  // After an answer the heading says what happened (a question would be stale), and focus is on it.
+  const shownTitle = result === null ? title : taken ? t('player.report.titleSent') : t('player.report.titleRefused');
+  const remaining = taken && typeof result.remaining === 'number' && Number.isFinite(result.remaining) && result.remaining >= 0 ? result.remaining : null;
+  const refusedKey = (r: unknown): PlayerText => {
+    const refused = (r as { refused?: unknown }).refused;
+    return typeof refused === 'string' && Object.hasOwn(REFUSED_TEXT, refused) ? REFUSED_TEXT[refused as ReportRefusal] : 'player.report.refused.unknown';
+  };
+  const option = (r: { id: string; label: string }) => (
+    <option key={r.id} value={r.id}>
+      {r.label}
+    </option>
+  );
+  const describedBy = [hint === null ? '' : reasonHintId, missing ? missingId : ''].filter((id) => id !== '').join(' ');
+
+  return (
+    <Portal container={container}>
+    <Root theme={theme} className={className}>
+      <Dialog labelledBy={titleId} initialFocus={heading} onEscape={() => !sending.current && onClose()} {...(returnFocusTo === undefined ? {} : { returnFocusTo })}>
+        <h2 id={titleId} ref={heading} className="cw-title" tabIndex={-1}>
+          {shownTitle}
+        </h2>
+        {/* Always there, so what is written into it is announced: the thank-you. */}
+        <div role="status" className="cw-live">
+          {taken && (
+            <p className="cw-result">
+              {thanks === '' ? t('player.report.thanks') : thanks}
+              {remaining !== null && ` ${t('player.report.remaining', { count: remaining })}`}
+            </p>
+          )}
+        </div>
+        {result === null ? (
+          <form onSubmit={submit} noValidate>
+            <p className="cw-body">{required ? t('player.report.intro') : t('player.report.oneTap.intro')}</p>
+            {quote !== '' && <blockquote className="cw-quote">{t('player.report.quote', { line: quote })}</blockquote>}
+            {hasReasons && (
+              <div className="cw-field">
+                <label className="cw-label" htmlFor={reasonId}>
+                  {required ? t('player.report.whyRequired') : t('player.report.why')}
+                </label>
+                <select
+                  id={reasonId}
+                  ref={select}
+                  className="cw-select"
+                  value={reasonValue}
+                  required={required}
+                  aria-invalid={missing || undefined}
+                  aria-describedby={describedBy === '' ? undefined : describedBy}
+                  onChange={(e) => {
+                    const id = e.target.value;
+                    setReason(id);
+                    setMissing(false);
+                    if (read.reasons.find((r) => r.id === id)?.asksNote === true) setNoteOpen(true);
+                  }}
+                >
+                  <option value="">{required ? t('player.report.chooseRequired') : t('player.report.choose')}</option>
+                  {named.map((g) => (
+                    <optgroup key={g.name} label={g.name}>
+                      {g.items.map(option)}
+                    </optgroup>
+                  ))}
+                  {bare.map(option)}
+                </select>
+                {hint !== null && (
+                  <p id={reasonHintId} className="cw-hint">
+                    {hint}
+                  </p>
+                )}
+                {missing && (
+                  <p id={missingId} className="cw-field-error" role="alert">
+                    {t('player.report.needReason')}
+                  </p>
+                )}
+              </div>
+            )}
+            {noteShown && (
+              <div className="cw-field">
+                <label className="cw-label" htmlFor={noteId}>
+                  {t('player.report.note')}
+                </label>
+                <textarea id={noteId} ref={noteField} className="cw-textarea" rows={3} maxLength={NOTE_MAX} value={note} aria-describedby={noteHintId} onChange={(e) => setNote(e.target.value)} />
+                <p id={noteHintId} className="cw-hint">
+                  {t('player.report.noteHint', { max: NOTE_MAX })}
+                </p>
+              </div>
+            )}
+            {hasReasons && !noteShown && (
+              // No aria-expanded: this is a one-way door. It is removed when pressed (the note takes its place) and focus moves to the note.
+              <button
+                type="button"
+                className="cw-linkbtn"
+                onClick={() => {
+                  setNoteOpen(true);
+                  setFocusNote(true);
+                }}
+              >
+                {t('player.report.addNote')}
+              </button>
+            )}
+            {extra !== undefined && extra !== null && extra !== false && <div className="cw-extra">{extra}</div>}
+            {failure !== null && (
+              <p className="cw-error" role="alert">
+                {t('player.report.failed')} {errorText(t, failure)}
+              </p>
+            )}
+            <div className="cw-actions">
+              <button type="submit" className="cw-btn cw-btn--primary" aria-disabled={busy || undefined} aria-busy={busy || undefined}>
+                {t('player.report.oneTap.send')}
+              </button>
+              {/* Closing while a report is on its way would lose the answer: busy, like Escape. */}
+              <button type="button" className="cw-btn" aria-disabled={busy || undefined} onClick={() => !sending.current && onClose()}>
+                {t('player.report.cancel')}
+              </button>
+            </div>
+          </form>
+        ) : (
+          <>
+            {!taken && (
+              <p className="cw-error" role="alert">
+                {t(refusedKey(refusal))}
+              </p>
+            )}
+            <div className="cw-actions">
+              <button type="button" className="cw-btn cw-btn--primary" aria-disabled={busy || undefined} onClick={() => !sending.current && onClose()}>
+                {t('player.report.close')}
+              </button>
+            </div>
+          </>
+        )}
+      </Dialog>
+    </Root>
+    </Portal>
+  );
+}

package/src/RestrictedChatLine.tsx

@@ -0,0 +1,42 @@
+import { timeLeft, untilText } from './format.js';
+import { Card, Root, useUi } from './ui.js';
+import type { PlayerUiProps } from './ui.js';
+
+export interface RestrictedChatLineProps extends PlayerUiProps {
+  /** When the restriction ends (epoch ms), or `null` for no end. From `cw.chat.restricted(...)`. */
+  until: number | null;
+  /** `true` when a moderator turned the chat off, `false` when the automatic filter did (kind `auto`). */
+  byModerator: boolean;
+  /** The reference code to quote to a moderator, when you have one. */
+  refCode?: string;
+}
+
+/** One line for the place a chat box would be, saying why the player cannot type, until when, and who did it. */
+export function RestrictedChatLine(props: RestrictedChatLineProps) {
+  const { until, byModerator, refCode, theme, className } = props;
+  const ui = useUi(props);
+  const { t, locale, timeZone } = ui;
+  const ends = typeof until === 'number' && Number.isFinite(until);
+  const when = ends ? untilText(until, locale, timeZone) : '';
+  const left = ends ? timeLeft(until, ui.now(), locale) : null;
+  const text = !ends
+    ? t(byModerator ? 'player.restricted.moderator.noEnd' : 'player.restricted.filter.noEnd')
+    : left === null
+      ? t('player.restricted.ended', { when })
+      : t(byModerator ? 'player.restricted.moderator.until' : 'player.restricted.filter.until', { when, left });
+
+  return (
+    <Root theme={theme} className={className}>
+      <p className="cw-restricted" role="status">
+        <Card kind="chat" />
+        <span className="cw-text">{text}</span>
+        {refCode !== undefined && (
+          <>
+            {' '}
+            <span className="cw-ref">{t('player.restricted.ref', { code: refCode })}</span>
+          </>
+        )}
+      </p>
+    </Root>
+  );
+}

package/src/RulesPage.tsx

@@ -0,0 +1,49 @@
+import { useId } from 'react';
+import type { PlayerClient } from './client.js';
+import { usePlayerData } from './hooks.js';
+import { ErrorBlock, Root, useUi } from './ui.js';
+import type { PlayerUiProps } from './ui.js';
+
+export interface RulesPageProps extends PlayerUiProps {
+  client: PlayerClient;
+  /** Change it to load the rules again. */
+  refreshKey?: number | string;
+}
+
+/** The community rules: the profile's summary and the numbered rules from `GET /rules`. Text only, never HTML. */
+export function RulesPage(props: RulesPageProps) {
+  const { client, refreshKey, theme, className } = props;
+  const ui = useUi(props);
+  const { t } = ui;
+  const state = usePlayerData(() => client.rules(), refreshKey);
+  const titleId = useId();
+  const data = state.data;
+
+  return (
+    <Root theme={theme} className={className}>
+      <section className="cw-section" aria-labelledby={titleId}>
+        <h2 id={titleId} className="cw-title">
+          {t('player.rules.title')}
+        </h2>
+        {state.error !== null && <ErrorBlock ui={ui} what={t('player.rules.loadFailed')} error={state.error} onRetry={state.reload} />}
+        {data === undefined && state.error === null && (
+          <p className="cw-state" role="status">
+            {t('player.rules.loading')}
+          </p>
+        )}
+        {data !== undefined && data.summary !== '' && <p className="cw-summary">{data.summary}</p>}
+        {data !== undefined && data.rules.length === 0 && <p className="cw-state">{t('player.rules.empty')}</p>}
+        {data !== undefined && data.rules.length > 0 && (
+          // The kit's own numbers, so a retired rule leaves a gap instead of renumbering the ones after it.
+          <ol className="cw-rules" aria-labelledby={titleId}>
+            {data.rules.map((rule) => (
+              <li key={rule.number} value={rule.number}>
+                <strong className="cw-rule-title">{rule.title}</strong> <span className="cw-rule-text">{rule.text}</span>
+              </li>
+            ))}
+          </ol>
+        )}
+      </section>
+    </Root>
+  );
+}

package/src/client.ts

@@ -0,0 +1,132 @@
+import type { PlayerNotice, PlayerReporting } from '@chatwarden/core';
+import { readReporting } from './reporting.js';
+import type { Transport, TransportRequest, TransportResponse } from './transport.js';
+
+/**
+ * Why a call to the player routes failed. `status` is the HTTP status, or 0 when no answer arrived. `code` is the kit's error
+ * code (`not_found`, `rate_limited`, ...), `network` for a dropped connection, `bad_response` for an answer that is not the
+ * shape the components expect, `unexpected` for anything else, and `http_<status>` when the body is not a kit error.
+ * `retryAfter` is the seconds from a `retry-after` header (a 429).
+ */
+export class PlayerError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly retryAfter: number | undefined;
+
+  constructor(init: { status: number; code: string; message: string; retryAfter?: number }) {
+    super(init.message);
+    this.name = 'PlayerError';
+    this.status = init.status;
+    this.code = init.code;
+    this.retryAfter = init.retryAfter;
+  }
+}
+
+/** A `PlayerError` as is; anything else (a bug in the caller's code, say) becomes status 0, code `unexpected`. */
+export function toPlayerError(e: unknown): PlayerError {
+  if (e instanceof PlayerError) return e;
+  return new PlayerError({ status: 0, code: 'unexpected', message: e instanceof Error ? e.message : 'Something went wrong.' });
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v: unknown): v is string => typeof v === 'string';
+
+function errorOf(res: TransportResponse): PlayerError {
+  const b = res.body;
+  const raw = res.headers['retry-after'];
+  const rest = raw !== undefined && /^\d{1,9}$/.test(raw) ? { retryAfter: Number(raw) } : {};
+  if (isObject(b) && text(b.error) && text(b.message)) return new PlayerError({ status: res.status, code: b.error, message: b.message, ...rest });
+  // A proxy's HTML page, or an empty body: say the status, never echo the body.
+  return new PlayerError({ status: res.status, code: `http_${res.status}`, message: `The server answered with status ${res.status}.`, ...rest });
+}
+
+async function send(transport: Transport, req: TransportRequest): Promise<unknown> {
+  let res: TransportResponse;
+  try {
+    res = await transport(req);
+  } catch (e) {
+    throw new PlayerError({ status: 0, code: 'network', message: e instanceof Error && e.name === 'AbortError' ? 'The request was cancelled.' : 'Could not reach the server.' });
+  }
+  if (res.status < 200 || res.status > 299) throw errorOf(res);
+  return res.body;
+}
+
+const bad = (): PlayerError => new PlayerError({ status: 200, code: 'bad_response', message: 'The server sent an answer these components do not understand.' });
+
+/** One notice, keeping only the fields the kit documents for a player. Anything else the server sent never reaches the page. */
+function noticeOf(raw: unknown): PlayerNotice | null {
+  if (!isObject(raw) || !text(raw.id) || !text(raw.kind)) return null;
+  const excerpt = Array.isArray(raw.excerpt)
+    ? raw.excerpt.filter(isObject).filter((l) => text(l.text) && text(l.day)).map((l) => ({ text: l.text as string, day: l.day as string }))
+    : [];
+  return {
+    id: raw.id,
+    kind: raw.kind as PlayerNotice['kind'],
+    rule: typeof raw.rule === 'number' || raw.rule === 'uncovered' ? raw.rule : null,
+    ruleLabel: text(raw.ruleLabel) ? raw.ruleLabel : null,
+    until: typeof raw.until === 'number' && Number.isFinite(raw.until) ? raw.until : null,
+    refCode: text(raw.refCode) ? raw.refCode : null,
+    excerpt,
+    createdAt: typeof raw.createdAt === 'number' && Number.isFinite(raw.createdAt) ? raw.createdAt : 0,
+    mustAcknowledge: raw.mustAcknowledge === true,
+  };
+}
+
+function noticesOf(body: unknown, key: 'notices' | 'record'): PlayerNotice[] {
+  if (!isObject(body) || !Array.isArray(body[key])) throw bad();
+  return (body[key] as unknown[]).map(noticeOf).filter((n): n is PlayerNotice => n !== null);
+}
+
+/** One rule as `GET /rules` gives it. */
+export interface PlayerRule {
+  number: number;
+  title: string;
+  text: string;
+}
+
+/** `GET /rules`: the profile's one-line summary, the active rules and how reporting works here (`undefined` from an older server). */
+export interface PlayerRules {
+  summary: string;
+  rules: PlayerRule[];
+  /** The flow, the reasons a player may give and the thank-you: pass it to `ReportDialog` as `reporting`. */
+  reporting?: PlayerReporting;
+}
+
+export interface PlayerClient {
+  /** `GET /notices`: notices not yet acknowledged, as the kit sends them (oldest first). */
+  notices(): Promise<PlayerNotice[]>;
+  /** `POST /notices/:id/ack`: `true` when it was this player's live notice, `false` (still a 200) when it was not, or it is gone. */
+  ack(id: string): Promise<boolean>;
+  /** `GET /record`: the player's sanctions that still apply (seen or not). */
+  record(): Promise<PlayerNotice[]>;
+  /** `GET /rules`: the summary, the numbered rules and the reporting settings. */
+  rules(): Promise<PlayerRules>;
+}
+
+export interface PlayerClientOptions {
+  /** How to reach the player routes: `fetchTransport({ baseUrl: '/player' })`, or any function with the same shape. */
+  transport: Transport;
+}
+
+/** A client over the kit's player routes. It resolves with typed values and rejects with a `PlayerError`. */
+export function createPlayerClient({ transport }: PlayerClientOptions): PlayerClient {
+  return {
+    notices: async () => noticesOf(await send(transport, { method: 'GET', path: '/notices' }), 'notices'),
+    record: async () => noticesOf(await send(transport, { method: 'GET', path: '/record' }), 'record'),
+    ack: async (id) => {
+      const body = await send(transport, { method: 'POST', path: `/notices/${encodeURIComponent(id)}/ack` });
+      if (!isObject(body) || typeof body.ok !== 'boolean') throw bad();
+      return body.ok;
+    },
+    rules: async () => {
+      const body = await send(transport, { method: 'GET', path: '/rules' });
+      if (!isObject(body) || !text(body.summary) || !Array.isArray(body.rules)) throw bad();
+      const rules = body.rules
+        .filter(isObject)
+        .filter((r) => typeof r.number === 'number' && text(r.title) && text(r.text))
+        .map((r) => ({ number: r.number as number, title: r.title as string, text: r.text as string }));
+      const reporting = readReporting(body.reporting);
+      return { summary: body.summary, rules, ...(reporting === undefined ? {} : { reporting }) };
+    },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+/** The longest note the kit keeps (a test keeps this the same as core's `REPORT_NOTE_MAX`). */
+export const NOTE_MAX = 500;
+
+/** How many days a warning stays on a record (a test keeps this the same as core's notice record window). */
+export const WARNING_DAYS = 90;

package/src/format.ts

@@ -0,0 +1,53 @@
+// Small pure helpers for showing days, times and waits. Times use Intl with the component's `locale`; none holds English.
+
+const MIN = 60_000;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+function safeLocale(locale: string): string {
+  try {
+    return Intl.getCanonicalLocales(locale)[0] ?? 'en';
+  } catch {
+    return 'en';
+  }
+}
+
+/** Some runtimes put a narrow no-break space before "PM". A plain space reads the same and survives a copy. */
+const plain = (text: string): string => text.replace(/[\u202f\u00a0]/g, ' ');
+
+/**
+ * A UTC day from the kit (`2027-01-15`) as the locale writes a date (`Jan 15, 2027`), in UTC whatever the viewer's zone: the kit
+ * names the day in UTC, so a notice never shows a different day than the moderator's tools. A value that is not a day comes back
+ * as it was; it is never shown as "Invalid Date".
+ */
+export function dayText(day: string, locale: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+  if (m === null) return day;
+  const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const date = new Date(Date.UTC(y, mo - 1, d));
+  if (date.getUTCFullYear() !== y || date.getUTCMonth() !== mo - 1 || date.getUTCDate() !== d) return day;
+  return new Intl.DateTimeFormat(safeLocale(locale), { dateStyle: 'medium', timeZone: 'UTC' }).format(date);
+}
+
+/** A date and time: `Jan 15, 2027, 8:30 PM`. Pass a time zone for a fixed one; the default is the viewer's. An unknown zone is ignored. */
+export function untilText(at: number, locale: string, timeZone?: string): string {
+  const options: Intl.DateTimeFormatOptions = { dateStyle: 'medium', timeStyle: 'short' };
+  try {
+    return plain(new Intl.DateTimeFormat(safeLocale(locale), { ...options, ...(timeZone === undefined ? {} : { timeZone }) }).format(at));
+  } catch {
+    return plain(new Intl.DateTimeFormat(safeLocale(locale), options).format(at));
+  }
+}
+
+/**
+ * How long is left until `at`, as the locale says it ("in 3 hours"): minutes under an hour (a part of a minute counts as a whole
+ * one, so a live restriction never reads "in 0 minutes"), hours under two days, then days. Null when `at` is now or has passed.
+ */
+export function timeLeft(at: number, now: number, locale: string): string | null {
+  const left = at - now;
+  if (!(left > 0)) return null;
+  const rtf = new Intl.RelativeTimeFormat(safeLocale(locale), { numeric: 'always' });
+  if (left < HOUR) return rtf.format(Math.max(1, Math.ceil(left / MIN)), 'minute');
+  if (left < 2 * DAY) return rtf.format(Math.round(left / HOUR), 'hour');
+  return rtf.format(Math.round(left / DAY), 'day');
+}

package/src/hooks.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { PlayerError, toPlayerError } from './client.js';
+
+export interface PlayerData<T> {
+  /** The last answer, kept when a later load fails. */
+  data: T | undefined;
+  /** The last failure, or null. Cleared when a load starts. */
+  error: PlayerError | null;
+  /** Starts the same load again. */
+  reload: () => void;
+}
+
+/**
+ * Runs `load` on mount, again when `refreshKey` changes, and again on `reload()`. An answer from a load that has been replaced
+ * (or from a component that is gone) is dropped, so a slow old request never overwrites a newer one.
+ */
+export function usePlayerData<T>(load: () => Promise<T>, refreshKey: unknown): PlayerData<T> {
+  const [state, setState] = useState<{ data: T | undefined; error: PlayerError | null }>({ data: undefined, error: null });
+  const [again, setAgain] = useState(0);
+  const loader = useRef(load);
+  loader.current = load;
+
+  useEffect(() => {
+    let live = true;
+    setState((s) => (s.error === null ? s : { ...s, error: null }));
+    loader.current().then(
+      (data) => {
+        if (live) setState({ data, error: null });
+      },
+      (e: unknown) => {
+        if (live) setState((s) => ({ data: s.data, error: toPlayerError(e) }));
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [refreshKey, again]);
+
+  const reload = useCallback(() => setAgain((n) => n + 1), []);
+  return { data: state.data, error: state.error, reload };
+}