import type Element from "./Element.js";
import type { ElementProperties } from "./Element.js";
import type { AttachmentInputUnion } from "./inputs/attachments/types.js";
import type { VideoInputProperties } from "./inputs/attachments/VideoInput.js";
import type { SignatureInputProperties } from "./inputs/attachments/SignatureInput.js";
import type { ImageInputProperties } from "./inputs/attachments/ImageInput.js";
import type { DocumentInputProperties } from "./inputs/attachments/DocumentInput.js";
import type { AudioInputProperties } from "./inputs/attachments/AudioInput.js";
import type { AttachmentInputProperties } from "./inputs/attachments/AttachmentInput.js";

/** @since 5.1 */
export interface AttachmentElementProperties extends ElementProperties, Partial<Pick<AttachmentElement, "allowUserRename" | "attachmentKeyword" | "displayFilename" | "editableExpression" | "filenameExpression" | "maxAttachmentCount" | "minAttachmentCount" | "useOriginalFilename">> {
  /**
   * The user-facing inputs used for the attachment element. This defines the type of attachments allowed.
   *
   * @since 5.1
   */
  input?: ((AttachmentInputProperties & { type: "attachment" }) | (AudioInputProperties & { type: "audio" }) | (DocumentInputProperties & { type: "document" }) | (ImageInputProperties & { type: "image" }) | (SignatureInputProperties & { type: "signature" }) | (VideoInputProperties & { type: "video" })) | null;
}

/**
 * An `AttachmentElement` defines how one or more attachments can participate in the [Editor's](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-editor/) form. Use this approach to set attachment configurations within a [feature layer's](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#formTemplate) `formTemplate`. When present in the form, the user has the ability to upload an attachment specific to its corresponding [input](#input).
 *
 * > [!CAUTION]
 * >
 * > * Any existing applications making use of attachments outside of a [FormTemplate](https://developers.arcgis.com/javascript/latest/references/core/form/FormTemplate/) will continue to work as they have in the past. However, to take advantage of the new capabilities provided by `AttachmentElement`, attachments must be configured in a [FormTemplate](https://developers.arcgis.com/javascript/latest/references/core/form/FormTemplate/) and associated to either a [feature layer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/) or the [Editor's `layerInfo`](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-editor/#layerInfos/).
 * > * Support for attachment elements is limited to single feature updates.
 * > * Support is limited to [form templates](https://developers.arcgis.com/javascript/latest/references/core/form/FormTemplate/) set on either the [Editor's `layerInfo`](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-editor/#layerInfos/) or directly on a [feature layer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/).
 * > * The feature layer must have attachments enabled and be editable for attachments.
 * > *  For attachment elements that use [AudioInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AudioInput/), [ImageInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/ImageInput/), or [VideoInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/VideoInput/), input methods that are configured as only allowing `capture` are not supported.
 * > * For attachment elements that use [AudioInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AudioInput/), [ImageInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/ImageInput/), or [VideoInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/VideoInput/), minimum requirements apply only in mobile editing workflows when the input method is set to only allow capture and the minimum file count is greater than or equal to one.
 * > * If a form was authored using older workflows, the [Editor](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-editor/) automatically recognizes any existing attachments and applies a compatibility fallback to preserve existing behavior.
 * > * When a form [supports attachment elements](https://developers.arcgis.com/javascript/latest/references/core/form/FormTemplate/#supportsAttachmentElements) and no attachment elements are explicitly defined, existing feature attachments will not be displayed.
 * > * When using specific input types, such as [AudioInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AudioInput/), [ImageInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/ImageInput/), [VideoInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/VideoInput/), or [DocumentInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/DocumentInput/), existing attachments are displayed only if they match the element's [keyword](https://developers.arcgis.com/javascript/latest/references/core/form/elements/AttachmentElement/#attachmentKeyword). Existing attachments without a matching keyword are not shown. To display attachments that do not have a corresponding keyword, use the general [AttachmentInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AttachmentInput/) instead. This input type provides a more general approach to displaying attachments and does not require a keyword to be specified by setting the [attachmentAssociationType](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AttachmentInput/#attachmentAssociationType) accordingly.
 *
 * @since 5.1
 * @see [FormTemplate](https://developers.arcgis.com/javascript/latest/references/core/form/FormTemplate/)
 * @example
 * // Create the attachment element
 * const attachmentElement = new AttachmentElement({
 *   label: "Tree images",
 *   input: { // autocastable to ImageInput
 *      type: "image",
 *      maxFileSize: 800,
 *   },
 *   attachmentKeyword: "treeKeyword"
 *   displayFilename: true,
 *   minAttachmentCount: 1,
 *   maxAttachmentCount: 5,
 * });
 *
 *
 * // Next pass in element to the FormTemplate
 * const formTemplate = new FormTemplate({
 *   title: "Tree inspection",
 *   description: "Attach tree info",
 *   elements: [attachmentElement] // Add element to the template
 * });
 */
export default class AttachmentElement extends Element {
  /** @since 5.1 */
  constructor(properties?: AttachmentElementProperties);
  /**
   * Indicates whether renaming of attachments is allowed by the user. If `true`, the user can rename attachments when adding them to the form. If `false`, the user cannot rename attachments and the file name will be determined by the [filenameExpression](#filenameexpression) property or generated automatically if [filenameExpression](#filenameexpression) is not specified.
   *
   * @default true
   * @since 5.1
   */
  accessor allowUserRename: boolean | null | undefined;
  /**
   * A string to identify the attachment(s). When a file is attached using the form, this property is used to set the value of the keywords field for the attachment. When a form is displaying existing attachments, this property is used to query attachments using an exact match on the keywords field.
   *
   * @since 5.1
   */
  accessor attachmentKeyword: string | null | undefined;
  /**
   * Indicates whether to display the file name.
   *
   * @default false
   * @since 5.1
   */
  accessor displayFilename: boolean | null | undefined;
  /**
   * A reference to an [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression that returns a boolean value. When this expression evaluates to `true`, the element is editable. When the expression evaluates to `false` the element is not editable.
   *
   * @since 5.1
   * @see [ExpressionInfo](https://developers.arcgis.com/javascript/latest/references/core/form/ExpressionInfo/)
   */
  accessor editableExpression: string | null | undefined;
  /**
   * A string-based [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) expression used to determine the file name of an attachment added through the form. If not specified, a unique name will be generated using the [attachmentKeyword](#attachmentKeyword) plus the current timestamp when attachment is added. This property is used when [useOriginalFilename](#useOriginalFilename) is set to `false` or when [allowUserRename](#allowUserRename) is set to `false` and the user adds an attachment without specifying a file name.
   *
   * > [!CAUTION]
   * >
   * > If wanting to set an attachment's [filenameExpression](#filenameExpression), it should be handled in-line as part of the element rather than as a reference to a shared expression.
   *
   * @default 'StandardizeFilename(`${$formElement.attachmentKeyword}_${Text(Now(), "YMMDDHHmmss")}`)'
   * @example
   * const attachmentElement = new AttachmentElement({
   *   label: "Tree canopy",
   *   allowUserRename: false,
   *   attachmentKeyword: "tree_canopy",
   *   displayFilename: true,
   *   // If not set, the default filenameExpression will generate a name using the
   *   // attachmentKeyword and current timestamp. For example: "tree_canopy_20240610123045"
   *   filenameExpression: 'StandardizeFilename(`${$formElement.attachmentKeyword}`)',
   *   input: { // autocastable to ImageInput
   *     type: "image",
   *     maxFileSize: 800
   *   },
   *   useOriginalFilename: false
   * });
   * @since 5.1
   */
  accessor filenameExpression: string;
  /**
   * The user-facing inputs used for the attachment element. This defines the type of attachments allowed.
   *
   * @since 5.1
   */
  get input(): AttachmentInputUnion | null | undefined;
  set input(value: ((AttachmentInputProperties & { type: "attachment" }) | (AudioInputProperties & { type: "audio" }) | (DocumentInputProperties & { type: "document" }) | (ImageInputProperties & { type: "image" }) | (SignatureInputProperties & { type: "signature" }) | (VideoInputProperties & { type: "video" })) | null | undefined);
  /**
   * Defines the maximum number of attachments allowed for this element. If not specified, there is no maximum number requirement.
   *
   * @since 5.1
   */
  accessor maxAttachmentCount: number | null | undefined;
  /**
   * Defines the minimum number of attachments required for this element. If not specified, there is no minimum number required.
   *
   * > [!CAUTION]
   * >
   * > For media attachment elements configured with [AudioInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/AudioInput/), [ImageInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/ImageInput/), or [VideoInput](https://developers.arcgis.com/javascript/latest/references/core/form/elements/inputs/attachments/VideoInput/), minimum file count validation is enforced only on mobile devices when the input is restricted to newly captured or recorded media and the minimum file count is greater than or equal to one.
   *
   * @since 5.1
   */
  accessor minAttachmentCount: number | null | undefined;
  /**
   * The type of the [Element](https://developers.arcgis.com/javascript/latest/references/core/form/elements/Element/).
   *
   * @since 5.1
   */
  get type(): "attachment";
  /**
   * Determines whether the uploaded attachment's file name is preserved. If `false`, the name is updated based on [filenameExpression](#filenameExpression).
   *
   * @default true
   * @since 5.1
   */
  accessor useOriginalFilename: boolean | null | undefined;
  /**
   * Creates a deep clone of the AttachmentElement class.
   *
   * @returns A deep clone of the AttachmentElement instance.
   * @since 5.1
   */
  clone(): AttachmentElement;
}