@eifi1/ui-kit 0.9.0 → 0.11.0

package/src/components/nav-pills.tsx

@@ -0,0 +1,145 @@
+import type { ComponentPropsWithoutRef, ComponentType, MouseEvent, ReactElement, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export interface NavPillItem<T extends string> {
+  value: T;
+  label: ReactNode;
+  /** Where the pill leads. With one it is a link (see `renderLink`); without, a button
+   *  that calls `onSelect`. */
+  href?: string;
+  /** A Lucide icon (or any component taking a `className`), before the label. */
+  icon?: ComponentType<{ className?: string; "aria-hidden"?: boolean }>;
+  /** Buttons only — a link cannot be disabled. */
+  disabled?: boolean;
+}
+
+/** What {@link NavPillsProps.renderLink} is handed. Spread it onto your router's link
+ *  — `({ href, ...p }) => <Link to={href} {...p} />`. */
+export interface NavPillLinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+  "aria-current": NavPillsCurrent | undefined;
+  onClick: (e: MouseEvent<HTMLAnchorElement>) => void;
+}
+
+/** The `aria-current` token the current pill carries. */
+export type NavPillsCurrent = "page" | "step" | "location" | "true";
+
+export interface NavPillsProps<T extends string> extends Omit<ComponentPropsWithoutRef<"nav">, "children" | "onSelect"> {
+  items: NavPillItem<T>[];
+  /** The pill that is current. `null` or a value not in `items`: none is. */
+  current: T | null;
+  /** Called with the pill's value on a click — of a button, and of a link too (before
+   *  the router follows it), for a caller that keeps the choice in state as well. */
+  onSelect?: (value: T) => void;
+  /** Your router's link. Default `<a>`. The API `Breadcrumbs`, `Chip` and `ListItem` share. */
+  renderLink?: (props: NavPillLinkProps) => ReactElement;
+  /** What `aria-current` says on the current pill. Default `page` where the items
+   *  are links and `true` where they are buttons (keksdose's swipe-surface picker
+   *  switches a panel on the same page, which is not a page). */
+  currentType?: NavPillsCurrent;
+  /** `sm`: 12px pills — the compact size of a {@link ToggleGroup}. Default `md`. */
+  size?: "sm" | "md";
+  /** Render a `<nav>` landmark (default) or a plain `<div role="group">` for a picker
+   *  that is not the page's navigation. Name either with `aria-label`. */
+  landmark?: boolean;
+  /** Classes for every pill. */
+  itemClassName?: string;
+}
+
+// The pill is a ToggleGroup segment's (`rounded`, `px-3 py-1.5`, the inverse fill for
+// the current one), so a strip of these beside a segmented control reads as the same
+// family. Unlike the segments, a pill never truncates: the strip WRAPS instead.
+const PILL =
+  "inline-flex items-center gap-1.5 whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-strong)] [&_svg]:size-4 [&_svg]:shrink-0";
+const PILL_SM = "gap-1 px-2 py-1 text-xs [&_svg]:size-3.5";
+const PILL_CURRENT = "bg-[var(--bg-inverse)] text-[var(--text-inverse)]";
+const PILL_IDLE = "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]";
+const PILL_DISABLED = "cursor-not-allowed opacity-50 hover:bg-transparent hover:text-[var(--text-secondary)]";
+
+/**
+ * A set of links or buttons that WRAPS onto as many rows as it needs, the current one
+ * filled and marked `aria-current`.
+ *
+ * keksdose's swipe-settings card (swipe-settings-card:152) hand-rolled this: four
+ * surface names that do not fit a 406px phone, and a sideways scroll would hide the
+ * ones that do not fit behind a gesture nothing announces (live #332: *"Have the tabs
+ * in more rows, rather than scrolling sideways"*). It is not {@link Tabs} with `wrap`
+ * because its items are not tabs: a `role="tab"` promises a tabpanel, a roving tab
+ * stop and arrow keys, and a set of links to pages (or of buttons that switch the rest
+ * of a card) promises none of that. So every pill is its own tab stop, the set is a
+ * list (a screen reader hears "list, 4 items"), and "current" is `aria-current` — the
+ * attribute a link to where you already are carries.
+ */
+export function NavPills<T extends string>({
+  items,
+  current,
+  onSelect,
+  renderLink,
+  currentType,
+  size = "md",
+  landmark = true,
+  itemClassName,
+  className,
+  ...rest
+}: NavPillsProps<T>) {
+  const Root = landmark ? "nav" : "div";
+  return (
+    <Root {...rest} role={landmark ? undefined : "group"} className={cn("min-w-0", className)}>
+      <ul className="m-0 flex list-none flex-wrap gap-1 p-0">
+        {items.map((item) => {
+          const isCurrent = item.value === current;
+          const Icon = item.icon;
+          const pillClass = cn(
+            PILL,
+            size === "sm" && PILL_SM,
+            isCurrent ? PILL_CURRENT : PILL_IDLE,
+            item.disabled && item.href === undefined && PILL_DISABLED,
+            itemClassName,
+          );
+          const children = (
+            <>
+              {Icon && <Icon aria-hidden />}
+              {item.label}
+            </>
+          );
+          let pill: ReactNode;
+          if (item.href !== undefined) {
+            const props: NavPillLinkProps = {
+              href: item.href,
+              className: pillClass,
+              children,
+              "aria-current": isCurrent ? (currentType ?? "page") : undefined,
+              onClick: () => onSelect?.(item.value),
+            };
+            pill = renderLink ? (
+              renderLink(props)
+            ) : (
+              <a href={props.href} className={props.className} aria-current={props["aria-current"]} onClick={props.onClick}>
+                {props.children}
+              </a>
+            );
+          } else {
+            pill = (
+              <button
+                type="button"
+                disabled={item.disabled}
+                aria-current={isCurrent ? (currentType ?? "true") : undefined}
+                onClick={() => onSelect?.(item.value)}
+                className={pillClass}
+              >
+                {children}
+              </button>
+            );
+          }
+          return (
+            <li key={item.value} className="flex">
+              {pill}
+            </li>
+          );
+        })}
+      </ul>
+    </Root>
+  );
+}

package/src/components/page-contents.tsx

@@ -176,14 +176,14 @@ export function PageContents({
           <li key={item.id} data-entry={item.id}>
             <a
               href={hrefFor(item.id)}
-              // One line per entry in the rail; past 22rem the ellipsis takes over and
-              // the full text is on hover. The disclosure has the page's width and wraps.
-              title={variant === "rail" && typeof item.label === "string" ? item.label : undefined}
+              // Entries WRAP in the rail rather than truncate: a cut-off heading needed a
+              // native `title` to be read at all, which a keyboard never sees and which
+              // broke keksdose's one-tooltip rule (dev#523).
               aria-current={current ? "location" : undefined}
               onClick={() => setClicked(item.id)}
               className={cn(
                 "-ms-px block border-s-2 py-1 pe-1 text-[13px] leading-snug transition-colors duration-150",
-                variant === "rail" && "truncate",
+                variant === "rail" && "[overflow-wrap:anywhere]",
                 item.level === 2 ? "ps-6" : "ps-3",
                 current
                   ? "border-[var(--brand)] font-medium text-[var(--brand)]"

package/src/components/page-header.tsx

@@ -0,0 +1,68 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { SECTION_LABEL_CLASS } from "./text";
+
+/** `md` (default) is kastlan's `text-2xl` page title from `sm` up, a step smaller on a
+ *  phone; `sm` is lenkbank's `text-lg` title on a dense tool page (projects-page.tsx). */
+export type PageHeaderSize = "sm" | "md";
+
+const TITLE: Record<PageHeaderSize, string> = {
+  sm: "text-lg font-semibold",
+  md: "text-xl font-semibold tracking-tight sm:text-2xl",
+};
+
+export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  title: ReactNode;
+  /** A sentence under the title. */
+  description?: ReactNode;
+  /** Buttons for the page — "New", "Export". At the title's end from `sm` up; under it,
+   *  wrapping, on a phone. */
+  actions?: ReactNode;
+  /** A `Breadcrumbs` trail, drawn above everything else. */
+  breadcrumbs?: ReactNode;
+  /** A small uppercase line above the title — the section or the kind of record
+   *  ("Building", "Settings"). The section-label type. */
+  eyebrow?: ReactNode;
+  /** The title's element. Default `h1`: a page has one, and this is it. `h2` for a
+   *  header inside a page that already has its `h1` (a tab's own header). */
+  as?: "h1" | "h2" | "h3";
+  size?: PageHeaderSize;
+}
+
+/**
+ * A page's head: optional breadcrumbs, an eyebrow, the title, a description, and the
+ * page's actions.
+ *
+ * kastlan's (shared/components/display/page-header.tsx) is the model — title and
+ * description on one side, actions on the other, stacked on a phone — and this adds
+ * what its pages kept writing around it: a trail above, an eyebrow, a `ReactNode`
+ * title (a status chip beside the name), and actions that WRAP when there are more
+ * than fit a phone's width, instead of running off it. No outer margin: the page's
+ * own rhythm (`space-y-*`, a grid gap) places it.
+ */
+export function PageHeader({
+  title,
+  description,
+  actions,
+  breadcrumbs,
+  eyebrow,
+  as = "h1",
+  size = "md",
+  className,
+  ...rest
+}: PageHeaderProps) {
+  const Heading = as as ElementType;
+  return (
+    <div {...rest} className={cn("flex min-w-0 flex-col gap-2", className)}>
+      {breadcrumbs}
+      <div className="flex min-w-0 flex-col gap-3 sm:flex-row sm:items-start sm:justify-between sm:gap-4">
+        <div className="min-w-0 flex-1">
+          {eyebrow != null && <p className={cn(SECTION_LABEL_CLASS.xs, "mb-1")}>{eyebrow}</p>}
+          <Heading className={cn("break-words text-[var(--text-primary)]", TITLE[size])}>{title}</Heading>
+          {description != null && <p className="mt-1 text-sm text-[var(--text-muted)]">{description}</p>}
+        </div>
+        {actions != null && <div className="flex shrink-0 flex-wrap items-center gap-2">{actions}</div>}
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar.tsx

@@ -41,6 +41,49 @@ 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;
+}
+
 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). */
@@ -69,6 +112,20 @@ 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;
 }
 
 /**
@@ -99,6 +156,8 @@ export function ProgressBar({
   tone = "brand",
   size = "md",
   locale,
+  segments,
+  legend = false,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
@@ -108,19 +167,37 @@ export function ProgressBar({
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
 
-  const meter = variant === "meter";
-  const current = value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value;
-  const indeterminate = current === undefined;
+  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);
+  const fills = stacked ? segmentFills(segments) : [];
+  const partTotal = stacked ? min + segments.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
+    ? segments.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 labelledBy = ariaLabelledBy ?? (label != null ? labelId : undefined);
   const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
@@ -151,13 +228,32 @@ export function ProgressBar({
         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) => (
+              <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 +278,28 @@ 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)]">
+                {format(min + partValue(seg.value))}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
     </div>
   );
 }

package/src/components/series-chart-labels.ts

@@ -15,6 +15,9 @@ export interface SeriesChartLabels {
   empty: string;
   /** Accessible name of a `ToggleLegend` — a group of switches, one per series. */
   legend: string;
+  /** Accessible name of the group of keyboard stops a clickable chart (`onPointClick`)
+   *  lays over its bars or periods — one tab stop, arrow keys between them. */
+  points: string;
 }
 
 export const DEFAULT_SERIES_CHART_LABELS: SeriesChartLabels = {
@@ -23,4 +26,5 @@ export const DEFAULT_SERIES_CHART_LABELS: SeriesChartLabels = {
     "Drag to zoom: a roughly square selection zooms both axes, a long thin one only its own. Double-click to reset.",
   empty: "No data",
   legend: "Series",
+  points: "Chart values",
 };