@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/progress-bar.tsx

@@ -3,6 +3,19 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
 
+/** The words a progress bar adds of its own. */
+export interface ProgressBarLabels {
+  /** Shown after the value when `max={null}`: a quota with no ceiling. */
+  unlimited: string;
+  /** The `overage` line: how far past `max` the value is. `amount` is formatted. */
+  overLimit: (amount: string) => string;
+}
+
+export const DEFAULT_PROGRESS_BAR_LABELS: ProgressBarLabels = {
+  unlimited: "Unlimited",
+  overLimit: (amount) => `${amount} over the limit`,
+};
+
 /**
  * `income` / `expense` are the money pair (`--money-income` / `--money-expense`), the
  * names `Chip`, `StatTile` and `Sparkline` already use for them: a share bar of what
@@ -41,12 +54,69 @@ const FILL: Record<ProgressBarTone, string> = {
 
 const TRACK_HEIGHT: Record<ProgressBarSize, string> = { sm: "h-1", slim: "h-1.5", md: "h-2", lg: "h-3" };
 
+// A segment with no tone of its own takes the next categorical chart colour, so a
+// stacked bar of unnamed parts is still a set of tellable parts rather than one fill.
+const SERIES_FILL = [
+  "bg-[var(--chart-1)]",
+  "bg-[var(--chart-2)]",
+  "bg-[var(--chart-3)]",
+  "bg-[var(--chart-4)]",
+  "bg-[var(--chart-5)]",
+  "bg-[var(--chart-6)]",
+  "bg-[var(--chart-7)]",
+  "bg-[var(--chart-8)]",
+  "bg-[var(--chart-9)]",
+];
+
+/** Each segment's fill classes: its own classes, else its tone, else (with no `color`)
+ *  the next chart colour. "Next" counts the UNCOLOURED segments only — a segment with
+ *  its own `className`/`tone`/`color` does not use up `--chart-1`, so an "Other" in grey
+ *  ahead of two plain parts leaves them `--chart-1` and `--chart-2`. */
+function segmentFills(segments: ProgressBarSegment[]): Array<string | undefined> {
+  let next = 0;
+  return segments.map((seg) => {
+    if (seg.className) return seg.className;
+    if (seg.tone) return FILL[seg.tone];
+    return seg.color ? undefined : SERIES_FILL[next++ % SERIES_FILL.length];
+  });
+}
+
+/** One part of a stacked bar. See {@link ProgressBarProps.segments}. */
+export interface ProgressBarSegment {
+  /** Its size, on the bar's own `min`–`max` scale. */
+  value: number;
+  /** A kit tone. Left out (and no `color`/`className`), the next `--chart-N` colour. */
+  tone?: ProgressBarTone;
+  /** Any CSS colour (`var(--token)`), for a palette the tones do not cover. Wins over `tone`. */
+  color?: string;
+  /** Classes for the segment's fill — keksdose's `STEP_CLASS` ramp. Wins over `tone`. */
+  className?: string;
+  /** The part's name: said in the bar's `aria-valuetext` and shown in the legend. */
+  label?: ReactNode;
+  /** A stable React key, when `label` is not a string. */
+  key?: string;
+  /**
+   * List it in the `legend` but leave it out of the bar — its value, its share of the
+   * `aria-valuetext`, and the sum. keksdose's cut card (reports/cut-card:132) names
+   * EVERY bucket under its bar, the empty ones included, while the bar draws only the
+   * ones with a share: pass the empty buckets as `legendOnly` entries.
+   */
+  legendOnly?: boolean;
+}
+
 export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
   /** Where it stands. Leave it undefined for an INDETERMINATE bar — work is under way
    *  and nobody knows how much is left (an import that reports no count). */
   value?: number;
   min?: number;
-  max?: number;
+  /**
+   * The top of the scale (default 100). `null` is a quota with NO ceiling — kastlan's
+   * billing usage on an unlimited plan (usage-progress-bar:25): nothing to fill, so no
+   * bar is drawn; the label row shows the value and "Unlimited" (`progressBar.unlimited`)
+   * as plain text. `formatValue` is then called with `max` = `Infinity`; without it,
+   * the value is a plain number in the kit's locale.
+   */
+  max?: number | null;
   /**
    * `progress` (default): a task moving toward completion — `role="progressbar"`.
    * `meter`: a share of a known whole that is not going anywhere (budget used, disk
@@ -69,6 +139,39 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
   tone?: ProgressBarTone;
   size?: ProgressBarSize;
   locale?: string;
+  /**
+   * Draw a METER OF PARTS: one bar, several fills side by side in order, a 2px gap
+   * between them — keksdose's discretionary-spending bar (cut-card:133), a whole
+   * split into the steps of a scale. Forces `variant="meter"`: parts of a whole are
+   * never "busy". `aria-valuenow` is the sum; `aria-valuetext` names every part
+   * ("Rent: 40%, Food: 25%"), each part's value through `formatValue` and joined in the
+   * kit's locale — the words keksdose's hand-drawn bar had to hide from a reader
+   * altogether, leaving the legend as the only way in. The sum is clamped to `max`,
+   * and parts past it are cut off at the track's end.
+   */
+  segments?: ProgressBarSegment[];
+  /** With `segments`: a list under the bar naming each part with its swatch and value
+   *  — the table view of the bar, in text tokens rather than the segment colour. */
+  legend?: boolean;
+  /**
+   * What a legend row shows at its end, in place of the part's formatted value — which
+   * it is handed, with the segment and its index. keksdose's cut card shows the share
+   * AND a private outflow amount per bucket (cut-card:150), which one figure could not:
+   * `legendValue={(seg, share) => <>{share} <Amount … /></>}`.
+   */
+  legendValue?: (segment: ProgressBarSegment, formatted: string, index: number) => ReactNode;
+  /** A muted line under the bar — the plan's reset date, "3 of 5 seats in use". It
+   *  describes the bar (`aria-describedby`). */
+  hint?: ReactNode;
+  /**
+   * When `value` is past `max`, say by how much, in a danger-coloured line under the bar
+   * (kastlan usage-progress-bar:46): `true` prints `progressBar.overLimit` with the
+   * excess as a plain number; a function renders the line itself from the excess (a
+   * currency, "2 seats"). The bar stays full at `max` either way — colour it with
+   * `tone="danger"` if it should read as over. Ignored for `segments` and `max={null}`.
+   */
+  overage?: boolean | ((over: number) => ReactNode);
+  labels?: Partial<ProgressBarLabels>;
 }
 
 /**
@@ -91,7 +194,7 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
 export function ProgressBar({
   value,
   min = 0,
-  max = 100,
+  max: maxProp = 100,
   variant = "progress",
   label,
   showValue = false,
@@ -99,28 +202,105 @@ export function ProgressBar({
   tone = "brand",
   size = "md",
   locale,
+  segments,
+  legend = false,
+  legendValue,
+  hint,
+  overage,
+  labels,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
   ...rest
 }: ProgressBarProps) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const text = useKitLabels("progressBar", DEFAULT_PROGRESS_BAR_LABELS, labels);
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
+  const hintId = useId();
+  const hintNode =
+    hint != null ? (
+      <p id={hintId} data-part="hint" className="mt-1 text-xs text-[var(--text-muted)]">
+        {hint}
+      </p>
+    ) : null;
 
-  const meter = variant === "meter";
-  const current = value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value;
-  const indeterminate = current === undefined;
+  if (maxProp === null) {
+    // No ceiling: no bar, no role — a meter with no maximum is not one. The value and
+    // "Unlimited" are the content, so they are plain visible text.
+    const shown =
+      value === undefined || !Number.isFinite(value)
+        ? undefined
+        : formatValue
+          ? formatValue(value, Infinity, min)
+          : new Intl.NumberFormat(kitLocale).format(value);
+    return (
+      <div {...rest} className={cn("min-w-0", className)} data-state="unlimited">
+        <div className="flex items-baseline gap-2 text-sm">
+          {label != null && (
+            <span id={labelId} className="min-w-0 text-[var(--text-secondary)]">
+              {label}
+            </span>
+          )}
+          <span data-part="unlimited" className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
+            {shown !== undefined && `${shown} · `}
+            {text.unlimited}
+          </span>
+        </div>
+        {hintNode}
+      </div>
+    );
+  }
+  const max = maxProp;
+
+  const stacked = segments !== undefined;
+  const meter = stacked || variant === "meter";
   const span = max - min;
+  const partValue = (v: number) => (Number.isFinite(v) ? Math.max(0, v - min) : 0);
+  // Colours are dealt over EVERY segment, legend-only ones included, so an entry keeps
+  // its swatch whether or not it is in the bar this time.
+  const fills = stacked ? segmentFills(segments) : [];
+  const barParts = stacked ? segments.filter((seg) => !seg.legendOnly) : [];
+  const partTotal = stacked ? min + barParts.reduce((sum, seg) => sum + partValue(seg.value), 0) : undefined;
+  const format = (v: number) =>
+    formatValue
+      ? formatValue(v, max, min)
+      : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(
+          span <= 0 ? 0 : (Math.min(max, Math.max(min, v)) - min) / span,
+        );
+  const partTexts = stacked
+    ? barParts.map((seg) => {
+        const text = format(min + partValue(seg.value));
+        return typeof seg.label === "string" || typeof seg.label === "number"
+          ? common.fieldValue(String(seg.label), text)
+          : text;
+      })
+    : [];
+  const current =
+    partTotal ?? (value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value);
+  const indeterminate = current === undefined;
   const clamped = indeterminate ? undefined : Math.min(max, Math.max(min, current));
   const fraction = clamped === undefined || span <= 0 ? 0 : (clamped - min) / span;
 
-  const valueText =
-    clamped === undefined
-      ? undefined
-      : formatValue
-        ? formatValue(clamped, max, min)
-        : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(fraction);
+  const valueText = clamped === undefined ? undefined : format(clamped);
+  const ariaValueText =
+    stacked && partTexts.length > 0
+      ? new Intl.ListFormat(kitLocale, { style: "short", type: "unit" }).format(partTexts)
+      : valueText;
+
+  const over =
+    overage && !stacked && value !== undefined && Number.isFinite(value) && value > max ? value - max : 0;
+  const overageNode =
+    over > 0 ? (
+      <p id={`${hintId}-over`} data-part="overage" className="mt-1 text-xs text-[var(--danger)]">
+        {typeof overage === "function"
+          ? overage(over)
+          : text.overLimit(new Intl.NumberFormat(kitLocale).format(over))}
+      </p>
+    ) : null;
+  const describedBy =
+    [ariaDescribedBy, hintNode && hintId, overageNode && `${hintId}-over`].filter(Boolean).join(" ") || undefined;
 
   const labelledBy = ariaLabelledBy ?? (label != null ? labelId : undefined);
   const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
@@ -148,16 +328,38 @@ export function ProgressBar({
         role={meter ? "meter" : "progressbar"}
         aria-label={name}
         aria-labelledby={labelledBy}
+        aria-describedby={describedBy}
         aria-valuemin={indeterminate ? undefined : min}
         aria-valuemax={indeterminate ? undefined : max}
         aria-valuenow={clamped}
-        aria-valuetext={valueText}
+        aria-valuetext={ariaValueText}
         aria-busy={!meter && indeterminate ? true : undefined}
         // `relative` + `overflow-hidden`: the indeterminate segment is positioned in
         // here and must not paint past the rounded ends.
         className={cn("relative w-full overflow-hidden rounded-full bg-[var(--bg-active)]", TRACK_HEIGHT[size])}
       >
-        {indeterminate ? (
+        {stacked ? (
+          // The parts in a flex row with a 2px gap, so two neighbouring steps of one
+          // hue are parted by the track rather than by their difference in lightness.
+          <div className="flex h-full w-full gap-0.5">
+            {segments.map((seg, i) =>
+              seg.legendOnly ? null : (
+                <div
+                  key={seg.key ?? i}
+                  data-part="segment"
+                  className={cn(
+                    "h-full shrink-0 rounded-full transition-[width] duration-300 motion-reduce:transition-none",
+                    fills[i],
+                  )}
+                  style={{
+                    width: `${span <= 0 ? 0 : (partValue(seg.value) / span) * 100}%`,
+                    backgroundColor: seg.className ? undefined : seg.color,
+                  }}
+                />
+              ),
+            )}
+          </div>
+        ) : indeterminate ? (
           <div
             data-part="fill"
             className={cn(
@@ -182,6 +384,32 @@ export function ProgressBar({
           />
         )}
       </div>
+      {stacked && legend && segments.length > 0 && (
+        <ul className="mt-2 space-y-1 text-sm" data-part="legend">
+          {segments.map((seg, i) => (
+            <li key={seg.key ?? i} className="flex items-center gap-2">
+              <span
+                aria-hidden
+                className={cn(
+                  "size-2.5 shrink-0 rounded-sm",
+                  fills[i],
+                )}
+                style={{ backgroundColor: seg.className ? undefined : seg.color }}
+              />
+              {seg.label != null && (
+                <span className="min-w-0 flex-1 truncate text-[var(--text-secondary)]">{seg.label}</span>
+              )}
+              <span className="ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]">
+                {legendValue
+                  ? legendValue(seg, format(min + partValue(seg.value)), i)
+                  : format(min + partValue(seg.value))}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+      {overageNode}
+      {hintNode}
     </div>
   );
 }

package/src/components/qr-code.tsx

@@ -0,0 +1,83 @@
+import { useMemo } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+import { encodeQr } from "../lib/qr-encode";
+import type { QrErrorCorrection } from "../lib/qr-encode";
+
+export interface QrCodeProps extends Omit<ComponentPropsWithoutRef<"svg">, "children" | "viewBox"> {
+  /** The text to encode (UTF-8) — an `otpauth://` URI, a URL, a pairing code. */
+  value: string;
+  /** The accessible name. Without it the code is decorative (`aria-hidden`): say what
+   *  it is for, not what it encodes — nobody wants a URI read out. */
+  label?: string;
+  /** Default `"M"`, raised automatically where the size allows it. */
+  errorCorrection?: QrErrorCorrection;
+  /** The quiet zone, in modules. The spec asks for 4; less reads worse. Default 4. */
+  margin?: number;
+}
+
+/**
+ * A QR code as one inline SVG — no canvas, no data URL, no dependency (see
+ * `lib/qr-encode.ts` for why the encoder lives in the kit).
+ *
+ * Sized by CSS (`className="size-48"`); the SVG scales without blurring because every
+ * module is a whole unit of the viewBox and `shape-rendering` is `crispEdges`.
+ *
+ * **Black on white, always — the one literal colour pair in the kit.** A camera looks
+ * for the contrast between the modules and their quiet zone; on the dark theme a
+ * surface-coloured background makes a code slow to acquire, and an inverted one is not
+ * read at all by several authenticator apps. The quiet zone is part of the SVG, so the
+ * code carries its own white border wherever it is placed.
+ *
+ * A value too long for any QR version (≈2.9 kB) renders nothing rather than throwing
+ * in render.
+ */
+export function QrCode({
+  value,
+  label,
+  errorCorrection = "M",
+  margin = 4,
+  className,
+  ...rest
+}: QrCodeProps) {
+  const path = useMemo(() => {
+    try {
+      const { modules, size } = encodeQr(value, { errorCorrection });
+      // One path, one sub-path per horizontal run of dark modules: a few hundred
+      // commands rather than one <rect> per module.
+      let d = "";
+      for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; ) {
+          if (!modules[y][x]) {
+            x++;
+            continue;
+          }
+          let run = 1;
+          while (x + run < size && modules[y][x + run]) run++;
+          d += `M${x + margin} ${y + margin}h${run}v1h-${run}z`;
+          x += run;
+        }
+      }
+      return { d, extent: size + margin * 2 };
+    } catch {
+      return null;
+    }
+  }, [value, errorCorrection, margin]);
+
+  if (!path) return null;
+  return (
+    <svg
+      {...rest}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={`0 0 ${path.extent} ${path.extent}`}
+      shapeRendering="crispEdges"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={cn("block", className)}
+    >
+      <rect width={path.extent} height={path.extent} fill="#ffffff" />
+      <path d={path.d} fill="#000000" />
+    </svg>
+  );
+}

package/src/components/search-field.tsx

@@ -3,6 +3,7 @@ import type { InputHTMLAttributes } from "react";
 import { Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
 import { FIELD_BASE } from "./ui";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 
 interface SearchFieldOwnProps
   extends Omit<
@@ -23,10 +24,22 @@ interface SearchFieldOwnProps
    * absent, so a consumer can migrate one call site at a time.
    */
   label?: string;
-  /** Names the clear button. Omit it and no clear button is rendered — which is a
-   *  decision, not a default: a filter you can type into and not untype is the
-   *  complaint that produced the button on three of these four screens. */
+  /** Names the clear button. Default: the catalogue's `common.clear`, in the
+   *  provider's language. */
   clearLabel?: string;
+  /**
+   * Draw the "×" that empties the field once there is something in it. Default
+   * `true`.
+   *
+   * It used to appear only when a `clearLabel` was passed, and every kastlan call
+   * site passed one — lease-list-page.tsx:91, trial-balance-page.tsx:~196,
+   * account-ledger-page.tsx:~131 and data-table/resource-list-page.tsx:256 each
+   * spelled `clearLabel={t("table.clear")}` — so the opt-in was boilerplate: a filter
+   * you can type into and not untype is the complaint that produced the button in
+   * the first place, and the catalogue already names it. `false` is for a field
+   * whose clearing lives elsewhere (a "Reset filters" beside it).
+   */
+  clearable?: boolean;
   /**
    * `"field"` (default): the bordered filter box that sits on a page.
    *
@@ -96,7 +109,8 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
     value,
     onChange,
     label,
-    clearLabel,
+    clearLabel: clearLabelProp,
+    clearable = true,
     className,
     inputClassName,
     placeholder,
@@ -107,6 +121,8 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
   ref,
 ) {
   const innerRef = useRef<HTMLInputElement>(null);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const clearLabel = clearable ? (clearLabelProp ?? common.clear) : undefined;
   // Whichever spelling the caller used. It is the accessible name AND the placeholder
   // fallback, so a box named only by `aria-label` still says what it is before anyone
   // has typed in it — the same deal `label` has always had.

package/src/components/series-chart.tsx

@@ -129,6 +129,18 @@ export interface SeriesChartSeries {
    * `{ r }` sets its radius. Default: recharts' dot. Bars have none, and ignore it.
    */
   activeDot?: boolean | { r?: number };
+  /**
+   * The shortest a bar of this series is drawn, in px — recharts' `minPointSize`. A
+   * zero or a value too small to see keeps a visible stub, so an empty slot still reads
+   * as a slot with a value rather than a gap: keksdose's weekday pattern, where a
+   * Sunday with no spending drew a 2% stub by hand. Only the DRAWING changes: the axis
+   * is fitted to the values, and the tooltip, the keyboard stops and every accessible
+   * name still say 0. A hole (no value in the row) stays a hole. Overrides the chart's
+   * {@link SeriesChartProps.minBarLength}; `0` turns it off for this series. Meant for
+   * unstacked bars — in a `stack` the stub is drawn over the layer above it. Lines and
+   * areas ignore it.
+   */
+  minBarLength?: number;
 }
 
 /** What a series draws. See {@link SeriesChartSeries.type}. */
@@ -507,6 +519,10 @@ export interface SeriesChartProps {
   locale?: string;
   /** Onto the chart's root (`ChartContainer`) — e.g. an app's own grid ink. */
   className?: string;
+  /** The shortest bar drawn, in px, for every bar series that does not set its own
+   *  {@link SeriesChartSeries.minBarLength}. Drawing only: domain, tooltip and names
+   *  keep the real value. Default: none — a zero draws nothing. */
+  minBarLength?: number;
 }
 
 /** How much of an axis band the rotated title takes, in px. Reserved rather than
@@ -1011,6 +1027,7 @@ function SeriesPlot({
   labels: labelsProp,
   locale: localeProp,
   className,
+  minBarLength,
 }: PlotProps) {
   const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
   const locale = useKitLocale(localeProp);
@@ -1418,6 +1435,7 @@ function SeriesPlot({
           const curve = entry.step ? "stepAfter" : (entry.curve ?? "monotone");
           const width = entry.strokeWidth ?? (entry.step ? STEP_WIDTH : LINE_WIDTH);
           if (type === "bar") {
+            const stub = entry.minBarLength ?? minBarLength;
             return (
               <Bar
                 key={entry.key}
@@ -1427,6 +1445,9 @@ function SeriesPlot({
                 fill={color}
                 fillOpacity={entry.fillOpacity}
                 radius={entry.stack === undefined ? BAR_RADIUS : 0}
+                // Read off the row rather than recharts' `value`: in a stack that is the
+                // layer's running top, which a hole has too — and a hole gets no stub.
+                {...(stub ? { minPointSize: (_value: unknown, index: number) => (finite(plotted[index]?.[entry.key]) === undefined ? 0 : stub) } : {})}
                 // Only the focused stop's series swaps its shape, and only for as long
                 // as it has focus: every other bar keeps recharts' own.
                 {...(focusedStop?.key === entry.key ? { shape: focusedBarShape(focusedStop.index) } : {})}