@wordpress/media-editor 0.2.0

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@wordpress/media-editor",
+	"version": "0.2.0",
+	"description": "Media editor components for WordPress.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"media",
+		"editor",
+		"attachment"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/media-editor/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/media-editor"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=18.12.0",
+		"npm": ">=8.19.2"
+	},
+	"main": "build/index.cjs",
+	"module": "build-module/index.mjs",
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.mjs",
+			"require": "./build/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"react-native": "src/index",
+	"types": "build-types",
+	"sideEffects": [
+		"build-style/**",
+		"src/**/*.scss"
+	],
+	"dependencies": {
+		"@babel/runtime": "^7.16.0",
+		"@wordpress/components": "^32.1.0",
+		"@wordpress/dataviews": "^11.3.0",
+		"@wordpress/element": "^6.39.0",
+		"@wordpress/i18n": "^6.12.0"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "eee1cfb1472f11183e40fb77465a5f13145df7ad"
+}

package/src/components/media-editor-provider/index.tsx

@@ -0,0 +1,90 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+import type { Field } from '@wordpress/dataviews';
+import type { ReactNode } from 'react';
+
+/**
+ * Media object from WordPress REST API.
+ */
+export interface Media {
+	id?: number;
+	source_url?: string;
+	mime_type?: string;
+	alt_text?: string;
+	title?: string | { rendered?: string; raw?: string };
+	caption?: string | { rendered?: string; raw?: string };
+	description?: string | { rendered?: string; raw?: string };
+	[ key: string ]: any;
+}
+
+/**
+ * Context value for MediaEditor.
+ */
+export interface MediaEditorContextValue {
+	media?: Media;
+	onChange?: ( updates: Partial< Media > ) => void;
+	fields: Field< Media >[];
+}
+
+/**
+ * Props for MediaEditorProvider.
+ */
+export interface MediaEditorProviderProps {
+	/** The media object to edit. */
+	value?: Media;
+	/**
+	 * Callback when media is updated.
+	 *
+	 * Optional - if not provided, the MediaEditor can be used in a read-only mode,
+	 * useful for preview-only scenarios.
+	 */
+	onChange?: ( updates: Partial< Media > ) => void;
+	/** Configuration settings for the media editor. */
+	settings?: {
+		fields?: Field< Media >[];
+	};
+	/** Child components. */
+	children: ReactNode;
+}
+
+const MediaEditorContext = createContext< MediaEditorContextValue | undefined >(
+	undefined
+);
+
+export function MediaEditorProvider( {
+	value,
+	onChange,
+	settings = {},
+	children,
+}: MediaEditorProviderProps ) {
+	const contextValue: MediaEditorContextValue = {
+		media: value,
+		onChange,
+		fields: settings.fields || [],
+	};
+
+	return (
+		<MediaEditorContext.Provider value={ contextValue }>
+			{ children }
+		</MediaEditorContext.Provider>
+	);
+}
+
+/**
+ * Hook to access the MediaEditor context.
+ *
+ * Must be used within a MediaEditorProvider component.
+ *
+ * @return MediaEditorContextValue value with media, onChange, and fields, etc.
+ */
+export function useMediaEditorContext(): MediaEditorContextValue {
+	const context = useContext( MediaEditorContext );
+	if ( ! context ) {
+		throw new Error(
+			'useMediaEditorContext must be used within MediaEditorProvider'
+		);
+	}
+	return context;
+}

package/src/components/media-form/index.tsx

@@ -0,0 +1,87 @@
+/**
+ * WordPress dependencies
+ */
+import { DataForm } from '@wordpress/dataviews';
+import type { Form, Field } from '@wordpress/dataviews';
+import { Spinner, __experimentalVStack as VStack } from '@wordpress/components';
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { useMediaEditorContext } from '../media-editor-provider';
+import type { Media } from '../media-editor-provider';
+
+/**
+ * Props for MediaForm component.
+ */
+export interface MediaFormProps {
+	form?: Form;
+	header?: ReactNode;
+}
+
+/**
+ * MediaForm component for editing media metadata.
+ *
+ * Renders a DataForm with fields for editing media properties like
+ * title, alt text, caption, description, etc.
+ *
+ * @param props        - Component props.
+ * @param props.form   - Optional form configuration.
+ * @param props.header - Optional header content to display above the form.
+ * @return The MediaForm component.
+ */
+export default function MediaForm( {
+	form: formOverrides,
+	header,
+}: MediaFormProps ) {
+	const { media, fields, onChange } = useMediaEditorContext();
+
+	if ( ! media || ! onChange ) {
+		return (
+			<div className="media-editor-form media-editor-form--loading">
+				<Spinner />
+			</div>
+		);
+	}
+
+	// Default form structure with panel layout
+	const defaultForm: Form = {
+		layout: {
+			type: 'panel',
+		},
+		fields: fields.map( ( field: Field< Media > ) => {
+			// Use regular layout for main editable fields
+			if (
+				[ 'title', 'alt_text', 'caption', 'description' ].includes(
+					field.id
+				)
+			) {
+				return {
+					id: field.id,
+					layout: {
+						type: 'regular',
+						labelPosition: 'top',
+					},
+				};
+			}
+			return field.id;
+		} ),
+	};
+
+	const form = formOverrides || defaultForm;
+
+	return (
+		<div className="media-editor-form">
+			<VStack spacing={ 4 }>
+				{ header }
+				<DataForm
+					data={ media }
+					fields={ fields }
+					form={ form }
+					onChange={ onChange }
+				/>
+			</VStack>
+		</div>
+	);
+}

package/src/components/media-preview/index.tsx

@@ -0,0 +1,154 @@
+/**
+ * WordPress dependencies
+ */
+import { Spinner } from '@wordpress/components';
+import { useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { useMediaEditorContext } from '../media-editor-provider';
+import { getMediaTypeFromMimeType } from '../../utils';
+
+/**
+ * Props for MediaPreview component.
+ */
+export interface MediaPreviewProps {
+	[ key: string ]: any; // TODO: Define specific props as needed, this will likely be for click handlers, accessibility attributes, etc.
+}
+
+/**
+ * Props for MediaPreviewContent component.
+ */
+interface MediaPreviewContentProps {
+	mediaType: { type: string };
+	mediaUrl: string;
+	altText?: string;
+	displayTitle?: string;
+	mimeType?: string;
+	onLoad: () => void;
+	onError: () => void;
+	loadingState: 'loading' | 'loaded' | 'error';
+}
+
+function MediaPreviewContent( {
+	mediaType,
+	mediaUrl,
+	altText,
+	displayTitle,
+	mimeType,
+	onLoad,
+	onError,
+	loadingState,
+}: MediaPreviewContentProps ) {
+	switch ( mediaType.type ) {
+		case 'image':
+			return (
+				<img
+					className={ loadingState === 'loaded' ? 'loaded' : '' }
+					src={ mediaUrl }
+					alt={ altText || '' }
+					onLoad={ onLoad }
+					onError={ onError }
+				/>
+			);
+		case 'video':
+			return (
+				<video src={ mediaUrl } controls onError={ onError }>
+					{ displayTitle }
+				</video>
+			);
+		case 'audio':
+			return (
+				<audio src={ mediaUrl } controls onError={ onError }>
+					{ displayTitle }
+				</audio>
+			);
+		default:
+			return (
+				<div className="media-editor-preview__file-info">
+					<p className="media-editor-preview__file-name">
+						{ displayTitle }
+					</p>
+					<p className="media-editor-preview__mime-type">
+						{ mimeType }
+					</p>
+					<a
+						href={ mediaUrl }
+						target="_blank"
+						rel="noopener noreferrer"
+						className="media-editor-preview__download-link"
+					>
+						{ __( 'View file' ) }
+					</a>
+				</div>
+			);
+	}
+}
+
+/**
+ * MediaPreview component displays the media file in the editor canvas.
+ * Supports images, videos, audio files, and generic file displays.
+ *
+ * @param props - Component props including click handlers and accessibility attributes.
+ * @return The MediaPreview component.
+ */
+export default function MediaPreview( props: MediaPreviewProps ) {
+	const [ loadingState, setLoadingState ] = useState<
+		'loading' | 'loaded' | 'error'
+	>( 'loading' );
+	const { media } = useMediaEditorContext();
+
+	const {
+		source_url: mediaUrl,
+		mime_type: mimeType,
+		alt_text: altText,
+		title,
+	} = media || {};
+
+	const mediaType = getMediaTypeFromMimeType( mimeType );
+
+	if ( ! mediaUrl ) {
+		return (
+			<div className="media-editor-preview media-editor-preview--empty">
+				<p>{ __( 'No media file available.' ) }</p>
+			</div>
+		);
+	}
+
+	if ( loadingState === 'error' ) {
+		return (
+			<div className="media-editor-preview media-editor-preview--error">
+				<p>{ __( 'Failed to load media file.' ) }</p>
+				<p className="media-editor-preview__url">{ mediaUrl }</p>
+			</div>
+		);
+	}
+
+	const displayTitle =
+		typeof title === 'string' ? title : title?.rendered || title?.raw;
+
+	return (
+		<div
+			{ ...props }
+			className={ `media-editor-preview media-editor-preview--${ mediaType.type }` }
+		>
+			{ mediaType.type === 'image' && loadingState === 'loading' && (
+				<div className="media-editor-preview__spinner">
+					<Spinner />
+				</div>
+			) }
+			<MediaPreviewContent
+				mediaType={ mediaType }
+				mediaUrl={ mediaUrl }
+				altText={ altText }
+				displayTitle={ displayTitle }
+				mimeType={ mimeType }
+				onLoad={ () => setLoadingState( 'loaded' ) }
+				onError={ () => setLoadingState( 'error' ) }
+				loadingState={ loadingState }
+			/>
+		</div>
+	);
+}

package/src/components/media-preview/style.scss

@@ -0,0 +1,89 @@
+@use "@wordpress/base-styles/animations" as *;
+@use "@wordpress/base-styles/colors" as *;
+@use "@wordpress/base-styles/variables" as *;
+
+.media-editor-preview {
+	box-sizing: border-box;
+	display: flex;
+	justify-content: center;
+	align-items: center;
+	min-height: 100%;
+	padding: $grid-unit-40;
+	position: relative;
+
+	&__spinner {
+		position: absolute;
+		top: 50%;
+		left: 50%;
+		transform: translate(-50%, -50%);
+	}
+
+	&--loading {
+		width: 100%;
+		height: 100%;
+	}
+
+	&--image img {
+		max-width: 100%;
+		max-height: 100%;
+		object-fit: contain;
+		width: auto;
+		height: auto;
+		opacity: 0;
+
+		&.loaded {
+			@include animation__fade-in();
+		}
+	}
+
+	&--video video {
+		max-width: 100%;
+		max-height: 100%;
+		object-fit: contain;
+		width: auto;
+		height: auto;
+	}
+
+	&--audio audio {
+		max-width: 100%;
+	}
+
+	&--file {
+		text-align: center;
+	}
+
+	&__file-info {
+		background: $gray-100;
+		padding: $grid-unit-30;
+		border-radius: 2px;
+	}
+
+	&__file-name {
+		font-weight: 600;
+		margin-bottom: $grid-unit-10;
+	}
+
+	&__mime-type {
+		color: $gray-700;
+		font-size: 0.9em;
+		margin-bottom: $grid-unit-20;
+	}
+
+	&__download-link {
+		display: inline-block;
+		margin-top: $grid-unit-10;
+	}
+
+	&--error,
+	&--empty {
+		color: $gray-700;
+		text-align: center;
+	}
+
+	&__url {
+		font-size: 0.9em;
+		color: $gray-600;
+		word-break: break-all;
+		margin-top: $grid-unit-10;
+	}
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// Components
+export { MediaEditorProvider } from './components/media-editor-provider';
+export { default as MediaPreview } from './components/media-preview';
+export { default as MediaForm } from './components/media-form';
+
+// Types
+export type {
+	Media,
+	MediaEditorProviderProps,
+} from './components/media-editor-provider';
+export type { MediaPreviewProps } from './components/media-preview';
+export type { MediaFormProps } from './components/media-form';
+
+// Re-export commonly used dataviews types for convenience
+export type { Field, Form } from '@wordpress/dataviews';

package/src/style.scss

@@ -0,0 +1,2 @@
+// Import component styles
+@use "./components/media-preview/style.scss" as *;

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

@@ -0,0 +1,29 @@
+/**
+ * Media type result.
+ */
+export interface MediaType {
+	type: 'image' | 'video' | 'audio' | 'application';
+}
+
+/**
+ * Determines the media type from a MIME type string.
+ *
+ * @param mimeType - The MIME type to check.
+ * @return Object with type property ('image', 'video', 'audio', or 'application').
+ */
+export function getMediaTypeFromMimeType( mimeType?: string ): MediaType {
+	if ( ! mimeType ) {
+		return { type: 'application' };
+	}
+
+	if ( mimeType.startsWith( 'image/' ) ) {
+		return { type: 'image' };
+	}
+	if ( mimeType.startsWith( 'video/' ) ) {
+		return { type: 'video' };
+	}
+	if ( mimeType.startsWith( 'audio/' ) ) {
+		return { type: 'audio' };
+	}
+	return { type: 'application' };
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { getMediaTypeFromMimeType } from './get-media-type';
+export type { MediaType } from './get-media-type';

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"types": [ "gutenberg-env" ]
+	},
+	"references": [
+		{ "path": "../components" },
+		{ "path": "../dataviews" },
+		{ "path": "../element" },
+		{ "path": "../i18n" }
+	]
+}