@agg-build/ui 2.1.1 → 2.1.3

package/dist/types/primitives/state-message/state-message.types.d.mts

@@ -7,7 +7,7 @@ export type StateMessageClassNames = {
     description?: string;
     action?: string;
 };
-export type StateMessageProps = {
+export type StateMessageProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
     /** Heading shown for the state message. */
     title: string;
     /** Supporting description shown under the title. */

package/dist/types/primitives/state-message/state-message.types.d.ts

@@ -7,7 +7,7 @@ export type StateMessageClassNames = {
     description?: string;
     action?: string;
 };
-export type StateMessageProps = {
+export type StateMessageProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
     /** Heading shown for the state message. */
     title: string;
     /** Supporting description shown under the title. */

package/dist/types/trading/index.d.mts

@@ -4,3 +4,5 @@ export * from "./settlement";
 export * from "./settlement/settlement-details";
 export * from "./place-order";
 export * from "./trading-context";
+export * from "./use-claim-winnings";
+export * from "./use-resolved-market-claim";

package/dist/types/trading/index.d.ts

@@ -4,3 +4,5 @@ export * from "./settlement";
 export * from "./settlement/settlement-details";
 export * from "./place-order";
 export * from "./trading-context";
+export * from "./use-claim-winnings";
+export * from "./use-resolved-market-claim";

package/dist/types/trading/place-order/index.d.mts

@@ -5,6 +5,6 @@ export { PlaceOrderSuccessView } from "./index.place-order.success";
 export type { PlaceOrderSuccessViewProps } from "./index.place-order.success";
 export type { PlaceOrderClassNames, PlaceOrderExecutionSummary, PlaceOrderResolvedClaimSummary, PlaceOrderTradingLabels, } from "./index.place-order.types";
 export declare const PlaceOrder: {
-    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
+    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, isQuotePanelActive, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onBeforePrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
     displayName: string;
 };

package/dist/types/trading/place-order/index.d.ts

@@ -5,6 +5,6 @@ export { PlaceOrderSuccessView } from "./index.place-order.success";
 export type { PlaceOrderSuccessViewProps } from "./index.place-order.success";
 export type { PlaceOrderClassNames, PlaceOrderExecutionSummary, PlaceOrderResolvedClaimSummary, PlaceOrderTradingLabels, } from "./index.place-order.types";
 export declare const PlaceOrder: {
-    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
+    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, isQuotePanelActive, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onBeforePrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
     displayName: string;
 };

package/dist/types/trading/place-order/index.place-order.types.d.mts

@@ -16,17 +16,45 @@ export type PlaceOrderProps = {
     isPrimaryActionDisabled?: boolean;
     /** Whether the primary submit action should show a loading spinner. */
     isPrimaryActionLoading?: boolean;
+    /**
+     * Whether this place-order instance is the active, visible quote surface.
+     * Hidden or closed surfaces should pass false so quote polling can pause.
+     * Defaults to true.
+     */
+    isQuotePanelActive?: boolean;
     /** Called when the entered order amount changes. */
     onAmountChange?: (amount: number) => void;
     /** Called when the place-order panel should close. */
     onClose?: () => void;
     /** Called when the selected outcome changes. */
     onOutcomeChange?: (outcomeId: string) => void;
-    /** Called when the primary action is triggered. */
+    /**
+     * Called when the primary action is triggered, in place of the internal
+     * quote execution. When provided, the component delegates the fill entirely
+     * to this callback and does NOT run its own execution. For a pre-flight gate
+     * that should run *before* the normal fill (and let it proceed), use
+     * `onBeforePrimaryAction` instead.
+     */
     onPrimaryAction?: (context?: {
         quoteId?: string;
         mode?: ExecutionMode;
     }) => void;
+    /**
+     * Called when the primary action is triggered, BEFORE the internal quote
+     * execution. Unlike `onPrimaryAction`, this does not replace the fill — it
+     * runs in between and, when it resolves, the order is filled as usual. Use it
+     * for a partner gate such as a verification/KYC modal that must complete
+     * before the order goes through.
+     *
+     * The returned promise is awaited before execution proceeds:
+     * - resolve (return `undefined`/`true`) → continue with the normal fill
+     * - return `false` → cancel silently; the panel returns to idle
+     * - throw → abort and surface the error as submission feedback
+     */
+    onBeforePrimaryAction?: (context?: {
+        quoteId?: string;
+        mode?: ExecutionMode;
+    }) => void | boolean | Promise<void | boolean>;
     /** Called when the slippage control value changes. */
     onSlippageChange?: (value: string) => void;
     /** Called when the active trade tab changes. */
@@ -207,6 +235,7 @@ export type PlaceOrderSubmissionProgressState = {
     failureSummary?: PlaceOrderFailureSummary;
     orderId?: string;
     orderIds?: string[];
+    quoteId?: string;
     phase: PlaceOrderSubmissionProgressPhase;
     summary?: PlaceOrderExecutionSummary;
     dagProgress?: DagStepProgress | null;

package/dist/types/trading/place-order/index.place-order.types.d.ts

@@ -16,17 +16,45 @@ export type PlaceOrderProps = {
     isPrimaryActionDisabled?: boolean;
     /** Whether the primary submit action should show a loading spinner. */
     isPrimaryActionLoading?: boolean;
+    /**
+     * Whether this place-order instance is the active, visible quote surface.
+     * Hidden or closed surfaces should pass false so quote polling can pause.
+     * Defaults to true.
+     */
+    isQuotePanelActive?: boolean;
     /** Called when the entered order amount changes. */
     onAmountChange?: (amount: number) => void;
     /** Called when the place-order panel should close. */
     onClose?: () => void;
     /** Called when the selected outcome changes. */
     onOutcomeChange?: (outcomeId: string) => void;
-    /** Called when the primary action is triggered. */
+    /**
+     * Called when the primary action is triggered, in place of the internal
+     * quote execution. When provided, the component delegates the fill entirely
+     * to this callback and does NOT run its own execution. For a pre-flight gate
+     * that should run *before* the normal fill (and let it proceed), use
+     * `onBeforePrimaryAction` instead.
+     */
     onPrimaryAction?: (context?: {
         quoteId?: string;
         mode?: ExecutionMode;
     }) => void;
+    /**
+     * Called when the primary action is triggered, BEFORE the internal quote
+     * execution. Unlike `onPrimaryAction`, this does not replace the fill — it
+     * runs in between and, when it resolves, the order is filled as usual. Use it
+     * for a partner gate such as a verification/KYC modal that must complete
+     * before the order goes through.
+     *
+     * The returned promise is awaited before execution proceeds:
+     * - resolve (return `undefined`/`true`) → continue with the normal fill
+     * - return `false` → cancel silently; the panel returns to idle
+     * - throw → abort and surface the error as submission feedback
+     */
+    onBeforePrimaryAction?: (context?: {
+        quoteId?: string;
+        mode?: ExecutionMode;
+    }) => void | boolean | Promise<void | boolean>;
     /** Called when the slippage control value changes. */
     onSlippageChange?: (value: string) => void;
     /** Called when the active trade tab changes. */
@@ -207,6 +235,7 @@ export type PlaceOrderSubmissionProgressState = {
     failureSummary?: PlaceOrderFailureSummary;
     orderId?: string;
     orderIds?: string[];
+    quoteId?: string;
     phase: PlaceOrderSubmissionProgressPhase;
     summary?: PlaceOrderExecutionSummary;
     dagProgress?: DagStepProgress | null;

package/dist/types/trading/settlement/settlement-text.utils.d.mts

@@ -30,7 +30,10 @@ export type SettlementSourceBlock = {
 };
 /**
  * Produces the ordered list of non-empty settlement blocks for the Settlement
- * section, dropping any source whose normalized text is identical to a block
- * already included.
+ * section, dropping any source whose normalized text is contained within
+ * another source's — keeping the superset. Containment (not just equality) is
+ * required because some venues (e.g. predict) store the same rules text on both
+ * the event and its markets, with the market copy adding only a trailing
+ * "Created At: ..." line, so the two are a prefix relationship, not identical.
  */
 export declare const dedupeSettlementSources: (sources: SettlementSourceInput) => SettlementSourceBlock[];

package/dist/types/trading/settlement/settlement-text.utils.d.ts

@@ -30,7 +30,10 @@ export type SettlementSourceBlock = {
 };
 /**
  * Produces the ordered list of non-empty settlement blocks for the Settlement
- * section, dropping any source whose normalized text is identical to a block
- * already included.
+ * section, dropping any source whose normalized text is contained within
+ * another source's — keeping the superset. Containment (not just equality) is
+ * required because some venues (e.g. predict) store the same rules text on both
+ * the event and its markets, with the market copy adding only a trailing
+ * "Created At: ..." line, so the two are a prefix relationship, not identical.
  */
 export declare const dedupeSettlementSources: (sources: SettlementSourceInput) => SettlementSourceBlock[];

package/dist/types/trading/use-claim-winnings.d.mts

@@ -0,0 +1,84 @@
+/**
+ * Shape of the `notifications.claim` label block consumed by the claim flow.
+ * Mirrors the typed labels so callers can reason about the toast copy.
+ */
+export type ClaimNotificationLabels = {
+    pendingTitle: string;
+    pendingMessage: string;
+    submittedTitle: string;
+    submittedMessage: string;
+    successTitle: string;
+    successMessage: string;
+    partialTitle: string;
+    partialMessage: (errorReason?: string) => string;
+    failedTitle: string;
+    failedMessage: (errorReason?: string) => string;
+    missingOutcomeMessage: string;
+};
+/** Terminal lifecycle summary forwarded to `onClaimResult`. */
+export type ClaimLifecycleResult = {
+    allConfirmed: boolean;
+    anyFailed: boolean;
+    errorMessage: string | null;
+};
+/** A single claim request keyed by `claimKey`. */
+export type ClaimWinningsInput<TPayload = void> = {
+    /** Stable identifier for the position being claimed (e.g. `marketId`). */
+    claimKey: string;
+    /** Winning venue-market-outcome ids to redeem. */
+    winningOutcomeIds: string[];
+    /** Opaque payload forwarded verbatim to a caller-provided `onClaim`. */
+    payload?: TPayload;
+};
+export type UseClaimWinningsOptions<TPayload = void> = {
+    /**
+     * Caller-owned claim handler. When provided, the hook delegates the actual
+     * redeem to this callback and toasts a simple pending → success/failure
+     * lifecycle (no WS lifecycle tracking). Partners who own the claim flow pass
+     * this; omit it to let the hook drive the internal redeem mutation.
+     */
+    onClaim?: (payload: TPayload) => Promise<void> | void;
+    /**
+     * Fired once per redeem when its WS lifecycle reaches terminal. Only fired on
+     * the internal claim path (i.e. when `onClaim` is omitted).
+     */
+    onClaimResult?: (claimKey: string, lifecycle: ClaimLifecycleResult) => void;
+    /**
+     * Fired when the redeem mutation itself rejects (transport error, validation
+     * error, or all legs ineligible/rejected at submit time). The redeem never
+     * enters the WS lifecycle in these cases, so `onClaimResult` does NOT fire.
+     */
+    onClaimSubmitError?: (claimKey: string, error: Error) => void;
+    /**
+     * Caller-owned spinner map. When provided, it fully replaces the hook's
+     * lifecycle-derived spinner state for display purposes (mirrors the legacy
+     * `claimingPositionKeys ?? internal` behavior).
+     */
+    externalClaimingKeys?: Record<string, boolean>;
+};
+export type UseClaimWinningsResult<TPayload = void> = {
+    /** Start a claim for a single position. Resolves once the submit settles. */
+    claim: (input: ClaimWinningsInput<TPayload>) => Promise<void>;
+    /** Map of claim key → in-flight flag, suitable to pass to a row renderer. */
+    claimingKeys: Record<string, boolean>;
+    /** Whether a given claim key is currently in-flight (submit or lifecycle). */
+    isClaiming: (claimKey: string) => boolean;
+};
+/**
+ * Encapsulates the full "claim winnings" (redeem) lifecycle so multiple
+ * surfaces (the profile positions list, the resolved market trade panel) can
+ * share one implementation instead of duplicating the redeem → WS lifecycle →
+ * toast → cache-invalidation orchestration.
+ *
+ * The flow has two paths:
+ *  - **Internal** (`onClaim` omitted): submit via the redeem mutation, bucket
+ *    the response legs (submitted / confirmed / ineligible / rejected), track
+ *    EVM async legs through their WS lifecycle, and toast pending → submitted →
+ *    success/partial/failed.
+ *  - **Delegated** (`onClaim` provided): the caller performs the redeem; the
+ *    hook only toasts pending → success/failure.
+ *
+ * Both paths invalidate balances, positions, the claimable count, the activity
+ * feed, and the current-user query so dependent UI refreshes.
+ */
+export declare function useClaimWinnings<TPayload = void>(options?: UseClaimWinningsOptions<TPayload>): UseClaimWinningsResult<TPayload>;

package/dist/types/trading/use-claim-winnings.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shape of the `notifications.claim` label block consumed by the claim flow.
+ * Mirrors the typed labels so callers can reason about the toast copy.
+ */
+export type ClaimNotificationLabels = {
+    pendingTitle: string;
+    pendingMessage: string;
+    submittedTitle: string;
+    submittedMessage: string;
+    successTitle: string;
+    successMessage: string;
+    partialTitle: string;
+    partialMessage: (errorReason?: string) => string;
+    failedTitle: string;
+    failedMessage: (errorReason?: string) => string;
+    missingOutcomeMessage: string;
+};
+/** Terminal lifecycle summary forwarded to `onClaimResult`. */
+export type ClaimLifecycleResult = {
+    allConfirmed: boolean;
+    anyFailed: boolean;
+    errorMessage: string | null;
+};
+/** A single claim request keyed by `claimKey`. */
+export type ClaimWinningsInput<TPayload = void> = {
+    /** Stable identifier for the position being claimed (e.g. `marketId`). */
+    claimKey: string;
+    /** Winning venue-market-outcome ids to redeem. */
+    winningOutcomeIds: string[];
+    /** Opaque payload forwarded verbatim to a caller-provided `onClaim`. */
+    payload?: TPayload;
+};
+export type UseClaimWinningsOptions<TPayload = void> = {
+    /**
+     * Caller-owned claim handler. When provided, the hook delegates the actual
+     * redeem to this callback and toasts a simple pending → success/failure
+     * lifecycle (no WS lifecycle tracking). Partners who own the claim flow pass
+     * this; omit it to let the hook drive the internal redeem mutation.
+     */
+    onClaim?: (payload: TPayload) => Promise<void> | void;
+    /**
+     * Fired once per redeem when its WS lifecycle reaches terminal. Only fired on
+     * the internal claim path (i.e. when `onClaim` is omitted).
+     */
+    onClaimResult?: (claimKey: string, lifecycle: ClaimLifecycleResult) => void;
+    /**
+     * Fired when the redeem mutation itself rejects (transport error, validation
+     * error, or all legs ineligible/rejected at submit time). The redeem never
+     * enters the WS lifecycle in these cases, so `onClaimResult` does NOT fire.
+     */
+    onClaimSubmitError?: (claimKey: string, error: Error) => void;
+    /**
+     * Caller-owned spinner map. When provided, it fully replaces the hook's
+     * lifecycle-derived spinner state for display purposes (mirrors the legacy
+     * `claimingPositionKeys ?? internal` behavior).
+     */
+    externalClaimingKeys?: Record<string, boolean>;
+};
+export type UseClaimWinningsResult<TPayload = void> = {
+    /** Start a claim for a single position. Resolves once the submit settles. */
+    claim: (input: ClaimWinningsInput<TPayload>) => Promise<void>;
+    /** Map of claim key → in-flight flag, suitable to pass to a row renderer. */
+    claimingKeys: Record<string, boolean>;
+    /** Whether a given claim key is currently in-flight (submit or lifecycle). */
+    isClaiming: (claimKey: string) => boolean;
+};
+/**
+ * Encapsulates the full "claim winnings" (redeem) lifecycle so multiple
+ * surfaces (the profile positions list, the resolved market trade panel) can
+ * share one implementation instead of duplicating the redeem → WS lifecycle →
+ * toast → cache-invalidation orchestration.
+ *
+ * The flow has two paths:
+ *  - **Internal** (`onClaim` omitted): submit via the redeem mutation, bucket
+ *    the response legs (submitted / confirmed / ineligible / rejected), track
+ *    EVM async legs through their WS lifecycle, and toast pending → submitted →
+ *    success/partial/failed.
+ *  - **Delegated** (`onClaim` provided): the caller performs the redeem; the
+ *    hook only toasts pending → success/failure.
+ *
+ * Both paths invalidate balances, positions, the claimable count, the activity
+ * feed, and the current-user query so dependent UI refreshes.
+ */
+export declare function useClaimWinnings<TPayload = void>(options?: UseClaimWinningsOptions<TPayload>): UseClaimWinningsResult<TPayload>;

package/dist/types/trading/use-resolved-market-claim.d.mts

@@ -0,0 +1,26 @@
+import { type VenueMarket } from "@agg-build/hooks";
+import type { PlaceOrderResolvedClaimSummary } from "./place-order";
+export type UseResolvedMarketClaimOptions = {
+    /** The resolved market whose claimable winnings should be summarized. */
+    market?: VenueMarket | null;
+    /** Gate fetching/computation (e.g. only when the trade panel is resolved). */
+    enabled?: boolean;
+    /** Execution mode — paper positions are fetched from the paper bucket. */
+    executionMode?: "live" | "paper";
+};
+/**
+ * Derives the resolved-market claim summary (resolution date, winning shares,
+ * total payout, and a wired claim action) for the position the current user
+ * holds in `market`, reusing the same redeem flow as the profile positions
+ * list via {@link useClaimWinnings}.
+ *
+ * Returns `undefined` (so the caller renders the plain resolved view) when:
+ *  - fetching is disabled, the user is unauthenticated, or the market is open;
+ *  - the user holds no position in this market;
+ *  - the user's position lost (no winning outcome with shares).
+ *
+ * When the user won but the position is already redeemed / pending / ineligible
+ * (i.e. not `eligible`), the summary is returned WITHOUT an `onClaim` action so
+ * the earnings show without a duplicate claim CTA.
+ */
+export declare function useResolvedMarketClaim(options?: UseResolvedMarketClaimOptions): PlaceOrderResolvedClaimSummary | undefined;

package/dist/types/trading/use-resolved-market-claim.d.ts

@@ -0,0 +1,26 @@
+import { type VenueMarket } from "@agg-build/hooks";
+import type { PlaceOrderResolvedClaimSummary } from "./place-order";
+export type UseResolvedMarketClaimOptions = {
+    /** The resolved market whose claimable winnings should be summarized. */
+    market?: VenueMarket | null;
+    /** Gate fetching/computation (e.g. only when the trade panel is resolved). */
+    enabled?: boolean;
+    /** Execution mode — paper positions are fetched from the paper bucket. */
+    executionMode?: "live" | "paper";
+};
+/**
+ * Derives the resolved-market claim summary (resolution date, winning shares,
+ * total payout, and a wired claim action) for the position the current user
+ * holds in `market`, reusing the same redeem flow as the profile positions
+ * list via {@link useClaimWinnings}.
+ *
+ * Returns `undefined` (so the caller renders the plain resolved view) when:
+ *  - fetching is disabled, the user is unauthenticated, or the market is open;
+ *  - the user holds no position in this market;
+ *  - the user's position lost (no winning outcome with shares).
+ *
+ * When the user won but the position is already redeemed / pending / ineligible
+ * (i.e. not `eligible`), the summary is returned WITHOUT an `onClaim` action so
+ * the earnings show without a duplicate claim CTA.
+ */
+export declare function useResolvedMarketClaim(options?: UseResolvedMarketClaimOptions): PlaceOrderResolvedClaimSummary | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agg-build/ui",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Pre-built React component library for the AGG prediction market aggregator. Tailwind-based, themeable, with primitives, event surfaces, trading flows, full pages, and modals.",
   "sideEffects": false,
   "license": "MIT",
@@ -100,8 +100,8 @@
     "liveline": "^0.0.7",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@agg-build/hooks": "^2.1.1",
-    "@agg-build/sdk": "^2.1.0"
+    "@agg-build/hooks": "^2.1.3",
+    "@agg-build/sdk": "^2.1.3"
   },
   "dependencies": {
     "@number-flow/react": "^0.6.0",