@valentinkolb/cloud 0.3.1 → 0.5.0

package/src/ui/misc/StatCell.tsx

@@ -1,31 +1,48 @@
 import type { JSX } from "solid-js";
+import { Show } from "solid-js";
+import Chart from "./Chart";
+import { type StatGridSize, useStatGridSize } from "./StatGrid";
 
 /**
- * Single cell in a stat-card row. See `skills/cloud-app/references/frontend.md`
- * § Stats and the live demos in
- * `packages/ui-lab/src/frontend/UiLabShowcase.island.tsx`.
+ * Single cell inside a {@link StatGrid}. Renders one stat: tiny
+ * uppercase label, prominent value, and an optional sub line that
+ * may carry an inline accent (pill with text, or a plain colored
+ * icon).
+ *
+ * The cell provides its own `bg-white dark:bg-zinc-900` so it works
+ * inside `StatGrid`'s hairline-bleed body (`gap-px bg-zinc-100`):
+ * each cell's background tile is what hides the bleed except at the
+ * 1px gaps, which become the inter-cell dividers. Don't strip the
+ * bg unless you're rendering the cell outside a StatGrid.
  *
- * Use inside a parent grid that frames the cells:
  * ```tsx
- * <div class="paper overflow-hidden">
- *   <div class="grid grid-cols-3 gap-px p-px bg-zinc-100 dark:bg-zinc-800">
- *     <StatCell label="Apps" value={17} sub="9 nav · 12 admin" />
- *     <StatCell
- *       label="Healthy"
- *       value="17/17"
- *       sub="all systems"
- *       accent={{ tone: "emerald", icon: "ti ti-check" }}
- *     />
- *   </div>
- * </div>
+ * <StatGrid columns={3}>
+ *   <StatCell label="Apps" value={17} sub="9 nav · 12 admin" />
+ *   <StatCell
+ *     label="Healthy"
+ *     value="17/17"
+ *     accent={{ tone: "emerald", icon: "ti ti-check", text: "ok" }}
+ *   />
+ *   <StatCell
+ *     label="P99"
+ *     value="89ms"
+ *     valueClass="text-amber-600 dark:text-amber-400"
+ *     accent={{ tone: "amber", icon: "ti ti-alert-triangle" }}
+ *   />
+ * </StatGrid>
  * ```
  *
  * Accent rules:
  * - `accent.text` set → renders an icon-and-text pill (`.tag` with bg).
- * - `accent.text` omitted → renders a plain colored icon (no bg). The `.tag`
- *   background looks squished around a single icon, so we drop it.
- * - When the accent should also colour the value (warnings, errors), pass
- *   `valueClass` like `text-amber-600 dark:text-amber-400`.
+ *   Use for short labels like "+12%" or "ok".
+ * - `accent.text` omitted → renders a plain colored icon (no bg). The
+ *   `.tag` background looks squished around a single icon, so we drop
+ *   it. Use for status hints next to a colored value.
+ * - When the accent should also colour the value itself (warnings,
+ *   errors), pass `valueClass` like `text-amber-600 dark:text-amber-400`.
+ *
+ * Pass `href` to make the whole cell a link — adds a subtle hover
+ * tint and keeps the cell visually identical when static.
  */
 export type StatCellAccent = {
   tone: "emerald" | "amber" | "red" | "blue" | "zinc";
@@ -33,16 +50,49 @@ export type StatCellAccent = {
   icon: string;
   /** Optional pill text. If set → tag with bg. If omitted → plain colored icon. */
   text?: string;
+  /**
+   * When set together with `text`, the pill renders as a link with
+   * a tone-matched hover state. Use for "drill into this status"
+   * affordances next to the value (e.g. an amber "open" pill that
+   * links to the requests page).
+   *
+   * Ignored when `text` is omitted — an icon-only accent is not a
+   * link target. Also incompatible with a cell-level `href`: the
+   * resulting `<a>` inside `<a>` is invalid HTML, so this is silently
+   * ignored when the parent cell is already a link.
+   */
+  href?: string;
 };
 
 export type StatCellProps = {
   label: string;
-  value: string | number;
-  /** Sub line under the value. Pass `" "` (non-breaking space) to keep cell heights equal when no sub exists. */
+  /**
+   * Value to display. Accepts JSX so callers can render formatted
+   * content (e.g. a number followed by an inline unit, or a mix of
+   * sizes). The default styling is `text-xl font-bold tabular-nums`.
+   */
+  value: string | number | JSX.Element;
+  /** Sub line under the value. */
   sub?: string;
   /** Override the default `text-primary` value colour for warning / error / success signals. */
   valueClass?: string;
   accent?: StatCellAccent;
+  /** When set, the whole cell becomes a link to this URL with a subtle hover state. */
+  href?: string;
+  /** Native `title` attribute on the value — useful when the value is truncated. */
+  title?: string;
+  /**
+   * Optional inline sparkline showing the value's recent history.
+   * Plain `number[]`, oldest → newest. Renders below the sub row at
+   * a fixed compact height; the line tone matches the cell's value
+   * tone (uses `currentColor` on a wrapper). Pass an empty array or
+   * omit to hide the sparkline.
+   */
+  trend?: number[];
+  /**
+   * Optional per-cell scale. Defaults to the parent StatGrid `size`.
+   */
+  size?: StatGridSize;
 };
 
 const ACCENT_PILL_CLASSES: Record<StatCellAccent["tone"], string> = {
@@ -61,28 +111,120 @@ const ACCENT_ICON_CLASSES: Record<StatCellAccent["tone"], string> = {
   zinc: "text-zinc-500 dark:text-zinc-400",
 };
 
-const StatCell = (props: StatCellProps): JSX.Element => {
+/** Hover tone for a clickable accent pill — one shade darker than the
+ *  resting state. Same tone family, no surprise jump to a different
+ *  hue on hover. */
+const ACCENT_PILL_HOVER_CLASSES: Record<StatCellAccent["tone"], string> = {
+  emerald: "hover:bg-emerald-200 dark:hover:bg-emerald-900/60",
+  amber: "hover:bg-amber-200 dark:hover:bg-amber-900/60",
+  red: "hover:bg-red-200 dark:hover:bg-red-900/60",
+  blue: "hover:bg-blue-200 dark:hover:bg-blue-900/60",
+  zinc: "hover:bg-zinc-200 dark:hover:bg-zinc-700",
+};
+
+/** Cell body — same markup whether the wrapper is a `<div>` or `<a>`.
+ *  `cellIsLink` is set by the wrapper to suppress nested-link rendering
+ *  (an `<a>` inside an `<a>` is invalid HTML). When true, an
+ *  `accent.href` falls back to a static span pill. */
+const Body = (props: StatCellProps & { cellIsLink: boolean }): JSX.Element => {
   const valueClass = props.valueClass ?? "text-primary";
-  const sub = props.sub ?? " ";
+  const gridSize = useStatGridSize();
+  const size = () => props.size ?? gridSize;
+  const valueSizeClass = () => (size() === "sm" ? "text-base" : "text-xl");
+  const labelSizeClass = () => (size() === "sm" ? "text-[9px]" : "text-[10px]");
+  const subSizeClass = () => (size() === "sm" ? "text-[9px]" : "text-[10px]");
   return (
-    <div class="bg-white dark:bg-zinc-900 px-4 py-4 flex flex-col gap-0.5">
-      <span class="text-[10px] uppercase tracking-wider text-dimmed">{props.label}</span>
-      <span class={`text-xl font-bold tabular-nums ${valueClass}`}>{props.value}</span>
-      {props.accent ? (
-        <div class="flex items-center gap-1.5">
-          <span class="text-[10px] text-dimmed">{sub}</span>
-          {props.accent.text ? (
-            <span class={`tag ${ACCENT_PILL_CLASSES[props.accent.tone]}`}>
-              <i class={`${props.accent.icon} text-[9px]`} />
-              {props.accent.text}
-            </span>
-          ) : (
-            <i class={`${props.accent.icon} ${ACCENT_ICON_CLASSES[props.accent.tone]} text-[11px]`} />
-          )}
+    <>
+      <span class={`${labelSizeClass()} uppercase tracking-wider text-dimmed truncate`}>{props.label}</span>
+      <span class={`${valueSizeClass()} font-bold tabular-nums leading-tight truncate ${valueClass}`} title={props.title}>
+        {props.value}
+      </span>
+      {/* Optional trend sparkline. Sits inline between the value and
+          the sub row so the eye lands on it right after parsing the
+          headline number.
+
+          Sizing: inline `style` for the height (Tailwind's h-8 class
+          didn't survive every hot-reload / cache combo in the wild;
+          inline style is immune). Full-bleed horizontally via -mx-4
+          to cancel the cell's px-4 padding so the line spans the
+          card edge-to-edge — the inset visual reads as "tucked-in
+          line in the middle", which the user reported as "doesn't
+          fit" against the surrounding card.
+
+          `showLast` + `showMinMax` add dots at the most-recent point
+          plus the min/max points so a flat-with-spikes series still
+          has visible anchor points (otherwise sparse data renders
+          as nearly-invisible horizontal lines). */}
+      <Show when={props.trend && props.trend.length > 1}>
+        <Chart kind="sparkline" class="-mx-4 self-stretch block" style={{ height: "32px" }} data={props.trend ?? []} showLast showMinMax />
+      </Show>
+      {/* Sub row: rendered only when there's actual content. Keeping
+          the row out entirely when both sub and accent are absent
+          lets the grid's row-height shrink naturally — callers that
+          want forced equal heights should pass `sub=" "`. */}
+      {props.sub || props.accent ? (
+        <div class="flex items-center gap-1.5 min-w-0">
+          {props.sub ? <span class={`${subSizeClass()} text-dimmed truncate`}>{props.sub}</span> : null}
+          {props.accent ? (
+            props.accent.text ? (
+              // Pill variant. `accent.href` upgrades the span to an
+              // anchor with a tone-matched hover background, but only
+              // when the surrounding cell isn't already a link — the
+              // browser refuses to nest `<a>` and silently flattens
+              // the inner one, which would look broken on hover.
+              props.accent.href && !props.cellIsLink ? (
+                <a
+                  href={props.accent.href}
+                  class={`tag shrink-0 transition-colors ${ACCENT_PILL_CLASSES[props.accent.tone]} ${ACCENT_PILL_HOVER_CLASSES[props.accent.tone]}`}
+                >
+                  <i class={`${props.accent.icon} text-[9px]`} />
+                  {props.accent.text}
+                </a>
+              ) : (
+                <span class={`tag shrink-0 ${ACCENT_PILL_CLASSES[props.accent.tone]}`}>
+                  <i class={`${props.accent.icon} text-[9px]`} />
+                  {props.accent.text}
+                </span>
+              )
+            ) : (
+              <i class={`${props.accent.icon} ${ACCENT_ICON_CLASSES[props.accent.tone]} text-[11px] shrink-0`} />
+            )
+          ) : null}
         </div>
-      ) : (
-        <span class="text-[10px] text-dimmed">{sub}</span>
-      )}
+      ) : null}
+    </>
+  );
+};
+
+const StatCell = (props: StatCellProps): JSX.Element => {
+  // Static layout classes — shared between link and non-link wrapper.
+  // `bg-white` (and dark equivalent) is what tiles over the parent
+  // grid's `bg-zinc-100` bleed; without it the cell would look
+  // transparent on top of the divider colour.
+  const gridSize = useStatGridSize();
+  const size = () => props.size ?? gridSize;
+  const baseClass = () => `bg-white dark:bg-zinc-900 flex flex-col gap-0.5 min-w-0 ${size() === "sm" ? "px-3 py-2.5" : "px-4 py-4"}`;
+  if (props.href) {
+    // Link variant: adds a subtle top-right `external-link` icon as
+    // an affordance — sits in dimmed zinc by default, shifts to the
+    // link-blue colour on cell hover. `group` lets the icon respond
+    // to the whole cell's hover state, not just its own. `pr-7`
+    // reserves space so a long truncate'd label can't slide under
+    // the icon (the icon is absolute, so it doesn't take a column
+    // in the flex layout).
+    return (
+      <a href={props.href} class={`${baseClass()} group relative pr-7 hover:bg-zinc-50 dark:hover:bg-zinc-800/40 transition-colors`}>
+        <i
+          class="ti ti-external-link absolute top-2 right-2 text-[11px] text-dimmed group-hover:text-blue-600 dark:group-hover:text-blue-400 transition-colors"
+          aria-hidden="true"
+        />
+        <Body {...props} cellIsLink />
+      </a>
+    );
+  }
+  return (
+    <div class={baseClass()}>
+      <Body {...props} cellIsLink={false} />
     </div>
   );
 };

package/src/ui/misc/StatGrid.tsx

@@ -0,0 +1,149 @@
+import type { JSX } from "solid-js";
+import { Show, createContext, useContext } from "solid-js";
+
+/**
+ * StatGrid — paper-framed container for a row of {@link StatCell}s.
+ *
+ * Replaces the inline `paper + grid + gap-px + p-px + bg-zinc` pattern
+ * that previously lived in every consumer. The two visual bugs that
+ * pattern produced are fixed here:
+ *
+ * 1. **No more doubled outer border.** The old pattern used
+ *    `p-px bg-zinc-100` to draw a 1px ring around the cells, which
+ *    overlapped the `paper` border (also 1px zinc-100) and made the
+ *    outer edge look thicker than the inner dividers. We drop the
+ *    `p-px` entirely — the cells touch the paper's inner edge
+ *    directly, and `paper`'s own border is the only outer line.
+ * 2. **No more squashed inner corners.** Without the inner ring, the
+ *    cells are simply clipped by `paper`'s `rounded-lg overflow-hidden`,
+ *    so the cell corners match the outer radius cleanly.
+ *
+ * The hairline dividers between cells come from the standard
+ * `gap-px bg-zinc-100` bleed trick: the body's background shows
+ * through the 1px gaps between cell `bg-white` tiles. This is why
+ * `StatCell` ships its own `bg-white` — don't strip it.
+ *
+ * ## API
+ *
+ * Composition-based, mirroring `Widget` / `WidgetStat` and most other
+ * platform containers:
+ *
+ * ```tsx
+ * <StatGrid
+ *   columns={3}
+ *   title="View totals"
+ *   action={{ label: "Open full view", href: "/app/grids/abc" }}
+ * >
+ *   <StatCell label="Apps" value={17} />
+ *   <StatCell label="Routes" value={106} />
+ *   <StatCell label="Search" value={5} sub="providers" />
+ * </StatGrid>
+ * ```
+ *
+ * ## Columns
+ *
+ * `columns` (1-6) picks a responsive grid track count from a static
+ * map below — Tailwind's JIT only compiles class names it can find
+ * literally in source, so interpolated `grid-cols-${n}` strings get
+ * stripped silently. Pass any number outside 1-6 and we fall back to
+ * the same `grid-cols-2 sm:grid-cols-3 md:grid-cols-6` ladder the
+ * grids app uses for its view-stats rows.
+ *
+ * When `columns` is omitted, callers get a sensible default for a
+ * mixed-count row. Pass it explicitly when you know the cell count
+ * statically — that's almost always.
+ */
+type StatGridAction = {
+  label: string;
+  href: string;
+};
+
+export type StatGridSize = "md" | "sm";
+
+const StatGridSizeContext = createContext<StatGridSize>("md");
+
+export const useStatGridSize = () => useContext(StatGridSizeContext);
+
+type StatGridProps = {
+  children: JSX.Element;
+  /**
+   * Optional title shown in a small header bar above the cells.
+   * When set, the header gets a `border-b` divider — same colour as
+   * the cell hairlines, so it visually continues the grid.
+   */
+  title?: string;
+  /**
+   * Optional right-aligned link in the header. Shows up only when
+   * `title` is also set (a lone link with no title would float
+   * orphaned).
+   */
+  action?: StatGridAction;
+  /**
+   * Number of columns at the widest breakpoint. Maps to a static
+   * responsive class set (see {@link GRID_COLS_CLASS}). Values
+   * outside 1-6 fall back to the 6-column ladder.
+   */
+  columns?: number;
+  /**
+   * Compact cells for secondary stats inside dense app surfaces. The
+   * default keeps the established admin/dashboard scale.
+   */
+  size?: StatGridSize;
+  /**
+   * Extra classes on the outer paper element — primarily for sizing
+   * (`h-full`, `flex-1`) when the grid needs to fill a parent
+   * container rather than collapse to its natural content height.
+   */
+  class?: string;
+};
+
+/**
+ * Static responsive column classes. Keys 1-6 map to the responsive
+ * ladders used across the platform (matches the grids `StatsRow` /
+ * `ViewStatsRow` originals so the visual rhythm is unchanged).
+ *
+ * The values are literal class strings so Tailwind's JIT picks them
+ * up — never inline an interpolation like `md:grid-cols-${n}`.
+ */
+const GRID_COLS_CLASS: Record<number, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-1 sm:grid-cols-3",
+  4: "grid-cols-2 md:grid-cols-4",
+  5: "grid-cols-2 sm:grid-cols-3 md:grid-cols-5",
+  6: "grid-cols-2 sm:grid-cols-3 md:grid-cols-6",
+};
+
+const DEFAULT_GRID_COLS = "grid-cols-2 sm:grid-cols-3 md:grid-cols-6";
+
+const StatGrid = (props: StatGridProps): JSX.Element => {
+  const gridCols = () => (props.columns ? (GRID_COLS_CLASS[props.columns] ?? DEFAULT_GRID_COLS) : DEFAULT_GRID_COLS);
+
+  return (
+    <div class={`paper overflow-hidden flex flex-col ${props.class ?? ""}`}>
+      <Show when={props.title}>
+        <header class="px-3 py-2 flex items-center justify-between gap-2 border-b border-zinc-100 dark:border-zinc-800/60">
+          <span class="text-xs font-semibold text-primary truncate">{props.title}</span>
+          <Show when={props.action}>
+            {(action) => (
+              <a href={action().href} class="text-[11px] text-dimmed hover:text-primary inline-flex items-center gap-1 shrink-0">
+                <span>{action().label}</span>
+                <i class="ti ti-arrow-up-right text-[10px]" />
+              </a>
+            )}
+          </Show>
+        </header>
+      </Show>
+      {/* Cell grid: `gap-px` carves 1px channels between cells, the
+          body `bg-zinc-100` bleeds through those channels, and each
+          cell's own `bg-white` covers the rest. No `p-px` — see the
+          docblock for why. `flex-1` lets the grid expand to fill the
+          paper when the caller passes a sizing class like `h-full`. */}
+      <StatGridSizeContext.Provider value={props.size ?? "md"}>
+        <div class={`grid ${gridCols()} gap-px bg-zinc-100 dark:bg-zinc-800 flex-1`}>{props.children}</div>
+      </StatGridSizeContext.Provider>
+    </div>
+  );
+};
+
+export default StatGrid;

package/src/ui/misc/StructuredDataPreview.tsx

@@ -0,0 +1,107 @@
+import { createMemo, createSignal, For, Show } from "solid-js";
+import CopyButton from "./CopyButton";
+
+export type StructuredDataPreviewMode = "formatted" | "raw";
+
+export type StructuredDataPreviewProps = {
+  title?: string;
+  data: unknown;
+  defaultMode?: StructuredDataPreviewMode;
+  copy?: boolean;
+  empty?: string;
+  maxRows?: number;
+  class?: string;
+};
+
+type Row = {
+  key: string;
+  value: unknown;
+};
+
+const toRows = (data: unknown): Row[] => {
+  if (Array.isArray(data)) return data.map((value, index) => ({ key: String(index), value }));
+  if (data && typeof data === "object") return Object.entries(data as Record<string, unknown>).map(([key, value]) => ({ key, value }));
+  if (data === null || data === undefined) return [];
+  return [{ key: "value", value: data }];
+};
+
+const formatInlineValue = (value: unknown): string => {
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+};
+
+const formatJson = (data: unknown): string => JSON.stringify(data ?? null, null, 2);
+
+export default function StructuredDataPreview(props: StructuredDataPreviewProps) {
+  const [mode, setMode] = createSignal<StructuredDataPreviewMode>(props.defaultMode ?? "formatted");
+  const rows = createMemo(() => toRows(props.data));
+  const visibleRows = createMemo(() => rows().slice(0, props.maxRows ?? rows().length));
+  const hiddenCount = createMemo(() => Math.max(0, rows().length - visibleRows().length));
+  const raw = createMemo(() => formatJson(props.data));
+  const hasData = createMemo(() => rows().length > 0);
+  const showRaw = createMemo(() => mode() === "raw");
+
+  return (
+    <div class={["flex flex-col gap-2", props.class].filter(Boolean).join(" ")}>
+      <Show when={props.title}>
+        {(title) => <h3 class="text-xs font-semibold uppercase tracking-wider text-secondary">{title()}</h3>}
+      </Show>
+
+      <Show
+        when={!showRaw()}
+        fallback={
+          <div class="relative rounded-lg bg-zinc-100 px-3 py-2 text-secondary dark:bg-zinc-900/80">
+            <pre class="max-h-72 overflow-auto whitespace-pre-wrap break-all pr-16 font-mono text-[11px] leading-relaxed">{raw()}</pre>
+            <Show when={props.copy !== false}>
+              <div class="absolute right-2 top-2">
+                <CopyButton text={raw()} label="Copy" class="text-[11px] text-dimmed transition-colors hover:text-secondary" />
+              </div>
+            </Show>
+          </div>
+        }
+      >
+        <div class="rounded-lg bg-zinc-100 px-3 py-2 dark:bg-zinc-900/80">
+          <Show
+            when={hasData()}
+            fallback={<p class="text-xs text-dimmed">{props.empty ?? "No data."}</p>}
+          >
+            <div class="grid grid-cols-[minmax(7rem,auto)_1fr] gap-x-4 gap-y-1.5 text-xs">
+              <For each={visibleRows()}>
+                {(row) => {
+                  const complex = typeof row.value === "object" && row.value !== null;
+                  return (
+                    <>
+                      <span class="min-w-0 truncate font-medium text-dimmed" title={row.key}>
+                        {row.key}
+                      </span>
+                      <span class={`min-w-0 break-all text-secondary ${complex ? "font-mono text-[11px]" : ""}`}>
+                        {formatInlineValue(row.value)}
+                      </span>
+                    </>
+                  );
+                }}
+              </For>
+            </div>
+            <Show when={hiddenCount() > 0}>
+              <p class="mt-2 text-[11px] text-dimmed">{hiddenCount()} more row{hiddenCount() === 1 ? "" : "s"} hidden.</p>
+            </Show>
+          </Show>
+        </div>
+      </Show>
+
+      <div class="flex items-center gap-2">
+        <Show when={hasData()}>
+          <button
+            type="button"
+            class="text-[11px] text-dimmed transition-colors hover:text-secondary"
+            onClick={() => setMode(showRaw() ? "formatted" : "raw")}
+          >
+            {showRaw() ? "View formatted" : "View raw"}
+          </button>
+        </Show>
+      </div>
+    </div>
+  );
+}