@cratis/scene.primereact 4.5.0 → 4.7.0

package/editor/serializeSafeNodes.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SafeNode } from './SafeNode';
+
+const voidTags = new Set(['br', 'hr', 'img']);
+
+const escapes: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+
+const escape = (text: string) => text.replace(/[&<>"]/g, character => escapes[character]);
+
+/**
+ * Writes safe nodes back out as an HTML string, for an editor that reads HTML.
+ *
+ * Text and attribute values are escaped, and only tags and attributes the allowlist produced are written, so
+ * the string can contain nothing the allowlist did not already accept.
+ *
+ * @param nodes The nodes `sanitizeHtml` returned.
+ */
+export function serializeSafeNodes(nodes: SafeNode[]): string {
+    return nodes.map(node => {
+        if (typeof node === 'string') return escape(node);
+        const attributes = Object.entries(node.attributes).map(([name, value]) => ` ${name}="${escape(value)}"`).join('');
+        return voidTags.has(node.tag) ? `<${node.tag}${attributes}>` : `<${node.tag}${attributes}>${serializeSafeNodes(node.children)}</${node.tag}>`;
+    }).join('');
+}

package/editor/toolbarLayout.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The formats the toolbar offers. Content in other formats is still shown, but cannot be produced here. */
+export const toolbarLayout: (string | Record<string, unknown>)[][] = [
+    ['bold', 'italic', 'underline'],
+    [{ header: [1, 2, 3, false] }],
+    [{ list: 'ordered' }, { list: 'bullet' }],
+    ['link'],
+];

package/editor/useQuillEditor.ts

@@ -0,0 +1,114 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useRef, useState } from 'react';
+import { QuillConstructor } from './QuillConstructor';
+import { QuillEditorOptions } from './QuillEditorOptions';
+import { QuillEditorState } from './QuillEditorState';
+import { QuillInstance } from './QuillInstance';
+import { applyHtml } from './applyHtml';
+import { characterCount } from './characterCount';
+import { toolbarLayout } from './toolbarLayout';
+
+const idle: QuillEditorState = { ready: false, failure: undefined, characters: 0 };
+
+/**
+ * Builds and owns a Quill editor inside an element React leaves alone.
+ *
+ * The editor is constructed once per loader and toolbar setting, in a container this hook creates and
+ * removes itself. React renders the host with no children, so a re-render can never wipe what Quill built -
+ * the failure of rendering the authored HTML as the host's children and then letting Quill take it over.
+ *
+ * Everything else is applied to the live editor without rebuilding it:
+ * - a changed `html` replaces the content silently, and only when the authored value really changed, so a
+ *   user's edit survives an unrelated property change;
+ * - `editable`, the placeholder and the accessible name update in place;
+ * - the `text-change` listener is removed, and the toolbar and surface with the container, when the editor
+ *   is rebuilt or the control unmounts.
+ *
+ * Only a user edit calls `onUserChange`.
+ */
+export function useQuillEditor(options: QuillEditorOptions): QuillEditorState {
+    const { loader, host, html, showHeader, editable, placeholder, ariaLabel } = options;
+    const [state, setState] = useState<QuillEditorState>(idle);
+    const quillReference = useRef<QuillInstance | undefined>(undefined);
+    const appliedHtml = useRef(html);
+    const latest = useRef(options);
+    latest.current = options;
+
+    useEffect(() => {
+        const container = host.current;
+        if (loader === undefined || container === null) return undefined;
+
+        let disposed = false;
+        let dispose: (() => void) | undefined;
+
+        loader().then(loaded => {
+            if (disposed) return;
+            const Quill: QuillConstructor = typeof loaded === 'function' ? loaded : loaded.default;
+            const surface = container.ownerDocument.createElement('div');
+            container.appendChild(surface);
+            const quill = new Quill(surface, {
+                theme: 'snow',
+                modules: { toolbar: showHeader ? toolbarLayout : false },
+                placeholder: latest.current.placeholder,
+                readOnly: !latest.current.editable,
+            });
+
+            applyHtml(quill, latest.current.html);
+            appliedHtml.current = latest.current.html;
+            const changed = (_delta: unknown, _previous: unknown, source: string) => {
+                if (source === 'silent') return;
+                setState(current => ({ ...current, characters: characterCount(quill) }));
+                if (source === 'user') latest.current.onUserChange();
+            };
+
+            quill.on('text-change', changed);
+            quillReference.current = quill;
+            dispose = () => {
+                quill.off('text-change', changed);
+                quillReference.current = undefined;
+                container.replaceChildren();
+            };
+            setState({ ready: true, failure: undefined, characters: characterCount(quill) });
+        }).catch((error: unknown) => {
+            if (!disposed) setState({ ...idle, failure: error instanceof Error ? error.message : String(error) });
+        });
+
+        return () => {
+            disposed = true;
+            dispose?.();
+            setState(idle);
+        };
+    }, [loader, host, showHeader]);
+
+    useEffect(() => {
+        const quill = quillReference.current;
+        if (!state.ready || quill === undefined || html === appliedHtml.current) return;
+        appliedHtml.current = html;
+        applyHtml(quill, html);
+        setState(current => ({ ...current, characters: characterCount(quill) }));
+    }, [html, state.ready]);
+
+    useEffect(() => {
+        const quill = quillReference.current;
+        if (!state.ready || quill === undefined) return;
+        quill.enable(editable);
+        quill.root.setAttribute('aria-readonly', String(!editable));
+        const toolbar = quill.getModule('toolbar') as { container?: HTMLElement } | undefined;
+        toolbar?.container?.querySelectorAll('button, select').forEach(control => {
+            if (editable) control.removeAttribute('disabled'); else control.setAttribute('disabled', '');
+        });
+    }, [editable, state.ready]);
+
+    useEffect(() => {
+        const quill = quillReference.current;
+        if (!state.ready || quill === undefined) return;
+        quill.root.setAttribute('role', 'textbox');
+        quill.root.setAttribute('aria-multiline', 'true');
+        quill.root.setAttribute('aria-label', ariaLabel);
+        if (placeholder === undefined) quill.root.removeAttribute('data-placeholder'); else quill.root.setAttribute('data-placeholder', placeholder);
+    }, [ariaLabel, placeholder, state.ready]);
+
+    return state;
+}

package/file/FileGallery.stories.tsx

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { SceneElementView } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { sceneComponent, sceneGallery } from '../storyElements';
+
+const meta = {
+    title: 'PrimeReact/File',
+    component: SceneElementView,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: { description: { component: 'File-upload controls through the Scene registry. A host supplies an upload handler or server URL when it wants files sent.' } },
+    },
+} satisfies Meta<typeof SceneElementView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Every file component in this package, rendered through the real Scene registry. */
+export const Gallery: Story = {
+    args: {
+        element: sceneGallery('gallery', [
+            sceneComponent('fileUpload', 'fileUpload', { mode: 'advanced', accept: 'image/*', multiple: true }),
+        ]),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};

package/file/FileUploadContext.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createContext } from 'react';
+import { FileUploadHandler } from './FileUploadHandler';
+
+/** What a host provides to the file uploads inside it. */
+export interface FileUploadContextValue {
+    /** The host-owned upload effect, when it owns the effect. */
+    handler: FileUploadHandler | undefined;
+
+    /** The origins, besides the page's own, an upload may be sent to. */
+    allowedOrigins: readonly string[];
+}
+
+/** Without a provider an upload goes only to the page's own origin and the control makes the request itself. */
+export const FileUploadContext = createContext<FileUploadContextValue>({ handler: undefined, allowedOrigins: [] });

package/file/FileUploadHandler.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A host-owned effect that sends selected files to the server the screen specifies. */
+export interface FileUploadHandler {
+    /**
+     * Uploads a selection without coupling the portable Scene package to a host's server client.
+     *
+     * @param files The files selected by the user.
+     * @param serverUrl The upload address authored on the Scene element, after the origin policy accepted it
+     * (same origin as the page, or one the host allowed). `undefined` when none was authored; an address the
+     * policy refused never reaches the handler.
+     */
+    (files: File[], serverUrl?: string): Promise<void>;
+}

package/file/FileUploadHandlerProvider.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, useMemo } from 'react';
+import { FileUploadContext } from './FileUploadContext';
+import { FileUploadHandler } from './FileUploadHandler';
+
+export interface FileUploadHandlerProviderProps {
+    /**
+     * The host-owned upload effect available to the enclosed Scene surface. When omitted the control posts the
+     * files itself, to the authored address, under the origin policy.
+     */
+    handler?: FileUploadHandler;
+
+    /**
+     * Origins besides the page's own that an authored upload address may name, for example
+     * `['https://files.example.com']`. An address on any other origin is refused before anything is sent - to
+     * the handler as well. Cookies are never sent to these origins.
+     */
+    allowedOrigins?: readonly string[];
+
+    /** The surface whose file uploads the host configures. */
+    children: ReactNode;
+}
+
+/**
+ * Makes a host's upload effect and origin policy available without coupling the Scene package to that host's
+ * server client.
+ */
+export function FileUploadHandlerProvider({ handler, allowedOrigins = [], children }: FileUploadHandlerProviderProps) {
+    const value = useMemo(() => ({ handler, allowedOrigins }), [handler, allowedOrigins]);
+    return <FileUploadContext.Provider value={value}>{children}</FileUploadContext.Provider>;
+}

package/file/FileUploadMode.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The canonical operating modes for a file upload control. */
+export enum FileUploadMode {
+    Advanced = 'advanced',
+    Basic = 'basic',
+    Auto = 'auto',
+}

package/file/PrimeFileUpload.tsx

@@ -0,0 +1,129 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChangeEvent, DragEvent, useContext, useMemo, useSyncExternalStore } from 'react';
+import { FileUpload, type FileUploadChangeEvent, type FileUploadHandlerEvent } from 'primereact/fileupload';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, numberProperty, stringProperty } from '../properties';
+import { resolveEnumeration } from '../resolveEnumeration';
+import { FileUploadContext } from './FileUploadContext';
+import { FileUploadMode } from './FileUploadMode';
+import { resolveUploadTarget } from './resolveUploadTarget';
+import { useUploadSession } from './useUploadSession';
+
+const subscribeToNothing = () => () => undefined;
+const pageOrigin = () => window.location.origin;
+const noPageOrigin = () => undefined;
+
+/**
+ * The `PrimeReact:fileUpload` component.
+ *
+ * PrimeReact 11 provides the accessible file picker and drop zone; this adapter owns everything that has an
+ * effect or a policy:
+ * - The authored `url` is untrusted data. It is checked by {@link resolveUploadTarget} - same origin as the
+ *   page unless the host allows more through {@link FileUploadHandlerProvider} - and a refused address is
+ *   reported and blocks every upload, the host's handler included.
+ * - Nothing is requested on mount. A request starts only when the user selects or drops files (automatic and
+ *   basic mode) or presses the upload button.
+ * - `multiple: false` is enforced before anything is sent, for the file input and for drag and drop.
+ * - One upload runs at a time (nothing can be selected or dropped while it runs), and a failure is shown
+ *   rather than thrown.
+ * - A disabled element (`isEnabled: false`) disables the picker, the upload button and the drop zone.
+ *
+ * Without a host handler the control posts the files itself with `fetch`, sending cookies to the page's own
+ * origin only.
+ */
+export function PrimeFileUpload({ element, interactions }: RegisteredComponentProps) {
+    const { handler, allowedOrigins } = useContext(FileUploadContext);
+    const origin = useSyncExternalStore(subscribeToNothing, pageOrigin, noPageOrigin);
+    const modeResolution = resolveEnumeration('mode', element.properties.mode, FileUploadMode, FileUploadMode.Advanced);
+    const mode = modeResolution.isValid ? modeResolution.value : FileUploadMode.Advanced;
+    const authoredUrl = stringProperty(element, 'url');
+    const target = useMemo(() => resolveUploadTarget(authoredUrl, origin, allowedOrigins), [authoredUrl, origin, allowedOrigins]);
+    const serverUrl = target.isValid ? target.url : undefined;
+    const multiple = booleanProperty(element, 'multiple', false);
+    const enabled = element.isEnabled;
+    const canUpload = target.isValid && (handler !== undefined || serverUrl !== undefined);
+    const session = useUploadSession(handler, serverUrl, stringProperty(element, 'name', 'files'));
+
+    const uploaded = async (event: FileUploadHandlerEvent) => {
+        if (!enabled || !canUpload) return;
+        if (await session.upload(event.files)) event.options.clear();
+    };
+
+    const changed = (event: FileUploadChangeEvent) => {
+        // Clearing the selection after an upload reports an empty change; it is not a new selection, and must not
+        // wipe the result of the upload that caused it.
+        if (event.acceptedFiles.length === 0 && event.rejectedFiles.length === 0) return;
+        const rejection = event.rejectedFiles.flatMap(rejected => rejected.errors.map(error => error.message)).join(' ');
+        session.setStatus(rejection === '' ? undefined : { kind: 'error', text: rejection });
+        interactions?.onChange?.();
+    };
+
+    const refuseSeveralFromInput = (event: ChangeEvent<HTMLElement>) => {
+        const input = event.target as HTMLInputElement;
+        if (input.type !== 'file') return;
+        if (session.busy) {
+            event.stopPropagation();
+            input.value = '';
+            return;
+        }
+
+        if (multiple || (input.files?.length ?? 0) < 2) return;
+        event.stopPropagation();
+        input.value = '';
+        session.setStatus({ kind: 'error', text: 'Only one file can be uploaded at a time.' });
+    };
+
+    const refuseDrop = (event: DragEvent<HTMLElement>) => {
+        if (!enabled) {
+            event.preventDefault();
+            return;
+        }
+        if (session.busy) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+
+        if (multiple || (event.dataTransfer?.files.length ?? 0) < 2) return;
+        event.preventDefault();
+        event.stopPropagation();
+        session.setStatus({ kind: 'error', text: 'Only one file can be uploaded at a time.' });
+    };
+
+    return (
+        <div
+            data-scene-id={element.id}
+            data-scene-component='fileUpload'
+            onClick={interactions?.onClick}
+            onDoubleClick={interactions?.onDoubleClick}
+            onChangeCapture={refuseSeveralFromInput}
+            onDropCapture={refuseDrop}
+            onDragOverCapture={event => { if (!enabled) event.preventDefault(); }}>
+            <FileUpload.Root
+                accept={stringProperty(element, 'accept')}
+                auto={(mode === FileUploadMode.Auto || mode === FileUploadMode.Basic) && canUpload}
+                customUpload
+                disabled={!enabled}
+                maxFileSize={numberProperty(element, 'maxFileSize')}
+                multiple={multiple}
+                name={stringProperty(element, 'name', 'files')}
+                uploadHandler={uploaded}
+                onChange={changed}>
+                <FileUpload.Content aria-label={stringProperty(element, 'ariaLabel', 'File upload drop zone')}>
+                    <p>{mode === FileUploadMode.Basic ? 'Choose a file to upload.' : 'Drop files here or choose files to upload.'}</p>
+                    <FileUpload.Trigger disabled={!enabled || session.busy}>{mode === FileUploadMode.Basic ? 'Choose file' : 'Choose files'}</FileUpload.Trigger>
+                    {mode === FileUploadMode.Advanced && (
+                        <FileUpload.Upload disabled={!enabled || !canUpload || session.busy}>Upload selected files</FileUpload.Upload>
+                    )}
+                    {!modeResolution.isValid && <p role='alert' data-scene-state='unsupported-mode'>{modeResolution.message}</p>}
+                    {!target.isValid && <p role='alert' data-scene-state='refused-address'>{target.message}</p>}
+                    {target.isValid && !canUpload && <p role='status'>Configure a server URL or provide an upload handler to upload files.</p>}
+                    {session.busy && <p role='status'>Uploading…</p>}
+                    {session.status !== undefined && <p role={session.status.kind === 'error' ? 'alert' : 'status'}>{session.status.text}</p>}
+                </FileUpload.Content>
+            </FileUpload.Root>
+        </div>
+    );
+}

package/file/UploadStatus.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** What a file upload last reported to the person using it. */
+export interface UploadStatus {
+    /** `error` is announced assertively; `success` politely. */
+    kind: 'success' | 'error';
+    text: string;
+}

package/file/UploadTarget.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The outcome of checking the `url` a file upload element names against the origin policy. */
+export type UploadTarget =
+    | {
+        isValid: true;
+
+        /** The address to send to: a relative address as authored, or a normalized absolute one. `undefined` when none was authored. */
+        url: string | undefined;
+    }
+    | { isValid: false; message: string };

package/file/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './FileUploadHandler';
+export * from './FileUploadHandlerProvider';
+export * from './FileUploadMode';
+export * from './PrimeFileUpload';
+export * from './resolveUploadTarget';
+export * from './UploadTarget';

package/file/postFiles.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Sends files to an address as a `multipart/form-data` POST.
+ *
+ * Cookies are sent only to the page's own origin (`credentials: 'same-origin'`), so an upload to another
+ * origin the host allowed carries no credentials. A redirect fails the upload rather than being followed,
+ * because following one would send the files to an address the origin policy never checked.
+ *
+ * @param url The address, already checked by `resolveUploadTarget`.
+ * @param field The multipart field name each file is appended under.
+ * @param files The files to send.
+ * @param signal Cancels the request.
+ * @throws When the request fails or the server does not answer with a success status.
+ */
+export async function postFiles(url: string, field: string, files: File[], signal: AbortSignal): Promise<void> {
+    const body = new FormData();
+    for (const file of files) body.append(field, file, file.name);
+
+    const response = await fetch(url, { method: 'POST', body, credentials: 'same-origin', redirect: 'error', signal });
+    if (!response.ok) throw new Error(`The server answered ${response.status}${response.statusText === '' ? '' : ` ${response.statusText}`}.`);
+}

package/file/resolveUploadTarget.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UploadTarget } from './UploadTarget';
+
+/** A scheme (`https:`) or a protocol-relative prefix (`//host`): the address names its own host. */
+const namesItsOwnHost = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+
+/** Whitespace, control characters and backslashes, which browsers normalize in ways that disguise another host. */
+const disguisesAHost = (address: string) => Array.from(address).some(character => character <= ' ' || character === '\u007f' || character === '\\');
+
+/** Resolved against, to read an address's own parts without depending on a page. It is never sent to. */
+const placeholderOrigin = 'https://upload-target.invalid';
+
+/**
+ * Checks the address an authored upload sends files to.
+ *
+ * The address comes from authored model data, so it is not trusted. By default an upload may only go to the
+ * origin the page was served from - a relative address, or an absolute one with the same origin. A host that
+ * needs another origin names it in `allowedOrigins` when it provides the upload handler. Whatever is accepted
+ * has the scheme `http:` or `https:`, carries no user information, and contains no whitespace, control
+ * characters or backslashes, because those are how an address is made to point somewhere other than where it
+ * reads.
+ *
+ * @param url The authored address, if any.
+ * @param pageOrigin The origin of the page, `undefined` where there is no page (server rendering).
+ * @param allowedOrigins The additional origins the host permits.
+ * @returns The address to send to, or why it cannot be used.
+ */
+export function resolveUploadTarget(url: string | undefined, pageOrigin: string | undefined, allowedOrigins: readonly string[]): UploadTarget {
+    if (url === undefined || url === '') return { isValid: true, url: undefined };
+    if (disguisesAHost(url)) return refused('it contains whitespace, control characters or a backslash');
+
+    let resolved: URL;
+    try {
+        resolved = new URL(url, placeholderOrigin);
+    } catch {
+        return refused('it is not a valid address');
+    }
+
+    if (resolved.protocol !== 'http:' && resolved.protocol !== 'https:') return refused(`the ${resolved.protocol} scheme is not allowed`);
+    if (resolved.username !== '' || resolved.password !== '') return refused('it carries user information');
+    if (!namesItsOwnHost.test(url)) return { isValid: true, url };
+
+    const permitted = [...(pageOrigin === undefined ? [] : [pageOrigin]), ...allowedOrigins.flatMap(originOf)];
+    return permitted.includes(resolved.origin)
+        ? { isValid: true, url: resolved.href }
+        : refused(`${resolved.origin} is not the origin of this page or one the host allows`);
+}
+
+function originOf(address: string): string[] {
+    try {
+        return [new URL(address).origin];
+    } catch {
+        return [];
+    }
+}
+
+function refused(reason: string): UploadTarget {
+    return { isValid: false, message: `The upload address is not allowed: ${reason}.` };
+}

package/file/useUploadSession.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { FileUploadHandler } from './FileUploadHandler';
+import { UploadStatus } from './UploadStatus';
+import { postFiles } from './postFiles';
+
+/** The state of the upload in flight, if any, and the action that starts one. */
+export interface UploadSession {
+    /** Whether an upload is running. */
+    busy: boolean;
+
+    /** The last result, or `undefined` before the first upload and after a new selection. */
+    status: UploadStatus | undefined;
+    setStatus(status: UploadStatus | undefined): void;
+
+    /**
+     * Sends the files, unless an upload is already running.
+     *
+     * @returns Whether the files were sent, so the caller knows to clear its selection. A failure is reported
+     * through `status` and returns `false`: the selection stays so it can be retried.
+     */
+    upload(files: File[]): Promise<boolean>;
+}
+
+/**
+ * Runs one upload at a time for a control, through the host's handler or a POST to the checked address.
+ *
+ * Starting an upload while one runs is ignored rather than queued, so a double click cannot send the same
+ * files twice. Every failure ends in a visible `status`; none escapes as an unhandled rejection. An upload
+ * still running when the control unmounts is cancelled.
+ *
+ * @param handler The host's upload effect, if it owns the effect.
+ * @param url The checked address, if one was authored.
+ * @param field The multipart field name used when the control posts the files itself.
+ */
+export function useUploadSession(handler: FileUploadHandler | undefined, url: string | undefined, field: string): UploadSession {
+    const running = useRef<AbortController | undefined>(undefined);
+    const [busy, setBusy] = useState(false);
+    const [status, setStatus] = useState<UploadStatus | undefined>(undefined);
+
+    useEffect(() => () => running.current?.abort(), []);
+
+    const upload = useCallback(async (files: File[]): Promise<boolean> => {
+        if (running.current !== undefined) return false;
+        const controller = new AbortController();
+        running.current = controller;
+        setBusy(true);
+        setStatus(undefined);
+        try {
+            if (handler !== undefined) await handler(files, url);
+            else if (url !== undefined) await postFiles(url, field, files, controller.signal);
+            else throw new Error('There is nowhere to send the files.');
+            setStatus({ kind: 'success', text: `${files.length} file${files.length === 1 ? '' : 's'} uploaded.` });
+            return true;
+        } catch (error) {
+            if (!controller.signal.aborted) setStatus({ kind: 'error', text: `Upload failed: ${error instanceof Error ? error.message : String(error)}` });
+            return false;
+        } finally {
+            running.current = undefined;
+            setBusy(false);
+        }
+    }, [handler, url, field]);
+
+    return { busy, status, setStatus, upload };
+}

package/form/FormGallery.stories.tsx

@@ -26,6 +26,7 @@ export const Gallery: Story = {
         element: sceneGallery('gallery', [
             sceneComponent('inputText', 'inputText', { placeholder: 'Name' }),
             sceneComponent('inputTextarea', 'inputTextarea', { placeholder: 'Notes', rows: 3 }),
+            sceneComponent('editor', 'editor', { value: '<p>Write a <strong>rich</strong> note.</p>' }),
             sceneComponent('inputNumber', 'inputNumber', { value: 42, showButtons: true }),
             sceneComponent('password', 'password', { placeholder: 'Password' }),
             sceneComponent('floatLabel', 'floatLabel', { label: 'Project name' }),
@@ -35,6 +36,14 @@ export const Gallery: Story = {
             sceneComponent('listBox', 'listBox', { options: ['Daily', 'Weekly', 'Monthly'] }),
             sceneComponent('selectButton', 'selectButton', { options: ['Day', 'Week', 'Month'], value: 'Week' }),
             sceneComponent('checkbox', 'checkbox', { label: 'Notify me', checked: true }),
+            sceneComponent('multiStateCheckbox', 'multiStateCheckbox', {
+                value: null,
+                options: [
+                    { label: 'Approved', value: 'approved', icon: 'pi pi-check' },
+                    { label: 'Rejected', value: 'rejected', icon: 'pi pi-times' },
+                ],
+                ariaLabel: 'Review state',
+            }),
             sceneComponent('radioButton', 'radioButton', { options: ['Email', 'SMS'], value: 'Email' }),
             sceneComponent('toggleSwitch', 'toggleSwitch', { label: 'Enabled', checked: true }),
             sceneComponent('slider', 'slider', { value: 35 }),