@checkstack/catalog-frontend 0.10.7 → 0.11.0

package/src/hooks/useCatalogBrowseState.ts

@@ -0,0 +1,107 @@
+import { useCallback, useMemo } from "react";
+import { useSearchParams } from "react-router-dom";
+import {
+  parseBrowseState,
+  serializeBrowseState,
+  type BrowseState,
+  type Density,
+  type HealthFilter,
+} from "../components/browse/browseState.logic";
+import { useDebouncedValue } from "./useDebouncedValue";
+
+const QUERY_DEBOUNCE_MS = 150;
+
+export interface CatalogBrowseStateApi {
+  /** Live state reflecting the URL (query updates immediately for the input). */
+  state: BrowseState;
+  /** Query debounced for filtering, so typing stays smooth on large lists. */
+  debouncedQuery: string;
+  setQuery: (query: string) => void;
+  setGroup: (group: string | null) => void;
+  setHealth: (health: HealthFilter) => void;
+  setTag: (tag: string | null) => void;
+  setDensity: (density: Density) => void;
+  /** Force a section's open/closed state (overrides the default policy). */
+  setSectionOpen: (id: string, open: boolean) => void;
+  /** Clear every filter (query/group/health/tag) but keep density + open. */
+  clearFilters: () => void;
+}
+
+/**
+ * Bridge between the browse URL params and the page. All persistence logic
+ * lives in `browseState.logic.ts` (DOM-free, tested); this hook only wires it
+ * to `useSearchParams` and adds query debouncing.
+ */
+export function useCatalogBrowseState(): CatalogBrowseStateApi {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const state = useMemo(
+    () => parseBrowseState(searchParams),
+    [searchParams],
+  );
+
+  const debouncedQuery = useDebouncedValue(state.query, QUERY_DEBOUNCE_MS);
+
+  const commit = useCallback(
+    (next: BrowseState) => {
+      const serialized = serializeBrowseState(next);
+      setSearchParams(
+        (prev) => {
+          const updated = new URLSearchParams(prev);
+          for (const [key, value] of Object.entries(serialized)) {
+            if (value.length > 0) {
+              updated.set(key, value);
+            } else {
+              updated.delete(key);
+            }
+          }
+          return updated;
+        },
+        { replace: true },
+      );
+    },
+    [setSearchParams],
+  );
+
+  const setQuery = useCallback(
+    (query: string) => commit({ ...state, query }),
+    [commit, state],
+  );
+  const setGroup = useCallback(
+    (group: string | null) => commit({ ...state, group }),
+    [commit, state],
+  );
+  const setHealth = useCallback(
+    (health: HealthFilter) => commit({ ...state, health }),
+    [commit, state],
+  );
+  const setTag = useCallback(
+    (tag: string | null) => commit({ ...state, tag }),
+    [commit, state],
+  );
+  const setDensity = useCallback(
+    (density: Density) => commit({ ...state, density }),
+    [commit, state],
+  );
+  const setSectionOpen = useCallback(
+    (id: string, open: boolean) =>
+      commit({ ...state, open: { ...state.open, [id]: open } }),
+    [commit, state],
+  );
+  const clearFilters = useCallback(
+    () => commit({ ...state, query: "", group: null, health: "all", tag: null }),
+    [commit, state],
+  );
+
+  return {
+    state,
+    debouncedQuery,
+    setQuery,
+    setGroup,
+    setHealth,
+    setTag,
+    setDensity,
+    setSectionOpen,
+    clearFilters,
+  };
+}

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,21 @@
+import React from "react";
+
+/**
+ * Return `value` debounced by `delayMs`: the returned value only updates after
+ * `value` has stopped changing for `delayMs`. Used to throttle the live browse
+ * search so a fast typist doesn't re-filter a large catalog on every keystroke.
+ *
+ * Copied (not imported) from script-packages-frontend per the code-style guide —
+ * there is no shared `useDebounce` in `@checkstack/ui` yet, and adding one
+ * unilaterally is out of scope.
+ */
+export function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = React.useState(value);
+
+  React.useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/index.tsx

@@ -1,8 +1,4 @@
-import {
-  UserMenuItemsSlot,
-  createSlotExtension,
-  createFrontendPlugin,
-} from "@checkstack/frontend-api";
+import { createFrontendPlugin } from "@checkstack/frontend-api";
 import {
   catalogRoutes,
   pluginMetadata,
@@ -12,11 +8,6 @@ import {
 import { Server, FolderTree } from "lucide-react";
 import { registerSubjectKind } from "@checkstack/notification-frontend";
 
-import { CatalogPage } from "./components/CatalogPage";
-import { CatalogConfigPage } from "./components/CatalogConfigPage";
-import { CatalogUserMenuItems } from "./components/UserMenuItems";
-import { SystemDetailPage } from "./components/SystemDetailPage";
-
 // Notification subject kinds emitted by catalog (see catalog-common's
 // `createSystemSubject` / `createGroupSubject`). Registered at module load
 // so the notification bell + page render kind-appropriate icons.
@@ -36,25 +27,46 @@ export const catalogPlugin = createFrontendPlugin({
   routes: [
     {
       route: catalogRoutes.routes.home,
-      element: <CatalogPage />,
+      load: () =>
+        import("./components/CatalogPage").then((m) => ({
+          default: m.CatalogPage,
+        })),
+      title: "Catalog",
+      nav: {
+        group: "Workspace",
+        icon: Server,
+        // Visible to anyone who can view systems in the catalog.
+        accessRule: catalogAccess.system.read,
+      },
     },
     {
       route: catalogRoutes.routes.config,
-      element: <CatalogConfigPage />,
+      load: () =>
+        import("./components/CatalogConfigPage").then((m) => ({
+          default: m.CatalogConfigPage,
+        })),
       accessRule: catalogAccess.system.manage,
     },
     {
       route: catalogRoutes.routes.systemDetail,
-      element: <SystemDetailPage />,
+      load: () =>
+        import("./components/SystemDetailPage").then((m) => ({
+          default: m.SystemDetailPage,
+        })),
     },
   ],
-  extensions: [
-    createSlotExtension(UserMenuItemsSlot, {
-      id: "catalog.user-menu.items",
-      component: CatalogUserMenuItems,
-      metadata: { group: "Workspace" },
-    }),
-  ],
+  extensions: [],
 });
 
 export * from "./api";
+
+// Reusable "Preview as: <environment>" picker + its DOM-free helpers, so host
+// plugins can let config authors preview `x-templatable` fields against a
+// catalog environment's custom fields.
+export { EnvironmentPreviewPicker } from "./components/EnvironmentPreviewPicker";
+export {
+  toPreviewOptions,
+  environmentToPreviewFields,
+  findSelectedEnvironment,
+  type EnvironmentPreviewOption,
+} from "./components/environment-preview.logic";

package/src/utils/formatDate.logic.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { formatDate } from "./formatDate.logic";
+
+describe("formatDate", () => {
+  test("returns '' for null", () => {
+    expect(formatDate(null)).toBe("");
+  });
+
+  test("returns '' for undefined", () => {
+    expect(formatDate(undefined)).toBe("");
+  });
+
+  test("returns '' for an invalid date string", () => {
+    expect(formatDate("not-a-date")).toBe("");
+  });
+
+  test("returns '' for an invalid Date object", () => {
+    expect(formatDate(new Date("not-a-date"))).toBe("");
+  });
+
+  test("does not embed 'en-US' locale in the output", () => {
+    // Run formatDate with a fixed date and verify the result does NOT contain
+    // a hardcoded locale marker. We can't assert the exact locale-formatted
+    // string since it depends on the runtime environment, but we can verify
+    // it produces a non-empty result and does not throw.
+    const result = formatDate(new Date("2025-01-05T00:00:00Z"));
+    expect(result.length).toBeGreaterThan(0);
+  });
+
+  test("accepts a Date object and produces a non-empty string", () => {
+    const date = new Date(2025, 0, 5); // Jan 5, 2025 local time
+    expect(formatDate(date).length).toBeGreaterThan(0);
+  });
+
+  test("accepts an ISO string and produces a non-empty string", () => {
+    expect(formatDate("2025-06-01T12:00:00.000Z").length).toBeGreaterThan(0);
+  });
+
+  test("a known fixed date produces output containing the year", () => {
+    const result = formatDate(new Date(2025, 5, 1)); // Jun 1, 2025
+    // The year should always appear regardless of locale
+    expect(result).toContain("2025");
+  });
+});

package/src/utils/formatDate.logic.ts

@@ -0,0 +1,27 @@
+/**
+ * Date formatting helpers for catalog-frontend.
+ *
+ * Uses the browser/runtime locale (undefined) instead of a hardcoded "en-US"
+ * so dates render in the user's preferred locale.
+ */
+
+/** Options used for human-readable catalog dates (e.g. "Jan 5, 2025"). */
+const DATE_FORMAT_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+};
+
+/**
+ * Format a date value as a short human-readable string using the runtime
+ * locale. Accepts a `Date` object or an ISO string.
+ *
+ * Returns an empty string for invalid or absent dates so the caller never
+ * shows "Invalid Date" in the UI.
+ */
+export function formatDate(value: Date | string | null | undefined): string {
+  if (!value) return "";
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  return date.toLocaleDateString(undefined, DATE_FORMAT_OPTIONS);
+}

package/src/utils/normalizeMetadata.logic.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeMetadata } from "./normalizeMetadata.logic";
+
+describe("normalizeMetadata", () => {
+  test("returns [] for null", () => {
+    expect(normalizeMetadata(null)).toEqual([]);
+  });
+
+  test("returns [] for undefined", () => {
+    expect(normalizeMetadata(undefined)).toEqual([]);
+  });
+
+  test("returns [] for an empty object", () => {
+    expect(normalizeMetadata({})).toEqual([]);
+  });
+
+  test("renders a string value inline", () => {
+    expect(normalizeMetadata({ owner: "platform-team" })).toEqual([
+      { key: "owner", displayValue: "platform-team" },
+    ]);
+  });
+
+  test("renders a number value inline", () => {
+    expect(normalizeMetadata({ priority: 1 })).toEqual([
+      { key: "priority", displayValue: "1" },
+    ]);
+  });
+
+  test("renders a boolean value inline", () => {
+    expect(normalizeMetadata({ critical: true })).toEqual([
+      { key: "critical", displayValue: "true" },
+    ]);
+  });
+
+  test("renders null value as 'null'", () => {
+    expect(normalizeMetadata({ deprecated: null })).toEqual([
+      { key: "deprecated", displayValue: "null" },
+    ]);
+  });
+
+  test("renders an object value as compact JSON", () => {
+    const result = normalizeMetadata({ links: { docs: "https://example.com" } });
+    expect(result).toEqual([
+      { key: "links", displayValue: '{"docs":"https://example.com"}' },
+    ]);
+  });
+
+  test("renders an array value as compact JSON", () => {
+    const result = normalizeMetadata({ tags: ["backend", "api"] });
+    expect(result).toEqual([
+      { key: "tags", displayValue: '["backend","api"]' },
+    ]);
+  });
+
+  test("handles multiple entries and preserves insertion order", () => {
+    const result = normalizeMetadata({
+      team: "payments",
+      version: 2,
+      active: false,
+    });
+    expect(result).toEqual([
+      { key: "team", displayValue: "payments" },
+      { key: "version", displayValue: "2" },
+      { key: "active", displayValue: "false" },
+    ]);
+  });
+});

package/src/utils/normalizeMetadata.logic.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/** Validated shape of a system's metadata field. */
+export const MetadataSchema = z.record(z.string(), z.unknown());
+
+/** A single displayable key/value pair derived from raw metadata. */
+export interface MetadataEntry {
+  key: string;
+  /** Human-readable value string: primitives as-is, objects/arrays as compact JSON. */
+  displayValue: string;
+}
+
+/**
+ * Normalise a raw `Record<string, unknown>` metadata object into a flat list
+ * of `{ key, displayValue }` pairs suitable for key/value rendering.
+ *
+ * - Primitives (`string`, `number`, `boolean`) are displayed as their string
+ *   representation.
+ * - `null` is displayed as `"null"`.
+ * - Objects and arrays are displayed as compact `JSON.stringify` output inside
+ *   a `<code>` element, so structure is preserved without a raw JSON blob.
+ * - An absent or empty metadata object yields `[]`.
+ */
+export function normalizeMetadata(
+  meta: Record<string, unknown> | null | undefined,
+): MetadataEntry[] {
+  if (!meta || typeof meta !== "object") return [];
+
+  const parsed = MetadataSchema.safeParse(meta);
+  if (!parsed.success) return [];
+
+  return Object.entries(parsed.data).map(([key, value]) => ({
+    key,
+    displayValue: valueToDisplay(value),
+  }));
+}
+
+function valueToDisplay(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "";
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/components/DraggableSystem.tsx

@@ -1,200 +0,0 @@
-import { useState } from "react";
-import { useDraggable } from "@dnd-kit/core";
-import { GripVertical, Edit, Trash2, FolderPlus } from "lucide-react";
-import { Button } from "@checkstack/ui";
-import { ExtensionSlot } from "@checkstack/frontend-api";
-import { CatalogSystemActionsSlot } from "@checkstack/catalog-common";
-import {
-  useProvenanceLock,
-  GitOpsSourceBadge,
-} from "@checkstack/gitops-frontend";
-import type { Group, System } from "../api";
-
-interface DraggableSystemProps {
-  system: System;
-  groups: Group[];
-  assignedGroupIds: string[];
-  onEdit: (system: System) => void;
-  onDelete: (id: string) => void;
-  onAddToGroup: (systemId: string, groupId: string) => void;
-}
-
-/**
- * A draggable system card for the Catalog Management page.
- *
- * Layout: two-row design so the system name is never truncated.
- *   Row 1: grip handle + full-width name + description
- *   Row 2 (footer): extension slot (Health Checks etc.) + action buttons
- *
- * On touch / small screens, the + button opens an inline group picker
- * since drag-and-drop can be imprecise on small viewports.
- *
- * We intentionally do NOT apply the useDraggable transform to the element —
- * DragOverlay handles the moving visual, keeping the original in-place.
- */
-export const DraggableSystem = ({
-  system,
-  groups,
-  assignedGroupIds,
-  onEdit,
-  onDelete,
-  onAddToGroup,
-}: DraggableSystemProps) => {
-  const [isPickerOpen, setIsPickerOpen] = useState(false);
-
-  const { isLocked, provenance } = useProvenanceLock({
-    kind: "System",
-    entityId: system.id,
-  });
-
-  const { attributes, listeners, setNodeRef } = useDraggable({
-    id: system.id,
-    disabled: isLocked,
-  });
-
-  const availableGroups = groups.filter((g) => !assignedGroupIds.includes(g.id));
-
-  return (
-    <div
-      ref={setNodeRef}
-      className="bg-muted/30 rounded-lg border border-border transition-all duration-150"
-    >
-      {/* Main row: grip + name/description */}
-      <div className="flex items-start gap-2 p-3 pb-2">
-        {/* Grip handle — only this element triggers the drag.
-            When GitOps-locked, swap in the source badge so users can click
-            through to the file that owns this system. */}
-        {isLocked && provenance ? (
-          <div className="flex-shrink-0 mt-0.5">
-            <GitOpsSourceBadge provenance={provenance} />
-          </div>
-        ) : (
-          <div
-            {...listeners}
-            {...attributes}
-            className="flex-shrink-0 mt-0.5 text-muted-foreground/40 touch-none cursor-grab active:cursor-grabbing hover:text-muted-foreground"
-            aria-label={`Drag ${system.name}`}
-          >
-            <GripVertical className="w-4 h-4" />
-          </div>
-        )}
-
-        {/* Name + description — gets all remaining width, never truncated */}
-        <div className="flex-1 min-w-0">
-          <p className="font-medium text-foreground leading-snug">
-            {system.name}
-          </p>
-          <p className="text-xs text-muted-foreground mt-0.5">
-            {system.description || "No description"}
-          </p>
-        </div>
-      </div>
-
-      {/* Footer row: unassigned badge (left) + all action buttons (right) */}
-      <div className="flex items-center justify-between gap-2 px-3 pb-2 pl-9">
-        {/* Left: unassigned badge */}
-        <div className="min-w-0">
-          {assignedGroupIds.length === 0 && (
-            <span className="flex-shrink-0 text-[10px] px-1.5 py-0.5 rounded bg-warning/15 text-warning-foreground font-mono">
-              unassigned
-            </span>
-          )}
-        </div>
-
-        {/* Right: extension slot + action buttons, all grouped together */}
-        <div className="flex items-center gap-1 flex-shrink-0">
-          <ExtensionSlot
-            slot={CatalogSystemActionsSlot}
-            context={{ systemId: system.id, systemName: system.name }}
-          />
-
-          {/* Group picker */}
-          <div className="relative">
-            <Button
-              variant="ghost"
-              size="sm"
-              className="h-7 w-7 p-0"
-              title={isLocked ? "Managed by GitOps" : `Add ${system.name} to a group`}
-              onClick={() => setIsPickerOpen((v) => !v)}
-              disabled={availableGroups.length === 0 || isLocked}
-              aria-expanded={isPickerOpen}
-              aria-haspopup="listbox"
-              aria-label={`Add ${system.name} to group`}
-            >
-              <FolderPlus className="w-3.5 h-3.5" />
-            </Button>
-
-            {isPickerOpen && availableGroups.length > 0 && (
-              <>
-                {/* Backdrop */}
-                <div
-                  className="fixed inset-0 z-40"
-                  onClick={() => setIsPickerOpen(false)}
-                />
-                <div
-                  role="listbox"
-                  aria-label="Select a group"
-                  className="absolute right-0 bottom-full mb-1 z-50 min-w-[160px] rounded-md border border-border bg-popover shadow-md py-1"
-                >
-                  {availableGroups.map((group) => (
-                    <button
-                      key={group.id}
-                      role="option"
-                      aria-selected={false}
-                      className="w-full text-left px-3 py-2 text-sm hover:bg-muted transition-colors"
-                      onClick={() => {
-                        onAddToGroup(system.id, group.id);
-                        setIsPickerOpen(false);
-                      }}
-                    >
-                      {group.name}
-                    </button>
-                  ))}
-                </div>
-              </>
-            )}
-          </div>
-
-          <Button
-            variant="ghost"
-            size="sm"
-            className="h-7 w-7 p-0"
-            onClick={() => onEdit(system)}
-            disabled={isLocked}
-            title={isLocked ? "Managed by GitOps" : undefined}
-            aria-label={`Edit ${system.name}`}
-          >
-            <Edit className="w-3.5 h-3.5" />
-          </Button>
-
-          <Button
-            variant="ghost"
-            size="sm"
-            className="text-destructive hover:text-destructive/90 hover:bg-destructive/10 h-7 w-7 p-0"
-            onClick={() => onDelete(system.id)}
-            disabled={isLocked}
-            title={isLocked ? "Managed by GitOps" : undefined}
-            aria-label={`Delete ${system.name}`}
-          >
-            <Trash2 className="w-3.5 h-3.5" />
-          </Button>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-/**
- * A non-interactive ghost card shown in the DragOverlay while dragging.
- */
-export const SystemDragOverlay = ({ system }: { system: System }) => (
-  <div className="flex items-center gap-2 p-3 bg-card rounded-lg border border-primary/50 shadow-lg cursor-grabbing w-full">
-    <GripVertical className="w-4 h-4 text-muted-foreground/40 flex-shrink-0" />
-    <div className="flex-1 min-w-0">
-      <p className="font-medium text-foreground">{system.name}</p>
-      <p className="text-xs text-muted-foreground">
-        {system.description || "No description"}
-      </p>
-    </div>
-  </div>
-);