@eifi1/ui-kit 0.30.0 → 0.31.1

package/src/components/settings-fields.tsx

@@ -1,6 +1,8 @@
 import type { ReactNode } from "react";
 import { Select } from "./ui";
 import type { SelectProps } from "./ui";
+import { ToggleGroup } from "./toggle-group";
+import type { ToggleGroupBaseProps } from "./toggle-group";
 import type { ThemePreference } from "../theme/theme-store";
 
 /**
@@ -20,6 +22,8 @@ import type { ThemePreference } from "../theme/theme-store";
  */
 export interface ThemeSettingProps
   extends Omit<SelectProps, "value" | "onChange" | "children"> {
+  /** The `Select` (default). See {@link ThemeSettingToggleProps} for `"toggle"`. */
+  variant?: "select";
   value: ThemePreference;
   onChange: (value: ThemePreference) => void;
   label: ReactNode;
@@ -28,7 +32,52 @@ export interface ThemeSettingProps
   id?: string;
 }
 
-export function ThemeSetting({ value, onChange, label, optionLabels, id, ...rest }: ThemeSettingProps) {
+/**
+ * `variant="toggle"` (0.31.0, docs/settings-harmonization.md §2.8): the three choices as
+ * one segmented control instead of a select — system, light and dark side by side, the
+ * choice visible without opening anything, in every app (keksdose offered light and dark
+ * only; its store already knew "system"). A {@link ToggleGroup}'s props pass through —
+ * `labelPlacement`, `disabledReason`, `commit`, `size` — minus the options and the value,
+ * which this owns.
+ *
+ * Bind it to the PREFERENCE (`"system"` included), never to the resolved mode: on a
+ * system-dark device a control bound to the mode shows "dark" and cannot say "follow the
+ * system" (keksdose's control, §8).
+ */
+export interface ThemeSettingToggleProps
+  extends Omit<ToggleGroupBaseProps<ThemePreference>, "options" | "label" | "ariaLabel"> {
+  variant: "toggle";
+  value: ThemePreference;
+  onChange: (value: ThemePreference) => void;
+  /**
+   * Names the group: the field's label, or the label above it (`labelPlacement`). Leave
+   * it out inside a card already titled "Theme" and name the group with `aria-label` or
+   * `aria-labelledby` instead, so the card does not say "Theme" twice.
+   */
+  label?: ReactNode;
+  /** Translated option labels. */
+  optionLabels: { system: string; light: string; dark: string };
+  id?: string;
+}
+
+export function ThemeSetting(props: ThemeSettingProps | ThemeSettingToggleProps) {
+  if (props.variant === "toggle") {
+    const { variant: _variant, value, onChange, label, optionLabels, ...rest } = props;
+    return (
+      <ToggleGroup<ThemePreference>
+        {...rest}
+        label={label}
+        value={value}
+        onChange={onChange}
+        options={[
+          { value: "system", label: optionLabels.system },
+          { value: "light", label: optionLabels.light },
+          { value: "dark", label: optionLabels.dark },
+        ]}
+      />
+    );
+  }
+  const { variant: _variant, value, onChange, label, optionLabels, id, ...rest } = props;
   return (
     <Select
       {...rest}

package/src/demo/demo-banner.tsx

@@ -0,0 +1,159 @@
+import { useState } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { ChevronDown, ChevronUp, Timer } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { AlertBanner } from "../components/alert-banner";
+import { Button, IconButton } from "../components/ui";
+import { useAccessAction } from "../landing/access";
+import type { AccessChoice } from "../landing/access";
+import { useLandingLabels } from "../landing/landing-labels";
+import type { LandingLabels } from "../landing/landing-labels";
+import { useDemoCountdown } from "./demo-countdown";
+import type { DemoCountdown, DemoExpiry } from "./demo-countdown";
+import { useDemoLabels } from "./demo-labels";
+import type { DemoLabels } from "./demo-labels";
+import type { DemoModel } from "./demo-session";
+
+/** The default `sessionStorage` key of the collapsed state. */
+const COLLAPSE_KEY = "kit.demoBanner.collapsed";
+
+/** `sessionStorage`, guarded like `lib/safe-storage`'s `localStorage`: blocked storage
+ *  reads as "not set" and writes nothing. */
+function readSession(key: string): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeSession(key: string, value: string | null): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (value === null) window.sessionStorage.removeItem(key);
+    else window.sessionStorage.setItem(key, value);
+  } catch {
+    // storage blocked: the banner just opens again next time
+  }
+}
+
+/** "Demo · 23 h 12 min left", "Demo · 50 min left", the end, or plain "Demo". */
+function timeText(countdown: DemoCountdown, labels: DemoLabels): string {
+  if (countdown.minutesLeft === null) return labels.badge;
+  if (countdown.ended) return labels.endedTitle;
+  return countdown.lastHour
+    ? labels.minutesLeft(countdown.minutes)
+    : labels.hoursLeft(countdown.hours, countdown.minutes);
+}
+
+export interface DemoBannerProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "onClick"> {
+  /** The demo's end: `expires_at` from the `TokenResponse`, or `demo_expires_at` from
+   *  `/auth/me` (§5.3). */
+  expiresAt: DemoExpiry | null | undefined;
+  /** Which line the banner says about the data (§2.3). */
+  model: DemoModel;
+  /** "Request access". */
+  access: AccessChoice;
+  /** "Sign in" — let through for a demo session by `RedirectIfAuthed allowDemo`. Default
+   *  `/login`. */
+  signInHref?: string;
+  /** The countdown reached zero: clear the session and replace to `/demo/ended` (§5.5). */
+  onEnded?: () => void;
+  /** Where the collapsed state is kept for the tab's session. Default
+   *  `kit.demoBanner.collapsed`. */
+  collapseKey?: string;
+  /** The clock, for tests and previews. Default `Date.now`. Keep it stable. */
+  now?: () => number;
+  labels?: Partial<DemoLabels>;
+  /** The access words (`landing` namespace) for this instance. */
+  landingLabels?: Partial<LandingLabels>;
+}
+
+/**
+ * The demo's strip under the top bar, on every page of a demo session
+ * (docs/landing-demo-harmonization.md §5.4) — a kit `AlertBanner` strip:
+ *
+ * - the time left, "Demo · 23 h 12 min left" — minutes only in the last hour, and the
+ *   warning tone in the last ten minutes (`useDemoCountdown`);
+ * - one line on the model: R "You're looking at sample data. Changes aren't possible.",
+ *   S "Your own work is deleted when the demo ends.";
+ * - "Request access" (the mail) and "Sign in".
+ *
+ * It collapses to the countdown alone, for the tab's session (`sessionStorage`) — never
+ * hidden for good: it is a live state, like keksdose's preview banner, which a demo user
+ * gets instead of. At zero it calls `onEnded`.
+ *
+ * The countdown is no live region: a sentence read out every minute would drown the
+ * page. A screen-reader user meets it at the top of the page, and the end page says
+ * the rest.
+ */
+export function DemoBanner({
+  expiresAt,
+  model,
+  access,
+  signInHref = "/login",
+  onEnded,
+  collapseKey = COLLAPSE_KEY,
+  now,
+  labels: labelsProp,
+  landingLabels,
+  className,
+  ...rest
+}: DemoBannerProps) {
+  const labels = useDemoLabels(labelsProp);
+  const landing = useLandingLabels(landingLabels);
+  const accessLink = useAccessAction(access, landingLabels);
+  const countdown = useDemoCountdown(expiresAt, { now, onEnded });
+  const [collapsed, setCollapsed] = useState(() => readSession(collapseKey) === "1");
+
+  const toggle = () => {
+    const next = !collapsed;
+    setCollapsed(next);
+    writeSession(collapseKey, next ? "1" : null);
+  };
+
+  return (
+    <AlertBanner
+      {...rest}
+      variant="strip"
+      size="sm"
+      tone={countdown.warning || countdown.ended ? "warning" : "info"}
+      icon={<Timer />}
+      data-demo-model={model}
+      className={cn("sm:text-sm", className)}
+      action={
+        <>
+          {!collapsed && (
+            <>
+              <Button href={accessLink.href} variant="brand" size="sm">
+                {accessLink.label}
+              </Button>
+              <Button href={signInHref} variant="secondary" size="sm">
+                {landing.signIn}
+              </Button>
+            </>
+          )}
+          <IconButton
+            size="2xs"
+            variant="ghost"
+            label={labels.details}
+            aria-expanded={!collapsed}
+            onClick={toggle}
+          >
+            {collapsed ? <ChevronDown /> : <ChevronUp />}
+          </IconButton>
+        </>
+      }
+    >
+      <span className="font-semibold">{timeText(countdown, labels)}</span>
+      {!collapsed && (
+        <>
+          {" "}
+          <span>{model === "read-only" ? labels.readOnly : labels.sandbox}</span>
+        </>
+      )}
+    </AlertBanner>
+  );
+}

package/src/demo/demo-countdown.ts

@@ -0,0 +1,141 @@
+import { useCallback, useEffect, useEffectEvent, useSyncExternalStore } from "react";
+
+/**
+ * The demo's countdown (docs/landing-demo-harmonization.md §5.3, §5.4): the time left to
+ * the demo account's end, from `expires_at` (the `TokenResponse`) or `demo_expires_at`
+ * (`/auth/me`). The client never decodes the JWT.
+ */
+
+/** When the demo ends: an ISO timestamp from the server, epoch milliseconds, or a
+ *  `Date`. */
+export type DemoExpiry = string | number | Date;
+
+/** The last stretch, in minutes, in which the banner turns to the warning tone (§5.4). */
+export const DEMO_WARNING_MINUTES = 10;
+/** Below this many minutes the countdown shows minutes only (§5.4). */
+export const DEMO_MINUTES_ONLY = 60;
+
+const MINUTE = 60_000;
+
+export interface DemoCountdown {
+  /**
+   * Whole minutes left, ROUNDED UP — 30 s left is "1 min", and 0 only once the demo has
+   * ended. `null` when `expiresAt` cannot be read: the countdown then shows no time and
+   * never ends by itself (a parse slip must not throw a visitor out).
+   */
+  minutesLeft: number | null;
+  /** The display split: whole hours, and the minutes past them. In the last hour
+   *  (`lastHour`) `hours` is 0 and `minutes` is `minutesLeft`. */
+  hours: number;
+  minutes: number;
+  /** `minutesLeft <= 60`: show minutes only. */
+  lastHour: boolean;
+  /** `minutesLeft <= 10`: the warning tone. */
+  warning: boolean;
+  /** The demo's time is up. */
+  ended: boolean;
+}
+
+/** `expiresAt` as epoch milliseconds, or NaN. */
+function expiryMs(expiresAt: DemoExpiry | null | undefined): number {
+  if (expiresAt === null || expiresAt === undefined) return Number.NaN;
+  if (typeof expiresAt === "number") return expiresAt;
+  if (expiresAt instanceof Date) return expiresAt.getTime();
+  return Date.parse(expiresAt);
+}
+
+/** Whole minutes left at `now`, rounded up, never below 0; null for an unreadable end. */
+function minutesAt(expiry: number, now: number): number | null {
+  if (!Number.isFinite(expiry)) return null;
+  return Math.max(0, Math.ceil((expiry - now) / MINUTE));
+}
+
+/**
+ * The countdown at `now` — pure, for a test or a server-rendered value. See
+ * {@link DemoCountdown} for the rounding and the thresholds.
+ */
+export function demoCountdown(expiresAt: DemoExpiry | null | undefined, now: number): DemoCountdown {
+  return countdownOf(minutesAt(expiryMs(expiresAt), now));
+}
+
+function countdownOf(minutesLeft: number | null): DemoCountdown {
+  if (minutesLeft === null) {
+    return { minutesLeft, hours: 0, minutes: 0, lastHour: false, warning: false, ended: false };
+  }
+  const lastHour = minutesLeft <= DEMO_MINUTES_ONLY;
+  return {
+    minutesLeft,
+    hours: lastHour ? 0 : Math.floor(minutesLeft / 60),
+    minutes: lastHour ? minutesLeft : minutesLeft % 60,
+    lastHour,
+    warning: minutesLeft <= DEMO_WARNING_MINUTES,
+    ended: minutesLeft === 0,
+  };
+}
+
+export interface DemoCountdownOptions {
+  /**
+   * The clock, in epoch milliseconds. Default `Date.now`. A test passes its own (or uses
+   * fake timers, which move `Date.now` too). Keep it a stable function — a new one each
+   * render re-arms the timer each render.
+   */
+  now?: () => number;
+  /** Called once when the countdown reaches zero — also on mount, if it already has.
+   *  The app clears the session and replaces to `/demo/ended` (§5.5). */
+  onEnded?: () => void;
+}
+
+/**
+ * The time left to `expiresAt`, re-rendering when the shown minute changes — one timer
+ * to the next minute boundary, not a tick a second — and once more when the tab comes
+ * back from the background (a hidden tab's timers are throttled).
+ *
+ * `onEnded` fires at zero (§5.5). The countdown is the client's, from `expires_at`; the
+ * server's answer to a request after the end (a 401) ends the demo as well — the app's
+ * 401 handler, not this hook.
+ */
+export function useDemoCountdown(
+  expiresAt: DemoExpiry | null | undefined,
+  { now = Date.now, onEnded }: DemoCountdownOptions = {},
+): DemoCountdown {
+  const expiry = expiryMs(expiresAt);
+  const subscribe = useCallback(
+    (notify: () => void) => {
+      if (!Number.isFinite(expiry)) return () => {};
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const arm = () => {
+        const left = expiry - now();
+        if (left <= 0) return;
+        // The rounded-up minute changes when `left` crosses the next whole minute below.
+        const delay = left - (Math.ceil(left / MINUTE) - 1) * MINUTE;
+        timer = setTimeout(() => {
+          notify();
+          arm();
+        }, delay);
+      };
+      const onVisible = () => {
+        if (document.visibilityState !== "visible") return;
+        clearTimeout(timer);
+        notify();
+        arm();
+      };
+      arm();
+      document.addEventListener("visibilitychange", onVisible);
+      return () => {
+        clearTimeout(timer);
+        document.removeEventListener("visibilitychange", onVisible);
+      };
+    },
+    [expiry, now],
+  );
+  const snapshot = () => minutesAt(expiry, now());
+  const minutesLeft = useSyncExternalStore(subscribe, snapshot, snapshot);
+  const countdown = countdownOf(minutesLeft);
+
+  const fireEnded = useEffectEvent(() => onEnded?.());
+  useEffect(() => {
+    if (countdown.ended) fireEnded();
+  }, [countdown.ended]);
+
+  return countdown;
+}

package/src/demo/demo-ended.tsx

@@ -0,0 +1,89 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { Hourglass } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { Button } from "../components/ui";
+import { useNoIndex } from "../hooks/use-noindex";
+import type { AuthHeadingLevel } from "../auth/status-parts";
+import { useAccessAction } from "../landing/access";
+import type { AccessChoice } from "../landing/access";
+import { useLandingLabels } from "../landing/landing-labels";
+import type { LandingLabels } from "../landing/landing-labels";
+import { useDemoLabels } from "./demo-labels";
+import type { DemoLabels } from "./demo-labels";
+import type { DemoModel } from "./demo-session";
+
+export interface DemoEndedProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "title"> {
+  /** Which line the page says about the data (§2.3). */
+  model: DemoModel;
+  /** "Request access". */
+  access: AccessChoice;
+  /** "Start a new demo". Default `/demo` — a new demo may start after one ends, within
+   *  the per-IP window (§2.7). */
+  restartHref?: string;
+  /** "Sign in". Default `/login`. */
+  signInHref?: string;
+  /** App content under the line. */
+  children?: ReactNode;
+  /** `false` adds no `noindex` — for a preview. Default `true` (§4.3). */
+  noIndex?: boolean;
+  /** Default `h2`, under `AuthLayout`'s `h1`. */
+  headingAs?: AuthHeadingLevel;
+  labels?: Partial<DemoLabels>;
+  /** The access words (`landing` namespace) for this instance. */
+  landingLabels?: Partial<LandingLabels>;
+}
+
+/**
+ * The `/demo/ended` page's content (docs/landing-demo-harmonization.md §5.5): "The demo
+ * has ended", one line on what became of the data, and three ways on — "Start a new
+ * demo", "Request access", "Sign in".
+ *
+ * Where a demo lands at `expires_at`, or on ANY 401 while the session is a demo: the
+ * client clears the session and replaces to `/demo/ended`, never to `/login`. keksdose's
+ * expired demo met an unexplained sign-in form. The server deletes the user at the next
+ * reap; nothing is kept.
+ *
+ * Content, like `NotFoundPage`: put it in the app's `AuthLayout` (its logo, language
+ * menu and legal footer). It marks the page `noindex`; robots.txt must NOT disallow it,
+ * or a crawler could never read that (§10.8).
+ */
+export function DemoEnded({
+  model,
+  access,
+  restartHref = "/demo",
+  signInHref = "/login",
+  children,
+  noIndex = true,
+  headingAs: Heading = "h2",
+  labels: labelsProp,
+  landingLabels,
+  className,
+  ...rest
+}: DemoEndedProps) {
+  const labels = useDemoLabels(labelsProp);
+  const landing = useLandingLabels(landingLabels);
+  const accessLink = useAccessAction(access, landingLabels);
+  useNoIndex(noIndex);
+  return (
+    <div {...rest} className={cn("flex flex-col items-center gap-2 py-4 text-center", className)}>
+      <Hourglass aria-hidden className="size-10 text-[var(--text-placeholder)]" />
+      <Heading className="mt-2 text-xl font-semibold text-[var(--text-primary)]">{labels.endedTitle}</Heading>
+      <p className="max-w-prose text-sm text-[var(--text-secondary)]">
+        {model === "sandbox" ? labels.endedSandbox : labels.endedReadOnly}
+      </p>
+      {children}
+      <div className="mt-4 flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:flex-wrap sm:justify-center">
+        <Button href={restartHref} variant="brand">
+          {labels.restart}
+        </Button>
+        <Button href={accessLink.href} variant="secondary">
+          {accessLink.label}
+        </Button>
+        <Button href={signInHref} variant="secondary">
+          {landing.signIn}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/demo/demo-labels.ts

@@ -0,0 +1,78 @@
+import { useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * The demo's words (docs/landing-demo-harmonization.md §5) — the `demo` namespace of
+ * `<UiKitProvider labels>`: `DemoStart`'s progress and refusals, `DemoBanner`'s
+ * countdown and model line, `DemoEnded`, and the reason of the read-only lock.
+ *
+ * "Demo" means the demo session and the shared demo data it shows (§2.10) — never
+ * keksdose's blur toggle, which is "Presentation mode" now. "Request access" and "Sign
+ * in" are the `landing` namespace's, so they read the same on every public page.
+ */
+export interface DemoLabels {
+  /** `DemoStart` while the demo is being created. */
+  starting: string;
+  /** `demo_rate_limited`: too many demos from one network, given the wait in whole
+   *  minutes from `Retry-After` — or `undefined` without one. */
+  rateLimited: (minutes?: number) => string;
+  /** `demo_capacity`: the live cap is reached. */
+  capacity: string;
+  /** `demo_disabled` and `demo_not_ready`: the demo is off, or its data isn't there. */
+  unavailable: string;
+  /** Any other failure — the network, a 500. */
+  failed: string;
+  /** `DemoStart`'s way out after a refusal, to the landing. */
+  backToStart: string;
+  /** The banner's countdown with an hour or more left: "Demo · 23 h 12 min left". */
+  hoursLeft: (hours: number, minutes: number) => string;
+  /** …and in the last hour, minutes only: "Demo · 50 min left". */
+  minutesLeft: (minutes: number) => string;
+  /** The banner's word when the end is unknown (no readable `expiresAt`). */
+  badge: string;
+  /** The banner's line for model R, shared read-only data. */
+  readOnly: string;
+  /** The banner's line for model S, a sandbox of one's own. */
+  sandbox: string;
+  /** The name of the banner's show/hide toggle (`aria-expanded` says which). */
+  details: string;
+  /** The reason a locked commit shows in a read-only demo (model R) — for the app's
+   *  `<WriteLockProvider locked reason={…}>` (§5.4). */
+  writeLocked: string;
+  /** `DemoEnded`'s heading; also the banner's text at zero. */
+  endedTitle: string;
+  /** `DemoEnded`'s line for model R. */
+  endedReadOnly: string;
+  /** `DemoEnded`'s line for model S. */
+  endedSandbox: string;
+  /** `DemoEnded`'s first action, to `/demo`. */
+  restart: string;
+}
+
+export const DEFAULT_DEMO_LABELS: DemoLabels = {
+  starting: "Starting the demo…",
+  rateLimited: (minutes) =>
+    minutes
+      ? `Too many demos from this network. Try again in ${minutes} min.`
+      : "Too many demos from this network. Try again later.",
+  capacity: "The demo is full right now. Try again later.",
+  unavailable: "The demo isn’t available right now.",
+  failed: "The demo could not be started. Please try again.",
+  backToStart: "Back to the start page",
+  hoursLeft: (hours, minutes) => `Demo · ${hours} h ${minutes} min left`,
+  minutesLeft: (minutes) => `Demo · ${minutes} min left`,
+  badge: "Demo",
+  readOnly: "You’re looking at sample data. Changes aren’t possible.",
+  sandbox: "Your own work is deleted when the demo ends.",
+  details: "Demo details",
+  writeLocked: "Not possible in the demo.",
+  endedTitle: "The demo has ended",
+  endedReadOnly: "Sample data is reset regularly.",
+  endedSandbox: "Sample data is reset regularly; your own work from the demo is deleted.",
+  restart: "Start a new demo",
+};
+
+/** The `demo` namespace, resolved: English, then the provider, then `labels`. The app
+ *  reads `writeLocked` from here for its `WriteLockProvider`. */
+export function useDemoLabels(labels?: Partial<DemoLabels>): DemoLabels {
+  return useKitLabels("demo", DEFAULT_DEMO_LABELS, labels);
+}

package/src/demo/demo-session.ts

@@ -0,0 +1,32 @@
+/**
+ * The two demo models (docs/landing-demo-harmonization.md §2.3):
+ *
+ * - `read-only` (R) — keksdose and kastlan: one pre-filled shared dataset a throwaway
+ *   demo user may look at but not change;
+ * - `sandbox` (S) — Kurvenschmiede: the demo user reads system-owned worked examples and
+ *   may create or copy work of its own, deleted with the demo account.
+ */
+export type DemoModel = "read-only" | "sandbox";
+
+/** The fields of an `/auth/me` answer {@link isDemoSession} reads — server-kit's
+ *  `UserResponse.is_demo` (0.5: and `demo_expires_at`), or a client's camel-cased copy. */
+export interface DemoSessionUser {
+  is_demo?: boolean | null;
+  isDemo?: boolean | null;
+}
+
+/**
+ * Whether the signed-in user is a demo (§5, §6.5): server-kit's `is_demo` on
+ * `/auth/me`, or a client's `isDemo`. `false` for no user at all.
+ *
+ * What the client branches on: the demo banner instead of keksdose's preview banner, the
+ * header's "Continue the demo", a 401 that ends at `/demo/ended` instead of `/login`, and
+ * the crash reporter, which files nothing for a demo:
+ *
+ * ```ts
+ * createCrashReporter({ …, suppress: () => isDemoSession(useAuth.getState().user) });
+ * ```
+ */
+export function isDemoSession(me: DemoSessionUser | null | undefined): boolean {
+  return me?.is_demo === true || me?.isDemo === true;
+}