@milktop/react-ui 0.0.0-stage → 0.1.1

package/dist/dialog/Dialog.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A modal dialog, rendered at the end of <body> so no ancestor's stacking or
+ * overflow can trap it.
+ *
+ *   <Dialog heading="Delete lesson?" description="This cannot be undone."
+ *     trigger={<Button>Delete</Button>}
+ *     footer={<Button onClick={…}>Cancel</Button>}>
+ *     …body…
+ *   </Dialog>
+ *
+ * Focus moves in and is trapped while it is open, the page behind doesn't
+ * scroll, Escape or a click on the backdrop closes it, and focus returns to
+ * the trigger.
+ *
+ * - `open`, `defaultOpen`; `onOpenChange`: called with the new open state;
+ *   `onExitComplete`: called once it has animated out
+ * - `trigger`: the element that opens it (optional; it gets the trigger's props,
+ *   so a component must pass them and its ref on, as Button does)
+ * - `heading`, `description`: label and describe it for assistive tech
+ * - `footer`: buttons along the bottom
+ * - `alert`: an alertdialog, for confirmations; the backdrop doesn't close it
+ * - `size`: 'sm', 'md' (default) or 'lg'
+ * - `closable`: false hides the close button
+ *
+ * Or composed, with the overlay still done for you (backdrop, positioning,
+ * close button), from Header, Body and Footer; a Dialog.Trigger child opens it:
+ *
+ *   <Dialog>
+ *     <Dialog.Trigger asChild><Button>Edit</Button></Dialog.Trigger>
+ *     <Dialog.Header heading="Edit student" description="Saved to their profile." />
+ *     <Dialog.Body>…</Dialog.Body>
+ *     <Dialog.Footer><Dialog.CloseTrigger asChild><Button>Cancel</Button></Dialog.CloseTrigger>…</Dialog.Footer>
+ *   </Dialog>
+ *
+ * Fully by hand, with Ark's parts (and Header, Body and Footer for the layout):
+ *
+ *   <Dialog.Root>
+ *     <Dialog.Trigger asChild><Button>Open</Button></Dialog.Trigger>
+ *     <Portal>
+ *       <Dialog.Backdrop />
+ *       <Dialog.Positioner>
+ *         <Dialog.Content>
+ *           <Dialog.Header><Dialog.Title>Title</Dialog.Title></Dialog.Header>
+ *           <Dialog.Body>…</Dialog.Body>
+ *           <Dialog.Footer><Dialog.CloseTrigger asChild><Button>Close</Button></Dialog.CloseTrigger></Dialog.Footer>
+ *         </Dialog.Content>
+ *       </Dialog.Positioner>
+ *     </Portal>
+ *   </Dialog.Root>
+ */
+import { Children, isValidElement } from 'react';
+import { Dialog as Ark } from '@ark-ui/react/dialog';
+import { Portal } from '@ark-ui/react/portal';
+import 'iconify-icon';
+import { cx, on, partOf, partsOf, withParts } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './dialog.css';
+function Header({ heading = null, description = null, children, ...rest }) {
+    return (_jsxs("div", { "data-scope": "dialog", "data-part": "header", ...rest, children: [heading && _jsx(Ark.Title, { children: heading }), description && _jsx(Ark.Description, { children: description }), children] }));
+}
+const Body = partOf('dialog', 'body');
+const Footer = partOf('dialog', 'footer');
+const layout = [Header, Body, Footer];
+function DialogShortcut({ open, defaultOpen, onOpenChange, onExitComplete, heading = null, description = null, alert = false, size = 'md', closable = true, trigger = null, footer = null, className, classes, children, ...rest }) {
+    const t = useMessages();
+    const part = partsOf('dialog', classes);
+    // Composed from Dialog.Header, Body and Footer: they go straight into the
+    // dialog (not wrapped as its body), and a Dialog.Trigger goes before it.
+    const nodes = Children.toArray(children);
+    const composed = nodes.some((node) => isValidElement(node) && layout.includes(node.type));
+    const triggers = nodes.filter((node) => isValidElement(node) && node.type === Ark.Trigger);
+    const content = composed ? nodes.filter((node) => !triggers.includes(node)) : children;
+    // Left out when not given: Zag reads undefined as a value.
+    const state = { ...(open !== undefined && { open }), ...(defaultOpen !== undefined && { defaultOpen }) };
+    return (_jsxs(Ark.Root, { ...state, ...on('onOpenChange', onOpenChange, (details) => details.open), ...(onExitComplete && { onExitComplete }), role: alert ? 'alertdialog' : 'dialog', closeOnInteractOutside: !alert, lazyMount: true, unmountOnExit: true, children: [trigger && _jsx(Ark.Trigger, { asChild: true, children: trigger }), composed && triggers, _jsxs(Portal, { children: [_jsx(Ark.Backdrop, { ...part('backdrop') }), _jsx(Ark.Positioner, { ...part('positioner'), children: _jsxs(Ark.Content, { ...rest, ...part('content'), className: cx(className, classes?.content), "data-size": size, children: [closable && _jsx(Ark.CloseTrigger, { ...part('close-trigger'), "aria-label": t.common.close, children: _jsx("iconify-icon", { icon: "lucide:x" }) }), (heading || description) && (_jsxs("div", { ...part('header'), children: [heading && _jsx(Ark.Title, { ...part('title'), children: heading }), description && _jsx(Ark.Description, { ...part('description'), children: description })] })), composed ? content : children != null && _jsx("div", { ...part('body'), children: children }), footer && _jsx("div", { ...part('footer'), children: footer })] }) })] })] }));
+}
+export const Dialog = withParts(DialogShortcut, {
+    Root: Ark.Root,
+    Trigger: Ark.Trigger,
+    Backdrop: Ark.Backdrop,
+    Positioner: Ark.Positioner,
+    Content: Ark.Content,
+    CloseTrigger: Ark.CloseTrigger,
+    Title: Ark.Title,
+    Description: Ark.Description,
+    Context: Ark.Context,
+    Header,
+    Body,
+    Footer,
+});

package/dist/dialog/dialog.css

@@ -0,0 +1,31 @@
+@layer ui {
+  [data-scope=dialog][data-part=backdrop] { position: fixed; inset: 0; z-index: 100; background: rgba(0, 0, 0, 0.45);
+    &[data-state=open] { animation: ui-fade-in 150ms ease-out; }
+    &[data-state=closed] { animation: ui-fade-out 120ms ease-in forwards; } }
+  /* Covers the screen to centre the panel, but lets clicks through to the backdrop. */
+  [data-scope=dialog][data-part=positioner] { position: fixed; inset: 0; z-index: 100; display: grid; place-items: center; padding: 1rem; pointer-events: none; }
+  [data-scope=dialog][data-part=content] {
+    position: relative; display: flex; flex-direction: column; width: 100%; max-width: 32rem; max-height: calc(100vh - 32px); box-sizing: border-box;
+    background: var(--ui-surface); color: var(--ui-text); font-family: var(--ui-font); font-size: 14px;
+    border: 1px solid var(--ui-border); border-radius: calc(var(--ui-radius) + 4px); box-shadow: var(--ui-shadow); outline: none; pointer-events: auto;
+    &[data-size=sm] { max-width: 24rem; }
+    &[data-size=lg] { max-width: 44rem; }
+    &[data-state=open] { animation: ui-dialog-in 180ms ease-out; }
+    &[data-state=closed] { animation: ui-dialog-out 120ms ease-in forwards; }
+  }
+  [data-scope=dialog][data-part=header] { padding: 1.5rem 3rem 0 1.5rem; }
+  [data-scope=dialog][data-part=title] { margin: 0; font-size: 18px; font-weight: 600; }
+  [data-scope=dialog][data-part=description] { margin: 0.375rem 0 0; color: var(--ui-muted); }
+  [data-scope=dialog][data-part=body] { padding: 1rem 1.5rem; overflow-y: auto;
+    &:first-child, [data-part=close-trigger] + & { padding-top: 1.5rem; } }
+  [data-scope=dialog][data-part=footer] { display: flex; justify-content: flex-end; gap: 0.5rem; flex-wrap: wrap; padding: 0 1.5rem 1.5rem;
+    [data-part=header] + & { padding-top: 1.5rem; } }
+  [data-scope=dialog][data-part=close-trigger] { position: absolute; top: 1rem; right: 1rem; display: grid; place-items: center; width: 2rem; height: 2rem;
+    border: none; background: transparent; border-radius: 6px; color: var(--ui-muted); cursor: pointer; font-size: 16px;
+    &:hover { background: var(--ui-hover); color: var(--ui-text); }
+    &:focus-visible { outline: 2px solid var(--ui-ring-soft); } }
+  @keyframes ui-fade-in { from { opacity: 0; } }
+  @keyframes ui-fade-out { to { opacity: 0; } }
+  @keyframes ui-dialog-in { from { opacity: 0; transform: translateY(8px) scale(0.97); } }
+  @keyframes ui-dialog-out { to { opacity: 0; transform: translateY(8px) scale(0.97); } }
+}

package/dist/divider/Divider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A line between things: across (between sections) or up (between toolbar
+ * buttons), with an optional label in the middle ('or', 'Today').
+ *
+ *   <Divider />
+ *   <Divider label="or" />
+ *   <Divider orientation="vertical" />
+ *
+ * - `label`: text (or anything) in the line; `align`: 'center' (default),
+ *   'start' or 'end'
+ * - `orientation`: 'horizontal' (default) or 'vertical' (as tall as its row)
+ * - `variant`: 'solid' (default), 'dashed' or 'dotted'
+ * - `spacing`: the room either side, a CSS length (0.75rem across, 0.5rem up)
+ */
+import type { HTMLAttributes, ReactNode } from 'react';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './divider.css';
+export type DividerProps = HTMLAttributes<HTMLDivElement> & {
+    label?: ReactNode;
+    align?: 'start' | 'center' | 'end';
+    orientation?: 'horizontal' | 'vertical';
+    variant?: 'solid' | 'dashed' | 'dotted';
+    spacing?: string | null;
+    classes?: Classes<'root' | 'label'>;
+};
+export declare function Divider({ label, align, orientation, variant, spacing, className, classes, style, ...rest }: DividerProps): import("react").JSX.Element;

package/dist/divider/Divider.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx, partsOf } from '../utils.js';
+import '../theme.css';
+import './divider.css';
+export function Divider({ label = null, align = 'center', orientation = 'horizontal', variant = 'solid', spacing = null, className, classes, style, ...rest }) {
+    const part = partsOf('divider', classes);
+    return (_jsx("div", { ...rest, ...part('root'), className: cx(className, classes?.root), role: "separator", "aria-orientation": orientation, "data-orientation": orientation, "data-variant": variant, "data-align": align, "data-labelled": label ? '' : undefined, style: { ...style, ...(spacing && { '--spacing': spacing }) }, children: label && _jsx("span", { ...part('label'), children: label }) }));
+}

package/dist/divider/divider.css

@@ -0,0 +1,12 @@
+@layer ui {
+  [data-scope=divider][data-part=root] { --line: 1px var(--style, solid) var(--ui-border); color: var(--ui-muted); font-family: var(--ui-font);
+    &[data-variant=dashed] { --style: dashed; }
+    &[data-variant=dotted] { --style: dotted; }
+    &[data-orientation=horizontal] { margin: var(--spacing, 0.75rem) 0; border-top: var(--line);
+      &[data-labelled] { display: flex; align-items: center; gap: 0.75rem; border-top: none;
+        &::before, &::after { content: ''; flex: 1; border-top: var(--line); }
+        &[data-align=start]::before { flex: 0 0 1rem; }
+        &[data-align=end]::after { flex: 0 0 1rem; } } }
+    &[data-orientation=vertical] { align-self: stretch; width: 0; min-height: 1em; margin: 0 var(--spacing, 0.5rem); border-left: var(--line); } }
+  [data-scope=divider][data-part=label] { flex-shrink: 0; font-size: 12px; font-weight: 500; white-space: nowrap; }
+}

package/dist/editable/Editable.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Text you click to edit in place, e.g. a pet's name or a price on a details
+ * page: it reads as text until clicked, then Enter saves and Escape cancels.
+ *
+ *   <Editable value={pet.name} onValueChange={(name) => save({ name })} />
+ *
+ * - `value`, `defaultValue`: the saved text; `onValueChange`: called with it
+ *   when an edit is saved (not on each key)
+ * - `placeholder`: shown when it's empty
+ * - `label`: a label above it (skipped inside a Field)
+ * - `activationMode`: 'click' (default), 'dblclick' or 'focus'
+ * - `controls`: ✓ and ✕ buttons while editing (true); `submitMode`: 'enter'
+ *   (default), 'blur', 'both' or 'none' saves on those
+ * - `disabled`, `readOnly`
+ *
+ * By hand, Ark's parts are here too: Editable.Root, Area, Input, Preview,
+ * Control, EditTrigger, SubmitTrigger, CancelTrigger, Label.
+ */
+import { type ReactNode } from 'react';
+import { Editable as Ark } from '@ark-ui/react/editable';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './editable.css';
+export type EditableProps = Omit<Ark.RootProps, 'value' | 'defaultValue' | 'onValueChange' | 'onValueCommit' | 'onValueRevert'> & {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    label?: ReactNode;
+    controls?: boolean;
+    classes?: Classes<'root' | 'label' | 'area' | 'input' | 'preview' | 'control' | 'editTrigger' | 'submitTrigger' | 'cancelTrigger'>;
+};
+declare function EditableShortcut({ value, defaultValue, onValueChange, label, controls, activationMode, placeholder, className, classes, ...rest }: EditableProps): import("react").JSX.Element;
+export declare const Editable: typeof EditableShortcut & {
+    Root: import("react").ForwardRefExoticComponent<Ark.RootProps & import("react").RefAttributes<HTMLDivElement>>;
+    RootProvider: import("react").ForwardRefExoticComponent<Ark.RootProviderProps & import("react").RefAttributes<HTMLDivElement>>;
+    Area: import("react").ForwardRefExoticComponent<Ark.AreaProps & import("react").RefAttributes<HTMLDivElement>>;
+    Input: import("react").ForwardRefExoticComponent<Ark.InputProps & import("react").RefAttributes<HTMLInputElement>>;
+    Preview: import("react").ForwardRefExoticComponent<Ark.PreviewProps & import("react").RefAttributes<HTMLSpanElement>>;
+    Control: import("react").ForwardRefExoticComponent<Ark.ControlProps & import("react").RefAttributes<HTMLDivElement>>;
+    EditTrigger: import("react").ForwardRefExoticComponent<Ark.EditTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    SubmitTrigger: import("react").ForwardRefExoticComponent<Ark.SubmitTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    CancelTrigger: import("react").ForwardRefExoticComponent<Ark.CancelTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+    Label: import("react").ForwardRefExoticComponent<Ark.LabelProps & import("react").RefAttributes<HTMLLabelElement>>;
+    Context: (props: Ark.ContextProps) => ReactNode;
+};
+export {};

package/dist/editable/Editable.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Text you click to edit in place, e.g. a pet's name or a price on a details
+ * page: it reads as text until clicked, then Enter saves and Escape cancels.
+ *
+ *   <Editable value={pet.name} onValueChange={(name) => save({ name })} />
+ *
+ * - `value`, `defaultValue`: the saved text; `onValueChange`: called with it
+ *   when an edit is saved (not on each key)
+ * - `placeholder`: shown when it's empty
+ * - `label`: a label above it (skipped inside a Field)
+ * - `activationMode`: 'click' (default), 'dblclick' or 'focus'
+ * - `controls`: ✓ and ✕ buttons while editing (true); `submitMode`: 'enter'
+ *   (default), 'blur', 'both' or 'none' saves on those
+ * - `disabled`, `readOnly`
+ *
+ * By hand, Ark's parts are here too: Editable.Root, Area, Input, Preview,
+ * Control, EditTrigger, SubmitTrigger, CancelTrigger, Label.
+ */
+import { useState } from 'react';
+import { Editable as Ark } from '@ark-ui/react/editable';
+import { useFieldContext } from '@ark-ui/react/field';
+import 'iconify-icon';
+import { cx, partsOf, withParts } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './editable.css';
+function EditableShortcut({ value, defaultValue = '', onValueChange, label = null, controls = true, activationMode = 'click', placeholder, className, classes, ...rest }) {
+    const t = useMessages();
+    const field = useFieldContext();
+    const part = partsOf('editable', classes);
+    // The saved text (ours, or the caller's), and the draft being typed.
+    const [own, setOwn] = useState(defaultValue);
+    const saved = value ?? own;
+    const [draft, setDraft] = useState(saved);
+    const [editing, setEditing] = useState(false);
+    // A new saved value from outside shows when not editing.
+    const [seen, setSeen] = useState(saved);
+    if (saved !== seen) {
+        setSeen(saved);
+        if (!editing)
+            setDraft(saved);
+    }
+    return (_jsxs(Ark.Root, { ...(t.zag.editable && { translations: t.zag.editable }), ...rest, ...part('root'), className: cx(className, classes?.root), activationMode: activationMode, ...(placeholder !== undefined && { placeholder }), value: draft, onValueChange: (d) => setDraft(d.value), edit: editing, onEditChange: (d) => setEditing(d.edit), onValueCommit: (d) => { if (value === undefined)
+            setOwn(d.value); if (d.value !== saved)
+            onValueChange?.(d.value); }, onValueRevert: () => setDraft(saved), children: [label && !field && _jsx(Ark.Label, { ...part('label'), children: label }), _jsxs("div", { ...part('row'), children: [_jsxs(Ark.Area, { ...part('area'), children: [_jsx(Ark.Input, { ...part('input') }), _jsx(Ark.Preview, { ...part('preview') })] }), controls && (_jsx(Ark.Control, { ...part('control'), children: editing ? _jsxs(_Fragment, { children: [_jsx(Ark.SubmitTrigger, { ...part('submit-trigger'), "aria-label": t.common.save, children: _jsx("iconify-icon", { icon: "lucide:check" }) }), _jsx(Ark.CancelTrigger, { ...part('cancel-trigger'), "aria-label": t.common.cancel, children: _jsx("iconify-icon", { icon: "lucide:x" }) })] }) : _jsx(Ark.EditTrigger, { ...part('edit-trigger'), "aria-label": t.common.edit, children: _jsx("iconify-icon", { icon: "lucide:pencil" }) }) }))] })] }));
+}
+export const Editable = withParts(EditableShortcut, {
+    Root: Ark.Root, RootProvider: Ark.RootProvider, Area: Ark.Area, Input: Ark.Input, Preview: Ark.Preview, Control: Ark.Control,
+    EditTrigger: Ark.EditTrigger, SubmitTrigger: Ark.SubmitTrigger, CancelTrigger: Ark.CancelTrigger, Label: Ark.Label, Context: Ark.Context,
+});

package/dist/editable/editable.css

@@ -0,0 +1,25 @@
+@layer ui {
+  [data-scope=editable][data-part=root] { display: block; min-width: 0; color: var(--ui-text); font-family: var(--ui-font); font-size: 14px; }
+  [data-scope=editable][data-part=label] { display: block; margin-bottom: 0.25rem; font-size: 14px; font-weight: 500; }
+  [data-scope=editable][data-part=row] { display: flex; align-items: center; gap: 0.25rem; min-width: 0; }
+  [data-scope=editable][data-part=area] { flex: 1; min-width: 0; }
+  /* As text until clicked: a faint box on hover says it can be edited. */
+  [data-scope=editable][data-part=preview] { display: block; margin: 0 -0.375rem; padding: 0.25rem 0.375rem; border-radius: calc(var(--ui-radius) - 2px);
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap; cursor: text;
+    &:hover { background: var(--ui-hover); }
+    &[data-placeholder-shown] { color: var(--ui-muted); }
+    [data-disabled] & { cursor: default; background: transparent; } }
+  [data-scope=editable][data-part=input] { width: 100%; box-sizing: border-box; margin: 0 -0.375rem; padding: 0.25rem 0.375rem;
+    border: 1px solid var(--ui-ring); border-radius: calc(var(--ui-radius) - 2px); outline: 2px solid var(--ui-ring-soft);
+    background: var(--ui-surface); color: inherit; font: inherit; }
+  [data-scope=editable][data-part=control] { display: flex; gap: 0.125rem; flex-shrink: 0; }
+  [data-scope=editable]:is([data-part=edit-trigger], [data-part=submit-trigger], [data-part=cancel-trigger]) {
+    display: grid; place-items: center; width: 1.75rem; height: 1.75rem; padding: 0; border: none; border-radius: calc(var(--ui-radius) - 2px);
+    background: transparent; color: var(--ui-muted); font-size: 14px; cursor: pointer;
+    &:hover { background: var(--ui-hover); color: var(--ui-text); }
+    &:focus-visible { outline: 2px solid var(--ui-ring-soft); } }
+  /* The pencil shows on hover (and when focused), to keep the text clean. */
+  [data-scope=editable][data-part=edit-trigger] { opacity: 0;
+    [data-part=root]:hover &, &:focus-visible { opacity: 1; } }
+  [data-scope=editable][data-part=submit-trigger] { color: var(--ui-accent); }
+}

package/dist/editor/Editor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A rich text editor on TipTap (ProseMirror): a toolbar over an editable area
+ * whose value is HTML.
+ *
+ *   <Editor label="Notes" placeholder="Lesson notes…" value={notes} onValueChange={setNotes} />
+ *
+ * Inside a Field it takes the field's label, hint and error.
+ *
+ * - `value`, `defaultValue`: the HTML ('' when empty); `onValueChange`
+ * - `label`: a label above it (skipped inside a Field)
+ * - `tools`: which toolbar buttons, in order ('|' for a divider): bold,
+ *   italic, underline, strike, code, h2, h3, bulletList, orderedList,
+ *   blockquote, link, image, undo, redo
+ * - `toolbar`: false hides the toolbar
+ * - `placeholder`: shown while it's empty
+ * - `maxLength`: a character limit, with a counter
+ * - `minHeight`, `maxHeight`: CSS lengths; it scrolls past maxHeight
+ * - `disabled`: read only
+ * - `uploadImage`: an async function taking a File and returning its URL, or
+ *   `{ src, alt, title, data-* }` (data-* kept on the <img>, e.g. a signed id
+ *   for your server). With it, images can be dropped, pasted or picked with
+ *   the image button, and are inserted once uploaded; without it, dropped
+ *   and pasted files are ignored. A failed upload calls `onError`
+ * - `editorRef`: a ref given the TipTap editor, for anything more
+ *
+ * Keyboard shortcuts are TipTap's (⌘B, ⌘I, ⌘U, ⌘⇧7/8 for lists, ⌘Z…).
+ */
+import { type HTMLAttributes, type ReactNode, type RefObject } from 'react';
+import { Editor as TipTap } from '@tiptap/core';
+import 'iconify-icon';
+import { type Classes } from '../utils.js';
+import '../theme.css';
+import './editor.css';
+export type EditorTool = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'h2' | 'h3' | 'bulletList' | 'orderedList' | 'blockquote' | 'link' | 'image' | 'undo' | 'redo' | '|';
+export type UploadedImage = string | {
+    src: string;
+    alt?: string;
+    title?: string;
+    [data: `data-${string}`]: string;
+};
+export declare const defaultTools: EditorTool[];
+export type EditorProps = Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onError'> & {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (html: string) => void;
+    label?: ReactNode;
+    placeholder?: string;
+    tools?: EditorTool[];
+    toolbar?: boolean;
+    maxLength?: number | null;
+    minHeight?: string;
+    maxHeight?: string | null;
+    disabled?: boolean;
+    uploadImage?: ((file: File) => Promise<UploadedImage | null | undefined>) | null;
+    onError?: (error: unknown) => void;
+    editorRef?: RefObject<TipTap | null>;
+    classes?: Classes<'label' | 'root' | 'toolbar' | 'divider' | 'tool' | 'imageInput' | 'content' | 'uploading' | 'count' | 'linkForm' | 'linkActions'>;
+};
+export declare function Editor({ value, defaultValue, onValueChange, label, placeholder, tools, toolbar, maxLength, minHeight, maxHeight, disabled, uploadImage, onError, editorRef, className, classes, ...rest }: EditorProps): import("react").JSX.Element;

package/dist/editor/Editor.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * A rich text editor on TipTap (ProseMirror): a toolbar over an editable area
+ * whose value is HTML.
+ *
+ *   <Editor label="Notes" placeholder="Lesson notes…" value={notes} onValueChange={setNotes} />
+ *
+ * Inside a Field it takes the field's label, hint and error.
+ *
+ * - `value`, `defaultValue`: the HTML ('' when empty); `onValueChange`
+ * - `label`: a label above it (skipped inside a Field)
+ * - `tools`: which toolbar buttons, in order ('|' for a divider): bold,
+ *   italic, underline, strike, code, h2, h3, bulletList, orderedList,
+ *   blockquote, link, image, undo, redo
+ * - `toolbar`: false hides the toolbar
+ * - `placeholder`: shown while it's empty
+ * - `maxLength`: a character limit, with a counter
+ * - `minHeight`, `maxHeight`: CSS lengths; it scrolls past maxHeight
+ * - `disabled`: read only
+ * - `uploadImage`: an async function taking a File and returning its URL, or
+ *   `{ src, alt, title, data-* }` (data-* kept on the <img>, e.g. a signed id
+ *   for your server). With it, images can be dropped, pasted or picked with
+ *   the image button, and are inserted once uploaded; without it, dropped
+ *   and pasted files are ignored. A failed upload calls `onError`
+ * - `editorRef`: a ref given the TipTap editor, for anything more
+ *
+ * Keyboard shortcuts are TipTap's (⌘B, ⌘I, ⌘U, ⌘⇧7/8 for lists, ⌘Z…).
+ */
+import { useEffect, useId, useReducer, useRef, useState } from 'react';
+import { Editor as TipTap } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { Placeholder, CharacterCount } from '@tiptap/extensions';
+import { useFieldContext } from '@ark-ui/react/field';
+import 'iconify-icon';
+import { RichImage } from './image.js';
+import { Popover } from '../popover/Popover.js';
+import { Input } from '../input/Input.js';
+import { Button } from '../button/Button.js';
+import { cx, partsOf, useControllable } from '../utils.js';
+import { useMessages } from '../format/LocaleProvider.js';
+import '../theme.css';
+import './editor.css';
+export const defaultTools = ['bold', 'italic', 'underline', 'strike', '|', 'h2', 'h3', '|', 'bulletList', 'orderedList', 'blockquote', '|', 'link', 'image', '|', 'undo', 'redo'];
+// Each tool: its icon and label, how it runs, and when it's active.
+const toolDefs = {
+    bold: { icon: 'lucide:bold', label: 'Bold', run: (c) => c.toggleBold(), active: ['bold'] },
+    italic: { icon: 'lucide:italic', label: 'Italic', run: (c) => c.toggleItalic(), active: ['italic'] },
+    underline: { icon: 'lucide:underline', label: 'Underline', run: (c) => c.toggleUnderline(), active: ['underline'] },
+    strike: { icon: 'lucide:strikethrough', label: 'Strikethrough', run: (c) => c.toggleStrike(), active: ['strike'] },
+    code: { icon: 'lucide:code', label: 'Code', run: (c) => c.toggleCode(), active: ['code'] },
+    h2: { icon: 'lucide:heading-2', label: 'Heading', run: (c) => c.toggleHeading({ level: 2 }), active: ['heading', { level: 2 }] },
+    h3: { icon: 'lucide:heading-3', label: 'Subheading', run: (c) => c.toggleHeading({ level: 3 }), active: ['heading', { level: 3 }] },
+    bulletList: { icon: 'lucide:list', label: 'Bulleted list', run: (c) => c.toggleBulletList(), active: ['bulletList'] },
+    orderedList: { icon: 'lucide:list-ordered', label: 'Numbered list', run: (c) => c.toggleOrderedList(), active: ['orderedList'] },
+    blockquote: { icon: 'lucide:text-quote', label: 'Quote', run: (c) => c.toggleBlockquote(), active: ['blockquote'] },
+    undo: { icon: 'lucide:undo-2', label: 'Undo', run: (c) => c.undo(), can: 'undo' },
+    redo: { icon: 'lucide:redo-2', label: 'Redo', run: (c) => c.redo(), can: 'redo' },
+};
+// A URL, or { src, alt, title, data-*… }, as the image node's attributes.
+function imageAttrs(result, file) {
+    if (!result)
+        return null;
+    if (typeof result === 'string')
+        return { src: result, alt: file.name };
+    const data = Object.fromEntries(Object.entries(result).filter(([key]) => key.startsWith('data-')));
+    return { src: result.src, alt: result.alt ?? file.name, title: result.title ?? null, data: Object.keys(data).length ? data : null };
+}
+export function Editor({ value, defaultValue = '', onValueChange, label = null, placeholder = '', tools = defaultTools, toolbar = true, maxLength = null, minHeight = '8rem', maxHeight = null, disabled = false, uploadImage = null, onError, editorRef, className, classes, ...rest }) {
+    const t = useMessages();
+    const field = useFieldContext();
+    const part = partsOf('editor', classes);
+    const id = useId();
+    const labelId = field ? field.ids.label : label ? `${id}-label` : undefined;
+    const [current, setCurrent] = useControllable(value, defaultValue, onValueChange);
+    const contentEl = useRef(null);
+    const [editor, setEditor] = useState(null);
+    const [focused, setFocused] = useState(false);
+    const [uploading, setUploading] = useState(0);
+    // Bumped on every transaction, so the toolbar's states re-read the editor.
+    const [, bump] = useReducer((n) => n + 1, 0);
+    // The HTML the editor last had, to tell its own changes from new values.
+    const html = useRef(current ?? '');
+    // The latest props, for the editor's callbacks (it's made once).
+    const latest = useRef({ setCurrent, placeholder, uploadImage, onError, labelId, field });
+    useEffect(() => { latest.current = { setCurrent, placeholder, uploadImage, onError, labelId, field }; });
+    // Uploads the images among `files` and inserts each at `pos` (or the cursor) as it arrives.
+    async function insertImages(instance, files, pos = null) {
+        const upload = latest.current.uploadImage;
+        if (!upload)
+            return;
+        for (const file of files.filter((f) => (f.type ?? '').startsWith('image/'))) {
+            setUploading((n) => n + 1);
+            try {
+                const attrs = imageAttrs(await upload(file), file);
+                if (attrs && !instance.isDestroyed)
+                    instance.chain().focus().insertContentAt(pos ?? instance.state.selection.to, { type: 'image', attrs }).run();
+            }
+            catch (error) {
+                latest.current.onError?.(error);
+            }
+            setUploading((n) => n - 1);
+        }
+    }
+    const insert = useRef(insertImages);
+    useEffect(() => { insert.current = insertImages; });
+    // Made once; the effects below keep it in step with the props.
+    useEffect(() => {
+        const instance = new TipTap({
+            element: contentEl.current,
+            content: html.current,
+            editable: !disabled,
+            extensions: [
+                StarterKit.configure({ heading: { levels: [2, 3] }, link: { openOnClick: false, autolink: true } }),
+                Placeholder.configure({ placeholder: () => latest.current.placeholder }),
+                CharacterCount.configure({ limit: maxLength }),
+                RichImage,
+            ],
+            editorProps: {
+                // Files dropped or pasted: images go to `uploadImage`; anything else
+                // is ignored, so the browser doesn't open the file in the tab.
+                handleDrop(view, event, _slice, moved) {
+                    const files = Array.from(event.dataTransfer?.files ?? []);
+                    if (moved || !files.length)
+                        return false;
+                    event.preventDefault();
+                    insert.current(instance, files, view.posAtCoords({ left: event.clientX, top: event.clientY })?.pos ?? null);
+                    return true;
+                },
+                handlePaste(_view, event) {
+                    const files = Array.from(event.clipboardData?.files ?? []);
+                    if (!files.length)
+                        return false;
+                    insert.current(instance, files);
+                    return true;
+                },
+                // Read on every update, so the field's label and messages follow.
+                attributes: () => ({
+                    role: 'textbox', 'aria-multiline': 'true',
+                    'aria-labelledby': latest.current.labelId ?? '', 'aria-describedby': latest.current.field?.ariaDescribedby ?? '',
+                    'aria-invalid': latest.current.field?.invalid ? 'true' : 'false',
+                }),
+            },
+            onCreate: () => setEditor(instance),
+            onUpdate: ({ editor }) => {
+                html.current = editor.isEmpty ? '' : editor.getHTML();
+                latest.current.setCurrent(html.current);
+            },
+            onTransaction: bump,
+            onFocus: () => setFocused(true),
+            onBlur: () => setFocused(false),
+        });
+        if (editorRef)
+            editorRef.current = instance;
+        return () => {
+            instance.destroy();
+            if (editorRef)
+                editorRef.current = null;
+            setEditor(null);
+        };
+        // Made once: maxLength and the rest are read when it's created.
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    // A new value from outside (not the editor's own) replaces the content.
+    useEffect(() => {
+        if (editor && (current ?? '') !== html.current) {
+            html.current = current ?? '';
+            editor.commands.setContent(html.current, { emitUpdate: false });
+        }
+    }, [editor, current]);
+    useEffect(() => { if (editor && editor.isEditable === disabled)
+        editor.setEditable(!disabled); }, [editor, disabled]);
+    // ProseMirror reads its attributes on updates; refresh them when the field changes.
+    useEffect(() => { editor?.view.setProps({}); }, [editor, labelId, field?.ariaDescribedby, field?.invalid]);
+    const isActive = (tool) => !!editor && !!tool.active && editor.isActive(...tool.active);
+    const canRun = (tool) => !!editor && !disabled && (tool.can ? editor.can()[tool.can]() : true);
+    const run = (tool) => editor && tool.run(editor.chain().focus()).run();
+    const characters = editor ? editor.storage.characterCount.characters() : 0;
+    // The link popover: the current link's address, applied or removed.
+    const [linkOpen, setLinkOpen] = useState(false);
+    const [linkUrl, setLinkUrl] = useState('');
+    const linkActive = !!editor?.isActive('link');
+    function openLink(open) {
+        if (open)
+            setLinkUrl(editor?.getAttributes('link')?.href ?? '');
+        setLinkOpen(open);
+    }
+    function applyLink(e) {
+        e.preventDefault();
+        if (!editor)
+            return;
+        const url = linkUrl.trim();
+        const chain = editor.chain().focus().extendMarkRange('link');
+        if (url)
+            chain.setLink({ href: /^[a-z]+:/i.test(url) ? url : `https://${url}` }).run();
+        else
+            chain.unsetLink().run();
+        setLinkOpen(false);
+    }
+    function removeLink() {
+        editor?.chain().focus().extendMarkRange('link').unsetLink().run();
+        setLinkOpen(false);
+    }
+    function pickedImages(e) {
+        const files = Array.from(e.target.files ?? []);
+        e.target.value = '';
+        if (editor)
+            insertImages(editor, files);
+    }
+    // Toolbar buttons keep the editor's selection (no focus on mousedown).
+    const keepFocus = (e) => e.preventDefault();
+    return _jsxs(_Fragment, { children: [label && !field && _jsx("span", { ...part('label'), id: labelId, children: label }), _jsxs("div", { ...rest, ...part('root'), className: cx(className, classes?.root), "data-focused": focused || undefined, "data-disabled": disabled || undefined, "data-invalid": field?.invalid || undefined, children: [toolbar && !disabled && (_jsx("div", { ...part('toolbar'), role: "toolbar", "aria-label": t.editor.toolbar, children: tools.map((name, i) => {
+                            if (name === '|')
+                                return _jsx("span", { ...part('divider') }, `d${i}`);
+                            if (name === 'link')
+                                return (_jsx(Popover, { placement: "bottom-start", open: linkOpen, onOpenChange: openLink, trigger: _jsx("button", { ...part('tool'), type: "button", "aria-label": t.editor.link, "aria-pressed": linkActive, onMouseDown: keepFocus, children: _jsx("iconify-icon", { icon: "lucide:link", "aria-hidden": "true" }) }), children: _jsxs("form", { ...part('link-form'), onSubmit: applyLink, children: [_jsx(Input, { size: "sm", icon: "lucide:link", placeholder: t.editor.linkPlaceholder, value: linkUrl, onValueChange: setLinkUrl }), _jsxs("div", { ...part('link-actions'), children: [linkActive && _jsx(Button, { size: "sm", variant: "ghost", onClick: removeLink, children: t.editor.remove }), _jsx(Button, { size: "sm", variant: "primary", type: "submit", children: t.editor.apply })] })] }) }, name));
+                            if (name === 'image')
+                                return uploadImage && (_jsxs("label", { ...part('tool'), "aria-label": t.editor.image, onMouseDown: keepFocus, children: [_jsx("input", { ...part('image-input'), type: "file", accept: "image/*", multiple: true, onChange: pickedImages }), _jsx("iconify-icon", { icon: "lucide:image", "aria-hidden": "true" })] }, name));
+                            const tool = toolDefs[name];
+                            return tool && (_jsx("button", { ...part('tool'), type: "button", "aria-label": t.editor.tools[name] ?? tool.label, "aria-pressed": tool.active ? isActive(tool) : undefined, disabled: !canRun(tool), onMouseDown: keepFocus, onClick: () => run(tool), children: _jsx("iconify-icon", { icon: tool.icon, "aria-hidden": "true" }) }, name));
+                        }) })), _jsx("div", { ...part('content'), ref: contentEl, style: { '--min-height': minHeight, '--max-height': maxHeight ?? 'none' } }), uploading > 0 && _jsx("div", { ...part('uploading'), children: t.editor.uploading }), maxLength && _jsxs("div", { ...part('count'), "data-over": characters >= maxLength || undefined, children: [characters, " / ", maxLength] })] })] });
+}

package/dist/editor/editor.css

@@ -0,0 +1,42 @@
+@layer ui {
+  [data-scope=editor][data-part=label] { display: block; margin-bottom: 0.375rem; font-size: 14px; font-weight: 500; color: var(--ui-text); font-family: var(--ui-font); }
+  [data-scope=editor][data-part=root] { display: block; position: relative; width: 100%; min-width: 0; box-sizing: border-box;
+    background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius);
+    color: var(--ui-text); font-family: var(--ui-font); font-size: 14px;
+    &[data-focused] { border-color: var(--ui-ring); outline: 2px solid var(--ui-ring-soft); }
+    &[data-invalid] { border-color: var(--ui-danger); }
+    &[data-disabled] { background: var(--ui-hover); } }
+  [data-scope=editor][data-part=toolbar] { display: flex; align-items: center; flex-wrap: wrap; gap: 0.125rem; padding: 0.25rem; border-bottom: 1px solid var(--ui-border); }
+  [data-scope=editor][data-part=tool] { display: grid; place-items: center; width: 2rem; height: 2rem; padding: 0; border: none;
+    border-radius: calc(var(--ui-radius) - 2px); background: transparent; color: var(--ui-muted); font-size: 16px; cursor: pointer;
+    &:hover { color: var(--ui-text); background: var(--ui-hover); }
+    &:focus-visible, &:focus-within:has(:focus-visible) { outline: 2px solid var(--ui-ring-soft); }
+    &:disabled { opacity: 0.35; cursor: default; background: transparent; }
+    &[aria-pressed=true] { color: var(--ui-text); background: var(--ui-hover); } }
+  [data-scope=editor][data-part=divider] { width: 1px; height: 1.25rem; margin: 0 0.25rem; background: var(--ui-border); }
+  [data-scope=editor][data-part=image-input] { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
+  [data-scope=editor][data-part=uploading] { position: absolute; left: 0.75rem; bottom: 0.375rem; font-size: 12px; color: var(--ui-muted); }
+  [data-scope=editor][data-part=link-form] { display: flex; flex-direction: column; gap: 0.5rem; width: 16rem; }
+  [data-scope=editor][data-part=link-actions] { display: flex; justify-content: flex-end; gap: 0.5rem; }
+  /* The editable area (ProseMirror renders it). */
+  [data-scope=editor][data-part=content] {
+    & .ProseMirror { min-height: var(--min-height); max-height: var(--max-height); overflow-y: auto; padding: 0.625rem 0.75rem; outline: none;
+      line-height: 1.6; overflow-wrap: anywhere; }
+    & :is(p, ul, ol, blockquote, h2, h3) { margin: 0 0 0.5rem; }
+    & .ProseMirror > :last-child { margin-bottom: 0; }
+    & h2 { font-size: 18px; font-weight: 600; line-height: 1.3; margin-top: 0.75rem; }
+    & h3 { font-size: 16px; font-weight: 600; line-height: 1.3; margin-top: 0.625rem; }
+    & :is(ul, ol) { padding-left: 1.25rem; }
+    & ul { list-style: disc; }
+    & ol { list-style: decimal; }
+    & li > p { margin: 0; }
+    & blockquote { padding-left: 0.75rem; border-left: 3px solid var(--ui-border); color: var(--ui-muted); }
+    & code { padding: 0.125rem 0.25rem; border-radius: 4px; background: var(--ui-hover); font-family: ui-monospace, monospace; font-size: 0.9em; }
+    & a { color: var(--ui-accent); text-decoration: underline; text-underline-offset: 2px; }
+    & img { display: block; max-width: 100%; height: auto; margin: 0.5rem 0; border-radius: var(--ui-radius); }
+    & img.ProseMirror-selectednode { outline: 2px solid var(--ui-ring); }
+    /* TipTap's placeholder: on the first empty paragraph. */
+    & p.is-editor-empty:first-child::before { content: attr(data-placeholder); float: left; height: 0; color: var(--ui-muted); pointer-events: none; } }
+  [data-scope=editor][data-part=count] { position: absolute; right: 0.625rem; bottom: 0.375rem; font-size: 12px; color: var(--ui-muted); pointer-events: none;
+    &[data-over] { color: var(--ui-danger); } }
+}

package/dist/editor/image.d.ts

@@ -0,0 +1 @@
+export declare const RichImage: import("@tiptap/core").Node<import("@tiptap/extension-image").ImageOptions, any>;