@ekanos/harness 0.4.3 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,6 +5,8 @@ real Ekanos chrome — the actual dashboard grid, the actual `Widget.*` compound
5
5
  components, the actual design tokens — from fixtures, with no Supabase, no auth
6
6
  and no network.
7
7
 
8
+ **Docs:** [sdk.ekanos.dev/harness/overview](https://sdk.ekanos.dev/harness/overview).
9
+
8
10
  **New here? Start with the `@ekanos/sdk` README** — it is the authoring
9
11
  reference for everything you declare (widgets, tools, webhooks, schedules,
10
12
  OAuth, storage, egress). This document covers only the local dev harness that
@@ -25,9 +25,10 @@ import { type WidgetRenderState } from '@ekanos/sdk/components';
25
25
  * - ADDED a `WidgetBoundary` around each widget so one partner's crash
26
26
  * renders a readable card instead of blanking the page.
27
27
  *
28
- * Everything else — grid classes, row grouping, the props handed to the
29
- * provider, the two props handed to the widget — is verbatim. If the real grid
30
- * changes, this needs the same change.
28
+ * Everything else — grid classes, the props handed to the provider, the two
29
+ * props handed to the widget — is verbatim. Row grouping is not copied: both
30
+ * grids import it from `@ekanos/sdk/layout` (the design system's widget rules). If
31
+ * the real grid's markup changes, this needs the same change.
31
32
  */
32
33
  type DashboardGridLayout = 'masonry' | 'two-column';
33
34
  interface DashboardGridProps {
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
  import { jsx, jsxs } from "react/jsx-runtime";
3
+ import { buildRowGroups, splitBalanced } from "@ekanos/sdk/layout";
3
4
  import { HarnessWidgetProvider } from "./harness-widget-provider.js";
4
- import { buildRowGroups, splitBalanced } from "./row-groups.js";
5
5
  import { WidgetBoundary } from "./widget-boundary.js";
6
6
  function DashboardGrid({
7
7
  widgets,
@@ -27,6 +27,16 @@ function DashboardGrid({
27
27
  group.widget.id
28
28
  );
29
29
  }
30
+ if (group.type === "compact") {
31
+ return /* @__PURE__ */ jsx(
32
+ "div",
33
+ {
34
+ className: "grid grid-cols-1 items-start gap-5 @xl/dashboard:grid-cols-2 @4xl/dashboard:grid-cols-4",
35
+ children: group.widgets.map((widget) => /* @__PURE__ */ jsx(WidgetRenderer, { widget, ...shared }, widget.id))
36
+ },
37
+ group.widgets[0].id
38
+ );
39
+ }
30
40
  const { left, right } = splitBalanced(group.widgets);
31
41
  return /* @__PURE__ */ jsxs(
32
42
  "div",
@@ -22,6 +22,7 @@ import {
22
22
  resolveEgress,
23
23
  supportsLiveMode
24
24
  } from "../../registry.js";
25
+ import { HARNESS_DOCS_URL } from "../lib/docs-links.js";
25
26
  import { getThemeToggleAccessibleLabel } from "../lib/theme-toggle.js";
26
27
  import {
27
28
  RENDER_STATES,
@@ -29,6 +30,7 @@ import {
29
30
  useToolbar
30
31
  } from "../lib/toolbar-context.js";
31
32
  import { useHarnessRegistry } from "../registry-context.js";
33
+ import { DocsLink } from "./docs-link.js";
32
34
  function Field({
33
35
  label,
34
36
  children
@@ -118,6 +120,7 @@ function DevToolbar() {
118
120
  }
119
121
  ) }),
120
122
  /* @__PURE__ */ jsxs("div", { className: "ml-auto flex items-center gap-2", children: [
123
+ /* @__PURE__ */ jsx(DocsLink, { href: HARNESS_DOCS_URL, "data-test": "toolbar-docs-link", children: "Docs" }),
121
124
  live ? /* @__PURE__ */ jsxs(
122
125
  "span",
123
126
  {
@@ -0,0 +1,11 @@
1
+ /**
2
+ * An external link into the public SDK docs. Opens in a new tab: the harness
3
+ * holds unsaved local state (toolbar choices, an in-progress activation form)
4
+ * that navigating away in place would throw out.
5
+ */
6
+ export declare function DocsLink({ href, children, className, ...rest }: {
7
+ href: string;
8
+ children: React.ReactNode;
9
+ className?: string;
10
+ 'data-test'?: string;
11
+ }): import("react").JSX.Element;
@@ -0,0 +1,30 @@
1
+ import { jsx, jsxs } from "react/jsx-runtime";
2
+ import { Icon } from "@ekanos/ui/icon";
3
+ import { cn } from "@ekanos/ui/utils";
4
+ function DocsLink({
5
+ href,
6
+ children,
7
+ className,
8
+ ...rest
9
+ }) {
10
+ return /* @__PURE__ */ jsxs(
11
+ "a",
12
+ {
13
+ href,
14
+ target: "_blank",
15
+ rel: "noopener noreferrer",
16
+ className: cn(
17
+ "text-muted-foreground hover:text-foreground flex items-center gap-2 text-sm underline-offset-2 hover:underline",
18
+ className
19
+ ),
20
+ ...rest,
21
+ children: [
22
+ /* @__PURE__ */ jsx(Icon, { name: "fa-solid fa-book", className: "h-4 w-4" }),
23
+ children
24
+ ]
25
+ }
26
+ );
27
+ }
28
+ export {
29
+ DocsLink
30
+ };
@@ -4,11 +4,17 @@ import Link from "next/link";
4
4
  import { usePathname } from "next/navigation";
5
5
  import { Icon } from "@ekanos/ui/icon";
6
6
  import { cn } from "@ekanos/ui/utils";
7
+ import { SURFACE_DOCS } from "../lib/docs-links.js";
7
8
  import { HARNESS_SURFACES } from "../surfaces.js";
9
+ import { DocsLink } from "./docs-link.js";
8
10
  function SurfaceNav({
9
11
  integration
10
12
  }) {
11
13
  const pathname = usePathname();
14
+ const activeSurface = HARNESS_SURFACES.find(
15
+ (surface) => pathname.startsWith(`/${integration.slug}/${surface.segment}`)
16
+ );
17
+ const surfaceDocs = activeSurface ? SURFACE_DOCS[activeSurface.segment] : void 0;
12
18
  return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-5 border-b px-6 py-5", children: [
13
19
  /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-baseline gap-3", children: [
14
20
  /* @__PURE__ */ jsxs(
@@ -25,25 +31,39 @@ function SurfaceNav({
25
31
  /* @__PURE__ */ jsx("h1", { className: "font-heading text-2xl tracking-tight", children: integration.name }),
26
32
  /* @__PURE__ */ jsx("code", { className: "text-muted-foreground text-xs", children: integration.slug })
27
33
  ] }),
28
- /* @__PURE__ */ jsx("nav", { className: "flex flex-wrap gap-1", children: HARNESS_SURFACES.map((surface) => {
29
- const href = `/${integration.slug}/${surface.segment}`;
30
- const active = pathname.startsWith(href);
31
- return /* @__PURE__ */ jsxs(
32
- Link,
34
+ /* @__PURE__ */ jsxs("nav", { className: "flex flex-wrap items-center gap-1", children: [
35
+ HARNESS_SURFACES.map((surface) => {
36
+ const href = `/${integration.slug}/${surface.segment}`;
37
+ const active = pathname.startsWith(href);
38
+ return /* @__PURE__ */ jsxs(
39
+ Link,
40
+ {
41
+ href,
42
+ className: cn(
43
+ "flex items-center gap-2 rounded-md px-3 py-2 text-sm transition-colors",
44
+ active ? "bg-accent text-accent-foreground font-medium" : "text-muted-foreground hover:bg-accent/50"
45
+ ),
46
+ children: [
47
+ /* @__PURE__ */ jsx(Icon, { name: surface.icon, className: "h-5 w-5" }),
48
+ surface.label
49
+ ]
50
+ },
51
+ surface.segment
52
+ );
53
+ }),
54
+ activeSurface && surfaceDocs ? /* @__PURE__ */ jsxs(
55
+ DocsLink,
33
56
  {
34
- href,
35
- className: cn(
36
- "flex items-center gap-2 rounded-md px-3 py-2 text-sm transition-colors",
37
- active ? "bg-accent text-accent-foreground font-medium" : "text-muted-foreground hover:bg-accent/50"
38
- ),
57
+ href: surfaceDocs,
58
+ className: "ml-auto px-3",
59
+ "data-test": "surface-docs-link",
39
60
  children: [
40
- /* @__PURE__ */ jsx(Icon, { name: surface.icon, className: "h-5 w-5" }),
41
- surface.label
61
+ activeSurface.label,
62
+ " docs"
42
63
  ]
43
- },
44
- surface.segment
45
- );
46
- }) }),
64
+ }
65
+ ) : null
66
+ ] }),
47
67
  integration.widgets.length > 0 ? /* @__PURE__ */ jsxs("nav", { className: "flex flex-wrap gap-1", children: [
48
68
  /* @__PURE__ */ jsx("span", { className: "text-muted-foreground px-3 py-2 text-xs", children: "Focus one widget:" }),
49
69
  integration.widgets.map((widget) => {
@@ -0,0 +1,5 @@
1
+ /** The public Ekanos SDK docs. Every docs link the harness renders reads this. */
2
+ export declare const SDK_DOCS_URL = "https://sdk.ekanos.dev";
3
+ export declare const HARNESS_DOCS_URL = "https://sdk.ekanos.dev/harness/overview";
4
+ /** The docs page for each harness surface, keyed by `HarnessSurface.segment`. */
5
+ export declare const SURFACE_DOCS: Readonly<Record<string, string>>;
@@ -0,0 +1,13 @@
1
+ const SDK_DOCS_URL = "https://sdk.ekanos.dev";
2
+ const HARNESS_DOCS_URL = `${SDK_DOCS_URL}/harness/overview`;
3
+ const SURFACE_DOCS = {
4
+ widgets: `${SDK_DOCS_URL}/sdk/surfaces/widgets`,
5
+ tile: `${SDK_DOCS_URL}/sdk/surfaces/marketplace-tile`,
6
+ activation: `${SDK_DOCS_URL}/sdk/surfaces/activation-form`,
7
+ triggers: `${SDK_DOCS_URL}/harness/triggers`
8
+ };
9
+ export {
10
+ HARNESS_DOCS_URL,
11
+ SDK_DOCS_URL,
12
+ SURFACE_DOCS
13
+ };
@@ -69,13 +69,13 @@ function ActivationPage() {
69
69
  /* @__PURE__ */ jsx(AlertTitle, { children: mode === "live" ? "Submissions run onActivate on the dev server" : "Submissions go nowhere" }),
70
70
  /* @__PURE__ */ jsxs(AlertDescription, { children: [
71
71
  /* @__PURE__ */ jsxs("p", { children: [
72
- "The harness has no Ekanos backend. Submitting shows you the",
72
+ mode === "live" ? "The generated shell stands in for the Ekanos backend. Submitting stores every string field of the form in .ekanos/local-secrets.json and hands it to your live handlers as ctx.secrets, then runs onActivate on that context \u2014 the same rule the host applies to the activation row. " : "The harness has no Ekanos backend. Submitting shows you the ",
73
+ mode === "live" ? null : /* @__PURE__ */ jsx("code", { children: "ActivationResult" }),
74
+ mode === "live" ? "The " : " your form handed back instead of persisting it \u2014 which is the part worth checking, since that payload is what the real activation action would store. The ",
75
+ "dialog, the capability and permission sections and the connected state are the real ones, rendered from your",
73
76
  " ",
74
- /* @__PURE__ */ jsx("code", { children: "ActivationResult" }),
75
- " your form handed back instead of persisting it \u2014 which is the part worth checking, since that payload is what the real activation action would store. The dialog, the capability and permission sections and the connected state are the real ones, rendered from your ",
76
77
  /* @__PURE__ */ jsx("code", { children: "defineIntegration()" }),
77
- " ",
78
- "declaration."
78
+ " declaration."
79
79
  ] }),
80
80
  /* @__PURE__ */ jsx("p", { "data-test": "activation-mode-notice-top", children: mode === "live" ? "Live API: an OAuth form\u2019s Connect runs the real loop through the generated shell (see Local OAuth below), onActivate runs on the server-held context that loop stored tokens in, and widgets reach real vendors through useIntegrationFetch(). The host runs the same declarations, with real enforcement, after you publish." : "Fixtures: an OAuth form reads its connection status from oauth.connected in your harness entry, onActivate runs in this browser against a context seeded from triggerMocks, and nothing leaves your machine." })
81
81
  ] })
@@ -0,0 +1,13 @@
1
+ /**
2
+ * `/<slug>` — the address the home page's cards, the back link and every
3
+ * partner's muscle memory land on. It has no surface of its own: the five
4
+ * surfaces live one segment deeper, so this sends the browser to
5
+ * `/<slug>/widgets` (the one every session starts on) instead of rendering a
6
+ * 404 under a working toolbar, which is how it read for three releases.
7
+ *
8
+ * A client component because the registry — and therefore "does this slug
9
+ * exist" — is only readable from context (see routes.ts). The effect is the
10
+ * redirect itself: `redirect()` from next/navigation is a server-side
11
+ * primitive, and `router.replace` is the client equivalent.
12
+ */
13
+ export declare function IntegrationIndexPage(): null;
@@ -0,0 +1,17 @@
1
+ "use client";
2
+ import { useEffect } from "react";
3
+ import { notFound, useParams, useRouter } from "next/navigation";
4
+ import { useHarnessIntegration } from "../registry-context.js";
5
+ function IntegrationIndexPage() {
6
+ const params = useParams();
7
+ const router = useRouter();
8
+ const integration = useHarnessIntegration();
9
+ useEffect(() => {
10
+ if (integration) router.replace(`/${params.slug}/widgets`);
11
+ }, [integration, params.slug, router]);
12
+ if (!integration) notFound();
13
+ return null;
14
+ }
15
+ export {
16
+ IntegrationIndexPage
17
+ };
package/dist/routes.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * The five `[slug]` surfaces plus their shared layout.
2
+ * The five `[slug]` surfaces, the `/<slug>` index that redirects to the first
3
+ * of them, plus their shared layout.
3
4
  *
4
5
  * Every one is a `'use client'` module: the registry holds live React component
5
6
  * references, which cannot cross the server/client boundary as props, so each
@@ -17,6 +18,7 @@
17
18
  * local dev tool that is not a real cost.
18
19
  */
19
20
  export { IntegrationLayout } from './internal/routes/integration-layout.js';
21
+ export { IntegrationIndexPage } from './internal/routes/integration-index-page.js';
20
22
  export { WidgetsPage } from './internal/routes/widgets-page.js';
21
23
  export { SingleWidgetPage } from './internal/routes/single-widget-page.js';
22
24
  export { TilePage } from './internal/routes/tile-page.js';
package/dist/routes.js CHANGED
@@ -1,5 +1,6 @@
1
1
  "use client";
2
2
  import { IntegrationLayout } from "./internal/routes/integration-layout.js";
3
+ import { IntegrationIndexPage } from "./internal/routes/integration-index-page.js";
3
4
  import { WidgetsPage } from "./internal/routes/widgets-page.js";
4
5
  import { SingleWidgetPage } from "./internal/routes/single-widget-page.js";
5
6
  import { TilePage } from "./internal/routes/tile-page.js";
@@ -7,6 +8,7 @@ import { ActivationPage } from "./internal/routes/activation-page.js";
7
8
  import { TriggersPage } from "./internal/routes/triggers-page.js";
8
9
  export {
9
10
  ActivationPage,
11
+ IntegrationIndexPage,
10
12
  IntegrationLayout,
11
13
  SingleWidgetPage,
12
14
  TilePage,
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@ekanos/harness",
3
- "version": "0.4.3",
3
+ "version": "0.5.1",
4
4
  "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Ekanos chrome, from fixtures, with no Supabase or auth; and, in live mode, a real localhost OAuth loop over your own dev-app credentials.",
5
+ "homepage": "https://sdk.ekanos.dev/harness/overview",
5
6
  "bugs": {
6
7
  "email": "npm@govastly.com"
7
8
  },
@@ -63,8 +64,8 @@
63
64
  "tw-animate-css": "1.4.0"
64
65
  },
65
66
  "devDependencies": {
66
- "@ekanos/sdk": "0.6.0",
67
- "@ekanos/ui": "0.6.0",
67
+ "@ekanos/sdk": "0.7.1",
68
+ "@ekanos/ui": "0.7.1",
68
69
  "@kit/tsconfig": "0.1.0",
69
70
  "@tailwindcss/postcss": "4.3.3",
70
71
  "@tanstack/react-query": "5.103.2",
@@ -83,8 +84,8 @@
83
84
  "zod": "4.6.5"
84
85
  },
85
86
  "peerDependencies": {
86
- "@ekanos/sdk": "^0.4.0 || ^0.5.0 || ^0.6.0",
87
- "@ekanos/ui": "^0.4.0 || ^0.5.0 || ^0.6.0",
87
+ "@ekanos/sdk": "^0.7.0",
88
+ "@ekanos/ui": "^0.4.0 || ^0.5.0 || ^0.6.0 || ^0.7.0",
88
89
  "@tanstack/react-query": "^5.101.4",
89
90
  "next": "^16.0.0",
90
91
  "next-intl": "^4.14.7",
@@ -94,7 +95,7 @@
94
95
  "tailwindcss": "^4.0.0"
95
96
  },
96
97
  "ekanos": {
97
- "shellContract": 2
98
+ "shellContract": 3
98
99
  },
99
100
  "scripts": {
100
101
  "build": "tsup && tsc -p tsconfig.build.json && node scripts/rewrite-esm-specifiers.mjs && node scripts/build-css.mjs",
@@ -1,23 +0,0 @@
1
- import { WidgetConfig } from '@ekanos/sdk';
2
- export type RowGroup = {
3
- type: 'full';
4
- widget: WidgetConfig;
5
- } | {
6
- type: 'half';
7
- widgets: WidgetConfig[];
8
- };
9
- /**
10
- * Build row groups that preserve widget order. Contiguous runs of half-width
11
- * widgets are grouped together; full-width widgets each get their own row.
12
- */
13
- export declare function buildRowGroups(widgets: WidgetConfig[]): RowGroup[];
14
- export declare function getColSpan(widget: WidgetConfig): 1 | 2;
15
- /**
16
- * Splits a run of half-width widgets into two balanced columns, alternating
17
- * into whichever column is currently shorter (left wins ties) — preserves
18
- * the exact alternation `MasonryGrid` rendered inline before extraction.
19
- */
20
- export declare function splitBalanced(widgets: WidgetConfig[]): {
21
- left: WidgetConfig[];
22
- right: WidgetConfig[];
23
- };
@@ -1,37 +0,0 @@
1
- function buildRowGroups(widgets) {
2
- const groups = [];
3
- let halfBatch = [];
4
- for (const widget of widgets) {
5
- if (getColSpan(widget) === 2) {
6
- if (halfBatch.length > 0) {
7
- groups.push({ type: "half", widgets: halfBatch });
8
- halfBatch = [];
9
- }
10
- groups.push({ type: "full", widget });
11
- } else {
12
- halfBatch.push(widget);
13
- }
14
- }
15
- if (halfBatch.length > 0) {
16
- groups.push({ type: "half", widgets: halfBatch });
17
- }
18
- return groups;
19
- }
20
- function getColSpan(widget) {
21
- const w = widget.layouts?.lg?.w ?? 6;
22
- return w > 6 ? 2 : 1;
23
- }
24
- function splitBalanced(widgets) {
25
- const left = [];
26
- const right = [];
27
- for (const w of widgets) {
28
- if (left.length <= right.length) left.push(w);
29
- else right.push(w);
30
- }
31
- return { left, right };
32
- }
33
- export {
34
- buildRowGroups,
35
- getColSpan,
36
- splitBalanced
37
- };