@wordpress/core-data 4.1.1 → 4.2.0-next.e230fbab09.0

package/src/entity-types/attachment.ts

@@ -0,0 +1,146 @@
+/**
+ * Internal dependencies
+ */
+import {
+	Context,
+	ContextualField,
+	MediaType,
+	PostStatus,
+	RenderedText,
+	OmitNevers,
+	CommentingStatus,
+	PingStatus,
+} from './helpers';
+
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface Attachment< C extends Context > {
+			/**
+			 * The date the post was published, in the site's timezone.
+			 */
+			date: string | null;
+			/**
+			 * The date the post was published, as GMT.
+			 */
+			date_gmt: ContextualField< string | null, 'view' | 'edit', C >;
+			/**
+			 * The globally unique identifier for the post.
+			 */
+			guid: ContextualField< RenderedText< C >, 'view' | 'edit', C >;
+			/**
+			 * Unique identifier for the post.
+			 */
+			id: number;
+			/**
+			 * URL to the post.
+			 */
+			link: string;
+			/**
+			 * The date the post was last modified, in the site's timezone.
+			 */
+			modified: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * The date the post was last modified, as GMT.
+			 */
+			modified_gmt: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * An alphanumeric identifier for the post unique to its type.
+			 */
+			slug: string;
+			/**
+			 * A named status for the post.
+			 */
+			status: ContextualField< PostStatus, 'view' | 'edit', C >;
+			/**
+			 * Type of post.
+			 */
+			type: string;
+			/**
+			 * Permalink template for the post.
+			 */
+			permalink_template: ContextualField< string, 'edit', C >;
+			/**
+			 * Slug automatically generated from the post title.
+			 */
+			generated_slug: ContextualField< string, 'edit', C >;
+			/**
+			 * The title for the post.
+			 */
+			title: RenderedText< C >;
+			/**
+			 * The ID for the author of the post.
+			 */
+			author: number;
+			/**
+			 * Whether or not comments are open on the post.
+			 */
+			comment_status: ContextualField<
+				CommentingStatus,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * Whether or not the post can be pinged.
+			 */
+			ping_status: ContextualField< PingStatus, 'view' | 'edit', C >;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * The theme file to use to display the post.
+			 */
+			template: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * Alternative text to display when attachment is not displayed.
+			 */
+			alt_text: string;
+			/**
+			 * The attachment caption.
+			 */
+			caption: ContextualField< string, 'edit', C >;
+			/**
+			 * The attachment description.
+			 */
+			description: ContextualField<
+				RenderedText< C >,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * Attachment type.
+			 */
+			media_type: MediaType;
+			/**
+			 * The attachment MIME type.
+			 */
+			mime_type: string;
+			/**
+			 * Details about the media file, specific to its type.
+			 */
+			media_details: Record< string, string >;
+			/**
+			 * The ID for the associated post of the attachment.
+			 */
+			post: ContextualField< number, 'view' | 'edit', C >;
+			/**
+			 * URL to the original attachment file.
+			 */
+			source_url: string;
+			/**
+			 * List of the missing image sizes of the attachment.
+			 */
+			missing_image_sizes: ContextualField< string[], 'edit', C >;
+		}
+	}
+}
+
+export type Attachment< C extends Context > = OmitNevers<
+	_BaseEntityTypes.Attachment< C >
+>;

package/src/entity-types/base-entity-types.ts

@@ -0,0 +1,36 @@
+/**
+ * This module exists solely to make the BaseEntityTypes namespace extensible
+ * with declaration merging:
+ *
+ * ```ts
+ * declare module './base-entity-types' {
+ *     export namespace BaseEntityTypes {
+ * 		     export interface Comment< C extends Context > {
+ * 		         id: number;
+ * 		         // ...
+ * 	       }
+ * 	   }
+ * }
+ * ```
+ *
+ * The huge upside is that consumers of @wordpress/core-data may extend the
+ * exported data types using interface merging as follows:
+ *
+ * ```ts
+ * import type { Context } from '@wordpress/core-data';
+ * declare module '@wordpress/core-data' {
+ *     export namespace BaseEntityTypes {
+ *         export interface Comment< C extends Context > {
+ *             numberOfViews: number;
+ *         }
+ *     }
+ * }
+ *
+ * import type { Comment } from '@wordpress/core-data';
+ * const c : Comment< 'view' > = ...;
+ *
+ * // c.numberOfViews is a number
+ * // c.id is still present
+ * ```
+ */
+export namespace BaseEntityTypes {}

package/src/entity-types/comment.ts

@@ -0,0 +1,96 @@
+/**
+ * Internal dependencies
+ */
+import {
+	AvatarUrls,
+	Context,
+	ContextualField,
+	OmitNevers,
+	RenderedText,
+} from './helpers';
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+export type CommentStatus = 'hold' | 'approve' | 'spam' | 'trash' | '1' | '0';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface Comment< C extends Context > {
+			/**
+			 * Unique identifier for the comment.
+			 */
+			id: number;
+			/**
+			 * The ID of the user object, if author was a user.
+			 */
+			author: number;
+			/**
+			 * Email address for the comment author.
+			 */
+			author_email: ContextualField< string, 'edit', C >;
+			/**
+			 * IP address for the comment author.
+			 */
+			author_ip: ContextualField< string, 'edit', C >;
+			/**
+			 * Display name for the comment author.
+			 */
+			author_name: string;
+			/**
+			 * URL for the comment author.
+			 */
+			author_url: string;
+			/**
+			 * User agent for the comment author.
+			 */
+			author_user_agent: ContextualField< string, 'edit', C >;
+			/**
+			 * The content for the comment.
+			 */
+			content: RenderedText< C >;
+			/**
+			 * The date the comment was published, in the site's timezone.
+			 */
+			date: string;
+			/**
+			 * The date the comment was published, as GMT.
+			 */
+			date_gmt: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * URL to the comment.
+			 */
+			link: string;
+			/**
+			 * The ID for the parent of the comment.
+			 */
+			parent: number;
+			/**
+			 * The ID of the associated post object.
+			 */
+			post: ContextualField< number, 'view' | 'edit', C >;
+			/**
+			 * State of the comment.
+			 */
+			status: ContextualField< CommentStatus, 'view' | 'edit', C >;
+			/**
+			 * Type of the comment.
+			 */
+			type: string;
+			/**
+			 * Avatar URLs for the comment author.
+			 */
+			author_avatar_urls: AvatarUrls;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+		}
+	}
+}
+
+export type Comment< C extends Context > = OmitNevers<
+	_BaseEntityTypes.Comment< C >
+>;

package/src/entity-types/helpers.ts

@@ -0,0 +1,153 @@
+/**
+ * Internal dependencies
+ */
+import { EntityRecord } from './index';
+
+export interface AvatarUrls {
+	/**
+	 * Avatar URL with image size of 24 pixels.
+	 */
+	'24': string;
+	/**
+	 * Avatar URL with image size of 48 pixels.
+	 */
+	'48': string;
+	/**
+	 * Avatar URL with image size of 96 pixels.
+	 */
+	'96': string;
+}
+
+export type MediaType = 'image' | 'file';
+export type CommentingStatus = 'open' | 'closed';
+export type PingStatus = 'open' | 'closed';
+export type PostStatus = 'publish' | 'future' | 'draft' | 'pending' | 'private';
+export type PostFormat =
+	| 'standard'
+	| 'aside'
+	| 'chat'
+	| 'gallery'
+	| 'link'
+	| 'image'
+	| 'quote'
+	| 'status'
+	| 'video'
+	| 'audio';
+
+/**
+ * The REST API context parameter.
+ */
+export type Context = 'view' | 'edit' | 'embed';
+
+/**
+ * ContextualField makes the field available only in the specified given contexts,
+ * and ensure the field is absent from the object when in a different context.
+ *
+ * @example
+ * ```ts
+ * interface Post< C extends Context > {
+ * 	…
+ * 	modified: ContextualField< string, 'edit' | 'view', C >;
+ * 	password: ContextualField< string, 'edit', C >;
+ * 	…
+ * }
+ *
+ * const post: Post<'edit'> = …
+ * // post.modified exists as a string
+ * // post.password exists as a string
+ *
+ * const post: Post<'view'> = …
+ * // post.modified still exists as a string
+ * // post.password is missing, undefined, because we're not in the `edit` context.
+ * ```
+ */
+export type ContextualField<
+	FieldType,
+	AvailableInContexts extends Context,
+	C extends Context
+> = AvailableInContexts extends C ? FieldType : never;
+
+/**
+ * Removes all the properties of type never, even the deeply nested ones.
+ *
+ * @example
+ * ```ts
+ * type MyType = {
+ *   foo: string;
+ *   bar: never;
+ *   nested: {
+ *     foo: string;
+ *     bar: never;
+ *   }
+ * }
+ * const x = {} as OmitNevers<MyType>;
+ * // x is of type { foo: string; nested: { foo: string; }}
+ * // The `never` properties were removed entirely
+ * ```
+ */
+export type OmitNevers<
+	T,
+	Nevers = {
+		[ K in keyof T ]: Exclude< T[ K ], undefined > extends never
+			? never
+			: T[ K ] extends Record< string, unknown >
+			? OmitNevers< T[ K ] >
+			: T[ K ];
+	}
+> = Pick<
+	Nevers,
+	{
+		[ K in keyof Nevers ]: Nevers[ K ] extends never ? never : K;
+	}[ keyof Nevers ]
+>;
+
+/**
+ * A string that the server renders which often involves
+ * modifications from the raw source string.
+ *
+ * For example, block HTML with the comment delimiters exists
+ * in `post_content` but those comments are stripped out when
+ * rendering to a page view. Similarly, plugins might modify
+ * content or replace shortcodes.
+ */
+export interface RenderedText< C extends Context > {
+	/**
+	 * The source string which will be rendered on page views.
+	 */
+	raw: ContextualField< string, 'edit', C >;
+	/**
+	 * The output of the raw source after processing and filtering on the server.
+	 */
+	rendered: string;
+}
+
+/**
+ * Updatable<EntityRecord> is a type describing Edited Entity Records. They are like
+ * regular Entity Records, but they have all the local edits applied on top of the REST API data.
+ *
+ * This turns certain field from an object into a string.
+ *
+ * Entities like Post have fields that only be rendered on the server, like title, excerpt,
+ * and content. The REST API exposes both the raw markup and the rendered version of those fields.
+ * For example, in the block editor, content.rendered could used as a visual preview, and
+ * content.raw could be used to populate the code editor.
+ *
+ * When updating these rendered fields, Javascript is not be able to properly render arbitrary block
+ * markup. Therefore, it stores only the raw markup without the rendered part. And since that's a string,
+ * the entire field becomes a string.
+ *
+ * @example
+ * ```ts
+ * type Post< C extends Context > {
+ *   title: RenderedText< C >;
+ * }
+ * const post = {} as Post;
+ * // post.title is an object with raw and rendered properties
+ *
+ * const updatablePost = {} as Updatable< Post >;
+ * // updatablePost.title is a string
+ * ```
+ */
+export type Updatable< T extends EntityRecord< 'edit' > > = {
+	[ K in keyof T ]: T[ K ] extends RenderedText< any > ? string : T[ K ];
+};

package/src/entity-types/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal dependencies
+ */
+import type { Attachment } from './attachment';
+import type { Comment } from './comment';
+import type { MenuLocation } from './menu-location';
+import type { NavMenu } from './nav-menu';
+import type { NavMenuItem } from './nav-menu-item';
+import type { NavigationArea } from './navigation-area';
+import type { Page } from './page';
+import type { Plugin } from './plugin';
+import type { Post } from './post';
+import type { Settings } from './settings';
+import type { Sidebar } from './sidebar';
+import type { Taxonomy } from './taxonomy';
+import type { Theme } from './theme';
+import type { User } from './user';
+import type { Type } from './type';
+import type { Widget } from './widget';
+import type { WidgetType } from './widget-type';
+import type { WpTemplate } from './wp-template';
+import type { WpTemplatePart } from './wp-template-part';
+import type { Context, Updatable } from './helpers';
+
+export type { BaseEntityTypes } from './base-entity-types';
+
+export type {
+	Context,
+	Updatable,
+	Attachment,
+	Comment,
+	MenuLocation,
+	NavMenu,
+	NavMenuItem,
+	NavigationArea,
+	Page,
+	Plugin,
+	Post,
+	Settings,
+	Sidebar,
+	Taxonomy,
+	Theme,
+	User,
+	Type,
+	Widget,
+	WidgetType,
+	WpTemplate,
+	WpTemplatePart,
+};
+
+export type EntityRecord< C extends Context > =
+	| Attachment< C >
+	| Comment< C >
+	| MenuLocation< C >
+	| NavMenu< C >
+	| NavMenuItem< C >
+	| NavigationArea< C >
+	| Page< C >
+	| Plugin< C >
+	| Post< C >
+	| Settings< C >
+	| Sidebar< C >
+	| Taxonomy< C >
+	| Theme< C >
+	| Type< C >
+	| User< C >
+	| Widget< C >
+	| WidgetType< C >
+	| WpTemplate< C >
+	| WpTemplatePart< C >;
+
+export type UpdatableEntityRecord = Updatable< EntityRecord< 'edit' > >;

package/src/entity-types/menu-location.ts

@@ -0,0 +1,29 @@
+/**
+ * Internal dependencies
+ */
+import { Context, OmitNevers } from './helpers';
+
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface MenuLocation< C extends Context > {
+			/**
+			 * The name of the menu location.
+			 */
+			name: string;
+			/**
+			 * The description of the menu location.
+			 */
+			description: string;
+			/**
+			 * The ID of the assigned menu.
+			 */
+			menu: number;
+		}
+	}
+}
+
+export type MenuLocation< C extends Context > = OmitNevers<
+	_BaseEntityTypes.MenuLocation< C >
+>;

package/src/entity-types/nav-menu-item.ts

@@ -0,0 +1,106 @@
+/**
+ * Internal dependencies
+ */
+import { RenderedText, Context, ContextualField, OmitNevers } from './helpers';
+
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+export type NavMenuItemType =
+	| 'taxonomy'
+	| 'post_type'
+	| 'post_type_archive'
+	| 'custom';
+export type NavMenuItemStatus =
+	| 'publish'
+	| 'future'
+	| 'draft'
+	| 'pending'
+	| 'private';
+export type Target = '_blank' | '';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface NavMenuItem< C extends Context > {
+			/**
+			 * The title for the object.
+			 */
+			title: RenderedText< C >;
+			/**
+			 * Unique identifier for the object.
+			 */
+			id: number;
+			/**
+			 * The singular label used to describe this type of menu item.
+			 */
+			type_label: string;
+			/**
+			 * The family of objects originally represented, such as "post_type" or "taxonomy".
+			 */
+			type: NavMenuItemType;
+			/**
+			 * A named status for the object.
+			 */
+			status: NavMenuItemStatus;
+			/**
+			 * The ID for the parent of the object.
+			 */
+			parent: number;
+			/**
+			 * Text for the title attribute of the link element for this menu item.
+			 */
+			attr_title: string;
+			/**
+			 * Class names for the link element of this menu item.
+			 */
+			classes: string[];
+			/**
+			 * The description of this menu item.
+			 */
+			description: string;
+			/**
+			 * The DB ID of the nav_menu_item that is this item's menu parent, if any, otherwise 0.
+			 */
+			menu_order: number;
+			/**
+			 * The type of object originally represented, such as "category", "post", or "attachment".
+			 */
+			object: string;
+			/**
+			 * The database ID of the original object this menu item represents, for example the ID for posts or the term_id for categories.
+			 */
+			object_id: number;
+			/**
+			 * The target attribute of the link element for this menu item.
+			 */
+			target: Target;
+			/**
+			 * The URL to which this menu item points.
+			 */
+			url: string;
+			/**
+			 * The XFN relationship expressed in the link of this menu item.
+			 */
+			xfn: string[];
+			/**
+			 * Whether the menu item represents an object that no longer exists.
+			 */
+			invalid: boolean;
+			/**
+			 * The terms assigned to the object in the nav_menu taxonomy.
+			 */
+			menus: ContextualField< number, 'view' | 'edit', C >;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+		}
+	}
+}
+
+export type NavMenuItem< C extends Context > = OmitNevers<
+	_BaseEntityTypes.NavMenuItem< C >
+>;

package/src/entity-types/nav-menu.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal dependencies
+ */
+import { Context, ContextualField, OmitNevers } from './helpers';
+
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface NavMenu< C extends Context > {
+			/**
+			 * Unique identifier for the term.
+			 */
+			id: number;
+			/**
+			 * HTML description of the term.
+			 */
+			description: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * HTML title for the term.
+			 */
+			name: string;
+			/**
+			 * An alphanumeric identifier for the term unique to its type.
+			 */
+			slug: string;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * The locations assigned to the menu.
+			 */
+			locations: ContextualField< string[], 'view' | 'edit', C >;
+			/**
+			 * The DB ID of the original object this menu item represents, e . g . ID for posts and term_id for categories.
+			 */
+			object_id: number;
+			/**
+			 * Whether to automatically add top level pages to this menu.
+			 */
+			auto_add: ContextualField< boolean, 'view' | 'edit', C >;
+		}
+	}
+}
+
+export type NavMenu< C extends Context > = OmitNevers<
+	_BaseEntityTypes.NavMenu< C >
+>;