cursedbelt 5.91.0 → 5.92.0

package/src/react/components/TagsInput.tsx

@@ -1,5 +1,5 @@
 import { X } from 'lucide-react';
-import { type KeyboardEvent, useId, useState } from 'react';
+import { type ComponentType, type KeyboardEvent, useEffect, useRef, useState } from 'react';
 import { cn } from '../lib/cn.js';
 import { CONTROL_MIN_HEIGHT_CLASS, type ControlSize } from '../lib/field.js';
 import { IconButton } from './IconButton.js';
@@ -16,9 +16,14 @@ export interface TagsInputProps {
   maxTags?: number;
   /**
    * Tags to offer as you type — the vocabulary already in use, so a re-tag matches
-   * the first spelling instead of minting "Bank"/"bank"/"banking" three ways. A
-   * native `<datalist>` (the browser owns the dropdown and its accessibility), and
-   * tags already committed on this value are not re-offered. Omit for none.
+   * the first spelling instead of minting "Bank"/"bank"/"banking" three ways. Drawn
+   * in the page by the kit's own list (Base UI Autocomplete), narrowed to what is
+   * typed; tags already committed on this value are not re-offered. Omit for none —
+   * and a field that omits it never loads that list's engine (see {@link TagsInput}).
+   *
+   * 🔴 Never a `<datalist>`: the browser draws its list outside the page, where no
+   * stylesheet reaches it — it popped up light in dark mode (owner, 2026-10-23,
+   * forge task 3602).
    */
   suggestions?: readonly string[];
   id?: string;
@@ -45,14 +50,142 @@ function mergeTags(current: string[], additions: string[]): string[] {
   return next;
 }
 
+/** What the suggesting field takes beyond the public props: the draft lives in {@link TagsInput},
+ *  so a word typed before the list's engine arrived is still there after it does. */
+export interface TagsFieldProps extends TagsInputProps {
+  draft: string;
+  setDraft: (draft: string) => void;
+  /** Focus the input on mount — the plain field had it when the engine arrived. */
+  initialFocus?: boolean;
+}
+
+/** The editing both fields share: commit, remove, the comma/Enter/Backspace keys, a pasted list. */
+export function useTagEditing({ value, onChange, draft, setDraft }: Pick<TagsFieldProps, 'value' | 'onChange' | 'draft' | 'setDraft'>) {
+  const commit = (raw: string) => {
+    const next = mergeTags(value, [raw]);
+    if (next.length !== value.length) onChange(next);
+    setDraft('');
+  };
+  const removeAt = (index: number) => onChange(value.filter((_, i) => i !== index));
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter' || e.key === ',') {
+      e.preventDefault();
+      if (draft.trim()) commit(draft);
+    } else if (e.key === 'Backspace' && draft === '' && value.length > 0) {
+      removeAt(value.length - 1);
+    }
+  };
+  /** A typed or pasted value: every comma commits what is before it, the rest stays the draft. */
+  const type = (v: string) => {
+    if (!v.includes(',')) return setDraft(v);
+    const parts = v.split(',');
+    const last = parts.pop() ?? '';
+    const merged = mergeTags(value, parts);
+    if (merged.length !== value.length) onChange(merged);
+    setDraft(last);
+  };
+  return { commit, removeAt, onKeyDown, type };
+}
+
+/** The chip row's frame — an Input-shaped container reading the field tokens. */
+export function tagsRowClass(size: ControlSize, disabled: boolean | undefined, className: string | undefined) {
+  return cn(
+    // `py-1`, not `py-1.5`: the empty row is a 20px line + 8px + 2px border, under the min-height, so it
+    // sits at exactly the control height beside an Input; `py-1.5` made it 38px next to a 36px one (FND-4).
+    // guardrails-ignore control-height-tokens: min-height chip-wrapping row (not fixed) — py- clears wrapped lines
+    'flex w-full flex-wrap items-center gap-1.5 rounded-field border border-field-border bg-field-bg px-2 py-1 transition focus-within:border-field-ring focus-within:ring-2 focus-within:ring-field-ring/30 aria-[invalid=true]:border-field-error',
+    CONTROL_MIN_HEIGHT_CLASS[size],
+    disabled && 'cursor-not-allowed opacity-50',
+    className,
+  );
+}
+
+export const TAGS_INPUT_CLASS =
+  'min-w-24 flex-1 bg-transparent py-0.5 text-base text-field-fg outline-none placeholder:text-field-placeholder sm:pointer-fine:text-sm';
+
+/** The committed tags as removable chips. */
+// no-attribute-forward: a list of chips with no element of its own — the row it sits in takes the caller's attributes
+export function TagChips({ value, disabled, onRemove }: { value: string[]; disabled?: boolean | undefined; onRemove: (index: number) => void }) {
+  return value.map((tag, i) => (
+    <span key={tag} className='inline-flex items-center gap-1 rounded bg-muted py-0.5 pl-2 pr-1 text-sm text-foreground'>
+      {tag}
+      <IconButton
+        label={`Remove ${tag}`}
+        disabled={disabled}
+        onClick={() => onRemove(i)}
+        className='h-auto min-h-0 w-auto size-4 rounded-sm p-0 text-muted-foreground hover:bg-border hover:text-foreground [&_svg]:size-3'
+      >
+        <X aria-hidden />
+      </IconButton>
+    </span>
+  ));
+}
+
+type SuggestingField = ComponentType<TagsFieldProps>;
+
+let loadedSuggesting: SuggestingField | null = null;
+let pendingSuggesting: Promise<SuggestingField> | null = null;
+
+/** Fetch the suggesting field (Base UI Autocomplete) once per page. */
+export function preloadSuggestingTagsInput(): Promise<SuggestingField> {
+  if (!pendingSuggesting) {
+    pendingSuggesting = import('./TagsInputSuggesting.js').then((m) => {
+      loadedSuggesting = m.default;
+      return m.default;
+    });
+  }
+  return pendingSuggesting;
+}
+
 /**
  * Comma / Enter-delimited tag input: pill chips inside an Input-shaped container that
  * reads the same field-style tokens (border / ring / invalid). Controlled —
  * `value: string[]`, `onChange(next)`. Type + Enter or comma to add (paste
  * "a,b,c" splits into three); the ✕ on a chip or Backspace on an empty input removes
  * one. Replaces the ad-hoc CommaTagsInput. The registry's `tags` control.
+ *
+ * ── Why the suggesting field is a dynamic `import()` ─────────────────────────
+ * 🔴 Suggestions are drawn by Base UI's Autocomplete, ~38 kB gzip. 5.92.0 rooted EVERY TagsInput
+ * in it, so a field that suggests nothing — station's disk-usage rules, every form's `tags`
+ * control — carried it: station's FolderSizesView chunk went 7.15 → 44.32 kB gzip (forge task
+ * 3614). A field given `suggestions` fetches it on mount (the same move as `InfoHint`); until it
+ * arrives — and for good, without `suggestions` — this file's plain input is the field, holding
+ * the draft and the focus it hands over.
  */
-export function TagsInput({
+export function TagsInput(props: TagsInputProps) {
+  const wantsList = props.suggestions !== undefined;
+  // `() => loadedSuggesting`: a component IS a function, and `useState(fn)` would call it.
+  const [Suggesting, setSuggesting] = useState<SuggestingField | null>(() => (wantsList ? loadedSuggesting : null));
+  const [draft, setDraft] = useState('');
+  const focused = useRef(false);
+
+  useEffect(() => {
+    if (!wantsList || Suggesting) return;
+    let alive = true;
+    void preloadSuggestingTagsInput().then((c) => {
+      if (alive) setSuggesting(() => c);
+    });
+    return () => {
+      alive = false;
+    };
+  }, [wantsList, Suggesting]);
+
+  if (wantsList && Suggesting) {
+    return <Suggesting {...props} draft={draft} setDraft={setDraft} initialFocus={focused.current} />;
+  }
+  return (
+    <PlainTagsField
+      {...props}
+      draft={draft}
+      setDraft={setDraft}
+      onFocusChange={(on) => {
+        focused.current = on;
+      }}
+    />
+  );
+}
+
+function PlainTagsField({
   value,
   onChange,
   onBlur,
@@ -61,112 +194,47 @@ export function TagsInput({
   maxTags,
   id,
   name,
-  suggestions,
+  suggestions: _suggestions,
   'aria-invalid': ariaInvalid,
   'aria-label': ariaLabel,
   'aria-describedby': ariaDescribedBy,
   className,
   size = 'md',
+  draft,
+  setDraft,
+  onFocusChange,
   ...rest
-}: TagsInputProps) {
-  const [draft, setDraft] = useState('');
-  const listId = useId();
+}: TagsFieldProps & { onFocusChange: (focused: boolean) => void }) {
+  const { commit, removeAt, onKeyDown, type } = useTagEditing({ value, onChange, draft, setDraft });
   const atMax = maxTags != null && value.length >= maxTags;
-  // Case-insensitive: a committed "Bank" must suppress the suggestion "bank" —
-  // offering it back commits nothing (mergeTags dedupes case-sensitively, so it
-  // WOULD land as a second chip) and reads as the field suggesting a duplicate.
-  const committed = new Set(value.map((tag) => tag.toLowerCase()));
-  const offered = (suggestions ?? []).filter((tag) => !committed.has(tag.toLowerCase()));
-
-  const commit = (raw: string) => {
-    const next = mergeTags(value, [raw]);
-    if (next.length !== value.length) onChange(next);
-    setDraft('');
-  };
-
-  const removeAt = (index: number) => onChange(value.filter((_, i) => i !== index));
-
-  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
-    if (e.key === 'Enter' || e.key === ',') {
-      e.preventDefault();
-      if (draft.trim()) commit(draft);
-    } else if (e.key === 'Backspace' && draft === '' && value.length > 0) {
-      removeAt(value.length - 1);
-    }
-  };
-
   return (
-    <div
-      {...rest}
-      aria-invalid={ariaInvalid}
-      className={cn(
-        // `py-1`, not `py-1.5`: the empty row is a 20px line + 8px + 2px border, under the min-height, so it
-        // sits at exactly the control height beside an Input; `py-1.5` made it 38px next to a 36px one (FND-4).
-        // guardrails-ignore control-height-tokens: min-height chip-wrapping row (not fixed) — py- clears wrapped lines
-        'flex w-full flex-wrap items-center gap-1.5 rounded-field border border-field-border bg-field-bg px-2 py-1 transition focus-within:border-field-ring focus-within:ring-2 focus-within:ring-field-ring/30 aria-[invalid=true]:border-field-error',
-        CONTROL_MIN_HEIGHT_CLASS[size],
-        disabled && 'cursor-not-allowed opacity-50',
-        className,
-      )}
-    >
-      {value.map((tag, i) => (
-        <span
-          key={tag}
-          className='inline-flex items-center gap-1 rounded bg-muted py-0.5 pl-2 pr-1 text-sm text-foreground'
-        >
-          {tag}
-          <IconButton
-            label={`Remove ${tag}`}
-            disabled={disabled}
-            onClick={() => removeAt(i)}
-            className='h-auto min-h-0 w-auto size-4 rounded-sm p-0 text-muted-foreground hover:bg-border hover:text-foreground [&_svg]:size-3'
-          >
-            <X aria-hidden />
-          </IconButton>
-        </span>
-      ))}
+    <div {...rest} aria-invalid={ariaInvalid} className={tagsRowClass(size, disabled, className)}>
+      <TagChips value={value} disabled={disabled} onRemove={removeAt} />
       {!atMax ? (
         <input
+          // guardrails-ignore no-raw-inputs: perf — the chip row is the field's frame, so its draft
+          // input is borderless; the Field-layer Input draws a second frame, and Base UI's (38 kB)
+          // is what this path exists to skip (forge task 3614).
           id={id}
           name={name}
-          // guardrails-ignore no-raw-inputs: this IS the TagsInput Field-family
-          // primitive — wraps the raw draft-tag text input it exposes.
-          type='text'
           value={draft}
+          onChange={(e) => type(e.target.value)}
           disabled={disabled}
           placeholder={value.length === 0 ? placeholder : undefined}
           aria-invalid={ariaInvalid}
           aria-label={ariaLabel}
           aria-describedby={ariaDescribedBy}
           autoComplete='off'
-          list={offered.length > 0 ? listId : undefined}
-          onChange={(e) => {
-            const v = e.target.value;
-            if (v.includes(',')) {
-              const parts = v.split(',');
-              const last = parts.pop() ?? '';
-              const merged = mergeTags(value, parts);
-              if (merged.length !== value.length) onChange(merged);
-              setDraft(last);
-            } else {
-              setDraft(v);
-            }
-          }}
           onKeyDown={onKeyDown}
+          onFocus={() => onFocusChange(true)}
           onBlur={() => {
+            onFocusChange(false);
             if (draft.trim()) commit(draft);
             onBlur?.();
           }}
-          className='min-w-24 flex-1 bg-transparent py-0.5 text-base text-field-fg outline-none placeholder:text-field-placeholder sm:pointer-fine:text-sm'
+          className={TAGS_INPUT_CLASS}
         />
       ) : null}
-      {offered.length > 0 ? (
-        <datalist id={listId}>
-          {offered.map((tag) => (
-            <option key={tag} value={tag} />
-          ))}
-        </datalist>
-      ) : null}
     </div>
   );
 }

package/src/react/components/TagsInputSuggesting.tsx

@@ -0,0 +1,94 @@
+import { Autocomplete } from '@base-ui/react/autocomplete';
+import { useLayoutEffect, useRef } from 'react';
+import { SuggestionList } from './suggestionList.js';
+import { TAGS_INPUT_CLASS, TagChips, type TagsFieldProps, tagsRowClass, useTagEditing } from './TagsInput.js';
+
+/**
+ * A `TagsInput` that suggests — the chip row as an Autocomplete input group, its list the kit's
+ * `SuggestionList`. Loaded by `TagsInput.tsx` with a dynamic `import()` only when a field is given
+ * `suggestions`; that file says why.
+ */
+export default function TagsInputSuggesting({
+  value,
+  onChange,
+  onBlur,
+  placeholder = 'Add a tag…',
+  disabled,
+  maxTags,
+  id,
+  name,
+  suggestions,
+  'aria-invalid': ariaInvalid,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+  className,
+  size = 'md',
+  draft,
+  setDraft,
+  initialFocus,
+  ...rest
+}: TagsFieldProps) {
+  const { commit, removeAt, onKeyDown, type } = useTagEditing({ value, onChange, draft, setDraft });
+  // Which suggestion the keyboard or pointer is on: Enter then picks IT, not the half-typed draft.
+  const highlighted = useRef<string | undefined>(undefined);
+  const input = useRef<HTMLInputElement>(null);
+  const atMax = maxTags != null && value.length >= maxTags;
+  // Case-insensitive: a committed "Bank" must suppress the suggestion "bank" —
+  // offering it back commits nothing (mergeTags dedupes case-sensitively, so it
+  // WOULD land as a second chip) and reads as the field suggesting a duplicate.
+  const committed = new Set(value.map((tag) => tag.toLowerCase()));
+  const offered = (suggestions ?? []).filter((tag) => !committed.has(tag.toLowerCase()));
+
+  // Mount-only: the plain field had the focus when this arrived, so the caret stays in the field.
+  // 🔴 A LAYOUT effect: it runs inside the commit that swaps the inputs. A passive one ran a task
+  // later, and a keystroke in between landed on <body> — the publish gate caught that gap under load.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a one-time hand-over, not a sync.
+  useLayoutEffect(() => {
+    if (initialFocus) input.current?.focus();
+  }, []);
+
+  return (
+    <Autocomplete.Root
+      value={draft}
+      onValueChange={(v, details) => {
+        // Picking a suggestion (a press, or Enter on the highlighted one) commits it as a tag.
+        if (details.reason === 'item-press') commit(v);
+        else type(v);
+      }}
+      items={offered}
+      disabled={disabled}
+      mode='list'
+      autoHighlight={false}
+      onItemHighlighted={(item) => {
+        highlighted.current = item;
+      }}
+    >
+      {/* The whole chip row is the input group, so the list opens under the field, not the caret. */}
+      <Autocomplete.InputGroup {...rest} aria-invalid={ariaInvalid} className={tagsRowClass(size, disabled, className)}>
+        <TagChips value={value} disabled={disabled} onRemove={removeAt} />
+        {!atMax ? (
+          <Autocomplete.Input
+            ref={input}
+            id={id}
+            name={name}
+            placeholder={value.length === 0 ? placeholder : undefined}
+            aria-invalid={ariaInvalid}
+            aria-label={ariaLabel}
+            aria-describedby={ariaDescribedBy}
+            autoComplete='off'
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' && highlighted.current !== undefined) return; // the list commits the pick
+              onKeyDown(e);
+            }}
+            onBlur={() => {
+              if (draft.trim()) commit(draft);
+              onBlur?.();
+            }}
+            className={TAGS_INPUT_CLASS}
+          />
+        ) : null}
+      </Autocomplete.InputGroup>
+      {offered.length > 0 ? <SuggestionList<string> /> : null}
+    </Autocomplete.Root>
+  );
+}

package/src/react/components/dropTransfer.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import { filesFromDataTransfer } from './dropTransfer.js';
+
+type Entry = {
+  isFile: boolean;
+  isDirectory: boolean;
+  name: string;
+  file?: (ok: (f: File) => void) => void;
+  createReader?: () => { readEntries: (ok: (e: Entry[]) => void) => void };
+};
+const file = (name: string, type: string) => new File(['x'], name, { type });
+const fileEntry = (f: File): Entry => ({ isFile: true, isDirectory: false, name: f.name, file: (ok) => ok(f) });
+/** A directory whose reader answers in batches of two, then empty — as browsers batch. */
+const dirEntry = (name: string, children: Entry[]): Entry => ({
+  isFile: false,
+  isDirectory: true,
+  name,
+  createReader: () => {
+    let at = 0;
+    return {
+      readEntries: (ok) => {
+        const batch = children.slice(at, at + 2);
+        at += 2;
+        ok(batch);
+      },
+    };
+  },
+});
+/** A DataTransfer whose item list empties once read past the first turn, as a browser's does. */
+const transfer = (entries: Entry[], files: File[]) => {
+  let live = true;
+  queueMicrotask(() => (live = false));
+  return {
+    files,
+    get items() {
+      return live ? entries.map((entry) => ({ kind: 'file', webkitGetAsEntry: () => entry })) : [];
+    },
+  } as unknown as DataTransfer;
+};
+
+describe('filesFromDataTransfer', () => {
+  test('walks a dropped folder: nested files, each with its path in the drop; hidden and turned-away skipped', async () => {
+    const album = dirEntry('Holiday', [
+      fileEntry(file('IMG_0001.JPG', 'image/jpeg')),
+      fileEntry(file('.DS_Store', '')),
+      fileEntry(file('notes.txt', 'text/plain')),
+      dirEntry('Day 2', [fileEntry(file('IMG_0002.JPG', 'image/jpeg')), fileEntry(file('IMG_0003.JPG', 'image/jpeg'))]),
+      dirEntry('.thumbnails', [fileEntry(file('t.jpg', 'image/jpeg'))]),
+    ]);
+    const loose = file('portrait.png', 'image/png');
+    const got = await filesFromDataTransfer(
+      transfer([fileEntry(loose), album], [loose, file('Holiday', '')]),
+      'image/*',
+    );
+    expect(got.map((f) => f.webkitRelativePath || f.name)).toEqual([
+      'portrait.png',
+      'Holiday/IMG_0001.JPG',
+      'Holiday/Day 2/IMG_0002.JPG',
+      'Holiday/Day 2/IMG_0003.JPG',
+    ]);
+  });
+
+  test('a drop with no folder is its files, filtered — no walk', async () => {
+    const got = await filesFromDataTransfer(
+      transfer([], [file('a.png', 'image/png'), file('b.txt', 'text/plain'), file('.hidden.png', 'image/png')]),
+      'image/*',
+    );
+    expect(got.map((f) => f.name)).toEqual(['a.png']);
+  });
+
+  test('stops at the limit', async () => {
+    const many = Array.from({ length: 7 }, (_, i) => fileEntry(file(`${i}.jpg`, 'image/jpeg')));
+    const got = await filesFromDataTransfer(transfer([dirEntry('Big', many)], [file('Big', '')]), undefined, { limit: 3 });
+    expect(got).toHaveLength(3);
+  });
+});

package/src/react/components/dropTransfer.ts

@@ -0,0 +1,133 @@
+/**
+ * A drop's FILES, with every dropped FOLDER walked for what is inside it — the one walk
+ * {@link FileDropZone} and every app's own drop target share (forge task 3579's follow-up).
+ *
+ * `DataTransfer.files` lists a dropped folder as one zero-byte entry and nothing in it. The File
+ * and Directory Entries API (`webkitGetAsEntry`) is the only door every browser ships, and it has
+ * three traps each copy of this walk had to rediscover:
+ *
+ * - 🔴 the entries must be taken SYNCHRONOUSLY, before the first `await` — a browser empties the
+ *   `DataTransfer` once the drop event returns, and a late walk finds nothing, silently;
+ * - a directory's reader answers in batches (Chrome: 100) until it answers EMPTY — one call
+ *   truncates a folder of 1,000 photos to 100;
+ * - a dropped file's `webkitRelativePath` is `''`, so each file here gets its path inside the drop
+ *   (`Album/CD1/01.mp3`), exactly as a folder PICKER's files carry natively — an app keying a
+ *   duplicate check or provenance on it gets one answer from both gestures.
+ *
+ * Hidden entries (`.DS_Store`, `.thumbnails`) are never what somebody meant and are skipped.
+ */
+
+/** The slice of the File and Directory Entries API a drop needs — every browser ships it. */
+interface DropEntry {
+  isFile: boolean;
+  isDirectory: boolean;
+  name: string;
+  file?: (ok: (file: File) => void, fail: (error: unknown) => void) => void;
+  createReader?: () => {
+    readEntries: (ok: (entries: DropEntry[]) => void, fail: (error: unknown) => void) => void;
+  };
+}
+
+/** What one drop may yield by default — a drop, not a disk scan. */
+export const MAX_DROP_FILES = 5000;
+
+export const isHiddenName = (name: string): boolean => name.startsWith('.');
+
+/**
+ * Whether `file` passes an `<input accept>` filter — `.mp3`, `image/*`, `application/zip`, comma
+ * separated. A drop bypasses the native `accept`, so a drop target re-filters with this.
+ */
+export const matchesAccept = (file: File, accept?: string): boolean => {
+  if (!accept) return true;
+  return accept.split(',').some((raw) => {
+    const rule = raw.trim().toLowerCase();
+    if (!rule) return false;
+    if (rule.startsWith('.')) return file.name.toLowerCase().endsWith(rule);
+    if (rule.endsWith('/*')) return file.type.toLowerCase().startsWith(rule.slice(0, -1));
+    return file.type.toLowerCase() === rule;
+  });
+};
+
+/** Every file under `entry`, depth-first, until `out` holds `limit`. */
+async function filesUnder(entry: DropEntry, out: File[], limit: number, prefix = ''): Promise<void> {
+  if (out.length >= limit || isHiddenName(entry.name)) return;
+  if (entry.isFile && entry.file) {
+    const read = entry.file.bind(entry);
+    const file = await new Promise<File>((ok, fail) => read(ok, fail));
+    Object.defineProperty(file, 'webkitRelativePath', { value: `${prefix}${file.name}`, configurable: true });
+    out.push(file);
+    return;
+  }
+  if (!entry.isDirectory || !entry.createReader) return;
+  const reader = entry.createReader();
+  while (out.length < limit) {
+    const batch = await new Promise<DropEntry[]>((ok, fail) => reader.readEntries(ok, fail));
+    if (batch.length === 0) return;
+    for (const child of batch) await filesUnder(child, out, limit, `${prefix}${entry.name}/`);
+  }
+}
+
+/** A drop, read: the loose files as dropped, and each dropped folder with the files found inside it. */
+export interface DropWalk {
+  loose: File[];
+  folders: { name: string; files: File[] }[];
+}
+
+/**
+ * Reads a drop that holds at least one folder — `null` when it holds none, so the ordinary path
+ * stays exactly `transfer.files`. Call it from the drop handler itself, before any `await`.
+ * Each folder yields up to `limit` files; an unreadable one yields what was read before the error.
+ */
+export function walkDrop(transfer: DataTransfer, limit = MAX_DROP_FILES): Promise<DropWalk> | null {
+  // Synchronous, and first: the item list is tied to the event.
+  const items = transfer.items ? [...transfer.items] : [];
+  const entries = items.map((item) =>
+    item.kind === 'file' && typeof item.webkitGetAsEntry === 'function'
+      ? (item.webkitGetAsEntry() as DropEntry | null)
+      : null,
+  );
+  if (!entries.some((entry) => entry?.isDirectory)) return null;
+  const looseFiles = [...transfer.files];
+  return (async () => {
+    const walk: DropWalk = { loose: [], folders: [] };
+    for (const [i, entry] of entries.entries()) {
+      if (!entry?.isDirectory) {
+        const file =
+          looseFiles[i] ?? (entry ? await new Promise<File | null>((ok) => entry.file?.(ok, () => ok(null))) : null);
+        if (file) walk.loose.push(file);
+        continue;
+      }
+      const files: File[] = [];
+      try {
+        await filesUnder(entry, files, limit);
+      } catch {
+        // Keep what was read before the error; the caller decides what an empty folder means.
+      }
+      walk.folders.push({ name: entry.name, files });
+    }
+    return walk;
+  })();
+}
+
+/**
+ * Every file in a drop, folders walked — the loose files, then each folder's — with what `accept`
+ * turns away and hidden files skipped, at most `limit` in all. For a drop target that is not a
+ * {@link FileDropZone}: a portrait, an open album, a whole page.
+ *
+ *   onDrop={(event) => { event.preventDefault(); void filesFromDataTransfer(event.dataTransfer, 'image/*').then(upload); }}
+ *
+ * 🔴 Call it from the drop handler itself, before any `await` (see the file header).
+ */
+export function filesFromDataTransfer(
+  transfer: DataTransfer,
+  accept?: string,
+  { limit = MAX_DROP_FILES }: { limit?: number } = {},
+): Promise<File[]> {
+  const keep = (file: File) => !isHiddenName(file.name) && matchesAccept(file, accept);
+  const walking = walkDrop(transfer, limit);
+  if (!walking) return Promise.resolve([...transfer.files].filter(keep).slice(0, limit));
+  return walking.then(({ loose, folders }) => {
+    const all = [...loose, ...folders.flatMap((folder) => folder.files)];
+    return all.filter(keep).slice(0, limit);
+  });
+}

package/src/react/components/suggestionList.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { Autocomplete } from '@base-ui/react/autocomplete';
+import type { ReactNode } from 'react';
+import { cn } from '../lib/cn.js';
+import { FLOATING_COLLISION_PADDING,
+  FLOATING_CONTENT_BASE, FLOATING_ITEM_BASE } from '../lib/floatingStyles.js';
+
+/**
+ * The dropdown of an Autocomplete root — every kit field that suggests as you type draws its list
+ * with this one, so the list is the kit's in every theme (`TagsInput` as well as
+ * `AutocompleteField`). Kept out of every export: it is the inside of those two, not a part an app
+ * assembles. Never a `<datalist>`: the browser draws that outside the page, where no
+ * stylesheet reaches it — light in dark mode (owner, 2026-10-23; forge task 3602).
+ */
+// no-attribute-forward: its root is Base UI's Portal — no element of its own; the popup is the kit's, not the caller's
+export function SuggestionList<S>({
+  itemToString = (item) => String(item),
+  renderSuggestion,
+}: {
+  itemToString?: (item: S) => string;
+  renderSuggestion?: ((item: S) => ReactNode) | undefined;
+}) {
+  return (
+    <Autocomplete.Portal>
+      {/* 🔴 The z-index goes on the POSITIONER, not only the popup. Base UI's positioner is
+          the element that is `position: absolute` (with a transform); the popup inside it is
+          `position: static`, so the popup's own `z-[var(--z-popover)]` does nothing and the
+          list painted UNDER any sibling with a z-index — measured 2026-09-22 in the
+          binary-server inspector, a sticky table header (z-index 1) covering the second option
+          of an open MultiSelectField. */}
+      <Autocomplete.Positioner
+        sideOffset={4}
+        collisionPadding={FLOATING_COLLISION_PADDING}
+        className='z-[var(--z-popover)]'
+      >
+        <Autocomplete.Popup
+          className={cn(
+            FLOATING_CONTENT_BASE,
+            // guardrails-ignore no-raw-overflow: floating popover panel outside the page's ScrollArea, height-capped by max-h-64 — no keyboard-inset concern.
+            'max-h-64 min-w-[var(--anchor-width)] overflow-y-auto p-0 py-1',
+            'transition-[transform,opacity] duration-100',
+            'data-[starting-style]:scale-95 data-[starting-style]:opacity-0',
+            'data-[ending-style]:scale-95 data-[ending-style]:opacity-0',
+          )}
+        >
+          {/* 🔴 The render function, never `items.map`: Base UI hands it the FILTERED items.
+              Mapping the array drew every suggestion whatever was typed — music-stage offered
+              every folder for "zz" (forge task 3602). */}
+          <Autocomplete.List>
+            {(s: S, index: number) => (
+              <Autocomplete.Item
+                key={itemToString(s)}
+                value={s}
+                index={index}
+                className={cn(FLOATING_ITEM_BASE, 'data-[highlighted]:bg-accent/10 data-[highlighted]:text-accent-strong')}
+              >
+                {renderSuggestion ? renderSuggestion(s) : itemToString(s)}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Popup>
+      </Autocomplete.Positioner>
+    </Autocomplete.Portal>
+  );
+}

package/src/react/disk-usage/DiskUsage.spec.tsx

@@ -188,6 +188,9 @@ describe('DiskUsageRulesEditor', () => {
     fireEvent.click(save());
     expect(onSave).not.toHaveBeenCalled();
 
+    // The rules fields suggest nothing, so each is TagsInput's plain draft input — never the
+    // Autocomplete combobox, whose engine a field without suggestions does not load (forge task 3614).
+    expect(screen.queryAllByRole('combobox')).toEqual([]);
     const inputs = screen.getAllByRole('textbox');
     fireEvent.change(inputs[1], { target: { value: 'huge-archive' } });
     fireEvent.keyDown(inputs[1], { key: 'Enter' });