@elabs-ai/components-ui 4.0.0

package/src/components/metric-card/metric-card.tsx

@@ -0,0 +1,229 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Card, CardContent } from "../card";
+import { CopyableValue } from "../copyable-value";
+import { Skeleton } from "../skeleton";
+import { useLocale } from "../locale-provider";
+import { cn } from "../../lib/cn";
+import { type NumberFormatKind, numberFormatOptions } from "../../lib/compact-number";
+
+/*
+ * `emphasis` — size/weight/space ONLY, no new hue (research 11 §B.5 KPI-1/5):
+ * `headline` is the answer-leading rung (`text-kpi`, ~32px); `default` stays
+ * calm on the intermediate 1.5rem reading rung (the pre-#188 step between
+ * `title` and `kpi` — no app role exists there, same precedent as the prose
+ * h1/h3 rungs; baselined in the text-scale ratchet).
+ */
+const metricValueVariants = cva("tabular-nums text-foreground", {
+  variants: {
+    emphasis: {
+      default: "text-2xl font-semibold tracking-tight",
+      headline: "text-kpi",
+    },
+  },
+  defaultVariants: { emphasis: "default" },
+});
+
+const metricContentVariants = cva("space-y-2", {
+  variants: {
+    emphasis: {
+      default: "p-5",
+      headline: "p-6",
+    },
+  },
+  defaultVariants: { emphasis: "default" },
+});
+
+export type MetricCardEmphasis = NonNullable<VariantProps<typeof metricValueVariants>["emphasis"]>;
+
+/**
+ * How a NUMERIC `value` is rendered. A function takes over completely.
+ *
+ * `"compact"` is the default because a KPI tile is a small box and
+ * `50012102.632741` does not fit in one — the exact figure stays one click
+ * away via `CopyableValue`. Anything that is not a `number` (a string, an
+ * element) is passed through untouched, so every existing call site is
+ * unaffected.
+ */
+export type MetricCardValueFormat = NumberFormatKind | ((value: number) => ReactNode);
+
+export interface MetricCardProps
+  extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof metricValueVariants> {
+  label: ReactNode;
+  value: ReactNode;
+  /**
+   * How to render a NUMERIC `value`. Default: `"compact"`. Ignored for every
+   * other `ReactNode` — a string you already formatted is rendered verbatim.
+   */
+  valueFormat?: MetricCardValueFormat;
+  /** ISO 4217 code for `valueFormat: "currency"`. Default: `"USD"`. */
+  currency?: string;
+  /**
+   * Offer the exact figure on click when a numeric `value` was shortened.
+   * Default: `true`. Turning it off leaves a compacted number with no way back
+   * to its digits, so only do that when the tile is decorative.
+   */
+  copyExactValue?: boolean;
+  /** Secondary line under the value — sublabel / context. */
+  description?: ReactNode;
+  /** Signed change, e.g. "+12.4%". Direction colors it. */
+  delta?: string;
+  deltaDirection?: "up" | "down" | "neutral";
+  /** Whether "up" is good (green) — flip for metrics where down is good. */
+  positiveIsGood?: boolean;
+  icon?: ReactNode;
+  /** Optional inline visual (e.g. a sparkline) shown under the value/description. */
+  visual?: ReactNode;
+  /**
+   * Optional grounding footer (research 11 §B.5 KPI-3) — connects a cited
+   * figure to its source (e.g. an `EvidenceChip` from `@elabs-ai/components-ai`). Rendered
+   * subdued (`text-meta text-muted-foreground`) under the tile body.
+   */
+  evidence?: ReactNode;
+  /**
+   * Loading vs ready — renders a layout-shaped skeleton (matching the real
+   * box height) instead of the value/label/delta text. Default: `false`.
+   */
+  loading?: boolean;
+  /**
+   * Whether this tile announces its own `loading` state via a live region.
+   * Set to `false` when several tiles are composed inside a container that
+   * already announces once for the whole region (e.g. a loading
+   * `MetricGrid`) — see loading-states.md §a11y ("one live region per
+   * region, not per box"). Default: `true`.
+   */
+  announceLoading?: boolean;
+}
+
+/** Compact KPI tile for dashboards. */
+export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function MetricCard(
+  {
+    label,
+    value,
+    valueFormat = "compact",
+    currency,
+    copyExactValue = true,
+    description,
+    delta,
+    deltaDirection = "neutral",
+    positiveIsGood = true,
+    icon,
+    visual,
+    evidence,
+    emphasis,
+    loading = false,
+    announceLoading = true,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const { t, formatNumber } = useLocale();
+
+  // Formatting applies to NUMBERS only. Every shipped call site passes a string
+  // it formatted itself, so this branch is inert for them — that is what makes
+  // a new default safe.
+  const isNumeric = typeof value === "number";
+  const formattedValue: ReactNode = !isNumeric
+    ? value
+    : typeof valueFormat === "function"
+      ? valueFormat(value)
+      : formatNumber(value, numberFormatOptions(valueFormat, value, currency));
+  // Only offer the exact figure when the display actually differs from it —
+  // a button around a value that was never shortened is noise.
+  const showsExact = isNumeric && String(formattedValue) === String(value);
+  const canCopyExact =
+    isNumeric && copyExactValue && typeof valueFormat !== "function" && !showsExact;
+
+  const good =
+    deltaDirection === "up" ? positiveIsGood : deltaDirection === "down" ? !positiveIsGood : null;
+  const deltaColor =
+    good === null ? "text-muted-foreground" : good ? "text-success-text" : "text-destructive-text";
+  // Stable, theme-agnostic polarity hook. High decoration reveals a non-color
+  // polarity glyph from this attribute (decoration.css); chromatic themes ignore it
+  // and use color. Issue #162.
+  const polarity = good === null ? "neutral" : good ? "good" : "bad";
+  const arrow = deltaDirection === "up" ? "↑" : deltaDirection === "down" ? "↓" : "";
+  // Direction is conveyed visually by the arrow glyph + color; give AT a single
+  // unambiguous name ("up 12.4%, favorable") since neither the glyph nor color is a
+  // reliable signal (high decoration / high-contrast collapse the hue) — and good/bad
+  // polarity is otherwise invisible to AT. See accessibility.md, #162.
+  const directionLabel = deltaDirection === "up" ? "up" : deltaDirection === "down" ? "down" : "";
+  const polarityLabel = good === null ? "" : good ? ", favorable" : ", unfavorable";
+
+  return (
+    <Card ref={ref} className={cn("overflow-hidden", className)} {...props}>
+      <CardContent
+        className={metricContentVariants({ emphasis })}
+        {...(loading && announceLoading ? { role: "status", "aria-live": "polite" as const } : {})}
+      >
+        {loading && announceLoading ? (
+          <span className="sr-only">{t("ui.metricCard.loading")}</span>
+        ) : null}
+        <div className="flex items-center justify-between">
+          {loading ? (
+            <Skeleton className="h-4 w-24" />
+          ) : (
+            <span className="text-body font-medium text-muted-foreground">{label}</span>
+          )}
+          {icon ? <span className="text-muted-foreground [&_svg]:size-4">{icon}</span> : null}
+        </div>
+        <div className="flex items-baseline gap-2">
+          {loading ? (
+            <Skeleton className={emphasis === "headline" ? "h-9 w-28" : "h-8 w-24"} />
+          ) : canCopyExact ? (
+            <CopyableValue
+              className={metricValueVariants({ emphasis })}
+              // Two tiles in one grid can compact to the same display ("$1.2M"),
+              // and the visible label is a sibling node the button's name does
+              // not include — so without this a screen-reader user tabbing the
+              // grid hears the identical name twice. A non-string label has no
+              // text to borrow; the default hint stands.
+              hint={
+                typeof label === "string" ? `${label}, ${t("ui.copyableValue.hint")}` : undefined
+              }
+              value={String(value)}
+            >
+              {formattedValue}
+            </CopyableValue>
+          ) : (
+            <span className={metricValueVariants({ emphasis })}>{formattedValue}</span>
+          )}
+          {delta ? (
+            loading ? (
+              <Skeleton className="h-4 w-14" />
+            ) : (
+              <span
+                data-polarity={polarity}
+                className={cn("text-meta tabular-nums", deltaColor)}
+                aria-label={
+                  directionLabel ? `${directionLabel} ${delta}${polarityLabel}` : undefined
+                }
+              >
+                {arrow ? <span aria-hidden="true">{arrow} </span> : null}
+                {delta}
+              </span>
+            )
+          ) : null}
+        </div>
+        {description ? (
+          loading ? (
+            <Skeleton className="h-3 w-32" />
+          ) : (
+            <p className="text-meta font-normal text-muted-foreground">{description}</p>
+          )
+        ) : null}
+        {visual ? (
+          <div className="pt-1">{loading ? <Skeleton className="h-8 w-full" /> : visual}</div>
+        ) : null}
+        {evidence ? (
+          <div className="pt-1 text-meta font-normal text-muted-foreground">
+            {loading ? <Skeleton className="h-3 w-24" /> : evidence}
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+});

package/src/components/model-picker/index.ts

@@ -0,0 +1,11 @@
+export { ModelPicker } from "./model-picker";
+export type { ModelPickerProps } from "./model-picker";
+export {
+  countItems,
+  modelPickerBody,
+  showsInlineError,
+  type ModelPickerBody,
+  type ModelPickerGroup,
+  type ModelPickerItem,
+  type ModelPickerStatus,
+} from "./model-picker-state";

package/src/components/model-picker/model-picker-state.ts

@@ -0,0 +1,85 @@
+/**
+ * `ModelPicker`'s two state decisions, kept OUT of the component on purpose.
+ *
+ * Both were inline ternaries in the consuming app this component came from, and
+ * both survived every mutation thrown at them — because no test could reach an
+ * expression buried in JSX. As exported pure functions they are directly
+ * testable, which is the whole reason they live in their own module.
+ */
+
+/** What the picker knows about the list it was handed. */
+export type ModelPickerStatus = "idle" | "loading" | "ready" | "stale" | "error" | "empty";
+
+/** Which of the four mutually-exclusive bodies the popover renders. */
+export type ModelPickerBody = "loading" | "list" | "error" | "empty";
+
+/**
+ * Pick the body.
+ *
+ * **A non-empty list always wins.** A failed refresh over usable stale data is an
+ * inline strip above a working list (see `showsInlineError`), never a takeover —
+ * collapsing "stale list + error" into "error panel" throws away a list the user
+ * could still have picked from.
+ */
+export function modelPickerBody(status: ModelPickerStatus, itemCount: number): ModelPickerBody {
+  if (itemCount > 0) return "list";
+  if (status === "loading" || status === "idle") return "loading";
+  if (status === "error" || status === "stale") return "error";
+  return "empty";
+}
+
+/**
+ * Whether to show the error line ABOVE a list that still works — i.e. the
+ * refresh failed but there is stale data worth keeping on screen.
+ */
+export function showsInlineError(status: ModelPickerStatus, itemCount: number): boolean {
+  return itemCount > 0 && (status === "stale" || status === "error");
+}
+
+/** One selectable row. */
+export interface ModelPickerItem {
+  id: string;
+  label: string;
+  /** Muted second line. */
+  description?: string;
+  /**
+   * Extra strings cmdk should MATCH on without displaying — ids, a space or
+   * workspace name. This is what lets a search for "northwind" find a target
+   * whose visible label never says it.
+   */
+  keywords?: string[];
+  /**
+   * Leading glyph. A ReactNode, never a URL: a renderer with no remote origins
+   * cannot fetch a logo, so the caller supplies a bundled node.
+   */
+  icon?: React.ReactNode;
+  /**
+   * Trailing muted badges ("not provisioned", "no modes").
+   *
+   * Deliberately a caller-supplied ARRAY rather than derived from flags. A
+   * three-valued flag where absent means "undecided" renders as "not enabled"
+   * the moment a component computes the badge from `!flag` — which mislabels
+   * every row on a deployment that simply never probed. Keeping this a list the
+   * caller builds means the library cannot get that wrong on their behalf.
+   */
+  meta?: string[];
+  /** Disable this row without removing it. */
+  disabled?: boolean;
+}
+
+/** A titled group of rows. */
+export interface ModelPickerGroup {
+  key: string;
+  /**
+   * Rendered verbatim as the group heading. The CALLER derives it (`Apps ·
+   * northwind`, `Assistants · personal`) — the library never invents grouping or
+   * heading text from the data.
+   */
+  label: string;
+  items: ModelPickerItem[];
+}
+
+/** Total rows across all groups. */
+export function countItems(groups: readonly ModelPickerGroup[]): number {
+  return groups.reduce((n, g) => n + g.items.length, 0);
+}

package/src/components/model-picker/model-picker.stories.tsx

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AppWindow, Bot, Sparkles } from "lucide-react";
+import { useState } from "react";
+import { ModelPicker } from "./model-picker";
+import type { ModelPickerGroup } from "./model-picker-state";
+
+const groups: ModelPickerGroup[] = [
+  {
+    key: "auto",
+    label: "Auto",
+    items: [
+      {
+        id: "auto",
+        label: "Choose for me",
+        description: "Picks the best target for each question",
+        icon: <Sparkles className="size-4 shrink-0" aria-hidden="true" />,
+      },
+    ],
+  },
+  {
+    key: "apps-northwind",
+    label: "Apps · northwind",
+    items: [
+      {
+        id: "app-sales",
+        label: "Sales overview",
+        description: "Updated 2 days ago",
+        // "northwind" appears in no visible label on this row — typing it still
+        // finds the row, which is the most-used behaviour of this component.
+        keywords: ["northwind", "app-sales"],
+        icon: <AppWindow className="size-4 shrink-0" aria-hidden="true" />,
+      },
+      {
+        id: "app-stock",
+        label: "Stock levels",
+        keywords: ["northwind", "app-stock"],
+        icon: <AppWindow className="size-4 shrink-0" aria-hidden="true" />,
+        meta: ["not provisioned"],
+      },
+    ],
+  },
+  {
+    key: "assistants-personal",
+    label: "Assistants · personal",
+    items: [
+      {
+        id: "asst-research",
+        label: "Research helper",
+        keywords: ["personal", "asst-research"],
+        icon: <Bot className="size-4 shrink-0" aria-hidden="true" />,
+      },
+    ],
+  },
+];
+
+const meta = {
+  title: "Core/ModelPicker",
+  component: ModelPicker,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A compact pill that opens a grouped, searchable target list anchored under itself — " +
+          "sized for a composer footer. The inline sibling of `@elabs-ai/components-ai`'s " +
+          "`ModelSelector`, which is the same `Command` internals in a modal `Dialog`.\n\n" +
+          "**`Command` lives in a `Popover`, never a `DropdownMenu`.** `DropdownMenuContent` owns " +
+          "roving tabindex and its own typeahead; both fight a real `<input>` in its subtree, so " +
+          "arrow keys move the menu's focus instead of cmdk's highlight and typing never reaches " +
+          "the field. `Popover` claims no keyboard.\n\n" +
+          "Search matches `keywords` as well as the label — try typing `northwind`.",
+      },
+    },
+  },
+  args: { groups, triggerLabel: "Sales overview", value: "app-sales" },
+} satisfies Meta<typeof ModelPicker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Skeleton rows while the first load is in flight. */
+export const Loading: Story = {
+  args: { groups: [], status: "loading", triggerLabel: "Loading…", value: undefined },
+};
+
+/**
+ * A failed refresh over usable stale data: an inline strip ABOVE a list that
+ * still works. Collapsing this into the error panel would throw away a list the
+ * user could still pick from.
+ */
+export const StaleWithInlineError: Story = {
+  args: { status: "stale", onRetry: () => {} },
+};
+
+/** Nothing to show AND the load failed — the panel takes over, with a retry. */
+export const ErrorState: Story = {
+  args: {
+    groups: [],
+    status: "error",
+    triggerLabel: "Unavailable",
+    value: undefined,
+    onRetry: () => {},
+  },
+};
+
+/** Nothing to show, but nothing went wrong — a different message, deliberately. */
+export const Empty: Story = {
+  args: { groups: [], status: "empty", triggerLabel: "No targets", value: undefined },
+};
+
+export const Disabled: Story = { args: { disabled: true } };
+
+/**
+ * Programmatic open via `open`/`onOpenChange` — e.g. re-opening the picker when
+ * a previously pinned target becomes unavailable, without the consumer having
+ * to reach into internal state.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    function ControlledModelPicker() {
+      const [open, setOpen] = useState(true);
+      return <ModelPicker {...args} open={open} onOpenChange={setOpen} />;
+    }
+    return <ControlledModelPicker />;
+  },
+};