@siratik/wp-component-library 0.1.1 → 0.1.2

package/components/query/README.md

@@ -0,0 +1,340 @@
+# Query Controls
+
+This directory contains standalone, modular query controls that can be composed together to build custom query interfaces. Each control is focused on a single responsibility and is always rendered as a ToolsPanelItem.
+
+## Individual Controls
+
+These controls are always ToolsPanelItems that can be composed together in ToolsPanel containers:
+
+### Core Controls
+
+- **`PostTypeSelect`** - Select post type
+- **`OrderBySelect`** - Order posts by date, title, etc.
+- **`SelectionModeControl`** - Toggle between auto and manual selection
+- **`HideCurrentPostControl`** - Exclude the post being viewed from feed results on singles/templates (default on)
+
+### Manual Selection Controls
+
+- **`ManualPostSelector`** - Search and select specific posts
+- **`TermSelector`** - Search and select taxonomy terms
+- **`TaxonomySelect`** - Select taxonomy for term filtering
+
+### Display Controls
+
+- **`DisplayTypeSelect`** - Choose grid, list, slider, or pills display
+- **`PostsPerPageControl`** - Control number of items to show
+- **`ColumnCountControl`** - Set columns for grid or slides for slider
+
+## Usage
+
+### Basic Usage
+
+```jsx
+import { __experimentalToolsPanel as ToolsPanel } from "@wordpress/components";
+import { PostTypeSelect, OrderBySelect } from "../query";
+
+function MyQueryInterface({ attributes, setAttributes }) {
+    const resetAll = () => {
+        setAttributes({
+            postType: "post",
+            orderPostsBy: "date",
+            orderPostsDirection: "desc",
+        });
+    };
+
+    return (
+        <ToolsPanel label="Query Settings" resetAll={resetAll}>
+            <PostTypeSelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+            <OrderBySelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+        </ToolsPanel>
+    );
+}
+```
+
+### Custom Order Options
+
+```jsx
+import { OrderBySelect, defaultOrderOptions } from "../query";
+
+function CustomOrderExample({ attributes, setAttributes }) {
+    // Option 1: Completely replace with custom options
+    const customOptions = [
+        { label: "Popularity", value: "meta_value_num_desc" },
+        { label: "Price (Low to High)", value: "meta_value_num_asc" },
+        { label: "Rating", value: "rating_desc" },
+    ];
+
+    // Option 2: Use defaults as a base and modify
+    const extendedOptions = [
+        ...defaultOrderOptions,
+        { label: "Custom Field", value: "meta_value_desc" },
+        { label: "View Count", value: "views_desc" },
+    ];
+
+    // Option 3: Mix defaults with custom (reorder, filter, etc.)
+    const mixedOptions = [
+        defaultOrderOptions[1], // Date (Newest → Oldest)
+        defaultOrderOptions[2], // Date (Oldest → Newest)
+        { label: "Featured First", value: "featured_desc" },
+        defaultOrderOptions[5], // Random
+    ];
+
+    return (
+        <ToolsPanel label="Query Settings" resetAll={resetAll}>
+            {/* Use completely custom options */}
+            <OrderBySelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+                orderOptions={customOptions}
+            />
+
+            {/* Or use extended options */}
+            <OrderBySelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+                orderOptions={extendedOptions}
+            />
+        </ToolsPanel>
+    );
+}
+```
+
+### Complete Query Interface
+
+```jsx
+import { __experimentalToolsPanel as ToolsPanel } from "@wordpress/components";
+import {
+    PostTypeSelect,
+    OrderBySelect,
+    SelectionModeControl,
+    ManualPostSelector,
+    DisplayTypeSelect,
+} from "../query";
+
+function CompleteQueryInterface({ attributes, setAttributes }) {
+    const resetAll = () => {
+        setAttributes({
+            postType: "post",
+            orderPostsBy: "date",
+            orderPostsDirection: "desc",
+            selectionMode: "auto",
+            selectedPosts: [],
+            displayAs: "grid",
+        });
+    };
+
+    return (
+        <ToolsPanel label="Query Settings" resetAll={resetAll}>
+            <PostTypeSelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+            <OrderBySelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+            <SelectionModeControl
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+            {attributes.selectionMode === "manual" && (
+                <ManualPostSelector
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                    postType={attributes.postType}
+                />
+            )}
+            <DisplayTypeSelect
+                attributes={attributes}
+                setAttributes={setAttributes}
+            />
+        </ToolsPanel>
+    );
+}
+```
+
+### Multiple Panels for Organization
+
+```jsx
+function OrganizedInterface({ attributes, setAttributes }) {
+    return (
+        <>
+            <ToolsPanel label="Content Selection" resetAll={resetContent}>
+                <PostTypeSelect
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                />
+                <OrderBySelect
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                />
+            </ToolsPanel>
+
+            <ToolsPanel label="Display Settings" resetAll={resetDisplay}>
+                <DisplayTypeSelect
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                />
+                <PostsPerPageControl
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                />
+                <ColumnCountControl
+                    attributes={attributes}
+                    setAttributes={setAttributes}
+                />
+            </ToolsPanel>
+        </>
+    );
+}
+```
+
+## Required Attributes
+
+Make sure your block attributes include these for the controls to work properly:
+
+```jsx
+// Required attributes for query controls
+const attributes = {
+    // Core query attributes
+    postType: {
+        type: "string",
+        default: "post",
+    },
+    orderPostsBy: {
+        type: "string",
+        default: "date",
+    },
+    orderPostsDirection: {
+        type: "string",
+        default: "desc",
+    },
+
+    // Selection mode attributes
+    selectionMode: {
+        type: "string",
+        default: "auto",
+    },
+    selectedPosts: {
+        type: "array",
+        default: [],
+    },
+
+    // Taxonomy attributes
+    selectedTaxonomy: {
+        type: "string",
+        default: "",
+    },
+    selectedTerms: {
+        type: "array",
+        default: [],
+    },
+
+    // Display attributes
+    displayAs: {
+        type: "string",
+        default: "grid",
+    },
+    postsPerPage: {
+        type: "number",
+        default: 6,
+    },
+    columnCount: {
+        type: "number",
+        default: 3,
+    },
+};
+```
+
+## Exports
+
+### Components
+
+All individual controls are exported as named exports.
+
+### Utilities
+
+- **`defaultOrderOptions`** - Array of default order options for OrderBySelect
+
+```jsx
+import { OrderBySelect, defaultOrderOptions } from "../query";
+
+// defaultOrderOptions contains:
+// [
+//   { label: "Custom Order", value: "menu_order_asc" },
+//   { label: "Date (Newest → Oldest)", value: "date_desc" },
+//   { label: "Date (Oldest → Newest)", value: "date_asc" },
+//   { label: "Title (A → Z)", value: "title_asc" },
+//   { label: "Title (Z → A)", value: "title_desc" },
+//   { label: "Random", value: "rand_asc" },
+// ]
+```
+
+## Control Props
+
+### Common Props
+
+All controls accept these common props:
+
+- **`attributes`** (Object) - Block attributes object
+- **`setAttributes`** (Function) - Function to update block attributes
+
+### Specific Props
+
+#### PostTypeSelect
+
+- No additional props
+
+#### OrderBySelect
+
+- **`orderOptions`** (Array) - Custom order options (replaces defaults)
+- **`additionalOrderOptions`** (Array) - Additional options to add to defaults (deprecated)
+
+#### TaxonomySelect
+
+- **`postType`** (String) - Post type to get taxonomies for
+
+#### TermSelector
+
+- **`selectedTaxonomy`** (String) - Taxonomy slug to get terms from
+
+#### ManualPostSelector
+
+- **`postType`** (String) - Post type to search (default: 'post')
+
+#### DisplayTypeSelect
+
+- **`allowedDisplayOptions`** (Array) - Allowed display types (default: ['grid', 'slider', 'list', 'pills'])
+
+#### PostsPerPageControl
+
+- **`label`** (String) - Label for control (default: 'Amount to Display')
+- **`min`** (Number) - Minimum value (default: 1)
+- **`max`** (Number) - Maximum value (default: 50)
+
+#### ColumnCountControl
+
+- **`min`** (Number) - Minimum value (default: 1)
+- **`max`** (Number) - Maximum value (default: 4)
+
+## Design Principles
+
+1. **Single Responsibility** - Each control does one thing well
+2. **Always ToolsPanelItems** - Controls are consistent ToolsPanelItem components
+3. **Composable** - Controls can be mixed and matched as needed
+4. **Consistent API** - All controls follow the same prop patterns
+5. **No Forced Panels** - Controls don't create their own ToolsPanel containers
+
+## Architecture Benefits
+
+- **Modular**: Use only the controls you need
+- **Flexible**: Arrange controls in any panel structure
+- **Consistent**: All controls work the same way
+- **Maintainable**: Each control is focused and isolated
+- **Composable**: Build complex interfaces from simple parts

package/components/query/cardTemplatePartPanel.js

@@ -0,0 +1,69 @@
+import { __experimentalToolsPanel as ToolsPanel } from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+import { CardTemplatePartSelect } from "./cardTemplatePartSelect";
+import { getDefaultCardSlugForPostType } from "./cardTemplatePartUtils";
+
+/**
+ * Card layout ToolsPanel — matches core/query block extension UI.
+ *
+ * @param {Object} props Component props.
+ * @param {Object} props.attributes Block attributes (postType, templatePartSlug).
+ * @param {Function} props.setAttributes Set block attributes.
+ * @param {string} [props.postType] Post type override.
+ * @param {string} [props.area] Template part area (default kitaris-cards).
+ * @param {string} [props.defaultSlug] Default slug for reset / deselect.
+ * @param {Function} [props.slugFilter] Optional (slug, postType) => boolean.
+ * @param {Function} [props.onSlugChange] Optional side effect when slug changes.
+ * @param {string} [props.textDomain] i18n text domain.
+ * @param {boolean} [props.disableAutoFill] Passed to CardTemplatePartSelect.
+ * @param {boolean} [props.usePersistedSlugOnly] Passed to CardTemplatePartSelect.
+ * @returns {import('react').WPElement|null} Element to render.
+ */
+function CardTemplatePartPanel({
+	attributes,
+	setAttributes,
+	postType: postTypeProp,
+	area,
+	defaultSlug: defaultSlugProp,
+	slugFilter,
+	onSlugChange,
+	textDomain = "built_starter",
+	disableAutoFill = false,
+	usePersistedSlugOnly = false,
+}) {
+	const postType = postTypeProp || attributes?.postType || "post";
+	const resolvedDefault =
+		defaultSlugProp || getDefaultCardSlugForPostType(postType);
+
+	const resetCardLayout = () => {
+		setAttributes({ templatePartSlug: resolvedDefault });
+
+		// onSlugChange is optional; query blocks handle inner sync via setAttributes.
+		if (onSlugChange) {
+			onSlugChange(resolvedDefault);
+		}
+	};
+
+	return (
+		<ToolsPanel
+			// eslint-disable-next-line @wordpress/i18n-text-domain -- text domain is a prop for the consumer.
+			label={__("Card layout", textDomain)}
+			resetAll={resetCardLayout}
+		>
+			<CardTemplatePartSelect
+				attributes={attributes}
+				setAttributes={setAttributes}
+				postType={postType}
+				area={area}
+				defaultSlug={resolvedDefault}
+				slugFilter={slugFilter}
+				onSlugChange={onSlugChange}
+				textDomain={textDomain}
+				disableAutoFill={disableAutoFill}
+				usePersistedSlugOnly={usePersistedSlugOnly}
+			/>
+		</ToolsPanel>
+	);
+}
+
+export { CardTemplatePartPanel };

package/components/query/cardTemplatePartSelect.js

@@ -0,0 +1,165 @@
+import {
+	SelectControl,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { useSelect } from "@wordpress/data";
+import { useEffect, useMemo } from "@wordpress/element";
+import { __ } from "@wordpress/i18n";
+import {
+	buildCardTemplatePartOptions,
+	getDefaultCardSlugForPostType,
+} from "./cardTemplatePartUtils";
+
+/**
+ * Card template part selector for query/post-feed blocks (kitaris-cards area).
+ *
+ * @param {Object} props Component props.
+ * @param {Object} props.attributes Block attributes (postType, templatePartSlug).
+ * @param {Function} props.setAttributes Set block attributes.
+ * @param {string} [props.postType] Post type override.
+ * @param {string} [props.area] Template part area (default kitaris-cards).
+ * @param {string} [props.defaultSlug] Default slug for deselect / empty state.
+ * @param {Function} [props.slugFilter] Optional (slug, postType) => boolean.
+ * @param {Function} [props.onSlugChange] Optional side effect when slug changes (e.g. sync inner blocks).
+ * @param {boolean} [props.isShownByDefault] ToolsPanelItem default visibility.
+ * @param {string} [props.textDomain] i18n text domain.
+ * @param {boolean} [props.disableAutoFill] Skip auto-setting default slug on mount.
+ * @param {boolean} [props.usePersistedSlugOnly] Select value is the saved slug only (no default fallback writes).
+ * @returns {import('react').WPElement|null} Element to render.
+ */
+function CardTemplatePartSelect({
+	attributes,
+	setAttributes,
+	postType: postTypeProp,
+	area = "kitaris-cards",
+	defaultSlug: defaultSlugProp,
+	slugFilter,
+	onSlugChange,
+	isShownByDefault = true,
+	textDomain = "built_starter",
+	disableAutoFill = false,
+	usePersistedSlugOnly = false,
+}) {
+	const postType = postTypeProp || attributes?.postType || "post";
+	const templatePartSlug = attributes?.templatePartSlug || "";
+	const resolvedDefault =
+		defaultSlugProp || getDefaultCardSlugForPostType(postType);
+
+	const templateParts = useSelect(
+		(select) =>
+			select("core").getEntityRecords("postType", "wp_template_part", {
+				per_page: 200,
+				area,
+			}),
+		[area],
+	);
+
+	const options = useMemo(() => {
+		const filtered = buildCardTemplatePartOptions(
+			templateParts,
+			postType,
+			slugFilter,
+		);
+
+		if (
+			!templatePartSlug ||
+			filtered.some((option) => option.value === templatePartSlug)
+		) {
+			return filtered;
+		}
+
+		const savedPart = templateParts?.find(
+			(part) => part.slug === templatePartSlug,
+		);
+
+		if (!savedPart) {
+			return filtered;
+		}
+
+		return [
+			{
+				label:
+					savedPart.title?.rendered ||
+					savedPart.title ||
+					savedPart.slug,
+				value: savedPart.slug,
+			},
+			...filtered,
+		];
+	}, [templateParts, postType, slugFilter, templatePartSlug]);
+
+	const selectValue = usePersistedSlugOnly
+		? templatePartSlug
+		: templatePartSlug || resolvedDefault;
+
+	useEffect(() => {
+		if (disableAutoFill) {
+			return;
+		}
+
+		if (!templatePartSlug && resolvedDefault && options.length > 0) {
+			const hasDefault = options.some((o) => o.value === resolvedDefault);
+			if (hasDefault) {
+				setAttributes({ templatePartSlug: resolvedDefault });
+			}
+		}
+	}, [
+		templatePartSlug,
+		resolvedDefault,
+		options,
+		setAttributes,
+		disableAutoFill,
+	]);
+
+	if (!options.length) {
+		return null;
+	}
+
+	const handleChange = (value) => {
+		if (!value || value === templatePartSlug) {
+			return;
+		}
+
+		setAttributes({ templatePartSlug: value });
+
+		// Caller may already sync in setAttributes (e.g. core/query); skip duplicate updates.
+		if (onSlugChange) {
+			onSlugChange(value);
+		}
+	};
+
+	return (
+		<ToolsPanelItem
+			hasValue={() =>
+				!!templatePartSlug && templatePartSlug !== resolvedDefault
+			}
+			// eslint-disable-next-line @wordpress/i18n-text-domain -- text domain is a prop for the consumer.
+			label={__("Card layout", textDomain)}
+			onDeselect={() => {
+				setAttributes({ templatePartSlug: resolvedDefault });
+
+				if (onSlugChange) {
+					onSlugChange(resolvedDefault);
+				}
+			}}
+			isShownByDefault={isShownByDefault}
+		>
+			<SelectControl
+				__nextHasNoMarginBottom={true}
+				__next40pxDefaultSize
+				// eslint-disable-next-line @wordpress/i18n-text-domain -- text domain is a prop for the consumer.
+				label={__("Card layout", textDomain)}
+				// eslint-disable-next-line @wordpress/i18n-text-domain -- text domain is a prop for the consumer.
+				help={__(
+					"Choose which card template part to use for each post in the loop.",
+					textDomain,
+				)}
+				value={selectValue}
+				options={options}
+				onChange={handleChange}
+			/>
+		</ToolsPanelItem>
+	);
+}
+
+export { CardTemplatePartSelect };

package/components/query/cardTemplatePartUtils.js

@@ -0,0 +1,119 @@
+/**
+ * Resolve card template part options for a post type.
+ *
+ * Override via editor_experience.card_templates[postType] in the host plugin's
+ * localize config (window.kitaris_localize.blocks.editor_experience).
+ *
+ * @param {string} postType Post type slug.
+ * @returns {string[]} Slug prefixes — a part matches if slug equals prefix or starts with prefix + '-'.
+ */
+export function getCardSlugPrefixesForPostType(postType) {
+	if (!postType) {
+		return ["card-"];
+	}
+
+	const config =
+		typeof window !== "undefined" &&
+		window.kitaris_localize?.blocks?.editor_experience?.card_templates?.[
+			postType
+		];
+
+	if (Array.isArray(config) && config.length > 0) {
+		return config.map((entry) =>
+			typeof entry === "string" ? entry : entry?.slug,
+		).filter(Boolean);
+	}
+
+	const knownPrefixes = {
+		kitaris_service: ["card-service"],
+		kitaris_team: ["card-team"],
+		kitaris_promotion: ["card-promotion"],
+		kitaris_coupon: ["card-promotion"],
+		kitaris_listing: ["kitaris_listing-card", "card-listing"],
+		kitaris_review: ["kitaris_review-card", "card-review"],
+		post: ["post-card", "card-post"],
+		page: ["page-card", "card-page"],
+		search: ["search-result-card", "card-search"],
+	};
+
+	if (knownPrefixes[postType]) {
+		return knownPrefixes[postType];
+	}
+
+	const base = postType.replace(/^kitaris_/, "");
+
+	return [`card-${base}`, `${postType}-card`];
+}
+
+/**
+ * @param {string} slug Template part slug.
+ * @param {string} postType Post type slug.
+ * @param {Function} [customFilter] Optional (slug, postType) => boolean.
+ * @returns {boolean}
+ */
+export function cardTemplatePartMatchesPostType(slug, postType, customFilter) {
+	if (typeof customFilter === "function") {
+		return customFilter(slug, postType);
+	}
+
+	if (!slug) {
+		return false;
+	}
+
+	const prefixes = getCardSlugPrefixesForPostType(postType);
+
+	return prefixes.some(
+		(prefix) => slug === prefix || slug.startsWith(`${prefix}-`),
+	);
+}
+
+/**
+ * Default card slug for a post type (first configured prefix).
+ *
+ * @param {string} postType Post type slug.
+ * @returns {string}
+ */
+export function getDefaultCardSlugForPostType(postType) {
+	const defaults = {
+		kitaris_service: "card-service-001",
+		kitaris_team: "card-team-001",
+		kitaris_promotion: "card-promotion-001",
+		kitaris_coupon: "card-promotion-001",
+		kitaris_location: "card-location-001",
+	};
+
+	if (defaults[postType]) {
+		return defaults[postType];
+	}
+
+	const prefixes = getCardSlugPrefixesForPostType(postType);
+
+	return prefixes[0] || `${postType}-card`;
+}
+
+/**
+ * Build select options from template part entities.
+ *
+ * @param {Array} templateParts wp_template_part records.
+ * @param {string} postType Post type slug.
+ * @param {Function} [slugFilter] Optional filter.
+ * @returns {Array<{ label: string, value: string }>}
+ */
+export function buildCardTemplatePartOptions(
+	templateParts,
+	postType,
+	slugFilter,
+) {
+	if (!templateParts?.length) {
+		return [];
+	}
+
+	const filtered = templateParts.filter((part) =>
+		cardTemplatePartMatchesPostType(part.slug, postType, slugFilter),
+	);
+
+	return filtered.map((part) => ({
+		label: part.title?.rendered || part.title || part.slug,
+		value: part.slug,
+	}));
+}