@eifi1/ui-kit 0.29.0 → 0.31.0

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.",
+    },
+  },
+};