@synergy-design-system/metadata 3.7.0 → 3.8.0

package/dist/intentPolicy/intents.js

@@ -0,0 +1,23 @@
+import { actionIntents } from './domains/action/index.js';
+import { assistanceIntents } from './domains/assistance/index.js';
+import { disclosureIntents } from './domains/disclosure/index.js';
+import { feedbackIntents } from './domains/feedback/index.js';
+import { inputIntents } from './domains/input/index.js';
+import { navigationIntents } from './domains/navigation/index.js';
+import { statusIntents } from './domains/status/index.js';
+import { structureIntents } from './domains/structure/index.js';
+/**
+ * A comprehensive list of intent definitions, categorized by their respective intent categories.
+ * Each intent definition includes detailed information about the intent's purpose, usage guidelines, and examples to illustrate how it can be effectively implemented within a user interface.
+ * This collection serves as a valuable resource for designers and developers seeking to create intuitive and user-friendly interfaces that align with established best practices for intent usage.
+ */
+export const intents = [
+    ...actionIntents,
+    ...feedbackIntents,
+    ...inputIntents,
+    ...navigationIntents,
+    ...disclosureIntents,
+    ...statusIntents,
+    ...assistanceIntents,
+    ...structureIntents,
+];

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/action.d.ts

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

package/dist/intentPolicy/patterns/action.js

@@ -0,0 +1,195 @@
+export const actionPatterns = [
+    {
+        description: 'Primary action button styling for default primary interaction.',
+        intent: 'action.primary',
+        structure: {
+            component: 'syn-button',
+            config: {
+                contentRules: [
+                    {
+                        code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                        kind: 'requiredContent',
+                        message: 'syn-button must contain visible content (text and/or child nodes).',
+                        rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                        suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                    },
+                ],
+                propRules: [
+                    {
+                        code: 'REQUIRED_PROP_BUTTON_TYPE',
+                        kind: 'requiredEquals',
+                        message: 'type property must be set to "button" for primary action intent.',
+                        prop: 'type',
+                        rationale: 'The semantic button type ensures proper HTML behavior and accessibility.',
+                        suggestedFix: 'Set type property to "button".',
+                        value: 'button',
+                    },
+                    {
+                        code: 'REQUIRED_PROP_FILLED_VARIANT',
+                        kind: 'requiredEquals',
+                        message: 'variant property should be set to "filled" for primary action emphasis.',
+                        prop: 'variant',
+                        rationale: 'Filled variant provides clear visual priority for primary actions.',
+                        suggestedFix: 'Set variant property to "filled".',
+                        value: 'filled',
+                    },
+                ],
+            },
+        },
+        target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+    },
+    {
+        description: 'Submit action with semantic submit type and filled emphasis.',
+        intent: 'action.submit',
+        notes: ['Do not combine submit intent with href-based navigation behavior.'],
+        structure: {
+            component: 'syn-button',
+            config: {
+                contentRules: [
+                    {
+                        code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                        kind: 'requiredContent',
+                        message: 'syn-button must contain visible content (text and/or child nodes).',
+                        rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                        suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                    },
+                ],
+                propRules: [
+                    {
+                        code: 'REQUIRED_PROP_SUBMIT_TYPE',
+                        kind: 'requiredEquals',
+                        message: 'type property must be set to "submit" for submit action intent.',
+                        prop: 'type',
+                        rationale: 'The semantic submit type ensures proper form submission behavior.',
+                        suggestedFix: 'Set type property to "submit".',
+                        value: 'submit',
+                    },
+                    {
+                        code: 'REQUIRED_PROP_FILLED_VARIANT',
+                        kind: 'requiredEquals',
+                        message: 'variant property should be set to "filled" for action emphasis.',
+                        prop: 'variant',
+                        rationale: 'Filled variant provides clear visual priority for actions.',
+                        suggestedFix: 'Set variant property to "filled".',
+                        value: 'filled',
+                    },
+                    {
+                        code: 'FORBIDDEN_PROP_HREF',
+                        kind: 'forbidden',
+                        message: 'href property is not compatible with submit action intent.',
+                        prop: 'href',
+                        rationale: 'Submit intent uses form submission semantics, not navigation. Use action.navigation for link-based navigation.',
+                        suggestedFix: 'Remove href property and use a form or event handler for submission.',
+                    },
+                    {
+                        code: 'INTENT_TEMPORARILY_BLOCKED',
+                        kind: 'warnWhenEquals',
+                        message: 'Submit intent is currently blocked because the control is disabled.',
+                        prop: 'disabled',
+                        rationale: 'This can be intentional in gated flows where the control is enabled after form input becomes valid.',
+                        severity: 'warning',
+                        suggestedFix: 'Enable the control once the form becomes valid so users can complete submission.',
+                        value: true,
+                    },
+                ],
+            },
+        },
+        target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+    },
+    {
+        description: 'Reset action styling for secondary importance.',
+        intent: 'action.reset',
+        structure: {
+            component: 'syn-button',
+            config: {
+                contentRules: [
+                    {
+                        code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                        kind: 'requiredContent',
+                        message: 'syn-button must contain visible content (text and/or child nodes).',
+                        rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                        suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                    },
+                ],
+                propRules: [
+                    {
+                        code: 'REQUIRED_PROP_RESET_TYPE',
+                        kind: 'requiredEquals',
+                        message: 'type property must be set to "reset" for reset action intent.',
+                        prop: 'type',
+                        rationale: 'The semantic reset type ensures proper form reset behavior.',
+                        suggestedFix: 'Set type property to "reset".',
+                        value: 'reset',
+                    },
+                    {
+                        code: 'REQUIRED_PROP_TEXT_VARIANT',
+                        kind: 'requiredEquals',
+                        message: 'variant property should be set to "text" for secondary action styling.',
+                        prop: 'variant',
+                        rationale: 'Text variant provides lower visual priority appropriate for reset actions.',
+                        suggestedFix: 'Set variant property to "text".',
+                        value: 'text',
+                    },
+                ],
+            },
+        },
+        target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+    },
+    {
+        description: 'Navigation action uses href and text variant.',
+        intent: 'action.navigation',
+        structure: {
+            component: 'syn-button',
+            config: {
+                contentRules: [
+                    {
+                        code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                        kind: 'requiredContent',
+                        message: 'syn-button must contain visible content (text and/or child nodes).',
+                        rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                        suggestedFix: 'Add a label, text, or ch------ild element such as syn-icon inside the button.',
+                    },
+                ],
+                propRules: [
+                    {
+                        code: 'REQUIRED_PROP_HREF',
+                        kind: 'requiredEquals',
+                        message: 'href property must be set for navigation action intent.',
+                        prop: 'href',
+                        rationale: 'The href property provides the navigation target for semantic link behavior.',
+                        suggestedFix: 'Set href property to the target URL or route.',
+                        value: '#',
+                    },
+                    {
+                        code: 'REQUIRED_PROP_TEXT_VARIANT',
+                        kind: 'requiredEquals',
+                        message: 'variant property should be set to "text" for navigation action styling.',
+                        prop: 'variant',
+                        rationale: 'Text variant provides unstyled appearance appropriate for link-like navigation.',
+                        suggestedFix: 'Set variant property to "text".',
+                        value: 'text',
+                    },
+                ],
+            },
+        },
+        target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+    },
+    {
+        description: 'Compact icon-only action button with accessible label requirements.',
+        intent: 'action.button.icon',
+        notes: ['Provide an accessible label (for example aria-label) because no visible text is shown.'],
+        structure: {
+            component: 'syn-icon-button',
+        },
+        target: { id: 'component:syn-icon-button', kind: 'component', name: 'syn-icon-button' },
+    },
+    {
+        description: 'Group related actions into one aligned unit for consistent interaction.',
+        intent: 'action.grouped',
+        notes: ['Prefer grouping actions with related intent and similar importance.'],
+        structure: {
+            component: 'syn-button-group',
+        },
+        target: { id: 'component:syn-button-group', kind: 'component', name: 'syn-button-group' },
+    },
+];

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

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

package/dist/intentPolicy/patterns/assistance.js

@@ -0,0 +1,13 @@
+export const assistancePatterns = [
+    {
+        description: 'Short non-critical contextual help tied to a nearby trigger.',
+        intent: 'assistance.tooltip.contextual',
+        target: { id: 'component:syn-tooltip', kind: 'component', name: 'syn-tooltip' },
+    },
+    {
+        description: 'Contextual icon used as a compact visual hint near related content.',
+        intent: 'assistance.icon.contextual',
+        notes: ['Use alongside text or tooltips when meaning is not universally obvious.'],
+        target: { id: 'component:syn-icon', kind: 'component', name: 'syn-icon' },
+    },
+];

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

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

package/dist/intentPolicy/patterns/disclosure.js

@@ -0,0 +1,23 @@
+export const disclosurePatterns = [
+    {
+        description: 'On-demand disclosure for one optional information block.',
+        intent: 'disclosure.details.on-demand',
+        target: { id: 'component:syn-details', kind: 'component', name: 'syn-details' },
+    },
+    {
+        description: 'Grouped progressive disclosure for multiple related sections.',
+        intent: 'disclosure.accordion.grouped',
+        preset: {
+            props: {
+                'close-others': true,
+            },
+        },
+        target: { id: 'component:syn-accordion', kind: 'component', name: 'syn-accordion' },
+    },
+    {
+        description: 'On-demand popup disclosure anchored to a trigger element.',
+        intent: 'disclosure.popup.on-demand',
+        notes: ['Keep popup content concise and directly related to the trigger context.'],
+        target: { id: 'component:syn-popup', kind: 'component', name: 'syn-popup' },
+    },
+];

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

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

package/dist/intentPolicy/patterns/feedback.js

@@ -0,0 +1,44 @@
+export const feedbackPatterns = [
+    {
+        description: 'Inline alert for contextual feedback near related content.',
+        intent: 'feedback.inline',
+        preset: {
+            props: {
+                duration: 0,
+                variant: 'warning',
+            },
+        },
+        target: { id: 'component:syn-alert', kind: 'component', name: 'syn-alert' },
+    },
+    {
+        description: 'Toast alert for brief, non-blocking status acknowledgement.',
+        intent: 'feedback.toast',
+        preset: {
+            props: {
+                duration: 4000,
+                variant: 'success',
+            },
+        },
+        target: { id: 'component:syn-alert', kind: 'component', name: 'syn-alert' },
+    },
+    {
+        description: 'Compact status or count feedback using badge visuals.',
+        intent: 'feedback.badge.status',
+        target: { id: 'component:syn-badge', kind: 'component', name: 'syn-badge' },
+    },
+    {
+        description: 'Compact categorical or state labeling using tags.',
+        intent: 'feedback.tag.label',
+        target: { id: 'component:syn-tag', kind: 'component', name: 'syn-tag' },
+    },
+    {
+        description: 'Grouped tags for concise display of multiple labels or states.',
+        intent: 'feedback.tag.label',
+        target: { id: 'component:syn-tag-group', kind: 'component', name: 'syn-tag-group' },
+    },
+    {
+        description: 'Generic validation feedback for incorrect or missing user input.',
+        intent: 'feedback.validation.generic',
+        target: { id: 'component:syn-validate', kind: 'component', name: 'syn-validate' },
+    },
+];

package/dist/intentPolicy/patterns/index.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/index.js

@@ -0,0 +1,22 @@
+import { actionPatterns } from './action.js';
+import { assistancePatterns } from './assistance.js';
+import { disclosurePatterns } from './disclosure.js';
+import { feedbackPatterns } from './feedback.js';
+import { inputPatterns } from './input.js';
+import { navigationPatterns } from './navigation.js';
+import { statusPatterns } from './status.js';
+import { structurePatterns } from './structure.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/patterns/input.d.ts

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

package/dist/intentPolicy/patterns/input.js

@@ -0,0 +1,99 @@
+export const inputPatterns = [
+    {
+        description: 'Single-line input for compact text or numeric values.',
+        intent: 'input.text.short',
+        preset: {
+            props: {
+                type: 'text',
+            },
+        },
+        target: { id: 'component:syn-input', kind: 'component', name: 'syn-input' },
+    },
+    {
+        description: 'Multiline text entry for detailed user-provided information.',
+        intent: 'input.text.long',
+        preset: {
+            props: {
+                resize: 'vertical',
+            },
+        },
+        target: { id: 'component:syn-textarea', kind: 'component', name: 'syn-textarea' },
+    },
+    {
+        description: 'Single selection from a predefined options list.',
+        intent: 'input.selection.single',
+        preset: {
+            props: {
+                multiple: false,
+            },
+        },
+        target: { id: 'component:syn-select', kind: 'component', name: 'syn-select' },
+    },
+    {
+        description: 'Multiple selection from a predefined options list.',
+        intent: 'input.selection.multiple',
+        preset: {
+            props: {
+                multiple: true,
+            },
+        },
+        target: { id: 'component:syn-select', kind: 'component', name: 'syn-select' },
+    },
+    {
+        description: 'Searchable selection with real-time filtering for larger option sets.',
+        intent: 'input.selection.searchable',
+        preset: {
+            props: {
+                autocomplete: 'list',
+            },
+        },
+        target: { id: 'component:syn-combobox', kind: 'component', name: 'syn-combobox' },
+    },
+    {
+        description: 'Binary toggle that applies changes immediately.',
+        intent: 'input.binary.immediate',
+        preset: {
+            props: {
+                checked: false,
+            },
+        },
+        target: { id: 'component:syn-switch', kind: 'component', name: 'syn-switch' },
+    },
+    {
+        description: 'Binary selection captured as part of a later form submit.',
+        intent: 'input.binary.deferred',
+        preset: {
+            props: {
+                checked: false,
+            },
+        },
+        target: { id: 'component:syn-checkbox', kind: 'component', name: 'syn-checkbox' },
+    },
+    {
+        description: 'Single required choice among related options.',
+        intent: 'input.selection.single',
+        notes: ['Provide one default selected option as recommended in component usage rules.'],
+        target: { id: 'component:syn-radio-group', kind: 'component', name: 'syn-radio-group' },
+    },
+    {
+        description: 'File attachment or upload control with optional multi-file mode.',
+        intent: 'input.file.upload',
+        preset: {
+            props: {
+                multiple: false,
+            },
+        },
+        target: { id: 'component:syn-file', kind: 'component', name: 'syn-file' },
+    },
+    {
+        description: 'Bounded numeric selection through a slider control.',
+        intent: 'input.range.slider',
+        target: { id: 'component:syn-range', kind: 'component', name: 'syn-range' },
+    },
+    {
+        description: 'Grouped select options organized through optgroup labels.',
+        intent: 'input.selection.grouped-options',
+        notes: ['Use syn-optgroup to cluster related syn-option entries under clear labels.'],
+        target: { id: 'component:syn-select', kind: 'component', name: 'syn-select' },
+    },
+];

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

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