Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the editor props’ JSDoc annotations #441

Merged
merged 1 commit into from
Apr 11, 2021
Merged

Improve the editor props’ JSDoc annotations #441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions examples/blocks/MediaBlock.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,27 @@ const OPTIONS_SPACING = 70;
const TOOLTIP_MAX_WIDTH = OPTIONS_MAX_WIDTH + OPTIONS_SPACING;

export type BlockProps = {|
/** The editorState is available for arbitrary content manipulation. */
editorState: EditorState,
/** Current entity to manage. */
entity: EntityInstance,
/** Current entityKey to manage. */
entityKey: string,
/** Whole entityType configuration, as provided to the editor. */
entityType: {
description: string,
icon: string | string[] | Node,
},
editorState: EditorState,
/** Make the whole editor read-only, except for the block. */
lockEditor: () => void,
/** Make the editor editable again. */
unlockEditor: () => void,
/** Shorthand to edit entity data. */
onEditEntity: (entityKey: string) => void,
/** Shorthand to remove an entity, and the related block. */
onRemoveEntity: (entityKey: string, blockKey: string) => void,
/** Update the editorState with arbitrary changes. */
onChange: (EditorState) => void,
onEditEntity: () => void,
onRemoveEntity: () => void,
|};

type Props = {
Expand Down
206 changes: 127 additions & 79 deletions lib/components/DraftailEditor.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,158 +37,204 @@ import type { IconProp } from "./Icon";
import DividerBlock from "../blocks/DividerBlock";

type ControlProp = {|
// Describes the control in the editor UI, concisely.
/** Describes the control in the editor UI, concisely. */
label?: string,
// Describes the control in the editor UI.
/** Describes the control in the editor UI. */
description?: string,
// Represents the control in the editor UI.
/** Represents the control in the editor UI. */
icon?: IconProp,
|};

type Props = {|
// Uncontrolled component props.
/** Initial content of the editor. Use this to edit pre-existing content. */
rawContentState: ?RawDraftContentState,
/** Called when changes occured. Use this to persist editor content. */
onSave: ?(content: null | RawDraftContentState) => void,
// Controlled component props.
/** Content of the editor, when using the editor as a controlled component. Incompatible with `rawContentState` and `onSave`. */
editorState: ?EditorState,
/** Called whenever the editor state is updated. Use this to manage the content of a controlled editor. Incompatible with `rawContentState` and `onSave`. */
onChange: ?(editorState: EditorState) => void,
/** Called when the editor receives focus. */
onFocus: ?() => void,
/** Called when the editor loses focus. */
onBlur: ?() => void,
/** Displayed when the editor is empty. Hidden if the user changes styling. */
placeholder: ?string,
/** Enable the use of horizontal rules in the editor. */
enableHorizontalRule: boolean | ControlProp,
/** Enable the use of line breaks in the editor. */
enableLineBreak: boolean | ControlProp,
/** Show undo control in the toolbar. */
showUndoControl: boolean | ControlProp,
/** Show redo control in the toolbar. */
showRedoControl: boolean | ControlProp,
/** Disable copy/paste of rich text in the editor. */
stripPastedStyles: boolean,
/** Set whether spellcheck is turned on for your editor.
* See https://draftjs.org/docs/api-reference-editor.html#spellcheck.
*/
spellCheck: boolean,
/** Set whether the editor should be rendered in readOnly mode.
* See https://draftjs.org/docs/api-reference-editor.html#readonly
*/
readOnly: boolean,
/** Optionally set the overriding text alignment for this editor.
* See https://draftjs.org/docs/api-reference-editor.html#textalignment.
*/
textAlignment: ?string,
/** Optionally set the overriding text directionality for this editor.
* See https://draftjs.org/docs/api-reference-editor.html#textdirectionality.
*/
textDirectionality: ?string,
/** Set if auto capitalization is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocapitalize-string.
*/
autoCapitalize: ?string,
/** Set if auto complete is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocomplete-string.
*/
autoComplete: ?string,
/** Set if auto correct is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocorrect-string.
*/
autoCorrect: ?string,
/** See https://draftjs.org/docs/api-reference-editor.html#aria-props. */
ariaDescribedBy: ?string,
/** List of the available block types. */
blockTypes: $ReadOnlyArray<{|
...ControlProp,
// Unique type shared between block instances.
/** Unique type shared between block instances. */
type: string,
// DOM element used to display the block within the editor area.
/** DOM element used to display the block within the editor area. */
element?: string,
|}>,
/** List of the available inline styles. */
inlineStyles: $ReadOnlyArray<{|
...ControlProp,
// Unique type shared between inline style instances.
/** Unique type shared between inline style instances. */
type: string,
// CSS properties (in JS format) to apply for styling within the editor area.
/** CSS properties (in JS format) to apply for styling within the editor area. */
style?: {},
|}>,
/** List of the available entity types. */
entityTypes: $ReadOnlyArray<{|
...ControlProp,
// Unique type shared between entity instances.
/** Unique type shared between entity instances. */
type: string,
// React component providing the UI to manage entities of this type.
/** React component providing the UI to manage entities of this type. */
source: ComponentType<{}>,
// React component to display inline entities.
/** React component to display inline entities. */
decorator?: ComponentType<{}>,
// React component to display block-level entities.
/** React component to display block-level entities. */
block?: ComponentType<{}>,
// Array of attributes the entity uses, to preserve when filtering entities on paste.
// If undefined, all entity data is preserved.
/** Array of attributes the entity uses, to preserve when filtering entities on paste.
* If undefined, all entity data is preserved.
*/
attributes?: $ReadOnlyArray<string>,
// Attribute - regex mapping, to preserve entities based on their data on paste.
// For example, { url: '^https:' } will only preserve links that point to HTTPS URLs.
/** Attribute - regex mapping, to preserve entities based on their data on paste.
* For example, { url: '^https:' } will only preserve links that point to HTTPS URLs.
*/
allowlist?: {},
// Attribute - regex mapping, to preserve entities based on their data on paste.
// For example, { url: '^https:' } will only preserve links that point to HTTPS URLs.
/** Attribute - regex mapping, to preserve entities based on their data on paste.
* For example, { url: '^https:' } will only preserve links that point to HTTPS URLs.
*/
whitelist?: {},
|}>,
/** List of active decorators. */
decorators: $ReadOnlyArray<DraftDecorator>,
// Additional React components to render in the toolbar.
/** List of extra toolbar controls. */
controls: $ReadOnlyArray<
ComponentType<{|
getEditorState: () => EditorState,
onChange: (EditorState) => void,
|}>,
>,
// List of plugins of the draft-js-plugins architecture.
/** List of plugins of the draft-js-plugins architecture. */
plugins: $ReadOnlyArray<{}>,
// Optionally override the default Draftail toolbar, removing or replacing it.
/** Optionally override the default Draftail toolbar, removing or replacing it. */
topToolbar: ?ComponentType<ToolbarProps>,
// Optionally add a custom toolbar underneath the editor, e.g. for metrics.
/** Optionally add a custom toolbar underneath the editor, e.g. for metrics. */
bottomToolbar: ?ComponentType<ToolbarProps>,
// Max level of nesting for list items. 0 = no nesting. Maximum = 10.
/** Max level of nesting for list items. 0 = no nesting. Maximum = 10. */
maxListNesting: number,
// Frequency at which to call the onSave callback (ms).
/** Frequency at which to call the onSave callback (ms). */
stateSaveInterval: number,
|};

const defaultProps = {
// Initial content of the editor. Use this to edit pre-existing content.
/** Initial content of the editor. Use this to edit pre-existing content. */
rawContentState: null,
// Called when changes occured. Use this to persist editor content.
/** Called when changes occured. Use this to persist editor content. */
onSave: null,
// Content of the editor, when using the editor as a controlled component. Incompatible with `rawContentState` and `onSave`.
/** Content of the editor, when using the editor as a controlled component. Incompatible with `rawContentState` and `onSave`. */
editorState: null,
// Called whenever the editor state is updated. Use this to manage the content of a controlled editor. Incompatible with `rawContentState` and `onSave`.
/** Called whenever the editor state is updated. Use this to manage the content of a controlled editor. Incompatible with `rawContentState` and `onSave`. */
onChange: null,
// Called when the editor receives focus.
/** Called when the editor receives focus. */
onFocus: null,
// Called when the editor loses focus.
/** Called when the editor loses focus. */
onBlur: null,
// Displayed when the editor is empty. Hidden if the user changes styling.
/** Displayed when the editor is empty. Hidden if the user changes styling. */
placeholder: null,
// Enable the use of horizontal rules in the editor.
/** Enable the use of horizontal rules in the editor. */
enableHorizontalRule: false,
// Enable the use of line breaks in the editor.
/** Enable the use of line breaks in the editor. */
enableLineBreak: false,
// Show undo control in the toolbar.
/** Show undo control in the toolbar. */
showUndoControl: false,
// Show redo control in the toolbar.
/** Show redo control in the toolbar. */
showRedoControl: false,
// Disable copy/paste of rich text in the editor.
/** Disable copy/paste of rich text in the editor. */
stripPastedStyles: true,
// Set whether spellcheck is turned on for your editor.
// See https://draftjs.org/docs/api-reference-editor.html#spellcheck.
/** Set whether spellcheck is turned on for your editor.
* See https://draftjs.org/docs/api-reference-editor.html#spellcheck.
*/
spellCheck: false,
// Set whether the editor should be rendered in readOnly mode.
// See https://draftjs.org/docs/api-reference-editor.html#readonly
/** Set whether the editor should be rendered in readOnly mode.
* See https://draftjs.org/docs/api-reference-editor.html#readonly
*/
readOnly: false,
// Optionally set the overriding text alignment for this editor.
// See https://draftjs.org/docs/api-reference-editor.html#textalignment.
/** Optionally set the overriding text alignment for this editor.
* See https://draftjs.org/docs/api-reference-editor.html#textalignment.
*/
textAlignment: null,
// Optionally set the overriding text directionality for this editor.
// See https://draftjs.org/docs/api-reference-editor.html#textdirectionality.
/** Optionally set the overriding text directionality for this editor.
* See https://draftjs.org/docs/api-reference-editor.html#textdirectionality.
*/
textDirectionality: null,
// Set if auto capitalization is turned on and how it behaves.
// See https://draftjs.org/docs/api-reference-editor.html#autocapitalize-string.
/** Set if auto capitalization is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocapitalize-string.
*/
autoCapitalize: null,
// Set if auto complete is turned on and how it behaves.
// See https://draftjs.org/docs/api-reference-editor.html#autocomplete-string.
/** Set if auto complete is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocomplete-string.
*/
autoComplete: null,
// Set if auto correct is turned on and how it behaves.
// See https://draftjs.org/docs/api-reference-editor.html#autocorrect-string.
/** Set if auto correct is turned on and how it behaves.
* See https://draftjs.org/docs/api-reference-editor.html#autocorrect-string.
*/
autoCorrect: null,
// See https://draftjs.org/docs/api-reference-editor.html#aria-props.
/** See https://draftjs.org/docs/api-reference-editor.html#aria-props. */
ariaDescribedBy: null,
// List of the available block types.
/** List of the available block types. */
blockTypes: [],
// List of the available inline styles.
/** List of the available inline styles. */
inlineStyles: [],
// List of the available entity types.
/** List of the available entity types. */
entityTypes: [],
// List of active decorators.
/** List of active decorators. */
decorators: [],
// List of extra toolbar controls.
/** List of extra toolbar controls. */
controls: [],
// List of plugins of the draft-js-plugins architecture.
/** List of plugins of the draft-js-plugins architecture. */
plugins: [],
// Optionally override the default Draftail toolbar, removing or replacing it.
/** Optionally override the default Draftail toolbar, removing or replacing it. */
topToolbar: Toolbar,
// Optionally add a custom toolbar underneath the editor, e.g. for metrics.
/** Optionally add a custom toolbar underneath the editor, e.g. for metrics. */
bottomToolbar: null,
// Max level of nesting for list items. 0 = no nesting. Maximum = 10.
/** Max level of nesting for list items. 0 = no nesting. Maximum = 10. */
maxListNesting: 1,
// Frequency at which to call the save callback (ms).
/** Frequency at which to call the onSave callback (ms). */
stateSaveInterval: 250,
};

Expand Down Expand Up @@ -766,34 +812,36 @@ class DraftailEditor extends Component<Props, State> {
component: entityType.block,
editable: false,
props: {
// The editorState is available for arbitrary content manipulation.
/** The editorState is available for arbitrary content manipulation. */
editorState,
// Current entity to manage.
/** Current entity to manage. */
entity,
// Current entityKey to manage.
/** Current entityKey to manage. */
entityKey,
// Whole entityType configuration, as provided to the editor.
/** Whole entityType configuration, as provided to the editor. */
entityType,
// Make the whole editor read-only, except for the block.
/** Make the whole editor read-only, except for the block. */
lockEditor: this.lockEditor,
// Make the editor editable again.
/** Make the editor editable again. */
unlockEditor: this.unlockEditor,
// Shorthand to edit entity data.
/** Shorthand to edit entity data. */
onEditEntity: this.onEditEntity.bind(null, entityKey),
// Shorthand to remove an entity, and the related block.
/** Shorthand to remove an entity, and the related block. */
onRemoveEntity: this.onRemoveEntity.bind(
null,
entityKey,
block.getKey(),
),
// Update the editorState with arbitrary changes.
/** Update the editorState with arbitrary changes. */
onChange: this.onChange,
},
};
}

// Imperative focus API similar to that of Draft.js.
// See https://draftjs.org/docs/advanced-topics-managing-focus.html#content.
/**
* Imperative focus API similar to that of Draft.js.
* See https://draftjs.org/docs/advanced-topics-managing-focus.html#content.
*/
/* :: focus: () => void; */
focus() {
this.editorRef.focus();
Expand All @@ -809,17 +857,17 @@ class DraftailEditor extends Component<Props, State> {

return (
<Source
// The editorState is available for arbitrary content manipulation.
/** The editorState is available for arbitrary content manipulation. */
editorState={editorState}
// Takes the updated editorState, or null if there are no changes, and focuses the editor.
/** Takes the updated editorState, or null if there are no changes, and focuses the editor. */
onComplete={this.onCompleteSource}
// Closes the source, without focusing the editor again.
/** Closes the source, without focusing the editor again. */
onClose={this.onCloseSource}
// Current entity to edit, if any.
/** Current entity to edit, if any. */
entity={sourceOptions.entity}
// Current entityKey to edit, if any.
/** Current entityKey to edit, if any. */
entityKey={sourceOptions.entityKey}
// Whole entityType configuration, as provided to the editor.
/** Whole entityType configuration, as provided to the editor. */
entityType={sourceOptions.entityType}
/>
);
Expand Down