@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-expand.d.ts

@@ -0,0 +1,102 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+
+/**
+ * Marks an `<ng-template>` as the lazy content for a `mlv-expand` panel.
+ *
+ * Nothing inside the template is constructed until the panel first opens, so a
+ * heavy child component in a panel the user never expands is never initialized.
+ * The template is re-instantiated on each subsequent open — it is not cached —
+ * because `mlv-expand` removes its body from the DOM while closed.
+ *
+ * @example
+ * ```html
+ * <button type="button" (click)="panel.toggle()">Load on demand</button>
+ * <mlv-expand #panel>
+ *   <ng-template mlvExpandContent>
+ *     <heavy-component />
+ *   </ng-template>
+ * </mlv-expand>
+ * ```
+ */
+declare class MlvExpandContent {
+    /** The template reference rendered once the panel first opens. */
+    readonly templateRef: TemplateRef<any>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvExpandContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvExpandContent, "[mlvExpandContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Expandable panel component with smooth `grid-template-rows` animation.
+ *
+ * The component renders no header or trigger of its own — it is the animated
+ * panel only. Drive it from your own control through `[(opened)]` or a template
+ * reference and `toggle()`.
+ *
+ * Supports two content modes:
+ * - **Eager** (default): place content directly inside `<mlv-expand>`.
+ * - **Lazy**: wrap content in `<ng-template mlvExpandContent>`.
+ *
+ * In both modes the body element only exists while `opened()` is `true`, so
+ * projected content is created on open and destroyed on close. The difference
+ * is *when the content is first constructed*: eager `<ng-content>` is created
+ * with the host component, the lazy template only on first open — which is what
+ * keeps a heavy child from being initialized in a panel the user never expands.
+ *
+ * @example Eager (ng-content)
+ * ```html
+ * <button type="button" (click)="panel.toggle()">Details</button>
+ * <mlv-expand #panel>
+ *   <p>Created with the host; in the DOM only while the panel is open.</p>
+ * </mlv-expand>
+ * ```
+ *
+ * @example Lazy (structural directive)
+ * ```html
+ * <button type="button" (click)="isOpen.set(!isOpen())">Load on demand</button>
+ * <mlv-expand [(opened)]="isOpen">
+ *   <ng-template mlvExpandContent>
+ *     <heavy-chart-component />
+ *   </ng-template>
+ * </mlv-expand>
+ * ```
+ */
+declare class MlvExpand {
+    /**
+     * Two-way bindable open/closed state.
+     * Bind with `[(opened)]="isOpen"` or read with `(openedChange)="onToggle($event)"`.
+     *
+     * @remarks Renamed from `open` to `opened` for consistency with the other
+     * open/close surfaces (`mlv-dialog`, `mlv-drawer`, `mlv-popup`). Breaking
+     * change — see the expand migration note.
+     */
+    readonly opened: _angular_core.ModelSignal<boolean>;
+    /**
+     * When `true`, prevents toggling and visually dims the component.
+     * Supports attribute syntax: `<mlv-expand disabled>`.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Optional accessible label for the expand body region.
+     * When set, applies `role="region"` with `aria-label` on the body element.
+     * Prefer `ariaLabelledBy` when a visible label element exists.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * ID of an element that labels this expand region.
+     * When set, applies `role="region"` with `aria-labelledby` on the body element.
+     */
+    readonly ariaLabelledBy: _angular_core.InputSignal<string | undefined>;
+    /** @internal Detects whether a lazy content directive is projected. */
+    protected readonly _lazyContent: _angular_core.Signal<MlvExpandContent | undefined>;
+    /**
+     * Toggles the open/closed state.
+     * No-op when the component is disabled.
+     */
+    toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvExpand, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvExpand, "mlv-expand", never, { "opened": { "alias": "opened"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; "isSignal": true; }; }, { "opened": "openedChange"; }, ["_lazyContent"], ["*"], true, never>;
+}
+
+export { MlvExpand, MlvExpandContent };

package/types/malva-ui-core-file-upload.d.ts

@@ -0,0 +1,267 @@
+import * as _angular_core from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvSignalFormControlBase } from '@malva-ui/core/form-utils';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { MlvFileUploadI18n } from '@malva-ui/i18n';
+
+/** Which side of the browse button a `[mlvFileUploadAction]` control renders on. */
+type MlvFileUploadActionPosition = 'start' | 'end';
+/**
+ * Marks a projected control as an extra action in the drop zone's action row,
+ * next to the built-in browse button. Typical use is an icon-only button that
+ * offers an alternative to picking a file — "generate with AI", "pick from
+ * library", "use camera".
+ *
+ * `position` is matched by the component's `<ng-content>` selectors, so it must
+ * be written as a **static attribute** (`position="end"`), exactly like the
+ * other Malva UI slot markers. A binding (`[position]="…"`) changes the
+ * directive's signal but cannot move the node between projection slots.
+ * DOM order equals visual order — nothing is reordered with CSS `order` — so
+ * the tab sequence always matches what the user sees.
+ *
+ * Clicks (including Enter/Space activation of a projected `<button>`) stop at
+ * the slot, so an extra action never also triggers the surrounding zone and
+ * opens the native file picker.
+ *
+ * Disabling a projected control is the consumer's job: `mlv-file-upload` only
+ * dims the zone and blocks pointer events while the control itself is
+ * disabled, it does not write `disabled` onto projected content.
+ *
+ * @example
+ * ```html
+ * <mlv-file-upload title="Image" actionLabel="Choose image">
+ *   <button mlvButton mlvFileUploadAction type="button" shape="square"
+ *           aria-label="Generate image with AI">
+ *     <svg lucideSparkles [size]="16" />
+ *   </button>
+ * </mlv-file-upload>
+ *
+ * <mlv-file-upload actionLabel="Choose image">
+ *   <button mlvButton mlvFileUploadAction position="end" type="button"
+ *           variant="transparent">
+ *     Import from URL
+ *   </button>
+ * </mlv-file-upload>
+ * ```
+ */
+declare class MlvFileUploadAction {
+    /**
+     * Where the action sits relative to the browse button. `'start'` (the
+     * default) renders it before the button, `'end'` after it.
+     *
+     * Set it as a static attribute — `position="end"` — because the value is
+     * read by the host component's content-projection selector, not at runtime.
+     */
+    readonly position: _angular_core.InputSignal<MlvFileUploadActionPosition>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFileUploadAction, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFileUploadAction, "[mlvFileUploadAction]", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Represents a file that has been selected or uploaded.
+ */
+interface MlvUploadedFile {
+    /** Unique identifier for the file entry. */
+    id: string;
+    /** The native File object. */
+    file: File;
+    /** Display name derived from the file. */
+    name: string;
+    /** File size in bytes. */
+    size: number;
+    /** Object URL for image preview — revoked when the file is removed. */
+    previewUrl?: string;
+    /** Current upload state. */
+    state: 'pending' | 'uploading' | 'success' | 'error';
+    /** Upload progress from 0–100 (used when state is `'uploading'`). */
+    progress?: number;
+    /** Validation error set when the file fails accept/size/count checks. */
+    error?: MlvFileValidationError;
+}
+/**
+ * Describes a file validation failure.
+ */
+interface MlvFileValidationError {
+    /** Machine-readable reason code. */
+    code: 'size' | 'type' | 'count';
+    /** Human-readable error message. */
+    message: string;
+}
+/** Overall state of the drop-zone. */
+type MlvFileUploadState = 'idle' | 'dragging' | 'disabled';
+/**
+ * How the drop zone presents the current selection.
+ *
+ * - `'list'` — the default. The zone always shows the prompt and browse
+ *   button, and selected files are listed below it.
+ * - `'cover'` — a single selected image fills the zone, with a floating
+ *   replace/remove toolbar. Falls back to `'list'` whenever the cover
+ *   preconditions are not met (see `MlvFileUpload.previewMode`).
+ */
+type MlvFileUploadPreviewMode = 'list' | 'cover';
+
+/**
+ * File upload component providing a drag-and-drop zone, file validation, and
+ * signal, reactive, and template-driven forms integration. Produces an array
+ * of `MlvUploadedFile` values.
+ */
+declare class MlvFileUpload extends MlvSignalFormControlBase<MlvUploadedFile[]> {
+    /** The uploaded-file list used by all Angular forms APIs. */
+    readonly value: _angular_core.ModelSignal<MlvUploadedFile[]>;
+    /** @protected Injected i18n translations for the file upload. */
+    protected readonly _i18n: _angular_core.Signal<MlvFileUploadI18n>;
+    /** @private ICU MessageFormat resolver for the parameterised rejection messages. */
+    private readonly _resolver;
+    /** Comma-separated list of accepted MIME types or file extensions (e.g. `"image/*,.pdf"`). */
+    readonly accept: _angular_core.InputSignal<string>;
+    /**
+     * Maximum allowed file size in bytes. `0` means unlimited.
+     */
+    readonly maxSize: _angular_core.InputSignal<number>;
+    /** Whether to allow selecting multiple files. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Primary heading text shown in the drop zone. */
+    readonly title: _angular_core.InputSignal<string>;
+    /** Secondary description text shown below the title. */
+    readonly subtitle: _angular_core.InputSignal<string>;
+    /** Label text for the browse button. */
+    readonly actionLabel: _angular_core.InputSignal<string>;
+    /** When true, renders a compact single-row drop zone instead of the full zone. */
+    readonly compact: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * How the zone presents the current selection.
+     *
+     * `'list'` (the default) keeps today's behaviour: the prompt and browse
+     * button always show, and selected files are listed below the zone.
+     *
+     * `'cover'` fills the zone with the selected image and swaps the browse
+     * button for a floating replace/remove toolbar. It only takes effect when
+     * **all** of these hold, and silently falls back to `'list'` otherwise:
+     *
+     * 1. `multiple` is `false`,
+     * 2. exactly one file is selected, and
+     * 3. that file carries a `previewUrl`.
+     *
+     * `previewUrl` is generated automatically for any dropped/picked file whose
+     * MIME type starts with `image/`. For an edit-mode seed, write it yourself —
+     * it accepts a remote `https://…` or a `data:` URL just as happily as the
+     * generated `blob:` one.
+     */
+    readonly previewMode: _angular_core.InputSignal<MlvFileUploadPreviewMode>;
+    /** Emits the current file list whenever files are added or removed. */
+    readonly filesChange: _angular_core.OutputEmitterRef<MlvUploadedFile[]>;
+    /** @private List of selected/uploaded files managed by the component. */
+    protected readonly _files: _angular_core.Signal<MlvUploadedFile[]>;
+    /** @private Validation errors from the last file selection or drop. */
+    protected readonly _errors: _angular_core.WritableSignal<MlvFileValidationError[]>;
+    /** @private Whether the user is currently dragging files over the drop zone. */
+    protected readonly _isDragOver: _angular_core.WritableSignal<boolean>;
+    /** @private Reference to the hidden file input element. */
+    private readonly _fileInput;
+    /** @private Reference to the host element for dragleave boundary detection. */
+    private readonly _elementRef;
+    /** @protected Computed list of files exposed to the template. */
+    protected readonly _fileList: _angular_core.Signal<MlvUploadedFile[]>;
+    /**
+     * @protected The single file rendered as a full-zone cover, or `null` when
+     * the cover preconditions are not met (see `previewMode`) and the zone falls
+     * back to the normal prompt.
+     */
+    protected readonly _coverFile: _angular_core.Signal<MlvUploadedFile | null>;
+    /** @protected Whether the zone currently renders the cover preview. */
+    protected readonly _isCover: _angular_core.Signal<boolean>;
+    /**
+     * @protected Whether the covered file is still uploading, which overlays a
+     * determinate progress bar on the image instead of falling back to list mode.
+     */
+    protected readonly _coverUploading: _angular_core.Signal<boolean>;
+    /**
+     * @protected Accessible name for the cover toolbar's remove button, with the
+     * covered file's name interpolated into the shared `removeFile` template.
+     */
+    protected readonly _coverRemoveLabel: _angular_core.Signal<string>;
+    /** Whether the control holds a clearable value — At least one file present. */
+    readonly hasValue: _angular_core.Signal<boolean>;
+    /**
+     * Programmatically opens the native file picker dialog.
+     */
+    openFilePicker(): void;
+    /**
+     * Handles changes from the hidden file input element.
+     * @param event - The native change event from the input.
+     */
+    onFileInputChange(event: Event): void;
+    /**
+     * Removes a file by its id, revoking the preview URL if present.
+     * @param id - The id of the `MlvUploadedFile` to remove.
+     */
+    removeFile(id: string): void;
+    /**
+     * @private Handles the dragover event to enable the drag-over state.
+     */
+    protected _onDragOver(event: DragEvent): void;
+    /**
+     * @private Handles the dragleave event to clear drag-over state when leaving the host.
+     */
+    protected _onDragLeave(event: DragEvent): void;
+    /**
+     * @private Handles the drop event, reads dropped files and validates them.
+     */
+    protected _onDrop(event: DragEvent): void;
+    /**
+     * @private Validates a FileList against accept/maxSize constraints and appends valid files.
+     */
+    private _validateAndAdd;
+    /**
+     * @private Resolves one of the component's ICU rejection templates with the
+     * offending file's details. Keeps every user-facing validation string in the
+     * language pack instead of hard-coded English.
+     */
+    private _translate;
+    /**
+     * @private Parses the accept input into a list of accepted MIME prefixes and extensions.
+     */
+    private _parseAccept;
+    /**
+     * @private Checks whether a file matches the accepted type list.
+     */
+    private _isTypeAccepted;
+    /**
+     * @private Emits the current file list through the public change output.
+     */
+    private _emitChange;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFileUpload, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvFileUpload, "mlv-file-upload", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "subtitle": { "alias": "subtitle"; "required": false; "isSignal": true; }; "actionLabel": { "alias": "actionLabel"; "required": false; "isSignal": true; }; "compact": { "alias": "compact"; "required": false; "isSignal": true; }; "previewMode": { "alias": "previewMode"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "filesChange": "filesChange"; }, never, ["[mlvFileUploadAction]:not([position=end])", "[mlvFileUploadAction][position=end]"], true, never>;
+}
+
+/**
+ * Renders a single uploaded file row with thumbnail, metadata, progress bar,
+ * status icon, and a remove button.
+ */
+declare class MlvFileUploadItem {
+    /** @protected Injected i18n translations for the file upload. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvFileUploadI18n>;
+    /** @private ICU MessageFormat resolver for parameterised i18n strings. */
+    private readonly _resolver;
+    /** The uploaded file descriptor to render. */
+    readonly file: _angular_core.InputSignal<MlvUploadedFile>;
+    /**
+     * @protected Accessible label for the remove button, naming the specific file
+     * (e.g. `"Remove report.xlsx"`) so screen-reader users know which file the
+     * button removes. Resolves the `removeFile` ICU template with the file name.
+     */
+    protected readonly _removeLabel: _angular_core.Signal<string>;
+    /** Emits when the user clicks the remove button. */
+    readonly remove: _angular_core.OutputEmitterRef<void>;
+    /** @protected Human-readable file size string (e.g. "1.2 MB"). */
+    protected readonly _formattedSize: _angular_core.Signal<string>;
+    /** @protected Whether to show the progress bar. */
+    protected readonly _showProgress: _angular_core.Signal<boolean>;
+    /** @protected Current progress value for the loader bar. */
+    protected readonly _progress: _angular_core.Signal<number>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFileUploadItem, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvFileUploadItem, "mlv-file-upload-item", never, { "file": { "alias": "file"; "required": true; "isSignal": true; }; }, { "remove": "remove"; }, never, never, true, never>;
+}
+
+export { MlvFileUpload, MlvFileUploadAction, MlvFileUploadItem };
+export type { MlvFileUploadActionPosition, MlvFileUploadPreviewMode, MlvFileUploadState, MlvFileValidationError, MlvUploadedFile };