@antscorp/antsomi-ui 1.3.7-beta.67 → 1.3.7-beta.68

package/es/components/organism/AllocateCoupon/components/PoolField.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import clsx from 'clsx';
+// Components
+import { FieldRow } from './FieldRow';
+import { Select } from '../../../molecules/Select';
+// Context
+import { useAllocateCouponContext } from '../contexts/AllocateCouponContext';
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+const { t } = i18nInstance;
+export const PoolField = props => {
+    const { pool: poolOverride, className, style, classNames, styles } = props;
+    const contextPool = useAllocateCouponContext(store => store.pool);
+    const pool = poolOverride ?? contextPool;
+    return (_jsx(FieldRow, { label: t(translations.allocateCoupon.poolField.label), required: true, helpText: pool.helpText, className: clsx('antsomi-allocate-coupon-pool-field-row', className), style: style, classNames: { label: classNames?.label, helpText: classNames?.helpText }, styles: { label: styles?.label, helpText: styles?.helpText }, children: _jsx(Select, { showSearch: true, loading: pool.isLoading, value: pool.selectedId ?? undefined, placeholder: t(translations.allocateCoupon.poolField.placeholder), className: clsx('antsomi-allocate-coupon-pool-select', classNames?.select), style: styles?.select, options: pool.options.map(option => ({ value: option.id, label: option.name })), onChange: pool.onSelect }) }));
+};

package/es/components/organism/AllocateCoupon/components/QuantityField.d.ts

@@ -0,0 +1,20 @@
+import React, { ReactNode } from 'react';
+import type { AllocateCouponConditionsState, AllocateCouponQuantityState, AllocateCouponSourceEventState, ConditionOperatorOptionsResolver, ConditionValueRenderer, SlotStyleProps, SourceEventGroupResolver } from '../types';
+export type QuantityFieldSlot = 'label' | 'modeToggle' | 'fixedValue' | 'eventPanel' | 'sourceEvent' | 'calcMethod' | 'field' | 'conditions' | 'fallback';
+export interface QuantityFieldProps extends SlotStyleProps<QuantityFieldSlot> {
+    quantity?: AllocateCouponQuantityState;
+    sourceEvent?: AllocateCouponSourceEventState;
+    conditions?: AllocateCouponConditionsState;
+    /** Forwarded to the internal `ConditionsField` when using the default (non-`children`)
+     * composition — see `ConditionValueRenderer`. */
+    renderValue?: ConditionValueRenderer;
+    /** Forwarded to the internal `ConditionsField` when using the default (non-`children`)
+     * composition — see `ConditionOperatorOptionsResolver`. */
+    getOperatorOptions?: ConditionOperatorOptionsResolver;
+    /** Forwarded to the internal `SourceEventField` when using the default (non-`children`)
+     * composition — see `SourceEventGroupResolver`. */
+    getSourceEventGroup?: SourceEventGroupResolver;
+    /** Custom internal composition — defaults to the spec order when omitted */
+    children?: ReactNode;
+}
+export declare const QuantityField: React.FC<QuantityFieldProps>;

package/es/components/organism/AllocateCoupon/components/QuantityField.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import clsx from 'clsx';
+// Components
+import { InputNumber, Radio, RadioGroupSub, RequiredLabel, Text, } from '@antscorp/antsomi-ui/es/components/atoms';
+import { SelectV2 as Select } from '@antscorp/antsomi-ui/es/components/molecules';
+import { TreeSelect } from '../../../molecules/TreeSelect';
+import { FieldRow } from './FieldRow';
+import { SourceEventField } from './SourceEventField';
+import { ConditionsField } from './ConditionsField';
+// Context
+import { useAllocateCouponContext } from '../contexts/AllocateCouponContext';
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+// Constants
+import { CALC_METHOD_OPTIONS } from '../constants';
+import { FALLBACK_MODE, QUANTITY_MODE } from '../types';
+// Utils
+import { toQuantityFieldOptions } from '../utils';
+const { t } = i18nInstance;
+export const QuantityField = props => {
+    const { quantity: quantityOverride, sourceEvent: sourceEventOverride, conditions: conditionsOverride, renderValue, getOperatorOptions, getSourceEventGroup, className, style, classNames, styles, children, } = props;
+    const contextPool = useAllocateCouponContext(store => store.pool);
+    const contextQuantity = useAllocateCouponContext(store => store.quantity);
+    const contextSourceEvent = useAllocateCouponContext(store => store.sourceEvent);
+    const quantity = quantityOverride ?? contextQuantity;
+    const sourceEvent = sourceEventOverride ?? contextSourceEvent;
+    const treeData = toQuantityFieldOptions(quantity.fieldOptions);
+    const selectedFieldValue = quantity.field
+        ? quantity.field.itemTypeId
+            ? `${quantity.field.itemTypeId}.${quantity.field.propertyName}`
+            : quantity.field.propertyName || undefined
+        : undefined;
+    const onChangeFieldValue = (value) => {
+        const [itemTypeIdPart, ...rest] = value.split('.');
+        const hasItemTypeId = rest.length > 0;
+        const flat = quantity.fieldOptions.flatMap(option => option.children?.length ? option.children : [option]);
+        const match = flat.find(option => hasItemTypeId
+            ? String(option.itemTypeId) === itemTypeIdPart && option.propertyName === rest.join('.')
+            : option.propertyName === value);
+        if (match) {
+            quantity.onChangeField?.({
+                itemTypeId: match.itemTypeId,
+                propertyName: match.propertyName,
+                propertyLabel: match.propertyLabel,
+                dataType: match.dataType,
+            });
+        }
+    };
+    const isCalculateFromEvent = quantity.mode === QUANTITY_MODE.CALCULATE_FROM_EVENT;
+    // Never hides an already-selected mode (e.g. if the upstream trigger is later removed).
+    const showCalculateFromEventOption = sourceEvent.list.length > 0 || isCalculateFromEvent;
+    if (!contextPool.selectedId) {
+        return null;
+    }
+    return (_jsx(FieldRow, { label: t(translations.allocateCoupon.quantityField.label), required: true, className: className, style: style, classNames: { label: classNames?.label }, styles: { label: styles?.label }, children: _jsxs("div", { className: clsx('antsomi-allocate-coupon-quantity-mode-stack', classNames?.modeToggle), style: styles?.modeToggle, children: [_jsxs(RadioGroupSub, { value: quantity.mode, onChange: event => quantity.onChangeMode?.(event.target.value), children: [_jsxs(Radio, { value: QUANTITY_MODE.FIXED, children: [t(translations.allocateCoupon.quantityField.allocatePrefix), ' ', _jsx(InputNumber, { size: "small", min: 1, disabled: quantity.mode !== QUANTITY_MODE.FIXED, value: quantity.fixedValue ?? undefined, placeholder: t(translations.allocateCoupon.quantityField.enterNumber), className: classNames?.fixedValue, style: styles?.fixedValue, onChange: value => quantity.onChangeFixedValue?.(value ?? null) }), ' ', t(translations.allocateCoupon.quantityField.codesPerTime)] }), showCalculateFromEventOption && (_jsx(Radio, { value: QUANTITY_MODE.CALCULATE_FROM_EVENT, children: t(translations.allocateCoupon.quantityField.calculateFromEvent) }))] }), isCalculateFromEvent &&
+                    (children ?? (_jsxs("div", { className: clsx('antsomi-allocate-coupon-indented-panel', classNames?.eventPanel), style: styles?.eventPanel, children: [_jsxs("div", { className: "antsomi-allocate-coupon-three-column-row", children: [_jsxs("div", { children: [_jsx(RequiredLabel, { isReverseMask: true, type: "secondary", children: t(translations.allocateCoupon.quantityField.eventLabel) }), _jsx(SourceEventField, { sourceEvent: sourceEventOverride, getSourceEventGroup: getSourceEventGroup, className: classNames?.sourceEvent, style: styles?.sourceEvent })] }), _jsxs("div", { children: [_jsx(RequiredLabel, { isReverseMask: true, type: "secondary", children: t(translations.allocateCoupon.quantityField.calcMethodLabel) }), _jsx(Select, { className: classNames?.calcMethod, style: styles?.calcMethod, value: quantity.calcMethod, options: CALC_METHOD_OPTIONS, onChange: (value) => quantity.onChangeCalcMethod?.(value) })] }), _jsxs("div", { children: [_jsx(RequiredLabel, { isReverseMask: true, type: "secondary", children: t(translations.allocateCoupon.quantityField.attributeLabel) }), _jsx(TreeSelect, { showSearch: true, className: classNames?.field, style: styles?.field, value: selectedFieldValue, placeholder: t(translations.allocateCoupon.quantityField.selectAttribute), treeData: treeData, loading: quantity.isFieldOptionsLoading, onChange: onChangeFieldValue })] })] }), _jsx(Text, { type: "secondary", children: t(translations.allocateCoupon.quantityField.onlyIncludeDataMatching) }), _jsx("div", { className: classNames?.conditions, style: styles?.conditions, children: _jsx(ConditionsField, { conditions: conditionsOverride, renderValue: renderValue, getOperatorOptions: getOperatorOptions }) }), _jsx(FieldRow, { label: t(translations.allocateCoupon.quantityField.whenNoDataMatches), required: true, className: clsx(classNames?.fallback, 'antsomi-allocate-coupon-fallback'), style: styles?.fallback, children: _jsxs(RadioGroupSub, { value: quantity.fallback.mode, onChange: event => quantity.onChangeFallbackMode?.(event.target.value), children: [_jsx(Radio, { value: FALLBACK_MODE.END_JOURNEY, children: t(translations.allocateCoupon.quantityField.endJourney) }), _jsxs(Radio, { value: FALLBACK_MODE.ALLOCATE_FIXED, children: [t(translations.allocateCoupon.quantityField.allocateFixedFallback), _jsx(InputNumber, { size: "small", min: 1, disabled: quantity.fallback.mode !== FALLBACK_MODE.ALLOCATE_FIXED, value: quantity.fallback.fixedValue ?? undefined, placeholder: t(translations.allocateCoupon.quantityField.enterNumber), onChange: value => quantity.onChangeFallbackFixedValue?.(value ?? null) })] })] }) })] })))] }) }));
+};

package/es/components/organism/AllocateCoupon/components/RefreshButton.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { AllocateCouponRefreshState, SlotStyleProps } from '../types';
+export type RefreshButtonSlot = 'button';
+export interface RefreshButtonProps extends SlotStyleProps<RefreshButtonSlot> {
+    /** Override the value read from context — mainly for Storybook/tests */
+    refresh?: AllocateCouponRefreshState;
+}
+/**
+ * Manual refresh for all 5 underlying queries at once (`refresh.onRefresh`, from the headless
+ * hook) — not tied to any single field, so it reads a dedicated `refresh` context slice rather
+ * than one of the field slices. Same override-prop pattern as every other field component, for
+ * standalone Storybook/test rendering without a `Root` ancestor.
+ */
+export declare const RefreshButton: React.FC<RefreshButtonProps>;

package/es/components/organism/AllocateCoupon/components/RefreshButton.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Components
+import { Button, Icon } from '@antscorp/antsomi-ui/es/components/atoms';
+// Context
+import { useAllocateCouponContext } from '../contexts/AllocateCouponContext';
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+const { t } = i18nInstance;
+/**
+ * Manual refresh for all 5 underlying queries at once (`refresh.onRefresh`, from the headless
+ * hook) — not tied to any single field, so it reads a dedicated `refresh` context slice rather
+ * than one of the field slices. Same override-prop pattern as every other field component, for
+ * standalone Storybook/test rendering without a `Root` ancestor.
+ */
+export const RefreshButton = props => {
+    const { refresh: refreshOverride, className, style } = props;
+    const contextRefresh = useAllocateCouponContext(store => store.refresh);
+    const refresh = refreshOverride ?? contextRefresh;
+    return (_jsx(Button, { type: "default", shape: "round", loading: refresh.isRefreshing, icon: refresh.isRefreshing ? undefined : _jsx(Icon, { type: "icon-ants-refresh-1", size: 12 }), className: className, style: { width: 'fit-content', ...style }, onClick: () => refresh.onRefresh?.(), children: t(translations.allocateCoupon.refreshButton.label) }));
+};

package/es/components/organism/AllocateCoupon/components/Root.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { AllocateCouponState } from '../types';
+export interface AllocateCouponRootProps extends Partial<AllocateCouponState> {
+    children?: React.ReactNode;
+}
+/**
+ * Provider-only wrapper — no layout of its own. Every `AllocateCoupon.*` field component reads
+ * its slice of state via context, so it can be mounted anywhere under `Root`, in any order.
+ */
+export declare const Root: React.FC<React.PropsWithChildren<AllocateCouponRootProps>>;

package/es/components/organism/AllocateCoupon/components/Root.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Hooks
+import { useAllocateCouponStore } from '../hooks/useAllocateCouponStore';
+import { useAllocateCouponSync } from '../hooks/useAllocateCouponSync';
+// Providers
+import { AllocateCouponProvider } from '../providers/AllocateCouponProvider';
+const RootSync = props => {
+    const { children, ...rest } = props;
+    useAllocateCouponSync(rest);
+    return children;
+};
+/**
+ * Provider-only wrapper — no layout of its own. Every `AllocateCoupon.*` field component reads
+ * its slice of state via context, so it can be mounted anywhere under `Root`, in any order.
+ */
+export const Root = props => {
+    const { children, ...rest } = props;
+    const store = useAllocateCouponStore(rest);
+    return (_jsx(AllocateCouponProvider, { store: store, children: _jsx(RootSync, { ...rest, children: children }) }));
+};

package/es/components/organism/AllocateCoupon/components/SourceEventField.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { AllocateCouponSourceEventState, SlotStyleProps, SourceEventGroupResolver } from '../types';
+export type SourceEventFieldSlot = 'select' | 'item';
+export interface SourceEventFieldProps extends SlotStyleProps<SourceEventFieldSlot> {
+    sourceEvent?: AllocateCouponSourceEventState;
+    getSourceEventGroup?: SourceEventGroupResolver;
+}
+/**
+ * The ancestor Trigger/Wait-for-Event node's event(s), rendered as a searchable dropdown
+ * grouped via the consumer-supplied `getSourceEventGroup` resolver (e.g. "Action based trigger"
+ * / "Wait for event" — per the design). The store already models this as selectable
+ * (`selectedKey`/`onSelect`) even though the resolution itself is derived, not freely authored —
+ * with a single upstream event the dropdown just has one (pre-selected) option.
+ */
+export declare const SourceEventField: React.FC<SourceEventFieldProps>;

package/es/components/organism/AllocateCoupon/components/SourceEventField.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Libraries
+import { useMemo } from 'react';
+// Components
+import { SelectV2 as Select } from '@antscorp/antsomi-ui/es/components/molecules';
+import { EventRefDisplay } from './EventRefDisplay';
+// Context
+import { useAllocateCouponContext } from '../contexts/AllocateCouponContext';
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+// Utils
+import { buildSourceEventKey } from '../utils';
+const { t } = i18nInstance;
+const UNGROUPED_KEY = 'UNGROUPED';
+/**
+ * The ancestor Trigger/Wait-for-Event node's event(s), rendered as a searchable dropdown
+ * grouped via the consumer-supplied `getSourceEventGroup` resolver (e.g. "Action based trigger"
+ * / "Wait for event" — per the design). The store already models this as selectable
+ * (`selectedKey`/`onSelect`) even though the resolution itself is derived, not freely authored —
+ * with a single upstream event the dropdown just has one (pre-selected) option.
+ */
+export const SourceEventField = props => {
+    const { sourceEvent: sourceEventOverride, getSourceEventGroup, className, style, classNames, styles, } = props;
+    const contextSourceEvent = useAllocateCouponContext(store => store.sourceEvent);
+    const sourceEvent = sourceEventOverride ?? contextSourceEvent;
+    const groupedOptions = useMemo(() => {
+        const groups = new Map();
+        sourceEvent.list.forEach(ref => {
+            const group = getSourceEventGroup?.(ref) ?? {
+                groupKey: UNGROUPED_KEY,
+                groupLabel: t(translations.allocateCoupon.sourceEventField.ungroupedLabel),
+            };
+            const option = {
+                value: buildSourceEventKey(ref),
+                label: (_jsx(EventRefDisplay, { eventRef: ref, hookError: sourceEvent.error, className: classNames?.item, style: styles?.item })),
+            };
+            const bucket = groups.get(group.groupKey) ?? { groupLabel: group.groupLabel, options: [] };
+            bucket.options.push(option);
+            groups.set(group.groupKey, bucket);
+        });
+        return Array.from(groups.values()).map(({ groupLabel, options }) => ({
+            label: groupLabel,
+            options,
+        }));
+    }, [sourceEvent.list, sourceEvent.error, getSourceEventGroup, classNames?.item, styles?.item]);
+    return (_jsx(Select, { showSearch: true, loading: sourceEvent.isLoading, disabled: !sourceEvent.list.length, value: sourceEvent.selectedKey ?? undefined, placeholder: t(translations.allocateCoupon.sourceEventField.noUpstreamNode), className: classNames?.select ?? className, style: { width: '100%', ...style, ...styles?.select }, options: groupedOptions, filterOption: (input, option) => typeof option?.label === 'string'
+            ? option.label.toLowerCase().includes(input.toLowerCase())
+            : true, onChange: value => sourceEvent.onSelect?.(value) }));
+};

package/es/components/organism/AllocateCoupon/constants/index.d.ts

@@ -0,0 +1,59 @@
+import { AllocateCouponState, CALC_METHOD, FALLBACK_MODE, GET_DATA_FROM, QUANTITY_MODE } from '../types';
+export { QUANTITY_MODE, CALC_METHOD, FALLBACK_MODE, GET_DATA_FROM };
+export declare const CALC_METHOD_OPTIONS: ({
+    label: string;
+    value: "SUM";
+} | {
+    label: string;
+    value: "COUNT";
+})[];
+/** Generic operator set for condition rows, used until each field's real `dataType` is threaded
+ * through `useGetListEventAttr`/`useGetListAttributeBO` — see plan §9 follow-up note. Uses the
+ * "suggestion" set since it's the only one in `src/constants/condition.ts` that includes a
+ * "matches any of" option, needed for multi-value BO attribute conditions (e.g. "Product >>
+ * Category matches any of Drinks, Food" in the design). */
+export declare const DEFAULT_CONDITION_OPERATOR_OPTIONS: ({
+    label: string;
+    value: "not_equals";
+} | {
+    label: string;
+    value: "equals";
+} | {
+    label: string;
+    value: "exists";
+} | {
+    label: string;
+    value: "not_exists";
+} | {
+    label: string;
+    value: "contains";
+} | {
+    label: string;
+    value: "doesnt_contain";
+} | {
+    label: string;
+    value: "start_with";
+} | {
+    label: string;
+    value: "not_start_with";
+} | {
+    label: string;
+    value: "end_with";
+} | {
+    label: string;
+    value: "not_end_with";
+} | {
+    label: string;
+    value: "matches";
+} | {
+    label: string;
+    value: "not_matches";
+})[];
+/** Fixed, static option set for the Identifier field's dropdown — there's no backend precedent
+ * for identifier types yet (identifier ownership is an open product decision, see
+ * `AllocateCouponIdentifierState` in types), so this isn't fetched from any API. */
+export declare const IDENTIFIER_OPTIONS: {
+    label: string;
+    value: string;
+}[];
+export declare const allocateCouponInitialState: AllocateCouponState;

package/es/components/organism/AllocateCoupon/constants/index.js

@@ -0,0 +1,70 @@
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+// Constants
+import { OPERATORS } from '@antscorp/antsomi-ui/es/constants/condition';
+// Types
+import { CALC_METHOD, FALLBACK_MODE, GET_DATA_FROM, QUANTITY_MODE, } from '../types';
+export { QUANTITY_MODE, CALC_METHOD, FALLBACK_MODE, GET_DATA_FROM };
+const { t } = i18nInstance;
+export const CALC_METHOD_OPTIONS = [
+    { label: t(translations.allocateCoupon.calcMethod.sum), value: CALC_METHOD.SUM },
+    { label: t(translations.allocateCoupon.calcMethod.count), value: CALC_METHOD.COUNT },
+];
+/** Generic operator set for condition rows, used until each field's real `dataType` is threaded
+ * through `useGetListEventAttr`/`useGetListAttributeBO` — see plan §9 follow-up note. Uses the
+ * "suggestion" set since it's the only one in `src/constants/condition.ts` that includes a
+ * "matches any of" option, needed for multi-value BO attribute conditions (e.g. "Product >>
+ * Category matches any of Drinks, Food" in the design). */
+export const DEFAULT_CONDITION_OPERATOR_OPTIONS = OPERATORS.suggestion.list;
+/** Fixed, static option set for the Identifier field's dropdown — there's no backend precedent
+ * for identifier types yet (identifier ownership is an open product decision, see
+ * `AllocateCouponIdentifierState` in types), so this isn't fetched from any API. */
+export const IDENTIFIER_OPTIONS = [
+    { label: t(translations.allocateCoupon.identifierOptions.phone), value: 'phone' },
+    { label: t(translations.allocateCoupon.identifierOptions.email), value: 'email' },
+    { label: t(translations.allocateCoupon.identifierOptions.customerId), value: 'customer_id' },
+    { label: t(translations.allocateCoupon.identifierOptions.userId), value: 'user_id' },
+];
+export const allocateCouponInitialState = {
+    pool: {
+        selectedId: null,
+        options: [],
+        isLoading: false,
+        error: null,
+        helpText: undefined,
+    },
+    quantity: {
+        mode: QUANTITY_MODE.FIXED,
+        fixedValue: null,
+        calcMethod: CALC_METHOD.SUM,
+        field: null,
+        fieldOptions: [],
+        isFieldOptionsLoading: false,
+        fieldOptionsError: null,
+        fallback: {
+            mode: FALLBACK_MODE.END_JOURNEY,
+            fixedValue: null,
+        },
+    },
+    sourceEvent: {
+        list: [],
+        selectedKey: null,
+        isLoading: false,
+        error: null,
+    },
+    conditions: {
+        items: [],
+        fieldOptions: [],
+        isFieldOptionsLoading: false,
+        fieldOptionsError: null,
+    },
+    identifier: {
+        value: null,
+        visible: false,
+        options: IDENTIFIER_OPTIONS,
+    },
+    refresh: {
+        isRefreshing: false,
+    },
+};

package/es/components/organism/AllocateCoupon/contexts/AllocateCouponContext.d.ts

@@ -0,0 +1,4 @@
+import { StoreApi } from 'zustand';
+import { AllocateCouponStore } from '../types';
+export declare const AllocateCouponContext: import("react").Context<StoreApi<AllocateCouponStore> | null>;
+export declare function useAllocateCouponContext<T>(selector: (allocateCouponStore: AllocateCouponStore) => T): T;

package/es/components/organism/AllocateCoupon/contexts/AllocateCouponContext.js

@@ -0,0 +1,15 @@
+// Libraries
+import { createContext, useContext } from 'react';
+import isEqual from 'react-fast-compare';
+import { useStore } from 'zustand';
+// Hooks
+import { useDeepCompareMemo } from '@antscorp/antsomi-ui/es/hooks';
+export const AllocateCouponContext = createContext(null);
+export function useAllocateCouponContext(selector) {
+    const store = useContext(AllocateCouponContext);
+    if (!store)
+        throw new Error('Missing AllocateCouponContext.Provider in the tree');
+    const selectedState = useStore(store, selector);
+    const memoizedState = useDeepCompareMemo(() => selectedState, [selectedState]);
+    return useDeepCompareMemo(() => (isEqual(selectedState, memoizedState) ? memoizedState : selectedState), [selectedState, memoizedState]);
+}

package/es/components/organism/AllocateCoupon/hooks/useAllocateCoupon.d.ts

@@ -0,0 +1,2 @@
+import { UseAllocateCouponProps, UseAllocateCouponResult } from '../types';
+export declare const useAllocateCoupon: (props: UseAllocateCouponProps) => UseAllocateCouponResult;

package/es/components/organism/AllocateCoupon/hooks/useAllocateCoupon.js

@@ -0,0 +1,231 @@
+// Libraries
+import { useCallback, useMemo } from 'react';
+import { useStore } from 'zustand';
+import { useQuery } from '@tanstack/react-query';
+import uniqueId from 'lodash/uniqueId';
+// Hooks
+import { useDeepCompareEffect } from '@antscorp/antsomi-ui/es/hooks';
+// Locales
+import i18nInstance from '@antscorp/antsomi-ui/es/locales/i18n';
+import { translations } from '@antscorp/antsomi-ui/es/locales/translations';
+// Constants
+import { CALC_METHOD, FALLBACK_MODE, GET_DATA_FROM, IDENTIFIER_OPTIONS, QUANTITY_MODE, } from '../constants';
+// Utils
+import { buildSourceEventKey, formatPoolIdentityList, fromAllocateCouponSettings, toAllocateCouponSettings, validateAllocateCouponSettings, } from '../utils';
+// Hooks (private store plumbing — creates its own separate store instance, never shared with
+// `Root`'s internal store; the two stay decoupled per the headless-component-pattern rule)
+import { useAllocateCouponStore } from './useAllocateCouponStore';
+// Hooks (private — resolves the merged event+BO attribute options shared by Quantity/Conditions)
+import { useAllocateCouponAttributeOptions } from './useAllocateCouponAttributeOptions';
+/**
+ * The headless business hook for the Allocate Coupon settings panel. Owns UI/selection state;
+ * all 5 data fetches (`getSourceEvents`, `getListPromotionPool`, `getPromotionPoolDetail`,
+ * `getListEventAttr`, `getListAttributeBO`) are required consumer-supplied query configs — this hook never knows
+ * about URLs, auth, or antsomi-ui's own services. It only merges in the internal `enabled`
+ * gating each fetch needs (e.g. don't fetch event attrs until a source event is selected) and
+ * hands the result to a generic `useQuery`. Never imports the presentational `AllocateCoupon`
+ * component — wiring happens at the consumer.
+ */
+const { t } = i18nInstance;
+export const useAllocateCoupon = (props) => {
+    const { getSourceEvents, getListPromotionPool, getPromotionPoolDetail, getListEventAttr, getListAttributeBO, initialData, onChange, showIdentifierField = false, getExtraValidationErrors, } = props;
+    // Hydrate once from `initialData` (edit mode) — not re-synced on later `initialData` changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const hydrated = useMemo(() => fromAllocateCouponSettings(initialData), []);
+    // Owns the user/selection-editable state (`pool.selectedId`, `quantity.*`, `conditions.items`,
+    // `identifier.value`, `sourceEvent.{list,selectedKey}`). `onChange` fires from inside the
+    // store's setter actions, action-attributably, only when the serialized settings actually
+    // change — see `stores/index.ts`'s `notifyIfChanged`.
+    const store = useAllocateCouponStore(hydrated, onChange);
+    const poolId = useStore(store, s => s.pool.selectedId);
+    const quantityMode = useStore(store, s => s.quantity.mode);
+    const fixedValue = useStore(store, s => s.quantity.fixedValue);
+    const calcMethod = useStore(store, s => s.quantity.calcMethod);
+    const quantityField = useStore(store, s => s.quantity.field);
+    const fallback = useStore(store, s => s.quantity.fallback);
+    const conditionItems = useStore(store, s => s.conditions.items);
+    const selectedSourceEventKey = useStore(store, s => s.sourceEvent.selectedKey);
+    const identifierValue = useStore(store, s => s.identifier.value);
+    const setPool = useStore(store, s => s.setPool);
+    const setQuantity = useStore(store, s => s.setQuantity);
+    const setSourceEvent = useStore(store, s => s.setSourceEvent);
+    const setConditions = useStore(store, s => s.setConditions);
+    const setIdentifier = useStore(store, s => s.setIdentifier);
+    /* Promotion Pool — the consumer's query already resolves to `AllocateCouponPoolOption[]`, so
+       no local re-shaping is needed. Fetched metadata (options/loading/error/helpText) is derived
+       locally, never pushed into the store — the store only holds the user-editable `selectedId`. */
+    const { data: poolOptions = [], isLoading: isPoolLoading, isFetching: isPoolFetching, error: poolError, refetch: refetchPool, } = useQuery(getListPromotionPool());
+    /* Selected pool's detail (in particular `restrictionType`) — kept as its own query, gated on
+       a pool actually being selected, so the consumer never has to resolve detail for every listed
+       pool up front just to show one help text. */
+    const poolDetailConfig = getPromotionPoolDetail({ poolId: poolId ?? undefined });
+    const isPoolDetailEnabled = !!poolId && (poolDetailConfig.enabled ?? true);
+    const { data: poolDetail, isFetching: isPoolDetailFetching, refetch: refetchPoolDetail, } = useQuery({
+        ...poolDetailConfig,
+        enabled: isPoolDetailEnabled,
+    });
+    // allocationTypeLabels is the pool's own restriction scope, not the journey Identifier field.
+    const poolHelpText = useMemo(() => {
+        if (!poolDetail?.restrictionType)
+            return undefined;
+        if (poolDetail.restrictionType !== 'unique') {
+            return t(translations.allocateCoupon.poolHelpText.multiple);
+        }
+        const identityList = formatPoolIdentityList(poolDetail.allocationTypeLabels, t(translations.allocateCoupon.poolHelpText.identityListJoiner));
+        return identityList
+            ? t(translations.allocateCoupon.poolHelpText.unique, { identityList })
+            : t(translations.allocateCoupon.poolHelpText.uniqueDefault);
+    }, [poolDetail]);
+    /* Source Event resolution — the one thing antsomi-ui cannot derive itself */
+    const { data: sourceEventList = [], isLoading: isSourceEventLoading, isFetching: isSourceEventFetching, error: sourceEventError, refetch: refetchSourceEvents, } = useQuery(getSourceEvents());
+    // `sourceEvent.list` is mirrored into the store (unlike other query metadata) because the
+    // store's own `toAllocateCouponSettings(get())` needs it to resolve `selectedKey` into
+    // `{eventActionId, eventCategoryId}`. The auto-select-first-event update rides along in the
+    // same call so the store's notify mechanism sees one consistent snapshot, not two partial ones.
+    useDeepCompareEffect(() => {
+        setSourceEvent({
+            list: sourceEventList,
+            ...(!selectedSourceEventKey && sourceEventList.length
+                ? { selectedKey: buildSourceEventKey(sourceEventList[0]) }
+                : null),
+        });
+    }, [sourceEventList, selectedSourceEventKey, setSourceEvent]);
+    const selectedSourceEvent = useMemo(() => sourceEventList.find(ref => buildSourceEventKey(ref) === selectedSourceEventKey), [sourceEventList, selectedSourceEventKey]);
+    /* Event attributes → Quantity-field / Condition options. Which source ids to scope this to
+       is entirely the consumer's concern now (typically resolved from
+       `selectedSourceEvent.additionalKey`) — antsomi-ui only forwards `selectedEvent`. See
+       `useAllocateCouponAttributeOptions` for how the 2 dependent queries (event attrs, then
+       Business Object attrs) resolve into one merged `fieldOptions` list. */
+    const { fieldOptions, isLoading: isFieldOptionsLoading, error: fieldOptionsError, isFetching: isFieldOptionsFetching, refetch: refetchFieldOptions, } = useAllocateCouponAttributeOptions({
+        selectedEvent: selectedSourceEvent,
+        getListEventAttr,
+        getListAttributeBO,
+    });
+    const onAddCondition = () => {
+        const newItem = {
+            id: uniqueId('allocate-coupon-condition_'),
+            field: null,
+            operator: null,
+            value: null,
+            getDataFrom: GET_DATA_FROM.EVENT,
+        };
+        setConditions({ items: [...conditionItems, newItem] });
+    };
+    const onChangeCondition = (id, patch) => {
+        setConditions({
+            items: conditionItems.map(item => (item.id === id ? { ...item, ...patch } : item)),
+        });
+    };
+    const onRemoveCondition = (id) => {
+        setConditions({ items: conditionItems.filter(item => item.id !== id) });
+    };
+    /* Manual refresh — re-runs every currently-relevant query at once. Pool/source-events have no
+       precondition, so they always refetch; pool detail is guarded by its own `enabled` gate
+       (TanStack Query v4's `refetch()` ignores `enabled` and would otherwise fire a request whose
+       precondition isn't actually met yet) — `refetchFieldOptions` applies the same gating
+       internally for its own 2 underlying queries. */
+    const onRefresh = useCallback(() => {
+        const tasks = [refetchPool(), refetchSourceEvents(), refetchFieldOptions()];
+        if (isPoolDetailEnabled)
+            tasks.push(refetchPoolDetail());
+        return Promise.all(tasks);
+    }, [
+        refetchPool,
+        refetchSourceEvents,
+        refetchPoolDetail,
+        refetchFieldOptions,
+        isPoolDetailEnabled,
+    ]);
+    const isRefreshing = isPoolFetching ||
+        isSourceEventFetching ||
+        (isPoolDetailEnabled && isPoolDetailFetching) ||
+        isFieldOptionsFetching;
+    const actions = useMemo(() => ({
+        reset: () => {
+            // One bulk `setState` call, not five separate setters — a setter-per-call reset would
+            // fire `onChange` up to 5x with intermediate half-reset snapshots instead of once with
+            // the final reset settings.
+            store.getState().setState({
+                pool: { selectedId: null },
+                quantity: {
+                    mode: QUANTITY_MODE.FIXED,
+                    fixedValue: null,
+                    calcMethod: CALC_METHOD.SUM,
+                    field: null,
+                    fallback: { mode: FALLBACK_MODE.END_JOURNEY, fixedValue: null },
+                },
+                conditions: { items: [] },
+                sourceEvent: { selectedKey: null },
+                identifier: { value: null },
+            });
+        },
+        getSettings: () => toAllocateCouponSettings(store.getState()),
+        // Delegates the built-in rules to `validateAllocateCouponSettings` -- the same pure
+        // function a consumer can call directly against persisted data without this hook
+        // mounted (see that function's own doc comment). `getExtraValidationErrors` receives
+        // `defaultErrors` alongside `settings` so a consumer never has to re-import/re-call
+        // the base validator itself just to layer on an app-specific rule; the merge stays
+        // additive here (base spread first) so an extra validator can never accidentally wipe
+        // out a built-in error by returning `{}`.
+        validate: () => {
+            const settings = toAllocateCouponSettings(store.getState());
+            const { errors: defaultErrors } = validateAllocateCouponSettings(settings);
+            const extraErrors = getExtraValidationErrors?.({ settings, defaultErrors }) ?? {};
+            const errors = { ...defaultErrors, ...extraErrors };
+            return { valid: Object.keys(errors).length === 0, errors };
+        },
+    }), [store, getExtraValidationErrors]);
+    return {
+        pool: {
+            selectedId: poolId,
+            options: poolOptions,
+            isLoading: isPoolLoading,
+            error: poolError,
+            helpText: poolHelpText,
+            onSelect: id => setPool({ selectedId: id }),
+        },
+        quantity: {
+            mode: quantityMode,
+            fixedValue,
+            calcMethod,
+            field: quantityField,
+            fieldOptions,
+            isFieldOptionsLoading,
+            fieldOptionsError,
+            fallback,
+            onChangeMode: mode => setQuantity({ mode }),
+            onChangeFixedValue: value => setQuantity({ fixedValue: value }),
+            onChangeCalcMethod: method => setQuantity({ calcMethod: method }),
+            onChangeField: field => setQuantity({ field }),
+            onChangeFallbackMode: mode => setQuantity({ fallback: { ...fallback, mode } }),
+            onChangeFallbackFixedValue: value => setQuantity({ fallback: { ...fallback, fixedValue: value } }),
+        },
+        sourceEvent: {
+            list: sourceEventList,
+            selectedKey: selectedSourceEventKey,
+            isLoading: isSourceEventLoading,
+            error: sourceEventError,
+            onSelect: key => setSourceEvent({ selectedKey: key }),
+        },
+        conditions: {
+            items: conditionItems,
+            fieldOptions,
+            isFieldOptionsLoading,
+            fieldOptionsError,
+            onAddCondition,
+            onChangeCondition,
+            onRemoveCondition,
+        },
+        identifier: {
+            value: identifierValue,
+            visible: showIdentifierField,
+            options: IDENTIFIER_OPTIONS,
+            onChange: value => setIdentifier({ value }),
+        },
+        refresh: {
+            isRefreshing,
+            onRefresh,
+        },
+        actions,
+    };
+};