@wordpress/abilities 0.1.1-next.dc3f6d3c1.0

package/src/store/index.ts

@@ -0,0 +1,55 @@
+/**
+ * WordPress dependencies
+ */
+import { createReduxStore, register, dispatch } from '@wordpress/data';
+import { store as coreStore } from '@wordpress/core-data';
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import reducer from './reducer';
+import * as actions from './actions';
+import * as selectors from './selectors';
+import * as resolvers from './resolvers';
+import {
+	STORE_NAME,
+	ENTITY_KIND,
+	ENTITY_NAME,
+	ENTITY_NAME_CATEGORIES,
+} from './constants';
+
+/**
+ * The abilities store definition.
+ */
+export const store = createReduxStore( STORE_NAME, {
+	reducer,
+	actions,
+	selectors,
+	resolvers,
+} );
+
+register( store );
+
+dispatch( coreStore ).addEntities( [
+	{
+		name: ENTITY_NAME,
+		kind: ENTITY_KIND,
+		key: 'name',
+		baseURL: '/wp-abilities/v1/abilities',
+		baseURLParams: { context: 'edit' },
+		plural: 'abilities',
+		label: __( 'Abilities' ),
+		supportsPagination: true,
+	},
+	{
+		name: ENTITY_NAME_CATEGORIES,
+		kind: ENTITY_KIND,
+		key: 'slug',
+		baseURL: '/wp-abilities/v1/categories',
+		baseURLParams: { context: 'edit' },
+		plural: 'ability-categories',
+		label: __( 'Ability Categories' ),
+		supportsPagination: true,
+	},
+] );

package/src/store/reducer.ts

@@ -0,0 +1,184 @@
+/**
+ * WordPress dependencies
+ */
+import { combineReducers } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import type { Ability, AbilityCategory } from '../types';
+import {
+	RECEIVE_ABILITIES,
+	REGISTER_ABILITY,
+	UNREGISTER_ABILITY,
+	RECEIVE_CATEGORIES,
+	REGISTER_ABILITY_CATEGORY,
+	UNREGISTER_ABILITY_CATEGORY,
+} from './constants';
+
+/**
+ * Valid keys for an Ability object.
+ * Used to filter out non-standard properties from server responses.
+ */
+const ABILITY_KEYS = [
+	'name',
+	'label',
+	'description',
+	'category',
+	'input_schema',
+	'output_schema',
+	'meta',
+	'callback',
+	'permissionCallback',
+] as const;
+
+/**
+ * Valid keys for an AbilityCategory object.
+ * Used to filter out non-standard properties from server responses.
+ */
+const CATEGORY_KEYS = [ 'slug', 'label', 'description', 'meta' ] as const;
+
+/**
+ * Sanitizes an ability object to only include valid properties.
+ * This ensures consistent shape regardless of source (server/client).
+ *
+ * @param ability Raw ability object that may contain extra properties.
+ * @return Sanitized ability with only valid properties.
+ */
+function sanitizeAbility( ability: any ): Ability {
+	return Object.keys( ability )
+		.filter(
+			( key ) =>
+				ABILITY_KEYS.includes( key as any ) &&
+				ability[ key ] !== undefined
+		)
+		.reduce(
+			( obj, key ) => ( { ...obj, [ key ]: ability[ key ] } ),
+			{} as Ability
+		);
+}
+
+/**
+ * Sanitizes a category object to only include valid properties.
+ * This ensures consistent shape regardless of source.
+ *
+ * @param category Raw category object that may contain extra properties.
+ * @return Sanitized category with only valid properties.
+ */
+function sanitizeCategory( category: any ): AbilityCategory {
+	return Object.keys( category )
+		.filter(
+			( key ) =>
+				CATEGORY_KEYS.includes( key as any ) &&
+				category[ key ] !== undefined
+		)
+		.reduce(
+			( obj, key ) => ( { ...obj, [ key ]: category[ key ] } ),
+			{} as AbilityCategory
+		);
+}
+
+interface AbilitiesAction {
+	type: string;
+	abilities?: Ability[];
+	ability?: Ability;
+	categories?: AbilityCategory[];
+	category?: AbilityCategory;
+	name?: string;
+	slug?: string;
+}
+
+const DEFAULT_STATE: Record< string, Ability > = {};
+
+/**
+ * Reducer managing the abilities by name.
+ *
+ * @param state  Current state.
+ * @param action Dispatched action.
+ * @return New state.
+ */
+function abilitiesByName(
+	state: Record< string, Ability > = DEFAULT_STATE,
+	action: AbilitiesAction
+): Record< string, Ability > {
+	switch ( action.type ) {
+		case RECEIVE_ABILITIES: {
+			if ( ! action.abilities ) {
+				return state;
+			}
+			const newState: Record< string, Ability > = {};
+			action.abilities.forEach( ( ability ) => {
+				newState[ ability.name ] = sanitizeAbility( ability );
+			} );
+			return newState;
+		}
+		case REGISTER_ABILITY: {
+			if ( ! action.ability ) {
+				return state;
+			}
+			return {
+				...state,
+				[ action.ability.name ]: sanitizeAbility( action.ability ),
+			};
+		}
+		case UNREGISTER_ABILITY: {
+			if ( ! action.name || ! state[ action.name ] ) {
+				return state;
+			}
+			const { [ action.name ]: _, ...newState } = state;
+			return newState;
+		}
+		default:
+			return state;
+	}
+}
+
+const DEFAULT_CATEGORIES_STATE: Record< string, AbilityCategory > = {};
+
+/**
+ * Reducer managing the categories by slug.
+ *
+ * @param state  Current state.
+ * @param action Dispatched action.
+ * @return New state.
+ */
+function categoriesBySlug(
+	state: Record< string, AbilityCategory > = DEFAULT_CATEGORIES_STATE,
+	action: AbilitiesAction
+): Record< string, AbilityCategory > {
+	switch ( action.type ) {
+		case RECEIVE_CATEGORIES: {
+			if ( ! action.categories ) {
+				return state;
+			}
+			const newState: Record< string, AbilityCategory > = {};
+			action.categories.forEach( ( category ) => {
+				newState[ category.slug ] = sanitizeCategory( category );
+			} );
+			return newState;
+		}
+		case REGISTER_ABILITY_CATEGORY: {
+			if ( ! action.category ) {
+				return state;
+			}
+			return {
+				...state,
+				[ action.category.slug ]: sanitizeCategory( action.category ),
+			};
+		}
+		case UNREGISTER_ABILITY_CATEGORY: {
+			if ( ! action.slug || ! state[ action.slug ] ) {
+				return state;
+			}
+			const { [ action.slug ]: _, ...newState } = state;
+			return newState;
+		}
+		default:
+			return state;
+	}
+}
+
+export default combineReducers( {
+	abilitiesByName,
+	categoriesBySlug,
+} );

package/src/store/resolvers.ts

@@ -0,0 +1,151 @@
+/**
+ * WordPress dependencies
+ */
+import { store as coreStore } from '@wordpress/core-data';
+
+/**
+ * Internal dependencies
+ */
+import type { Ability, AbilityCategory } from '../types';
+import { ENTITY_KIND, ENTITY_NAME, ENTITY_NAME_CATEGORIES } from './constants';
+import {
+	receiveAbilities,
+	receiveCategories,
+	registerAbility,
+	registerAbilityCategory,
+} from './actions';
+
+/**
+ * Resolver for getAbilities selector.
+ * Fetches all abilities from the server.
+ *
+ * The resolver only fetches once (without query args filter) and stores all abilities.
+ * Query args filtering handled client-side by the selector for better performance
+ * and to avoid multiple API requests when filtering by different categories.
+ */
+export function getAbilities() {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { dispatch, registry, select } ) => {
+		const existingAbilities = select.getAbilities();
+
+		// Check if we have any server-side abilities (abilities without callbacks)
+		// Client abilities have callbacks and are registered immediately on page load
+		// We only want to skip fetching if we've already fetched server abilities
+		const hasServerAbilities = existingAbilities.some(
+			( ability: Ability ) => ! ability.callback
+		);
+
+		if ( hasServerAbilities ) {
+			return;
+		}
+
+		const abilities = await registry
+			.resolveSelect( coreStore )
+			.getEntityRecords( ENTITY_KIND, ENTITY_NAME, {
+				per_page: -1,
+			} );
+
+		dispatch( receiveAbilities( abilities || [] ) );
+	};
+}
+
+/**
+ * Resolver for getAbility selector.
+ * Fetches a specific ability from the server if not already in store.
+ *
+ * @param name Ability name.
+ */
+export function getAbility( name: string ) {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { dispatch, registry, select } ) => {
+		// Check if ability already exists in store (i.e. client ability or already fetched)
+		const existingAbility = select.getAbility( name );
+		if ( existingAbility ) {
+			return;
+		}
+
+		try {
+			const ability = await registry
+				.resolveSelect( coreStore )
+				.getEntityRecord( ENTITY_KIND, ENTITY_NAME, name );
+
+			if ( ability ) {
+				await dispatch( registerAbility( ability ) );
+			}
+		} catch ( error ) {
+			// If ability doesn't exist or error, we'll return undefined from the selector
+			// eslint-disable-next-line no-console
+			console.debug( `Ability not found: ${ name }` );
+		}
+	};
+}
+
+/**
+ * Resolver for getAbilityCategories selector.
+ * Fetches all categories from the server.
+ *
+ * The resolver only fetches once and stores all categories.
+ */
+export function getAbilityCategories() {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { dispatch, registry, select } ) => {
+		const existingCategories = select.getAbilityCategories();
+
+		// Check if we have any server-side categories (categories without meta._clientRegistered flag)
+		// Client categories have meta._clientRegistered=true and might be registered immediately
+		// We only want to skip fetching if we've already fetched server categories
+		const hasServerCategories = existingCategories.some(
+			( category: AbilityCategory ) => ! category.meta?._clientRegistered
+		);
+
+		if ( hasServerCategories ) {
+			return;
+		}
+
+		const categories = await registry
+			.resolveSelect( coreStore )
+			.getEntityRecords( ENTITY_KIND, ENTITY_NAME_CATEGORIES, {
+				per_page: -1,
+			} );
+
+		dispatch( receiveCategories( categories || [] ) );
+	};
+}
+
+/**
+ * Resolver for getAbilityCategory selector.
+ * Fetches a specific category from the server if not already in store.
+ *
+ * @param slug Category slug.
+ */
+export function getAbilityCategory( slug: string ) {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { dispatch, registry, select } ) => {
+		// Check if category already exists in store (either client-registered or server-fetched).
+		// This prevents unnecessary network requests while allowing client-side categories
+		// to be retrieved immediately without hitting the API.
+		const existingCategory = select.getAbilityCategory( slug );
+		if ( existingCategory ) {
+			return;
+		}
+
+		try {
+			const category = await registry
+				.resolveSelect( coreStore )
+				.getEntityRecord( ENTITY_KIND, ENTITY_NAME_CATEGORIES, slug );
+
+			if ( category ) {
+				await dispatch(
+					registerAbilityCategory( category.slug, {
+						label: category.label,
+						description: category.description,
+						meta: category.meta,
+					} )
+				);
+			}
+		} catch ( error ) {
+			// eslint-disable-next-line no-console
+			console.debug( `Category not found: ${ slug }` );
+		}
+	};
+}

package/src/store/selectors.ts

@@ -0,0 +1,82 @@
+/**
+ * WordPress dependencies
+ */
+import { createSelector } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	Ability,
+	AbilityCategory,
+	AbilitiesQueryArgs,
+	AbilitiesState,
+} from '../types';
+
+/**
+ * Returns all registered abilities.
+ * Optionally filters by query arguments.
+ *
+ * @param state Store state.
+ * @param args  Optional query arguments to filter. Defaults to empty object.
+ * @return Array of abilities.
+ */
+export const getAbilities = createSelector(
+	(
+		state: AbilitiesState,
+		{ category }: AbilitiesQueryArgs = {}
+	): Ability[] => {
+		const abilities = Object.values( state.abilitiesByName );
+		if ( category ) {
+			return abilities.filter(
+				( ability ) => ability.category === category
+			);
+		}
+		return abilities;
+	},
+	( state: AbilitiesState, category?: string ) => [
+		state.abilitiesByName,
+		category,
+	]
+);
+
+/**
+ * Returns a specific ability by name.
+ *
+ * @param state Store state.
+ * @param name  Ability name.
+ * @return Ability object or undefined if not found.
+ */
+export function getAbility(
+	state: AbilitiesState,
+	name: string
+): Ability | undefined {
+	return state.abilitiesByName[ name ];
+}
+
+/**
+ * Returns all registered ability categories.
+ *
+ * @param state Store state.
+ * @return Array of categories.
+ */
+export const getAbilityCategories = createSelector(
+	( state: AbilitiesState ): AbilityCategory[] => {
+		return Object.values( state.categoriesBySlug );
+	},
+	( state: AbilitiesState ) => [ state.categoriesBySlug ]
+);
+
+/**
+ * Returns a specific ability category by slug.
+ *
+ * @param state Store state.
+ * @param slug  Category slug.
+ * @return Category object or undefined if not found.
+ */
+export function getAbilityCategory(
+	state: AbilitiesState,
+	slug: string
+): AbilityCategory | undefined {
+	return state.categoriesBySlug[ slug ];
+}