@bizapps/design-system-testing 1.0.11 → 1.6.0

package/dist/editor.d.cts

@@ -0,0 +1,318 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Editor } 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;
+
+/**
+ * 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 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;
+
+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 RichTextEditorProps, RichTextToolbar, type RichTextToolbarProps, TableMenu, type TableMenuLabels, type TableMenuProps, type ToolbarItem, createResizableImage };

package/dist/editor.d.ts

@@ -0,0 +1,318 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Editor } 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;
+
+/**
+ * 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 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;
+
+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 RichTextEditorProps, RichTextToolbar, type RichTextToolbarProps, TableMenu, type TableMenuLabels, type TableMenuProps, type ToolbarItem, createResizableImage };