@stacksjs/stx 0.2.0 → 0.2.3

package/dist/forms-validation.d.ts

@@ -0,0 +1,173 @@
+export type { ValidatorFn, AsyncValidatorFn, ValidatorRule, FieldState, FormState };
+/**
+ * Define a form with validation schema.
+ *
+ * @example
+ * ```typescript
+ * const form = defineForm({
+ *   email: v.required().email(),
+ *   password: v.required().min(8),
+ *   age: v.number().between(18, 100)
+ * })
+ *
+ * // Access form state
+ * form.values.email
+ * form.errors.email
+ * form.isValid
+ *
+ * // Validate
+ * await form.validate()
+ *
+ * // Handle submit
+ * form.handleSubmit((values) => {
+ *   console.log(values)
+ * })
+ * ```
+ */
+export declare function defineForm<T extends Record<string, Validator>>(schema: T, initialValues?: Partial<{ [K in keyof T]: unknown }>): FormState<T>;
+/**
+ * Process @error directive in templates
+ *
+ * @example
+ * ```html
+ * @error(form.email)
+ *   <span class="text-red-500">{{ message }}</span>
+ * @enderror
+ * ```
+ */
+export declare function processErrorDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Process @errors directive (shows all errors for a field)
+ *
+ * @example
+ * ```html
+ * @errors(form.password)
+ *   <li>{{ message }}</li>
+ * @enderrors
+ * ```
+ */
+export declare function processErrorsDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Process @hasErrors directive (conditional block if field has errors)
+ *
+ * @example
+ * ```html
+ * @hasErrors(form.email)
+ *   <div class="error-container">
+ *     ...
+ *   </div>
+ * @endhasErrors
+ * ```
+ */
+export declare function processHasErrorsDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Process all form validation directives
+ */
+export declare function processFormValidationDirectives(content: string, context: Record<string, unknown>, filePath?: string): string;
+/**
+ * Starting point for building validation rules.
+ *
+ * @example
+ * ```typescript
+ * v.required().email()
+ * v.required().min(8).hasUppercase()
+ * v.number().between(1, 100)
+ * ```
+ */
+export declare const v: Validator;
+declare interface ValidatorRule {
+  name: string
+  validate: ValidatorFn | AsyncValidatorFn
+  message: string
+  async?: boolean
+}
+declare interface FieldState {
+  value: unknown
+  errors: string[]
+  touched: boolean
+  dirty: boolean
+  valid: boolean
+  validating: boolean
+}
+declare interface FormState<T extends Record<string, Validator>> {
+  values: { [K in keyof T]: unknown }
+  errors: { [K in keyof T]: string[] }
+  touched: { [K in keyof T]: boolean }
+  dirty: { [K in keyof T]: boolean }
+  isValid: boolean
+  isValidating: boolean
+  isDirty: boolean
+  validate: () => Promise<boolean>
+  validateField: (field: keyof T) => Promise<boolean>
+  reset: () => void
+  setValues: (values: Partial<{ [K in keyof T]: unknown }>) => void
+  setFieldValue: (field: keyof T, value: unknown) => void
+  setFieldTouched: (field: keyof T, touched?: boolean) => void
+  getFieldState: (field: keyof T) => FieldState
+  handleSubmit: (onSubmit: (values: { [K in keyof T]: unknown }) => void | Promise<void>) => (e?: Event) => Promise<void>
+}
+/**
+ * STX Form Validation
+ *
+ * A simple, chainable form validation API.
+ *
+ * @example
+ * ```typescript
+ * import { defineForm, v } from 'stx'
+ *
+ * const form = defineForm({
+ *   email: v.required().email(),
+ *   password: v.required().min(8),
+ *   age: v.number().between(18, 100)
+ * })
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+declare type ValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => true | string
+declare type AsyncValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => Promise<true | string>
+// =============================================================================
+// Validator Class
+// =============================================================================
+declare class Validator {
+  private rules: ValidatorRule[];
+  private defaultValue: unknown;
+  private addRule(rule: ValidatorRule): Validator;
+  required(message?: any): Validator;
+  email(message?: any): Validator;
+  url(message?: any): Validator;
+  min(length: number, message?: string): Validator;
+  max(length: number, message?: string): Validator;
+  length(min: number, max: number, message?: string): Validator;
+  pattern(regex: RegExp, message?: any): Validator;
+  hasUppercase(message?: any): Validator;
+  hasLowercase(message?: any): Validator;
+  hasNumber(message?: any): Validator;
+  hasSpecial(message?: any): Validator;
+  alphanumeric(message?: any): Validator;
+  startsWithLetter(message?: any): Validator;
+  noSpaces(message?: any): Validator;
+  number(message?: any): Validator;
+  integer(message?: any): Validator;
+  positive(message?: any): Validator;
+  negative(message?: any): Validator;
+  minValue(min: number, message?: string): Validator;
+  maxValue(max: number, message?: string): Validator;
+  between(min: number, max: number, message?: string): Validator;
+  matches(fieldName: string, message?: string): Validator;
+  oneOf(values: unknown[], message?: string): Validator;
+  notOneOf(values: unknown[], message?: string): Validator;
+  date(message?: any): Validator;
+  before(date: Date | string, message?: string): Validator;
+  after(date: Date | string, message?: string): Validator;
+  custom(fn: ValidatorFn, message?: any): Validator;
+  async(fn: AsyncValidatorFn, message?: any): Validator;
+  when(condition: (value: unknown, formValues: Record<string, unknown>) => boolean, thenValidator: Validator): Validator;
+  getRules(): ValidatorRule[];
+  getDefaultValue(): unknown;
+  default(value: unknown): Validator;
+  validate(value: unknown, formValues?: Record<string, unknown>): Promise<string[]>;
+  validateSync(value: unknown, formValues?: Record<string, unknown>): string[];
+}
+export { Validator };

package/dist/forms.d.ts

@@ -1,21 +1,170 @@
 import type { StxOptions } from './types';
 /**
- * Process all form-related directives
+ * Process all form-related directives.
+ *
+ * Processing order:
+ * 1. Validation setup (@validate - generates HTML5 attributes)
+ * 2. Basic directives (@csrf, @method)
+ * 3. Form input directives (@form, @input, @textarea, etc.)
+ * 4. Error display directives (@error)
  */
-export declare function processForms(template: string, context: Record<string, any>, _filePath: string, _options: StxOptions): string;
+export declare function processForms(template: string, context: Record<string, any>, _filePath: string, options: StxOptions): string;
 /**
  * Process basic form directives (@csrf, @method)
  */
 export declare function processBasicFormDirectives(template: string, context: Record<string, any>): string;
 /**
- * Process form input directives
+ * Process form input directives.
+ * Handles @form, @input, @textarea, @select, @checkbox, @radio, @label.
  */
-export declare function processFormInputDirectives(template: string, context: Record<string, any>): string;
+export declare function processFormInputDirectives(template: string, context: Record<string, any>, classes?: FormClassConfig): string;
 /**
- * Process @error directive for form validation
+ * Process @error directive for form validation.
+ * Renders content only when the specified field has validation errors.
+ *
+ * @example
+ * ```html
+ * @error('email')
+ *   <span class="error">{{ $message }}</span>
+ * @enderror
+ * ```
  */
-export declare function processErrorDirective(template: string, context: Record<string, any>): string;
+export declare function processErrorDirective(template: string, context: Record<string, any>, _classes?: FormClassConfig): string;
 /**
- * Process @form directives for forms
+ * Register a custom validation rule.
+ *
+ * @param name - Rule name
+ * @param validator - Validation function returning error message or null
+ *
+ * @example
+ * ```typescript
+ * registerValidationRule('phone', (value, params, field) => {
+ *   if (!/^\+?[\d\s-]+$/.test(value)) {
+ *     return `The ${field} field must be a valid phone number.`
+ *   }
+ *   return null
+ * })
+ * ```
  */
-export declare function processFormDirectives(template: string, context: Record<string, any>): string;
+export declare function registerValidationRule(name: string, validator: (value: any, params: string[], field: string) => string | null): void;
+/**
+ * Validate a single field value against rules.
+ *
+ * @param field - Field name
+ * @param value - Field value
+ * @param rules - Pipe-separated rules (e.g., 'required|email|max:255')
+ * @param context - Context for accessing other field values (for confirmed rule)
+ * @returns Validation result
+ */
+export declare function validateField(field: string, value: any, rules: string, context?: Record<string, any>): FieldValidationResult;
+/**
+ * Validate multiple fields.
+ *
+ * @param data - Object with field values
+ * @param rules - Object mapping field names to rule strings
+ * @returns Object with errors per field (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const errors = validateFields(
+ *   { email: 'test', password: '123' },
+ *   { email: 'required|email', password: 'required|min:8' }
+ * )
+ * // => { email: ['The email field must be a valid email address.'], password: ['The password field must be at least 8 characters.'] }
+ * ```
+ */
+export declare function validateFields(data: Record<string, any>, rules: Record<string, string>): Record<string, string[]>;
+/**
+ * Process @validate directive.
+ * Adds validation attributes to the next form element.
+ *
+ * Usage:
+ * ```html
+ * @validate('email', 'required|email|max:255')
+ * @input('email')
+ *
+ * @validate('password', 'required|min:8', { message: 'Password too short' })
+ * @input('password', '', { type: 'password' })
+ * ```
+ */
+export declare function processValidateDirective(template: string, _context: Record<string, any>): string;
+/**
+ * Register a custom enhanced validation rule
+ */
+export declare function registerEnhancedValidationRule(rule: EnhancedValidationRule): void;
+/**
+ * Validate a single value against enhanced rules
+ */
+export declare function validateValueEnhanced(value: unknown, rules: string, allValues?: Record<string, unknown>): { valid: boolean, errors: string[] };
+/**
+ * Validate multiple values with enhanced validation
+ */
+export declare function validateFormEnhanced(values: Record<string, unknown>, rules: Record<string, string>): { valid: boolean, errors: Record<string, string[]> };
+/**
+ * Generate client-side validation script for a form
+ */
+export declare function generateValidationScript(formId: string, rules: Record<string, string>): string;
+/**
+ * Default form class configuration (Bootstrap-compatible)
+ */
+export declare const defaultFormClasses: FormClassConfig;
+/**
+ * Enhanced validation rules registry with full validation support
+ */
+export declare const enhancedValidationRules: {
+  required: { name: 'required'; validate: (value) => unknown; toHtml5: () => unknown; message: 'This field is required' };
+  email: { name: 'email'; validate: (value) => unknown };
+  url: { name: 'url'; validate: (value) => unknown };
+  numeric: { name: 'numeric'; validate: (value) => unknown; toHtml5: () => unknown };
+  integer: { name: 'integer'; validate: (value) => unknown; message: 'Please enter a whole number' };
+  alpha: { name: 'alpha'; validate: (value) => unknown; toHtml5: () => unknown };
+  alphanumeric: { name: 'alphanumeric'; validate: (value) => unknown; toHtml5: () => unknown };
+  min: { name: 'min'; validate: (value, params) => unknown };
+  max: { name: 'max'; validate: (value, params) => unknown };
+  between: { name: 'between'; validate: (value, params) => unknown; toHtml5: unknown };
+  confirmed: { name: 'confirmed'; validate: (value, _params, allValues) => unknown };
+  in: { name: 'in'; validate: (value, params) => unknown; message: 'Must be one of: {{values}}' };
+  notIn: { name: 'notIn'; validate: (value, params) => unknown; message: 'Must not be: {{values}}' };
+  regex: { name: 'regex'; validate: (value, params) => unknown };
+  date: { name: 'date'; validate: (value) => unknown };
+  before: { name: 'before'; validate: (value, params) => unknown };
+  after: { name: 'after'; validate: (value, params) => unknown };
+  size: { name: 'size'; validate: (value, params) => unknown };
+  phone: { name: 'phone'; validate: (value) => unknown }
+};
+/**
+ * Default CSS class names for form elements.
+ * Based on Bootstrap conventions but fully customizable.
+ */
+export declare interface FormClassConfig {
+  input: string
+  inputError: string
+  checkInput: string
+  label: string
+  errorFeedback: string
+}
+/**
+ * Validation rule definition
+ */
+export declare interface ValidationRule {
+  name: string
+  params?: string[]
+  message?: string
+}
+/**
+ * Validation result for a single field
+ */
+export declare interface FieldValidationResult {
+  field: string
+  valid: boolean
+  errors: string[]
+}
+/**
+ * Enhanced validation rule definition with HTML5 support
+ */
+export declare interface EnhancedValidationRule {
+  name: string
+  validate: (value: unknown, params: string[], allValues: Record<string, unknown>) => true | string
+  toHtml5?: (params: string[]) => string[]
+  message: string
+}

package/dist/head.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Get the current accumulated head config.
+ */
+export declare function getHead(): HeadConfig;
+/**
+ * Get current page meta.
+ */
+export declare function getPageMeta(): PageMeta;
+/**
+ * Reset head state (for SSR).
+ */
+export declare function resetHead(): void;
+/**
+ * Set document head configuration.
+ *
+ * @example
+ * ```typescript
+ * useHead({
+ *   title: 'My Page',
+ *   meta: [
+ *     { name: 'description', content: 'Page description' },
+ *     { property: 'og:image', content: '/og.png' }
+ *   ],
+ *   link: [
+ *     { rel: 'canonical', href: 'https://example.com/page' }
+ *   ],
+ *   script: [
+ *     { src: 'https://example.com/analytics.js', async: true }
+ *   ]
+ * })
+ * ```
+ */
+export declare function useHead(config: HeadConfig): void;
+/**
+ * Set SEO meta tags with a simplified API.
+ *
+ * @example
+ * ```typescript
+ * useSeoMeta({
+ *   title: 'My Page',
+ *   description: 'This is my awesome page',
+ *   ogImage: 'https://example.com/og.png',
+ *   twitterCard: 'summary_large_image'
+ * })
+ * ```
+ */
+export declare function useSeoMeta(config: SeoMeta): void;
+/**
+ * Define page-level metadata.
+ *
+ * @example
+ * ```typescript
+ * definePageMeta({
+ *   title: 'Dashboard',
+ *   layout: 'admin',
+ *   middleware: ['auth', 'admin'],
+ *   keepAlive: true
+ * })
+ * ```
+ */
+export declare function definePageMeta(config: PageMeta): void;
+/**
+ * Set just the page title.
+ *
+ * @example
+ * ```typescript
+ * useTitle('My Page')
+ * useTitle(() => `${productName} - My Store`)
+ * ```
+ */
+export declare function usePageTitle(title: string | (() => string)): void;
+/**
+ * Render head config to HTML string.
+ */
+export declare function renderHead(config?: HeadConfig): string;
+/**
+ * Get HTML attributes string.
+ */
+export declare function renderHtmlAttrs(config?: HeadConfig): string;
+/**
+ * Get body attributes string.
+ */
+export declare function renderBodyAttrs(config?: HeadConfig): string;
+/**
+ * Apply head config to the actual document (client-side).
+ */
+export declare function applyHead(config?: HeadConfig): void;
+/**
+ * Process @head directive.
+ *
+ * @example
+ * ```html
+ * @head
+ *   <title>My Page</title>
+ *   <meta name="description" content="...">
+ * @endhead
+ * ```
+ */
+export declare function processHeadDirective(content: string): { content: string; headContent: string };
+/**
+ * Process @title directive.
+ *
+ * @example
+ * ```html
+ * @title('My Page Title')
+ * @title(pageTitle)
+ * ```
+ */
+export declare function processTitleDirective(content: string, context: Record<string, unknown>): string;
+/**
+ * Process @meta directive.
+ *
+ * @example
+ * ```html
+ * @meta('description', 'Page description')
+ * @meta('og:image', ogImageUrl)
+ * ```
+ */
+export declare function processMetaDirective(content: string, context: Record<string, unknown>): string;
+/**
+ * STX Head Management
+ *
+ * Manage document head (title, meta, links, scripts) with a simple API.
+ *
+ * @example
+ * ```typescript
+ * import { useHead, useSeoMeta, definePageMeta } from 'stx'
+ *
+ * // Full control
+ * useHead({
+ *   title: 'My Page',
+ *   meta: [{ name: 'description', content: '...' }]
+ * })
+ *
+ * // SEO shorthand
+ * useSeoMeta({
+ *   title: 'My Page',
+ *   description: 'Page description',
+ *   ogImage: '/og.png'
+ * })
+ *
+ * // Page configuration
+ * definePageMeta({
+ *   title: 'My Page',
+ *   layout: 'default'
+ * })
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface MetaTag {
+  name?: string
+  property?: string
+  content: string
+  httpEquiv?: string
+  charset?: string
+}
+export declare interface LinkTag {
+  rel: string
+  href: string
+  type?: string
+  sizes?: string
+  crossorigin?: string
+  as?: string
+  media?: string
+}
+export declare interface ScriptTag {
+  src?: string
+  type?: string
+  async?: boolean
+  defer?: boolean
+  content?: string
+  id?: string
+}
+export declare interface HeadConfig {
+  title?: string
+  titleTemplate?: string | ((title: string) => string)
+  base?: { href?: string; target?: string }
+  meta?: MetaTag[]
+  link?: LinkTag[]
+  script?: ScriptTag[]
+  style?: { content: string; type?: string }[]
+  htmlAttrs?: Record<string, string>
+  bodyAttrs?: Record<string, string>
+}
+export declare interface SeoMeta {
+  title?: string
+  titleTemplate?: string
+  description?: string
+  keywords?: string | string[]
+  author?: string
+  robots?: string
+  canonical?: string
+  ogTitle?: string
+  ogDescription?: string
+  ogImage?: string
+  ogUrl?: string
+  ogType?: string
+  ogSiteName?: string
+  ogLocale?: string
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  twitterTitle?: string
+  twitterDescription?: string
+  twitterImage?: string
+  twitterSite?: string
+  twitterCreator?: string
+  articleAuthor?: string
+  articlePublishedTime?: string
+  articleModifiedTime?: string
+  articleSection?: string
+  articleTags?: string[]
+}
+export declare interface PageMeta {
+  title?: string
+  description?: string
+  layout?: string | false
+  middleware?: string | string[]
+  transition?: string | { name: string; mode?: string }
+  keepAlive?: boolean
+  key?: string | ((route: unknown) => string)
+}
+export {
+  usePageTitle as useTitle
+};

package/dist/heatmap.d.ts

@@ -0,0 +1,125 @@
+import type { CustomDirective, StxOptions } from './types';
+/**
+ * Generate heatmap tracking script based on configuration
+ */
+export declare function generateHeatmapScript(options: StxOptions): string;
+/**
+ * Inject heatmap script into HTML
+ * Scripts are injected just before </body> for optimal loading
+ */
+export declare function injectHeatmap(html: string, options: StxOptions): string;
+/**
+ * Create a heatmap aggregator instance
+ */
+export declare function createHeatmapAggregator(): HeatmapAggregator;
+/**
+ * Default heatmap configuration
+ */
+export declare const defaultHeatmapConfig: HeatmapConfig;
+/**
+ * Custom @heatmap directive for explicit placement
+ */
+export declare const heatmapDirective: CustomDirective;
+/**
+ * Heatmap Module
+ *
+ * Privacy-compliant heatmap tracking library that tracks user interactions
+ * without collecting personally identifiable information (PII).
+ *
+ * ## Features
+ * - Mouse movement tracking
+ * - Click tracking
+ * - Scroll depth tracking
+ * - Privacy compliant (no PII, no cookies by default)
+ * - Configurable sampling rates
+ * - Export data for analysis
+ *
+ * ## Configuration
+ *
+ * Heatmap can be configured in `stx.config.ts`:
+ * ```typescript
+ * export default {
+ *   heatmap: {
+ *     enabled: true,
+ *     trackMouse: true,
+ *     trackClicks: true,
+ *     trackScroll: true,
+ *     samplingRate: 100, // Track every 100ms
+ *     honorDnt: true,
+ *     endpoint: '/api/heatmap'
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Heatmap tracking configuration
+ */
+export declare interface HeatmapConfig {
+  enabled: boolean
+  trackMouse?: boolean
+  trackClicks?: boolean
+  trackScroll?: boolean
+  samplingRate?: number
+  honorDnt?: boolean
+  endpoint?: string
+  batchSize?: number
+  maxDataPoints?: number
+  sessionTimeout?: number
+  persistData?: boolean
+  storagePrefix?: string
+  captureAttributes?: string[]
+  ignoreSelectors?: string[]
+  zones?: HeatmapZone[]
+  debugOverlay?: boolean
+  minViewportWidth?: number
+  maxViewportWidth?: number
+}
+/**
+ * Zone definition for grouped tracking
+ */
+export declare interface HeatmapZone {
+  id: string
+  selector: string
+  label?: string
+}
+/**
+ * Heatmap data point
+ */
+export declare interface HeatmapDataPoint {
+  x: number
+  y: number
+  type: 'move' | 'click' | 'scroll'
+  t: number
+  el?: string
+  zone?: string
+  depth?: number
+  attrs?: Record<string, string>
+}
+/**
+ * Heatmap session data
+ */
+export declare interface HeatmapSession {
+  sid: string
+  page: string
+  vw: number
+  vh: number
+  points: HeatmapDataPoint[]
+  started: number
+  lastActivity: number
+}
+/**
+ * Server-side heatmap data aggregator
+ * For processing collected heatmap data into visualizations
+ */
+export declare class HeatmapAggregator {
+  private sessions: Map<string, HeatmapSession>;
+  addSession(data: HeatmapSession): void;
+  getPageData(page: string): HeatmapDataPoint[];
+  getClickData(page: string): HeatmapDataPoint[];
+  getMovementData(page: string): HeatmapDataPoint[];
+  getScrollData(page: string): { depth: number, count: number }[];
+  getZoneStats(page: string): Map<string, { clicks: number, hovers: number }>;
+  generateGridData(page: string, gridSize?: number): { x: number, y: number, intensity: number }[][];
+  exportJSON(): string;
+  clear(): void;
+}