@synergy-design-system/metadata 3.7.0 → 3.8.0

package/dist/intentPolicy/patterns/navigation.js

@@ -0,0 +1,192 @@
+export const navigationPatterns = [
+    {
+        description: 'Class-based link navigation pattern for inline or standalone links.',
+        intent: 'action.navigation',
+        notes: [
+            'Use syn-link--quiet when the link should have lower visual emphasis.',
+            'Use size variants like syn-link--small, syn-link--medium, or syn-link--large as needed.',
+        ],
+        preset: {
+            requiredClasses: ['syn-link'],
+        },
+        structure: {
+            children: [
+                {
+                    component: 'text',
+                    text: 'Link',
+                },
+            ],
+            component: 'a',
+            props: {
+                class: 'syn-link',
+                href: '#',
+            },
+        },
+        target: {
+            classes: ['syn-link'],
+            id: 'style:syn-link',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link',
+        },
+    },
+    {
+        description: 'Grouped navigation links using the link-list utility class.',
+        intent: 'navigation.link-list.grouped',
+        preset: {
+            requiredClasses: ['syn-link-list'],
+        },
+        structure: {
+            children: [
+                {
+                    children: [
+                        {
+                            children: [
+                                {
+                                    component: 'syn-icon',
+                                    props: {
+                                        name: 'keyboard_arrow_right',
+                                    },
+                                },
+                                {
+                                    component: 'text',
+                                    text: 'Link',
+                                },
+                            ],
+                            component: 'a',
+                            props: {
+                                class: 'syn-link',
+                                href: '#',
+                            },
+                        },
+                    ],
+                    component: 'li',
+                },
+                {
+                    children: [
+                        {
+                            children: [
+                                {
+                                    component: 'syn-icon',
+                                    props: {
+                                        name: 'keyboard_arrow_right',
+                                    },
+                                },
+                                {
+                                    component: 'text',
+                                    text: 'Link',
+                                },
+                            ],
+                            component: 'a',
+                            props: {
+                                class: 'syn-link',
+                                href: '#',
+                            },
+                        },
+                    ],
+                    component: 'li',
+                },
+                {
+                    children: [
+                        {
+                            children: [
+                                {
+                                    component: 'syn-icon',
+                                    props: {
+                                        name: 'keyboard_arrow_right',
+                                    },
+                                },
+                                {
+                                    component: 'text',
+                                    text: 'Link',
+                                },
+                            ],
+                            component: 'a',
+                            props: {
+                                class: 'syn-link',
+                                href: '#',
+                            },
+                        },
+                    ],
+                    component: 'li',
+                },
+                {
+                    children: [
+                        {
+                            children: [
+                                {
+                                    component: 'syn-icon',
+                                    props: {
+                                        name: 'keyboard_arrow_right',
+                                    },
+                                },
+                                {
+                                    component: 'text',
+                                    text: 'Link',
+                                },
+                            ],
+                            component: 'a',
+                            props: {
+                                class: 'syn-link',
+                                href: '#',
+                            },
+                        },
+                    ],
+                    component: 'li',
+                },
+            ],
+            component: 'ul',
+            props: {
+                class: 'syn-link-list',
+            },
+        },
+        target: {
+            classes: ['syn-link-list'],
+            id: 'style:syn-link-list',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link-list',
+        },
+    },
+    {
+        description: 'In-page section navigation through related tabs.',
+        intent: 'navigation.tabs.section',
+        notes: ['Prefer concise tab labels and keep tab count manageable (typically up to six).'],
+        target: { id: 'component:syn-tab-group', kind: 'component', name: 'syn-tab-group' },
+    },
+    {
+        description: 'Action-oriented menu with logical grouping and keyboard access.',
+        intent: 'navigation.menu.actions',
+        target: { id: 'component:syn-menu', kind: 'component', name: 'syn-menu' },
+    },
+    {
+        description: 'Compact trigger-based reveal of related options or destinations.',
+        intent: 'navigation.dropdown.compact-options',
+        target: { id: 'component:syn-dropdown', kind: 'component', name: 'syn-dropdown' },
+    },
+    {
+        description: 'Dataset paging controls for large result sets.',
+        intent: 'navigation.pagination.dataset',
+        target: { id: 'component:syn-pagination', kind: 'component', name: 'syn-pagination' },
+    },
+    {
+        description: 'Hierarchy-aware breadcrumb trail for location and backtracking.',
+        intent: 'navigation.breadcrumb.trail',
+        target: { id: 'component:syn-breadcrumb', kind: 'component', name: 'syn-breadcrumb' },
+    },
+    {
+        description: 'Breadcrumb item representing one navigable hierarchy level.',
+        intent: 'navigation.breadcrumb.trail',
+        target: { id: 'component:syn-breadcrumb-item', kind: 'component', name: 'syn-breadcrumb-item' },
+    },
+    {
+        description: 'Primary vertical navigation for app shell section switching.',
+        intent: 'navigation.sidenav.menu',
+        target: { id: 'component:syn-side-nav', kind: 'component', name: 'syn-side-nav' },
+    },
+    {
+        description: 'Single destination entry within side navigation structures.',
+        intent: 'navigation.sidenav.menu',
+        target: { id: 'component:syn-nav-item', kind: 'component', name: 'syn-nav-item' },
+    },
+];

package/dist/intentPolicy/patterns/status.d.ts

@@ -0,0 +1,2 @@
+import type { IntentUsagePattern } from '../types.js';
+export declare const statusPatterns: IntentUsagePattern[];

package/dist/intentPolicy/patterns/status.js

@@ -0,0 +1,32 @@
+export const statusPatterns = [
+    {
+        description: 'Section-local loading indicator while content is fetched.',
+        intent: 'status.loading.section',
+        preset: {
+            props: {
+                size: 'medium',
+            },
+        },
+        target: { id: 'component:syn-spinner', kind: 'component', name: 'syn-spinner' },
+    },
+    {
+        description: 'Inline processing indicator inside an action flow.',
+        intent: 'status.loading.action',
+        preset: {
+            props: {
+                size: 'small',
+            },
+        },
+        target: { id: 'component:syn-spinner', kind: 'component', name: 'syn-spinner' },
+    },
+    {
+        description: 'Determinate linear progress indicator for measurable workflow completion.',
+        intent: 'status.progress.linear',
+        target: { id: 'component:syn-progress-bar', kind: 'component', name: 'syn-progress-bar' },
+    },
+    {
+        description: 'Determinate circular progress indicator for compact progress displays.',
+        intent: 'status.progress.circular',
+        target: { id: 'component:syn-progress-ring', kind: 'component', name: 'syn-progress-ring' },
+    },
+];

package/dist/intentPolicy/patterns/structure.d.ts

@@ -0,0 +1,2 @@
+import type { IntentUsagePattern } from '../types.js';
+export declare const structurePatterns: IntentUsagePattern[];

package/dist/intentPolicy/patterns/structure.js

@@ -0,0 +1,107 @@
+export const structurePatterns = [
+    {
+        description: 'Confirmation dialog with explicit cancel and destructive actions in footer slot.',
+        intent: 'structure.confirmation',
+        notes: [
+            'Renderers should preserve footer action ordering (cancel before destructive confirm).',
+            'Destructive action should be visually distinct from the cancel action.',
+        ],
+        roles: {
+            cancelAction: 'abort',
+            confirmAction: 'confirm-destructive',
+            container: 'dialog',
+            footer: 'group',
+        },
+        structure: {
+            children: [
+                {
+                    component: 'text',
+                    role: 'content',
+                    text: 'Content',
+                },
+                {
+                    children: [
+                        {
+                            component: 'syn-button',
+                            config: {
+                                propRules: [
+                                    {
+                                        code: 'REQUIRED_CANCEL_VARIANT_TEXT',
+                                        kind: 'requiredEquals',
+                                        message: 'Cancel action should use text variant in confirmation dialog footer.',
+                                        prop: 'variant',
+                                        rationale: 'Text variant keeps cancel action visually secondary to destructive confirmation.',
+                                        suggestedFix: 'Set variant property to "text".',
+                                        value: 'text',
+                                    },
+                                ],
+                            },
+                            role: 'cancelAction',
+                            text: 'Abort',
+                        },
+                        {
+                            component: 'syn-button',
+                            config: {
+                                propRules: [
+                                    {
+                                        code: 'REQUIRED_CONFIRM_VARIANT_FILLED',
+                                        kind: 'requiredEquals',
+                                        message: 'Confirm action should use filled variant in confirmation dialog footer.',
+                                        prop: 'variant',
+                                        rationale: 'Filled variant visually signals the destructive nature of the action.',
+                                        suggestedFix: 'Set variant property to "filled".',
+                                        value: 'filled',
+                                    },
+                                    {
+                                        code: 'FORBIDDEN_CONFIRM_HREF',
+                                        kind: 'forbidden',
+                                        message: 'Confirm action in confirmation dialogs must not use href navigation.',
+                                        prop: 'href',
+                                        rationale: 'Destructive confirmation should execute an explicit action, not navigate away.',
+                                        suggestedFix: 'Remove href and handle confirmation through action callbacks.',
+                                    },
+                                ],
+                            },
+                            role: 'confirmAction',
+                            text: 'Delete this!',
+                        },
+                    ],
+                    component: 'nav',
+                    role: 'footer',
+                    slot: 'footer',
+                },
+            ],
+            component: 'syn-dialog',
+            props: {
+                open: true,
+            },
+            role: 'container',
+        },
+        target: { id: 'component:syn-dialog', kind: 'component', name: 'syn-dialog' },
+    },
+    {
+        description: 'Edge-aligned drawer overlay for secondary contextual workflows.',
+        intent: 'structure.drawer.overlay',
+        notes: ['Use drawers for supplementary content that should not replace the current page context.'],
+        target: { id: 'component:syn-drawer', kind: 'component', name: 'syn-drawer' },
+    },
+    {
+        description: 'Top-level header shell structure for branding and navigation regions.',
+        intent: 'structure.header.shell',
+        notes: [
+            'Navigation slot can host primary navigation controls such as syn-prio-nav.',
+            'Meta-navigation slot can host compact utility actions such as syn-icon-button.',
+        ],
+        target: { id: 'component:syn-header', kind: 'component', name: 'syn-header' },
+    },
+    {
+        description: 'Card container grouping related content and supporting actions.',
+        intent: 'structure.content.container',
+        target: { id: 'component:syn-card', kind: 'component', name: 'syn-card' },
+    },
+    {
+        description: 'Visual separator between adjacent blocks of related content.',
+        intent: 'structure.content.separator',
+        target: { id: 'component:syn-divider', kind: 'component', name: 'syn-divider' },
+    },
+];

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;