@astryxdesign/richtext 0.4.0-canary.e144ea7 → 0.4.0-canary.faedff7

package/README.md

@@ -1,23 +1,62 @@
 # @astryxdesign/richtext
 
-Astryx rich text — a Lexical-based rich text editor and viewer.
+Astryx rich text — a Lexical-based rich text editor and read-only viewer, styled
+with Astryx design tokens.
 
-> **Status: empty scaffold.** This package is bootstrapped but does not export
-> anything yet. It will house the rich text editor and viewer that currently
-> live in `@astryxdesign/lab`; that code will move here without a fresh package
-> rollout.
+```tsx
+import {RichTextEditor, RichTextView} from '@astryxdesign/richtext';
 
-It will ship to npm **only under the `@canary` dist-tag** — there is never a
-stable (`latest`) release yet.
+<RichTextEditor label="Notes" onChange={setState} />;
+<RichTextView label="Notes" value={serializedState} />;
+```
+
+The editor is deliberately minimal and extensible: pass `nodes` and `plugins` to
+layer richer behaviour (toolbars, mentions, hover cards) on top without forking.
+`RichTextEditorToolbar` is a composable formatting toolbar that drops into the
+editor's `plugins` slot, and `markdownToEditorStateJSON` /
+`editorStateJSONToMarkdown` convert Markdown to/from serialized editor state
+headlessly (no mounted editor required). It consumes `@astryxdesign/core` theme
+tokens directly (StyleX build mirrors `@astryxdesign/lab` / `@astryxdesign/charts`).
+
+`lexical` and the `@lexical/*` packages are **optional** peer dependencies —
+install them alongside richtext to use the editor. See the RFC:
+[facebook/astryx#3899](https://github.com/facebook/astryx/issues/3899).
+
+It ships to npm **only under the `@canary` dist-tag** — there is never a stable
+(`latest`) release yet.
+
+> Note: this package is the successor to the experimental `RichTextEditor` that
+> used to live in `@astryxdesign/lab`; that code has moved here so it can be
+> canaried independently (e.g. into EPS/Nest) without a fresh package rollout.
+
+## Status
+
+Under active development. The editor, view, composable toolbar, and Markdown
+serializers are in place; API and visuals are still being refined. The goal is
+graduation to `@astryxdesign/core` after the design/API stabilizes.
+
+## Usage
 
-## Trying richtext in your own project (canary)
+Inside the monorepo (storybook/sandbox), imports resolve via pnpm workspaces:
 
-Once components land, `@astryxdesign/richtext` will be published **only** under
-the `@canary` dist-tag, so you must request that tag explicitly. There is no
-`latest` version to install.
+```tsx
+import {RichTextEditor, RichTextView} from '@astryxdesign/richtext';
+import '@astryxdesign/core/astryx.css';
+import '@astryxdesign/richtext/richtext.css';
+```
+
+Interactive examples live in the storybook app under **Lab/RichTextEditor**
+(`apps/storybook/stories/RichTextEditor.stories.tsx`).
+
+### Trying richtext in your own project (canary)
+
+`@astryxdesign/richtext` is published **only** under the `@canary` dist-tag, so
+you must request that tag explicitly. There is no `latest` version to install.
 
 ```bash
 npm install @astryxdesign/richtext@canary @astryxdesign/core@canary
+# plus the optional lexical peers you use:
+npm install lexical @lexical/react @lexical/markdown @lexical/rich-text
 ```
 
 > Canary builds track the latest commit on `main` (`0.x.y-canary.<sha>`). They
@@ -37,28 +76,9 @@ checkout only (never in git) to publish the `@canary` tag. The committed
 
 When maintainers are ready to promote richtext to a stable public release:
 
-1. Move the editor/view source from `@astryxdesign/lab` into `src/` and export
-   it from `src/index.ts`. Add the StyleX CSS build wiring (see below).
-2. Remove `"private": true` **and** the `"astryx": { "canaryOnly": true }`
+1. Remove `"private": true` **and** the `"astryx": { "canaryOnly": true }`
    marker from `package.json`.
-3. Add a changeset (`pnpm changeset`) selecting `@astryxdesign/richtext` so the
+2. Add a changeset (`pnpm changeset`) selecting `@astryxdesign/richtext` so the
    release workflow versions and publishes it to the `latest` dist-tag.
-4. The stable (`latest`) release job (`.github/workflows/release.yml`) will then
+3. The stable (`latest`) release job (`.github/workflows/release.yml`) will then
    include richtext on the next release.
-
-### Adding the StyleX CSS build (deferred until the first component)
-
-This scaffold intentionally omits the `build:css` step. `build-css.mjs` exits
-with an error ("No StyleX rules found") when a package has zero StyleX
-components, which would break CI for an empty package. When the first StyleX
-component lands:
-
-1. Register a `richtext` target in `scripts/build-css.mjs` (mirror the `lab` /
-   `charts` entries — same core token alias).
-2. Add `"build:css": "node ../../scripts/build-css.mjs --package richtext"` to
-   the `scripts` block and append `&& pnpm build:css` to the `build` script
-   (before `check-no-dev-jsx`).
-3. Add a `"./richtext.css"` entry to `exports` and add `richtext.css` under
-   `files` if needed.
-
-The babel config is already StyleX-ready, so this is a small, mechanical add.

package/dist/RichTextEditor.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @file RichTextEditor.tsx
+ * @input Uses React, useId, Lexical (lexical + @lexical/react), Field,
+ *   VisuallyHidden, useInputStatusIcon, mergeProps, design tokens
+ * @output Exports an accessibly labelled RichTextEditor component with a flush
+ *   top toolbar slot and configurable editable-surface minimum height, RichTextEditorProps,
+ *   RichTextEditorStatus, RichTextEditorStatusType, RichTextEditorSize
+ * @position Experimental (richtext) implementation; consumed by the package index.ts and
+ *   re-exported from @astryxdesign/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: This is an EXPERIMENTAL component in @astryxdesign/richtext (published only under
+ * the `@canary` dist-tag, never as stable `latest`). It is the initial landing for the
+ * OSS Lexical editor RFC; the goal is graduation to @astryxdesign/core after the
+ * Component Specification Protocol. `lexical` and `@lexical/*` are OPTIONAL peer
+ * dependencies — install them to use this component.
+ */
+import { type ReactNode } from 'react';
+import { type FieldStatusVariant } from '@astryxdesign/core/Field';
+import type { BaseProps } from '@astryxdesign/core';
+import { type SizeValue } from '@astryxdesign/core/utils';
+import { type Transformer } from '@lexical/markdown';
+export 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). Equivalent to
+     * `$convertToMarkdownString` run in a read context.
+     */
+    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'> {
+    /** 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).
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Whether the editor is disabled (non-editable, dimmed).
+     * @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;
+    /**
+     * 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).
+     * @default true
+     */
+    hasMarkdownShortcuts?: boolean;
+    /**
+     * Markdown transformers — the single source of truth for markdown behaviour.
+     * Defaults to the standard `@lexical/markdown` `TRANSFORMERS`.
+     *
+     * 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>;
+    /** 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 localize 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.'
+     */
+    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. Experimental — ships from `@astryxdesign/richtext` (canary). `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 '@astryxdesign/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: import("react").ForwardRefExoticComponent<RichTextEditorProps & import("react").RefAttributes<RichTextEditorRef>>;
+//# 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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"}