@thorprovider/blocks 4.0.0 → 4.3.0

package/dist/blocks/designs/order-detail/contracts.d.ts

@@ -0,0 +1,717 @@
+import type { ReactNode } from 'react';
+export type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+/** Integer minor units. Formatting belongs to the view or the host. */
+export type Money = {
+    amount: number;
+    currency: string;
+};
+export type SectionId = 'logistics' | 'items' | 'pricing' | 'payments' | 'afterSales' | 'documents' | 'b2b' | 'revisions';
+export type SectionIssue = 'unavailable' | 'error' | 'forbidden';
+export type SettingId = 'productAttributes' | 'logisticsGroups' | 'tracking' | 'pickup' | 'promotions' | 'detailedTaxes' | 'paymentHistory' | 'returns' | 'exchanges' | 'claims' | 'documents' | 'b2b' | 'revisions' | 'customerActions' | 'sensitivePricing';
+export type OrderDetailSettings = Partial<Record<SettingId, boolean>>;
+export declare const SETTING_IDS: SettingId[];
+export declare const DEFAULT_SETTINGS: OrderDetailSettings;
+export type ProductKind = 'physical' | 'digital' | 'bundle' | 'service' | 'configured' | 'custom' | 'serialized' | 'warranty' | 'measured';
+export type AttributeKind = 'variant' | 'commercial' | 'custom';
+export type OrderLineAttribute = {
+    id: string;
+    label: string;
+    value: string;
+    kind: AttributeKind;
+};
+export type TaxLine = {
+    id: string;
+    label: string;
+    /** Display-only rate label, e.g. "16%". Never used to recalculate. */
+    rate?: string;
+    amount: Money;
+    included?: boolean;
+    exemption?: boolean;
+};
+export type Adjustment = {
+    id: string;
+    label: string;
+    scope: 'product' | 'order' | 'shipping' | 'payment';
+    direction: 'discount' | 'surcharge';
+    amount: Money;
+    source: 'promotion' | 'manual' | 'contract' | 'tax';
+    promotionId?: string;
+};
+export type PriceKind = 'list' | 'volume' | 'contract' | 'customer' | 'promotion';
+export type OrderLine = {
+    id: string;
+    /** Catalog identity, kept only for adapters; never rendered. */
+    productId?: string;
+    name: string;
+    sku: string;
+    image?: string;
+    variant?: string;
+    quantity: number;
+    /** Quantity cancelled after creation; never inferred from totals. */
+    cancelledQuantity: number;
+    unitPrice: {
+        original: Money;
+        applied: Money;
+        kind: PriceKind;
+    };
+    /** Gross historical subtotal for the chargeable quantity. */
+    subtotal: Money;
+    /** Explanatory product-scope discounts; already inside the applied price. */
+    discounts: Adjustment[];
+    taxes: TaxLine[];
+    /** Authoritative charged amount for this line, taxes included. */
+    total: Money;
+    attributes: OrderLineAttribute[];
+    kind: ProductKind;
+    serialNumber?: string;
+    warranty?: string;
+    measure?: {
+        quantity: number;
+        unit: string;
+    };
+    bundle?: {
+        name: string;
+        sku: string;
+        quantity: number;
+    }[];
+    note?: string;
+};
+export type FulfillmentStatus = 'pending' | 'preparing' | 'shipped' | 'delivered' | 'partially_delivered' | 'ready_for_pickup' | 'picked_up' | 'cancelled';
+export type FulfillmentAllocation = {
+    lineId: string;
+    quantity: number;
+};
+export type TrackingEvent = {
+    id: string;
+    at: string;
+    label: string;
+    place?: string;
+};
+export type PackageRef = {
+    id: string;
+    label: string;
+};
+export type PickupDetails = {
+    locationName: string;
+    address: string;
+    schedule: string;
+    instructions?: string;
+    status: 'scheduled' | 'ready' | 'picked_up' | 'expired';
+    availableFrom?: string;
+    expiresAt?: string;
+    code?: string;
+    evidence?: string;
+};
+export type Fulfillment = {
+    id: string;
+    groupId: string;
+    status: FulfillmentStatus;
+    carrier?: string;
+    provider?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    shippedAt?: string;
+    deliveredAt?: string;
+    packages: PackageRef[];
+    events: TrackingEvent[];
+    allocations: FulfillmentAllocation[];
+    pickup?: PickupDetails;
+    evidence?: string;
+};
+export type ShippingMethod = {
+    id: string;
+    name: string;
+    description?: string;
+    /** Internal warehouse/profile ids are never rendered. */
+    profileId?: string;
+};
+export type LogisticsGroup = {
+    id: string;
+    mode: 'shipping' | 'pickup';
+    method: ShippingMethod;
+    shippingSubtotal: Money;
+    discounts: Adjustment[];
+    taxes: TaxLine[];
+    /** Authoritative group total, shipping taxes included. */
+    total: Money;
+    etaLabel?: string;
+    pickup?: PickupDetails;
+};
+export type PromotionType = 'fixed-product' | 'percent-product' | 'fixed-order' | 'percent-order' | 'buy-x-get-y' | 'free-shipping' | 'shipping-discount' | 'payment-method-discount' | 'financing-benefit' | 'provider-incentive';
+export type PromotionScope = 'product' | 'order' | 'shipping' | 'payment';
+export type PromotionNominal = {
+    kind: 'percent';
+    percent: number;
+} | {
+    kind: 'fixed';
+    money: Money;
+};
+export type BuyXGetY = {
+    conditionLineIds: string[];
+    rewardLineIds: string[];
+    rewardQuantity: number;
+    freeQuantity: number;
+    partial: boolean;
+};
+export type Promotion = {
+    id: string;
+    code?: string;
+    name: string;
+    type: PromotionType;
+    scope: PromotionScope;
+    application: 'automatic' | 'code';
+    nominal: PromotionNominal;
+    /** Effective historical amount. Must equal its linked adjustments. */
+    discounted: Money;
+    lineIds: string[];
+    groupIds?: string[];
+    adjustmentIds: string[];
+    buyXGetY?: BuyXGetY;
+};
+export type PromotionPresentationScope = 'item' | 'shipping' | 'order' | 'payment' | 'unknown';
+/**
+ * One promotion benefit as it materialises in the order. `appliedAmount` always
+ * comes from the linked persisted adjustment(s), never from the nominal value or
+ * a re-run rule.
+ */
+export type PromotionPresentation = {
+    /** Unique presentation entry: promotion + scope + target. */
+    id: string;
+    promotionId: string;
+    adjustmentIds: string[];
+    name: string;
+    code?: string;
+    scope: PromotionPresentationScope;
+    targetId?: string;
+    appliedAmount: Money;
+    promotionType?: PromotionType;
+    description?: string;
+    buyXGetY?: BuyXGetY;
+};
+export type PromotionPresentationModel = {
+    items: Record<string, PromotionPresentation[]>;
+    shipping: Record<string, PromotionPresentation[]>;
+    order: PromotionPresentation[];
+    payment: PromotionPresentation[];
+    unknown: PromotionPresentation[];
+};
+export type TransactionKind = 'payment' | 'authorization' | 'refund' | 'credit';
+export type TransactionStatus = 'pending' | 'authorized' | 'captured' | 'refunded' | 'failed';
+export type PaymentMethodKind = 'card' | 'wallet' | 'transfer' | 'credit' | 'cash';
+export type Transaction = {
+    id: string;
+    kind: TransactionKind;
+    status: TransactionStatus;
+    amount: Money;
+    at: string;
+    method: PaymentMethodKind;
+    reference?: string;
+    note?: string;
+};
+export type AfterSalesType = 'return' | 'exchange' | 'claim';
+export type AfterSalesStatus = 'requested' | 'approved' | 'in_transit' | 'received' | 'completed' | 'rejected';
+export type AfterSalesLine = {
+    lineId: string;
+    quantity: number;
+};
+export type AfterSalesCase = {
+    id: string;
+    type: AfterSalesType;
+    status: AfterSalesStatus;
+    createdAt: string;
+    reason: string;
+    lines: AfterSalesLine[];
+    refund?: Money;
+    replacement?: {
+        name: string;
+        sku: string;
+        quantity: number;
+    }[];
+    shipment?: {
+        carrier?: string;
+        trackingNumber?: string;
+        trackingUrl?: string;
+        status?: string;
+    };
+    availableActions: OrderActionId[];
+};
+export type DocumentKind = 'invoice' | 'receipt' | 'payment-proof' | 'credit-note' | 'shipping' | 'business';
+export type OrderDocument = {
+    id: string;
+    kind: DocumentKind;
+    label: string;
+    issuedAt?: string;
+    /** Only available documents are rendered with an action. */
+    available: boolean;
+};
+export type InvoiceStatus = 'not_issued' | 'pending' | 'issued' | 'overdue';
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected';
+export type OrderBusiness = {
+    company: string;
+    buyer: string;
+    branch?: string;
+    purchaseOrder?: string;
+    internalReference?: string;
+    costCenter?: string;
+    paymentTerms?: string;
+    creditLimit?: Money;
+    creditUsed?: Money;
+    dueAt?: string;
+    invoiceStatus?: InvoiceStatus;
+    approval?: {
+        status: ApprovalStatus;
+        by?: string;
+        at?: string;
+    };
+};
+export type RevisionKind = 'item-added' | 'item-removed' | 'quantity' | 'price' | 'shipping' | 'tax' | 'cancel';
+export type OrderRevision = {
+    id: string;
+    at: string;
+    kind: RevisionKind;
+    summary: string;
+    delta?: Money;
+};
+export type Address = {
+    name: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+};
+export type MoneySummary = {
+    itemsSubtotal: Money;
+    itemDiscounts: Money;
+    orderDiscounts: Money;
+    shippingSubtotal: Money;
+    shippingDiscounts: Money;
+    tax: Money;
+    adjustments: Money;
+    total: Money;
+};
+export type OrderActionId = 'reorder' | 'invoice' | 'track' | 'return' | 'exchange' | 'problem' | 'cancel' | 'pay-balance' | 'support';
+export declare const ORDER_ACTIONS: OrderActionId[];
+export type CommercialStatus = 'pending' | 'processing' | 'completed' | 'cancelled';
+export type PresentationStatusId = 'pending' | 'processing' | 'shipped' | 'partially-delivered' | 'delivered' | 'completed' | 'ready-for-pickup' | 'delayed' | 'attention' | 'refunded' | 'partially-refunded' | 'cancelled';
+export type PaymentStatusId = 'unpaid' | 'authorized' | 'partially_paid' | 'paid' | 'partially_refunded' | 'refunded' | 'not_charged';
+export type LineStatusId = 'unfulfilled' | 'preparing' | 'ready_for_pickup' | 'partially_sent' | 'sent' | 'partially_delivered' | 'delivered' | 'cancelled' | 'returned';
+export type OrderDetailOrder = {
+    id: string;
+    number: string;
+    createdAt: string;
+    updatedAt: string;
+    currency: string;
+    commercial: CommercialStatus;
+    logistics: {
+        status: FulfillmentStatus;
+        delayed?: boolean;
+    };
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    lines: OrderLine[];
+    groups: LogisticsGroup[];
+    fulfillments: Fulfillment[];
+    promotions: Promotion[];
+    adjustments: Adjustment[];
+    transactions: Transaction[];
+    cases: AfterSalesCase[];
+    documents: OrderDocument[];
+    business?: OrderBusiness;
+    revisions: OrderRevision[];
+    totals: MoneySummary;
+    availableActions: OrderActionId[];
+};
+export type OrderDetailSnapshot = {
+    order: OrderDetailOrder;
+    /** Per-section issues from a partial load. Absent means the section is valid. */
+    issues?: Partial<Record<SectionId, SectionIssue>>;
+    warning?: boolean;
+};
+export type OrderDetailDataSource = {
+    get(orderId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<OrderDetailSnapshot>;
+};
+export type QuantityView = {
+    ordered: number;
+    cancelled: number;
+    sent: number;
+    delivered: number;
+    pending: number;
+    returned: number;
+};
+export type LineFulfillment = {
+    fulfillmentId: string;
+    groupName: string;
+    status: FulfillmentStatus;
+    quantity: number;
+};
+export type EconomicSummary = {
+    itemsSubtotal: Money;
+    itemDiscounts: Money;
+    orderDiscounts: Money;
+    paymentAdjustments: Money;
+    shippingSubtotal: Money;
+    shippingDiscounts: Money;
+    shippingAdjustments: Money;
+    tax: Money;
+    adjustments: Money;
+    /** Recomputed from line/group/order totals. */
+    computedTotal: Money;
+    /** Authoritative total supplied by the backend. */
+    total: Money;
+    reconciles: boolean;
+    paid: Money;
+    refunded: Money;
+    net: Money;
+    due: Money;
+    credit: Money;
+};
+export type PromotionView = {
+    promotion: Promotion;
+    effective: Money;
+    lines: {
+        id: string;
+        name: string;
+        quantity: number;
+    }[];
+    groups: string[];
+    /** True when the linked adjustments do not add up to `discounted`. */
+    inconsistent: boolean;
+};
+export type Scenario = {
+    id: string;
+    name: string;
+    blurb: string;
+    orderId: string;
+    mode?: 'b2c' | 'b2b';
+    settings?: OrderDetailSettings;
+    latencyMs?: number;
+    fail?: boolean;
+    partial?: boolean;
+};
+export type PresentationDensity = 'auto' | 'compact' | 'detailed';
+/**
+ * Presentation-only configuration. It changes what is visible initially and
+ * how dense the surface is; it never changes data, amounts or permissions.
+ */
+export type OrderDetailPresentationConfig = {
+    density: PresentationDensity;
+    showTechnicalDetailsByDefault: boolean;
+    expandActiveDeliveries: boolean;
+    compactCompletedOrders: boolean;
+    showFinancialSidebar: boolean;
+    showProductImages: boolean;
+    showEmptySections: boolean;
+};
+export declare const DEFAULT_PRESENTATION: OrderDetailPresentationConfig;
+export type OrderDetailLabels = {
+    header: {
+        back: string;
+        title: string;
+        placedAt: string;
+        items: string;
+        itemsOne: string;
+        total: string;
+        reference: string;
+        businessReference: string;
+    };
+    status: Record<PresentationStatusId, string>;
+    paymentStatus: Record<PaymentStatusId, string>;
+    fulfilmentStatus: Record<FulfillmentStatus, string>;
+    lineStatus: Record<LineStatusId, string>;
+    summary: {
+        payment: string;
+        logistics: string;
+        returns: string;
+        progress: string;
+        progressValue: string;
+        noReturns: string;
+        openCase: string;
+        openCaseOne: string;
+        shippingAddress: string;
+        billingAddress: string;
+        taxId?: string;
+    };
+    logistics: {
+        title: string;
+        description: string;
+        group: string;
+        shipping: string;
+        pickup: string;
+        method: string;
+        eta: string;
+        cost: string;
+        originalCost: string;
+        finalCost: string;
+        promotion: string;
+        shippingFree: string;
+        discounts: string;
+        taxes: string;
+        total: string;
+        contents: string;
+        shipment: string;
+        carrier: string;
+        provider: string;
+        trackingNumber: string;
+        track: string;
+        noTracking: string;
+        packages: string;
+        events: string;
+        shippedAt: string;
+        deliveredAt: string;
+        evidence: string;
+        pickupTitle: string;
+        pickupFulfillment: string;
+        pickupPoint: string;
+        pickupState: string;
+        address: string;
+        schedule: string;
+        instructions: string;
+        availableFrom: string;
+        expiresAt: string;
+        code: string;
+        pickupStatus: Record<PickupDetails['status'], string>;
+        units: string;
+        completed: string;
+        pickupCompleted: string;
+        inProgress: string;
+        groupSummary: string;
+        groupSummaryOne: string;
+        pendingUnits: string;
+        pendingPickup: string;
+        details: string;
+        hideDetails: string;
+    };
+    items: {
+        title: string;
+        description: string;
+        quantity: string;
+        sku: string;
+        variant: string;
+        originalPrice: string;
+        appliedPrice: string;
+        subtotal: string;
+        productsPrice: string;
+        discounts: string;
+        adjustment: string;
+        taxes: string;
+        lineTotal: string;
+        finalPrice: string;
+        calculation: string;
+        attributes: string;
+        variantAttributes: string;
+        commercialAttributes: string;
+        customAttributes: string;
+        bundleContents: string;
+        serial: string;
+        warranty: string;
+        measure: string;
+        sent: string;
+        delivered: string;
+        pending: string;
+        cancelled: string;
+        returned: string;
+        units: string;
+        details: string;
+        hideDetails: string;
+        saved: string;
+        distribution: string;
+        imageAlt: string;
+        noImage: string;
+        priceHidden: string;
+        priceKinds: Record<PriceKind, string>;
+        kinds: Record<ProductKind, string>;
+    };
+    promotions: {
+        title: string;
+        description: string;
+        code: string;
+        coupon: string;
+        automatic: string;
+        origin: string;
+        scope: Record<PromotionScope, string>;
+        type: Record<PromotionType, string>;
+        nominal: string;
+        effective: string;
+        affectedLines: string;
+        affectedShipping: string;
+        totalSaved: string;
+        youSave: string;
+        discountsApplied: string;
+        paymentTitle: string;
+        unassigned: string;
+        buyXGetYTitle: string;
+        condition: string;
+        reward: string;
+        rewardQuantity: string;
+        freeQuantity: string;
+        partial: string;
+        confirmedOnly: string;
+        none: string;
+        inconsistent: string;
+    };
+    pricing: {
+        title: string;
+        description: string;
+        itemsSubtotal: string;
+        itemDiscounts: string;
+        priceAdjustments: string;
+        orderDiscounts: string;
+        shippingSubtotal: string;
+        shippingDiscounts: string;
+        shippingAdjustments: string;
+        tax: string;
+        taxBreakdown: string;
+        adjustments: string;
+        total: string;
+        paid: string;
+        refunded: string;
+        due: string;
+        credit: string;
+        inconsistent: string;
+    };
+    payments: {
+        title: string;
+        description: string;
+        date: string;
+        method: string;
+        status: string;
+        kind: string;
+        reference: string;
+        amount: string;
+        none: string;
+        refundsTitle: string;
+        refunded: string;
+        pendingBalance: string;
+        movements: string;
+        movementsOne: string;
+        methods: Record<PaymentMethodKind, string>;
+        statuses: Record<TransactionStatus, string>;
+        kinds: Record<TransactionKind, string>;
+    };
+    afterSales: {
+        title: string;
+        description: string;
+        returnsTitle: string;
+        returnsDescription: string;
+        exchangesTitle: string;
+        exchangesDescription: string;
+        claimsTitle: string;
+        claimsDescription: string;
+        createdAt: string;
+        reason: string;
+        items: string;
+        refund: string;
+        replacement: string;
+        tracking: string;
+        status: Record<AfterSalesStatus, string>;
+        types: Record<AfterSalesType, string>;
+        empty: string;
+        cases: string;
+        casesOne: string;
+    };
+    documents: {
+        title: string;
+        description: string;
+        issuedAt: string;
+        download: string;
+        view: string;
+        kinds: Record<DocumentKind, string>;
+        empty: string;
+        count: string;
+        countOne: string;
+    };
+    b2b: {
+        title: string;
+        description: string;
+        company: string;
+        buyer: string;
+        branch: string;
+        purchaseOrder: string;
+        internalReference: string;
+        costCenter: string;
+        paymentTerms: string;
+        creditLimit: string;
+        creditUsed: string;
+        dueAt: string;
+        invoiceStatus: string;
+        approval: string;
+        approvedBy: string;
+        restricted: string;
+        invoiceStatuses: Record<InvoiceStatus, string>;
+        approvalStatuses: Record<ApprovalStatus, string>;
+    };
+    revisions: {
+        title: string;
+        description: string;
+        delta: string;
+        kinds: Record<RevisionKind, string>;
+        none: string;
+        count: string;
+        countOne: string;
+    };
+    actions: Record<OrderActionId, string>;
+    moreActions: string;
+    addresses: {
+        title: string;
+        shipping: string;
+        billing: string;
+    };
+    states: {
+        loading: string;
+        errorTitle: string;
+        errorBody: string;
+        retry: string;
+        forbiddenTitle: string;
+        forbiddenBody: string;
+        notFoundTitle: string;
+        notFoundBody: string;
+        partial: string;
+        sectionUnavailable: string;
+        sectionError: string;
+        sectionForbidden: string;
+    };
+    demo: {
+        title: string;
+        hint: string;
+        scenario: string;
+        mode: string;
+        modeB2c: string;
+        modeB2b: string;
+        density: string;
+        densityAuto: string;
+        densityCompact: string;
+        densityDetailed: string;
+        settings: string;
+        callback: string;
+        callbackFormat: string;
+        noCallback: string;
+        note: string;
+        settingLabels: Record<SettingId, string>;
+    };
+};
+export type OrderDetailProps = {
+    orderId: string;
+    dataSource: OrderDetailDataSource;
+    settings?: OrderDetailSettings;
+    labels: OrderDetailLabels;
+    locale?: string;
+    formatMoney?: (money: Money) => string;
+    formatDate?: (iso: string) => string;
+    access?: 'allowed' | 'forbidden';
+    openSections?: SectionId[];
+    /** Adaptive presentation. Defaults to `auto`. */
+    presentation?: Partial<OrderDetailPresentationConfig>;
+    onBack?: () => void;
+    onAction?: (action: OrderActionId) => void;
+    /** Case-scoped action (return/exchange/claim). Falls back to `onAction`. */
+    onCaseAction?: (action: OrderActionId, caseId: string) => void;
+    onDocument?: (document: OrderDocument) => void;
+    /** Render-only slot for the host (breadcrumbs, page chrome). */
+    headerActions?: ReactNode;
+};
+//# sourceMappingURL=contracts.d.ts.map