@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/RichTextEditor/useLinkEditor.ts

@@ -0,0 +1,107 @@
+import { useCallback, useRef, useState } from 'react';
+import type { RichDoc, Range } from '../RichText/engine/model';
+import type { EditKind } from './history';
+import { linkAt, setLink, removeLink } from './links';
+import { readSelection, writeSelection, selectionRect, type Rect } from './selection';
+
+/** Open-state of the floating link editor: the captured model range, the href
+ * being edited, whether it's editing an existing link (vs. creating) — which
+ * gates the Remove action and the empty-href→remove branch — the anchor rect to
+ * position against, and a `key` that remounts the bubble on each open. */
+export interface LinkEditorOpen {
+  range: Range;
+  href: string;
+  editing: boolean;
+  anchorRect: Rect;
+  key: number;
+}
+
+interface UseLinkEditorArgs {
+  /** The editable root — read to resolve the live selection and to refocus. */
+  rootRef: React.RefObject<HTMLDivElement | null>;
+  /** The editor's commit path (history + onChange round-trip). */
+  commit: (result: { doc: RichDoc; selection: Range }, kind?: EditKind) => void;
+  /** The synchronously-latest controlled doc (`() => latest.current.value`). */
+  getValue: () => RichDoc;
+  /** The synchronously-latest readOnly flag (`() => latest.current.readOnly`). */
+  getReadOnly: () => boolean;
+}
+
+/**
+ * The link-editor cluster, extracted from `RichTextEditor`: owns the open-state
+ * and the apply/remove/cancel handlers for the floating link editor. The editor
+ * keeps the `<RichTextLinkEditor>` JSX (it needs `rangeRect`/`rootRef` from
+ * render scope) and the toolbar's `linkActive` derivation (a render-memo on the
+ * live selection, not on this open-state) — only the state + handlers live here.
+ *
+ * Returns the open-state plus stable handlers. `openLinkEditor` opens for the
+ * live selection (editing the link under the caret if there is one — href
+ * pre-filled, Remove available — else creating over the selection, inserting at
+ * a collapsed caret on Apply); `onLinkApply`/`onLinkRemove` route through
+ * `commit`; `onLinkCancel` restores the captured selection and refocuses.
+ */
+export function useLinkEditor({ rootRef, commit, getValue, getReadOnly }: UseLinkEditorArgs) {
+  // Link editor state.
+  const [linkEditor, setLinkEditor] = useState<LinkEditorOpen | null>(null);
+  const linkKeyRef = useRef(0);
+
+  // Open the link editor for the live selection: edit the link under the caret
+  // if there is one (href pre-filled, Remove available), else create over the
+  // selection (or insert at a collapsed caret on Apply).
+  const openLinkEditor = useCallback(() => {
+    if (getReadOnly()) return;
+    const root = rootRef.current;
+    if (!root) return;
+    const range = readSelection(root);
+    if (!range) return;
+    const existing = linkAt(getValue(), range.focus);
+    const anchorRect = selectionRect(root);
+    linkKeyRef.current += 1;
+    setLinkEditor(
+      existing
+        ? {
+            range: existing.range,
+            href: existing.href,
+            editing: true,
+            anchorRect,
+            key: linkKeyRef.current,
+          }
+        : { range, href: '', editing: false, anchorRect, key: linkKeyRef.current },
+    );
+  }, [rootRef, getValue, getReadOnly]);
+
+  const onLinkApply = useCallback(
+    (href: string) => {
+      const le = linkEditor;
+      if (!le) return;
+      const trimmed = href.trim();
+      if (trimmed !== '') {
+        commit(setLink(getValue(), le.range, trimmed));
+      } else if (le.editing) {
+        commit(removeLink(getValue(), le.range));
+      }
+      // empty href while creating → just close (cancel).
+      setLinkEditor(null);
+      rootRef.current?.focus();
+    },
+    [linkEditor, commit, getValue, rootRef],
+  );
+
+  const onLinkRemove = useCallback(() => {
+    const le = linkEditor;
+    if (!le) return;
+    commit(removeLink(getValue(), le.range));
+    setLinkEditor(null);
+    rootRef.current?.focus();
+  }, [linkEditor, commit, getValue, rootRef]);
+
+  const onLinkCancel = useCallback(() => {
+    const le = linkEditor;
+    setLinkEditor(null);
+    const root = rootRef.current;
+    if (root && le) writeSelection(root, le.range);
+    root?.focus();
+  }, [linkEditor, rootRef]);
+
+  return { linkEditor, openLinkEditor, onLinkApply, onLinkRemove, onLinkCancel };
+}

package/src/components/RichTextEditor/useMention.ts

@@ -0,0 +1,226 @@
+// useMention.ts — menu-state hook for RichTextEditor @-mention autocomplete.
+// Owns context detection (driven by the editor's selection/content cycle), async
+// querying with stale-drop, and the active-index for keyboard navigation. DOM
+// glue only; the pure decision lives in mentionContext.ts.
+import { useCallback, useId, useRef, useState } from 'react';
+import type { RichDoc, Range } from '../RichText/engine/model';
+import { runsText } from '../RichText/engine/inlines';
+import { isCollapsed } from '../RichText/engine/position';
+import { selectionRect, type Rect } from './selection';
+import { getMentionContext } from './mentionContext';
+import type { MentionItem } from './mentions';
+
+export interface UseMentionParams {
+  enabled: boolean;
+  rootRef: React.RefObject<HTMLElement | null>;
+  doc: RichDoc;
+  trigger: string;
+  onQuery?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  /** Perform the insertion (editor wires this to commit(insertMention(...))). */
+  onInsert: (
+    blockId: string,
+    range: { from: number; to: number },
+    trigger: string,
+    item: MentionItem,
+  ) => void;
+}
+
+export interface UseMentionResult {
+  open: boolean;
+  items: MentionItem[];
+  activeIndex: number;
+  anchorRect: Rect | null;
+  /**
+   * Read the caret rect LIVE (current viewport coords). The menu's Floating UI
+   * virtual anchor calls this on every `autoUpdate` (incl. scroll/resize) so the
+   * menu tracks the caret instead of sticking to the rect captured on open — the
+   * static `anchorRect` only updates on `selectionchange`, which scroll doesn't fire.
+   */
+  getAnchorRect: () => Rect | null;
+  listboxId: string;
+  activeOptionId: string | undefined;
+  getOptionId: (index: number) => string;
+  /**
+   * Recompute the menu from a model selection the EDITOR already read. The hook no
+   * longer owns a `selectionchange` listener — the editor drives this from its
+   * single consolidated subscription, passing the selection it read once. A
+   * `null` / non-collapsed / out-of-trigger-context selection closes the menu.
+   */
+  recompute: (sel: Range | null) => void;
+  setActiveIndex: (index: number) => void;
+  move: (delta: 1 | -1) => void;
+  selectIndex: (index: number) => void;
+  commitActive: () => void;
+  close: () => void;
+}
+
+/** True when two Rect values are equal (avoids spurious re-renders). */
+function rectEqual(a: Rect | null, b: Rect | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+}
+
+export function useMention(params: UseMentionParams): UseMentionResult {
+  const { enabled, rootRef, doc, trigger, onQuery, onInsert } = params;
+  const baseId = useId();
+  const listboxId = `${baseId}-mention-listbox`;
+  const getOptionId = useCallback((index: number) => `${baseId}-mention-opt-${index}`, [baseId]);
+
+  const [open, setOpen] = useState(false);
+  const [items, setItems] = useState<MentionItem[]>([]);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [anchorRect, setAnchorRect] = useState<Rect | null>(null);
+
+  // Detected context (block + range), kept in a ref for commitActive.
+  const ctxRef = useRef<{ blockId: string; from: number; to: number } | null>(null);
+  // Monotonic token to drop stale async resolutions.
+  const queryToken = useRef(0);
+  // Last query string we issued (dedupe redundant onQuery calls).
+  const lastQuery = useRef<string | null>(null);
+  // Track open + anchorRect in refs for stable-function pattern.
+  const openRef = useRef(false);
+  const anchorRectRef = useRef<Rect | null>(null);
+
+  // Keep latest props in refs so recompute() is stable and doesn't cause effect re-fires.
+  const enabledRef = useRef(enabled);
+  const docRef = useRef(doc);
+  const triggerRef = useRef(trigger);
+  const onQueryRef = useRef(onQuery);
+  enabledRef.current = enabled;
+  docRef.current = doc;
+  triggerRef.current = trigger;
+  onQueryRef.current = onQuery;
+
+  const close = useCallback(() => {
+    openRef.current = false;
+    setOpen(false);
+    anchorRectRef.current = null;
+    setAnchorRect(null);
+    ctxRef.current = null;
+    lastQuery.current = null;
+    queryToken.current += 1; // invalidate any in-flight query
+  }, []);
+
+  const runQuery = useCallback(
+    (query: string) => {
+      const qFn = onQueryRef.current;
+      if (!qFn) return;
+      const token = (queryToken.current += 1);
+      Promise.resolve(qFn(query)).then(
+        (resolved) => {
+          if (token !== queryToken.current) return; // stale
+          setItems(resolved);
+          setActiveIndex(0);
+        },
+        () => {
+          if (token !== queryToken.current) return;
+          setItems([]);
+          setActiveIndex(0);
+        },
+      );
+    },
+    [], // stable: reads onQueryRef.current
+  );
+
+  // Stable recompute — reads all mutable values via refs, never recreated. The
+  // editor passes the model selection it already read from its single
+  // `selectionchange` listener, so the menu doesn't re-walk the DOM here.
+  const recompute = useCallback(
+    (sel: Range | null) => {
+      const root = rootRef.current;
+      const qFn = onQueryRef.current;
+      if (!enabledRef.current || !root || !qFn) {
+        if (openRef.current) close();
+        return;
+      }
+      if (!sel || !isCollapsed(sel)) {
+        if (openRef.current) close();
+        return;
+      }
+      const currentDoc = docRef.current;
+      const block = currentDoc.blocks.find((b) => b.id === sel.anchor.blockId);
+      if (!block) {
+        if (openRef.current) close();
+        return;
+      }
+      const text = runsText(block.inlines);
+      const trig = triggerRef.current;
+      const ctx = getMentionContext(text, sel.anchor.offset, trig);
+      if (!ctx) {
+        if (openRef.current) close();
+        return;
+      }
+      ctxRef.current = {
+        blockId: block.id,
+        from: ctx.triggerOffset,
+        to: ctx.triggerOffset + trig.length + ctx.query.length,
+      };
+      // Only update anchorRect state if the value changed (prevents render loops).
+      const newRect = selectionRect(root);
+      if (!rectEqual(anchorRectRef.current, newRect)) {
+        anchorRectRef.current = newRect;
+        setAnchorRect(newRect);
+      }
+      // Only flip open state if not already open (prevents render loops).
+      if (!openRef.current) {
+        openRef.current = true;
+        setOpen(true);
+      }
+      if (ctx.query !== lastQuery.current) {
+        lastQuery.current = ctx.query;
+        runQuery(ctx.query);
+      }
+    },
+    [rootRef, close, runQuery], // stable: reads props via refs
+  );
+
+  const move = useCallback(
+    (delta: 1 | -1) => {
+      setActiveIndex((i) => {
+        const n = items.length;
+        if (n === 0) return 0;
+        return (i + delta + n) % n;
+      });
+    },
+    [items.length],
+  );
+
+  const selectIndex = useCallback(
+    (index: number) => {
+      const ctx = ctxRef.current;
+      const item = items[index];
+      if (!ctx || !item) return;
+      onInsert(ctx.blockId, { from: ctx.from, to: ctx.to }, triggerRef.current, item);
+      close();
+    },
+    [items, onInsert, close],
+  );
+
+  const commitActive = useCallback(() => selectIndex(activeIndex), [selectIndex, activeIndex]);
+
+  // Live caret rect — read on demand (current viewport coords). Stable identity so
+  // the menu's virtual anchor doesn't churn; Floating UI's autoUpdate calls it on
+  // scroll/resize so the menu follows the caret.
+  const getAnchorRect = useCallback((): Rect | null => {
+    const root = rootRef.current;
+    return root ? selectionRect(root) : null;
+  }, [rootRef]);
+
+  return {
+    open,
+    items,
+    activeIndex,
+    anchorRect,
+    getAnchorRect,
+    listboxId,
+    activeOptionId: open && items.length > 0 ? getOptionId(activeIndex) : undefined,
+    getOptionId,
+    recompute,
+    setActiveIndex,
+    move,
+    selectIndex,
+    commitActive,
+    close,
+  };
+}

package/src/components/RichTextEditor/useOverlayRect.ts

@@ -0,0 +1,73 @@
+// useOverlayRect.ts — shared gutter/handle overlay plumbing for <RichTextEditor>.
+// The block-controls gutter and the image resize handle both (a) measure a target
+// element's box relative to the editor shell, retrying across the mount race, and
+// (b) report drag start/end while guarding against a mid-drag unmount. Both live
+// here so the two overlays don't reimplement them. Internal; NOT exported from
+// the package.
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type RefObject } from 'react';
+
+/** A box measured relative to the editor shell (top/left/width/height, all in px). */
+export interface ShellRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Measure `getEl()`'s box relative to the shell (`rootRef`), re-running whenever
+ * `key` or `getEl` changes. Returns `null` when the shell or target element is
+ * missing, retrying up to twice — the parent's element ref can attach after this
+ * child's layout pass on mount, so the first measurement can race and come up empty.
+ * Callers derive whatever they need from the returned rect (gutter: top/height;
+ * resize handle: the bottom-right corner = top+height / left+width).
+ */
+export function useShellRelativeRect(
+  rootRef: RefObject<HTMLElement | null>,
+  getEl: () => HTMLElement | null,
+  key: unknown,
+): ShellRect | null {
+  const [rect, setRect] = useState<ShellRect | null>(null);
+  // Bumped to re-run measurement when the shell ref / target element is not yet
+  // attached on the first layout-effect pass. Capped at 2.
+  const [retry, setRetry] = useState(0);
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    const el = getEl();
+    if (!root || !el) {
+      setRect(null);
+      if (retry < 2) setRetry((n) => n + 1);
+      return;
+    }
+    const rootBox = root.getBoundingClientRect();
+    const box = el.getBoundingClientRect();
+    setRect({
+      top: box.top - rootBox.top,
+      left: box.left - rootBox.left,
+      width: box.width,
+      height: box.height,
+    });
+  }, [rootRef, getEl, key, retry]);
+  return rect;
+}
+
+/**
+ * Returns a stable setter to report drag start/end, and fires `onDraggingChange(false)`
+ * on unmount — so an overlay that unmounts mid-drag (its content removed, the editor
+ * toggled to read-only, etc.) never leaves the editor stuck in a dragging state (no
+ * pointerup/cancel fires in that case). The setter reads the latest `onDraggingChange`
+ * via a ref, so it stays referentially stable across renders.
+ */
+export function useDraggingReporter(
+  onDraggingChange?: (dragging: boolean) => void,
+): (dragging: boolean) => void {
+  // Latest callback, read by the stable setter + the unmount cleanup without resubscribing.
+  const ref = useRef(onDraggingChange);
+  ref.current = onDraggingChange;
+  useEffect(() => {
+    return () => {
+      ref.current?.(false);
+    };
+  }, []);
+  return useCallback((dragging: boolean) => ref.current?.(dragging), []);
+}

package/src/components/RichTextEditor/useUpload.ts

@@ -0,0 +1,246 @@
+// useUpload.ts — drives the attachment upload lifecycle for RichTextEditor. Owns
+// the in-flight File map (for retry), inserts spinner blocks, runs onUpload in
+// parallel, and settles each block by id. Editor I/O is injected so the hook is
+// unit-testable without a DOM editor.
+import { useCallback, useRef } from 'react';
+import type { RichDoc, Point } from '../RichText/engine/model';
+import { emptyDoc } from '../RichText/engine/model';
+import {
+  insertAttachmentBlock,
+  updateAttachmentBlock,
+  clearAttachmentFields,
+} from '../RichText/engine/attachment';
+import { computeDisplaySize, measureImageFromFile, type NaturalSize } from './imageSize';
+
+/** What a consumer's upload handler must resolve with. */
+export interface UploadResult {
+  /** Where the uploaded file now lives. Required. */
+  url: string;
+  /** Display name; defaults to the File's name. */
+  name?: string;
+  /** MIME type; defaults to the File's type. Decides image-preview vs file-chip. */
+  mime?: string;
+  /**
+   * NATURAL pixel dimensions of the image (not the on-screen size). The editor
+   * derives the initial display size from these — scaling by the device pixel
+   * ratio and capping to the editor width — so a retina screenshot isn't inserted
+   * at 2× its perceived size. Omit them and the editor measures the file itself.
+   */
+  width?: number;
+  height?: number;
+  /** Initial alt text. */
+  alt?: string;
+}
+
+/**
+ * Reject `onUpload` with this to show `message` on the failed attachment block
+ * (e.g. the server's "The file may not be larger than 5 MB."). Any other
+ * rejection shows only the generic "Upload failed", so raw network/library
+ * errors never reach the user. Write `message` for end users, localized.
+ */
+export class UploadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UploadError';
+  }
+}
+
+/** Consumer config for `RichTextEditor`'s `upload` prop. */
+export interface UploadConfig {
+  /** Upload one file; resolve with where it landed, reject to show an error (reject with an `UploadError` to show its message). */
+  onUpload: (file: File) => Promise<UploadResult>;
+  /** Optional native file-picker filter, e.g. "image/*,.pdf". Convenience only —
+   *  it does NOT enforce types (paste bypasses it); enforce in `onUpload`. */
+  accept?: string;
+  /** Fired with `true` while ≥1 upload is in flight, `false` when all settle. */
+  onUploadingChange?: (uploading: boolean) => void;
+}
+
+interface UseUploadArgs {
+  config: UploadConfig;
+  getValue: () => RichDoc;
+  /** Apply the synchronous spinner-block insert (records ONE undo step). */
+  applyInsert: (doc: RichDoc) => void;
+  /** Apply an async settle patch (resolve/error) WITHOUT a new undo step. */
+  applySettle: (doc: RichDoc) => void;
+  /** Current caret Point (where to insert). */
+  getCaret: () => Point;
+  /** Measure an image File's natural pixel size (injectable for tests). */
+  measureImage?: (file: File) => Promise<NaturalSize | null>;
+  /** Editor content width in CSS px — caps a pasted image's initial width. `0` = no cap. */
+  getContentWidth?: () => number;
+  /** Current device pixel ratio (injectable for tests). */
+  getDevicePixelRatio?: () => number;
+  /**
+   * Upload-failure feed for the editor's live region: `null` when an attempt
+   * starts (clears the last message, so a repeat failure re-announces), the
+   * file name + optional `UploadError` reason when it fails.
+   */
+  onFailureChange?: (failure: { name: string; reason?: string } | null) => void;
+}
+
+export function useUpload({
+  config,
+  getValue,
+  applyInsert,
+  applySettle,
+  getCaret,
+  measureImage = measureImageFromFile,
+  getContentWidth = () => 0,
+  getDevicePixelRatio = () => (typeof window !== 'undefined' && window.devicePixelRatio) || 1,
+  onFailureChange,
+}: UseUploadArgs) {
+  const filesRef = useRef(new Map<string, File>()); // block id → File (for retry)
+  const inflightRef = useRef(0);
+
+  const setInflight = useCallback(
+    (delta: number) => {
+      const prev = inflightRef.current;
+      inflightRef.current = Math.max(0, prev + delta);
+      if (prev === 0 && inflightRef.current > 0) config.onUploadingChange?.(true);
+      if (prev > 0 && inflightRef.current === 0) config.onUploadingChange?.(false);
+    },
+    [config],
+  );
+
+  const runUpload = useCallback(
+    (id: string, file: File) => {
+      setInflight(1);
+      onFailureChange?.(null);
+      config
+        .onUpload(file)
+        .then(
+          async (res) => {
+            filesRef.current.delete(id);
+            // Natural dims: prefer the consumer's reported size (documented as
+            // natural px), else measure the File. Then lay out at perceived size
+            // (÷DPR) capped to the editor width — so a retina screenshot doesn't
+            // come in at 2× the size you saw.
+            let naturalW = res.width;
+            let naturalH = res.height;
+            // Only a COMPLETE consumer pair short-circuits the measure; if either is
+            // missing we measure and take the measured pair WHOLESALE, so a partial
+            // (and possibly inconsistent) consumer value can't distort the aspect.
+            // The measure is best-effort — a throwing injected measurer must not
+            // strand the block mid-upload, so swallow and fall back to "unsized".
+            if (naturalW == null || naturalH == null) {
+              let measured: NaturalSize | null = null;
+              try {
+                measured = await measureImage(file);
+              } catch {
+                measured = null;
+              }
+              naturalW = measured?.width ?? naturalW;
+              naturalH = measured?.height ?? naturalH;
+            }
+            const display = computeDisplaySize(
+              naturalW,
+              naturalH,
+              getDevicePixelRatio(),
+              getContentWidth(),
+            );
+            applySettle(
+              updateAttachmentBlock(getValue(), id, {
+                status: 'ready',
+                src: res.url,
+                name: res.name ?? file.name,
+                mime: res.mime ?? file.type,
+                width: display?.width,
+                height: display?.height,
+                alt: res.alt,
+              }),
+            );
+          },
+          (err: unknown) => {
+            // Opt-in only: a plain Error's message ("Failed to fetch", …) is not
+            // written for end users.
+            const reason = err instanceof UploadError && err.message ? err.message : undefined;
+            applySettle(
+              updateAttachmentBlock(getValue(), id, { status: 'error', uploadError: reason }),
+            );
+            onFailureChange?.({ name: file.name, reason });
+          },
+        )
+        .finally(() => setInflight(-1));
+    },
+    [
+      config,
+      getValue,
+      applySettle,
+      setInflight,
+      measureImage,
+      getContentWidth,
+      getDevicePixelRatio,
+      onFailureChange,
+    ],
+  );
+
+  const uploadFiles = useCallback(
+    (files: File[]) => {
+      if (files.length === 0) return;
+      // Insert all spinner blocks first (in order), then kick off uploads.
+      let doc = getValue();
+      let caret = getCaret();
+      const pending: { id: string; file: File }[] = [];
+      for (const file of files) {
+        const r = insertAttachmentBlock(doc, caret, {
+          name: file.name,
+          mime: file.type,
+          status: 'uploading',
+        });
+        // Skip a file whose insert no-op'd (caret block not in the doc) rather
+        // than crashing the whole batch on a stale/invalid caret.
+        if (r.attachmentId === null) continue;
+        doc = r.doc;
+        caret = r.selection.anchor; // next insert goes after the trailing paragraph
+        pending.push({ id: r.attachmentId, file });
+        filesRef.current.set(r.attachmentId, file);
+      }
+      if (pending.length === 0) return;
+      applyInsert(doc);
+      pending.forEach(({ id, file }) => runUpload(id, file));
+    },
+    [getValue, getCaret, applyInsert, runUpload],
+  );
+
+  const retry = useCallback(
+    (id: string) => {
+      const file = filesRef.current.get(id);
+      if (!file) return;
+      applySettle(
+        clearAttachmentFields(updateAttachmentBlock(getValue(), id, { status: 'uploading' }), id, [
+          'uploadError',
+        ]),
+      );
+      runUpload(id, file);
+    },
+    [getValue, applySettle, runUpload],
+  );
+
+  const remove = useCallback(
+    (id: string) => {
+      filesRef.current.delete(id);
+      const doc = getValue();
+      const blocks = doc.blocks.filter((b) => b.id !== id);
+      // If that emptied the doc, leave one empty paragraph (mirrors the engine's
+      // removeBlockUnit) — never silently re-keep the block the user removed.
+      applySettle(blocks.length ? { blocks } : emptyDoc());
+    },
+    [getValue, applySettle],
+  );
+
+  const replace = useCallback(
+    (id: string, file: File) => {
+      filesRef.current.set(id, file);
+      // Keep align/alt; drop the old display size so the new file's natural size
+      // applies. Then run the upload (settles src/name/mime via runUpload).
+      let doc = updateAttachmentBlock(getValue(), id, { status: 'uploading' });
+      doc = clearAttachmentFields(doc, id, ['width', 'height']);
+      applySettle(doc);
+      runUpload(id, file);
+    },
+    [getValue, applySettle, runUpload],
+  );
+
+  return { uploadFiles, retry, remove, replace, accept: config.accept };
+}

package/src/components/Screen/Screen.module.scss

@@ -0,0 +1,46 @@
+@use './Screen.tokens';
+
+// Screen is a layout-owning primitive — the documented exception to the
+// "no layout properties on components" rule (like Page / Rail). It takes over
+// the viewport (min-height) and grows its main slot (flex) because laying out a
+// full-bleed screen is its entire job. (stylelint's property-disallowed-list
+// blocks flex-grow / flex-basis but not the `flex` shorthand or min-height, so
+// no disable is needed here.)
+.root {
+  display: flex;
+  flex-direction: column;
+  padding: var(--screen-padding);
+}
+
+.fillViewport {
+  min-height: 100vh;
+}
+
+.fillBlock {
+  min-height: var(--screen-block-min-height);
+}
+
+.main {
+  flex: 1;
+  display: grid;
+}
+
+.alignCenter {
+  place-items: center;
+}
+
+.alignStart {
+  place-items: start center;
+}
+
+.backdropPlain {
+  background: var(--screen-backdrop-plain);
+}
+
+.backdropAccent {
+  background: var(--screen-backdrop-accent);
+}
+
+.backdropDanger {
+  background: var(--screen-backdrop-danger);
+}