@manta-eu/horns-kit 0.1.3 → 0.2.0

package/dist/embed/horn-snapshot-view.d.ts

@@ -2,6 +2,7 @@ import { type ReactNode } from "react";
 import { type HornSnapshot, type SnapshotView } from "@manta-eu/horns/render";
 import { type ChartTheme, type EntityLink } from "../look/index.ts";
 import type { PlanActions } from "./plan-strip.tsx";
+import { type PlanStripArgs } from "./plan-placement.tsx";
 import { type ExplainedFact } from "./view-powers.tsx";
 export type HornViewMode = "page" | "embed" | "capture";
 /**
@@ -58,6 +59,8 @@ export type HornSnapshotViewProps = {
     catalogCard?: (content: Extract<SnapshotView["content"], {
         lane: "component";
     }>, view: SnapshotView, context: WrittenViewContext) => ReactNode;
+    /** Draws a plan's changes and its buttons. Same bargain again; without it the kit's own strip draws. */
+    planStrip?: (args: PlanStripArgs) => ReactNode;
 };
 /**
  * Where each of a snapshot's IRIs opens, ready to hand a view.

package/dist/embed/horn-snapshot-view.js

@@ -69,7 +69,7 @@ function WrittenSlot({ placeholder, draw }) {
 }
 function ViewCard(props) {
     const { view, theme, chrome, hornStyle, labels, links, plans, planActions, controls, writtenView } = props;
-    const { catalogCard, datastoreId, style } = props;
+    const { catalogCard, datastoreId, planStrip, style } = props;
     const context = { labels, links, datastoreId };
     const colors = surfaces[theme];
     const { content } = view;
@@ -88,6 +88,7 @@ function ViewCard(props) {
                     links,
                     palette: chartPalette(theme, hornStyle),
                     ...(planActions ? { actions: planActions } : {}),
+                    ...(planStrip ? { strip: planStrip } : {}),
                     shown: Object.fromEntries((content.plans ?? []).map((behind) => [behind.plan, behind.entities])),
                 }, children: _jsx(WrittenSlot, { placeholder: _jsx("p", { style: { margin: 0, color: colors.muted, fontSize: 14 }, children: "This view is written code, which draws in the browser rather than here." }), draw: () => writtenView?.(content, view, context) }) })) : (_jsx("p", { role: "alert", style: { margin: 0, color: colors.error, fontSize: 14 }, children: content.message }))] }));
 }
@@ -100,6 +101,7 @@ export function hornSurface(snapshot, theme) {
 }
 export function HornSnapshotView(props) {
     const { snapshot, mode = "page", theme = "light", planActions, viewControls, writtenView, catalogCard } = props;
+    const { planStrip } = props;
     const { explain, onVariableChange } = props;
     const style = snapshot.style;
     const surface = hornSurface(snapshot, theme);
@@ -110,10 +112,10 @@ export function HornSnapshotView(props) {
         return (_jsx("main", { style: { width: captureWidth, background: colors.card, color: colors.ink, fontFamily: font }, children: snapshot.views.map((view) => (_jsx(ViewCard, { view: view, theme: surface, chrome: chrome, hornStyle: style, labels: snapshot.labels, links: links, datastoreId: snapshot.horn.datastoreId, plans: snapshot.plans, 
                 // A capture on a server has no browser to draw written source in and passes neither of these, so
                 // it still gets the placeholder. A capture taken *by* a browser passes them and gets the view.
-                writtenView: writtenView, catalogCard: catalogCard }, view.id))) }));
+                writtenView: writtenView, catalogCard: catalogCard, planStrip: planStrip }, view.id))) }));
     }
     if (mode === "embed") {
-        return (_jsx("div", { style: { display: "grid", gap: chrome.gap, fontFamily: font, color: colors.ink }, children: snapshot.views.map((view) => (_jsx(ViewCard, { view: view, theme: surface, chrome: chrome, hornStyle: style, labels: snapshot.labels, links: links, datastoreId: snapshot.horn.datastoreId, plans: snapshot.plans, planActions: planActions, writtenView: writtenView, catalogCard: catalogCard, style: { borderRadius: chrome.radius, border: `1px solid ${colors.border}` } }, view.id))) }));
+        return (_jsx("div", { style: { display: "grid", gap: chrome.gap, fontFamily: font, color: colors.ink }, children: snapshot.views.map((view) => (_jsx(ViewCard, { view: view, theme: surface, chrome: chrome, hornStyle: style, labels: snapshot.labels, links: links, datastoreId: snapshot.horn.datastoreId, plans: snapshot.plans, planActions: planActions, writtenView: writtenView, catalogCard: catalogCard, planStrip: planStrip, style: { borderRadius: chrome.radius, border: `1px solid ${colors.border}` } }, view.id))) }));
     }
     const byId = new Map(snapshot.views.map((view) => [view.id, view]));
     const order = new Map(snapshot.views.map((view, index) => [view.id, index]));
@@ -151,7 +153,7 @@ export function HornSnapshotView(props) {
                                     minWidth: `min(100%, ${Math.max(minCard, (span / gridColumns) * minPageWidth)}px)`,
                                     minHeight: rows * rowHeight + (rows - 1) * chrome.gap,
                                     boxSizing: "border-box",
-                                }, children: _jsx(ViewCard, { view: view, theme: surface, chrome: chrome, hornStyle: style, labels: snapshot.labels, links: links, datastoreId: snapshot.horn.datastoreId, plans: snapshot.plans, planActions: planActions, writtenView: writtenView, catalogCard: catalogCard, ...(viewControls ? { controls: viewControls(view) } : {}), style: {
+                                }, children: _jsx(ViewCard, { view: view, theme: surface, chrome: chrome, hornStyle: style, labels: snapshot.labels, links: links, datastoreId: snapshot.horn.datastoreId, plans: snapshot.plans, planActions: planActions, writtenView: writtenView, catalogCard: catalogCard, planStrip: planStrip, ...(viewControls ? { controls: viewControls(view) } : {}), style: {
                                         flex: "1 1 auto",
                                         minWidth: 0,
                                         borderRadius: chrome.radius,

package/dist/embed/plan-placement.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import type { PlanStatus, SnapshotPlan } from "@manta-eu/horns/render";
 import type { ChartPalette } from "../look/palette.ts";
 import type { EntityLink } from "../look/types.ts";
@@ -11,6 +12,21 @@ export type PlanPlacement = {
     actions?: PlanActions | undefined;
     /** The things each plan changes that this view draws, by plan IRI. */
     shown?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Draws the plan. Same bargain as `writtenView`: the kit knows nothing of `@manta-eu/react`, so a host
+     * that wants its own buttons and badges supplies this. Without it the kit's own strip draws, which is what
+     * a server render and a capture without a host always see.
+     */
+    strip?: (args: PlanStripArgs) => ReactNode;
+};
+/** What a host needs to draw one plan, already resolved against the snapshot. */
+export type PlanStripArgs = {
+    plan: SnapshotPlan;
+    /** The things the plan changes that this view draws, first in the list. */
+    onView: readonly string[];
+    labels: Readonly<Record<string, string>>;
+    links: Readonly<Record<string, EntityLink>>;
+    actions?: PlanActions | undefined;
 };
 export declare const PlanPlacementProvider: import("react").Provider<PlanPlacement | undefined>;
 export type SuggestedChangesProps = {
@@ -23,7 +39,7 @@ export type SuggestedChangesProps = {
  * Says so plainly when there is nothing to draw rather than rendering an empty box: a view naming a plan the
  * Horn does not hold is a mistake worth seeing while somebody is reading the code.
  */
-export declare function SuggestedChanges({ plan }: SuggestedChangesProps): import("react").JSX.Element | null;
+export declare function SuggestedChanges({ plan }: SuggestedChangesProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 /** The plans behind the view being drawn, so a view can name them without being handed callbacks. */
 export declare function usePlansBehindView(): readonly SnapshotPlan[];
 export type { PlanStatus };

package/dist/embed/plan-placement.js

@@ -16,7 +16,17 @@ export function SuggestedChanges({ plan }) {
     const found = placement.plans.find((one) => one.iri === plan);
     if (found === undefined)
         return null;
-    return (_jsx(PlanStrip, { plan: found, onView: placement.shown?.[plan] ?? [], labels: placement.labels, links: placement.links, palette: placement.palette, actions: placement.actions }));
+    const onView = placement.shown?.[plan] ?? [];
+    if (placement.strip !== undefined) {
+        return placement.strip({
+            plan: found,
+            onView,
+            labels: placement.labels,
+            links: placement.links,
+            actions: placement.actions,
+        });
+    }
+    return (_jsx(PlanStrip, { plan: found, onView: onView, labels: placement.labels, links: placement.links, palette: placement.palette, actions: placement.actions }));
 }
 /** The plans behind the view being drawn, so a view can name them without being handed callbacks. */
 export function usePlansBehindView() {

package/dist/embed/plan-strip.d.ts

@@ -22,6 +22,13 @@ export type PlanActions = {
 export declare function planTitle(plan: SnapshotPlan, labels: Readonly<Record<string, string>>): string;
 /** "Changes 1 campaign and 3 campaign budgets." */
 export declare function planSummary(plan: SnapshotPlan, labels: Readonly<Record<string, string>>): string;
+/**
+ * Said when the plan touches more things than it has readable changes for.
+ *
+ * `kinds` counts what the plan concerns; `changes` holds the ones whose before and after could both be read.
+ * "Changes 3 campaigns" over one listed row reads as a bug unless the gap is named.
+ */
+export declare function unreadableChanges(plan: SnapshotPlan): number;
 export declare function planValue(value: PlanChange["from"], change: PlanChange, labels: Readonly<Record<string, string>>): string;
 /**
  * How the plan's last run went, in words. A run from before this page was opened says when it was, because a

package/dist/embed/plan-strip.js

@@ -47,6 +47,16 @@ export function planSummary(plan, labels) {
     }
     return `Changes ${listed(typed.map((kind) => `${kind.count} ${plural(labels[kind.type ?? ""] ?? "", kind.count)}`))}.`;
 }
+/**
+ * Said when the plan touches more things than it has readable changes for.
+ *
+ * `kinds` counts what the plan concerns; `changes` holds the ones whose before and after could both be read.
+ * "Changes 3 campaigns" over one listed row reads as a bug unless the gap is named.
+ */
+export function unreadableChanges(plan) {
+    const things = plan.kinds.reduce((total, kind) => total + kind.count, 0);
+    return Math.max(0, things - new Set(plan.changes.map((change) => change.entity)).size);
+}
 // Platforms name states in capitals: "PAUSED" reads "Paused".
 function spoken(text) {
     if (!/^[A-Z][A-Z0-9_]*$/.test(text))
@@ -68,22 +78,28 @@ export function planValue(value, change, labels) {
  * preview from last week says little about the plan as it stands now.
  */
 export function planStateText(status, earlier = false) {
-    const said = planStateWords(status);
+    const said = planStateWords(status, earlier);
     const day = status.lastRun?.startedAt.slice(0, 10);
     return earlier && status.state !== "draft" && day !== undefined && day !== ""
-        ? { ...said, text: `${said.text} (${day})` }
+        ? { ...said, text: `${said.text} ${day}` }
         : said;
 }
-function planStateWords(status) {
+function planStateWords(status, earlier) {
     const preview = status.lastRun?.preview === true;
     return match(status.state)
-        .with("draft", () => ({ text: "Not run yet", tone: "quiet" }))
-        .with("running", () => ({ text: preview ? "Validating…" : "Making the changes…", tone: "busy" }))
-        .with("completed", () => preview
-        ? { text: "Validated — nothing was changed", tone: "good" }
+        .with("draft", () => ({ text: "Not checked yet", tone: "quiet" }))
+        .with("running", () => ({ text: preview ? "Checking…" : "Making the changes…", tone: "busy" }))
+        .with("completed", () => 
+    // A check from before this page was opened does not make the plan runnable, so it must not say it is:
+    // the run button stays disabled, and "ready to make" beside a disabled button reads as a bug.
+    preview
+        ? {
+            text: earlier ? "Checked" : "Checked, ready to make",
+            tone: earlier ? "quiet" : "good",
+        }
         : { text: "Changes made", tone: "good" })
         .with("failed", () => ({
-        text: preview ? "Validation found a problem" : "The changes did not go through",
+        text: preview ? "Checking found a problem" : "The changes did not go through",
         tone: "bad",
     }))
         .with("timed-out", () => ({ text: "It took too long and stopped", tone: "bad" }))
@@ -107,6 +123,7 @@ export function PlanStrip(props) {
     const changes = [...plan.changes].sort((a, b) => Number(near.has(b.entity)) - Number(near.has(a.entity)));
     const shown = changes.slice(0, maxShownChanges);
     const hidden = plan.changes.length - shown.length;
+    const unreadable = unreadableChanges(plan);
     const toneColor = {
         quiet: palette.muted,
         busy: palette.secondary,
@@ -142,5 +159,5 @@ export function PlanStrip(props) {
                     const name = nameOf(change.entity);
                     const why = reasonsFor(change.entity);
                     return (_jsxs("li", { "data-plan-change": true, children: [link === undefined ? (_jsx("span", { style: { fontWeight: 600 }, children: name })) : (_jsx("a", { href: link.href, target: "_blank", rel: "noopener noreferrer", title: link.label, style: { fontWeight: 600, color: "inherit", textUnderlineOffset: 3 }, children: name })), _jsxs("span", { style: { color: palette.secondary }, children: [` — ${labels[change.property] ?? "A setting"}: `, _jsx("span", { style: { textDecoration: "line-through", textDecorationColor: palette.muted }, children: planValue(change.from, change, labels) }), " → "] }), _jsx("span", { style: { fontWeight: 600 }, children: planValue(change.to, change, labels) }), why.length > 0 ? (_jsx("div", { style: { color: palette.muted }, children: `Why: ${why.map((reason) => reason.text).join("; ")}` })) : null] }, index));
-                }) })) : (_jsx("p", { style: { margin: 0, color: palette.muted }, children: "Nothing here differs from how things are now." })), hidden > 0 ? (_jsx("p", { style: { margin: "6px 0 0", color: palette.muted }, children: `And ${hidden} more ${hidden === 1 ? "change" : "changes"}.` })) : null, actions === undefined ? null : (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 8, marginTop: 10 }, children: [button("Validate", () => actions.onPreview(plan), !busy, false, "Check the changes without making them"), button("Make these changes", () => actions.onRun(plan), !busy && runnable(live), true, runnable(live) ? "Changes them in the platforms they came from" : "Validate it first")] }))] }));
+                }) })) : (_jsx("p", { style: { margin: 0, color: palette.muted }, children: "Nothing here differs from how things are now." })), hidden > 0 ? (_jsx("p", { style: { margin: "6px 0 0", color: palette.muted }, children: `And ${hidden} more ${hidden === 1 ? "change" : "changes"}.` })) : null, unreadable > 0 ? (_jsx("p", { style: { margin: "6px 0 0", color: palette.muted }, children: `It also touches ${unreadable} more ${unreadable === 1 ? "thing" : "things"} whose before and after could not be read.` })) : null, actions === undefined ? null : (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 8, marginTop: 10 }, children: [button("Check it", () => actions.onPreview(plan), !busy, false, "Try the changes without making them"), button("Make these changes", () => actions.onRun(plan), !busy && runnable(live), true, runnable(live) ? "Changes them in the platforms they came from" : "Check it first")] }))] }));
 }

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { mantaReactCatalog } from "./catalog.ts";
 export * from "./look/index.ts";
 export { shapeViewSpecs } from "./shape-views/index.ts";
 export { entityLinks, HornSnapshotView, type HornSnapshotViewProps, type HornViewMode, type WrittenViewContext, } from "./embed/horn-snapshot-view.tsx";
-export { planStateText, planSummary, planTitle, runnable, type PlanActions } from "./embed/plan-strip.tsx";
+export { maxShownChanges, planStateText, planSummary, planTitle, planValue, runnable, unreadableChanges, type PlanActions, } from "./embed/plan-strip.tsx";
+export type { PlanStripArgs } from "./embed/plan-placement.tsx";
 export type { WrittenSurface } from "./written/runtime.ts";

package/dist/index.js

@@ -2,4 +2,4 @@ export { mantaReactCatalog } from "./catalog.js";
 export * from "./look/index.js";
 export { shapeViewSpecs } from "./shape-views/index.js";
 export { entityLinks, HornSnapshotView, } from "./embed/horn-snapshot-view.js";
-export { planStateText, planSummary, planTitle, runnable } from "./embed/plan-strip.js";
+export { maxShownChanges, planStateText, planSummary, planTitle, planValue, runnable, unreadableChanges, } from "./embed/plan-strip.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manta-eu/horns-kit",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Manta Horns component kit: charts and snapshot views that render on a server and hydrate in any React host, and the components the HornView sandbox runs.",
   "license": "MIT",
   "repository": {
@@ -55,7 +55,7 @@
   "dependencies": {
     "sucrase": "^3.35.1",
     "ts-pattern": "^5.9.0",
-    "@manta-eu/horns": "0.1.3"
+    "@manta-eu/horns": "0.2.0"
   },
   "peerDependencies": {
     "react": ">=18",