@tsrx/core 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,249 @@
+# @tsrx/core
+
+**TypeScript Ripple Extensions (TSRX)** — the shared parser and compiler
+infrastructure that powers TypeScript UI frameworks.
+
+`@tsrx/core` is framework-agnostic. It provides the parser, AST definitions, scope
+analysis, and code-generation utilities needed to target _any_ framework runtime
+using Ripple's syntax. Framework-specific packages (such as
+[`@tsrx/ripple`](../tsrx-ripple)) build on top of `@tsrx/core` to produce the
+runtime output for Ripple.
+
+## What is TSRX?
+
+TSRX is an extension to TypeScript's syntax — in the same spirit that JSX is an
+extension to JavaScript. It adds a small set of orthogonal syntactic forms that
+are ergonomic for describing reactive UI, and leaves the semantics of those forms
+to the consuming framework.
+
+A `.tsrx` file is a TypeScript module with TSRX enabled.
+
+## Installation
+
+```bash
+pnpm add @tsrx/core
+```
+
+## Usage
+
+```js
+import { parseModule } from '@tsrx/core';
+
+const ast = parseModule(source, 'App.tsrx');
+```
+
+The parser produces an ESTree-compatible AST, augmented with the TSRX node types
+listed below. Framework compilers walk this AST to emit their own output.
+
+## TSRX Specification (draft)
+
+TSRX is a superset of TypeScript. All valid TypeScript is valid TSRX. TSRX adds
+the following productions.
+
+### 1. `component` declarations
+
+A `component` is a new top-level and expression-level declaration form. It has the
+same shape as a function declaration, but is a distinct AST node (`Component`) so
+that framework compilers can treat it specially.
+
+```tsx
+component Button(props: Props) {
+  <button>{props.label}</button>
+}
+```
+
+- `component` may be used wherever `function` may be used (declaration,
+  expression, default export).
+- The body of a `component` may contain JSX-like elements as statements — see §3.
+- `component` is a contextual keyword. Use as an identifier is preserved in
+  non-declaration positions.
+
+### 2. JSX-as-statements
+
+Inside a `component` body, JSX elements are valid _statement_ forms. They describe
+rendered output and are not expressions — they have no value.
+
+```tsx
+component Greeting() {
+  <h1>{'Hello'}</h1>
+  <p>{'Welcome'}</p>
+}
+```
+
+Elsewhere (outside a `component` body), JSX remains an expression, as in standard
+JSX.
+
+### 4. Control-flow statements in `component` bodies
+
+Inside a `component` body, the standard JavaScript control-flow keywords `if`,
+`else`, `for`, `switch`, and `try` gain an additional role: their branches may
+contain JSX-as-statements (§2) describing conditionally- or repeatedly-rendered
+output. The keywords retain their usual JavaScript syntax — no new grammar is
+introduced — but framework compilers treat them as _reactive_ boundaries.
+
+```tsx
+component List(props: { items: Item[]; showHeader: boolean }) {
+  if (props.showHeader) {
+    <h1>{'Items'}</h1>
+  } else {
+    <h2>{'(no header)'}</h2>
+  }
+
+  for (const item of props.items) {
+    <li>{item.name}</li>
+  }
+
+  switch (props.items.length) {
+    case 0:
+      <p>{'empty'}</p>
+      break;
+    default:
+      <p>{'has items'}</p>
+  }
+
+  try {
+    <AsyncThing />
+  } catch (e) {
+    <pre>{String(e)}</pre>
+  }
+}
+```
+
+**Early returns.** A bare `return;` (or `return` at the end of a branch) is a
+valid statement inside a `component` body and short-circuits any remaining
+rendering in the current branch. This composes naturally with the control-flow
+forms above:
+
+```tsx
+component Page(props: { user: User | null }) {
+  if (props.user == null) {
+    <LoginPrompt />
+    return;
+  }
+
+  <Dashboard user={props.user} />
+}
+```
+
+Because a `component` body does not produce a value, `return` never carries an
+expression — it only marks a rendering short-circuit.
+
+**Nesting inside elements.** Control-flow statements may appear directly as
+children of a JSX element, not only at the top level of the component body. Their
+branches contribute children to the enclosing element in source order:
+
+```tsx
+component Menu(props: { items: Item[]; loading: boolean }) {
+  <ul>
+    if (props.loading) {
+      <li>{'loading…'}</li>
+    } else {
+      for (const item of props.items) {
+        <li>
+          <a href={item.href}>{item.label}</a>
+          if (item.badge) {
+            <span class="badge">{item.badge}</span>
+          }
+        </li>
+      }
+    }
+  </ul>
+}
+```
+
+Any control-flow form that is legal at the component-body level is also legal as a
+child of a JSX element, and may be nested to arbitrary depth.
+
+TSRX only describes what is syntactically permitted. The reactive semantics
+(dependency tracking, list reconciliation, error boundaries, suspense) are the
+responsibility of the framework compiler.
+
+### 5. JSX escape hatch: `<tsx>...</tsx>`
+
+Because JSX inside a `component` body is a _statement_ (§2), the element itself
+has no value. To embed regular _expression_-form JSX — e.g. when a third-party
+library accepts a JSX tree as a value — wrap it in the reserved `<tsx>` element.
+Its children are parsed as standard JSX expressions and the whole form evaluates
+to the JSX expression value (or an array of values if there are multiple
+children).
+
+```tsx
+component Page() {
+  const header = <tsx><h1>{'Hello'}</h1></tsx>;
+  renderSomewhereElse(header);
+}
+```
+
+`<tsx>` is a reserved tag name in TSRX. It has no runtime representation of its
+own — the framework compiler unwraps it into the underlying JSX expression.
+
+### 6. Lazy destructuring: `&[]` and `&{}`
+
+Two new destructuring forms prefixed with `&` bind by _reference_ rather than by
+value. Each bound name compiles to a lazy property lookup on the source, so reads
+and writes are deferred to the use-site.
+
+```tsx
+let &[count] = source;        // array-style lazy destructure
+let &{ name, age } = props;   // object-style lazy destructure
+```
+
+Semantics are provided by the framework compiler. TSRX only defines the syntax and
+the AST shape (`kind: 'lazy'` binding patterns).
+
+### 7. `#server` blocks
+
+A `#server { ... }` block marks a lexical region whose contents are intended for
+the server compile target. TSRX parses the block and records its exports;
+framework compilers decide how to emit or strip it per target.
+
+```ts
+#server {
+  export async function load() { /* ... */ }
+}
+```
+
+### 8. `#style` identifier
+
+`#style` is a reserved identifier that refers, at compile time, to the set of
+scoped CSS classes declared in the current module. It is legal only in positions
+where the framework compiler expects a class-name value.
+
+```tsx
+<div class={#style.card} />
+```
+
+### 9. Scoped CSS blocks
+
+A `component` may contain a trailing CSS block (delimited by the framework
+compiler's chosen grammar). The block is parsed into a `CSS.StyleSheet` AST node
+and hashed for scoping.
+
+## What `@tsrx/core` provides
+
+- **`parseModule(source, filename, options?)`** — parse a TSRX module into an
+  ESTree AST.
+- **Scope analysis** — `createScopes`, `Scope`, `ScopeRoot`, binding tracking
+  (`import`, `prop`, `let`, `const`, `function`, `component`, `for_pattern`, …).
+- **AST utilities** — pattern walkers, identifier extraction, builders, location
+  helpers, obfuscation helpers.
+- **CSS support** — `parseStyle`, `analyzeCss`, `renderStylesheets`.
+- **HTML helpers** — `isVoidElement`, `isBooleanAttribute`, `isDomProperty`,
+  `validateNesting`.
+- **Event helpers** — delegated-event utilities, event-name normalization.
+- **Source maps** — `convertSourceMapToMappings`.
+
+See `src/index.js` for the full exported surface.
+
+## Non-goals
+
+- `@tsrx/core` does **not** emit runtime code. Code generation lives in framework
+  packages (e.g. `@tsrx/ripple`).
+- `@tsrx/core` does **not** ship a runtime. There is no reactivity, rendering, or
+  DOM code here.
+- `@tsrx/core` does **not** lock consumers to a specific output format. Multiple
+  compile targets can share the same parser and analysis.
+
+## License
+
+MIT © Dominic Gannaway

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@tsrx/core",
-  "description": "Core compiler infrastructure for tsrx-based frameworks",
+  "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
   },
   "exports": {
     ".": {
+      "types": "./src/index.js",
       "default": "./src/index.js"
     },
     "./types": {

package/src/index.js

@@ -1,14 +1,15 @@
 /**
  * @tsrx/core - Core compiler infrastructure for tsrx-based frameworks
  *
- * Re-exports key modules for convenience.
+ * Public API surface uses camelCase. Internal modules retain snake_case per
+ * the project's code conventions; the exports below alias them at the boundary.
  */
 
 // Parse
+export { parse_module as parseModule } from './parse/parse-module.js';
 export {
-	createParser,
-	get_comment_handlers,
-	convert_from_jsx,
+	get_comment_handlers as getCommentHandlers,
+	convert_from_jsx as convertFromJsx,
 	skipWhitespace,
 	isWhitespaceTextNode,
 	BINDING_TYPES,
@@ -16,10 +17,10 @@ export {
 	acorn,
 	tsPlugin,
 } from './parse/index.js';
-export { parse_style } from './parse/style.js';
+export { parse_style as parseStyle } from './parse/style.js';
 
 // Scope
-export { create_scopes, ScopeRoot, Scope } from './scope.js';
+export { create_scopes as createScopes, ScopeRoot, Scope } from './scope.js';
 
 // Errors
 export { error } from './errors.js';
@@ -51,91 +52,92 @@ export {
 	STYLE_IDENTIFIER,
 	SERVER_IDENTIFIER,
 	CSS_HASH_IDENTIFIER,
-	obfuscate_identifier,
-	is_identifier_obfuscated,
-	deobfuscate_identifier,
+	obfuscate_identifier as obfuscateIdentifier,
+	is_identifier_obfuscated as isIdentifierObfuscated,
+	deobfuscate_identifier as deobfuscateIdentifier,
 } from './identifier-utils.js';
 
 // Comment utils
 export {
-	is_ts_pragma,
-	is_triple_slash_directive,
-	is_jsdoc_ts_annotation,
-	should_preserve_comment,
-	format_comment,
+	is_ts_pragma as isTsPragma,
+	is_triple_slash_directive as isTripleSlashDirective,
+	is_jsdoc_ts_annotation as isJsdocTsAnnotation,
+	should_preserve_comment as shouldPreserveComment,
+	format_comment as formatComment,
 } from './comment-utils.js';
 
 // Generic utils
 export {
 	hash,
-	is_void_element,
-	is_reserved,
-	is_boolean_attribute,
-	is_dom_property,
+	is_void_element as isVoidElement,
+	is_reserved as isReserved,
+	is_boolean_attribute as isBooleanAttribute,
+	is_dom_property as isDomProperty,
 } from './utils.js';
 
 // AST utils
 export {
 	object,
-	unwrap_pattern,
-	extract_identifiers,
-	extract_paths,
-	build_fallback,
-	build_assignment_value,
+	unwrap_pattern as unwrapPattern,
+	extract_identifiers as extractIdentifiers,
+	extract_paths as extractPaths,
+	build_fallback as buildFallback,
+	build_assignment_value as buildAssignmentValue,
 } from './utils/ast.js';
 
-// Builders (namespace re-export)
+// Builders (namespace re-export — members mirror AST node kinds)
 export * as builders from './utils/builders.js';
 
 // Also export individual builder utilities used directly
-export { set_location } from './utils/builders.js';
+export { set_location as setLocation } from './utils/builders.js';
 
 // Event utils
 export {
-	is_non_delegated,
-	is_event_attribute,
-	is_capture_event,
-	get_original_event_name,
-	normalize_event_name,
-	event_name_from_capture,
-	get_attribute_event_name,
-	is_passive_event,
+	is_non_delegated as isNonDelegated,
+	is_event_attribute as isEventAttribute,
+	is_capture_event as isCaptureEvent,
+	get_original_event_name as getOriginalEventName,
+	normalize_event_name as normalizeEventName,
+	event_name_from_capture as eventNameFromCapture,
+	get_attribute_event_name as getAttributeEventName,
+	is_passive_event as isPassiveEvent,
 } from './utils/events.js';
 
-// Hashing (also available via utils.hash)
-// Already exported via ./utils.js
-
 // Patterns
 export {
-	regex_whitespace,
-	regex_whitespaces,
-	regex_starts_with_newline,
-	regex_starts_with_whitespace,
-	regex_starts_with_whitespaces,
-	regex_ends_with_whitespace,
-	regex_ends_with_whitespaces,
-	regex_not_whitespace,
-	regex_whitespaces_strict,
-	regex_only_whitespaces,
-	regex_newline_characters,
-	regex_not_newline_characters,
-	regex_is_valid_identifier,
-	regex_invalid_identifier_chars,
-	regex_starts_with_vowel,
-	regex_heading_tags,
-	regex_illegal_attribute_character,
+	regex_whitespace as regexWhitespace,
+	regex_whitespaces as regexWhitespaces,
+	regex_starts_with_newline as regexStartsWithNewline,
+	regex_starts_with_whitespace as regexStartsWithWhitespace,
+	regex_starts_with_whitespaces as regexStartsWithWhitespaces,
+	regex_ends_with_whitespace as regexEndsWithWhitespace,
+	regex_ends_with_whitespaces as regexEndsWithWhitespaces,
+	regex_not_whitespace as regexNotWhitespace,
+	regex_whitespaces_strict as regexWhitespacesStrict,
+	regex_only_whitespaces as regexOnlyWhitespaces,
+	regex_newline_characters as regexNewlineCharacters,
+	regex_not_newline_characters as regexNotNewlineCharacters,
+	regex_is_valid_identifier as regexIsValidIdentifier,
+	regex_invalid_identifier_chars as regexInvalidIdentifierChars,
+	regex_starts_with_vowel as regexStartsWithVowel,
+	regex_heading_tags as regexHeadingTags,
+	regex_illegal_attribute_character as regexIllegalAttributeCharacter,
 } from './utils/patterns.js';
 
 // Sanitize
-export { sanitize_template_string } from './utils/sanitize_template_string.js';
+export { sanitize_template_string as sanitizeTemplateString } from './utils/sanitize_template_string.js';
 
 // Escaping
 export { escape } from './utils/escaping.js';
 
 // Transform
-export { render_stylesheets } from './transform/stylesheet.js';
-export { convert_source_map_to_mappings } from './transform/segments.js';
+export { render_stylesheets as renderStylesheets } from './transform/stylesheet.js';
+export {
+	convert_source_map_to_mappings as convertSourceMapToMappings,
+	create_volar_mappings_result as createVolarMappingsResult,
+	create_basic_volar_mappings_result as createBasicVolarMappingsResult,
+} from './transform/segments.js';
 
 // Analyze
-export { analyze_css } from './analyze/css-analyze.js';
-export { validate_nesting } from './analyze/validation.js';
+export { analyze_css as analyzeCss } from './analyze/css-analyze.js';
+export { validate_nesting as validateNesting } from './analyze/validation.js';

package/src/parse/index.js

@@ -113,7 +113,7 @@ export function isWhitespaceTextNode(node) {
 /**
  * Create a parser by composing Acorn with TypeScript/JSX support and optional framework plugins.
  *
- * This is the core factory for building tsrx-based parsers. Framework plugins (like RipplePlugin)
+ * This is the core factory for building tsrx-based parsers. Framework plugins (like TSRXPlugin)
  * extend the base parser with framework-specific syntax.
  *
  * @param {...(AcornPlugin | Function)} plugins - Framework parser plugins to compose

package/src/parse/parse-module.js

@@ -0,0 +1,18 @@
+/** @import * as AST from 'estree' */
+/** @import { ParseOptions } from '../../types/index' */
+
+import { createParser } from './index.js';
+import { TSRXPlugin } from '../plugin.js';
+
+const parse = createParser(TSRXPlugin());
+
+/**
+ * Parse source code to an ESTree AST using the TSRX parser.
+ * @param {string} source
+ * @param {string} [filename]
+ * @param {ParseOptions} [options]
+ * @returns {AST.Program}
+ */
+export function parse_module(source, filename, options) {
+	return parse(source, filename, options);
+}