@siratik/wp-component-library 0.1.1 → 0.1.3

package/components/media/image-controls.js

@@ -0,0 +1,196 @@
+import {
+	Flex,
+	FlexBlock,
+	SelectControl,
+	ToggleControl,
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
+	__experimentalToolsPanel as ToolsPanel,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	__experimentalUnitControl as UnitControl,
+} from "@wordpress/components";
+import { useSelect } from "@wordpress/data";
+import { __ } from "@wordpress/i18n";
+
+import { useAspectRatioOptions } from "./utils/aspect-ratios";
+
+/**
+ * Reusable image controls for aspect ratio, width, height, scale, and caption.
+ * @param {object} props
+ * @param {string} props.aspectRatio
+ * @param {string} props.width
+ * @param {string} props.height
+ * @param {boolean} props.showCaption
+ * @param {string} props.scale - Object-fit value: "cover" or "contain".
+ * @param {function} props.setAttributes
+ */
+const SCALE_HELP = {
+	cover: __("Image covers the space evenly.", "wp-component-library"),
+	contain: __("Image is contained without cropping.", "wp-component-library"),
+};
+
+const ImageControls = ({
+	aspectRatio = "4/3",
+	width = "auto",
+	height = "auto",
+	showCaption = false,
+	scale = "cover",
+	imageSize = "",
+	setAttributes,
+}) => {
+	// Get aspect ratio options from theme.json
+	const aspectRatioOptions = useAspectRatioOptions();
+
+	// Build resolution options from registered image sizes
+	const imageSizeOptions = useSelect((select) => {
+		const sizes = select("core/block-editor").getSettings().imageSizes || [];
+		return [
+			{ value: "", label: __("Auto", "wp-component-library") },
+			...sizes.map(({ name, slug }) => ({ value: slug, label: name })),
+		];
+	}, []);
+
+	const resetAllFilter = (newAttributes) => {
+		return {
+			...newAttributes,
+			aspectRatio: "4/3",
+			width: "auto",
+			height: "auto",
+			showCaption: false,
+			scale: "cover",
+			imageSize: "",
+		};
+	};
+
+	return (
+		<ToolsPanel
+			label={__("Image Settings", "wp-component-library")}
+			resetAllFilter={resetAllFilter}
+			panelId="image-settings"
+		>
+			<ToolsPanelItem
+				hasValue={() => aspectRatio !== "4/3"}
+				label={__("Aspect Ratio", "wp-component-library")}
+				onDeselect={() => setAttributes({ aspectRatio: "4/3" })}
+				resetAllFilter={resetAllFilter}
+				isShownByDefault
+				panelId="image-settings"
+			>
+				<SelectControl
+					__nextHasNoMarginBottom={true}
+					__next40pxDefaultSize
+					label={__("Aspect Ratio", "wp-component-library")}
+					value={aspectRatio}
+					onChange={(value) => setAttributes({ aspectRatio: value })}
+					options={aspectRatioOptions}
+				/>
+			</ToolsPanelItem>
+
+			<ToolsPanelItem
+				hasValue={() => scale !== "cover"}
+				label={__("Scale", "wp-component-library")}
+				onDeselect={() => setAttributes({ scale: "cover" })}
+				resetAllFilter={resetAllFilter}
+				isShownByDefault
+				panelId="image-settings"
+			>
+				<ToggleGroupControl
+					__nextHasNoMarginBottom={true}
+					__next40pxDefaultSize
+					label={__("Scale", "wp-component-library")}
+					value={scale}
+					onChange={(value) => setAttributes({ scale: value })}
+					isBlock
+					help={SCALE_HELP[scale] ?? ""}
+				>
+					<ToggleGroupControlOption
+						value="cover"
+						label={__("Cover", "wp-component-library")}
+					/>
+					<ToggleGroupControlOption
+						value="contain"
+						label={__("Contain", "wp-component-library")}
+					/>
+				</ToggleGroupControl>
+			</ToolsPanelItem>
+
+			<Flex gap={4} style={{ minWidth: 250 }}>
+				<FlexBlock>
+					<ToolsPanelItem
+						hasValue={() => width !== "auto"}
+						label={__("Width", "wp-component-library")}
+						onDeselect={() => setAttributes({ width: "auto" })}
+						resetAllFilter={resetAllFilter}
+						panelId="image-settings"
+					>
+						<UnitControl
+							__next40pxDefaultSize
+							label={__("Width", "wp-component-library")}
+							onChange={(value) =>
+								setAttributes({ width: value })
+							}
+							value={width}
+							placeholder={__("Auto", "wp-component-library")}
+						/>
+					</ToolsPanelItem>
+				</FlexBlock>
+				<FlexBlock>
+					<ToolsPanelItem
+						hasValue={() => height !== "auto"}
+						label={__("Height", "wp-component-library")}
+						onDeselect={() => setAttributes({ height: "auto" })}
+						resetAllFilter={resetAllFilter}
+						panelId="image-settings"
+					>
+						<UnitControl
+							__next40pxDefaultSize
+							label={__("Height", "wp-component-library")}
+							onChange={(value) =>
+								setAttributes({ height: value })
+							}
+							value={height}
+							placeholder={__("Auto", "wp-component-library")}
+						/>
+					</ToolsPanelItem>
+				</FlexBlock>
+			</Flex>
+
+			<ToolsPanelItem
+				hasValue={() => showCaption !== false}
+				label={__("Show Caption", "wp-component-library")}
+				onDeselect={() => setAttributes({ showCaption: false })}
+				resetAllFilter={resetAllFilter}
+				isShownByDefault={false}
+				panelId="image-settings"
+			>
+				<ToggleControl
+					__nextHasNoMarginBottom={true}
+					label={__("Show Caption", "wp-component-library")}
+					checked={showCaption}
+					onChange={(value) => setAttributes({ showCaption: value })}
+				/>
+			</ToolsPanelItem>
+
+			<ToolsPanelItem
+				hasValue={() => !!imageSize}
+				label={__("Resolution", "wp-component-library")}
+				onDeselect={() => setAttributes({ imageSize: "" })}
+				resetAllFilter={resetAllFilter}
+				isShownByDefault={false}
+				panelId="image-settings"
+			>
+				<SelectControl
+					__nextHasNoMarginBottom={true}
+					__next40pxDefaultSize
+					label={__("Resolution", "wp-component-library")}
+					value={imageSize}
+					options={imageSizeOptions}
+					onChange={(value) => setAttributes({ imageSize: value })}
+					help={__("Override the default image resolution. Leave as Auto for smart sizing.", "wp-component-library")}
+				/>
+			</ToolsPanelItem>
+		</ToolsPanel>
+	);
+};
+
+export { ImageControls };

package/components/media/index.js

@@ -0,0 +1,13 @@
+/**
+ * Media Upload Components
+ *
+ * A collection of media upload components for different contexts
+ * within the WordPress block editor and admin settings.
+ */
+
+// Re-export individual media upload components
+export { EditorMediaUpload } from "./editor-media-upload";
+export { ImageControls } from "./image-controls";
+export { InspectorMediaUpload } from "./inspector-media-upload";
+export { SettingsMediaUpload } from "./SettingsMediaUpload";
+export { ToolbarMediaUpload } from "./toolbar-media-upload";

package/components/media/inspector-media-upload.js

@@ -0,0 +1,290 @@
+/**
+ * Inspector Media Upload Component
+ *
+ * Uses wp.media() directly instead of the block editor's MediaUpload
+ * slot, ensuring it works on both block editor and settings pages.
+ */
+import styled from "@emotion/styled";
+import { BaseControl, Button, Flex, Placeholder } from "@wordpress/components";
+import { useCallback } from "@wordpress/element";
+import { __ } from "@wordpress/i18n";
+import { AttachmentImage } from "../attachment-image";
+
+/**
+ * "auto", a number ("1.91") or a ratio ("16/9", "16 / 9").
+ */
+const ASPECT_RATIO_PATTERN = /^(auto|\d+(\.\d+)?(\s*\/\s*\d+(\.\d+)?)?)$/;
+
+/**
+ * A number with an optional length unit ("400", "64px", "20rem", "50%").
+ */
+const MAX_WIDTH_PATTERN = /^\d+(\.\d+)?(px|em|rem|%|vw|ch)?$/;
+
+/**
+ * CSS aspect-ratio accepts a number (e.g. 1.91) or a ratio string ("16/9").
+ * Anything else falls back to 16/9, so a prop value can never add CSS rules.
+ *
+ * @param {number|string} ratio
+ * @returns {string}
+ */
+function toCssAspectRatio(ratio) {
+	if (typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0) {
+		return String(ratio);
+	}
+	if (typeof ratio === "string" && ASPECT_RATIO_PATTERN.test(ratio.trim())) {
+		return ratio.trim();
+	}
+	return String(16 / 9);
+}
+
+/**
+ * CSS max-width for the preview (number = px; empty or invalid = none).
+ *
+ * @param {number|string|null} maxWidth
+ * @returns {string}
+ */
+function toCssMaxWidth(maxWidth) {
+	if (typeof maxWidth === "number" && Number.isFinite(maxWidth) && maxWidth >= 0) {
+		return `${maxWidth}px`;
+	}
+	if (typeof maxWidth === "string" && MAX_WIDTH_PATTERN.test(maxWidth.trim())) {
+		return maxWidth.trim();
+	}
+	return "none";
+}
+
+// Styled components
+const StyledWrapper = styled.div`
+	max-width: ${(props) => toCssMaxWidth(props.maxWidth)};
+
+	/* Shared frame so placeholder and selected image occupy the same box. */
+	.built-inspector-media-preview {
+		width: 100%;
+		aspect-ratio: ${(props) => props.$aspectRatio};
+		overflow: hidden;
+		box-sizing: border-box;
+		background: #f0f0f0;
+	}
+
+	.built-inspector-media-preview .components-placeholder {
+		width: 100%;
+		height: 100%;
+		min-height: 0 !important;
+		margin: 0;
+		padding: 0;
+		box-sizing: border-box;
+	}
+
+	.built-inspector-media-preview img {
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+		object-position: center;
+		display: block;
+	}
+`;
+
+const StyledImageContainer = styled.div`
+	width: 100%;
+	height: 100%;
+
+	.components-flex {
+		height: auto;
+	}
+`;
+
+const StyledActions = styled.div`
+	margin-top: 12px;
+`;
+
+const ALLOWED_MEDIA_TYPES = ["image"];
+
+/**
+ * Hook to open the native wp.media frame.
+ */
+function useMediaOpen({ onSelect, multiple, allowedTypes }) {
+	return useCallback(() => {
+		if (typeof wp === "undefined" || !wp.media) { return; }
+
+		const frame = wp.media({
+			title: __("Select or Upload Media", "wp-component-library"),
+			multiple: multiple || false,
+			library: { type: allowedTypes || ["image"] },
+			button: { text: __("Select", "wp-component-library") },
+		});
+
+		frame.on("select", () => {
+			const selection = frame.state().get("selection");
+			if (multiple) {
+				onSelect(selection.map((att) => att.toJSON()));
+			} else {
+				onSelect(selection.first().toJSON());
+			}
+		});
+
+		frame.open();
+	}, [onSelect, multiple, allowedTypes]);
+}
+
+/**
+ * Inspector Media Upload
+ *
+ * @param {object} props
+ * @param {number|string|null} [props.maxWidth] Optional max width for the
+ *   preview/placeholder (number = px). Default: none (full width).
+ * @param {number|string} [props.aspectRatio=16/9] Locked preview box ratio;
+ *   selected images use object-fit: cover inside the same box as the placeholder.
+ * @returns {JSX.Element}
+ */
+function InspectorMediaUpload({
+	mediaIDs,
+	onSelect,
+	onRemove,
+	multiple,
+	buttonTitle,
+	variant,
+	showFeatureImage = false,
+	featureImage = null,
+	label = null,
+	help = null,
+	showImagePlaceholder,
+	aspectRatio = 16 / 9,
+	maxWidth = null,
+}) {
+	// Handle ID, [id], and attachment object formats for mediaIDs.
+	const getMediaId = (mediaData) => {
+		if (!mediaData) { return null; }
+		if (typeof mediaData === "number") { return mediaData; }
+		if (typeof mediaData === "string" && /^\d+$/.test(mediaData)) {
+			return parseInt(mediaData, 10);
+		}
+		if (Array.isArray(mediaData)) {
+			return getMediaId(mediaData[0]);
+		}
+		if (typeof mediaData === "object" && mediaData.id) { return mediaData.id; }
+		return null;
+	};
+
+	const mediaId = getMediaId(mediaIDs);
+	const hasImage = !!mediaId;
+	const hasFeatureImage = !!(
+		showFeatureImage &&
+		featureImage &&
+		featureImage !== 0
+	);
+	const cssAspectRatio = toCssAspectRatio(aspectRatio);
+
+	// Generate a unique ID for BaseControl
+	const controlId = `inspector-media-upload-${mediaId || "new"}`;
+
+	// Open native wp.media frame
+	const openMedia = useMediaOpen({
+		onSelect,
+		multiple,
+		allowedTypes: ALLOWED_MEDIA_TYPES,
+	});
+
+	const imageDisplay = (
+		<>
+			{showImagePlaceholder && !hasImage && !hasFeatureImage && (
+				<div className="built-inspector-media-preview">
+					<Placeholder
+						withIllustration={true}
+						className="built-editor-panel-image placeholder-image placeholder-image--built"
+					/>
+				</div>
+			)}
+
+			{showImagePlaceholder && hasImage && (
+				<div className="built-inspector-media-preview">
+					<StyledImageContainer className="built-editor-panel-image">
+						<AttachmentImage
+							className="built-editor-panel-image"
+							imageId={mediaId}
+							size="wide_medium"
+							includeFigure={false}
+							aspectRatio={cssAspectRatio}
+						/>
+					</StyledImageContainer>
+				</div>
+			)}
+
+			{showImagePlaceholder && hasFeatureImage && !hasImage && (
+				<div className="built-inspector-media-preview">
+					<StyledImageContainer className="built-editor-panel-image">
+						<AttachmentImage
+							className="built-editor-panel-image"
+							imageId={featureImage.id || featureImage}
+							size="wide_medium"
+							includeFigure={false}
+							aspectRatio={cssAspectRatio}
+						/>
+					</StyledImageContainer>
+				</div>
+			)}
+		</>
+	);
+
+	const buttons = (
+		<StyledActions>
+			{!hasImage ? (
+				<Button
+					__next40pxDefaultSize
+					className="is-full-width"
+					size="default"
+					variant={variant || "secondary"}
+					onClick={openMedia}
+				>
+					{buttonTitle ||
+						__("Select or Upload Media", "wp-component-library")}
+				</Button>
+			) : (
+				<Flex>
+					<Button
+						__next40pxDefaultSize
+						size="default"
+						className="is-full-width"
+						variant="secondary"
+						onClick={openMedia}
+					>
+						{__("Edit/Replace", "wp-component-library")}
+					</Button>
+					<Button
+						__next40pxDefaultSize
+						size="default"
+						variant="secondary"
+						className="is-full-width"
+						onClick={onRemove}
+						isDestructive
+					>
+						{__("Remove", "wp-component-library")}
+					</Button>
+				</Flex>
+			)}
+		</StyledActions>
+	);
+
+	// If label or help text is provided, wrap in BaseControl
+	if (label || help) {
+		return (
+			<StyledWrapper maxWidth={maxWidth} $aspectRatio={cssAspectRatio}>
+				<BaseControl id={controlId} label={label} help={help}>
+					{imageDisplay}
+				</BaseControl>
+				{buttons}
+			</StyledWrapper>
+		);
+	}
+
+	// Otherwise, return controls without BaseControl wrapper
+	return (
+		<StyledWrapper maxWidth={maxWidth} $aspectRatio={cssAspectRatio}>
+			<Flex direction="column" expanded={true} style={{ flexGrow: 1 }}>
+				{imageDisplay}
+				{buttons}
+			</Flex>
+		</StyledWrapper>
+	);
+}
+
+export { InspectorMediaUpload };

package/components/media/toolbar-media-upload.js

@@ -0,0 +1,53 @@
+/**
+ * Toolbar Media Upload Component
+ */
+import { MediaUpload, MediaUploadCheck } from "@wordpress/block-editor";
+import { ToolbarButton } from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+import { pencil } from "@wordpress/icons";
+
+const ALLOWED_MEDIA_TYPES = ["image"];
+
+/**
+ * Toolbar Media Upload
+ *
+ * @param {object} props
+ * @returns {JSX.Element}
+ */
+function ToolbarMediaUpload({
+    mediaIDs,
+    onSelect,
+    gallery,
+    multiple,
+}) {
+    // Handle both ID and object formats for mediaIDs
+    const getMediaId = (mediaData) => {
+        if (!mediaData) { return null; }
+        if (typeof mediaData === "number") { return mediaData; }
+        if (typeof mediaData === "object" && mediaData.id) { return mediaData.id; }
+        return null;
+    };
+
+    const mediaId = getMediaId(mediaIDs);
+
+    return (
+        <MediaUploadCheck>
+            <MediaUpload
+                onSelect={onSelect}
+                allowedTypes={ALLOWED_MEDIA_TYPES}
+                value={mediaId}
+                render={({ open }) => (
+                    <ToolbarButton
+                        icon={pencil}
+                        label={__("Edit/Replace Media", "wp-component-library")}
+                        onClick={open}
+                    />
+                )}
+                gallery={gallery}
+                multiple={multiple}
+            />
+        </MediaUploadCheck>
+    );
+}
+
+export { ToolbarMediaUpload };

package/components/media/utils/aspect-ratios.js

@@ -0,0 +1,118 @@
+import { useSettings } from "@wordpress/block-editor";
+import { useMemo } from "@wordpress/element";
+import { __ } from "@wordpress/i18n";
+
+/**
+ * WordPress core aspect ratio presets (when theme enables defaultAspectRatios).
+ * @see https://developer.wordpress.org/news/2024/08/registering-custom-aspect-ratios-in-wordpress-6-6/
+ */
+const getDefaultCoreAspectRatios = () => [
+	{ name: __("Square", "wp-component-library"), ratio: "1" },
+	{ name: __("Standard", "wp-component-library"), ratio: "4/3" },
+	{ name: __("Portrait", "wp-component-library"), ratio: "3/4" },
+	{ name: __("Classic", "wp-component-library"), ratio: "3/2" },
+	{ name: __("Classic Portrait", "wp-component-library"), ratio: "2/3" },
+	{ name: __("Wide", "wp-component-library"), ratio: "16/9" },
+	{ name: __("Extra Wide", "wp-component-library"), ratio: "21/9" },
+	{ name: __("Tall", "wp-component-library"), ratio: "9/16" },
+];
+
+/**
+ * Flatten aspect ratio presets from useSettings (array or { default, theme } object).
+ *
+ * @param {unknown} setting
+ * @return {Array<{ name: string, ratio: string }>}
+ */
+function collectAspectRatioPresets(setting) {
+	if (!setting) {
+		return [];
+	}
+
+	if (Array.isArray(setting)) {
+		return setting;
+	}
+
+	if (typeof setting !== "object") {
+		return [];
+	}
+
+	const merged = [];
+
+	for (const key of ["default", "theme", "custom"]) {
+		if (Array.isArray(setting[key])) {
+			merged.push(...setting[key]);
+		}
+	}
+
+	return merged;
+}
+
+/**
+ * Hook to get aspect ratio options from theme.json
+ * Returns whatever aspect ratios are defined (default or custom)
+ * Includes "Original" option like core/image block
+ */
+export function useAspectRatioOptions() {
+	const [
+		aspectRatiosSetting,
+		defaultPresets,
+		themePresets,
+		defaultAspectRatiosEnabled,
+	] = useSettings([
+		"dimensions.aspectRatios",
+		"dimensions.aspectRatios.default",
+		"dimensions.aspectRatios.theme",
+		"dimensions.defaultAspectRatios",
+	]);
+
+	return useMemo(() => {
+		const originalOption = {
+			label: __("Original", "wp-component-library"),
+			value: "original",
+		};
+
+		let presets = [
+			...collectAspectRatioPresets(aspectRatiosSetting),
+			...collectAspectRatioPresets(defaultPresets),
+			...collectAspectRatioPresets(themePresets),
+		];
+
+		// Deduplicate by ratio value.
+		const seen = new Set();
+		presets = presets.filter((ratio) => {
+			if (
+				!ratio ||
+				typeof ratio !== "object" ||
+				!ratio.name ||
+				!ratio.ratio
+			) {
+				return false;
+			}
+			if (seen.has(ratio.ratio)) {
+				return false;
+			}
+			seen.add(ratio.ratio);
+			return true;
+		});
+
+		if (presets.length === 0 && defaultAspectRatiosEnabled !== false) {
+			presets = getDefaultCoreAspectRatios();
+		}
+
+		const ratioOptions = presets
+			.filter(
+				(ratio) => ratio.ratio !== "original" && ratio.ratio !== "auto",
+			)
+			.map((ratio) => ({
+				label: ratio.name,
+				value: ratio.ratio,
+			}));
+
+		return [originalOption, ...ratioOptions];
+	}, [
+		aspectRatiosSetting,
+		defaultPresets,
+		themePresets,
+		defaultAspectRatiosEnabled,
+	]);
+}