@plaudit/gutenberg-api-extensions 2.79.0 → 2.80.0

package/src/blocks/layout/PanelRoot.tsx

@@ -0,0 +1,33 @@
+import {InspectorControls} from "@wordpress/block-editor";
+import {PanelBody} from "@wordpress/components";
+import {cautionFilled} from "@wordpress/icons";
+
+import {testCondition} from "../conditions";
+import {LaidOutPropertyRow} from "./LaidOutPropertyRow";
+import {HydratedSimpleNativePanel, isRootLevelPanelGroup} from "../simple-native-property-internal-shared";
+import {useSNPTreeContext} from "../SNPTreeContext";
+
+import type {ComponentPropsWithoutRef} from "react";
+
+export type PanelRootProps = {panel: HydratedSimpleNativePanel};
+export function PanelRoot({panel}: PanelRootProps) {
+	const {condition, properties, raw, ...panelBodyProps} = panel;
+
+	const dataController = useSNPTreeContext("construct a PanelRoot");
+
+	if (!dataController.hasRenderedNode(properties)
+		|| !testCondition(condition, dataController.makePropertyValueResolver([]))) {
+		return null;
+	}
+
+	const bonusProps: Partial<ComponentPropsWithoutRef<typeof PanelBody>> = dataController.hasValidationErrors(properties)
+		? {icon: cautionFilled, buttonProps: {className: "has-validation-error components-panel__body-toggle"}} //We have to include the default button class for some insane reason
+		: {};
+
+	const panelGroup = panel.group === 'layered-styles' ? 'styles' : panel.group;
+	const children = properties.map(property => {
+		const key = Array.isArray(property) ? property.map(prop => prop.name).join('-') : property.name;
+		return <LaidOutPropertyRow key={key} property={property} dataController={dataController}/>;
+	});
+	return <InspectorControls group={panelGroup} children={(raw ?? !isRootLevelPanelGroup(panelGroup)) ? children : <PanelBody {...panelBodyProps} {...bonusProps} children={children} />} />;
+}

package/src/blocks/layout/TabsRoot.tsx

@@ -0,0 +1,56 @@
+import {InspectorControls} from "@wordpress/block-editor";
+import {PanelBody, TabPanel} from "@wordpress/components";
+
+import {testCondition} from "../conditions";
+import {LaidOutPropertyRow} from "./LaidOutPropertyRow";
+import type {DataController, InspectorPanelGroup} from "../simple-native-property-api";
+import type {HydratedSimpleNativeTab, HydratedSimpleNativeTabItem, HydratedSimpleNativeTabGroup} from "../simple-native-property-internal-shared";
+import {useSNPTreeContext} from "../SNPTreeContext";
+
+import type {ComponentPropsWithoutRef, ReactNode} from "react";
+
+type Tab = ComponentPropsWithoutRef<typeof TabPanel>['tabs'][number]&{panels: [boolean, HydratedSimpleNativeTab['items'][number], string][]};
+
+export type TabsRootProps = {tabs: HydratedSimpleNativeTabGroup, tabGroupName: InspectorPanelGroup};
+export function TabsRoot({tabs, tabGroupName}: TabsRootProps) {
+	//TODO: It should be possible to use immer to make this entire thing memoized
+	const dataController = useSNPTreeContext("construct a TabsRoot component");
+	const instantiatedTabs = instantiateTabsForRenderCycle(tabs, dataController);
+	if (instantiatedTabs.every(tab => tab.disabled)) {
+		return null;
+	}
+	return <InspectorControls group={tabGroupName}>
+		<TabPanel tabs={instantiatedTabs} children={tab => (tab as Tab).panels
+			.filter(([rendered]) => rendered)
+			.map(([_, panel, key]) => <RenderedTabPanel dataController={dataController} panel={panel} key={key} />)} />
+	</InspectorControls>;
+}
+//TODO: Figure out how to memoize this (will probably need some sort of panel/tab-based cache in the dataController)
+function instantiateTabsForRenderCycle(hydratedTabs: {[name: string]: HydratedSimpleNativeTab}, dataController: DataController): Tab[] {
+	const propertyValueResolver = dataController.makePropertyValueResolver([]);
+	return Object.entries(hydratedTabs).map(([name, hydratedTab]) => {
+		const instantiatedPanels: Tab['panels'] = [];
+		let disabled = true;
+		let index = 0;
+		let hasValidationErrors = false;
+		for (const panel of hydratedTab.items) {
+			const rendered = dataController.hasRenderedNode(panel.properties) && (panel.condition === undefined || testCondition(panel.condition, propertyValueResolver));
+			if (rendered) {
+				if (!hasValidationErrors && dataController.hasValidationErrors(panel.properties)) {
+					hasValidationErrors = true;
+				}
+				disabled = false;
+			}
+			instantiatedPanels.push([rendered, panel, `rendered-tab-panel-${name}-${panel.title?.replaceAll(/\W+/gi, "-") ?? ""}-${index++}`]);
+		}
+		return {name, title: hydratedTab.title, panels: instantiatedPanels, disabled, className: hasValidationErrors ? "has-validation-error components-tab-panel__tabs-item" : undefined};
+	});
+}
+
+type RenderedTabPanelProps = {dataController: DataController, panel: HydratedSimpleNativeTabItem};
+function RenderedTabPanel({dataController, panel}: RenderedTabPanelProps): ReactNode {
+	// We have already tested the rendered-ness of the Panel earlier, so there's no need to redo it
+	const {condition, properties, raw, ...panelBodyProps} = panel;
+	const children = properties.map(property => <LaidOutPropertyRow property={property} dataController={dataController} />);
+	return raw ? children : <PanelBody {...panelBodyProps} opened={panelBodyProps.title ? undefined : true} children={children} />;
+}

package/src/blocks/layout/ToolsPanelContext.tsx

@@ -0,0 +1,22 @@
+import {createContext, useContext, useMemo} from "@wordpress/element";
+
+export type ToolsPanelContextValue = {getDefaultValue(name: string): unknown, panelId: string};
+
+export const ToolsPanelContext = createContext<ToolsPanelContextValue|undefined>(undefined);
+
+let nextPanelId = 0;
+export function makeToolsPanelContextValue(actualDefaultValues: {[key in string]: unknown}): ToolsPanelContextValue {
+	const panelId = useMemo(() => (nextPanelId++).toString(), []);
+	return useMemo(() => ({
+		panelId,
+		getDefaultValue: (name: string) => actualDefaultValues[name]
+	}), [panelId, actualDefaultValues]);
+}
+
+export function useToolsPanelContext(action: string): ToolsPanelContextValue {
+	const currentContext = useContext(ToolsPanelContext);
+	if (currentContext === undefined) {
+		throw new Error(`Cannot ${action} outside of an existing ToolsPanelContext`);
+	}
+	return currentContext;
+}

package/src/blocks/shared-exportable-types.ts

@@ -0,0 +1,6 @@
+import type {PlauditIconName, WordPressIconName} from "./shared-internal-types";
+
+import type {ReactElement} from "react";
+
+export type IconName = WordPressIconName|`plaudit:${PlauditIconName}`|`<svg${string}`;
+export type OptionalLabel = string|{text: string, icon?: ReactElement|IconName, tooltip?: string}|undefined;

package/src/blocks/shared-internal-types.ts

@@ -0,0 +1,18 @@
+import type * as icons from "@wordpress/icons";
+
+import type * as plauditIcons from "../lib/plaudit-icons";
+import type {OptionalLabel} from "./shared-exportable-types";
+
+export type PlauditIconName = keyof typeof plauditIcons;
+export type WordPressIconName = Exclude<keyof typeof icons, 'Icon'>;
+
+export type NamedSwitchTypes = "showHide"|"yesNo";
+export type BaseSwitch = {onLabel?: OptionalLabel, offLabel?: OptionalLabel, type?: NamedSwitchTypes};
+export type SmallSwitch = {small: true}&BaseSwitch;
+export type NormalSwitch = ({small?: false|undefined, narrow?: boolean}&BaseSwitch)|NamedSwitchTypes;
+
+export type CSNPControlComponentProps<C, V, P extends {[key: Exclude<string, 'config'|'onChange'|'value'>]: any} = {}> = {
+	config: C,
+	onChange: (v: V|undefined) => void,
+	value: V|undefined
+}&P;

package/src/blocks/simple-block.tsx

@@ -0,0 +1,74 @@
+import {type Block, type BlockConfiguration, type BlockSaveProps, registerBlockType} from "@wordpress/blocks";
+import {InnerBlocks, useBlockProps, useInnerBlocksProps} from "@wordpress/block-editor";
+import type {UseBlockProps} from "@wordpress/block-editor/components/use-block-props";
+
+import {plauditIcon} from "../lib/plaudit-icons";
+
+import type {ComponentType, ReactNode} from "react";
+
+export type SimpleBlockTypeConfig<TAttributes extends Record<string, any>> = {
+	icon?: BlockConfiguration<TAttributes>['icon']|undefined,
+	defaults?: Required<TAttributes>,
+	controls?: NonNullable<Block<TAttributes>['edit']>,
+	renderer: (attributes: BlockSaveProps<TAttributes>, wrapperProps: UseBlockProps|UseBlockProps['save'], InnerBlocks: () => React.ReactElement, mode: "edit"|"save") => ReactNode,
+	innerBlocksProps?: InnerBlocks.Props,
+	settings?: Partial<BlockConfiguration<TAttributes>>,
+};
+function applyDefaults<TAttributes extends Record<string, any>, K extends BlockSaveProps<TAttributes>>(
+	config: Omit<SimpleBlockTypeConfig<TAttributes>, 'renderer'>, props: K
+) {
+	type attrs = { [P in keyof K['attributes']]: K['attributes'][P] };
+	const mutableProps = {...props, attributes: {...props.attributes}} as Omit<typeof props, 'attributes'>&{attributes: attrs};
+	for (const [k, v] of Object.entries(config.defaults ?? {}) as Array<[keyof typeof mutableProps.attributes, any]>) {
+		if (mutableProps.attributes[k] === undefined) {
+			mutableProps.attributes[k] = v;
+		}
+	}
+	return mutableProps;
+}
+
+export function registerSimpleBlockType<TAttributes extends Record<string, any> = {}>(
+	metadata: BlockConfiguration<TAttributes>, config: SimpleBlockTypeConfig<TAttributes>
+): Block<TAttributes>|undefined {
+	return registerBlockType<TAttributes>(metadata, {
+		...config.settings,
+		icon: config.icon ?? plauditIcon,
+		edit(props) {
+			const populatedProps = applyDefaults(config, props);
+			return <>
+				{config.controls && <config.controls {...populatedProps} />}
+				{config.renderer(populatedProps, useBlockProps, () => <InnerBlocks {...config.innerBlocksProps} />, "edit")}
+			</>;
+		},
+		save(props) {
+			return config.renderer(applyDefaults(config, props), useBlockProps.save, () => <InnerBlocks.Content />, "save");
+		}
+	});
+}
+
+type SimpleContainerTypeConfig<TAttributes extends Record<string, any>> = Omit<SimpleBlockTypeConfig<TAttributes>, 'renderer'>&{
+	tag?: ComponentType,
+	attributesFromProps?: (arg: ReturnType<typeof applyDefaults<TAttributes, BlockSaveProps<TAttributes>>>, mode: "edit"|"save") => Parameters<UseBlockProps|UseBlockProps['save']>[0]
+}
+
+export function registerSimpleContainerBlock<TAttributes extends Record<string, any> = {}>(
+	metadata: BlockConfiguration<TAttributes>, config: SimpleContainerTypeConfig<TAttributes>
+): Block<TAttributes>|undefined {
+	const Tag = config.tag ?? ((props: any) => <div {...props} />);
+	return registerBlockType<TAttributes>(metadata, {
+		...config.settings,
+		icon: config.icon ?? plauditIcon,
+		edit(props) {
+			const populatedProps = applyDefaults(config, props);
+			return <>
+				{config.controls && <config.controls {...populatedProps} />}
+				<Tag {...useInnerBlocksProps(useBlockProps(
+					(config.attributesFromProps ?? (() => ({} as Parameters<UseBlockProps>[0])))(populatedProps, "edit")), config.innerBlocksProps)} />
+			</>;
+		},
+		save(props) {
+			return <Tag {...useInnerBlocksProps.save(useBlockProps.save(
+				(config.attributesFromProps ?? (() => ({} as Parameters<UseBlockProps['save']>[0])))(applyDefaults(config, props), "edit")))} />;
+		}
+	})
+}

package/src/blocks/simple-native-property-api.ts

@@ -0,0 +1,170 @@
+import type {configureStore} from "@reduxjs/toolkit/src/configureStore";
+
+import type {createSlotFill} from "@wordpress/components";
+import {dispatch, select} from "@wordpress/data";
+
+import type {CSNPConfig} from "./csnp-api";
+import type {Condition} from "./conditions";
+import type {DataControllerActions, DCNode, DCStoreState} from "./data-controller";
+import {installGutenbergExtensions} from "../index";
+import type {ActualBlockEditProps, BlockName} from "../lib/useful-types";
+import type {HydratedLaidOutProperties} from "./simple-native-property-internal-shared";
+
+import type {ReactElement, ReactNode} from "react";
+
+export type InspectorPanelGroup = 'layered-styles'|'post'|'default'|'advanced'|'background'|'border'|'color'|'dimensions'|'effects'|'filter'|'list'|'position'|'settings'|'styles'|'typography';
+export type {Condition, ConditionFunction, ConditionStruct} from './conditions';
+
+export interface DataStore<B = unknown> {
+	getValue(name: string): any;
+	setValue(name: string, value: any): void;
+
+	reattach(blockEditProps: B, attributeCache: Record<string, any>): DataStore<B>;
+
+	handlesProperty(name: string): boolean;
+
+	addProperty(property: HydratedSimpleNativeProperty, writeThroughOnUndefined?: boolean): void;
+
+	blockEditProps: ActualBlockEditProps;
+}
+export type RawPath = (string|number)[];
+export type NodePath = [string, ...(string|number)[]];
+export type DataController = {
+	dispatch: ReturnType<typeof configureStore<DCStoreState, DataControllerActions, []>>['dispatch'],
+	getDataStore(property: string, required: true): DataStore,
+	getDataStore(property: string, required?: undefined|false): DataStore|undefined,
+	getDataStore(property: string, required?: boolean): DataStore|undefined,
+	getAllDataStores(): DataStore[],
+	makePropertyValueResolver(contextPath: RawPath): (propertyPath: RawPath) => any,
+
+	getValue(path: NodePath): any|undefined,
+	setValue(path: NodePath, value: any): void,
+
+	addProperties(properties: HydratedLaidOutProperties, dataStore: DataStore, inBatch?: boolean): void,
+	addNode(path: NodePath, value?: any): void,
+	removeNode(path: NodePath): void,
+	moveNode(path: NodePath, indices: {from: number, to: number}|{from: string, to: string}): void,
+
+	hasRenderedNode(properties: HydratedLaidOutProperties): boolean,
+	hasValidationErrors(properties?: HydratedLaidOutProperties): boolean,
+	getIsRendered(path: NodePath): boolean,
+	getNode(path: NodePath): DCNode,
+	getValidationError(path: NodePath): string|undefined,
+
+	getWasChangedByManagedControl(): boolean,
+	markManagedControlChangeHandled(): void,
+	blockClientId: string
+};
+export enum NodeMessageSeverity {
+	info,
+	warning,
+	error
+}
+export type NodeMessage = {
+	message: string,
+	severity: NodeMessageSeverity
+};
+
+export type ProvidedSlot = ReturnType<typeof createSlotFill>['Slot'];
+export type SimpleNativePropertyType = 'string'|'number'|'boolean'|'array'|'object';
+export type SNPControlProps<T> = {value: T|undefined, onChange: (v: T|undefined) => void, slots: SNPControlSlots};
+export type GenericSimpleNativeProperty<T, V extends SimpleNativePropertyType> = {
+	name: string,
+	label?: string,
+	type: V,
+	enum?: T[],
+	default?: T,
+	alwaysStore?: boolean|undefined,
+	control(props: SNPControlProps<T>): ReactElement,
+	condition?: Condition,
+	required?: boolean,
+	validator?(value: T|undefined): string|null|undefined,
+	transformer?: {
+		to(input: unknown): T|undefined,
+		from(value: T|undefined): any
+	}
+};
+export type SimpleNativeProperty = GenericSimpleNativeProperty<string, 'string'>&{enum?: string[], styleProperty?: string}
+	|GenericSimpleNativeProperty<number, 'number'>&{enum?: number[], styleProperty?: string}
+	|GenericSimpleNativeProperty<boolean, 'boolean'>
+	|GenericSimpleNativeProperty<any[], 'array'>
+	|GenericSimpleNativeProperty<Record<string|number, unknown>, 'object'>;
+
+export type PDSimpleNativeProperty = SimpleNativeProperty|CSNPConfig;
+export type PotentiallyDesiccatedSimpleNativeProperty = PDSimpleNativeProperty;
+
+export type HydratedSimpleNativeProperty = SimpleNativeProperty
+	&{children?: {[subtype: string]: HydratedSimpleNativeProperty[]}|HydratedSimpleNativeProperty[], controlType?: string, branching?: boolean, initializing?: ReactNode|(() => ReactNode)};
+export type SNPControlSlots = {Label: ProvidedSlot, Messages: ProvidedSlot};
+
+export type LaidOutProperties = Array<PDSimpleNativeProperty|Array<PDSimpleNativeProperty>>;
+export type SimpleNativePanel = {
+	title: string,
+	group?: InspectorPanelGroup,
+	initialOpen?: boolean,
+	properties: LaidOutProperties,
+	condition?: Condition,
+	position?: number,
+	raw?: boolean,
+	identifier?: any
+};
+
+export type SimpleNativeTab = {
+	title: string,
+	group?: InspectorPanelGroup,
+	items: Array<Omit<SimpleNativePanel, 'group'>|LaidOutProperties[number]>,
+	identifier?: any
+}
+
+export type PropertiesParameter = SimpleNativePanel|SimpleNativeTab|Array<LaidOutProperties[number]|SimpleNativePanel|SimpleNativeTab>;
+
+export function registerSimpleNativeProperties(config: {block: BlockName|Array<BlockName>, properties: PropertiesParameter}) {
+	dispatch('plaudit/gutenberg-api-extensions').addProperties(config.block, config.properties);
+}
+export function getSimpleNativeProperties(block: BlockName): Array<PDSimpleNativeProperty>|undefined {
+	const panelsAndTabs = select('plaudit/gutenberg-api-extensions').desiccatedProperties(block);
+	if (panelsAndTabs === undefined) {
+		return undefined;
+	}
+	const res: PDSimpleNativeProperty[] = [];
+	for (const panelOrTab of panelsAndTabs) {
+		if ('items' in panelOrTab) {
+			for (const item of panelOrTab.items) {
+				if ('properties' in item) {
+					res.push(...flattenLaidOutProperties(item.properties));
+				} else if (Array.isArray(item)) {
+					res.push(...flattenLaidOutProperties(item));
+				} else {
+					res.push(item);
+				}
+			}
+		} else {
+			for (const property of panelOrTab.properties) {
+				if (Array.isArray(property)) {
+					res.push(...flattenLaidOutProperties(property));
+				} else {
+					res.push(property);
+				}
+			}
+		}
+	}
+	return res;
+}
+function flattenLaidOutProperties(properties: LaidOutProperties): PDSimpleNativeProperty[] {
+	const res: PDSimpleNativeProperty[] = [];
+	for (const property of properties) {
+		if (Array.isArray(property)) {
+			res.push(...flattenLaidOutProperties(property));
+		} else {
+			res.push(property);
+		}
+	}
+	return res;
+}
+
+/**
+ * @deprecated use installGutenbergExtensions() instead.
+ */
+export function installSimpleNativePropertiesSupport() {
+	installGutenbergExtensions();
+}