@blue-patterns/richtext 0.0.0-stage → 0.7.18

package/dist/RichTextEditor.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @file RichTextEditor.tsx
+ * @input Uses React, useId, a declared DOM boundary, Lexical (lexical + @lexical/react, composed through
+ *   LexicalExtensionComposer), Field, VisuallyHidden, useInputStatusIcon,
+ *   mergeProps, design tokens
+ * @output Exports an accessibly labelled RichTextEditor component with a flush
+ *   top toolbar slot, configurable editable-surface minimum height, and distinct
+ *   read-only and disabled states that follow prop changes, RichTextEditorProps,
+ *   RichTextEditorStatus, RichTextEditorStatusType, RichTextEditorSize
+ * @position @blue-patterns/richtext implementation; consumed by the package index.ts and
+ *   re-exported from @blue-patterns/richtext. Tested by RichTextEditor.test.tsx.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/richtext/src/RichTextEditor.doc.mjs (props table, features, implementation notes)
+ * - /packages/richtext/src/RichTextEditor.test.tsx (tests for new/changed behavior)
+ * - /packages/richtext/src/index.ts (exports if types change)
+ * - /apps/storybook/stories/RichTextEditor.stories.tsx (storybook stories)
+ *
+ * NOTE: `lexical` and `@lexical/*` are OPTIONAL peer dependencies — install them to
+ * use this component.
+ */
+import { type ReactNode, type Ref } from 'react';
+import { type FieldStatusVariant } from '@blue-patterns/core/Field';
+import type { BaseProps } from '@blue-patterns/core';
+import { type SizeValue } from '@blue-patterns/core/utils';
+import type { RichTextMarkdownExtension } from './markdownExtensions.js';
+import type { CodeLanguage } from '@blue-patterns/core/CodeBlock';
+import { type Transformer } from '@lexical/markdown';
+import { type EditorState, type Klass, type LexicalEditor, type LexicalNode } from 'lexical';
+export type RichTextEditorStatusType = 'warning' | 'error' | 'success';
+export type RichTextEditorSize = 'sm' | 'md' | 'lg';
+export interface RichTextEditorStatus {
+    /** The type of status to display. */
+    type: RichTextEditorStatusType;
+    /** Optional message to display below the editor. */
+    message?: string;
+}
+/**
+ * Imperative handle exposed via `ref`. Lets callers focus, clear, and read the
+ * editor without wiring a custom plugin. Available after mount.
+ */
+export interface RichTextEditorRef {
+    /**
+     * Move focus into the editor's editable surface. No-op when the editor is
+     * read-only or disabled.
+     */
+    focus: () => void;
+    /**
+     * Remove all content, resetting the editor to a single empty paragraph.
+     * No-op when the editor is read-only or disabled.
+     */
+    clear: () => void;
+    /** Read the current `EditorState`. Serialize with `.toJSON()` to persist. */
+    getEditorState: () => EditorState;
+    /**
+     * Serialize the current content to a Markdown string, using the same
+     * `transformers` the editor is configured with (so custom transformers
+     * layered in via the `transformers` prop are honored). Content imported
+     * with `markdownToEditorStateJSON` comes back as written: blocks nobody
+     * changed byte for byte, and only edited or added blocks in canonical
+     * Markdown.
+     */
+    getMarkdown: () => string;
+    /**
+     * Serialize the current content to an HTML string via
+     * `$generateHtmlFromNodes`. Requires a DOM (available in the browser and in
+     * jsdom-based tests). Useful for copy/paste, email, or non-Lexical consumers.
+     */
+    getHTML: () => string;
+    /**
+     * Access the underlying `LexicalEditor` instance for advanced use cases
+     * (custom commands, listeners, node transforms).
+     */
+    getEditor: () => LexicalEditor;
+}
+export interface RichTextEditorProps extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
+    /**
+     * Imperative handle for callers that manage the editor from outside. In
+     * React 19 `ref` is an ordinary prop, so it is declared here rather than
+     * supplied by a `forwardRef` wrapper.
+     */
+    ref?: Ref<RichTextEditorRef>;
+    /** Label text for the editor (always rendered for accessibility). */
+    label: string;
+    /**
+     * Whether to visually hide the label (still accessible to screen readers).
+     * @default false
+     */
+    isLabelHidden?: boolean;
+    /** Description text displayed between the label and editor. */
+    description?: string;
+    /**
+     * Whether the field is optional. Mutually exclusive with isRequired.
+     * @default false
+     */
+    isOptional?: boolean;
+    /**
+     * Whether the field is required. Mutually exclusive with isOptional.
+     * @default false
+     */
+    isRequired?: boolean;
+    /**
+     * Initial serialized editor state (a JSON string produced by
+     * `JSON.stringify(editorState.toJSON())`), used to seed the editor on mount.
+     * The editor is uncontrolled: this is read once.
+     */
+    defaultValue?: string;
+    /**
+     * Callback fired when the editor content changes. Receives the current
+     * `EditorState` and the `LexicalEditor` instance. Serialize with
+     * `editorState.toJSON()` for persistence.
+     */
+    onChange?: (editorState: EditorState, editor: LexicalEditor) => void;
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /**
+     * Whether the editor is read-only (non-editable). The content stays at full
+     * opacity, in the tab order, and announced as read-only, so people can still
+     * reach, read, and copy it. Takes effect when changed after mount.
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Whether the editor is disabled: non-editable, dimmed, out of the tab
+     * order, and announced as disabled. Its links do not navigate and are not
+     * tab stops. Wins when `isReadOnly` is also set.
+     * Takes effect when changed after mount.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Status indicator. When set, displays a colored border. If message is
+     * provided, displays a message box below the editor.
+     */
+    status?: RichTextEditorStatus;
+    /**
+     * How the status message is placed relative to the editor.
+     * - 'attached': message overlaps directly below the editor and the status
+     *   icon remains inside the editing surface
+     * - 'detached': message floats below with its own leading status icon
+     * - 'tooltip': no message box; the in-editor status icon becomes a focusable
+     *   info-tip button that reveals the message
+     * @default 'attached'
+     */
+    statusVariant?: FieldStatusVariant | 'tooltip';
+    /**
+     * Width of the field. Numbers are treated as pixels, strings are used as-is
+     * (e.g. `'100%'`).
+     */
+    width?: SizeValue;
+    /**
+     * Minimum height of the editable content surface. Numbers are treated as
+     * pixels, strings are used as CSS lengths.
+     * @default '4.5rem'
+     */
+    minHeight?: SizeValue;
+    /** Tooltip text to display in an info icon at the end of the label. */
+    labelTooltip?: string;
+    /**
+     * The size of the editor, affecting internal padding.
+     * @default 'md'
+     */
+    size?: RichTextEditorSize;
+    /**
+     * Additional Lexical nodes to register beyond the default OSS set
+     * (Heading, Quote, List, Link, Code). Use this extension point to plug in
+     * custom nodes (e.g. mentions, images) without forking the editor.
+     */
+    nodes?: ReadonlyArray<Klass<LexicalNode>>;
+    /**
+     * Toolbar content rendered edge-to-edge at the top of the field, before the
+     * padded editing surface. Pass `<RichTextEditorToolbar />` here so the
+     * toolbar stays inside the Lexical composer while retaining correct visual
+     * and keyboard order.
+     */
+    toolbar?: ReactNode;
+    /**
+     * Additional Lexical plugins to render inside the composer. Use this to
+     * compose extra behaviour (mentions, autolink, etc.) on top of the base
+     * editor. Plugins receive the editor via `useLexicalComposerContext()`.
+     */
+    plugins?: ReactNode;
+    /**
+     * Whether to enable Markdown shortcut typing (e.g. `# ` for a heading,
+     * `- ` for a list). Uses the `transformers` prop (defaults to the standard
+     * `@lexical/markdown` transformers plus GFM tables). At the start of a list
+     * item, `- `, `1. `, or `[ ] ` switches its list between bullets, numbers,
+     * and tasks, and `# ` or `> ` takes a top-level item out of its list as a
+     * heading or a quote.
+     * @default true
+     */
+    hasMarkdownShortcuts?: boolean;
+    /**
+     * Markdown transformers — the single source of truth for markdown behaviour.
+     * Defaults to the standard `@lexical/markdown` `TRANSFORMERS` plus GFM
+     * tables. A custom array replaces the default, tables included.
+     *
+     * The same array drives all three markdown operations in Lexical (see the
+     * lexical-playground reference, where one `PLAYGROUND_TRANSFORMERS` array
+     * feeds each):
+     *  - shortcut typing        — `registerMarkdownShortcuts` (wired here today)
+     *  - markdown -> state       — `$convertFromMarkdownString` (future import API)
+     *  - state -> markdown       — `$convertToMarkdownString` (future `getMarkdown`)
+     *
+     * Pass a custom array to support additional node types (e.g. custom
+     * transformers layered in via the `nodes` extension point) consistently
+     * across all three. Shortcut typing is only applied when
+     * `hasMarkdownShortcuts` is true; the array is still the intended input for
+     * the serialization APIs added in later phases.
+     */
+    transformers?: ReadonlyArray<Transformer>;
+    /**
+     * Markdown plugins whose nodes this surface draws, each adopted with
+     * `createRichTextExtension` (spec:AST-064). A plugin node renders exactly as
+     * core `Markdown` renders it, and one whose plugin is not given here shows
+     * its source. Pass the extensions the content was converted with. Create
+     * them in a client module: they hold the plugins' functions, so they are not
+     * serializable props.
+     */
+    markdownExtensions?: ReadonlyArray<RichTextMarkdownExtension>;
+    /**
+     * CodeBlock language values a fence may name, each imported on its own,
+     * such as `graphql` from `@blue-patterns/core/CodeBlock/languages/graphql`,
+     * or made with `createCodeLanguage`. Pass the same list as `Markdown`'s
+     * `codeLanguages`, so reading and editing paint and label the same
+     * languages (spec:AST-061).
+     */
+    codeLanguages?: ReadonlyArray<CodeLanguage>;
+    /** Whether to automatically focus the editor on mount. @default false */
+    hasAutoFocus?: boolean;
+    /**
+     * Screen-reader hint describing how to move focus out of the editor, since
+     * Tab is bound to indentation (press Escape, then Tab). Rendered visually
+     * hidden and referenced from the editor's `aria-describedby`. Override it
+     * to change the text, or pass an empty string to omit the hint entirely
+     * (e.g. when the host app provides its own instructions).
+     * @default 'Press Escape then Tab to move focus out of the editor.', translated for the active locale
+     */
+    tabEscapeHint?: string;
+    /**
+     * Maximum number of characters. When set, a character counter
+     * (current/max) is displayed below the editor. Like TextArea, this does
+     * NOT enforce the limit natively — the counter shows error styling when the
+     * plain-text length exceeds the limit. Count is the editor's plain-text
+     * content length.
+     */
+    maxLength?: number;
+    /**
+     * The Lexical composer namespace, used for editor identity.
+     * @default 'astryx-editor'
+     */
+    namespace?: string;
+}
+/**
+ * A WYSIWYG rich-text editor built on Lexical, styled with Astryx design
+ * tokens. Ships from `@blue-patterns/richtext`. `lexical` and `@lexical/*` are
+ * optional peer dependencies — install them to use this component.
+ *
+ * The editor is intentionally minimal and extensible: pass `toolbar`, `nodes`,
+ * and `plugins` to layer richer behaviour (formatting, mentions, hover cards)
+ * on top without forking.
+ *
+ * The forwarded `RichTextEditorRef` exposes imperative `focus()` and `clear()`
+ * methods for callers that manage the editor from outside.
+ *
+ * @example
+ * ```
+ * import {RichTextEditor, type RichTextEditorRef} from '@blue-patterns/richtext';
+ * const ref = useRef<RichTextEditorRef>(null);
+ * <RichTextEditor
+ *   ref={ref}
+ *   label="Notes"
+ *   placeholder="Write something..."
+ *   onChange={state => save(JSON.stringify(state.toJSON()))}
+ * />
+ * ```
+ */
+export declare const RichTextEditor: {
+    ({ label, isLabelHidden, description, isOptional, isRequired, defaultValue, onChange, placeholder, isReadOnly, isDisabled, status, statusVariant, width, minHeight, labelTooltip, size: sizeProp, nodes, toolbar, plugins, hasMarkdownShortcuts, transformers, markdownExtensions, codeLanguages, hasAutoFocus, tabEscapeHint: tabEscapeHintFromProps, maxLength, namespace, xstyle, className, style, ref, ...rest }: RichTextEditorProps): import("react").JSX.Element;
+    displayName: string;
+};
+//# sourceMappingURL=RichTextEditor.d.ts.map

package/dist/RichTextEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RichTextEditor.d.ts","sourceRoot":"","sources":["../src/RichTextEditor.tsx"],"names":[],"mappings":"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"}