@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
229 lines • 6.71 kB
TypeScript
import type { StxOptions } from './types';
/**
* Builds web components from stx components
*/
export declare function buildWebComponents(options: StxOptions, dependencies: Set<string>): Promise<string[]>;
/**
* Generate a unique scope ID for a component
*/
export declare function generateScopeId(componentName: string): string;
/**
* Scope CSS for a web component.
*
* This function transforms CSS to be scoped to a specific component,
* preventing style leakage in non-shadow DOM scenarios.
*
* @param css - Original CSS content
* @param componentTag - Component tag name
* @param config - Scoping configuration
* @returns Scoped CSS
*
* @example
* // Attribute scoping (default)
* scopeCSS('.btn { color: red; }', 'my-button')
* // => '.btn[data-v-a1b2c3d4] { color: red; }'
*
* @example
* // Prefix scoping
* scopeCSS('.btn { color: red; }', 'my-button', { strategy: 'prefix', prefix: 'my-button' })
* // => '.my-button-btn { color: red; }'
*/
export declare function scopeCSS(css: string, componentTag: string, config?: Partial<CssScopingConfig>): string;
/**
* Transform HTML to include scope attributes
*
* @param html - Original HTML content
* @param componentTag - Component tag name
* @param config - Scoping configuration
* @returns HTML with scope attributes added
*/
export declare function scopeHTML(html: string, componentTag: string, config?: Partial<CssScopingConfig>): string;
/**
* Get the scope attribute for a component
*/
export declare function getScopeAttribute(componentTag: string, config?: Partial<CssScopingConfig>): string;
/**
* Extract and scope inline styles from HTML
*
* @param html - HTML content with style tags
* @param componentTag - Component tag name
* @param config - Scoping configuration
* @returns Object with scoped HTML and extracted scoped CSS
*/
export declare function extractAndScopeStyles(html: string, componentTag: string, config?: Partial<CssScopingConfig>): { html: string, css: string };
/**
* Generate a reactive web component with full lifecycle management.
*
* Features:
* - Reactive properties with automatic re-rendering
* - Property observers for side effects
* - Attribute reflection (property <-> attribute sync)
* - Internal state management with setState()
* - Batched rendering with requestAnimationFrame
* - Full lifecycle hooks (connected, disconnected, adopted)
* - Event handling system
* - Template interpolation with property values
*
* @param config - Reactive web component configuration
* @returns JavaScript code for the web component
*
* @example
* ```typescript
* const code = generateReactiveWebComponent({
* name: 'CounterButton',
* tag: 'counter-button',
* template: '<button>Count: {{count}}</button>',
* properties: {
* count: { type: 'number', default: 0, reflect: true, render: true },
* label: { type: 'string', default: 'Click me' }
* },
* state: { clicks: 0 },
* events: {
* click: 'this._handleClick()'
* },
* methods: {
* _handleClick: `this.count++; this.setState({ clicks: this._state.clicks + 1 });`
* }
* })
* ```
*/
export declare function generateReactiveWebComponent(config: ReactiveWebComponentConfig): string;
/**
* Generate TypeScript version of reactive web component
*/
export declare function generateReactiveWebComponentTS(config: ReactiveWebComponentConfig): string;
/**
* Create a mixin for adding reactivity to existing web components.
*
* @returns JavaScript code for a ReactiveElement mixin
*
* @example
* ```javascript
* // Generated mixin usage:
* class MyComponent extends ReactiveElement(HTMLElement) {
* static get properties() {
* return {
* name: { type: 'string', default: 'World' }
* }
* }
* }
* ```
*/
export declare function generateReactiveMixin(): string;
/**
* Generate a complete reactive web component runtime that can be included in pages.
* This provides the base classes and utilities for reactive components.
*
* @returns JavaScript runtime code
*/
export declare function generateReactiveRuntime(): string;
/**
* Parse an SFC-style web component file
*
* Expected format:
* ```html
* <script>
* export default {
* tag: 'my-button',
* props: ['type', 'text'],
* shadowDOM: true // optional, defaults to true
* }
* </script>
*
* <button class="{{ type }}">{{ text }}</button>
*
* <style>
* button { padding: 8px 16px; }
* </style>
* ```
*/
export declare function parseSFCComponent(source: string, defaultTag: string): ParsedSFCComponent;
/**
* Generate a web component class from parsed SFC
*/
export declare function generateSFCWebComponent(parsed: ParsedSFCComponent): string;
/**
* Directive handler for embedding web components in templates.
*
* The directive looks for an SFC-style component file and generates
* an inline script with the web component class.
*
* Usage:
* ```html
* @webcomponent('my-button')
* <my-button type="primary" text="Click Me"></my-button>
* ```
*
* Component file (components/my-button.stx):
* ```html
* <script>
* export default {
* tag: 'my-button',
* props: ['type', 'text']
* }
* </script>
*
* <button class="{{ type }}">{{ text }}</button>
*
* <style>
* button { padding: 8px 16px; }
* </style>
* ```
*/
export declare function webComponentDirectiveHandler(content: string, params: string[], context: Record<string, any>, filePath: string): Promise<string>;
/**
* Property definition for reactive web components
*/
export declare interface ReactivePropertyDefinition {
type: 'string' | 'number' | 'boolean' | 'object' | 'array'
default?: unknown
reflect?: boolean
attribute?: string | false
observer?: string
render?: boolean
}
/**
* Reactive web component configuration
*/
export declare interface ReactiveWebComponentConfig {
name: string
tag: string
baseElement?: string
template: string
styles?: string
shadowDOM?: boolean
properties?: Record<string, ReactivePropertyDefinition>
lifecycle?: {
connected?: string
disconnected?: string
adopted?: string
attributeChanged?: string
}
events?: Record<string, string>
methods?: Record<string, string>
state?: Record<string, unknown>
}
/**
* CSS scoping configuration
*/
export declare interface CssScopingConfig {
strategy: CssScopingStrategy
prefix?: string
attributeName?: string
preserveOriginal?: boolean
}
/**
* Parsed SFC web component structure
*/
export declare interface ParsedSFCComponent {
tag: string
props: string[]
template: string
styles: string
script: string
shadowDOM: boolean
}
/**
* CSS scoping strategy
*/
export type CssScopingStrategy = 'shadow' | 'prefix' | 'attribute' | 'bem'