@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/shell/option-switcher-menu.tsx

@@ -1,84 +0,0 @@
-import type { ReactNode } from "react";
-import { Check } from "lucide-react";
-import { HoverMenu } from "../components/hover-menu";
-import { TOPBAR_MENU_ITEM_CLASS, TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
-import { Tooltip } from "../components/tooltip";
-
-export interface OptionSwitcherOption<T extends string> {
-  value: T;
-  label: ReactNode;
-}
-
-/**
- * A top-bar hover menu that switches between a small set of options, with a
- * check on the active one and an optional heading. Generic glue over
- * {@link HoverMenu} — e.g. a dev role/impersonation switcher, an environment
- * picker. Controlled: the app owns `value` and `onSelect`.
- */
-export function OptionSwitcherMenu<T extends string>({
-  icon,
-  "aria-label": ariaLabel,
-  title,
-  heading,
-  options,
-  value,
-  onSelect,
-}: {
-  icon: ReactNode;
-  /** Names the trigger and the menu. Required: the trigger is an icon (refactor audit
-   *  2026-10, API-1 — the `ariaLabel` spelling went in 0.35). */
-  "aria-label": string;
-  /** The trigger's tooltip. Default: `aria-label` (0.48) — the name, shown on hover and
-   *  focus. A different text also describes the trigger (`aria-describedby`). */
-  title?: string;
-  heading?: string;
-  options: OptionSwitcherOption<T>[];
-  value: T;
-  onSelect: (value: T) => void;
-}) {
-  return (
-    <HoverMenu
-      aria-label={ariaLabel}
-      trigger={({ toggle }) => {
-        const button = (
-          <button type="button" onClick={toggle} aria-label={ariaLabel} className={TOPBAR_TRIGGER_CLASS}>
-            {icon}
-          </button>
-        );
-        // The name on hover and focus even without a `title` (0.48, keksdose dev#610). A
-        // bubble that repeats the name sits round the button in a fragment, as IconButton's
-        // does, so it does not describe the button by its own name — a reader heard "Text
-        // size, button, Text size". A `title` that says more still describes it.
-        const tip = title ?? ariaLabel;
-        return (
-          <Tooltip label={tip} portal>
-            {tip === ariaLabel ? <>{button}</> : button}
-          </Tooltip>
-        );
-      }}
-    >
-      {(close) => (
-        <ul className="py-1">
-          {heading && (
-            <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-placeholder">{heading}</li>
-          )}
-          {options.map((opt) => (
-            <li key={opt.value}>
-              <button
-                type="button"
-                onClick={() => {
-                  onSelect(opt.value);
-                  close();
-                }}
-                className={TOPBAR_MENU_ITEM_CLASS}
-              >
-                <span>{opt.label}</span>
-                {value === opt.value && <Check className="size-4 text-secondary" />}
-              </button>
-            </li>
-          ))}
-        </ul>
-      )}
-    </HoverMenu>
-  );
-}

package/src/shell/sync-status-indicator.tsx

@@ -1,303 +0,0 @@
-import { useEffect, useRef, useState } from "react";
-import type { ComponentType } from "react";
-import { Check, Cloud, CloudAlert, CloudOff, RefreshCw, UploadCloud } from "lucide-react";
-import type { LucideProps } from "lucide-react";
-import { cn } from "../lib/cn";
-import { IconButton } from "../components/icon-button";
-import { Tooltip } from "../components/tooltip";
-import { useBillingLabels } from "../billing/billing-labels";
-import { useKitLocale, type LabelOverride } from "../i18n/kit-labels";
-import { useTopBarPartsLabels, type SyncStatusLabels } from "./top-bar-parts-labels";
-
-/**
- * What the indicator shows, fed by the app's sync engine (docs/top-bar-harmonization.md
- * §2.6). Small on purpose: keksdose's sync-status store, kastlan's handover controller and
- * Kurvenschmiede's online state + `useIsMutating` all fill it.
- */
-export interface SyncStatus {
-  /** What the engine is doing. `offline` is the engine's own verdict; `online: false` is
-   *  the browser's — either shows the offline state. */
-  phase: "idle" | "syncing" | "offline" | "error";
-  /** The browser's `navigator.onLine` (or the app's better guess). */
-  online: boolean;
-  /** Writes kept on this device and not yet sent. */
-  pending: number;
-  /** Writes this device cannot send at all (keksdose: no key for the budget). Ranked first. */
-  blocked?: number;
-  /** Writes the server refused as read-only and keeps until a plan (billing §12.5). */
-  waitingForPlan?: number;
-  /** When the last good round ended — epoch ms, an ISO string or a `Date`. */
-  lastSyncedAt?: number | string | Date | null;
-}
-
-/** The seven states, in their ranking: the first that holds wins. */
-export type SyncState = "blocked" | "waitingForPlan" | "offline" | "error" | "syncing" | "pending" | "synced";
-
-/**
- * Which of the seven states a {@link SyncStatus} is in — keksdose's ranking
- * (sync-status-indicator.tsx): a write that cannot be sent at all ranks above everything,
- * because waiting cannot help it; then one waiting for a plan; then offline; then a refused
- * round; then a round under way; then writes waiting; else in sync. `syncing` also holds
- * while a tap's own round runs (`refreshing`), before the engine publishes its phase.
- */
-export function syncState(status: SyncStatus, refreshing = false): SyncState {
-  if ((status.blocked ?? 0) > 0) return "blocked";
-  if ((status.waitingForPlan ?? 0) > 0) return "waitingForPlan";
-  if (!status.online || status.phase === "offline") return "offline";
-  if (status.phase === "error") return "error";
-  if (status.phase === "syncing" || refreshing) return "syncing";
-  if (status.pending > 0) return "pending";
-  return "synced";
-}
-
-type Tone = "danger" | "warning" | "info" | "success";
-
-const LOOK: Record<SyncState, { Icon: ComponentType<LucideProps>; tone: Tone }> = {
-  // The one the user must act on: the kit's danger, where keksdose had rose.
-  blocked: { Icon: CloudAlert, tone: "danger" },
-  // Safe, and a payment sends them: amber, the kit's warning.
-  waitingForPlan: { Icon: CloudAlert, tone: "warning" },
-  offline: { Icon: CloudOff, tone: "warning" },
-  // Usually resolves by itself (a deploy, a read-only view): amber, not danger.
-  error: { Icon: CloudAlert, tone: "warning" },
-  syncing: { Icon: RefreshCw, tone: "info" },
-  pending: { Icon: UploadCloud, tone: "warning" },
-  synced: { Icon: Cloud, tone: "success" },
-};
-
-const TEXT_TONE: Record<Tone, string> = {
-  danger: "text-danger",
-  warning: "text-warning",
-  info: "text-info",
-  success: "text-success",
-};
-
-/** The scope words of an indicator that covers only part of the app (§6.10). */
-export interface SyncStatusScope {
-  /** Put before every state in the tooltip: "Handovers on this device" →
-   *  "Handovers on this device: 3 changes waiting to sync". */
-  name: string;
-  /** The whole offline sentence instead of the kit's, when offline means something
-   *  narrower: "Offline: handovers keep working on this device; everything else needs a
-   *  connection". */
-  offline?: string;
-}
-
-export interface SyncStatusIndicatorProps {
-  status: SyncStatus;
-  /**
-   * Run a round now (push, then pull, then re-read what is on screen). With it the
-   * indicator is a "sync now" button, disabled offline and mid-round but keeping its
-   * colour; a returned promise keeps the spin until it settles. Without it, a status only
-   * (§6.9).
-   */
-  onSync?: () => void | Promise<unknown>;
-  /** Render nothing while in sync — kastlan and Kurvenschmiede show it only while offline,
-   *  syncing or with changes waiting, held or refused (§2.6). */
-  hideWhenIdle?: boolean;
-  /** The app's words for its part of the app (§6.10). */
-  scope?: SyncStatusScope;
-  /**
-   * Where the app keeps a change before the server has it. `"device"` (the default): an
-   * offline-first app (keksdose, kastlan's handovers) — offline means "kept here, sent
-   * later". `"none"`: an online-only app that keeps nothing on the device (Kurvenschmiede,
-   * build review B1) — offline reads "changes can't be saved until you reconnect", a
-   * round reads "Saving…", and `pending`, `blocked` and `waitingForPlan` are ignored,
-   * since there is nowhere for a change to wait. "Up to date" when settled.
-   */
-  storage?: "device" | "none";
-  /** Short words beside the cloud ("Offline", "Syncing…", "3 waiting") while not in sync. */
-  showLabel?: boolean;
-  /** Prop > `<UiKitProvider labels={{ topBarParts: { sync } }}>` > English. */
-  labels?: LabelOverride<SyncStatusLabels>;
-  /** The clock's language for "Synced at 14:05". Default: the provider's locale. */
-  locale?: string;
-  className?: string;
-  /** `data-*` attributes go on the trigger — a tour's anchor (`data-tour="sync-status"`). */
-  [key: `data-${string}`]: string | number | boolean | undefined;
-}
-
-/** The `data-*` attributes of a rest object, for a trigger. */
-function dataAttributes(rest: Record<string, unknown>): Record<string, unknown> {
-  return Object.fromEntries(Object.entries(rest).filter(([k]) => k.startsWith("data-")));
-}
-
-/**
- * The top bar's sync status (docs/top-bar-harmonization.md §2.6), lifted from keksdose's
- * `SyncStatusIndicator`: the seven states and their ranking ({@link syncState}), one cloud
- * per state, a ✓ badge when in sync and a spin while syncing. With `onSync` it is also the
- * "sync now" button, and its name says both what it is and what a tap does.
- *
- * Colours are the kit's roles — danger for a write that cannot be sent, warning for
- * anything waiting, info while syncing, success when in sync — where keksdose had raw
- * rose/amber/sky/emerald pairs.
- */
-export function SyncStatusIndicator({
-  status,
-  onSync,
-  hideWhenIdle = false,
-  scope,
-  showLabel = false,
-  labels: labelsProp,
-  locale: localeProp,
-  className,
-  storage = "device",
-  ...rest
-}: SyncStatusIndicatorProps) {
-  const words = useTopBarPartsLabels(labelsProp ? { sync: labelsProp } : undefined).sync;
-  const billing = useBillingLabels();
-  const locale = useKitLocale(localeProp);
-  // The tap's own round, local rather than in the app's store: the store's phase belongs
-  // to the sync engine, and a second writer would race the round itself.
-  const [refreshing, setRefreshing] = useState(false);
-  const mounted = useRef(true);
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-    };
-  }, []);
-
-  const onlineOnly = storage === "none";
-  // Online-only: nothing waits on the device, so only offline, error, saving and settled.
-  const state = syncState(onlineOnly ? { ...status, pending: 0, blocked: 0, waitingForPlan: 0 } : status, refreshing);
-  const data = dataAttributes(rest);
-  if (hideWhenIdle && state === "synced") return null;
-
-  const { Icon, tone } = LOOK[state];
-  const spin = state === "syncing";
-  let text: string;
-  switch (state) {
-    case "blocked":
-      text = words.blocked(status.blocked ?? 0);
-      break;
-    case "waitingForPlan":
-      text = billing.waitingChanges(status.waitingForPlan ?? 0);
-      break;
-    case "offline":
-      text = onlineOnly ? words.offlineUnsaved : words.offline;
-      break;
-    case "error":
-      text = words.refused;
-      break;
-    case "syncing":
-      text = onlineOnly ? words.saving : words.syncing;
-      break;
-    case "pending":
-      text = words.pending(status.pending);
-      break;
-    default:
-      text =
-        !onlineOnly && status.lastSyncedAt
-          ? words.syncedAt(
-              // A clock time in the UI's language, never the browser's (keksdose live #246).
-              new Date(status.lastSyncedAt).toLocaleTimeString(locale, { hour: "2-digit", minute: "2-digit" }),
-            )
-          : words.idle;
-  }
-  if (scope) {
-    text = state === "offline" && scope.offline ? scope.offline : words.scoped(scope.name, text);
-  }
-
-  const short =
-    state === "offline"
-      ? words.offlineShort
-      : state === "syncing"
-        ? onlineOnly
-          ? words.saving
-          : words.syncingShort
-        : state === "error"
-          ? words.refusedShort
-          : state === "pending" || state === "blocked" || state === "waitingForPlan"
-            ? words.waitingShort(
-                state === "pending"
-                  ? status.pending
-                  : state === "blocked"
-                    ? (status.blocked ?? 0)
-                    : (status.waitingForPlan ?? 0),
-              )
-            : null;
-
-  const offline = state === "offline";
-  const canSync = !!onSync && status.online && status.phase !== "offline" && !spin;
-  const name = onSync
-    ? canSync
-      ? words.withHint(text, words.syncHint)
-      : offline
-        ? words.withHint(text, words.offlineHint)
-        : text
-    : text;
-  const badge = state === "synced" ? <Check className="stroke-[3]" /> : undefined;
-  const glyph = <Icon aria-hidden className={spin ? "animate-spin" : undefined} />;
-
-  const sync = async () => {
-    if (!canSync || !onSync) return;
-    setRefreshing(true);
-    try {
-      await onSync();
-    } finally {
-      if (mounted.current) setRefreshing(false);
-    }
-  };
-
-  const control = onSync ? (
-    <IconButton
-      {...data}
-      data-sync-state={state}
-      size="2xs"
-      glyphSize={20}
-      shape="round"
-      // A status that is also an action: disabled (offline, mid-round) is exactly when
-      // the state matters most, so it keeps its colour.
-      disabledStyle="keep"
-      tone={tone}
-      quiet={false}
-      label={name}
-      labelVisible={false}
-      // Below: the bar is at the top edge, where a bubble above has no room.
-      tooltipSide="bottom"
-      onClick={() => void sync()}
-      disabled={!canSync}
-      // It announces itself as a status: a reader hears the state change.
-      aria-live="polite"
-      badge={badge}
-    >
-      {glyph}
-    </IconButton>
-  ) : (
-    <Tooltip label={name} side="bottom">
-      <span
-        {...data}
-        role="status"
-        data-sync-state={state}
-        className={cn(
-          "relative inline-flex size-9 shrink-0 items-center justify-center [&>svg]:size-5",
-          TEXT_TONE[tone],
-        )}
-      >
-        {glyph}
-        <span className="sr-only">{name}</span>
-        {badge && (
-          <span
-            aria-hidden
-            className="pointer-events-none absolute bottom-1.5 end-1.5 inline-flex rounded-full bg-surface [&_svg]:size-3"
-          >
-            {badge}
-          </span>
-        )}
-      </span>
-    </Tooltip>
-  );
-
-  if (!showLabel || !short)
-    return className ? <span className={cn("inline-flex", className)}>{control}</span> : control;
-  return (
-    <span className={cn("inline-flex items-center gap-1", className)}>
-      {control}
-      {/* The eye's short words; the name above already says it in full. */}
-      <span aria-hidden className={cn("whitespace-nowrap text-xs font-medium", TEXT_TONE[tone])}>
-        {short}
-      </span>
-    </span>
-  );
-}

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

@@ -1,87 +0,0 @@
-import { Fragment } from "react";
-import type { ReactNode } from "react";
-
-/**
- * The top bar's items by name (docs/top-bar-harmonization.md §2.1, §6.6). Each is the
- * app's own node — a kit part or its own — and any may be left out.
- */
-export interface TopBarActionsProps {
-  /** kastlan's `CompanySwitcher`: the context, first. */
-  companySwitcher?: ReactNode;
-  /** `GlobalSearch` (⌘K). */
-  search?: ReactNode;
-  /** `ThemeToggle`. */
-  theme?: ReactNode;
-  /** `FeedbackMenu`. */
-  feedback?: ReactNode;
-  /** `TourMenu`. */
-  tours?: ReactNode;
-  /** kastlan's assistant, beside the tours while it is on. */
-  assistant?: ReactNode;
-  /** `SyncStatusIndicator`. */
-  sync?: ReactNode;
-  /** `DevMenu` (0.51, docs/top-bar-harmonization.md §2.7.1): the one flask — the role,
-   *  the plan, then the app's own dev sections. Fill it only behind
-   *  `import.meta.env.DEV`, so a production build drops the branch. (0.42's
-   *  `DevSwitchers` was a DevMenu with no sections; removed in 0.52.) */
-  dev?: ReactNode;
-  /** kastlan's platform button. */
-  platform?: ReactNode;
-  /** 0.46 (docs/notifications-harmonization.md §10.1): `NotificationBell`, right before the
-   *  account menu. Optional per app: an app shows the bell or an unread dot on the avatar,
-   *  never both (keksdose keeps its dot and leaves this empty). */
-  notifications?: ReactNode;
-  /** The account menu. When it is set the signed-out slots are not drawn. */
-  account?: ReactNode;
-  /** Signed out (§6.6): the bar's `LanguageMenu`, since there is no account menu to hold
-   *  the language. Drawn only without `account`. */
-  language?: ReactNode;
-  /** Signed out (§6.6): the "Sign in" button, where the account menu would be. Drawn only
-   *  without `account`. */
-  signIn?: ReactNode;
-}
-
-/** §2.1's order, then the signed-out pair in the account menu's place. */
-export const TOP_BAR_ACTION_ORDER = [
-  "companySwitcher",
-  "search",
-  "theme",
-  "feedback",
-  "tours",
-  "assistant",
-  "sync",
-  "dev",
-  "platform",
-  "notifications",
-  "account",
-  "language",
-  "signIn",
-] as const satisfies readonly (keyof TopBarActionsProps)[];
-
-const present = (node: ReactNode) => node !== undefined && node !== null && node !== false && node !== "";
-
-/**
- * The top bar's actions in the one order every app shares (§2.1): company switcher ·
- * Search · Theme · Feedback · Tours (· Assistant) · Sync · dev role · dev plan · platform ·
- * notifications (the bell, 0.46) · account menu — and, signed out, Language · Sign in where the account menu goes (§6.6).
- * The app fills the slots it has; an empty slot is skipped, so it leaves no gap.
- *
- * It draws a fragment, no box of its own: hand it to `TopBar`'s `actions`, whose row
- * spaces the items.
- *
- * ```tsx
- * <TopBar brand={…} actions={<TopBarActions search={…} theme={…} tours={…} account={…} />} />
- * ```
- */
-export function TopBarActions(props: TopBarActionsProps) {
-  const signedOut = !present(props.account);
-  return (
-    <>
-      {TOP_BAR_ACTION_ORDER.map((slot) => {
-        if ((slot === "language" || slot === "signIn") && !signedOut) return null;
-        const node = props[slot];
-        return present(node) ? <Fragment key={slot}>{node}</Fragment> : null;
-      })}
-    </>
-  );
-}

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

@@ -1,78 +0,0 @@
-import type { ReactNode } from "react";
-import { Link as RouterLink } from "react-router";
-import { cn } from "../lib/cn";
-import { FOCUS_RING } from "../components/focus-ring";
-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-primary hover:opacity-80",
-        FOCUS_RING,
-        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);
-}