@eifi1/ui-kit 0.54.0 → 0.56.0

package/src/settings/settings-section.tsx

@@ -1,108 +0,0 @@
-import type { ComponentPropsWithRef, ReactNode } from "react";
-import { Card } from "../components/card";
-import type { CardTone } from "../components/card";
-import { cn } from "../lib/cn";
-import { CARD_DESCRIPTION_CLASS, CARD_TITLE_CLASS } from "./settings-card-classes";
-import { SettingsHeading, useSettingsHeadingLevel } from "./settings-heading";
-import { useSettingsLayout } from "./settings-context";
-
-export interface SettingsSectionProps extends Omit<ComponentPropsWithRef<"div">, "title" | "id"> {
-  /** The card's DOM id — the catalogue entry's `anchor`, the `?focus=` target. */
-  anchor: string;
-  /** The card's name: a heading at the layout's level (`h3` by default). */
-  title: ReactNode;
-  /**
-   * `false` keeps the title for screen readers only — for a card alone in a group named
-   * after it, so the page does not print the same heading twice (§3.7, keksdose's admin,
-   * dev#490/#493/#494). The heading is still there: the outline and `?focus=` need it.
-   * Default `true`.
-   */
-  titleVisible?: boolean;
-  /** One muted line under the title. */
-  description?: ReactNode;
-  /** `danger` for the destructive cards at the end of "data" (§3.7). */
-  tone?: CardTone;
-  /** A control at the title's end — a refresh, a toggle. It drops under the title when
-   *  the card is too narrow for both. */
-  action?: ReactNode;
-  children?: ReactNode;
-}
-
-/**
- * Is this a development build? The consumer's bundler makes `import.meta.env.DEV` false in
- * production, so the check below is dead code there. Unlike the kit's warnings it stays
- * on under vitest: a card that cannot be found is a bug a test should fail on.
- * Optional-chained: `import.meta.env` is a Vite injection, absent under plain Node.
- */
-function devChecks(): boolean {
-  return Boolean(import.meta.env?.DEV);
-}
-
-/**
- * An app's own settings card (docs/settings-harmonization.md §3.7, §7.1): a kit `Card` at
- * the settings type scale — the title `text-sm font-medium`, the description `text-xs`
- * muted, as the kit's own setting cards — with the catalogue anchor as its id, the title
- * as a heading under the group's, and the `?focus=` ring landing on it.
- *
- * **A card without a catalogue entry throws in development** (keksdose's `section()`
- * guard). A card search cannot find breaks the rule that every setting is findable
- * (§4.1), and the old failure was silent: a hit that scrolled nowhere. The check runs
- * inside a {@link SettingsLayout}, which holds the catalogue; outside one there is
- * nothing to check against.
- */
-export function SettingsSection({
-  anchor,
-  title,
-  titleVisible = true,
-  description,
-  tone,
-  action,
-  children,
-  className,
-  ...rest
-}: SettingsSectionProps) {
-  const layout = useSettingsLayout();
-  const level = useSettingsHeadingLevel() ?? "h3";
-  if (layout && devChecks() && !layout.hasAnchor(anchor)) {
-    throw new Error(
-      `SettingsSection "${anchor}" has no catalogue entry: add a SettingsEntry with anchor "${anchor}" so search and ?focus= can reach it.`,
-    );
-  }
-  const heading = (
-    <SettingsHeading
-      as={level}
-      // Focusable from script only: `?focus=` moves focus here (§3.5).
-      tabIndex={-1}
-      data-settings-heading=""
-      className={cn(CARD_TITLE_CLASS, "outline-none", !titleVisible && "sr-only-fixed")}
-    >
-      {title}
-    </SettingsHeading>
-  );
-  const header =
-    titleVisible || description != null || action != null ? (
-      <div className="flex flex-wrap items-start justify-between gap-x-3 gap-y-2">
-        <div className="min-w-0 flex-1 basis-48">
-          {heading}
-          {description != null && <div className={CARD_DESCRIPTION_CLASS}>{description}</div>}
-        </div>
-        {action != null && <div className="flex shrink-0 items-center gap-2">{action}</div>}
-      </div>
-    ) : (
-      heading
-    );
-  return (
-    <Card
-      {...rest}
-      id={anchor}
-      tone={tone}
-      // A column with a gap, not `space-y-3`: a hidden title is `position: fixed` and so
-      // out of the flow, and a gap is only drawn between items in it — `space-y` would
-      // still push the first card part down by a gap for the title nobody sees.
-      className={cn("flex flex-col gap-3 p-4 transition-shadow motion-reduce:transition-none", className)}
-    >
-      {header}
-      {children}
-    </Card>
-  );
-}

package/src/settings/use-account-appearance.ts

@@ -1,148 +0,0 @@
-import { useCallback, useMemo } from "react";
-import { isTextSize, resolveTextSize } from "../theme/text-size";
-import type { TextSize } from "../theme/text-size";
-import { isContrastMode, resolveContrastMode } from "../theme/contrast";
-import type { ContrastMode } from "../theme/contrast";
-
-/**
- * The text size and contrast follow the account like the language does
- * (docs/text-size-harmonization.md §2.2, §2.6, §6; settings contract §6.2) — the same
- * rule as {@link useAccountLanguage}, for two values at once.
- */
-
-/** Where a value in force came from, in the order they are asked. */
-export type AppearanceSource = "device" | "account" | "default";
-
-/** The two fields of an `/auth/me` answer this reads — server-kit 0.6's `UserResponse`,
- *  both nullable (null = never chosen). */
-export interface AccountAppearanceFields {
-  text_size?: string | null;
-  contrast?: string | null;
-}
-
-/** This device's own choices — the text-size and contrast stores' values, `null` where
- *  this device never chose. */
-export interface DeviceAppearance {
-  textSize?: string | null;
-  contrast?: string | null;
-}
-
-/** The body of `PATCH /auth/me` for a pick: one field, as server-kit's `ProfileUpdate`
- *  spells it. */
-export type AccountAppearancePatch = { text_size: TextSize } | { contrast: ContrastMode };
-
-export interface ResolvedAccountAppearance {
-  textSize: TextSize;
-  /** The stored MODE — "system" included — not whether more contrast is on now. */
-  contrast: ContrastMode;
-  sources: { textSize: AppearanceSource; contrast: AppearanceSource };
-}
-
-function source(device: boolean, account: boolean): AppearanceSource {
-  return device ? "device" : account ? "account" : "default";
-}
-
-/**
- * The values on a device (§2.6): **its own choice → the account's → the default**
- * (Normal; "system" for contrast), each taken only when it is a known value. Pure.
- */
-export function resolveAccountAppearance(
-  device: DeviceAppearance,
-  account: AccountAppearanceFields | null | undefined,
-): ResolvedAccountAppearance {
-  return {
-    textSize: resolveTextSize(device.textSize, account?.text_size),
-    contrast: resolveContrastMode(device.contrast, account?.contrast),
-    sources: {
-      textSize: source(isTextSize(device.textSize), isTextSize(account?.text_size)),
-      contrast: source(isContrastMode(device.contrast), isContrastMode(account?.contrast)),
-    },
-  };
-}
-
-export interface UseAccountAppearanceOptions {
-  /** The signed-in account (`/auth/me`), or `null` / `undefined` while signed out or not
-   *  loaded yet — then nothing is saved to it. */
-  account: AccountAppearanceFields | null | undefined;
-  /** This device's own choices: `useTextSizeStore((s) => s.size)` and
-   *  `useContrastStore((s) => s.contrast)`. */
-  device: DeviceAppearance;
-  /** Store a device choice: `(patch) => { if (patch.textSize) setSize(patch.textSize);
-   *  if (patch.contrast) setContrast(patch.contrast); }`. */
-  setDevice: (patch: { textSize?: TextSize; contrast?: ContrastMode }) => void;
-  /** Write the account: `PATCH /auth/me` with the patch as its body. Return its promise. */
-  save: (patch: AccountAppearancePatch) => unknown;
-  /** A demo session: a pick stays on the device, the account is never written (§6). */
-  isDemo?: boolean;
-}
-
-export interface AccountAppearance extends ResolvedAccountAppearance {
-  /** The user picked a size: it becomes the device's choice and — signed in, and not a
-   *  demo — the account's. The promise is `save`'s; the device keeps the pick if it
-   *  fails, and the app says so (`appearance.saveFailed`, 0.32.1). */
-  pickTextSize: (size: TextSize) => Promise<unknown>;
-  /** As {@link pickTextSize}, for the contrast mode. */
-  pickContrast: (mode: ContrastMode) => Promise<unknown>;
-}
-
-/**
- * The account's text size and contrast on this device (§6): the order of
- * {@link resolveAccountAppearance}, and the writes.
- *
- * - **Nothing writes the account on its own.** Rendering, signing in and adopting the
- *   account's values call neither `save` nor `setDevice`, so a new device adopts the
- *   account instead of overwriting it.
- * - **A pick** writes the device's choice, then `save` — except in a demo session or
- *   signed out.
- *
- * The hook only answers. The values are put in force by the stores' apply hooks, which
- * resolve the same order from the same inputs:
- *
- * ```tsx
- * useApplyTextSize({ account: me?.text_size });
- * useApplyContrast({ account: me?.contrast });
- * ```
- */
-export function useAccountAppearance(options: UseAccountAppearanceOptions): AccountAppearance {
-  const { account, device, setDevice, save, isDemo = false } = options;
-  const deviceTextSize = device.textSize;
-  const deviceContrast = device.contrast;
-  const accountTextSize = account?.text_size;
-  const accountContrast = account?.contrast;
-  const signedIn = account !== null && account !== undefined;
-  // By value, so a fresh `/auth/me` object with the same two fields changes nothing.
-  const resolved = useMemo(
-    () =>
-      resolveAccountAppearance(
-        { textSize: deviceTextSize, contrast: deviceContrast },
-        signedIn ? { text_size: accountTextSize, contrast: accountContrast } : undefined,
-      ),
-    [deviceTextSize, deviceContrast, signedIn, accountTextSize, accountContrast],
-  );
-  const write = useCallback(
-    (patch: AccountAppearancePatch) => {
-      if (isDemo || !signedIn) return Promise.resolve();
-      try {
-        return Promise.resolve(save(patch));
-      } catch (error) {
-        return Promise.reject(error);
-      }
-    },
-    [save, isDemo, signedIn],
-  );
-  const pickTextSize = useCallback(
-    (size: TextSize) => {
-      setDevice({ textSize: size });
-      return write({ text_size: size });
-    },
-    [setDevice, write],
-  );
-  const pickContrast = useCallback(
-    (mode: ContrastMode) => {
-      setDevice({ contrast: mode });
-      return write({ contrast: mode });
-    },
-    [setDevice, write],
-  );
-  return { ...resolved, pickTextSize, pickContrast };
-}

package/src/settings/use-account-language.ts

@@ -1,146 +0,0 @@
-import { useCallback, useMemo } from "react";
-
-/**
- * Where the language on screen came from (docs/settings-harmonization.md §6.2), in the
- * order they are asked.
- */
-export type AccountLanguageSource = "device" | "account" | "browser" | "default";
-
-/** `de_ch`, `DE-ch` → `de-CH`: the case and separator a BCP 47 tag is written in. */
-function canonicalTag(tag: string): string {
-  const parts = tag.trim().replace(/_/g, "-").split("-").filter(Boolean);
-  return parts
-    .map((part, i) => {
-      if (i === 0) return part.toLowerCase();
-      if (part.length === 2) return part.toUpperCase();
-      if (part.length === 4) return part[0].toUpperCase() + part.slice(1).toLowerCase();
-      return part.toLowerCase();
-    })
-    .join("-");
-}
-
-/**
- * The offered language a tag means, or `null` — the client's half of server-kit's
- * `canonical_locale(tag, offered)` (§6.2): case and `_` normalised; an offered tag matches
- * exactly; otherwise the first offered tag of the same language (`de`, `de-DE` → `de-CH`
- * where `de-CH` is what the app offers); anything else is no match.
- */
-export function matchOfferedLanguage(tag: string | null | undefined, offered: readonly string[]): string | null {
-  if (!tag || !tag.trim()) return null;
-  const wanted = canonicalTag(tag);
-  const exact = offered.find((code) => canonicalTag(code) === wanted);
-  if (exact !== undefined) return exact;
-  const language = wanted.split("-")[0];
-  return offered.find((code) => canonicalTag(code).split("-")[0] === language) ?? null;
-}
-
-export interface ResolveAccountLanguageInput {
-  /** This device's own choice — made on this device, stored only when the user picks. */
-  device: string | null | undefined;
-  /** The signed-in account's `locale`; `undefined` while signed out. */
-  account: string | null | undefined;
-  /** The browser's languages, most wanted first (`navigator.languages`). */
-  browser?: readonly string[];
-  /** The languages the app offers. */
-  offered: readonly string[];
-  /** The app's default, when nothing else matches. */
-  fallback: string;
-}
-
-export interface ResolvedAccountLanguage {
-  language: string;
-  source: AccountLanguageSource;
-}
-
-/**
- * The language on a device (§6.2): **its own choice → the account's locale → the
- * browser's language → the app's default**, each taken only when it names a language the
- * app offers. Pure: the order, without the storage.
- *
- * "At sign-in the account applies unless the device has its own choice" is this order and
- * nothing more: once the account's locale arrives it outranks the browser, never the
- * device's pick.
- */
-export function resolveAccountLanguage(input: ResolveAccountLanguageInput): ResolvedAccountLanguage {
-  const { device, account, browser = [], offered, fallback } = input;
-  const fromDevice = matchOfferedLanguage(device, offered);
-  if (fromDevice) return { language: fromDevice, source: "device" };
-  const fromAccount = matchOfferedLanguage(account, offered);
-  if (fromAccount) return { language: fromAccount, source: "account" };
-  for (const tag of browser) {
-    const fromBrowser = matchOfferedLanguage(tag, offered);
-    if (fromBrowser) return { language: fromBrowser, source: "browser" };
-  }
-  return { language: fallback, source: "default" };
-}
-
-export interface UseAccountLanguageOptions {
-  /** The signed-in account's `locale` (`/auth/me`). `undefined` while signed out or not
-   *  loaded yet; `null` for an account with no language set. */
-  account: string | null | undefined;
-  /** This device's own choice — `<app>-lang` — or `null` when it was never picked here.
-   *  Detection must not fill it (i18next's detector with `caches: []`, §6.2). */
-  device: string | null | undefined;
-  /** Store the device's own choice (`<app>-lang`). */
-  setDevice: (code: string) => void;
-  /** Write the account's locale: `PATCH /auth/me {locale}`. Return its promise. */
-  save: (code: string) => unknown;
-  /** A demo session: a pick stays on the device, the account is never written (§6.2). */
-  isDemo?: boolean;
-  /** The languages the app offers, as it writes them. */
-  offered: readonly string[];
-  /** The app's default language. */
-  fallback: string;
-  /** The browser's languages. Default: `navigator.languages`. */
-  browser?: readonly string[];
-}
-
-export interface AccountLanguage extends ResolvedAccountLanguage {
-  /**
-   * The user picked `code` (the language card, the top bar's quick switch): it becomes the
-   * device's own choice and — signed in, and not a demo — the account's locale. The
-   * promise is `save`'s; the device keeps the pick if it fails, and the app says so.
-   */
-  pick: (code: string) => Promise<unknown>;
-}
-
-function navigatorLanguages(): readonly string[] {
-  if (typeof navigator === "undefined") return [];
-  return navigator.languages?.length ? navigator.languages : navigator.language ? [navigator.language] : [];
-}
-
-/**
- * The account's language on this device (§6.2, §10.8): the order of
- * {@link resolveAccountLanguage}, and the writes — so the three apps' copies go.
- *
- * - **Nothing writes the account on its own.** Rendering, signing in and adopting the
- *   account's locale call neither `save` nor `setDevice`; keksdose's
- *   `useSyncLanguageToAccount` (a PATCH on every session start) overwrote the account
- *   from a new device before that device could adopt it.
- * - **A pick** writes the device's choice, then `save` — except in a demo session, whose
- *   throwaway account needs no language (and model R refuses the write).
- *
- * The hook only answers; the app applies `language` (`i18n.changeLanguage`) where it
- * applies languages today.
- */
-export function useAccountLanguage(options: UseAccountLanguageOptions): AccountLanguage {
-  const { account, device, setDevice, save, isDemo = false, offered, fallback, browser } = options;
-  const resolved = useMemo(
-    () => resolveAccountLanguage({ device, account, browser: browser ?? navigatorLanguages(), offered, fallback }),
-    [device, account, browser, offered, fallback],
-  );
-  const signedIn = account !== undefined;
-  const pick = useCallback(
-    (code: string) => {
-      setDevice(code);
-      if (isDemo || !signedIn) return Promise.resolve();
-      try {
-        return Promise.resolve(save(code));
-      } catch (error) {
-        return Promise.reject(error);
-      }
-    },
-    [setDevice, save, isDemo, signedIn],
-  );
-  return { ...resolved, pick };
-}

package/src/settings/use-settings-focus.ts

@@ -1,128 +0,0 @@
-import { useEffect, useRef } from "react";
-import { useLocation, useNavigate } from "react-router";
-import { prefersReducedMotion } from "../lib/reduced-motion";
-
-/**
- * The ring a `?focus=` target wears for {@link SETTINGS_FOCUS_MS} — keksdose's
- * `HIGHLIGHT`, in tokens: `--brand` for the ring and the page's own surface for the gap,
- * where keksdose named a slate for the dark theme. A ring rather than a background
- * flash: the destructive cards already own a background tint, and a ring reads the same
- * on every card.
- */
-export const SETTINGS_FOCUS_RING = ["ring-2", "ring-brand", "ring-offset-2", "ring-offset-page"];
-
-/** How long the ring stays (§3.5). */
-export const SETTINGS_FOCUS_MS = 1800;
-
-/** How long a target that is not on the page yet (a lazy card, a card waiting for its
- *  data) is waited for before the hook gives up on it. */
-const WAIT_MS = 5000;
-
-const HEADING = "[data-settings-heading], h1, h2, h3, h4, h5, h6";
-
-/**
- * `?focus=<anchor>` (docs/settings-harmonization.md §3.5): scroll the card into view, ring
- * it for 1.8 s, move focus to its heading for a screen reader, then remove `focus` — and
- * ONLY `focus` — with a replace, so a reload does not ring it again. Every other
- * parameter stays: a tour's `tour` / `tourStep`, the admin roster's filters (dropping URL
- * parts broke keksdose's tours once, dev#495). The hash and `location.state` stay too.
- *
- * A search hit, ⌘K, a tour and a mail link all arrive this way. `SettingsLayout` calls it
- * for its own page; an app's own page can call it with no argument to act on its URL.
- *
- * `anchor`:
- *  - left out: the URL's `focus` parameter;
- *  - a string: that anchor (the layout passes the URL's, once its route is canonical);
- *  - `null`: nothing to do yet — the layout passes it while the address is about to be
- *    replaced, so a removal here cannot undo a redirect there.
- *
- * "Once its group has rendered": the effect runs after the commit that mounted the
- * group's cards, so the card is there; a card that mounts later (lazy, or behind its
- * data) is waited for, for a few seconds, before the hook gives up and leaves the URL
- * as it is.
- */
-export function useSettingsFocus(anchor?: string | null): void {
-  const location = useLocation();
-  const navigate = useNavigate();
-  const target = anchor === undefined ? new URLSearchParams(location.search).get("focus") : anchor;
-  // The ring outlives the effect that drew it: removing `focus` from the URL re-runs the
-  // effect (and cleans it up) at once, and the ring must still stay its 1.8 s.
-  const ring = useRef<{ el: HTMLElement; timer: number } | null>(null);
-
-  useEffect(() => {
-    if (!target) return;
-    const { pathname, search, hash, state } = location;
-
-    const land = (el: HTMLElement) => {
-      el.scrollIntoView?.({ behavior: prefersReducedMotion() ? "auto" : "smooth", block: "center" });
-
-      if (ring.current) {
-        window.clearTimeout(ring.current.timer);
-        ring.current.el.classList.remove(...SETTINGS_FOCUS_RING);
-        // The mark goes with the ring, as the timer's own end takes both: left behind, the
-        // first card stayed "focused" for good (keksdose's matching-tab test reads it).
-        ring.current.el.removeAttribute("data-settings-focus");
-      }
-      el.classList.add(...SETTINGS_FOCUS_RING);
-      el.setAttribute("data-settings-focus", "");
-      const timer = window.setTimeout(() => {
-        el.classList.remove(...SETTINGS_FOCUS_RING);
-        el.removeAttribute("data-settings-focus");
-        if (ring.current?.el === el) ring.current = null;
-      }, SETTINGS_FOCUS_MS);
-      ring.current = { el, timer };
-
-      // The heading, so a screen reader starts at the card's name; the card itself when
-      // it has none. `preventScroll`: the smooth scroll above is already on its way.
-      const heading = el.querySelector<HTMLElement>(HEADING) ?? el;
-      if (!heading.hasAttribute("tabindex")) heading.setAttribute("tabindex", "-1");
-      heading.focus({ preventScroll: true });
-
-      const params = new URLSearchParams(search);
-      if (params.get("focus") !== target) return;
-      params.delete("focus");
-      const rest = params.toString();
-      navigate({ pathname, search: rest ? `?${rest}` : "", hash }, { replace: true, state });
-    };
-
-    const found = document.getElementById(target);
-    if (found) {
-      land(found);
-      return;
-    }
-    const observer = new MutationObserver(() => {
-      const el = document.getElementById(target);
-      if (!el) return;
-      observer.disconnect();
-      window.clearTimeout(giveUp);
-      land(el);
-    });
-    observer.observe(document.body, { childList: true, subtree: true });
-    const giveUp = window.setTimeout(() => observer.disconnect(), WAIT_MS);
-    return () => {
-      observer.disconnect();
-      window.clearTimeout(giveUp);
-    };
-    // `location`, a new object per navigation: the same hit picked twice is two
-    // navigations, and rings twice.
-  }, [target, location, navigate]);
-
-  useEffect(
-    () => () => {
-      const current = ring.current;
-      if (!current) return;
-      window.clearTimeout(current.timer);
-      current.el.classList.remove(...SETTINGS_FOCUS_RING);
-      current.el.removeAttribute("data-settings-focus");
-    },
-    [],
-  );
-}
-
-/**
- * {@link useSettingsFocus} under a name for any page (0.51.4, keksdose run 89): the hook
- * was always allowed on an app's own pages (keksdose's /reports/matching lands
- * `?focus=matching-unmatched` on a card), but its name said Settings at every such call
- * site. The same function, so the two cannot drift; `useSettingsFocus` stays.
- */
-export const useFocusParam: typeof useSettingsFocus = useSettingsFocus;