@siratik/wp-component-library 0.1.1 → 0.1.2

package/components/meta/MetaPanel.js

@@ -0,0 +1,75 @@
+/**
+ * Meta Panel Component
+ *
+ * A reusable component for adding meta fields to the Gutenberg Document sidebar.
+ * This component provides the core structure (modal, button) for meta panels.
+ *
+ * Usage:
+ * ```jsx
+ * <MetaPanel title="My Panel">
+ *   <TextControl ... />
+ *   <TextareaControl ... />
+ * </MetaPanel>
+ * ```
+ */
+
+import { Button, Modal } from "@wordpress/components";
+import { compose } from "@wordpress/compose";
+import { withSelect } from "@wordpress/data";
+import { PluginPostStatusInfo } from "@wordpress/editor";
+import { useState, memo } from "@wordpress/element";
+
+const MetaPanelBase = ({
+    title,
+    postType,
+    children,
+    buttonText = "Edit Meta Details",
+    currentPostType,
+}) => {
+    const [isOpen, setOpen] = useState(false);
+
+    // Only show for specified post type
+    if (postType && postType !== currentPostType) { return null; }
+
+    return (
+        <>
+            <PluginPostStatusInfo>
+                <Button
+                    __next40pxDefaultSize
+                    variant="secondary"
+                    onClick={() => setOpen(true)}
+                    style={{ flexGrow: 1, justifyContent: "center" }}
+                >
+                    {buttonText}
+                </Button>
+            </PluginPostStatusInfo>
+            {isOpen && (
+                <Modal
+                    title={title || "Meta Details"}
+                    size="medium"
+                    onRequestClose={() => setOpen(false)}
+                >
+                    <div style={{ padding: "16px" }}>{children}</div>
+                    <Button variant="secondary" onClick={() => setOpen(false)}>
+                        Close
+                    </Button>
+                </Modal>
+            )}
+        </>
+    );
+};
+
+// Memoize to prevent unnecessary re-renders
+const MetaPanelMemo = memo(MetaPanelBase);
+
+const MetaPanel = compose([
+    withSelect((select) => {
+        const { getCurrentPostType } = select("core/editor");
+        
+        return {
+            currentPostType: getCurrentPostType(),
+        };
+    }),
+])(MetaPanelMemo);
+
+export { MetaPanel };

package/components/meta/README.md

@@ -0,0 +1,46 @@
+# Meta Components
+
+Components for post meta in the Gutenberg editor.
+
+## MetaPanel
+
+Adds a button to the document sidebar that opens a modal for editing post meta fields. Used by plugins such as Kitaris Directory and Kitaris Reviews.
+
+```jsx
+import { MetaPanel } from "@siratik/wp-component-library";
+import { TextControl } from "@wordpress/components";
+
+function ListingMetaPanel({ postMeta, onChange }) {
+	return (
+		<MetaPanel title="Listing Details" postType="kitaris_listing">
+			<TextControl
+				label="Website"
+				value={postMeta.kitaris_directory_website_url || ""}
+				onChange={(value) => onChange({ kitaris_directory_website_url: value })}
+			/>
+		</MetaPanel>
+	);
+}
+```
+
+Restrict to a post type with the `postType` prop. Meta fields must be registered with `show_in_rest => true`.
+
+## Meta-gated editor visibility
+
+For blocks that support meta-gated visibility (via wp-utility on the frontend), use:
+
+- `useMetaGatedEditorVisibility` — hook for custom editor UI
+- `isMetaValueEmpty` — shared empty check
+- `isTemplateEditorSurface` — detect template/template-part editor context
+
+See `meta-gated-editor.js` and the `meta-gated-editor-visibility` filter in wp-blocks.
+
+## Template bindings
+
+For template parts and patterns, bind blocks to post meta with the Block Bindings API in block markup:
+
+```html
+<!-- wp:image {"metadata":{"bindings":{"id":{"source":"core/post-meta","args":{"key":"kitaris_directory_logo_id"}}}}} -->
+```
+
+Register meta on the post type in your plugin's `post_types_config.php`.

package/components/meta/index.js

@@ -0,0 +1,6 @@
+export {
+	isMetaValueEmpty,
+	isTemplateEditorSurface,
+	useMetaGatedEditorVisibility,
+} from './meta-gated-editor';
+export { MetaPanel } from './MetaPanel';

package/components/meta/meta-gated-editor.js

@@ -0,0 +1,282 @@
+/**
+ * Editor visibility rules for hide-when-empty blocks (hideWhenMetaEmpty).
+ *
+ * Frontend output is suppressed by siratik-utility MetaGatedBlockSupport /
+ * render.php. In the editor, blocks stay visible on template surfaces so card
+ * layouts remain editable; they hide in query/post-feed loop previews when
+ * their Block Bindings are empty — the block's own, or for a wrapper with no
+ * bindings of its own, every bound block inside it.
+ */
+
+import { getBlockBindingsSource } from "@wordpress/blocks";
+import { store as blockEditorStore } from "@wordpress/block-editor";
+import { store as coreStore } from "@wordpress/core-data";
+import { useSelect } from "@wordpress/data";
+
+/**
+ * @param {string|null|undefined} editorPostType Current editor post type.
+ * @returns {boolean}
+ */
+export function isTemplateEditorSurface(editorPostType) {
+	return (
+		!editorPostType ||
+		editorPostType === "wp_template" ||
+		editorPostType === "wp_template_part" ||
+		editorPostType === "wp_block"
+	);
+}
+
+/** Characters PHP's trim() strips (not JS's wider whitespace set). */
+const PHP_TRIM = /^[ \t\n\r\0\x0B]+|[ \t\n\r\0\x0B]+$/g;
+
+/**
+ * PHP's empty() for a scalar.
+ *
+ * @param {unknown} value Value.
+ * @returns {boolean}
+ */
+function isPhpEmpty(value) {
+	return !value || value === "0" || (Array.isArray(value) && value.length === 0);
+}
+
+/**
+ * Whether a bound value counts as empty, as siratik-utility
+ * MetaGatedRender::is_value_empty() decides on the front end: arrays and
+ * objects are empty unless they are a usable icon (name + source).
+ *
+ * @param {unknown} value Post meta value.
+ * @returns {boolean}
+ */
+export function isMetaValueEmpty(value) {
+	if (value === undefined || value === null || value === false || value === "") {
+		return true;
+	}
+
+	if (Array.isArray(value)) {
+		return true;
+	}
+
+	if (typeof value === "object") {
+		return isPhpEmpty(value.name) || isPhpEmpty(value.source);
+	}
+
+	if (typeof value === "string") {
+		return value.replace(PHP_TRIM, "") === "";
+	}
+
+	return false;
+}
+
+const POST_META_SOURCE = "core/post-meta";
+
+/**
+ * A post meta value as the front end reads it. Core's PHP post-meta source
+ * gives null for a protected key and for a key not shown in REST (absent from
+ * the record). REST types an unsaved integer or number field as 0 where the
+ * front end reads '', so 0 counts as unsaved.
+ *
+ * @returns {unknown} Meta value, or undefined when it isn't readable.
+ */
+function readablePostMeta(select, key, context) {
+	if (typeof key !== "string" || key === "" || key.startsWith("_")) {
+		return undefined;
+	}
+
+	const store = select(coreStore);
+	const record = (store.getEditedEntityRecord ?? store.getEntityRecord)(
+		"postType",
+		context.postType,
+		context.postId,
+	);
+	const value = record?.meta?.[key];
+
+	return value === 0 ? "" : value;
+}
+
+/**
+ * Values of a block's own bindings resolved through their registered
+ * sources, as the front end does; null when none resolves (no binding, only
+ * unregistered sources, or only attributes without binding support).
+ *
+ * @returns {unknown[]|null} Bound values.
+ */
+function ownBoundValues(select, blockName, bindings, context, clientId) {
+	const supported =
+		select(blockEditorStore).getSettings?.()?.__experimentalBlockBindingsSupportedAttributes?.[blockName];
+	const values = [];
+
+	for (const [attribute, binding] of Object.entries(bindings || {})) {
+		if (Array.isArray(supported) && !supported.includes(attribute)) {
+			continue;
+		}
+
+		if (typeof binding?.source !== "string") {
+			continue;
+		}
+
+		const args = binding.args && typeof binding.args === "object" ? binding.args : {};
+
+		if (binding.source === POST_META_SOURCE) {
+			values.push(readablePostMeta(select, args.key, context));
+			continue;
+		}
+
+		const source = getBlockBindingsSource(binding.source);
+
+		if (!source?.getValues) {
+			continue;
+		}
+
+		const result = source.getValues({
+			select,
+			context,
+			bindings: { [attribute]: { ...binding, args } },
+			clientId,
+		});
+		values.push(result?.[attribute]);
+	}
+
+	return values.length > 0 ? values : null;
+}
+
+/**
+ * Values of a block's own bindings, else of its descendants' bindings (for
+ * wrappers such as a group around a bound paragraph), as siratik-utility
+ * MetaGatedRender::bound_values() reads them on the front end.
+ *
+ * @returns {unknown[]|null} Bound values, or null when nothing is bound.
+ */
+function boundValues(select, blockName, bindings, innerBlocks, context, clientId) {
+	const own = ownBoundValues(select, blockName, bindings, context, clientId);
+
+	if (own !== null) {
+		return own;
+	}
+
+	let values = null;
+
+	for (const inner of innerBlocks || []) {
+		const innerValues = boundValues(
+			select,
+			inner.name,
+			inner.attributes?.metadata?.bindings,
+			inner.innerBlocks,
+			context,
+			clientId,
+		);
+
+		if (innerValues !== null) {
+			values = [...(values ?? []), ...innerValues];
+		}
+	}
+
+	return values;
+}
+
+/**
+ * @param {object} props
+ * @param {object} props.attributes Block attributes.
+ * @param {string} [props.clientId] Block client ID.
+ * @param {object} [props.context] Block context (postId, postType).
+ * @returns {{ shouldHide: boolean, isTemplateSurface: boolean, isLoopPreview: boolean }}
+ */
+export function useMetaGatedEditorVisibility({ attributes, clientId, context }) {
+	const { hideWhenMetaEmpty, metaField, metadata } = attributes || {};
+	const ownBindings = metadata?.bindings;
+	const contextPostId = context?.postId;
+	const contextPostType = context?.postType;
+
+	return useSelect(
+		(select) => {
+			const defaultResult = {
+				shouldHide: false,
+				isTemplateSurface: false,
+				isLoopPreview: false,
+			};
+
+			if (!hideWhenMetaEmpty) {
+				return defaultResult;
+			}
+
+			const editor = select("core/editor");
+			const editorPostType = editor?.getCurrentPostType?.() ?? null;
+			const editorPostId = editor?.getCurrentPostId?.() ?? null;
+			const isTemplateSurface = isTemplateEditorSurface(editorPostType);
+
+			if (isTemplateSurface) {
+				return {
+					shouldHide: false,
+					isTemplateSurface: true,
+					isLoopPreview: false,
+				};
+			}
+
+			const inPostContext = Boolean(contextPostId && contextPostType);
+			const isLoopPreview =
+				inPostContext &&
+				editorPostId !== null &&
+				Number(contextPostId) !== Number(editorPostId);
+
+			// Editing the source post — keep visible so fields can be filled in.
+			if (!isLoopPreview) {
+				return defaultResult;
+			}
+
+			const block = clientId ? select(blockEditorStore).getBlock(clientId) : null;
+			const values = boundValues(
+				select,
+				block?.name,
+				ownBindings,
+				block?.innerBlocks ?? [],
+				{ postId: contextPostId, postType: contextPostType },
+				clientId,
+			);
+
+			if (values !== null) {
+				return {
+					shouldHide: values.every(isMetaValueEmpty),
+					isTemplateSurface: false,
+					isLoopPreview: true,
+				};
+			}
+
+			// Legacy: content saved before bindings keyed the gate by metaField.
+			if (!metaField) {
+				return defaultResult;
+			}
+
+			const record = select(coreStore).getEntityRecord(
+				"postType",
+				contextPostType,
+				contextPostId,
+			);
+
+			// The front end reads any unprotected field; the editor only sees
+			// REST meta, so a field not in REST stays visible.
+			const unreadable =
+				!metaField.startsWith("_") &&
+				!(record?.meta && Object.prototype.hasOwnProperty.call(record.meta, metaField));
+
+			return {
+				shouldHide: unreadable
+					? false
+					: isMetaValueEmpty(
+							readablePostMeta(select, metaField, {
+								postType: contextPostType,
+								postId: contextPostId,
+							}),
+						),
+				isTemplateSurface: false,
+				isLoopPreview: true,
+			};
+		},
+		[
+			hideWhenMetaEmpty,
+			metaField,
+			ownBindings,
+			clientId,
+			contextPostId,
+			contextPostType,
+		],
+	);
+}