@hoyrynpm/bsm-kit 0.1.0 → 0.2.0

package/README.md

@@ -2,9 +2,20 @@
 
 Pure JS helpers shared by Block Styles Manager and Höyry block plugins.
 
-Phase 0 ships this package from `packages/bsm-kit` inside the BSM repo via a
-`file:` dependency so builds work before the private npm publish. After Tuki
-publishes `0.1.0` to the `@hoyrynpm` registry, switch BSM to `"@hoyrynpm/bsm-kit": "^0.1.0"`.
+## 0.2.0
+
+New exports (existing exports unchanged; `KIT_API_VERSION` remains `1`):
+
+- `buildSchemaCss( schema, settings, derivedFn, getCssVar )` — declarative schema
+  CSS loop (rule A + mobile rule M at `schema.viewports.mobile.max` + derived
+  parts). Pass the host `getCssVar` (BSM `src/helpers.js`) as the fourth
+  argument, or `{ derivedFn, getCssVar }` as the third.
+- `migrateSettings( settings, schema, from )` — JS pair of
+  `Style_Settings_Migrator::plan` ops (`rename`, `drop`, `move`, `default`,
+  `map_value`); returns `{ settings, orphans, warnings }`.
 
 No `@wordpress/*` dependencies. Runtime settings are read from `window.hoyryBsm`
 at call time.
+
+Publish `0.2.0` from the PR branch to the `@hoyrynpm` registry before bumping
+BSM's dependency and lockfile to the published package (phase 0 §4.9).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hoyrynpm/bsm-kit",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Shared pure helpers for Höyry Block Styles Manager and block plugins",
 	"license": "GPL-2.0-or-later",
 	"author": "Digi-ja mainostoimisto Höyry",
@@ -12,6 +12,7 @@
 		"./fluid": "./src/fluid.js",
 		"./viewport": "./src/viewport.js",
 		"./schemaCss": "./src/schemaCss.js",
+		"./migrateSettings": "./src/migrateSettings.js",
 		"./stampSchemaVersion": "./src/stampSchemaVersion.js"
 	},
 	"files": [

package/src/config.js

@@ -71,9 +71,12 @@ export function getViewportConfig() {
 	const allowed = Array.isArray( viewports.allowed )
 		? viewports.allowed.map( Number ).filter( ( n ) => Number.isFinite( n ) )
 		: [ ...DEFAULT_ALLOWED ];
+	const rawExceptions = viewports.exceptions;
 	const exceptions =
-		viewports.exceptions && typeof viewports.exceptions === 'object'
-			? { ...viewports.exceptions }
+		rawExceptions &&
+		typeof rawExceptions === 'object' &&
+		! Array.isArray( rawExceptions )
+			? { ...rawExceptions }
 			: {};
 	return {
 		mobileMax:

package/src/index.js

@@ -20,5 +20,6 @@ export {
 	emitMobileCssVar,
 	emitTabletCssVar,
 } from './viewport.js';
-export { resolveCssValue, cssVarName } from './schemaCss.js';
+export { resolveCssValue, cssVarName, buildSchemaCss } from './schemaCss.js';
+export { migrateSettings } from './migrateSettings.js';
 export { stampSchemaVersion } from './stampSchemaVersion.js';

package/src/migrateSettings.js

@@ -0,0 +1,428 @@
+/**
+ * JS pair of Style_Settings_Migrator::plan ops (rename/drop/move/default/map_value).
+ * Pure settings transform — no CSS generation, no post writes.
+ */
+
+/**
+ * Apply declarative migrations from `from` toward schema.schemaVersion.
+ *
+ * @param {Object} settings styleSettings tree.
+ * @param {Object} schema   Schema document with migrations + groups.
+ * @param {string} from     Source schema version stamp.
+ * @return {{ settings: Object, orphans: Object, warnings: Array<{code:string,message:string}> }}
+ */
+export function migrateSettings( settings, schema, from ) {
+	const warnings = [];
+	const doc = schema && typeof schema === 'object' ? schema : {};
+	const to =
+		typeof doc.schemaVersion === 'string' ? doc.schemaVersion : '';
+	let migrated = deepCopy(
+		settings && typeof settings === 'object' ? settings : {}
+	);
+
+	const source = typeof from === 'string' && from !== '' ? from : 'unknown';
+
+	if ( source === to && source !== 'unknown' ) {
+		return {
+			settings: migrated,
+			orphans: collectOrphans( migrated, doc ),
+			warnings,
+		};
+	}
+
+	const chain = migrationChain( doc, source, to );
+	if ( chain === null ) {
+		warnings.push( {
+			code: 'migration_chain_incomplete',
+			message: `No complete migration path from ${ source } to ${ to }.`,
+		} );
+	} else {
+		for ( const step of chain ) {
+			const ops = Array.isArray( step?.ops ) ? step.ops : [];
+			for ( const op of ops ) {
+				if ( ! op || typeof op !== 'object' ) {
+					continue;
+				}
+				migrated = applyOp( migrated, op, warnings );
+			}
+		}
+	}
+
+	return {
+		settings: migrated,
+		orphans: collectOrphans( migrated, doc ),
+		warnings,
+	};
+}
+
+/**
+ * @param {Object} schema
+ * @param {string} from
+ * @param {string} to
+ * @return {Array<Object>|null}
+ */
+function migrationChain( schema, from, to ) {
+	if ( from === to ) {
+		return [];
+	}
+	const migrations = Array.isArray( schema.migrations )
+		? schema.migrations
+		: [];
+	if ( migrations.length === 0 ) {
+		return null;
+	}
+
+	const byFrom = {};
+	for ( const step of migrations ) {
+		if ( ! step || typeof step !== 'object' ) {
+			continue;
+		}
+		const stepFrom = typeof step.from === 'string' ? step.from : '';
+		if ( stepFrom !== '' ) {
+			byFrom[ stepFrom ] = step;
+		}
+	}
+
+	const chain = [];
+	let current = from;
+	let guard = 0;
+	while ( current !== to && guard < 64 ) {
+		guard += 1;
+		if ( ! Object.prototype.hasOwnProperty.call( byFrom, current ) ) {
+			return null;
+		}
+		const step = byFrom[ current ];
+		chain.push( step );
+		current = typeof step.to === 'string' ? step.to : '';
+		if ( current === '' ) {
+			return null;
+		}
+	}
+
+	return current === to ? chain : null;
+}
+
+/**
+ * @param {Object} settings
+ * @param {Object} op
+ * @param {Array}  warnings
+ * @return {Object}
+ */
+function applyOp( settings, op, warnings ) {
+	if ( op.rename && typeof op.rename === 'object' ) {
+		let next = settings;
+		for ( const [ fromPath, toPath ] of Object.entries( op.rename ) ) {
+			if ( pathExists( next, String( fromPath ) ) ) {
+				const value = pathGet( next, String( fromPath ) );
+				next = pathSet( next, String( toPath ), value );
+				next = pathUnset( next, String( fromPath ) );
+			}
+		}
+		return next;
+	}
+
+	if ( op.move && typeof op.move === 'object' ) {
+		const fromPath =
+			typeof op.move.from === 'string' ? op.move.from : '';
+		const toPath = typeof op.move.to === 'string' ? op.move.to : '';
+		if ( fromPath !== '' && toPath !== '' ) {
+			const value = pathGet( settings, fromPath );
+			let next = pathSet( settings, toPath, value );
+			next = pathUnset( next, fromPath );
+			return next;
+		}
+		return settings;
+	}
+
+	if ( Object.prototype.hasOwnProperty.call( op, 'drop' ) ) {
+		const paths = [];
+		if ( typeof op.drop === 'string' ) {
+			paths.push( op.drop );
+		} else if ( Array.isArray( op.drop ) ) {
+			for ( const path of op.drop ) {
+				if ( typeof path === 'string' ) {
+					paths.push( path );
+				}
+			}
+		} else if ( op.drop && typeof op.drop === 'object' ) {
+			if ( typeof op.drop.path === 'string' ) {
+				paths.push( op.drop.path );
+			}
+		}
+		let next = settings;
+		for ( const path of paths ) {
+			next = pathUnset( next, path );
+		}
+		return next;
+	}
+
+	if ( op.default && typeof op.default === 'object' ) {
+		const path =
+			typeof op.default.path === 'string' ? op.default.path : '';
+		const value = op.default.value;
+		if ( path !== '' && ! pathExists( settings, path ) ) {
+			return pathSet( settings, path, value );
+		}
+		return settings;
+	}
+
+	if ( op.map_value && typeof op.map_value === 'object' ) {
+		const path =
+			typeof op.map_value.path === 'string' ? op.map_value.path : '';
+		const map =
+			op.map_value.map && typeof op.map_value.map === 'object'
+				? op.map_value.map
+				: {};
+		if ( path !== '' && pathExists( settings, path ) ) {
+			const current = pathGet( settings, path );
+			const key =
+				current === null || current === undefined
+					? null
+					: typeof current === 'object'
+						? null
+						: String( current );
+			if ( key !== null && Object.prototype.hasOwnProperty.call( map, key ) ) {
+				return pathSet( settings, path, map[ key ] );
+			}
+		}
+		return settings;
+	}
+
+	warnings.push( {
+		code: 'unknown_migration_op',
+		message: `Unknown migration op keys: ${ Object.keys( op ).join( ',' ) }`,
+	} );
+	return settings;
+}
+
+/**
+ * @param {Object} settings
+ * @param {Object} schema
+ * @return {Object}
+ */
+function collectOrphans( settings, schema ) {
+	const known = knownSettingKeys( schema );
+	const orphans = {};
+	walkSettings( settings, '', ( path, value ) => {
+		if ( path === '' ) {
+			return;
+		}
+		if ( isPlainObject( value ) && isGroupPath( path, known ) ) {
+			return;
+		}
+		const base = stripViewportStateSuffix( path, known );
+		if ( ! Object.prototype.hasOwnProperty.call( known, base ) ) {
+			orphans[ path ] = value;
+		}
+	} );
+	return orphans;
+}
+
+/**
+ * @param {Object} schema
+ * @return {Object<string,true>}
+ */
+function knownSettingKeys( schema ) {
+	const known = {};
+	const groups =
+		schema.groups && typeof schema.groups === 'object'
+			? schema.groups
+			: {};
+	for ( const [ group, fields ] of Object.entries( groups ) ) {
+		if ( ! fields || typeof fields !== 'object' ) {
+			continue;
+		}
+		for ( const field of Object.keys( fields ) ) {
+			known[ `${ group }.${ field }` ] = true;
+		}
+	}
+	return known;
+}
+
+/**
+ * @param {string} path
+ * @param {Object} known
+ * @return {boolean}
+ */
+function isGroupPath( path, known ) {
+	for ( const key of Object.keys( known ) ) {
+		if ( key.startsWith( `${ path }.` ) ) {
+			return true;
+		}
+	}
+	return ! path.includes( '.' );
+}
+
+/**
+ * @param {string} path
+ * @param {Object} known
+ * @return {string}
+ */
+function stripViewportStateSuffix( path, known ) {
+	if ( Object.prototype.hasOwnProperty.call( known, path ) ) {
+		return path;
+	}
+	const suffixes = [
+		'HoverMobile',
+		'ActiveMobile',
+		'Hover',
+		'Active',
+		'Mobile',
+	];
+	for ( const suffix of suffixes ) {
+		if ( path.endsWith( suffix ) ) {
+			const base = path.slice( 0, -suffix.length );
+			if ( Object.prototype.hasOwnProperty.call( known, base ) ) {
+				return base;
+			}
+		}
+	}
+	return path;
+}
+
+/**
+ * @param {Object}   settings
+ * @param {string}   prefix
+ * @param {Function} cb
+ */
+function walkSettings( settings, prefix, cb ) {
+	if ( ! settings || typeof settings !== 'object' ) {
+		return;
+	}
+	for ( const [ key, value ] of Object.entries( settings ) ) {
+		const path = prefix === '' ? String( key ) : `${ prefix }.${ key }`;
+		cb( path, value );
+		if ( isPlainObject( value ) && looksLikeGroup( value ) ) {
+			walkSettings( value, path, cb );
+		}
+	}
+}
+
+/**
+ * @param {*} value
+ * @return {boolean}
+ */
+function isPlainObject( value ) {
+	return (
+		value !== null &&
+		typeof value === 'object' &&
+		! Array.isArray( value )
+	);
+}
+
+/**
+ * @param {Object} value
+ * @return {boolean}
+ */
+function looksLikeGroup( value ) {
+	const sideKeys = {
+		top: true,
+		right: true,
+		bottom: true,
+		left: true,
+		topLeft: true,
+		topRight: true,
+		bottomLeft: true,
+		bottomRight: true,
+		color: true,
+		gradient: true,
+		width: true,
+	};
+	const keys = Object.keys( value );
+	if ( keys.length === 0 ) {
+		return false;
+	}
+	let sideHits = 0;
+	for ( const key of keys ) {
+		if ( sideKeys[ key ] ) {
+			sideHits += 1;
+		}
+	}
+	return sideHits < keys.length;
+}
+
+/**
+ * @param {Object} arr
+ * @param {string} path
+ * @return {*}
+ */
+function pathGet( arr, path ) {
+	if ( path === '' ) {
+		return undefined;
+	}
+	const keys = path.split( '.' );
+	let cur = arr;
+	for ( const key of keys ) {
+		if ( ! isPlainObject( cur ) || ! Object.prototype.hasOwnProperty.call( cur, key ) ) {
+			return undefined;
+		}
+		cur = cur[ key ];
+	}
+	return cur;
+}
+
+/**
+ * @param {Object} arr
+ * @param {string} path
+ * @return {boolean}
+ */
+function pathExists( arr, path ) {
+	const keys = path.split( '.' );
+	let cur = arr;
+	for ( const key of keys ) {
+		if ( ! isPlainObject( cur ) || ! Object.prototype.hasOwnProperty.call( cur, key ) ) {
+			return false;
+		}
+		cur = cur[ key ];
+	}
+	return true;
+}
+
+/**
+ * @param {Object} arr
+ * @param {string} path
+ * @param {*}      value
+ * @return {Object}
+ */
+function pathSet( arr, path, value ) {
+	const keys = path.split( '.' );
+	const next = deepCopy( arr );
+	let ref = next;
+	const last = keys.pop();
+	for ( const key of keys ) {
+		if ( ! isPlainObject( ref[ key ] ) ) {
+			ref[ key ] = {};
+		}
+		ref = ref[ key ];
+	}
+	ref[ last ] = value;
+	return next;
+}
+
+/**
+ * @param {Object} arr
+ * @param {string} path
+ * @return {Object}
+ */
+function pathUnset( arr, path ) {
+	const keys = path.split( '.' );
+	const next = deepCopy( arr );
+	let ref = next;
+	const last = keys.pop();
+	for ( const key of keys ) {
+		if ( ! isPlainObject( ref[ key ] ) ) {
+			return next;
+		}
+		ref = ref[ key ];
+	}
+	delete ref[ last ];
+	return next;
+}
+
+/**
+ * @param {*} value
+ * @return {*}
+ */
+function deepCopy( value ) {
+	return JSON.parse( JSON.stringify( value ?? null ) );
+}

package/src/schemaCss.js

@@ -1,8 +1,8 @@
 /**
- * JS pair of Schema_Css_Generator declarative css key rules.
+ * JS pair of Schema_Css_Generator declarative css key rules + schema CSS loop.
  */
 
-import { isEmptyViewportValue } from './viewport.js';
+import { isEmptyViewportValue, emitMobileCssVar } from './viewport.js';
 
 /**
  * Resolve a field value: stored → fallbackFrom → default.
@@ -57,6 +57,351 @@ export function cssVarName( prefix, varName, state = '', mobile = false ) {
 	return name;
 }
 
+/**
+ * Declarative schema CSS parts (rule A + mobile rule M + derived).
+ * Same structure as PHP Schema_Css_Generator::from_attrs before wrap_named_css.
+ *
+ * @param {Object}                          schema      style-schema.json document.
+ * @param {Object}                          [settings]  styleSettings.
+ * @param {Function|Object|null|undefined}  [derivedFn] (settings)=>string[] or
+ *                                          { derivedFn, getCssVar }.
+ * @param {Function|null|undefined}         [getCssVarFn] getCssVar(var, type, value, suffix?).
+ * @return {string[]} CSS parts with {{selector}} placeholders.
+ */
+export function buildSchemaCss(
+	schema,
+	settings = {},
+	derivedFn = null,
+	getCssVarFn = null
+) {
+	let derived = derivedFn;
+	let getCssVar = getCssVarFn;
+	if ( derived && typeof derived === 'object' && ! Array.isArray( derived ) ) {
+		getCssVar = derived.getCssVar ?? getCssVar;
+		derived = derived.derivedFn ?? derived.derived ?? null;
+	}
+	if ( typeof getCssVar !== 'function' ) {
+		getCssVar = () => '';
+	}
+
+	const doc = schema && typeof schema === 'object' ? schema : {};
+	const bag = settings && typeof settings === 'object' ? settings : {};
+	const { desktop, mobile } = buildSchemaDecls( bag, doc, getCssVar );
+	const mobileMax = mobileMaxFromSchema( doc );
+	const mq = `@media(max-width:${ mobileMax }px)`;
+
+	const parts = [];
+	if ( desktop !== '' ) {
+		parts.push( `{{selector}}{${ desktop }}` );
+	}
+	if ( mobile !== '' ) {
+		parts.push( mq + '{{{selector}}{' + mobile + '}}' );
+	}
+
+	if ( typeof derived === 'function' ) {
+		const extra = derived( bag, doc );
+		if ( Array.isArray( extra ) ) {
+			for ( const part of extra ) {
+				if ( typeof part === 'string' && part !== '' ) {
+					parts.push( part );
+				}
+			}
+		}
+	}
+
+	return parts;
+}
+
+/**
+ * @param {Object}   settings
+ * @param {Object}   doc
+ * @param {Function} getCssVar
+ * @return {{ desktop: string, mobile: string }}
+ */
+function buildSchemaDecls( settings, doc, getCssVar ) {
+	const prefix =
+		typeof doc.cssVarPrefix === 'string'
+			? doc.cssVarPrefix
+			: doc.slug || '';
+	const states = schemaStates( doc );
+	const mobileSuffix = mobileSuffixFromSchema( doc );
+	let desktopDecls = '';
+	let mobileDecls = '';
+
+	const emitMobile = ( name, cssType, desktopVal, mobileVal ) =>
+		emitMobileCssVar( name, cssType, desktopVal, mobileVal, getCssVar );
+
+	const groups =
+		doc.groups && typeof doc.groups === 'object' ? doc.groups : {};
+	Object.keys( groups ).forEach( ( groupKey ) => {
+		const fields = groups[ groupKey ];
+		if ( ! fields || typeof fields !== 'object' ) {
+			return;
+		}
+		Object.keys( fields ).forEach( ( fieldKey ) => {
+			const field = fields[ fieldKey ];
+			if (
+				! field ||
+				typeof field !== 'object' ||
+				! field.css ||
+				typeof field.css !== 'object'
+			) {
+				return;
+			}
+			const cssSpec = field.css;
+			const varName =
+				typeof cssSpec.var === 'string' ? cssSpec.var : '';
+			const cssType =
+				typeof cssSpec.type === 'string' ? cssSpec.type : '';
+			if ( ! varName || ! cssType ) {
+				return;
+			}
+			const baseVar = cssVarName( prefix, varName );
+
+			const desktopValue = resolveSchemaValue(
+				settings,
+				groupKey,
+				fieldKey,
+				'',
+				'',
+				cssSpec
+			);
+			if ( ! isEmptyViewportValue( desktopValue ) ) {
+				desktopDecls += getCssVar( baseVar, cssType, desktopValue );
+			}
+
+			const fieldStates = Array.isArray( field.states )
+				? field.states
+				: null;
+			Object.keys( states ).forEach( ( stateName ) => {
+				if ( fieldStates && ! fieldStates.includes( stateName ) ) {
+					return;
+				}
+				const storageSuffix =
+					states[ stateName ]?.suffix ||
+					stateName.charAt( 0 ).toUpperCase() + stateName.slice( 1 );
+				const cssState = String( stateName ).toLowerCase();
+				const stateValue = resolveSchemaValue(
+					settings,
+					groupKey,
+					fieldKey,
+					storageSuffix,
+					'',
+					cssSpec
+				);
+				if ( ! isEmptyViewportValue( stateValue ) ) {
+					desktopDecls += getCssVar(
+						baseVar,
+						cssType,
+						stateValue,
+						`-${ cssState }`
+					);
+				}
+			} );
+
+			const mobileValue = resolveSchemaValue(
+				settings,
+				groupKey,
+				fieldKey,
+				'',
+				mobileSuffix,
+				cssSpec
+			);
+			const hasMobile = ! isEmptyViewportValue( mobileValue );
+			const inherits = !! cssSpec.mobileInherits;
+			if ( hasMobile ) {
+				mobileDecls += emitMobile( baseVar, cssType, null, mobileValue );
+			} else if (
+				inherits &&
+				! isEmptyViewportValue( desktopValue )
+			) {
+				mobileDecls += emitMobile(
+					baseVar,
+					cssType,
+					null,
+					desktopValue
+				);
+			}
+
+			Object.keys( states ).forEach( ( stateName ) => {
+				if ( fieldStates && ! fieldStates.includes( stateName ) ) {
+					return;
+				}
+				const storageSuffix =
+					states[ stateName ]?.suffix ||
+					stateName.charAt( 0 ).toUpperCase() + stateName.slice( 1 );
+				const cssState = String( stateName ).toLowerCase();
+				const stateMobile = resolveSchemaValue(
+					settings,
+					groupKey,
+					fieldKey,
+					storageSuffix,
+					mobileSuffix,
+					cssSpec
+				);
+				if ( ! isEmptyViewportValue( stateMobile ) ) {
+					mobileDecls += emitMobile(
+						`${ baseVar }-${ cssState }`,
+						cssType,
+						null,
+						stateMobile
+					);
+				}
+			} );
+		} );
+	} );
+
+	return { desktop: desktopDecls, mobile: mobileDecls };
+}
+
+/**
+ * Resolve stored → fallbackFrom → css.default (Schema_Css_Generator::resolve_value).
+ *
+ * @param {Object} settings
+ * @param {string} groupKey
+ * @param {string} fieldKey
+ * @param {string} stateSuffix
+ * @param {string} mobileSuffix
+ * @param {Object} cssSpec
+ * @return {*}
+ */
+function resolveSchemaValue(
+	settings,
+	groupKey,
+	fieldKey,
+	stateSuffix,
+	mobileSuffix,
+	cssSpec
+) {
+	const group =
+		settings?.[ groupKey ] && typeof settings[ groupKey ] === 'object'
+			? settings[ groupKey ]
+			: {};
+	const storageKey = `${ fieldKey }${ stateSuffix }${ mobileSuffix }`;
+	if (
+		Object.prototype.hasOwnProperty.call( group, storageKey ) &&
+		! isEmptyViewportValue( group[ storageKey ] )
+	) {
+		return group[ storageKey ];
+	}
+
+	const fallback = cssSpec?.fallbackFrom;
+	const paths = Array.isArray( fallback )
+		? fallback
+		: fallback
+			? [ fallback ]
+			: [];
+	for ( const path of paths ) {
+		if ( typeof path !== 'string' || path === '' ) {
+			continue;
+		}
+		let value;
+		if ( path.includes( '.' ) ) {
+			value = getByPath(
+				settings,
+				`${ path }${ stateSuffix }${ mobileSuffix }`
+			);
+			if (
+				isEmptyViewportValue( value ) &&
+				stateSuffix === '' &&
+				mobileSuffix === ''
+			) {
+				value = getByPath( settings, path );
+			}
+		} else {
+			const fbKey = `${ path }${ stateSuffix }${ mobileSuffix }`;
+			value = Object.prototype.hasOwnProperty.call( group, fbKey )
+				? group[ fbKey ]
+				: undefined;
+			if (
+				isEmptyViewportValue( value ) &&
+				stateSuffix === '' &&
+				mobileSuffix === ''
+			) {
+				value = Object.prototype.hasOwnProperty.call( group, path )
+					? group[ path ]
+					: undefined;
+			}
+		}
+		if ( ! isEmptyViewportValue( value ) ) {
+			return value;
+		}
+	}
+
+	if (
+		cssSpec &&
+		Object.prototype.hasOwnProperty.call( cssSpec, 'default' ) &&
+		! isEmptyViewportValue( cssSpec.default )
+	) {
+		if ( stateSuffix === '' && mobileSuffix === '' ) {
+			return cssSpec.default;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * @param {Object} doc
+ * @return {Object<string,{suffix?:string}>}
+ */
+function schemaStates( doc ) {
+	const defaults = {
+		hover: { suffix: 'Hover' },
+		active: { suffix: 'Active' },
+	};
+	if (
+		! doc?.states ||
+		typeof doc.states !== 'object' ||
+		Object.keys( doc.states ).length === 0
+	) {
+		return defaults;
+	}
+	const out = {};
+	Object.keys( doc.states ).forEach( ( name ) => {
+		const meta = doc.states[ name ];
+		out[ name ] =
+			meta && typeof meta === 'object'
+				? meta
+				: {
+						suffix:
+							name.charAt( 0 ).toUpperCase() + name.slice( 1 ),
+				  };
+	} );
+	return out;
+}
+
+/**
+ * @param {Object} doc
+ * @return {string}
+ */
+function mobileSuffixFromSchema( doc ) {
+	const mobile = doc?.viewports?.mobile;
+	if (
+		mobile &&
+		typeof mobile === 'object' &&
+		typeof mobile.suffix === 'string' &&
+		mobile.suffix !== ''
+	) {
+		return mobile.suffix;
+	}
+	return 'Mobile';
+}
+
+/**
+ * @param {Object} doc
+ * @return {number}
+ */
+function mobileMaxFromSchema( doc ) {
+	const mobile = doc?.viewports?.mobile;
+	if ( mobile && typeof mobile === 'object' && Number.isFinite( mobile.max ) ) {
+		const max = Number( mobile.max );
+		if ( max === 800 || max === 1023 ) {
+			return max;
+		}
+	}
+	return 800;
+}
+
 /**
  * @param {Object|null|undefined} root
  * @param {string}                path