@wordpress/media-fields 0.1.1-next.6deb34194.0

package/src/media_thumbnail/view.tsx

@@ -0,0 +1,104 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { store as coreStore } from '@wordpress/core-data';
+import {
+	__experimentalTruncate as Truncate,
+	__experimentalVStack as VStack,
+	Icon,
+} from '@wordpress/components';
+import type { Attachment } from '@wordpress/core-data';
+import { getFilename } from '@wordpress/url';
+import type { DataViewRenderFieldProps } from '@wordpress/dataviews';
+/**
+ * Internal dependencies
+ */
+import { getMediaTypeFromMimeType } from '../utils/get-media-type-from-mime-type';
+import type { MediaItem } from '../types';
+
+export default function MediaThumbnailView( {
+	item,
+	config,
+}: DataViewRenderFieldProps< MediaItem > ) {
+	const _featuredMedia = useSelect(
+		( select ) => {
+			// Avoid the network request if it's not needed. `featured_media` is
+			// 0 for images and media without featured media.
+			if ( ! item.featured_media ) {
+				return;
+			}
+			return select( coreStore ).getEntityRecord< Attachment >(
+				'postType',
+				'attachment',
+				item.featured_media
+			);
+		},
+		[ item.featured_media ]
+	);
+	const featuredMedia = item.featured_media ? _featuredMedia : item;
+
+	// Fetching.
+	if ( ! featuredMedia ) {
+		return null;
+	}
+
+	const filename = getFilename( featuredMedia.source_url || '' );
+
+	if (
+		// Ensure the featured media is an image.
+		getMediaTypeFromMimeType( featuredMedia.mime_type ).type === 'image'
+	) {
+		return (
+			<div className="dataviews-media-field__media-thumbnail">
+				<img
+					className="dataviews-media-field__media-thumbnail--image"
+					src={ featuredMedia.source_url }
+					srcSet={
+						featuredMedia?.media_details?.sizes
+							? (
+									Object.values(
+										featuredMedia.media_details.sizes
+									) as Array< {
+										source_url: string;
+										width: number;
+									} >
+							   )
+									.map(
+										( size ) =>
+											`${ size.source_url } ${ size.width }w`
+									)
+									.join( ', ' )
+							: undefined
+					}
+					sizes={ config?.sizes || '100vw' }
+					alt={ featuredMedia.alt_text || featuredMedia.title.raw }
+				/>
+			</div>
+		);
+	}
+
+	return (
+		<div className="dataviews-media-field__media-thumbnail">
+			<VStack
+				justify="center"
+				alignment="center"
+				className="dataviews-media-field__media-thumbnail__stack"
+				spacing={ 0 }
+			>
+				<Icon
+					className="dataviews-media-field__media-thumbnail--icon"
+					icon={ getMediaTypeFromMimeType( item.mime_type ).icon }
+					size={ 24 }
+				/>
+				{ !! filename && (
+					<div className="dataviews-media-field__media-thumbnail__filename">
+						<Truncate className="dataviews-media-field__media-thumbnail__filename__truncate">
+							{ filename }
+						</Truncate>
+					</div>
+				) }
+			</VStack>
+		</div>
+	);
+}

package/src/mime_type/index.ts

@@ -0,0 +1,19 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import type { Attachment, Updatable } from '@wordpress/core-data';
+import type { Field } from '@wordpress/dataviews';
+
+const mimeTypeField: Partial< Field< Updatable< Attachment > > > = {
+	id: 'mime_type',
+	type: 'text',
+	label: __( 'File type' ),
+	getValue: ( { item } ) => item?.mime_type || '',
+	render: ( { item } ) => item?.mime_type || '-',
+	enableSorting: true,
+	filterBy: false,
+	readOnly: true,
+};
+
+export default mimeTypeField;

package/src/stories/index.story.tsx

@@ -0,0 +1,290 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import { DataForm, DataViews, type Form } from '@wordpress/dataviews';
+import type { Field, View } from '@wordpress/dataviews';
+
+/**
+ * Internal dependencies
+ */
+import {
+	altTextField,
+	captionField,
+	descriptionField,
+	filenameField,
+	filesizeField,
+	mediaDimensionsField,
+	mediaThumbnailField,
+	mimeTypeField,
+	type MediaItem,
+} from '../index';
+
+export default {
+	title: 'Fields/Media Fields',
+	component: DataForm,
+};
+
+// Sample data for media fields
+const sampleMediaItem: MediaItem = {
+	id: 123,
+	date: '2024-01-15T10:30:00',
+	date_gmt: '2024-01-15T10:30:00',
+	guid: {
+		raw: 'https://cldup.com/cXyG__fTLN.jpg',
+		rendered: 'https://cldup.com/cXyG__fTLN.jpg',
+	},
+	modified: '2024-01-15T10:30:00',
+	modified_gmt: '2024-01-15T10:30:00',
+	slug: 'sample-image',
+	status: 'publish',
+	type: 'attachment',
+	link: 'https://example.com/sample-image/',
+	title: {
+		raw: 'Sample Image',
+		rendered: 'Sample Image',
+	},
+	author: 1,
+	featured_media: 0,
+	comment_status: 'open',
+	ping_status: 'closed',
+	template: '',
+	meta: {},
+	permalink_template: 'https://example.com/?attachment_id=123',
+	generated_slug: 'sample-image',
+	class_list: [ 'post-123', 'attachment' ],
+	alt_text: 'A beautiful sample image',
+	caption: {
+		raw: 'A caption for the image',
+		rendered: '<p>A caption for the image</p>\n',
+	},
+	description: {
+		raw: 'This is a detailed description of the sample image. It contains useful information about what the image depicts and its context.',
+		rendered:
+			'<p>This is a detailed description of the sample image. It contains useful information about what the image depicts and its context.</p>',
+	},
+	mime_type: 'image/jpeg',
+	media_type: 'image',
+	post: null,
+	source_url: 'https://cldup.com/cXyG__fTLN.jpg',
+	media_details: {
+		file: 'sample-image.jpg',
+		width: 1920,
+		height: 1080,
+		filesize: 524288,
+		image_meta: {
+			aperture: '2.8',
+			credit: '',
+			camera: 'Sample Camera',
+			caption: '',
+			created_timestamp: '1705315800',
+			copyright: '',
+			focal_length: '50',
+			iso: '100',
+			shutter_speed: '0.004',
+			title: '',
+			orientation: '1',
+			keywords: [],
+		},
+		sizes: {
+			thumbnail: {
+				file: 'sample-image-150x150.jpg',
+				width: 150,
+				height: 150,
+				filesize: 8192,
+				mime_type: 'image/jpeg',
+				source_url: 'https://cldup.com/cXyG__fTLN.jpg',
+			},
+			medium: {
+				file: 'sample-image-300x169.jpg',
+				width: 300,
+				height: 169,
+				filesize: 24576,
+				mime_type: 'image/jpeg',
+				source_url: 'https://cldup.com/cXyG__fTLN.jpg',
+			},
+		},
+	},
+	missing_image_sizes: [],
+};
+
+// Sample data for a non-image file (ZIP)
+const sampleMediaItemZip: MediaItem = {
+	id: 101,
+	date: '2025-11-07T00:28:54',
+	date_gmt: '2025-11-07T00:28:54',
+	guid: {
+		raw: 'http://localhost:8888/wp-content/uploads/2025/11/gutenberg-v22-0-0.zip',
+		rendered:
+			'http://localhost:8888/wp-content/uploads/2025/11/gutenberg-v22-0-0.zip',
+	},
+	modified: '2025-11-07T00:28:54',
+	modified_gmt: '2025-11-07T00:28:54',
+	slug: 'gutenberg-v22-0-0',
+	status: 'publish',
+	type: 'attachment',
+	link: 'http://localhost:8888/gutenberg-v22-0-0/',
+	title: {
+		raw: 'gutenberg-v22-0-0',
+		rendered: 'gutenberg-v22-0-0',
+	},
+	author: 1,
+	featured_media: 0,
+	comment_status: 'open',
+	ping_status: 'closed',
+	template: '',
+	meta: {},
+	permalink_template: 'http://localhost:8888/?attachment_id=101',
+	generated_slug: 'gutenberg-v22-0-0',
+	class_list: [ 'post-101', 'attachment' ],
+	alt_text: '',
+	caption: {
+		raw: '',
+		rendered: '<p>gutenberg-v22-0-0</p>\n',
+	},
+	description: {
+		raw: '',
+		rendered: '',
+	},
+	mime_type: 'application/zip',
+	media_type: 'file',
+	post: 1,
+	source_url:
+		'http://localhost:8888/wp-content/uploads/2025/11/gutenberg-v22-0-0.zip',
+	media_details: {
+		file: 'gutenberg-v22-0-0.zip',
+		filesize: 19988723,
+		width: 0,
+		height: 0,
+		image_meta: {
+			aperture: '',
+			credit: '',
+			camera: '',
+			caption: '',
+			created_timestamp: '',
+			copyright: '',
+			focal_length: '',
+			iso: '',
+			shutter_speed: '',
+			title: '',
+			orientation: '',
+			keywords: [],
+		},
+		sizes: {},
+	},
+	missing_image_sizes: [],
+};
+
+// Create a showcase of all media fields.
+const showcaseFields = [
+	mediaThumbnailField,
+	filenameField,
+	altTextField,
+	captionField,
+	descriptionField,
+	mimeTypeField,
+	mediaDimensionsField,
+	filesizeField,
+] as Field< any >[];
+
+const DataFormsComponent = ( { type }: { type: 'regular' | 'panel' } ) => {
+	const [ data, setData ] = useState< MediaItem >( sampleMediaItem );
+
+	const handleChange = ( updates: Partial< MediaItem > ) => {
+		setData( ( prev: MediaItem ) => ( { ...prev, ...updates } ) );
+	};
+
+	// Form configuration for the media fields showcase.
+	const showcaseForm: Form = {
+		layout: {
+			type,
+		},
+		fields: [
+			'media_thumbnail',
+			'alt_text',
+			'caption',
+			'description',
+			'filename',
+			'mime_type',
+			'media_dimensions',
+			'filesize',
+		],
+	};
+
+	return (
+		<div style={ { padding: '20px' } }>
+			<h2>Media Fields</h2>
+			<p>
+				This story demonstrates all the media fields from the
+				@wordpress/media-fields package within a DataForm.
+			</p>
+
+			<DataForm
+				data={ data }
+				fields={ showcaseFields }
+				form={ showcaseForm }
+				onChange={ handleChange }
+			/>
+		</div>
+	);
+};
+
+export const DataFormsPreview = {
+	render: DataFormsComponent,
+	argTypes: {
+		type: {
+			control: { type: 'select' },
+			description: 'Choose the layout type.',
+			options: [ 'regular', 'panel' ],
+		},
+	},
+	args: {
+		type: 'regular',
+	},
+};
+
+export const DataViewsPreview = () => {
+	const [ view, setView ] = useState< View >( {
+		type: 'table',
+		fields: showcaseFields
+			.map( ( f ) => f.id )
+			.filter( ( id ) => id !== 'media_thumbnail' ),
+		descriptionField: undefined,
+		mediaField: 'media_thumbnail',
+		showTitle: false,
+	} );
+	const [ data ] = useState< MediaItem[] >( [
+		sampleMediaItem,
+		sampleMediaItemZip,
+	] );
+
+	const paginationInfo = {
+		totalItems: 2,
+		totalPages: 1,
+	};
+
+	const defaultLayouts = {
+		table: {},
+		list: {},
+		grid: {},
+	};
+
+	return (
+		<div style={ { padding: '20px' } }>
+			<h2>Media Fields DataViews Preview</h2>
+			<p>
+				This story demonstrates all the media fields from the
+				@wordpress/media-fields package, rendered in a DataViews
+				component, allowing preview of view state and layout switching.
+			</p>
+			<DataViews
+				data={ data }
+				fields={ showcaseFields }
+				view={ view }
+				onChangeView={ ( nextView: View ) => setView( nextView ) }
+				paginationInfo={ paginationInfo }
+				defaultLayouts={ defaultLayouts }
+			/>
+		</div>
+	);
+};

package/src/style.scss

@@ -0,0 +1 @@
+@use "./media_thumbnail/style.scss" as *;

package/src/types.ts

@@ -0,0 +1,24 @@
+/**
+ * WordPress dependencies
+ */
+import type { Attachment, Updatable, Post } from '@wordpress/core-data';
+
+export type MediaKind = 'image' | 'video' | 'audio' | 'application';
+
+export interface MediaType {
+	type: MediaKind;
+	label: string;
+	icon: JSX.Element;
+}
+
+// TODO: Update the Attachment type separately.
+export interface MediaItem extends Attachment< 'edit' > {
+	// featured_media is not in the Attachment type. See https://github.com/WordPress/gutenberg/blob/trunk/packages/core-data/src/entity-types/attachment.ts#L10
+	featured_media: number;
+	_embedded?: {
+		// TODO: Include wp:attached-to properly, and backport PHP changes from wordpress-develop to support this.
+		'wp:attached-to'?: Post[] | Partial< Post >[];
+	};
+}
+
+export type MediaItemUpdatable = Updatable< Attachment >;

package/src/utils/get-media-type-from-mime-type.ts

@@ -0,0 +1,54 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { audio, video, image, file } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import type { MediaType } from '../types';
+
+/**
+ * Get the media type from a mime type, including an icon.
+ * TODO - media types should be formalized somewhere.
+ *
+ * References:
+ * https://developer.wordpress.org/reference/functions/wp_mime_type_icon/
+ * https://developer.wordpress.org/reference/hooks/mime_types/
+ * https://developer.wordpress.org/reference/functions/wp_get_mime_types/
+ *
+ * @param mimeType - The mime type to get the media type from.
+ * @return The media type.
+ */
+export function getMediaTypeFromMimeType( mimeType: string ): MediaType {
+	if ( mimeType.startsWith( 'image/' ) ) {
+		return {
+			type: 'image',
+			label: __( 'Image' ),
+			icon: image,
+		};
+	}
+
+	if ( mimeType.startsWith( 'video/' ) ) {
+		return {
+			type: 'video',
+			label: __( 'Video' ),
+			icon: video,
+		};
+	}
+
+	if ( mimeType.startsWith( 'audio/' ) ) {
+		return {
+			type: 'audio',
+			label: __( 'Audio' ),
+			icon: audio,
+		};
+	}
+
+	return {
+		type: 'application',
+		label: __( 'Application' ),
+		icon: file,
+	};
+}

package/src/utils/get-raw-content.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility function to extract raw content from either a string or an object
+ * containing raw and rendered properties.
+ *
+ * This handles the inconsistency in WordPress REST API responses where
+ * some fields like caption and description can be either:
+ * - A simple string
+ * - An object with { raw: string, rendered: string }
+ *
+ * @param content - The content to extract raw value from
+ * @return The raw content string, or empty string if content is falsy
+ */
+export function getRawContent(
+	content: string | { raw: string; rendered: string } | undefined | null
+): string {
+	if ( ! content ) {
+		return '';
+	}
+
+	// If it's a string, return it directly
+	if ( typeof content === 'string' ) {
+		return content;
+	}
+
+	// If it's an object with raw property, return the raw value
+	if ( typeof content === 'object' && 'raw' in content ) {
+		return content.raw || '';
+	}
+
+	// Fallback to empty string
+	return '';
+}

package/src/utils/get-rendered-content.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility function to extract rendered content from either a string or an object
+ * containing raw and rendered properties.
+ *
+ * This handles the inconsistency in WordPress REST API responses where
+ * some fields like caption and description can be either:
+ * - A simple string
+ * - An object with { raw: string, rendered: string }
+ *
+ * @param content - The content to extract raw value from
+ * @return The rendered content string, falling back to raw or empty string if content is falsy
+ */
+export function getRenderedContent(
+	content: string | { raw: string; rendered: string } | undefined | null
+): string {
+	if ( ! content ) {
+		return '';
+	}
+
+	// If it's a string, return it directly
+	if ( typeof content === 'string' ) {
+		return content;
+	}
+
+	// If it's an object with raw property, return the raw value
+	if ( typeof content === 'object' ) {
+		return content.rendered || content.raw || '';
+	}
+
+	// Fallback to empty string
+	return '';
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"types": [
+			"gutenberg-env",
+			"gutenberg-test-env",
+			"jest",
+			"@testing-library/jest-dom"
+		]
+	},
+	"references": [
+		{ "path": "../components" },
+		{ "path": "../core-data" },
+		{ "path": "../data" },
+		{ "path": "../dataviews" },
+		{ "path": "../element" },
+		{ "path": "../i18n" },
+		{ "path": "../icons" },
+		{ "path": "../primitives" },
+		{ "path": "../url" }
+	],
+	"exclude": [
+		"src/**/*.android.js",
+		"src/**/*.ios.js",
+		"src/**/*.native.js",
+		"src/**/react-native-*",
+		"src/**/stories/**/*.js", // only exclude js files, tsx files should be checked
+		"src/**/test/**/*.js" // only exclude js files, ts{x} files should be checked
+	]
+}