@runtypelabs/persona 3.2.2 → 3.4.0

package/dist/theme-reference.d.cts

@@ -0,0 +1,899 @@
+type TokenType = 'color' | 'spacing' | 'typography' | 'shadow' | 'border' | 'radius';
+type TokenReference<_T extends TokenType = TokenType> = string;
+interface ColorShade {
+    50?: string;
+    100?: string;
+    200?: string;
+    300?: string;
+    400?: string;
+    500?: string;
+    600?: string;
+    700?: string;
+    800?: string;
+    900?: string;
+    950?: string;
+    [key: string]: string | undefined;
+}
+interface ColorPalette {
+    gray: ColorShade;
+    primary: ColorShade;
+    secondary: ColorShade;
+    accent: ColorShade;
+    success: ColorShade;
+    warning: ColorShade;
+    error: ColorShade;
+    [key: string]: ColorShade;
+}
+interface SpacingScale {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+    6: string;
+    8: string;
+    10: string;
+    12: string;
+    16: string;
+    20: string;
+    24: string;
+    32: string;
+    40: string;
+    48: string;
+    56: string;
+    64: string;
+    [key: string]: string;
+}
+interface ShadowScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    [key: string]: string;
+}
+interface BorderScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    [key: string]: string;
+}
+interface RadiusScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    full: string;
+    [key: string]: string;
+}
+interface TypographyScale {
+    fontFamily: {
+        sans: string;
+        serif: string;
+        mono: string;
+    };
+    fontSize: {
+        xs: string;
+        sm: string;
+        base: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+        '4xl': string;
+    };
+    fontWeight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        tight: string;
+        normal: string;
+        relaxed: string;
+    };
+}
+interface SemanticColors {
+    primary: TokenReference<'color'>;
+    secondary: TokenReference<'color'>;
+    accent: TokenReference<'color'>;
+    surface: TokenReference<'color'>;
+    background: TokenReference<'color'>;
+    container: TokenReference<'color'>;
+    text: TokenReference<'color'>;
+    textMuted: TokenReference<'color'>;
+    textInverse: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    divider: TokenReference<'color'>;
+    interactive: {
+        default: TokenReference<'color'>;
+        hover: TokenReference<'color'>;
+        focus: TokenReference<'color'>;
+        active: TokenReference<'color'>;
+        disabled: TokenReference<'color'>;
+    };
+    feedback: {
+        success: TokenReference<'color'>;
+        warning: TokenReference<'color'>;
+        error: TokenReference<'color'>;
+        info: TokenReference<'color'>;
+    };
+}
+interface SemanticSpacing {
+    xs: TokenReference<'spacing'>;
+    sm: TokenReference<'spacing'>;
+    md: TokenReference<'spacing'>;
+    lg: TokenReference<'spacing'>;
+    xl: TokenReference<'spacing'>;
+    '2xl': TokenReference<'spacing'>;
+}
+interface SemanticTypography {
+    fontFamily: TokenReference<'typography'>;
+    fontSize: TokenReference<'typography'>;
+    fontWeight: TokenReference<'typography'>;
+    lineHeight: TokenReference<'typography'>;
+}
+interface SemanticTokens {
+    colors: SemanticColors;
+    spacing: SemanticSpacing;
+    typography: SemanticTypography;
+}
+interface ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    foreground?: TokenReference<'color'>;
+    border?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    margin?: TokenReference<'spacing'>;
+    shadow?: TokenReference<'shadow'>;
+    opacity?: number;
+}
+interface ButtonTokens extends ComponentTokenSet {
+    primary: ComponentTokenSet;
+    secondary: ComponentTokenSet;
+    ghost: ComponentTokenSet;
+}
+interface InputTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    placeholder: TokenReference<'color'>;
+    focus: {
+        border: TokenReference<'color'>;
+        ring: TokenReference<'color'>;
+    };
+}
+interface LauncherTokens extends ComponentTokenSet {
+    size: string;
+    iconSize: string;
+    shadow: TokenReference<'shadow'>;
+}
+interface PanelTokens extends ComponentTokenSet {
+    width: string;
+    maxWidth: string;
+    height: string;
+    maxHeight: string;
+}
+interface HeaderTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    borderRadius: TokenReference<'radius'>;
+    /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
+    iconBackground: TokenReference<'color'>;
+    /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
+    iconForeground: TokenReference<'color'>;
+    /** Header title line (next to the icon, or minimal layout title). */
+    titleForeground: TokenReference<'color'>;
+    /** Header subtitle line under the title. */
+    subtitleForeground: TokenReference<'color'>;
+    /** Default color for clear / close icon buttons when launcher overrides are unset. */
+    actionIconForeground: TokenReference<'color'>;
+    /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
+    shadow?: string;
+    /** Override the header bottom border (e.g., `none`). */
+    borderBottom?: string;
+}
+interface MessageTokens {
+    user: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** User bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+    assistant: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** Assistant bubble border color (CSS color). */
+        border?: TokenReference<'color'>;
+        /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+}
+interface MarkdownTokens {
+    inlineCode: {
+        background: TokenReference<'color'>;
+        foreground: TokenReference<'color'>;
+    };
+    /** Foreground for `<a>` in rendered markdown (assistant bubbles + artifact pane). */
+    link?: {
+        foreground: TokenReference<'color'>;
+    };
+    /**
+     * Body font for rendered markdown blocks (artifact pane + markdown bubbles).
+     * Use a raw CSS `font-family` value, e.g. `Georgia, serif`.
+     */
+    prose?: {
+        fontFamily?: string;
+    };
+    /** Optional heading scale overrides (raw CSS or resolvable token paths). */
+    heading?: {
+        h1?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+        h2?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+    };
+}
+interface VoiceTokens {
+    recording: {
+        indicator: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+    processing: {
+        icon: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+    };
+    speaking: {
+        icon: TokenReference<'color'>;
+    };
+}
+interface ApprovalTokens {
+    requested: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+    };
+    approve: ComponentTokenSet;
+    deny: ComponentTokenSet;
+}
+interface AttachmentTokens {
+    image: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+}
+/** Tool-call row chrome (collapsible tool bubbles). */
+interface ToolBubbleTokens {
+    /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Reasoning / “thinking” row chrome. */
+interface ReasoningBubbleTokens {
+    shadow: string;
+}
+/** Composer (message input) chrome. */
+interface ComposerChromeTokens {
+    /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Artifact toolbar chrome. */
+interface ArtifactToolbarTokens {
+    iconHoverColor?: string;
+    iconHoverBackground?: string;
+    iconPadding?: string;
+    iconBorderRadius?: string;
+    iconBorder?: string;
+    toggleGroupGap?: string;
+    toggleBorderRadius?: string;
+    copyBackground?: string;
+    copyBorder?: string;
+    copyColor?: string;
+    copyBorderRadius?: string;
+    copyPadding?: string;
+    copyMenuBackground?: string;
+    copyMenuBorder?: string;
+    copyMenuShadow?: string;
+    copyMenuBorderRadius?: string;
+    copyMenuItemHoverBackground?: string;
+    /** Base background of icon buttons (defaults to --persona-surface). */
+    iconBackground?: string;
+    /** Border on the toolbar (e.g., `none` to remove the bottom border). */
+    toolbarBorder?: string;
+}
+/** Artifact tab strip chrome. */
+interface ArtifactTabTokens {
+    background?: string;
+    activeBackground?: string;
+    activeBorder?: string;
+    borderRadius?: string;
+    textColor?: string;
+    /** Hover background for inactive tabs. */
+    hoverBackground?: string;
+    /** Tab list container background. */
+    listBackground?: string;
+    /** Tab list container border color. */
+    listBorderColor?: string;
+    /** Tab list container padding (CSS shorthand). */
+    listPadding?: string;
+}
+/** Artifact pane chrome. */
+interface ArtifactPaneTokens {
+    /**
+     * Background for the artifact column (toolbar + content), resolved from the theme.
+     * Defaults to `semantic.colors.container` so the pane matches assistant message surfaces.
+     * `features.artifacts.layout.paneBackground` still wins when set (layout escape hatch).
+     */
+    background?: string;
+    toolbarBackground?: string;
+}
+/** Icon button chrome (used by createIconButton). */
+interface IconButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    hoverColor?: string;
+    /** Background when aria-pressed="true". */
+    activeBackground?: string;
+    /** Border color when aria-pressed="true". */
+    activeBorder?: string;
+}
+/** Label button chrome (used by createLabelButton). */
+interface LabelButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    fontSize?: string;
+    gap?: string;
+}
+/** Toggle group chrome (used by createToggleGroup). */
+interface ToggleGroupTokens {
+    /** Gap between toggle buttons. Default: 0 (connected). */
+    gap?: string;
+    /** Border radius for first/last buttons. */
+    borderRadius?: string;
+}
+interface ComponentTokens {
+    button: ButtonTokens;
+    input: InputTokens;
+    launcher: LauncherTokens;
+    panel: PanelTokens;
+    header: HeaderTokens;
+    message: MessageTokens;
+    /** Markdown surfaces (chat + artifact pane). */
+    markdown?: MarkdownTokens;
+    voice: VoiceTokens;
+    approval: ApprovalTokens;
+    attachment: AttachmentTokens;
+    toolBubble: ToolBubbleTokens;
+    reasoningBubble: ReasoningBubbleTokens;
+    composer: ComposerChromeTokens;
+    /** Icon button styling tokens. */
+    iconButton?: IconButtonTokens;
+    /** Label button styling tokens. */
+    labelButton?: LabelButtonTokens;
+    /** Toggle group styling tokens. */
+    toggleGroup?: ToggleGroupTokens;
+    /** Artifact toolbar, tab strip, and pane chrome. */
+    artifact?: {
+        toolbar?: ArtifactToolbarTokens;
+        tab?: ArtifactTabTokens;
+        pane?: ArtifactPaneTokens;
+    };
+}
+interface PaletteExtras {
+    transitions?: Record<string, string>;
+    easings?: Record<string, string>;
+}
+interface PersonaThemeBase {
+    palette: {
+        colors: ColorPalette;
+        spacing: SpacingScale;
+        typography: TypographyScale;
+        shadows: ShadowScale;
+        borders: BorderScale;
+        radius: RadiusScale;
+    } & PaletteExtras;
+}
+interface PersonaThemeSemantic {
+    semantic: SemanticTokens;
+}
+interface PersonaThemeComponents {
+    components: ComponentTokens;
+}
+type PersonaTheme = PersonaThemeBase & PersonaThemeSemantic & PersonaThemeComponents;
+/** Recursive partial for `config.theme` / `config.darkTheme` overrides. */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+
+/**
+ * Theme Reference — Structured documentation and examples for the Persona v2 theme system.
+ *
+ * Exported via the `@runtypelabs/persona/theme-reference` entry point so it stays
+ * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
+ */
+
+declare const THEME_TOKEN_DOCS: {
+    overview: string;
+    layers: {
+        palette: {
+            description: string;
+            colors: {
+                description: string;
+                scales: {
+                    gray: string;
+                    primary: string;
+                    accent: string;
+                    secondary: string;
+                    success: string;
+                    warning: string;
+                    error: string;
+                };
+            };
+            radius: {
+                description: string;
+                defaults: {
+                    none: string;
+                    sm: string;
+                    md: string;
+                    lg: string;
+                    xl: string;
+                    '2xl': string;
+                    full: string;
+                };
+            };
+            typography: {
+                fontFamily: string;
+                fontSize: string;
+                fontWeight: string;
+                lineHeight: string;
+            };
+            shadows: string;
+            borders: string;
+            spacing: string;
+        };
+        semantic: {
+            description: string;
+            colors: {
+                primary: string;
+                secondary: string;
+                accent: string;
+                surface: string;
+                background: string;
+                container: string;
+                text: string;
+                textMuted: string;
+                textInverse: string;
+                border: string;
+                divider: string;
+                interactive: {
+                    default: string;
+                    hover: string;
+                    focus: string;
+                    active: string;
+                    disabled: string;
+                };
+                feedback: {
+                    success: string;
+                    warning: string;
+                    error: string;
+                    info: string;
+                };
+            };
+            spacing: string;
+            typography: string;
+        };
+        components: {
+            description: string;
+            button: {
+                description: string;
+                properties: string;
+            };
+            input: {
+                description: string;
+                properties: string;
+            };
+            launcher: {
+                description: string;
+                properties: string;
+            };
+            panel: {
+                description: string;
+                properties: string;
+            };
+            header: {
+                description: string;
+                properties: string;
+            };
+            message: {
+                description: string;
+                user: string;
+                assistant: string;
+            };
+            markdown: {
+                description: string;
+                properties: string;
+            };
+            voice: string;
+            approval: string;
+            attachment: string;
+            toolBubble: string;
+            reasoningBubble: string;
+            composer: string;
+            artifact: string;
+        };
+    };
+    colorScheme: string;
+    plugins: {
+        description: string;
+        available: {
+            brandPlugin: string;
+            accessibilityPlugin: string;
+            highContrastPlugin: string;
+            reducedMotionPlugin: string;
+            animationsPlugin: string;
+        };
+        usage: string;
+    };
+    widgetConfig: {
+        description: string;
+        launcher: {
+            description: string;
+            properties: {
+                enabled: string;
+                title: string;
+                subtitle: string;
+                position: string;
+                width: string;
+                fullHeight: string;
+                mountMode: string;
+                agentIconText: string;
+                border: string;
+                shadow: string;
+                collapsedMaxWidth: string;
+            };
+        };
+        sendButton: {
+            description: string;
+            properties: string;
+        };
+        closeButton: {
+            description: string;
+            properties: string;
+        };
+        clearChat: {
+            description: string;
+            properties: string;
+        };
+        toolCall: {
+            description: string;
+            properties: string;
+        };
+        copy: {
+            description: string;
+            properties: string;
+        };
+        voiceRecognition: {
+            description: string;
+            properties: string;
+        };
+        suggestionChips: string;
+        layout: {
+            description: string;
+            header: string;
+            messages: string;
+        };
+        features: {
+            description: string;
+            properties: string;
+        };
+    };
+};
+interface ThemeExample {
+    description: string;
+    colorScheme?: 'light' | 'dark' | 'auto';
+    theme: DeepPartial<PersonaTheme>;
+}
+declare const THEME_EXAMPLES: Record<string, ThemeExample>;
+/**
+ * Complete theme reference payload for AI / MCP tool consumption.
+ *
+ * Returns token system docs, the default color palette and radius scale,
+ * example themes, and a list of SDK-bundled presets.
+ */
+declare function getThemeReference(): {
+    tokenDocs: {
+        overview: string;
+        layers: {
+            palette: {
+                description: string;
+                colors: {
+                    description: string;
+                    scales: {
+                        gray: string;
+                        primary: string;
+                        accent: string;
+                        secondary: string;
+                        success: string;
+                        warning: string;
+                        error: string;
+                    };
+                };
+                radius: {
+                    description: string;
+                    defaults: {
+                        none: string;
+                        sm: string;
+                        md: string;
+                        lg: string;
+                        xl: string;
+                        '2xl': string;
+                        full: string;
+                    };
+                };
+                typography: {
+                    fontFamily: string;
+                    fontSize: string;
+                    fontWeight: string;
+                    lineHeight: string;
+                };
+                shadows: string;
+                borders: string;
+                spacing: string;
+            };
+            semantic: {
+                description: string;
+                colors: {
+                    primary: string;
+                    secondary: string;
+                    accent: string;
+                    surface: string;
+                    background: string;
+                    container: string;
+                    text: string;
+                    textMuted: string;
+                    textInverse: string;
+                    border: string;
+                    divider: string;
+                    interactive: {
+                        default: string;
+                        hover: string;
+                        focus: string;
+                        active: string;
+                        disabled: string;
+                    };
+                    feedback: {
+                        success: string;
+                        warning: string;
+                        error: string;
+                        info: string;
+                    };
+                };
+                spacing: string;
+                typography: string;
+            };
+            components: {
+                description: string;
+                button: {
+                    description: string;
+                    properties: string;
+                };
+                input: {
+                    description: string;
+                    properties: string;
+                };
+                launcher: {
+                    description: string;
+                    properties: string;
+                };
+                panel: {
+                    description: string;
+                    properties: string;
+                };
+                header: {
+                    description: string;
+                    properties: string;
+                };
+                message: {
+                    description: string;
+                    user: string;
+                    assistant: string;
+                };
+                markdown: {
+                    description: string;
+                    properties: string;
+                };
+                voice: string;
+                approval: string;
+                attachment: string;
+                toolBubble: string;
+                reasoningBubble: string;
+                composer: string;
+                artifact: string;
+            };
+        };
+        colorScheme: string;
+        plugins: {
+            description: string;
+            available: {
+                brandPlugin: string;
+                accessibilityPlugin: string;
+                highContrastPlugin: string;
+                reducedMotionPlugin: string;
+                animationsPlugin: string;
+            };
+            usage: string;
+        };
+        widgetConfig: {
+            description: string;
+            launcher: {
+                description: string;
+                properties: {
+                    enabled: string;
+                    title: string;
+                    subtitle: string;
+                    position: string;
+                    width: string;
+                    fullHeight: string;
+                    mountMode: string;
+                    agentIconText: string;
+                    border: string;
+                    shadow: string;
+                    collapsedMaxWidth: string;
+                };
+            };
+            sendButton: {
+                description: string;
+                properties: string;
+            };
+            closeButton: {
+                description: string;
+                properties: string;
+            };
+            clearChat: {
+                description: string;
+                properties: string;
+            };
+            toolCall: {
+                description: string;
+                properties: string;
+            };
+            copy: {
+                description: string;
+                properties: string;
+            };
+            voiceRecognition: {
+                description: string;
+                properties: string;
+            };
+            suggestionChips: string;
+            layout: {
+                description: string;
+                header: string;
+                messages: string;
+            };
+            features: {
+                description: string;
+                properties: string;
+            };
+        };
+    };
+    defaultColorPalette: {
+        primary: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+            950: string;
+        };
+        secondary: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+            950: string;
+        };
+        accent: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+            950: string;
+        };
+        gray: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+            950: string;
+        };
+        success: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        warning: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        error: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+    };
+    defaultRadius: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        full: string;
+    };
+    examples: Record<string, ThemeExample>;
+    sdkPresets: string[];
+};
+
+export { THEME_EXAMPLES, THEME_TOKEN_DOCS, type ThemeExample, getThemeReference };