@sckyzo/cosmos-react 0.5.0 → 0.6.0

package/dist/editor/index.d.cts

@@ -4,11 +4,18 @@ import { JSONContent } from '@tiptap/react';
 import { FieldSize } from '../index.cjs';
 
 /** The buttons a toolbar can hold, in the order `RICH_TEXT_ACTIONS` lists them. */
-type RichTextAction = 'bold' | 'italic' | 'strike' | 'heading' | 'bulletList' | 'orderedList' | 'blockquote' | 'code' | 'link' | 'undo' | 'redo';
+type RichTextAction = 'bold' | 'italic' | 'underline' | 'strike' | 'heading' | 'bulletList' | 'orderedList' | 'blockquote' | 'code' | 'codeBlock' | 'align' | 'link' | 'image' | 'undo' | 'redo';
 declare const RICH_TEXT_ACTIONS: readonly RichTextAction[];
+/** The items of the menus a button opens: one of them is checked. */
+type RichTextChoice = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'alignStart' | 'alignCenter' | 'alignEnd';
 
-/** Every text the editor draws itself, so a host can translate it. All optional. */
-type RichTextLabels = Partial<Record<RichTextAction, string>> & {
+type Named = RichTextAction | RichTextChoice;
+/**
+ * Every text the editor draws itself, so a host can translate it. All optional. The buttons are
+ * named by their action (`bold`, `heading`, `align`, `image`…) and the items of the heading and
+ * alignment menus by their choice (`paragraph`, `heading1`, `alignCenter`…).
+ */
+type RichTextLabels = Partial<Record<Named, string>> & {
     /** Accessible name of the toolbar. Default `Text formatting`. */
     toolbar?: string;
     /** Accessible name of the field where a link's URL is typed. Default `Link URL`. */
@@ -21,6 +28,20 @@ type RichTextLabels = Partial<Record<RichTextAction, string>> & {
     linkRemove?: string;
     /** Shown when the URL is refused. Default `Enter an http(s), mailto or relative link.` */
     linkInvalid?: string;
+    /** Accessible name of the image popover. Default `Image details`. */
+    imageDialog?: string;
+    /** Label of the field where an image's URL is typed. Default `Image URL`. */
+    imageUrl?: string;
+    /** Label of the description field, the image's `alt`. Default `Description (alt text)`. */
+    imageAlt?: string;
+    /** Label of the box that marks an image as decorative. Default `Decorative image, no description`. */
+    imageDecorative?: string;
+    /** Default `Apply`. */
+    imageApply?: string;
+    /** Shown when the URL is refused. Default `Enter an http(s) image address.` */
+    imageInvalid?: string;
+    /** Shown when an image has no description and is not marked decorative. Default `Describe the image, or mark it decorative.` */
+    imageAltRequired?: string;
 };
 
 /** What `value` and `onChange` carry: the HTML string, or the ProseMirror JSON document. */
@@ -47,7 +68,7 @@ type RichTextEditorProps<F extends RichTextFormat = 'html'> = {
      * the link for `bubble`. Ignored by `minimal`.
      */
     toolbar?: readonly RichTextAction[];
-    /** Replaces any text the editor draws itself: the buttons, their tooltips, the link field. */
+    /** Replaces any text the editor draws itself: the buttons, their tooltips and menus, the link and image fields. */
     labels?: RichTextLabels;
     label?: string;
     description?: string;
@@ -84,15 +105,20 @@ type RichTextEditorProps<F extends RichTextFormat = 'html'> = {
     className?: string;
 };
 /**
- * A formatted text field, built on Tiptap: bold, italic, strike, headings, lists, quote, code,
- * links, undo and redo, behind a toolbar, a bubble over the selection, or only keyboard shortcuts.
- * Part of the `@sckyzo/cosmos-react/editor` entry, which needs the optional peer dependencies
- * (`@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extensions`, `@tiptap/core`, `@tiptap/pm`).
+ * A formatted text field, built on Tiptap: bold, italic, underline, strike, headings, lists,
+ * quote, code and code blocks, alignment, links, images, undo and redo, behind a toolbar, a bubble
+ * over the selection, or only keyboard shortcuts. Part of the `@sckyzo/cosmos-react/editor` entry,
+ * which needs the optional peer dependencies (`@tiptap/react`, `@tiptap/starter-kit`,
+ * `@tiptap/extensions`, `@tiptap/extension-text-align`, `@tiptap/extension-image`,
+ * `@tiptap/core`, `@tiptap/pm`).
  *
- * The schema holds paragraphs, headings (2 and 3), bullet and numbered lists, quotes, hard
- * breaks and the marks above: nothing else survives a paste or `value`. Links go through
- * `isSafeLinkUrl` (http(s), mailto, relative). That is the editor's guarantee, not the server's:
- * the HTML a host stores has to be sanitised again where it is read back.
+ * The schema holds paragraphs, headings (1 to 3), bullet and numbered lists, quotes, code blocks,
+ * hard breaks, images and the marks above: nothing else survives a paste or `value`, and no image
+ * comes in by paste or drop (the toolbar's field and the host's `value` are its ways in). Links go
+ * through `isSafeLinkUrl` (http(s), mailto, relative) and an image's source through `isHttpUrl`
+ * (http(s) only); alignment is `center` or `end`, written as `style="text-align: …"`. That is the
+ * editor's guarantee, not the server's: the HTML a host stores has to be sanitised again where it
+ * is read back.
  */
 declare function RichTextEditor<F extends RichTextFormat = 'html'>({ format, value, defaultValue, onChange, variant, toolbar, labels: labelProps, label, description, error, required, labelTrailing, size, placeholder, readOnly, disabled, maxLength, rows, autoFocus, id, name, 'aria-label': ariaLabel, className, }: RichTextEditorProps<F>): react.JSX.Element;
 

package/dist/editor/index.d.ts

@@ -4,11 +4,18 @@ import { JSONContent } from '@tiptap/react';
 import { FieldSize } from '../index.js';
 
 /** The buttons a toolbar can hold, in the order `RICH_TEXT_ACTIONS` lists them. */
-type RichTextAction = 'bold' | 'italic' | 'strike' | 'heading' | 'bulletList' | 'orderedList' | 'blockquote' | 'code' | 'link' | 'undo' | 'redo';
+type RichTextAction = 'bold' | 'italic' | 'underline' | 'strike' | 'heading' | 'bulletList' | 'orderedList' | 'blockquote' | 'code' | 'codeBlock' | 'align' | 'link' | 'image' | 'undo' | 'redo';
 declare const RICH_TEXT_ACTIONS: readonly RichTextAction[];
+/** The items of the menus a button opens: one of them is checked. */
+type RichTextChoice = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'alignStart' | 'alignCenter' | 'alignEnd';
 
-/** Every text the editor draws itself, so a host can translate it. All optional. */
-type RichTextLabels = Partial<Record<RichTextAction, string>> & {
+type Named = RichTextAction | RichTextChoice;
+/**
+ * Every text the editor draws itself, so a host can translate it. All optional. The buttons are
+ * named by their action (`bold`, `heading`, `align`, `image`…) and the items of the heading and
+ * alignment menus by their choice (`paragraph`, `heading1`, `alignCenter`…).
+ */
+type RichTextLabels = Partial<Record<Named, string>> & {
     /** Accessible name of the toolbar. Default `Text formatting`. */
     toolbar?: string;
     /** Accessible name of the field where a link's URL is typed. Default `Link URL`. */
@@ -21,6 +28,20 @@ type RichTextLabels = Partial<Record<RichTextAction, string>> & {
     linkRemove?: string;
     /** Shown when the URL is refused. Default `Enter an http(s), mailto or relative link.` */
     linkInvalid?: string;
+    /** Accessible name of the image popover. Default `Image details`. */
+    imageDialog?: string;
+    /** Label of the field where an image's URL is typed. Default `Image URL`. */
+    imageUrl?: string;
+    /** Label of the description field, the image's `alt`. Default `Description (alt text)`. */
+    imageAlt?: string;
+    /** Label of the box that marks an image as decorative. Default `Decorative image, no description`. */
+    imageDecorative?: string;
+    /** Default `Apply`. */
+    imageApply?: string;
+    /** Shown when the URL is refused. Default `Enter an http(s) image address.` */
+    imageInvalid?: string;
+    /** Shown when an image has no description and is not marked decorative. Default `Describe the image, or mark it decorative.` */
+    imageAltRequired?: string;
 };
 
 /** What `value` and `onChange` carry: the HTML string, or the ProseMirror JSON document. */
@@ -47,7 +68,7 @@ type RichTextEditorProps<F extends RichTextFormat = 'html'> = {
      * the link for `bubble`. Ignored by `minimal`.
      */
     toolbar?: readonly RichTextAction[];
-    /** Replaces any text the editor draws itself: the buttons, their tooltips, the link field. */
+    /** Replaces any text the editor draws itself: the buttons, their tooltips and menus, the link and image fields. */
     labels?: RichTextLabels;
     label?: string;
     description?: string;
@@ -84,15 +105,20 @@ type RichTextEditorProps<F extends RichTextFormat = 'html'> = {
     className?: string;
 };
 /**
- * A formatted text field, built on Tiptap: bold, italic, strike, headings, lists, quote, code,
- * links, undo and redo, behind a toolbar, a bubble over the selection, or only keyboard shortcuts.
- * Part of the `@sckyzo/cosmos-react/editor` entry, which needs the optional peer dependencies
- * (`@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extensions`, `@tiptap/core`, `@tiptap/pm`).
+ * A formatted text field, built on Tiptap: bold, italic, underline, strike, headings, lists,
+ * quote, code and code blocks, alignment, links, images, undo and redo, behind a toolbar, a bubble
+ * over the selection, or only keyboard shortcuts. Part of the `@sckyzo/cosmos-react/editor` entry,
+ * which needs the optional peer dependencies (`@tiptap/react`, `@tiptap/starter-kit`,
+ * `@tiptap/extensions`, `@tiptap/extension-text-align`, `@tiptap/extension-image`,
+ * `@tiptap/core`, `@tiptap/pm`).
  *
- * The schema holds paragraphs, headings (2 and 3), bullet and numbered lists, quotes, hard
- * breaks and the marks above: nothing else survives a paste or `value`. Links go through
- * `isSafeLinkUrl` (http(s), mailto, relative). That is the editor's guarantee, not the server's:
- * the HTML a host stores has to be sanitised again where it is read back.
+ * The schema holds paragraphs, headings (1 to 3), bullet and numbered lists, quotes, code blocks,
+ * hard breaks, images and the marks above: nothing else survives a paste or `value`, and no image
+ * comes in by paste or drop (the toolbar's field and the host's `value` are its ways in). Links go
+ * through `isSafeLinkUrl` (http(s), mailto, relative) and an image's source through `isHttpUrl`
+ * (http(s) only); alignment is `center` or `end`, written as `style="text-align: …"`. That is the
+ * editor's guarantee, not the server's: the HTML a host stores has to be sanitised again where it
+ * is read back.
  */
 declare function RichTextEditor<F extends RichTextFormat = 'html'>({ format, value, defaultValue, onChange, variant, toolbar, labels: labelProps, label, description, error, required, labelTrailing, size, placeholder, readOnly, disabled, maxLength, rows, autoFocus, id, name, 'aria-label': ariaLabel, className, }: RichTextEditorProps<F>): react.JSX.Element;