@synergy-design-system/metadata 3.7.0 → 3.9.0

package/dist/public/domains/intent-policy.d.ts

@@ -0,0 +1,255 @@
+import { type FrameworkProfile, type IntentCapability, type IntentCategory, type IntentDefinition, type IntentPresetValue, type IntentResolutionResult, type IntentTargetRef, type MetadataStoreOptions, type PublicResponse } from '../types.js';
+import type { IntentPhase, IntentPropRule, IntentStructureNode } from '../../intentPolicy/types.js';
+/**
+ * @experimental Intent policy query options may evolve during rollout.
+ */
+export type IntentListQueryOptions = {
+    category?: string;
+    includePhases?: IntentPhase[];
+};
+/**
+ * @experimental Intent policy query options may evolve during rollout.
+ */
+export type IntentResolutionQuery = {
+    includePhases?: IntentPhase[];
+    intent: string;
+    target: IntentTargetRef;
+};
+/**
+ * @experimental Intent policy query options may evolve during rollout.
+ */
+export type IntentRenderQuery = {
+    content?: string;
+    framework: FrameworkProfile;
+    includePhases?: IntentPhase[];
+    intent: string;
+    target?: IntentTargetRef;
+};
+/**
+ * @experimental Intent policy query options may evolve during rollout.
+ */
+export type IntentPhaseQueryOptions = {
+    includePhases?: IntentPhase[];
+};
+/**
+ * @experimental Intent policy query options may evolve during rollout.
+ */
+export type IntentCategoryQueryOptions = {
+    includePhases?: IntentPhase[];
+};
+/**
+ * List all available intent categories.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const listIntentCategories: (storeOptions?: MetadataStoreOptions, options?: IntentPhaseQueryOptions) => Promise<PublicResponse<IntentCategory[]>>;
+/**
+ * Return one intent category by its ID.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const getIntentCategory: (categoryId: string, options?: IntentCategoryQueryOptions, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentCategory | null>>;
+/**
+ * List intents, optionally filtered by category.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const listIntents: (options?: IntentListQueryOptions, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentDefinition[]>>;
+/**
+ * List all capabilities (targets) that support a given intent.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const listIntentCapabilities: (intentId: string, options?: IntentListQueryOptions, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentCapability[]>>;
+/**
+ * Return capability categories for one target.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const getTargetCapabilities: (target: IntentTargetRef, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentCapability | null>>;
+/**
+ * Resolve one target + intent pair to a usage pattern/preset.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const resolveIntent: (query: IntentResolutionQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentResolutionResult | null>>;
+/**
+ * Render one target + intent pair to framework-specific component markup.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const renderIntent: (query: IntentRenderQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<string | null>>;
+/**
+ * @experimental Validation severity levels for component usage checks.
+ */
+export type ComponentValidationSeverity = 'error' | 'info' | 'warning';
+/**
+ * @experimental Validation issue emitted by validateComponent.
+ */
+export type ComponentValidationIssue = {
+    code: string;
+    message: string;
+    path?: string;
+    rationale?: string;
+    severity: ComponentValidationSeverity;
+    suggestedFix?: string;
+};
+/**
+ * @experimental Query payload for validateComponent.
+ */
+export type ValidateComponentQuery = {
+    component: string;
+    framework: FrameworkProfile;
+    includePhases?: IntentPhase[];
+    intent?: string;
+    props?: Record<string, IntentPresetValue>;
+    structure?: IntentStructureNode;
+};
+/**
+ * @experimental validateComponent response payload.
+ */
+export type ValidateComponentResult = {
+    component: string;
+    framework: FrameworkProfile;
+    issues: ComponentValidationIssue[];
+    score: number;
+    valid: boolean;
+};
+/**
+ * @experimental Query payload for getComponentGuide.
+ */
+export type ComponentGuideQuery = {
+    component: string;
+    framework: FrameworkProfile;
+    includePhases?: IntentPhase[];
+};
+/**
+ * @experimental Supported intent summary for one component.
+ */
+export type ComponentGuideIntent = {
+    category: string;
+    description: string;
+    id: string;
+    phase?: IntentPhase;
+};
+/**
+ * @experimental Recommended usage snippet for one component + intent.
+ */
+export type ComponentGuideUsage = {
+    description: string;
+    intentId: string;
+    propRules: IntentPropRule[];
+    snippet: string;
+};
+/**
+ * @experimental getComponentGuide response payload.
+ */
+export type ComponentGuideResult = {
+    commonMisuses: ComponentValidationIssue[];
+    component: string;
+    framework: FrameworkProfile;
+    quickChecks: Array<{
+        detail: string;
+        pass: boolean;
+        title: string;
+    }>;
+    recommendedUsages: ComponentGuideUsage[];
+    supportedIntents: ComponentGuideIntent[];
+};
+/**
+ * @experimental Query payload for findComponentsForTask.
+ */
+export type FindComponentsForTaskQuery = {
+    constraints?: {
+        avoidTargets?: string[];
+        preferredTargets?: string[];
+    };
+    content?: string;
+    framework: FrameworkProfile;
+    includePhases?: IntentPhase[];
+    maxAlternatives?: number;
+    taskId: string;
+};
+/**
+ * @experimental One ranked recommendation for a task.
+ */
+export type TaskRecommendation = {
+    intentId: string;
+    rank: number;
+    snippet: string;
+    targetId: string;
+    why: string;
+};
+/**
+ * @experimental findComponentsForTask response payload.
+ */
+export type FindComponentsForTaskResult = {
+    alternatives: TaskRecommendation[];
+    framework: FrameworkProfile;
+    notes: string[];
+    primaryRecommendation: TaskRecommendation | null;
+    taskId: string;
+};
+/**
+ * @experimental Query payload for getIntentOptions.
+ */
+export type IntentOptionsQuery = {
+    content?: string;
+    framework: FrameworkProfile;
+    includeDiagnostics?: boolean;
+    includePhases?: IntentPhase[];
+    intentId: string;
+    maxAlternatives?: number;
+};
+/**
+ * @experimental One renderable option for an intent.
+ */
+export type IntentOption = {
+    phase?: IntentPhase;
+    previewCode: string;
+    reason: string;
+    targetId: string;
+    targetName?: string;
+};
+/**
+ * @experimental One non-renderable candidate for an intent.
+ */
+export type NonRenderableIntentCandidate = {
+    detail: string;
+    reasonCode: string;
+    targetId: string;
+};
+/**
+ * @experimental getIntentOptions response payload.
+ */
+export type IntentOptionsResult = {
+    bestDefaultTargetId: string | null;
+    framework: FrameworkProfile;
+    intentId: string;
+    nonRenderableCandidates: NonRenderableIntentCandidate[];
+    renderableTargets: IntentOption[];
+};
+/**
+ * Validate whether a component usage aligns with intent-policy guidance.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const validateComponent: (query: ValidateComponentQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<ValidateComponentResult | null>>;
+/**
+ * Return developer-focused usage guidance for one component.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const getComponentGuide: (query: ComponentGuideQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<ComponentGuideResult | null>>;
+/**
+ * Find component recommendations for a task mapped to an intent ID.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const findComponentsForTask: (query: FindComponentsForTaskQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<FindComponentsForTaskResult | null>>;
+/**
+ * Return renderable options for one intent and framework.
+ *
+ * @experimental This API is still under active design.
+ */
+export declare const getIntentOptions: (query: IntentOptionsQuery, storeOptions?: MetadataStoreOptions) => Promise<PublicResponse<IntentOptionsResult | null>>;