@synergy-design-system/metadata 3.7.0 → 3.8.0

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

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

package/dist/intentPolicy/intents/action.js

@@ -0,0 +1,38 @@
+export const actionIntents = [
+    {
+        category: 'action',
+        description: 'Use when the component should present the primary action in a context.',
+        id: 'action.primary',
+        userGoal: 'Highlight the most important next action for the user.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component submits form data.',
+        id: 'action.submit',
+        userGoal: 'Submit user-provided data to a form handler.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component resets form state to defaults.',
+        id: 'action.reset',
+        userGoal: 'Clear or reset user-entered data.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component should navigate to another location.',
+        id: 'action.navigation',
+        userGoal: 'Move the user to another destination.',
+    },
+    {
+        category: 'action',
+        description: 'Use icon-only buttons for compact actions where space is constrained.',
+        id: 'action.button.icon',
+        userGoal: 'Provide a compact action trigger while preserving quick recognition.',
+    },
+    {
+        category: 'action',
+        description: 'Use grouped actions when related actions should be presented as one unit.',
+        id: 'action.grouped',
+        userGoal: 'Present related actions with clear grouping and consistent alignment.',
+    },
+];

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

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

package/dist/intentPolicy/intents/assistance.js

@@ -0,0 +1,14 @@
+export const assistanceIntents = [
+    {
+        category: 'assistance',
+        description: 'Use tooltip guidance for short, non-critical contextual help.',
+        id: 'assistance.tooltip.contextual',
+        userGoal: 'Clarify a nearby control or value with concise supplemental text.',
+    },
+    {
+        category: 'assistance',
+        description: 'Use contextual icons to visually support meaning near controls or status text.',
+        id: 'assistance.icon.contextual',
+        userGoal: 'Improve scannability and comprehension with compact visual cues.',
+    },
+];

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

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

package/dist/intentPolicy/intents/disclosure.js

@@ -0,0 +1,20 @@
+export const disclosureIntents = [
+    {
+        category: 'disclosure',
+        description: 'Use details to progressively reveal one block of optional content.',
+        id: 'disclosure.details.on-demand',
+        userGoal: 'Show extra information only when requested by the user.',
+    },
+    {
+        category: 'disclosure',
+        description: 'Use accordions to reveal grouped sections and reduce information overload.',
+        id: 'disclosure.accordion.grouped',
+        userGoal: 'Organize larger content into scannable, expandable sections.',
+    },
+    {
+        category: 'disclosure',
+        description: 'Use popups to reveal related secondary content on demand near a trigger.',
+        id: 'disclosure.popup.on-demand',
+        userGoal: 'Show contextual secondary content without navigating away.',
+    },
+];

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

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

package/dist/intentPolicy/intents/feedback.js

@@ -0,0 +1,32 @@
+export const feedbackIntents = [
+    {
+        category: 'feedback',
+        description: 'Use when contextual feedback should remain near the affected content.',
+        id: 'feedback.inline',
+        userGoal: 'Explain outcome directly in the current workflow context.',
+    },
+    {
+        category: 'feedback',
+        description: 'Use when a short, non-blocking overlay notification is sufficient.',
+        id: 'feedback.toast',
+        userGoal: 'Acknowledge an event without interrupting the current task.',
+    },
+    {
+        category: 'feedback',
+        description: 'Use badges to communicate compact status or count information inline.',
+        id: 'feedback.badge.status',
+        userGoal: 'Expose concise status signals without interrupting surrounding content.',
+    },
+    {
+        category: 'feedback',
+        description: 'Use tag labels to communicate categorization or state in compact form.',
+        id: 'feedback.tag.label',
+        userGoal: 'Help users identify and scan categories or states quickly.',
+    },
+    {
+        category: 'feedback',
+        description: 'Use generic validation feedback to explain invalid or missing input.',
+        id: 'feedback.validation.generic',
+        userGoal: 'Guide users to correct invalid form input with clear feedback.',
+    },
+];

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

@@ -0,0 +1,23 @@
+import { actionIntents } from './action.js';
+import { assistanceIntents } from './assistance.js';
+import { disclosureIntents } from './disclosure.js';
+import { feedbackIntents } from './feedback.js';
+import { inputIntents } from './input.js';
+import { navigationIntents } from './navigation.js';
+import { statusIntents } from './status.js';
+import { structureIntents } from './structure.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/intents/input.d.ts

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

package/dist/intentPolicy/intents/input.js

@@ -0,0 +1,62 @@
+export const inputIntents = [
+    {
+        category: 'input',
+        description: 'Use when a user should provide short, single-line text input.',
+        id: 'input.text.short',
+        userGoal: 'Capture compact textual or numeric values in a form field.',
+    },
+    {
+        category: 'input',
+        description: 'Use when a user should provide longer, multi-line input.',
+        id: 'input.text.long',
+        userGoal: 'Capture detailed comments, descriptions, or narrative responses.',
+    },
+    {
+        category: 'input',
+        description: 'Use when one option should be selected from predefined choices.',
+        id: 'input.selection.single',
+        userGoal: 'Make one explicit selection from a known set.',
+    },
+    {
+        category: 'input',
+        description: 'Use when multiple options should be selected from predefined choices.',
+        id: 'input.selection.multiple',
+        userGoal: 'Select multiple relevant options in one control.',
+    },
+    {
+        category: 'input',
+        description: 'Use when options are numerous and should be filtered by typing.',
+        id: 'input.selection.searchable',
+        userGoal: 'Find and select options quickly through live filtering.',
+    },
+    {
+        category: 'input',
+        description: 'Use for binary choices that apply immediately on toggle.',
+        id: 'input.binary.immediate',
+        userGoal: 'Enable or disable a setting with instant effect.',
+    },
+    {
+        category: 'input',
+        description: 'Use for binary choices that are submitted later with the form.',
+        id: 'input.binary.deferred',
+        userGoal: 'Record a binary preference without immediate side effects.',
+    },
+    {
+        category: 'input',
+        description: 'Use when files or folders must be attached or uploaded.',
+        id: 'input.file.upload',
+        userGoal: 'Provide one or more local files for processing.',
+    },
+    {
+        category: 'input',
+        description: 'Use sliders when selecting a numeric value within a bounded range.',
+        id: 'input.range.slider',
+        userGoal: 'Pick a value quickly with immediate visual feedback across a range.',
+    },
+    {
+        category: 'input',
+        description: 'Use grouped options to organize long option lists into logical clusters.',
+        id: 'input.selection.grouped-options',
+        userGoal: 'Find and choose options faster through labeled option groupings.',
+    },
+];

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

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

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

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

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

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

package/dist/intentPolicy/intents/structure.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/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[];