@checkstack/api-docs-frontend 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @checkstack/api-docs-frontend
 
+## 0.3.0
+
+### Minor Changes
+
+- 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.
+
+- 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/api-docs-common@0.1.16
+
 ## 0.2.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/api-docs-frontend",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
@@ -16,10 +16,10 @@
     "@checkstack/frontend-api": "0.6.0",
     "@checkstack/common": "0.12.0",
     "@checkstack/api-docs-common": "0.1.15",
-    "@checkstack/ui": "1.11.0",
-    "react": "^18.2.0",
-    "react-router-dom": "^6.22.0",
-    "lucide-react": "^0.344.0"
+    "@checkstack/ui": "1.12.0",
+    "react": "^18.3.1",
+    "react-router-dom": "^7.16.0",
+    "lucide-react": "^1.17.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/index.tsx

@@ -1,12 +1,7 @@
-import {
-  createFrontendPlugin,
-  createSlotExtension,
-  UserMenuItemsSlot,
-} from "@checkstack/frontend-api";
+import { createFrontendPlugin } from "@checkstack/frontend-api";
 import { createRoutes } from "@checkstack/common";
 import { pluginMetadata, apiDocsAccess } from "@checkstack/api-docs-common";
-import { ApiDocsPage } from "./ApiDocsPage";
-import { ApiDocsMenuItem } from "./ApiDocsMenuItem";
+import { FileCode2 } from "lucide-react";
 
 export const apiDocsRoutes = createRoutes(pluginMetadata.pluginId, {
   docs: "/",
@@ -17,17 +12,15 @@ export const apiDocsPlugin = createFrontendPlugin({
   routes: [
     {
       route: apiDocsRoutes.routes.docs,
-      element: <ApiDocsPage />,
+      load: () => import("./ApiDocsPage").then((m) => ({ default: m.ApiDocsPage })),
       accessRule: apiDocsAccess.view,
+      nav: {
+        group: "Documentation",
+        icon: FileCode2,
+        label: "API Documentation",
+      },
     },
   ],
-  extensions: [
-    createSlotExtension(UserMenuItemsSlot, {
-      id: "api-docs.user-menu.link",
-      component: ApiDocsMenuItem,
-      metadata: { group: "Documentation" },
-    }),
-  ],
 });
 
 export default apiDocsPlugin;

package/src/ApiDocsMenuItem.tsx

@@ -1,29 +0,0 @@
-import { useNavigate } from "react-router-dom";
-import { FileCode2 } from "lucide-react";
-import { DropdownMenuItem } from "@checkstack/ui";
-import type { UserMenuItemsContext } from "@checkstack/frontend-api";
-import { resolveRoute } from "@checkstack/common";
-import { pluginMetadata, apiDocsAccess } from "@checkstack/api-docs-common";
-import { apiDocsRoutes } from "./index";
-import React from "react";
-
-const REQUIRED_ACCESS_RULE = `${pluginMetadata.pluginId}.${apiDocsAccess.view.id}`;
-
-export function ApiDocsMenuItem({
-  accessRules: userPerms,
-}: UserMenuItemsContext) {
-  const navigate = useNavigate();
-  const canView =
-    userPerms.includes("*") || userPerms.includes(REQUIRED_ACCESS_RULE);
-
-  if (!canView) return <React.Fragment />;
-
-  return (
-    <DropdownMenuItem
-      onClick={() => navigate(resolveRoute(apiDocsRoutes.routes.docs))}
-      icon={<FileCode2 className="h-4 w-4" />}
-    >
-      API Documentation
-    </DropdownMenuItem>
-  );
-}