@cadraos/sdk 0.3.14-p46.3 → 0.3.14

package/dist/board-host/index.d.ts

@@ -319,6 +319,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -381,6 +386,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Who performed a transition / stage-run (server-engine side).
@@ -498,6 +515,23 @@ interface ApplyTransitionInput {
     contextPatch?: Record<string, unknown>;
     /** Execution UUID to stamp on the card (handler advances). */
     executionUuid?: string;
+    /**
+     * p46 (P46-002, F8): set ONLY by `engine.hostMove` (a move the external host
+     * made — e.g. a Jira drag mirrored by the sync). A host-aware adapter, inside
+     * the same card lock as the `fromLane` CAS, (1) refuses the move with a
+     * `HostFenceError` while the card has any `host.*` op `pending` (D19 — never
+     * mistake our own half-done move for a human one), (2) writes `externalMeta`,
+     * then (3) moves. Adapters that don't know it ignore it (optional, additive).
+     */
+    hostObservation?: {
+        externalMeta?: Record<string, unknown>;
+        /**
+         * ISO time the host state was READ. The fence also refuses the move when a
+         * `host.*` op for the card settled (done/failed) after this instant — the
+         * read may predate our own write landing in the host.
+         */
+        observedAt?: string;
+    };
 }
 
 /**
@@ -682,6 +716,16 @@ interface KanbanStorageAdapter {
      * config and passes it as `initialLane`.
      */
     createCard(input: CreateCardServerInput): Promise<KanbanCard>;
+    /**
+     * p46 (P46-002) OPTIONAL: the card with this `externalRef` on this board, or
+     * null. When present, `engine.createCard({externalRef})` looks it up first and
+     * returns an existing card WITHOUT dispatching (exactly-once create per issue
+     * key). A host that stores `externalRef` SHOULD also make `createCard` itself
+     * idempotent on `(boardConfigUuid, externalRef)` (unique index + `ON CONFLICT
+     * DO NOTHING` → return the existing row) for the lookup/insert race. Hosts
+     * without external refs (crm/yobo) omit it.
+     */
+    getCardByExternalRef?(boardConfigUuid: string, externalRef: string): Promise<KanbanCard | null>;
     /**
      * Patch a card's mutable fields.
      */
@@ -1368,6 +1412,57 @@ interface BoardHostMappingProps {
 }
 declare function BoardHostMapping({ boardConfigUuid, adapter: adapterProp, onSaved, onError, }: BoardHostMappingProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * `<LaneMapStep/>` — the lane-map rows (board stage → host state), extracted
+ * from `<BoardHostMapping/>` ② (P46-002-1) so a hosted host (the Jira link
+ * page) reuses the same step.
+ *
+ * - WITHOUT `hostStates`: today's free-text host-state input per lane — the
+ *   crm/yobo `<BoardHostMapping/>` path, DOM unchanged.
+ * - WITH `hostStates` (e.g. a Jira board's column statuses): a `<select>` per
+ *   lane plus an "Also accepts" multi-select (D17: inbound, any of
+ *   `[hostState, ...alsoFrom]` maps to the lane; outbound writes `hostState`).
+ *
+ * Controlled: `value` in, the whole next map out via `onChange`. Zero runtime
+ * deps; plain inline styles.
+ *
+ * @module @cadraos/sdk/board-host
+ */
+
+/** One lane's host-state binding (`LaneBinding` minus the stage identity). */
+interface LaneMapEntry {
+    /** The host state a move INTO this lane writes (and reads). */
+    hostState: string;
+    /** Extra host states that also map INTO this lane (inbound only, D17). */
+    alsoFrom?: string[];
+}
+/** Lane map keyed by stage `key`. */
+type LaneMapValue = Record<string, LaneMapEntry>;
+/** A host state the host offers (e.g. a Jira status: id + display name). */
+interface HostStateOption {
+    value: string;
+    label: string;
+}
+interface LaneMapStepProps {
+    /** Board lanes, in order. */
+    lanes: KanbanLane[];
+    /** Current map (keyed by stage key). */
+    value: LaneMapValue;
+    /** Receives the WHOLE next map. */
+    onChange: (next: LaneMapValue) => void;
+    /** Offered host states → `<select>` mode; absent → free-text mode. */
+    hostStates?: HostStateOption[];
+    /**
+     * Optional per-lane "create if missing" checkbox (the p34 crm/yobo mapping).
+     * Absent → no checkbox.
+     */
+    createIfMissing?: {
+        value: Record<string, boolean>;
+        onChange: (stageKey: string, checked: boolean) => void;
+    };
+}
+declare function LaneMapStep({ lanes, value, onChange, hostStates, createIfMissing, }: LaneMapStepProps): React.ReactElement;
+
 interface BoardHostMappingProviderProps {
     /**
      * The session-authed adapter the host injects (wraps the §6b endpoints with
@@ -1450,4 +1545,4 @@ interface DueRef {
  */
 declare function collectDueRefs(lanes: KanbanLane[]): DueRef[];
 
-export { type BoardHostDelegate, BoardHostMapping, type BoardHostMappingAdapter, type BoardHostMapping$1 as BoardHostMappingData, type BoardHostMappingProps, BoardHostMappingProvider, type BoardHostMappingProviderProps, type BoardQueryRunner, type DueRef, type FieldBinding, type LaneBinding, type MappingValidationStatus, type ScopeBinding, WIDGET_IDENTIFIER_PATTERN, collectDueRefs, identifierError, isValidIdentifier, isValidJsonPath, useBoardHostMappingAdapter, useBoardHostMappingAdapterOptional };
+export { type BoardHostDelegate, BoardHostMapping, type BoardHostMappingAdapter, type BoardHostMapping$1 as BoardHostMappingData, type BoardHostMappingProps, BoardHostMappingProvider, type BoardHostMappingProviderProps, type BoardQueryRunner, type DueRef, type FieldBinding, type HostStateOption, type LaneBinding, type LaneMapEntry, LaneMapStep, type LaneMapStepProps, type LaneMapValue, type MappingValidationStatus, type ScopeBinding, WIDGET_IDENTIFIER_PATTERN, collectDueRefs, identifierError, isValidIdentifier, isValidJsonPath, useBoardHostMappingAdapter, useBoardHostMappingAdapterOptional };

package/dist/board-host/index.js

@@ -1,5 +1,5 @@
 import { createContext, useMemo, useContext, useState, useCallback, useEffect } from 'react';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 
 var BoardHostMappingContext = createContext(null);
 function BoardHostMappingProvider({
@@ -71,86 +71,8 @@ function collectDueRefs(lanes) {
   }
   return Array.from(byRef.values());
 }
-var DEFAULT_ORG_COLUMN = "org_id";
-function laneStageId(lane) {
-  return lane.id ?? lane.key;
-}
-function suggestHostState(lane) {
-  return lane.label ?? lane.key ?? "";
-}
-function freshFieldRow(ref, requiresPredicate) {
-  return {
-    ref,
-    kind: requiresPredicate ? "predicate" : "column",
-    column: "",
-    path: "",
-    via: "",
-    table: "",
-    name: "",
-    predicateOnly: requiresPredicate
-  };
-}
-function fieldRowFromBinding(b, requiresPredicate) {
-  const base = freshFieldRow(b.ref, requiresPredicate);
-  switch (b.kind) {
-    case "column":
-      return { ...base, kind: "column", column: b.column };
-    case "json":
-      return { ...base, kind: "json", column: b.column, path: b.path };
-    case "fk":
-      return { ...base, kind: "fk", via: b.via, table: b.table, column: b.column };
-    case "predicate":
-      return { ...base, kind: "predicate", name: b.name };
-    default:
-      return base;
-  }
-}
-function fieldRowError(row) {
-  switch (row.kind) {
-    case "column":
-      return identifierError(row.column) && `column ${identifierError(row.column)}`;
-    case "json": {
-      const colErr = identifierError(row.column);
-      if (colErr) return `column ${colErr}`;
-      if (!isValidJsonPath(row.path))
-        return "path must be dot-separated identifiers";
-      return null;
-    }
-    case "fk": {
-      const viaErr = identifierError(row.via);
-      if (viaErr) return `via ${viaErr}`;
-      const tableErr = identifierError(row.table);
-      if (tableErr) return `table ${tableErr}`;
-      const colErr = identifierError(row.column);
-      if (colErr) return `column ${colErr}`;
-      return null;
-    }
-    case "predicate":
-      return row.name.length === 0 ? "pick a predicate" : !isValidIdentifier(row.name) ? "predicate name must be a single identifier" : null;
-    default:
-      return "unknown kind";
-  }
-}
-function rowToBinding(row) {
-  switch (row.kind) {
-    case "column":
-      return { ref: row.ref, kind: "column", column: row.column };
-    case "json":
-      return { ref: row.ref, kind: "json", column: row.column, path: row.path };
-    case "fk":
-      return {
-        ref: row.ref,
-        kind: "fk",
-        via: row.via,
-        table: row.table,
-        column: row.column
-      };
-    case "predicate":
-      return { ref: row.ref, kind: "predicate", name: row.name };
-    default:
-      return { ref: row.ref, kind: "column", column: "" };
-  }
-}
+
+// src/board-host/widget/styles.ts
 var S = {
   card: {
     background: "#fff",
@@ -232,6 +154,200 @@ var S = {
     borderRadius: 999
   }
 };
+function laneStageId(lane) {
+  return lane.id ?? lane.key;
+}
+function withStale(offered, extra) {
+  const known = new Set(offered.map((o) => o.value));
+  const stale = extra.filter((v) => v && !known.has(v)).map((v) => ({ value: v, label: `${v} (not on the board)` }));
+  return [...offered, ...stale];
+}
+function LaneMapStep({
+  lanes,
+  value,
+  onChange,
+  hostStates,
+  createIfMissing
+}) {
+  function setEntry(key, entry) {
+    onChange({ ...value, [key]: entry });
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: lanes.map((lane) => {
+    const entry = value[lane.key];
+    const hostState = entry?.hostState ?? "";
+    const alsoFrom = entry?.alsoFrom ?? [];
+    const mapped = hostState.trim().length > 0;
+    return /* @__PURE__ */ jsxs("div", { style: S.lane, children: [
+      /* @__PURE__ */ jsxs("span", { children: [
+        lane.label,
+        /* @__PURE__ */ jsx("small", { style: { display: "block", color: "#98a1ad", fontSize: 11 }, children: laneStageId(lane) })
+      ] }),
+      /* @__PURE__ */ jsx("span", { style: { color: "#98a1ad", textAlign: "center" }, children: "\u2192" }),
+      hostStates ? /* @__PURE__ */ jsxs(
+        "select",
+        {
+          "aria-label": `Host state for ${lane.label}`,
+          value: hostState,
+          onChange: (e) => {
+            const next = e.target.value;
+            setEntry(lane.key, {
+              hostState: next,
+              alsoFrom: alsoFrom.filter((s) => s !== next)
+            });
+          },
+          style: { ...S.input, minWidth: 0, width: "100%" },
+          children: [
+            /* @__PURE__ */ jsx("option", { value: "", children: "\u2014 host state \u2014" }),
+            withStale(hostStates, [hostState]).map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label }, o.value))
+          ]
+        }
+      ) : /* @__PURE__ */ jsx(
+        "input",
+        {
+          "aria-label": `Host state for ${lane.label}`,
+          value: hostState,
+          placeholder: "\u2014 host state \u2014",
+          onChange: (e) => {
+            setEntry(lane.key, { ...entry, hostState: e.target.value });
+          },
+          style: { ...S.input, minWidth: 0, width: "100%" }
+        }
+      ),
+      createIfMissing ? /* @__PURE__ */ jsxs(
+        "label",
+        {
+          style: { display: "flex", alignItems: "center", gap: 6, fontSize: 11.5, color: "#6b7480" },
+          children: [
+            /* @__PURE__ */ jsx(
+              "input",
+              {
+                type: "checkbox",
+                "aria-label": `Create lane ${lane.label} if missing`,
+                checked: createIfMissing.value[lane.key] ?? false,
+                onChange: (e) => createIfMissing.onChange(lane.key, e.target.checked)
+              }
+            ),
+            "create"
+          ]
+        }
+      ) : /* @__PURE__ */ jsx("span", {}),
+      hostStates && /* @__PURE__ */ jsxs(
+        "label",
+        {
+          style: {
+            gridColumn: "1 / -1",
+            display: "flex",
+            alignItems: "flex-start",
+            gap: 8,
+            fontSize: 11.5,
+            color: "#6b7480"
+          },
+          children: [
+            "Also accepts",
+            /* @__PURE__ */ jsx(
+              "select",
+              {
+                multiple: true,
+                "aria-label": `Also accepts for ${lane.label}`,
+                value: alsoFrom,
+                onChange: (e) => {
+                  const picked = Array.from(e.target.options).filter((o) => o.selected).map((o) => o.value);
+                  setEntry(lane.key, { hostState, alsoFrom: picked });
+                },
+                style: { ...S.input, minWidth: 0, flex: 1 },
+                children: withStale(hostStates, alsoFrom).filter((o) => o.value !== hostState).map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label }, o.value))
+              }
+            )
+          ]
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "span",
+        {
+          style: { ...S.st, color: mapped ? "#16a34a" : "#c2710c", gridColumn: "1 / -1", marginTop: 2 },
+          children: mapped ? "\u2713 mapped" : "\u26A0 gap \u2014 unmapped lane"
+        }
+      )
+    ] }, lane.key);
+  }) });
+}
+var DEFAULT_ORG_COLUMN = "org_id";
+function suggestHostState(lane) {
+  return lane.label ?? lane.key ?? "";
+}
+function freshFieldRow(ref, requiresPredicate) {
+  return {
+    ref,
+    kind: requiresPredicate ? "predicate" : "column",
+    column: "",
+    path: "",
+    via: "",
+    table: "",
+    name: "",
+    predicateOnly: requiresPredicate
+  };
+}
+function fieldRowFromBinding(b, requiresPredicate) {
+  const base = freshFieldRow(b.ref, requiresPredicate);
+  switch (b.kind) {
+    case "column":
+      return { ...base, kind: "column", column: b.column };
+    case "json":
+      return { ...base, kind: "json", column: b.column, path: b.path };
+    case "fk":
+      return { ...base, kind: "fk", via: b.via, table: b.table, column: b.column };
+    case "predicate":
+      return { ...base, kind: "predicate", name: b.name };
+    default:
+      return base;
+  }
+}
+function fieldRowError(row) {
+  switch (row.kind) {
+    case "column":
+      return identifierError(row.column) && `column ${identifierError(row.column)}`;
+    case "json": {
+      const colErr = identifierError(row.column);
+      if (colErr) return `column ${colErr}`;
+      if (!isValidJsonPath(row.path))
+        return "path must be dot-separated identifiers";
+      return null;
+    }
+    case "fk": {
+      const viaErr = identifierError(row.via);
+      if (viaErr) return `via ${viaErr}`;
+      const tableErr = identifierError(row.table);
+      if (tableErr) return `table ${tableErr}`;
+      const colErr = identifierError(row.column);
+      if (colErr) return `column ${colErr}`;
+      return null;
+    }
+    case "predicate":
+      return row.name.length === 0 ? "pick a predicate" : !isValidIdentifier(row.name) ? "predicate name must be a single identifier" : null;
+    default:
+      return "unknown kind";
+  }
+}
+function rowToBinding(row) {
+  switch (row.kind) {
+    case "column":
+      return { ref: row.ref, kind: "column", column: row.column };
+    case "json":
+      return { ref: row.ref, kind: "json", column: row.column, path: row.path };
+    case "fk":
+      return {
+        ref: row.ref,
+        kind: "fk",
+        via: row.via,
+        table: row.table,
+        column: row.column
+      };
+    case "predicate":
+      return { ref: row.ref, kind: "predicate", name: row.name };
+    default:
+      return { ref: row.ref, kind: "column", column: "" };
+  }
+}
 function statusColors(status) {
   switch (status) {
     case "valid":
@@ -590,57 +706,28 @@ function BoardHostMapping({
           /* @__PURE__ */ jsx("span", { style: S.ttl, children: "Lane map" }),
           /* @__PURE__ */ jsx("span", { style: { marginLeft: "auto", fontSize: 11, color: "#98a1ad" }, children: "auto-matched by name" })
         ] }),
-        lanes.map((lane) => {
-          const mapped = (laneStates[lane.key] ?? "").trim().length > 0;
-          return /* @__PURE__ */ jsxs("div", { style: S.lane, children: [
-            /* @__PURE__ */ jsxs("span", { children: [
-              lane.label,
-              /* @__PURE__ */ jsx("small", { style: { display: "block", color: "#98a1ad", fontSize: 11 }, children: laneStageId(lane) })
-            ] }),
-            /* @__PURE__ */ jsx("span", { style: { color: "#98a1ad", textAlign: "center" }, children: "\u2192" }),
-            /* @__PURE__ */ jsx(
-              "input",
-              {
-                "aria-label": `Host state for ${lane.label}`,
-                value: laneStates[lane.key] ?? "",
-                placeholder: "\u2014 host state \u2014",
-                onChange: (e) => {
-                  setLaneStates((s) => ({ ...s, [lane.key]: e.target.value }));
-                  setValidation(null);
-                },
-                style: { ...S.input, minWidth: 0, width: "100%" }
-              }
-            ),
-            /* @__PURE__ */ jsxs(
-              "label",
-              {
-                style: { display: "flex", alignItems: "center", gap: 6, fontSize: 11.5, color: "#6b7480" },
-                children: [
-                  /* @__PURE__ */ jsx(
-                    "input",
-                    {
-                      type: "checkbox",
-                      "aria-label": `Create lane ${lane.label} if missing`,
-                      checked: laneCreate[lane.key] ?? false,
-                      onChange: (e) => {
-                        setLaneCreate((c) => ({ ...c, [lane.key]: e.target.checked }));
-                        setValidation(null);
-                      }
-                    }
-                  ),
-                  "create"
-                ]
-              }
+        /* @__PURE__ */ jsx(
+          LaneMapStep,
+          {
+            lanes,
+            value: Object.fromEntries(
+              Object.entries(laneStates).map(([k, hostState]) => [k, { hostState }])
             ),
-            /* @__PURE__ */ jsx(
-              "span",
-              {
-                style: { ...S.st, color: mapped ? "#16a34a" : "#c2710c", gridColumn: "1 / -1", marginTop: 2 },
-                children: mapped ? "\u2713 mapped" : "\u26A0 gap \u2014 unmapped lane"
+            onChange: (next) => {
+              setLaneStates(
+                Object.fromEntries(Object.entries(next).map(([k, e]) => [k, e.hostState]))
+              );
+              setValidation(null);
+            },
+            createIfMissing: {
+              value: laneCreate,
+              onChange: (key, checked) => {
+                setLaneCreate((c) => ({ ...c, [key]: checked }));
+                setValidation(null);
               }
-            )
-          ] }, lane.key);
-        })
+            }
+          }
+        )
       ] }),
       /* @__PURE__ */ jsxs("section", { style: S.sec, "aria-label": "Field map", children: [
         /* @__PURE__ */ jsxs("div", { style: S.lbl, children: [
@@ -815,6 +902,6 @@ function BoardHostMapping({
   ] });
 }
 
-export { BoardHostMapping, BoardHostMappingProvider, WIDGET_IDENTIFIER_PATTERN, collectDueRefs, identifierError, isValidIdentifier, isValidJsonPath, useBoardHostMappingAdapter, useBoardHostMappingAdapterOptional };
+export { BoardHostMapping, BoardHostMappingProvider, LaneMapStep, WIDGET_IDENTIFIER_PATTERN, collectDueRefs, identifierError, isValidIdentifier, isValidJsonPath, useBoardHostMappingAdapter, useBoardHostMappingAdapterOptional };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map