@cosmicdrift/kumiko-bundled-features 0.224.2 → 0.225.0

package/src/cap-overview/web/__tests__/cap-cards-panel.test.tsx

@@ -0,0 +1,198 @@
+// @runtime test
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import {
+  createStaticLocaleResolver,
+  type ExtensionSectionProps,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CapOverviewQueries } from "../../constants";
+import type { CapUsageTone, CapUsageWithMeta } from "../../types";
+import { CapCardsPanel } from "../cap-cards-panel";
+
+type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
+
+type QueryState = {
+  readonly data: CapsUsageResponse | null;
+  readonly loading: boolean;
+  readonly error: DispatcherError | null;
+};
+
+let queryState: QueryState = { data: { rows: [] }, loading: false, error: null };
+
+const useQuerySpy = mock((_type: string, _params: unknown) => ({
+  ...queryState,
+  refetch: mock(async () => {}),
+}));
+
+const actualRenderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actualRenderer,
+  useQuery: useQuerySpy,
+}));
+
+// The real StatusBadge bakes `tone` into a computed Tailwind class string and
+// exposes it nowhere in the DOM — asserting TONE_TO_STATUS through it would
+// mean matching class substrings. Surface the prop as data-tone instead.
+const actualRendererWeb = await import("@cosmicdrift/kumiko-renderer-web");
+mock.module("@cosmicdrift/kumiko-renderer-web", () => ({
+  ...actualRendererWeb,
+  StatusBadge: ({
+    tone,
+    children,
+  }: {
+    readonly tone: string;
+    readonly children: ReactNode;
+  }): ReactNode => <span data-tone={tone}>{children}</span>,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+function renderPanel(filterParams: ExtensionSectionProps["filterParams"]): void {
+  render(
+    <Wrapper>
+      <CapCardsPanel
+        entityName="cap-overview-dashboard"
+        entityId={null}
+        filterParams={filterParams}
+      />
+    </Wrapper>,
+  );
+}
+
+function capRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta {
+  return {
+    id: "cap-1",
+    label: "cap.label",
+    tone: "default",
+    percent: 0,
+    used: 0,
+    limit: 100,
+    fraction: 0,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  queryState = { data: { rows: [] }, loading: false, error: null };
+  useQuerySpy.mockClear();
+});
+
+describe("CapCardsPanel", () => {
+  test("renders one card per row, with the row's label and used/limit value", () => {
+    queryState = {
+      data: {
+        rows: [
+          capRow({ id: "c1", label: "Storage", used: 3, limit: 10 }),
+          capRow({ id: "c2", label: "Seats", used: 7, limit: 20 }),
+        ],
+      },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getAllByTestId("cap-card")).toHaveLength(2);
+    expect(screen.getByText("Storage")).toBeTruthy();
+    expect(screen.getByText("Seats")).toBeTruthy();
+    expect(screen.getByText("3 / 10")).toBeTruthy();
+    expect(screen.getByText("7 / 20")).toBeTruthy();
+  });
+
+  test("maps the default tone to the muted StatusBadge tone", () => {
+    queryState = {
+      data: { rows: [capRow({ tone: "default", percent: 12 })] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("12%").getAttribute("data-tone")).toBe("muted");
+  });
+
+  test("maps the warn tone to the warn StatusBadge tone", () => {
+    queryState = {
+      data: { rows: [capRow({ tone: "warn", percent: 80 })] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("80%").getAttribute("data-tone")).toBe("warn");
+  });
+
+  test("maps the danger tone to the critical StatusBadge tone", () => {
+    const tone: CapUsageTone = "danger";
+    queryState = { data: { rows: [capRow({ tone, percent: 99 })] }, loading: false, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("99%").getAttribute("data-tone")).toBe("critical");
+  });
+
+  test("empty rows without loading show the empty state and no cards", () => {
+    queryState = { data: { rows: [] }, loading: false, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-cards-panel-empty")).toBeTruthy();
+    expect(screen.queryAllByTestId("cap-card")).toHaveLength(0);
+  });
+
+  test("a query error shows the error banner with the message and no cards", () => {
+    queryState = {
+      data: null,
+      loading: false,
+      error: {
+        code: "internal",
+        httpStatus: 500,
+        i18nKey: "kumiko.error.internal",
+        message: "caps usage failed",
+      },
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-cards-panel-error").textContent).toContain("caps usage failed");
+    expect(screen.queryAllByTestId("cap-card")).toHaveLength(0);
+  });
+
+  test("a string tenantId in filterParams is passed through to useQuery", () => {
+    renderPanel({ tenantId: "t-42" });
+
+    expect(useQuerySpy).toHaveBeenCalledWith(CapOverviewQueries.capsUsage, { tenantId: "t-42" });
+  });
+
+  test("missing or non-string tenantId in filterParams omits the tenantId key", () => {
+    renderPanel(undefined);
+    const [, undefinedFilterArgs] = useQuerySpy.mock.calls[0] as [string, Record<string, unknown>];
+    expect("tenantId" in undefinedFilterArgs).toBe(false);
+
+    useQuerySpy.mockClear();
+    renderPanel({ tenantId: 123 });
+    const [, numericTenantIdArgs] = useQuerySpy.mock.calls[0] as [string, Record<string, unknown>];
+    expect("tenantId" in numericTenantIdArgs).toBe(false);
+  });
+
+  test("loading with empty rows shows the loading text instead of the empty state", () => {
+    queryState = { data: null, loading: true, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("cap-overview.cards.loading")).toBeTruthy();
+    expect(screen.queryByTestId("cap-cards-panel-empty")).toBeNull();
+  });
+});

package/src/cap-overview/web/__tests__/cap-usage-bar.test.tsx

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../../types";
+import { CapUsageBar } from "../cap-usage-bar";
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+function fillClass(): string | undefined {
+  return screen.getByTestId("cap-usage-bar").firstElementChild?.className;
+}
+
+describe("CapUsageBar", () => {
+  test("renders the danger fill class when usage is at or over the limit", () => {
+    const usage: CapUsage = { used: 120, limit: 100, fraction: 1.2 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-status-critical");
+    expect(fillClass()).not.toContain("bg-primary");
+  });
+
+  test("renders the default fill class when usage is well under the limit", () => {
+    const usage: CapUsage = { used: 4, limit: 100, fraction: 0.04 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-primary");
+    expect(fillClass()).not.toContain("bg-status-critical");
+  });
+
+  test("renders the warn fill class when usage is in the warn zone", () => {
+    const usage: CapUsage = { used: 85, limit: 100, fraction: 0.85 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-status-warn");
+    expect(fillClass()).not.toContain("bg-primary");
+    expect(fillClass()).not.toContain("bg-status-critical");
+  });
+});

package/src/cap-overview/web/cap-cards-panel.tsx

@@ -0,0 +1,99 @@
+// @runtime client
+import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  EmptyState,
+  StatCard,
+  StatusBadge,
+  type StatusTone,
+} from "@cosmicdrift/kumiko-renderer-web";
+import { Database, FileText, Gauge, Hash, Mail, Users } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { CapOverviewQueries } from "../constants";
+import type { CapIconKey, CapUsageTone, CapUsageWithMeta } from "../types";
+import { CapUsageBar } from "./cap-usage-bar";
+
+type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
+
+// caps:usage's wire tone stays "default"/"warn"/"danger" (matches the
+// server-side thresholds literally); mapped here to the renderer's actual
+// StatusTone vocabulary instead of inventing new CSS ("danger" has no
+// StatusBadge tone equivalent — "critical" is the closer semantic fit).
+const TONE_TO_STATUS: Record<CapUsageTone, StatusTone> = {
+  default: "muted",
+  warn: "warn",
+  danger: "critical",
+};
+
+// Matches CapIconKey (types.ts) 1:1 — extend both together.
+const CAP_ICONS: Record<CapIconKey, ComponentType<{ className?: string }>> = {
+  file: FileText,
+  hash: Hash,
+  database: Database,
+  users: Users,
+  mail: Mail,
+  gauge: Gauge,
+};
+
+export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  const tenantId =
+    typeof filterParams?.["tenantId"] === "string" ? filterParams["tenantId"] : undefined;
+  const query = useQuery<CapsUsageResponse | null>(CapOverviewQueries.capsUsage, {
+    ...(tenantId !== undefined && { tenantId }),
+  });
+
+  if (query.error !== null) {
+    return (
+      <Banner variant="error" testId="cap-cards-panel-error">
+        {query.error.message}
+      </Banner>
+    );
+  }
+
+  const rows = query.data?.rows ?? [];
+
+  if (!query.loading && rows.length === 0) {
+    return <EmptyState title={t("cap-overview.cards.empty")} testId="cap-cards-panel-empty" />;
+  }
+
+  return (
+    <div
+      // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
+      // styles.css's Tailwind v4 @source scan only covers renderer-web/src,
+      // renderer/src and samples/**/src (see its comment) — bundled-features
+      // isn't scanned, so a class unique to this file has no generated rule
+      // and silently no-ops (the grid fell back to one implicit column,
+      // stacking every card full-width). Reusing the exact classes
+      // dashboard-body.tsx's own panel grid already uses guarantees the
+      // rule exists, since that file IS in the scanned surface.
+      className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4"
+      data-testid="cap-cards-panel"
+    >
+      {query.loading && rows.length === 0 && (
+        <div className="text-sm text-muted-foreground">{t("cap-overview.cards.loading")}</div>
+      )}
+      {rows.map((cap) => {
+        const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
+        return (
+          <StatCard
+            key={cap.id}
+            icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
+            label={t(cap.label)}
+            value={`${cap.used} / ${cap.limit}`}
+            {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
+            testId="cap-card"
+          >
+            <div className="flex flex-col gap-2">
+              <div className="flex items-center justify-between gap-2">
+                <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
+              </div>
+              <CapUsageBar usage={cap} showLabel={false} />
+            </div>
+          </StatCard>
+        );
+      })}
+    </div>
+  );
+}

package/src/cap-overview/web/cap-usage-bar.tsx

@@ -0,0 +1,38 @@
+// @runtime client
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types";
+import { computeTone } from "../usage-math";
+
+export function CapUsageBar({
+  usage,
+  showLabel = true,
+}: {
+  readonly usage: CapUsage;
+  // The cap-cards-panel StatCard already shows used/limit as its headline
+  // value — the bar's own label would just repeat it there.
+  readonly showLabel?: boolean;
+}): ReactNode {
+  const { Progress, Text, Banner } = usePrimitives();
+  const t = useTranslation();
+  return (
+    <div className="flex flex-col gap-1">
+      {Progress ? (
+        <Progress
+          value={usage.fraction}
+          tone={computeTone(usage.fraction)}
+          testId="cap-usage-bar"
+        />
+      ) : (
+        // Progress is typed optional only so partial CorePrimitives test
+        // doubles keep compiling — production always registers it via
+        // defaultPrimitives. If it's ever missing, say so instead of
+        // silently dropping the bar (it's the requested content, not decoration).
+        <Banner variant="error" testId="cap-usage-bar-missing-primitive">
+          {t("cap-overview.errors.progressPrimitiveMissing")}
+        </Banner>
+      )}
+      {showLabel && <Text variant="small">{`${usage.used} / ${usage.limit}`}</Text>}
+    </div>
+  );
+}

package/src/cap-overview/web/cap-usage-cell.tsx

@@ -0,0 +1,20 @@
+// @runtime client
+import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types";
+import { CapUsageBar } from "./cap-usage-bar";
+
+function isCapUsage(value: unknown): value is CapUsage {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { used?: unknown }).used === "number" &&
+    typeof (value as { limit?: unknown }).limit === "number" &&
+    typeof (value as { fraction?: unknown }).fraction === "number"
+  );
+}
+
+export function CapUsageCell({ value }: ColumnRendererProps): ReactNode {
+  if (!isCapUsage(value)) return null;
+  return <CapUsageBar usage={value} />;
+}

package/src/cap-overview/web/client-plugin.tsx

@@ -0,0 +1,27 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_OVERVIEW_FEATURE,
+  CAP_USAGE_CELL_COMPONENT,
+} from "../constants";
+import { CapCardsPanel } from "./cap-cards-panel";
+import { CapUsageCell } from "./cap-usage-cell";
+
+export type CapOverviewClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function capOverviewClient(options?: CapOverviewClientOptions): ClientFeatureDefinition {
+  return {
+    name: CAP_OVERVIEW_FEATURE,
+    columnRenderers: {
+      [CAP_USAGE_CELL_COMPONENT]: CapUsageCell,
+    },
+    extensionSectionComponents: {
+      [CAP_CARDS_PANEL_COMPONENT]: CapCardsPanel,
+    },
+    ...(options?.translations !== undefined && { translations: options.translations }),
+  };
+}

package/src/cap-overview/web/index.ts

@@ -0,0 +1,10 @@
+// @runtime client
+// Public exports for the browser side of the cap-overview feature.
+// Consumed via `@cosmicdrift/kumiko-bundled-features/cap-overview/web` —
+// the server side (createCapOverviewFeature) lives under
+// `@cosmicdrift/kumiko-bundled-features/cap-overview` and has no React deps.
+
+export { CapCardsPanel } from "./cap-cards-panel";
+export { CapUsageBar } from "./cap-usage-bar";
+export { CapUsageCell } from "./cap-usage-cell";
+export { type CapOverviewClientOptions, capOverviewClient } from "./client-plugin";