@eifi1/ui-kit 0.10.0 → 0.12.0

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;
@@ -76,11 +89,25 @@ export interface ToggleGroupBaseProps<T extends string>
   error?: ReactNode;
 }
 
+/**
+ * A line under the group saying what the CHOSEN option means — lenkbank's ToggleField
+ * `hint` (features/gear/common.tsx:97): not help behind a "?" but a caption, and one
+ * that changes as the choice does. Pass a function of the value for that; it is
+ * attached with `aria-describedby`, and a function caption is also a polite live
+ * region, because a description is read when the group is entered and not again when
+ * an arrow key changes the choice underneath it.
+ *
+ * In muted 11px text under the field (or the bare group), above an `error`.
+ */
+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;
   value: T;
   onChange: (value: T) => void;
+  /** See {@link ToggleGroupCaption}. */
+  caption?: ToggleGroupCaption<T>;
 }
 
 /**
@@ -97,6 +124,8 @@ export interface ToggleGroupClearableProps<T extends string> extends ToggleGroup
   allowEmpty: true;
   value: T | null;
   onChange: (value: T | null) => void;
+  /** See {@link ToggleGroupCaption}. `null` while nothing is chosen. */
+  caption?: ToggleGroupCaption<T | null>;
 }
 
 /** `allowEmpty` picks the shape, so `onChange` is typed `(T) => void` unless the group
@@ -127,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,
@@ -134,11 +164,21 @@ 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, ...rest } = restWithMode;
+  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;
+  const hasCaption = captionNode !== undefined && captionNode !== null && captionNode !== false && captionNode !== "";
   const choose = (next: T) => {
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
@@ -182,10 +222,10 @@ 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={
-        hasError ? (rest["aria-describedby"] ? `${rest["aria-describedby"]} ${errorId}` : errorId) : rest["aria-describedby"]
+        [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || undefined
       }
       // `aria-disabled` on the group as well as `disabled` on each button: a radio
       // group is what the user is being refused, and a screen reader announcing
@@ -209,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) => {
@@ -273,7 +315,61 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       })}
     </div>
   );
-  if (!field) return group;
+  // Rendered whenever the caption is — `aria-live` must be on the element BEFORE its
+  // text changes, or the change is not announced — but empty (no height, no margin)
+  // when there is nothing to say, so a function caption that returns null for some
+  // options leaves no gap. Empty rather than `hidden`: some readers do not announce
+  // text that appears inside an element coming back from `display: none`.
+  const captionEl =
+    hasCaption || captionIsLive ? (
+      <p
+        id={captionId}
+        aria-live={captionIsLive ? "polite" : undefined}
+        className={cn("text-[11px] leading-snug text-[var(--text-muted)]", hasCaption && "mt-1")}
+      >
+        {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.
+    return (
+      <div className="min-w-0">
+        {group}
+        {captionEl}
+      </div>
+    );
+  }
   return (
     // `h-full` + `flex-1`: the chrome fills a grid or stretched flex row, which is what
     // levels it with a select beside it whatever the browser makes of the select.
@@ -294,11 +390,8 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           {group}
         </div>
       </FloatingField>
-      {hasError && (
-        <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
-          {error}
-        </p>
-      )}
+      {captionEl}
+      {errorEl}
     </div>
   );
 }

package/src/components/toggle-legend.tsx

@@ -68,14 +68,21 @@ export interface LegendEntry {
   /**
    * What the entry's mark looks like. `swatch` — a filled square, the default — says
    * WHICH MEASUREMENT. `stroke` says WHICH QUANTITY, for the charts that carry both at
-   * once and tell them apart by colour and by dash.
+   * once and tell them apart by colour and by dash. `dot` is a round mark, for a
+   * MARKER on the chart (a point, an event) rather than a series.
    */
-  marker?: "swatch" | "stroke";
+  marker?: "swatch" | "stroke" | "dot";
   /** Which of {@link STROKE_PATTERNS}, when the marker is a stroke — the same index
    *  `SeriesChartSeries.dash` takes, so a legend cannot promise a dot-dash the plot
    *  draws dashed. Or the same custom `stroke-dasharray` string the series draws with
    *  (keksdose's `"4 3"`). */
   dash?: number | string;
+  /**
+   * A mark of the caller's own, drawn in place of {@link marker} — for a key whose
+   * mark is not a colour at all (a fading bar for "open-ended", a hairline for
+   * "today"). Decorative: it is wrapped `aria-hidden`, and the label is the name.
+   */
+  icon?: ReactNode;
 }
 
 export interface ToggleLegendProps {
@@ -163,6 +170,65 @@ export function ToggleLegend({
   );
 }
 
+export interface StaticLegendProps {
+  entries: LegendEntry[];
+  /** See {@link ToggleLegendProps.orientation}. */
+  orientation?: "horizontal" | "vertical";
+  /** The list's accessible name. Default: the `seriesChart.legend` label. */
+  "aria-label"?: string;
+  className?: string;
+  /** Per-instance strings over `<UiKitProvider labels={{ seriesChart }}>`. */
+  labels?: Partial<SeriesChartLabels>;
+}
+
+/**
+ * A legend that is a KEY, not a control: the same entries and marks as
+ * {@link ToggleLegend} — swatch, stroke (with the chart's own dash), dot, or a mark of
+ * the caller's own — but nothing to press.
+ *
+ * A separate component rather than `ToggleLegend` without `onToggle`, because the two
+ * are different things to a screen reader: a group of switches announces a pressed
+ * state on every entry, a key is a LIST, read as "list, 4 items" and walked with the
+ * list keys, and costs no tab stops. The apps drew this by hand under the charts that
+ * say what a colour or a dash means without letting you switch it (kastlan's lease
+ * timeline, keksdose's cash buffer).
+ *
+ * Unlike `ToggleLegend` it draws a single entry: a key with one line still says what
+ * the one mark on the chart means.
+ */
+export function StaticLegend({
+  entries,
+  orientation = "horizontal",
+  "aria-label": ariaLabel,
+  className,
+  labels: labelsProp,
+}: StaticLegendProps) {
+  const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
+  if (entries.length === 0) return null;
+  return (
+    <ul
+      aria-label={ariaLabel ?? labels.legend}
+      className={cn(
+        "m-0 flex list-none gap-x-3 gap-y-1 p-0",
+        orientation === "vertical"
+          ? "flex-col items-start justify-center"
+          : "mt-2 flex-wrap items-center",
+        className,
+      )}
+    >
+      {entries.map((entry) => (
+        <li
+          key={entry.key}
+          className="flex items-center gap-1.5 text-[11px] text-[var(--text-secondary)]"
+        >
+          <LegendMark entry={entry} off={false} />
+          {entry.label}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
 /**
  * The column a vertical legend stands in: beside the charts, on their horizontal
  * centre line. `h-full` + `justify-center`, so it centres in a grid cell or a flex row
@@ -205,6 +271,25 @@ export function LegendGroup({ title, children }: { title: ReactNode; children: R
  *  and the line used to take its own 0.35 on top — 0.35 × 0.35, about 12 %, a mark
  *  gone rather than dimmed, while the square beside it read at the full 35 %. */
 function LegendMark({ entry, off }: { entry: LegendEntry; off: boolean }) {
+  if (entry.icon != null) {
+    return (
+      <span aria-hidden className="inline-flex shrink-0 items-center">
+        {entry.icon}
+      </span>
+    );
+  }
+  if (entry.marker === "dot") {
+    return (
+      <span
+        aria-hidden
+        className="size-2 shrink-0 rounded-full"
+        style={{
+          backgroundColor: off ? "transparent" : entry.color,
+          boxShadow: `inset 0 0 0 1.5px ${entry.color}`,
+        }}
+      />
+    );
+  }
   if (entry.marker === "stroke") {
     return (
       <svg aria-hidden viewBox="0 0 20 2" className="h-0.5 w-5 shrink-0 overflow-visible">

package/src/components/tooltip.tsx

@@ -17,6 +17,13 @@ import { useAnchoredRect, type AnchorRect } from "../hooks/use-anchored-rect";
 import { dirOf, type Direction } from "../lib/direction";
 import { hasClippingAncestor } from "../lib/clipping";
 
+/** The attribute that marks an element as a clipping container for {@link Tooltip}'s
+ *  auto-portal, whatever its computed `overflow` — `<div data-clips>` or
+ *  `<div {...{ [CLIPS_ATTRIBUTE]: "" }}>`. Put it on an app's own scroller so a test
+ *  environment without stylesheets (jsdom) portals the same tooltips the browser
+ *  does. DataTable's body and Table's wrapper already carry it. */
+export { CLIPS_ATTRIBUTE } from "../lib/clipping";
+
 /** Where the bubble sits. `start` / `end` follow the reading direction — `end` is the
  *  right in LTR and the left in RTL — and are what a layout that mirrors should ask
  *  for. `left` / `right` stay physical, for a bubble tied to something that does not
@@ -75,8 +82,8 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
   /**
    * Where the bubble lives. Left out (the default since 0.10.0), the tooltip decides for
    * itself: the bubble stays next to the trigger unless an ancestor clips or scrolls
-   * (`overflow` other than `visible`), in which case it is portalled — see "Inside a
-   * scroll container" below. `true` always portals, `false` never does; both are exactly
+   * (`overflow` other than `visible`, or the {@link CLIPS_ATTRIBUTE} marker), in which
+   * case it is portalled — see "Inside a scroll container" below. `true` always portals, `false` never does; both are exactly
    * what they were before the default existed.
    */
   portal?: boolean;
@@ -144,7 +151,14 @@ type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: Toolt
  * being one: every tooltip in a table, a drawer or a scrolling card had to remember it,
  * and the ones that forgot were only found by someone scrolling sideways. So with
  * `portal` left out, the tooltip looks for a clipping ancestor itself — any element
- * between it and `<body>` whose computed `overflow-x` / `overflow-y` is not `visible`.
+ * between it and `<body>` whose computed `overflow-x` / `overflow-y` is not `visible`,
+ * or that carries {@link CLIPS_ATTRIBUTE} (`data-clips`). The marker is what makes the
+ * answer the same under test: jsdom computes no Tailwind, so there every scroller
+ * reads `visible` and a table-cell tooltip used to stay in place — its always-mounted
+ * bubble then repeated the label in the cell's accessible name and `textContent`
+ * ("CheckingChecking"), and apps pinned `portal` to stop it. The kit's own scrollers
+ * are marked, so a tooltip in a DataTable or Table cell portals in jsdom exactly as it
+ * does in the browser.
  * It looks at MOUNT, not only on open: dev#488's phantom scroll is caused by a bubble
  * nobody opened, so a check that waited for the hover would find the damage already
  * done. It looks again on every open, for a container that started scrolling after