@nizivo/react 0.1.0 → 0.2.0

package/dist/file-upload/file-upload.client.js

@@ -0,0 +1,406 @@
+"use client";
+import { cx } from "../_internal/cx.js";
+import { mergeProps } from "../contracts/merge-props.js";
+import { useLabels } from "../config/config.client.js";
+import { CircleCheckGlyph, CircleXGlyph, CloseGlyph } from "../_internal/glyphs.js";
+import { Button } from "../button/button.js";
+import { stateAttrs } from "../contracts/state.js";
+import { joinIds } from "../_internal/field.js";
+import { InlineError } from "../inline-error/inline-error.js";
+import { useFieldControl } from "../field/field-scope.client.js";
+import { iconButtonElement } from "../icon-button/icon-button-static.js";
+import { ProgressBar } from "../progress-bar/progress-bar.js";
+import { useDropTarget } from "../_engines/react-aria/file-upload.client.js";
+import { useEffect, useEffectEvent, useId, useLayoutEffect, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/file-upload/file-upload.client.tsx
+const LABELS = {
+	prompt: "Drop files here or {browse}",
+	browse: "browse",
+	release: "Release to add files",
+	summary: "{complete} of {total} uploaded",
+	wrongType: "{name} is not an accepted file type.",
+	tooLarge: "{name} is larger than {max}.",
+	tooMany: "{name} was not added: choose one file.",
+	list: "Chosen files",
+	remove: "Remove {name}",
+	retry: "Retry",
+	cancel: "Cancel",
+	uploading: "Uploading {name}",
+	complete: "Uploaded",
+	failed: "Upload failed"
+};
+/** Ids for held files: unique on the page, and never in the server HTML. */
+let nextId = 0;
+/**
+* `className` and `style` go on the root; every other input prop, `ref` included, goes on the
+* native `<input type="file">`.
+*/
+function FileUpload({ id, name, accept, multiple = false, maxSize, disabled, required, invalid, hint, icon, items, onFilesChange, onReject, onRemove, onRetry, onCancel, labels: labelsProp, locale = "en-US", className, style, "aria-invalid": ariaInvalid, "aria-describedby": describedByProp, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }) {
+	const labels = {
+		...LABELS,
+		...useLabels("fileUpload", labelsProp)
+	};
+	const base = useId();
+	const hintId = `${base}-hint`;
+	const messagesId = `${base}-messages`;
+	const [files, setFiles] = useState([]);
+	const [rejected, setRejected] = useState([]);
+	const zone = useRef(null);
+	const list = useRef(null);
+	const refocus = useRef(null);
+	const showHint = hint != null && hint !== false && hint !== "";
+	const field = useFieldControl({
+		id,
+		name,
+		required,
+		disabled,
+		invalid: invalid ?? (ariaInvalid === true || ariaInvalid === "true" ? true : void 0),
+		"aria-describedby": joinIds(describedByProp, showHint && hintId, rejected.length > 0 && messagesId),
+		labelBehavior: "focus"
+	});
+	const rows = listRows(files, items);
+	const pending = rows.filter((row) => row.item?.status === "uploading").length > 0;
+	const complete = rows.filter((row) => row.item?.status === "complete").length;
+	/** Writes the list into the input, then into state, then tells the app. */
+	const commit = (element, nextFiles) => {
+		write(element, nextFiles);
+		setFiles(nextFiles);
+		onFilesChange?.(nextFiles);
+	};
+	/** A pick or a drop: check each file, add the ones that pass, report the others. */
+	const add = (incoming, element) => {
+		const accepted = [];
+		const refused = [];
+		for (const file of incoming) {
+			const reason = !matches(file, accept) ? "type" : maxSize !== void 0 && file.size > maxSize ? "size" : !multiple && accepted.length > 0 ? "count" : void 0;
+			if (reason !== void 0) refused.push({
+				file,
+				reason
+			});
+			else if (!files.some((held) => same(held.file, file))) {
+				nextId += 1;
+				accepted.push({
+					id: `${base}-${nextId}`,
+					file
+				});
+			}
+		}
+		setRejected(refused);
+		if (refused.length > 0) onReject?.(refused);
+		if (accepted.length > 0) commit(element, multiple ? [...files, ...accepted] : accepted);
+		else write(element, files);
+	};
+	const { dropProps, isDropTarget } = useDropTarget({
+		disabled: field.disabled,
+		onDrop: (dropped, target) => add(dropped, inputIn(target))
+	}, zone);
+	const adopt = useEffectEvent((element) => {
+		if (element.files !== null && element.files.length > 0) add([...element.files], element);
+	});
+	useLayoutEffect(() => {
+		const element = fileInputOf(zone.current);
+		if (element !== null) adopt(element);
+	}, []);
+	useEffect(() => {
+		const form = fileInputOf(zone.current)?.form;
+		if (form == null) return void 0;
+		const onReset = () => {
+			setFiles([]);
+			setRejected([]);
+			onFilesChange?.([]);
+		};
+		form.addEventListener("reset", onReset);
+		return () => form.removeEventListener("reset", onReset);
+	}, [onFilesChange]);
+	const count = rows.length;
+	useLayoutEffect(() => {
+		const removed = refocus.current;
+		refocus.current = null;
+		if (removed === null || count >= removed.count) return;
+		const buttons = [...list.current?.children ?? []].map((row) => row.querySelector("button"));
+		(buttons[Math.min(removed.index, buttons.length - 1)] ?? fileInputOf(zone.current))?.focus();
+	});
+	const drop = (row, index, event) => {
+		refocus.current = {
+			index,
+			count
+		};
+		if (row.held) commit(inputIn(event.currentTarget), files.filter((entry) => entry.id !== row.id));
+	};
+	const onChange = (event) => {
+		const chosen = [...event.currentTarget.files ?? []];
+		if (chosen.length > 0) add(chosen, event.currentTarget);
+		else write(event.currentTarget, files);
+	};
+	const prompt = isDropTarget ? labels.release : pending ? fill(labels.summary, {
+		complete: String(complete),
+		total: String(rows.length)
+	}) : browseLine(labels.prompt, labels.browse);
+	const invalidShown = field.invalid || rejected.length > 0;
+	const removeLabel = (row) => fill(labels.remove, { name: row.name });
+	return /* @__PURE__ */ jsxs("div", {
+		className: cx("nz-file-upload", className),
+		"data-slot": "file-upload",
+		...stateAttrs({
+			disabled: field.disabled,
+			invalid: invalidShown,
+			pending
+		}),
+		style,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				...dropProps,
+				ref: zone,
+				className: "nz-file-upload-dropzone",
+				"data-slot": "file-upload-dropzone",
+				"data-drag-over": isDropTarget ? "" : void 0,
+				...stateAttrs({
+					disabled: field.disabled,
+					invalid: invalidShown
+				}),
+				"aria-disabled": field.disabled ? true : void 0,
+				children: [
+					/* @__PURE__ */ jsx("input", {
+						...mergeProps(field.controlProps, rest),
+						onChange,
+						type: "file",
+						className: "nz-file-upload-input",
+						"data-slot": "file-upload-input",
+						accept,
+						multiple,
+						required: field.required && rows.length === 0 ? true : void 0,
+						"aria-label": ariaLabel ?? (ariaLabelledBy === void 0 && field.labelledBy === void 0 ? fill(labels.prompt, { browse: labels.browse }) : void 0),
+						"aria-labelledby": ariaLabelledBy
+					}),
+					icon != null && /* @__PURE__ */ jsx("span", {
+						className: "nz-file-upload-icon",
+						"data-slot": "file-upload-icon",
+						"aria-hidden": "true",
+						children: icon
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "nz-file-upload-prompt",
+						"data-slot": "file-upload-prompt",
+						children: prompt
+					}),
+					showHint && /* @__PURE__ */ jsx("span", {
+						className: "nz-file-upload-hint",
+						"data-slot": "file-upload-hint",
+						id: hintId,
+						children: hint
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "nz-file-upload-messages",
+				"data-slot": "file-upload-messages",
+				id: messagesId,
+				"aria-live": "polite",
+				children: rejected.map(({ file, reason }) => /* @__PURE__ */ jsx(InlineError, { children: rejection(labels, reason, file.name, maxSize, locale) }, `${reason}-${file.name}-${file.size}-${file.lastModified}`))
+			}),
+			rows.length > 0 && /* @__PURE__ */ jsx("ul", {
+				ref: list,
+				className: "nz-file-upload-list",
+				"data-slot": "file-upload-list",
+				"aria-label": labels.list,
+				children: rows.map((row, index) => {
+					const status = row.item?.status;
+					const nameId = `${base}-name-${row.id}`;
+					return /* @__PURE__ */ jsxs("li", {
+						className: "nz-file-upload-item",
+						"data-slot": "file-upload-item",
+						...stateAttrs({
+							pending: status === "uploading",
+							error: status === "error"
+						}),
+						children: [
+							/* @__PURE__ */ jsx("span", {
+								className: "nz-file-upload-item-name",
+								"data-slot": "file-upload-item-name",
+								id: nameId,
+								children: row.name
+							}),
+							/* @__PURE__ */ jsxs("span", {
+								className: "nz-file-upload-item-status",
+								"data-slot": "file-upload-item-status",
+								children: [row.size !== void 0 && /* @__PURE__ */ jsx("span", {
+									className: "nz-file-upload-item-size",
+									"data-slot": "file-upload-item-size",
+									children: formatBytes(row.size, locale)
+								}), itemStatus(row, labels)]
+							}),
+							/* @__PURE__ */ jsxs("span", {
+								className: "nz-file-upload-item-actions",
+								"data-slot": "file-upload-item-actions",
+								children: [status === "error" && /* @__PURE__ */ jsx(Button, {
+									variant: "tertiary",
+									size: "sm",
+									"aria-describedby": nameId,
+									disabled: field.disabled,
+									onClick: () => onRetry?.(row.id),
+									children: labels.retry
+								}), status === "uploading" ? /* @__PURE__ */ jsx(Button, {
+									variant: "tertiary",
+									size: "sm",
+									"aria-describedby": nameId,
+									disabled: field.disabled,
+									onClick: (event) => {
+										drop(row, index, event);
+										onCancel?.(row.id);
+									},
+									children: labels.cancel
+								}) : /* @__PURE__ */ jsx(RemoveButton, {
+									label: removeLabel(row),
+									disabled: field.disabled,
+									onClick: (event) => {
+										drop(row, index, event);
+										onRemove?.(row.id);
+									}
+								})]
+							})
+						]
+					}, row.id);
+				})
+			})
+		]
+	});
+}
+/** IconButton's element with no tooltip, as Toast's close button: the row's name is visible. */
+function RemoveButton(props) {
+	return iconButtonElement({
+		label: props.label,
+		icon: /* @__PURE__ */ jsx(CloseGlyph, {}),
+		variant: "tertiary",
+		size: "sm",
+		disabled: props.disabled,
+		onClick: props.onClick
+	});
+}
+/** The file input of the FileUpload that holds `element`. */
+function inputIn(element) {
+	return fileInputOf(element.closest("[data-slot=\"file-upload\"]"));
+}
+function fileInputOf(scope) {
+	return scope?.querySelector("[data-slot=\"file-upload-input\"]") ?? null;
+}
+/** The held files in order, each with its item, then the items that match no held file. */
+function listRows(files, items) {
+	const byId = new Map((items ?? []).map((item) => [item.id, item]));
+	const rows = files.map(({ id, file }) => {
+		const item = byId.get(id);
+		byId.delete(id);
+		return {
+			id,
+			name: item?.name ?? file.name,
+			size: item?.size ?? file.size,
+			item,
+			held: true
+		};
+	});
+	for (const item of byId.values()) rows.push({
+		id: item.id,
+		name: item.name ?? item.id,
+		size: item.size,
+		item,
+		held: false
+	});
+	return rows;
+}
+function itemStatus(row, labels) {
+	const item = row.item;
+	switch (item?.status) {
+		case "uploading": return /* @__PURE__ */ jsx(ProgressBar, {
+			value: item.progress ?? 0,
+			indeterminate: item.progress === void 0,
+			showValue: false,
+			"aria-label": fill(labels.uploading, { name: row.name })
+		});
+		case "complete": return /* @__PURE__ */ jsxs("span", {
+			className: "nz-file-upload-item-complete",
+			"data-slot": "file-upload-item-complete",
+			children: [/* @__PURE__ */ jsx(CircleCheckGlyph, {}), labels.complete]
+		});
+		case "error": return /* @__PURE__ */ jsxs("span", {
+			className: "nz-file-upload-item-error",
+			"data-slot": "file-upload-item-error",
+			children: [/* @__PURE__ */ jsx(CircleXGlyph, {}), item.error ?? labels.failed]
+		});
+		default: return null;
+	}
+}
+function rejection(labels, reason, name, maxSize, locale) {
+	if (reason === "type") return fill(labels.wrongType, { name });
+	if (reason === "count") return fill(labels.tooMany, { name });
+	return fill(labels.tooLarge, {
+		name,
+		max: formatBytes(maxSize ?? 0, locale)
+	});
+}
+/** The prompt with the browse word in its own span, where `{browse}` is (at the end if absent). */
+function browseLine(template, browse) {
+	const at = template.indexOf("{browse}");
+	const word = /* @__PURE__ */ jsx("span", {
+		className: "nz-file-upload-browse",
+		"data-slot": "file-upload-browse",
+		children: browse
+	});
+	if (at === -1) return template;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		template.slice(0, at),
+		word,
+		template.slice(at + 8)
+	] });
+}
+function fill(template, values) {
+	let out = template;
+	for (const [key, value] of Object.entries(values)) out = out.replaceAll(`{${key}}`, value);
+	return out;
+}
+const UNITS = [
+	"byte",
+	"kilobyte",
+	"megabyte",
+	"gigabyte",
+	"terabyte"
+];
+/** Decimal units (1 MB = 1,000,000 bytes), as macOS and the `maxSize` docs write them. */
+function formatBytes(bytes, locale) {
+	let value = Math.max(bytes, 0);
+	let unit = 0;
+	while (value >= 1e3 && unit < UNITS.length - 1) {
+		value /= 1e3;
+		unit += 1;
+	}
+	return new Intl.NumberFormat(locale, {
+		style: "unit",
+		unit: UNITS[unit],
+		unitDisplay: unit === 0 ? "long" : "short",
+		maximumFractionDigits: unit > 0 && value < 10 ? 1 : 0
+	}).format(value);
+}
+/** The native `accept` rule: a MIME type, a `type/*` wildcard or a `.ext`, any of them. */
+function matches(file, accept) {
+	const rules = (accept ?? "").split(",").map((rule) => rule.trim().toLowerCase()).filter((rule) => rule !== "");
+	if (rules.length === 0) return true;
+	const fileName = file.name.toLowerCase();
+	const type = file.type.toLowerCase();
+	return rules.some((rule) => rule.startsWith(".") ? fileName.endsWith(rule) : rule.endsWith("/*") ? type.startsWith(rule.slice(0, -1)) : type === rule);
+}
+function same(a, b) {
+	return a.name === b.name && a.size === b.size && a.lastModified === b.lastModified;
+}
+/**
+* Puts the held files in the input, as a FileList (the only kind `input.files` takes), and fires
+* `input` so a Field withdraws a "choose a file" message. Not `change`: React's onChange on a file
+* input is the native `change`, which would run the pick handler again.
+*/
+function write(element, files) {
+	if (element === null) return;
+	const transfer = new DataTransfer();
+	for (const { file } of files) transfer.items.add(file);
+	element.files = transfer.files;
+	element.dispatchEvent(new Event("input", { bubbles: true }));
+}
+//#endregion
+export { FileUpload };

package/dist/file-upload/file-upload.contract.d.ts

@@ -0,0 +1,112 @@
+import "./seam.js";
+import { ComponentPropsWithRef, ReactNode, RefObject } from "react";
+//#region src/file-upload/file-upload.contract.d.ts
+/** Where an item's upload is. Absent on an item: chosen, not sent yet. */
+export type FileUploadStatus = "uploading" | "complete" | "error";
+/** A file the component holds (and its input submits), with the id the component gave it. */
+export interface FileUploadFile {
+  /** Stays the same while the file is listed. Key your `items` and upload requests by it. */
+  id: string;
+  file: File;
+}
+/**
+ * An item's upload state, from the app, which does the uploading. Matched to a held file by `id`;
+ * an item whose id matches no held file is listed too, after the held files (a file uploaded
+ * earlier, shown on an edit form).
+ */
+export interface FileUploadItem {
+  id: string;
+  /**
+   * Shown in the list. Defaults to the held file's name; an item that matches no held file needs
+   * one, or its `id` is shown.
+   */
+  name?: string;
+  /** In bytes, shown beside the name. Defaults to the held file's size. */
+  size?: number;
+  status?: FileUploadStatus;
+  /** 0 to 100 while `uploading`; absent, the bar is indeterminate. */
+  progress?: number;
+  /** The message while `status` is `error`. @default labels.failed */
+  error?: string;
+}
+/** Why a chosen or dropped file was not added. */
+export type FileUploadRejectionReason = "type" | "size" | "count";
+export interface FileUploadRejection {
+  file: File;
+  reason: FileUploadRejectionReason;
+}
+/**
+ * Strings FileUpload renders (§16.4): serialisable, English defaults. `{name}` is a file's name,
+ * `{max}` the formatted `maxSize`, `{browse}` where the browse word goes, `{complete}` and `{total}`
+ * counts.
+ */
+export interface FileUploadLabels {
+  /** The dropzone's line. @default 'Drop files here or {browse}' */
+  prompt: string;
+  /** The word that reads as the picker's button, in the brand colour. @default 'browse' */
+  browse: string;
+  /** Replaces the prompt while a drag with files is over the dropzone. @default 'Release to add files' */
+  release: string;
+  /** Replaces the prompt while an item is uploading. @default '{complete} of {total} uploaded' */
+  summary: string;
+  /** A file `accept` does not match. @default '{name} is not an accepted file type.' */
+  wrongType: string;
+  /** A file over `maxSize`. @default '{name} is larger than {max}.' */
+  tooLarge: string;
+  /** Without `multiple`, every file of a drop after the first. @default '{name} was not added: choose one file.' */
+  tooMany: string;
+  /** The list's accessible name. @default 'Chosen files' */
+  list: string;
+  /** Each item's remove button. @default 'Remove {name}' */
+  remove: string;
+  /** An item in error. @default 'Retry' */
+  retry: string;
+  /** An item uploading. @default 'Cancel' */
+  cancel: string;
+  /** An uploading item's progress bar. @default 'Uploading {name}' */
+  uploading: string;
+  /** A complete item's status. @default 'Uploaded' */
+  complete: string;
+  /** An item in error with no `error` text. @default 'Upload failed' */
+  failed: string;
+}
+export interface FileUploadProps extends Omit<ComponentPropsWithRef<"input">, "type" | "size" | "children" | "value" | "defaultValue" | "onChange" | "accept" | "multiple"> {
+  /**
+   * The native `accept`: MIME types (`image/png`), wildcards (`image/*`) and extensions (`.pdf`),
+   * comma-separated. The picker filters by it, and a dropped or picked file that does not match is
+   * not added.
+   */
+  accept?: string;
+  /** More than one file; each pick or drop adds to the list. Without it, a new file replaces the old. @default false */
+  multiple?: boolean;
+  /** Bytes. A larger file is not added. 1 MB is 1,000,000 bytes, as `{max}` is written. */
+  maxSize?: number;
+  /**
+   * An error message is presented for this control (§8.3). Inside a Field, the Field sets it; an
+   * explicit value here wins.
+   */
+  invalid?: boolean;
+  /** The line under the prompt, such as "PNG, JPG or WebP, up to 20 MB". */
+  hint?: ReactNode;
+  /** Decorative mark above the prompt, such as your icon set's `upload` glyph (`aria-hidden`). */
+  icon?: ReactNode;
+  /**
+   * Upload state per file, keyed by the ids `onFilesChange` gives. Leave it out when the form
+   * submits the files itself.
+   */
+  items?: readonly FileUploadItem[];
+  /** The held files changed: a pick, a drop, a remove, a cancel or the form's reset. Every held file, in order. */
+  onFilesChange?: (files: FileUploadFile[]) => void;
+  /** Files of a pick or drop that were not added; their messages show under the dropzone. */
+  onReject?: (rejections: FileUploadRejection[]) => void;
+  /** An item's remove button. A held file has already left the list and the input. */
+  onRemove?: (id: string) => void;
+  /** An item's retry button, on an item in `error`. */
+  onRetry?: (id: string) => void;
+  /** An item's cancel button, on an item `uploading`. The held file has already left the list. */
+  onCancel?: (id: string) => void;
+  labels?: Partial<FileUploadLabels>;
+  /** BCP 47 tag for sizes. @default 'en-US' */
+  locale?: string;
+}
+//#endregion

package/dist/file-upload/index.d.ts

@@ -0,0 +1,3 @@
+import { FileUploadFile, FileUploadItem, FileUploadLabels, FileUploadProps, FileUploadRejection, FileUploadRejectionReason, FileUploadStatus } from "./file-upload.contract.js";
+import { FileUpload } from "./file-upload.client.js";
+export { FileUpload, type FileUploadFile, type FileUploadItem, type FileUploadLabels, type FileUploadProps, type FileUploadRejection, type FileUploadRejectionReason, type FileUploadStatus };

package/dist/file-upload/index.js

@@ -0,0 +1 @@
+export { FileUpload } from "./file-upload.client.js";

package/dist/file-upload/seam.d.ts

@@ -0,0 +1 @@
+import "react";

package/dist/form/form.client.d.ts

@@ -0,0 +1,38 @@
+import { RenderProp } from "../contracts/render.js";
+import { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+//#region src/form/form.client.d.ts
+/** One Field's errors: a message, or several (the first is shown), or none. */
+export type FormErrorValue = string | readonly string[] | null | undefined;
+/**
+ * Errors keyed by the Field's `name`, as a server action returns them (Zod's
+ * `z.flattenError(error).fieldErrors`, or Conform's and TanStack Form's issues mapped to text). A
+ * nested name is one key, written as the Field's `name` is: `items.0.title`. Serialisable.
+ */
+export type FormErrors = Readonly<Record<string, FormErrorValue>>;
+/** Form's own strings (§16.4): serialisable, English defaults. */
+export interface FormLabels {
+  /** The error summary's title. @default 'There is a problem' */
+  summaryTitle: string;
+}
+export interface FormProps extends Omit<ComponentPropsWithRef<"form">, "children"> {
+  /**
+   * Errors by Field `name`, typically a server action's reply. Each one is presented by the Field
+   * with that `name` (the Field's own `error` prop wins over it) until the user edits that control.
+   * A new object (by identity) presents them all again and moves focus: to the error summary with
+   * `summary`, else to the first invalid control. The first render moves no focus.
+   */
+  errors?: FormErrors | undefined;
+  /**
+   * Renders an error summary at the start of the form while `errors` presents a message: a title
+   * and one link per error to its control, in page order. New errors focus the summary instead of
+   * the first invalid control (GOV.UK's error summary). For long forms. @default false
+   */
+  summary?: boolean;
+  /** Overrides Form's strings, for example `labels={{ summaryTitle: 'Es gibt ein Problem' }}`. */
+  labels?: Partial<FormLabels>;
+  /** Composition of the `<form>`. */
+  render?: RenderProp<Record<string, never>>;
+  children?: ReactNode;
+}
+export declare function Form({ errors, summary, labels: labelsProp, render, className, children, ...rest }: FormProps): ReactElement;
+//#endregion