/// <reference path="./element-settings.d.ts" />
/// <reference path="./instance-props.d.ts" />

// ── Collection List settings read/write shapes ─────────────────────────────
// These types back the Collection List settings surfaced on DynamoWrapperElement
// through getSettings(), searchSettings(), plus the discovery methods
// searchAvailableSources()/searchAvailableFields()/searchAvailableItems().
// searchSettings() surfaces them as structured, non-bindable settings.

/**
 * The source collection for a Collection List.
 */
interface CollectionListSource {
  /** The unique ID of the CMS collection this list is connected to. */
  collectionId: string;
}

/**
 * All supported filter operators.
 *
 * Not every operator is valid for every field type. Use
 * `searchAvailableFields()` to discover which operators apply to each field.
 */
type CollectionListFilterOperator =
  | 'equals'
  | 'doesNotEqual'
  | 'greaterThan'
  | 'lessThan'
  | 'greaterThanOrEqual'
  | 'lessThanOrEqual'
  | 'isSet'
  | 'isNotSet'
  | 'contains'
  | 'doesNotContain'
  | 'isOn'
  | 'isOff';

/**
 * A relative date value for date-based filter operators.
 */
interface DateFilterValue {
  /**
   * The number of time units. A non-negative integer.
   * Use 0 to represent "today".
   */
  amount: number;
  /** The time unit. */
  unit: 'days' | 'weeks' | 'months' | 'years';
  /** The direction relative to today. */
  direction: 'past' | 'future';
}

/**
 * A single filter condition on a Collection List.
 *
 * Modeled as a discriminated union by operator value-arity, so the presence
 * and type of `value` always match the operator:
 * - Presence/boolean operators carry no static `value`, or binding metadata
 *   when reading a dynamically-bound `When` control from `getSettings()`.
 * - Equality/containment operators carry a `string` value, or binding metadata
 *   when reading a dynamically-bound value from `getSettings()`. For Option
 *   fields, pass the option `id` (see `searchAvailableFields().options`); for
 *   reference fields, use `contains`/`doesNotContain` with an item `id` (see
 *   `searchAvailableItems()`).
 * - Comparison operators carry a `string` (e.g. a number), binding metadata
 *   when reading a dynamically-bound value from `getSettings()`, or, for date
 *   fields, a `DateFilterValue`.
 */
type CollectionListFilter =
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'isSet' | 'isNotSet' | 'isOn' | 'isOff';
      /** A bound `When` control value, when the filter operator is dynamically bound. */
      value?: BindingValue;
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'equals' | 'doesNotEqual' | 'contains' | 'doesNotContain';
      /** The match value. For Option fields the option `id`; for reference fields an item `id`. */
      value: string | BindingValue;
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator:
        | 'greaterThan'
        | 'lessThan'
        | 'greaterThanOrEqual'
        | 'lessThanOrEqual';
      /** A comparable value: a number as a string, or a `DateFilterValue` for date fields. */
      value: string | DateFilterValue | BindingValue;
    };

/**
 * A filter condition accepted by `setSettings()`.
 *
 * Unlike `CollectionListFilter` returned by `getSettings()`, bound writes use
 * `BindingInput` descriptors. `BindingValue` metadata returned from
 * `getSettings()` is the read shape.
 */
type CollectionListFilterInput =
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'isSet' | 'isOn';
      /** A bound `When` control value. Static presence/boolean filters omit this. */
      value?: BindingInput;
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'isNotSet' | 'isOff';
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'equals' | 'doesNotEqual';
      /** The match value. For Option fields the option `id`; for reference fields an item `id`. */
      value: string | BindingInput;
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator: 'contains' | 'doesNotContain';
      /** The match item id for reference fields. */
      value: string;
    }
  | {
      /** The CMS field slug to filter by (e.g., 'name', 'author:name'). */
      fieldSlug: string;
      operator:
        | 'greaterThan'
        | 'lessThan'
        | 'greaterThanOrEqual'
        | 'lessThanOrEqual';
      /** A comparable value: a number as a string, or a `DateFilterValue` for date fields. */
      value: string | DateFilterValue | BindingInput;
    };

/**
 * A single sort entry on a Collection List.
 */
interface CollectionListSort {
  /** The CMS field slug to sort by. */
  fieldSlug: string;
  /** The sort direction. */
  direction: 'ascending' | 'descending';
}

/**
 * The query mode for a Collection List.
 * - 'dynamic': Items are loaded from the CMS based on filters and sort.
 * - 'curated': Items are manually selected by ID.
 */
type CollectionListQueryMode = 'dynamic' | 'curated';

/**
 * How multiple filters are combined.
 * - 'all': All filter conditions must match (AND).
 * - 'any': At least one filter condition must match (OR).
 */
type CollectionListFilterMatch = 'all' | 'any';

/**
 * The structured value of a Collection List setting key, as surfaced through
 * `getSettings()` and structured `searchSettings()` entries alongside the
 * generic element settings.
 */
type CollectionListSettingValue =
  | CollectionListSource
  | CollectionListQueryMode
  | CollectionListFilter[]
  | CollectionListFilterMatch
  | CollectionListSort[]
  | CollectionListPagination
  | number
  | string[]
  | null;

/**
 * Pagination configuration for a Collection List. `null` (on
 * `CollectionListSettings.pagination`) means pagination is disabled.
 */
interface CollectionListPagination {
  /**
   * Number of items shown per page. Values are rounded up and clamped to the
   * Designer's supported range of 1-100.
   */
  itemsPerPage: number;
}

/**
 * Collection List settings returned by `DynamoWrapperElement.getSettings()`.
 *
 * Every Collection List key is optional: the keys are only populated when the
 * Collection List settings API is enabled. While it is disabled (and until GA)
 * `getSettings()` resolves the generic element settings and omits these keys,
 * so narrow before use. The generic element settings (e.g., `domId`,
 * `visibility`, `attributes`) are also present, via `ElementSettingSummaries` —
 * intersecting it keeps this return type assignable to the base
 * `getSettings()` contract without widening it for every other element.
 */
type CollectionListSettings = ElementSettingSummaries & {
  /** The connected CMS collection, or null if not connected. */
  source?: CollectionListSource | null;
  /** The current query mode. */
  queryMode?: CollectionListQueryMode;
  /** Active filters. Empty array when none are configured. */
  filters?: CollectionListFilter[];
  /** How filters are combined. Defaults to 'all'. */
  filterMatch?: CollectionListFilterMatch;
  /** Active sort rules. Empty array when none are configured. */
  sort?: CollectionListSort[];
  /** Maximum number of items to display. */
  limit?: number;
  /** Number of items to skip before displaying. */
  offset?: number;
  /** Pagination configuration, or null when pagination is disabled. */
  pagination?: CollectionListPagination | null;
  /** Ordered list of curated item IDs. Empty array in dynamic mode. */
  curatedItemIds?: string[];
};

/**
 * The writable Collection List settings accepted by
 * `DynamoWrapperElement.setSettings()`. Every field is optional — a partial
 * update sets only the keys it includes. Passing `null` resets that setting to
 * its default value where supported.
 */
interface CollectionListSettingsInput {
  /** Connect to a collection, or pass null to disconnect. */
  source?: CollectionListSource | null;
  /** Switch query mode. Null resets to dynamic mode. */
  queryMode?: CollectionListQueryMode | null;
  /**
   * Replace the filter list. Null or an empty array clears filters.
   * `CollectionListFilter[]` is also accepted for backwards compatibility, but
   * bound writes should use `BindingInput`.
   */
  filters?: CollectionListFilterInput[] | CollectionListFilter[] | null;
  /** How filters are combined. Null resets to all. */
  filterMatch?: CollectionListFilterMatch | null;
  /** Replace the sort list. Null or an empty array clears sort. */
  sort?: CollectionListSort[] | null;
  /** Maximum number of items to display. Null resets to the default. */
  limit?: number | null;
  /** Number of items to skip before displaying. Null resets to 0. */
  offset?: number | null;
  /**
   * Pagination configuration, or null to disable pagination. Only supported
   * for direct-collection lists in dynamic mode.
   */
  pagination?: CollectionListPagination | null;
  /**
   * Replace the ordered list of curated item IDs. Only supported in curated
   * mode. Item IDs are not validated at write time.
   */
  curatedItemIds?: string[];
}

type CollectionListSetSettingsInputValue =
  | ResolvedValue
  | BindingInput
  | SetElementAttribute[]
  | CollectionListSource
  | CollectionListPagination
  | CollectionListFilterInput[]
  | CollectionListFilter[]
  | CollectionListSort[]
  | CollectionListQueryMode
  | CollectionListFilterMatch
  | string[]
  | null
  | undefined;

/**
 * Input to `DynamoWrapperElement.setSettings()`. Collection Lists support the
 * generic element settings plus structured Collection List settings.
 */
interface CollectionListSetSettingsInput extends CollectionListSettingsInput {
  [key: string]: CollectionListSetSettingsInputValue;
}

// ── Discovery API types ────────────────────────────────────────────────────

/**
 * An available source that a Collection List can connect to.
 * Returned by `searchAvailableSources()`.
 */
interface CollectionListAvailableSource {
  /** The collection ID to pass to `setSettings({ source: { collectionId } })`. */
  collectionId: string;
  /** Human-readable display name (e.g., "Blog Posts", "Authors → Posts"). */
  displayName: string;
}

/**
 * An available CMS field for filtering and/or sorting.
 * Returned by `searchAvailableFields()`.
 */
interface CollectionListAvailableField {
  /** The field slug to use in filters and sort (e.g., 'name', 'price'). */
  slug: string;
  /** Human-readable display name. */
  displayName: string;
  /** The public CMS field type. */
  fieldType: CmsFieldType;
  /** Whether this field can be used in filters. */
  canFilter: boolean;
  /** Whether this field can be used in sort. */
  canSort: boolean;
  /**
   * Valid filter operators for this field. Empty array when `canFilter`
   * is false.
   */
  filterOperators: CollectionListFilterOperator[];
  /**
   * Available option choices. Only present for 'option' type fields.
   * Use the `id` as the filter value when filtering by this field.
   */
  options?: Array<{id: string; name: string}>;
  /**
   * The ID of the referenced collection. Only present for 'itemRef' and
   * 'itemRefSet' type fields. Use with `searchAvailableItems({ fieldSlug })`
   * to discover items for filter values.
   */
  referenceCollectionId?: string;
}

/**
 * Options for `searchAvailableItems()`.
 */
interface SearchAvailableItemsOptions {
  /**
   * The field slug of a reference field to get items for. When omitted,
   * returns items from the list's connected collection (for curated mode).
   */
  fieldSlug?: string;
  /** Search query to filter items by display name. */
  query?: string;
  /** Zero-based page index. Defaults to 0. */
  page?: number;
  /** Number of items per page. Defaults to 50. */
  pageSize?: number;
}

/**
 * A CMS item returned by `searchAvailableItems()`.
 */
interface CollectionListAvailableItem {
  /** The item ID. Use this in `curatedItemIds` or filter values. */
  id: string;
  /** Human-readable display name of the item. */
  displayName: string;
}

/**
 * Paginated response from `searchAvailableItems()`.
 */
interface SearchAvailableItemsResult {
  /** The matching items. */
  items: CollectionListAvailableItem[];
  /** Total number of matching items (for pagination). */
  total: number;
}