@ai-matrx/associations 0.10.7 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @ai-matrx/associations
 
+## 0.11.0
+
+**Filed-under mode** — `direction: "outgoing"` on the primary entity. A thing that is filed under
+containers (a Source under a project, a research topic, a Library) is now a first-class primary:
+
+* `PrimaryEntity` is `PrimaryContainerEntity` (the default, `direction?: "incoming"`, a container
+  TARGET type — unchanged) or `PrimaryFiledEntity` (`direction: "outgoing"`, any registered token).
+* `useContainerLinks({ …, direction: "outgoing" })` lists the primary's OUTGOING edges (the
+  containers it is filed under); `attach` writes `primary → container` as the same role-less edge
+  the landing door writes; `detach` / `setPinned` address that edge. A token that is not a
+  container type is refused before any write ("… cannot be filed under").
+* `containerLinksArgs(primary)` — the one mapping the faces use, so the direction is never dropped.
+* `AssociationCardGrid` / `AssociationCard` / `AssociationList` / `AttachedItemsSheet` /
+  `AssociationPicker` honour it: only container types are offered, counts read "N filed under",
+  the picker header reads "File X under a …" (`AssociationPickerProps.filing`).
+* New root export `isAssociationTargetType` and type `AssociationDirection`.
+
+Consumer action: none for containers. To show what an entity is filed under, pass
+`{ type, id, orgId, label, direction: "outgoing" }` to `PrimaryEntityProvider`.
+
 ## 0.10.7
 
 Regenerated the entity vocabulary from the live registry (998 active tokens):

package/dist/{CommentThread-DobuYuwz.d.cts → CommentThread-ZWiJVDpI.d.cts}

@@ -595,6 +595,11 @@ interface AssociationPickerProps {
         ok: boolean;
         error?: string;
     }>;
+    /**
+     * Filed-under mode: the primary is being FILED UNDER the picked items
+     * (`primary → item`), so the header says "File … under" not "Attach to".
+     */
+    filing?: boolean;
 }
 /** Per-token picker override map — absent tokens use the generic picker sheet. */
 type PickerOverrideMap = Partial<Record<EntityTypeToken, ComponentType<AssociationPickerProps>>>;
@@ -1445,6 +1450,37 @@ declare function useAssociations(args: UseAssociationsArgs): UseAssociationsRetu
  */
 declare const useEntityRelationships: typeof useAssociations;
 
+interface PrimaryEntityBase {
+    id: string;
+    /** Org to stamp on edges created here (org-scoped RLS / counts). */
+    orgId?: string | null;
+    /** Human label for headings (e.g. the org/scope name). */
+    label?: string;
+}
+/** A container: its surfaces list what is attached INTO it (the default). */
+interface PrimaryContainerEntity extends PrimaryEntityBase {
+    /** Container token — must be an association TARGET type. */
+    type: AssociationTargetType;
+    direction?: "incoming";
+}
+/**
+ * A thing FILED UNDER containers (e.g. a Source under a project): its
+ * surfaces list its own outgoing edges and "+" files it under a container.
+ */
+interface PrimaryFiledEntity extends PrimaryEntityBase {
+    /** Any registered entity type — it is the edge SOURCE. */
+    type: EntityTypeToken;
+    direction: "outgoing";
+}
+/** The primary entity a surface is anchored to. */
+type PrimaryEntity = PrimaryContainerEntity | PrimaryFiledEntity;
+declare function PrimaryEntityProvider({ value, children, }: {
+    value: PrimaryEntity;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Read the surrounding primary entity, or null when unprovided. */
+declare function usePrimaryEntity(): PrimaryEntity | null;
+
 interface ContainerLink {
     /** The edge id (for keys / removal). */
     edgeId: string;
@@ -1458,13 +1494,25 @@ interface ContainerLink {
     /** Per-edge props from `platform.associations.metadata` (e.g. representation). */
     metadata: unknown;
 }
-interface UseContainerLinksArgs {
-    /** The primary entity — always an association TARGET (container). */
-    containerType: AssociationTargetType;
+interface UseContainerLinksBase {
     containerId: string | null;
     /** Org to stamp on new edges (for org-scoped RLS / counts). */
     orgId?: string | null;
 }
+/**
+ * `incoming` (default): the primary is a container (edge TARGET) — links are
+ * what is attached into it. `outgoing`: the primary is filed under containers
+ * (edge SOURCE) — links are the containers it is filed under, and `attach`
+ * writes `primary → container` (the same role-less edge the landing door
+ * writes), refusing tokens that are not container types.
+ */
+type UseContainerLinksArgs = (UseContainerLinksBase & {
+    containerType: AssociationTargetType;
+    direction?: "incoming";
+}) | (UseContainerLinksBase & {
+    containerType: EntityTypeToken;
+    direction: "outgoing";
+});
 interface UseContainerLinksReturn {
     status: ReturnType<typeof useAssociations>["status"];
     error: string | null;
@@ -1496,6 +1544,11 @@ interface UseContainerLinksReturn {
     setPinned: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<AssociationWriteResult>;
 }
 declare function useContainerLinks(args: UseContainerLinksArgs): UseContainerLinksReturn;
+/**
+ * `useContainerLinks` args for a surface's primary entity — the ONE mapping
+ * the faces (card, list) use, so a primary's direction is never dropped.
+ */
+declare function containerLinksArgs(container: PrimaryEntity | null): UseContainerLinksArgs;
 
 interface AssociationEntitySelectItem {
     id: string;
@@ -1543,23 +1596,6 @@ interface UseAssociationEntitySelectAdapterArgs {
 }
 declare function useAssociationEntitySelectAdapter(args: UseAssociationEntitySelectAdapterArgs): AssociationEntitySelectAdapter;
 
-/** The primary (container) entity a surface is anchored to. */
-interface PrimaryEntity {
-    /** Container token — must be an association TARGET type. */
-    type: AssociationTargetType;
-    id: string;
-    /** Org to stamp on edges created here (org-scoped RLS / counts). */
-    orgId?: string | null;
-    /** Human label for headings (e.g. the org/scope name). */
-    label?: string;
-}
-declare function PrimaryEntityProvider({ value, children, }: {
-    value: PrimaryEntity;
-    children: ReactNode;
-}): react.JSX.Element;
-/** Read the surrounding primary entity, or null when unprovided. */
-declare function usePrimaryEntity(): PrimaryEntity | null;
-
 interface AssociationWindowProps {
     /** Controls mount — callers should also gate their JSX on this. */
     open: boolean;
@@ -1927,4 +1963,4 @@ declare function buildCommentTree(comments: readonly PlatformComment[]): {
 };
 declare function CommentThread({ token, id, orgId, showHeader, className, }: CommentThreadProps): react.JSX.Element;
 
-export { DefaultEntityIcon as $, type AssociationCaptureToolbarProps as A, AssociationCaptureToolbar as B, type CategorySelectProps as C, AssociationCard as D, type EntityDoorsPort as E, AssociationCardGrid as F, AssociationEntitySelect as G, type AssociationEntitySelectAdapter as H, type AssociationEntitySelectItem as I, AssociationList as J, AssociationWindow as K, type AssociationWriteResult as L, AttachedItemsSheet as M, type CaptureAttach as N, type CaptureAttachResult as O, type PickerOverrideMap as P, CaptureToolbarAction as Q, CategorySelect as R, CategoryTagPicker as S, CommentComposer as T, type UniversalAssociationPickerProps as U, type CommentComposerProps as V, type WindowShellPort as W, CommentThread as X, type ContainerLink as Y, type ContainerResourceRow as Z, type ContainerResourcesAdapter as _, type AssociationCardProps as a, type PrimaryEntity as a0, PrimaryEntityProvider as a1, type TagPickerIcon as a2, UniversalAssociationPicker as a3, type UseAssociationEntitySelectAdapterArgs as a4, type UseAssociationsArgs as a5, type UseAssociationsReturn as a6, type UseContainerLinksArgs as a7, type UseContainerLinksReturn as a8, attachedKey as a9, buildCommentTree as aa, useAssociationEntitySelectAdapter as ab, useAssociations as ac, useContainerLinks as ad, useContainerLinksAdapter as ae, useEntityRelationships as af, usePrimaryEntity as ag, type AssociationCardGridProps as b, type AssociationEntitySelectProps as c, type AssociationListProps as d, type AssociationPickerProps as e, type AssociationWindowProps as f, type AttachedItemsSheetProps as g, type CategoryTagPickerProps as h, type CommentThreadProps as i, type AssociationsNotifier as j, type CapturePort as k, type AuthorDisplayPort as l, type AssociationsStore as m, type CategoryMutationResult as n, type CategoryDimension as o, type PlatformCategory as p, type CategoriesEntry as q, type EntityTypeToken as r, type UniversalCandidate as s, type CandidateRecord as t, type PlatformComment as u, type CommentsEntry as v, type CommentMutationResult as w, type EntityDoorProps as x, type EntityRefProps as y, type ContentRole as z };
+export { DefaultEntityIcon as $, type AssociationCaptureToolbarProps as A, AssociationCaptureToolbar as B, type CategorySelectProps as C, AssociationCard as D, type EntityDoorsPort as E, AssociationCardGrid as F, AssociationEntitySelect as G, type AssociationEntitySelectAdapter as H, type AssociationEntitySelectItem as I, AssociationList as J, AssociationWindow as K, type AssociationWriteResult as L, AttachedItemsSheet as M, type CaptureAttach as N, type CaptureAttachResult as O, type PickerOverrideMap as P, CaptureToolbarAction as Q, CategorySelect as R, CategoryTagPicker as S, CommentComposer as T, type UniversalAssociationPickerProps as U, type CommentComposerProps as V, type WindowShellPort as W, CommentThread as X, type ContainerLink as Y, type ContainerResourceRow as Z, type ContainerResourcesAdapter as _, type AssociationCardProps as a, type PrimaryContainerEntity as a0, type PrimaryEntity as a1, PrimaryEntityProvider as a2, type PrimaryFiledEntity as a3, type TagPickerIcon as a4, UniversalAssociationPicker as a5, type UseAssociationEntitySelectAdapterArgs as a6, type UseAssociationsArgs as a7, type UseAssociationsReturn as a8, type UseContainerLinksArgs as a9, type UseContainerLinksReturn as aa, attachedKey as ab, buildCommentTree as ac, containerLinksArgs as ad, useAssociationEntitySelectAdapter as ae, useAssociations as af, useContainerLinks as ag, useContainerLinksAdapter as ah, useEntityRelationships as ai, usePrimaryEntity as aj, type AssociationCardGridProps as b, type AssociationEntitySelectProps as c, type AssociationListProps as d, type AssociationPickerProps as e, type AssociationWindowProps as f, type AttachedItemsSheetProps as g, type CategoryTagPickerProps as h, type CommentThreadProps as i, type AssociationsNotifier as j, type CapturePort as k, type AuthorDisplayPort as l, type AssociationsStore as m, type CategoryMutationResult as n, type CategoryDimension as o, type PlatformCategory as p, type CategoriesEntry as q, type EntityTypeToken as r, type UniversalCandidate as s, type CandidateRecord as t, type PlatformComment as u, type CommentsEntry as v, type CommentMutationResult as w, type EntityDoorProps as x, type EntityRefProps as y, type ContentRole as z };

package/dist/{CommentThread-DobuYuwz.d.ts → CommentThread-ZWiJVDpI.d.ts}

@@ -595,6 +595,11 @@ interface AssociationPickerProps {
         ok: boolean;
         error?: string;
     }>;
+    /**
+     * Filed-under mode: the primary is being FILED UNDER the picked items
+     * (`primary → item`), so the header says "File … under" not "Attach to".
+     */
+    filing?: boolean;
 }
 /** Per-token picker override map — absent tokens use the generic picker sheet. */
 type PickerOverrideMap = Partial<Record<EntityTypeToken, ComponentType<AssociationPickerProps>>>;
@@ -1445,6 +1450,37 @@ declare function useAssociations(args: UseAssociationsArgs): UseAssociationsRetu
  */
 declare const useEntityRelationships: typeof useAssociations;
 
+interface PrimaryEntityBase {
+    id: string;
+    /** Org to stamp on edges created here (org-scoped RLS / counts). */
+    orgId?: string | null;
+    /** Human label for headings (e.g. the org/scope name). */
+    label?: string;
+}
+/** A container: its surfaces list what is attached INTO it (the default). */
+interface PrimaryContainerEntity extends PrimaryEntityBase {
+    /** Container token — must be an association TARGET type. */
+    type: AssociationTargetType;
+    direction?: "incoming";
+}
+/**
+ * A thing FILED UNDER containers (e.g. a Source under a project): its
+ * surfaces list its own outgoing edges and "+" files it under a container.
+ */
+interface PrimaryFiledEntity extends PrimaryEntityBase {
+    /** Any registered entity type — it is the edge SOURCE. */
+    type: EntityTypeToken;
+    direction: "outgoing";
+}
+/** The primary entity a surface is anchored to. */
+type PrimaryEntity = PrimaryContainerEntity | PrimaryFiledEntity;
+declare function PrimaryEntityProvider({ value, children, }: {
+    value: PrimaryEntity;
+    children: ReactNode;
+}): react.JSX.Element;
+/** Read the surrounding primary entity, or null when unprovided. */
+declare function usePrimaryEntity(): PrimaryEntity | null;
+
 interface ContainerLink {
     /** The edge id (for keys / removal). */
     edgeId: string;
@@ -1458,13 +1494,25 @@ interface ContainerLink {
     /** Per-edge props from `platform.associations.metadata` (e.g. representation). */
     metadata: unknown;
 }
-interface UseContainerLinksArgs {
-    /** The primary entity — always an association TARGET (container). */
-    containerType: AssociationTargetType;
+interface UseContainerLinksBase {
     containerId: string | null;
     /** Org to stamp on new edges (for org-scoped RLS / counts). */
     orgId?: string | null;
 }
+/**
+ * `incoming` (default): the primary is a container (edge TARGET) — links are
+ * what is attached into it. `outgoing`: the primary is filed under containers
+ * (edge SOURCE) — links are the containers it is filed under, and `attach`
+ * writes `primary → container` (the same role-less edge the landing door
+ * writes), refusing tokens that are not container types.
+ */
+type UseContainerLinksArgs = (UseContainerLinksBase & {
+    containerType: AssociationTargetType;
+    direction?: "incoming";
+}) | (UseContainerLinksBase & {
+    containerType: EntityTypeToken;
+    direction: "outgoing";
+});
 interface UseContainerLinksReturn {
     status: ReturnType<typeof useAssociations>["status"];
     error: string | null;
@@ -1496,6 +1544,11 @@ interface UseContainerLinksReturn {
     setPinned: (token: EntityTypeToken, resourceId: string, pinned: boolean, role?: string) => Promise<AssociationWriteResult>;
 }
 declare function useContainerLinks(args: UseContainerLinksArgs): UseContainerLinksReturn;
+/**
+ * `useContainerLinks` args for a surface's primary entity — the ONE mapping
+ * the faces (card, list) use, so a primary's direction is never dropped.
+ */
+declare function containerLinksArgs(container: PrimaryEntity | null): UseContainerLinksArgs;
 
 interface AssociationEntitySelectItem {
     id: string;
@@ -1543,23 +1596,6 @@ interface UseAssociationEntitySelectAdapterArgs {
 }
 declare function useAssociationEntitySelectAdapter(args: UseAssociationEntitySelectAdapterArgs): AssociationEntitySelectAdapter;
 
-/** The primary (container) entity a surface is anchored to. */
-interface PrimaryEntity {
-    /** Container token — must be an association TARGET type. */
-    type: AssociationTargetType;
-    id: string;
-    /** Org to stamp on edges created here (org-scoped RLS / counts). */
-    orgId?: string | null;
-    /** Human label for headings (e.g. the org/scope name). */
-    label?: string;
-}
-declare function PrimaryEntityProvider({ value, children, }: {
-    value: PrimaryEntity;
-    children: ReactNode;
-}): react.JSX.Element;
-/** Read the surrounding primary entity, or null when unprovided. */
-declare function usePrimaryEntity(): PrimaryEntity | null;
-
 interface AssociationWindowProps {
     /** Controls mount — callers should also gate their JSX on this. */
     open: boolean;
@@ -1927,4 +1963,4 @@ declare function buildCommentTree(comments: readonly PlatformComment[]): {
 };
 declare function CommentThread({ token, id, orgId, showHeader, className, }: CommentThreadProps): react.JSX.Element;
 
-export { DefaultEntityIcon as $, type AssociationCaptureToolbarProps as A, AssociationCaptureToolbar as B, type CategorySelectProps as C, AssociationCard as D, type EntityDoorsPort as E, AssociationCardGrid as F, AssociationEntitySelect as G, type AssociationEntitySelectAdapter as H, type AssociationEntitySelectItem as I, AssociationList as J, AssociationWindow as K, type AssociationWriteResult as L, AttachedItemsSheet as M, type CaptureAttach as N, type CaptureAttachResult as O, type PickerOverrideMap as P, CaptureToolbarAction as Q, CategorySelect as R, CategoryTagPicker as S, CommentComposer as T, type UniversalAssociationPickerProps as U, type CommentComposerProps as V, type WindowShellPort as W, CommentThread as X, type ContainerLink as Y, type ContainerResourceRow as Z, type ContainerResourcesAdapter as _, type AssociationCardProps as a, type PrimaryEntity as a0, PrimaryEntityProvider as a1, type TagPickerIcon as a2, UniversalAssociationPicker as a3, type UseAssociationEntitySelectAdapterArgs as a4, type UseAssociationsArgs as a5, type UseAssociationsReturn as a6, type UseContainerLinksArgs as a7, type UseContainerLinksReturn as a8, attachedKey as a9, buildCommentTree as aa, useAssociationEntitySelectAdapter as ab, useAssociations as ac, useContainerLinks as ad, useContainerLinksAdapter as ae, useEntityRelationships as af, usePrimaryEntity as ag, type AssociationCardGridProps as b, type AssociationEntitySelectProps as c, type AssociationListProps as d, type AssociationPickerProps as e, type AssociationWindowProps as f, type AttachedItemsSheetProps as g, type CategoryTagPickerProps as h, type CommentThreadProps as i, type AssociationsNotifier as j, type CapturePort as k, type AuthorDisplayPort as l, type AssociationsStore as m, type CategoryMutationResult as n, type CategoryDimension as o, type PlatformCategory as p, type CategoriesEntry as q, type EntityTypeToken as r, type UniversalCandidate as s, type CandidateRecord as t, type PlatformComment as u, type CommentsEntry as v, type CommentMutationResult as w, type EntityDoorProps as x, type EntityRefProps as y, type ContentRole as z };
+export { DefaultEntityIcon as $, type AssociationCaptureToolbarProps as A, AssociationCaptureToolbar as B, type CategorySelectProps as C, AssociationCard as D, type EntityDoorsPort as E, AssociationCardGrid as F, AssociationEntitySelect as G, type AssociationEntitySelectAdapter as H, type AssociationEntitySelectItem as I, AssociationList as J, AssociationWindow as K, type AssociationWriteResult as L, AttachedItemsSheet as M, type CaptureAttach as N, type CaptureAttachResult as O, type PickerOverrideMap as P, CaptureToolbarAction as Q, CategorySelect as R, CategoryTagPicker as S, CommentComposer as T, type UniversalAssociationPickerProps as U, type CommentComposerProps as V, type WindowShellPort as W, CommentThread as X, type ContainerLink as Y, type ContainerResourceRow as Z, type ContainerResourcesAdapter as _, type AssociationCardProps as a, type PrimaryContainerEntity as a0, type PrimaryEntity as a1, PrimaryEntityProvider as a2, type PrimaryFiledEntity as a3, type TagPickerIcon as a4, UniversalAssociationPicker as a5, type UseAssociationEntitySelectAdapterArgs as a6, type UseAssociationsArgs as a7, type UseAssociationsReturn as a8, type UseContainerLinksArgs as a9, type UseContainerLinksReturn as aa, attachedKey as ab, buildCommentTree as ac, containerLinksArgs as ad, useAssociationEntitySelectAdapter as ae, useAssociations as af, useContainerLinks as ag, useContainerLinksAdapter as ah, useEntityRelationships as ai, usePrimaryEntity as aj, type AssociationCardGridProps as b, type AssociationEntitySelectProps as c, type AssociationListProps as d, type AssociationPickerProps as e, type AssociationWindowProps as f, type AttachedItemsSheetProps as g, type CategoryTagPickerProps as h, type CommentThreadProps as i, type AssociationsNotifier as j, type CapturePort as k, type AuthorDisplayPort as l, type AssociationsStore as m, type CategoryMutationResult as n, type CategoryDimension as o, type PlatformCategory as p, type CategoriesEntry as q, type EntityTypeToken as r, type UniversalCandidate as s, type CandidateRecord as t, type PlatformComment as u, type CommentsEntry as v, type CommentMutationResult as w, type EntityDoorProps as x, type EntityRefProps as y, type ContentRole as z };

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(src_exports, {
   ENTITY_TYPE_TOKENS: () => ENTITY_TYPE_TOKENS,
   REFERENCE_CATEGORY_DISPLAY: () => REFERENCE_CATEGORY_DISPLAY,
   SCHEMA_DISPLAY: () => SCHEMA_DISPLAY,
+  isAssociationTargetType: () => isAssociationTargetType,
   isAssociationsRpcErr: () => isAssociationsRpcErr,
   isEntityTypeToken: () => isEntityTypeToken
 });
@@ -2140,6 +2141,9 @@ var ASSOCIATION_TARGET_TYPES = [
   "rulebook"
   //             a Masterwork Rulebook — its Scout interviews attach here (conversation→rulebook, role 'interview')
 ];
+function isAssociationTargetType(value) {
+  return typeof value === "string" && ASSOCIATION_TARGET_TYPES.includes(value);
+}
 
 // src/results.ts
 function isAssociationsRpcErr(r) {