@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/components/skeleton.tsx

@@ -21,6 +21,13 @@ export interface SkeletonProps extends Omit<ComponentPropsWithoutRef<"div">, "ch
   shape?: SkeletonShape;
   /** For `line`: this many lines, the last one shorter — a paragraph's outline. */
   lines?: number;
+  /**
+   * Say what is loading, once: wraps the placeholder in a `role="status"` region with
+   * this as its (visually hidden) text — kastlan's activity feed (activity-feed:52)
+   * built exactly that by hand around `<Skeleton lines={5} />`. The placeholder itself
+   * stays hidden. Left out, nothing is announced, as before.
+   */
+  label?: string;
 }
 
 const SHAPE: Record<SkeletonShape, string> = {
@@ -37,10 +44,21 @@ const SHAPE: Record<SkeletonShape, string> = {
  *
  * ALWAYS `aria-hidden`. A placeholder is not content, and a reader that met twelve
  * unnamed grey boxes would have learned nothing. Say "loading" once, where it
- * belongs: `aria-busy` on the region being filled, or a `Spinner` / sr-only line
- * beside the skeletons.
+ * belongs: `aria-busy` on the region being filled, a `Spinner` / sr-only line
+ * beside the skeletons, or this component's own `label`.
  */
-export function Skeleton({ shape = "line", lines, className, ...rest }: SkeletonProps) {
+export function Skeleton({ label, ...props }: SkeletonProps) {
+  if (!label) return <SkeletonFill {...props} />;
+  return (
+    // `relative`: the containing block for the sr-only text (sr-only-containment.test).
+    <div role="status" className="relative" data-skeleton-status="">
+      <span className="sr-only">{label}</span>
+      <SkeletonFill {...props} />
+    </div>
+  );
+}
+
+function SkeletonFill({ shape = "line", lines, className, ...rest }: Omit<SkeletonProps, "label">) {
   if (shape === "line" && lines !== undefined && lines > 1) {
     return (
       <div {...rest} aria-hidden className={cn("flex flex-col gap-2", className)} data-skeleton="lines">

package/src/components/stat-tile.tsx

@@ -2,7 +2,8 @@ import { isValidElement, useId, useLayoutEffect, useState } from "react";
 import type { ComponentPropsWithoutRef, CSSProperties, ReactElement, ReactNode } from "react";
 import { ArrowDown, ArrowUp, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink, useKitLocale } from "../i18n/kit-labels";
+import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 import { Card, FieldHint } from "./ui";
 import { Sparkline } from "./sparkline";
 import { Tooltip } from "./tooltip";
@@ -219,7 +220,8 @@ export interface StatTileProps
   /** Makes the tile a link. See {@link renderLink} for a router. */
   href?: string;
   /** Renders the link for `href` — pass your router's `<Link>` here, since a plain
-   *  `<a>` reloads a single-page app. Default: `<a>`. */
+   *  `<a>` reloads a single-page app. Default: the `<UiKitProvider linkComponent>`
+   *  (for an in-app `href`), then `<a>`. */
   renderLink?: (props: StatTileLinkProps) => ReactElement;
   /** Makes the tile a button (ignored when `href` is given). */
   onClick?: () => void;
@@ -297,6 +299,7 @@ export function StatTile({
   ...rest
 }: StatTileProps) {
   const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
+  const kitLink = useKitLink();
   const [labelEl, setLabelEl] = useState<HTMLElement | null>(null);
   const labelCut = useIsTruncated(truncateLabel ? labelEl : null);
   const kitLocale = useKitLocale(locale);
@@ -334,8 +337,11 @@ export function StatTile({
       "aria-describedby": describedBy,
       children: label,
     };
+    const kit = pickLinkRenderer<StatTileLinkProps>(undefined, kitLink, href);
     labelNode = renderLink ? (
       renderLink(linkProps)
+    ) : kit ? (
+      <RenderedKitLink render={kit} props={linkProps} />
     ) : (
       <a href={href} className={stretched} aria-describedby={describedBy}>
         {label}

package/src/components/table.tsx

@@ -29,10 +29,21 @@ export type TableHeaderCellSize = "xs" | "sm";
 /** The header cell's weight. Default `medium`. */
 export type TableHeaderCellWeight = "normal" | "medium" | "semibold";
 
+/**
+ * What a {@link TableRow} is in a statement-style table (0.12.0): an ordinary `row`, a
+ * `group` heading ("Current assets", a tinted full-width label row), a `subtotal` under
+ * a group, or the `total` of the whole table. kastlan's balance sheet, income statement
+ * and journal entry each spelled these as `className="font-medium"`, `"font-bold
+ * border-t-2"` and `bg-muted/50` on the cell — three pages, three sets of classes for
+ * the same four kinds of line.
+ */
+export type TableRowVariant = "row" | "group" | "subtotal" | "total";
+
 interface TableContextValue {
   density: TableDensity;
   zebra: boolean;
   hover: boolean;
+  rowDividers: boolean;
   captionId: string;
   registerCaption: () => () => void;
 }
@@ -41,12 +52,44 @@ const TableContext = createContext<TableContextValue>({
   density: "comfortable",
   zebra: false,
   hover: false,
+  rowDividers: true,
   captionId: "",
   registerCaption: () => () => {},
 });
 
-/** Which section a row sits in — zebra and hover apply to body rows only. */
-const SectionContext = createContext<"head" | "body" | "foot">("body");
+type TableSection = "head" | "body" | "foot";
+
+/** Which section a row sits in — zebra and hover apply to body rows only. `undefined`
+ *  outside the kit's section parts: a raw `<thead>` / `<tbody>`, which
+ *  {@link useSection} then reads off the DOM. */
+const SectionContext = createContext<TableSection | undefined>(undefined);
+
+const SECTION_OF_TAG: Record<string, TableSection> = { THEAD: "head", TBODY: "body", TFOOT: "foot" };
+
+/**
+ * The section a row or cell sits in: the kit part's context where there is one, else the
+ * nearest `<thead>` / `<tbody>` / `<tfoot>` in the DOM.
+ *
+ * keksdose's VAT summary writes a raw `<thead>` round kit cells in places, and a
+ * `TableHeaderCell` there took itself for a BODY cell — `scope="row"`, body type — with
+ * nothing on the page to say why. React cannot see an ancestor's tag, so the fallback
+ * reads it after mount; a layout effect, so the corrected cell is what gets painted.
+ */
+function useSection<E extends HTMLElement>(): [TableSection, ((el: E | null) => void) | undefined] {
+  const fromContext = useContext(SectionContext);
+  const [node, setNode] = useState<E | null>(null);
+  const [detected, setDetected] = useState<TableSection | undefined>(undefined);
+  useLayoutEffect(() => {
+    if (fromContext !== undefined || !node) return;
+    const section = node.closest("thead, tbody, tfoot");
+    const found = section ? SECTION_OF_TAG[section.tagName] : undefined;
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- read off the DOM, which only exists after mount
+    if (found !== detected) setDetected(found);
+  }, [fromContext, node, detected]);
+  // No ref at all under a kit section: holding the node would cost every row and cell
+  // a second render on mount for an answer the context already gave.
+  return [fromContext ?? detected ?? "body", fromContext === undefined ? setNode : undefined];
+}
 
 /** A {@link TableRow}'s `valign`, which its cells take unless they set their own. It
  *  cannot be left to CSS inheritance: every cell states its own default alignment,
@@ -102,6 +145,22 @@ export interface TableProps extends ComponentPropsWithoutRef<"table"> {
   wrapperClassName?: string;
   /** See {@link TableLayout}. Unset leaves the browser's `auto` and adds no class. */
   layout?: TableLayout;
+  /**
+   * A rounded border round the whole table (0.12.0) — for a table standing on the page
+   * or in a dialog rather than inside a card. kastlan wraps six of them in
+   * `<div className="rounded-md border">` by hand (payment allocation, the new-budget
+   * lines, the meter readings, the deposit transactions, the unit values editor, the
+   * maintenance detail), and a hand-made frame outside the scroll wrapper does not clip
+   * the rows' tint to its corners.
+   */
+  framed?: boolean;
+  /**
+   * The rule between body rows. Default true. `false` for a small table whose rows are
+   * spaced by their own content — keksdose's VAT summary, a block of three quiet
+   * columns inside a card — which otherwise had to drop to raw `<tr>`s to lose it. One
+   * row can still say otherwise with {@link TableRowProps.bordered}.
+   */
+  rowDividers?: boolean;
 }
 
 /**
@@ -127,6 +186,8 @@ export function Table({
   hover = false,
   wrapperClassName,
   layout,
+  framed = false,
+  rowDividers = true,
   className,
   "aria-label": ariaLabel,
   ...rest
@@ -141,13 +202,14 @@ export function Table({
       density,
       zebra,
       hover,
+      rowDividers,
       captionId,
       registerCaption: () => {
         setCaptions((n) => n + 1);
         return () => setCaptions((n) => n - 1);
       },
     }),
-    [density, zebra, hover, captionId],
+    [density, zebra, hover, rowDividers, captionId],
   );
 
   const regionName = captions > 0 ? { "aria-labelledby": captionId } : ariaLabel ? { "aria-label": ariaLabel } : null;
@@ -163,9 +225,13 @@ export function Table({
         tabIndex={overflowing ? 0 : undefined}
         data-overflowing={overflowing || undefined}
         data-clips=""
+        data-framed={framed || undefined}
         className={cn(
           // `relative`: the containing block for an `sr-only` caption.
           "relative w-full overflow-x-auto",
+          // On the scroll wrapper itself, so its clipping keeps the rows inside the
+          // rounded corners.
+          framed && "rounded-md border border-[var(--border)]",
           THIN_SCROLLBAR_CLASS,
           "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
           wrapperClassName,
@@ -187,12 +253,16 @@ export function Table({
   );
 }
 
-export type TableHeadProps = ComponentPropsWithoutRef<"thead">;
+export interface TableHeadProps extends ComponentPropsWithoutRef<"thead"> {
+  /** The rule under the head. Default true; `false` for a quiet header over a small
+   *  table (keksdose's VAT summary wrote `className="border-b-0"` to lose it). */
+  bordered?: boolean;
+}
 
-export function TableHead({ className, ...rest }: TableHeadProps) {
+export function TableHead({ bordered = true, className, ...rest }: TableHeadProps) {
   return (
     <SectionContext.Provider value="head">
-      <thead {...rest} className={cn("border-b border-[var(--border)]", className)} />
+      <thead {...rest} className={cn(bordered && "border-b border-[var(--border)]", className)} />
     </SectionContext.Provider>
   );
 }
@@ -290,24 +360,42 @@ export function TableFoot({ className, ...rest }: TableFootProps) {
   );
 }
 
+const ROW_VARIANT: Record<TableRowVariant, string | false> = {
+  row: false,
+  group: "bg-[var(--bg-surface-2)] font-semibold",
+  subtotal: "font-medium",
+  // A 2px rule over the 1px divider the row above draws on its bottom: collapsed
+  // borders meet on one line, the wider wins, and the heavier rule is what says "sum".
+  total: "border-t-2 border-t-[var(--border-strong)] font-semibold",
+};
+
 /** The deprecated HTML `valign` attribute is replaced by a class-backed one. */
 export interface TableRowProps extends ComponentPropsWithoutRef<"tr"> {
   /** Vertical alignment for every cell of the row that does not set its own. See
    *  {@link TableVAlign}. Left out, each cell keeps its default. */
   valign?: TableVAlign;
+  /** See {@link TableRowVariant}. Default `row`. Zebra and hover tint ordinary rows
+   *  only: a group heading or a total is not one more record. */
+  variant?: TableRowVariant;
+  /** The rule under this body row. Default: the table's `rowDividers`. */
+  bordered?: boolean;
 }
 
-export function TableRow({ valign, className, ...rest }: TableRowProps) {
-  const { zebra, hover } = useContext(TableContext);
-  const section = useContext(SectionContext);
+export function TableRow({ valign, variant = "row", bordered, className, ...rest }: TableRowProps) {
+  const { zebra, hover, rowDividers } = useContext(TableContext);
+  const [section, ref] = useSection<HTMLTableRowElement>();
   const body = section === "body";
+  const record = body && variant === "row";
   const row = (
     <tr
+      ref={ref}
       {...rest}
+      data-variant={variant === "row" ? undefined : variant}
       className={cn(
-        body && "border-b border-[var(--border)]",
-        body && zebra && "even:bg-[var(--bg-surface-2)]",
-        body && hover && "transition-colors hover:bg-[var(--bg-hover)]",
+        body && (bordered ?? rowDividers) && "border-b border-[var(--border)]",
+        record && zebra && "even:bg-[var(--bg-surface-2)]",
+        record && hover && "transition-colors hover:bg-[var(--bg-hover)]",
+        ROW_VARIANT[variant],
         // On the row as well, for a raw `<td>` of the caller's, which inherits it.
         valign && VALIGN[valign],
         className,
@@ -356,12 +444,13 @@ export function TableHeaderCell({
   ...rest
 }: TableHeaderCellProps) {
   const { density } = useContext(TableContext);
-  const section = useContext(SectionContext);
+  const [section, ref] = useSection<HTMLTableCellElement>();
   const rowVAlign = useContext(RowVAlignContext);
   const head = section === "head";
   const textSize = size ?? (head ? "xs" : undefined);
   return (
     <th
+      ref={ref}
       {...rest}
       scope={scope ?? (section === "head" ? "col" : "row")}
       className={cn(

package/src/components/text-link.tsx

@@ -0,0 +1,248 @@
+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";
+
+/* ── 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;
+}
+
+/**
+ * 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. */
+export type TextLinkTone = "brand" | "muted" | "danger" | "inherit";
+
+/** `hover` (default): underlined under the pointer — the idiom all three apps draw.
+ *  `always` 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;
+  [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 `hover`. */
+  underline?: TextLinkUnderline;
+  /**
+   * 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> = {
+  brand: "text-[var(--brand)] hover:text-[var(--brand-hover)]",
+  muted: "text-[var(--text-muted)] hover:text-[var(--text-primary)]",
+  danger: "text-[var(--danger)] hover:text-[var(--danger-hover)]",
+  inherit: "",
+};
+
+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 = "hover",
+  external = false,
+  stopPropagation = false,
+  current,
+  icon: Icon,
+  renderLink,
+  className,
+  onClick,
+  onKeyDown,
+  ref,
+  ...rest
+}: TextLinkProps) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const kitLink = useKitLink();
+  const ariaCurrent: TextLinkCurrent | undefined =
+    current === true ? "page" : current === false ? undefined : current;
+
+  const look = cn(
+    "rounded-sm underline-offset-2 transition-colors",
+    "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--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 props: TextLinkRenderProps = {
+    ...(rest as Partial<TextLinkRenderProps>),
+    ref,
+    href,
+    className: look,
+    "aria-current": ariaCurrent,
+    onClick: stopPropagation
+      ? (event) => {
+          event.stopPropagation();
+          onClick?.(event);
+        }
+      : onClick,
+    onKeyDown: stopPropagation
+      ? (event) => {
+          if (event.key === "Enter") event.stopPropagation();
+          onKeyDown?.(event);
+        }
+      : onKeyDown,
+    children: body,
+  };
+
+  const render = external ? undefined : pickLinkRenderer(renderLink, kitLink, href);
+  if (render) return <RenderedTextLink render={render} {...props} />;
+  const { children: content, ...anchor } = props;
+  return (
+    <a {...anchor} {...(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/toggle-group.tsx

@@ -2,7 +2,7 @@ import { useId } from "react";
 import type { ComponentPropsWithoutRef, KeyboardEvent, ReactElement, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
-import { FIELD_INVALID, FloatingField } from "./ui";
+import { FIELD_INVALID, FloatingField, Label } from "./ui";
 
 export interface ToggleOption<T extends string> {
   value: T;
@@ -67,6 +67,19 @@ export interface ToggleGroupBaseProps<T extends string>
    * group's own box is dropped: two nested borders read as a control in a control.
    */
   label?: ReactNode;
+  /**
+   * Where `label` goes. `"field"` (default): the field chrome described under `label`.
+   * `"above"`: the kit's {@link Label} over the bare group — the shape of a {@link Field}
+   * — with `hint` beside the label and `error` under the group, for a form that sets
+   * its labels above its fields (kastlan's international-rent-calculator.tsx, whose DE
+   * cap pair sits in a `Field` column between two labelled-above inputs, where the
+   * chrome's inner label would be the only one of its kind).
+   *
+   * Inside a `Field`, pass no `label` at all and spread the render-prop instead —
+   * `{(ids, { labelId }) => <ToggleGroup {...ids} aria-labelledby={labelId} … />}` —
+   * so the Field's label names the group and its hint and error describe it.
+   */
+  labelPlacement?: "field" | "above";
   /** A {@link FieldHint} on the label line, as on a labelled {@link Select}. Only with
    *  `label`. */
   hint?: ReactNode;
@@ -143,6 +156,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     disabled = false,
     size = "md",
     label,
+    labelPlacement = "field",
     hint,
     error,
     "aria-label": ariaLabelAttr,
@@ -150,11 +164,17 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   } = props;
   const labelId = useId();
   const errorId = useId();
-  const field = label !== undefined && label !== null && label !== false && label !== "";
-  const hasError = field && error !== undefined && error !== null && error !== false && error !== "";
+  const labelled = label !== undefined && label !== null && label !== false && label !== "";
+  // `field` is the chrome; a label placed above keeps the bare group's own box.
+  const field = labelled && labelPlacement === "field";
+  const above = labelled && labelPlacement === "above";
+  const hasError = labelled && error !== undefined && error !== null && error !== false && error !== "";
   // Taken off the rest so neither reaches the DOM; `props` keeps them paired, which is
   // what lets the `onChange` below be called with `null` only in the mode that allows it.
   const { allowEmpty: _allowEmpty, onChange: _onChange, caption, ...rest } = restWithMode;
+  // Invalid from outside too: a `Field` hands the bare group `aria-invalid`, and the
+  // border has to say what the attribute says.
+  const outsideInvalid = rest["aria-invalid"] === true || rest["aria-invalid"] === "true";
   const captionId = useId();
   const captionIsLive = typeof caption === "function";
   const captionNode = captionIsLive ? (caption as (v: T | null) => ReactNode)(value) : caption;
@@ -202,7 +222,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       // The DOM spelling wins; `ariaLabel` is the fallback for the call sites that
       // have not moved yet.
       aria-label={ariaLabelAttr ?? ariaLabel}
-      aria-labelledby={field && ariaLabelAttr === undefined && ariaLabel === undefined ? labelId : rest["aria-labelledby"]}
+      aria-labelledby={labelled && ariaLabelAttr === undefined && ariaLabel === undefined ? labelId : rest["aria-labelledby"]}
       aria-invalid={hasError || rest["aria-invalid"] || undefined}
       aria-describedby={
         [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || undefined
@@ -229,10 +249,12 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         // package does; `cursor-not-allowed` is on the buttons, which is what a
         // pointer is actually over.
         disabled && "opacity-60",
+        // The bare group (no chrome to paint) wears the invalid border itself.
+        !field && (outsideInvalid || (above && hasError)) && FIELD_INVALID,
         // Inside the field's chrome the group is only a row of segments: no border, no
         // surface, no padding of its own, and the field (not the group) is what dims.
         field && "border-0 bg-transparent p-0 shadow-none opacity-100",
-        !field && className,
+        !labelled && className,
       )}
     >
       {options.map((opt, index) => {
@@ -308,6 +330,36 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         {hasCaption ? captionNode : null}
       </p>
     ) : null;
+  const errorEl = hasError ? (
+    <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
+      {error}
+    </p>
+  ) : null;
+  if (above) {
+    // `relative` so a caller's `sr-only` label cannot escape (sr-only-containment).
+    return (
+      <div className={cn("relative grid min-w-0 gap-1.5", className)}>
+        <div className="flex items-center gap-1">
+          {/* A `<label>` with no `htmlFor`: a group is not labelable, so it is named
+              by `aria-labelledby` on the group; the element keeps the Field look. */}
+          <Label
+            id={labelId}
+            disabled={disabled}
+            data-error={hasError || undefined}
+            className="data-[error=true]:text-[var(--danger)]"
+          >
+            {label}
+          </Label>
+          {hint}
+        </div>
+        <div className="min-w-0">
+          {group}
+          {captionEl}
+          {errorEl}
+        </div>
+      </div>
+    );
+  }
   if (!field) {
     if (!captionEl) return group;
     // The group keeps its `className`, as without a caption; the wrapper only stacks.
@@ -339,11 +391,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         </div>
       </FloatingField>
       {captionEl}
-      {hasError && (
-        <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
-          {error}
-        </p>
-      )}
+      {errorEl}
     </div>
   );
 }