@wp-typia/block-types 0.2.4 → 0.3.0

package/dist/blocks/variations.js

@@ -0,0 +1,298 @@
+import { createWordPressBlockApiCompatibilityManifest, } from "./compatibility.js";
+export const DEFINED_BLOCK_VARIATION_METADATA = Symbol.for("@wp-typia/block-types/defined-variation");
+export const DEFINED_BLOCK_VARIATIONS_METADATA = Symbol.for("@wp-typia/block-types/defined-variations");
+const DEFINE_VARIATION_INLINE_OPTION_KEYS = new Set([
+    "allowMissingIsActive",
+    "minVersion",
+    "minWordPress",
+    "onDiagnostic",
+    "requireIsActive",
+    "strict",
+]);
+const STABLE_VARIATION_MARKER_ATTRIBUTES = [
+    "className",
+    "namespace",
+    "wpTypiaVariation",
+];
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function splitDefineVariationInput(variation) {
+    const inlineOptions = {};
+    const normalizedVariation = {};
+    for (const [key, value] of Object.entries(variation)) {
+        if (DEFINE_VARIATION_INLINE_OPTION_KEYS.has(key)) {
+            Object.assign(inlineOptions, { [key]: value });
+            continue;
+        }
+        normalizedVariation[key] = value;
+    }
+    return {
+        inlineOptions,
+        variation: normalizedVariation,
+    };
+}
+function resolveDefineVariationSettings(inlineOptions, options) {
+    const compatibility = {};
+    const allowUnknownFutureKeys = options.allowUnknownFutureKeys;
+    const minVersion = options.minVersion ??
+        options.minWordPress ??
+        inlineOptions.minVersion ??
+        inlineOptions.minWordPress;
+    const strict = options.strict ?? inlineOptions.strict ?? true;
+    if (allowUnknownFutureKeys !== undefined) {
+        Object.assign(compatibility, { allowUnknownFutureKeys });
+    }
+    if (minVersion !== undefined) {
+        Object.assign(compatibility, { minVersion });
+    }
+    Object.assign(compatibility, { strict });
+    return {
+        compatibility,
+        diagnostics: {
+            allowMissingIsActive: options.allowMissingIsActive ?? inlineOptions.allowMissingIsActive ?? false,
+            requireIsActive: options.requireIsActive ?? inlineOptions.requireIsActive ?? true,
+            strict,
+        },
+        onDiagnostic: options.onDiagnostic ?? inlineOptions.onDiagnostic,
+    };
+}
+function getDiagnosticSeverity(strict) {
+    return strict ? "error" : "warning";
+}
+export function collectBlockVariationCompatibilityFeatures() {
+    return [
+        {
+            area: "blockVariations",
+            feature: "editorRegistration",
+        },
+    ];
+}
+export function createBlockVariationCompatibilityManifest(settings = {}) {
+    const resolved = resolveDefineVariationSettings({}, settings);
+    return createWordPressBlockApiCompatibilityManifest(collectBlockVariationCompatibilityFeatures(), resolved.compatibility);
+}
+function hasStableMarkerAttribute(attributes) {
+    if (!isObjectRecord(attributes)) {
+        return false;
+    }
+    return STABLE_VARIATION_MARKER_ATTRIBUTES.some((key) => key in attributes);
+}
+function createVariationDiagnostics(blockName, variation, options) {
+    const diagnostics = [];
+    const variationName = variation.name;
+    const attributes = variation.attributes;
+    const isActive = variation.isActive;
+    if (options.requireIsActive &&
+        !options.allowMissingIsActive &&
+        !variation.isDefault &&
+        isActive === undefined) {
+        diagnostics.push({
+            blockName,
+            code: "missing-is-active",
+            message: `Block variation "${variationName}" for "${blockName}" does not declare isActive; add an active discriminator or set allowMissingIsActive.`,
+            severity: "warning",
+            variationName,
+        });
+    }
+    if (options.requireIsActive &&
+        !options.allowMissingIsActive &&
+        !variation.isDefault &&
+        isActive === undefined &&
+        !hasStableMarkerAttribute(attributes)) {
+        diagnostics.push({
+            blockName,
+            code: "missing-stable-marker",
+            message: `Block variation "${variationName}" for "${blockName}" has no stable marker attribute such as className, namespace, or wpTypiaVariation.`,
+            severity: "warning",
+            variationName,
+        });
+    }
+    if (Array.isArray(isActive)) {
+        for (const attribute of isActive) {
+            if (!isObjectRecord(attributes) || !(attribute in attributes)) {
+                diagnostics.push({
+                    attribute,
+                    blockName,
+                    code: "unknown-is-active-attribute",
+                    message: `Block variation "${variationName}" for "${blockName}" uses isActive attribute "${attribute}" that is not present in its attributes.`,
+                    severity: "warning",
+                    variationName,
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+function handleVariationDiagnostics(diagnostics, onDiagnostic) {
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+        throw new Error([
+            "WordPress block variation check failed:",
+            ...errors.map((diagnostic) => `- ${diagnostic.message}`),
+        ].join("\n"));
+    }
+    for (const diagnostic of diagnostics) {
+        if (onDiagnostic) {
+            onDiagnostic(diagnostic);
+            continue;
+        }
+        console.warn(`[wp-typia] ${diagnostic.message}`);
+    }
+}
+export function getDefinedVariationMetadata(variation) {
+    return isObjectRecord(variation)
+        ? variation[DEFINED_BLOCK_VARIATION_METADATA]
+        : undefined;
+}
+export function getDefinedVariationBlockName(variation) {
+    return getDefinedVariationMetadata(variation)?.blockName;
+}
+export function getDefinedVariationCompatibilityManifest(variation) {
+    return getDefinedVariationMetadata(variation)?.manifest;
+}
+export function getDefinedVariationsMetadata(variations) {
+    return Array.isArray(variations)
+        ? variations[DEFINED_BLOCK_VARIATIONS_METADATA]
+        : undefined;
+}
+export function defineVariation(blockName, variation, options = {}) {
+    const { inlineOptions, variation: normalizedVariation } = splitDefineVariationInput(variation);
+    const resolved = resolveDefineVariationSettings(inlineOptions, options);
+    const manifest = createWordPressBlockApiCompatibilityManifest(collectBlockVariationCompatibilityFeatures(), resolved.compatibility);
+    const diagnostics = [
+        ...manifest.diagnostics,
+        ...createVariationDiagnostics(blockName, normalizedVariation, resolved.diagnostics),
+    ];
+    handleVariationDiagnostics(diagnostics, resolved.onDiagnostic);
+    Object.defineProperty(normalizedVariation, DEFINED_BLOCK_VARIATION_METADATA, {
+        configurable: false,
+        enumerable: false,
+        value: {
+            blockName,
+            diagnostics,
+            manifest,
+        },
+        writable: false,
+    });
+    return normalizedVariation;
+}
+function createCollectionDiagnostics(entries, strict) {
+    const diagnostics = [];
+    const seenNames = new Map();
+    const seenActiveMarkers = new Map();
+    for (const entry of entries) {
+        const nameKey = `${entry.blockName}:${entry.variation.name}`;
+        const activeMarker = Array.isArray(entry.variation.isActive)
+            ? entry.variation.isActive.join("|")
+            : undefined;
+        if (seenNames.has(nameKey)) {
+            diagnostics.push({
+                blockName: entry.blockName,
+                code: "duplicate-variation-name",
+                message: `Duplicate block variation name "${entry.variation.name}" for "${entry.blockName}".`,
+                severity: getDiagnosticSeverity(strict),
+                variationName: entry.variation.name,
+            });
+        }
+        seenNames.set(nameKey, entry);
+        if (activeMarker && activeMarker.length > 0) {
+            const markerKey = `${entry.blockName}:${activeMarker}`;
+            const existing = seenActiveMarkers.get(markerKey);
+            if (existing) {
+                diagnostics.push({
+                    blockName: entry.blockName,
+                    code: "duplicate-active-marker",
+                    message: `Block variations "${existing.variation.name}" and "${entry.variation.name}" for "${entry.blockName}" share the same isActive discriminator "${activeMarker}".`,
+                    severity: "warning",
+                    variationName: entry.variation.name,
+                });
+            }
+            seenActiveMarkers.set(markerKey, entry);
+        }
+    }
+    return diagnostics;
+}
+export function createBlockVariationRegistrationPlan(variations) {
+    return variations.map((variation) => {
+        const metadata = getDefinedVariationMetadata(variation);
+        if (!metadata) {
+            throw new Error(`Block variation "${variation.name}" was not created by defineVariation().`);
+        }
+        return {
+            blockName: metadata.blockName,
+            variation,
+        };
+    });
+}
+export function defineVariations(variations, options = {}) {
+    const entries = createBlockVariationRegistrationPlan(variations);
+    const strict = options.strict ?? true;
+    const variationDiagnostics = entries.flatMap((entry) => getDefinedVariationMetadata(entry.variation)?.diagnostics ?? []);
+    const collectionDiagnostics = createCollectionDiagnostics(entries, strict);
+    const diagnostics = [
+        ...variationDiagnostics,
+        ...collectionDiagnostics,
+    ];
+    handleVariationDiagnostics(collectionDiagnostics, options.onDiagnostic);
+    const normalizedVariations = [...variations];
+    Object.defineProperty(normalizedVariations, DEFINED_BLOCK_VARIATIONS_METADATA, {
+        configurable: false,
+        enumerable: false,
+        value: {
+            diagnostics,
+            entries,
+        },
+        writable: false,
+    });
+    return normalizedVariations;
+}
+function normalizeStaticRegistrationValue(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "function") {
+        throw new Error(`Cannot generate static variation registration code for function value at ${path}.`);
+    }
+    if (typeof value === "bigint" || typeof value === "symbol") {
+        throw new Error(`Cannot generate static variation registration code for ${typeof value} value at ${path}.`);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => normalizeStaticRegistrationValue(entry, `${path}[${index}]`));
+    }
+    if (isObjectRecord(value)) {
+        const normalized = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            const nextValue = normalizeStaticRegistrationValue(nestedValue, `${path}.${key}`);
+            if (nextValue !== undefined) {
+                normalized[key] = nextValue;
+            }
+        }
+        return normalized;
+    }
+    throw new Error(`Cannot generate static variation registration code for unsupported value at ${path}.`);
+}
+export function createStaticBlockVariationRegistrationSource(variations, options = {}) {
+    const importSource = options.importSource ?? "@wordpress/blocks";
+    const functionName = options.functionName ?? "registerWpTypiaBlockVariations";
+    const entries = createBlockVariationRegistrationPlan(variations).map((entry, index) => normalizeStaticRegistrationValue(entry, `variations[${index}]`));
+    const serializedEntries = JSON.stringify(entries, null, 2);
+    return [
+        `import { registerBlockVariation } from ${JSON.stringify(importSource)};`,
+        "",
+        `const variations = ${serializedEntries};`,
+        "",
+        `export function ${functionName}() {`,
+        "  for (const { blockName, variation } of variations) {",
+        "    registerBlockVariation(blockName, variation);",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/block-types",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Shared WordPress block semantic types derived from Gutenberg and unofficial declarations",
   "type": "module",
   "main": "dist/index.js",
@@ -56,6 +56,16 @@
       "import": "./dist/blocks/index.js",
       "default": "./dist/blocks/index.js"
     },
+    "./blocks/bindings": {
+      "types": "./dist/blocks/bindings.d.ts",
+      "import": "./dist/blocks/bindings.js",
+      "default": "./dist/blocks/bindings.js"
+    },
+    "./blocks/compatibility": {
+      "types": "./dist/blocks/compatibility.d.ts",
+      "import": "./dist/blocks/compatibility.js",
+      "default": "./dist/blocks/compatibility.js"
+    },
     "./blocks/registration": {
       "types": "./dist/blocks/registration.d.ts",
       "import": "./dist/blocks/registration.js",
@@ -66,6 +76,11 @@
       "import": "./dist/blocks/supports.js",
       "default": "./dist/blocks/supports.js"
     },
+    "./blocks/variations": {
+      "types": "./dist/blocks/variations.d.ts",
+      "import": "./dist/blocks/variations.js",
+      "default": "./dist/blocks/variations.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [