@eifi1/ui-kit 0.30.0 → 0.31.1

package/src/index.ts

@@ -545,7 +545,7 @@ export type { CompanySwitcherProps, CompanySwitcherLabels, CompanySwitcherCompan
 // invitations panel, and the account's own settings — email change, sessions, deletion,
 // export. Callbacks only; the confirmation level is the server's.
 export { isRateLimited, retryAfterSeconds } from "./auth/auth-errors";
-export type { AccountErrorCode, KitErrorCode } from "./auth/auth-errors";
+export type { AccountErrorCode, DemoErrorCode, KitErrorCode } from "./auth/auth-errors";
 export { EmailChangeSetting, DEFAULT_EMAIL_CHANGE_LABELS } from "./account/email-change-setting";
 export type {
   EmailChangeSettingProps,
@@ -633,6 +633,103 @@ export type {
   InvitationsPanelProps,
 } from "./admin/invitations-panel";
 export type { AdminPerson } from "./admin/admin-parts";
+
+// ── 0.31.0: the settings page and the admin page on one shell (docs/settings-harmonization.md) ──
+// Router-aware: the layout, its route and focus hooks (also in `@eifi1/ui-kit/shell`).
+export { SettingsLayout, SETTINGS_SEARCH_THRESHOLD } from "./settings/settings-layout";
+export type { SettingsLayoutProps, SettingsLayoutWidth } from "./settings/settings-layout";
+export {
+  useSettingsRoute,
+  resolveSettingsLocation,
+  settingsFromListState,
+  SETTINGS_FROM_LIST_STATE,
+} from "./settings/use-settings-route";
+export type {
+  UseSettingsRouteOptions,
+  SettingsRoute,
+  SettingsLayoutMode,
+  SettingsLocation,
+  SettingsLocationRules,
+  SettingsLocationResult,
+} from "./settings/use-settings-route";
+export { useSettingsFocus, SETTINGS_FOCUS_RING, SETTINGS_FOCUS_MS } from "./settings/use-settings-focus";
+// The router-free companions: a card, the context, the heading level, the catalogue.
+export { SettingsSection } from "./settings/settings-section";
+export type { SettingsSectionProps } from "./settings/settings-section";
+export { useSettingsLayout } from "./settings/settings-context";
+export type { SettingsLayoutContextValue } from "./settings/settings-context";
+export { SettingsHeadingLevel, useSettingsHeadingLevel } from "./settings/settings-heading";
+export type { SettingsHeadingLevelProps, SettingsHeadingTag } from "./settings/settings-heading";
+export {
+  settingsSearchEntries,
+  visibleSettingsGroups,
+  visibleSettingsEntries,
+  settingsHref,
+} from "./settings/settings-catalogue";
+export type { SettingsGroup, SettingsEntry, SettingsSearchEntriesOptions } from "./settings/settings-catalogue";
+export { DEFAULT_SETTINGS_LABELS, useSettingsLabels } from "./settings/settings-labels";
+export type { SettingsLabels, SettingsGroupLabels, SettingsCoreGroup } from "./settings/settings-labels";
+// Only the language follows the account (§6.2).
+export { useAccountLanguage, resolveAccountLanguage, matchOfferedLanguage } from "./settings/use-account-language";
+export type {
+  UseAccountLanguageOptions,
+  AccountLanguage,
+  AccountLanguageSource,
+  ResolveAccountLanguageInput,
+  ResolvedAccountLanguage,
+} from "./settings/use-account-language";
+
+// ── 0.31.0: the public landing page and the demo (docs/landing-demo-harmonization.md) ──
+export { DEFAULT_LANDING_LABELS, useLandingLabels } from "./landing/landing-labels";
+export type { LandingLabels } from "./landing/landing-labels";
+export { accessAction, useAccessAction } from "./landing/access";
+export type { AccessChoice, AccessLink, AccessLabels } from "./landing/access";
+export { LandingActions } from "./landing/landing-actions";
+export type { LandingActionsProps, LandingSession } from "./landing/landing-actions";
+export { Hero, FeatureRows, FeatureRow, TrustStrip, CtaBand, PublicFooter } from "./landing/landing-sections";
+export type {
+  HeroProps,
+  FeatureRowsProps,
+  FeatureRowProps,
+  TrustItem,
+  TrustStripProps,
+  CtaBandProps,
+  PublicFooterProps,
+} from "./landing/landing-sections";
+export { usePageSeo, seoCopyProblems, metaContent } from "./landing/page-seo";
+export type { SeoCopy, SeoCopyLimits, SeoCopyProblem, SeoCopyProblemCode } from "./landing/page-seo";
+// Router-aware (also in `@eifi1/ui-kit/shell`): the header and the resume.
+export {
+  RootEntry,
+  RedirectIfAuthed,
+  useLastVisitedPage,
+  readLastVisitedPage,
+  clearLastVisitedPage,
+  safeNextPath,
+  NEXT_PARAM,
+  DEFAULT_LAST_VISITED_EXCLUDES,
+} from "./landing/routing";
+export type {
+  RootEntryProps,
+  RedirectIfAuthedProps,
+  RoutingSession,
+  LastVisitedPageOptions,
+  PathPattern,
+} from "./landing/routing";
+export { PublicHeader } from "./landing/public-header";
+export type { PublicHeaderProps, PublicHeaderBrand } from "./landing/public-header";
+export { DEFAULT_DEMO_LABELS, useDemoLabels } from "./demo/demo-labels";
+export type { DemoLabels } from "./demo/demo-labels";
+export { isDemoSession } from "./demo/demo-session";
+export type { DemoModel, DemoSessionUser } from "./demo/demo-session";
+export { useDemoCountdown, demoCountdown, DEMO_WARNING_MINUTES, DEMO_MINUTES_ONLY } from "./demo/demo-countdown";
+export type { DemoCountdown, DemoCountdownOptions, DemoExpiry } from "./demo/demo-countdown";
+export { DemoStart } from "./demo/demo-start";
+export type { DemoStartProps } from "./demo/demo-start";
+export { DemoBanner } from "./demo/demo-banner";
+export type { DemoBannerProps } from "./demo/demo-banner";
+export { DemoEnded } from "./demo/demo-ended";
+export type { DemoEndedProps } from "./demo/demo-ended";
 export type {
   LegalPageProps,
   LegalKitSectionProps,

package/src/landing/access.ts

@@ -0,0 +1,97 @@
+import { useMemo } from "react";
+
+import { DEFAULT_LANDING_LABELS, useLandingLabels } from "./landing-labels";
+import type { LandingLabels } from "./landing-labels";
+
+/**
+ * How a visitor gets an account (docs/landing-demo-harmonization.md §2.2, §4.2).
+ *
+ * - `request` — every app today: registration is invitation-only, so the primary action
+ *   is a mail to `support@<domain>`, answered with an invitation. There is no request
+ *   form and no table. `app` names the product in the mail's subject ("Access to
+ *   Kastlan"); `askCompany` adds kastlan's "Company:" line to the body.
+ * - `register` — the day an app opens registration, the SAME slot becomes "Get started"
+ *   → its `/register`. Nothing else on the page changes.
+ *
+ * One value per app, passed to every part that offers access — `PublicHeader`, `Hero`,
+ * `CtaBand`, `LandingActions`, `SignInForm`, `DemoStart`, `DemoBanner`, `DemoEnded` — so
+ * the switch is one line when it comes.
+ */
+export type AccessChoice =
+  | { kind: "request"; email: string; app?: string; askCompany?: boolean }
+  | { kind: "register"; href: string };
+
+/** What {@link accessAction} answers: where the access action goes and what it says. */
+export interface AccessLink {
+  kind: AccessChoice["kind"];
+  /** A `mailto:` for `request`, the app's register page for `register`. */
+  href: string;
+  /** "Request access" or "Get started". */
+  label: string;
+}
+
+/** The words {@link accessAction} reads. */
+export type AccessLabels = Pick<
+  LandingLabels,
+  "requestAccess" | "getStarted" | "accessSubject" | "accessName" | "accessCompany" | "accessUse"
+>;
+
+/**
+ * RFC 3986 percent-encoding, stricter than `encodeURIComponent`: `!'()*` too. RFC 6068
+ * would allow them in a header value, but a mail client that splits on `'` or `(` is
+ * the one that breaks a subject like "Access to Ada's Garden Planner", and an encoded
+ * one reads the same everywhere.
+ */
+function encodeStrict(value: string): string {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+/**
+ * The `mailto:` of a request (§4.2): the subject in the visitor's language ("Access to
+ * <App>") and a short body to fill in — "Name:", kastlan's "Company:", "What would you
+ * use it for:" — one prompt per line.
+ *
+ * RFC 6068: the lines are separated by CRLF (`%0D%0A`), spaces are `%20` (a `+` would be
+ * read as a plus), and the address keeps its `@` but nothing else unencoded.
+ */
+function mailtoHref(access: Extract<AccessChoice, { kind: "request" }>, labels: AccessLabels): string {
+  const body = [labels.accessName, ...(access.askCompany ? [labels.accessCompany] : []), labels.accessUse].join("\r\n");
+  const to = encodeStrict(access.email).replace(/%40/g, "@");
+  return `mailto:${to}?subject=${encodeStrict(labels.accessSubject(access.app))}&body=${encodeStrict(body)}`;
+}
+
+/**
+ * The access action for `access`, in the language of `labels` (§4.2): "Request access"
+ * as a mail to support, or "Get started" → the register page.
+ *
+ * Pure, so a test or an app's own button can use it; the kit's parts call
+ * {@link useAccessAction}, which takes the words from the provider. The labels already
+ * carry the language — there is no separate locale argument.
+ */
+export function accessAction(access: AccessChoice, labels: Partial<AccessLabels> = {}): AccessLink {
+  // A key given as `undefined` keeps the English, as in every kit namespace.
+  const words: AccessLabels = { ...DEFAULT_LANDING_LABELS };
+  for (const [key, value] of Object.entries(labels)) {
+    if (value !== undefined) (words as unknown as Record<string, unknown>)[key] = value;
+  }
+  if (access.kind === "register") return { kind: "register", href: access.href, label: words.getStarted };
+  return { kind: "request", href: mailtoHref(access, words), label: words.requestAccess };
+}
+
+/** {@link accessAction} with the `landing` words of the nearest provider (then `labels`). */
+export function useAccessAction(access: AccessChoice, labels?: Partial<LandingLabels>): AccessLink {
+  const words = useLandingLabels(labels);
+  // `access` is usually an inline object; its fields are what the link depends on.
+  const kind = access.kind;
+  const target = access.kind === "register" ? access.href : access.email;
+  const app = access.kind === "request" ? access.app : undefined;
+  const askCompany = access.kind === "request" ? access.askCompany === true : false;
+  return useMemo(
+    () =>
+      accessAction(
+        kind === "register" ? { kind, href: target } : { kind, email: target, app, askCompany },
+        words,
+      ),
+    [kind, target, app, askCompany, words],
+  );
+}

package/src/landing/landing-actions.tsx

@@ -0,0 +1,96 @@
+import type { ComponentPropsWithoutRef } from "react";
+
+import { cn } from "../lib/cn";
+import { Button } from "../components/ui";
+import type { ButtonSize } from "../components/ui";
+import { useAccessAction } from "./access";
+import type { AccessChoice } from "./access";
+import { useLandingLabels } from "./landing-labels";
+import type { LandingLabels } from "./landing-labels";
+
+/**
+ * Who is looking at a public page (docs/landing-demo-harmonization.md §3.1, §4.1):
+ * nobody signed in, a demo session, or a real account. The app derives it from its auth
+ * state — a demo is `isDemoSession(me)`.
+ */
+export type LandingSession = "none" | "demo" | "user";
+
+/** keksdose's hero buttons: wider than the kit's `md` (px-5 py-2.5), the page's
+ *  largest actions. */
+const LARGE = "px-5 py-2.5";
+
+export interface LandingActionsProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  session: LandingSession;
+  access: AccessChoice;
+  /** "Try the demo" without a session, "Continue the demo" with a demo one. Default
+   *  `/demo`, which starts a demo — or, for a live one, continues it (§3.1). `null`
+   *  (0.31.1): the app has no demo yet, and the action is left out — "Request access"
+   *  stands alone (Kurvenschmiede's 0.31 adoption). */
+  demoHref?: string | null;
+  /** "Open app" for a real session: the resume target. Default `/`, which resumes
+   *  through `RootEntry`. */
+  openAppHref?: string;
+  /** `large` (default): the hero's and the CTA band's size. Or a kit `ButtonSize`. */
+  size?: ButtonSize | "large";
+  /** `start` (default) under the hero's copy; `center` in the CTA band. */
+  align?: "start" | "center";
+  labels?: Partial<LandingLabels>;
+}
+
+/**
+ * The landing's action pair for the visitor's state (§4.1), shared by {@link Hero} and
+ * {@link CtaBand}:
+ *
+ * | session | actions |
+ * |---|---|
+ * | none | **Request access** (primary), Try the demo |
+ * | demo | **Request access** (primary), Continue the demo |
+ * | user | **Open app** (primary), alone |
+ *
+ * keksdose showed a signed-in visitor (who reached the landing by its brand link,
+ * `/welcome`) the register/demo pair, which `RedirectIfAuthed` then silently bounced
+ * back into the app; one "Open app" says where it goes. "Request access" is the mail of
+ * {@link accessAction}, or "Get started" once the app opens registration.
+ *
+ * Stacked full-width on a phone, a row from `sm` up — keksdose's layout.
+ */
+export function LandingActions({
+  session,
+  access,
+  demoHref = "/demo",
+  openAppHref = "/",
+  size = "large",
+  align = "start",
+  labels: labelsProp,
+  className,
+  ...rest
+}: LandingActionsProps) {
+  const labels = useLandingLabels(labelsProp);
+  const accessLink = useAccessAction(access, labelsProp);
+  const buttonSize: ButtonSize = size === "large" ? "md" : size;
+  const extra = size === "large" ? LARGE : undefined;
+  return (
+    <div
+      {...rest}
+      data-slot="landing-actions"
+      className={cn("flex flex-col gap-3 sm:flex-row", align === "center" && "sm:justify-center", className)}
+    >
+      {session === "user" ? (
+        <Button href={openAppHref} variant="brand" size={buttonSize} className={extra}>
+          {labels.openApp}
+        </Button>
+      ) : (
+        <>
+          <Button href={accessLink.href} variant="brand" size={buttonSize} className={extra}>
+            {accessLink.label}
+          </Button>
+          {demoHref !== null && (
+            <Button href={demoHref} variant="secondary" size={buttonSize} className={extra}>
+              {session === "demo" ? labels.continueDemo : labels.tryDemo}
+            </Button>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

package/src/landing/landing-labels.ts

@@ -0,0 +1,59 @@
+import { useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * The kit's words on the public landing page (docs/landing-demo-harmonization.md §4.1,
+ * §4.2) — the `landing` namespace of `<UiKitProvider labels>`.
+ *
+ * Only the GENERIC words are the kit's: the actions every app's header, hero and CTA band
+ * share, the "Beta" badge, and the template of the request-access mail. The marketing
+ * copy (the hero's title, the feature rows, the trust strip, the tagline) is each app's,
+ * in every language it ships (§4.1 "Words").
+ *
+ * The demo parts and `SignInForm` read the access words from here too, so "Request
+ * access" and its mail are said the same way on the landing, the sign-in page, the demo
+ * start, the banner and the end page.
+ */
+export interface LandingLabels {
+  /** The header's secondary action without a session; also the demo banner's and the
+   *  end page's way to an existing account. */
+  signIn: string;
+  /** The access action of an invitation-only app: a mail to support (§2.2, §4.2). */
+  requestAccess: string;
+  /** The access action once an app opens registration (`{kind: "register"}`, §4.2). */
+  getStarted: string;
+  /** The hero's and the CTA band's second action without a session. */
+  tryDemo: string;
+  /** The one action for a real session: into the app, at the resume target. */
+  openApp: string;
+  /** The secondary action for a demo session: back into the live demo. */
+  continueDemo: string;
+  /** The hero's optional badge. */
+  beta: string;
+  /** The request mail's subject, given the app's name (`access.app`): "Access to
+   *  Kastlan". `undefined` when the app named none. */
+  accessSubject: (app?: string) => string;
+  /** The request mail's body, one prompt per line; the sender writes after each. */
+  accessName: string;
+  /** Asked only where the app says so (`askCompany`, kastlan). */
+  accessCompany: string;
+  accessUse: string;
+}
+
+export const DEFAULT_LANDING_LABELS: LandingLabels = {
+  signIn: "Sign in",
+  requestAccess: "Request access",
+  getStarted: "Get started",
+  tryDemo: "Try the demo",
+  openApp: "Open app",
+  continueDemo: "Continue the demo",
+  beta: "Beta",
+  accessSubject: (app) => (app ? `Access to ${app}` : "Access request"),
+  accessName: "Name:",
+  accessCompany: "Company:",
+  accessUse: "What would you use it for:",
+};
+
+/** The `landing` namespace, resolved: English, then the provider, then `labels`. */
+export function useLandingLabels(labels?: Partial<LandingLabels>): LandingLabels {
+  return useKitLabels("landing", DEFAULT_LANDING_LABELS, labels);
+}