@connextar/house 0.17.0 → 0.19.0

package/dist/whats-new/select.d.ts

@@ -0,0 +1,89 @@
+import { type ChangeType, type ChangelogRelease } from "../release/changelog.js";
+/**
+ * What a signed-in person is told about the releases since they last looked —
+ * worked out on the server, from the app's `CHANGELOG` and the one version it
+ * stores against them.
+ *
+ * Pure: no React, no clock unless one is passed, nothing read or written. The
+ * signed-in layout calls `whatsNew` and hands the answer to the client, which
+ * is why the answer holds the public wording and nothing else: a change marked
+ * `internal`, a release not yet reviewed, and the team's wording of anything
+ * the review reworded never leave the server.
+ */
+/** One change the dialog leads with, in the public's words. */
+export interface WhatsNewHighlight {
+    version: string;
+    /** ISO date of its release. */
+    date: string;
+    /** Its release's public headline. */
+    releaseTitle: string;
+    /** Its section's public heading ("Invoices"). */
+    heading: string;
+    type: ChangeType;
+    title: string;
+    text: string;
+    /** Its release's fragment id on the changelog page, `v1-4-0`. */
+    anchor: string;
+}
+export interface WhatsNewData {
+    /** The newest release in the changelog: what dismissing stores. */
+    latestVersion: string;
+    /** The version stored against the person, as read — null when there was none worth reading. */
+    since: string | null;
+    /** How many reviewed releases have come out since `since`. */
+    releaseCount: number;
+    /** The changes the dialog leads with, `changed` first, at most `maxItems`. */
+    highlights: WhatsNewHighlight[];
+    /** How many more would have qualified as highlights. */
+    moreCount: number;
+    /** The fragment id of the newest unseen public release, for "See everything in the changelog". */
+    anchor: string | null;
+    /** Open the dialog: something new or changed since they last looked, and long enough since they last did. */
+    shouldShow: boolean;
+    /** Nothing was stored (a new account, or a value that isn't a version): store `latestVersion` without a word. */
+    stampSilently: boolean;
+}
+export interface WhatsNewOptions {
+    /** The most highlights to return. Defaults to 5; the rest are counted in `moreCount`. */
+    maxItems?: number;
+    /**
+     * The types that can be highlights, in the order they are shown. Defaults to
+     * `changed` (someone may need to act), `new`, `improved` — a fix is the
+     * changelog's business, not a reason to interrupt someone.
+     */
+    highlightTypes?: readonly ChangeType[];
+    /** The types that open the dialog. Defaults to `new` and `changed`: improvements alone wait for the next one. */
+    showFor?: readonly ChangeType[];
+    /** Sections whose changes are never highlights, matched case-insensitively. Defaults to `DEFAULT_SKIP_HEADINGS`. */
+    skipHeadings?: readonly string[];
+    /**
+     * Days to wait after the stored version's release date before showing again.
+     * Defaults to 0. An app releasing several times a day sets 7: the date of the
+     * version someone last stored stands in for when they last saw the dialog, so
+     * no second column is needed — they stored the newest release there was.
+     */
+    minDaysBetween?: number;
+    /** The time to measure `minDaysBetween` against. Defaults to now. */
+    now?: Date | number;
+    /** The person's role, matched against `roles` on changes and sections. Without one, only changes for everyone. */
+    role?: string;
+}
+export declare const DEFAULT_SKIP_HEADINGS: readonly string[];
+export declare const DEFAULT_HIGHLIGHT_TYPES: readonly ChangeType[];
+export declare const DEFAULT_SHOW_FOR: readonly ChangeType[];
+export declare const WHATS_NEW_MAX_ITEMS = 5;
+/**
+ * What's new for someone who last stored `lastSeen`, or null when the
+ * changelog has no release to speak of.
+ *
+ * - Unseen means every release newer than `lastSeen` by version, so a stored
+ *   version the changelog no longer holds still works, and one newer than the
+ *   changelog (a rollback) has nothing unseen and stores nothing.
+ * - Only reviewed releases count, through the same public wording as
+ *   `publicRelease`, and without the generic "Behind the scenes" line — there is
+ *   no cap of five, as `publicChangelog` has, because a week of AltEd is twenty-five.
+ * - `lastSeen` missing or not a version: nothing shown, `stampSilently`, so a
+ *   new account isn't greeted by a hundred releases.
+ */
+export declare function whatsNew(changelog: readonly ChangelogRelease[], lastSeen: string | null | undefined, { maxItems, highlightTypes, showFor, skipHeadings, minDaysBetween, now, role, }?: WhatsNewOptions): WhatsNewData | null;
+//# sourceMappingURL=select.d.ts.map

package/dist/whats-new/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/whats-new/select.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAGjC;;;;;;;;;;GAUG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6GAA6G;IAC7G,UAAU,EAAE,OAAO,CAAC;IACpB,iHAAiH;IACjH,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,iHAAiH;IACjH,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,oHAAoH;IACpH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,kHAAkH;IAClH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAgD,CAAC;AACpG,eAAO,MAAM,uBAAuB,EAAE,SAAS,UAAU,EAAmC,CAAC;AAC7F,eAAO,MAAM,gBAAgB,EAAE,SAAS,UAAU,EAAuB,CAAC;AAC1E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAiBrC;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,EACE,QAA8B,EAC9B,cAAwC,EACxC,OAA0B,EAC1B,YAAoC,EACpC,cAAkB,EAClB,GAAG,EACH,IAAI,GACL,GAAE,eAAoB,GACtB,YAAY,GAAG,IAAI,CAkFrB"}

package/dist/whats-new/select.js

@@ -0,0 +1,117 @@
+import { isInternalChange, publicHeading, publicWording, releaseAnchor, } from "../release/changelog.js";
+import { compareVersions, isReleaseVersion } from "../release/version.js";
+export const DEFAULT_SKIP_HEADINGS = ["Fixes", "Bug fixes", "Behind the scenes"];
+export const DEFAULT_HIGHLIGHT_TYPES = ["changed", "new", "improved"];
+export const DEFAULT_SHOW_FOR = ["new", "changed"];
+export const WHATS_NEW_MAX_ITEMS = 5;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const forRole = (roles, role) => roles === undefined || (role !== undefined && roles.includes(role));
+/**
+ * What's new for someone who last stored `lastSeen`, or null when the
+ * changelog has no release to speak of.
+ *
+ * - Unseen means every release newer than `lastSeen` by version, so a stored
+ *   version the changelog no longer holds still works, and one newer than the
+ *   changelog (a rollback) has nothing unseen and stores nothing.
+ * - Only reviewed releases count, through the same public wording as
+ *   `publicRelease`, and without the generic "Behind the scenes" line — there is
+ *   no cap of five, as `publicChangelog` has, because a week of AltEd is twenty-five.
+ * - `lastSeen` missing or not a version: nothing shown, `stampSilently`, so a
+ *   new account isn't greeted by a hundred releases.
+ */
+export function whatsNew(changelog, lastSeen, { maxItems = WHATS_NEW_MAX_ITEMS, highlightTypes = DEFAULT_HIGHLIGHT_TYPES, showFor = DEFAULT_SHOW_FOR, skipHeadings = DEFAULT_SKIP_HEADINGS, minDaysBetween = 0, now, role, } = {}) {
+    const releases = changelog
+        .filter((release) => isReleaseVersion(release.version))
+        .sort((a, b) => compareVersions(b.version, a.version));
+    const newest = releases[0];
+    if (!newest)
+        return null;
+    const stored = typeof lastSeen === "string" ? lastSeen.trim() : "";
+    const nothing = {
+        latestVersion: newest.version,
+        since: null,
+        releaseCount: 0,
+        highlights: [],
+        moreCount: 0,
+        anchor: null,
+        shouldShow: false,
+        stampSilently: false,
+    };
+    if (!isReleaseVersion(stored))
+        return { ...nothing, stampSilently: true };
+    const unseen = releases.filter((release) => release.public && compareVersions(release.version, stored) > 0);
+    const skipped = new Set(skipHeadings.map((heading) => heading.trim().toLowerCase()));
+    const candidates = [];
+    unseen.forEach((release, releaseIndex) => {
+        const releaseTitle = release.public?.title ?? release.title;
+        // Sections sharing a public heading are one section on the public page, placed where the first one was.
+        const headings = release.sections.map(publicHeading);
+        release.sections.forEach((section, part) => {
+            const heading = publicHeading(section);
+            section.changes.forEach((change, changeIndex) => {
+                if (isInternalChange(change, section))
+                    return;
+                if (!forRole(section.roles, role) || !forRole(change.roles, role))
+                    return;
+                if (change.highlight === false)
+                    return;
+                const forced = change.highlight === true;
+                if (!forced && (!highlightTypes.includes(change.type) || skipped.has(heading.trim().toLowerCase())))
+                    return;
+                const rank = highlightTypes.indexOf(change.type);
+                candidates.push({
+                    highlight: {
+                        version: release.version,
+                        date: release.date,
+                        releaseTitle,
+                        heading,
+                        type: change.type,
+                        ...publicWording(change),
+                        anchor: releaseAnchor(release.version),
+                    },
+                    forced,
+                    rank: rank === -1 ? highlightTypes.length : rank,
+                    release: releaseIndex,
+                    section: headings.indexOf(heading),
+                    part,
+                    change: changeIndex,
+                });
+            });
+        });
+    });
+    const shown = (a, b) => a.rank - b.rank || a.release - b.release || a.section - b.section || a.part - b.part || a.change - b.change;
+    // A forced highlight is guaranteed a place; the rest are taken in the order they are shown.
+    const kept = new Set([...candidates]
+        .sort((a, b) => Number(b.forced) - Number(a.forced) || shown(a, b))
+        .slice(0, Math.max(0, Math.floor(maxItems))));
+    const highlights = candidates
+        .filter((candidate) => kept.has(candidate))
+        .sort(shown)
+        .map((candidate) => candidate.highlight);
+    const worthShowing = candidates.some((candidate) => candidate.forced || showFor.includes(candidate.highlight.type));
+    return {
+        ...nothing,
+        since: stored,
+        releaseCount: unseen.length,
+        highlights,
+        moreCount: candidates.length - highlights.length,
+        anchor: unseen[0] ? releaseAnchor(unseen[0].version) : null,
+        shouldShow: worthShowing && longEnoughSince(releases, stored, minDaysBetween, now),
+    };
+}
+/**
+ * Whether `minDaysBetween` days have passed since the stored version's release
+ * date. A version the changelog doesn't hold, or a date that won't parse, has
+ * nothing to wait for.
+ */
+function longEnoughSince(releases, stored, minDaysBetween, now) {
+    if (!(minDaysBetween > 0))
+        return true;
+    const seen = releases.find((release) => release.version === stored);
+    const released = seen ? Date.parse(`${seen.date}T00:00:00Z`) : Number.NaN;
+    if (Number.isNaN(released))
+        return true;
+    const at = now === undefined ? Date.now() : typeof now === "number" ? now : now.getTime();
+    return at - released >= minDaysBetween * DAY_MS;
+}
+//# sourceMappingURL=select.js.map

package/dist/whats-new/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../src/whats-new/select.ts"],"names":[],"mappings":"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"}

package/dist/whats-new/use-whats-new.d.ts

@@ -0,0 +1,36 @@
+import type { WhatsNewData } from "./select.js";
+export interface UseWhatsNewOptions {
+    /** `whatsNew(...)` from the signed-in layout, or null for nobody (signed out, or not in the audience). */
+    initial: WhatsNewData | null;
+    /**
+     * Store the version the person has now seen — the app's `POST /api/whats-new/seen`.
+     * `false` or a throw means it did not take. Use `keepalive` on the request:
+     * following the changelog link may unload the page while it is in flight.
+     */
+    markSeen: (version: string) => Promise<boolean>;
+    /** Somebody viewing as this person: never opens, never stores. */
+    readOnly?: boolean;
+}
+export interface WhatsNew {
+    open: boolean;
+    /** For the dialog's `onOpenChange`. Closing it any way — Escape, a click outside — counts as seen. */
+    setOpen: (open: boolean) => void;
+    data: WhatsNewData | null;
+    /** Close at once and store `latestVersion`. */
+    dismiss: () => void;
+    /** For the changelog link: following it counts as seen. */
+    onChangelogClick: () => void;
+}
+/**
+ * When the "what's new" dialog opens, and what closing it stores.
+ *
+ * It opens once, on mount, when the server said `shouldShow` — never while
+ * someone is viewing as the person. A new account (`stampSilently`) stores the
+ * newest version without opening, so its first visit after the next release
+ * says only what came out since it arrived. Closing, however it's done, closes
+ * at once and stores the newest version; if that fails the person is told
+ * through the app's `ActionFeedbackProvider`, and the dialog stays closed for
+ * this visit rather than coming back to ask again.
+ */
+export declare function useWhatsNew({ initial, markSeen, readOnly }: UseWhatsNewOptions): WhatsNew;
+//# sourceMappingURL=use-whats-new.d.ts.map

package/dist/whats-new/use-whats-new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-whats-new.d.ts","sourceRoot":"","sources":["../../src/whats-new/use-whats-new.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,0GAA0G;IAC1G,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,sGAAsG;IACtG,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAgB,EAAE,EAAE,kBAAkB,GAAG,QAAQ,CAkEjG"}

package/dist/whats-new/use-whats-new.js

@@ -0,0 +1,81 @@
+"use client";
+import * as React from "react";
+import { useActionReporter } from "../ux/feedback.js";
+/**
+ * When the "what's new" dialog opens, and what closing it stores.
+ *
+ * It opens once, on mount, when the server said `shouldShow` — never while
+ * someone is viewing as the person. A new account (`stampSilently`) stores the
+ * newest version without opening, so its first visit after the next release
+ * says only what came out since it arrived. Closing, however it's done, closes
+ * at once and stores the newest version; if that fails the person is told
+ * through the app's `ActionFeedbackProvider`, and the dialog stays closed for
+ * this visit rather than coming back to ask again.
+ */
+export function useWhatsNew({ initial, markSeen, readOnly = false }) {
+    const report = useActionReporter();
+    const [open, setOpenState] = React.useState(false);
+    const isOpen = React.useRef(false);
+    const started = React.useRef(false);
+    const stored = React.useRef(false);
+    // Read through a ref so the callbacks below keep one identity across renders.
+    const latest = React.useRef({ initial, markSeen, readOnly, report });
+    React.useEffect(() => {
+        latest.current = { initial, markSeen, readOnly, report };
+    });
+    const store = React.useCallback(async (quietly) => {
+        const { initial: data, markSeen: save, readOnly: viewingAs, report: tell } = latest.current;
+        if (!data || viewingAs || stored.current)
+            return;
+        stored.current = true;
+        let saved = false;
+        try {
+            saved = await save(data.latestVersion);
+        }
+        catch {
+            saved = false;
+        }
+        if (saved)
+            return;
+        // Not stored: the next visit may ask again, which is the honest outcome of a failed save.
+        stored.current = false;
+        if (quietly)
+            return;
+        tell({
+            tone: "error",
+            title: "Couldn't save that you've seen what's new",
+            description: "It may show again next time you visit.",
+        });
+    }, []);
+    const show = React.useCallback((next) => {
+        isOpen.current = next;
+        setOpenState(next);
+    }, []);
+    // Once, the first time there is an answer: a later render with fresh data must not reopen what was just closed.
+    React.useEffect(() => {
+        if (started.current || !initial)
+            return;
+        started.current = true;
+        if (readOnly)
+            return;
+        if (initial.stampSilently) {
+            void store(true);
+            return;
+        }
+        if (initial.shouldShow)
+            show(true);
+    }, [initial, readOnly, store, show]);
+    const dismiss = React.useCallback(() => {
+        show(false);
+        void store(false);
+    }, [store, show]);
+    const setOpen = React.useCallback((next) => {
+        if (next)
+            show(true);
+        // Closing what is open is a dismissal; "closing" what never opened stores nothing.
+        else if (isOpen.current)
+            dismiss();
+    }, [dismiss, show]);
+    return { open, setOpen, data: initial, dismiss, onChangelogClick: dismiss };
+}
+//# sourceMappingURL=use-whats-new.js.map

package/dist/whats-new/use-whats-new.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-whats-new.js","sourceRoot":"","sources":["../../src/whats-new/use-whats-new.ts"],"names":[],"mappings":"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"}

package/docs/ReleaseProcess.md

@@ -164,6 +164,18 @@ The public page adds one line — **Behind the scenes · Reliability and securit
 
 The release guard checks it: `publicChangelogProblems(CHANGELOG)` must be empty, and it fails until the newest five releases each have their review.
 
+### The "what's new" dialog
+
+Signed-in people hear about a release from the dialog in `@connextar/house/whats-new`, which picks a few public changes — `changed` first, then `new`, then `improved`; never a fix, nothing under **Fixes** or **Behind the scenes**. Two optional fields steer it, and neither touches either changelog:
+
+| Field                                | Use it for                                                                                                                            |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `highlight: true` on a change        | A change the dialog must lead with whatever its type or heading — the fix everyone asked for. Never on an internal change             |
+| `highlight: false` on a change       | A change that is real but not worth interrupting anyone for                                                                           |
+| `roles: [...]` on a change / section | Who it is for, by the app's own role names (`["guardian"]`). Left off means everyone; the dialog shows a scoped change to no one else |
+
+`releaseHistoryProblems` checks both: a boolean `highlight`, never on an internal change, and a `roles` list of distinct, non-blank names.
+
 ---
 
 ## 4. The pieces in code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -42,6 +42,22 @@
       "types": "./dist/auth/step-up-client-index.d.ts",
       "default": "./dist/auth/step-up-client-index.js"
     },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./admin/second-factor": {
+      "types": "./dist/admin/second-factor-index.d.ts",
+      "default": "./dist/admin/second-factor-index.js"
+    },
+    "./admin/client": {
+      "types": "./dist/admin/client-index.d.ts",
+      "default": "./dist/admin/client-index.js"
+    },
+    "./admin/testing": {
+      "types": "./dist/admin/testing-index.d.ts",
+      "default": "./dist/admin/testing-index.js"
+    },
     "./account": {
       "types": "./dist/account/index.d.ts",
       "default": "./dist/account/index.js"
@@ -62,6 +78,10 @@
       "types": "./dist/guides/index.d.ts",
       "default": "./dist/guides/index.js"
     },
+    "./health": {
+      "types": "./dist/health/index.d.ts",
+      "default": "./dist/health/index.js"
+    },
     "./trail": {
       "types": "./dist/trail/index.d.ts",
       "default": "./dist/trail/index.js"
@@ -102,6 +122,10 @@
       "types": "./dist/setup-guide/index.d.ts",
       "default": "./dist/setup-guide/index.js"
     },
+    "./whats-new": {
+      "types": "./dist/whats-new/index.d.ts",
+      "default": "./dist/whats-new/index.js"
+    },
     "./editor": {
       "types": "./dist/editor/index.d.ts",
       "default": "./dist/editor/index.js"