@eifi1/ui-kit 0.54.0 → 0.56.0

package/src/components/toggle-legend.tsx

@@ -1,394 +0,0 @@
-// 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 { FOCUS_RING } from "./focus-ring";
-import { useKitLabels, type LabelOverride } 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;
-}
-
-/**
- * Where a legend that stands BESIDE a chart goes from Large up: UNDER it
- * (docs/text-size-harmonization.md §4). Beside a chart, a legend column takes a third of
- * a row whose plot needs all of it once the text is 25–50 % larger; under it, the row
- * is the plot's and the legend wraps across the width.
- *
- * Pure CSS (`large:`), so a legend moves with the text size alone, whatever drew the
- * row around it:
- * - in a GRID it spans a row of its own (`col-span-full`) after the charts
- *   (`order-last`) — Kurvenschmiede's facing pairs;
- * - in a FLEX row it takes a line of its own (`basis-full`), and its row is allowed to
- *   wrap for it (`[*:has(>&)]:flex-wrap` sets `flex-wrap` on the PARENT — the one rule
- *   here that reaches outside the legend, because a row that may not wrap would squeeze
- *   the chart to nothing beside a full-width legend) — Kurvenschmiede's chart rows.
- *
- * A caller that places its legend itself and wants it kept beside the chart at every
- * size overrides with `large:col-auto large:basis-auto`.
- */
-const UNDER_THE_CHART_AT_LARGE = "large:order-last large:col-span-full large:basis-full large:[*:has(>&)]:flex-wrap";
-
-/** A vertical legend's entries from Large up: across, wrapping — it is under the chart
- *  now (see {@link UNDER_THE_CHART_AT_LARGE}), where a column of entries would be a
- *  screenful of one-word lines. */
-const VERTICAL_AT_LARGE = "large:flex-row large:flex-wrap large:items-center large:justify-start";
-
-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. `dot` is a round mark, for a
-   * MARKER on the chart (a point, an event) rather than a series.
-   */
-  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;
-  /**
-   * `"end"`: push this entry to the legend's inline END — the far right in LTR, the far
-   * left in RTL — with everything before it kept at the start. kastlan's lease gantt
-   * (feedback #49) keys its bars at the start and its "today" hairline at the end, over
-   * the time axis whose end "today" is nearest, and wrote it as
-   * `className="[&>li:last-child]:ms-auto"` — a selector that breaks the moment the
-   * entries are reordered and that reaches into the legend's markup.
-   *
-   * An auto inline-start margin, so it is logical (RTL mirrors it) and it takes only the
-   * row's LEFTOVER space: on a narrow screen where the row wraps, the entry wraps with it
-   * and sits at the end of its own line rather than overflowing. Give it to the LAST
-   * entry — auto margins push everything after them too, so an end entry in the middle
-   * drags the rest over with it (which is also how to end-align a GROUP: mark its first).
-   * In a vertical legend it sits at the column's inline end. Honoured by both
-   * {@link StaticLegend} and {@link ToggleLegend}, which share this entry type.
-   */
-  align?: "start" | "end";
-}
-
-export interface ToggleLegendProps {
-  entries: readonly 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.
-   *
-   *  From Large up a vertical legend moves under the charts and lays its entries
-   *  across (0.32, docs/text-size-harmonization.md §4) — see {@link LegendColumn}. */
-  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?: LabelOverride<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"
-          ? cn("flex-col items-start justify-center", VERTICAL_AT_LARGE, UNDER_THE_CHART_AT_LARGE)
-          : "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-caption text-secondary transition-opacity hover:opacity-80",
-              FOCUS_RING,
-              entry.align === "end" && "ms-auto",
-            )}
-          >
-            <LegendMark entry={entry} off={off} />
-            {/* Off, the label keeps its ink and is struck through; only the mark fades
-                (0.52, refactor audit 2026-10-30, DSP-9). The whole entry at 35 % put the
-                label at 1.8:1 — on a button that brings the series back, whose label is
-                the only thing saying which one. `aria-pressed` carries the state. */}
-            <span className={cn(off && "line-through")}>{entry.label}</span>
-          </button>
-        );
-      })}
-    </div>
-  );
-}
-
-export interface StaticLegendProps {
-  entries: readonly LegendEntry[];
-  /** See {@link ToggleLegendProps.orientation}. */
-  orientation?: "horizontal" | "vertical";
-  /** The list's accessible name. Default: the `seriesChart.legend` label. */
-  "aria-label"?: string;
-  /**
-   * `ul` (default): a list — "list, 4 items", walked with the list keys. Its entries are
-   * `listitem`s, so a host test that counts `getAllByRole("listitem")` on a page with
-   * the legend on it counts the legend too: scope it (`within(...)`) or use `div`.
-   *
-   * `div`: a named `role="group"` of plain entries, for a legend set inside something
-   * that is already a list or a table row, where a list in a list reads as nesting that
-   * is not there, or where the entries are too few for "list, 2 items" to help. The
-   * entries are read in order either way; only the list framing goes.
-   */
-  as?: "ul" | "div";
-  className?: string;
-  /** Per-instance strings over `<UiKitProvider labels={{ seriesChart }}>`. */
-  labels?: LabelOverride<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,
-  as = "ul",
-  className,
-  labels: labelsProp,
-}: StaticLegendProps) {
-  const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
-  if (entries.length === 0) return null;
-  const List = as;
-  const Item = as === "ul" ? "li" : "div";
-  return (
-    <List
-      // A `div` takes `group`: a name on a role-less div is one ARIA forbids and
-      // screen readers drop, and the name is what says these marks are a key.
-      role={as === "div" ? "group" : undefined}
-      aria-label={ariaLabel ?? labels.legend}
-      className={cn(
-        "m-0 flex list-none gap-x-3 gap-y-1 p-0",
-        orientation === "vertical"
-          ? cn("flex-col items-start justify-center", VERTICAL_AT_LARGE, UNDER_THE_CHART_AT_LARGE)
-          : "mt-2 flex-wrap items-center",
-        className,
-      )}
-    >
-      {entries.map((entry) => (
-        <Item
-          key={entry.key}
-          className={cn("flex items-center gap-1.5 text-caption text-secondary", entry.align === "end" && "ms-auto")}
-        >
-          <LegendMark entry={entry} off={false} />
-          {entry.label}
-        </Item>
-      ))}
-    </List>
-  );
-}
-
-/**
- * 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.
- *
- * **From Large up it goes UNDER the charts** (0.32, docs/text-size-harmonization.md
- * §4): a row of its own in a grid, a line of its own in a flex row (see
- * `UNDER_THE_CHART_AT_LARGE`), with what it holds laid across and wrapping. A
- * caller's own `max-sm:flex-row …` for the phone keeps working; the caller's width
- * (`sm:w-40`) gives way to the full row, because a size wins over a breakpoint.
- */
-export function LegendColumn({ children, className }: { children: ReactNode; className?: string }) {
-  return (
-    <div
-      className={cn(
-        "flex h-full flex-col justify-center gap-3",
-        UNDER_THE_CHART_AT_LARGE,
-        "large:h-auto large:flex-row large:flex-wrap large:items-start large:justify-start large:gap-x-6",
-        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-micro font-semibold uppercase tracking-wide 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.
- *
- *  A hidden mark fades ONCE, on its own box (`opacity-35`; since 0.52 the label beside
- *  it keeps its ink, DSP-9). The line used to take its own 0.35 inside a faded button —
- *  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 }) {
-  const fade = off && "opacity-35";
-  if (entry.icon != null) {
-    return (
-      <span aria-hidden className={cn("inline-flex shrink-0 items-center", fade)}>
-        {entry.icon}
-      </span>
-    );
-  }
-  if (entry.marker === "dot") {
-    return (
-      <span
-        aria-hidden
-        className={cn("size-2 shrink-0 rounded-full", fade)}
-        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={cn("h-0.5 w-5 shrink-0 overflow-visible", fade)}>
-        <line
-          x1={0}
-          y1={1}
-          x2={20}
-          y2={1}
-          stroke={entry.color}
-          strokeWidth={2}
-          strokeDasharray={typeof entry.dash === "string" ? entry.dash : strokeDash(entry.dash ?? 0)}
-        />
-      </svg>
-    );
-  }
-  return (
-    <span
-      aria-hidden
-      className={cn("h-2.5 w-2.5 shrink-0 rounded-[3px]", fade)}
-      style={{
-        backgroundColor: off ? "transparent" : entry.color,
-        boxShadow: `inset 0 0 0 1.5px ${entry.color}`,
-      }}
-    />
-  );
-}