@ai-matrx/design-system 0.21.2 → 0.21.3

package/dist/content-transfer.d.cts

@@ -1,9 +1,36 @@
 import * as React from 'react';
-import { AgentPayloadInput, TransferOutcome, TransferCapabilities, Transport, PageAction, TransferPreferenceOverrides, Source, Payload, ExportProjection, Section, SurfaceHandle, TransferScope } from '@ai-matrx/kit/content-transfer';
+import { Json, Artifact, TransferOutcome, FormatAdapter, PageAction, AgentPayloadInput, TransferCapabilities, Transport, TransferPreferenceOverrides, Source, Payload, ExportProjection, Section, SurfaceHandle, TransferScope } from '@ai-matrx/kit/content-transfer';
 import { AlchemyIcon } from './content-transfer/icon.cjs';
 export { ALCHEMY_COPY_TRANSFORM_SVG, ALCHEMY_GLYPH_SVG } from './content-transfer/icon.cjs';
-import { C as ContentTransferReference, a as ContentTransferReferencePort, b as ContentTransferEmailPort } from './extensions-DCHtNwG3.cjs';
-export { c as createTransferEmailActions, t as tableDataFormat, d as tableSchemaFormat } from './extensions-DCHtNwG3.cjs';
+
+type ContentTransferReference = {
+    id: string;
+    label: string;
+    noun: string;
+    items: Record<string, Json>[];
+};
+type ContentTransferReferencePort = {
+    supports(reference: ContentTransferReference): boolean;
+    build(reference: ContentTransferReference): string | Promise<string>;
+};
+type ContentTransferEmailPort = {
+    send(artifact: Artifact, context: {
+        label: string;
+        signal: AbortSignal;
+    }): Promise<TransferOutcome>;
+};
+/** A sealed, projection-safe representation of a tabular draft's declared schema and values. */
+declare const tableSchemaFormat: FormatAdapter;
+/** Flat row JSON keyed by user-facing display labels, never raw table records. */
+declare const tableDataFormat: FormatAdapter;
+type TransferEmailAction = PageAction & {
+    prepared: true;
+    group: "email";
+};
+/** Prepared-only delivery actions always serialize the current draft, never a host source. */
+declare function createTransferEmailActions(email: ContentTransferEmailPort, options?: {
+    jsonFormat?: FormatAdapter;
+}): TransferEmailAction[];
 
 type AlchemyOptionValues = Record<string, boolean | number>;
 type AlchemySourceOption = {
@@ -144,6 +171,8 @@ interface MatrxCopyMenuProps {
     grouped?: boolean;
     icon?: AlchemyIcon;
     triggerVariant?: "transparent" | "glass" | "outline";
+    controllerRef?: React.Ref<ContentTransferController>;
+    triggerHidden?: boolean;
 }
 /** Opinionated bridge for Matrx's existing content builders, with one transfer UI. */
 declare function MatrxCopyMenu(props: MatrxCopyMenuProps): React.JSX.Element;
@@ -231,6 +260,8 @@ interface ContentTransferMenuProps {
     /** Uses the canonical TapTargetButton presentation. */
     triggerVariant?: "transparent" | "glass" | "outline";
     triggerSize?: "default" | "compact";
+    /** Mount the transfer session without a visible trigger for a host-owned menu command. */
+    triggerHidden?: boolean;
     className?: string;
     stopPropagation?: boolean;
     hide?: readonly ("copy" | "prepare" | "download")[];
@@ -238,6 +269,9 @@ interface ContentTransferMenuProps {
 }
 interface ContentTransferController {
     focusTrigger(): void;
+    preparePrimary(options?: {
+        restoreFocus?: () => void;
+    }): Promise<void>;
     prepare(source: Source | Payload, options?: {
         id?: string;
         label?: string;
@@ -245,4 +279,4 @@ interface ContentTransferController {
 }
 declare function ContentTransferMenu(props: ContentTransferMenuProps): React.JSX.Element;
 
-export { type AlchemyCopyVariant, type AlchemyCustomSource, type AlchemyDetail, type AlchemyExportItem, AlchemyGlyph, type AlchemyGroomerConfig, type AlchemyGroomerPreset, type AlchemyGroomerSection, AlchemyIcon, type AlchemyOptionValues, type AlchemySourceOption, type ContentTransferCapabilities, ContentTransferCapabilitiesProvider, type ContentTransferController, ContentTransferEmailPort, ContentTransferMenu, type ContentTransferMenuProps, ContentTransferReference, type ContentTransferReferenceAction, ContentTransferReferencePort, ContentTransferSurfaceProvider, GROOMER_LEVELS, MatrxCopyMenu, type MatrxCopyMenuProps, type SerializableFormat, type TransferMenuPresentation, type TransferMenuVariant, applyGroomerPreset, buildGroomerPresetPayload, defaultGroomerSelections, groomerPresetVariants, useContentTransferCapabilities, useContentTransferSurface };
+export { type AlchemyCopyVariant, type AlchemyCustomSource, type AlchemyDetail, type AlchemyExportItem, AlchemyGlyph, type AlchemyGroomerConfig, type AlchemyGroomerPreset, type AlchemyGroomerSection, AlchemyIcon, type AlchemyOptionValues, type AlchemySourceOption, type ContentTransferCapabilities, ContentTransferCapabilitiesProvider, type ContentTransferController, type ContentTransferEmailPort, ContentTransferMenu, type ContentTransferMenuProps, type ContentTransferReference, type ContentTransferReferenceAction, type ContentTransferReferencePort, ContentTransferSurfaceProvider, GROOMER_LEVELS, MatrxCopyMenu, type MatrxCopyMenuProps, type SerializableFormat, type TransferMenuPresentation, type TransferMenuVariant, applyGroomerPreset, buildGroomerPresetPayload, createTransferEmailActions, defaultGroomerSelections, groomerPresetVariants, tableDataFormat, tableSchemaFormat, useContentTransferCapabilities, useContentTransferSurface };

package/dist/content-transfer.d.ts

@@ -1,9 +1,36 @@
 import * as React from 'react';
-import { AgentPayloadInput, TransferOutcome, TransferCapabilities, Transport, PageAction, TransferPreferenceOverrides, Source, Payload, ExportProjection, Section, SurfaceHandle, TransferScope } from '@ai-matrx/kit/content-transfer';
+import { Json, Artifact, TransferOutcome, FormatAdapter, PageAction, AgentPayloadInput, TransferCapabilities, Transport, TransferPreferenceOverrides, Source, Payload, ExportProjection, Section, SurfaceHandle, TransferScope } from '@ai-matrx/kit/content-transfer';
 import { AlchemyIcon } from './content-transfer/icon.js';
 export { ALCHEMY_COPY_TRANSFORM_SVG, ALCHEMY_GLYPH_SVG } from './content-transfer/icon.js';
-import { C as ContentTransferReference, a as ContentTransferReferencePort, b as ContentTransferEmailPort } from './extensions-DCHtNwG3.js';
-export { c as createTransferEmailActions, t as tableDataFormat, d as tableSchemaFormat } from './extensions-DCHtNwG3.js';
+
+type ContentTransferReference = {
+    id: string;
+    label: string;
+    noun: string;
+    items: Record<string, Json>[];
+};
+type ContentTransferReferencePort = {
+    supports(reference: ContentTransferReference): boolean;
+    build(reference: ContentTransferReference): string | Promise<string>;
+};
+type ContentTransferEmailPort = {
+    send(artifact: Artifact, context: {
+        label: string;
+        signal: AbortSignal;
+    }): Promise<TransferOutcome>;
+};
+/** A sealed, projection-safe representation of a tabular draft's declared schema and values. */
+declare const tableSchemaFormat: FormatAdapter;
+/** Flat row JSON keyed by user-facing display labels, never raw table records. */
+declare const tableDataFormat: FormatAdapter;
+type TransferEmailAction = PageAction & {
+    prepared: true;
+    group: "email";
+};
+/** Prepared-only delivery actions always serialize the current draft, never a host source. */
+declare function createTransferEmailActions(email: ContentTransferEmailPort, options?: {
+    jsonFormat?: FormatAdapter;
+}): TransferEmailAction[];
 
 type AlchemyOptionValues = Record<string, boolean | number>;
 type AlchemySourceOption = {
@@ -144,6 +171,8 @@ interface MatrxCopyMenuProps {
     grouped?: boolean;
     icon?: AlchemyIcon;
     triggerVariant?: "transparent" | "glass" | "outline";
+    controllerRef?: React.Ref<ContentTransferController>;
+    triggerHidden?: boolean;
 }
 /** Opinionated bridge for Matrx's existing content builders, with one transfer UI. */
 declare function MatrxCopyMenu(props: MatrxCopyMenuProps): React.JSX.Element;
@@ -231,6 +260,8 @@ interface ContentTransferMenuProps {
     /** Uses the canonical TapTargetButton presentation. */
     triggerVariant?: "transparent" | "glass" | "outline";
     triggerSize?: "default" | "compact";
+    /** Mount the transfer session without a visible trigger for a host-owned menu command. */
+    triggerHidden?: boolean;
     className?: string;
     stopPropagation?: boolean;
     hide?: readonly ("copy" | "prepare" | "download")[];
@@ -238,6 +269,9 @@ interface ContentTransferMenuProps {
 }
 interface ContentTransferController {
     focusTrigger(): void;
+    preparePrimary(options?: {
+        restoreFocus?: () => void;
+    }): Promise<void>;
     prepare(source: Source | Payload, options?: {
         id?: string;
         label?: string;
@@ -245,4 +279,4 @@ interface ContentTransferController {
 }
 declare function ContentTransferMenu(props: ContentTransferMenuProps): React.JSX.Element;
 
-export { type AlchemyCopyVariant, type AlchemyCustomSource, type AlchemyDetail, type AlchemyExportItem, AlchemyGlyph, type AlchemyGroomerConfig, type AlchemyGroomerPreset, type AlchemyGroomerSection, AlchemyIcon, type AlchemyOptionValues, type AlchemySourceOption, type ContentTransferCapabilities, ContentTransferCapabilitiesProvider, type ContentTransferController, ContentTransferEmailPort, ContentTransferMenu, type ContentTransferMenuProps, ContentTransferReference, type ContentTransferReferenceAction, ContentTransferReferencePort, ContentTransferSurfaceProvider, GROOMER_LEVELS, MatrxCopyMenu, type MatrxCopyMenuProps, type SerializableFormat, type TransferMenuPresentation, type TransferMenuVariant, applyGroomerPreset, buildGroomerPresetPayload, defaultGroomerSelections, groomerPresetVariants, useContentTransferCapabilities, useContentTransferSurface };
+export { type AlchemyCopyVariant, type AlchemyCustomSource, type AlchemyDetail, type AlchemyExportItem, AlchemyGlyph, type AlchemyGroomerConfig, type AlchemyGroomerPreset, type AlchemyGroomerSection, AlchemyIcon, type AlchemyOptionValues, type AlchemySourceOption, type ContentTransferCapabilities, ContentTransferCapabilitiesProvider, type ContentTransferController, type ContentTransferEmailPort, ContentTransferMenu, type ContentTransferMenuProps, type ContentTransferReference, type ContentTransferReferenceAction, type ContentTransferReferencePort, ContentTransferSurfaceProvider, GROOMER_LEVELS, MatrxCopyMenu, type MatrxCopyMenuProps, type SerializableFormat, type TransferMenuPresentation, type TransferMenuVariant, applyGroomerPreset, buildGroomerPresetPayload, createTransferEmailActions, defaultGroomerSelections, groomerPresetVariants, tableDataFormat, tableSchemaFormat, useContentTransferCapabilities, useContentTransferSurface };

package/dist/content-transfer.js

@@ -1497,7 +1497,12 @@ function MatrxCopyMenuSession(props) {
         ...props.referenceActions ? { referenceActions: props.referenceActions } : {},
         ...props.icon !== void 0 ? { icon: props.icon } : {},
         ...props.triggerVariant !== void 0 ? { triggerVariant: props.triggerVariant } : {},
-        controllerRef: controller,
+        controllerRef: (value) => {
+          controller.current = value;
+          if (typeof props.controllerRef === "function") props.controllerRef(value);
+          else if (props.controllerRef) props.controllerRef.current = value;
+        },
+        ...props.triggerHidden ? { triggerHidden: true } : {},
         label: props.label,
         variants,
         actions,
@@ -2053,8 +2058,9 @@ function ContentTransferMenu(props) {
   const identityKey = props.capabilities?.identityKey ?? inherited.identityKey;
   return /* @__PURE__ */ jsx11(ContentTransferMenuSession, { ...props }, identityKey ?? "anonymous");
 }
-function ContentTransferMenuSession({ references = [], referenceActions = [], source, surface, label, projection, sections, preferences, table, formatSources, sourceFormats = true, variants = EMPTY_VARIANTS, actions = [], capabilities: local, disabled, enabled = true, className, stopPropagation = true, hide = [], controllerRef, icon = "portal", triggerVariant = "transparent", triggerSize = "default" }) {
+function ContentTransferMenuSession({ references = [], referenceActions = [], source, surface, label, projection, sections, preferences, table, formatSources, sourceFormats = true, variants = EMPTY_VARIANTS, actions = [], capabilities: local, disabled, enabled = true, className, stopPropagation = true, hide = [], controllerRef, icon = "portal", triggerVariant = "transparent", triggerSize = "default", triggerHidden = false }) {
   const triggerRef = React10.useRef(null);
+  const restoreFocusRef = React10.useRef(null);
   const inherited = React10.useContext(CapabilityContext);
   const nearestSurface = React10.useContext(SurfaceContext);
   const fence = useFence();
@@ -2304,13 +2310,21 @@ function ContentTransferMenuSession({ references = [], referenceActions = [], so
   );
   React10.useImperativeHandle(controllerRef, () => ({
     focusTrigger: () => triggerRef.current?.focus(),
+    preparePrimary: async (options) => {
+      if (!enabled) throw new Error("Alchemy is not enabled for this record.");
+      if (disabled) throw new Error("Alchemy is disabled for this record.");
+      if (hide.includes("prepare")) throw new Error("Alchemy preparation is unavailable for this record.");
+      if (!primary) throw new Error("Alchemy has no source to prepare.");
+      restoreFocusRef.current = options?.restoreFocus ?? null;
+      await openWorkspace(primaryWorkspaceKey, { source: primary, label: sourceLabel });
+    },
     prepare: async (requestedSource, options) => {
       const requestedLabel = options?.label ?? ("label" in requestedSource ? requestedSource.label : "content");
       const requestedKey = `controller:${options?.id ?? "source"}:${materialIdentity(requestedSource)}`;
       externalWorkspaceKeys.current.add(requestedKey);
       await openWorkspace(requestedKey, { source: requestedSource, label: requestedLabel });
     }
-  }), [openWorkspace]);
+  }), [disabled, enabled, hide, openWorkspace, primary, primaryWorkspaceKey, sourceLabel]);
   const runAction = React10.useCallback(async (action) => {
     const { controller, id } = fence.begin();
     try {
@@ -2393,7 +2407,7 @@ function ContentTransferMenuSession({ references = [], referenceActions = [], so
     ] }, id);
   };
   return /* @__PURE__ */ jsxs6("span", { className: cn("matrx-alchemy", className), onClick: stopPropagation ? (event) => event.stopPropagation() : void 0, children: [
-    /* @__PURE__ */ jsxs6(Popover, { open: paletteOpen, onOpenChange: (open) => {
+    !triggerHidden ? /* @__PURE__ */ jsxs6(Popover, { open: paletteOpen, onOpenChange: (open) => {
       setPaletteOpen(open);
       if (open) {
         setMode("copy");
@@ -2502,13 +2516,13 @@ function ContentTransferMenuSession({ references = [], referenceActions = [], so
           ] }, group) : null;
         })
       ] })
-    ] }),
+    ] }) : null,
     notice && triggerRef.current ? createPortal(/* @__PURE__ */ jsxs6("div", { className: "matrx-alchemy-feedback", children: [
       /* @__PURE__ */ jsx11("span", { role: "status", children: notice }),
       /* @__PURE__ */ jsx11(ReceiptLink, { target: receiptTarget }),
       /* @__PURE__ */ jsx11("button", { type: "button", "aria-label": "Dismiss Alchemy feedback", onClick: () => setNotice(null), children: "\xD7" })
     ] }), triggerRef.current.ownerDocument.body) : null,
-    Object.values(workspaces).map((saved) => /* @__PURE__ */ jsx11(PreparationWorkspace, { restoreFocus: () => triggerRef.current?.focus(), open: workspaceOpen && workspaceKey === saved.key, state: saved, scopes, scopeLabels: table?.scopeLabels, onClose: () => setWorkspaceOpen(false), onChange: (next) => setWorkspaces((current) => ({ ...current, [saved.key]: next })), transport, adapters, actions: preparedActions, captureScope: workspaceCaptures.current.get(saved.key) ?? capturePrimary, ...ai ? { ai } : {}, onOutcome: report }, saved.key)),
+    Object.values(workspaces).map((saved) => /* @__PURE__ */ jsx11(PreparationWorkspace, { restoreFocus: () => restoreFocusRef.current?.() ?? triggerRef.current?.focus(), open: workspaceOpen && workspaceKey === saved.key, state: saved, scopes, scopeLabels: table?.scopeLabels, onClose: () => setWorkspaceOpen(false), onChange: (next) => setWorkspaces((current) => ({ ...current, [saved.key]: next })), transport, adapters, actions: preparedActions, captureScope: workspaceCaptures.current.get(saved.key) ?? capturePrimary, ...ai ? { ai } : {}, onOutcome: report }, saved.key)),
     emailReview
   ] });
 }