@siratik/wp-component-library 0.1.0 → 0.1.2

package/components/query/orderBySelect.js

@@ -0,0 +1,95 @@
+import {
+    SelectControl,
+    __experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * Default order options - can be imported and used as a base
+ */
+export const defaultOrderOptions = [
+    { 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" },
+];
+
+/**
+ * Standalone order by selection control
+ *
+ * @param {Object} props Component props
+ * @param {Object} props.attributes Block attributes
+ * @param {Function} props.setAttributes Function to set attributes
+ * @param {Array} props.orderOptions Custom order options (replaces defaults if provided)
+ * @param {Array} props.additionalOrderOptions Additional options to add to defaults (deprecated, use orderOptions instead)
+ * @param {boolean} props.isShownByDefault Whether to show by default in ToolsPanel (default: true)
+ * @returns {WPElement} Element to render
+ */
+/**
+ * Split an order option value ("menu_order_asc") into orderby and order at
+ * its last underscore: orderby values can hold underscores themselves.
+ *
+ * @param {string} value Option value, `${orderby}_${order}`.
+ * @return {{ orderPostsBy: string, orderPostsDirection: string }} Attributes.
+ */
+export function parseOrderValue(value) {
+    const at = value.lastIndexOf("_");
+    return {
+        orderPostsBy: value.slice(0, at),
+        orderPostsDirection: value.slice(at + 1),
+    };
+}
+
+function OrderBySelect({
+    attributes: { orderPostsBy, orderPostsDirection },
+    setAttributes,
+    orderOptions,
+    additionalOrderOptions = [], // Keep for backward compatibility
+    isShownByDefault = true,
+}) {
+    const defaultOrderPostsBy = "date";
+    const defaultOrderPostsDirection = "desc";
+
+    // Determine which options to use
+    let finalOptions;
+    if (orderOptions) {
+        // Use custom options if provided
+        finalOptions = orderOptions;
+    } else if (additionalOrderOptions.length > 0) {
+        // Use defaults + additional for backward compatibility
+        finalOptions = [...defaultOrderOptions, ...additionalOrderOptions];
+    } else {
+        // Use defaults
+        finalOptions = defaultOrderOptions;
+    }
+
+    return (
+        <ToolsPanelItem
+            hasValue={() =>
+                orderPostsBy !== defaultOrderPostsBy ||
+                orderPostsDirection !== defaultOrderPostsDirection
+            }
+            label={__("Order By", "built_starter")}
+            onDeselect={() =>
+                setAttributes({
+                    orderPostsBy: defaultOrderPostsBy,
+                    orderPostsDirection: defaultOrderPostsDirection,
+                })
+            }
+            isShownByDefault={isShownByDefault}
+        >
+            <SelectControl
+                __nextHasNoMarginBottom={true}
+                __next40pxDefaultSize
+                label="Order By"
+                value={`${orderPostsBy}_${orderPostsDirection}`}
+                options={finalOptions}
+                onChange={(value) => setAttributes(parseOrderValue(value))}
+            />
+        </ToolsPanelItem>
+    );
+}
+
+export { OrderBySelect };

package/components/query/postTypeSelect.js

@@ -0,0 +1,67 @@
+import {
+    SelectControl,
+    __experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { useSelect } from "@wordpress/data";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * Standalone post type selection control
+ *
+ * @param {Object} props Component props
+ * @param {Object} props.attributes Block attributes
+ * @param {Function} props.setAttributes Function to set attributes
+ * @param {boolean} props.isShownByDefault Whether to show by default in ToolsPanel (default: true)
+ * @returns {WPElement} Element to render
+ */
+function PostTypeSelect({
+    attributes: { postType },
+    setAttributes,
+    isShownByDefault = true,
+}) {
+    const defaultPostType = "post";
+
+    const getPostTypeList = useSelect((select) =>
+        select("core").getPostTypes({ per_page: 20 }),
+    );
+
+    const getPostTypesOptions = () => {
+        let filteredPostTypes = [];
+        let postTypesOptions = [];
+
+        if (getPostTypeList) {
+            filteredPostTypes = getPostTypeList.filter(
+                (type) =>
+                    type.viewable === true &&
+                    type.rest_base !== "media" &&
+                    type.rest_base !== "pages",
+            );
+            postTypesOptions = filteredPostTypes.map((type) => ({
+                label: type.name,
+                value: type.slug,
+            }));
+        }
+
+        return postTypesOptions;
+    };
+
+    return (
+        <ToolsPanelItem
+            hasValue={() => postType !== defaultPostType}
+            label={__("Select Post Type", "built_starter")}
+            onDeselect={() => setAttributes({ postType: defaultPostType })}
+            isShownByDefault={isShownByDefault}
+        >
+            <SelectControl
+                __nextHasNoMarginBottom={true}
+                __next40pxDefaultSize
+                label={__("Select Post Type", "built_starter")}
+                onChange={(value) => setAttributes({ postType: value })}
+                options={getPostTypesOptions()}
+                value={postType}
+            />
+        </ToolsPanelItem>
+    );
+}
+
+export { PostTypeSelect };

package/components/query/postsPerPageControl.js

@@ -0,0 +1,51 @@
+import {
+    RangeControl,
+    __experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * Standalone posts per page control
+ *
+ * @param {Object} props Component props
+ * @param {Object} props.attributes Block attributes
+ * @param {Function} props.setAttributes Function to set attributes
+ * @param {string} props.label Label for the control
+ * @param {number} props.min Minimum value
+ * @param {number} props.max Maximum value
+ * @param {boolean} props.isShownByDefault Whether to show by default in ToolsPanel (default: false)
+ * @param {number} props.defaultValue The block's default count (default: 6)
+ * @returns {WPElement} Element to render
+ */
+function PostsPerPageControl({
+    attributes: { postsPerPage },
+    setAttributes,
+    label = __("Amount to display", "wp-component-library"),
+    min = 1,
+    max = 50,
+    isShownByDefault = false,
+    defaultValue = 6,
+}) {
+    return (
+        <ToolsPanelItem
+            hasValue={() => postsPerPage !== defaultValue}
+            label={label}
+            onDeselect={() => setAttributes({ postsPerPage: defaultValue })}
+            isShownByDefault={isShownByDefault}
+        >
+            <RangeControl
+                __nextHasNoMarginBottom={true}
+                __next40pxDefaultSize
+                label={label}
+                value={postsPerPage}
+                onChange={(postsPerPageNew) =>
+                    setAttributes({ postsPerPage: postsPerPageNew })
+                }
+                min={min}
+                max={max}
+            />
+        </ToolsPanelItem>
+    );
+}
+
+export { PostsPerPageControl };

package/components/query/selectionModeControl.js

@@ -0,0 +1,61 @@
+import {
+    __experimentalToggleGroupControl as ToggleGroupControl,
+    __experimentalToggleGroupControlOption as ToggleGroupControlOption,
+    __experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * Standalone selection mode control (auto vs manual)
+ *
+ * @param {Object} props Component props
+ * @param {Object} props.attributes Block attributes
+ * @param {Function} props.setAttributes Function to set attributes
+ * @param {boolean} props.isShownByDefault Whether to show by default in ToolsPanel (default: true)
+ * @returns {WPElement} Element to render
+ */
+function SelectionModeControl({
+    attributes: { selectionMode = "auto" },
+    setAttributes,
+    isShownByDefault = true,
+}) {
+    const defaultSelectionMode = "auto";
+
+    const handleSelectionModeChange = (value) => {
+        setAttributes({
+            selectionMode: value,
+            // Preserve existing selections when switching modes
+        });
+    };
+
+    return (
+        <ToolsPanelItem
+            hasValue={() => selectionMode !== defaultSelectionMode}
+            label={__("Selection Mode", "wp-component-library")}
+            onDeselect={() =>
+                setAttributes({ selectionMode: defaultSelectionMode })
+            }
+            isShownByDefault={isShownByDefault}
+        >
+            <ToggleGroupControl
+                __next40pxDefaultSize={true}
+                __nextHasNoMarginBottom
+                label={__("Selection Mode", "wp-component-library")}
+                value={selectionMode}
+                onChange={handleSelectionModeChange}
+                isBlock
+            >
+                <ToggleGroupControlOption
+                    label={__("Auto", "wp-component-library")}
+                    value="auto"
+                />
+                <ToggleGroupControlOption
+                    label={__("Manual", "wp-component-library")}
+                    value="manual"
+                />
+            </ToggleGroupControl>
+        </ToolsPanelItem>
+    );
+}
+
+export { SelectionModeControl };

package/components/query/taxonomySelect.js

@@ -0,0 +1,139 @@
+import {
+    SelectControl,
+    __experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { useSelect } from "@wordpress/data";
+import { useEffect, useMemo } from "@wordpress/element";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * Standalone taxonomy selection control
+ *
+ * @param {Object} props Component props
+ * @param {Object} props.attributes Block attributes
+ * @param {Function} props.setAttributes Function to set attributes
+ * @param {string} props.postType The post type to get taxonomies for
+ * @param {boolean} props.showNoneOption Whether to show a "none" option (default: false)
+ * @param {string} props.noneOptionLabel Label for the "none" option (default: "No Taxonomy Filter")
+ * @param {boolean} props.isShownByDefault Whether to show by default in ToolsPanel (default: false)
+ * @returns {WPElement} Element to render
+ */
+function TaxonomySelect({
+    attributes: { selectedTaxonomy },
+    setAttributes,
+    postType,
+    showNoneOption = false,
+    noneOptionLabel = "No Taxonomy Filter",
+    isShownByDefault = false,
+}) {
+    const defaultSelectedTaxonomy = "";
+
+    // Get all taxonomies (fetch once, cache the result)
+    const allTaxonomies = useSelect((select) => {
+        return select("core").getTaxonomies({
+            per_page: -1,
+        });
+    }, []);
+
+    // Memoize the filtered taxonomies to prevent unnecessary re-renders
+    const filteredTaxonomies = useMemo(() => {
+        if (!postType || !allTaxonomies) {
+            return [];
+        }
+        return allTaxonomies.filter((tax) => tax.types.includes(postType));
+    }, [allTaxonomies, postType]);
+
+    // Auto-select first taxonomy when post type changes (only if showNoneOption is false)
+    useEffect(() => {
+        if (filteredTaxonomies.length > 0) {
+            // Only set if current selection is empty or not in the filtered list
+            const isCurrentSelectionValid =
+                selectedTaxonomy === "" || // Empty is always valid when showNoneOption is true
+                filteredTaxonomies.some((tax) => tax.slug === selectedTaxonomy);
+
+            if (!isCurrentSelectionValid) {
+                // If showNoneOption is true, default to empty, otherwise select first taxonomy
+                const defaultValue = showNoneOption
+                    ? ""
+                    : filteredTaxonomies[0].slug;
+                setAttributes({
+                    selectedTaxonomy: defaultValue,
+                    selectedTerms: [], // Clear terms when taxonomy changes
+                });
+            } else if (
+                !showNoneOption &&
+                !selectedTaxonomy &&
+                filteredTaxonomies.length > 0
+            ) {
+                // If showNoneOption is false and no selection, select first taxonomy
+                setAttributes({
+                    selectedTaxonomy: filteredTaxonomies[0].slug,
+                    selectedTerms: [],
+                });
+            }
+        } else if (filteredTaxonomies.length === 0 && selectedTaxonomy) {
+            // Clear selection if no taxonomies available
+            setAttributes({
+                selectedTaxonomy: defaultSelectedTaxonomy,
+                selectedTerms: [],
+            });
+        }
+    }, [filteredTaxonomies, selectedTaxonomy, setAttributes, showNoneOption]);
+
+    // Memoize taxonomy options to prevent recreation
+    const taxonomyOptions = useMemo(() => {
+        return filteredTaxonomies.map((tax) => ({
+            label: tax.labels.singular_name || tax.name,
+            value: tax.slug,
+        }));
+    }, [filteredTaxonomies]);
+
+    // Memoize all options to prevent recreation
+    const allOptions = useMemo(() => {
+        return showNoneOption
+            ? [{ label: noneOptionLabel, value: "" }, ...taxonomyOptions]
+            : taxonomyOptions;
+    }, [showNoneOption, noneOptionLabel, taxonomyOptions]);
+
+    return (
+        <ToolsPanelItem
+            hasValue={() => selectedTaxonomy !== defaultSelectedTaxonomy}
+            label={__("Select Taxonomy", "built")}
+            onDeselect={() =>
+                setAttributes({
+                    selectedTaxonomy: defaultSelectedTaxonomy,
+                    selectedTerms: [],
+                })
+            }
+            isShownByDefault={isShownByDefault}
+        >
+            <SelectControl
+                __nextHasNoMarginBottom={true}
+                __next40pxDefaultSize
+                label={__("Select Taxonomy", "built")}
+                value={selectedTaxonomy}
+                options={allOptions}
+                onChange={(value) =>
+                    setAttributes({
+                        selectedTaxonomy: value,
+                        selectedTerms: [], // Clear terms when taxonomy changes
+                    })
+                }
+                disabled={!postType || filteredTaxonomies.length === 0}
+                help={
+                    // eslint-disable-next-line no-nested-ternary -- render branches.
+                    !postType
+                        ? __("Please select a post type first", "built")
+                        : filteredTaxonomies.length === 0
+                          ? __(
+                                "No taxonomies available for this post type",
+                                "built",
+                            )
+                          : undefined
+                }
+            />
+        </ToolsPanelItem>
+    );
+}
+
+export { TaxonomySelect };

package/components/query/utils.js

@@ -0,0 +1,75 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Utility functions for query components
+ */
+
+/**
+ * Reorder an array of items based on a given order of IDs
+ * 
+ * @param {Array} items - Array of objects to reorder
+ * @param {Array} orderedIds - Array of IDs in the desired order
+ * @param {Function} getItemId - Function to extract ID from an item (default: item => item.id)
+ * @returns {Array} Reordered array
+ */
+export function reorderByIds(items, orderedIds, getItemId = (item) => item.id) {
+	if (!items || !orderedIds || orderedIds.length === 0) {
+		return items || [];
+	}
+
+	// Create a map for quick lookup
+	const itemMap = new Map();
+	items.forEach((item) => {
+		itemMap.set(getItemId(item), item);
+	});
+
+	// Build the ordered array
+	const ordered = [];
+	orderedIds.forEach((id) => {
+		const item = itemMap.get(id);
+		if (item) {
+			ordered.push(item);
+		}
+	});
+
+	return ordered;
+}
+
+// Shared empty result: useSelect compares results, so a new [] per call would
+// re-render and log "useSelect returns different values".
+const NO_TERMS = [];
+
+/**
+ * Hook to fetch and reorder terms based on selectedTerms order
+ * 
+ * Example usage:
+ * ```js
+ * const orderedTerms = useOrderedTerms(selectedTerms, taxonomy);
+ * ```
+ */
+export function useOrderedTerms(selectedTerms, taxonomy) {
+	const { terms } = useSelect(
+		(select) => {
+			if (!taxonomy || !selectedTerms || selectedTerms.length === 0) {
+				return { terms: NO_TERMS };
+			}
+
+			const fetchedTerms = select('core').getEntityRecords('taxonomy', taxonomy, {
+				include: selectedTerms,
+				per_page: selectedTerms.length,
+			});
+
+			return { terms: fetchedTerms || NO_TERMS };
+		},
+		[selectedTerms, taxonomy]
+	);
+
+	// Reorder terms to match selectedTerms order
+	return useMemo(() => {
+		return reorderByIds(terms, selectedTerms);
+	}, [terms, selectedTerms]);
+}

package/components/repeater/README.md

@@ -0,0 +1,159 @@
+# Repeater Component
+
+A flexible repeater component with drag-and-drop functionality powered by @dnd-kit. This component allows users to add, remove, and reorder items in a list with a smooth dragging experience.
+
+## Features
+
+- **Drag and Drop**: Smooth drag-and-drop reordering using @dnd-kit
+- **Keyboard Navigation**: Full keyboard support for accessibility
+- **Flexible Content**: Render any content inside repeater items via renderItem prop
+- **Collapsible Rows**: Optional header summary with expand/collapse (opt-in)
+- **Min/Max Limits**: Configure minimum and maximum number of items
+- **Customizable**: Custom labels, empty states, and styling
+- **Accessible**: ARIA labels and keyboard navigation support
+
+## Usage
+
+```jsx
+import { Repeater } from '@siratik/wp-component-library/components/repeater';
+import { useState } from '@wordpress/element';
+
+function MyComponent() {
+    const [items, setItems] = useState([
+        { id: '1', title: 'First Item', content: 'Some content' },
+        { id: '2', title: 'Second Item', content: 'More content' }
+    ]);
+
+    const handleAdd = () => {
+        const newItem = {
+            id: Date.now().toString(),
+            title: '',
+            content: ''
+        };
+        setItems([...items, newItem]);
+    };
+
+    const handleRemove = (id) => {
+        setItems(items.filter(item => item.id !== id));
+    };
+
+    const handleReorder = (newItems) => {
+        setItems(newItems);
+    };
+
+    const renderItem = (item) => (
+        <div>
+            <TextControl
+                label="Title"
+                value={item.title}
+                onChange={(title) => updateItem(item.id, { title })}
+            />
+            <TextareaControl
+                label="Content"
+                value={item.content}
+                onChange={(content) => updateItem(item.id, { content })}
+            />
+        </div>
+    );
+
+    return (
+        <Repeater
+            items={items}
+            renderItem={renderItem}
+            onAdd={handleAdd}
+            onRemove={handleRemove}
+            onReorder={handleReorder}
+            addButtonText="Add New Item"
+            emptyStateText="No items yet. Click below to add one."
+            maxItems={10}
+            minItems={1}
+        />
+    );
+}
+```
+
+## Collapsible items
+
+Pass `collapsible` to show a header row with an expand/collapse control. Use `renderSummary` for whatever should stay visible when the item is closed (name, enable toggle, badge, etc.). `renderItem` is only mounted while the item is expanded.
+
+Existing items start collapsed (`defaultExpanded={false}`). A single newly added item starts open (`expandNewItems`). Drag overlay shows the collapsed header only.
+
+When `collapsible` is on, Repeater owns the header chrome (drag handle, chevron, remove). Put interactive header content in `renderSummary` — do not place `DragHandle` or `RemoveButton` there.
+
+```jsx
+<Repeater
+    items={items}
+    collapsible
+    enableReorder={false}
+    renderSummary={(item) => (
+        <>
+            <ToggleControl
+                __nextHasNoMarginBottom
+                label=""
+                checked={item.enabled}
+                onChange={(enabled) => updateItem(item.id, { enabled })}
+            />
+            <span className="built-repeater__summary-name">
+                {item.name || "Untitled"}
+            </span>
+        </>
+    )}
+    renderItem={(item) => (
+        <TextControl
+            label="Name"
+            value={item.name}
+            onChange={(name) => updateItem(item.id, { name })}
+        />
+    )}
+    onAdd={handleAdd}
+    onRemove={handleRemove}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Array` | `[]` | Array of items with unique `id` property |
+| `renderItem` | `Function` | Required | Function to render each item's content. Receives `(item, index)`. When `collapsible` is true, this is the expanded body only. |
+| `onAdd` | `Function` | Required | Callback when add button is clicked |
+| `onRemove` | `Function` | Required | Callback when remove button is clicked |
+| `onReorder` | `Function` | Required | Callback when items are reordered |
+| `className` | `String` | `""` | Additional CSS classes |
+| `addButtonText` | `String` | `"Add Item"` | Text for the add button |
+| `emptyStateText` | `String` | `"No items added yet..."` | Text shown when list is empty |
+| `maxItems` | `Number` | `null` | Maximum number of items allowed |
+| `minItems` | `Number` | `0` | Minimum number of items required |
+| `renderMode` | `String` | `"default"` | `"default"` uses built-in drag/remove chrome. `"integrated"` lets `renderItem` place `DragHandle` and `RemoveButton`. Ignored when `collapsible` is true. |
+| `enableReorder` | `Boolean` | `true` | Whether items can be dragged to reorder. Set to `false` for lists where order doesn't matter (e.g. a set of find/replace pairs) — no drag handle renders, and `onReorder` is not required. |
+| `collapsible` | `Boolean` | `false` | Collapse each item behind a header. Existing callers omit this and keep always-open rows. |
+| `renderSummary` | `Function` | `null` | Header content shown while collapsed (and still shown while expanded). Receives `(item, index)`. |
+| `defaultExpanded` | `Boolean` | `false` | When `collapsible`, existing items start expanded. |
+| `expandNewItems` | `Boolean` | `true` | When `collapsible`, a single newly added item starts expanded. |
+
+## Keyboard Shortcuts
+
+- **Tab**: Navigate between items and controls
+- **Space/Enter**: Activate drag handle
+- **Arrow Keys**: Move item up/down when dragging
+- **Escape**: Cancel drag operation
+
+## Styling
+
+The component provides these CSS classes for customization:
+
+- `.wpcl-repeater--collapsible` - Root class when `collapsible` is true
+- `.wpcl-repeater__item--dragging` - Applied to the placeholder while an item is being dragged
+- `.wpcl-repeater__item--integrated` - Applied in integrated render mode
+- `.wpcl-repeater__item--collapsible` - Collapsible item (header + optional body)
+- `.wpcl-repeater__item--expanded` - Collapsible item that is currently open
+- `.built-repeater__items` - Items container
+- `.built-repeater__item-handle` - Drag handle
+- `.built-repeater__item-header` - Collapsible header row
+- `.built-repeater__item-toggle` - Expand/collapse button
+- `.built-repeater__summary` - Always-visible header content
+- `.built-repeater__summary-name` - Optional truncated label in the header
+- `.built-repeater__item-content` - Item content area
+- `.built-repeater__item-actions` - Action buttons area
+- `.built-repeater__empty-state` - Empty state message
+- `.built-repeater__add-button` - Add button container