@ikas/component-cli 1.4.0-beta.20 → 1.4.0-beta.201

package/dist/utils/component-helpers.js

@@ -35,6 +35,40 @@ export function generateUniqueId() {
 export function generateComponentId(projectId) {
     return `${projectId}-${generateUniqueId()}`;
 }
+/**
+ * The editor's publish-id machinery (rewrite-asset-ids.ts, MIN_ROOT_ID_LENGTH = 6)
+ * treats a leading run of >=6 alphanumeric characters before a `-`/`_` separator as
+ * a strippable project prefix, and republish stability (insert-vs-version matching
+ * by source suffix) depends on every projectId satisfying that shape. A projectId
+ * that is shorter, or that contains a separator/non-alphanumeric character, shifts
+ * the prefix/suffix boundary and silently re-opens the duplicate-element bug.
+ * `generateProjectId()` always satisfies this; the check exists because
+ * ikas.config.json is hand-editable and parsed without a schema.
+ */
+export const PROJECT_ID_PATTERN = /^[A-Za-z0-9]{6,}$/;
+export function isValidProjectId(projectId) {
+    return PROJECT_ID_PATTERN.test(projectId);
+}
+/**
+ * A component id is publishable when the editor's prefix-strip machinery parses it
+ * unambiguously: either a legacy atomic id (alphanumeric only, no separators) or a
+ * `<projectId>-<suffix>` form whose PREFIX meets the same >=6 floor as PROJECT_ID_PATTERN.
+ * The prefix must stay >=6 alphanumeric with NO separator (the editor strips exactly one
+ * leading `>=MIN_ROOT_ID_LENGTH` run before the first `-`/`_`); a short/separator-bearing
+ * prefix shifts that boundary and re-opens the duplicate-element bug.
+ *
+ * The SUFFIX, however, may be multi-segment (`<projectId>-hero-slider`,
+ * `<projectId>-product-detail-add-to-cart`): older CLI configs used human-readable
+ * suffixes, and those ids are already placed on published themes so they cannot be
+ * renamed. The editor's `normalizeSourceElementId` canonicalizes every suffix separator
+ * to `_`, so a hyphenated local suffix and its underscore-sterilized published form
+ * normalize to the same republish-invariant key — multi-segment suffixes match stably.
+ * Each segment must still be a non-empty alphanumeric run (no trailing/doubled separators).
+ */
+export const COMPONENT_ID_PATTERN = /^(?:[A-Za-z0-9]+|[A-Za-z0-9]{6,}(?:[-_][A-Za-z0-9]+)+)$/;
+export function findInvalidComponentIds(components) {
+    return components.filter((c) => !COMPONENT_ID_PATTERN.test(c.id));
+}
 /**
  * Validate that every entry in `input` is the id of a component currently in `components`.
  * Returns the list of unknown entries (empty array means all valid).
@@ -96,8 +130,8 @@ export const PROP_TYPE_TO_TS = {
     COLOR: "string",
     PRODUCT: "IkasProduct | null",
     PRODUCT_LIST: "IkasProductList",
-    PRODUCT_ATTRIBUTE: "IkasProductAttributeValue | null",
-    PRODUCT_ATTRIBUTE_LIST: "IkasProductAttributeValue[]",
+    PRODUCT_ATTRIBUTE: "IkasProductAttributeDetail | null",
+    PRODUCT_ATTRIBUTE_LIST: "IkasProductAttributeList",
     CATEGORY: "IkasCategory | null",
     CATEGORY_LIST: "IkasCategoryList",
     BRAND: "IkasBrand | null",
@@ -111,6 +145,58 @@ export const PROP_TYPE_TO_TS = {
     COMPONENT: "any",
     COMPONENT_LIST: "any",
 };
+/**
+ * Pattern-element ("Font Style" / typography) enum sentinel. The editor builds
+ * this synthetic enum at theme time (createPatternElementEnum). Mirror of
+ * PATTERN_ELEMENT_ENUM_ID in @ikas/editor-models — kept local to avoid an
+ * editor-models dependency in the CLI.
+ */
+export const PATTERN_ELEMENT_ENUM_ID = "__patternElementEnum__";
+/**
+ * Built-in enum type ids do not need to exist in config.customTypes: @ikas/*
+ * enums ship with the storefront models, and the pattern-element sentinel is
+ * resolved by the editor at theme time. Author-defined enums are NOT built-in.
+ */
+export function isBuiltInEnumTypeId(enumTypeId) {
+    return (enumTypeId.startsWith("@ikas/") || enumTypeId === PATTERN_ELEMENT_ENUM_ID);
+}
+const ENUM_OPTIONS_EXAMPLE = `'{"Small":"sm","Medium":"md"}' or '[{"name":"Small","value":"sm"}]'`;
+/**
+ * The parsed `--options` of `config add-enum` / `config update-enum`, as the `{ "Label": "value" }`
+ * record an enum stores. The object form passes through unchanged. The array form
+ * `[{ "name": "Label", "value": "value" }]` (`label` is accepted for `name`) — which older project
+ * docs showed and agents still produce — is converted, with values stringified like every enum value.
+ */
+export function normalizeEnumOptionsInput(input) {
+    if (Array.isArray(input)) {
+        const options = {};
+        for (const item of input) {
+            if (!item || typeof item !== "object" || Array.isArray(item)) {
+                return { error: `Each option in the array must be an object { "name", "value" }, e.g. ${ENUM_OPTIONS_EXAMPLE}.` };
+            }
+            const { name, label, value } = item;
+            const optionLabel = name ?? label;
+            if (typeof optionLabel !== "string" || !optionLabel.trim()) {
+                return { error: `Every option needs a non-empty string "name", e.g. ${ENUM_OPTIONS_EXAMPLE}.` };
+            }
+            if ((typeof value !== "string" && typeof value !== "number") || String(value).trim() === "") {
+                return { error: `Option "${optionLabel}" needs a non-empty string "value", e.g. ${ENUM_OPTIONS_EXAMPLE}.` };
+            }
+            if (Object.prototype.hasOwnProperty.call(options, optionLabel)) {
+                return { error: `Duplicate option name "${optionLabel}".` };
+            }
+            options[optionLabel] = String(value);
+        }
+        if (Object.keys(options).length === 0) {
+            return { error: `Options must not be empty, e.g. ${ENUM_OPTIONS_EXAMPLE}.` };
+        }
+        return { options };
+    }
+    if (input && typeof input === "object" && Object.keys(input).length > 0) {
+        return { options: input };
+    }
+    return { error: `Options must be a non-empty JSON object or array, e.g. ${ENUM_OPTIONS_EXAMPLE}.` };
+}
 export function toKebabCase(str) {
     return str
         .replace(/([a-z])([A-Z])/g, "$1-$2")
@@ -149,14 +235,16 @@ function resolveTypeId(typeId) {
  */
 function resolveCustomEnumTypeName(enumTypeId, editorTypes, customTypes) {
     if (editorTypes) {
-        const editorType = editorTypes.find(t => t.id === enumTypeId);
-        if (editorType?.enumOptions && Object.keys(editorType.enumOptions).length > 0) {
+        const editorType = editorTypes.find((t) => t.id === enumTypeId);
+        if (editorType?.enumOptions &&
+            Object.keys(editorType.enumOptions).length > 0) {
             return toPascalCase(editorType.name);
         }
     }
     if (customTypes) {
-        const customType = customTypes.find(t => t.id === enumTypeId);
-        if (customType?.enumOptions && Object.keys(customType.enumOptions).length > 0) {
+        const customType = customTypes.find((t) => t.id === enumTypeId);
+        if (customType?.enumOptions &&
+            Object.keys(customType.enumOptions).length > 0) {
             return toPascalCase(customType.name);
         }
     }
@@ -176,7 +264,9 @@ export function generateTypesFile(componentName, props, type, editorTypes, custo
                 typeIdResolved.set(prop.name, resolved.isArray ? `${resolved.typeName}[]` : resolved.typeName);
             }
         }
-        else if (prop.type === "ENUM" && prop.enumTypeId) {
+        else if (prop.type === "ENUM" &&
+            prop.enumTypeId &&
+            prop.enumTypeId !== PATTERN_ELEMENT_ENUM_ID) {
             const resolved = resolveTypeId(prop.enumTypeId);
             if (resolved) {
                 // Built-in enum — import from @ikas/bp-storefront
@@ -193,6 +283,9 @@ export function generateTypesFile(componentName, props, type, editorTypes, custo
             }
         }
         else {
+            // Non-ENUM props, plus the font-style (pattern-element) sentinel whose
+            // runtime value is a plain pattern-element id string → PROP_TYPE_TO_TS
+            // (PROP_TYPE_TO_TS["ENUM"] === "string"), no import emitted.
             const tsType = PROP_TYPE_TO_TS[prop.type];
             if (tsType?.includes("Ikas")) {
                 const matches = tsType.match(/Ikas\w+/g);
@@ -298,6 +391,96 @@ export function collectUsedCustomTypeIds(customTypes, components) {
     }
     return used;
 }
+/**
+ * Enum ids referenced by ENUM theme settings. Their union types must be emitted into
+ * `global-types.ts` even when no component prop uses the enum, so the setting's value-map
+ * entry (and `themeValue()`) can narrow to it.
+ */
+export function collectThemeSettingEnumIds(themeSettings) {
+    const ids = new Set();
+    for (const s of themeSettings || []) {
+        if (s.type === "ENUM" && s.enumTypeId)
+            ids.add(s.enumTypeId);
+    }
+    return ids;
+}
+/**
+ * Map a global-variable kind to a TS type. Primitives narrowed; complex kinds stay `any`. An
+ * ENUM setting narrows to the union type THIS file declares for its enum: `resolveEnumTypeName`
+ * only knows the enums emitted above the theme block, so the map can never name an undeclared
+ * identifier. An ENUM whose enum is not emitted here — a deleted type, or a built-in `@ikas/*`
+ * enum (which the editor does not accept for a theme global, and whose import from
+ * `@ikas/bp-storefront` this generator cannot verify) — degrades to `string`.
+ */
+function themeSettingTsType(setting, resolveEnumTypeName) {
+    switch (setting.type) {
+        case "NUMBER":
+            return "number";
+        case "BOOLEAN":
+            return "boolean";
+        case "TEXT":
+        case "RICH_TEXT":
+        case "COLOR":
+            return "string";
+        case "ENUM":
+            return ((setting.enumTypeId && resolveEnumTypeName(setting.enumTypeId)) ||
+                "string");
+        default:
+            return "any"; // IMAGE, BORDER, SHADOW — object shapes can drift from runtime
+    }
+}
+/**
+ * Import line for the typed theme-globals wrapper. Must sit at the top of the generated
+ * file (after the header). Emitted only when there are theme globals.
+ *
+ * A module augmentation can't deliver key-safety here: the runtime `getThemeSettingValue`
+ * is declared `(name: string): any`, so an added narrower overload never wins resolution —
+ * unknown keys still match `string` and return `any`. A generated wrapper whose parameter
+ * is `ThemeSettingName` (no `string` overload) does reject unknown keys and narrow the value.
+ */
+const THEME_GLOBALS_IMPORT = `import { getThemeSettingValue as _getThemeSettingValueRaw } from "@ikas/bp-storefront";\n`;
+/**
+ * Sentinel that marks a generated `global-types.ts` as containing the theme-globals block.
+ * This is the exported symbol authors import (stable public API), and it must stay a substring
+ * of what {@link generateThemeGlobalsBlock} emits — keep the two in sync if that output changes.
+ */
+const THEME_GLOBALS_MARKER = "export type ThemeSettingName";
+/**
+ * Build the theme-globals block for `src/global-types.ts`: the key union, a value-type map,
+ * and a type-safe `themeValue` wrapper (authors import it from `./global-types`). The wrapper
+ * is deliberately named differently from the SDK's `getThemeSettingValue` so authors can't
+ * accidentally import the untyped SDK version and lose key-safety (no shadowing).
+ * Returns "" when there are no globals (an empty union would resolve to `never`). The import
+ * the wrapper needs is emitted separately via {@link THEME_GLOBALS_IMPORT}.
+ */
+function generateThemeGlobalsBlock(themeSettings, resolveEnumTypeName = () => null) {
+    if (!themeSettings || themeSettings.length === 0)
+        return "";
+    const sorted = [...themeSettings].sort((a, b) => a.name.localeCompare(b.name));
+    const unionLines = sorted
+        .map((s) => {
+        // Escape the JSDoc comment terminator to avoid prematurely closing the
+        // generated `/** ... */` block when a displayName contains `*/`.
+        const label = String(s.displayName).replace(/\*\//g, "*\\/");
+        return `  /** ${label} (${s.type}) */\n  | ${JSON.stringify(s.name)}`;
+    })
+        .join("\n");
+    const mapLines = sorted
+        .map((s) => `  ${JSON.stringify(s.name)}: ${themeSettingTsType(s, resolveEnumTypeName)};`)
+        .join("\n");
+    return (`\n/** Stable keys of theme global variables defined in the editor's "Styles" panel. */\n` +
+        `export type ThemeSettingName =\n${unionLines};\n\n` +
+        `/** Narrowed value type per global key (primitives and ENUM unions; complex kinds are \`any\`). */\n` +
+        `type ThemeSettingValueMap = {\n${mapLines}\n};\n\n` +
+        `/**\n` +
+        ` * Type-safe theme global accessor — only accepts keys declared in the editor's Styles panel.\n` +
+        ` * Import this from \`./global-types\`, not \`getThemeSettingValue\` from \`@ikas/bp-storefront\`\n` +
+        ` * (that one is untyped: it accepts any string and returns \`any\`).\n` +
+        ` */\n` +
+        `export function themeValue<K extends ThemeSettingName>(name: K): ThemeSettingValueMap[K] {\n` +
+        `  return _getThemeSettingValueRaw(name) as ThemeSettingValueMap[K];\n` +
+        `}\n`);
+}
 /**
  * Generate the content for `src/global-types.ts`.
  * Collects all custom enum types from editorTypes (preferred) or customTypes (fallback)
@@ -311,8 +494,11 @@ export function generateGlobalTypesFile(editorTypes, customTypes,
  * Callers should compute this from `config.components[*].props[*].enumTypeId`
  * so unused enums are excluded from `global-types.ts`.
  */
-usedEnumIds) {
+usedEnumIds, themeSettings) {
     const header = `// Auto-generated global type definitions for ikas code components.\n// This file is regenerated automatically — do not edit manually.\n`;
+    // Enums an ENUM theme setting selects from are emitted regardless of `usedEnumIds`: the
+    // setting's value-map entry names them, so they must exist even if no prop uses them.
+    const forcedEnumIds = collectThemeSettingEnumIds(themeSettings);
     // Collect all custom enum types with their options
     // Use a Map keyed by type ID to deduplicate
     const enumTypes = new Map();
@@ -320,10 +506,10 @@ usedEnumIds) {
     if (editorTypes) {
         for (const t of editorTypes) {
             if (t.enumOptions && Object.keys(t.enumOptions).length > 0) {
-                // Skip built-in types
-                if (t.id.startsWith("@ikas/"))
+                // Skip built-in types (@ikas/* and the pattern-element font-style sentinel)
+                if (isBuiltInEnumTypeId(t.id))
                     continue;
-                if (usedEnumIds && !usedEnumIds.has(t.id))
+                if (usedEnumIds && !usedEnumIds.has(t.id) && !forcedEnumIds.has(t.id))
                     continue;
                 enumTypes.set(t.id, {
                     name: toPascalCase(t.name),
@@ -339,9 +525,9 @@ usedEnumIds) {
             const id = t.id;
             if (enumTypes.has(id))
                 continue;
-            if (id.startsWith("@ikas/"))
+            if (isBuiltInEnumTypeId(id))
                 continue;
-            if (usedEnumIds && !usedEnumIds.has(id))
+            if (usedEnumIds && !usedEnumIds.has(id) && !forcedEnumIds.has(id))
                 continue;
             if (t.enumOptions && Object.keys(t.enumOptions).length > 0) {
                 enumTypes.set(id, {
@@ -352,17 +538,56 @@ usedEnumIds) {
             }
         }
     }
+    // The theme block may only name enum types declared in THIS file (see themeSettingTsType).
+    const resolveEnumTypeName = (enumTypeId) => enumTypes.get(enumTypeId)?.name ?? null;
+    const themeBlock = generateThemeGlobalsBlock(themeSettings, resolveEnumTypeName);
+    // The wrapper's runtime import must sit at the top of the file (after the header).
+    const themeImport = themeBlock ? THEME_GLOBALS_IMPORT : "";
     if (enumTypes.size === 0) {
-        return `${header}// Custom enum types from the editor will appear here.\n\nexport {};\n`;
+        if (!themeBlock) {
+            return `${header}// Custom enum types from the editor will appear here.\n\nexport {};\n`;
+        }
+        return `${header}${themeImport}${themeBlock}`;
     }
     // Sort by type name for stable output
     const sorted = Array.from(enumTypes.values()).sort((a, b) => a.name.localeCompare(b.name));
-    let content = `${header}\n`;
+    let content = `${header}${themeImport}\n`;
     for (const enumType of sorted) {
-        const unionType = enumType.options.map(v => `"${v}"`).join(" | ");
+        const unionType = enumType.options.map((v) => `"${v}"`).join(" | ");
         content += `/** Enum type: ${enumType.id} */\nexport type ${enumType.name} = ${unionType};\n`;
     }
-    return content;
+    return `${content}${themeBlock}`;
+}
+/**
+ * Decide whether freshly generated `global-types.ts` content should overwrite
+ * the existing file on disk.
+ *
+ * Guards the dev-server startup race: before the editor connects, the theme
+ * settings cache is empty, so the generated content omits the theme-globals
+ * block (`themeValue`, `ThemeSettingName`). Writing it would clobber the rich
+ * file left from the previous session and break every component that imports
+ * those exports until the editor reconnects and re-syncs. While theme settings
+ * are not yet cached, preserve an existing theme-globals block instead of
+ * stubbing it out — the editor's `onSyncTypes` is the authoritative writer once
+ * connected.
+ *
+ * @param existing               current file content, or null if the file is absent
+ * @param next                   freshly generated content
+ * @param hasThemeSettingsCached whether the editor has synced theme settings yet
+ */
+export function shouldWriteGlobalTypes(existing, next, hasThemeSettingsCached) {
+    // No file yet — always write so imports resolve.
+    if (existing === null)
+        return true;
+    // Identical content — skip to avoid file-watcher loops.
+    if (existing === next)
+        return false;
+    // Editor has synced theme settings — it's authoritative, write freely.
+    if (hasThemeSettingsCached)
+        return true;
+    // Not synced yet: write unless we'd drop an existing theme-globals block for a stub.
+    return (!existing.includes(THEME_GLOBALS_MARKER) ||
+        next.includes(THEME_GLOBALS_MARKER));
 }
 export function generateComponentFile(componentName, props, type) {
     const propsDestructure = props.map((p) => p.name).join(", ");
@@ -392,6 +617,39 @@ export function updateBarrelExport(projectRoot, componentNames) {
         .join("\n") + "\n";
     fs.writeFileSync(indexPath, content);
 }
+/**
+ * A config visibility gate in wire form, or nothing at all — spread it.
+ *
+ * Config names the governing prop; the editor needs its id, and ids are minted here from position.
+ * A gate naming a prop this component does not have is dropped rather than passed on: the editor
+ * would show the control anyway, and a dangling id in the theme is worse than none.
+ */
+export function resolveCondition(gate, propIdByName) {
+    if (!gate?.requiredProp)
+        return {};
+    const requiredPropId = propIdByName.get(gate.requiredProp);
+    if (!requiredPropId)
+        return {};
+    // An ENUM gate carries its option and no boolean state; a BOOLEAN one the reverse. Emitting only
+    // the half that applies keeps a stale option from a re-typed governing prop out of the theme.
+    if (gate.requiredEnumOptionValue !== undefined) {
+        return {
+            requiredPropId,
+            requiredEnumOptionId: gate.requiredEnumOptionId,
+            requiredEnumOptionValue: gate.requiredEnumOptionValue,
+        };
+    }
+    return { requiredPropId, requiredPropValue: gate.requiredPropValue ?? true };
+}
+/**
+ * Config prop name to the id this component's props are broadcast under.
+ *
+ * The formula is duplicated at each mapping site (dev broadcast, config rebuild, publish); this
+ * reads it back off whatever that site produced rather than restating it a fourth time.
+ */
+export function propIdsByName(props) {
+    return new Map(props.map((prop) => [prop.name, prop.id]));
+}
 /**
  * Convert flat config-format prop groups into an IThemePropGroup[] hierarchy.
  *
@@ -405,11 +663,14 @@ export function updateBarrelExport(projectRoot, componentNames) {
  */
 export function buildPropGroupHierarchy(componentId, propGroups, props) {
     const result = [];
+    // A group names its governing prop; the leaf wrappers below carry no gate of their own, because a
+    // prop's gate travels on the prop itself (see `resolveCondition` at each prop mapping site).
+    const propIdByName = propIdsByName(props);
     for (const group of propGroups) {
         const groupGlobalId = `${componentId}_pg_${group.id}`;
         // Collect props assigned to this group
-        const groupProps = props.filter(p => p.groupId === group.id);
-        const propChildren = groupProps.map(p => ({
+        const groupProps = props.filter((p) => p.groupId === group.id);
+        const propChildren = groupProps.map((p) => ({
             id: `${componentId}_pgp_${p.id}`,
             propId: p.id,
         }));
@@ -419,8 +680,8 @@ export function buildPropGroupHierarchy(componentId, propGroups, props) {
             for (const child of group.children) {
                 const childGlobalId = `${componentId}_pg_${child.id}`;
                 // Collect props assigned to this child group
-                const childProps = props.filter(p => p.groupId === child.id);
-                const childPropChildren = childProps.map(p => ({
+                const childProps = props.filter((p) => p.groupId === child.id);
+                const childPropChildren = childProps.map((p) => ({
                     id: `${componentId}_pgp_${p.id}`,
                     propId: p.id,
                 }));
@@ -428,7 +689,10 @@ export function buildPropGroupHierarchy(componentId, propGroups, props) {
                     id: childGlobalId,
                     name: child.name,
                     ...(child.description ? { description: child.description } : {}),
-                    ...(childPropChildren.length > 0 ? { children: childPropChildren } : {}),
+                    ...resolveCondition(child, propIdByName),
+                    ...(childPropChildren.length > 0
+                        ? { children: childPropChildren }
+                        : {}),
                 });
             }
         }
@@ -437,19 +701,117 @@ export function buildPropGroupHierarchy(componentId, propGroups, props) {
             id: groupGlobalId,
             name: group.name,
             ...(group.description ? { description: group.description } : {}),
+            ...resolveCondition(group, propIdByName),
             ...(allChildren.length > 0 ? { children: allChildren } : {}),
         });
     }
     return result;
 }
+/** Every group id under `group`, itself included — the groups a prop assigned "inside" it can sit in. */
+export function groupIdsUnder(group) {
+    return new Set([
+        group.id,
+        ...(group.children || []).map((child) => child.id),
+    ]);
+}
+/**
+ * Validate a visibility condition — the `requiredProp` family on a prop or a prop group — against
+ * the component it lives on. Returns an error message, or null when it is sound (or absent).
+ *
+ * What is rejected, and why each one would otherwise strand a control with no way to reach it:
+ *
+ * - a name no prop on this component has, or a prop that is not BOOLEAN — nothing to read a
+ *   true/false off, so the gate could never resolve;
+ * - a prop gating itself, or a chain of props that comes back around to it — every prop in the
+ *   cycle stays hidden forever, including the toggles that would let someone out of it;
+ * - an ENUM gate with no option to wait for, or an option value hung on a BOOLEAN prop;
+ * - a group gated by a toggle that lives inside it — turning that toggle off takes the toggle away
+ *   with the rest of the group.
+ */
+export function visibilityGateError(component, gate, where, opts = {}) {
+    const { requiredProp, requiredPropValue, requiredEnumOptionValue } = gate;
+    if (requiredProp === undefined || requiredProp === null) {
+        return requiredPropValue === undefined &&
+            requiredEnumOptionValue === undefined
+            ? null
+            : `${where} declares a visibility state with no requiredProp to read it off. Name the prop that gates it, or drop both.`;
+    }
+    if (typeof requiredProp !== "string" || !requiredProp) {
+        return `requiredProp on ${where} must be the name of a BOOLEAN or ENUM prop on this component.`;
+    }
+    if (requiredPropValue !== undefined &&
+        typeof requiredPropValue !== "boolean") {
+        return `requiredPropValue on ${where} must be true or false (it defaults to true).`;
+    }
+    if (opts.selfPropName && requiredProp === opts.selfPropName) {
+        return `${where} cannot gate itself on "${requiredProp}".`;
+    }
+    const governing = component.props.find((prop) => prop.name === requiredProp);
+    if (!governing) {
+        const names = component.props.map((prop) => prop.name).join(", ");
+        return `requiredProp "${requiredProp}" on ${where} is not a prop of component "${component.name}". Available props: ${names || "(none)"}.`;
+    }
+    if (governing.type !== "BOOLEAN" && governing.type !== "ENUM") {
+        return `requiredProp "${requiredProp}" on ${where} is a ${governing.type} prop; only a BOOLEAN or ENUM prop can gate visibility.`;
+    }
+    // An ENUM gate is meaningless without the option it waits for: nothing would ever match it, so
+    // the node would never appear at all.
+    if (governing.type === "ENUM" &&
+        typeof requiredEnumOptionValue !== "string") {
+        return `requiredProp "${requiredProp}" on ${where} is an ENUM prop, so requiredEnumOptionValue must name the option value that shows it.`;
+    }
+    if (governing.type === "BOOLEAN" && requiredEnumOptionValue !== undefined) {
+        return `requiredEnumOptionValue on ${where} has no meaning against the BOOLEAN prop "${requiredProp}" — use requiredPropValue instead.`;
+    }
+    if (opts.group &&
+        governing.groupId &&
+        groupIdsUnder(opts.group).has(governing.groupId)) {
+        return `requiredProp "${requiredProp}" on ${where} sits inside that group — hiding the group would take that control with it, leaving nothing to bring it back.`;
+    }
+    // Walk the chain the governing prop hangs on. It cannot come back to this prop, and it cannot
+    // close on itself either — a cycle anywhere in it hides everything on it.
+    const byName = new Map(component.props.map((prop) => [prop.name, prop]));
+    const seen = new Set([requiredProp]);
+    let current = governing.requiredProp;
+    while (current) {
+        if (opts.selfPropName && current === opts.selfPropName) {
+            return `requiredProp "${requiredProp}" on ${where} depends on it in turn — the two would hide each other permanently.`;
+        }
+        if (seen.has(current)) {
+            return `requiredProp "${requiredProp}" on ${where} sits in a visibility cycle through "${current}" — everything on it would stay hidden.`;
+        }
+        seen.add(current);
+        current = byName.get(current)?.requiredProp;
+    }
+    return null;
+}
 /**
  * Validate prop groups configuration for a component.
  * Returns an array of error messages (empty = valid).
  */
 export function validatePropGroups(component) {
     const errors = [];
-    const propGroups = component.propGroups;
-    if (!propGroups || propGroups.length === 0)
+    const propGroups = component.propGroups || [];
+    // A prop can name a visibility gate whether or not this component has groups at all, so gates are
+    // checked before the group walk bails out below.
+    for (const prop of component.props) {
+        const error = visibilityGateError(component, prop, `prop "${prop.name}"`, {
+            selfPropName: prop.name,
+        });
+        if (error)
+            errors.push(error);
+    }
+    for (const group of [
+        ...propGroups,
+        ...propGroups.flatMap((group) => group.children || []),
+    ]) {
+        const error = visibilityGateError(component, group, `group "${group.id}"`, {
+            group,
+        });
+        if (error)
+            errors.push(error);
+    }
+    if (propGroups.length === 0)
         return errors;
     // Collect all group IDs and check uniqueness
     const allIds = new Set();
@@ -528,7 +890,9 @@ export function movePropGroupInTree(propGroups, propGroupId, parentGroupId, inde
     const found = findPropGroup(propGroups, propGroupId);
     if (!found)
         throw new Error(`Prop group "${propGroupId}" not found`);
-    if (parentGroupId && found.group.children && found.group.children.length > 0) {
+    if (parentGroupId &&
+        found.group.children &&
+        found.group.children.length > 0) {
         throw new Error(`Cannot nest "${propGroupId}": it already has child groups`);
     }
     if (parentGroupId) {
@@ -542,10 +906,10 @@ export function movePropGroupInTree(propGroups, propGroupId, parentGroupId, inde
     }
     let roots = propGroups;
     if (found.parent) {
-        found.parent.children = (found.parent.children || []).filter(c => c.id !== propGroupId);
+        found.parent.children = (found.parent.children || []).filter((c) => c.id !== propGroupId);
     }
     else {
-        roots = roots.filter(g => g.id !== propGroupId);
+        roots = roots.filter((g) => g.id !== propGroupId);
     }
     if (parentGroupId) {
         const target = findPropGroup(roots, parentGroupId);
@@ -553,13 +917,17 @@ export function movePropGroupInTree(propGroups, propGroupId, parentGroupId, inde
             throw new Error(`Target parent group "${parentGroupId}" not found after removal`);
         if (!target.group.children)
             target.group.children = [];
-        const insertAt = typeof index === "number" && index >= 0 && index <= target.group.children.length
+        const insertAt = typeof index === "number" &&
+            index >= 0 &&
+            index <= target.group.children.length
             ? index
             : target.group.children.length;
         target.group.children.splice(insertAt, 0, found.group);
     }
     else {
-        const insertAt = typeof index === "number" && index >= 0 && index <= roots.length ? index : roots.length;
+        const insertAt = typeof index === "number" && index >= 0 && index <= roots.length
+            ? index
+            : roots.length;
         roots.splice(insertAt, 0, found.group);
     }
     return roots;