@eifi1/ui-kit 0.30.0 → 0.31.0

package/src/landing/public-header.tsx

@@ -0,0 +1,120 @@
+import type { ReactNode } from "react";
+
+import { Button, PHONE_QUERY } from "../components/ui";
+import { useMediaQuery } from "../hooks/use-media-query";
+import { TopBar } from "../shell/top-bar";
+import type { TopBarProps } from "../shell/top-bar";
+import { TopBarBrand } from "../shell/top-bar-brand";
+import { useAccessAction } from "./access";
+import type { AccessChoice } from "./access";
+import { useLandingLabels } from "./landing-labels";
+import type { LandingLabels } from "./landing-labels";
+import type { LandingSession } from "./landing-actions";
+
+/** The header's brand: what `TopBarBrand` draws. */
+export interface PublicHeaderBrand {
+  /** The brand mark — an SVG or an `<img alt="">`. */
+  logo: ReactNode;
+  /** The product name beside it, and the link's accessible name. */
+  name: ReactNode;
+  /** See `TopBarBrand`. Default `sm`: the logo alone on a phone. */
+  collapseBelow?: "sm" | "md" | false;
+}
+
+export interface PublicHeaderProps extends Omit<TopBarProps, "brand" | "actions" | "children"> {
+  brand: PublicHeaderBrand;
+  /** Where the brand links. Default `/` without a session and `/welcome` with one —
+   *  `/` would resume into the app, `/welcome` is always the landing (§3.1). */
+  homeHref?: string;
+  session: LandingSession;
+  access: AccessChoice;
+  /** "Sign in". Default `/login`. */
+  signInHref?: string;
+  /** "Open app" for a real session — the resume target. Default `/`, which resumes
+   *  through `RootEntry`. */
+  openAppHref?: string;
+  /** "Continue the demo" for a demo session. Default `/demo`, which continues a live
+   *  demo (§3.1). */
+  demoHref?: string;
+  /** The app's `LanguageMenu`, before the actions. */
+  languageMenu?: ReactNode;
+  /** The app's `ThemeToggle`, before the language menu. */
+  themeToggle?: ReactNode;
+  labels?: Partial<LandingLabels>;
+}
+
+/**
+ * The header of every public page (docs/landing-demo-harmonization.md §4.1): the
+ * landing, the auth pages, the legal pages and the 404 — keksdose's `LandingHeader`, on
+ * the kit's `TopBar` and `TopBarBrand`, with its hard-coded teal turned into `--brand`.
+ *
+ * | session | actions |
+ * |---|---|
+ * | none | Sign in (secondary, hidden below `sm`), **Request access** (primary) |
+ * | demo | Continue the demo (secondary), **Request access** (primary) |
+ * | user | **Open app** (primary) |
+ *
+ * A demo session is not "signed in" here: it is still offered access, which is the point
+ * of the demo (§5.6). On a phone (`PHONE_QUERY`) the actions take the kit's `sm` size, so
+ * the brand mark, the two controls and two actions fit 390px; "Sign in" gives way below
+ * `sm` as in keksdose — the sign-in page is one tap away from "Request access" anyway.
+ */
+export function PublicHeader({
+  brand,
+  homeHref,
+  session,
+  access,
+  signInHref = "/login",
+  openAppHref = "/",
+  demoHref = "/demo",
+  languageMenu,
+  themeToggle,
+  labels: labelsProp,
+  className,
+  ...rest
+}: PublicHeaderProps) {
+  const labels = useLandingLabels(labelsProp);
+  const accessLink = useAccessAction(access, labelsProp);
+  const phone = useMediaQuery(PHONE_QUERY, false);
+  const size = phone ? "sm" : "md";
+  const home = homeHref ?? (session === "none" ? "/" : "/welcome");
+
+  const actions =
+    session === "user" ? (
+      <Button href={openAppHref} variant="brand" size={size}>
+        {labels.openApp}
+      </Button>
+    ) : (
+      <>
+        {session === "demo" ? (
+          <Button href={demoHref} variant="secondary" size={size}>
+            {labels.continueDemo}
+          </Button>
+        ) : (
+          <Button href={signInHref} variant="secondary" size={size} className="max-sm:hidden">
+            {labels.signIn}
+          </Button>
+        )}
+        <Button href={accessLink.href} variant="brand" size={size}>
+          {accessLink.label}
+        </Button>
+      </>
+    );
+
+  return (
+    <TopBar
+      {...rest}
+      className={className}
+      brand={<TopBarBrand logo={brand.logo} name={brand.name} to={home} collapseBelow={brand.collapseBelow} />}
+      actions={
+        <>
+          {themeToggle}
+          {languageMenu}
+          <span data-slot="public-header-actions" className="ms-1 flex items-center gap-1.5 sm:gap-2">
+            {actions}
+          </span>
+        </>
+      }
+    />
+  );
+}

package/src/landing/routing.tsx

@@ -0,0 +1,209 @@
+import { useEffect } from "react";
+import type { ReactNode } from "react";
+import { Navigate, Outlet, useLocation } from "react-router";
+
+import { readStored, writeStored } from "../lib/safe-storage";
+import type { LandingSession } from "./landing-actions";
+
+/**
+ * The public routes' logic (docs/landing-demo-harmonization.md §3): what `/` shows,
+ * which pages a session skips, and the page a session resumes on — keksdose's
+ * `RootEntry`, `RedirectIfAuthed` and use-last-visited-page.ts, for every app.
+ * Router-aware (react-router), so they belong to the `./shell` entry.
+ */
+
+/* ── ?next= ──────────────────────────────────────────────────────────────── */
+
+/** The query parameter that carries "where I was actually trying to go" through the
+ *  sign-in bounce (keksdose's `NEXT_PARAM`). */
+export const NEXT_PARAM = "next";
+
+/**
+ * A `?next=` value that is safe to navigate to, or null.
+ *
+ * Same-origin PATHS only, decided by the URL PARSER rather than by string prefix —
+ * this is the open-redirect check, and it is the reason this lives in one place
+ * instead of at each call site.
+ *
+ * The prefix version ("starts with `/`, does not start with `//`") let two shapes
+ * through that the browser resolves cross-origin, because the WHATWG parser does not
+ * read them as text: a backslash after the leading slash counts as a second slash for
+ * a special scheme, so `/\evil.example` resolves to `https://evil.example/`; and tab,
+ * LF and CR are STRIPPED anywhere in the input before parsing, so `/<TAB>/evil.example`
+ * becomes `//evil.example`. Asking the same parser the browser will use closes every
+ * such shape at once, including ones nobody has thought of yet, and it normalises what
+ * comes back instead of echoing the caller's spelling.
+ *
+ * keksdose's (shared/hooks/use-last-visited-page.ts), verbatim but for the fallback
+ * origin.
+ */
+export function safeNextPath(raw: string | null | undefined): string | null {
+  if (!raw) return null;
+  const base = typeof window !== "undefined" ? window.location.origin : "https://kit.invalid";
+  try {
+    const url = new URL(raw, base);
+    if (url.origin !== base) return null;
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return null;
+  }
+}
+
+/* ── The last visited page (§3.2) ────────────────────────────────────────── */
+
+/** A path to leave out: a string is the path and everything under it (`/demo` is
+ *  `/demo` and `/demo/ended`; `/` is only `/`), a RegExp is tested on the pathname. */
+export type PathPattern = string | RegExp;
+
+/**
+ * The pages never recorded as a resume target (§3.2): the landing (`/`, `/welcome`), the
+ * auth pages, the demo's own (`/demo*`) and the legal pages. The 404 has no path of its
+ * own — call {@link useLastVisitedPage} inside the signed-in layout, as keksdose does,
+ * and it never sees one. The app adds its own one-shot routes (keksdose:
+ * `/banks/callback`, `/join`, `/share-target`) through `exclude`.
+ */
+export const DEFAULT_LAST_VISITED_EXCLUDES: readonly PathPattern[] = Object.freeze([
+  "/",
+  "/welcome",
+  "/login",
+  "/register",
+  "/forgot-password",
+  "/reset-password",
+  "/verify-email",
+  "/demo",
+  "/impressum",
+  "/privacy",
+  "/terms",
+]);
+
+function matchesPath(pathname: string, pattern: PathPattern): boolean {
+  if (typeof pattern !== "string") return new RegExp(pattern.source, pattern.flags.replace("g", "")).test(pathname);
+  if (pattern === "/") return pathname === "/";
+  const base = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+  return pathname === base || pathname.startsWith(`${base}/`);
+}
+
+/** Whether `pathname` is one of the defaults or the app's `exclude`. */
+function isExcluded(pathname: string, exclude: readonly PathPattern[]): boolean {
+  return [...DEFAULT_LAST_VISITED_EXCLUDES, ...exclude].some((pattern) => matchesPath(pathname, pattern));
+}
+
+export interface LastVisitedPageOptions {
+  /** The device key: `<app>.lastVisitedPage` (§3.2), one per app on the origin. */
+  key: string;
+  /** The app's own paths to leave out, ON TOP of {@link DEFAULT_LAST_VISITED_EXCLUDES}. */
+  exclude?: readonly PathPattern[];
+  /** `false` records nothing — while the session is still being restored, say. */
+  enabled?: boolean;
+}
+
+/**
+ * Remember the page a session is on (path and query), on every navigation, so `/` — a
+ * revisit, a fresh sign-in, the installed PWA, whose `start_url` is `/` — resumes there
+ * (§3.2, keksdose feedback #59). Device-local, in `localStorage` under `key`; a blocked
+ * storage records nothing.
+ *
+ * Call it once in the signed-in layout. The excluded paths are never written, so a
+ * one-shot page (a bank callback, an invitation link) never becomes the place the next
+ * launch opens on.
+ */
+export function useLastVisitedPage({ key, exclude = [], enabled = true }: LastVisitedPageOptions): void {
+  const { pathname, search } = useLocation();
+  // Decided here, so the effect depends on the answer and not on an `exclude` array the
+  // caller likely builds inline.
+  const skip = !enabled || isExcluded(pathname, exclude);
+  useEffect(() => {
+    if (skip) return;
+    writeStored(key, pathname + search);
+  }, [key, pathname, search, skip]);
+}
+
+/**
+ * The page {@link useLastVisitedPage} remembered under `key` — checked by
+ * {@link safeNextPath}, so a value someone planted in storage cannot leave the origin —
+ * or `fallback` (default `null`) when there is none or storage is blocked. A string
+ * fallback narrows the answer to a string, for react-router's `to`.
+ */
+export function readLastVisitedPage(key: string, fallback: string): string;
+export function readLastVisitedPage(key: string, fallback?: null): string | null;
+export function readLastVisitedPage(key: string, fallback: string | null = null): string | null {
+  return safeNextPath(readStored(key)) ?? fallback;
+}
+
+/** Forget the remembered page — on an explicit sign-out, so the next account does not
+ *  resume on the previous one's page. */
+export function clearLastVisitedPage(key: string): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+    // storage blocked: there is nothing to forget
+  }
+}
+
+/* ── RootEntry ───────────────────────────────────────────────────────────── */
+
+export interface RootEntryProps {
+  /** Without a session `/` is the landing; with one (real or demo) it resumes. */
+  session: LandingSession;
+  /** The remembered page — `readLastVisitedPage(key)`. */
+  resumePath?: string | null;
+  /** The landing page element. */
+  landing: ReactNode;
+  /** The app's home: where a session goes with nothing to resume (keksdose `/budget`,
+   *  kastlan and Kurvenschmiede `/dashboard`). */
+  home: string;
+}
+
+/**
+ * The `/` route (§3.1): the landing for a visitor, and for a session — real or demo —
+ * the last visited page, else the app's home. Indexed and canonical `/` for the visitor;
+ * a crawler never has a session, so for it `/` is stable.
+ *
+ * keksdose showed a session with nothing remembered the landing; the contract sends it
+ * home instead, because a session at `/` came to use the app. The landing stays one tap
+ * away at `/welcome`, where the signed-in brand link points.
+ */
+export function RootEntry({ session, resumePath, landing, home }: RootEntryProps) {
+  if (session === "none") return <>{landing}</>;
+  const resume = safeNextPath(resumePath);
+  return <Navigate to={resume && resume !== "/" ? resume : home} replace />;
+}
+
+/* ── RedirectIfAuthed ────────────────────────────────────────────────────── */
+
+export interface RedirectIfAuthedProps {
+  session: LandingSession;
+  /**
+   * Let a DEMO session through (§5.6): on `/login`, `/register` and the app's invitation
+   * pages, so a demo visitor can sign in or accept an invitation — a successful one
+   * replaces the demo session. Default `false`: on `/demo` a live demo continues instead
+   * of starting a second one (§5.2), and on `/forgot-password` a demo has no password.
+   */
+  allowDemo?: boolean;
+  /** Where a redirected session goes: the resume target —
+   *  `readLastVisitedPage(key, home)`. A safe `?next=` goes first. */
+  fallback: string;
+  /** The page. Left out, an `<Outlet />`: the component is a layout route around the
+   *  public pages, as in keksdose. */
+  children?: ReactNode;
+}
+
+/**
+ * Public pages a session skips (§3.1): a signed-in visitor at `/login` goes back into
+ * the app, to a safe `?next=` when the URL carries one (a share invitation or a push
+ * deep link opened with a live session in another tab — keksdose) and else to
+ * `fallback`.
+ *
+ * A demo session passes where `allowDemo` says so (§5.6). Mount one wrapper with
+ * `allowDemo` around `/login`, `/register` and the invitation pages, and one without
+ * around `/demo` (and `/forgot-password`).
+ */
+export function RedirectIfAuthed({ session, allowDemo = false, fallback, children }: RedirectIfAuthedProps) {
+  const { search } = useLocation();
+  if (session === "none" || (session === "demo" && allowDemo)) {
+    return children === undefined ? <Outlet /> : <>{children}</>;
+  }
+  const next = safeNextPath(new URLSearchParams(search).get(NEXT_PARAM));
+  return <Navigate to={next ?? fallback} replace />;
+}

package/src/settings/settings-catalogue.ts

@@ -0,0 +1,132 @@
+import type { ReactNode } from "react";
+import type { SearchEntry } from "../search/search-index";
+
+/**
+ * The settings catalogue (docs/settings-harmonization.md §4.1), lifted from keksdose's
+ * `settings-index.ts`: the groups a settings page is split into, and one entry per
+ * SETTING — not per card — so a search for "quiet hours" finds the field inside the
+ * notifications card. One list feeds the sidebar, the phone list, the in-page search and
+ * ⌘K ({@link settingsSearchEntries}); keksdose's page and its palette drifted when they
+ * had one each.
+ *
+ * The kit resolves no words: `title`, `help` and `keywords` arrive translated (an app's
+ * own, or the core groups' from `DEFAULT_SETTINGS_LABELS.groups`).
+ */
+
+/** One group of the page: a sidebar row on a desktop, a list row on a phone (§3.2, §3.3). */
+export interface SettingsGroup<G extends string = string> {
+  /** The path segment, `/settings/<id>`: lowercase, a–z and "-". */
+  id: G;
+  /** The row's icon — a lucide icon at the row's size is sized by the row. */
+  icon: ReactNode;
+  /** The group's name: the sidebar row, the heading over its cards, the phone list. */
+  title: string;
+  /** One line under the heading and in the phone list, where it is cut to one line. */
+  help: string;
+  /**
+   * `false` hides the group: no row, no hits, and its path acts as an unknown one — it
+   * lands on the default group (desktop) or the list (phone), never on a 404 (§3.1).
+   * kastlan's `/admin/billing` while billing is off. Default: visible.
+   */
+  visible?: boolean;
+}
+
+/** One setting, and the card that holds it (§4.1). */
+export interface SettingsEntry<G extends string = string> {
+  /** Unique within the catalogue. */
+  id: string;
+  /** The group whose page shows the card. */
+  group: G;
+  /** The card's DOM id, unique on the page — the `?focus=` target. Several entries may
+   *  share one: a card that holds four settings has four entries. */
+  anchor: string;
+  /** What a search hit says. */
+  title: string;
+  /** Localized, space-separated words people type that the title does not contain
+   *  ("dark night" for the theme, "2fa totp" for two-factor). Never shown. */
+  keywords?: string;
+  /**
+   * `false` drops the entry from the page's search and ⌘K. A group whose entries are
+   * ALL hidden is hidden with them (§4.1): a demo session marks every card it is refused
+   * (passkeys, 2FA, export, deletion …) and so never sees a page of cards that each
+   * answer 403. Default: visible.
+   */
+  visible?: boolean;
+}
+
+/**
+ * The groups that show, in their order: not `visible: false`, and — when `entries` is
+ * given — holding at least one visible entry (§4.1: Kurvenschmiede's notifications group
+ * stays hidden until it has a card). Without `entries` only the groups' own flag counts.
+ */
+export function visibleSettingsGroups<G extends string>(
+  groups: readonly SettingsGroup<G>[],
+  entries?: readonly SettingsEntry<G>[],
+): SettingsGroup<G>[] {
+  if (!entries) return groups.filter((g) => g.visible !== false);
+  const filled = new Set<G>();
+  for (const e of entries) if (e.visible !== false) filled.add(e.group);
+  return groups.filter((g) => g.visible !== false && filled.has(g.id));
+}
+
+/** The visible entries of the visible groups — what search may find. */
+export function visibleSettingsEntries<G extends string>(
+  groups: readonly SettingsGroup<G>[],
+  entries: readonly SettingsEntry<G>[],
+): SettingsEntry<G>[] {
+  const shown = new Set(visibleSettingsGroups(groups, entries).map((g) => g.id));
+  return entries.filter((e) => e.visible !== false && shown.has(e.group));
+}
+
+/** `basePath` without a trailing slash: "/settings/" and "/settings" are one page. */
+export function normalizeSettingsBase(basePath: string): string {
+  const trimmed = basePath.replace(/\/+$/, "");
+  return trimmed.startsWith("/") || trimmed === "" ? trimmed : `/${trimmed}`;
+}
+
+/** `/settings/<group>`, and `?focus=<anchor>` when a card is named (§3.4). */
+export function settingsHref(basePath: string, group: string, anchor?: string): string {
+  const path = `${normalizeSettingsBase(basePath)}/${group}`;
+  return anchor ? `${path}?focus=${encodeURIComponent(anchor)}` : path;
+}
+
+/** "dark  night" → ["dark", "night"]. */
+export function settingsKeywords(keywords: string | undefined): string[] {
+  return keywords ? keywords.split(/\s+/).filter(Boolean) : [];
+}
+
+export interface SettingsSearchEntriesOptions {
+  /** `/settings` or `/admin` — the hits link to `<basePath>/<group>?focus=<anchor>`. */
+  basePath: string;
+}
+
+/**
+ * The catalogue as {@link GlobalSearch} entries (§3.4): each visible setting, under its
+ * group's name as the palette's section, linking to `/settings/<group>?focus=<anchor>` —
+ * the same link the page's own search hit is, so ⌘K, a tour and a mail all land the
+ * same way (§3.5). The group's name is a keyword too, as on the page: "security" lists
+ * the security group's settings.
+ *
+ * Ids are prefixed with the base path ("settings:theme", "admin:users") so a palette
+ * that also holds pages and actions keeps them unique.
+ */
+export function settingsSearchEntries<G extends string>(
+  groups: readonly SettingsGroup<G>[],
+  entries: readonly SettingsEntry<G>[],
+  options: SettingsSearchEntriesOptions,
+): SearchEntry[] {
+  const base = normalizeSettingsBase(options.basePath);
+  const prefix = base.replace(/^\//, "").replace(/\//g, ":") || "settings";
+  const byId = new Map(visibleSettingsGroups(groups, entries).map((g) => [g.id, g]));
+  return visibleSettingsEntries(groups, entries).map((e) => {
+    const group = byId.get(e.group)!;
+    return {
+      id: `${prefix}:${e.id}`,
+      title: e.title,
+      keywords: [group.title, ...settingsKeywords(e.keywords)],
+      group: group.title,
+      icon: group.icon,
+      href: settingsHref(base, e.group, e.anchor),
+    };
+  });
+}

package/src/settings/settings-context.ts

@@ -0,0 +1,33 @@
+import { createContext, useContext } from "react";
+import type { SettingsHeadingTag } from "./settings-heading";
+
+/**
+ * What {@link SettingsLayout} hands the cards it renders (docs/settings-harmonization.md
+ * §3.1, §3.7). Router-free on purpose, so `SettingsSection` and an app's cards can read
+ * it without importing the layout.
+ */
+export interface SettingsLayoutContextValue {
+  /** `/settings` or `/admin`, without a trailing slash. */
+  basePath: string;
+  /** The group on screen; `null` on a phone's list. */
+  group: string | null;
+  /** The path segment after the group — the surface a card owns (keksdose's swipe card). */
+  sub: string | null;
+  /**
+   * Select the card's sub-surface: `/settings/<group>/<sub>`, or the group alone with
+   * `null`. A replace, keeping the query and the history marker: switching a tab inside a
+   * card is not a place to go back to. The card never builds the path itself (§3.1).
+   */
+  selectSub: (sub: string | null) => void;
+  /** The level the cards' titles are at: `h3` on a desktop, `h2` on a phone. */
+  headingLevel: SettingsHeadingTag;
+  /** Whether the catalogue has an entry with this anchor — `SettingsSection`'s check. */
+  hasAnchor: (anchor: string) => boolean;
+}
+
+export const SettingsLayoutContext = createContext<SettingsLayoutContextValue | null>(null);
+
+/** The {@link SettingsLayout} around this card, or `null` outside one. */
+export function useSettingsLayout(): SettingsLayoutContextValue | null {
+  return useContext(SettingsLayoutContext);
+}

package/src/settings/settings-heading.tsx

@@ -0,0 +1,65 @@
+import { createContext, useContext } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { CARD_TITLE_CLASS } from "../account/account-parts";
+
+/** The heading a settings card's title becomes. */
+export type SettingsHeadingTag = "h2" | "h3" | "h4";
+
+const SettingsHeadingLevelContext = createContext<SettingsHeadingTag | null>(null);
+
+export interface SettingsHeadingLevelProps {
+  /** The element every kit setting card below titles itself with. */
+  level: SettingsHeadingTag;
+  children?: ReactNode;
+}
+
+/**
+ * The level the kit's setting cards title themselves at (docs/settings-harmonization.md
+ * §3.7). Inside {@link SettingsLayout} a card's title is a heading under the group's —
+ * `h3` under the desktop's `h2`, `h2` under a phone group page's `h1` — and the layout
+ * sets this for every card it renders. Outside one, nothing is set and the same cards
+ * keep the plain `div` title they always had, so a card on an app's own page does not
+ * suddenly put an `h3` into an outline that has no `h2`.
+ *
+ * Set it yourself only where an app lays out settings cards without the layout and
+ * wants them in its outline: `<SettingsHeadingLevel level="h3">…</SettingsHeadingLevel>`.
+ * `ProfileSetting`, `PasswordSetting`, `TwoFactorSetting`, `PasskeysSetting`,
+ * `EmailChangeSetting`, `SessionsSetting`, `DataExportSetting`, `DeleteAccountSetting`
+ * and `SettingsSection` read it.
+ */
+export function SettingsHeadingLevel({ level, children }: SettingsHeadingLevelProps) {
+  return <SettingsHeadingLevelContext.Provider value={level}>{children}</SettingsHeadingLevelContext.Provider>;
+}
+
+/** The nearest {@link SettingsHeadingLevel}, or `null` outside one. */
+export function useSettingsHeadingLevel(): SettingsHeadingTag | null {
+  return useContext(SettingsHeadingLevelContext);
+}
+
+/**
+ * A setting card's title at the settings type scale: a heading inside a
+ * {@link SettingsHeadingLevel}, the plain `div` outside one.
+ *
+ * As a heading it takes `tabIndex={-1}`: `?focus=` moves focus to the card's heading so a
+ * screen reader lands on the card it was sent to (§3.5), and a heading is not focusable
+ * otherwise. No outline of its own — the ring round the card marks it.
+ *
+ * @internal The kit's cards use it; not part of the barrel.
+ */
+export function SettingsCardTitle({ className, ...props }: ComponentPropsWithoutRef<"div">) {
+  const level = useSettingsHeadingLevel();
+  if (!level) return <div {...props} className={cn(CARD_TITLE_CLASS, className)} />;
+  return <SettingsHeading as={level} tabIndex={-1} {...props} className={cn(CARD_TITLE_CLASS, "outline-none", className)} />;
+}
+
+/**
+ * A heading at a level chosen at run time. Its own component, taking the tag as a prop
+ * (as `CardTitle` does), so the element type is a prop and not a value computed in the
+ * caller's render.
+ *
+ * @internal
+ */
+export function SettingsHeading({ as: Tag, ...props }: { as: SettingsHeadingTag } & ComponentPropsWithoutRef<"h2">) {
+  return <Tag {...props} />;
+}

package/src/settings/settings-labels.ts

@@ -0,0 +1,75 @@
+/**
+ * The `settings` namespace (docs/settings-harmonization.md §4.3): the settings page's
+ * own words, and the names and help lines of the five core groups every app shares —
+ * appearance, account, security, notifications, data (§2.6). An app's own groups bring
+ * their own words; any core label may be overridden like any kit label (prop >
+ * `<UiKitProvider labels={{ settings }}>` > English).
+ */
+
+/** A core group's two strings, as {@link SettingsGroup} takes them. */
+export interface SettingsGroupLabels {
+  /** The group's name. */
+  title: string;
+  /** One line: under the heading, and in the phone list. */
+  help: string;
+}
+
+/** The five groups whose words the kit ships (§2.6, §4.2). */
+export type SettingsCoreGroup = "appearance" | "account" | "security" | "notifications" | "data";
+
+export interface SettingsLabels {
+  /** The page's heading, and the back link's visible text on a phone's group page. */
+  title: string;
+  /** The search field's accessible name. */
+  search: string;
+  /** The search field's placeholder. */
+  searchPlaceholder: string;
+  /** The hit list's accessible name. */
+  results: string;
+  /** No hits for the trimmed query (§3.4). */
+  noMatches: (query: string) => string;
+  /** The button beside it that empties the field. */
+  clearSearch: string;
+  /** The phone's back link's accessible name: "‹ Settings" says where, this says what. */
+  back: string;
+  /** The sidebar's accessible name (the vertical tablist). */
+  sections: string;
+  /** A sidebar row's hit badge, read in place of the bare number while searching. */
+  matchCount: (count: number) => string;
+  /** The core groups' names and help lines. */
+  groups: Record<SettingsCoreGroup, SettingsGroupLabels>;
+}
+
+export const DEFAULT_SETTINGS_LABELS: SettingsLabels = {
+  title: "Settings",
+  search: "Search settings",
+  searchPlaceholder: "Search settings…",
+  results: "Matching settings",
+  noMatches: (query) => `No settings match “${query}”.`,
+  clearSearch: "Clear search",
+  back: "Back to settings",
+  sections: "Settings sections",
+  matchCount: (count) => (count === 1 ? "1 match" : `${count} matches`),
+  groups: {
+    appearance: {
+      title: "Appearance",
+      help: "Language, theme and how the app looks on this device.",
+    },
+    account: {
+      title: "Account",
+      help: "Your profile and your email address.",
+    },
+    security: {
+      title: "Security",
+      help: "How you sign in: password, two-factor codes, passkeys and sessions.",
+    },
+    notifications: {
+      title: "Notifications",
+      help: "What you are told about, when, and on which devices.",
+    },
+    data: {
+      title: "Data",
+      help: "Export what is yours, or delete it together with your account.",
+    },
+  },
+};