@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/rhf/line-items.tsx

@@ -0,0 +1,130 @@
+/**
+ * {@link LineItems} over react-hook-form's `useFieldArray`. `@eifi1/ui-kit/rhf`.
+ *
+ * ```tsx
+ * <RhfLineItems
+ *   name="components"
+ *   newItem={() => ({ type: "net_rent", amount: null, validFrom: "" })}
+ *   minItems={1}
+ *   columns={[
+ *     { key: "type", header: "Type", render: ({ name, label }) => (
+ *       <RhfSelect name={`${name}.type`} options={TYPES} aria-label={label} />
+ *     ) },
+ *     { key: "amount", header: "Amount", width: "8rem", align: "end", render: ({ name, label }) => (
+ *       <RhfMoneyField name={`${name}.amount`} ariaLabel={label} />
+ *     ) },
+ *   ]}
+ *   totals={{ amount: formatMoney(total) }}
+ * />
+ * ```
+ *
+ * The rows are the array's `fields` (keyed by their `id`, as react-hook-form asks),
+ * Add appends `newItem()`, remove is `remove(index)`, and an error on the array
+ * itself — the `rules` here, or a resolver's `lines: "At least two lines"` — is the
+ * list's `error`. Each cell's `render` gets `name`, the row's path
+ * (`"components.2"`), to bind its field to.
+ */
+import type { ReactNode } from "react";
+import {
+  useFieldArray,
+  useFormState,
+  type FieldArray,
+  type FieldArrayPath,
+  type FieldArrayWithId,
+  type FieldValues,
+  type UseFieldArrayProps,
+} from "react-hook-form";
+import {
+  LineItems,
+  type LineItemCellContext,
+  type LineItemsColumn,
+  type LineItemsProps,
+} from "../components/line-items";
+
+/** A cell's context, with the row's path in the form. */
+export interface RhfLineItemCellContext<TItem, TArrayName extends string>
+  extends LineItemCellContext<TItem> {
+  /** The row's path: `${name}.${index}` — bind the cell's field to
+   *  `` `${name}.amount` ``. */
+  name: `${TArrayName}.${number}`;
+}
+
+export interface RhfLineItemsColumn<TItem, TArrayName extends string>
+  extends Omit<LineItemsColumn<TItem>, "render"> {
+  render: (ctx: RhfLineItemCellContext<TItem, TArrayName>) => ReactNode;
+}
+
+export interface RhfLineItemsProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> extends Omit<
+    LineItemsProps<FieldArrayWithId<TFieldValues, TArrayName, "id">>,
+    "items" | "columns" | "onAdd" | "onRemove" | "getKey"
+  > {
+  name: TArrayName;
+  /** `form.control`. Optional under `<Form {...form}>`. */
+  control?: UseFieldArrayProps<TFieldValues, TArrayName, "id", TTransformed>["control"];
+  /** `useFieldArray`'s `rules` (`minLength`, `validate` …); its message is the list's
+   *  error. */
+  rules?: UseFieldArrayProps<TFieldValues, TArrayName, "id", TTransformed>["rules"];
+  columns: readonly RhfLineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, "id">, TArrayName>[];
+  /** A new row's values. Omitted: no add button. */
+  newItem?: () => FieldArray<TFieldValues, TArrayName>;
+  /** `false`: no remove buttons. Default `true`. */
+  removable?: boolean;
+}
+
+/** The message of an error at `path` in react-hook-form's errors tree: the array's
+ *  own (`root`, from `rules`) or one a resolver put on the array. */
+function arrayError(errors: unknown, path: string): string | undefined {
+  let node: unknown = errors;
+  for (const key of path.split(".")) {
+    if (node === null || typeof node !== "object") return undefined;
+    node = (node as Record<string, unknown>)[key];
+  }
+  if (node === null || typeof node !== "object") return undefined;
+  const { root, message } = node as { root?: { message?: unknown }; message?: unknown };
+  const text = root?.message ?? message;
+  return typeof text === "string" && text !== "" ? text : undefined;
+}
+
+/** {@link LineItems} bound to a field array. See the module note. */
+export function RhfLineItems<
+  TFieldValues extends FieldValues = FieldValues,
+  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  columns,
+  newItem,
+  removable = true,
+  error,
+  ...rest
+}: RhfLineItemsProps<TFieldValues, TArrayName, TTransformed>) {
+  const { fields, append, remove } = useFieldArray<TFieldValues, TArrayName, "id", TTransformed>({
+    control,
+    name,
+    rules,
+  });
+  const { errors } = useFormState({ control, name: name as never });
+  const bound: LineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, "id">>[] = columns.map(
+    ({ render, ...column }) => ({
+      ...column,
+      render: (ctx) => render({ ...ctx, name: `${name}.${ctx.index}` as `${TArrayName}.${number}` }),
+    }),
+  );
+  return (
+    <LineItems
+      {...rest}
+      items={fields}
+      columns={bound}
+      getKey={(field) => field.id}
+      onAdd={newItem ? () => append(newItem()) : undefined}
+      onRemove={removable ? (index) => remove(index) : undefined}
+      error={error ?? arrayError(errors, name)}
+    />
+  );
+}

package/src/rhf.ts

@@ -9,3 +9,9 @@
 export * from "./rhf/form";
 // The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
 export * from "./rhf/use-rhf-wizard-step";
+// Bound fields — one line per field (RhfTextField, RhfNumberField, RhfMoneyField,
+// RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox)
+// and RhfField, the shell they are built on.
+export * from "./rhf/fields";
+// LineItems over useFieldArray.
+export * from "./rhf/line-items";

package/src/shell/app-shell.tsx

@@ -1,17 +1,19 @@
 import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { createPortal } from "react-dom";
-import { NavLink, matchPath, useLocation } from "react-router";
+import { Link, NavLink, matchPath, useLocation } from "react-router";
 import { ChevronRight, PanelLeftClose, PanelLeftOpen } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { dirOf, type Direction } from "../lib/direction";
 import { readStored, writeStored } from "../lib/safe-storage";
 import { Tooltip } from "../components/tooltip";
+import { pickLinkRenderer } from "../components/text-link";
 import { useAnchoredRect } from "../hooks/use-anchored-rect";
 import { useEscapeKey } from "../hooks/use-dismiss";
 import { useMediaQuery } from "../hooks/use-media-query";
-import { DEFAULT_APP_SHELL_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_APP_SHELL_LABELS, useKitLabels, useKitLink } from "../i18n/kit-labels";
+import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
 
 export interface AppShellSubItem {
   to: string;
@@ -48,6 +50,44 @@ export interface AppShellNavItem {
   items?: AppShellSubItem[];
 }
 
+/**
+ * One entry of the sidebar's bottom area ({@link AppShellProps.sidebarFooterItems}) —
+ * the version link and the legal links kastlan hand-built in `sidebarFooter`.
+ *
+ * - `link` (default): one link. Expanded it shows `icon` + `text` (default `label`),
+ *   with `hint` as a tooltip if given; collapsed it is the icon alone, named and
+ *   tooltipped by `label`.
+ * - `links`: a small group — the legal links. Expanded, a `<nav>` named `label` holding
+ *   the links as a wrapping row of small text; collapsed, ONE icon link to `to` (default
+ *   the first link's), named and tooltipped by `label`, since a column of icons for
+ *   "Imprint", "Privacy" and "Terms" would say nothing an icon can.
+ */
+export type AppShellSidebarFooterItem =
+  | {
+      kind?: "link";
+      key: string;
+      to: string;
+      icon: LucideIcon;
+      /** The link's name, and the tooltip when collapsed ("What's new · v1.4.0"). */
+      label: string;
+      /** Visible text when expanded ("Kastlan v1.4.0"). Default `label`. */
+      text?: ReactNode;
+      /** A tooltip on the expanded link ("What's new"). */
+      hint?: string;
+      /** Leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`. */
+      external?: boolean;
+    }
+  | {
+      kind: "links";
+      key: string;
+      icon: LucideIcon;
+      /** The group's name — its `<nav>` label, and the collapsed icon's name ("Legal"). */
+      label: string;
+      /** The collapsed icon's target. Default the first link's `to`. */
+      to?: string;
+      links: { to: string; label: string; external?: boolean }[];
+    };
+
 /**
  * Exported and `<div>`-shaped. This is the outermost element of every consuming app, so
  * there is nothing above it to hang an id, a landmark label or a `data-tour` anchor on —
@@ -66,6 +106,13 @@ export interface AppShellProps extends ComponentPropsWithoutRef<"div"> {
   /** Extra sidebar content above the collapse toggle (e.g. a version link).
    *  Receives the collapsed state so it can render compact vs. full. */
   sidebarFooter?: (collapsed: boolean) => ReactNode;
+  /** The sidebar's bottom area as data — a version link, the legal links — drawn full
+   *  when expanded and as icon + tooltip when collapsed. Rendered above
+   *  `sidebarFooter`, which stays for anything the data cannot describe. */
+  sidebarFooterItems?: AppShellSidebarFooterItem[];
+  /** The router link for `sidebarFooterItems`. Default: the provider's
+   *  `linkComponent`, else react-router's `Link`. */
+  renderLink?: KitLinkComponent;
   /** localStorage key for the persisted collapse state. */
   collapseStorageKey?: string;
   /** Default: `appShell.collapse` from the {@link UiKitProvider}, else English. */
@@ -201,6 +248,8 @@ export function AppShell({
   children,
   footer,
   sidebarFooter,
+  sidebarFooterItems,
+  renderLink,
   collapseStorageKey: collapseStorageKeyProp,
   collapseLabel,
   expandLabel,
@@ -296,6 +345,9 @@ export function AppShell({
                 ))}
               </div>
             </nav>
+            {!!sidebarFooterItems?.length && (
+              <SidebarFooterItems items={sidebarFooterItems} collapsed={collapsed} renderLink={renderLink} />
+            )}
             {sidebarFooter?.(collapsed)}
             <div className="border-t border-[var(--border)] p-2">
               {collapsed ? (
@@ -397,6 +449,99 @@ export function AppShell({
   );
 }
 
+const routerLink: KitLinkComponent = ({ href, ...p }) => <Link to={href} {...p} />;
+const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}</a>;
+
+const FOOTER_ICON_LINK =
+  "flex min-h-8 items-center justify-center rounded-md text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]";
+
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
+  return render(props);
+}
+
+/** The sidebar's bottom area, from {@link AppShellSidebarFooterItem}s. */
+function SidebarFooterItems({
+  items,
+  collapsed,
+  renderLink,
+}: {
+  items: AppShellSidebarFooterItem[];
+  collapsed: boolean;
+  renderLink?: KitLinkComponent;
+}) {
+  const kitLink = useKitLink();
+  const linkTo = (to: string, external: boolean | undefined, { children, ...props }: Omit<KitLinkProps, "href">) => {
+    // The kit's one link rule (`pickLinkRenderer`): an external `to` or an in-page
+    // `#anchor` is a plain `<a>` even without `external`; only `external` opens a tab.
+    const InApp = pickLinkRenderer(renderLink, kitLink ?? routerLink, to) ?? plainLink;
+    return external ? (
+      <a href={to} target="_blank" rel="noopener noreferrer" {...props}>
+        {children}
+      </a>
+    ) : (
+      <RenderedLink render={InApp} href={to} {...props}>
+        {children}
+      </RenderedLink>
+    );
+  };
+
+  return (
+    <div data-slot="sidebar-footer-items" className={cn("px-2 py-1", collapsed ? "space-y-1" : "space-y-1.5")}>
+      {items.map((item) => {
+        if (collapsed) {
+          const to = item.kind === "links" ? (item.to ?? item.links[0]?.to) : item.to;
+          if (!to) return null;
+          const external = item.kind === "links" ? item.links.find((l) => l.to === to)?.external : item.external;
+          return (
+            <Tooltip key={item.key} label={item.label} side="end" portal className="block">
+              {linkTo(to, external, {
+                "aria-label": item.label,
+                className: FOOTER_ICON_LINK,
+                children: <item.icon className="size-4" aria-hidden />,
+              })}
+            </Tooltip>
+          );
+        }
+        if (item.kind === "links") {
+          return (
+            <nav
+              key={item.key}
+              aria-label={item.label}
+              className="flex flex-wrap justify-center gap-x-3 gap-y-0.5 text-[11px] text-[var(--text-muted)]"
+            >
+              {item.links.map((l) => (
+                <span key={l.to}>
+                  {linkTo(l.to, l.external, {
+                    className: "rounded-sm hover:text-[var(--text-secondary)] hover:underline",
+                    children: l.label,
+                  })}
+                </span>
+              ))}
+            </nav>
+          );
+        }
+        const link = linkTo(item.to, item.external, {
+          className: cn(FOOTER_ICON_LINK, "gap-1.5 text-xs font-medium"),
+          children: (
+            <>
+              <item.icon className="size-3.5 shrink-0" aria-hidden />
+              <span className="min-w-0 truncate">{item.text ?? item.label}</span>
+            </>
+          ),
+        });
+        return item.hint ? (
+          <Tooltip key={item.key} label={item.hint} side="top" portal className="block">
+            {link}
+          </Tooltip>
+        ) : (
+          <div key={item.key}>{link}</div>
+        );
+      })}
+    </div>
+  );
+}
+
 /** One cell of the phone's group bar. Marked while the group's own page OR any of its
  *  pages is current — NavLink alone only knows its own `to`, which left the bar with
  *  nothing marked on every sub-page (the same defect the sidebar had). */

package/src/shell/auth-layout.tsx

@@ -0,0 +1,190 @@
+import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { Card } from "../components/ui";
+
+/**
+ * `extends ComponentPropsWithoutRef<"div">` because this is the page's outermost element
+ * — the one that owns `min-h-dvh` and the safe-area padding — so there is nothing a
+ * consumer could wrap it in to add an id or a `data-*` hook without breaking that.
+ */
+export interface AuthLayoutProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  /** The brand mark (an SVG), drawn in a brand-coloured tile above the title. */
+  logo?: ReactNode;
+  /** `false` draws `logo` as it is, without the tile — for a full-colour logo image. */
+  logoTile?: boolean;
+  /** The page's `<h1>` (see `headingAs`): the product name on sign-in, "Verify email",
+   *  "Imprint". */
+  title?: ReactNode;
+  /** The muted line under the title. */
+  description?: ReactNode;
+  /** The card's content — the form, the status, the legal text. */
+  children: ReactNode;
+  /**
+   * Above the header, outside the card — the legal pages' "← Back to sign in" link, or
+   * a notice banner. Start-aligned in both widths.
+   */
+  back?: ReactNode;
+  /** The top-end corner: a `LanguageMenu`. */
+  languageMenu?: ReactNode;
+  /** The top-end corner, before the language menu: a `ThemeToggle`. */
+  themeToggle?: ReactNode;
+  /** Below the card, centred — the legal links. */
+  footer?: ReactNode;
+  /** Wraps the footer in a `<nav>` with this name ("Legal"). Without it, a plain block. */
+  footerLabel?: string;
+  /**
+   * - `"narrow"` (default) — a `max-w-sm` card centred on the page, header centred:
+   *   sign-in, register, verify email, two-factor.
+   * - `"wide"` — a `max-w-3xl` column from the top of the page, header start-aligned:
+   *   running text (imprint, privacy, terms), which reads badly centred.
+   */
+  width?: "narrow" | "wide";
+  /** `false` lays the header and content on the page itself, without the card's
+   *  surface and border — the legal pages. Default true. */
+  card?: boolean;
+  /** Extra classes for the card (or, with `card={false}`, the content column). */
+  cardClassName?: string;
+  /**
+   * `false` draws the content column and the footer as plain `<div>`s instead of
+   * `<main>` and `<footer>` — for an AuthLayout embedded in a page that already has its
+   * landmarks (a preview, a docs page, a dialog), where a second `<main>` would nest
+   * one inside the other. Default `true`: on its own route it IS the page.
+   */
+  landmark?: boolean;
+  /** The title's element. Default `h1` — the page's heading; an embedded layout takes
+   *  the level of where it sits (`h2`, `h3`). */
+  headingAs?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+/** Keeps the page clear of a notch, the rounded corners and the home indicator on a
+ *  phone in `viewport-fit=cover`; 1rem where the platform reports no inset. Physical
+ *  left/right, because that is what `env()` reports. */
+const SAFE_AREA: CSSProperties = {
+  paddingTop: "max(1rem, env(safe-area-inset-top, 0px))",
+  paddingBottom: "max(1rem, env(safe-area-inset-bottom, 0px))",
+  paddingLeft: "max(1rem, env(safe-area-inset-left, 0px))",
+  paddingRight: "max(1rem, env(safe-area-inset-right, 0px))",
+};
+
+const FOOTER_CLASS =
+  "flex flex-wrap justify-center gap-x-4 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a:hover]:underline [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-2 [&_a:focus-visible]:ring-[var(--brand)]";
+
+/**
+ * The public page frame outside the app shell: sign-in, registration, email
+ * verification, two-factor — and, `width="wide"`, the legal pages.
+ *
+ * kastlan's login, register, verify-email and two-factor pages each repeat the same
+ * `min-h-screen` centring, the absolutely placed language switcher, the brand tile, the
+ * centred title + subtitle and an absolutely placed legal footer. Absolutely placed,
+ * the footer and the switcher sat ON the card on a short phone screen (a tall register
+ * form, or the software keyboard up); here they are rows of a column that grows with
+ * its content, so the page scrolls instead of overlapping.
+ *
+ * The corner controls, the `<main>` and the footer are in reading order: a screen
+ * reader meets the language switch first, which is where someone who cannot read the
+ * page's language needs it.
+ */
+export function AuthLayout({
+  logo,
+  logoTile = true,
+  title,
+  description,
+  children,
+  back,
+  languageMenu,
+  themeToggle,
+  footer,
+  footerLabel,
+  width = "narrow",
+  card = true,
+  cardClassName,
+  landmark = true,
+  headingAs: Heading = "h1",
+  className,
+  style,
+  ...rest
+}: AuthLayoutProps) {
+  const Main = landmark ? "main" : "div";
+  const Footer = landmark ? "footer" : "div";
+  const wide = width === "wide";
+  const hasCorner = languageMenu != null || themeToggle != null;
+  const hasHeader = logo != null || title != null || description != null;
+
+  const header = hasHeader && (
+    <div
+      data-slot="auth-layout-header"
+      className={cn("flex flex-col gap-1.5", wide ? "items-start text-start" : "items-center text-center")}
+    >
+      {logo != null &&
+        (logoTile ? (
+          <div className="mb-2 flex size-12 items-center justify-center rounded-lg bg-[var(--brand)] text-[var(--brand-contrast)] [&_svg]:size-6">
+            {logo}
+          </div>
+        ) : (
+          <div className="mb-2">{logo}</div>
+        ))}
+      {title != null && (
+        <Heading
+          className={cn(
+            "font-semibold leading-tight text-[var(--text-primary)]",
+            wide ? "text-2xl md:text-3xl" : "text-2xl",
+          )}
+        >
+          {title}
+        </Heading>
+      )}
+      {description != null && <p className="text-sm text-[var(--text-muted)]">{description}</p>}
+    </div>
+  );
+
+  const body = (
+    <>
+      {header}
+      <div className={cn(hasHeader && (wide ? "mt-6" : "mt-5"))}>{children}</div>
+    </>
+  );
+
+  return (
+    <div
+      {...rest}
+      data-auth-layout={width}
+      style={{ ...SAFE_AREA, ...style }}
+      className={cn("flex min-h-dvh flex-col bg-[var(--bg-page)] text-[var(--text-primary)]", className)}
+    >
+      {hasCorner && (
+        <div data-slot="auth-layout-corner" className="flex items-center justify-end gap-1">
+          {themeToggle}
+          {languageMenu}
+        </div>
+      )}
+      <Main
+        data-slot="auth-layout-main"
+        className={cn(
+          // `relative` contains any `sr-only` child (see AppShell's <main>).
+          "relative flex w-full flex-1 flex-col",
+          wide ? "py-6 md:py-10" : "items-center justify-center py-8",
+        )}
+      >
+        <div className={cn("mx-auto w-full", wide ? "max-w-3xl" : "max-w-sm")}>
+          {back != null && <div className="mb-4">{back}</div>}
+          {card ? (
+            <Card className={cn(wide ? "p-6 md:p-8" : "p-6", cardClassName)}>{body}</Card>
+          ) : (
+            <div className={cardClassName}>{body}</div>
+          )}
+        </div>
+      </Main>
+      {footer != null && footer !== false && (
+        <Footer data-slot="auth-layout-footer" className="pt-4">
+          {footerLabel ? (
+            <nav aria-label={footerLabel} className={FOOTER_CLASS}>
+              {footer}
+            </nav>
+          ) : (
+            <div className={FOOTER_CLASS}>{footer}</div>
+          )}
+        </Footer>
+      )}
+    </div>
+  );
+}

package/src/shell/top-bar-brand.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from "react";
+import { Link as RouterLink } from "react-router";
+import { cn } from "../lib/cn";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer } from "../components/text-link";
+import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
+
+const routerLink: KitLinkComponent = ({ href, ...p }) => <RouterLink to={href} {...p} />;
+const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}</a>;
+
+/** Below which width only the logo shows. The name stays in the link's accessible
+ *  name at every width. */
+const COLLAPSE = {
+  sm: "sr-only sm:not-sr-only sm:truncate",
+  md: "sr-only md:not-sr-only md:truncate",
+} as const;
+
+export interface TopBarBrandProps extends Omit<KitLinkProps, "href" | "children"> {
+  /** The brand mark — an SVG, sized by the caller or `h-6 w-auto` by default. */
+  logo: ReactNode;
+  /** The product name beside the logo, and the link's accessible name. */
+  name: ReactNode;
+  /** Where the brand links to. Default `/`. */
+  to?: string;
+  /** Hide the name below `sm` (default) or `md`; `false` always shows it. It is
+   *  visually hidden, not removed, so the link keeps its name on a phone. */
+  collapseBelow?: "sm" | "md" | false;
+  /** The app's router link for this one link. Default: the provider's
+   *  `linkComponent`, else react-router's `Link`. */
+  renderLink?: KitLinkComponent;
+}
+
+/**
+ * The top bar's home link: logo + product name, collapsing to the logo on a phone.
+ * Pass it as {@link TopBar}'s `brand`.
+ *
+ * kastlan's (top-bar.tsx:66) hid nothing and truncated the name instead — on a phone
+ * with five actions that left "Ka…" beside the logo — and needed an `aria-label`
+ * because the name could be cut. Here the name is `sr-only` below the breakpoint, so
+ * the logo is the whole visible link there and the name is still what it is called.
+ */
+export function TopBarBrand({
+  logo,
+  name,
+  to = "/",
+  collapseBelow = "sm",
+  renderLink,
+  className,
+  ...rest
+}: TopBarBrandProps) {
+  const kitLink = useKitLink();
+  return (
+    <RenderedLink
+      // The kit's one link rule (`pickLinkRenderer`): an external `to` or an in-page
+      // `#anchor` is a plain `<a>`, never the router's link.
+      render={pickLinkRenderer(renderLink, kitLink ?? routerLink, to) ?? plainLink}
+      {...rest}
+      href={to}
+      className={cn(
+        // `relative` contains the sr-only name.
+        "relative flex min-w-0 items-center gap-2 rounded-md font-semibold text-[var(--text-primary)] hover:opacity-80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        className,
+      )}
+    >
+      <span aria-hidden className="flex shrink-0 items-center [&_svg]:h-6 [&_svg]:w-auto">
+        {logo}
+      </span>
+      <span className={collapseBelow ? COLLAPSE[collapseBelow] : "truncate"}>{name}</span>
+    </RenderedLink>
+  );
+}
+
+/** Calls the link renderer as a component, so a router link's hooks are its own. */
+function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
+  return render(props);
+}

package/src/shell/topbar-action-menu.tsx

@@ -5,6 +5,8 @@ import { cn } from "../lib/cn";
 import { HoverMenu } from "../components/hover-menu";
 import { MenuItem } from "../components/menu-item";
 import type { MenuItemTone } from "../components/menu-item";
+import { StatusDot } from "../components/status-dot";
+import type { UserAvatarBadge } from "../components/user-avatar";
 import { TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
 
 /**
@@ -125,6 +127,7 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
  */
 export function TopBarActionMenu({
   icon,
+  iconBadge,
   trigger,
   triggerClassName,
   ariaLabel,
@@ -139,6 +142,13 @@ export function TopBarActionMenu({
 }: {
   /** The trigger's face for the usual icon button. Ignored when `trigger` is given. */
   icon?: ReactNode;
+  /**
+   * A status dot in the top-end corner of `icon` — keksdose's unread-support dot on the
+   * feedback trigger. Like `UserAvatar`'s `badge`, its `label` joins the trigger's name
+   * ("Send feedback 2 unread"), so the dot is not something only the eye is told about.
+   * Ignored with `trigger`: give the face its own badge there.
+   */
+  iconBadge?: UserAvatarBadge | null;
   /**
    * A face of your own for the trigger — the account menu's `UserAvatar`. It is drawn
    * INSIDE the kit's button, which keeps the wiring: `aria-haspopup`, `aria-expanded`,
@@ -190,6 +200,17 @@ export function TopBarActionMenu({
             {" "}
             {trigger({ open })}
           </button>
+        ) : iconBadge ? (
+          // Named by its content, like the custom-trigger branch, so the badge label is
+          // part of the name; an `aria-label` would have hidden it.
+          <button type="button" onClick={toggle} className={cn(TOPBAR_TRIGGER_CLASS, "relative", triggerClassName)}>
+            <span className="sr-only">{ariaLabel}</span>{" "}
+            <span aria-hidden className="relative inline-flex">
+              {icon}
+              <StatusDot ring tone={iconBadge.tone ?? "danger"} className="absolute -end-0.5 -top-0.5" />
+            </span>{" "}
+            <span className="sr-only">{iconBadge.label}</span>
+          </button>
         ) : (
           <button
             type="button"

package/src/shell.ts

@@ -8,3 +8,5 @@ export * from "./shell/app-shell";
 export * from "./shell/option-switcher-menu";
 export * from "./shell/role-switcher";
 export * from "./shell/topbar-action-menu";
+export * from "./shell/top-bar-brand";
+export * from "./shell/auth-layout";