@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/components/text-link.tsx

@@ -0,0 +1,356 @@
+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;
+}
+
+/** 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();
+    window.location.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> = {
+  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: "",
+  primary: "text-[var(--text-primary)] hover:decoration-2",
+  secondary: "text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
+  warning: "text-[var(--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-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 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

@@ -16,6 +16,14 @@ import { cn } from "../lib/cn";
  * (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";
 
@@ -34,6 +42,31 @@ export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
   sm: "text-xs font-semibold uppercase tracking-wide text-[var(--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 `text-[…]` from a colour `text-[var(…)]`. */
+const SECTION_LABEL_BAND_CLASS: Record<SectionLabelSize, string> = {
+  xs: "text-[10px]",
+  md: "text-[11px]",
+  sm: "text-xs",
+};
+const BAND =
+  "block border-b border-[var(--border)] bg-[var(--bg-surface-2)] px-4 py-2 font-medium uppercase tracking-wide text-[var(--text-secondary)]";
+
 type SectionLabelElement = "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "div" | "legend";
 
 export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
@@ -45,6 +78,9 @@ export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
    */
   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;
 }
 
@@ -55,10 +91,18 @@ export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
  * 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", className, children, ...rest }: SectionLabelProps) {
+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(SECTION_LABEL_CLASS[size], className)}>
+    <Tag {...rest} className={cn(type, className)}>
       {children}
     </Tag>
   );

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;
@@ -91,6 +104,25 @@ type ToggleGroupCaption<V> = ReactNode | ((value: V) => ReactNode);
 /** The group as it has always been: one option is always the answer. */
 export interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupBaseProps<T> {
   allowEmpty?: false;
+  /**
+   * What the options ARE to a screen reader, separately from whether the group can be
+   * emptied (kastlan feedback #47).
+   *
+   *  - `"radio"` (default) — a `radiogroup` of radios: one Tab stop, arrow keys MOVE the
+   *    choice. Right for a choice between answers ("Monthly / Yearly").
+   *  - `"pressed"` — a `group` of toggle buttons (`aria-pressed`), each its own Tab stop,
+   *    Space/Enter to press; still one option always pressed. Right for a row that reads
+   *    as a set of switches — a view mode, a toolbar-like filter — where arrows moving the
+   *    selection on focus would be a surprise.
+   *
+   * Before this the only way to `aria-pressed` was `allowEmpty`, which also let a second
+   * press clear the choice — so kastlan took the clearable shape and threw the `null`
+   * away in `onChange` (`(v) => v && setMode(v)`), a group announcing that a press would
+   * unpress what it would not. Here a press on the pressed option re-sends its value, as
+   * the radio shape does, and nothing is ever unpressed. A clearable group
+   * (`allowEmpty`) is always `"pressed"`: a radio cannot be unchecked by activating it.
+   */
+  semantics?: "radio" | "pressed";
   value: T;
   onChange: (value: T) => void;
   /** See {@link ToggleGroupCaption}. */
@@ -109,6 +141,9 @@ export interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupB
  */
 export interface ToggleGroupClearableProps<T extends string> extends ToggleGroupBaseProps<T> {
   allowEmpty: true;
+  /** Always toggle buttons — see {@link ToggleGroupRequiredProps.semantics}. Accepted so
+   *  a wrapper can forward one `semantics` to either shape. */
+  semantics?: "pressed";
   value: T | null;
   onChange: (value: T | null) => void;
   /** See {@link ToggleGroupCaption}. `null` while nothing is chosen. */
@@ -143,6 +178,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 +186,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;
+  const { allowEmpty: _allowEmpty, onChange: _onChange, caption, semantics: _semantics, ...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;
@@ -163,11 +205,14 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
   };
-  const clearable = props.allowEmpty === true;
+  // `pressed`: toggle buttons. Every clearable group is; a required one is when it asks
+  // (kastlan #47) — the role, and not whether a second press clears, is what this flag
+  // decides from here on, so `choose` above still keys off `allowEmpty` alone.
+  const pressed = props.allowEmpty === true || props.semantics === "pressed";
   // A radio group is ONE tab stop (the checked radio, else the first) and arrows move
   // the choice — the pattern `role="radiogroup"` promises a screen-reader user. Before
-  // 0.7.0 each segment was its own tab stop with no arrow keys. The clearable mode is a
-  // row of toggle buttons, where separate tab stops are the pattern.
+  // 0.7.0 each segment was its own tab stop with no arrow keys. The toggle-button shape
+  // is a row of buttons, where separate tab stops are the pattern.
   const tabStop = options.some((o) => o.value === value) ? value : options[0]?.value;
   const onRadioKey = (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
     const last = options.length - 1;
@@ -198,11 +243,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       // radiogroup role or the disabled state by accident. `className` is destructured
       // out entirely and merged through `cn`, so it is never in here.
       {...rest}
-      role={clearable ? "group" : "radiogroup"}
+      role={pressed ? "group" : "radiogroup"}
       // 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 +274,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) => {
@@ -241,12 +288,12 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           <button
             key={opt.value}
             type="button"
-            role={clearable ? undefined : "radio"}
-            aria-checked={clearable ? undefined : active}
-            aria-pressed={clearable ? active : undefined}
+            role={pressed ? undefined : "radio"}
+            aria-checked={pressed ? undefined : active}
+            aria-pressed={pressed ? active : undefined}
             disabled={disabled}
-            tabIndex={clearable ? undefined : opt.value === tabStop ? 0 : -1}
-            onKeyDown={clearable ? undefined : (e) => onRadioKey(e, index)}
+            tabIndex={pressed ? undefined : opt.value === tabStop ? 0 : -1}
+            onKeyDown={pressed ? undefined : (e) => onRadioKey(e, index)}
             onClick={() => choose(opt.value)}
             className={cn(
               // `truncate` (which carries whitespace-nowrap) rather than letting a
@@ -308,6 +355,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 +416,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>
   );
 }