@plaudit/gutenberg-api-extensions 2.79.0 → 2.80.1

package/src/controls/FullSizeToggleControl.tsx

@@ -0,0 +1,94 @@
+import {
+	__experimentalToggleGroupControl as ToggleGroupControl, __experimentalToggleGroupControlOption as ToggleGroupControlOption,
+	__experimentalToggleGroupControlOptionIcon as ToggleGroupControlOptionIcon, PanelBody, TabPanel
+} from "@wordpress/components";
+import {memo, useCallback, useMemo} from "@wordpress/element";
+import {__} from "@wordpress/i18n";
+import * as icons from "@wordpress/icons";
+
+import type {TogglePropertyCSNPConfig} from "../blocks/csnp-api";
+import * as plauditIcons from "../lib/plaudit-icons";
+import type {IconName, OptionalLabel} from "../blocks";
+import type {CSNPControlComponentProps, NormalSwitch, PlauditIconName, WordPressIconName} from "../blocks/shared-internal-types";
+
+import parse from "html-react-parser";
+
+import type {ComponentPropsWithoutRef, ReactElement} from "react";
+
+type ToggleGroupControlProps = ComponentPropsWithoutRef<typeof ToggleGroupControl>;
+export type FullSizeToggleControlProps = Omit<CSNPControlComponentProps<TogglePropertyCSNPConfig, boolean, {switchCfg: NormalSwitch}>, 'config'>&{
+	componentConfig?: Partial<ToggleGroupControlProps>,
+	label: ToggleGroupControlProps['label'],
+	help?: ToggleGroupControlProps['help']
+};
+export function FullSizeToggleControl({componentConfig, label, help, onChange, switchCfg, value}: FullSizeToggleControlProps) {
+	const [switchLabels, style] = useMemo(() => {
+		let switchLabels: {onLabel: NonNullable<OptionalLabel>, offLabel: NonNullable<OptionalLabel>};
+		if (typeof switchCfg === 'string') {
+			switchCfg = {type: switchCfg};
+		}
+		switch (switchCfg.type) {
+			case "showHide":
+				switchLabels = {onLabel: "Show", offLabel: "Hide"};
+				break;
+			case "yesNo":
+				switchLabels = {onLabel: "Yes", offLabel: "No"};
+				break;
+			default:
+				if (switchCfg.type !== undefined) {
+					console.error("Invalid switch type:", switchCfg.type);
+				}
+				switchLabels = {onLabel: "On", offLabel: "Off"};
+				break;
+		}
+		if (switchCfg.onLabel) {
+			switchLabels.onLabel = switchCfg.onLabel;
+		}
+		if (switchCfg.offLabel) {
+			switchLabels.offLabel = switchCfg.offLabel;
+		}
+		return [{onLabel: i18nSwitchLabel(switchLabels.onLabel), offLabel: i18nSwitchLabel(switchLabels.offLabel)}, {width: switchCfg.narrow ? "min-content" : undefined}];
+	}, [switchCfg]);
+
+	const safeOnChange = useCallback((v: string|number|undefined) => onChange(v === "true"), [onChange]);
+
+	return <ToggleGroupControl
+		{...componentConfig}
+		value={value ? "true" : "false"} label={label} help={help} isBlock
+		onChange={safeOnChange} style={style}
+	>
+		<ToggleGroupControlOptionWithOptionalIcon key="true" value="true" label={switchLabels.onLabel} />
+		<ToggleGroupControlOptionWithOptionalIcon key="false" value="false" label={switchLabels.offLabel} />
+	</ToggleGroupControl>;
+}
+
+export const ToggleGroupControlOptionWithOptionalIcon
+	= memo(function<V extends string|number>({value, label}: {value: V, label: NonNullable<OptionalLabel>}) {
+	if (typeof label === 'string') {
+		return <ToggleGroupControlOption value={value} label={label} />;
+	} else {
+		const icon = resolveIcon(label.icon);
+		if (icon) {
+			return <ToggleGroupControlOptionIcon value={value} label={label.text} icon={icon} aria-label={label.tooltip} />;
+		} else {
+			return <ToggleGroupControlOption value={value} label={label.text} aria-label={label.tooltip} showTooltip={!!label.tooltip} />;
+		}
+	}
+});
+
+function i18nSwitchLabel(label: NonNullable<OptionalLabel>): typeof label {
+	return typeof label === 'string' ? __(label) : {...label, text: __(label.text)};
+}
+
+function resolveIcon(icon: ReactElement|IconName|undefined): ReactElement|undefined {
+	if (typeof icon !== 'string') {
+		return icon;
+	}
+	if (icon.startsWith("plaudit:")) {
+		return plauditIcons[icon.substring(8) as PlauditIconName];
+	} else if (icon.startsWith("<svg")) {
+		return parse(icon) as ReactElement;
+	} else {
+		return icons[icon as WordPressIconName];
+	}
+}

package/src/controls/ImageControl.tsx

@@ -0,0 +1,143 @@
+import {MediaUpload, MediaUploadCheck} from "@wordpress/block-editor";
+import {BaseControl, Button, FocalPointPicker, ResponsiveWrapper, useBaseControlProps} from "@wordpress/components";
+import {type Attachment, type Context, store as coreStore} from "@wordpress/core-data";
+import {useSelect} from "@wordpress/data";
+import {useCallback, useMemo} from "@wordpress/element";
+import {__} from "@wordpress/i18n";
+
+import type {ProvidedSlot} from "../blocks";
+
+import type {ComponentPropsWithoutRef, ReactNode} from "react";
+
+export type ImageData = {media?: {id?: number, url?: string}, pos?: {x?: number, y?: number}};
+
+type FocalPoint = ComponentPropsWithoutRef<typeof FocalPointPicker>['value'];
+
+export type ImageControlProps = {
+	includeFocalPointPicker?: boolean,
+	label: string,
+	help?: ReactNode,
+	onChange: (value?: Record<string|number, unknown>) => void,
+	value?: ImageData,
+	Label?: ProvidedSlot, Messages?: ProvidedSlot,
+	storage?: 'default'|'slim'
+};
+export function ImageControl(props: ImageControlProps) {
+	const {label, help, value, Label, Messages} = props;
+
+	const media = useSelect(select => value?.media?.id ? select(coreStore).getMedia(value.media.id) : undefined, [value]);
+	const {baseControlProps, controlProps} = useBaseControlProps({label: Label ? <Label /> : label, help});
+	return <BaseControl {...baseControlProps}>
+		<div {...controlProps} className="editor-post-featured-image">
+			{media
+				? <ImageControlWithUploadedImage {...props} media={media} />
+				: <ImageControlWithoutUploadedImage {...props} media={media} />}
+		</div>
+		{Messages && <Messages />}
+	</BaseControl>;
+}
+
+export const RETAINED_FIELDS = ["id", "filename", "url", "date", "mime", "height", "width", "orientation"] as const;
+export const MINIMAL_STORAGE_FIELDS = ['id', 'url'];
+type HypotheticalImageDataType<C extends Context> = Partial<Attachment<C>>&ImageData['media']&{[k in typeof RETAINED_FIELDS[number]]?: k extends keyof Attachment<C> ? Attachment<C>[k] : unknown};
+export function filterImageValueForSaving<C extends Context = 'edit'>(attachment: HypotheticalImageDataType<C>, storage: 'default'|'slim'): Pick<HypotheticalImageDataType<C>, typeof RETAINED_FIELDS[number]> {
+	if (storage === 'slim') {
+		return Object.fromEntries(Object.entries(attachment).filter((entry): entry is [typeof MINIMAL_STORAGE_FIELDS[number], any] => MINIMAL_STORAGE_FIELDS.includes(entry[0] as any)));
+	}
+	return Object.fromEntries(Object.entries(attachment).filter((entry): entry is [typeof RETAINED_FIELDS[number], any] => RETAINED_FIELDS.includes(entry[0] as any)));
+}
+
+const ALLOWED_TYPES = ['image'];
+function ImageControlWithUploadedImage(props: ImageControlProps&{media: Attachment}) {
+	const {includeFocalPointPicker, media, storage, onChange, value} = props;
+	const onFPPChange = useCallback((pos: FocalPoint) => onChange(mergeInUpdatedValuePart(value, 'pos', {x: pos.x * 100, y: pos.y * 100}, storage)), [onChange, value]);
+	const onSelect = useCallback((media: {id: number}&{[k: string]: any}) => onChange(mergeInUpdatedValuePart(value, 'media', media, storage)), [onChange, value]);
+	const renderOpenButton = useCallback(({open}: {open(): void}) => <Button onClick={open} variant="secondary">{__('Replace image', 'plaudit')}</Button>, []);
+	const clear = useCallback(() => onChange(undefined), [onChange]);
+
+	const fppValue = useMemo(() => ({
+		x: (value?.pos?.x ?? 50) / 100,
+		y: (value?.pos?.y ?? 50) / 100
+	}), [value?.pos?.x, value?.pos?.y]);
+
+	let fppOrMedia;
+	if (includeFocalPointPicker !== false) {
+		fppOrMedia = <FocalPointPicker
+			onChange={onFPPChange}
+			url={value?.media?.url ?? ''}
+			value={fppValue}
+		/>;
+	} else {
+		fppOrMedia = <ResponsiveWrapper
+			naturalWidth={parsePossiblyUndefinedFloat(media.media_details["width"])}
+			naturalHeight={parsePossiblyUndefinedFloat(media.media_details["height"])}
+		>
+			<img src={value?.media?.url ?? ''} alt="The currently-selected image." />
+		</ResponsiveWrapper>
+	}
+	return <>
+		{value?.media?.url && fppOrMedia}
+		<MediaUploadCheck>
+			<MediaUpload
+				title={__('Replace image', 'plaudit')}
+				value={value?.media?.id ?? 0}
+				onSelect={onSelect}
+				allowedTypes={ALLOWED_TYPES}
+				render={renderOpenButton}
+			/>
+			<Button onClick={clear} isDestructive>{__('Remove image', 'plaudit')}</Button>
+		</MediaUploadCheck>
+	</>;
+}
+function ImageControlWithoutUploadedImage(props: ImageControlProps&{media: Attachment|undefined}) {
+	const {media, onChange, storage, value} = props;
+	const onSelect = useCallback((media: {id: number}&{[k: string]: any}) => onChange(mergeInUpdatedValuePart(value, 'media', media, storage)), [onChange, value]);
+	const renderOpenButton = useCallback(({open}: {open(): void}) => (
+		<Button
+			className={!value?.media?.id ? 'editor-post-featured-image__toggle' : 'editor-post-featured-image__preview'}
+			onClick={open}
+		>
+			{!value?.media?.id && __('Choose an image', 'plaudit')}
+			{media &&
+				<ResponsiveWrapper
+					naturalWidth={parsePossiblyUndefinedFloat(media.media_details["width"])}
+					naturalHeight={parsePossiblyUndefinedFloat(media.media_details["height"])}
+				>
+					<img src={media.source_url} alt="The currently-selected image." />
+				</ResponsiveWrapper>
+			}
+		</Button>
+	), [media, value?.media?.id]);
+	return <MediaUploadCheck>
+		<MediaUpload
+			onSelect={onSelect}
+			value={value?.media?.id ?? 0}
+			allowedTypes={ALLOWED_TYPES}
+			render={renderOpenButton}
+		/>
+	</MediaUploadCheck>;
+}
+
+function parsePossiblyUndefinedFloat(string: string|number|undefined): number|undefined {
+	return typeof string === 'number' ? string : (string !== undefined ? parseFloat(string) : undefined);
+}
+
+function mergeInUpdatedValuePart(value: ImageData|undefined, partName: 'media'|'pos', part: Required<ImageData>[typeof partName]|undefined, storage: 'default'|'slim'|undefined): ImageData|undefined {
+	if (part === undefined) {
+		return undefined;
+	}
+	if (partName === 'media') {
+		const prt = (part as Required<ImageData>[typeof partName]);
+		if (prt.id === 0) {
+			return undefined;
+		} else if (value === undefined) {
+			return {media: filterImageValueForSaving(prt, storage ?? 'default'), pos: {x: 50, y: 50}};
+		}
+		return {media: filterImageValueForSaving(prt, storage ?? 'default'), pos: {x: value.pos?.x ?? 50, y: value.pos?.y ?? 50}};
+	} else if (value === undefined || !value.media?.id) {
+		return undefined;
+	} else {
+		const prt = (part as Required<ImageData>[typeof partName]);
+		return {media: value.media, pos: {x: prt.x ?? value.pos?.x ?? 50, y: prt.y ?? value.pos?.y ?? 50}};
+	}
+}

package/src/controls/InspectorPanel.tsx

@@ -0,0 +1,37 @@
+import {InspectorControls} from "@wordpress/block-editor";
+import {Panel, PanelBody, TabPanel} from "@wordpress/components";
+import {useState} from "@wordpress/element";
+
+import {type ComponentPropsWithoutRef, type ReactNode, useCallback} from "react";
+
+type TabPanelProps = ComponentPropsWithoutRef<typeof TabPanel>;
+type PanelBodyProps = ComponentPropsWithoutRef<typeof PanelBody>;
+type Tab = TabPanelProps['tabs'][number]&{items: ReactNode};
+type GroupAndCondition = {group?: string, condition?(): boolean};
+type NormalPanelInspectorPanelProps = {tabbed?: false|undefined, raw?: boolean|undefined}&Omit<PanelBodyProps, 'children'>&Pick<InspectorControls.Props, 'children'>&GroupAndCondition;
+type TabbedPanelInspectorPanelProps = {tabbed: true, tabs: Tab[]}&Omit<TabPanelProps, 'children'|'tabs'>&GroupAndCondition;
+export type InspectorPanelProps = (NormalPanelInspectorPanelProps|TabbedPanelInspectorPanelProps);
+export function InspectorPanel(props: InspectorPanelProps) {
+	if (props["tabbed"]) {
+		const {tabbed, tabs, group, condition, ...tabPanelProps} = props;
+		return <InspectorControls group={group}>
+			<TabPanel {...tabPanelProps} tabs={condition === undefined || condition() ? tabs : []}>
+				{tab => <Panel>{(tab as Tab).items}</Panel>}
+			</TabPanel>
+		</InspectorControls>;
+	} else {
+		return <InspectorPanelPanel {...props} />;
+	}
+}
+function InspectorPanelPanel(props: NormalPanelInspectorPanelProps) {
+	const {tabbed, raw, group, condition, children, onToggle, initialOpen, ...panelBodyProps} = props;
+	const [wasOpened, setWasOpened] = useState(initialOpen);
+	const memoOnToggle = useCallback((value: boolean) => {
+		onToggle?.(value);
+		setWasOpened(value);
+	}, [onToggle, setWasOpened]);
+	return <InspectorControls group={group} children={raw
+		? (condition === undefined || condition() ? children : [])
+		: <PanelBody {...panelBodyProps} children={condition === undefined || condition() ? children : []} onToggle={memoOnToggle} initialOpen={wasOpened} />
+	} />;
+}

package/src/controls/LazySuggestionsComboboxControl.tsx

@@ -0,0 +1,62 @@
+import {BaseControl, ComboboxControl, Spinner} from "@wordpress/components";
+import {useCallback, useMemo, useState} from "@wordpress/element";
+import {__} from "@wordpress/i18n";
+
+import {useSuggestions} from "./hooks/useSuggestions";
+
+import type {ComponentProps} from "react";
+
+type ComboboxControlProps = ComponentProps<typeof ComboboxControl>;
+type ComboboxControlOption = ComboboxControlProps['options'][number];
+export type LazySuggestionsComboboxControlProps = Omit<ComboboxControlProps, 'options'> & {
+	getOption(value?: string): Promise<ComboboxControlOption|undefined>;
+	getSuggestions(filterValue: string): Promise<ComboboxControlOption[]>;
+};
+export function LazySuggestionsComboboxControl(props: LazySuggestionsComboboxControlProps) {
+	const {help, allowReset, className, ...passthroughProps} = props;
+
+	const {
+		hasLoadingError, isInitializing, isLoading, suggestions, input, setInput
+	} = useSuggestions(props.value, props);
+
+	const [hasFocus, setHasFocus] = useState(false);
+	const options = useMemo(
+		() => hasFocus && input.length < 2 || (isLoading && !suggestions.length) ? [{label: input, value: "", disabled: true}] : suggestions,
+		[hasFocus, input, isLoading, suggestions]);
+
+	const onFocus = useCallback((e: React.FocusEvent<HTMLElement>) => setHasFocus(e.currentTarget.contains(e.target)), [setHasFocus]);
+	const onBlur = useCallback((e: React.FocusEvent<HTMLElement>) => setHasFocus(e.currentTarget.contains(e.relatedTarget)), [setHasFocus]);
+
+	const onFilterValueChange = useCallback((value: string) => {
+		if (props.onFilterValueChange) {
+			props.onFilterValueChange(value);
+		}
+		setInput(value);
+	}, [props.onFilterValueChange, setInput]);
+
+	const __experimentalRenderItem = useMemo(() => {
+		return hasFocus && input.length < 2 ? () => __("Start typing to see suggestions")
+			: (isLoading && !suggestions.length ? () => __("Loading suggestions") : undefined);
+	}, [hasFocus, input, isLoading, suggestions])
+
+	if (isInitializing) {
+		return <BaseControl {...props}>
+			<Spinner /><span>{__(`Initializing ${props.label}`)}</span>
+		</BaseControl>
+	}
+
+	const needsGreyOut = input.length < 2 || (isLoading && !suggestions.length);
+	return <div onFocus={onFocus} onBlur={onBlur}>
+		{isLoading && <Spinner style={{marginTop: "30px", position: "absolute", right: "40px"}} aria-label="Updating Suggestions" />}
+		<ComboboxControl
+			{...passthroughProps}
+			className={className ? `${className}${needsGreyOut ? " insufficient-input-length" : ""}` : (needsGreyOut ? "insufficient-input-length" : undefined)}
+			help={help}
+			options={options}
+			onFilterValueChange={onFilterValueChange}
+			__experimentalRenderItem={__experimentalRenderItem}
+			allowReset={allowReset !== false}
+		/>
+		{hasLoadingError && <div><span className="components-base-control__help">{__("An error occurred while updating suggestions")}</span></div>}
+	</div>;
+}

package/src/controls/MultiSelectControl.tsx

@@ -0,0 +1,59 @@
+import {useCallback, useMemo} from "@wordpress/element";
+
+import {ExtendedFormTokenField, ValidationState} from "./ExtendedFormTokenField";
+import type {SNPControlSlots} from "../blocks";
+import {getLabel, normalizePickableOptionsToPairs} from "./shared";
+import type {PickableOptions} from "./types";
+
+import type {ReactNode} from "react";
+
+type MultiSelectProps = {
+	onChange: (value: string[]) => void;
+	options: PickableOptions<string|number>;
+	label: string;
+	help?: ReactNode;
+	placeholder: string;
+	value?: string[];
+	expandOnFocus?: boolean;
+	maxLength?: number;
+}&Partial<Pick<SNPControlSlots, 'Messages'>>;
+
+type MandatoryKeys = 'onChange'|'value'|'label'|'options';
+export type MultiSelectConstructorProps = Partial<Omit<MultiSelectProps, MandatoryKeys>> & Pick<MultiSelectProps, MandatoryKeys>;
+
+export function MultiSelectControl(props: MultiSelectConstructorProps) {
+	const {value, options, ...fieldProps} = props;
+	const normalizedOptions = useMemo(() => normalizePickableOptionsToPairs(options), [options]);
+	const validOptions = useMemo(
+		() => Object.fromEntries(normalizedOptions.map(opt => [opt[0], getLabel(opt)])),
+		[normalizedOptions]);
+
+	return <ExtendedFormTokenField
+		{...fieldProps}
+		value={value}
+		multiple={true}
+		stringToTokenConverter={useCallback(token => {
+			if (validOptions[token]) {
+				return {value: token, title: validOptions[token], status: ValidationState.Valid};
+			} else {
+				const result = /(.+) \(#([^)]+)\)$/.exec(token);
+				return result && result[1] && result[2] ? {value: result[2], title: result[1], status: ValidationState.Validating} : {value: token, status: ValidationState.Invalid};
+			}
+		}, [validOptions])}
+		suggestionQuery={useCallback(input => {
+			return normalizedOptions
+				.filter(option => option[0]?.toString().includes(input) || getLabel(option).includes(input))
+				.map(option => ({value: option[0]?.toString(), status: ValidationState.Valid, title: getLabel(option)}));
+		}, [normalizedOptions])}
+		validationQuery={useCallback(values => {
+			return values
+				.filter(value => validOptions[value] !== undefined)
+				.map(value => ({value, title: validOptions[value], status: ValidationState.Valid}));
+		}, [validOptions])}
+		validator={validator}
+	/>;
+}
+
+function validator(token: string) {
+	return /\(#([^)]+)\)$/.exec(token)?.[1] !== undefined;
+}

package/src/controls/PickOne.tsx

@@ -0,0 +1,84 @@
+import {
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
+	__experimentalToggleGroupControlOptionIcon as ToggleGroupControlOptionIcon, BaseControl,
+	ColorPalette, RadioControl, SelectControl, useBaseControlProps
+} from "@wordpress/components";
+
+import {normalizePickableOptionsToPairs} from "./shared";
+import type {PickableOptions, SimpleBlockControlProps} from "./types";
+
+import type {ComponentPropsWithoutRef, ReactElement} from "react";
+
+function makeSharedRadioAndSelectProps<T extends string>(props: SimpleBlockControlProps<T, string>&{options: PickableOptions<string>}) {
+	return {
+		label: props.label,
+		help: props.help,
+		onChange(value: string) {
+			props.setAttributes({[props.attribute]: value});
+		},
+		options: normalizePickableOptionsToPairs(props.options).map(([value, label]) => ({
+			value, label: typeof label === 'string' ? label : label.text
+		}))
+	} as Pick<Parameters<typeof RadioControl>[0], 'label'|'options'>&{onChange(value: string): void};
+}
+
+export type PickOneFromToggleGroupProps<T extends string> = SimpleBlockControlProps<T, string|number>&{options: PickableOptions<string, {icon: ReactElement}>};
+export function PickOneFromToggleGroup<T extends string>(props: PickOneFromToggleGroupProps<T>) {
+	return <ToggleGroupControl
+		label={props.label}
+		help={props.help}
+		value={props.attributes[props.attribute]}
+		onChange={value => props.setAttributes({[props.attribute]: value})}
+		children={
+			normalizePickableOptionsToPairs(props.options).map(([value, label]) => typeof label === 'string'
+				? <ToggleGroupControlOption key={value} value={value} label={label} />
+				: <ToggleGroupControlOptionIcon key={value} value={value} label={label.text} icon={label.icon} />)
+		}
+	/>;
+}
+
+export function PickOneFromSelect<T extends string>(props: SimpleBlockControlProps<T, string>& { options: PickableOptions<string> }) {
+	return <SelectControl
+		{...makeSharedRadioAndSelectProps(props)}
+		value={props.attributes[props.attribute]}
+	/>;
+}
+export function PickOneFromRadios<T extends string>(props: SimpleBlockControlProps<T, string>& { options: PickableOptions<string> }) {
+	return <RadioControl
+		{...makeSharedRadioAndSelectProps(props)}
+		selected={props.attributes[props.attribute]}
+	/>;
+}
+
+type ColorObject = Exclude<NonNullable<ComponentPropsWithoutRef<typeof ColorPalette>['colors']>, {colors: any}[]>[number];
+
+export function PickOneFromColors<T extends string>(props: SimpleBlockControlProps<T, string>&{options: PickableOptions<string, {color?: string|undefined}>}) {
+	const valueToColorMap = new Map<string, string>();
+	const colorToValueMap = new Map<string, string>();
+	const colors: ColorObject[] = [];
+	for (const [value, display] of normalizePickableOptionsToPairs(props.options)) {
+		if (typeof display === 'string') {
+			colors.push({color: value, name: display});
+		} else if (display.color) {
+			valueToColorMap.set(value, display.color);
+			colorToValueMap.set(display.color, value);
+			colors.push({color: display.color, name: display.text});
+		} else {
+			colors.push({color: value, name: display.text});
+		}
+	}
+
+	const currentColor = valueToColorMap.get(props.attributes[props.attribute]) ?? props.attributes[props.attribute];
+	const {baseControlProps, controlProps} = useBaseControlProps({label: props.label, help: props.help});
+	return <BaseControl {...baseControlProps}>
+		<ColorPalette
+			{...controlProps}
+			disableCustomColors={true}
+			onChange={color => props.setAttributes({[props.attribute]: colorToValueMap.get(color ?? currentColor) ?? color ?? currentColor})}
+			colors={colors}
+			value={currentColor}
+			clearable={false}
+		/>
+	</BaseControl>;
+}

package/src/controls/PromisableComponent.tsx

@@ -0,0 +1,56 @@
+import {Spinner} from '@wordpress/components';
+import {useRef} from "@wordpress/element";
+
+import {use, type WrappedPromise, wrapPromise} from "../lib/suspense";
+
+import {Suspense, type ReactNode} from "react";
+
+export type AwaitedProps<T extends object> = {[K in keyof T]: Awaited<T[K]>};
+export type PromisableComponentProps<T extends Awaited<object>> = {
+	promisedProps: T|Promise<T>, initializing?: (() => ReactNode)|ReactNode, renderer(props: AwaitedProps<T>): ReactNode,
+	forceSuspend?: boolean
+};
+
+export function PromisableComponent<T extends Awaited<object>>(props: PromisableComponentProps<T>) {
+	const wrappedPromise = useWrappedArgsParameter(props.promisedProps, props.forceSuspend);
+	if (!(wrappedPromise instanceof Promise)) {
+		return props.renderer(wrappedPromise);
+	}
+	return <Suspense fallback={typeof props.initializing === 'function' ? props.initializing() : <><Spinner /> {props.initializing}</>}>
+		<PromisableComponentDelegator promise={wrappedPromise} children={props.renderer} />
+	</Suspense>;
+}
+function PromisableComponentDelegator<T extends AwaitedProps<Awaited<object>>>(
+	{promise, children}: {promise: WrappedPromise<T>, children(props: T): ReactNode}
+) {
+	return children(use(promise));
+}
+
+function useWrappedArgsParameter<T extends {}>(args: T, forcePromise?: boolean) {
+	const ref = useRef<WrappedArgsHolder<T>|null>(null);
+	if (ref.current === null || args !== ref.current.args || forcePromise !== ref.current.forcePromise) {
+		return (ref.current = {args, forcePromise, value: actuallyWrapTheArgsParameter(args, forcePromise)}).value;
+	} else {
+		const oldArgs = Object.values(ref.current.args);
+		const newArgs = Object.values(args);
+		if (oldArgs.length !== newArgs.length) {
+			return (ref.current = {args, forcePromise, value: actuallyWrapTheArgsParameter(args, forcePromise)}).value;
+		}
+		for (let i = 0; i < newArgs.length; i++) {
+			if (newArgs[i] !== oldArgs[i]) {
+				return (ref.current = {args, forcePromise, value: actuallyWrapTheArgsParameter(args, forcePromise)}).value;
+			}
+		}
+	}
+	return ref.current.value;
+}
+
+type WrappedArgsHolder<T extends {}> = {args: T, forcePromise?: boolean, value: ReturnType<typeof actuallyWrapTheArgsParameter<T>>};
+function actuallyWrapTheArgsParameter<T extends {}>(args: T, forcePromise?: boolean) {
+	if (!Object.values(args).some(v => v instanceof Promise)) {
+		return forcePromise ? (wrapPromise(Promise.resolve(args)) as WrappedPromise<AwaitedProps<Awaited<T>>>) : (args as AwaitedProps<Awaited<T>>);
+	}
+	return wrapPromise(Promise
+		.all(Object.entries(args).map(async ([key, value]): Promise<[typeof key, Awaited<typeof value>]> => [key, await value]))
+		.then<AwaitedProps<T>>(entries => Object.fromEntries(entries) as any));
+}

package/src/controls/ProperLinkControl.tsx

@@ -0,0 +1,93 @@
+import {LinkControl} from "@wordpress/block-editor";
+import {BaseControl, Button, TextControl, ToggleControl} from "@wordpress/components";
+import {useCallback, useEffect, useRef, useState} from "@wordpress/element";
+import {chevronDown, chevronUp} from "@wordpress/icons";
+
+import type {ReactNode} from "react";
+
+export type ProperLinkControlSetting = LinkControl.Setting&({type?: 'toggle'|undefined, default?: boolean|undefined}|{type: 'text', default?: string|undefined});
+
+export type ProperLinkControlProps = Omit<LinkControl.Props, 'settings'>&{label: ReactNode, help?: ReactNode, settings?: ProperLinkControlSetting[]|false};
+export function ProperLinkControl(props: ProperLinkControlProps) {
+	const {value, onChange, onRemove, label, help,
+		settings = ProperLinkControl.DEFAULT_LINK_SETTINGS, ...linkControlProps} = props;
+	const [areAdvancedSettingsVisible, setAreAdvancedSettingsVisible] = useState(false);
+	const advancedSettingsRef = useRef<HTMLDivElement|null>(null);
+
+	useEffect(() => {
+		const advancedSettingsElement = advancedSettingsRef.current;
+		if (!advancedSettingsElement) {
+			return () => {};
+		}
+		const transitionListener = (evt: TransitionEvent) => {
+			if (evt.propertyName === 'max-height' && evt.target === advancedSettingsElement) {
+				if (advancedSettingsElement.style.maxHeight === '0px') {
+					advancedSettingsElement.style.display = 'none';
+				} else {
+					advancedSettingsElement.style.maxHeight = '';
+				}
+			}
+		};
+		advancedSettingsElement.addEventListener('transitionend', transitionListener);
+		return () => advancedSettingsElement.addEventListener('transitionend', transitionListener);
+	}, [advancedSettingsRef]);
+
+	useEffect(() => {
+		const advancedSettingsElement = advancedSettingsRef.current;
+		if (!advancedSettingsElement) {
+			return;
+		}
+		if (areAdvancedSettingsVisible) {
+			advancedSettingsElement.style.display = '';
+			advancedSettingsElement.style.maxHeight = advancedSettingsElement.scrollHeight + "px";
+		} else {
+			advancedSettingsElement.style.maxHeight = advancedSettingsElement.scrollHeight + "px";
+			// We have to use window.requestAnimationFrame in order to force the maxHeight to be treated as "recalculated".
+			// Unless something else on the page goes horribly wrong, there shouldn't be any actual painting done as part of updating the max height.
+			window.requestAnimationFrame(() => advancedSettingsElement.style.maxHeight = "0px");
+		}
+	}, [areAdvancedSettingsVisible, advancedSettingsRef]);
+
+	const safeOnRemove = useCallback(() => onRemove !== undefined ? onRemove() : onChange?.(undefined), [onRemove, onChange]);
+
+	const renderableSettings = settings === false ? [] : settings;
+	const renderControlBottom = useCallback(() => (value?.url && renderableSettings?.length && <>
+		<Button variant="tertiary" onClick={() => setAreAdvancedSettingsVisible(!areAdvancedSettingsVisible)}
+		        icon={areAdvancedSettingsVisible ? chevronUp : chevronDown} iconPosition="right" text="Advanced"
+		/>
+		<div ref={advancedSettingsRef} style={{display: "none", transition: "max-height 200ms ease-in-out", overflow: "hidden"}}>
+			{...renderableSettings.map(setting => <ProperLinkControlSetting setting={setting} onChange={onChange} value={value} />)}
+		</div>
+	</>) || "", [value, settings, areAdvancedSettingsVisible, onChange]);
+
+	return <BaseControl id="" label={props.label} help={props.help}>
+		<LinkControl
+			{...linkControlProps}
+			value={value}
+			onChange={onChange}
+			onRemove={safeOnRemove}
+			settings={ProperLinkControl.DUMMY_LINK_SETTINGS}
+			renderControlBottom={renderControlBottom}
+		/>
+	</BaseControl>
+}
+ProperLinkControl.DEFAULT_LINK_SETTINGS = LinkControl.DEFAULT_LINK_SETTINGS;
+ProperLinkControl.DUMMY_LINK_SETTINGS = [] as LinkControl.Setting[];
+
+export interface ProperLinkControl {
+	(props: ProperLinkControlProps): ReactNode;
+	readonly DEFAULT_LINK_SETTINGS: ReadonlyArray<ProperLinkControlSetting>;
+	readonly DUMMY_LINK_SETTINGS: ReadonlyArray<LinkControl.Setting>;
+}
+
+type ProperLinkControlSettingProps = {value?: LinkControl.Value, onChange?: (nextValue?: LinkControl.Value) => void, setting: ProperLinkControlSetting};
+function ProperLinkControlSetting({value, onChange, setting}: ProperLinkControlSettingProps) {
+	return <div style={{marginTop: "8px"}}>
+		{setting.type === 'text'
+			? <TextControl style={{marginTop: "8px"}} value={value?.[setting.id] ?? setting.default ?? ''} label={setting.title}
+			               onChange={v => onChange?.({...value, [setting.id]: v})} />
+			: <ToggleControl style={{marginTop: "8px"}} checked={value?.[setting.id] ?? setting.default ?? false} label={setting.title}
+			                 onChange={v => onChange?.({...value, [setting.id]: v})} />
+		}
+	</div>;
+}

package/src/controls/SimpleToggle.tsx

@@ -0,0 +1,9 @@
+import {ToggleControl} from "@wordpress/components";
+import {useCallback} from "@wordpress/element";
+
+import type {SimpleBlockControlProps} from "./types";
+
+export function SimpleToggle<T extends string>(props: SimpleBlockControlProps<T, boolean>) {
+	const onChange = useCallback((checked: boolean) => props.setAttributes({[props.attribute]: checked}), [props.setAttributes, props.attribute]);
+	return <ToggleControl checked={props.attributes[props.attribute]} label={props.label} onChange={onChange} />;
+}