@sjolystinnovation/app-kit 1.0.2 → 1.1.0

package/README.md

@@ -165,7 +165,7 @@ The config every app shares, for `next.config.ts`. It imports nothing but Next's
 loads it with no build step.
 
 `defineAppConfig(options, extra?)` gives the standalone build, app-kit in `transpilePackages`, no
-`X-Powered-By`, an `expireTime` of five minutes, image qualities 75 and 100, the incremental cache
+`X-Powered-By`, an `expireTime` of a year, image qualities 75 and 100, the incremental cache
 in memory, and the security headers on every page. It merges `extra` over that config. It combines
 `transpilePackages`, `images`, `experimental`, `headers`, and `rewrites` instead of replacing them.
 
@@ -191,9 +191,18 @@ export default defineAppConfig({
 | `frameSrc`, `objectSrc` | `string[]` | Sources for those directives. Both default to `'none'`. |
 | `pathHeaders` | `{ source, headers }[]` | Headers for particular paths, such as a file download. They come after the page headers and replace a page header of the same name. Every path keeps the rest. |
 | `permissionsPolicy` | `string` | Replaces `camera=(), microphone=(), geolocation=()`. |
-| `expireTime` | `number` | The seconds a cache may serve a stale page. Defaults to 300. Next's default is a year. |
+| `expireTime` | `number` | The seconds a cached page may be served after it was last generated. Defaults to a year, Next's default. |
 | `isrFlushToDisk` | `boolean` | Whether to write revalidated pages to disk. Defaults to `false`, for a read-only root filesystem. |
 
+Until a page reaches its `expireTime`, Next serves the cached copy at once and regenerates it in the
+background when it is stale. If the regeneration fails, for example because the API is down, Next
+keeps the last good copy and tries again on a later request. Once the page is past its
+`expireTime`, Next regenerates it while the visitor waits, and a page whose `publicGet` throws then
+answers 500. The long default keeps legal pages, the sitemap, and other pages with few visitors up
+through an API outage. A page that was never generated still answers 500 while the API is down,
+rather than being cached empty. Set a shorter `expireTime` only if a page must never be served more
+than that old, and accept the 500.
+
 Scripts allow `'unsafe-inline'`, since a nonce would make every statically rendered page dynamic.
 The package also exports the `AppConfigOptions` and `CspOptions` types.
 
@@ -1189,19 +1198,31 @@ it plots and its label. It takes the next color of a built-in palette of five un
 The stats page card for the transactional email, from the `MapAppKitEmailStats` endpoint of
 SjolystInnovation.AppKit.Email through `createEmailStatsService`. It shows the emails sent,
 delivered, bounced, and blocked or reported as spam, for the last `days` days. Hard and soft bounces
-count together. The title names the days the API answered for. While the stats load, the panel shows
-`loading`. When they cannot load, such as when Brevo does not answer, it shows `unavailable` without
-a toast. The panel loads again when `days` changes, not when an inline `service` does.
+count together, and so do blocked emails and spam reports. With `separateCounts`, each count the API
+returns gets its own row: hard bounces, soft bounces, blocked, spam reports, and invalid addresses.
+The title names the days the API answered for. While the stats load, the panel shows `loading`.
+When they cannot load, such as when Brevo does not answer, it shows `unavailable` without a toast.
+The panel loads again when the days change, not when an inline `service` does, and shows `loading`
+until the new days answer.
+
+Give `periods` to let an admin pick the days with a row of buttons next to the title. The panel then
+keeps the picked days itself, starting on `days`. Give `onDaysChange` as well to keep the days in the
+app, which then passes the picked days back as `days`.
 
 ```tsx
 <EmailStatsPanel service={createEmailStatsService(api)} strings={{ title: "E-post (siste {days} dager)" }} />
+
+<EmailStatsPanel service={createEmailStatsService(api)} periods={[7, 30, 90]} separateCounts />
 ```
 
 | Prop | Type | Description |
 | --- | --- | --- |
 | `service` | `{ get(days?) }` | The email stats call, such as `createEmailStatsService(api)`. |
-| `days` | `number` | How many days back the stats go. Defaults to 30. |
-| `strings` | `TextOverrides<EmailStatsPanelStrings>` | `title`, where `{days}` becomes the days, and `sent`, `delivered`, `bounces`, `blocked`, `loading`, and `unavailable`. |
+| `days` | `number` | How many days back the stats go. Defaults to 30. With `periods` and no `onDaysChange`, the days the picker starts on. |
+| `periods` | `readonly number[]` | The days an admin can pick between, such as `[7, 30, 90]`. Without it, there is no picker. |
+| `onDaysChange` | `(days: number) => void` | Called with the picked days. Give it to control `days` from the app. |
+| `separateCounts` | `boolean` | Shows each count on its own row. Defaults to `false`. |
+| `strings` | `TextOverrides<EmailStatsPanelStrings>` | `title` and `periodOption`, where `{days}` becomes the days, `sent`, `delivered`, `bounces`, `blocked`, `loading`, and `unavailable`, the rows of `separateCounts` in `hardBounces`, `softBounces`, `blockedOnly`, `spamReports`, and `invalid`, and `period`, the picker's name for screen readers. |
 | `className` | `string` | Replaces the card's border and spacing, `rounded-2xl border border-admin-border p-5`, such as to sit in the app's own card. |
 
 ## `@sjolystinnovation/app-kit/branding`
@@ -1768,7 +1789,7 @@ The components draw every color, corner radius, and label size from theme variab
 | `--font-weight-auth-link` | semibold |
 | `--color-admin-title` | gray 900, the title of `AdminShell` |
 | `--color-admin-border` | gray 200, the line under the tabs |
-| `--color-admin-tab`, `-hover` | gray 500 and gray 900 |
+| `--color-admin-tab`, `-hover` | gray 500 and gray 900, also the periods `EmailStatsPanel` has not picked |
 | `--color-admin-tab-active` | gray 900 |
 | `--color-admin-tab-indicator` | `var(--color-primary)`, the line under the active tab |
 | `--color-chart-grid` | gray 200, the scale lines of `StatHistoryChart` |
@@ -1776,7 +1797,7 @@ The components draw every color, corner radius, and label size from theme variab
 | `--color-admin-stat-label` | gray 500, the labels and the waiting text of `EmailStatsPanel` |
 | `--color-admin-stat-value` | gray 700, the numbers of `EmailStatsPanel` |
 | `--radius-button` | `var(--radius-lg)` |
-| `--color-button-primary-bg` | `var(--color-primary)` |
+| `--color-button-primary-bg` | `var(--color-primary)`, also the period `EmailStatsPanel` has picked |
 | `--color-button-primary-text` | `var(--color-primary-foreground)` |
 | `--color-button-secondary-border` | gray 300 |
 | `--color-button-secondary-text` | gray 700 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",

package/src/admin/EmailStatsPanel.tsx

@@ -9,59 +9,123 @@ import { defaultEmailStatsPanelStrings, type EmailStatsPanelStrings } from "./em
 export interface EmailStatsPanelProps {
   /** The email stats call, such as `createEmailStatsService(api)`. */
   service: { get: (days?: number) => Promise<EmailStats> };
-  /** How many days back the stats go. Defaults to 30. */
+  /**
+   * How many days back the stats go. Defaults to 30. With `onDaysChange` the panel shows these days
+   * and leaves the choice to the app. Without it, this is where the picker starts.
+   */
   days?: number | undefined;
+  /** The days an admin can pick between, such as `[7, 30, 90]`. Without it, the panel has no picker. */
+  periods?: readonly number[] | undefined;
+  /** Called with the days an admin picks. Give it to control `days` from the app. */
+  onDaysChange?: ((days: number) => void) | undefined;
+  /** Shows hard and soft bounces, blocked, spam reports, and invalid addresses on their own rows. */
+  separateCounts?: boolean | undefined;
   strings?: TextOverrides<EmailStatsPanelStrings> | undefined;
   /** The classes that replace the card's border and spacing, such as when the panel sits in the app's own card. */
   className?: string | undefined;
 }
 
-type State = { status: "loading" } | { status: "failed" } | { status: "loaded"; stats: EmailStats };
+type State = { days: number } & ({ status: "failed" } | { status: "loaded"; stats: EmailStats });
 
 /**
  * The admin card for the transactional email of the last days, from SjolystInnovation.AppKit.Email's
- * stats endpoint: sent, delivered, bounces, and blocked or reported as spam. It says the stats are
- * unavailable when they cannot load, without a toast, so the rest of the stats page stays calm.
+ * stats endpoint: sent, delivered, bounces, and blocked or reported as spam, or each count on its own.
+ * It says the stats are unavailable when they cannot load, without a toast, so the rest of the stats
+ * page stays calm.
  */
-export function EmailStatsPanel({ service, days = 30, strings, className = "rounded-2xl border border-admin-border p-5" }: EmailStatsPanelProps) {
+export function EmailStatsPanel({
+  service,
+  days = 30,
+  periods,
+  onDaysChange,
+  separateCounts = false,
+  strings,
+  className = "rounded-2xl border border-admin-border p-5",
+}: EmailStatsPanelProps) {
   const text = withDefaults(defaultEmailStatsPanelStrings, strings);
-  const [state, setState] = useState<State>({ status: "loading" });
+  // The days picked in the panel itself, until the app gives other days. A panel with
+  // `onDaysChange` never picks on its own.
+  const [picked, setPicked] = useState<{ from: number; days: number } | null>(null);
+  const selected = picked?.from === days ? picked.days : days;
+  const hasPicker = periods !== undefined && periods.length > 0;
+  const [state, setState] = useState<State | null>(null);
   // The latest service, so an inline one does not load the stats again on every render.
   const serviceRef = useRef(service);
   useEffect(() => {
     serviceRef.current = service;
   }, [service]);
 
-  // An answer for an earlier `days` is ignored, so a slow one cannot replace the newer stats.
+  // An answer for earlier days is ignored, so a slow one cannot replace the newer stats.
   useEffect(() => {
     let replaced = false;
     serviceRef.current
-      .get(days)
+      .get(selected)
       .then((stats) => {
-        if (!replaced) setState({ status: "loaded", stats });
+        if (!replaced) setState({ days: selected, status: "loaded", stats });
       })
       .catch(() => {
-        if (!replaced) setState({ status: "failed" });
+        if (!replaced) setState({ days: selected, status: "failed" });
       });
     return () => {
       replaced = true;
     };
-  }, [days]);
+  }, [selected]);
 
-  const shownDays = state.status === "loaded" ? state.stats.days : days;
-  const rows = (stats: EmailStats) => [
-    { label: text.sent, value: stats.requests },
-    { label: text.delivered, value: stats.delivered },
-    { label: text.bounces, value: stats.hardBounces + stats.softBounces },
-    { label: text.blocked, value: stats.blocked + stats.spamReports },
-  ];
+  // Stats for other days than the selected ones count as loading.
+  const current = state?.days === selected ? state : null;
+  const shownDays = current?.status === "loaded" ? current.stats.days : selected;
+  const rows = (stats: EmailStats) =>
+    separateCounts
+      ? [
+          { label: text.sent, value: stats.requests },
+          { label: text.delivered, value: stats.delivered },
+          { label: text.hardBounces, value: stats.hardBounces },
+          { label: text.softBounces, value: stats.softBounces },
+          { label: text.blockedOnly, value: stats.blocked },
+          { label: text.spamReports, value: stats.spamReports },
+          { label: text.invalid, value: stats.invalid },
+        ]
+      : [
+          { label: text.sent, value: stats.requests },
+          { label: text.delivered, value: stats.delivered },
+          { label: text.bounces, value: stats.hardBounces + stats.softBounces },
+          { label: text.blocked, value: stats.blocked + stats.spamReports },
+        ];
+
+  const pick = (next: number) => {
+    if (onDaysChange) onDaysChange(next);
+    else setPicked({ from: days, days: next });
+  };
+
+  const title = <h2 className={`font-bold text-admin-title${hasPicker ? "" : " mb-3"}`}>{text.title.replaceAll("{days}", String(shownDays))}</h2>;
 
   return (
     <section className={className}>
-      <h2 className="font-bold text-admin-title mb-3">{text.title.replaceAll("{days}", String(shownDays))}</h2>
-      {state.status === "loaded" ? (
+      {hasPicker ? (
+        <div className="mb-3 flex flex-wrap items-center justify-between gap-2">
+          {title}
+          <div role="group" aria-label={text.period} className="flex gap-1">
+            {periods.map((option) => (
+              <button
+                key={option}
+                type="button"
+                onClick={() => pick(option)}
+                aria-pressed={option === selected}
+                className={`rounded-button px-2.5 py-1 text-xs transition-colors ${
+                  option === selected ? "bg-button-primary-bg text-button-primary-text" : "text-admin-tab hover:text-admin-tab-hover"
+                }`}
+              >
+                {text.periodOption.replaceAll("{days}", String(option))}
+              </button>
+            ))}
+          </div>
+        </div>
+      ) : (
+        title
+      )}
+      {current?.status === "loaded" ? (
         <dl className="space-y-1.5 text-sm">
-          {rows(state.stats).map((row) => (
+          {rows(current.stats).map((row) => (
             <div key={row.label} className="flex justify-between">
               <dt className="text-admin-stat-label">{row.label}</dt>
               <dd className="tabular-nums text-admin-stat-value">{row.value}</dd>
@@ -69,7 +133,7 @@ export function EmailStatsPanel({ service, days = 30, strings, className = "roun
           ))}
         </dl>
       ) : (
-        <p className="text-sm text-admin-stat-label">{state.status === "failed" ? text.unavailable : text.loading}</p>
+        <p className="text-sm text-admin-stat-label">{current?.status === "failed" ? text.unavailable : text.loading}</p>
       )}
     </section>
   );

package/src/admin/emailStatsPanelStrings.ts

@@ -2,7 +2,7 @@
 
 /**
  * The email stats panel's text. Pass the app's own language. The defaults are English. The panel
- * fills in `{days}` in `title`.
+ * fills in `{days}` in `title` and `periodOption`.
  */
 export interface EmailStatsPanelStrings {
   title: string;
@@ -13,6 +13,18 @@ export interface EmailStatsPanelStrings {
   bounces: string;
   /** Blocked emails and spam reports together. */
   blocked: string;
+  /** The rows of `separateCounts`, each count on its own. */
+  hardBounces: string;
+  softBounces: string;
+  /** Blocked emails without spam reports. */
+  blockedOnly: string;
+  spamReports: string;
+  /** Emails to an address that does not exist or cannot be used. */
+  invalid: string;
+  /** The name of the period picker, for screen readers. */
+  period: string;
+  /** Each choice in the period picker, such as `7 days`. */
+  periodOption: string;
   loading: string;
   /** The text shown when the stats could not load, such as when Brevo does not answer. */
   unavailable: string;
@@ -24,6 +36,13 @@ export const defaultEmailStatsPanelStrings: EmailStatsPanelStrings = {
   delivered: "Delivered",
   bounces: "Bounces",
   blocked: "Blocked / spam",
+  hardBounces: "Hard bounces",
+  softBounces: "Soft bounces",
+  blockedOnly: "Blocked",
+  spamReports: "Spam reports",
+  invalid: "Invalid",
+  period: "Period",
+  periodOption: "{days} days",
   loading: "Loading…",
   unavailable: "Unavailable.",
 };

package/src/locales/nb.ts

@@ -240,6 +240,13 @@ export const nbEmailStatsPanelStrings: EmailStatsPanelStrings = {
   delivered: "Levert",
   bounces: "Returnert",
   blocked: "Blokkert eller spam",
+  hardBounces: "Returnert, permanent feil",
+  softBounces: "Returnert, midlertidig feil",
+  blockedOnly: "Blokkert",
+  spamReports: "Meldt som spam",
+  invalid: "Ugyldig adresse",
+  period: "Periode",
+  periodOption: "{days} dager",
   loading: "Laster…",
   unavailable: "E-poststatistikken er ikke tilgjengelig akkurat nå. Prøv igjen senere.",
 };

package/src/next-config/index.ts

@@ -3,6 +3,8 @@ import { contentImagesRewrite, securityHeaders, type CspOptions, type Header } f
 
 export type { CspOptions } from "./headers";
 
+const ONE_YEAR_SECONDS = 31_536_000;
+
 /** Options for `defineAppConfig`. */
 export interface AppConfigOptions extends CspOptions {
   /**
@@ -18,9 +20,10 @@ export interface AppConfigOptions extends CspOptions {
   /** A Permissions-Policy that replaces the default one. */
   permissionsPolicy?: string | undefined;
   /**
-   * The number of seconds a cache may go on serving a page after it goes stale. Next's default is a
-   * year, long enough for a browser to hand back an old page and fetch the current one behind it.
-   * Defaults to `300`, matching the client router cache's stale time.
+   * The number of seconds a cached page may go on being served after it was last generated. Defaults
+   * to a year, Next's own default. Until then a stale page is served at once and regenerated in the
+   * background, and a failed regeneration keeps the last good page. Past it, the page is regenerated
+   * while the visitor waits, so a page that reads a down API answers 500 instead.
    */
   expireTime?: number | undefined;
   /**
@@ -43,7 +46,7 @@ export function defineAppConfig(o: AppConfigOptions, extra: NextConfig = {}): Ne
   return {
     output: "standalone",
     poweredByHeader: false,
-    expireTime: o.expireTime ?? 300,
+    expireTime: o.expireTime ?? ONE_YEAR_SECONDS,
     ...rest,
     transpilePackages: [...new Set(["@sjolystinnovation/app-kit", ...(transpilePackages ?? [])])],
     images: { qualities: [75, 100], ...images },