@bizapps/design-system-testing 1.8.0 → 1.9.0

package/dist/editor.d.cts

@@ -1,428 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { Editor, JSONContent, EditorOptions } from '@tiptap/react';
-import * as _tiptap_core from '@tiptap/core';
-import { ImageOptions } from '@tiptap/extension-image';
-
-/**
- * A toolbar entry is data, never a mark.
- *
- * An editor's marks are ProseMirror extensions — code with serialization and
- * parsing rules — so they belong to whoever owns the document contract, not to
- * this package. A consumer declares what its buttons do here and keeps its own
- * custom marks; the toolbar only asks the editor whether something is active
- * and runs the callback it was handed.
- */
-type ToolbarItem = {
-    kind: 'separator';
-} | {
-    kind: 'button';
-    id: string;
-    /**
-     * A node, not an icon name: keeps this package off any icon library
-     * and lets a button pass bare text (a font's own name, say) instead.
-     */
-    icon: ReactNode;
-    /** Already translated. Names the button for both `title` and `aria-label`. */
-    label: string;
-    /**
-     * What to ask the editor for the pressed state. Omit for actions that
-     * only open a dialog and are never "on" — announcing those as a
-     * permanently-off toggle misleads a screen reader.
-     */
-    active?: {
-        name: string;
-        attrs?: Record<string, unknown>;
-    };
-    run: (editor: Editor) => void;
-}
-/** Escape hatch for entries that own state or render their own popover. */
- | {
-    kind: 'custom';
-    id: string;
-    render: (editor: Editor | null) => ReactNode;
-};
-interface RichTextToolbarProps {
-    /** Null while the editor mounts; every button disables itself until then. */
-    editor: Editor | null;
-    items: ToolbarItem[];
-}
-/** Renders a declarative toolbar for a Tiptap editor. */
-declare function RichTextToolbar({ editor, items }: RichTextToolbarProps): react.JSX.Element;
-
-/**
- * Base content styles for the editable area, exported so a consumer can pass
- * them to `useEditor({ editorProps: { attributes: { class } } })` — ProseMirror
- * needs that class at construction time, before this component renders.
- *
- * Compose rather than replace: `cn(EDITOR_CONTENT_STYLE, 'my-overrides')`.
- */
-declare const EDITOR_CONTENT_STYLE: string;
-interface RichTextEditorProps {
-    /** Null while the editor mounts. Build it with Tiptap's `useEditor`. */
-    editor: Editor | null;
-    items: ToolbarItem[];
-    /**
-     * Already translated. Omit to render no visible label.
-     *
-     * Note that a visible label does NOT name the editable area on its own:
-     * ProseMirror renders that as role='textbox', and EditorContent's props land
-     * on a wrapper div rather than on the editable node. Give the editor its own
-     * name where you construct it:
-     *
-     * ```ts
-     * useEditor({
-     *   editorProps: { attributes: { class: EDITOR_CONTENT_STYLE, 'aria-label': t('body') } },
-     * })
-     * ```
-     */
-    label?: string;
-    /** Already translated message. Drives the destructive border and the hint. */
-    error?: string;
-    /**
-     * Slot under the editor for product-specific actions, so the editor itself
-     * stays free of any one product's features.
-     */
-    footer?: ReactNode;
-    className?: string;
-}
-/** Chrome for a Tiptap editor: a declarative toolbar, the editable area, and an error slot. */
-declare function RichTextEditor({ editor, items, label, error, footer, className }: RichTextEditorProps): react.JSX.Element;
-
-interface TableMenuLabels {
-    trigger: string;
-    insert: string;
-    /**
-     * A function, not a string: this is the only label with variables, and
-     * formatting it here would mean reimplementing message interpolation. The
-     * consumer keeps that in whatever i18n layer it already has.
-     */
-    dimensions: (rows: number, columns: number) => string;
-    rowBefore: string;
-    rowAfter: string;
-    deleteRow: string;
-    columnBefore: string;
-    columnAfter: string;
-    deleteColumn: string;
-    toggleHeader: string;
-    deleteTable: string;
-}
-interface TableMenuProps {
-    editor: Editor | null;
-    labels: TableMenuLabels;
-    icon: ReactNode;
-    /**
-     * The picker grid's extent. These bound the visual picker only — a
-     * consumer whose document contract caps table size should also enforce
-     * that ceiling where it validates the document.
-     */
-    maxRows?: number;
-    maxColumns?: number;
-}
-/** Word-style table controls: a grid picker to insert, then row/column actions. */
-declare function TableMenu({ editor, labels, icon, maxRows, maxColumns, }: TableMenuProps): react.JSX.Element;
-
-interface InsertImageDialogLabels {
-    title: string;
-    urlLabel: string;
-    urlPlaceholder: string;
-    altLabel: string;
-    hint: string;
-    cancel: string;
-    apply: string;
-    remove: string;
-}
-interface InsertImageDialogProps {
-    open: boolean;
-    onOpenChange: (open: boolean) => void;
-    labels: InsertImageDialogLabels;
-    url: string;
-    onUrlChange: (url: string) => void;
-    alt: string;
-    onAltChange: (alt: string) => void;
-    file: File | null;
-    onFileChange: (file: File | null) => void;
-    /** True while the consumer is transferring the picked file. Locks the form. */
-    uploading: boolean;
-    onApply: () => void;
-    onCancel?: () => void;
-    /**
-     * True when editing an image already in the document — reveals the
-     * destructive remove action beside the apply button.
-     */
-    removable?: boolean;
-    onRemove?: () => void;
-    /** Upload limits belong to whoever receives the file, not to this dialog. */
-    maxSizeBytes?: number;
-    accept?: Record<string, string[]>;
-}
-/**
- * A controlled form for inserting an image. It deliberately does NOT upload:
- * the consumer owns the transfer (its own API, its own storage) and drives
- * `uploading` / `onApply` from there, so this dialog stays reusable across
- * products with different backends.
- */
-declare function InsertImageDialog({ open, onOpenChange, labels, url, onUrlChange, alt, onAltChange, file, onFileChange, uploading, onApply, onCancel, removable, onRemove, maxSizeBytes, accept, }: InsertImageDialogProps): react.JSX.Element;
-
-interface LinkBubbleMenuLabels {
-    open: string;
-    edit: string;
-    remove: string;
-}
-interface LinkBubbleMenuProps {
-    editor: Editor | null;
-    labels: LinkBubbleMenuLabels;
-    /** Opens the consumer's link dialog, pre-filled with the current href. */
-    onEdit: () => void;
-    /**
-     * Follows the link. Left to the consumer for the cases this package cannot
-     * judge — routing instead of navigating, or confirming first.
-     *
-     * Defaults to opening a new tab, which is also what Ctrl/Cmd-click does, so
-     * the author never loses unsaved work just by checking a URL.
-     */
-    onOpen?: (href: string) => void;
-}
-/**
- * A floating bar that appears when the caret sits inside a link, offering to
- * open, edit or unlink it.
- *
- * It exists because an editor cannot let a plain click navigate: clicking is how
- * you place the caret to fix a typo, so `openOnClick` stays false and this gives
- * the author a deliberate way out to the URL. Ctrl/Cmd-click is wired separately,
- * on the editor itself, for people who expect the shortcut.
- */
-declare function LinkBubbleMenu({ editor, labels, onEdit, onOpen }: LinkBubbleMenuProps): react.JSX.Element | null;
-
-/**
- * Whatever `useEditor` accepts in its `extensions` array.
- *
- * Derived from Tiptap's own option rather than imported as AnyExtension: the
- * name resolves to a structurally different declaration depending on which copy
- * of @tiptap/core is in scope, and the two do not assign to each other.
- */
-type EditorExtension = EditorOptions['extensions'][number];
-/** Every string the built-in toolbar and menus need. All already translated. */
-interface RichTextEditorLabels {
-    /** Names the editable area for assistive tech. Required — it has no visible label. */
-    editor: string;
-    bold: string;
-    italic: string;
-    heading: string;
-    underline: string;
-    strikethrough: string;
-    quote: string;
-    insertLink: string;
-    insertImage: string;
-    resizeImage: string;
-    lists: {
-        trigger: string;
-        bullet: string;
-        ordered: string;
-    };
-    /** The floating bar shown while the caret sits inside a link. */
-    link: LinkBubbleMenuLabels;
-    table: TableMenuLabels;
-    highlight: string;
-}
-interface UseRichTextEditorOptions {
-    labels: RichTextEditorLabels;
-    /** Fires on every document change, with the current ProseMirror JSON. */
-    onUpdate?: (doc: JSONContent) => void;
-    /** Initial document. */
-    content?: JSONContent | string;
-    /** Opens the consumer's link dialog. Wire the toolbar's link button to it. */
-    onInsertLink?: () => void;
-    /** Opens the consumer's image dialog. */
-    onInsertImage?: () => void;
-    /**
-     * Marks and nodes this product's document contract requires — a brand font,
-     * a colour palette, anything a server-side whitelist validates. They are
-     * appended to the built-in set rather than replacing it.
-     */
-    extraExtensions?: EditorExtension[];
-    /**
-     * Extra toolbar entries, and where they go. `after` names a built-in id
-     * (`heading`, `highlight`, `strike`, `image`…); omit it to append at the end.
-     */
-    extraToolbar?: {
-        after?: string;
-        items: ToolbarItem[];
-    }[];
-    /**
-     * Replaces a built-in entry, keyed by its id.
-     *
-     * For when a product needs a richer version of something the preset already
-     * provides — swapping the single highlight button for a palette of shades,
-     * say. Replacing rather than adding keeps the toolbar from carrying both.
-     */
-    replaceToolbar?: Record<string, ToolbarItem>;
-    /** Merged on top of the built-in content styles. */
-    contentClassName?: string;
-    /** Allows data: URIs in images. Off by default: uploads belong in storage. */
-    allowBase64Images?: boolean;
-    /**
-     * Merged into the editor's `editorProps`. For behaviour only a product can
-     * define — clamping pasted tables to a contract's row limit, say.
-     *
-     * `attributes` and `handleClick` are set by the hook and are not overridable:
-     * they carry the accessible name and the link shortcut, which are the
-     * defaults consumers were getting wrong by hand.
-     */
-    editorProps?: Omit<NonNullable<EditorOptions['editorProps']>, 'attributes' | 'handleClick'>;
-}
-interface UseRichTextEditorResult {
-    editor: Editor | null;
-    /**
-     * The floating link bar, ready to render beside `<RichTextEditor />`.
-     *
-     * Returned as an element rather than left to the consumer because it is easy
-     * to forget, and an editor without it gives the author no way to reach or
-     * remove a link they have already inserted.
-     */
-    linkMenu: ReactNode;
-    /** Ready for `<RichTextEditor items={...} />`. */
-    toolbar: ToolbarItem[];
-    /** True when the caret has no selection, so a new link needs its own text. */
-    linkNeedsText: boolean;
-    /** Reads the caret's current href — pre-fill the dialog with it. */
-    currentLinkHref: () => string;
-    /** Applies a link, inserting `text` when there is no selection to wrap. */
-    applyLink: (href: string, text?: string) => void;
-}
-/**
- * Builds a configured Tiptap editor and its toolbar.
- *
- * Everything a rich text editor needs to behave correctly is set up here —
- * Ctrl/Cmd-click on links, the accessible name for the editable area, the
- * repaint-on-transaction the toolbar's pressed state depends on, the content
- * styles — so a consumer cannot end up with a subtly different editor by
- * forgetting one of them.
- *
- * What stays with the consumer is what only it can know: the marks its document
- * contract allows, and the copy. Both arrive as options.
- */
-declare function useRichTextEditor({ labels, onUpdate, content, onInsertLink, onInsertImage, extraExtensions, extraToolbar, replaceToolbar, contentClassName, allowBase64Images, editorProps, }: UseRichTextEditorOptions): UseRichTextEditorResult;
-
-/**
- * One entry in the palette.
- *
- * `mark` is a mark name, not a colour value: a consumer's document contract
- * decides which marks exist, and a palette of named marks costs nothing to
- * validate server-side — unlike a mark carrying an arbitrary colour, which would
- * change the shape of every stored span.
- */
-interface ColorSwatch {
-    /** The Tiptap mark this swatch toggles, e.g. `colorPrimary`. */
-    mark: string;
-    /** Already translated name, used as the swatch's accessible label. */
-    label: string;
-    /** CSS colour for the swatch preview only. */
-    preview: string;
-}
-interface ColorMenuLabels {
-    trigger: string;
-    /** Heading above the swatches. */
-    heading: string;
-    /** Clears whichever colour mark is applied. */
-    clear: string;
-}
-interface ColorMenuProps {
-    editor: Editor | null;
-    labels: ColorMenuLabels;
-    icon: ReactNode;
-    swatches: ColorSwatch[];
-}
-/**
- * A palette dropdown that toggles one mark at a time.
- *
- * Deliberately not the design system's `ColorPicker`: a free picker offers
- * millions of values, and an editor whose authors can pick any colour produces
- * articles that no longer look like one publication. A short list of brand
- * shades is the constraint that keeps them consistent.
- */
-declare function ColorMenu({ editor, labels, icon, swatches }: ColorMenuProps): react.JSX.Element;
-
-/** One list style the consumer offers. */
-interface ListOption {
-    /** The Tiptap node this entry toggles, e.g. `bulletList`. */
-    node: string;
-    /** Already translated name. */
-    label: string;
-    icon: ReactNode;
-    run: (editor: Editor) => void;
-}
-interface ListMenuProps {
-    editor: Editor | null;
-    /** Already translated. Names the trigger for assistive tech. */
-    triggerLabel: string;
-    /** Shown on the trigger when no list style is active. */
-    icon: ReactNode;
-    options: ListOption[];
-}
-/**
- * Groups the list styles behind one trigger.
- *
- * A row of separate buttons costs three toolbar slots for choices that are
- * mutually exclusive; one trigger showing the active style reads faster and
- * leaves room for the rest of the toolbar. The trigger swaps to the active
- * style's icon so the current state is visible without opening the menu.
- */
-declare function ListMenu({ editor, triggerLabel, icon, options }: ListMenuProps): react.JSX.Element;
-
-interface InsertLinkDialogLabels {
-    title: string;
-    urlLabel: string;
-    urlPlaceholder: string;
-    /** Explains that clearing the field removes an existing link. */
-    hint: string;
-    /** Field for the visible text, shown only when there is no selection to wrap. */
-    textLabel: string;
-    textPlaceholder: string;
-    cancel: string;
-    apply: string;
-}
-interface InsertLinkDialogProps {
-    open: boolean;
-    onOpenChange: (open: boolean) => void;
-    labels: InsertLinkDialogLabels;
-    url: string;
-    onUrlChange: (url: string) => void;
-    /**
-     * The visible text for a brand-new link. Pass these three together with
-     * `needsText` when the editor has no selection to turn into a link — without
-     * them the dialog can only re-point an existing one.
-     */
-    text?: string;
-    onTextChange?: (text: string) => void;
-    /**
-     * True when there is nothing selected, so the link needs its own text.
-     * Reveals the text field and requires it before applying.
-     */
-    needsText?: boolean;
-    onApply: () => void;
-    onCancel?: () => void;
-}
-/**
- * A controlled form for inserting or editing a link.
- *
- * Clearing the URL and applying is how a link is removed — the consumer decides
- * what that means for its document, so this dialog only reports the values.
- */
-declare function InsertLinkDialog({ open, onOpenChange, labels, url, onUrlChange, text, onTextChange, needsText, onApply, onCancel, }: InsertLinkDialogProps): react.JSX.Element;
-
-interface ResizableImageOptions {
-    /** Already translated: names the resize handle for assistive tech. */
-    resizeLabel: string;
-    minWidth?: number;
-}
-/**
- * Builds an Image extension whose node view carries a resize handle.
- *
- * A factory rather than a component because ProseMirror — not React —
- * instantiates the node view, so there is no place to hand it props. Options
- * ride on the extension instead, and the view reads them off `extension.options`.
- */
-declare function createResizableImage(options: ResizableImageOptions): _tiptap_core.Node<ImageOptions & ResizableImageOptions, any>;
-
-export { ColorMenu, type ColorMenuLabels, type ColorMenuProps, type ColorSwatch, EDITOR_CONTENT_STYLE, InsertImageDialog, type InsertImageDialogLabels, type InsertImageDialogProps, InsertLinkDialog, type InsertLinkDialogLabels, type InsertLinkDialogProps, LinkBubbleMenu, type LinkBubbleMenuLabels, type LinkBubbleMenuProps, ListMenu, type ListMenuProps, type ListOption, type ResizableImageOptions, RichTextEditor, type RichTextEditorLabels, type RichTextEditorProps, RichTextToolbar, type RichTextToolbarProps, TableMenu, type TableMenuLabels, type TableMenuProps, type ToolbarItem, type UseRichTextEditorOptions, type UseRichTextEditorResult, createResizableImage, useRichTextEditor };