From b7c382e2734d2b097d7f0fcdd4ddd749fd69b231 Mon Sep 17 00:00:00 2001 From: Derek Sifford Date: Mon, 22 Jul 2019 20:14:44 -0400 Subject: [PATCH] [@wordpress/block-editor] add new definitions (#37006) * [@wordpress/block-editor] add new definitions * triggering a rebuild --- .../components/alignment-toolbar.d.ts | 19 + .../components/autocomplete.d.ts | 3 + .../components/block-alignment-toolbar.d.ts | 16 + .../components/block-controls.d.ts | 14 + .../components/block-edit.d.ts | 9 + .../block-editor-keyboard-shortcuts.d.ts | 10 + .../components/block-format-controls.d.ts | 14 + .../components/block-icon.d.ts | 13 + .../components/block-inspector.d.ts | 11 + .../components/block-list.d.ts | 14 + .../components/block-mover.d.ts | 17 + .../components/block-navigation/dropdown.d.ts | 11 + .../components/block-selection-clearer.d.ts | 8 + .../components/block-settings-menu.d.ts | 11 + .../block-switcher/multi-blocks-switcher.d.ts | 10 + .../components/block-title.d.ts | 11 + .../components/block-toolbar.d.ts | 10 + .../block-vertical-alignment-toolbar.d.ts | 13 + .../components/button-block-appender.d.ts | 17 + .../components/color-palette/index.d.ts | 3 + .../color-palette/with-color-context.d.ts | 25 + .../components/colors.d.ts | 97 ++++ .../components/contrast-checker.d.ts | 16 + .../components/copy-handler.d.ts | 10 + .../components/default-block-appender.d.ts | 11 + .../components/font-sizes.d.ts | 51 ++ .../components/index.d.ts | 58 ++ .../components/inner-blocks.d.ts | 56 ++ .../components/inserter.d.ts | 15 + .../inspector-advanced-controls.d.ts | 14 + .../components/inspector-controls.d.ts | 14 + .../components/media-placeholder.d.ts | 101 ++++ .../components/media-upload/check.d.ts | 11 + .../components/media-upload/index.d.ts | 38 ++ .../multi-select-scroll-into-view.d.ts | 10 + .../components/navigable-toolbar.d.ts | 11 + .../components/observe-typing.d.ts | 10 + .../components/panel-color-settings.d.ts | 14 + .../components/plain-text.d.ts | 22 + .../preserve-scroll-in-reorder.d.ts | 10 + .../components/provider.d.ts | 48 ++ .../components/rich-text.d.ts | 100 ++++ .../components/skip-to-selected-block.d.ts | 10 + .../components/url-input/button.d.ts | 16 + .../components/url-input/index.d.ts | 51 ++ .../components/url-popover.d.ts | 17 + .../components/warning.d.ts | 16 + .../components/writing-flow.d.ts | 10 + types/wordpress__block-editor/index.d.ts | 213 +++++++ types/wordpress__block-editor/package.json | 6 + .../store/actions.d.ts | 288 ++++++++++ .../store/defaults.d.ts | 3 + .../wordpress__block-editor/store/index.d.ts | 7 + .../store/selectors.d.ts | 513 +++++++++++++++++ types/wordpress__block-editor/tsconfig.json | 82 +++ types/wordpress__block-editor/tslint.json | 1 + .../wordpress__block-editor/utils/index.d.ts | 7 + .../wordpress__block-editor-tests.tsx | 519 ++++++++++++++++++ 58 files changed, 2735 insertions(+) create mode 100644 types/wordpress__block-editor/components/alignment-toolbar.d.ts create mode 100644 types/wordpress__block-editor/components/autocomplete.d.ts create mode 100644 types/wordpress__block-editor/components/block-alignment-toolbar.d.ts create mode 100644 types/wordpress__block-editor/components/block-controls.d.ts create mode 100644 types/wordpress__block-editor/components/block-edit.d.ts create mode 100644 types/wordpress__block-editor/components/block-editor-keyboard-shortcuts.d.ts create mode 100644 types/wordpress__block-editor/components/block-format-controls.d.ts create mode 100644 types/wordpress__block-editor/components/block-icon.d.ts create mode 100644 types/wordpress__block-editor/components/block-inspector.d.ts create mode 100644 types/wordpress__block-editor/components/block-list.d.ts create mode 100644 types/wordpress__block-editor/components/block-mover.d.ts create mode 100644 types/wordpress__block-editor/components/block-navigation/dropdown.d.ts create mode 100644 types/wordpress__block-editor/components/block-selection-clearer.d.ts create mode 100644 types/wordpress__block-editor/components/block-settings-menu.d.ts create mode 100644 types/wordpress__block-editor/components/block-switcher/multi-blocks-switcher.d.ts create mode 100644 types/wordpress__block-editor/components/block-title.d.ts create mode 100644 types/wordpress__block-editor/components/block-toolbar.d.ts create mode 100644 types/wordpress__block-editor/components/block-vertical-alignment-toolbar.d.ts create mode 100644 types/wordpress__block-editor/components/button-block-appender.d.ts create mode 100644 types/wordpress__block-editor/components/color-palette/index.d.ts create mode 100644 types/wordpress__block-editor/components/color-palette/with-color-context.d.ts create mode 100644 types/wordpress__block-editor/components/colors.d.ts create mode 100644 types/wordpress__block-editor/components/contrast-checker.d.ts create mode 100644 types/wordpress__block-editor/components/copy-handler.d.ts create mode 100644 types/wordpress__block-editor/components/default-block-appender.d.ts create mode 100644 types/wordpress__block-editor/components/font-sizes.d.ts create mode 100644 types/wordpress__block-editor/components/index.d.ts create mode 100644 types/wordpress__block-editor/components/inner-blocks.d.ts create mode 100644 types/wordpress__block-editor/components/inserter.d.ts create mode 100644 types/wordpress__block-editor/components/inspector-advanced-controls.d.ts create mode 100644 types/wordpress__block-editor/components/inspector-controls.d.ts create mode 100644 types/wordpress__block-editor/components/media-placeholder.d.ts create mode 100644 types/wordpress__block-editor/components/media-upload/check.d.ts create mode 100644 types/wordpress__block-editor/components/media-upload/index.d.ts create mode 100644 types/wordpress__block-editor/components/multi-select-scroll-into-view.d.ts create mode 100644 types/wordpress__block-editor/components/navigable-toolbar.d.ts create mode 100644 types/wordpress__block-editor/components/observe-typing.d.ts create mode 100644 types/wordpress__block-editor/components/panel-color-settings.d.ts create mode 100644 types/wordpress__block-editor/components/plain-text.d.ts create mode 100644 types/wordpress__block-editor/components/preserve-scroll-in-reorder.d.ts create mode 100644 types/wordpress__block-editor/components/provider.d.ts create mode 100644 types/wordpress__block-editor/components/rich-text.d.ts create mode 100644 types/wordpress__block-editor/components/skip-to-selected-block.d.ts create mode 100644 types/wordpress__block-editor/components/url-input/button.d.ts create mode 100644 types/wordpress__block-editor/components/url-input/index.d.ts create mode 100644 types/wordpress__block-editor/components/url-popover.d.ts create mode 100644 types/wordpress__block-editor/components/warning.d.ts create mode 100644 types/wordpress__block-editor/components/writing-flow.d.ts create mode 100644 types/wordpress__block-editor/index.d.ts create mode 100644 types/wordpress__block-editor/package.json create mode 100644 types/wordpress__block-editor/store/actions.d.ts create mode 100644 types/wordpress__block-editor/store/defaults.d.ts create mode 100644 types/wordpress__block-editor/store/index.d.ts create mode 100644 types/wordpress__block-editor/store/selectors.d.ts create mode 100644 types/wordpress__block-editor/tsconfig.json create mode 100644 types/wordpress__block-editor/tslint.json create mode 100644 types/wordpress__block-editor/utils/index.d.ts create mode 100644 types/wordpress__block-editor/wordpress__block-editor-tests.tsx diff --git a/types/wordpress__block-editor/components/alignment-toolbar.d.ts b/types/wordpress__block-editor/components/alignment-toolbar.d.ts new file mode 100644 index 0000000000..9f8561635a --- /dev/null +++ b/types/wordpress__block-editor/components/alignment-toolbar.d.ts @@ -0,0 +1,19 @@ +import { Dashicon } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +declare namespace AlignmentToolbar { + interface Props { + alignmentControls?: Array<{ + align: string; + icon: Dashicon.Icon | JSX.Element; + title: string; + }>; + children?: never; + value: string; + onChange(newValue?: string): void; + } +} + +declare const AlignmentToolbar: ComponentType; + +export default AlignmentToolbar; diff --git a/types/wordpress__block-editor/components/autocomplete.d.ts b/types/wordpress__block-editor/components/autocomplete.d.ts new file mode 100644 index 0000000000..8f4c0f5d76 --- /dev/null +++ b/types/wordpress__block-editor/components/autocomplete.d.ts @@ -0,0 +1,3 @@ +import { Autocomplete } from '@wordpress/components'; + +export default Autocomplete; diff --git a/types/wordpress__block-editor/components/block-alignment-toolbar.d.ts b/types/wordpress__block-editor/components/block-alignment-toolbar.d.ts new file mode 100644 index 0000000000..4d1f7f7256 --- /dev/null +++ b/types/wordpress__block-editor/components/block-alignment-toolbar.d.ts @@ -0,0 +1,16 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockAlignmentToolbar { + type Control = 'center' | 'full' | 'left' | 'right' | 'wide'; + interface Props { + children?: never; + controls?: Control[]; + isCollapsed?: boolean; + onChange(newValue: Control | undefined): void; + value: Control; + } +} + +declare const BlockAlignmentToolbar: ComponentType; + +export default BlockAlignmentToolbar; diff --git a/types/wordpress__block-editor/components/block-controls.d.ts b/types/wordpress__block-editor/components/block-controls.d.ts new file mode 100644 index 0000000000..1f95517650 --- /dev/null +++ b/types/wordpress__block-editor/components/block-controls.d.ts @@ -0,0 +1,14 @@ +import { Toolbar, Slot } from '@wordpress/components'; +import { FC, ReactNode } from '@wordpress/element'; + +declare namespace BlockControls { + interface Props extends Pick { + children: ReactNode; + } +} +declare const BlockControls: { + (props: BlockControls.Props): JSX.Element; + Slot: FC>; +}; + +export default BlockControls; diff --git a/types/wordpress__block-editor/components/block-edit.d.ts b/types/wordpress__block-editor/components/block-edit.d.ts new file mode 100644 index 0000000000..20bc0d8a45 --- /dev/null +++ b/types/wordpress__block-editor/components/block-edit.d.ts @@ -0,0 +1,9 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockEdit { + // It is extremely unclear what props this component accepts. + type Props = any; +} +declare const BlockEdit: ComponentType; + +export default BlockEdit; diff --git a/types/wordpress__block-editor/components/block-editor-keyboard-shortcuts.d.ts b/types/wordpress__block-editor/components/block-editor-keyboard-shortcuts.d.ts new file mode 100644 index 0000000000..d0dde6226c --- /dev/null +++ b/types/wordpress__block-editor/components/block-editor-keyboard-shortcuts.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockEditorKeyboardShortcuts { + interface Props { + children?: never; + } +} +declare const BlockEditorKeyboardShortcuts: ComponentType; + +export default BlockEditorKeyboardShortcuts; diff --git a/types/wordpress__block-editor/components/block-format-controls.d.ts b/types/wordpress__block-editor/components/block-format-controls.d.ts new file mode 100644 index 0000000000..e2b3ed48d9 --- /dev/null +++ b/types/wordpress__block-editor/components/block-format-controls.d.ts @@ -0,0 +1,14 @@ +import { Slot } from '@wordpress/components'; +import { FC, ReactNode } from '@wordpress/element'; + +declare namespace BlockFormatControls { + interface Props { + children: ReactNode; + } +} +declare const BlockFormatControls: { + (props: BlockFormatControls.Props): JSX.Element; + Slot: FC>; +}; + +export default BlockFormatControls; diff --git a/types/wordpress__block-editor/components/block-icon.d.ts b/types/wordpress__block-editor/components/block-icon.d.ts new file mode 100644 index 0000000000..2bd844efa6 --- /dev/null +++ b/types/wordpress__block-editor/components/block-icon.d.ts @@ -0,0 +1,13 @@ +import { Icon } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockIcon { + interface Props { + className?: string; + icon: Icon.Props['icon']; + showColors?: boolean; + } +} +declare const BlockIcon: ComponentType; + +export default BlockIcon; diff --git a/types/wordpress__block-editor/components/block-inspector.d.ts b/types/wordpress__block-editor/components/block-inspector.d.ts new file mode 100644 index 0000000000..ee9f0a8a52 --- /dev/null +++ b/types/wordpress__block-editor/components/block-inspector.d.ts @@ -0,0 +1,11 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockInspector { + interface Props { + children?: never; + showNoBlockSelectedMessage?: boolean; + } +} +declare const BlockInspector: ComponentType; + +export default BlockInspector; diff --git a/types/wordpress__block-editor/components/block-list.d.ts b/types/wordpress__block-editor/components/block-list.d.ts new file mode 100644 index 0000000000..5516da254f --- /dev/null +++ b/types/wordpress__block-editor/components/block-list.d.ts @@ -0,0 +1,14 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockList { + interface Props { + /** + * A 'render prop' function that can be used to customize the block's appender. + */ + renderAppender?(): JSX.Element; + rootClientId?: string; + } +} +declare const BlockList: ComponentType; + +export default BlockList; diff --git a/types/wordpress__block-editor/components/block-mover.d.ts b/types/wordpress__block-editor/components/block-mover.d.ts new file mode 100644 index 0000000000..0d95725861 --- /dev/null +++ b/types/wordpress__block-editor/components/block-mover.d.ts @@ -0,0 +1,17 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockMover { + interface Props { + blockElementId?: string; + clientIds: string[]; + children?: never; + instanceId?: string; + isDraggable?: boolean; + isHidden?: boolean; + onDragEnd?(): void; + onDragStart?(): void; + } +} +declare const BlockMover: ComponentType; + +export default BlockMover; diff --git a/types/wordpress__block-editor/components/block-navigation/dropdown.d.ts b/types/wordpress__block-editor/components/block-navigation/dropdown.d.ts new file mode 100644 index 0000000000..57d8bd790a --- /dev/null +++ b/types/wordpress__block-editor/components/block-navigation/dropdown.d.ts @@ -0,0 +1,11 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockNavigationDropdown { + interface Props { + children?: never; + isDisabled?: boolean; + } +} +declare const BlockNavigationDropdown: ComponentType; + +export default BlockNavigationDropdown; diff --git a/types/wordpress__block-editor/components/block-selection-clearer.d.ts b/types/wordpress__block-editor/components/block-selection-clearer.d.ts new file mode 100644 index 0000000000..2d93a979b3 --- /dev/null +++ b/types/wordpress__block-editor/components/block-selection-clearer.d.ts @@ -0,0 +1,8 @@ +import { ComponentType, HTMLProps } from '@wordpress/element'; + +declare namespace BlockSelectionClearer { + type Props = HTMLProps; +} +declare const BlockSelectionClearer: ComponentType; + +export default BlockSelectionClearer; diff --git a/types/wordpress__block-editor/components/block-settings-menu.d.ts b/types/wordpress__block-editor/components/block-settings-menu.d.ts new file mode 100644 index 0000000000..949c2d3db1 --- /dev/null +++ b/types/wordpress__block-editor/components/block-settings-menu.d.ts @@ -0,0 +1,11 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockSettingsMenu { + interface Props { + children?: never; + clientIds: string[]; + } +} +declare const BlockSettingsMenu: ComponentType; + +export default BlockSettingsMenu; diff --git a/types/wordpress__block-editor/components/block-switcher/multi-blocks-switcher.d.ts b/types/wordpress__block-editor/components/block-switcher/multi-blocks-switcher.d.ts new file mode 100644 index 0000000000..756f8e5479 --- /dev/null +++ b/types/wordpress__block-editor/components/block-switcher/multi-blocks-switcher.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace MultiBlocksSwitcher { + interface Props { + children?: never; + } +} +declare const MultiBlocksSwitcher: ComponentType; + +export default MultiBlocksSwitcher; diff --git a/types/wordpress__block-editor/components/block-title.d.ts b/types/wordpress__block-editor/components/block-title.d.ts new file mode 100644 index 0000000000..9654ce6c4d --- /dev/null +++ b/types/wordpress__block-editor/components/block-title.d.ts @@ -0,0 +1,11 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockTitle { + interface Props { + children?: never; + clientId: string; + } +} +declare const BlockTitle: ComponentType; + +export default BlockTitle; diff --git a/types/wordpress__block-editor/components/block-toolbar.d.ts b/types/wordpress__block-editor/components/block-toolbar.d.ts new file mode 100644 index 0000000000..6597fd4f86 --- /dev/null +++ b/types/wordpress__block-editor/components/block-toolbar.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockToolbar { + interface Props { + children?: never; + } +} +declare const BlockToolbar: ComponentType; + +export default BlockToolbar; diff --git a/types/wordpress__block-editor/components/block-vertical-alignment-toolbar.d.ts b/types/wordpress__block-editor/components/block-vertical-alignment-toolbar.d.ts new file mode 100644 index 0000000000..a6feef0fc2 --- /dev/null +++ b/types/wordpress__block-editor/components/block-vertical-alignment-toolbar.d.ts @@ -0,0 +1,13 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace BlockVerticalAlignmentToolbar { + type Value = 'bottom' | 'center' | 'top' | undefined; + interface Props { + children?: never; + value: Value; + onChange(newValue: Value): void; + } +} +declare const BlockVerticalAlignmentToolbar: ComponentType; + +export default BlockVerticalAlignmentToolbar; diff --git a/types/wordpress__block-editor/components/button-block-appender.d.ts b/types/wordpress__block-editor/components/button-block-appender.d.ts new file mode 100644 index 0000000000..b1f50b7f37 --- /dev/null +++ b/types/wordpress__block-editor/components/button-block-appender.d.ts @@ -0,0 +1,17 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace ButtonBlockAppender { + interface Props { + children?: never; + className?: string; + /** + * The `clientId` of the Block from who's root new Blocks should be inserted. This prop is + * required by the block `Inserter` component. Typically this is the `clientID` of the Block + * where the prop is being rendered. + */ + rootClientId: string; + } +} +declare const ButtonBlockAppender: ComponentType; + +export default ButtonBlockAppender; diff --git a/types/wordpress__block-editor/components/color-palette/index.d.ts b/types/wordpress__block-editor/components/color-palette/index.d.ts new file mode 100644 index 0000000000..f8b84f1348 --- /dev/null +++ b/types/wordpress__block-editor/components/color-palette/index.d.ts @@ -0,0 +1,3 @@ +import { ColorPalette } from '@wordpress/components'; + +export default ColorPalette; diff --git a/types/wordpress__block-editor/components/color-palette/with-color-context.d.ts b/types/wordpress__block-editor/components/color-palette/with-color-context.d.ts new file mode 100644 index 0000000000..4012eba331 --- /dev/null +++ b/types/wordpress__block-editor/components/color-palette/with-color-context.d.ts @@ -0,0 +1,25 @@ +// tslint:disable:no-unnecessary-generics +import { ComponentType } from '@wordpress/element'; + +import { EditorColor } from '../../'; + +declare namespace withColorContext { + interface Props { + colors: EditorColor[]; + disableCustomColors: boolean; + hasColorsToChoose: boolean; + } +} + +// prettier-ignore +declare function withColorContext< + ProvidedProps extends Partial, + OwnProps extends any, + T extends ComponentType +>(component: T): + T extends ComponentType ? ComponentType< + Omit & + Omit> : + never; + +export default withColorContext; diff --git a/types/wordpress__block-editor/components/colors.d.ts b/types/wordpress__block-editor/components/colors.d.ts new file mode 100644 index 0000000000..9a16ed20ad --- /dev/null +++ b/types/wordpress__block-editor/components/colors.d.ts @@ -0,0 +1,97 @@ +// tslint:disable:no-unnecessary-generics +import { ComponentType } from '@wordpress/element'; + +import { EditorColor } from '../'; + +/** + * A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic + * for class generation color value, retrieval and color attribute setting. + * + * @remarks + * Use this higher-order component to work with a custom set of colors. + * + * NOTE: this function is poorly designed and is thereby not able to have strong types associated. + * + * @example + * ```jsx + * const CUSTOM_COLORS = [ { name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' } ]; + * const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS ); + * // ... + * export default compose( + * withCustomColors( 'backgroundColor', 'borderColor' ), + * MyColorfulComponent, + * ); + * ``` + */ +export function createCustomColorsHOC( + colorsArray: EditorColor[] +): (...colorNames: T) => (component: ComponentType) => ComponentType; + +/** + * Returns a class based on the context a color is being used and its slug. + * + * @param colorContextName - Context/place where color is being used e.g: background, text etc... + * @param colorSlug - Slug of the color. + */ +export function getColorClassName(colorContextName: string, colorSlug: string): string; +export function getColorClassName( + colorContextName: string | undefined, + colorSlug: string | undefined +): string | undefined; + +/** + * Provided an array of color objects as set by the theme or by the editor defaults, and the values + * of the defined color or custom color returns a color object describing the color. + * + * @remarks + * If `definedColor` is passed and the name is found in `colors`, the color object exactly as + * set by the theme or editor defaults is returned. Otherwise, an object that just sets the color + * is defined. + * + * @param colors - Array of color objects as set by the theme or by the editor defaults. + * @param definedColor - A string containing the color slug. + * @param customColor - A string containing the customColor value. + */ +export function getColorObjectByAttributeValues( + colors: EditorColor[], + definedColor: string | undefined, + customColor: string +): EditorColor | Pick; + +/** + * Provided an array of color objects as set by the theme or by the editor defaults, and a color + * value, returns the color object matching that value or undefined. + * + * @param colors - Array of color objects as set by the theme or by the editor defaults. + * @param colorValue - A string containing the color value. + */ +export function getColorObjectByColorValue(colors: EditorColor[], colorValue: string | undefined): EditorColor | undefined; + +/** + * A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting. + * + * @remarks + * For use with the default editor/theme color palette. + * + * NOTE: this function is poorly designed and is thereby not able to have strong types associated. + * + * @example + * ```jsx + * export default compose( + * withColors( 'backgroundColor', { textColor: 'color' } ), + * MyColorfulComponent, + * ); + * ``` + * + * @param colorTypes - The arguments can be strings or objects. If the argument is an object, it + * should contain the color attribute name as key and the color context as + * value. If the argument is a string the value should be the color attribute + * name, the color context is computed by applying a kebab case transform to the + * value. Color context represents the context/place where the color is going + * to be used. The class name of the color is generated using 'has' followed by + * the color name and ending with the color context all in kebab case e.g: + * has-green-background-color. + */ +export function withColors( + ...colorTypes: Array> +): (component: ComponentType) => ComponentType; diff --git a/types/wordpress__block-editor/components/contrast-checker.d.ts b/types/wordpress__block-editor/components/contrast-checker.d.ts new file mode 100644 index 0000000000..4bbdcd27f6 --- /dev/null +++ b/types/wordpress__block-editor/components/contrast-checker.d.ts @@ -0,0 +1,16 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace ContrastChecker { + interface Props { + backgroundColor?: string; + children?: never; + fallbackBackgroundColor?: string; + fallbackTextColor?: string; + fontSize?: number; + isLargeText?: boolean; + textColor?: string; + } +} +declare const ContrastChecker: ComponentType; + +export default ContrastChecker; diff --git a/types/wordpress__block-editor/components/copy-handler.d.ts b/types/wordpress__block-editor/components/copy-handler.d.ts new file mode 100644 index 0000000000..f663c192f6 --- /dev/null +++ b/types/wordpress__block-editor/components/copy-handler.d.ts @@ -0,0 +1,10 @@ +import { ComponentType, ReactNode } from '@wordpress/element'; + +declare namespace CopyHandler { + interface Props { + children: ReactNode; + } +} +declare const CopyHandler: ComponentType; + +export default CopyHandler; diff --git a/types/wordpress__block-editor/components/default-block-appender.d.ts b/types/wordpress__block-editor/components/default-block-appender.d.ts new file mode 100644 index 0000000000..c824447174 --- /dev/null +++ b/types/wordpress__block-editor/components/default-block-appender.d.ts @@ -0,0 +1,11 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace DefaultBlockAppender { + interface Props { + lastBlockClientId: string; + rootClientId: string; + } +} +declare const DefaultBlockAppender: ComponentType; + +export default DefaultBlockAppender; diff --git a/types/wordpress__block-editor/components/font-sizes.d.ts b/types/wordpress__block-editor/components/font-sizes.d.ts new file mode 100644 index 0000000000..c5a744db0a --- /dev/null +++ b/types/wordpress__block-editor/components/font-sizes.d.ts @@ -0,0 +1,51 @@ +import { FontSizePicker as FSP } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +import { EditorFontSize } from '../'; + +export namespace FontSizePicker { + type Props = Omit; +} +export const FontSizePicker: ComponentType; + +/** + * Returns the font size object based on an array of named font sizes and the `namedFontSize` and + * `customFontSize` values. If `namedFontSize` is `undefined` or not found in `fontSizes` an object with + * just the size value based on `customFontSize` is returned. + * + * @remarks + * If `fontSizeAttribute` is set and an equal slug is found in `fontSizes` it returns the font + * size object for that slug. Otherwise, an object with just the `size` value based on `customFontSize` + * is returned. + * + * @param fontSizes - Array of font size objects containing at least the "name" and "size" values as properties. + * @param fontSizeAttribute - Content of the font size attribute (slug). + * @param customFontSizeAttribute - Contents of the custom font size attribute (value). + */ +export function getFontSize( + fontSizes: EditorFontSize[], + fontSizeAttribute: string | undefined, + customFontSizeAttribute: number +): Partial & Pick; + +/** + * Returns a class based on fontSizeName. + * + * @remarks + * Value returned is generated by appending 'has-' followed by fontSizeSlug in kebab-case and ending + * with '-font-size'. + * + * @param fontSizeSlug - Slug of the fontSize. + */ +export function getFontSizeClass(fontSizeSlug: string): string; + +/** + * Higher-order component, which handles font size logic for class generation, + * font size value retrieval, and font size change handling. + * + * @remarks + * NOTE: this function is poorly designed and is thereby not able to have strong types associated. + * + * @param attributeNames - 1 or more font size attributes + */ +export function withFontSizes(...attributeNames: string[]): (component: ComponentType) => ComponentType; diff --git a/types/wordpress__block-editor/components/index.d.ts b/types/wordpress__block-editor/components/index.d.ts new file mode 100644 index 0000000000..a53d735f07 --- /dev/null +++ b/types/wordpress__block-editor/components/index.d.ts @@ -0,0 +1,58 @@ +/** + * Block Creation Components + */ +export * from './colors'; +export * from './font-sizes'; +export { default as AlignmentToolbar } from './alignment-toolbar'; +export { default as Autocomplete } from './autocomplete'; +export { default as BlockAlignmentToolbar } from './block-alignment-toolbar'; +export { default as BlockControls } from './block-controls'; +export { default as BlockEdit } from './block-edit'; +export { default as BlockFormatControls } from './block-format-controls'; +export { default as BlockIcon } from './block-icon'; +export { default as BlockNavigationDropdown } from './block-navigation/dropdown'; +export { default as BlockVerticalAlignmentToolbar } from './block-vertical-alignment-toolbar'; +export { default as ButtonBlockerAppender } from './button-block-appender'; +export { default as ColorPalette } from './color-palette'; +export { default as ContrastChecker } from './contrast-checker'; +export { default as InnerBlocks } from './inner-blocks'; +export { default as InspectorAdvancedControls } from './inspector-advanced-controls'; +export { default as InspectorControls } from './inspector-controls'; +export { default as MediaPlaceholder } from './media-placeholder'; +export { default as MediaUpload } from './media-upload'; +export { default as MediaUploadCheck } from './media-upload/check'; +export { default as PanelColorSettings } from './panel-color-settings'; +export { default as PlainText } from './plain-text'; +export { default as RichText, RichTextShortcut, RichTextToolbarButton } from './rich-text'; +export { default as URLInput } from './url-input'; +export { default as URLInputButton } from './url-input/button'; +export { default as URLPopover } from './url-popover'; +export { default as withColorContext } from './color-palette/with-color-context'; + +/** + * Content Related Components + */ +export { default as BlockEditorKeyboardShortcuts } from './block-editor-keyboard-shortcuts'; +export { default as BlockInspector } from './block-inspector'; +export { default as BlockList } from './block-list'; +export { default as BlockMover } from './block-mover'; +export { default as BlockSelectionClearer } from './block-selection-clearer'; +export { default as BlockSettingsMenu } from './block-settings-menu'; +export { default as BlockTitle } from './block-title'; +export { default as BlockToolbar } from './block-toolbar'; +export { default as CopyHandler } from './copy-handler'; +export { default as DefaultBlockAppender } from './default-block-appender'; +export { default as Inserter } from './inserter'; +export { default as MultiBlocksSwitcher } from './block-switcher/multi-blocks-switcher'; +export { default as MultiSelectScrollIntoView } from './multi-select-scroll-into-view'; +export { default as NavigableToolbar } from './navigable-toolbar'; +export { default as ObserveTyping } from './observe-typing'; +export { default as PreserveScrollInReorder } from './preserve-scroll-in-reorder'; +export { default as SkipToSelectedBlock } from './skip-to-selected-block'; +export { default as Warning } from './warning'; +export { default as WritingFlow } from './writing-flow'; + +/* + * State Related Components + */ +export { default as BlockEditorProvider } from './provider'; diff --git a/types/wordpress__block-editor/components/inner-blocks.d.ts b/types/wordpress__block-editor/components/inner-blocks.d.ts new file mode 100644 index 0000000000..acb4422842 --- /dev/null +++ b/types/wordpress__block-editor/components/inner-blocks.d.ts @@ -0,0 +1,56 @@ +import { TemplateArray } from '@wordpress/blocks'; +import { ComponentType } from '@wordpress/element'; + +import { EditorTemplateLock } from '../'; + +declare namespace InnerBlocks { + interface Props { + allowedBlocks?: string[]; + /** + * A 'render prop' function that can be used to customize the block's appender. + */ + renderAppender?: ComponentType; + /** + * The template is defined as a list of block items. Such blocks can have predefined + * attributes, placeholder, content, etc. Block templates allow specifying a default initial + * state for an InnerBlocks area. + * + * See {@link https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-templates.md } + */ + template?: TemplateArray; + /** + * If `true` when child blocks in the template are inserted the selection is updated. + * If `false` the selection should not be updated when child blocks specified in the template are inserted. + * @defaultValue true + */ + templateInsertUpdatesSelection?: boolean; + /** + * Template locking allows locking the `InnerBlocks` area for the current template. + * + * - `'all'` — prevents all operations. It is not possible to insert new blocks. Move existing blocks or delete them. + * - `'insert'` — prevents inserting or removing blocks, but allows moving existing ones. + * - `false` — prevents locking from being applied to an `InnerBlocks` area even if a parent block contains locking. + * + * If locking is not set in an `InnerBlocks` area: the locking of the parent `InnerBlocks` area is used. + * + * If the block is a top level block: the locking of the Custom Post Type is used. + */ + templateLock?: EditorTemplateLock; + } +} +declare const InnerBlocks: { + (props: InnerBlocks.Props): JSX.Element; + Content: ComponentType<{ children?: never }>; + /** + * display a `+` (plus) icon button that, when clicked, displays the block picker menu. No + * default Block is inserted. + */ + ButtonBlockerAppender: ComponentType<{ children?: never }>; + /** + * display the default block appender as set by `wp.blocks.setDefaultBlockName`. Typically this + * is the `paragraph` block. + */ + DefaultBlockAppender: ComponentType<{ children?: never }>; +}; + +export default InnerBlocks; diff --git a/types/wordpress__block-editor/components/inserter.d.ts b/types/wordpress__block-editor/components/inserter.d.ts new file mode 100644 index 0000000000..816910a1cc --- /dev/null +++ b/types/wordpress__block-editor/components/inserter.d.ts @@ -0,0 +1,15 @@ +import { Dropdown } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +declare namespace Inserter { + interface Props extends Partial> { + clientId?: string; + disabled?: boolean; + isAppender?: boolean; + onToggle?(isOpen: boolean): void; + rootClientId?: string; + } +} +declare const Inserter: ComponentType; + +export default Inserter; diff --git a/types/wordpress__block-editor/components/inspector-advanced-controls.d.ts b/types/wordpress__block-editor/components/inspector-advanced-controls.d.ts new file mode 100644 index 0000000000..0a80c77345 --- /dev/null +++ b/types/wordpress__block-editor/components/inspector-advanced-controls.d.ts @@ -0,0 +1,14 @@ +import { Slot } from '@wordpress/components'; +import { FC, ReactNode } from '@wordpress/element'; + +declare namespace InspectorAdvancedControls { + interface Props { + children: ReactNode; + } +} +declare const InspectorAdvancedControls: { + (props: InspectorAdvancedControls.Props): JSX.Element; + Slot: FC>; +}; + +export default InspectorAdvancedControls; diff --git a/types/wordpress__block-editor/components/inspector-controls.d.ts b/types/wordpress__block-editor/components/inspector-controls.d.ts new file mode 100644 index 0000000000..0247b72b1f --- /dev/null +++ b/types/wordpress__block-editor/components/inspector-controls.d.ts @@ -0,0 +1,14 @@ +import { Slot } from '@wordpress/components'; +import { FC, ReactNode } from '@wordpress/element'; + +declare namespace InspectorControls { + interface Props { + children: ReactNode; + } +} +declare const InspectorControls: { + (props: InspectorControls.Props): JSX.Element; + Slot: FC>; +}; + +export default InspectorControls; diff --git a/types/wordpress__block-editor/components/media-placeholder.d.ts b/types/wordpress__block-editor/components/media-placeholder.d.ts new file mode 100644 index 0000000000..149b9f8d82 --- /dev/null +++ b/types/wordpress__block-editor/components/media-placeholder.d.ts @@ -0,0 +1,101 @@ +// tslint:disable:no-unnecessary-generics +import { Dashicon, DropZone } from '@wordpress/components'; +import { ComponentType, MouseEventHandler } from '@wordpress/element'; + +declare namespace MediaPlaceholder { + interface Props extends Pick { + /** + * A string passed to `FormFileUpload` that tells the browser which file types can be uploaded + * to the upload window the browser use e.g: `image#<{(|,video#<{(|`. + * + * This property is similar to the `allowedTypes` property. The difference is the format + * and the fact that this property affects the behavior of `FormFileUpload` while + * `allowedTypes` affects the behavior `MediaUpload`. + * + * See: {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers } + */ + accept?: string; + /** + * If `true`, and if `gallery === true` the gallery media modal opens directly in the media + * library where the user can add additional images. When uploading/selecting files on the + * placeholder, the placeholder appends the files to the existing files list. If `false` the + * gallery media modal opens in the edit mode where the user can edit existing images, by + * reordering them, remove them, or change their attributes. When uploading/selecting files + * on the placeholder the files replace the existing files list. + * @defaultValue false + */ + addToGallery?: boolean; + /** + * Array with the types of the media to upload/select from the media library. + * + * @remarks + * Each type is a string that can contain the general mime type e.g: `image`, `audio`, + * `text`, or the complete mime type e.g: `audio/mpeg`, `image/gif`. + * + * If allowedTypes is unset all mime types should be allowed. This property is similar to + * the `accept` property. The difference is the format and the fact that this property + * affects the behavior of `MediaUpload` while `accept` affects the behavior + * `FormFileUpload`. + */ + allowedTypes?: string[]; + children?: never; + className?: string; + /** Undocumented. */ + dropZoneUIOnly?: boolean; + /** + * Icon to display left of the title. + */ + icon?: Dashicon.Icon | JSX.Element; + /** + * If `true`, the property changes the look of the placeholder to be adequate to scenarios + * where new files are added to an already existing set of files, e.g., adding files to a + * gallery. + * + * If `false` the default placeholder style is used. + * + * @defaultValue false + */ + isAppender?: boolean; + /** + * An object that can contain a `title` and `instructions` properties. These properties are + * passed to the placeholder component as `label` and `instructions` respectively. + */ + labels?: { + title?: string; + instructions?: string; + }; + /** Undocumented. */ + mediaPreview?: JSX.Element; + /** + * Optionally pass in `noticeUI` obtained from `withNotices` HOC. + */ + notices?: JSX.Element; + onCancel?(): void; + onDoubleClick?: MouseEventHandler; + /** + * Callback called when an upload error happens. + */ + onError?(message: string): void; + onSelectURL?(src: string): void; + multiple?: T; + value?: T extends true ? number[] : number; + onSelect( + value: T extends true ? Array<{ id: number } & { [k: string]: any }> : { id: number } & { [k: string]: any } + ): void; + } + // type Props = BaseProps; + // interface PropsWithMultiple extends BaseProps { + // multiple: true; + // onSelect(values: Array<{ id: number } & { [k: string]: any }>): void; + // value?: number[]; + // } + // interface PropsWithoutMultiple extends BaseProps { + // multiple?: false; + // onSelect(value: { id: number } & { [k: string]: any }): void; + // value?: number; + // } + // type Props = PropsWithoutMultiple | PropsWithMultiple; +} +declare function MediaPlaceholder(props: MediaPlaceholder.Props): JSX.Element; + +export default MediaPlaceholder; diff --git a/types/wordpress__block-editor/components/media-upload/check.d.ts b/types/wordpress__block-editor/components/media-upload/check.d.ts new file mode 100644 index 0000000000..e7a56db6b1 --- /dev/null +++ b/types/wordpress__block-editor/components/media-upload/check.d.ts @@ -0,0 +1,11 @@ +import { ComponentType, ReactNode } from '@wordpress/element'; + +declare namespace MediaUploadCheck { + interface Props { + children: ReactNode; + fallback?: ReactNode; + } +} +declare const MediaUploadCheck: ComponentType; + +export default MediaUploadCheck; diff --git a/types/wordpress__block-editor/components/media-upload/index.d.ts b/types/wordpress__block-editor/components/media-upload/index.d.ts new file mode 100644 index 0000000000..d02d825e88 --- /dev/null +++ b/types/wordpress__block-editor/components/media-upload/index.d.ts @@ -0,0 +1,38 @@ +// tslint:disable:no-unnecessary-generics +import { ComponentType } from '@wordpress/element'; + +import { default as MediaPlaceholder } from '../media-placeholder'; + +declare namespace MediaUpload { + interface Props + extends Pick, 'addToGallery' | 'allowedTypes' | 'multiple' | 'onSelect' | 'value'> { + children?: never; + /** + * If `true`, the component will initiate all the states required to represent a gallery. By + * default, the media modal opens in the gallery edit frame, but that can be changed using + * the `addToGallery`flag. + */ + gallery?: boolean; + /** + * CSS class added to the media modal frame. + */ + modalClass?: string; + /** + * A callback invoked to render the Button opening the media library. + */ + render(props: { + /** + * A function opening the media modal when called. + */ + open(): void; + }): JSX.Element; + /** + * Title displayed in the media modal. + * @defaultValue "Select or Upload Media" + */ + title?: string; + } +} +declare function MediaUpload(props: MediaUpload.Props): JSX.Element; + +export default MediaUpload; diff --git a/types/wordpress__block-editor/components/multi-select-scroll-into-view.d.ts b/types/wordpress__block-editor/components/multi-select-scroll-into-view.d.ts new file mode 100644 index 0000000000..e4f66289db --- /dev/null +++ b/types/wordpress__block-editor/components/multi-select-scroll-into-view.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace MultiSelectScrollIntoView { + interface Props { + children?: never; + } +} +declare const MultiSelectScrollIntoView: ComponentType; + +export default MultiSelectScrollIntoView; diff --git a/types/wordpress__block-editor/components/navigable-toolbar.d.ts b/types/wordpress__block-editor/components/navigable-toolbar.d.ts new file mode 100644 index 0000000000..3dd2d7ab91 --- /dev/null +++ b/types/wordpress__block-editor/components/navigable-toolbar.d.ts @@ -0,0 +1,11 @@ +import { NavigableMenu } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +declare namespace NavigableToolbar { + interface Props extends NavigableMenu.Props { + focusOnMount?: boolean; + } +} +declare const NavigableToolbar: ComponentType; + +export default NavigableToolbar; diff --git a/types/wordpress__block-editor/components/observe-typing.d.ts b/types/wordpress__block-editor/components/observe-typing.d.ts new file mode 100644 index 0000000000..99ba1b092d --- /dev/null +++ b/types/wordpress__block-editor/components/observe-typing.d.ts @@ -0,0 +1,10 @@ +import { ComponentType, ReactNode } from '@wordpress/element'; + +declare namespace ObserveTyping { + interface Props { + children: ReactNode; + } +} +declare const ObserveTyping: ComponentType; + +export default ObserveTyping; diff --git a/types/wordpress__block-editor/components/panel-color-settings.d.ts b/types/wordpress__block-editor/components/panel-color-settings.d.ts new file mode 100644 index 0000000000..f2b6c52ff7 --- /dev/null +++ b/types/wordpress__block-editor/components/panel-color-settings.d.ts @@ -0,0 +1,14 @@ +import { ColorPalette, PanelBody } from '@wordpress/components'; +import { ComponentType } from '@wordpress/element'; + +declare namespace PanelColorSettings { + type ColorSetting = Partial & + Pick & { label: string }; + interface Props extends Omit { + colorSettings: ColorSetting[]; + disableCustomColors?: boolean; + } +} +declare const PanelColorSettings: ComponentType; + +export default PanelColorSettings; diff --git a/types/wordpress__block-editor/components/plain-text.d.ts b/types/wordpress__block-editor/components/plain-text.d.ts new file mode 100644 index 0000000000..5702b09bcf --- /dev/null +++ b/types/wordpress__block-editor/components/plain-text.d.ts @@ -0,0 +1,22 @@ +import { ComponentType, Ref } from '@wordpress/element'; +import TextareaAutosize from 'react-autosize-textarea'; + +declare namespace PlainText { + interface Props extends Omit { + /** + * The component forwards the `ref` property to the `TextareaAutosize` component. + */ + ref?: Ref; + /** + * String value of the textarea + */ + value: string; + /** + * Called when the value changes. + */ + onChange(value: string): void; + } +} +declare const PlainText: ComponentType; + +export default PlainText; diff --git a/types/wordpress__block-editor/components/preserve-scroll-in-reorder.d.ts b/types/wordpress__block-editor/components/preserve-scroll-in-reorder.d.ts new file mode 100644 index 0000000000..a2989678f3 --- /dev/null +++ b/types/wordpress__block-editor/components/preserve-scroll-in-reorder.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace PreserveScrollInReorder { + interface Props { + children?: never; + } +} +declare const PreserveScrollInReorder: ComponentType; + +export default PreserveScrollInReorder; diff --git a/types/wordpress__block-editor/components/provider.d.ts b/types/wordpress__block-editor/components/provider.d.ts new file mode 100644 index 0000000000..e828a90b79 --- /dev/null +++ b/types/wordpress__block-editor/components/provider.d.ts @@ -0,0 +1,48 @@ +import { BlockInstance } from '@wordpress/blocks'; +import { ComponentType, ReactNode } from '@wordpress/element'; + +import { EditorSettings } from '../'; + +declare namespace BlockEditorProvider { + interface Props { + /** + * Children elements for which the BlockEditorProvider context should apply. + */ + children: ReactNode; + /** + * A callback invoked when the blocks have been modified in a persistent manner. Contrasted + * with `onInput`, a "persistent" change is one which is not an extension of a composed + * input. Any update to a distinct block or block attribute is treated as persistent. + * + * @remarks + * The distinction between these two callbacks is akin to the differences between `input` + * and `change` events in the DOM API: + * + * > The input event is fired every time the value of the element changes. **This is unlike + * the change event, which only fires when the value is committed**, such as by pressing the + * enter key, selecting a value from a list of options, and the like. + * + * In the context of an editor, an example usage of this distinction is for managing a + * history of blocks values (an "Undo"/"Redo" mechanism). While value updates should always + * be reflected immediately (`onInput`), you may only want history entries to reflect change + * milestones (`onChange`). + */ + onChange?(blocks: BlockInstance[]): void; + /** + * A callback invoked when the blocks have been modified in a non-persistent manner. + * Contrasted with `onChange`, a "non-persistent" change is one which is part of a composed + * input. Any sequence of updates to the same block attribute are treated as non-persistent, + * except for the first. + */ + onInput?(blocks: BlockInstance[]): void; + settings?: Partial; + useSubRegistry?: boolean; + /** + * The current array of blocks. + */ + value?: BlockInstance[]; + } +} +declare const BlockEditorProvider: ComponentType; + +export default BlockEditorProvider; diff --git a/types/wordpress__block-editor/components/rich-text.d.ts b/types/wordpress__block-editor/components/rich-text.d.ts new file mode 100644 index 0000000000..1bc83681a5 --- /dev/null +++ b/types/wordpress__block-editor/components/rich-text.d.ts @@ -0,0 +1,100 @@ +// tslint:disable:no-unnecessary-generics +import { BlockInstance } from '@wordpress/blocks'; +import { Autocomplete, ToolbarButton } from '@wordpress/components'; +import { ComponentType, HTMLProps, ReactNode } from '@wordpress/element'; +import { displayShortcut, rawShortcut } from '@wordpress/keycodes'; + +declare namespace RichText { + interface Props extends Omit, 'onChange'> { + /** + * A list of autocompleters to use instead of the default. + */ + autocompleters?: Array>; + children?: never; + className?: string; + identifier?: string; + inlineToolbar?: boolean; + /** + * By default, the placeholder will hide as soon as the editable field receives focus. With + * this setting it can be be kept while the field is focussed and empty. + */ + keepPlaceholderOnFocus?: boolean; + multiline?: boolean | keyof HTMLElementTagNameMap; + /** + * Called when the value changes. + */ + onChange(value: string): void; + /** + * Called when blocks can be merged. `forward` is `true` when merging with the next block, + * false when merging with the previous block. + */ + onMerge?(forward: boolean): void; + /** + * Called when the block can be removed. `forward` is `true` when the selection is expected to + * move to the next block, `false` to the previous block. + */ + onRemove?(forward: boolean): void; + /** + * Called when the `RichText` instance can be replaced with the given blocks. + */ + onReplace?(blocks: BlockInstance[]): void; + /** + * Called when the content can be split, where `value` is a piece of content being split + * off. Here you should create a new block with that content and return it. Note that you + * also need to provide `onReplace` in order for this to take any effect. + */ + onSplit?(value: string): void; + onTagNameChange?(tagName: keyof HTMLElementTagNameMap): void; + /** + * Placeholder text to show when the field is empty, similar to the `input` and `textarea` + * attribute of the same name. + * See: {@link https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/HTML5_updates#The_placeholder_attribute } + */ + placeholder?: string; + /** + * The tag name of the editable element. + * @defaultValue div + */ + tagName?: T; + /** + * HTML string to make editable. The HTML should be valid, and valid inside the `tagName`, + * if provided. + */ + value: string; + wrapperClassName?: string; + } + interface ContentProps extends HTMLProps { + children?: never; + multiline?: boolean | 'p' | 'li'; + tagName?: T; + value: string; + } +} +declare const RichText: { + (props: RichText.Props): JSX.Element; + /** + * Should be used in the `save` function of your block to correctly save rich text content. + */ + Content(props: RichText.ContentProps): JSX.Element; + isEmpty(value: string | string[]): boolean; +}; + +export namespace RichTextShortcut { + interface Props { + character: string; + type: keyof typeof rawShortcut; + onUse(): void; + } +} +export const RichTextShortcut: ComponentType; + +export namespace RichTextToolbarButton { + interface Props extends ToolbarButton.Props { + name?: string; + shortcutType?: keyof typeof displayShortcut; + shortcutCharacter?: string; + } +} +export const RichTextToolbarButton: ComponentType; + +export default RichText; diff --git a/types/wordpress__block-editor/components/skip-to-selected-block.d.ts b/types/wordpress__block-editor/components/skip-to-selected-block.d.ts new file mode 100644 index 0000000000..64b6693a18 --- /dev/null +++ b/types/wordpress__block-editor/components/skip-to-selected-block.d.ts @@ -0,0 +1,10 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace SkipToSelectedBlock { + interface Props { + children?: never; + } +} +declare const SkipToSelectedBlock: ComponentType; + +export default SkipToSelectedBlock; diff --git a/types/wordpress__block-editor/components/url-input/button.d.ts b/types/wordpress__block-editor/components/url-input/button.d.ts new file mode 100644 index 0000000000..7d7b94c9fd --- /dev/null +++ b/types/wordpress__block-editor/components/url-input/button.d.ts @@ -0,0 +1,16 @@ +import { ComponentType } from '@wordpress/element'; + +import URLInput from './'; + +declare namespace URLInputButton { + interface Props extends Pick { + children?: never; + /** + * This should be set to the attribute (or component state) property used to store the URL. + */ + url: string; + } +} +declare const URLInputButton: ComponentType; + +export default URLInputButton; diff --git a/types/wordpress__block-editor/components/url-input/index.d.ts b/types/wordpress__block-editor/components/url-input/index.d.ts new file mode 100644 index 0000000000..c3c87fdd76 --- /dev/null +++ b/types/wordpress__block-editor/components/url-input/index.d.ts @@ -0,0 +1,51 @@ +import { ComponentType } from '@wordpress/element'; + +declare namespace URLInput { + // TODO: if PostType is ever typed import it and use it here + type PostType = Record; + interface Props { + /** + * By default, the input will gain focus when it is rendered, as typically it is displayed + * conditionally. For example when clicking on `URLInputButton` or editing a block. + * + * If you are not conditionally rendering this component set this property to `false`. + * @defaultValue true + */ + autoFocus?: boolean; + children?: never; + /** + * Adds and optional class to the parent `div` that wraps the URLInput field and popover. + */ + className?: string; + /** + * Provides additional control over whether suggestions are disabled. + * + * @remarks + * When hiding the URLInput using CSS (as is sometimes done for accessibility purposes), the + * suggestions can still be displayed. This is because they're rendered in a popover in a + * different part of the DOM, so any styles applied to the URLInput's container won't affect + * the popover. + * + * This prop allows the suggestions list to be programmatically not rendered by passing a + * boolean—it can be `true` to make sure suggestions aren't rendered, or `false`/`undefined` + * to fall back to the default behaviour of showing suggestions when matching autocompletion + * items are found. + */ + disableSuggestions?: boolean; + hasBorder?: boolean; + id?: string; + isFullWidth?: boolean; + /** + * Called when the value changes. The second parameter is `null` unless the user selects a + * post from the suggestions dropdown. + */ + onChange(url: string, post: PostType | null): void; + /** + * This should be set to the attribute (or component state) property used to store the URL. + */ + value: string; + } +} +declare const URLInput: ComponentType; + +export default URLInput; diff --git a/types/wordpress__block-editor/components/url-popover.d.ts b/types/wordpress__block-editor/components/url-popover.d.ts new file mode 100644 index 0000000000..4ecebdd5b4 --- /dev/null +++ b/types/wordpress__block-editor/components/url-popover.d.ts @@ -0,0 +1,17 @@ +import { Popover } from '@wordpress/components'; +import { ComponentType, ReactNode } from '@wordpress/element'; + +declare namespace URLPopover { + interface Props extends Popover.Props { + additionalControls?: ReactNode; + /** + * Callback used to return the React Elements that will be rendered inside the settings + * drawer. When this function is provided, a toggle button will be rendered in the popover + * that allows the user to open and close the settings drawer. + */ + renderSettings?(): JSX.Element; + } +} +declare const URLPopover: ComponentType; + +export default URLPopover; diff --git a/types/wordpress__block-editor/components/warning.d.ts b/types/wordpress__block-editor/components/warning.d.ts new file mode 100644 index 0000000000..4174267522 --- /dev/null +++ b/types/wordpress__block-editor/components/warning.d.ts @@ -0,0 +1,16 @@ +import { ComponentType, MouseEventHandler, ReactFragment, ReactNode } from '@wordpress/element'; + +declare namespace Warning { + interface Props { + actions?: ReactFragment; + children: ReactNode; + className?: string; + secondaryActions?: Array<{ + title: ReactNode; + onClick: MouseEventHandler; + }>; + } +} +declare const Warning: ComponentType; + +export default Warning; diff --git a/types/wordpress__block-editor/components/writing-flow.d.ts b/types/wordpress__block-editor/components/writing-flow.d.ts new file mode 100644 index 0000000000..738c3439df --- /dev/null +++ b/types/wordpress__block-editor/components/writing-flow.d.ts @@ -0,0 +1,10 @@ +import { ComponentType, ReactNode } from '@wordpress/element'; + +declare namespace WritingFlow { + interface Props { + children: ReactNode; + } +} +declare const WritingFlow: ComponentType; + +export default WritingFlow; diff --git a/types/wordpress__block-editor/index.d.ts b/types/wordpress__block-editor/index.d.ts new file mode 100644 index 0000000000..b32ae031c7 --- /dev/null +++ b/types/wordpress__block-editor/index.d.ts @@ -0,0 +1,213 @@ +// Type definitions for @wordpress/block-editor 2.2 +// Project: https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/README.md +// Definitions by: Derek Sifford +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.5 +import { BlockIconNormalized } from '@wordpress/blocks'; +import { dispatch, select } from '@wordpress/data'; + +export * from './components'; +export * from './utils'; +export { storeConfig } from './store'; +export { SETTINGS_DEFAULTS } from './store/defaults'; + +declare module '@wordpress/data' { + function dispatch(key: 'core/block-editor'): typeof import('./store/actions'); + function select(key: 'core/block-editor'): typeof import('./store/selectors'); +} + +export type EditorBlockMode = 'html' | 'visual'; +export type EditorMode = 'text' | 'visual'; +export type EditorTemplateLock = 'all' | 'insert' | false; + +export interface EditorBaseSetting { + name: string; + slug: string; +} + +export interface EditorBlockListSettings { + allowedBlocks?: string[]; + templateLock?: EditorTemplateLock; +} + +export interface EditorColor extends EditorBaseSetting { + color: string; +} + +export interface EditorFontSize extends EditorBaseSetting { + size: number; +} + +export type EditorImageSize = EditorBaseSetting; + +export interface EditorInserterItem { + /** + * Unique identifier for the item. + */ + id: string; + /** + * The type of block to create. + */ + name: string; + /** + * Attributes to pass to the newly created block. + */ + initialAttributes: Record; + /** + * Title of the item, as it appears in the inserter. + */ + title: string; + /** + * Icon for the item, as it appears in the inserter. + */ + icon: BlockIconNormalized; + /** + * Block category that the item is associated with. + */ + category: string; + /** + * Keywords that can be searched to find this item. + */ + keywords: string[]; + /** + * Whether or not the user should be prevented from inserting this item. + */ + isDisabled: boolean; + /** + * How useful we think this item is, between 0 and 3. + */ + utility: number; + /** + * Hueristic that combines frequency and recency. + */ + frecency: number; +} + +export interface EditorSelection { + /** + * The selected block client ID. + */ + clientId?: string; + /** + * The selected block attribute key. + */ + attributeKey?: string; + /** + * The selected block attribute offset. + */ + offset?: number; +} + +export interface EditorStyle { + css: string; + baseURL?: string; +} + +export interface EditorSettings { + /** + * Enable/Disable Wide/Full Alignments + * @defaultValue `false` + */ + alignWide: boolean; + /** + * Array of allowed block types, `true` for all blocks, or `false` for no blocks. + * @defaultValue `true` + */ + allowedBlockTypes: string[] | boolean; + /** + * Mapping of extension:mimetype + * @example + * ```js + * { + * "jpg|jpeg|jpe": "image/jpeg", + * } + * ``` + */ + allowedMimeTypes: Record | null; + autosaveInterval: number; + /** + * Array of objects representing the legacy widgets available. + */ + availableLegacyWidgets: Array<{ + description: string; + isCallbackWidget: boolean; + isHidden: boolean; + name: string; + }>; + // FIXME: it is unclear what this value should be. + availableTemplates: any[]; + /** + * Empty post placeholder. + * @defaultValue `"Start writing or type / to choose a block"` + */ + bodyPlaceholder: string; + /** + * Whether or not the user can switch to the code editor. + */ + codeEditingEnabled: boolean; + /** + * Palette colors. + */ + colors: EditorColor[]; + /** + * Whether or not the custom colors are disabled. + */ + disableCustomColors: boolean; + /** + * Whether or not the custom font sizes are disabled. + */ + disableCustomEditorFontSizes: boolean; + /** + * Whether or not the custom post formats are disabled. + */ + disablePostFormats: boolean; + /** + * Whether or not the custom fields are enabled. + */ + enableCustomFields: boolean; + /** + * Whether the focus mode is enabled or not. + */ + focusMode: boolean; + /** + * Array of available font sizes. + */ + fontSizes: EditorFontSize[]; + /** + * Whether or not the editor toolbar is fixed. + */ + hasFixedToolbar: boolean; + /** + * Whether or not the user is able to manage widgets. + */ + hasPermissionsToManageWidgets: boolean; + /** + * Available image sizes. + */ + imageSizes: EditorImageSize[]; + /** + * Whether the editor is in RTL mode. + */ + isRTL: boolean; + maxUploadFileSize: number; + /** + * Max width to constraint resizing. + */ + maxWidth: number; + postLock: { + isLocked: boolean; + user: null | string; + }; + postLockUtils: { + nonce: string; + unlockNonce: string; + ajaxUrl: string; + }; + richEditingEnabled: boolean; + styles: EditorStyle[]; + /** + * Empty title placeholder. + * @defaultValue `"Add title"` + */ + titlePlaceholder: string; +} diff --git a/types/wordpress__block-editor/package.json b/types/wordpress__block-editor/package.json new file mode 100644 index 0000000000..a235ad5798 --- /dev/null +++ b/types/wordpress__block-editor/package.json @@ -0,0 +1,6 @@ +{ + "private": true, + "dependencies": { + "react-autosize-textarea": "^7.0.0" + } +} diff --git a/types/wordpress__block-editor/store/actions.d.ts b/types/wordpress__block-editor/store/actions.d.ts new file mode 100644 index 0000000000..1abdac63c9 --- /dev/null +++ b/types/wordpress__block-editor/store/actions.d.ts @@ -0,0 +1,288 @@ +import { BlockInstance } from '@wordpress/blocks'; + +import { EditorBlockListSettings, EditorSettings } from '../'; + +/** + * Signals that the block selection is cleared. + */ +export function clearSelectedBlock(): void; + +/** + * Signals that the caret has entered formatted text. + */ +export function enterFormattedText(): void; + +/** + * Signals that the user caret has exited formatted text. + */ +export function exitFormattedText(): void; + +/** + * Hides the insertion point. + */ +export function hideInsertionPoint(): void; + +/** + * Signals that a single block should be inserted, optionally at a specific index, respective a root + * block list. + * + * @param block - Block object to insert. + * @param index - Index at which block should be inserted. + * @param rootClientId - Optional root client ID of block list on which to insert. + * @param updateSelection - If `true` block selection will be updated. If `false`, block selection + * will not change. Defaults to true. + */ +export function insertBlock( + block: BlockInstance, + index?: number, + rootClientId?: string, + updateSelection?: boolean +): void; + +/** + * Signals that an array of blocks should be inserted, optionally at a specific index respective a + * root block list. + * + * @param blocks - Block objects to insert. + * @param index - Index at which block should be inserted. + * @param rootClientId - Optional root client ID of block list on which to insert. + * @param updateSelection - If `true` block selection will be updated. If `false`, block selection will + * not change. Defaults to `true`. + */ +export function insertBlocks( + blocks: BlockInstance[], + index?: number, + rootClientId?: string, + updateSelection?: boolean +): IterableIterator; + +/** + * Returns an action object used in signalling that a new block of the default type should be added + * to the block list. + * + * @param attributes - Attributes of the block to assign. + * @param rootClientId - Root client ID of block list on which to append. + * @param index - Index where to insert the default block. + */ +export function insertDefaultBlock(attributes?: Record, rootClientId?: string, index?: number): void; + +/** + * Returns an action object used in signalling that two blocks should be merged. + * + * @param firstBlockClientId - Client ID of the first block to merge. + * @param secondBlockClientId - Client ID of the second block to merge. + */ +export function mergeBlocks(firstBlockClientId: string, secondBlockClientId: string): void; + +/** + * Signals that an indexed block should be moved to a new index. + * + * @param clientId - The client ID of the block. + * @param fromRootClientId - Root client ID source. + * @param toRootClientId - Root client ID destination. + * @param index - The index to move the block into. + */ +export function moveBlockToPosition( + clientId: string | undefined, + fromRootClientId: string | undefined, + toRootClientId: string | undefined, + index: number +): IterableIterator; + +export function moveBlocksDown(clientIds: string | string[], rootClientId: string): void; + +export function moveBlocksUp(clientIds: string | string[], rootClientId: string): void; + +/** + * Signals that block multi-selection changed. + * + * @param start - First block of the multi selection. + * @param end - Last block of the multiselection. + */ +export function multiSelect(start: string, end: string): void; + +/** + * Signals that blocks have been received. Unlike `resetBlocks`, these should be appended to the + * existing known set, not replacing. + * + * @param blocks - Array of block instances. + */ +export function receiveBlocks(blocks: BlockInstance[]): void; + +/** + * Signals that the block with the specified client ID is to be removed. + * + * @param clientId - Client ID of block to remove. + * @param selectPrevious - `true` if the previous block should be selected when a block is removed. + */ +export function removeBlock(clientId: string, selectPrevious?: boolean): void; + +/** + * Signalling that the blocks corresponding to the set of specified client IDs are to be removed. + * + * @param clientIds - Client IDs of blocks to remove. + * @param selectPrevious - `true` if the previous block should be selected when a block is removed. + * Default: `true` + */ +export function removeBlocks(clientIds: string | string[], selectPrevious?: boolean): IterableIterator; + +/** + * Returns an action object signalling that a single block should be replaced + * with one or more replacement blocks. + * + * @param clientId - Block client ID to replace. + * @param block - Replacement block(s). + */ +export function replaceBlock(clientId: string | string[], block: BlockInstance | BlockInstance[]): void; + +/** + * Signals that a blocks should be replaced with one or more replacement blocks. + * + * @param clientIds - Block client ID(s) to replace. + * @param blocks - Replacement block(s). + * @param indexToSelect - Index of replacement block to select. + */ +export function replaceBlocks( + clientIds: string | string[], + blocks: BlockInstance | BlockInstance[], + indexToSelect?: number +): IterableIterator; + +/** + * Signals that the inner blocks with the specified client ID should be replaced. + * + * @param rootClientId - Client ID of the block whose InnerBlocks will re replaced. + * @param blocks - Block objects to insert as new InnerBlocks + * @param updateSelection - If `true` block selection will be updated. If `false`, block selection + * will not change. Defaults to `true`. + */ +export function replaceInnerBlocks(rootClientId: string, blocks: BlockInstance[], updateSelection?: boolean): void; + +/** + * Returns an action object used in signalling that blocks state should be reset to the specified + * array of blocks, taking precedence over any other content reflected as an edit in state. + * + * @param blocks - Array of blocks. + */ +export function resetBlocks(blocks: BlockInstance[]): void; + +/** + * Signals that the block with the specified client ID has been selected, optionally accepting a + * position value reflecting its selection directionality. An initialPosition of `-1` reflects a + * reverse selection. + * + * @param clientId - Block client ID. + * @param initialPosition - Initial position. Pass as `-1` to reflect reverse selection. + */ +export function selectBlock(clientId: string, initialPosition?: number): void; + +/** + * Yields action objects used in signalling that the block following the given `clientId` should be + * selected. + * + * @param clientId - Block client ID. + */ +export function selectNextBlock(clientId: string): IterableIterator; + +/** + * Yields action objects used in signalling that the block preceding the given clientId should be + * selected. + * + * @param clientId - Block client ID. + */ +export function selectPreviousBlock(clientId: string): IterableIterator; + +/** + * Signals that the user caret has changed position. + * + * @param clientId - The selected block client ID. + * @param attributeKey - The selected block attribute key. + * @param startOffset - The start offset. + * @param endOffset - The end offset. + */ +export function selectionChange(clientId: string, attributeKey: string, startOffset: number, endOffset: number): void; + +/** + * Resets the template validity. + * + * @param isValid - template validity flag. + */ +export function setTemplateValidity(isValid: boolean): void; + +/** + * Signals that the insertion point should be shown. + * + * @param rootClientId - Optional root client ID of block list on which to insert. + * @param index - Index at which block should be inserted. + */ +export function showInsertionPoint(rootClientId?: string, index?: number): void; + +/** + * Signals that a block multi-selection has started. + */ +export function startMultiSelect(): void; + +/** + * Signals that the user has begun to type. + */ +export function startTyping(): void; + +/** + * Signals that block multi-selection stopped. + */ +export function stopMultiSelect(): void; + +/** + * Signals that the user has stopped typing. + */ +export function stopTyping(): void; + +/** + * Synchronize the template with the list of blocks. + */ +export function synchronizeTemplate(): void; + +/** + * Toggle the block editing mode between visual and HTML modes. + * + * @param clientId - Block client ID. + */ +export function toggleBlockMode(clientId: string): void; + +/** + * Enables or disables block selection. + * + * @param isSelectionEnabled - Whether block selection should be enabled. + */ +export function toggleSelection(isSelectionEnabled?: boolean): void; + +/** + * Signals that the block with the specified client ID has been updated. + * + * @param clientId - Block client ID. + * @param updates - Block attributes to be merged. + */ +export function updateBlock(clientId: string, updates: Partial): void; + +/** + * Signals that the block attributes with the specified client ID has been updated. + * + * @param clientId - Block client ID. + * @param attributes - Block attributes to be merged. + */ +export function updateBlockAttributes(clientId: string, attributes: Record): void; + +/** + * Changes the nested settings of a given block. + * + * @param clientId - Client ID of the block whose nested setting are being received. + * @param settings - Object with the new settings for the nested block. + */ +export function updateBlockListSettings(clientId: string, settings: EditorBlockListSettings): void; + +/** + * Signals that the block editor settings have been updated. + * + * @param settings - Updated settings. + */ +export function updateSettings(settings: Partial): void; diff --git a/types/wordpress__block-editor/store/defaults.d.ts b/types/wordpress__block-editor/store/defaults.d.ts new file mode 100644 index 0000000000..776c3ef97b --- /dev/null +++ b/types/wordpress__block-editor/store/defaults.d.ts @@ -0,0 +1,3 @@ +import { EditorSettings } from '../'; + +export const SETTINGS_DEFAULTS: EditorSettings; diff --git a/types/wordpress__block-editor/store/index.d.ts b/types/wordpress__block-editor/store/index.d.ts new file mode 100644 index 0000000000..42e832702f --- /dev/null +++ b/types/wordpress__block-editor/store/index.d.ts @@ -0,0 +1,7 @@ +// This is only used internally by `@wordpress/editor`. Not worth the effort of typing this. +export const storeConfig: { + reducer: any; + selectors: any; + actions: any; + controls: any; +}; diff --git a/types/wordpress__block-editor/store/selectors.d.ts b/types/wordpress__block-editor/store/selectors.d.ts new file mode 100644 index 0000000000..cff5579cd5 --- /dev/null +++ b/types/wordpress__block-editor/store/selectors.d.ts @@ -0,0 +1,513 @@ +import { BlockInstance } from '@wordpress/blocks'; + +import { EditorBlockListSettings, EditorBlockMode, EditorInserterItem, EditorSelection, EditorSettings } from '../'; + +/** + * Determines if the given block type is allowed to be inserted into the block list. + * + * @param blockName - The name of the block type, e.g.' core/paragraph'. + * @param rootClientId - Optional root client ID of block list. + * + * @returns Whether the given block type is allowed to be inserted. + */ +export function canInsertBlockType(blockName: string, rootClientId?: string): boolean; + +/** + * Returns the client ID of the block adjacent one at the given reference `startClientId` and modifier + * directionality. Defaults start `startClientId` to the selected block, and direction as next block. + * Returns `null` if there is no adjacent block. + * + * @param startClientId - Optional client ID of block from which to search. + * @param modifier - Directionality multiplier (1 next, -1 previous). + * + * @returns Return the client ID of the block, or null if none exists. + */ +export function getAdjacentBlockClientId(startClientId?: string, modifier?: 1 | -1): string | null; + +/** + * Returns a block given its client ID. This is a parsed copy of the block, containing its + * `blockName`, `clientId`, and current `attributes` state. This is not the block's registration + * settings, which must be retrieved from the blocks module registration store. + * + * @param clientId - Block client ID. + * + * @returns Parsed block object. + */ +export function getBlock(clientId: string): BlockInstance | null; + +/** + * Returns a block's attributes given its client ID, or null if no block exists with the client ID. + * + * @param clientId - Block client ID. + * + * @returns Block attributes. + */ +export function getBlockAttributes(clientId: string): Record | null; + +/** + * Returns the number of blocks currently present in the post. + * + * @param rootClientId - Optional root client ID of block list. + * + * @returns Number of blocks in the post. + */ +export function getBlockCount(rootClientId?: string): number; + +/** + * Given a block client ID, returns the root of the hierarchy from which the block is nested, return + * the block itself for root level blocks. + * + * @param clientId - Block from which to find root client ID. + * + * @returns Root client ID + */ +export function getBlockHierarchyRootClientId(clientId: string): string; + +/** + * Returns the index at which the block corresponding to the specified client ID occurs within the + * block order, or `-1` if the block does not exist. + * + * @param clientId - Block client ID. + * @param rootClientId - Optional root client ID of block list. + * + * @returns Index at which block exists in order. + */ +export function getBlockIndex(clientId: string, rootClientId?: string): number; + +/** + * Returns the insertion point, the index at which the new inserted block would + * be placed. Defaults to the last index. + */ +export function getBlockInsertionPoint(): { index: number; rootClientId?: string }; + +/** + * Returns the Block List settings of a block, if any exist. + * + * @param clientId - Block client ID. + * + * @returns Block settings of the block if set. + */ +export function getBlockListSettings(clientId?: string): EditorBlockListSettings | undefined; + +/** + * Returns the block's editing mode, defaulting to `"visual"` if not explicitly assigned. + * + * @param clientId - Block client ID. + * + * @returns Block editing mode. + */ +export function getBlockMode(clientId: string): EditorBlockMode; + +/** + * Returns a block's name given its client ID, or `null` if no block exists with the client ID. + * + * @param clientId - Block client ID. + * + * @returns Block name. + */ +export function getBlockName(clientId: string): string | null; + +/** + * Returns an array containing all block client IDs in the editor in the order they appear. + * Optionally accepts a root client ID of the block list for which the order should be returned, + * defaulting to the top-level block order. + * + * @param rootClientId - Optional root client ID of block list. + * + * @returns Ordered client IDs of editor blocks. + */ +export function getBlockOrder(rootClientId?: string): string[]; + +/** + * Given a block client ID, returns the root block from which the block is nested, an empty string + * for top-level blocks, or `null` if the block does not exist. + * + * @param clientId - Block from which to find root client ID. + * + * @returns Root client ID, if exists + */ +export function getBlockRootClientId(clientId: string): string | null; + +/** + * Returns the current block selection end. This value may be `undefined`, and it may represent either a + * singular block selection or multi-selection end. A selection is singular if its start and end + * match. + * + * @returns Client ID of block selection end. + */ +export function getBlockSelectionEnd(): string | undefined; + +/** + * Returns the current block selection start. This value may be `undefined`, and it may represent + * either a singular block selection or multi-selection start. A selection is singular if its start + * and end match. + * + * @returns Client ID of block selection start. + */ +export function getBlockSelectionStart(): string | undefined; + +/** + * Returns all block objects for the current post being edited as an array in the order they appear + * in the post. + * + * Note: It's important to memoize this selector to avoid return a new instance + * on each call + * + * @param rootClientId - Optional root client ID of block list. + * + * @returns Post blocks. + */ +export function getBlocks(rootClientId?: string): BlockInstance[]; + +/** + * Given an array of block client IDs, returns the corresponding array of block objects or `null`. + * + * @param clientIds - Client IDs for which blocks are to be returned. + */ +export function getBlocksByClientId(clientIds: string | string[]): Array; + +/** + * Returns an array containing the clientIds of all descendants of the blocks given. + * + * @param clientIds - Array of block ids to inspect. + * + * @returns ids of descendants. + */ +export function getClientIdsOfDescendants(clientIds: string[]): string[]; + +/** + * Returns an array containing the `clientIds` of the top-level blocks and their descendants of any + * depth (for nested blocks). + * + * @returns ids of top-level and descendant blocks. + */ +export function getClientIdsWithDescendants(): string[]; + +/** + * Returns the client ID of the first block in the multi-selection set, or `null` if there is no + * multi-selection. + * + * @returns First block client ID in the multi-selection set. + */ +export function getFirstMultiSelectedBlockClientId(): string | null; + +/** + * Returns the total number of blocks, or the total number of blocks with a specific name in a post. + * The number returned includes nested blocks. + * + * @param blockName - Optional block name, if specified only blocks of that type will be counted. + * + * @returns Number of blocks in the post, or number of blocks with name equal to `blockName`. + */ +export function getGlobalBlockCount(blockName?: string): number; + +/** + * Determines the items that appear in the inserter. Includes both static items (e.g. a regular + * block type) and dynamic items (e.g. a reusable block). + * + * @remarks + * Each item object contains what's necessary to display a button in the inserter and handle its + * selection. + * + * The `utility` property indicates how useful we think an item will be to the user. There are 4 + * levels of utility: + * + * 1. Blocks that are contextually useful (utility = 3) + * 2. Blocks that have been previously inserted (utility = 2) + * 3. Blocks that are in the common category (utility = 1) + * 4. All other blocks (utility = 0) + * + * The `frecency` property is a heuristic (https://en.wikipedia.org/wiki/Frecency) + * that combines block usage frequenty and recency. + * + * Items are returned ordered descendingly by their `utility` and `frecency`. + * + * @param rootClientId - Optional root client ID of block list. + * + * @returns Items that appear in inserter. + */ +export function getInserterItems(rootClientId?: string): EditorInserterItem[]; + +/** + * Returns the client ID of the last block in the multi-selection set, or `null` if there is no + * multi-selection. + * + * @returns Last block client ID in the multi-selection set. + */ +export function getLastMultiSelectedBlockClientId(): string | null; + +/** + * Returns the current multi-selection set of block client IDs, or an empty array if there is no + * multi-selection. + * + * @returns Multi-selected block client IDs. + */ +export function getMultiSelectedBlockClientIds(): string[]; + +/** + * Returns the current multi-selection set of blocks, or an empty array if there is no + * multi-selection. + * + * @returns Multi-selected block objects. + */ +export function getMultiSelectedBlocks(): BlockInstance[]; + +/** + * Returns the client ID of the block which ends the multi-selection set, or `null` if there is no + * multi-selection. + * + * This is not necessarily the last client ID in the selection. + * + * @see getLastMultiSelectedBlockClientId + * + * @returns Client ID of block ending multi-selection. + */ +export function getMultiSelectedBlocksEndClientId(): string | null; + +/** + * Returns the client ID of the block which begins the multi-selection set, or `null` if there is no + * multi-selection. + * + * This is not necessarily the first client ID in the selection. + * + * @see getFirstMultiSelectedBlockClientId + * + * @returns Client ID of block beginning multi-selection. + */ +export function getMultiSelectedBlocksStartClientId(): string | null; + +/** + * Returns the next block's client ID from the given reference start ID. Defaults start to the + * selected block. Returns `null` if there is no next block. + * + * @param startClientId - Optional client ID of block from which to search. + * + * @returns Adjacent block's client ID, or `null` if none exists. + */ +export function getNextBlockClientId(startClientId?: string): string | null; + +/** + * Returns the previous block's client ID from the given reference start ID. Defaults start to the + * selected block. Returns `null` if there is no previous block. + * + * @param startClientId - Optional client ID of block from which to search. + * + * @returns Adjacent block's client ID, or `null` if none exists. + */ +export function getPreviousBlockClientId(startClientId?: string): string | null; + +/** + * Returns the currently selected block, or `null` if there is no selected block. + * + * @returns Selected block. + */ +export function getSelectedBlock(): BlockInstance | null; + +/** + * Returns the currently selected block client ID, or `null` if there is no selected block. + * + * @returns Selected block client ID. + */ +export function getSelectedBlockClientId(): string | null; + +/** + * Returns the current selection set of block client IDs (multiselection or single selection). + * + * @returns Multi-selected block client IDs. + */ +export function getSelectedBlockClientIds(): string[]; + +/** + * Returns the number of blocks currently selected in the post. + * + * @returns Number of blocks selected in the post. + */ +export function getSelectedBlockCount(): number; + +/** + * Returns the initial caret position for the selected block. This position is to used to position + * the caret properly when the selected block changes. + */ +export function getSelectedBlocksInitialCaretPosition(): number | null; + +/** + * Returns the current selection end. + * + * @returns Selection end information. + */ +export function getSelectionEnd(): EditorSelection; + +/** + * Returns the current selection start. + * + * @returns Selection start information. + */ +export function getSelectionStart(): EditorSelection; + +/** + * Returns the editor settings. + */ +export function getSettings(): EditorSettings; + +// FIXME: This is poorly documented. It's not clear what this is. +/** + * Returns the defined block template. + */ +export function getTemplate(): any; + +/** + * Returns the defined block template lock. Optionally accepts a root block client ID as context, + * otherwise defaulting to the global context. + * + * @param rootClientId - Optional block root client ID. + * + * @returns Block Template Lock + */ +export function getTemplateLock(rootClientId?: string): string | undefined; + +/** + * Determines whether there are items to show in the inserter. + * + * @param rootClientId - Optional root client ID of block list. + * + * @returns Items that appear in inserter. + */ +export function hasInserterItems(rootClientId?: string): boolean; + +/** + * Returns `true` if a multi-selection has been made, or `false` otherwise. + * + * @returns Whether multi-selection has been made. + */ +export function hasMultiSelection(): boolean; + +/** + * Returns `true` if there is a single selected block, or `false` otherwise. + * + * @returns Whether a single block is selected. + */ +export function hasSelectedBlock(): boolean; + +/** + * Returns `true` if one of the block's inner blocks is selected. + * + * @param clientId - Block client ID. + * @param deep - Perform a deep check. (default: `true`) + * + * @returns Whether the block as an inner block selected + */ +export function hasSelectedInnerBlock(clientId: string, deep?: boolean): boolean; + +/** + * Returns `true` if an ancestor of the block is multi-selected, or `false` otherwise. + * + * @param clientId - Block client ID. + * + * @returns Whether an ancestor of the block is in multi-selection set. + */ +export function isAncestorMultiSelected(clientId: string): boolean; + +/** + * Returns `true` if we should show the block insertion point. + * + * @returns Whether the insertion point is visible or not. + */ +export function isBlockInsertionPointVisible(): boolean; + +/** + * Returns `true` if the client ID occurs within the block multi-selection, or `false` otherwise. + * + * @param clientId - Block client ID. + * + * @returns Whether block is in multi-selection set. + */ +export function isBlockMultiSelected(clientId: string): boolean; + +/** + * Returns `true` if the block corresponding to the specified client ID is currently selected and no + * multi-selection exists, or `false` otherwise. + * + * @param clientId - Block client ID. + * + * @returns Whether block is selected and multi-selection exists. + */ +export function isBlockSelected(clientId: string): boolean; + +/** + * Returns whether a block is valid or not. + * + * @param clientId - Block client ID. + * + * @returns Is Valid. + */ +export function isBlockValid(clientId: string): boolean; + +/** + * Returns `true` if the block corresponding to the specified client ID is currently selected but + * isn't the last of the selected blocks. Here "last" refers to the block sequence in the document, + * _not_ the sequence of multi-selection, which is why `state.blockSelection.end` isn't used. + * + * @param clientId - Block client ID. + * + * @returns Whether block is selected and not the last in the selection. + */ +export function isBlockWithinSelection(clientId: string): boolean; + +/** + * Returns `true` if the caret is within formatted text, or `false` otherwise. + * + * @returns Whether the caret is within formatted text. + */ +export function isCaretWithinFormattedText(): boolean; + +/** + * Returns `true` if a multi-selection exists, and the block corresponding to the specified client + * ID is the first block of the multi-selection set, or `false` otherwise. + * + * @param clientId - Block client ID. + * + * @returns Whether block is first in multi-selection. + */ +export function isFirstMultiSelectedBlock(clientId: string): boolean; + +/** + * Returns `true` if the most recent block change is be considered persistent, or `false` otherwise. + * A persistent change is one committed by BlockEditorProvider via its `onChange` callback, in + * addition to `onInput`. + * + * @returns Whether the most recent block change was persistent. + */ +export function isLastBlockChangePersistent(): boolean; + +/** + * Whether in the process of multi-selecting or not. This flag is only `true` while the + * multi-selection is being selected (by mouse move), and is `false` once the multi-selection has + * been settled. + * + * @see hasMultiSelection + * + * @returns `true` if multi-selecting, `false` if not. + */ +export function isMultiSelecting(): boolean; + +/** + * Selector that returns if multi-selection is enabled or not. + * + * @returns `true` if it should be possible to multi-select blocks, `false` if multi-selection is + * disabled. + */ +export function isSelectionEnabled(): boolean; + +/** + * Returns `true` if the user is typing, or `false` otherwise. + * + * @returns Whether user is typing. + */ +export function isTyping(): boolean; + +/** + * Returns whether the blocks matches the template or not. + * + * @returns Whether the template is valid or not. + */ +export function isValidTemplate(): boolean; diff --git a/types/wordpress__block-editor/tsconfig.json b/types/wordpress__block-editor/tsconfig.json new file mode 100644 index 0000000000..a573702559 --- /dev/null +++ b/types/wordpress__block-editor/tsconfig.json @@ -0,0 +1,82 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": ["dom", "es6"], + "jsx": "preserve", + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": ["../"], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true, + "paths": { + "@wordpress/block-editor": ["wordpress__block-editor"], + "@wordpress/blocks": ["wordpress__blocks"], + "@wordpress/components": ["wordpress__components"], + "@wordpress/data": ["wordpress__data"], + "@wordpress/element": ["wordpress__element"], + "@wordpress/keycodes": ["wordpress__keycodes"], + "@wordpress/notices": ["wordpress__notices"], + "@wordpress/rich-text": ["wordpress__rich-text"] + } + }, + "files": [ + "components/alignment-toolbar.d.ts", + "components/autocomplete.d.ts", + "components/block-alignment-toolbar.d.ts", + "components/block-controls.d.ts", + "components/block-edit.d.ts", + "components/block-editor-keyboard-shortcuts.d.ts", + "components/block-format-controls.d.ts", + "components/block-icon.d.ts", + "components/block-inspector.d.ts", + "components/block-list.d.ts", + "components/block-mover.d.ts", + "components/block-navigation/dropdown.d.ts", + "components/block-selection-clearer.d.ts", + "components/block-settings-menu.d.ts", + "components/block-switcher/multi-blocks-switcher.d.ts", + "components/block-title.d.ts", + "components/block-toolbar.d.ts", + "components/block-vertical-alignment-toolbar.d.ts", + "components/button-block-appender.d.ts", + "components/color-palette/index.d.ts", + "components/color-palette/with-color-context.d.ts", + "components/colors.d.ts", + "components/contrast-checker.d.ts", + "components/copy-handler.d.ts", + "components/default-block-appender.d.ts", + "components/font-sizes.d.ts", + "components/index.d.ts", + "components/inner-blocks.d.ts", + "components/inserter.d.ts", + "components/inspector-advanced-controls.d.ts", + "components/inspector-controls.d.ts", + "components/media-placeholder.d.ts", + "components/media-upload/check.d.ts", + "components/media-upload/index.d.ts", + "components/multi-select-scroll-into-view.d.ts", + "components/navigable-toolbar.d.ts", + "components/observe-typing.d.ts", + "components/panel-color-settings.d.ts", + "components/plain-text.d.ts", + "components/preserve-scroll-in-reorder.d.ts", + "components/provider.d.ts", + "components/rich-text.d.ts", + "components/skip-to-selected-block.d.ts", + "components/url-input/button.d.ts", + "components/url-input/index.d.ts", + "components/url-popover.d.ts", + "components/warning.d.ts", + "components/writing-flow.d.ts", + "index.d.ts", + "store/actions.d.ts", + "store/defaults.d.ts", + "store/index.d.ts", + "store/selectors.d.ts", + "wordpress__block-editor-tests.tsx" + ] +} diff --git a/types/wordpress__block-editor/tslint.json b/types/wordpress__block-editor/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/wordpress__block-editor/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/wordpress__block-editor/utils/index.d.ts b/types/wordpress__block-editor/utils/index.d.ts new file mode 100644 index 0000000000..c849eccfe2 --- /dev/null +++ b/types/wordpress__block-editor/utils/index.d.ts @@ -0,0 +1,7 @@ +import { EditorStyle } from '../'; + +/** + * Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite + * URLs depending on the parameters passed. + */ +export function transformStyles(styles: EditorStyle[], wrapperClassName?: string): string[]; diff --git a/types/wordpress__block-editor/wordpress__block-editor-tests.tsx b/types/wordpress__block-editor/wordpress__block-editor-tests.tsx new file mode 100644 index 0000000000..7908057457 --- /dev/null +++ b/types/wordpress__block-editor/wordpress__block-editor-tests.tsx @@ -0,0 +1,519 @@ +import { BlockInstance } from '@wordpress/blocks'; +import * as be from '@wordpress/block-editor'; +import { dispatch, select } from '@wordpress/data'; + +declare const BLOCK_INSTANCE: BlockInstance; + +const COLORS = [{ name: 'Red', slug: 'red', color: '#ff0000' }, { name: 'Blue', slug: 'blue', color: '#0000ff' }]; +const FONT_SIZES = [{ name: 'Small', slug: 'small', size: 12 }, { name: 'Large', slug: 'large', size: 18 }]; +const STYLES = [{ css: '.foo { color: red; }' }, { css: '.bar { color: blue; }', baseUrl: 'https://foo.bar' }]; + +// +// Components +// ============================================================================ + +// +// alignment-toolbar +// + newValue && console.log(newValue.toUpperCase())} />; + newValue && console.log(newValue.toUpperCase())} +/>; + +// +// block-alignment-toolbar +// + newValue && console.log(newValue.toUpperCase())} />; + newValue && console.log(newValue.toUpperCase())} +/>; + +// +// block-controls +// +Hello World; + + Hello World +; +; + +// +// block-format-controls +// +Hello World; +; + +// +// block-icon +// +; +foo} showColors />; + +// +// block-mover +// +; + console.log('dragging')} />; + +// +// block-navigation/dropdown +// +; +; + +// +// block-selection-clearer +// + + +
+