stimeo-ui 0.6.0 → 0.8.0

package/dist/controllers/file_dropzone_controller.d.ts

@@ -5,7 +5,8 @@ import { Controller } from '@hotwired/stimulus';
  *
  * Markup contract (identifier: `stimeo--file-dropzone`):
  *   <div data-controller="stimeo--file-dropzone"
- *        data-stimeo--file-dropzone-max-size-value="5242880">
+ *        data-stimeo--file-dropzone-max-size-value="5242880"
+ *        data-stimeo--file-dropzone-announce-added-text-value="{name} added; {total} selected">
  *     <div data-stimeo--file-dropzone-target="zone"
  *          data-action="dragover->stimeo--file-dropzone#onDragOver
  *                       dragleave->stimeo--file-dropzone#onDragLeave
@@ -17,9 +18,14 @@ import { Controller } from '@hotwired/stimulus';
  *              data-action="change->stimeo--file-dropzone#onChange" />
  *     </div>
  *     <ul data-stimeo--file-dropzone-target="list" aria-label="Selected files"></ul>
- *     <span role="status" aria-live="polite" class="visually-hidden"
- *           data-stimeo--file-dropzone-target="status"></span>
- *     <template data-stimeo--file-dropzone-target="itemTemplate">…</template>
+ *     <template data-stimeo--file-dropzone-target="itemTemplate">
+ *       <li data-stimeo--file-dropzone-target="item">
+ *         <img data-stimeo--file-dropzone-target="thumb" alt="" hidden />
+ *         <span data-stimeo--file-dropzone-target="name"></span>
+ *         <button type="button" aria-label="Remove {name}"
+ *                 data-stimeo--file-dropzone-target="remove">×</button>
+ *       </li>
+ *     </template>
  *   </div>
  *
  * There is no single APG pattern; the native `<input type="file">` stays the
@@ -29,17 +35,50 @@ import { Controller } from '@hotwired/stimulus';
  *
  * Behavior provided:
  * - Click / keyboard via the `trigger` opens the native file dialog; drag-and-drop
- *   over the `zone` adds files (with a `data-dragover` flag and a spoken hint).
- * - Each file is validated against `accept`, `maxSize`, and the file count
- *   (`maxFiles`, or 1 when the input is not `multiple`); rejects fire
- *   `stimeo--file-dropzone:reject` and set `data-…-invalid`.
- * - Accepted files render from `itemTemplate` with a `Remove {name}` button and an
- *   image thumbnail (`objectURL`); every change dispatches
- *   `stimeo--file-dropzone:change` with the current `File[]`.
+ *   over the `zone` adds files. The zone carries `data-dragover` for as long as the
+ *   pointer is anywhere inside it, descendants included — a `dragleave` whose
+ *   `relatedTarget` is still in the zone is the pointer crossing an inner element,
+ *   not leaving.
+ * - Each file is validated in order against `accept`, `maxSize`, duplication, and
+ *   the file count (`maxFiles`, or 1 when the input is not `multiple`). The reason
+ *   is therefore the most specific one: a file the zone would refuse whatever the
+ *   count says reports its own defect rather than `count`. Rejects fire
+ *   `stimeo--file-dropzone:reject` and set `data-…-invalid`, which the next batch
+ *   clears.
+ * - Two files count as the same when name, size, and last-modified time all match;
+ *   `allowDuplicates` turns the check off.
+ * - Accepted files render from `itemTemplate`; the template's own remove-button
+ *   `aria-label` is kept and its `{name}` expanded, so the accessible name stays in
+ *   the consumer's language. A template missing a part renders nothing, changes no
+ *   state, and reports itself once per connection.
+ * - 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.
  * - Removing a file revokes its `objectURL` and moves focus to the next (else
- *   previous) remove button, falling back to the trigger; `disconnect()` revokes
- *   every outstanding `objectURL`. Replacing the `list` target rebinds delegated
- *   removal and moves the client-only previews into the replacement.
+ *   previous) remove button, falling back to the trigger.
+ * - Additions, rejections, removals, and the drag affordance are handed to the
+ *   page's shared `stimeo--announcer` as one polite message each, worded by the
+ *   consumer (`{name}` is the file this message is about, `{count}` how many files
+ *   it covers, `{total}` how many are selected afterwards). Empty templates stay
+ *   silent, keeping announcements opt-in and i18n-neutral. One batch produces at
+ *   most one message per outcome, so dropping twenty files never reads twenty lines.
+ * - A drop into a disabled field is refused: with the input `disabled` or inside a
+ *   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.
+ * `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.
  */
 declare class FileDropzoneController extends Controller<HTMLElement> {
     #private;
@@ -53,45 +92,102 @@ declare class FileDropzoneController extends Controller<HTMLElement> {
             type: NumberConstructor;
             default: number;
         };
-        dragLabel: {
+        allowDuplicates: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        announceDragText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceAddedText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceRemovedText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceRejectedTypeText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceRejectedSizeText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceRejectedDuplicateText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceRejectedCountText: {
             type: StringConstructor;
             default: string;
         };
     };
     static actions: readonly ["onChange", "onDragLeave", "onDragOver", "onDrop", "openDialog"];
-    static events: readonly ["change", "reject"];
+    static events: readonly ["change", "reject", "reconcile"];
     readonly inputTarget: HTMLInputElement;
     readonly listTarget: HTMLElement;
     readonly listTargets: HTMLElement[];
     readonly triggerTarget: HTMLElement;
     readonly itemTemplateTarget: HTMLTemplateElement;
-    readonly statusTarget: HTMLElement;
+    readonly hasInputTarget: boolean;
     readonly hasListTarget: boolean;
     readonly hasTriggerTarget: boolean;
     readonly hasItemTemplateTarget: boolean;
-    readonly hasStatusTarget: boolean;
     readonly hasZoneTarget: boolean;
     readonly zoneTarget: HTMLElement;
     maxSizeValue: number;
     maxFilesValue: number;
-    dragLabelValue: string;
-    /** Wires file removal as a delegated listener on the list container. */
+    allowDuplicatesValue: boolean;
+    announceDragTextValue: string;
+    announceAddedTextValue: string;
+    announceRemovedTextValue: string;
+    announceRejectedTypeTextValue: string;
+    announceRejectedSizeTextValue: string;
+    announceRejectedDuplicateTextValue: string;
+    announceRejectedCountTextValue: string;
+    /** Subscribes to the Turbo cache rewind and re-arms the template diagnostic. */
     connect(): void;
-    /** Revokes any outstanding preview URLs so none leaks across navigations. */
+    /**
+     * Releases the delegated listeners. The selection itself survives an in-page
+     * move and is released only once the gate proves a real detach — revoking a
+     * preview URL on a move would leave a live item pointing at a dead `blob:`.
+     */
     disconnect(): void;
-    /** Rebinds removal and restores client-only previews when Turbo replaces the list target. */
+    /**
+     * 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.
+     */
     listTargetConnected(list: HTMLElement): void;
     /** Releases only the list target that actually disconnected. */
     listTargetDisconnected(list: HTMLElement): void;
     /** Opens the native file dialog. Bound via `data-action` (trigger click). */
     openDialog(): void;
-    /** Adds the files chosen through the native dialog. */
+    /**
+     * 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.
+     */
     onChange(): void;
-    /** Marks the zone as a drop target and announces the affordance in words. */
+    /**
+     * 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
+     * the drop, so a disabled field and a drag an inner dropzone already claimed
+     * both fall through untouched.
+     */
     onDragOver(event: DragEvent): void;
-    /** Clears the drag-over flag when the pointer leaves the zone. */
-    onDragLeave(): void;
-    /** Accepts dropped files, clearing the drag-over state. */
+    /**
+     * Clears the drag-over flag when the pointer leaves the zone. Bound via
+     * `data-action` (dragleave). `dragleave` bubbles from every descendant the
+     * pointer crosses, so the flag only drops when the element being entered is
+     * outside the zone (or there is none, the pointer having left the window).
+     */
+    onDragLeave(event: DragEvent): void;
+    /** Accepts dropped files, clearing the drag-over state. Bound via `data-action` (drop). */
     onDrop(event: DragEvent): void;
 }