@hoyrynpm/bsm-kit 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @hoyrynpm/bsm-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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"`.
+
+No `@wordpress/*` dependencies. Runtime settings are read from `window.hoyryBsm`
+at call time.

package/package.json

@@ -1,6 +1,27 @@
 {
-  "name": "@hoyrynpm/bsm-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@hoyrynpm/bsm-kit",
+	"version": "0.1.1",
+	"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",
+	"type": "module",
+	"main": "src/index.js",
+	"exports": {
+		".": "./src/index.js",
+		"./config": "./src/config.js",
+		"./fluid": "./src/fluid.js",
+		"./viewport": "./src/viewport.js",
+		"./schemaCss": "./src/schemaCss.js",
+		"./stampSchemaVersion": "./src/stampSchemaVersion.js"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"test": "node --test test/*.js"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}

package/src/config.js

@@ -0,0 +1,89 @@
+/**
+ * Runtime settings from window.hoyryBsm (read at call time).
+ */
+
+export const KIT_API_VERSION = 1;
+
+const DEFAULT_ROOT = 16;
+const DEFAULT_FLUID = { min: 320, max: 1920 };
+const DEFAULT_MOBILE_MAX = 800;
+const DEFAULT_ALLOWED = [ 800, 1023 ];
+
+/**
+ * @return {object|undefined}
+ */
+function hoyryBsm() {
+	return typeof window !== 'undefined' ? window.hoyryBsm : undefined;
+}
+
+/**
+ * @return {boolean}
+ */
+function apiReady() {
+	const raw = hoyryBsm();
+	if ( ! raw || typeof raw !== 'object' ) {
+		return false;
+	}
+	const version = Number( raw.apiVersion );
+	return Number.isFinite( version ) && version >= KIT_API_VERSION;
+}
+
+/**
+ * @return {number}
+ */
+export function getRootFontSize() {
+	const raw = hoyryBsm()?.rootFontSize;
+	const n = Number( raw );
+	return Number.isFinite( n ) && n > 0 ? n : DEFAULT_ROOT;
+}
+
+/**
+ * @return {{ min: number, max: number }}
+ */
+export function getFluidRange() {
+	const raw = hoyryBsm()?.fluidRange;
+	const min = Number( raw?.min );
+	const max = Number( raw?.max );
+	if (
+		Number.isFinite( min ) &&
+		Number.isFinite( max ) &&
+		min > 0 &&
+		max > min
+	) {
+		return { min, max };
+	}
+	return { ...DEFAULT_FLUID };
+}
+
+/**
+ * @return {{ mobileMax: number, allowed: number[], exceptions: Object<string, number> }}
+ */
+export function getViewportConfig() {
+	if ( ! apiReady() ) {
+		return {
+			mobileMax: DEFAULT_MOBILE_MAX,
+			allowed: [ ...DEFAULT_ALLOWED ],
+			exceptions: {},
+		};
+	}
+	const viewports = hoyryBsm()?.viewports || {};
+	const mobileMax = Number( viewports.mobileMax );
+	const allowed = Array.isArray( viewports.allowed )
+		? viewports.allowed.map( Number ).filter( ( n ) => Number.isFinite( n ) )
+		: [ ...DEFAULT_ALLOWED ];
+	const rawExceptions = viewports.exceptions;
+	const exceptions =
+		rawExceptions &&
+		typeof rawExceptions === 'object' &&
+		! Array.isArray( rawExceptions )
+			? { ...rawExceptions }
+			: {};
+	return {
+		mobileMax:
+			Number.isFinite( mobileMax ) && mobileMax > 0
+				? mobileMax
+				: DEFAULT_MOBILE_MAX,
+		allowed: allowed.length ? allowed : [ ...DEFAULT_ALLOWED ],
+		exceptions,
+	};
+}

package/src/fluid.js

@@ -0,0 +1,56 @@
+/**
+ * Shared fluid clamp helpers. Fallback root 16 and range 320–1920 live only here
+ * (and PHP Fluid_Range).
+ */
+
+import { getFluidRange, getRootFontSize } from './config.js';
+
+export { getFluidRange, getRootFontSize } from './config.js';
+
+/**
+ * Convert a rem quantity to px using the localized root font size.
+ *
+ * @param {number} rem Rem value.
+ * @return {number} Rounded px.
+ */
+export function remToPx( rem ) {
+	return Math.round( rem * getRootFontSize() );
+}
+
+/**
+ * Generate clamp() CSS from min/max px, matching Fluid_Range::generate_clamp.
+ *
+ * @param {number} minValue     Smaller px (usually mobile).
+ * @param {number} maxValue     Larger px (usually desktop).
+ * @param {number} [minViewport]
+ * @param {number} [maxViewport]
+ * @param {number} [rootFontSize]
+ * @return {string}
+ */
+export function generateClampValue(
+	minValue,
+	maxValue,
+	minViewport,
+	maxViewport,
+	rootFontSize
+) {
+	const range = getFluidRange();
+	const vmin = minViewport ?? range.min;
+	const vmax = maxViewport ?? range.max;
+	const root = rootFontSize ?? getRootFontSize();
+
+	const minRem = Math.round( minValue * 1000 ) / ( root * 1000 );
+	if ( Math.abs( minValue - maxValue ) < 0.0001 ) {
+		return `${ minRem }rem`;
+	}
+
+	const slope =
+		Math.round( ( maxValue - minValue ) * 100 * 1000 ) /
+		( ( vmax - vmin ) * 1000 );
+	const yAxisIntersection =
+		Math.round( ( minValue - vmin * ( slope / 100 ) ) * 1000 ) /
+		( root * 1000 );
+	const maxRem = Math.round( maxValue * 1000 ) / ( root * 1000 );
+
+	return `clamp(${ minRem }rem, ${ yAxisIntersection }rem + ${ slope }vw, ${ maxRem }rem)`;
+}

package/src/index.js

@@ -0,0 +1,24 @@
+export { KIT_API_VERSION, getRootFontSize, getFluidRange, getViewportConfig } from './config.js';
+export { remToPx, generateClampValue } from './fluid.js';
+export {
+	VIEWPORT_DESKTOP,
+	VIEWPORT_TABLET,
+	VIEWPORT_MOBILE,
+	VIEWPORT_MOBILE_MAX,
+	SUPPORTS_TABLET_VIEWPORT,
+	mobileKey,
+	tabletKey,
+	declaresTabletViewport,
+	isEmptyViewportValue,
+	getViewportValue,
+	viewportNumberValue,
+	isMobileOverride,
+	isTabletOverride,
+	isMvpOverrideKey,
+	writeViewportKey,
+	getViewportBreakpoints,
+	emitMobileCssVar,
+	emitTabletCssVar,
+} from './viewport.js';
+export { resolveCssValue, cssVarName } from './schemaCss.js';
+export { stampSchemaVersion } from './stampSchemaVersion.js';

package/src/schemaCss.js

@@ -0,0 +1,78 @@
+/**
+ * JS pair of Schema_Css_Generator declarative css key rules.
+ */
+
+import { isEmptyViewportValue } from './viewport.js';
+
+/**
+ * Resolve a field value: stored → fallbackFrom → default.
+ *
+ * @param {Object|null|undefined} settings styleSettings root or group bag.
+ * @param {Object}                css      Schema css key object.
+ * @param {string}                [path]   Dotted path into settings for the field.
+ * @return {*}
+ */
+export function resolveCssValue( settings, css, path = '' ) {
+	const stored = path ? getByPath( settings, path ) : undefined;
+	if ( ! isEmptyViewportValue( stored ) ) {
+		return stored;
+	}
+
+	const fallbacks = css?.fallbackFrom;
+	const list = Array.isArray( fallbacks )
+		? fallbacks
+		: fallbacks
+			? [ fallbacks ]
+			: [];
+	for ( const fb of list ) {
+		const value = getByPath( settings, String( fb ) );
+		if ( ! isEmptyViewportValue( value ) ) {
+			return value;
+		}
+	}
+
+	if ( css && Object.prototype.hasOwnProperty.call( css, 'default' ) ) {
+		return css.default;
+	}
+	return undefined;
+}
+
+/**
+ * Build CSS custom property name.
+ *
+ * @param {string} prefix cssVarPrefix.
+ * @param {string} varName css.var.
+ * @param {string} [state] hover|active.
+ * @param {boolean} [mobile]
+ * @return {string} --prefix-var[-state][-mobile]
+ */
+export function cssVarName( prefix, varName, state = '', mobile = false ) {
+	let name = `--${ prefix }-${ varName }`;
+	if ( state ) {
+		name += `-${ state }`;
+	}
+	if ( mobile ) {
+		name += '-mobile';
+	}
+	return name;
+}
+
+/**
+ * @param {Object|null|undefined} root
+ * @param {string}                path
+ * @return {*}
+ */
+function getByPath( root, path ) {
+	if ( ! root || typeof root !== 'object' || ! path ) {
+		return undefined;
+	}
+	const parts = String( path ).split( '.' );
+	let cur = root;
+	for ( const part of parts ) {
+		if ( cur === null || cur === undefined || typeof cur !== 'object' ) {
+			return undefined;
+		}
+		cur = cur[ part ];
+	}
+	return cur;
+}

package/src/stampSchemaVersion.js

@@ -0,0 +1,29 @@
+/**
+ * Stamp styleSchemaVersion on new styles or after migration.
+ *
+ * @param {Object}   attributes    Block attributes.
+ * @param {Function} setAttributes Gutenberg setAttributes.
+ * @param {string}   version       schemaVersion to stamp.
+ */
+export function stampSchemaVersion( attributes, setAttributes, version ) {
+	if ( typeof setAttributes !== 'function' || typeof version !== 'string' || version === '' ) {
+		return;
+	}
+
+	const current = attributes?.styleSchemaVersion;
+	if ( typeof current === 'string' && current !== '' ) {
+		return;
+	}
+
+	const settings = attributes?.styleSettings;
+	const emptySettings =
+		settings === undefined ||
+		settings === null ||
+		( typeof settings === 'object' && Object.keys( settings ).length === 0 );
+
+	if ( ! emptySettings ) {
+		return;
+	}
+
+	setAttributes( { styleSchemaVersion: version } );
+}

package/src/viewport.js

@@ -0,0 +1,230 @@
+/**
+ * Desktop / mobile values for block-style settings, with an optional tablet band.
+ */
+
+import { getViewportConfig } from './config.js';
+
+/** Desktop viewport id. */
+export const VIEWPORT_DESKTOP = 'desktop';
+
+/** Tablet viewport id. Used only when the block declares tablet keys. */
+export const VIEWPORT_TABLET = 'tablet';
+
+/** Mobile viewport id. Only the editor device type `Mobile` maps here. */
+export const VIEWPORT_MOBILE = 'mobile';
+
+/**
+ * Front-end breakpoint in pixels. Generated CSS does not include the query.
+ * Block SCSS uses `@media (max-width: 800px)`.
+ */
+export const VIEWPORT_MOBILE_MAX = 800;
+
+/** Feature flag kept for existing BSM consumers. */
+export const SUPPORTS_TABLET_VIEWPORT = true;
+
+/**
+ * @param {string} key Desktop setting key.
+ * @return {string}
+ */
+export function mobileKey( key ) {
+	return `${ key }Mobile`;
+}
+
+/**
+ * @param {string} key Desktop setting key.
+ * @return {string}
+ */
+export function tabletKey( key ) {
+	return `${ key }Tablet`;
+}
+
+/**
+ * @param {string[]|undefined|null} keys Tablet allow-list from the block.
+ * @return {boolean}
+ */
+export function declaresTabletViewport( keys ) {
+	return Array.isArray( keys ) && keys.length > 0;
+}
+
+/**
+ * @param {*} value Stored value.
+ * @return {boolean}
+ */
+export function isEmptyViewportValue( value ) {
+	return (
+		value === undefined ||
+		value === null ||
+		value === '' ||
+		isNaNViewportValue( value )
+	);
+}
+
+/**
+ * @param {Object|null|undefined}       settings Setting object.
+ * @param {string}                      key      Desktop setting key.
+ * @param {'desktop'|'tablet'|'mobile'} viewport Active viewport.
+ * @return {*}
+ */
+export function getViewportValue( settings, key, viewport ) {
+	if ( viewport === VIEWPORT_MOBILE ) {
+		const mobile = settings?.[ mobileKey( key ) ];
+		if ( ! isEmptyViewportValue( mobile ) ) {
+			return mobile;
+		}
+	}
+	if ( viewport === VIEWPORT_TABLET ) {
+		const tablet = settings?.[ tabletKey( key ) ];
+		if ( ! isEmptyViewportValue( tablet ) ) {
+			return tablet;
+		}
+	}
+	const value = settings?.[ key ];
+	return isNaNViewportValue( value ) ? undefined : value;
+}
+
+/**
+ * @param {*} value Stored or typed value.
+ * @return {number|undefined}
+ */
+export function viewportNumberValue( value ) {
+	if ( typeof value === 'number' ) {
+		return Number.isFinite( value ) ? value : undefined;
+	}
+	if ( typeof value === 'string' ) {
+		const trimmed = value.trim();
+		if ( trimmed === '' ) {
+			return undefined;
+		}
+		const parsed = parseFloat( trimmed );
+		return Number.isFinite( parsed ) ? parsed : undefined;
+	}
+	return undefined;
+}
+
+/**
+ * @param {Object|null|undefined} settings Setting object.
+ * @param {string}                key      Desktop setting key.
+ * @return {boolean}
+ */
+export function isMobileOverride( settings, key ) {
+	return ! isEmptyViewportValue( settings?.[ mobileKey( key ) ] );
+}
+
+/**
+ * @param {Object|null|undefined} settings Setting object.
+ * @param {string}                key      Desktop setting key.
+ * @return {boolean}
+ */
+export function isTabletOverride( settings, key ) {
+	return ! isEmptyViewportValue( settings?.[ tabletKey( key ) ] );
+}
+
+/**
+ * @param {string}   key  Desktop setting key.
+ * @param {string[]} keys Allow-list supplied by the block.
+ * @return {boolean}
+ */
+export function isMvpOverrideKey( key, keys ) {
+	return Array.isArray( keys ) && keys.includes( key );
+}
+
+/**
+ * @param {string}                      key        Desktop setting key.
+ * @param {'desktop'|'tablet'|'mobile'} viewport   Active viewport.
+ * @param {string[]}                    keys       Mobile allow-list.
+ * @param {string[]|undefined}          tabletKeys Tablet allow-list.
+ * @return {string|null}
+ */
+export function writeViewportKey( key, viewport, keys, tabletKeys ) {
+	if ( viewport === VIEWPORT_MOBILE && isMvpOverrideKey( key, keys ) ) {
+		return mobileKey( key );
+	}
+	if ( viewport === VIEWPORT_TABLET ) {
+		if ( isMvpOverrideKey( key, tabletKeys ) ) {
+			return tabletKey( key );
+		}
+		return null;
+	}
+	return key;
+}
+
+/**
+ * @param {{ tabletMin?: number, tabletMax?: number }} [range]
+ * @return {{ mobileMax: number, tabletMin?: number, tabletMax?: number }}
+ */
+export function getViewportBreakpoints( range = {} ) {
+	const source = range && typeof range === 'object' ? range : {};
+	const config = getViewportConfig();
+	const breakpoints = {
+		mobileMax: config.mobileMax || VIEWPORT_MOBILE_MAX,
+	};
+	const tabletMin = finiteBreakpoint( source.tabletMin );
+	const tabletMax = finiteBreakpoint( source.tabletMax );
+	if ( tabletMin !== undefined ) {
+		breakpoints.tabletMin = tabletMin;
+	}
+	if ( tabletMax !== undefined ) {
+		breakpoints.tabletMax = tabletMax;
+	}
+	return breakpoints;
+}
+
+/**
+ * @param {string}   name
+ * @param {string}   cssType
+ * @param {*}        desktopVal
+ * @param {*}        mobileVal
+ * @param {Function} [getCssVarFn]
+ * @return {string}
+ */
+export function emitMobileCssVar(
+	name,
+	cssType,
+	desktopVal,
+	mobileVal,
+	getCssVarFn
+) {
+	if ( typeof getCssVarFn !== 'function' ) {
+		return '';
+	}
+	return getCssVarFn( `${ name }-mobile`, cssType, mobileVal );
+}
+
+/**
+ * @param {string}   name
+ * @param {string}   cssType
+ * @param {*}        desktopVal
+ * @param {*}        tabletVal
+ * @param {Function} [getCssVarFn]
+ * @return {string}
+ */
+export function emitTabletCssVar(
+	name,
+	cssType,
+	desktopVal,
+	tabletVal,
+	getCssVarFn
+) {
+	if ( typeof getCssVarFn !== 'function' ) {
+		return '';
+	}
+	return getCssVarFn( `${ name }-tablet`, cssType, tabletVal );
+}
+
+/**
+ * @param {*} value
+ * @return {boolean}
+ */
+function isNaNViewportValue( value ) {
+	return typeof value === 'number' && Number.isNaN( value );
+}
+
+/**
+ * @param {*} value
+ * @return {number|undefined}
+ */
+function finiteBreakpoint( value ) {
+	return typeof value === 'number' && Number.isFinite( value )
+		? value
+		: undefined;
+}