interface PropBindableSource {
  sourceType: 'prop';
  propId: string;
  propName: string;
  propGroup: string | null;
  valueType: BindableValueType;
  bindableTo: readonly BindableValueType[];
}

interface CmsBindableSource {
  sourceType: 'cms';
  collectionId: string;
  collectionName: string;
  fieldId: string;
  fieldName: string;
  fieldGroup: string | null;
  fieldType: CmsFieldType;
  valueType: BindableValueType;
  bindableTo: readonly BindableValueType[];
}

interface PageBindableSource {
  sourceType: 'page';
  fieldKey: string;
  fieldName: string;
  valueType: BindableValueType;
  bindableTo: readonly BindableValueType[];
}

interface LocaleBindableSource {
  sourceType: 'locale';
  fieldKey: string;
  fieldName: string;
  fieldType: 'string';
  valueType: BindableValueType;
  bindableTo: readonly BindableValueType[];
}

interface LocaleItemBindableSource {
  sourceType: 'localeItem';
  fieldKey: string;
  fieldName: string;
  fieldType: 'string';
  valueType: BindableValueType;
  bindableTo: readonly BindableValueType[];
}

type BindableSource =
  | PropBindableSource
  | CmsBindableSource
  | PageBindableSource
  | LocaleBindableSource
  | LocaleItemBindableSource;

interface ElementSetting {
  valueType: BindableValueType;
  canBind: boolean;
  value: SettingValue | UnsupportedElementSettingValue;
  resolvedValue: ResolvedValue | null;
  display: SettingDisplay;
}

interface CollectionListElementSetting {
  valueType: 'collectionListSetting';
  canBind: false;
  value: CollectionListSettingValue;
  resolvedValue?: never;
  display: SettingDisplay;
}

type SearchSettingsResult = ElementSetting | CollectionListElementSetting;

type SearchSettingValueType =
  | ElementSetting['valueType']
  | CollectionListElementSetting['valueType'];

interface SearchSettingsOptions {
  /** Filter to settings that produce a specific value type (e.g., "string", "image", "collectionListSetting") */
  valueType?: SearchSettingValueType;
  /** Filter to a specific setting by key (e.g., "domId", "assetId") */
  key?: string;
}

interface SearchBindableSourcesOptions {
  /** Filter to sources compatible with a specific element setting key (e.g., "altText", "src", "domId") */
  settingKey?: string;
  /** Filter to sources that produce a specific value type (e.g., "string", "imageAsset") */
  valueType?: BindableValueType;
}

/** An attribute on an element, as returned by `getSettings()`. */
interface ElementAttribute {
  /** The attribute name — a plain string, or binding metadata if bound to a data source. Null when the underlying binding can't be resolved. */
  name: string | BindingValue | null;
  /** The attribute's value — a plain string, or binding metadata if bound to a data source. Null when the underlying binding can't be resolved. */
  value: string | BindingValue | null;
}

/** An attribute on an element, as returned by `getResolvedSettings()`. */
interface ResolvedElementAttribute {
  /** The evaluated string name. Null when a binding can't be resolved at design time. */
  name: string | null;
  /** The evaluated string value. Null when a binding can't be resolved at design time. */
  value: string | null;
}

/** An attribute to set on an element via `setSettings()`. */
interface SetElementAttribute {
  /** A plain string name, or a binding descriptor. Name bindings are only supported on DOM elements. */
  name: string | BindingInput;
  /** A plain string value, or a binding descriptor to bind to a data source. */
  value: string | BindingInput;
}

interface UnsupportedElementSettingValue {
  sourceType: 'unsupported';
  /** The setting contains inline dynamic bindings and cannot be represented as editable static text. */
  reason: 'containsBindings';
}

/**
 * Input to `element.setSettings()`.
 *
 * Each key is a setting (e.g., `domId`, `tag`, `assetId`). Values can be a
 * static value, a binding descriptor, or `null` to reset to default.
 *
 * The `attributes` key is special: it takes a `SetElementAttribute[]` that
 * replaces all attributes on the element (pass an empty array to remove
 * them all). Only `attributes` accepts `SetElementAttribute[]` — other
 * setting keys expect a value, binding descriptor, or `null`.
 */
interface SetSettingsInput {
  [key: string]: ResolvedValue | BindingInput | SetElementAttribute[] | null;
}

/**
 * Return type for `element.getSettings()`.
 *
 * Each key is a setting (e.g., `domId`, `tag`, `visibility`). Static values
 * are returned as-is. Bound values include binding metadata. Null means the
 * setting has no value and no default.
 *
 * `attributes` (when present) is the element's full attribute list.
 */
interface ElementSettingSummaries {
  [key: string]:
    | ResolvedValue
    | BindingValue
    | UnsupportedElementSettingValue
    | ElementAttribute[]
    | null;
}

/**
 * Return type for `element.getResolvedSettings()`.
 *
 * Same keys as `getSettings()`, but every value is fully evaluated.
 * Bindings that can't be resolved at design time are null.
 *
 * `attributes` (when present) contains the resolved attribute values.
 */
interface ResolvedElementSettings {
  [key: string]: ResolvedValue | ResolvedElementAttribute[] | null;
}