@eifi1/ui-kit 0.4.1 → 0.5.0

package/src/components/toggle-group.tsx

@@ -0,0 +1,153 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+
+export interface ToggleOption<T extends string> {
+  value: T;
+  label: string;
+  className?: string;
+}
+
+/**
+ * `onChange` is the group's own — the chosen VALUE, not a DOM event — so the div's
+ * `onChange` is omitted rather than shadowed: leaving both in scope would give the
+ * prop two incompatible meanings depending on which overload TypeScript picked.
+ *
+ * `children` is omitted too: this renders its `options` and nothing else, so a `children` the type
+ * accepted and the component ignored would be a prop that silently does nothing —
+ * worse than one that does not compile.
+ */
+export interface ToggleGroupProps<T extends string>
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "children"> {
+  value: T;
+  onChange: (value: T) => void;
+  options: ToggleOption<T>[];
+  className?: string;
+  /** Applied to every option button (e.g. to tune height/rounding to match
+   *  adjacent fields). Per-option `className` still wins over this. */
+  optionClassName?: string;
+  /**
+   * @deprecated Pass `aria-label` instead — the DOM spelling, which every other
+   * control in this kit now answers to. Kept working because three applications ship
+   * this one today; it names the group only when `aria-label` is absent.
+   */
+  ariaLabel?: string;
+  /**
+   * Show, refuse the change (Keksdose live #288: a payment dated in the future has no
+   * state to set).
+   *
+   * Whatever `value` says stays pressed and keeps its own fill rather than going grey
+   * with the rest — a reader who cannot see WHICH option is chosen has been told less
+   * than before it was disabled. A caller with nothing to show passes no value, and
+   * the group renders dimmed with nothing pressed, which is the shape Keksdose's
+   * status picker uses for a row whose status does not exist yet.
+   *
+   * On the whole GROUP, not per option: a segmented control where some segments are
+   * live and others are not is a menu with holes in it, and no caller here wants one.
+   */
+  disabled?: boolean;
+}
+
+export function ToggleGroup<T extends string>({
+  value,
+  onChange,
+  options,
+  className,
+  optionClassName,
+  ariaLabel,
+  disabled = false,
+  "aria-label": ariaLabelAttr,
+  ...rest
+}: ToggleGroupProps<T>) {
+  return (
+    <div
+      // The audit's named example of a closed prop list (§"Public API design"): the
+      // tour locates a step by CSS SELECTOR, so a component that drops every attribute
+      // it was not expecting cannot be spotlighted at all — and Keksdose's rule editor
+      // carries a comment explaining that it wraps this group in a bare <div> for
+      // exactly that reason.
+      //
+      // `...rest` first, then the attributes the group cannot do without: a caller
+      // hanging an anchor or a test id on the group must not be able to overwrite the
+      // 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="radiogroup"
+      // The DOM spelling wins; `ariaLabel` is the fallback for the call sites that
+      // have not moved yet.
+      aria-label={ariaLabelAttr ?? ariaLabel}
+      // `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
+      // three separately-disabled radios does not say that.
+      aria-disabled={disabled || undefined}
+      className={cn(
+        // `gap-0.5` — the same 2px as the container's own padding, so EVERY segment
+        // sits in a uniform 2px moat and no two fills ever touch. Flush segments were
+        // Keksdose live #268's rework: the pressed segment wears a saturated fill and
+        // an unpressed neighbour wears a pale hover fill, and with a shared edge the
+        // two rectangles read as one smeared shape — *"the boundary of the selected
+        // option and hovering next to it overlays the boundary of the selected
+        // button"*. A gap is what makes each segment its own chip; it cannot be
+        // undone by a caller's per-option colour, which a hover-only fix could.
+        //
+        // (The hover fill is the DESKTOP half of that report: Tailwind v4 wraps every
+        // `hover:` in `@media (hover: hover)`, so a phone never paints it. The half a
+        // phone does see is the focus ring — see the segment's own note below.)
+        "inline-flex w-full gap-0.5 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] p-0.5 shadow-sm",
+        // The whole group fades, the way every other disabled control in this
+        // package does; `cursor-not-allowed` is on the buttons, which is what a
+        // pointer is actually over.
+        disabled && "opacity-60",
+        className,
+      )}
+    >
+      {options.map((opt) => {
+        const active = opt.value === value;
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            role="radio"
+            aria-checked={active}
+            disabled={disabled}
+            onClick={() => onChange(opt.value)}
+            className={cn(
+              // `truncate` (which carries whitespace-nowrap) rather than letting a
+              // label wrap: a segmented control sizes its whole row to the tallest
+              // option, so one two-word option — Keksdose feedback #147's "Where I
+              // am" — silently doubles the height of every segment beside it.
+              //
+              // `basis-auto` is what keeps that ellipsis a LAST resort rather than
+              // the normal state (Keksdose dev#475). With flex-1's `basis-0`, a
+              // shrink-to-fit group (`w-auto`) still resolves to the sum of the
+              // labels' widths — and then splits it EQUALLY, so the short option
+              // got 66px it did not need and "Where I am" got 66 of the 81 it did:
+              // truncated at 1778px of free screen. Basing each segment on its own
+              // content and sharing only the LEFTOVER space keeps a full-width
+              // group's segments near-equal and an auto-width group's exact.
+              //
+              // `focus-visible` + `ring-inset`, not `focus` + an outset ring. A ring
+              // is a box-shadow that spreads OUTWARD, so on a flush group it painted
+              // 2px of ring over both neighbours and over the container's own border
+              // — and on a phone it appeared on every TAP, because a tap focuses the
+              // button. That is the other half of what live #268's rework saw
+              // overlaying the selected segment's boundary. Inset keeps the ring
+              // inside the segment it belongs to; focus-visible keeps it for the
+              // keyboard, which is the only input that needs it.
+              "min-w-0 flex-1 basis-auto truncate rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
+              active
+                ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
+                : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
+              // No hover fill on a group that cannot be changed — a segment that
+              // lights up under the pointer is an offer, and there is none here.
+              disabled && "cursor-not-allowed hover:bg-transparent dark:hover:bg-transparent",
+              optionClassName,
+              opt.className,
+            )}
+          >
+            {opt.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/toggle-legend.tsx

@@ -0,0 +1,229 @@
+// A legend whose entries are SWITCHES — and the stroke table it shares with
+// `SeriesChart`. Lifted out of lenkbank's measurement plots, where ten legends over
+// thirteen charts took channels on and off the picture.
+//
+// No recharts in this module: a legend of switches is plain buttons, and it is as
+// useful under a chart the consumer drew by hand as under `SeriesChart`.
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_SERIES_CHART_LABELS, type SeriesChartLabels } from "./series-chart-labels";
+
+/**
+ * The strokes a reader can tell apart, in the order they are handed out.
+ *
+ * For the charts where the colour is already spoken for: a comparison draws each
+ * measurement in its own colour, so a chart carrying several CHANNELS of each has
+ * nothing left but the stroke — and "solid versus dashed" only gets you two.
+ *
+ * **Five, and the fifth is the last one.** They are the draughtsman's line types, in
+ * the draughtsman's order — continuous, dashed, dotted, dash-dot, dash-dot-dot — the
+ * one family of five a century of drawings has already proved legible at a hair's
+ * width. A sixth is not distinguishable from one of these at two pixels wide, so a
+ * chart needing one is a chart that should be split.
+ *
+ * Kept here, beside the legend's own mark, and read by `SeriesChart` from here — so
+ * the key under a chart and the lines on it cannot disagree.
+ */
+export const STROKE_PATTERNS: readonly (string | undefined)[] = [
+  undefined,
+  "5 4",
+  "1 3",
+  "9 3 2 3",
+  "9 3 2 3 2 3",
+];
+
+/** The dash array for the nth pattern, wrapping past the fifth. */
+export function strokeDash(order: number): string | undefined {
+  const n = STROKE_PATTERNS.length;
+  return STROKE_PATTERNS[((Math.trunc(order) % n) + n) % n];
+}
+
+/** Which of the patterns a `step` series is drawn in.
+ *
+ *  A whole-number channel that jumps rather than travels is drawn dashed, and it has
+ *  to be one of {@link STROKE_PATTERNS} rather than a dash array written out at the
+ *  call site: a legend entry says its pattern by index, so a step line drawn in
+ *  anything else would be a legend promising a solid line for a dashed one. */
+export const STEP_DASH = 1;
+
+/**
+ * One key switched, as a new hidden set.
+ *
+ * Every caller writes `onToggle={(key) => setHidden(toggleHidden(hidden, key))}`. A
+ * new set rather than a mutated one, because the state is read during render and a
+ * mutation of something a component already holds is invisible to React.
+ */
+export function toggleHidden(hidden: ReadonlySet<string>, key: string): ReadonlySet<string> {
+  const next = new Set(hidden);
+  if (!next.delete(key)) next.add(key);
+  return next;
+}
+
+export interface LegendEntry {
+  key: string;
+  label: ReactNode;
+  /** Any CSS colour — `paletteFor(i)` for the kit's own ramp. */
+  color: string;
+  /**
+   * 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.
+   */
+  marker?: "swatch" | "stroke";
+  /** 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. */
+  dash?: number;
+}
+
+export interface ToggleLegendProps {
+  entries: LegendEntry[];
+  /** The keys currently off the chart. */
+  hidden: ReadonlySet<string>;
+  onToggle: (key: string) => void;
+  /** `vertical` is for a legend standing BESIDE the charts rather than under them —
+   *  what a row of charts sharing one legend wants, since under two charts there is
+   *  no "under", and putting it under one says it belongs to that one. */
+  orientation?: "horizontal" | "vertical";
+  /**
+   * Draw a legend of ONE entry rather than nothing.
+   *
+   * A single line's legend is usually noise. It is not where the legend is the only
+   * SWITCH that line has — a series that starts hidden and has no entry to bring it
+   * back is gone for good.
+   */
+  showSingle?: boolean;
+  className?: string;
+  /** Per-instance strings over `<UiKitProvider labels={{ seriesChart }}>`. */
+  labels?: Partial<SeriesChartLabels>;
+}
+
+/**
+ * A legend whose entries are switches.
+ *
+ * `ChartLegendContent` with `onItemClick`/`activeKey` is the other kind: clicking an
+ * entry HIGHLIGHTS it and dims the rest, which is right when every series belongs on
+ * the chart and one of them is momentarily interesting. This is for the opposite —
+ * three coordinates on one axis where y runs to 800 and z barely moves, and the only
+ * way to see z is to take y off the chart entirely. Any number may be off at once.
+ *
+ * A hidden entry keeps its mark and its place. Removing it would reflow the legend on
+ * every click and lose the one thing it is for: saying what COULD be shown.
+ *
+ * Each entry is a real `<button>` with `aria-pressed` — pressed means "on the chart" —
+ * so Tab reaches every switch and Space/Enter flips it.
+ */
+export function ToggleLegend({
+  entries,
+  hidden,
+  onToggle,
+  orientation = "horizontal",
+  showSingle = false,
+  className,
+  labels: labelsProp,
+}: ToggleLegendProps) {
+  const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
+  if (entries.length < (showSingle ? 1 : 2)) return null;
+  return (
+    <div
+      role="group"
+      aria-label={labels.legend}
+      className={cn(
+        "flex gap-x-3 gap-y-1",
+        orientation === "vertical"
+          ? "flex-col items-start justify-center"
+          : "mt-2 flex-wrap items-center",
+        className,
+      )}
+    >
+      {entries.map((entry) => {
+        const off = hidden.has(entry.key);
+        return (
+          <button
+            key={entry.key}
+            type="button"
+            // Pressed rather than a checkbox: it is a control over what the chart
+            // draws, and "not pressed" is the same sentence the dimmed mark says.
+            aria-pressed={!off}
+            onClick={() => onToggle(entry.key)}
+            className={cn(
+              "flex items-center gap-1.5 rounded text-start text-[11px] text-[var(--text-secondary)] transition-opacity hover:opacity-80",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+              off && "opacity-35",
+            )}
+          >
+            <LegendMark entry={entry} off={off} />
+            {entry.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * 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
+ * that stretches it — and stacks whatever it is given, which is what a panel showing
+ * two legends at once needs. The width is the caller's: how wide a legend column is
+ * is a fact about that screen's layout.
+ */
+export function LegendColumn({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <div className={cn("flex h-full flex-col justify-center gap-3", className)}>{children}</div>
+  );
+}
+
+/**
+ * A legend and what it is a legend OF, as a headed column.
+ *
+ * For legends that are several vocabularies at once — which measurement and which
+ * channel — so the entries are read down a group and the groups across. Wrapped rows
+ * would put the second half of one group on a line under the first half of the next.
+ */
+export function LegendGroup({ title, children }: { title: ReactNode; children: ReactNode }) {
+  return (
+    <div className="flex min-w-0 flex-col items-start gap-1">
+      <span className="text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]">
+        {title}
+      </span>
+      <div className="flex flex-col items-start gap-y-0.5">{children}</div>
+    </div>
+  );
+}
+
+/** The entry's mark: a square for a measurement, a stroke for a quantity. A hidden one
+ *  keeps its outline — a mark that vanished would leave a line of text with nothing in
+ *  front of it.
+ *
+ *  A stroke is an SVG line with the chart's own `strokeDasharray`, not a CSS gradient
+ *  approximating it: a gradient can say "solid or dashed" and nothing more. */
+function LegendMark({ entry, off }: { entry: LegendEntry; off: boolean }) {
+  if (entry.marker === "stroke") {
+    return (
+      <svg aria-hidden viewBox="0 0 20 2" className="h-0.5 w-5 shrink-0 overflow-visible">
+        <line
+          x1={0}
+          y1={1}
+          x2={20}
+          y2={1}
+          stroke={entry.color}
+          strokeWidth={2}
+          strokeDasharray={strokeDash(entry.dash ?? 0)}
+          opacity={off ? 0.35 : 1}
+        />
+      </svg>
+    );
+  }
+  return (
+    <span
+      aria-hidden
+      className="h-2.5 w-2.5 shrink-0 rounded-[3px]"
+      style={{
+        backgroundColor: off ? "transparent" : entry.color,
+        boxShadow: `inset 0 0 0 1.5px ${entry.color}`,
+      }}
+    />
+  );
+}