@synergy-design-system/components
Version:
This package provides the base of the Synergy Design System as native web components. It uses [lit](https://www.lit.dev) and parts of [shoelace](https://shoelace.style/). Synergy officially supports the latest two versions of all major browsers (as define
200 lines (199 loc) • 9.16 kB
TypeScript
import type { CSSResultGroup } from 'lit';
import type { SynergyFormControl } from '../../internal/synergy-element.js';
import SynergyElement from '../../internal/synergy-element.js';
import SynButton from '../button/button.component.js';
import SynIcon from '../icon/icon.component.js';
/**
* @summary File controls allow selecting an arbitrary number of files for uploading.
* @documentation https://synergy-design-system.github.io/?path=/docs/components-syn-file--docs
* @status stable
*
* @dependency syn-button
* @dependency syn-icon
*
* @slot label - The file control's label. Alternatively, you can use the `label` attribute.
* @slot help-text - Text that describes how to use the file control.
* Alternatively, you can use the `help-text` attribute.
* @slot droparea-icon - Optional droparea icon to use instead of the default.
* Works best with `<syn-icon>`.
* @slot trigger - Optional content to be used as trigger instead of the default content.
* Opening the file dialog on click and as well as drag and drop will work for this content.
* Following attributes will no longer work: *label*, *droparea*, *help-text*, *size*,
* *hide-value*. Also if using the disabled attribute, the disabled styling will not be
* applied and must be taken care of yourself.
*
* @event syn-blur - Emitted when the control loses focus.
* @event syn-change - Emitted when an alteration to the control's value is committed by the user.
* @event syn-error - Emitted when multiple files are selected via drag and drop, without
* the `multiple` property being set.
* @event syn-focus - Emitted when the control gains focus.
* @event syn-input - Emitted when the control receives input.
*
* @csspart form-control - The form control that wraps the label, input, and help text.
* @csspart form-control-label - The label's wrapper.
* @csspart form-control-input - The input's wrapper.
* @csspart form-control-help-text - The help text's wrapper.
* @csspart button-wrapper - The wrapper around the button and text value.
* @csspart button - The syn-button acting as a file input.
* @csspart button__base - The syn-button's exported `base` part.
* @csspart value - The chosen files or placeholder text for the file input.
* @csspart droparea - The element wrapping the drop zone.
* @csspart droparea-background - The background of the drop zone.
* @csspart droparea-icon - The container that wraps the icon for the drop zone.
* @csspart droparea-value - The text for the drop zone.
* @csspart trigger - The container that wraps the trigger.
*
* @animation file.iconDrop - The animation to use for the file icon
* when a file is dropped
* @animation file.text.disappear - The disappear animation to use for the file placeholder text
* when a file is dropped
* @animation file.text.appear - The appear animation to use for the file placeholder text
* when a file is dropped
*/
export default class SynFile extends SynergyElement implements SynergyFormControl {
static styles: CSSResultGroup;
static dependencies: {
'syn-button': typeof SynButton;
'syn-icon': typeof SynIcon;
};
private readonly formControlController;
private readonly hasSlotController;
private readonly localize;
private userIsDragging;
/**
* The selected files as a FileList object containing a list of File objects.
* The FileList behaves like an array, so you can get the number of selected files
* via its length property.
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#getting_information_on_selected_files)
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#getting_information_on_selected_files
*/
set files(v: FileList | null);
get files(): FileList | null;
/** The name of the file control, submitted as a name/value pair with form data. */
name: string;
/**
* The current value of the input, submitted as a name/value pair with form data.
* Beware that the only valid value when setting a file input is an empty string!
*/
/**
* The value of the file control contains a string that represents the path of the selected file.
* If multiple files are selected, the value represents the first file in the list.
* If no file is selected, the value is an empty string.
* Beware that the only valid value when setting a file control is an empty string!
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#value)
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#value
*/
set value(v: string);
get value(): string;
/** The default value of the form control. Primarily used for resetting the form control. */
defaultValue: string;
/** The file control's size. */
size: 'small' | 'medium' | 'large';
/** The file control's label. If you need to display HTML, use the `label` slot instead. */
label: string;
/**
* The file control's help text.
* If you need to display HTML, use the `help-text` slot instead.
*/
helpText: string;
/** Disables the file control. */
disabled: boolean;
/** Draw the file control as a drop area */
droparea: boolean;
/**
* Comma separated list of supported file types
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept)
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept
* @example <syn-file accept=".jpg,.jpeg,.png,.gif,text/plain,image/*"></syn-file>
*/
accept: string;
/**
* Specifies the types of files that the server accepts.
* Can be set either to user or environment.
* Works only when not using a droparea!
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/capture)
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/capture
*/
capture: 'user' | 'environment';
/**
* Indicates whether the user can select more than one file.
* Has no effect if webkitdirectory is set.
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#multiple)
*
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#multiple
*/
multiple: boolean;
/**
* Indicates that the file control should let the user select directories instead of files.
* When a directory is selected, the directory and its entire hierarchy of contents are included
* in the set of selected items.
* Note: This is a non-standard attribute but is supported in the major browsers.
* [see MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory)
*
* @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory
*/
webkitdirectory: boolean;
/**
* By default, form controls are associated with the nearest containing `<form>` element.
* This attribute allows you to place the form control outside of a form and associate it
* with the form that has this `id`. The form must be in the same document
* or shadow root for this to work.
*/
form: string;
/** Makes the input a required field. */
required: boolean;
/** Suppress the value from being displayed in the file control */
hideValue: boolean;
input: HTMLInputElement;
button: SynButton;
dropareaWrapper: HTMLDivElement;
dropareaIcon: HTMLSpanElement;
inputChosen: HTMLSpanElement;
/** Gets the validity state object */
get validity(): ValidityState;
/** Gets the validation message */
get validationMessage(): string;
/**
* Checks for validity but does not show a validation message.
* Returns `true` when valid and `false` when invalid.
*/
checkValidity(): boolean;
/** Gets the associated form, if one exists. */
getForm(): HTMLFormElement | null;
/** Checks for validity and shows the browser's validation message if the control is invalid. */
reportValidity(): boolean;
/** Sets a custom validation message. Pass an empty string to restore validity. */
setCustomValidity(message: string): void;
handleDisabledChange(): void;
handleValueChange(): Promise<void>;
/** Sets focus on the button or droparea. */
focus(options?: FocusOptions): void;
/** Removes focus from the button or droparea. */
blur(): void;
private handleInvalid;
private handleFiles;
private handleTransferItems;
private getFilesFromEntry;
private handleClick;
/** Handles the change event of the native input */
private handleChange;
private handleDragOver;
private handleDragLeave;
private handleDrop;
/**
* Handle the focus of the droparea and emit focus event
*/
private handleFocus;
/**
* Handle the blur of the droparea and emit blur event
*/
private handleBlur;
private renderValue;
private renderDroparea;
private renderButton;
render(): import("lit").TemplateResult<1>;
}