@lokascript/framework 2.0.0

package/dist/grammar/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Generalized Grammar System for Multilingual Hyperscript
+ *
+ * This system abstracts grammatical patterns across language families,
+ * enabling deep multilingual support without per-language hardcoding.
+ *
+ * Key Linguistic Concepts:
+ * - Word Order: SVO, SOV, VSO (and variations)
+ * - Adposition Type: Preposition (English) vs Postposition (Japanese/Korean)
+ * - Morphology: Isolating (Chinese) vs Agglutinative (Turkish) vs Fusional (Arabic)
+ * - Text Direction: LTR vs RTL
+ */
+/**
+ * Semantic roles in hyperscript commands.
+ * These are universal across all 13 supported languages - only the surface form changes.
+ *
+ * ## Core Thematic Roles (from linguistic theory)
+ * | Role        | Usage | Purpose                     | Example                   |
+ * |-------------|-------|-----------------------------|---------------------------|
+ * | action      | 100%  | Command verb                | toggle, put, fetch        |
+ * | patient     | 90%   | What is acted upon          | .active, #count           |
+ * | destination | 40%   | Where something goes        | into #output, to .class   |
+ * | source      | 13%   | Where something comes from  | from #input, from URL     |
+ * | event       | 106%  | Trigger events              | click, keydown, submit    |
+ * | condition   | 8%    | Boolean expressions         | if x > 5, when visible    |
+ * | agent       | 0%    | Who performs action         | Reserved for future use   |
+ * | goal        | 1%    | Target value/state          | to 'red' (in transition)  |
+ *
+ * ## Quantitative Roles (answer "how much/long")
+ * | Role     | Usage | Purpose        | Example              |
+ * |----------|-------|----------------|----------------------|
+ * | quantity | 7%    | Numeric amount | by 5, 3 times        |
+ * | duration | 1%    | Time span      | for 5 seconds, 500ms |
+ *
+ * ## Adverbial/Modifier Roles (answer "how/by what means")
+ * | Role         | Usage | Purpose                   | Example           |
+ * |--------------|-------|---------------------------|-------------------|
+ * | style        | 2%    | Animation/behavior        | with fade         |
+ * | manner       | 2%    | Insertion position        | before, after     |
+ * | method       | 1%    | HTTP method/technique     | via POST, as GET  |
+ * | responseType | 1%    | Response format           | as json, as html  |
+ *
+ * ## Control Flow Roles
+ * | Role     | Usage | Purpose      | Example               |
+ * |----------|-------|--------------|-----------------------|
+ * | loopType | 6%    | Loop variant | forever, until, times |
+ *
+ * ## Design Notes
+ * - Low-usage roles (agent, goal, method, responseType) are intentionally kept for:
+ *   - Linguistic completeness across all 13 languages
+ *   - Future extensibility (AI agents, server-side execution)
+ *   - Command-specific semantics (fetch, transition)
+ * - Each role has distinct grammatical markers per language (see profiles/index.ts)
+ * - Usage percentages based on pattern database analysis
+ */
+export type SemanticRole = 'action' | 'agent' | 'patient' | 'source' | 'destination' | 'goal' | 'event' | 'condition' | 'quantity' | 'duration' | 'responseType' | 'method' | 'style' | 'manner' | 'loopType' | 'continues';
+/**
+ * Word order patterns
+ * These represent the major typological categories
+ */
+export type WordOrder = 'SVO' | 'SOV' | 'VSO' | 'VOS' | 'OVS' | 'OSV' | 'free';
+/**
+ * Where grammatical markers appear relative to their noun/verb
+ */
+export type AdpositionType = 'preposition' | 'postposition' | 'circumposition' | 'none';
+/**
+ * Morphological typology - how words are constructed
+ */
+export type MorphologyType = 'isolating' | 'agglutinative' | 'fusional' | 'polysynthetic';
+/**
+ * A grammatical marker (particle, case ending, preposition)
+ */
+export interface GrammaticalMarker {
+    form: string;
+    role: SemanticRole;
+    position: AdpositionType;
+    required: boolean;
+    alternatives?: string[];
+}
+/**
+ * Metadata for preserving line structure during translation.
+ * Tracks indentation and blank lines so output maintains the same format.
+ */
+export interface LineMetadata {
+    /** Trimmed line content (empty string for blank lines) */
+    content: string;
+    /** Leading whitespace (tabs/spaces) from original line */
+    originalIndent: string;
+    /** True if the line was empty or whitespace-only */
+    isBlank: boolean;
+}
+/**
+ * Complete grammatical profile for a language
+ * This captures the essential typological features needed for transformation
+ */
+export interface LanguageProfile {
+    code: string;
+    name: string;
+    wordOrder: WordOrder;
+    adpositionType: AdpositionType;
+    morphology: MorphologyType;
+    direction: 'ltr' | 'rtl';
+    markers: GrammaticalMarker[];
+    canonicalOrder: SemanticRole[];
+    rules?: GrammarRule[];
+}
+/**
+ * Pattern for transforming hyperscript structures
+ */
+export interface GrammarRule {
+    name: string;
+    description: string;
+    match: PatternMatcher;
+    transform: PatternTransform;
+    priority: number;
+}
+/**
+ * Matches a hyperscript pattern
+ */
+export interface PatternMatcher {
+    commands?: string[];
+    requiredRoles: SemanticRole[];
+    optionalRoles?: SemanticRole[];
+    predicate?: (parsed: ParsedStatement) => boolean;
+}
+/**
+ * Defines how to transform a matched pattern
+ */
+export interface PatternTransform {
+    roleOrder: SemanticRole[];
+    insertMarkers?: boolean;
+    custom?: (parsed: ParsedStatement, profile: LanguageProfile) => string;
+}
+/**
+ * A parsed hyperscript statement broken into semantic components
+ */
+export interface ParsedStatement {
+    type: 'event-handler' | 'command' | 'conditional' | 'loop';
+    roles: Map<SemanticRole, ParsedElement>;
+    original: string;
+}
+/**
+ * A single element with its semantic role
+ */
+export interface ParsedElement {
+    role: SemanticRole;
+    value: string;
+    translated?: string;
+    isSelector?: boolean;
+    isLiteral?: boolean;
+}
+/**
+ * Universal templates for common hyperscript patterns
+ * These define the semantic structure independent of surface form
+ */
+export declare const UNIVERSAL_PATTERNS: {
+    readonly eventIncrement: {
+        readonly name: "event-increment";
+        readonly roles: SemanticRole[];
+        readonly english: "on {event} {action} {patient}";
+    };
+    readonly putInto: {
+        readonly name: "put-into";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {patient} into {destination}";
+    };
+    readonly addTo: {
+        readonly name: "add-to";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {patient} to {destination}";
+    };
+    readonly toggleOn: {
+        readonly name: "toggle-on";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {patient} on {destination}";
+    };
+    readonly waitDuration: {
+        readonly name: "wait-duration";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {quantity}";
+    };
+    readonly conditional: {
+        readonly name: "conditional";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {condition} then ... end";
+    };
+    readonly fetchAs: {
+        readonly name: "fetch-as";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {source} as {method}";
+    };
+    readonly showWith: {
+        readonly name: "show-with";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {patient} with {style}";
+    };
+    readonly transitionOver: {
+        readonly name: "transition-over";
+        readonly roles: SemanticRole[];
+        readonly english: "{action} {patient} over {duration}";
+    };
+};
+/**
+ * Default profiles for major language families
+ * Individual languages inherit and override these
+ */
+export declare const LANGUAGE_FAMILY_DEFAULTS: Record<string, Partial<LanguageProfile>>;
+/**
+ * Reorder semantic roles according to target language.
+ * Includes a safety net to append any roles present in input
+ * but missing from the target order, preventing data loss.
+ */
+export declare function reorderRoles(roles: Map<SemanticRole, ParsedElement>, targetOrder: SemanticRole[]): ParsedElement[];
+/**
+ * Insert grammatical markers between elements
+ */
+export declare function insertMarkers(elements: ParsedElement[], markers: GrammaticalMarker[], adpositionType: AdpositionType): string[];
+/**
+ * Intelligently joins tokens, handling agglutinative suffixes and prefixes.
+ *
+ * Rules:
+ * 1. If a token ends with '-' (prefix marker), no space after it
+ * 2. If a token starts with '-' (suffix marker), no space before it
+ * 3. Removes the hyphen indicators from the final output
+ *
+ * Examples:
+ * - ['#count', '-ta'] → '#countta' (Quechua accusative suffix)
+ * - ['بـ-', 'الماوس'] → 'بـالماوس' (Arabic prefix attachment)
+ * - ['value', 'を'] → 'value を' (Japanese particle, normal spacing)
+ */
+export declare function joinTokens(tokens: string[]): string;
+/**
+ * Transform a parsed statement to target language
+ */
+export declare function transformStatement(parsed: ParsedStatement, _sourceProfile: LanguageProfile, targetProfile: LanguageProfile): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/grammar/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/grammar/types.ts"],"names":[],"mappings":"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"}