@synergy-design-system/metadata 3.7.0 → 3.9.0

package/dist/intentPolicy/domains/navigation/capabilities.js

@@ -0,0 +1,54 @@
+export const navigationCapabilities = [
+    {
+        categories: ['navigation', 'action'],
+        target: {
+            classes: ['syn-link'],
+            id: 'style:syn-link',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link',
+        },
+    },
+    {
+        categories: ['navigation'],
+        target: {
+            classes: ['syn-link-list'],
+            id: 'style:syn-link-list',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link-list',
+        },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-tab-group', kind: 'component', name: 'syn-tab-group' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-menu', kind: 'component', name: 'syn-menu' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-dropdown', kind: 'component', name: 'syn-dropdown' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-pagination', kind: 'component', name: 'syn-pagination' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-breadcrumb', kind: 'component', name: 'syn-breadcrumb' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-breadcrumb-item', kind: 'component', name: 'syn-breadcrumb-item' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-side-nav', kind: 'component', name: 'syn-side-nav' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-nav-item', kind: 'component', name: 'syn-nav-item' },
+    },
+];

package/dist/intentPolicy/domains/navigation/category.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../../types.js';
+export declare const navigationCategory: IntentCategory;

package/dist/intentPolicy/domains/navigation/category.js

@@ -0,0 +1,4 @@
+export const navigationCategory = {
+    description: 'Information architecture and movement between sections or datasets.',
+    id: 'navigation',
+};

package/dist/intentPolicy/domains/navigation/index.d.ts

@@ -0,0 +1,4 @@
+export { navigationCapabilities } from './capabilities.js';
+export { navigationCategory } from './category.js';
+export { navigationIntents } from './intents.js';
+export { navigationPatterns } from './patterns.js';

package/dist/intentPolicy/domains/navigation/index.js

@@ -0,0 +1,4 @@
+export { navigationCapabilities } from './capabilities.js';
+export { navigationCategory } from './category.js';
+export { navigationIntents } from './intents.js';
+export { navigationPatterns } from './patterns.js';

package/dist/intentPolicy/domains/navigation/intents.d.ts

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

package/dist/intentPolicy/domains/navigation/intents.js

@@ -0,0 +1,44 @@
+export const navigationIntents = [
+    {
+        category: 'navigation',
+        description: 'Use link-list styles to present grouped navigation links with consistent spacing.',
+        id: 'navigation.link-list.grouped',
+        userGoal: 'Scan and navigate related links quickly in a vertical list.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use tabs to switch between related content sections in-place.',
+        id: 'navigation.tabs.section',
+        userGoal: 'Move between grouped views without leaving the current page.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use menus to provide grouped actions or destinations.',
+        id: 'navigation.menu.actions',
+        userGoal: 'Access frequently used commands through a structured action list.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use pagination controls for large datasets split across pages.',
+        id: 'navigation.pagination.dataset',
+        userGoal: 'Navigate through bounded result sets efficiently.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use dropdowns to reveal compact, related options from a trigger.',
+        id: 'navigation.dropdown.compact-options',
+        userGoal: 'Access secondary options while preserving layout space.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use breadcrumb trails to show hierarchy and support quick backtracking.',
+        id: 'navigation.breadcrumb.trail',
+        userGoal: 'Understand current location and navigate to ancestor levels quickly.',
+    },
+    {
+        category: 'navigation',
+        description: 'Use side navigation to expose primary navigation sections in vertical layouts.',
+        id: 'navigation.sidenav.menu',
+        userGoal: 'Move between major sections in an app shell efficiently.',
+    },
+];

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

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

package/dist/intentPolicy/domains/navigation/patterns.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/domains/status/capabilities.d.ts

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

package/dist/intentPolicy/domains/status/capabilities.js

@@ -0,0 +1,14 @@
+export const statusCapabilities = [
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-spinner', kind: 'component', name: 'syn-spinner' },
+    },
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-progress-bar', kind: 'component', name: 'syn-progress-bar' },
+    },
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-progress-ring', kind: 'component', name: 'syn-progress-ring' },
+    },
+];

package/dist/intentPolicy/domains/status/category.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../../types.js';
+export declare const statusCategory: IntentCategory;

package/dist/intentPolicy/domains/status/category.js

@@ -0,0 +1,4 @@
+export const statusCategory = {
+    description: 'Transient loading and processing indicators.',
+    id: 'status',
+};

package/dist/intentPolicy/domains/status/index.d.ts

@@ -0,0 +1,4 @@
+export { statusCapabilities } from './capabilities.js';
+export { statusCategory } from './category.js';
+export { statusIntents } from './intents.js';
+export { statusPatterns } from './patterns.js';

package/dist/intentPolicy/domains/status/index.js

@@ -0,0 +1,4 @@
+export { statusCapabilities } from './capabilities.js';
+export { statusCategory } from './category.js';
+export { statusIntents } from './intents.js';
+export { statusPatterns } from './patterns.js';

package/dist/intentPolicy/domains/status/intents.d.ts

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

package/dist/intentPolicy/domains/status/intents.js

@@ -0,0 +1,26 @@
+export const statusIntents = [
+    {
+        category: 'status',
+        description: 'Use loading indicators inside a specific region while content is fetched.',
+        id: 'status.loading.section',
+        userGoal: 'Communicate in-progress loading without blocking the full interface.',
+    },
+    {
+        category: 'status',
+        description: 'Use loading indicators inside actions while a command is processing.',
+        id: 'status.loading.action',
+        userGoal: 'Signal ongoing processing for a submitted user action.',
+    },
+    {
+        category: 'status',
+        description: 'Use linear progress bars to communicate determinate progress in workflows.',
+        id: 'status.progress.linear',
+        userGoal: 'Show measurable progress toward completion over time.',
+    },
+    {
+        category: 'status',
+        description: 'Use circular progress rings for compact determinate progress indicators.',
+        id: 'status.progress.circular',
+        userGoal: 'Show measurable progress in compact UI regions.',
+    },
+];

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

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

package/dist/intentPolicy/domains/status/patterns.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/domains/structure/capabilities.d.ts

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

package/dist/intentPolicy/domains/structure/capabilities.js

@@ -0,0 +1,22 @@
+export const structureCapabilities = [
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-dialog', kind: 'component', name: 'syn-dialog' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-drawer', kind: 'component', name: 'syn-drawer' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-header', kind: 'component', name: 'syn-header' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-card', kind: 'component', name: 'syn-card' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-divider', kind: 'component', name: 'syn-divider' },
+    },
+];

package/dist/intentPolicy/domains/structure/category.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../../types.js';
+export declare const structureCategory: IntentCategory;

package/dist/intentPolicy/domains/structure/category.js

@@ -0,0 +1,4 @@
+export const structureCategory = {
+    description: 'Structural interaction intent requiring composition, slots, and semantic roles.',
+    id: 'structure',
+};

package/dist/intentPolicy/domains/structure/index.d.ts

@@ -0,0 +1,4 @@
+export { structureCapabilities } from './capabilities.js';
+export { structureCategory } from './category.js';
+export { structureIntents } from './intents.js';
+export { structurePatterns } from './patterns.js';

package/dist/intentPolicy/domains/structure/index.js

@@ -0,0 +1,4 @@
+export { structureCapabilities } from './capabilities.js';
+export { structureCategory } from './category.js';
+export { structureIntents } from './intents.js';
+export { structurePatterns } from './patterns.js';

package/dist/intentPolicy/domains/structure/intents.d.ts

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

package/dist/intentPolicy/domains/structure/intents.js

@@ -0,0 +1,32 @@
+export const structureIntents = [
+    {
+        category: 'structure',
+        description: 'Use when confirming a risky or destructive operation in a dialog.',
+        id: 'structure.confirmation',
+        userGoal: 'Require clear user confirmation before executing a destructive action.',
+    },
+    {
+        category: 'structure',
+        description: 'Use drawers to reveal supplemental panels from an edge overlay.',
+        id: 'structure.drawer.overlay',
+        userGoal: 'Present secondary workflows without leaving the current context.',
+    },
+    {
+        category: 'structure',
+        description: 'Use headers to establish a consistent top-level page shell structure.',
+        id: 'structure.header.shell',
+        userGoal: 'Provide a consistent frame for branding, navigation, and meta actions.',
+    },
+    {
+        category: 'structure',
+        description: 'Use card containers to group related content into a bounded section.',
+        id: 'structure.content.container',
+        userGoal: 'Improve scannability by grouping related information and actions.',
+    },
+    {
+        category: 'structure',
+        description: 'Use dividers to separate adjacent sections and improve visual hierarchy.',
+        id: 'structure.content.separator',
+        userGoal: 'Clarify boundaries between groups of content.',
+    },
+];

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

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

package/dist/intentPolicy/domains/structure/patterns.js

@@ -0,0 +1,96 @@
+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: [
+                {
+                    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',
+                                    },
+                                ],
+                            },
+                        },
+                        {
+                            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.',
+                                    },
+                                ],
+                            },
+                        },
+                    ],
+                    component: 'nav',
+                    slot: 'footer',
+                },
+            ],
+            component: 'syn-dialog',
+            props: {
+                open: true,
+            },
+        },
+        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/intents.d.ts

@@ -0,0 +1,7 @@
+import type { IntentDefinition } from './types.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 declare const intents: IntentDefinition[];

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,
+];