@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/components/toggle-legend.tsx

@@ -68,14 +68,38 @@ 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;
+  /**
+   * `"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 {
@@ -152,6 +176,7 @@ export function ToggleLegend({
               "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",
+              entry.align === "end" && "ms-auto",
             )}
           >
             <LegendMark entry={entry} off={off} />
@@ -163,6 +188,68 @@ 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={cn(
+            "flex items-center gap-1.5 text-[11px] text-[var(--text-secondary)]",
+            entry.align === "end" && "ms-auto",
+          )}
+        >
+          <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 +292,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

@@ -87,6 +87,19 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
    * what they were before the default existed.
    */
   portal?: boolean;
+  /**
+   * Mount the IN-PLACE bubble only while it is up (hovered or focused, not dismissed),
+   * instead of always. It still sits next to its trigger and is still placed by CSS
+   * alone; what changes is that, while closed, it is not in the DOM — so it is not in
+   * `getAllByRole("tooltip")`, not in an ancestor's `textContent` and not in an
+   * ancestor's accessible name. The trigger is described (`aria-describedby`) while
+   * the bubble is up, exactly as a portalled one is. See "Lazy in place" on
+   * {@link Tooltip} for why this exists (keksdose F6) and why it is not the default.
+   *
+   * Has no effect on a bubble that is portalled (`portal`, or auto-portalled inside a
+   * clipping container) — that one is already mounted only while up.
+   */
+  lazy?: boolean;
   /** Tag the bubble `data-private`, for a label that repeats the user's own data. */
   redact?: boolean;
   children: ReactNode;
@@ -94,7 +107,7 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
 
 /** What each variant below takes: the resolved `side`, and every span attribute the
  *  caller handed {@link Tooltip}, forwarded to that variant's own wrapper. */
-type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: TooltipSide };
+type TooltipVariantProps = Omit<TooltipProps, "side" | "portal" | "lazy"> & { side: TooltipSide };
 
 /**
  * Hover/focus label for a control.
@@ -170,12 +183,50 @@ type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: Toolt
  * Why not simply portal everything? Because the in-place bubble is the one existing
  * app tests rely on (it is in the DOM without a hover), and because it follows its
  * trigger through a scroll or an animation for free — the portalled one re-measures.
+ *
+ * ⚠️ **Lazy in place: `lazy` keeps the bubble next to its trigger but out of the DOM
+ * until it is up (keksdose F6).** `data-clips` cured the doubled text for tooltips
+ * inside a table; it did nothing for the ones outside any clipping container, where the
+ * always-mounted bubble is still a real `role="tooltip"` node full of text. About seven
+ * keksdose sites — column-header tooltips, a direction toggle, an fx-estimate row, a
+ * FlagBadge, a toast inside a `<button>` — still pinned `portal` for that alone: their
+ * tests found two tooltips with `getAllByRole("tooltip")`, read the label twice in a
+ * `textContent`, or got a button whose accessible name had the bubble's sentence glued
+ * on. `portal` fixed the test and cost the browser the measured, re-positioning bubble
+ * for no reason. `lazy` is the in-place bubble with the portalled one's lifetime: it is
+ * rendered only while hovered or focused (and not dismissed), in the same slot, with the
+ * same classes, so it looks and sits exactly as the default one does when it is up.
+ *
+ * Why unmount rather than hide? Hiding was the other option — keep the bubble mounted
+ * with `hidden` (or `aria-hidden` plus `display: none` until `:hover` / `:focus-within`)
+ * and let `aria-describedby` go on pointing at it, which the accname algorithm allows:
+ * a node referenced directly by `aria-describedby` contributes its text even while
+ * hidden. That would take the bubble out of the role queries and out of an ancestor's
+ * accessible name — but NOT out of `textContent`, which is plain DOM and counts hidden
+ * text too, and `textContent` is one of the three things F6 lists. Only a bubble that
+ * is not there solves all three. The cost is the portalled variant's: the trigger is
+ * described while the bubble is up rather than always. Focusing the trigger IS what
+ * puts it up, and React commits the `aria-describedby` in the same task as that focus
+ * event, so a screen reader landing on the control still hears it; what goes is the description
+ * of a trigger that is read in browse mode without ever being focused.
+ *
+ * Escape still dismisses it — here by unmounting it, which takes it off the screen and
+ * out of the accessibility tree at once — and the next hover or focus brings it back.
+ * There is no fade to lose: neither in-place bubble has ever had a transition, only the
+ * `opacity` switch, so appearing on a state change looks the same as appearing on
+ * `:hover`.
+ *
+ * Why opt-in rather than the new default? Because the always-mounted bubble is the one
+ * existing app tests find without a hover (see above): flipping it would turn every
+ * `getByRole("tooltip")` written against 0.12 into a failure in all three apps at once.
+ * Reach for `lazy` wherever a `portal` was pinned only to keep a test's DOM clean.
  */
 export function Tooltip({
   label,
   side = "top",
   className,
   portal,
+  lazy = false,
   redact = false,
   children,
   ...rest
@@ -208,6 +259,7 @@ export function Tooltip({
       className={className}
       redact={redact}
       detect={portal === undefined}
+      lazy={lazy}
       {...rest}
     >
       {children}
@@ -235,9 +287,10 @@ function InPlaceTooltip({
   className,
   redact,
   detect,
+  lazy,
   children,
   ...rest
-}: TooltipVariantProps & { detect: boolean }) {
+}: TooltipVariantProps & { detect: boolean; lazy: boolean }) {
   const id = useId();
   const triggerRef = useRef<HTMLSpanElement | null>(null);
   const [clipped, setClipped] = useState(false);
@@ -263,6 +316,9 @@ function InPlaceTooltip({
     setClipped(hasClippingAncestor(el));
   };
   return (
+    /* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- the handlers track
+       whether the bubble is up and activate nothing; the caller's child is the
+       interactive element, keeps its own handlers, and its focus shows the bubble too. */
     <span
       // `...rest` first: the four handlers below are what decides whether a bubble is
       // up, and a caller passing an `onFocus` of its own must not replace them.
@@ -272,10 +328,6 @@ function InPlaceTooltip({
       // These four track WHETHER A BUBBLE IS UP. They activate nothing — the only thing
       // here that can be activated is the caller's child, which keeps every handler it
       // arrived with — so this wrapper needs no role and no key handling of its own.
-      // `jsx-a11y/no-static-element-interactions` warns about it all the same, as it
-      // already does about the portal variant's identical trigger below; both are left
-      // visible rather than silenced, because a rule this package ratchets should be
-      // argued with in the backlog and not in a disable comment.
       onMouseEnter={(e) => {
         setHovered(true);
         arm(e.currentTarget);
@@ -287,12 +339,28 @@ function InPlaceTooltip({
       }}
       onBlur={() => setFocused(false)}
     >
-      {/* In place the bubble is always there to point at; portalled, only while up. */}
-      {describedBy(children, clipped ? (open ? id : undefined) : dismissed ? undefined : id)}
+      {/* In place the bubble is always there to point at; portalled or lazy, only while up. */}
+      {describedBy(children, clipped || lazy ? (open ? id : undefined) : dismissed ? undefined : id)}
       {clipped ? (
         open && (
           <PortalBubble triggerRef={triggerRef} id={id} label={label} side={side} dir={dir} redact={redact} />
         )
+      ) : lazy ? (
+        // keksdose F6: the in-place slot and classes, the portalled lifetime. Mounted only
+        // while up, so it is visible whenever it exists — `opacity-100` outright rather
+        // than the `group-hover` switch, which would also be right but would make the
+        // bubble's visibility depend on two sources (the state that mounted it and the
+        // CSS that shows it) that can disagree for a frame after Escape.
+        open && (
+          <span
+            id={id}
+            role="tooltip"
+            data-private={redact ? "" : undefined}
+            className={cn(TOOLTIP_SURFACE, "pointer-events-none absolute z-50 opacity-100", sidePositionClass[side])}
+          >
+            {label}
+          </span>
+        )
       ) : (
         <span
           id={id}
@@ -506,6 +574,9 @@ function PortalTooltip({
 
   return (
     <>
+      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- as in
+          `InPlaceTooltip`: the handlers only show and hide the bubble; the caller's child
+          is the interactive element, and focusing it shows the bubble. */}
       <span
         // As in `InPlaceTooltip`: the caller's attributes first, the four handlers that
         // run this component after them. The BUBBLE is deliberately not given them — it