@frockbot/client-ui 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/client-ui",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,7 +12,7 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.9",
+    "@frockbot/client-core": "0.3.11",
     "markdown-it": "15.0.1",
     "vue": "3.5.41"
   },

package/src/UiActivityRing.vue

@@ -0,0 +1,156 @@
+<script setup lang="ts">
+/**
+ * A thin stroke drawn around an avatar while that Bot is working.
+ *
+ * It says two things without words: that something is still happening — it
+ * breathes — and that steps are going by, because the stroke advances as the
+ * caller's `progress` does. It never names what those steps were; the point of
+ * the ring is that the transcript stays a conversation.
+ *
+ * The element positions itself over its parent, which must be `position:
+ * relative`, and sits behind pointer events. `laps` draws a faint completed
+ * ring behind the live one so a long Turn reads as further along without the
+ * ring growing.
+ */
+const props = withDefaults(
+  defineProps<{
+    /** Fraction of the ring the live stroke draws, `0 … 1`. */
+    progress?: number;
+    /** Whether the ring breathes. A settled ring is still, and full. */
+    running?: boolean;
+    /** Faint rings behind the live stroke. Bounded by the caller. */
+    laps?: number;
+    /** What a screen reader is told this ring means. */
+    label?: string;
+  }>(),
+  { progress: 0, running: true, laps: 0, label: "Working" },
+);
+
+/*
+ * A 100-unit viewBox makes the geometry readable: the circumference below is
+ * the only number the stroke maths needs, and `stroke-dasharray` splits it
+ * into the drawn arc and the gap.
+ */
+const RADIUS = 46;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+const arc = () => {
+  const fraction = Math.min(1, Math.max(0, props.progress));
+  // A ring with nothing drawn on it is a ring nobody sees, and the first
+  // moment of a Turn — before a single step has settled — is exactly when
+  // somebody needs to see one. The minimum arc is a fifth of the circle: big
+  // enough to read as a moving head, small enough that the first real tick is
+  // still an advance.
+  const drawn = Math.max(0.2, fraction) * CIRCUMFERENCE;
+  return `${drawn} ${CIRCUMFERENCE - drawn}`;
+};
+</script>
+
+<template>
+  <span
+    class="ui-activity-ring"
+    :class="{ 'ui-activity-ring--running': running }"
+    role="status"
+    :aria-label="label"
+  >
+    <svg viewBox="0 0 100 100" aria-hidden="true" focusable="false">
+      <circle
+        v-if="laps > 0"
+        class="ui-activity-ring__lap"
+        cx="50"
+        cy="50"
+        :r="RADIUS"
+      />
+      <circle class="ui-activity-ring__track" cx="50" cy="50" :r="RADIUS" />
+      <circle
+        class="ui-activity-ring__arc"
+        cx="50"
+        cy="50"
+        :r="RADIUS"
+        :stroke-dasharray="arc()"
+      />
+    </svg>
+  </span>
+</template>
+
+<style scoped>
+.ui-activity-ring {
+  position: absolute;
+
+  /*
+   * Clear of the avatar rather than on top of it: an avatar is usually a
+   * rounded square, and a circle inscribed in its own box would run under the
+   * art at the sides and vanish. `z-index` keeps it above a positioned avatar,
+   * which is what the sidebar rows use.
+   */
+  z-index: 1;
+  inset: -7px;
+  pointer-events: none;
+}
+
+.ui-activity-ring svg {
+  width: 100%;
+  height: 100%;
+  /* Twelve o'clock, so the stroke advances the way a clock hand does. */
+  transform: rotate(-90deg);
+  overflow: visible;
+}
+
+/*
+ * The viewBox is 100 units across and the element is roughly 36px, so 6 units
+ * of stroke is the ~2px hairline this is meant to be at the size an avatar is
+ * actually drawn.
+ */
+.ui-activity-ring circle {
+  fill: none;
+  stroke-width: 6;
+  stroke-linecap: round;
+}
+
+/* The unfilled part of the ring. Present enough to read as a circle. */
+.ui-activity-ring__track {
+  stroke: var(--frock-border-strong);
+  opacity: 0.75;
+}
+
+.ui-activity-ring__lap {
+  stroke: var(--frock-action-primary);
+  opacity: 0.28;
+}
+
+.ui-activity-ring__arc {
+  stroke: var(--frock-action-primary);
+  /*
+   * The tick itself: a step settles, `progress` changes, and the dash grows
+   * into its new length rather than jumping there.
+   */
+  transition: stroke-dasharray 420ms ease-out;
+}
+
+.ui-activity-ring--running .ui-activity-ring__arc {
+  animation: frock-ring-pulse 2200ms ease-in-out infinite;
+}
+
+@keyframes frock-ring-pulse {
+  0%,
+  100% {
+    opacity: 0.7;
+  }
+
+  50% {
+    opacity: 1;
+  }
+}
+
+/*
+ * Reduced motion keeps the information and drops the movement: the ring still
+ * ticks forward for every step, it simply does not breathe or animate there.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .ui-activity-ring__arc {
+    transition: none;
+    animation: none;
+    opacity: 1;
+  }
+}
+</style>

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   UI_ANCHOR_HIGHLIGHT_MS,
   type UiAnchorEvent,
 } from "./anchors.js";
+export { default as UiActivityRing } from "./UiActivityRing.vue";
 export { default as UiButton } from "./UiButton.vue";
 export { default as UiField } from "./UiField.vue";
 export { default as UiIcon } from "./UiIcon.vue";
@@ -15,3 +16,11 @@ export { default as UiMarkdown } from "./UiMarkdown.vue";
 export { renderMarkdown } from "./markdown.js";
 export { default as UiSkeleton } from "./UiSkeleton.vue";
 export { createClientSurfaceRegistry } from "./surfaces.js";
+export {
+  browserTimeZoneV1,
+  formatDayV1,
+  formatMomentV1,
+  formatRelativeMomentV1,
+  formatTimeOfDayV1,
+  type UiMomentOptionsV1,
+} from "./time.js";

package/src/time.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import {
+  browserTimeZoneV1,
+  formatDayV1,
+  formatMomentV1,
+  formatRelativeMomentV1,
+  formatTimeOfDayV1,
+} from "./time.js";
+
+const SYDNEY = { timeZone: "Australia/Sydney" } as const;
+
+describe("formatMomentV1", () => {
+  test("renders a durable ISO moment in the reader's zone, day first", () => {
+    // The panel used to render this exact string verbatim.
+    expect(formatMomentV1("2026-09-03T12:08:28.834Z", SYDNEY)).toBe(
+      "3 Sep 2026, 10:08pm",
+    );
+  });
+
+  test("never renders the US month-first order", () => {
+    const formatted = formatMomentV1("2026-09-03T11:59:51.000Z", SYDNEY);
+    expect(formatted).not.toContain("9/3/2026");
+    expect(formatted.startsWith("3 Sep 2026")).toBe(true);
+  });
+
+  test("renders the same characters on every ICU build", () => {
+    // The month abbreviation and the am/pm marker are CLDR data, so a locale's
+    // own rendering of them moves between platform versions: the same instant
+    // read out of `en-AU` is "3 Sep 2026" under one ICU and "3 Sept 2026"
+    // under the next, with a narrow no-break space before the marker on some
+    // builds. This module assembles the string itself so two people reading
+    // the same Bot see the same text.
+    const formatted = formatMomentV1("2026-09-03T12:08:28.834Z", SYDNEY);
+    expect(formatted).toBe("3 Sep 2026, 10:08pm");
+    expect(formatted).not.toContain("Sept");
+    expect(formatted).toMatch(
+      /^\d{1,2} [A-Z][a-z]{2} \d{4}, \d{1,2}:\d{2}(am|pm)$/u,
+    );
+    // No exotic whitespace anywhere: one plain space after the day and the
+    // month, and nothing at all before the marker.
+    expect(/[^\u0020\w:,]/u.test(formatted)).toBe(false);
+  });
+
+  test("returns unparseable text untouched rather than 'Invalid Date'", () => {
+    expect(formatMomentV1("not a moment", SYDNEY)).toBe("not a moment");
+    expect(formatRelativeMomentV1("", SYDNEY)).toBe("");
+  });
+});
+
+describe("formatTimeOfDayV1", () => {
+  test("reads midnight and noon as 12, not as 0", () => {
+    // A 24-hour clock reads midnight as `0` and some ICU builds as `24`;
+    // neither is an hour anybody writes down.
+    expect(formatTimeOfDayV1("2026-09-03T14:00:00.000Z", SYDNEY)).toBe(
+      "12:00am",
+    );
+    expect(formatTimeOfDayV1("2026-09-03T02:00:00.000Z", SYDNEY)).toBe(
+      "12:00pm",
+    );
+  });
+
+  test("is 12-hour with a lowercase marker and no leading zero", () => {
+    expect(formatTimeOfDayV1("2026-09-03T23:30:00.000Z", SYDNEY)).toBe(
+      "9:30am",
+    );
+    expect(formatTimeOfDayV1("2026-09-03T04:05:00.000Z", SYDNEY)).toBe(
+      "2:05pm",
+    );
+  });
+});
+
+describe("formatDayV1", () => {
+  test("abbreviates the month", () => {
+    expect(formatDayV1("2026-09-03T12:00:00.000Z", SYDNEY)).toBe("3 Sep 2026");
+  });
+});
+
+describe("formatRelativeMomentV1", () => {
+  const now = new Date("2026-09-03T12:00:00.000Z");
+
+  test("reads a fresh run relatively and an old one absolutely", () => {
+    expect(
+      formatRelativeMomentV1("2026-09-03T11:59:30.000Z", { ...SYDNEY, now }),
+    ).toBe("just now");
+    expect(
+      formatRelativeMomentV1("2026-09-03T11:45:00.000Z", { ...SYDNEY, now }),
+    ).toBe("15 min ago");
+    expect(
+      formatRelativeMomentV1("2026-09-03T09:00:00.000Z", { ...SYDNEY, now }),
+    ).toBe("3 hours ago");
+    expect(
+      formatRelativeMomentV1("2026-08-30T09:00:00.000Z", { ...SYDNEY, now }),
+    ).toBe("30 Aug 2026, 7:00pm");
+  });
+
+  test("a future moment is absolute — 'in a while' is not a next run", () => {
+    expect(
+      formatRelativeMomentV1("2026-09-03T12:30:00.000Z", { ...SYDNEY, now }),
+    ).toBe("3 Sep 2026, 10:30pm");
+  });
+});
+
+describe("browserTimeZoneV1", () => {
+  test("names a zone the form can default to", () => {
+    expect(browserTimeZoneV1().length).toBeGreaterThan(0);
+  });
+});

package/src/time.ts

@@ -0,0 +1,176 @@
+/**
+ * One place the whole client turns a durable ISO moment into something a
+ * person reads.
+ *
+ * Every durable record carries UTC ISO text, because that is the only form two
+ * machines can agree on. A person reading the panel is not two machines: they
+ * want the moment in their own day. Panels used to render the ISO string
+ * verbatim — "Next run 2026-09-03T12:08:28.834Z" — which is precise and
+ * unreadable, and the one panel that did format dates picked the US order for
+ * an Australian reader. So this module, and nothing else, decides the shape.
+ *
+ * The shape is assembled here from numeric parts rather than taken from a
+ * locale's own rendering. `Intl` is asked only for the two things it alone
+ * knows — which calendar day and clock hour a UTC instant falls on in a given
+ * zone — and every visible character after that is ours. It has to be: the
+ * month abbreviation and the am/pm marker are CLDR data, so the same code
+ * renders "3 Sep 2026" under one ICU version and "3 Sept 2026" under the next,
+ * and a narrow no-break space before the marker under some builds and a plain
+ * one under others. That is invisible until a test written on one machine
+ * fails on another, and worse, it means two people reading the same Bot see
+ * different text. A house style that varies by machine is not a house style.
+ */
+
+/** The month names this module renders. Ours, not the platform's. */
+const MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+] as const;
+
+/**
+ * A locale chosen for one property only: it yields plain numeric parts for
+ * `year`/`month`/`day`/`hour`/`minute` in every ICU build. Nothing of its
+ * ordering, separators or names reaches the screen — `formatToParts` is read
+ * by name and the string is rebuilt below.
+ */
+const PARTS_LOCALE = "en-GB";
+
+/** The reader's own zone, or UTC where the environment will not say. */
+export function browserTimeZoneV1(): string {
+  try {
+    const zone = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof zone === "string" && zone.length > 0 ? zone : "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export interface UiMomentOptionsV1 {
+  /** The zone to read the moment in. Defaults to the reader's own. */
+  timeZone?: string;
+}
+
+interface MomentPartsV1 {
+  day: number;
+  month: number;
+  year: number;
+  hour: number;
+  minute: number;
+}
+
+/**
+ * The calendar day and clock time one UTC instant falls on in one zone.
+ *
+ * Read as a 24-hour clock and converted below, because `hour12` is where the
+ * am/pm marker and its spacing come from, and those are exactly the parts that
+ * differ between ICU builds.
+ */
+function momentParts(
+  iso: string,
+  options: UiMomentOptionsV1,
+): MomentPartsV1 | undefined {
+  const parsed = Date.parse(iso);
+  if (!Number.isFinite(parsed)) return undefined;
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat(PARTS_LOCALE, {
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+      hour12: false,
+      timeZone: options.timeZone ?? browserTimeZoneV1(),
+    }).formatToParts(new Date(parsed));
+  } catch {
+    return undefined;
+  }
+  const read = (type: Intl.DateTimeFormatPartTypes): number => {
+    const found = parts.find((part) => part.type === type);
+    return found === undefined ? Number.NaN : Number(found.value);
+  };
+  const moment = {
+    day: read("day"),
+    month: read("month"),
+    year: read("year"),
+    // Some builds render midnight under a 24-hour clock as `24`.
+    hour: read("hour") % 24,
+    minute: read("minute"),
+  };
+  return Object.values(moment).every((value) => Number.isFinite(value))
+    ? moment
+    : undefined;
+}
+
+/** `9:30am`, lowercase, no leading zero on the hour. */
+export function formatTimeOfDayV1(
+  iso: string,
+  options: UiMomentOptionsV1 = {},
+): string {
+  const moment = momentParts(iso, options);
+  if (!moment) return iso;
+  const marker = moment.hour < 12 ? "am" : "pm";
+  const hour = moment.hour % 12 === 0 ? 12 : moment.hour % 12;
+  return `${hour}:${String(moment.minute).padStart(2, "0")}${marker}`;
+}
+
+/** `3 Sep 2026` — day first, never the US month-first order. */
+export function formatDayV1(
+  iso: string,
+  options: UiMomentOptionsV1 = {},
+): string {
+  const moment = momentParts(iso, options);
+  if (!moment) return iso;
+  const month = MONTHS[moment.month - 1];
+  if (month === undefined) return iso;
+  return `${moment.day} ${month} ${moment.year}`;
+}
+
+/**
+ * `3 Sep 2026, 9:30am`. An unparseable value is returned untouched rather than
+ * rendered as "Invalid Date": the durable text is at least true.
+ */
+export function formatMomentV1(
+  iso: string,
+  options: UiMomentOptionsV1 = {},
+): string {
+  const moment = momentParts(iso, options);
+  if (!moment) return iso;
+  return `${formatDayV1(iso, options)}, ${formatTimeOfDayV1(iso, options)}`;
+}
+
+/**
+ * A moment relative to now while that is the more useful reading, and the
+ * absolute one after. A run log is scanned for "did it just fire?"; a run from
+ * last month is scanned for which day it was.
+ */
+export function formatRelativeMomentV1(
+  iso: string,
+  options: UiMomentOptionsV1 & { now?: Date } = {},
+): string {
+  const parsed = Date.parse(iso);
+  if (!Number.isFinite(parsed)) return iso;
+  const now = (options.now ?? new Date()).getTime();
+  const elapsed = now - parsed;
+  if (elapsed < 0) return formatMomentV1(iso, options);
+  if (elapsed < 60_000) return "just now";
+  if (elapsed < 3_600_000) {
+    const minutes = Math.floor(elapsed / 60_000);
+    return `${minutes} min ago`;
+  }
+  if (elapsed < 86_400_000) {
+    const hours = Math.floor(elapsed / 3_600_000);
+    return `${hours} ${hours === 1 ? "hour" : "hours"} ago`;
+  }
+  return formatMomentV1(iso, options);
+}