@checkstack/integration-frontend 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @checkstack/integration-frontend
 
+## 0.6.0
+
+### Minor Changes
+
+- 9dcc848: Surface integration connection validation errors inline, and fix blank secrets clearing stored credentials on edit.
+
+  `@checkstack/ui` `DynamicForm` gains opt-in, backward-compatible props plus pure DOM-free helpers:
+
+  - `showInlineErrors` (default `false`): renders a concise per-field error under each touched required field; the `onValidChange` validity boolean derives from the same per-field error map.
+  - `fieldErrors`: an externally-supplied `{ [fieldPath]: message }` map (dot-joined for nested fields) for surfacing SERVER validation inline; nested paths flag their parent.
+  - `keepExistingSecretFields`: in EDIT mode, lists `x-secret` keys already stored server-side - a blank input means "keep existing" and is treated as VALID (CREATE mode omits it). New exported helpers: `deriveClientFieldErrors`, `deriveServerFieldErrors`, `parseServerValidationData`, `omitKeepExistingSecrets`, `listSecretFieldKeys`. `DynamicForm` also no longer shows a required (`*`) marker on the child fields of an OPTIONAL nested object while that object is empty (e.g. the OpenAI-compatible `spendCap`); required nested objects are unchanged.
+
+  `@checkstack/integration-backend`: connection-config validation failures attach the structured zod issues to `ORPCError.data` under a `CONFIG_VALIDATION` discriminator; the human-readable message is unchanged.
+
+  `@checkstack/integration-frontend` `ProviderConnectionsPage`: validation failures appear inline on the offending fields (the toast remains a fallback); Create/Save stays disabled while invalid; on edit a blank `x-secret` field is treated as "keep existing" (no required error, omitted from the update so the stored secret is not cleared).
+
+  BREAKING CHANGES: none. The new `DynamicForm` props are optional and default to previous behavior.
+
+  This is a beta minor.
+
+- 9dcc848: Cut initial-load JS: lazy plugin contributions, a hardened lazy-by-default contribution contract, on-demand Monaco, and a lighter icon/chart load.
+
+  - Lazy plugin route pages: each plugin's route `element` references a `React.lazy`-wrapped page rendered inside a shared `<Suspense>` boundary. Plugins still register synchronously, so nav, slots, commands, API factories, and `foreignSignals` are available on first paint. This moves ~37 route-page chunks (~600 KB) out of the entry; the entry chunk drops from ~2.4 MB to ~190 KB. Auth flow pages stay eager. The `@checkstack/scripts` scaffold template generates lazy route pages too.
+  - Hardened contribution contract (BREAKING, frontend plugin contract): plugins declare contributions lazily and let the framework own code-splitting, Suspense, and per-plugin error isolation. Routes use `load: () => import("./Page").then((m) => ({ default: m.Page }))` instead of `element: <Page />` (`element` is still accepted for the rare page that must paint without a chunk fetch; provide exactly one). Slot extensions accept either an eager `component` or a lazy `load`; new `getLazyContribution` + `ExtensionComponent` exports from `@checkstack/frontend-api` render either kind. This also fixes runtime-installed plugins: `ExtensionSlot` subscribes to the plugin registry, and the API registry rebuilds when the plugin set changes (`getPlugins()` returns an immutable snapshot via `useSyncExternalStore`). A per-plugin error boundary contains a bad contribution.
+  - On-demand Monaco: the `@checkstack/ui` barrel no longer pulls the `@codingame/*` / `monaco-languageclient` stack into the initial load. `CodeEditor` lazy-loads its Monaco-backed editor behind `React.lazy` + Suspense, `validateTypeScriptSources` imports the editor API via in-body `await import(...)`, and the "vscode services ready" signal moved to a Monaco-free module. The ~10 MB editor body loads only when a `CodeEditor` mounts. A `react-vendor` `manualChunks` split was added for stable vendor caching.
+  - lucide-react 1.x + lighter icons/charts (BREAKING for icon consumers): lucide-react unified from three drifting ranges to `^1.17.0`. lucide v1 removed brand icons, so the GitHub/GitLab marks are vendored in `@checkstack/ui` (`GithubIcon`, `GitlabIcon`, `brandIcons`); a new `IconName` type (`LucideIconName | BrandIconName`) in `@checkstack/common` is canonical, accepted by `AuthStrategy.icon` and the card components, so data-driven brand names keep working. `DynamicIcon` no longer eagerly imports lucide's ~1600-icon map (~1 MB) - it lives in a `React.lazy` `iconRegistry` chunk fetched on first data-driven render, while statically named-imported icons tree-shake normally. The recharts-backed health-check charts (~300 KB) and the `HealthCheckSystemOverview` drawer leave the initial load.
+
+  BREAKING CHANGES:
+
+  - Frontend plugin contract: routes/slot contributions are lazy-by-default (`load` instead of `element`/eager elements) as described above.
+  - Any external consumer importing a brand icon from `lucide-react` (e.g. `import { Github } from "lucide-react"`) must switch to the vendored `@checkstack/ui` brand icons or a custom SVG.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- 9dcc848: Move primary navigation into a left sidebar, and serve the user guide in-app.
+
+  Feature navigation (a ~20-item user-menu dropdown) now lives in a persistent left sidebar (a slide-over drawer on mobile), grouped by section with the active route highlighted; the user menu keeps only account actions. A route opts into the sidebar with new `nav` metadata (`{ group, icon, label?, order?, accessRule? }`) on its registration, co-located with path + access + title. The sidebar filters entries with the same access check as page guards. `@checkstack/common` gains `isAccessRuleSatisfied` and a centralized set of in-app doc slugs (`APP_DOC_SLUGS` + `docsPath`, with a test asserting each resolves to a real docs page); `@checkstack/auth-frontend` exports `useAccessRules`.
+
+  The backend now serves the Astro Starlight docs build same-origin at `/checkstack/*` (the same artifact deployed to GitHub Pages), so the user guide is available inside the app including for self-hosted / air-gapped installs (served verbatim, no rebuild, no link rewriting; from `CHECKSTACK_DOCS_DIST`, before the SPA catch-all, degrading gracefully when absent; the Docker image builds and ships `docs/dist`; Vite proxies `/checkstack` in dev). The "Docs" link is a shell-owned external sidebar entry under the Documentation group (book icon), opening `/checkstack/user-guide/` in a new tab; the group renders even when no plugin route contributes to it.
+
+  BREAKING (plugin authors): `UserMenuItemsSlot` is no longer the way to add navigation - registering a top user-menu item no longer surfaces it anywhere. Add `nav` to the page's route instead. `UserMenuItemsBottomSlot` (account items) is unchanged. All bundled plugins have been migrated.
+
+  This is a beta minor.
+
+- 9dcc848: Guard component animations behind isLowPower, and add a shared inline Spinner.
+
+  - `@checkstack/ui` shared components (`Tabs`, `ConfirmationModal`, `Accordion`, `CodeEditor` popout-button backdrop blur) now drop their `animate-*` / `backdrop-blur` classes when the device reports the low-power tier, matching `LoadingSpinner` / `Skeleton`. No public API change; normal-power rendering is unchanged.
+  - A new shared inline `Spinner` (`@checkstack/ui`) renders a lucide `Loader2` whose `animate-spin` is gated internally behind `usePerformance().isLowPower`, so call sites inherit the low-power guard. Props: `size` (`sm`/`md`/`lg`), `className`, rest spread to the icon; decorative by default (`aria-hidden`), `role="status"` when given `aria-label`. The hand-rolled `Loader2` button/table spinners in `HealthCheckDrawer`, `HealthCheckRunsTable`, `IncidentEditor`, `IncidentUpdateForm`, `ProviderConnectionsPage`, `MaintenanceEditor`, `MaintenanceUpdateForm`, `UserChannelCard`, and `DynamicOptionsField` are migrated onto it.
+  - Remaining unguarded `animate-*` / `animate-in` / blur classes across the auth, gitops, healthcheck, incident, integration, maintenance, and notification frontends are gated behind `usePerformance().isLowPower`, so effects degrade gracefully on low-power devices per the performance rule.
+
+  Normal-power behavior is unchanged; low-power rendering drops the animations.
+
+  This is a beta minor.
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/ui@1.13.0
+  - @checkstack/common@0.13.0
+  - @checkstack/frontend-api@0.7.0
+  - @checkstack/tips-frontend@0.3.0
+  - @checkstack/integration-common@0.7.0
+  - @checkstack/signal-frontend@0.2.0
+
 ## 0.5.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/integration-frontend",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
@@ -17,11 +17,11 @@
     "@checkstack/frontend-api": "0.6.0",
     "@checkstack/integration-common": "0.6.0",
     "@checkstack/signal-frontend": "0.1.5",
-    "@checkstack/tips-frontend": "0.2.6",
-    "@checkstack/ui": "1.11.0",
-    "lucide-react": "^0.344.0",
-    "react": "^18.2.0",
-    "react-router-dom": "^6.22.0"
+    "@checkstack/tips-frontend": "0.2.7",
+    "@checkstack/ui": "1.12.0",
+    "lucide-react": "^1.17.0",
+    "react": "^18.3.1",
+    "react-router-dom": "^7.16.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/index.tsx

@@ -1,16 +1,10 @@
-import {
-  createFrontendPlugin,
-  createSlotExtension,
-  UserMenuItemsSlot,
-} from "@checkstack/frontend-api";
+import { createFrontendPlugin } from "@checkstack/frontend-api";
 import {
   integrationRoutes,
   pluginMetadata,
   integrationAccess,
 } from "@checkstack/integration-common";
-import { IntegrationsLandingPage } from "./pages/IntegrationsLandingPage";
-import { ProviderConnectionsPage } from "./pages/ProviderConnectionsPage";
-import { IntegrationMenuItem } from "./components/IntegrationMenuItem";
+import { Webhook } from "lucide-react";
 
 /**
  * Integration frontend — now scoped to connection management. The
@@ -24,22 +18,26 @@ export const integrationPlugin = createFrontendPlugin({
   routes: [
     {
       route: integrationRoutes.routes.list,
-      element: <IntegrationsLandingPage />,
+      load: () =>
+        import("./pages/IntegrationsLandingPage").then((m) => ({
+          default: m.IntegrationsLandingPage,
+        })),
       accessRule: integrationAccess.manage,
+      nav: {
+        group: "Configuration",
+        icon: Webhook,
+        label: "Integrations",
+      },
     },
     {
       route: integrationRoutes.routes.connections,
-      element: <ProviderConnectionsPage />,
+      load: () =>
+        import("./pages/ProviderConnectionsPage").then((m) => ({
+          default: m.ProviderConnectionsPage,
+        })),
       accessRule: integrationAccess.manage,
     },
   ],
-  extensions: [
-    createSlotExtension(UserMenuItemsSlot, {
-      id: "integration.user-menu.link",
-      component: IntegrationMenuItem,
-      metadata: { group: "Configuration" },
-    }),
-  ],
 });
 
 export default integrationPlugin;

package/src/pages/ProviderConnectionsPage.tsx

@@ -13,7 +13,6 @@ import {
   TestTube2,
   CheckCircle2,
   XCircle,
-  Loader2,
 } from "lucide-react";
 import {
   PageLayout,
@@ -43,6 +42,12 @@ import {
   ConfirmationModal,
   BackLink,
   toastError,
+  Spinner,
+  deriveServerFieldErrors,
+  parseServerValidationData,
+  omitKeepExistingSecrets,
+  listSecretFieldKeys,
+  type FieldErrorMap,
   type LucideIconName,
 } from "@checkstack/ui";
 import { usePluginClient } from "@checkstack/frontend-api";
@@ -81,6 +86,8 @@ export const ProviderConnectionsPage = () => {
 
   // Form validation state
   const [configValid, setConfigValid] = useState(false);
+  // Server validation errors mapped to form fields (cleared on each submit).
+  const [serverFieldErrors, setServerFieldErrors] = useState<FieldErrorMap>({});
 
   // Queries using hooks
   const { data: providers = [], isLoading: providersLoading } =
@@ -98,6 +105,40 @@ export const ProviderConnectionsPage = () => {
   const loading = providersLoading || connectionsLoading;
   const provider = providers.find((p) => p.qualifiedId === providerId);
 
+  // Try to surface a mutation error INLINE on the offending form fields. The
+  // backend attaches structured zod issues (field path + message) to the
+  // error `data` for connection-config validation failures; parse that
+  // payload (typed, via the shared schema) and map each issue to its field.
+  // Anything not field-mappable (generic / unknown errors, or issues whose
+  // root is not a rendered field) falls back to the existing toast so nothing
+  // is swallowed.
+  const handleMutationError = (action: string, error: unknown): void => {
+    const schema = provider?.connectionSchema;
+    const data =
+      error && typeof error === "object" && "data" in error
+        ? error.data
+        : undefined;
+    const parsed = schema ? parseServerValidationData(data) : undefined;
+
+    if (schema && parsed) {
+      const { mapped, unmapped } = deriveServerFieldErrors({
+        issues: parsed.issues,
+        schema,
+      });
+      if (Object.keys(mapped).length > 0) {
+        setServerFieldErrors(mapped);
+      }
+      // Surface any non-mappable issues (and a fully-unmappable payload) via
+      // the toast so they are never silently dropped.
+      if (unmapped.length > 0 || Object.keys(mapped).length === 0) {
+        toastError(toast, action, error);
+      }
+      return;
+    }
+
+    toastError(toast, action, error);
+  };
+
   // Mutations
   const createMutation = client.createConnection.useMutation({
     onSuccess: () => {
@@ -109,7 +150,7 @@ export const ProviderConnectionsPage = () => {
       setSaving(false);
     },
     onError: (error) => {
-      toastError(toast, "Failed to create connection", error);
+      handleMutationError("Failed to create connection", error);
       setSaving(false);
     },
   });
@@ -123,7 +164,7 @@ export const ProviderConnectionsPage = () => {
       setSaving(false);
     },
     onError: (error) => {
-      toastError(toast, "Failed to update connection", error);
+      handleMutationError("Failed to update connection", error);
       setSaving(false);
     },
   });
@@ -163,8 +204,18 @@ export const ProviderConnectionsPage = () => {
     },
   });
 
+  // In EDIT mode every `x-secret` field defined by the provider schema may
+  // already hold a stored value (secrets are redacted out of the loaded
+  // preview), so a blank input means "keep existing" and is valid. In CREATE
+  // mode no secret is stored yet, so this is empty and blank secrets stay
+  // required.
+  const keepExistingSecretFields = provider?.connectionSchema
+    ? listSecretFieldKeys(provider.connectionSchema)
+    : [];
+
   const handleCreate = () => {
     if (!providerId || !formName.trim()) return;
+    setServerFieldErrors({});
     setSaving(true);
     createMutation.mutate({
       providerId,
@@ -178,17 +229,26 @@ export const ProviderConnectionsPage = () => {
     setFormName("");
     setFormConfig({});
     setConfigValid(false);
+    setServerFieldErrors({});
     setCreateDialogOpen(true);
   };
 
   const handleUpdate = () => {
-    if (!selectedConnection) return;
+    if (!selectedConnection || !provider?.connectionSchema) return;
+    setServerFieldErrors({});
     setSaving(true);
+    // Drop blank keep-existing secrets so an empty input does not clear the
+    // stored secret on update.
+    const config = omitKeepExistingSecrets({
+      schema: provider.connectionSchema,
+      value: formConfig,
+      keepExistingSecretFields,
+    });
     updateMutation.mutate({
       connectionId: selectedConnection.id,
       updates: {
         name: formName.trim() || selectedConnection.name,
-        config: formConfig,
+        config,
       },
     });
   };
@@ -208,6 +268,7 @@ export const ProviderConnectionsPage = () => {
     setFormName(connection.name);
     setFormConfig(connection.configPreview);
     setConfigValid(true); // Existing connections should have valid config
+    setServerFieldErrors({});
     setEditDialogOpen(true);
   };
 
@@ -347,7 +408,7 @@ export const ProviderConnectionsPage = () => {
                             disabled={isTesting}
                           >
                             {isTesting ? (
-                              <Loader2 className="h-4 w-4 animate-spin" />
+                              <Spinner size="sm" />
                             ) : (
                               <TestTube2 className="h-4 w-4" />
                             )}
@@ -402,6 +463,8 @@ export const ProviderConnectionsPage = () => {
                 value={formConfig}
                 onChange={setFormConfig}
                 onValidChange={setConfigValid}
+                showInlineErrors
+                fieldErrors={serverFieldErrors}
               />
             )}
           </div>
@@ -416,7 +479,7 @@ export const ProviderConnectionsPage = () => {
               onClick={handleCreate}
               disabled={!formName.trim() || !configValid || saving}
             >
-              {saving && <Loader2 className="h-4 w-4 mr-2 animate-spin" />}
+              {saving && <Spinner size="sm" className="mr-2" />}
               Create
             </Button>
           </DialogFooter>
@@ -445,6 +508,9 @@ export const ProviderConnectionsPage = () => {
                 value={formConfig}
                 onChange={setFormConfig}
                 onValidChange={setConfigValid}
+                showInlineErrors
+                fieldErrors={serverFieldErrors}
+                keepExistingSecretFields={keepExistingSecretFields}
               />
             )}
           </div>
@@ -453,7 +519,7 @@ export const ProviderConnectionsPage = () => {
               Cancel
             </Button>
             <Button onClick={handleUpdate} disabled={!configValid || saving}>
-              {saving && <Loader2 className="h-4 w-4 mr-2 animate-spin" />}
+              {saving && <Spinner size="sm" className="mr-2" />}
               Save Changes
             </Button>
           </DialogFooter>

package/src/components/IntegrationMenuItem.tsx

@@ -1,37 +0,0 @@
-import React from "react";
-import { Link } from "react-router-dom";
-import { Webhook } from "lucide-react";
-import { DropdownMenuItem } from "@checkstack/ui";
-import type { UserMenuItemsContext } from "@checkstack/frontend-api";
-import { resolveRoute } from "@checkstack/common";
-import {
-  integrationRoutes,
-  integrationAccess,
-  pluginMetadata,
-} from "@checkstack/integration-common";
-
-/**
- * "Integrations" entry in the user menu. Links to the integrations landing
- * page (provider list); each provider links on to its connection-management
- * page. Gated on `integration.manage` — mirrors the access check the routes
- * themselves enforce, but hiding the link is the cleaner UX for users who
- * can't manage connections.
- */
-export const IntegrationMenuItem = ({
-  accessRules: userPerms,
-}: UserMenuItemsContext) => {
-  const qualifiedId = `${pluginMetadata.pluginId}.${integrationAccess.manage.id}`;
-  const allowed = userPerms.includes("*") || userPerms.includes(qualifiedId);
-
-  if (!allowed) {
-    return <React.Fragment />;
-  }
-
-  return (
-    <Link to={resolveRoute(integrationRoutes.routes.list)}>
-      <DropdownMenuItem icon={<Webhook className="h-4 w-4" />}>
-        Integrations
-      </DropdownMenuItem>
-    </Link>
-  );
-};