@stacksjs/stx 0.2.0 → 0.2.3

package/dist/runtime.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Get a store by name
+ *
+ * @example
+ * ```ts
+ * const appStore = useStore('appStore')
+ * console.log(appStore.state.count)
+ *
+ * appStore.setState({ count: appStore.state.count + 1 })
+ * ```
+ */
+export declare function useStore<T = unknown>(name: string): StoreRef<T> | null;
+/**
+ * Get a store, throwing if not found
+ */
+export declare function useStoreOrThrow<T = unknown>(name: string): StoreRef<T>;
+/**
+ * Check if a store exists
+ */
+export declare function hasStore(name: string): boolean;
+/**
+ * Get all store names
+ */
+export declare function getStoreNames(): string[];
+/**
+ * Wait for a store to be ready (for async initialization)
+ */
+export declare function waitForStore<T = unknown>(name: string, timeout?: any): Promise<StoreRef<T>>;
+/**
+ * Get current route parameters
+ *
+ * @example
+ * ```ts
+ * // URL: /users/123
+ * const params = useRouteParams()
+ * console.log(params.id) // '123'
+ * ```
+ */
+export declare function useRouteParams(): RouteParams;
+/**
+ * Get a specific route parameter
+ *
+ * @example
+ * ```ts
+ * const userId = useRouteParam('id')
+ * ```
+ */
+export declare function useRouteParam(name: string): string | undefined;
+/**
+ * Get a route parameter or throw if missing
+ */
+export declare function useRouteParamOrThrow(name: string): string;
+/**
+ * Get state passed from middleware
+ *
+ * @example
+ * ```ts
+ * // In middleware:
+ * ctx.state.user = { id: 1, name: 'John' }
+ *
+ * // In component:
+ * const state = useMiddlewareState()
+ * console.log(state.user)
+ * ```
+ */
+export declare function useMiddlewareState<T = MiddlewareState>(): T;
+/**
+ * Get a specific middleware state value
+ */
+export declare function useMiddlewareValue<T = unknown>(key: string): T | undefined;
+/**
+ * @internal
+ * Initialize the store registry
+ */
+export declare function initStoreRegistry(): void;
+/**
+ * @internal
+ * Register a store in the registry
+ */
+export declare function registerStore(name: string, store: StoreRef): void;
+/**
+ * @internal
+ * Get serialized store state for hydration
+ */
+export declare function getHydratedStoreState(): Record<string, unknown> | null;
+/**
+ * @internal
+ * Set route params (called by router)
+ */
+export declare function setRouteParams(params: RouteParams): void;
+/**
+ * @internal
+ * Set middleware state (called by middleware runner)
+ */
+export declare function setMiddlewareState(state: MiddlewareState): void;
+/**
+ * Check if running on the server
+ */
+export declare function isServer(): boolean;
+/**
+ * Check if running on the client
+ */
+export declare function isClient(): boolean;
+/**
+ * Run callback only on client
+ *
+ * @example
+ * ```ts
+ * onClient(() => {
+ *   document.title = 'Hello'
+ * })
+ * ```
+ */
+export declare function onClient(callback: () => void): void;
+/**
+ * Run callback only on server
+ */
+export declare function onServer(callback: () => void): void;
+// =============================================================================
+// Store Access
+// =============================================================================
+export declare interface StoreRef<T = unknown> {
+  state: T
+  getState: () => T
+  setState: (updater: Partial<T> | ((state: T) => Partial<T>)) => void
+  subscribe: (listener: (state: T) => void) => () => void
+  reset: () => void
+}
+// =============================================================================
+// Route Params
+// =============================================================================
+export declare interface RouteParams {
+
+}
+// =============================================================================
+// Middleware State
+// =============================================================================
+export declare interface MiddlewareState {
+
+}

package/dist/safe-evaluator.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Configure the safe evaluator
+ *
+ * @example
+ * ```typescript
+ * configureSafeEvaluator({
+ *   maxSanitizeDepth: 20,
+ *   allowBracketNotation: true
+ * })
+ * ```
+ */
+export declare function configureSafeEvaluator(config: Partial<SafeEvaluatorConfig>): void;
+/**
+ * Reset configuration to defaults
+ */
+export declare function resetSafeEvaluatorConfig(): void;
+/**
+ * Get current configuration
+ */
+export declare function getSafeEvaluatorConfig(): SafeEvaluatorConfig;
 /**
  * Sanitize an expression by checking for dangerous patterns
  */
@@ -5,12 +25,106 @@ export declare function sanitizeExpression(expression: string): string;
 /**
  * Create a safer context object that only exposes safe properties
  */
-export declare function createSafeContext(context: Record<string, any>): Record<string, any>;
+export declare function createSafeContext(context: Record<string, unknown>): Record<string, unknown>;
 /**
  * Safely evaluate an expression with the given context
+ *
+ * @param expression - The JavaScript expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns The result of the expression evaluation, or undefined on error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = safeEvaluate('name.toUpperCase()', { name: 'hello' })
+ *
+ * // With type parameter for typed result
+ * const count = safeEvaluate<number>('items.length', { items: [1, 2, 3] })
+ * ```
  */
-export declare function safeEvaluate(expression: string, context: Record<string, any>): any;
+export declare function safeEvaluate<T = unknown>(expression: string, context: Record<string, unknown>): T | undefined;
 /**
  * Check if an expression is safe to evaluate
  */
-export declare function isExpressionSafe(expression: string): boolean;
+export declare function isExpressionSafe(expression: string): boolean;
+/**
+ * Safely evaluate an expression and return a boolean result
+ * Used for conditional expressions in @if, @unless, etc.
+ *
+ * @param expression - The condition expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Boolean result, defaults to false on error
+ */
+export declare function safeEvaluateCondition(expression: string, context: Record<string, unknown>): boolean;
+/**
+ * Safely evaluate an expression that returns an array
+ * Used for loop iterations in @foreach, @for, etc.
+ *
+ * @param expression - The array expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Array result, defaults to empty array on error
+ */
+export declare function safeEvaluateArray(expression: string, context: Record<string, unknown>): unknown[];
+/**
+ * Safely evaluate an expression that returns an object
+ * Used for props, attributes, configuration objects
+ *
+ * @param expression - The object expression to evaluate
+ * @param context - Variables available during evaluation
+ * @returns Object result, defaults to empty object on error
+ */
+export declare function safeEvaluateObject(expression: string, context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a sandboxed function that can only access the provided context
+ * This is a safer alternative to `new Function()` that validates expressions first
+ *
+ * @param expression - The expression to compile into a function
+ * @param contextKeys - Variable names that will be available
+ * @returns A function that takes context values and returns the result
+ * @throws Error if expression contains dangerous patterns
+ *
+ * @example
+ * ```typescript
+ * const fn = createSafeFunction('x + y', ['x', 'y'])
+ * const result = fn(1, 2) // returns 3
+ * ```
+ */
+export declare function createSafeFunction(expression: string, contextKeys: string[]): (...args: unknown[]) => unknown;
+/**
+ * Safely evaluate a return expression (e.g., "return x + y")
+ * Used for script block execution
+ *
+ * @param code - Code that may contain return statements
+ * @param context - Variables available during evaluation
+ * @returns The result of the code execution
+ */
+export declare function safeEvaluateCode(code: string, context: Record<string, unknown>): unknown;
+/**
+ * Validate a for loop expression for safety
+ * Checks for dangerous patterns like eval, Function, import, etc.
+ *
+ * @param expression - The for loop expression (e.g., "let i = 0; i < n; i++")
+ * @returns true if safe, false if potentially dangerous
+ */
+export declare function isForExpressionSafe(expression: string): boolean;
+/**
+ * Create a safe loop function with iteration limits
+ *
+ * @param loopType - 'for' or 'while'
+ * @param expression - The loop expression or condition
+ * @param body - The loop body template
+ * @param contextKeys - Variable names available in context
+ * @param maxIterations - Maximum iterations allowed (for while loops)
+ * @returns A function that executes the loop safely
+ */
+export declare function createSafeLoopFunction(loopType: 'for' | 'while', expression: string, body: string, contextKeys: string[], maxIterations?: number): (...args: unknown[]) => string;
+/**
+ * Safe expression evaluator that reduces security risks from using new Function()
+ */
+/**
+ * Safe evaluator configuration options
+ */
+export declare interface SafeEvaluatorConfig {
+  maxSanitizeDepth: number
+  allowBracketNotation: boolean
+}

package/dist/scaffolding.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Create a new stx project
+ */
+export declare function createProject(projectName: string, options?: CreateProjectOptions): Promise<ScaffoldResult>;
+/**
+ * Add a component
+ */
+export declare function addComponent(name: string, options?: AddComponentOptions): Promise<ScaffoldResult>;
+/**
+ * Add a page
+ */
+export declare function addPage(name: string, options?: AddPageOptions): Promise<ScaffoldResult>;
+/**
+ * Add a store
+ */
+export declare function addStore(name: string, options?: AddStoreOptions): Promise<ScaffoldResult>;
+/**
+ * Add a layout
+ */
+export declare function addLayout(name: string, options?: AddLayoutOptions): Promise<ScaffoldResult>;
+/**
+ * Project template definitions
+ */
+export declare const PROJECT_TEMPLATES: {
+  default: {
+  description: 'Standard stx project with pages, components, and stores';
+  features: readonly ['Pages', 'Components', 'Layouts', 'Stores', 'Dev server']
+};
+  minimal: {
+  description: 'Minimal setup with just the essentials';
+  features: readonly ['Single page', 'Basic styles']
+};
+  full: {
+  description: 'Full-featured project with all stx capabilities';
+  features: readonly ['Pages', 'Components', 'Layouts', 'Stores', 'API routes', 'PWA', 'i18n', 'Testing']
+};
+  blog: {
+  description: 'Blog template with markdown support';
+  features: readonly ['Blog layout', 'Post pages', 'Tags', 'RSS feed', 'Markdown']
+};
+  dashboard: {
+  description: 'Admin dashboard template';
+  features: readonly ['Sidebar', 'Charts', 'Tables', 'Forms', 'Auth pages']
+};
+  landing: {
+  description: 'Marketing landing page template';
+  features: readonly ['Hero section', 'Features', 'Pricing', 'CTA', 'Contact form']
+}
+};
+/**
+ * Project creation options
+ */
+export declare interface CreateProjectOptions {
+  template?: ProjectTemplate
+  skipGit?: boolean
+  skipInstall?: boolean
+  packageManager?: 'bun' | 'npm' | 'pnpm' | 'yarn'
+  typescript?: boolean
+  examples?: boolean
+  pwa?: boolean
+  tailwind?: boolean
+}
+/**
+ * Add component options
+ */
+export declare interface AddComponentOptions {
+  dir?: string
+  props?: boolean
+  styles?: boolean
+  script?: boolean
+  force?: boolean
+}
+/**
+ * Add page options
+ */
+export declare interface AddPageOptions {
+  dir?: string
+  layout?: string
+  dynamic?: boolean
+  loader?: boolean
+  force?: boolean
+}
+/**
+ * Add store options
+ */
+export declare interface AddStoreOptions {
+  dir?: string
+  persist?: boolean
+  actions?: boolean
+  force?: boolean
+}
+/**
+ * Add layout options
+ */
+export declare interface AddLayoutOptions {
+  dir?: string
+  nav?: boolean
+  footer?: boolean
+  force?: boolean
+}
+/**
+ * Scaffolding result
+ */
+export declare interface ScaffoldResult {
+  success: boolean
+  message: string
+  files: string[]
+  errors: string[]
+}
+/**
+ * Project template options
+ */
+export type ProjectTemplate = 'default' | 'minimal' | 'full' | 'blog' | 'dashboard' | 'landing'

package/dist/seo.d.ts

@@ -1,24 +1,102 @@
 import type { CustomDirective, StxOptions } from './types';
 /**
- * Process @meta directive for generating meta tags
+ * Process @meta directive for generating meta tags.
+ * Supports both simple `@meta('name', 'content')` and
+ * OpenGraph `@meta('og:title')` formats.
  */
-export declare function processMetaDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): string;
+export declare function processMetaDirectives(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
 /**
- * Process @structuredData directive for JSON-LD
+ * Process @structuredData directive for JSON-LD.
+ * Automatically adds schema.org context if not provided.
  */
-export declare function processStructuredData(template: string, context: Record<string, any>, filePath: string): string;
+export declare function processStructuredData(template: string, context: Record<string, any>, _filePath: string): string;
 /**
- * Process @seo directive for automatic meta tag generation
+ * Process @seo directive for automatic meta tag generation.
+ * Generates title, description, Open Graph, Twitter, and structured data tags.
  */
-export declare function processSeoDirective(template: string, context: Record<string, any>, filePath: string, options: StxOptions): string;
+export declare function processSeoDirective(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
 /**
- * Injects default SEO tags if no @seo directive is used
+ * Injects default SEO tags if no @seo directive is used.
+ * Respects seo.enabled config and skipDefaultSeoTags option.
  */
 export declare function injectSeoTags(html: string, context: Record<string, any>, options: StxOptions): string;
 /**
  * Register SEO directives
  */
 export declare function registerSeoDirectives(): CustomDirective[];
+/**
+ * Generate an XML sitemap from a list of URL entries.
+ *
+ * @param entries - Array of sitemap entries
+ * @param options - Sitemap generation options
+ * @returns XML sitemap string
+ *
+ * @example
+ * ```typescript
+ * const sitemap = generateSitemap([
+ *   { loc: '/', priority: 1.0 },
+ *   { loc: '/about', priority: 0.8 },
+ *   { loc: '/blog', changefreq: 'daily' },
+ * ], { baseUrl: 'https://example.com' })
+ * ```
+ */
+export declare function generateSitemap(entries: SitemapEntry[], options: SitemapOptions): string;
+/**
+ * Generate a sitemap index for multiple sitemaps.
+ *
+ * @param sitemaps - Array of sitemap URLs
+ * @param baseUrl - Base URL for the site
+ * @returns XML sitemap index string
+ */
+export declare function generateSitemapIndex(sitemaps: string[], baseUrl: string): string;
+/**
+ * Scan a directory and generate sitemap entries.
+ *
+ * @param directory - Directory to scan for .stx/.html files
+ * @param options - Scan options
+ * @param options.extensions - File extensions to include
+ * @param options.ignore - Patterns to ignore
+ * @param options.baseUrl - Base URL for the sitemap
+ * @returns Array of sitemap entries
+ */
+export declare function scanForSitemapEntries(directory: string, options: {
+    extensions?: string[]
+    ignore?: string[]
+    baseUrl: string
+  }): Promise<SitemapEntry[]>;
+/**
+ * Generate a robots.txt file content.
+ *
+ * @param options - Robots.txt options
+ * @returns robots.txt content string
+ *
+ * @example
+ * ```typescript
+ * const robotsTxt = generateRobotsTxt({
+ *   rules: [
+ *     {
+ *       userAgent: '*',
+ *       allow: ['/'],
+ *       disallow: ['/admin', '/private'],
+ *     },
+ *     {
+ *       userAgent: 'Googlebot',
+ *       allow: ['/'],
+ *       crawlDelay: 1,
+ *     },
+ *   ],
+ *   sitemap: 'https://example.com/sitemap.xml',
+ * })
+ * ```
+ */
+export declare function generateRobotsTxt(options: RobotsOptions): string;
+/**
+ * Generate a default robots.txt that allows all crawling.
+ *
+ * @param sitemapUrl - Optional sitemap URL
+ * @returns robots.txt content string
+ */
+export declare function generateDefaultRobotsTxt(sitemapUrl?: string): string;
 /**
  * SEO meta directive for basic meta tag generation
  */
@@ -30,4 +108,39 @@ export declare const structuredDataDirective: CustomDirective;
 declare interface StructuredData {
   '@context': string
   '@type': string
+}
+/**
+ * URL entry for sitemap
+ */
+export declare interface SitemapEntry {
+  loc: string
+  lastmod?: string
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number
+}
+/**
+ * Sitemap generation options
+ */
+export declare interface SitemapOptions {
+  baseUrl: string
+  defaultChangefreq?: SitemapEntry['changefreq']
+  defaultPriority?: number
+  includeLastmod?: boolean
+}
+/**
+ * Robots.txt rule
+ */
+export declare interface RobotsRule {
+  userAgent: string
+  allow?: string[]
+  disallow?: string[]
+  crawlDelay?: number
+}
+/**
+ * Robots.txt generation options
+ */
+export declare interface RobotsOptions {
+  rules: RobotsRule[]
+  sitemap?: string | string[]
+  host?: string
 }

package/dist/server-components.d.ts

@@ -0,0 +1,134 @@
+import type { CustomDirective } from './types';
+/**
+ * Register a server component.
+ */
+export declare function registerServerComponent(component: ServerComponent): void;
+/**
+ * Register a client component.
+ */
+export declare function registerClientComponent(component: ClientComponent): void;
+/**
+ * Get a registered component.
+ */
+export declare function getComponent(name: string): ComponentEntry | undefined;
+/**
+ * Check if a component is registered.
+ */
+export declare function hasComponent(name: string): boolean;
+/**
+ * Get all registered component names.
+ */
+export declare function getComponentNames(): string[];
+/**
+ * Clear all registered components.
+ */
+export declare function clearComponents(): void;
+/**
+ * Clear component cache.
+ */
+export declare function clearComponentCache(name?: string): void;
+/**
+ * Render a server component.
+ */
+export declare function renderServerComponent(name: string, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Render a client component (server-side with hydration markers).
+ */
+export declare function renderClientComponent(name: string, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Render any registered component.
+ */
+export declare function renderComponent(name: string, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Create a suspense boundary.
+ */
+export declare function createSuspenseBoundary(id: string, fallback: string): { wrap: (promise: Promise<string>) => Promise<string>, getFallback: () => string };
+/**
+ * Get suspense state by ID.
+ */
+export declare function getSuspenseState(id: string): SuspenseState | undefined;
+/**
+ * Clear suspense state.
+ */
+export declare function clearSuspenseState(id?: string): void;
+/**
+ * Create a streaming renderer for server components.
+ */
+export declare function createStreamingRenderer(components: string[], options?: RenderOptions): {
+    renderToStream: () => ReadableStream<string>
+    renderToString: () => Promise<string>
+  };
+/**
+ * Register all server component directives.
+ */
+export declare function registerServerComponentDirectives(): CustomDirective[];
+/**
+ * Generate client-side runtime for server components hydration.
+ */
+export declare function generateServerComponentsRuntime(): string;
+/**
+ * @serverComponent directive for defining server components inline.
+ */
+export declare const serverComponentDirective: CustomDirective;
+/**
+ * @clientComponent directive for defining client components inline.
+ */
+export declare const clientComponentDirective: CustomDirective;
+/**
+ * @suspense directive for async boundaries.
+ */
+export declare const suspenseDirective: CustomDirective;
+/** Server component definition */
+export declare interface ServerComponent {
+  name: string
+  template: string
+  loader?: (props: Record<string, unknown>) => Promise<Record<string, unknown>>
+  dependencies?: string[]
+  cache?: CacheConfig
+  errorBoundary?: string
+  suspenseFallback?: string
+}
+/** Client component definition */
+export declare interface ClientComponent {
+  name: string
+  template: string
+  clientScript?: string
+  clientProps?: string[]
+  priority?: 'eager' | 'lazy' | 'idle'
+}
+/** Cache configuration */
+export declare interface CacheConfig {
+  enabled: boolean
+  ttl?: number
+  keyGenerator?: (props: Record<string, unknown>) => string
+  staleWhileRevalidate?: boolean
+}
+/** Server component rendering options */
+export declare interface RenderOptions {
+  props?: Record<string, unknown>
+  streaming?: boolean
+  request?: { url: string, headers: Record<string, string> }
+  signal?: AbortSignal
+}
+/** Server component render result */
+export declare interface RenderResult {
+  html: string
+  renderTime: number
+  data?: Record<string, unknown>
+  dependencies: string[]
+  cached: boolean
+  hydrationScript?: string
+}
+/** Component registry entry */
+declare interface ComponentEntry {
+  component: ServerComponent | ClientComponent
+  type: 'server' | 'client'
+}
+/** Suspense boundary state */
+declare interface SuspenseState {
+  id: string
+  status: 'pending' | 'resolved' | 'error'
+  promise?: Promise<unknown>
+  result?: string
+  error?: Error
+}