@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/types/context-types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Context Types - Typed interfaces for template context objects
+ */
+import type { StxOptions } from './config-types';
+/**
+ * Loop context object available within @foreach loops
+ * Provides iteration metadata for template logic
+ */
+export interface LoopContext {
+    /** Current zero-based index */
+    index: number;
+    /** Current one-based iteration count */
+    iteration: number;
+    /** Whether this is the first iteration */
+    first: boolean;
+    /** Whether this is the last iteration */
+    last: boolean;
+    /** Total number of items in the array */
+    count: number;
+}
+/**
+ * Authentication context for @auth, @guest, @can directives
+ * Required shape for auth-related template directives
+ *
+ * @example
+ * ```typescript
+ * const authContext: AuthContext = {
+ *   check: true,
+ *   user: { id: 1, name: 'John', role: 'admin' }
+ * }
+ * ```
+ */
+export interface AuthContext {
+    /** Whether the user is authenticated */
+    check: boolean;
+    /** User object (null if not authenticated) */
+    user: Record<string, unknown> | null;
+}
+/**
+ * Permissions context for @can, @cannot directives
+ *
+ * @example
+ * ```typescript
+ * const permissions: PermissionsContext = {
+ *   check: (ability, type?, id?) => {
+ *     // Check if user has the ability
+ *     return user.abilities.includes(ability)
+ *   }
+ * }
+ * ```
+ */
+export interface PermissionsContext {
+    /** Function to check if user has a specific permission */
+    check: (ability: string, type?: string, id?: unknown) => boolean;
+}
+/**
+ * Translation context for @translate, @t directives
+ */
+export interface TranslationContext {
+    /** Translation lookup object keyed by locale */
+    [locale: string]: Record<string, string>;
+}
+/**
+ * Base template context with common properties
+ * Extend this interface for specific template contexts
+ */
+export interface BaseTemplateContext {
+    /** Authentication context (optional) */
+    auth?: AuthContext;
+    /** Permissions context (optional) */
+    permissions?: PermissionsContext;
+    /** User permissions map for simple boolean checks */
+    userCan?: Record<string, boolean>;
+    /** Translations for i18n */
+    __translations?: TranslationContext;
+    /** Internal sections storage (set by layout processing) */
+    __sections?: Record<string, string>;
+    /** Internal stx options reference */
+    __stx_options?: StxOptions;
+    /** Loop context (available within @foreach) */
+    loop?: LoopContext;
+    /** Alias for loop context to avoid conflicts with user variables */
+    $loop?: LoopContext;
+    /** Slot content for components */
+    slot?: string;
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Template context type alias for backward compatibility
+ * Use BaseTemplateContext for new code
+ */
+export type TemplateContext = BaseTemplateContext;
+/**
+ * Generic template context that allows specifying custom typed properties
+ *
+ * @example
+ * ```typescript
+ * // Define your typed context
+ * interface MyContext extends TypedContext<{
+ *   user: { name: string; email: string }
+ *   items: string[]
+ *   count: number
+ * }> {}
+ *
+ * // Use in template processing
+ * const ctx: MyContext = {
+ *   user: { name: 'John', email: 'john@example.com' },
+ *   items: ['a', 'b'],
+ *   count: 42
+ * }
+ * ```
+ */
+export type TypedContext<T extends Record<string, unknown>> = BaseTemplateContext & T;
+/**
+ * Utility type to extract the value type from a context key
+ */
+export type ContextValue<C extends BaseTemplateContext, K extends keyof C> = C[K];
+/**
+ * Utility type to make certain context properties required
+ */
+export type RequireContextKeys<C extends BaseTemplateContext, K extends keyof C> = Required<Pick<C, K>> & Omit<C, K>;

package/dist/types/csp-types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Content Security Policy Types
+ */
+/**
+ * CSP directive source values
+ * These are the standard source values that can be used in CSP directives
+ */
+export type CspSourceValue = '\'self\'' | '\'unsafe-inline\'' | '\'unsafe-eval\'' | '\'unsafe-hashes\'' | '\'strict-dynamic\'' | '\'report-sample\'' | '\'wasm-unsafe-eval\'' | '\'none\'' | 'data:' | 'blob:' | 'https:' | 'http:' | 'ws:' | 'wss:' | string;
+/**
+ * Individual CSP directive configuration
+ * Maps directive names to arrays of allowed sources
+ */
+export interface CspDirectives {
+    /** Default policy for all resource types */
+    'default-src'?: CspSourceValue[];
+    /** Valid sources for JavaScript */
+    'script-src'?: CspSourceValue[];
+    /** Valid sources for stylesheets */
+    'style-src'?: CspSourceValue[];
+    /** Valid sources for images */
+    'img-src'?: CspSourceValue[];
+    /** Valid sources for fonts */
+    'font-src'?: CspSourceValue[];
+    /** Valid sources for XHR, fetch, WebSockets */
+    'connect-src'?: CspSourceValue[];
+    /** Valid sources for media elements (audio, video) */
+    'media-src'?: CspSourceValue[];
+    /** Valid sources for object, embed, applet */
+    'object-src'?: CspSourceValue[];
+    /** Valid sources for iframes */
+    'frame-src'?: CspSourceValue[];
+    /** Valid sources for workers */
+    'worker-src'?: CspSourceValue[];
+    /** Valid sources for child contexts */
+    'child-src'?: CspSourceValue[];
+    /** Valid sources for manifests */
+    'manifest-src'?: CspSourceValue[];
+    /** Restricts URLs for form submissions */
+    'form-action'?: CspSourceValue[];
+    /** Restricts URLs which can embed this page */
+    'frame-ancestors'?: CspSourceValue[];
+    /** Restricts URLs for link prefetch/prerender */
+    'prefetch-src'?: CspSourceValue[];
+    /** Restricts URLs for navigate-to */
+    'navigate-to'?: CspSourceValue[];
+    /** Base URI for relative URLs */
+    'base-uri'?: CspSourceValue[];
+    /** URL to report CSP violations to */
+    'report-uri'?: string[];
+    /** Reporting endpoint name for CSP violations */
+    'report-to'?: string[];
+    /** Enable upgrade-insecure-requests */
+    'upgrade-insecure-requests'?: boolean;
+    /** Enable block-all-mixed-content */
+    'block-all-mixed-content'?: boolean;
+    /** Sandbox restrictions */
+    'sandbox'?: ('allow-forms' | 'allow-modals' | 'allow-orientation-lock' | 'allow-pointer-lock' | 'allow-popups' | 'allow-popups-to-escape-sandbox' | 'allow-presentation' | 'allow-same-origin' | 'allow-scripts' | 'allow-top-navigation' | 'allow-top-navigation-by-user-activation')[];
+    /** Require trusted types */
+    'require-trusted-types-for'?: ('script')[];
+    /** Trusted types policies */
+    'trusted-types'?: string[];
+}
+/**
+ * CSP configuration options
+ */
+export interface CspConfig {
+    /** Enable CSP generation */
+    enabled: boolean;
+    /** Use report-only mode (Content-Security-Policy-Report-Only header) */
+    reportOnly?: boolean;
+    /** CSP directives */
+    directives: CspDirectives;
+    /** Generate nonce for inline scripts/styles */
+    useNonce?: boolean;
+    /** Add CSP as meta tag in HTML head */
+    addMetaTag?: boolean;
+    /** Custom nonce generator function */
+    nonceGenerator?: () => string;
+}
+/**
+ * Preset CSP configurations for common use cases
+ */
+export type CspPreset = 'strict' | 'moderate' | 'relaxed' | 'api';

package/dist/types/directive-types.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Directive Types - Discriminated Unions for all directive types
+ */
+/**
+ * Base directive type with common properties
+ */
+interface BaseDirective {
+    /** The directive type for discriminated union */
+    readonly kind: string;
+    /** Raw matched string from template */
+    raw: string;
+    /** Start position in template */
+    start: number;
+    /** End position in template */
+    end: number;
+}
+/**
+ * Conditional directive (@if, @elseif, @else, @unless, @isset, @empty)
+ */
+export interface ConditionalDirective extends BaseDirective {
+    kind: 'conditional';
+    /** Specific conditional type */
+    type: 'if' | 'elseif' | 'else' | 'endif' | 'unless' | 'endunless' | 'isset' | 'endisset' | 'empty' | 'endempty';
+    /** Condition expression (undefined for @else, @endif, etc.) */
+    condition?: string;
+    /** Content inside the directive block */
+    content?: string;
+}
+/**
+ * Loop directive (@foreach, @for, @while, @forelse)
+ */
+export interface LoopDirective extends BaseDirective {
+    kind: 'loop';
+    /** Specific loop type */
+    type: 'foreach' | 'endforeach' | 'for' | 'endfor' | 'while' | 'endwhile' | 'forelse' | 'empty' | 'endforelse';
+    /** Loop expression (e.g., "items as item" or "let i = 0; i < 10; i++") */
+    expression?: string;
+    /** Item variable name (for foreach) */
+    itemVar?: string;
+    /** Array expression (for foreach) */
+    arrayExpr?: string;
+    /** Content inside the loop */
+    content?: string;
+    /** Empty content (for forelse) */
+    emptyContent?: string;
+}
+/**
+ * Include directive (@include, @includeIf, @includeWhen, @includeUnless, @includeFirst)
+ */
+export interface IncludeDirective extends BaseDirective {
+    kind: 'include';
+    /** Specific include type */
+    type: 'include' | 'includeIf' | 'includeWhen' | 'includeUnless' | 'includeFirst' | 'partial' | 'once';
+    /** Path to the included template */
+    path?: string;
+    /** Array of paths (for includeFirst) */
+    paths?: string[];
+    /** Condition expression (for includeWhen/includeUnless) */
+    condition?: string;
+    /** Local variables to pass to included template */
+    variables?: Record<string, unknown>;
+}
+/**
+ * Layout directive (@layout, @extends, @section, @yield, @parent)
+ */
+export interface LayoutDirective extends BaseDirective {
+    kind: 'layout';
+    /** Specific layout type */
+    type: 'layout' | 'extends' | 'section' | 'endsection' | 'yield' | 'parent' | 'show';
+    /** Layout or section name */
+    name?: string;
+    /** Default content (for yield) */
+    defaultContent?: string;
+    /** Section content */
+    content?: string;
+}
+/**
+ * Component directive (@component, x-component)
+ */
+export interface ComponentDirective extends BaseDirective {
+    kind: 'component';
+    /** Specific component type */
+    type: 'component' | 'endcomponent' | 'slot' | 'endslot';
+    /** Component name */
+    name?: string;
+    /** Component props */
+    props?: Record<string, unknown>;
+    /** Slot name (for named slots) */
+    slotName?: string;
+    /** Slot content */
+    content?: string;
+}
+/**
+ * Auth directive (@auth, @guest, @can, @cannot)
+ */
+export interface AuthDirective extends BaseDirective {
+    kind: 'auth';
+    /** Specific auth type */
+    type: 'auth' | 'endauth' | 'guest' | 'endguest' | 'can' | 'endcan' | 'cannot' | 'endcannot' | 'role' | 'endrole';
+    /** Guard name (optional) */
+    guard?: string;
+    /** Ability/permission name (for can/cannot) */
+    ability?: string;
+    /** Additional arguments for permission check */
+    arguments?: unknown[];
+    /** Content inside the auth block */
+    content?: string;
+}
+/**
+ * Form directive (@csrf, @method, @error, @old)
+ */
+export interface FormDirective extends BaseDirective {
+    kind: 'form';
+    /** Specific form type */
+    type: 'csrf' | 'method' | 'error' | 'enderror' | 'old';
+    /** HTTP method (for @method) */
+    method?: 'PUT' | 'PATCH' | 'DELETE';
+    /** Field name (for @error, @old) */
+    field?: string;
+    /** Content inside error block */
+    content?: string;
+}
+/**
+ * Stack directive (@push, @prepend, @stack)
+ */
+export interface StackDirective extends BaseDirective {
+    kind: 'stack';
+    /** Specific stack type */
+    type: 'push' | 'endpush' | 'prepend' | 'endprepend' | 'stack';
+    /** Stack name */
+    name: string;
+    /** Content to push/prepend */
+    content?: string;
+}
+/**
+ * Expression directive ({{ }}, {!! !!})
+ */
+export interface ExpressionDirective extends BaseDirective {
+    kind: 'expression';
+    /** Expression type */
+    type: 'escaped' | 'raw';
+    /** The expression to evaluate */
+    expression: string;
+    /** Applied filters */
+    filters?: Array<{
+        name: string;
+        args?: unknown[];
+    }>;
+}
+/**
+ * Switch directive (@switch, @case, @default)
+ */
+export interface SwitchDirective extends BaseDirective {
+    kind: 'switch';
+    /** Specific switch type */
+    type: 'switch' | 'case' | 'default' | 'break' | 'endswitch';
+    /** Switch expression */
+    expression?: string;
+    /** Case value */
+    caseValue?: unknown;
+    /** Content */
+    content?: string;
+}
+/**
+ * SEO directive (@meta, @seo, @og, @twitter, @jsonld)
+ */
+export interface SeoDirective extends BaseDirective {
+    kind: 'seo';
+    /** Specific SEO type */
+    type: 'meta' | 'seo' | 'og' | 'twitter' | 'jsonld' | 'canonical' | 'robots';
+    /** Meta name or property */
+    name?: string;
+    /** Meta content */
+    metaContent?: string;
+    /** SEO configuration object */
+    config?: Record<string, unknown>;
+}
+/**
+ * Accessibility directive (@a11y, @screenReader, @ariaDescribe)
+ */
+export interface A11yDirective extends BaseDirective {
+    kind: 'a11y';
+    /** Specific a11y type */
+    type: 'screenReader' | 'srOnly' | 'ariaDescribe' | 'a11y';
+    /** Screen reader text content */
+    text?: string;
+    /** Target element selector (for ariaDescribe) */
+    target?: string;
+    /** Description ID */
+    descriptionId?: string;
+}
+/**
+ * JavaScript/TypeScript execution directive (@js, @ts)
+ */
+export interface ScriptDirective extends BaseDirective {
+    kind: 'script';
+    /** Script type */
+    type: 'js' | 'ts';
+    /** Script code to execute */
+    code: string;
+}
+/**
+ * Environment directive (@env, @production, @development)
+ */
+export interface EnvDirective extends BaseDirective {
+    kind: 'env';
+    /** Specific env type */
+    type: 'env' | 'endenv' | 'production' | 'endproduction' | 'development' | 'enddevelopment';
+    /** Environment names to match */
+    environments?: string[];
+    /** Content */
+    content?: string;
+}
+/**
+ * i18n directive (@translate, @t, @lang)
+ */
+export interface I18nDirective extends BaseDirective {
+    kind: 'i18n';
+    /** Specific i18n type */
+    type: 'translate' | 't' | 'lang' | 'endlang' | 'choice';
+    /** Translation key */
+    key?: string;
+    /** Replacement parameters */
+    params?: Record<string, unknown>;
+    /** Count for pluralization */
+    count?: number;
+    /** Locale override */
+    locale?: string;
+    /** Content (for lang blocks) */
+    content?: string;
+}
+/**
+ * Custom directive (user-defined)
+ */
+export interface UserCustomDirective extends BaseDirective {
+    kind: 'custom';
+    /** Directive name */
+    name: string;
+    /** Parameters passed to the directive */
+    params: string[];
+    /** Content inside the directive (if hasEndTag) */
+    content?: string;
+}
+/**
+ * Union type of all directive types (discriminated union)
+ *
+ * Use the `kind` property to narrow the type:
+ *
+ * @example
+ * ```typescript
+ * function processDirective(directive: Directive) {
+ *   switch (directive.kind) {
+ *     case 'conditional':
+ *       // TypeScript knows directive is ConditionalDirective here
+ *       if (directive.type === 'if') {
+ *         console.log(directive.condition)
+ *       }
+ *       break
+ *     case 'loop':
+ *       // TypeScript knows directive is LoopDirective here
+ *       console.log(directive.expression)
+ *       break
+ *     // ... other cases
+ *   }
+ * }
+ * ```
+ */
+export type Directive = ConditionalDirective | LoopDirective | IncludeDirective | LayoutDirective | ComponentDirective | AuthDirective | FormDirective | StackDirective | ExpressionDirective | SwitchDirective | SeoDirective | A11yDirective | ScriptDirective | EnvDirective | I18nDirective | UserCustomDirective;
+/**
+ * Type guard to check if a directive is a specific kind
+ */
+export declare function isDirectiveKind<K extends Directive['kind']>(directive: Directive, kind: K): directive is Extract<Directive, {
+    kind: K;
+}>;
+/**
+ * Helper type to extract directive by kind
+ */
+export type DirectiveOfKind<K extends Directive['kind']> = Extract<Directive, {
+    kind: K;
+}>;
+/**
+ * Custom directive handler function
+ */
+export type CustomDirectiveHandler = (content: string, params: string[], context: Record<string, unknown>, filePath: string) => string | Promise<string>;
+/**
+ * Custom directive definition
+ */
+export interface CustomDirective {
+    /** The name of the directive without the @ symbol (e.g., 'uppercase') */
+    name: string;
+    /** Handler function for the directive */
+    handler: CustomDirectiveHandler;
+    /** Whether the directive has a closing tag (e.g., @directive...@enddirective) */
+    hasEndTag?: boolean;
+    /** Optional description for documentation */
+    description?: string;
+}
+/**
+ * Middleware handler function
+ */
+export type MiddlewareHandler = (template: string, context: Record<string, unknown>, filePath: string, options: import('./config-types').StxOptions) => string | Promise<string>;
+/**
+ * Middleware definition
+ */
+export interface Middleware {
+    /** Unique name for the middleware */
+    name: string;
+    /** Handler function for the middleware */
+    handler: MiddlewareHandler;
+    /** When to run this middleware (before or after directive processing) */
+    timing: 'before' | 'after';
+    /** Optional description for documentation */
+    description?: string;
+}
+export {};

package/dist/types/directive-types.js

@@ -0,0 +1,3 @@
+export function isDirectiveKind(directive, kind) {
+  return directive.kind === kind;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * stx Types
+ *
+ * This file re-exports all types from domain-specific type files.
+ * For new code, prefer importing from specific type files for better code organization.
+ *
+ * @example
+ * // Import from specific file (preferred)
+ * import type { StxConfig } from './types/config-types'
+ *
+ * // Or import from index (backward compatible)
+ * import type { StxConfig } from './types'
+ */
+export type { AuthContext, BaseTemplateContext, ContextValue, LoopContext, PermissionsContext, RequireContextKeys, TemplateContext, TranslationContext, TypedContext, } from './context-types';
+export type { A11yDirective, AuthDirective, ComponentDirective, ConditionalDirective, CustomDirective, CustomDirectiveHandler, Directive, DirectiveOfKind, EnvDirective, ExpressionDirective, FormDirective, I18nDirective, IncludeDirective, LayoutDirective, LoopDirective, Middleware, MiddlewareHandler, ScriptDirective, SeoDirective, StackDirective, SwitchDirective, UserCustomDirective, } from './directive-types';
+export { isDirectiveKind } from './directive-types';
+export type { ComponentLibraryBuildResult, ComponentLibraryComponent, ComponentLibraryConfig, ComponentLibraryEvent, ComponentLibraryProperty, ComponentConfig, ComponentDefinition, ComponentDoc, ComponentPropDoc, ComponentPropsSchema, DirectiveDoc, DocFormat, DocGeneratorConfig, PropDefinition, PropType, TemplateDoc, WebComponent, WebComponentConfig, } from './component-types';
+export type { A11yConfig, AnalyticsConfig, AnalyticsDriver, AnimationConfig, FormConfig, HydrationConfig, I18nConfig, Island, LoopConfig, MarkdownConfig, OpenGraphConfig, SeoConfig, SeoFeatureConfig, StreamingConfig, StreamRenderer, StrictModeConfig, StxConfig, StxOptions, SyntaxHighlightingConfig, SyntaxHighlightTheme, TwitterConfig, } from './config-types';
+export type { PwaBackgroundSyncConfig, PwaCacheStorageConfig, PwaCacheStrategy, PwaConfig, PwaFileHandlerConfig, PwaIconConfig, PwaManifestConfig, PwaOfflineConfig, PwaPrecacheConfig, PwaProtocolHandlerConfig, PwaPushConfig, PwaRouteCache, PwaScreenshot, PwaServiceWorkerConfig, PwaShareTargetConfig, PwaShortcut, PwaUpdateConfig, } from './pwa-types';
+export type { CspConfig, CspDirectives, CspPreset, CspSourceValue, } from './csp-types';

package/dist/types/index.js

@@ -0,0 +1 @@
+export { isDirectiveKind } from "./directive-types.js";