@ai-matrx/associations 0.5.2 → 0.6.0

package/dist/index.d.cts

@@ -11104,9 +11104,13 @@ interface AssociationsIdentity {
     ensureOrgId?(): Promise<string>;
 }
 /**
- * The scream seam — REQUIRED: recovery layers must scream somewhere. Every
- * degraded path, every `demanded_schema_violation`, every create-then-attach
- * partial failure reports here regardless of notifier availability.
+ * The scream seam. Every degraded path, every `demanded_schema_violation`,
+ * every create-then-attach partial failure reports here regardless of
+ * notifier availability.
+ *
+ * DEFAULT (0.6.0, C23): absent → `createDefaultErrorSink()` — a tagged
+ * `console.error` per event that announces ONCE that no sink is bound and
+ * names the remedy. A host with a diagnostics surface binds its own.
  */
 type ErrorSink = (event: {
     code: string;
@@ -11171,9 +11175,13 @@ interface AssociationsNotifier {
     }): void;
 }
 /**
- * The draggable-window seam (today: `WindowPanel` in AssociationWindow).
- * Absent → the package's internal fixed overlay (non-draggable); behavior
- * identical, chrome plainer.
+ * The window seam.
+ *
+ * DEFAULT (0.6.0, C23): absent → `DefaultWindowShell`, the package's OWN
+ * window — draggable, resizable, maximizable, viewport-clamped, portalled,
+ * non-modal, mobile bottom-card. Not a degradation; the shipped default.
+ * A host binds this port only when its own window MANAGER (tray docking,
+ * workspace persistence, cross-window z-order) must own the surface.
  */
 interface WindowShellPort {
     Window: ComponentType<{
@@ -11210,12 +11218,35 @@ interface CapturePickOpts {
     description?: string;
 }
 /**
- * The capture-toolbar seam (today: features/files upload + pickers and
- * features/data-tables imports in AssociationCaptureToolbar). PER-HANDLER
- * optional: the toolbar renders only the chips whose handler exists; zero
- * handlers → the toolbar renders nothing. NEVER dead buttons.
+ * The capture-toolbar seam. PER-HANDLER optional: the toolbar renders only
+ * the chips it can actually honour; a chip with no path behind it is never
+ * rendered dead. NEVER dead buttons.
+ *
+ * THE UPLOAD DEFAULT (0.6.0, C23): a host does NOT have to build an upload
+ * flow. Bind the one-file primitive `uploadFile` and the package ships the
+ * WHOLE flow over it — the file input, whole-body drag-and-drop, sequential
+ * uploads, the stall watchdog, per-file outcomes, and the loud
+ * created-but-unattached report. `requestUpload` stays for a host that owns
+ * a richer pipeline (duplicate-alias dialogs, progress UI); when both are
+ * bound `requestUpload` wins.
  */
 interface CapturePort {
+    /**
+     * The MINIMAL upload primitive: persist ONE file, answer with its id (or
+     * an honest error). Everything else — batching, drag-and-drop, progress
+     * state, failure copy — is the package's job.
+     */
+    uploadFile?(file: File, opts: {
+        folderPath: string;
+        visibility?: string;
+    }): Promise<{
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** The full host upload pipeline. Wins over `uploadFile` when bound. */
     requestUpload?(opts: CaptureUploadOpts): Promise<CaptureUploadResult>;
     /** Resolves with picked file ids, or null/empty on cancel. */
     openFilePicker?(opts: CapturePickOpts): Promise<string[] | null>;
@@ -11314,14 +11345,16 @@ interface EntityDoorsPort {
     }>;
 }
 /**
- * Everything a host binds, once. `createAssociationsStore(cfg)` (/core, W2)
- * throws when a REQUIRED port is missing; every optional port degrades per
- * its own documented contract, never silently.
+ * Everything a host binds, once. `createAssociationsStore(cfg)` (/core)
+ * throws when `dataSource` or `identity` is missing — those two ARE the
+ * host's app identity and cannot be defaulted. Every other port ships a
+ * working default (C23) or degrades per its own documented contract, never
+ * silently.
  */
 interface AssociationsConfig {
     dataSource: AssociationsDataSource;
     identity: AssociationsIdentity;
-    errorSink: ErrorSink;
+    errorSink?: ErrorSink;
     entityOverlay?: EntityOverlayMap;
     notifier?: AssociationsNotifier;
     windowShell?: WindowShellPort;

package/dist/index.d.ts

@@ -11104,9 +11104,13 @@ interface AssociationsIdentity {
     ensureOrgId?(): Promise<string>;
 }
 /**
- * The scream seam — REQUIRED: recovery layers must scream somewhere. Every
- * degraded path, every `demanded_schema_violation`, every create-then-attach
- * partial failure reports here regardless of notifier availability.
+ * The scream seam. Every degraded path, every `demanded_schema_violation`,
+ * every create-then-attach partial failure reports here regardless of
+ * notifier availability.
+ *
+ * DEFAULT (0.6.0, C23): absent → `createDefaultErrorSink()` — a tagged
+ * `console.error` per event that announces ONCE that no sink is bound and
+ * names the remedy. A host with a diagnostics surface binds its own.
  */
 type ErrorSink = (event: {
     code: string;
@@ -11171,9 +11175,13 @@ interface AssociationsNotifier {
     }): void;
 }
 /**
- * The draggable-window seam (today: `WindowPanel` in AssociationWindow).
- * Absent → the package's internal fixed overlay (non-draggable); behavior
- * identical, chrome plainer.
+ * The window seam.
+ *
+ * DEFAULT (0.6.0, C23): absent → `DefaultWindowShell`, the package's OWN
+ * window — draggable, resizable, maximizable, viewport-clamped, portalled,
+ * non-modal, mobile bottom-card. Not a degradation; the shipped default.
+ * A host binds this port only when its own window MANAGER (tray docking,
+ * workspace persistence, cross-window z-order) must own the surface.
  */
 interface WindowShellPort {
     Window: ComponentType<{
@@ -11210,12 +11218,35 @@ interface CapturePickOpts {
     description?: string;
 }
 /**
- * The capture-toolbar seam (today: features/files upload + pickers and
- * features/data-tables imports in AssociationCaptureToolbar). PER-HANDLER
- * optional: the toolbar renders only the chips whose handler exists; zero
- * handlers → the toolbar renders nothing. NEVER dead buttons.
+ * The capture-toolbar seam. PER-HANDLER optional: the toolbar renders only
+ * the chips it can actually honour; a chip with no path behind it is never
+ * rendered dead. NEVER dead buttons.
+ *
+ * THE UPLOAD DEFAULT (0.6.0, C23): a host does NOT have to build an upload
+ * flow. Bind the one-file primitive `uploadFile` and the package ships the
+ * WHOLE flow over it — the file input, whole-body drag-and-drop, sequential
+ * uploads, the stall watchdog, per-file outcomes, and the loud
+ * created-but-unattached report. `requestUpload` stays for a host that owns
+ * a richer pipeline (duplicate-alias dialogs, progress UI); when both are
+ * bound `requestUpload` wins.
  */
 interface CapturePort {
+    /**
+     * The MINIMAL upload primitive: persist ONE file, answer with its id (or
+     * an honest error). Everything else — batching, drag-and-drop, progress
+     * state, failure copy — is the package's job.
+     */
+    uploadFile?(file: File, opts: {
+        folderPath: string;
+        visibility?: string;
+    }): Promise<{
+        ok: true;
+        id: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** The full host upload pipeline. Wins over `uploadFile` when bound. */
     requestUpload?(opts: CaptureUploadOpts): Promise<CaptureUploadResult>;
     /** Resolves with picked file ids, or null/empty on cancel. */
     openFilePicker?(opts: CapturePickOpts): Promise<string[] | null>;
@@ -11314,14 +11345,16 @@ interface EntityDoorsPort {
     }>;
 }
 /**
- * Everything a host binds, once. `createAssociationsStore(cfg)` (/core, W2)
- * throws when a REQUIRED port is missing; every optional port degrades per
- * its own documented contract, never silently.
+ * Everything a host binds, once. `createAssociationsStore(cfg)` (/core)
+ * throws when `dataSource` or `identity` is missing — those two ARE the
+ * host's app identity and cannot be defaulted. Every other port ships a
+ * working default (C23) or degrades per its own documented contract, never
+ * silently.
  */
 interface AssociationsConfig {
     dataSource: AssociationsDataSource;
     identity: AssociationsIdentity;
-    errorSink: ErrorSink;
+    errorSink?: ErrorSink;
     entityOverlay?: EntityOverlayMap;
     notifier?: AssociationsNotifier;
     windowShell?: WindowShellPort;