@synergy-design-system/metadata 3.7.0 → 3.9.0

package/dist/intentPolicy/intermediate-representation/types.d.ts

@@ -0,0 +1,38 @@
+import type { IntentPhase, IntentPresetValue, IntentTargetRef } from '../types.js';
+/**
+ * Supported framework profiles for parsing and rendering intent output.
+ */
+export type FrameworkProfile = 'react-wrapper' | 'react-web-components' | 'angular' | 'vue' | 'vanilla';
+/**
+ * Union of node shapes supported by the intermediate representation tree.
+ */
+export type IntermediateRepresentationNode = IntermediateRepresentationComponentNode | IntermediateRepresentationTextNode;
+/**
+ * Literal text node in the intermediate representation tree.
+ */
+export type IntermediateRepresentationTextNode = {
+    kind: 'text';
+    value: string;
+};
+/**
+ * Component node in the intermediate representation tree.
+ */
+export type IntermediateRepresentationComponentNode = {
+    children?: IntermediateRepresentationNode[];
+    component: string;
+    intentId?: string;
+    kind: 'component';
+    phase?: IntentPhase;
+    props?: Record<string, IntentPresetValue>;
+    target?: IntentTargetRef;
+};
+/**
+ * Root document container for intent intermediate representation output.
+ */
+export type IntermediateRepresentationDocument = {
+    framework: FrameworkProfile;
+    intentId: string;
+    irVersion: '1.0';
+    root: IntermediateRepresentationComponentNode;
+    target: IntentTargetRef;
+};

package/dist/intentPolicy/intermediate-representation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/intentPolicy/mappings/framework-targets.d.ts

@@ -0,0 +1,5 @@
+import type { FrameworkProfile } from '../intermediate-representation/types.js';
+/**
+ * Resolve the framework-specific render symbol for a Synergy component name.
+ */
+export declare const resolveFrameworkComponentName: (componentName: string, framework: FrameworkProfile) => string;

package/dist/intentPolicy/mappings/framework-targets.js

@@ -0,0 +1,21 @@
+const toPascalCase = (value) => value
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join('');
+/**
+ * Resolve the framework-specific render symbol for a Synergy component name.
+ */
+export const resolveFrameworkComponentName = (componentName, framework) => {
+    if (!componentName.startsWith('syn-')) {
+        return componentName;
+    }
+    const normalizedComponent = toPascalCase(componentName.replace(/^syn-/, ''));
+    if (framework === 'react-wrapper') {
+        return `Syn${normalizedComponent}`;
+    }
+    if (framework === 'vue') {
+        return `SynVue${normalizedComponent}`;
+    }
+    return componentName;
+};

package/dist/intentPolicy/patterns.d.ts

@@ -0,0 +1,6 @@
+import type { IntentUsagePattern } from './types.js';
+/**
+ * A comprehensive list of intent usage patterns, categorized by their respective intent categories.
+ * Each pattern provides a specific example of how an intent can be implemented within a user interface, demonstrating best practices and common use cases for that category.
+ */
+export declare const usagePatterns: IntentUsagePattern[];

package/dist/intentPolicy/patterns.js

@@ -0,0 +1,22 @@
+import { actionPatterns } from './domains/action/index.js';
+import { assistancePatterns } from './domains/assistance/index.js';
+import { disclosurePatterns } from './domains/disclosure/index.js';
+import { feedbackPatterns } from './domains/feedback/index.js';
+import { inputPatterns } from './domains/input/index.js';
+import { navigationPatterns } from './domains/navigation/index.js';
+import { statusPatterns } from './domains/status/index.js';
+import { structurePatterns } from './domains/structure/index.js';
+/**
+ * A comprehensive list of intent usage patterns, categorized by their respective intent categories.
+ * Each pattern provides a specific example of how an intent can be implemented within a user interface, demonstrating best practices and common use cases for that category.
+ */
+export const usagePatterns = [
+    ...actionPatterns,
+    ...feedbackPatterns,
+    ...inputPatterns,
+    ...navigationPatterns,
+    ...disclosurePatterns,
+    ...statusPatterns,
+    ...assistancePatterns,
+    ...structurePatterns,
+];

package/dist/intentPolicy/registry.d.ts

@@ -0,0 +1,4 @@
+export { intentCategories } from './categories.js';
+export { targetCapabilities } from './capabilities.js';
+export { intents } from './intents.js';
+export { usagePatterns } from './patterns.js';

package/dist/intentPolicy/registry.js

@@ -0,0 +1,4 @@
+export { intentCategories } from './categories.js';
+export { targetCapabilities } from './capabilities.js';
+export { intents } from './intents.js';
+export { usagePatterns } from './patterns.js';

package/dist/intentPolicy/renderers/index.d.ts

@@ -0,0 +1,6 @@
+import type { IntentUsagePattern } from '../types.js';
+import type { FrameworkProfile } from '../intermediate-representation/types.js';
+/**
+ * Render one usage pattern into framework-specific component markup.
+ */
+export declare const renderIntentUsagePattern: (pattern: IntentUsagePattern, framework: FrameworkProfile, content: string) => string;

package/dist/intentPolicy/renderers/index.js

@@ -0,0 +1,95 @@
+import { resolveFrameworkComponentName } from '../mappings/framework-targets.js';
+const escapeAttribute = (value) => value.replace(/"/g, '"');
+const renderPropValue = (key, value, framework) => {
+    if (typeof value === 'boolean') {
+        if (!value) {
+            return '';
+        }
+        if (framework === 'react-wrapper') {
+            return ` ${key}={true}`;
+        }
+        return ` ${key}`;
+    }
+    if (value === null) {
+        return '';
+    }
+    return ` ${key}="${escapeAttribute(String(value))}"`;
+};
+const renderProps = (props, framework) => {
+    if (!props) {
+        return '';
+    }
+    return Object.entries(props)
+        .map(([key, value]) => renderPropValue(key, value, framework))
+        .join('');
+};
+const extractRenderableNodeProps = (node) => {
+    const requiredRuleProps = (node.config?.propRules ?? [])
+        .filter((rule) => rule.kind === 'requiredEquals')
+        .reduce((acc, rule) => {
+        acc[rule.prop] = rule.value;
+        return acc;
+    }, {});
+    const mergedProps = {
+        ...requiredRuleProps,
+        ...(node.props ?? {}),
+    };
+    return Object.keys(mergedProps).length > 0 ? mergedProps : undefined;
+};
+const renderStructureNode = (node, framework, fallbackContent = '') => {
+    if (node.component === 'text') {
+        return node.text ?? '';
+    }
+    const component = resolveFrameworkComponentName(node.component, framework);
+    const slotAttribute = node.slot ? ` slot="${escapeAttribute(node.slot)}"` : '';
+    const hasStructuredChildren = !!node.children && node.children.length > 0;
+    const childrenParts = [];
+    if (node.text) {
+        childrenParts.push(node.text);
+    }
+    else if (!hasStructuredChildren) {
+        childrenParts.push(fallbackContent);
+    }
+    if (hasStructuredChildren) {
+        childrenParts.push(...node.children.map((child) => renderStructureNode(child, framework)));
+    }
+    const children = childrenParts.join('');
+    return `<${component}${slotAttribute}${renderProps(extractRenderableNodeProps(node), framework)}>${children}</${component}>`;
+};
+const inferPatternComponent = (pattern) => {
+    if (pattern.target.name) {
+        return pattern.target.name;
+    }
+    if (pattern.target.id?.includes(':')) {
+        return pattern.target.id.split(':')[1] ?? pattern.target.id;
+    }
+    return 'div';
+};
+/**
+ * Extract renderable props from a pattern structure root config.propRules (requiredEquals rules)
+ * or fall back to the legacy preset.props field.
+ */
+const extractRenderableProps = (pattern) => {
+    const propRules = pattern.structure?.config?.propRules;
+    if (propRules && propRules.length > 0) {
+        const props = {};
+        for (const rule of propRules) {
+            if (rule.kind === 'requiredEquals') {
+                props[rule.prop] = rule.value;
+            }
+        }
+        return Object.keys(props).length > 0 ? props : undefined;
+    }
+    return pattern.preset?.props;
+};
+/**
+ * Render one usage pattern into framework-specific component markup.
+ */
+export const renderIntentUsagePattern = (pattern, framework, content) => {
+    if (pattern.structure) {
+        return renderStructureNode(pattern.structure, framework, content);
+    }
+    const component = resolveFrameworkComponentName(inferPatternComponent(pattern), framework);
+    const props = renderProps(extractRenderableProps(pattern), framework);
+    return `<${component}${props}>${content}</${component}>`;
+};

package/dist/intentPolicy/resolution.d.ts

@@ -0,0 +1,41 @@
+import { type IntentCapability, type IntentCategory, type IntentDefinition, type IntentPhase, type IntentResolutionResult, type IntentTargetRef, type IntentUsagePattern } from './types.js';
+/**
+ * Normalize an intent ID for deterministic registry lookup.
+ */
+export declare const normalizeIntentId: (intentId: string) => string;
+/**
+ * Normalize a target reference so matching stays deterministic across registry lookups.
+ */
+export declare const normalizeTargetRef: (target: IntentTargetRef) => IntentTargetRef;
+/**
+ * List intent categories from the in-memory registry.
+ */
+export declare const listIntentCategoriesFromRegistry: (phases?: IntentPhase[]) => IntentCategory[];
+/**
+ * List intent definitions from the in-memory registry.
+ */
+export declare const listIntentsFromRegistry: (category?: string, phases?: IntentPhase[]) => IntentDefinition[];
+/**
+ * Return a single intent definition by ID if present and phase-compatible.
+ */
+export declare const getIntentFromRegistry: (intentId: string, phases?: IntentPhase[]) => IntentDefinition | null;
+/**
+ * Return the capability declaration for a normalized target reference.
+ */
+export declare const getTargetCapabilityFromRegistry: (target: IntentTargetRef, phases?: IntentPhase[]) => IntentCapability | null;
+/**
+ * Resolve one target + intent pair to the matching usage pattern.
+ */
+export declare const resolveUsagePatternFromRegistry: (target: IntentTargetRef, intentId: string, phases?: IntentPhase[]) => IntentUsagePattern | null;
+/**
+ * Check whether a target is eligible to resolve a given intent.
+ */
+export declare const canTargetResolveIntent: (target: IntentTargetRef, intentId: string, phases?: IntentPhase[]) => boolean;
+/**
+ * List all capabilities that support the category of a given intent.
+ */
+export declare const listCapabilitiesForIntentFromRegistry: (intentId: string, phases?: IntentPhase[]) => IntentCapability[];
+/**
+ * Resolve a target + intent pair to a full intent-resolution payload.
+ */
+export declare const resolveIntentFromRegistry: (target: IntentTargetRef, intentId: string, phases?: IntentPhase[]) => IntentResolutionResult | null;

package/dist/intentPolicy/resolution.js

@@ -0,0 +1,226 @@
+import { intentCategories, intents, targetCapabilities, usagePatterns, } from './registry.js';
+import { INTENT_OUTPUT_NAME, INTENT_POLICY_LAYER_NAME, INTENT_RESOLUTION_PROCESS_NAME, } from './types.js';
+const normalize = (value) => value.trim().toLowerCase();
+const DEFAULT_PHASE = 'experimental';
+const ALL_PHASES = ['experimental', 'preview', 'stable', 'deprecated'];
+const TARGET_KINDS = [
+    'asset',
+    'component',
+    'style',
+];
+const isTargetKind = (value) => TARGET_KINDS.includes(value);
+const isIntentPhase = (value) => ALL_PHASES.includes(value);
+const normalizePhase = (phase) => {
+    if (!phase) {
+        return DEFAULT_PHASE;
+    }
+    const normalized = normalize(phase);
+    return isIntentPhase(normalized) ? normalized : DEFAULT_PHASE;
+};
+const normalizePhaseFilter = (phases) => {
+    if (!phases || phases.length === 0) {
+        return new Set([DEFAULT_PHASE]);
+    }
+    const normalized = phases
+        .map((phase) => normalizePhase(phase))
+        .filter((phase, index, list) => list.indexOf(phase) === index);
+    return new Set(normalized.length > 0 ? normalized : [DEFAULT_PHASE]);
+};
+const isAllowedPhase = (phase, allowedPhases) => allowedPhases.has(phase);
+const withCategoryPhase = (category) => ({
+    ...category,
+    phase: normalizePhase(category.phase),
+});
+const withIntentPhase = (intent) => ({
+    ...intent,
+    phase: normalizePhase(intent.phase),
+});
+const withCapabilityPhase = (capability) => ({
+    ...capability,
+    phase: normalizePhase(capability.phase),
+});
+const withPatternPhase = (pattern) => ({
+    ...pattern,
+    phase: normalizePhase(pattern.phase),
+});
+/**
+ * Normalize an intent ID for deterministic registry lookup.
+ */
+export const normalizeIntentId = (intentId) => normalize(intentId);
+/**
+ * Normalize a target reference so matching stays deterministic across registry lookups.
+ */
+export const normalizeTargetRef = (target) => {
+    const normalizedKind = normalize(target.kind);
+    const kind = isTargetKind(normalizedKind) ? normalizedKind : 'component';
+    const classes = target.classes
+        ?.map((entry) => normalize(entry).replace(/^\./, ''))
+        .filter(Boolean);
+    const normalized = {
+        kind,
+    };
+    if (target.id) {
+        normalized.id = normalize(target.id);
+    }
+    if (target.name) {
+        normalized.name = normalize(target.name);
+    }
+    if (target.selector) {
+        normalized.selector = normalize(target.selector);
+    }
+    if (target.layer) {
+        normalized.layer = normalize(target.layer);
+    }
+    if (classes && classes.length > 0) {
+        normalized.classes = Array.from(new Set(classes)).sort();
+    }
+    return normalized;
+};
+const targetKey = (target) => {
+    const normalized = normalizeTargetRef(target);
+    if (normalized.id) {
+        return `${normalized.kind}|id:${normalized.id}`;
+    }
+    if (normalized.selector) {
+        return `${normalized.kind}|selector:${normalized.selector}`;
+    }
+    if (normalized.classes && normalized.classes.length > 0) {
+        return `${normalized.kind}|classes:${normalized.classes.join('.')}`;
+    }
+    if (normalized.name) {
+        return `${normalized.kind}|name:${normalized.name}`;
+    }
+    return `${normalized.kind}|unknown`;
+};
+const getCapabilityTarget = (capability) => normalizeTargetRef(capability.target);
+const getPatternTarget = (pattern) => normalizeTargetRef(pattern.target);
+/**
+ * List intent categories from the in-memory registry.
+ */
+export const listIntentCategoriesFromRegistry = (phases) => {
+    const allowedPhases = normalizePhaseFilter(phases);
+    return structuredClone(intentCategories)
+        .map(withCategoryPhase)
+        .filter((category) => isAllowedPhase(category.phase ?? DEFAULT_PHASE, allowedPhases));
+};
+/**
+ * List intent definitions from the in-memory registry.
+ */
+export const listIntentsFromRegistry = (category, phases) => {
+    const allowedPhases = normalizePhaseFilter(phases);
+    const categoriesById = new Map(structuredClone(intentCategories)
+        .map(withCategoryPhase)
+        .map((entry) => [normalize(entry.id), entry]));
+    const filteredIntents = structuredClone(intents)
+        .map(withIntentPhase)
+        .filter((intent) => {
+        const intentPhase = intent.phase ?? DEFAULT_PHASE;
+        if (!isAllowedPhase(intentPhase, allowedPhases)) {
+            return false;
+        }
+        const categoryEntry = categoriesById.get(normalize(intent.category));
+        const categoryPhase = categoryEntry?.phase ?? DEFAULT_PHASE;
+        return isAllowedPhase(categoryPhase, allowedPhases);
+    });
+    if (!category) {
+        return filteredIntents;
+    }
+    const normalizedCategory = normalize(category);
+    return filteredIntents.filter((intent) => normalize(intent.category) === normalizedCategory);
+};
+/**
+ * Return a single intent definition by ID if present and phase-compatible.
+ */
+export const getIntentFromRegistry = (intentId, phases) => {
+    const allowedPhases = normalizePhaseFilter(phases);
+    const categoriesById = new Map(structuredClone(intentCategories)
+        .map(withCategoryPhase)
+        .map((entry) => [normalize(entry.id), entry]));
+    const normalizedIntent = normalizeIntentId(intentId);
+    const intent = structuredClone(intents)
+        .map(withIntentPhase)
+        .find((candidate) => normalize(candidate.id) === normalizedIntent);
+    if (!intent) {
+        return null;
+    }
+    const intentPhase = intent.phase ?? DEFAULT_PHASE;
+    if (!isAllowedPhase(intentPhase, allowedPhases)) {
+        return null;
+    }
+    const categoryEntry = categoriesById.get(normalize(intent.category));
+    const categoryPhase = categoryEntry?.phase ?? DEFAULT_PHASE;
+    if (!isAllowedPhase(categoryPhase, allowedPhases)) {
+        return null;
+    }
+    return intent;
+};
+/**
+ * Return the capability declaration for a normalized target reference.
+ */
+export const getTargetCapabilityFromRegistry = (target, phases) => {
+    const allowedPhases = normalizePhaseFilter(phases);
+    const normalizedTargetKey = targetKey(target);
+    const capability = structuredClone(targetCapabilities)
+        .map(withCapabilityPhase)
+        .find((candidate) => (targetKey(getCapabilityTarget(candidate)) === normalizedTargetKey
+        && isAllowedPhase(candidate.phase ?? DEFAULT_PHASE, allowedPhases)));
+    return capability ?? null;
+};
+/**
+ * Resolve one target + intent pair to the matching usage pattern.
+ */
+export const resolveUsagePatternFromRegistry = (target, intentId, phases) => {
+    const allowedPhases = normalizePhaseFilter(phases);
+    const normalizedTargetKey = targetKey(target);
+    const normalizedIntent = normalizeIntentId(intentId);
+    const pattern = structuredClone(usagePatterns)
+        .map(withPatternPhase)
+        .find((candidate) => (targetKey(getPatternTarget(candidate)) === normalizedTargetKey
+        && normalize(candidate.intent) === normalizedIntent
+        && isAllowedPhase(candidate.phase ?? DEFAULT_PHASE, allowedPhases)));
+    return pattern ?? null;
+};
+/**
+ * Check whether a target is eligible to resolve a given intent.
+ */
+export const canTargetResolveIntent = (target, intentId, phases) => {
+    const capability = getTargetCapabilityFromRegistry(target, phases);
+    const intent = getIntentFromRegistry(intentId, phases);
+    if (!capability || !intent) {
+        return false;
+    }
+    return capability.categories.map(normalize).includes(normalize(intent.category));
+};
+/**
+ * List all capabilities that support the category of a given intent.
+ */
+export const listCapabilitiesForIntentFromRegistry = (intentId, phases) => {
+    const intent = getIntentFromRegistry(intentId, phases);
+    if (!intent) {
+        return [];
+    }
+    const allowedPhases = normalizePhaseFilter(phases);
+    const normalizedCategory = normalize(intent.category);
+    return structuredClone(targetCapabilities)
+        .map(withCapabilityPhase)
+        .filter((capability) => isAllowedPhase(capability.phase ?? DEFAULT_PHASE, allowedPhases)
+        && capability.categories.map(normalize).includes(normalizedCategory));
+};
+/**
+ * Resolve a target + intent pair to a full intent-resolution payload.
+ */
+export const resolveIntentFromRegistry = (target, intentId, phases) => {
+    if (!canTargetResolveIntent(target, intentId, phases)) {
+        return null;
+    }
+    const pattern = resolveUsagePatternFromRegistry(target, intentId, phases);
+    if (!pattern) {
+        return null;
+    }
+    return {
+        architecture: INTENT_POLICY_LAYER_NAME,
+        output: INTENT_OUTPUT_NAME,
+        pattern,
+        process: INTENT_RESOLUTION_PROCESS_NAME,
+    };
+};

package/dist/intentPolicy/services/render.d.ts

@@ -0,0 +1,16 @@
+import type { IntentPhase, IntentTargetRef } from '../types.js';
+import type { FrameworkProfile } from '../intermediate-representation/types.js';
+/**
+ * Query payload for rendering a target + intent pair to framework output.
+ */
+export type RenderIntentQuery = {
+    content?: string;
+    framework: FrameworkProfile;
+    includePhases?: IntentPhase[];
+    intent: string;
+    target?: IntentTargetRef;
+};
+/**
+ * Resolve and render a registered intent pattern into framework-specific markup.
+ */
+export declare const renderIntentFromRegistry: (query: RenderIntentQuery) => string | null;

package/dist/intentPolicy/services/render.js

@@ -0,0 +1,29 @@
+import { listCapabilitiesForIntentFromRegistry, normalizeTargetRef, resolveUsagePatternFromRegistry, } from '../resolution.js';
+import { renderIntentUsagePattern } from '../renderers/index.js';
+/**
+ * Resolve and render a registered intent pattern into framework-specific markup.
+ */
+export const renderIntentFromRegistry = (query) => {
+    if (!query.intent) {
+        return null;
+    }
+    let pattern = null;
+    const explicitTarget = query.target && query.target.kind ? query.target : null;
+    if (explicitTarget) {
+        pattern = resolveUsagePatternFromRegistry(normalizeTargetRef(explicitTarget), query.intent, query.includePhases);
+    }
+    if (!pattern && !explicitTarget) {
+        const candidateCapabilities = listCapabilitiesForIntentFromRegistry(query.intent, query.includePhases);
+        for (const capability of candidateCapabilities) {
+            const candidatePattern = resolveUsagePatternFromRegistry(normalizeTargetRef(capability.target), query.intent, query.includePhases);
+            if (candidatePattern) {
+                pattern = candidatePattern;
+                break;
+            }
+        }
+    }
+    if (!pattern) {
+        return null;
+    }
+    return renderIntentUsagePattern(pattern, query.framework, query.content ?? 'CONTENT');
+};