stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/file_dropzone_controller.d.ts

@@ -54,7 +54,10 @@ import { Controller } from '@hotwired/stimulus';
  * - The accepted set is mirrored onto the native input, so a plain form submit
  *   carries the dropped files with no JavaScript from the consumer. Where
  *   `DataTransfer` cannot be constructed the previews and events still work and the
- *   input keeps whatever the native dialog last put there.
+ *   input keeps whatever the native dialog last put there. An input that takes
+ *   over — in one task, or after an earlier one leaves in a later task — gets the
+ *   accepted set too, silently; the files on one that departs are its own form value
+ *   and stay.
  * - Removing a file revokes its `objectURL` and moves focus to the next (else
  *   previous) remove button, falling back to the trigger.
  * - Additions, rejections, removals, and the drag affordance are handed to the
@@ -67,18 +70,29 @@ import { Controller } from '@hotwired/stimulus';
  *   disabled `fieldset` the zone never becomes a drop target, matching what the
  *   native click and keyboard paths already do.
  * - Replacing the `list` target rebinds delegated removal and moves the
- *   client-only previews into the replacement; a morph that empties the list in
- *   place moves them back on the next interaction.
+ *   client-only previews into the replacement; a list inserted behind the current
+ *   one receives them only once the current one leaves. A morph that empties the
+ *   list in place — a Turbo morph does, as the server never rendered them — moves
+ *   them back at once, and the drag and rejection hooks the morph took off with them.
+ *   A preview taken out any other way comes back the same way: the remove button is
+ *   what drops a file.
  * `reject` dispatches `{ file: File, reason: "type" | "size" | "duplicate" | "count" }`.
  * `change` and `reconcile` dispatch `{ files: File[] }`.
  *
  * @remarks
  * Previews are client-only state that no restored snapshot can revive — the `File`
- * objects and their `blob:` URLs die with the page. Just before Turbo caches the
- * page the generated items are removed, every `objectURL` revoked, and both state
- * attributes withdrawn, so a restored snapshot starts pristine instead of showing
- * rows that cannot be removed and do not count towards `maxFiles`. A `disconnect()`
- * that turns out to be an in-page move keeps the selection intact.
+ * objects and their `blob:` URLs die with the page. Every item this controller renders
+ * carries `data-<identifier>-generated`, so a page Turbo restores from its cache, which
+ * still shows the items of the page it copied, is recognised when it connects: a
+ * connection that holds no selection of its own removes the marked items it finds in
+ * its lists, empties the native input, withdraws both state attributes, and reports the
+ * empty selection as `reconcile`. Rows that cannot be removed and do not count towards
+ * `maxFiles` therefore never stay on a restored page. Nothing is undone on
+ * `turbo:before-cache`, which Turbo also dispatches on pages that stay — a promoted
+ * frame navigation, a state-less `popstate`, a refresh of a cached URL, a
+ * `data-turbo-permanent` element carried to the next page — where the selection is the
+ * one the form is about to submit. A `disconnect()` that turns out to be an in-page move
+ * keeps the selection intact, and so does a permanent element's reconnection.
  */
 declare class FileDropzoneController extends Controller<HTMLElement> {
     #private;
@@ -125,9 +139,20 @@ declare class FileDropzoneController extends Controller<HTMLElement> {
             default: string;
         };
     };
+    static valueConstraints: {
+        maxSize: {
+            readonly finite: true;
+            readonly min: 0;
+        };
+        maxFiles: {
+            readonly finite: true;
+            readonly min: 0;
+        };
+    };
     static actions: readonly ["onChange", "onDragLeave", "onDragOver", "onDrop", "openDialog"];
     static events: readonly ["change", "reject", "reconcile"];
     readonly inputTarget: HTMLInputElement;
+    readonly inputTargets: HTMLInputElement[];
     readonly listTarget: HTMLElement;
     readonly listTargets: HTMLElement[];
     readonly triggerTarget: HTMLElement;
@@ -138,6 +163,7 @@ declare class FileDropzoneController extends Controller<HTMLElement> {
     readonly hasItemTemplateTarget: boolean;
     readonly hasZoneTarget: boolean;
     readonly zoneTarget: HTMLElement;
+    readonly zoneTargets: HTMLElement[];
     maxSizeValue: number;
     maxFilesValue: number;
     allowDuplicatesValue: boolean;
@@ -148,7 +174,7 @@ declare class FileDropzoneController extends Controller<HTMLElement> {
     announceRejectedSizeTextValue: string;
     announceRejectedDuplicateTextValue: string;
     announceRejectedCountTextValue: string;
-    /** Subscribes to the Turbo cache rewind and re-arms the template diagnostic. */
+    /** Re-arms the template diagnostic and discards the items a restored page carries. */
     connect(): void;
     /**
      * Releases the delegated listeners. The selection itself survives an in-page
@@ -157,22 +183,41 @@ declare class FileDropzoneController extends Controller<HTMLElement> {
      */
     disconnect(): void;
     /**
-     * Binds removal and restores client-only previews for every list this controller
-     * renders into — the one present at connect and any Turbo puts in its place.
-     * This is the only place the listener is attached, so the pair with
-     * {@link listTargetDisconnected} keeps it from outliving the element it is on.
+     * Binds removal on every list this controller renders into — the one present at
+     * connect and any Turbo puts in its place — watches it for previews taken out of it,
+     * and restores client-only previews into the list that is first, so a list waiting
+     * behind the current one stays empty. This is the only place the listener is
+     * attached, so the pair with {@link listTargetDisconnected} keeps it from outliving
+     * the element it is on; the watch ends with the connection.
+     *
+     * @stimeoListenerLifetime element each list is bound when it becomes a target and
+     *   unbound when it stops being one or the controller disconnects.
      */
     listTargetConnected(list: HTMLElement): void;
-    /** Releases only the list target that actually disconnected. */
+    /** Releases the list that disconnected and moves the previews into the list that stays. */
     listTargetDisconnected(list: HTMLElement): void;
+    /** Mirrors the accepted set onto an input that arrives after connect. */
+    inputTargetConnected(): void;
+    /** Mirrors the accepted set onto the input left once an earlier one departs. */
+    inputTargetDisconnected(): void;
+    /** Writes the drag and rejection hooks onto a zone that arrives after connect. */
+    zoneTargetConnected(): void;
+    /**
+     * Gives a zone that no longer resolves as the target its own hooks back — after
+     * `disconnect()` too, since dropping the identifier leaves the element on the page —
+     * and, while connected, writes them onto the zone left.
+     */
+    zoneTargetDisconnected(zone: HTMLElement): void;
     /** Opens the native file dialog. Bound via `data-action` (trigger click). */
     openDialog(): void;
     /**
-     * Adds the files chosen through the native dialog. The input holds only what
-     * the dialog just returned, so the accepted set is written back over it once
-     * the batch is validated.
+     * Adds the files chosen through the native dialog, read from the input the `change`
+     * came from — an input waiting behind the one in use included — or from the input in
+     * use for an event no input dispatched and for a call with no event. The dialog
+     * leaves only its own answer on that input, so the accepted set is written back over
+     * the input in use once the batch is validated.
      */
-    onChange(): void;
+    onChange(event?: Event): void;
     /**
      * Marks the zone as a drop target and announces the affordance once per drag.
      * Bound via `data-action` (dragover). Leaving the default alone is what refuses