@eifi1/ui-kit 0.54.0 → 0.55.0

package/src/components/text-link.tsx

@@ -1,359 +0,0 @@
-import type { ComponentPropsWithoutRef, KeyboardEvent, MouseEvent, ReactElement, ReactNode, Ref } from "react";
-import { ExternalLink } from "lucide-react";
-import type { LucideIcon } from "lucide-react";
-import { cn } from "../lib/cn";
-import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLink } from "../i18n/kit-labels";
-import type { KitLinkComponent } from "../i18n/kit-labels";
-import { documentNavigation } from "../lib/document-navigation";
-
-/* ── Choosing what draws a link ──────────────────────────────────────────── */
-
-/**
- * An `href` that leaves the app: a scheme (`https:`, `mailto:`, `tel:`) or a
- * protocol-relative `//host`. A router's link is for paths inside the app, so the
- * provider's `linkComponent` is never handed one of these — they stay a plain `<a>`.
- *
- * NOT external, and so handed to the router link: a path (`/x`, `x`, `?q=1`) and the
- * hash-router form `#/x` — that IS a route in a `HashRouter` app, which maps it to
- * `to="/x"`. A plain in-page anchor (`#section`) is not external either, but it is not
- * a route: see {@link isInPageAnchor}.
- */
-export function isExternalHref(href: string): boolean {
-  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href);
-}
-
-/**
- * An `href` that only scrolls the current page: `#section` (or a bare `#`). The
- * hash-router form `#/x` is a ROUTE, not an anchor, and is not one of these. A router
- * link must not get an anchor — under a `HashRouter` `#section` would navigate to the
- * path `/section` — so every kit link draws it as a plain `<a>`.
- */
-export function isInPageAnchor(href: string): boolean {
-  return href.startsWith("#") && !href.startsWith("#/");
-}
-
-/**
- * Whether the provider's `linkComponent` (or a kit component's router fallback) draws
- * `href`: an in-app path, `#/x` included — not an external `href`
- * ({@link isExternalHref}) and not an in-page `#anchor` ({@link isInPageAnchor}).
- */
-export function isRoutableHref(href: string): boolean {
-  return !isExternalHref(href) && !isInPageAnchor(href);
-}
-
-/**
- * What draws a kit link to `href`: the component's own `renderLink` when it was given
- * one (it always wins — the caller asked for it by name), else the
- * `<UiKitProvider linkComponent>` for a routable `href` ({@link isRoutableHref}), else
- * `undefined` — a plain `<a>`. The one rule every kit link follows: `https:` /
- * `mailto:` / `//host` and `#section` stay plain anchors; `/x`, `x` and a hash-router
- * `#/x` go to the router link. Every kit link props type is a subset of the anchor
- * attributes `KitLinkProps` describes, which is what makes the cast sound.
- * @internal Shared by the kit's link-bearing components; not part of the barrel.
- */
-export function pickLinkRenderer<P>(
-  own: ((props: P) => ReactElement) | undefined,
-  kitLink: KitLinkComponent | undefined,
-  href: string | undefined,
-): ((props: P) => ReactElement) | undefined {
-  if (own) return own;
-  if (!kitLink || href === undefined || !isRoutableHref(href)) return undefined;
-  return kitLink as unknown as (props: P) => ReactElement;
-}
-
-/** The plain primary click a page navigates on — not a middle click, not ⌘ / Ctrl /
- *  Shift / Alt (new tab, new window, download), and not one a handler already took. */
-function isPlainNavigationClick(event: MouseEvent<HTMLAnchorElement>): boolean {
-  return (
-    !event.defaultPrevented &&
-    event.button === 0 &&
-    !event.metaKey &&
-    !event.ctrlKey &&
-    !event.shiftKey &&
-    !event.altKey
-  );
-}
-
-/**
- * The `onClick` of a PLAIN `<a>` whose kit link was asked to `replace` (keksdose F1).
- *
- * A router link replaces the history entry itself (it is handed `replace`, see
- * {@link routerLinkNavigation}); a plain `<a>` has no attribute that says so, and the
- * browser's own navigation always pushes. So a plain click is taken over — the caller's
- * `onClick` runs first and may still `preventDefault` — and becomes
- * `location.replace(href)`: the same document load, with Back skipping the one-shot URL.
- * That is the case of `replace` together with `reloadDocument`, or an app with no
- * `linkComponent`. A modified click (new tab) and a `target` other than `_self` are left
- * to the browser: they do not navigate THIS history. Without `replace`, `onClick` comes
- * back untouched.
- * @internal
- */
-export function replacingClick(
-  onClick: ((event: MouseEvent<HTMLAnchorElement>) => void) | undefined,
-  href: string,
-  replace: boolean | undefined,
-  target?: string,
-): ((event: MouseEvent<HTMLAnchorElement>) => void) | undefined {
-  if (!replace || (target !== undefined && target !== "" && target !== "_self")) return onClick;
-  return (event) => {
-    onClick?.(event);
-    if (!isPlainNavigationClick(event)) return;
-    event.preventDefault();
-    documentNavigation.replace(href);
-  };
-}
-
-/**
- * What a ROUTER link is handed for `replace`: `{ replace: true }` when asked, else
- * nothing at all — so a provider link that spreads its props onto a DOM `<a>` never
- * receives an unknown attribute from a link that did not ask (see `KitLinkProps.replace`).
- * @internal
- */
-export function routerLinkNavigation(replace: boolean | undefined): { replace?: true } {
-  return replace ? { replace: true } : {};
-}
-
-/**
- * Draws `props` through `render` as a component of its own, so a router link's hooks
- * belong to it and not to the kit component calling it — for the kit components that
- * call their own `renderLink` inline and reach the provider's link through here.
- * @internal
- */
-export function RenderedKitLink<P>({ render, props }: { render: (props: P) => ReactElement; props: P }) {
-  return render(props);
-}
-
-/* ── TextLink ─────────────────────────────────────────────────────────────── */
-
-/**
- * `brand` (default) for a link in running text, `muted` for footer and meta links
- * that should not compete with the content, `danger` for a destructive one ("Leave
- * group"), `inherit` for a link that takes its surroundings' colour.
- *
- * `primary` and `secondary` are the body and the secondary text colour, UNDERLINED
- * (keksdose F3): a link that must read as part of the text around it — a name in a
- * list row, a reference in a card's meta line — where `brand` repaints it in the accent
- * and `muted` is a step too light to read as content. `secondary` darkens to the body
- * colour under the pointer, as `muted` does; `primary` has nowhere darker to go, so its
- * underline thickens instead.
- *
- * `warning` is the kit's `--warning` text colour, underlined (kastlan 46): a link inside
- * a `<Tone tone="warning">` sentence or a warning banner, which `brand` would paint in a
- * second hue and `inherit` would leave indistinguishable from the sentence. Like
- * `primary`, it keeps its colour on hover and thickens the underline.
- *
- * The three colours that sit IN the text default to `underline="always"`: with the
- * colour of their surroundings, the underline is the only thing that says "link"
- * (WCAG 1.4.1). An explicit `underline` still wins.
- */
-export type TextLinkTone = "brand" | "muted" | "danger" | "inherit" | "primary" | "secondary" | "warning";
-
-/** `hover` (the default for `brand`, `muted`, `danger`, `inherit`): underlined under
- *  the pointer — the idiom all three apps draw. `always` (the default for `primary`,
- *  `secondary`, `warning`) for a link inside prose, where colour alone must not be the
- *  only mark (WCAG 1.4.1). `none` where the context already says "link" (a footer nav). */
-export type TextLinkUnderline = "hover" | "always" | "none";
-
-/** The `aria-current` token. `true` on {@link TextLinkProps.current} means `page`. */
-export type TextLinkCurrent = "page" | "step" | "location" | "date" | "time" | "true";
-
-/** What {@link TextLinkProps.renderLink} (and the provider's `linkComponent`) is
- *  handed. Spread it onto your router's link — `({ href, ...p }) => <Link to={href} {...p} />`. */
-export interface TextLinkRenderProps {
-  href: string;
-  /** The link's look — keep it, or the tone, underline and focus ring go. */
-  className: string;
-  children: ReactNode;
-  ref?: Ref<HTMLAnchorElement>;
-  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
-  onKeyDown?: (event: KeyboardEvent<HTMLAnchorElement>) => void;
-  "aria-current"?: TextLinkCurrent;
-  id?: string;
-  title?: string;
-  /** Present, as `true`, only when the link was given `replace` — see
-   *  `KitLinkProps.replace`. Map it to your router's replace; never onto a DOM `<a>`. */
-  replace?: boolean;
-  [key: `aria-${string}`]: string | boolean | number | undefined;
-  [key: `data-${string}`]: unknown;
-}
-
-export interface TextLinkProps extends Omit<
-  ComponentPropsWithoutRef<"a">,
-  "href" | "children" | "aria-current" | "onClick" | "onKeyDown"
-> {
-  href: string;
-  children: ReactNode;
-  /** Default `brand`. */
-  tone?: TextLinkTone;
-  /** Default `always` for `primary`, `secondary` and `warning`, else `hover`. */
-  underline?: TextLinkUnderline;
-  /**
-   * Navigate by replacing the current history entry, so Back does not return to this
-   * URL — keksdose F1, a one-shot URL (a confirmation landing, a `?done=1` hop). Handed
-   * to the router link as `replace` (see `KitLinkProps.replace` for mapping it); on a
-   * plain `<a>` (no `linkComponent`, or `reloadDocument`) a plain click becomes
-   * `location.replace(href)`. Ignored on an `external` link, which opens a new tab.
-   */
-  replace?: boolean;
-  /**
-   * A plain `<a>` for an in-app `href`: the browser loads the whole document instead of
-   * the router swapping the view — keksdose F1, a route served outside the SPA (a file
-   * download, a server-rendered page, a logout that must drop every in-memory cache).
-   * Wins over `renderLink` and the provider's `linkComponent`: it is the caller saying
-   * "not the router" for this one link.
-   */
-  reloadDocument?: boolean;
-  /**
-   * The link leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`
-   * (never the router's), an external-link mark after the text (mirrored in RTL), and
-   * "opens in a new tab" (`common.opensInNewTab`) read after it — the mark says it
-   * only to the eye. kastlan's BWO / BFS source links (rent-increase-calculator-page).
-   */
-  external?: boolean;
-  /**
-   * Keep the click (and the Enter that activates the link) from reaching an ancestor —
-   * a link in a DataTable row with `onRowClick` goes to its own target instead of
-   * running the row's action. kastlan's `CellLink` did this by hand.
-   */
-  stopPropagation?: boolean;
-  /** Mark the link as the current one of a set — `true` is `aria-current="page"`, the
-   *  legal footer's link to the page you are on. Drawn in semibold. */
-  current?: boolean | TextLinkCurrent;
-  /** A Lucide icon before the text, at the text's size — kastlan's "← Back" link. */
-  icon?: LucideIcon;
-  /** Your router's link for an in-app `href`. Default: the `<UiKitProvider
-   *  linkComponent>`, then a plain `<a>`. Ignored on an `external` link. */
-  renderLink?: (props: TextLinkRenderProps) => ReactElement;
-  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
-  onKeyDown?: (event: KeyboardEvent<HTMLAnchorElement>) => void;
-  ref?: Ref<HTMLAnchorElement>;
-}
-
-const TONE: Record<TextLinkTone, string> = {
-  // Under More contrast the brand as text, `--brand-muted`, at rest and hovered (0.36,
-  // colour-roles §13.3 decision 8): `--brand` is a mark's colour, solved to 3:1.
-  brand: "text-brand hover:text-[var(--brand-hover)] contrast:text-brand-muted contrast:hover:text-brand-muted",
-  muted: "text-muted hover:text-primary",
-  danger: "text-danger hover:text-[var(--danger-hover)]",
-  inherit: "",
-  primary: "text-primary hover:decoration-2",
-  secondary: "text-secondary hover:text-primary",
-  warning: "text-warning hover:decoration-2",
-};
-
-/** The tones whose colour is their surroundings' — underlined by default; see
- *  {@link TextLinkTone}. */
-const UNDERLINED_BY_DEFAULT = new Set<TextLinkTone>(["primary", "secondary", "warning"]);
-
-const UNDERLINE: Record<TextLinkUnderline, string> = {
-  hover: "no-underline hover:underline",
-  always: "underline",
-  none: "no-underline",
-};
-
-/**
- * The one inline link: a real `<a href>` (middle click, "open in new tab", link
- * semantics) through the app's router for an in-app path, in one of four tones.
- *
- * kastlan draws this link a dozen ways by hand — `EntityLink` and `CellLink` (text-primary,
- * hover underline, one stopping the row click), the legal pages' back link and footer,
- * the feedback page's URL links, the calculator's external sources with a hand-placed
- * ↗ and no word for a screen reader — and the lease wizard's unit step (lease-unit-step)
- * used a raw `<a>` to an in-app route, which reloads the whole app. Here the router
- * link comes from `<UiKitProvider linkComponent>`, set once.
- *
- * Inline, not `inline-flex`: a link inside a sentence must wrap with it. The icons sit
- * on the text's baseline at the text's size, so they scale with whatever type the link
- * is set in. The focus ring is an outline, which follows every line of a wrapped link.
- */
-export function TextLink({
-  href,
-  children,
-  tone = "brand",
-  underline: underlineProp,
-  external = false,
-  replace,
-  reloadDocument = false,
-  stopPropagation = false,
-  current,
-  icon: Icon,
-  renderLink,
-  className,
-  onClick,
-  onKeyDown,
-  ref,
-  ...rest
-}: TextLinkProps) {
-  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
-  const kitLink = useKitLink();
-  const underline = underlineProp ?? (UNDERLINED_BY_DEFAULT.has(tone) ? "always" : "hover");
-  const ariaCurrent: TextLinkCurrent | undefined = current === true ? "page" : current === false ? undefined : current;
-
-  const look = cn(
-    "rounded-sm underline-offset-2 transition-colors",
-    "focus-visible:outline-focus focus-visible:outline-offset-2 focus-visible:outline-brand",
-    TONE[tone],
-    UNDERLINE[underline],
-    ariaCurrent && "font-semibold",
-    className,
-  );
-
-  const body = (
-    <>
-      {Icon && <Icon aria-hidden className="me-1 inline size-[1em] shrink-0 align-[-0.125em]" />}
-      {children}
-      {external && (
-        <>
-          <ExternalLink aria-hidden className="ms-1 inline size-[0.85em] align-[-0.1em] rtl:-scale-x-100" />{" "}
-          <span className="sr-only">({common.opensInNewTab})</span>
-        </>
-      )}
-    </>
-  );
-
-  const handleClick: TextLinkRenderProps["onClick"] = stopPropagation
-    ? (event) => {
-        event.stopPropagation();
-        onClick?.(event);
-      }
-    : onClick;
-  const props: TextLinkRenderProps = {
-    ...(rest as Partial<TextLinkRenderProps>),
-    ref,
-    href,
-    className: look,
-    "aria-current": ariaCurrent,
-    onClick: handleClick,
-    onKeyDown: stopPropagation
-      ? (event) => {
-          if (event.key === "Enter") event.stopPropagation();
-          onKeyDown?.(event);
-        }
-      : onKeyDown,
-    children: body,
-  };
-
-  const render = external || reloadDocument ? undefined : pickLinkRenderer(renderLink, kitLink, href);
-  if (render) return <RenderedTextLink render={render} {...props} {...routerLinkNavigation(replace)} />;
-  // A plain `<a>` never gets `replace` as an attribute; asked for, it takes the click.
-  const plainClick = external ? handleClick : replacingClick(handleClick, href, replace, rest.target);
-  const { children: content, ...anchor } = props;
-  return (
-    <a
-      {...anchor}
-      href={href}
-      onClick={plainClick}
-      {...(external ? { target: "_blank", rel: "noopener noreferrer" } : null)}
-    >
-      {content}
-    </a>
-  );
-}
-
-/** Calls the link renderer as a component, so a router link's hooks are its own. */
-function RenderedTextLink({
-  render,
-  ...props
-}: TextLinkRenderProps & { render: (props: TextLinkRenderProps) => ReactElement }) {
-  return render(props);
-}

package/src/components/text.tsx

@@ -1,150 +0,0 @@
-import type { ComponentPropsWithoutRef, ElementType, ReactNode, Ref } from "react";
-import { cn } from "../lib/cn";
-
-/* ── SectionLabel ─────────────────────────────────────────────────────────── */
-
-/**
- * `xs` is 10px — the size `LegendGroup`'s title and the top-bar menus' heading row draw;
- * `sm` (default) is 12px — the size `StatTile`'s label and lenkbank's section headings
- * (control-page.tsx:119/123/127) draw. Two sizes because the label sits either inside a
- * dense panel (a legend, a menu) or above a block of page content, and one size looked
- * wrong in the other place.
- *
- * `md` (0.11.0) is 11px, the rung between them: keksdose's budget-summary card labels
- * its figures ("Assigned", "Activity", "Upcoming", "Available" —
- * budget-summary-card:258/264/286/297) and its support thread its day divider and a message's meta line
- * (support-thread:153/223) at `text-[11px]` by hand — 10px read as a footnote under a
- * figure that size, 12px competed with it. Named `md` rather than slotted in order
- * because `sm` was already the default and renaming it would move every caller.
- *
- * `md` is also the heading over a CHART COLUMN (lenkbank P9): the small label centred
- * over each of a pair of facing charts, or over each column of a small-multiples grid.
- * There the label names a plot, not a section of the page, so `sm` (12px, the page's
- * section heading) out-ranks the card title above it, and `xs` (10px, a legend's
- * title) sinks below the axis ticks it sits beside. Rule of thumb: `xs` inside a
- * control (legend, menu), `md` over a figure or a plot, `sm` over a block of page
- * content.
- */
-export type SectionLabelSize = "xs" | "md" | "sm";
-
-/**
- * The small, uppercase, tracked, muted label — as a class string, per size.
- *
- * Exported because `LegendGroup` and `StatTile` already draw it inline, and a class a
- * caller has to position itself (a `<th>`, a `<legend>`, a menu `<li>`) is better
- * reached as a string than wrapped in a component that only takes a `className`. The
- * uppercase is CSS, so a screen reader reads the text as written: write it in normal
- * case.
- *
- * The sizes are the kit's named rem steps since 0.32 (`text-micro` 0.625rem,
- * `text-caption` 0.6875rem — 10 and 11 px at Normal), so a label grows with the text
- * size like everything around it (docs/text-size-harmonization.md §3.2).
- */
-export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
-  xs: "text-micro font-semibold uppercase tracking-wide text-muted",
-  md: "text-caption font-semibold uppercase tracking-wide text-muted",
-  sm: "text-xs font-semibold uppercase tracking-wide text-muted",
-};
-
-/**
- * `plain` (default): the label alone, as above.
- *
- * `band` (0.13, keksdose F5): the label on a full-width `surface-2` bar with a bottom
- * border — the day-group header of keksdose's mobile transaction list
- * (mobile-transaction-list.tsx:171), which separates one day's rows from the next.
- * Its type is kept as keksdose drew it — `font-medium` in the SECONDARY text colour,
- * not the plain label's semibold muted — so adopting the kit does not restyle a live
- * list: the bar already sets the label apart, and needs no extra weight. The padding (`px-4 py-2`) lines the text up with a
- * `ListItem density="comfortable"` row below it; override it with `className` for a
- * list at another density. A sticky header is the caller's: add `sticky top-0`.
- */
-export type SectionLabelVariant = "plain" | "band";
-
-/** The band's own type and box, per size — spelled out rather than merged over
- *  {@link SECTION_LABEL_CLASS}, so the result does not hang on tailwind-merge telling
- *  a font-size arbitrary `text-` value from a colour one. (Not spelt out as class
- *  names here: Tailwind scans comments, and a literal one broke the showcase CSS.) */
-const SECTION_LABEL_BAND_CLASS: Record<SectionLabelSize, string> = {
-  xs: "text-micro",
-  md: "text-caption",
-  sm: "text-xs",
-};
-const BAND = "block border-b border-subtle bg-surface-2 px-4 py-2 font-medium uppercase tracking-wide text-secondary";
-
-type SectionLabelElement = "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "div" | "legend";
-
-export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
-  /**
-   * The element — which is the heading LEVEL, and so is the caller's to pick: the kit
-   * cannot know where in the outline the label sits. Default `h3`, which is what
-   * lenkbank's control page writes under its `h2` card title. Pass `span` or `p` for a
-   * label that is not a heading at all (a legend group's title).
-   */
-  as?: SectionLabelElement;
-  size?: SectionLabelSize;
-  /** `band` draws the label on a `surface-2` bar with a bottom border — a list's group
-   *  header. See {@link SectionLabelVariant}. */
-  variant?: SectionLabelVariant;
-  children: ReactNode;
-  /** The element `as` names — hence `HTMLElement` (0.34, API-2, refactor audit 2026-10). */
-  ref?: Ref<HTMLElement>;
-}
-
-/**
- * A section's small uppercase label. lenkbank spells
- * `text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400`
- * on every `<h3>` of its control page and more; keksdose's budget switcher writes the
- * 10px version on a menu row. One component, the token colour, and the level chosen
- * where the outline is known.
- */
-export function SectionLabel({
-  as = "h3",
-  size = "sm",
-  variant = "plain",
-  className,
-  children,
-  ...rest
-}: SectionLabelProps) {
-  const Tag = as as ElementType;
-  const type = variant === "band" ? cn(SECTION_LABEL_BAND_CLASS[size], BAND) : SECTION_LABEL_CLASS[size];
-  return (
-    <Tag {...rest} className={cn(type, className)}>
-      {children}
-    </Tag>
-  );
-}
-
-/* ── Caption ──────────────────────────────────────────────────────────────── */
-
-/**
- * The caption type as a class string: `text-caption` (0.6875rem, 11 px at Normal, §3.2),
- * snug, muted. lenkbank's `CAPTION`
- * (shared/ui/caption.ts:23) — written out 31 times before it was a constant — as a
- * token colour rather than `slate-500 dark:slate-400`, so it follows the palette.
- * Exported for the same reason lenkbank's is a string: every caller positions it
- * differently (`mt-1`, `self-end pb-2`, `border-t`), and what must be one thing is the
- * type, not the box.
- */
-export const CAPTION_CLASS = "text-caption leading-snug text-muted";
-
-export interface CaptionProps extends ComponentPropsWithoutRef<"p"> {
-  /** Default `p`; `span` for a caption inside a line of other content. */
-  as?: "p" | "span" | "div";
-  children: ReactNode;
-  /** The element `as` names — hence `HTMLElement` (0.34, API-2, refactor audit 2026-10). */
-  ref?: Ref<HTMLElement>;
-}
-
-/**
- * The small grey sentence under a field, a table or a button — prose ABOUT the thing
- * above it. Not `FieldHint`, which hides behind a field label's "?" so a paragraph does
- * not make one field taller than its neighbour (lenkbank feedback #27).
- */
-export function Caption({ as = "p", className, children, ...rest }: CaptionProps) {
-  const Tag = as as ElementType;
-  return (
-    <Tag {...rest} className={cn(CAPTION_CLASS, className)}>
-      {children}
-    </Tag>
-  );
-}