@ai-matrx/associations 0.10.7 → 0.11.1

package/dist/react/index.cjs

@@ -46,6 +46,7 @@ __export(react_exports, {
   UnresolvedRef: () => UnresolvedRef,
   attachedKey: () => attachedKey,
   buildCommentTree: () => buildCommentTree,
+  containerLinksArgs: () => containerLinksArgs,
   getContentRoleMeta: () => getContentRoleMeta,
   lazyPickerOverride: () => lazyPickerOverride,
   lazyWindowShell: () => lazyWindowShell,
@@ -1254,6 +1255,77 @@ var useEntityRelationships = useAssociations;
 
 // src/react/hooks/useContainerLinks.ts
 var import_react3 = require("react");
+
+// src/edges.ts
+var ASSOCIATION_TARGET_TYPES = [
+  "organization",
+  //         an org — the top-level container resources attach into
+  "scope",
+  "scope_type",
+  "project",
+  "task",
+  "context_item",
+  "thread",
+  "war_room",
+  "category",
+  "conversation",
+  //         a chat conversation a working_document is attached to
+  "fc_set",
+  //               a flashcard set (card→set membership)
+  "fc_card",
+  //              a flashcard (card→card hierarchy, quiz→card)
+  "study_media",
+  //          a study-media artifact (summary/mind_map) — converter lineage target
+  "assessment",
+  //           a quiz / practice test — a converter lineage target + origin (assessment→artifact 'source')
+  "note",
+  //                 a note — the origin a converted study artifact links back to (artifact→note 'source' lineage, P4)
+  "file",
+  //                 a file (card→file media + source lineage)
+  "quiz_session",
+  //         a quiz a card is used in
+  "agent",
+  //                an orchestrator agent — the container an Orchestra's member agents attach into (role 'member'); an 'orchestra' self-edge marks the orchestrator
+  "agent_term_list",
+  //      a term list — durable file attachments target its vocabulary resource
+  "research_tag",
+  //         a research tag a source is filed under (rs_source_tag M2M collapsed into associations)
+  "skill",
+  //                a skill — projects link to it (skill→project, role 'member'); code_files attach as resources (code_file→skill, role 'resource')
+  "surface",
+  //              a UI surface — agents bind here (agent→surface); context menu reads via agent.menu_surface
+  "plan_entity",
+  //          a Content Planning source/media citation — plan_node role edges (about/cites/embeds) target it
+  "plan_node",
+  //            a planned page — research topics/tags attach here and follow realization into web_page
+  "web_site",
+  //             a web.site — parties attach onto a site's roster (party→web_site role 'writes_for')
+  "seo_topic",
+  //            a taxonomy topic — plan_node/plan_entity tag into it (role 'topic')
+  "seo_keyword",
+  //          a keyword — plan_node attaches secondaries (role 'secondary_keyword'; the primary is an FK, never an edge)
+  "web_page",
+  //             a canonical page — the page workspace attaches notes/tasks/files/keywords onto it (keyword edges: role 'primary'|'supporting')
+  "web_screenshot",
+  //       a page capture — per-image attachments on the page workspace
+  "party",
+  //                a CRM person/company (crm.party) — the record page attaches tasks/files/notes onto it
+  "crm_outreach_list",
+  //    a CRM outreach list (a worked send/dial queue) — parties and resources attach into it
+  "crm_deal",
+  //             a CRM deal (crm.deal) — people on it (role 'deal_contact'), tasks/files attach onto it
+  "rulebook",
+  //             a Masterwork Rulebook — its Scout interviews attach here (conversation→rulebook, role 'interview')
+  "research_topic",
+  //       a research topic — Sources are filed under it (processed_document→research_topic, the landing door's edge)
+  "media_source_library"
+  // a media-catalog Library — Sources are catalogued into it (processed_document→media_source_library)
+];
+function isAssociationTargetType(value) {
+  return typeof value === "string" && ASSOCIATION_TARGET_TYPES.includes(value);
+}
+
+// src/react/hooks/useContainerLinks.ts
 function metadataRecord(metadata) {
   if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
     return metadata == null ? {} : null;
@@ -1262,6 +1334,7 @@ function metadataRecord(metadata) {
 }
 function useContainerLinks(args) {
   const { containerType, containerId, orgId } = args;
+  const outgoing = args.direction === "outgoing";
   const store = useAssociationsStore();
   const {
     edges,
@@ -1272,7 +1345,7 @@ function useContainerLinks(args) {
     type: containerType,
     id: containerId
   });
-  const conversationKey = containerType === "conversation" && containerId ? `conversation:${containerId}` : null;
+  const conversationKey = !outgoing && containerType === "conversation" && containerId ? `conversation:${containerId}` : null;
   const activeConversationKey = (0, import_react3.useRef)(conversationKey);
   const conversationGeneration = (0, import_react3.useRef)(0);
   const [conversationResult, setConversationResult] = (0, import_react3.useState)(null);
@@ -1328,9 +1401,9 @@ function useContainerLinks(args) {
   }, [loadConversationFiles]);
   const conversationFiles = conversationResult?.key === conversationKey ? conversationResult.files : [];
   const conversationFileError = conversationResult?.key === conversationKey ? conversationResult.error : null;
-  const conversationFileStatus = containerType !== "conversation" ? "idle" : conversationResult?.key !== conversationKey ? "loading" : conversationResult.loading ? "loading" : conversationFileError ? "error" : "ready";
+  const conversationFileStatus = outgoing || containerType !== "conversation" ? "idle" : conversationResult?.key !== conversationKey ? "loading" : conversationResult.loading ? "loading" : conversationFileError ? "error" : "ready";
   const incomingGeneric = edges.filter(
-    (edge) => edge.direction === "incoming" && !(containerType === "conversation" && edge.otherType === "file")
+    (edge) => outgoing ? edge.direction === "outgoing" : edge.direction === "incoming" && !(containerType === "conversation" && edge.otherType === "file")
   ).map((edge) => ({
     edgeId: edge.id,
     resourceId: edge.otherId,
@@ -1339,7 +1412,29 @@ function useContainerLinks(args) {
     label: edge.label ?? null,
     metadata: edge.metadata ?? {}
   }));
-  const incoming = containerType === "conversation" ? [...incomingGeneric, ...conversationFiles] : incomingGeneric;
+  const incoming = !outgoing && containerType === "conversation" ? [...incomingGeneric, ...conversationFiles] : incomingGeneric;
+  const endpoints = (token, resourceId) => {
+    if (!containerId) return { error: "Missing container id" };
+    if (outgoing) {
+      if (!isAssociationTargetType(token)) {
+        return {
+          error: `A ${token.replace(/_/g, " ")} cannot be filed under: it is not a container type.`
+        };
+      }
+      return {
+        sourceType: containerType,
+        sourceId: containerId,
+        targetType: token,
+        targetId: resourceId
+      };
+    }
+    return {
+      sourceType: token,
+      sourceId: resourceId,
+      targetType: containerType,
+      targetId: containerId
+    };
+  };
   const linksFor = (token) => incoming.filter((link) => link.token === token);
   const countFor = (token) => incoming.reduce((n, link) => link.token === token ? n + 1 : n, 0);
   const attachedIdsFor = (token) => {
@@ -1350,39 +1445,36 @@ function useContainerLinks(args) {
     return set;
   };
   const attach = async (token, resourceId, label, metadata, options) => {
-    if (!containerId) return { ok: false, error: "Missing container id" };
+    const ends = endpoints(token, resourceId);
+    if ("error" in ends) return { ok: false, error: ends.error };
     const result = await store.add({
-      sourceType: token,
-      sourceId: resourceId,
-      targetType: containerType,
-      targetId: containerId,
+      ...ends,
       ...orgId != null ? { orgId } : {},
       ...label !== void 0 ? { label } : {},
       ...metadata !== void 0 ? { metadata } : {},
       ...options?.role !== void 0 ? { role: options.role } : {},
       ...options?.replaceMetadata !== void 0 ? { replaceMetadata: options.replaceMetadata } : {}
     });
-    if (result.ok && containerType === "conversation" && token === "file") {
+    if (result.ok && !outgoing && containerType === "conversation" && token === "file") {
       await loadConversationFiles();
     }
     return result;
   };
   const detach = async (token, resourceId, role) => {
-    if (!containerId) return { ok: false, error: "Missing container id" };
+    const ends = endpoints(token, resourceId);
+    if ("error" in ends) return { ok: false, error: ends.error };
     const result = await store.remove({
-      sourceType: token,
-      sourceId: resourceId,
-      targetType: containerType,
-      targetId: containerId,
+      ...ends,
       ...role !== void 0 ? { role } : {}
     });
-    if (result.ok && containerType === "conversation" && token === "file") {
+    if (result.ok && !outgoing && containerType === "conversation" && token === "file") {
       await loadConversationFiles();
     }
     return result;
   };
   const setPinned = async (token, resourceId, pinned, role) => {
-    if (!containerId) return { ok: false, error: "Missing container id" };
+    const ends = endpoints(token, resourceId);
+    if ("error" in ends) return { ok: false, error: ends.error };
     const exactRole = role ?? null;
     const link = incoming.find(
       (candidate) => candidate.token === token && candidate.resourceId === resourceId && candidate.role === exactRole
@@ -1396,10 +1488,7 @@ function useContainerLinks(args) {
       };
     }
     return store.add({
-      sourceType: token,
-      sourceId: resourceId,
-      targetType: containerType,
-      targetId: containerId,
+      ...ends,
       ...orgId != null ? { orgId } : {},
       ...link.label != null ? { label: link.label } : {},
       ...role !== void 0 ? { role } : {},
@@ -1409,16 +1498,17 @@ function useContainerLinks(args) {
   const reload = async () => {
     await Promise.all([
       reloadGeneric(),
-      containerType === "conversation" ? loadConversationFiles() : Promise.resolve()
+      !outgoing && containerType === "conversation" ? loadConversationFiles() : Promise.resolve()
     ]);
   };
-  const status = !containerId ? genericStatus : conversationFileStatus === "error" ? "error" : containerType === "conversation" && (conversationFileStatus === "idle" || conversationFileStatus === "loading") ? "loading" : genericStatus;
+  const status = !containerId ? genericStatus : conversationFileStatus === "error" ? "error" : !outgoing && containerType === "conversation" && (conversationFileStatus === "idle" || conversationFileStatus === "loading") ? "loading" : genericStatus;
   const error = conversationFileError ?? genericError;
   return {
     status,
     error,
     reload,
     totalCount: incoming.length,
+    presentTokens: [...new Set(incoming.map((link) => link.token))],
     countFor,
     attachedIdsFor,
     linksFor,
@@ -1427,6 +1517,21 @@ function useContainerLinks(args) {
     setPinned
   };
 }
+function containerLinksArgs(container) {
+  if (container?.direction === "outgoing") {
+    return {
+      containerType: container.type,
+      containerId: container.id,
+      orgId: container.orgId ?? null,
+      direction: "outgoing"
+    };
+  }
+  return {
+    containerType: container?.type ?? "organization",
+    containerId: container?.id ?? null,
+    orgId: container?.orgId ?? null
+  };
+}
 
 // src/react/hooks/useEntityTitles.ts
 var import_react4 = require("react");
@@ -2261,7 +2366,7 @@ function AssociationPicker(props) {
   const Override = pickerOverrides?.[props.token];
   if (Override) return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(Override, { ...props });
   const title = `Add ${info.labelPlural}`;
-  const subtitle = props.containerLabel ? `Attach to ${props.containerLabel}` : "Click an item to attach or detach it";
+  const subtitle = props.filing ? `File ${props.containerLabel ?? "this"} under a ${info.label.toLowerCase()}` : props.containerLabel ? `Attach to ${props.containerLabel}` : "Click an item to attach or detach it";
   if (!props.open) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
     AssociationWindow,
@@ -2878,8 +2983,9 @@ function AttachedItemsSheet(props) {
   const Icon = info.Icon ?? DefaultEntityIcon;
   const title = info.labelPlural;
   const containerName = props.container?.label ?? props.containerLabel;
+  const filing = props.container?.direction === "outgoing";
   const subtitle = props.container ? /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("span", { className: "inline-flex min-w-0 max-w-full items-center gap-1", children: [
-    "Attached to",
+    filing ? "What this is filed under:" : "Attached to",
     /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
       DoorRef,
       {
@@ -3155,11 +3261,7 @@ function AssociationCard({
     attach,
     detach,
     setPinned
-  } = useContainerLinks({
-    containerType: container?.type ?? "organization",
-    containerId: container?.id ?? null,
-    orgId: container?.orgId ?? null
-  });
+  } = useContainerLinks(containerLinksArgs(container));
   if (!container) {
     store.errorSink({
       code: "association_card_no_container",
@@ -3170,7 +3272,8 @@ function AssociationCard({
   }
   const count = countFor(token);
   const loading = status === "loading" || status === "idle";
-  const canAttach = info.canListCandidates;
+  const filing = container.direction === "outgoing";
+  const canAttach = info.canListCandidates && (!filing || isAssociationTargetType(token));
   const canDrillIn = count > 0;
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
@@ -3218,7 +3321,7 @@ function AssociationCard({
                   /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "block text-[11px] text-muted-foreground tabular-nums", children: loading ? /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("span", { className: "inline-flex items-center gap-1", children: [
                     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(SpinnerIcon, { className: "h-3 w-3 animate-spin" }),
                     "Loading\u2026"
-                  ] }) : `${count} attached` })
+                  ] }) : `${count} ${container.direction === "outgoing" ? "filed under" : "attached"}` })
                 ] })
               ]
             }
@@ -3264,6 +3367,7 @@ function AssociationCard({
         token,
         ...container.label !== void 0 ? { containerLabel: container.label } : {},
         orgId: container.orgId ?? null,
+        ...filing ? { filing: true } : {},
         attachedIds: attachedIdsFor(token),
         onAttach: (resourceId, title) => attach(token, resourceId, title),
         onDetach: (resourceId) => detach(token, resourceId)
@@ -3281,31 +3385,55 @@ function AssociationCardGrid({
   className
 }) {
   const store = useAssociationsStore();
+  const primary = usePrimaryEntity();
   const excluded = new Set(excludeTokens ?? []);
-  const list = (tokens ?? store.registry.curatedTokens()).filter(
-    (token) => !excluded.has(token)
+  const filing = primary?.direction === "outgoing";
+  const links = useContainerLinks(containerLinksArgs(primary));
+  const base2 = tokens ?? store.registry.curatedTokens();
+  const withPresent = filing ? [
+    ...base2,
+    ...links.presentTokens.filter(
+      (t) => isEntityTypeToken(t) && !base2.includes(t)
+    )
+  ] : base2;
+  const list = withPresent.filter(
+    (token) => !excluded.has(token) && (!filing || isAssociationTargetType(token))
   );
-  return /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { className: (0, import_design_system7.cn)("space-y-5", className), children: CONTENT_ROLES.map((role) => {
-    const inRole = list.filter(
-      (token) => store.registry.getEntityInfo(token).contentRole === role.id
-    );
-    if (inRole.length === 0) return null;
-    return /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("section", { children: [
-      /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: "mb-2.5 flex items-baseline gap-3 pl-1.5", children: [
-        /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: "flex items-center gap-2", children: [
-          /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(
-            "span",
-            {
-              className: (0, import_design_system7.cn)("h-2.5 w-2.5 rounded-full", role.accentBar)
-            }
-          ),
-          /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("h3", { className: "text-sm font-semibold text-foreground", children: role.title })
+  const roleIds = new Set(CONTENT_ROLES.map((r) => r.id));
+  const roleless = filing ? list.filter((token) => {
+    const role = store.registry.getEntityInfo(token).contentRole;
+    return !role || !roleIds.has(role);
+  }) : [];
+  return /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: (0, import_design_system7.cn)("space-y-5", className), children: [
+    CONTENT_ROLES.map((role) => {
+      const inRole = list.filter(
+        (token) => store.registry.getEntityInfo(token).contentRole === role.id
+      );
+      if (inRole.length === 0) return null;
+      return /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("section", { children: [
+        /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: "mb-2.5 flex items-baseline gap-3 pl-1.5", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: "flex items-center gap-2", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(
+              "span",
+              {
+                className: (0, import_design_system7.cn)("h-2.5 w-2.5 rounded-full", role.accentBar)
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("h3", { className: "text-sm font-semibold text-foreground", children: role.title })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("p", { className: "hidden text-xs text-muted-foreground sm:block", children: role.tagline })
         ] }),
-        /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("p", { className: "hidden text-xs text-muted-foreground sm:block", children: role.tagline })
+        /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { className: "grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-3", children: inRole.map((token) => /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(AssociationCard, { token }, token)) })
+      ] }, role.id);
+    }),
+    roleless.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("section", { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("div", { className: "mb-2.5 flex items-baseline gap-3 pl-1.5", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("h3", { className: "text-sm font-semibold text-foreground", children: "Filed under" }),
+        /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("p", { className: "hidden text-xs text-muted-foreground sm:block", children: "Libraries, topics and other places this is kept." })
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { className: "grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-3", children: inRole.map((token) => /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(AssociationCard, { token }, token)) })
-    ] }, role.id);
-  }) });
+      /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { className: "grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-3", children: roleless.map((token) => /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(AssociationCard, { token }, token)) })
+    ] })
+  ] });
 }
 
 // src/react/components/AssociationList.tsx
@@ -3317,11 +3445,7 @@ function metadataIsPinned2(metadata) {
 }
 function useContainerLinksAdapter(container, tokens) {
   const store = useAssociationsStore();
-  const links = useContainerLinks({
-    containerType: container?.type ?? "organization",
-    containerId: container?.id ?? null,
-    orgId: container?.orgId ?? null
-  });
+  const links = useContainerLinks(containerLinksArgs(container));
   const rows = container ? (tokens ?? store.registry.curatedTokens()).flatMap(
     (token) => links.linksFor(token).map((l) => ({
       key: l.edgeId,