@vyuh/react-feature-system/dist/index.d.ts

System feature package for Vyuh React framework

import { FeatureDescriptor, RouteBase, ContentItem, SchemaItem, ImageReference, ObjectReference, Condition, FileReference, TypeDescriptor, LayoutConfiguration, ActionConfiguration, ConditionConfiguration } from '@vyuh/react-core';
import { ContentDescriptor } from '@vyuh/react-extension-content';
import { PortableTextTypeComponent, PortableTextMarkComponent, PortableTextBlockComponent, PortableTextListComponent, PortableTextListItemComponent } from '@portabletext/react';
import React from 'react';

/**
 * System feature for Vyuh React
 *
 * Provides core content types and functionality:
 */
declare const system: FeatureDescriptor;

declare const ROUTE_SCHEMA_TYPE = "vyuh.route";
/**
 * Route content item implementation for Vyuh React
 *
 * Routes represent navigable content in a Vyuh application. They combine
 * content from the CMS with routing configuration to create dynamic,
 * content-driven navigation.
 */
interface Route extends RouteBase {
    /**
     * Regions containing content items for this route
     */
    readonly regions: Region[];
}
/**
 * Interface for content regions in a route
 *
 * Regions are named sections of a route that can contain content items.
 * They allow for organizing content into logical sections that can be
 * targeted by layouts and styling.
 */
interface Region {
    /**
     * Unique identifier for the region
     */
    readonly identifier: string;
    /**
     * Display title for the region
     */
    readonly title: string;
    /**
     * Content items contained in this region
     */
    readonly items: ContentItem[];
}

/**
 * Configuration for route lifecycle handlers.
 *
 * Lifecycle handlers allow executing code at specific points in a route's lifecycle:
 * - When a route is initialized
 * - When a route is disposed
 */
interface RouteLifecycleConfiguration extends SchemaItem {
    /**
     * Initialize the route when it becomes active.
     *
     * @param route The route being initialized
     * @returns The initialized route, or null if initialization failed
     */
    init?(route: RouteBase): Promise<RouteBase | null>;
    /**
     * Clean up the route when it is no longer active.
     *
     * @param route The route being disposed
     */
    dispose?(route: RouteBase): Promise<void>;
}

/**
 * Descriptor for configuring route content type in the system.
 *
 * Allows configuring:
 * - Lifecycle handlers for route initialization and cleanup
 * - Available layouts for routes
 */
declare class RouteDescriptor extends ContentDescriptor<Route> {
    /**
     * Lifecycle handlers available for routes
     */
    readonly lifecycleHandlers?: RouteLifecycleConfiguration[];
    /**
     * Creates a new route descriptor
     */
    constructor(props?: Partial<RouteDescriptor>);
}

declare const PORTABLE_TEXT_SCHEMA_TYPE = "vyuh.portableText";
/**
 * Portable Text content item for rendering rich text content
 */
interface PortableText extends ContentItem {
    readonly blocks: any[];
}

/**
 * Descriptor for a block type component
 */
interface BlockTypeDescriptor {
    type: string;
    component: PortableTextTypeComponent;
}
/**
 * Descriptor for a mark component
 */
interface MarkDescriptor {
    type: string;
    component: PortableTextMarkComponent;
}
/**
 * Descriptor for a block style component
 */
interface BlockStyleDescriptor {
    style: string;
    component: PortableTextBlockComponent;
}
/**
 * Descriptor for a list component
 */
interface ListDescriptor {
    type: string;
    component: PortableTextListComponent;
}
/**
 * Descriptor for a list item component
 */
interface ListItemDescriptor {
    type: string;
    component: PortableTextListItemComponent;
}
/**
 * Descriptor for configuring portable text content type in the system
 */
declare class PortableTextDescriptor extends ContentDescriptor<PortableText> {
    readonly blockTypes?: BlockTypeDescriptor[];
    readonly marks?: MarkDescriptor[];
    readonly blockStyles?: BlockStyleDescriptor[];
    readonly lists?: ListDescriptor[];
    readonly listItems?: ListItemDescriptor[];
    constructor(props?: Partial<PortableTextDescriptor>);
}

declare const CARD_SCHEMA_TYPE = "vyuh.card";
/**
 * Card content item for displaying content in a card format
 *
 * Cards can include:
 * - Title and description
 * - Image (via URL or ImageReference)
 * - Content body
 * - Actions that can be configured with multiple action configurations
 */
interface Card extends ContentItem {
    /**
     * The title of the card
     */
    readonly title?: string;
    /**
     * The description or subtitle of the card
     */
    readonly description?: string;
    /**
     * URL for the card's image
     */
    readonly imageUrl?: string;
    /**
     * Image reference for the card
     */
    readonly image?: ImageReference;
    /**
     * The main content of the card
     */
    readonly content?: any;
    /**
     * Primary action for the card
     */
    readonly action?: any;
    /**
     * Secondary action for the card
     */
    readonly secondaryAction?: any;
    /**
     * Tertiary action for the card
     */
    readonly tertiaryAction?: any;
}

/**
 * Descriptor for the Card content type
 *
 * This descriptor configures:
 * - The schema type for cards
 * - Available layouts for cards
 * - Default configuration
 *
 * Example:
 * ```tsx
 * const descriptor = new CardDescriptor({
 *   layouts: [new TypeDescriptor<CustomCardLayout>()],
 * });
 * ```
 */
declare class CardDescriptor extends ContentDescriptor<Card> {
    /**
     * Creates a new Card descriptor
     *
     * @param options Configuration options for the descriptor
     */
    constructor(options?: Partial<CardDescriptor>);
}

declare const GROUP_SCHEMA_TYPE = "vyuh.group";
/**
 * Group content item for displaying a collection of content items
 *
 * Groups can include:
 * - Title and description
 * - A collection of content items
 * - Display options for how items are presented (carousel, grid, etc.)
 */
interface Group extends ContentItem {
    /**
     * The title of the group
     */
    readonly title?: string;
    /**
     * The description or subtitle of the group
     */
    readonly description?: string;
    /**
     * The items contained in this group
     */
    readonly items: ContentItem[];
}

/**
 * Descriptor for the Group content type
 *
 * This descriptor configures:
 * - The schema type for groups
 * - Available layouts for groups
 * - Default configuration
 *
 * Example:
 * ```tsx
 * const descriptor = new GroupDescriptor({
 *   layouts: [new CustomGroupLayout()],
 * });
 * ```
 */
declare class GroupDescriptor extends ContentDescriptor<Group> {
    /**
     * Creates a new Group descriptor
     *
     * @param options Configuration options for the descriptor
     */
    constructor(options?: Partial<GroupDescriptor>);
}

declare const ACCORDION_SCHEMA_TYPE = "vyuh.accordion";
/**
 * Accordion item for individual sections within an accordion
 *
 * Each accordion item has:
 * - A title that serves as the trigger/header
 * - Optional icon identifier
 * - Content to be displayed when expanded
 */
interface AccordionItem {
    /**
     * The title of the accordion item (displayed in the header)
     */
    readonly title: string;
    /**
     * Optional icon identifier for the accordion item
     */
    readonly iconIdentifier?: string;
    /**
     * The content to display when the accordion item is expanded
     */
    readonly content?: ContentItem;
}
/**
 * Accordion content item for displaying collapsible content sections
 *
 * Accordions can include:
 * - Title and description for the overall accordion
 * - Multiple accordion items, each with their own title and content
 * - Configurable expand/collapse behavior
 */
interface Accordion extends ContentItem {
    /**
     * The title of the accordion
     */
    readonly title?: string;
    /**
     * The description or subtitle of the accordion
     */
    readonly description?: string;
    /**
     * The accordion items to display
     */
    readonly items: AccordionItem[];
}

/**
 * Descriptor for the Accordion content type
 *
 * This descriptor configures:
 * - The schema type for accordions
 * - Available layouts for accordions
 * - Default configuration
 *
 * Example:
 * ```tsx
 * const descriptor = new AccordionDescriptor({
 *   layouts: [new TypeDescriptor<CustomAccordionLayout>()],
 * });
 * ```
 */
declare class AccordionDescriptor extends ContentDescriptor<Accordion> {
    /**
     * Creates a new Accordion descriptor
     *
     * @param options Configuration options for the descriptor
     */
    constructor(options?: Partial<AccordionDescriptor>);
}

/**
 * A case item that pairs a condition value with its corresponding route reference.
 *
 * Used within ConditionalRoute to define what route should be shown for each
 * condition value.
 *
 * Example:
 * ```typescript
 * const caseItem = new CaseRouteItem({
 *   value: 'mobile',
 *   item: { type: 'reference', ref: 'route-123' },
 * });
 * ```
 */
interface CaseRouteItem {
    /**
     * The value to match against the condition result
     */
    readonly value?: string;
    /**
     * Reference to the route to display when this case matches
     */
    readonly item?: ObjectReference;
}
declare const CONDITIONAL_ROUTE_SCHEMA_TYPE = "vyuh.conditionalRoute";
/**
 * A route that conditionally displays different routes based on a condition.
 *
 * ConditionalRoute evaluates a condition and then displays the appropriate
 * route based on the result. This allows for dynamic routing based on
 * user state, device characteristics, or other runtime conditions.
 *
 * Example:
 * ```typescript
 * const route = new ConditionalRoute({
 *   id: 'route-123',
 *   title: 'Conditional Route',
 *   path: '/conditional',
 *   condition: {
 *     configuration: new DeviceTypeCondition(),
 *   },
 *   cases: [
 *     new CaseRouteItem({
 *       value: 'mobile',
 *       item: { type: 'reference', ref: 'mobile-route' },
 *     }),
 *     new CaseRouteItem({
 *       value: 'desktop',
 *       item: { type: 'reference', ref: 'desktop-route' },
 *     }),
 *   ],
 *   defaultCase: 'desktop',
 *   createdAt: new Date(),
 *   updatedAt: new Date(),
 * });
 * ```
 */
interface ConditionalRoute extends RouteBase {
    /**
     * The schema type for this content item
     * This is required by ContentItem
     */
    readonly schemaType: typeof CONDITIONAL_ROUTE_SCHEMA_TYPE;
    /**
     * The condition to evaluate
     */
    readonly condition?: Condition;
    /**
     * The cases to match against the condition result
     */
    readonly cases?: CaseRouteItem[];
    /**
     * The default case to use if no cases match
     */
    readonly defaultCase?: string;
}
/**
 * Evaluate the condition and return the appropriate route
 */
declare function evaluateConditionalRoute(route: ConditionalRoute): Promise<RouteBase | undefined>;

/**
 * Descriptor for configuring conditional route content type in the system.
 *
 * Allows configuring:
 * - Available layouts for conditional routes
 * - Custom layouts for specific use cases
 *
 * Example:
 * ```typescript
 * const descriptor = new ConditionalRouteDescriptor({
 *   layouts: [
 *     DefaultConditionalRouteLayout.typeDescriptor,
 *   ],
 * });
 * ```
 */
declare class ConditionalRouteDescriptor extends ContentDescriptor<ConditionalRoute> {
    /**
     * Creates a new conditional route descriptor
     */
    constructor(props?: Partial<ConditionalRouteDescriptor>);
}

/**
 * A case item that pairs a condition value with its corresponding content.
 */
interface CaseContentItem {
    /**
     * The value to match against the condition result
     */
    readonly value?: string;
    /**
     * The content to display when this case matches
     */
    readonly item?: ContentItem;
}
declare const CONDITIONAL_CONTENT_SCHEMA_TYPE = "vyuh.conditional";
/**
 * A content item that conditionally displays different content based on a condition.
 */
interface ConditionalContent extends ContentItem {
    /**
     * The schema type for this content item
     */
    readonly schemaType: typeof CONDITIONAL_CONTENT_SCHEMA_TYPE;
    /**
     * The condition to evaluate
     */
    readonly condition?: Condition;
    /**
     * The cases to match against the condition result
     */
    readonly cases?: CaseContentItem[];
    /**
     * The default case to use if no cases match
     */
    readonly defaultCase?: string;
}
/**
 * Evaluate the condition and return the appropriate content
 */
declare function evaluateConditionalContent(content: ConditionalContent): Promise<ContentItem | null>;

/**
 * Descriptor for configuring conditional content type in the system.
 */
declare class ConditionalContentDescriptor extends ContentDescriptor<ConditionalContent> {
    /**
     * Creates a new conditional content descriptor
     */
    constructor(props?: Partial<ConditionalContentDescriptor>);
}

declare const DIVIDER_SCHEMA_TYPE = "vyuh.divider";
/**
 * Divider content item
 *
 * A visual separator that can be used between content sections
 * with configurable thickness and indentation.
 */
interface Divider extends ContentItem {
    /**
     * The thickness of the divider in pixels
     */
    readonly thickness: number;
    /**
     * Indent from the edges (in pixels or CSS units)
     */
    readonly indent?: string | number;
}

/**
 * Descriptor for the Divider content type
 *
 * This descriptor configures:
 * - The schema type for dividers
 * - Available layouts for dividers
 * - Default configuration
 */
declare class DividerDescriptor extends ContentDescriptor<Divider> {
    /**
     * Creates a new Divider descriptor
     *
     * @param options Configuration options for the descriptor
     */
    constructor(options?: Partial<DividerDescriptor>);
}

/**
 * Type of video link source
 */
declare enum VideoLinkType {
    url = "url",
    file = "file"
}
declare const VIDEO_PLAYER_SCHEMA_TYPE = "vyuh.videoPlayer";
/**
 * A content item that plays video content from various sources.
 *
 * Features:
 * * Network video playback
 * * File reference video playback (e.g., from CMS)
 * * Autoplay, loop, and mute controls
 * * Optional title/caption
 * * Full-screen support
 * * Playback controls
 */
interface VideoPlayer extends ContentItem {
    /**
     * Optional title for the video that can be used as a caption
     */
    readonly title?: string;
    /**
     * The type of link for the video
     */
    readonly linkType: VideoLinkType;
    /**
     * The File reference of the video
     */
    readonly file?: FileReference;
    /**
     * The URL of the video
     */
    readonly url?: string;
    /**
     * Whether the video should loop
     */
    readonly loop: boolean;
    /**
     * Whether the video should autoplay
     */
    readonly autoplay: boolean;
    /**
     * Whether the video should be muted
     */
    readonly muted: boolean;
}

/**
 * Descriptor for the VideoPlayer content type
 *
 * This descriptor configures:
 * - The schema type for video players
 * - Available layouts for video players
 * - Default configuration
 */
declare class VideoPlayerDescriptor extends ContentDescriptor<VideoPlayer> {
    /**
     * Creates a new VideoPlayer descriptor
     *
     * @param options Configuration options for the descriptor
     */
    constructor(options?: Partial<VideoPlayerDescriptor>);
}

declare const API_CONTENT_SCHEMA_TYPE = "vyuh.apiContent";
/**
 * Interface for API Content items
 */
interface APIContent extends ContentItem {
    readonly schemaType: string;
    readonly showPending: boolean;
    readonly showError: boolean;
    readonly configuration?: APIConfiguration;
}
/**
 * Base class for API configuration
 */
declare abstract class APIConfiguration<T = any> implements SchemaItem {
    readonly schemaType: string;
    readonly title?: string;
    protected constructor(props: {
        schemaType: string;
        title?: string;
    });
    /**
     * Invokes the API to fetch data
     */
    abstract invoke(): Promise<T | undefined>;
    /**
     * Builds the UI with the fetched data
     */
    abstract build(data: T | undefined): React.ReactNode;
    static fromJson(json: APIContent): APIConfiguration | undefined;
}
/**
 * Descriptor for API Content
 */
declare class APIContentDescriptor extends ContentDescriptor<APIContent> {
    readonly configurations?: TypeDescriptor<APIConfiguration>[];
    constructor(props?: Partial<APIContentDescriptor>);
}

/**
 * Schema type for DocumentView content
 */
declare const DOCUMENT_VIEW_SCHEMA_TYPE = "vyuh.document.view";
/**
 * Document load strategy
 */
declare enum DocumentLoadStrategy {
    REFERENCE = "reference",
    QUERY = "query"
}
/**
 * Query configuration interface
 */
declare abstract class QueryConfiguration implements SchemaItem {
    readonly schemaType: string;
    readonly title?: string;
    protected constructor(props: {
        schemaType: string;
        title?: string;
    });
    /**
     * Build a query string from the configuration
     */
    abstract buildQuery(): string | null;
    static fromJson(json: DocumentView): QueryConfiguration | undefined;
}
/**
 * DocumentView content type
 *
 * Represents a view that loads and displays a document
 */
interface DocumentView extends ContentItem {
    schemaType: typeof DOCUMENT_VIEW_SCHEMA_TYPE;
    /**
     * Optional title for the document view
     */
    title?: string;
    /**
     * Reference to a document
     */
    reference?: ObjectReference;
    /**
     * Strategy for loading the document
     */
    loadStrategy: DocumentLoadStrategy;
    /**
     * Query configuration for loading documents
     */
    query?: QueryConfiguration;
}

/**
 * Descriptor for DocumentView content
 */
declare class DocumentViewDescriptor extends ContentDescriptor {
    /**
     * List of query configurations that can be used with this view
     */
    queries?: TypeDescriptor<QueryConfiguration>[];
    constructor(props?: {
        documentTypes?: TypeDescriptor<any>[];
        queries?: TypeDescriptor<QueryConfiguration>[];
        layouts?: TypeDescriptor<any>[];
    });
}

/**
 * Document view component props
 */
interface DocumentViewComponentProps {
    content: DocumentView;
    itemLayout?: LayoutConfiguration<ContentItem>;
}
/**
 * Document view component
 */
declare const DocumentViewComponent: React.FC<DocumentViewComponentProps>;

/**
 * Action configuration for navigating to a URL or route reference.
 *
 * This action uses the router to navigate to a specified path or route.
 *
 * Example usage:
 * ```typescript
 * // Navigate by URL
 * const urlAction = new NavigateAction({
 *   url: '/dashboard',
 *   navigationType: 'push',
 * });
 *
 * // Navigate by route reference
 * const routeAction = new NavigateAction({
 *   routeId: 'route-123',
 *   navigationType: 'push',
 * });
 * ```
 */
declare class NavigateAction extends ActionConfiguration {
    /**
     * Schema type for the navigate action
     */
    static readonly schemaType = "vyuh.action.navigation";
    /**
     * Type descriptor for the navigate action
     */
    static readonly typeDescriptor: TypeDescriptor<NavigateAction>;
    /**
     * The URL to navigate to (used when linkType is 'url')
     */
    readonly url?: string;
    /**
     * The route ID reference to navigate to (used when linkType is 'route')
     */
    readonly route?: ObjectReference;
    /**
     * The type of link - either direct URL or route reference
     */
    readonly linkType?: 'route' | 'url';
    /**
     * The navigation type - push adds to history, replace changes current entry
     */
    readonly navigationType?: 'push' | 'replace' | 'go';
    /**
     * Creates a new navigate action
     */
    constructor(data?: Partial<NavigateAction>);
    /**
     * Executes the navigation action
     */
    execute(): Promise<void>;
}

/**
 * Enum for URL launch modes
 */
declare enum UrlLaunchMode {
    inAppWebView = "inAppWebView",
    externalApplication = "externalApplication",
    platformDefault = "platformDefault"
}
/**
 * Action configuration for opening URLs in various ways.
 *
 * Features:
 * * Open in new tab
 * * Open in current tab
 * * Open in background tab
 * * URL validation
 * * Error handling
 *
 * Example usage:
 * ```typescript
 * // Open in new tab
 * const action = new OpenUrlAction({
 *   url: 'https://example.com',
 *   mode: UrlLaunchMode.NewTab,
 * });
 *
 * // Open in current tab
 * const action = new OpenUrlAction({
 *   url: 'https://example.com',
 *   mode: UrlLaunchMode.CurrentTab,
 * });
 * ```
 */
declare class OpenUrlAction extends ActionConfiguration {
    /**
     * Schema type for the open URL action
     */
    static readonly schemaType = "vyuh.action.openUrl";
    /**
     * Type descriptor for the open URL action
     */
    static readonly typeDescriptor: TypeDescriptor<OpenUrlAction>;
    /**
     * The URL to open
     */
    readonly url?: string;
    /**
     * The mode to use when launching the URL
     */
    readonly mode: UrlLaunchMode;
    /**
     * Creates a new open URL action
     */
    constructor(data?: Partial<OpenUrlAction>);
    /**
     * Executes the open URL action
     */
    execute(): Promise<void>;
}

/**
 * A simple boolean condition that returns a fixed value.
 *
 * This condition can be used for:
 * - Feature flags
 * - Testing conditional routes
 * - Temporarily enabling/disabling features
 * - Simulating network delays with the evaluationDelayInSeconds property
 *
 * Example:
 * ```typescript
 * const condition = {
 *   configuration: new BooleanCondition({
 *     value: true,
 *     evaluationDelayInSeconds: 2 // 2 second delay
 *   }),
 * };
 *
 * // Execute the condition
 * const result = await executeCondition(condition);
 * ```
 */
declare class BooleanCondition extends ConditionConfiguration {
    static readonly schemaType = "vyuh.condition.boolean";
    /**
     * The boolean value this condition will return
     */
    readonly value: boolean;
    /**
     * Optional delay in seconds before returning the result
     * Useful for testing loading states
     */
    readonly evaluationDelayInSeconds?: number;
    /**
     * Type descriptor for the boolean condition
     */
    static readonly typeDescriptor: TypeDescriptor<BooleanCondition>;
    /**
     * Creates a new boolean condition
     */
    constructor(data?: Partial<BooleanCondition>);
    /**
     * Executes the condition and returns the result
     *
     * @param params Optional parameters for condition evaluation
     * @returns null if the condition is true (passes), or an error message if false
     */
    execute(params?: Record<string, any>): Promise<string | null>;
}

export { ACCORDION_SCHEMA_TYPE, APIConfiguration, type APIContent, APIContentDescriptor, API_CONTENT_SCHEMA_TYPE, type Accordion, AccordionDescriptor, type AccordionItem, type BlockStyleDescriptor, type BlockTypeDescriptor, BooleanCondition, CARD_SCHEMA_TYPE, CONDITIONAL_CONTENT_SCHEMA_TYPE, CONDITIONAL_ROUTE_SCHEMA_TYPE, type Card, CardDescriptor, type CaseContentItem, type CaseRouteItem, type ConditionalContent, ConditionalContentDescriptor, type ConditionalRoute, ConditionalRouteDescriptor, DIVIDER_SCHEMA_TYPE, DOCUMENT_VIEW_SCHEMA_TYPE, type Divider, DividerDescriptor, DocumentLoadStrategy, type DocumentView, DocumentViewComponent, type DocumentViewComponentProps, DocumentViewDescriptor, GROUP_SCHEMA_TYPE, type Group, GroupDescriptor, type ListDescriptor, type ListItemDescriptor, type MarkDescriptor, NavigateAction, OpenUrlAction, PORTABLE_TEXT_SCHEMA_TYPE, type PortableText, PortableTextDescriptor, QueryConfiguration, ROUTE_SCHEMA_TYPE, type Region, type Route, RouteDescriptor, type RouteLifecycleConfiguration, UrlLaunchMode, VIDEO_PLAYER_SCHEMA_TYPE, VideoLinkType, type VideoPlayer, VideoPlayerDescriptor, evaluateConditionalContent, evaluateConditionalRoute, system };