@statorjs/stator 1.0.0

package/src/template/parser.ts

@@ -0,0 +1,341 @@
+import { allocElementId, type ElementId, type RenderState } from '../server/render-context.ts'
+
+type Mode =
+  | 'text'
+  | 'after_lt'
+  | 'tag_name'
+  | 'in_tag'
+  | 'attr_name'
+  | 'attr_after_eq'
+  | 'attr_value_dq'
+  | 'attr_value_sq'
+  | 'closing_tag'
+
+export type ValuePosition =
+  | { kind: 'text' }
+  | {
+      kind: 'attr-value'
+      attrName: string
+      elementId: ElementId
+      /** True if the static template literal had any non-whitespace content
+       *  in this attribute value before the interpolation. Used to enforce
+       *  the one-source-per-attribute rule. */
+      hasLiteralText: boolean
+    }
+  | { kind: 'directive'; elementId: ElementId }
+  | { kind: 'invalid'; reason: string }
+
+/**
+ * Streaming HTML builder. Consume static template strings via pushStatic, then
+ * call positionForValue between strings to learn where an interpolation will land.
+ * For directive / attr-value positions, the parser will assign a data-stator-id
+ * to the parent element on demand via ensureCurrentElementId / addAttribute.
+ */
+export class HtmlBuilder {
+  private chunks: string[] = []
+  private mode: Mode = 'text'
+
+  // Position in chunks where additional attributes for the current open tag
+  // should be spliced in. Null when not inside a tag-open.
+  private tagOpenInsertIdx: number | null = null
+  private currentElementId: ElementId | null = null
+
+  // The attribute name currently being built or just completed.
+  private attrNameBuf = ''
+
+  // Whether the current attribute value has any non-whitespace literal text.
+  // Reset when an attribute value starts (opening quote) and consulted at
+  // interpolation time to enforce the one-source-per-attribute rule.
+  private attrValueLiteralHasText = false
+
+  // Chunk index where the current attribute's first name character sits —
+  // the start of the splice range for whole-attribute omission (boolean
+  // attributes bound to a falsy read). Null outside attr parsing.
+  private attrStartIdx: number | null = null
+  // Set by omitCurrentAttribute(); consumed at the closing quote.
+  private omitPending = false
+
+  constructor(private readonly state: RenderState) {}
+
+  pushStatic(s: string): void {
+    for (let i = 0; i < s.length; i++) {
+      this.consume(s[i]!)
+    }
+  }
+
+  /** Append raw HTML at the current position (text content only). */
+  pushRaw(s: string): void {
+    if (this.mode !== 'text' && this.mode !== 'attr_value_dq' && this.mode !== 'attr_value_sq') {
+      throw new Error(`stator: cannot insert content at this position (parser mode: ${this.mode})`)
+    }
+    this.chunks.push(s)
+  }
+
+  /** Classify the next interpolation's position based on current parser state. */
+  positionForValue(): ValuePosition {
+    if (this.mode === 'text') return { kind: 'text' }
+    if (this.mode === 'attr_value_dq' || this.mode === 'attr_value_sq') {
+      const elementId = this.ensureCurrentElementId()
+      return {
+        kind: 'attr-value',
+        attrName: this.attrNameBuf,
+        elementId,
+        hasLiteralText: this.attrValueLiteralHasText,
+      }
+    }
+    if (this.mode === 'in_tag' || this.mode === 'tag_name') {
+      const elementId = this.ensureCurrentElementId()
+      return { kind: 'directive', elementId }
+    }
+    if (this.mode === 'attr_name') {
+      return {
+        kind: 'invalid',
+        reason: 'cannot interpolate inside an attribute name; use a directive instead',
+      }
+    }
+    if (this.mode === 'attr_after_eq') {
+      return {
+        kind: 'invalid',
+        reason: 'unquoted attribute values are not supported; wrap the value in quotes',
+      }
+    }
+    return { kind: 'invalid', reason: `unexpected parser state: ${this.mode}` }
+  }
+
+  /**
+   * Add an attribute to the current open tag.
+   * Throws if not currently inside a tag-open.
+   */
+  addAttribute(name: string, value: string): ElementId {
+    if (this.tagOpenInsertIdx === null) {
+      throw new Error('stator: addAttribute called outside of an open tag')
+    }
+    const id = this.ensureCurrentElementId()
+    this.chunks.splice(this.tagOpenInsertIdx, 0, ` ${name}="${escapeAttribute(value)}"`)
+    this.tagOpenInsertIdx += 1
+    if (this.attrStartIdx !== null) this.attrStartIdx += 1
+    return id
+  }
+
+  /**
+   * Drop the attribute currently being parsed from the output — the whole
+   * `name="value"` span — once its closing quote arrives. This is how a
+   * boolean attribute bound to a falsy read() renders as ABSENT: by the time
+   * the value is known, `name="` is already in the chunk stream, so omission
+   * is a retroactive splice.
+   */
+  omitCurrentAttribute(): void {
+    if (
+      (this.mode !== 'attr_value_dq' && this.mode !== 'attr_value_sq') ||
+      this.attrStartIdx === null
+    ) {
+      throw new Error('stator: omitCurrentAttribute called outside an attribute value')
+    }
+    this.omitPending = true
+  }
+
+  /**
+   * Ensure the current open tag has a data-stator-id and return it.
+   * Throws if not currently inside a tag-open.
+   */
+  ensureCurrentElementId(): ElementId {
+    if (this.tagOpenInsertIdx === null) {
+      throw new Error('stator: ensureCurrentElementId called outside of an open tag')
+    }
+    if (!this.currentElementId) {
+      this.currentElementId = allocElementId(this.state)
+      this.chunks.splice(this.tagOpenInsertIdx, 0, ` data-stator-id="${this.currentElementId}"`)
+      this.tagOpenInsertIdx += 1
+      if (this.attrStartIdx !== null) this.attrStartIdx += 1
+    }
+    return this.currentElementId
+  }
+
+  toString(): string {
+    return this.chunks.join('')
+  }
+
+  private consume(c: string): void {
+    switch (this.mode) {
+      case 'text':
+        this.chunks.push(c)
+        if (c === '<') this.mode = 'after_lt'
+        return
+
+      case 'after_lt':
+        this.chunks.push(c)
+        if (c === '/') {
+          this.mode = 'closing_tag'
+        } else if (isAlpha(c)) {
+          this.mode = 'tag_name'
+        } else {
+          this.mode = 'text'
+        }
+        return
+
+      case 'tag_name':
+        if (isAlphaNum(c) || c === '-') {
+          this.chunks.push(c)
+          return
+        }
+        // tag name ends — record splice position before consuming this char
+        this.tagOpenInsertIdx = this.chunks.length
+        this.currentElementId = null
+        this.mode = 'in_tag'
+        this.handleInTag(c)
+        return
+
+      case 'in_tag':
+        this.handleInTag(c)
+        return
+
+      case 'attr_name':
+        if (isAlphaNum(c) || c === '-' || c === '_' || c === ':') {
+          this.attrNameBuf += c
+          this.chunks.push(c)
+          return
+        }
+        if (c === '=') {
+          this.chunks.push(c)
+          this.mode = 'attr_after_eq'
+          return
+        }
+        // attr name ended without '=' — boolean attribute or end of tag
+        if (c === '>') {
+          this.chunks.push(c)
+          this.tagOpenInsertIdx = null
+          this.currentElementId = null
+          this.attrNameBuf = ''
+          this.mode = 'text'
+          return
+        }
+        this.chunks.push(c)
+        this.attrNameBuf = ''
+        this.mode = 'in_tag'
+        return
+
+      case 'attr_after_eq':
+        if (c === '"') {
+          this.chunks.push(c)
+          this.attrValueLiteralHasText = false
+          this.mode = 'attr_value_dq'
+          return
+        }
+        if (c === "'") {
+          this.chunks.push(c)
+          this.attrValueLiteralHasText = false
+          this.mode = 'attr_value_sq'
+          return
+        }
+        // Unquoted attribute value — POC requires quotes, but be lenient on whitespace/>.
+        if (c === '>' || isWhitespace(c)) {
+          this.chunks.push(c)
+          this.attrNameBuf = ''
+          if (c === '>') {
+            this.tagOpenInsertIdx = null
+            this.currentElementId = null
+            this.mode = 'text'
+          } else {
+            this.mode = 'in_tag'
+          }
+          return
+        }
+        // tolerate but treat as in_tag
+        this.chunks.push(c)
+        this.mode = 'in_tag'
+        return
+
+      case 'attr_value_dq':
+        if (c === '"' && this.omitPending) {
+          this.spliceOutCurrentAttribute()
+          return
+        }
+        this.chunks.push(c)
+        if (c === '"') {
+          this.attrNameBuf = ''
+          this.attrStartIdx = null
+          this.mode = 'in_tag'
+        } else if (!isWhitespace(c)) {
+          this.attrValueLiteralHasText = true
+        }
+        return
+
+      case 'attr_value_sq':
+        if (c === "'" && this.omitPending) {
+          this.spliceOutCurrentAttribute()
+          return
+        }
+        this.chunks.push(c)
+        if (c === "'") {
+          this.attrNameBuf = ''
+          this.attrStartIdx = null
+          this.mode = 'in_tag'
+        } else if (!isWhitespace(c)) {
+          this.attrValueLiteralHasText = true
+        }
+        return
+
+      case 'closing_tag':
+        this.chunks.push(c)
+        if (c === '>') this.mode = 'text'
+        return
+    }
+  }
+
+  private handleInTag(c: string): void {
+    if (c === '>') {
+      this.chunks.push(c)
+      this.tagOpenInsertIdx = null
+      this.currentElementId = null
+      this.attrNameBuf = ''
+      this.attrStartIdx = null
+      this.mode = 'text'
+      return
+    }
+    if (isWhitespace(c) || c === '/') {
+      this.chunks.push(c)
+      return
+    }
+    if (isAlpha(c) || c === '_' || c === ':' || c === '@') {
+      this.attrNameBuf = c
+      this.attrStartIdx = this.chunks.length
+      this.chunks.push(c)
+      this.mode = 'attr_name'
+      return
+    }
+    this.chunks.push(c)
+  }
+
+  /** Remove chunks from the current attribute's start through now, plus the
+   *  preceding whitespace separator if present. */
+  private spliceOutCurrentAttribute(): void {
+    const start = this.attrStartIdx!
+    this.chunks.splice(start, this.chunks.length - start)
+    this.omitPending = false
+    this.attrNameBuf = ''
+    this.attrStartIdx = null
+    this.mode = 'in_tag'
+  }
+}
+
+function isAlpha(c: string): boolean {
+  return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')
+}
+function isAlphaNum(c: string): boolean {
+  return isAlpha(c) || (c >= '0' && c <= '9')
+}
+function isWhitespace(c: string): boolean {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f'
+}
+
+export function escapeText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+export function escapeAttribute(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}

package/src/template/read.ts

@@ -0,0 +1,50 @@
+import type { AnyMachineDef } from '../server/define-machine.ts'
+import { defForProxy } from '../server/instance-proxy.ts'
+import {
+  allocSlotId,
+  type ErasedSelector,
+  requireCurrentRenderState,
+  type SlotId,
+} from '../server/render-context.ts'
+import type { InstanceOf } from './types.ts'
+
+export interface ReadResult<T = unknown> {
+  readonly __isReadResult: true
+  slotId: SlotId
+  machineName: string
+  selector: ErasedSelector
+  /** The machine proxy this read was bound against. Re-evaluating
+   *  `selector(instance)` always returns fresh state because the proxy
+   *  reads through `actor.getSnapshot()` on every access. */
+  instance: unknown
+  value: T
+}
+
+export function isReadResult(v: unknown): v is ReadResult {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isReadResult === true
+  )
+}
+
+export function read<TDef extends AnyMachineDef, TResult>(
+  instance: InstanceOf<TDef>,
+  selector: (instance: InstanceOf<TDef>) => TResult,
+): ReadResult<TResult> {
+  const state = requireCurrentRenderState()
+  const def = defForProxy(instance as unknown as object)
+  if (!def) {
+    throw new Error(
+      'stator: read() must be called with a machine instance produced by the framework',
+    )
+  }
+  const slotId = allocSlotId(state)
+  const value = selector(instance)
+  return {
+    __isReadResult: true,
+    slotId,
+    machineName: def.name,
+    selector: selector as ErasedSelector,
+    instance,
+    value: value as TResult,
+  }
+}

package/src/template/types.ts

@@ -0,0 +1,33 @@
+import type { AnyMachineDef, InstanceOf as SelectorsOf } from '../engine/index.ts'
+import type { EventDescriptor } from '../server/render-context.ts'
+
+/**
+ * The template-facing shape of a machine instance: the engine's selector view
+ * (each selector as a property carrying its return type, callable if it returns
+ * a function) plus the framework-provided `send` / `state` / `snapshot`.
+ */
+export type InstanceOf<TDef extends AnyMachineDef> = SelectorsOf<TDef> & InstanceCommon
+
+export interface InstanceCommon<TStateKey extends string = string> {
+  send(event: { type: string; [k: string]: unknown }): EventDescriptor | undefined
+  readonly state: TStateKey
+  readonly snapshot: unknown
+}
+
+/**
+ * Opaque marker for rendered HTML chunks. Produced by the `html` tag.
+ */
+export interface HtmlFragment {
+  readonly __isHtmlFragment: true
+  readonly html: string
+}
+
+export function createHtmlFragment(html: string): HtmlFragment {
+  return { __isHtmlFragment: true, html }
+}
+
+export function isHtmlFragment(v: unknown): v is HtmlFragment {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isHtmlFragment === true
+  )
+}

package/src/vite/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Vite integration for `.stator` single-file components.
+ * `import { stator } from '@statorjs/stator/vite'` and add it to `plugins`.
+ */
+export { stator } from './plugin.ts'
+export { machineStub } from './stub.ts'

package/src/vite/plugin.ts

@@ -0,0 +1,151 @@
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { transform } from 'esbuild'
+import type { Plugin } from 'vite'
+import {
+  CompileError,
+  type CompileResult,
+  compile,
+  componentImportSpecifier,
+  declaredRegions,
+  splitStator,
+} from '../compiler/index.ts'
+
+/** Build a region resolver for a file: maps a component identifier used in
+ *  `file` to the named regions its imported `.stator` declares. Reads sibling
+ *  files synchronously (resolution happens mid-compile). Returns null when the
+ *  identifier isn't a `.stator` default import or the file can't be read. */
+function regionResolverFor(file: string, source: string) {
+  const { frontmatter } = splitStator(source)
+  return (componentName: string): Set<string> | null => {
+    const spec = componentImportSpecifier(frontmatter, componentName)
+    if (!spec) return null
+    const target = spec.startsWith('.') ? resolve(dirname(file), spec) : null
+    if (!target) return null
+    try {
+      return declaredRegions(readFileSync(target, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+}
+
+/** Map a `CompileError` to a Vite/Rollup-friendly error so the dev overlay and
+ *  terminal show file:line:column with a code frame. */
+function toViteError(err: unknown): unknown {
+  if (!(err instanceof CompileError) || !err.loc) return err
+  const { file, line, column, frame } = err.loc
+  return Object.assign(new Error(err.message), {
+    id: file,
+    loc: file ? { file, line, column } : undefined,
+    frame,
+  })
+}
+
+/**
+ * The `.stator` Vite plugin — a thin adapter over the pure compiler
+ * (`@statorjs/stator/compiler`). It routes one `.stator` file to its outputs via
+ * the virtual-query pattern Astro/Svelte/Vue use:
+ *
+ *   - `Foo.stator`                          → the server render module
+ *   - `Foo.stator?stator&type=style&lang.css` → scoped CSS (Vite's CSS pipeline
+ *     claims it via the `lang.css` suffix; the server module imports it so the
+ *     CSS lands in the module graph for SSR head collection)
+ *   - `Foo.stator?stator&type=client`        → the client `<script>` entry (3b)
+ *
+ * The plugin does no CSS or JSX parsing itself — that's all in the compiler.
+ */
+
+const STYLE_QUERY = 'stator&type=style&lang.css'
+const CLIENT_QUERY = 'stator&type=client'
+
+export function stator(): Plugin {
+  const cache = new Map<string, CompileResult>()
+
+  async function compileFile(file: string): Promise<CompileResult> {
+    const cached = cache.get(file)
+    if (cached) return cached
+    const source = await readFile(file, 'utf8')
+    // routes/*.stator are route pages; everything else is a component.
+    const kind = /[\\/]routes[\\/].*\.stator$/.test(file) ? 'route' : 'component'
+    let result: CompileResult
+    try {
+      result = compile(source, {
+        id: file,
+        kind,
+        resolveRegions: regionResolverFor(file, source),
+      })
+    } catch (err) {
+      throw toViteError(err)
+    }
+    cache.set(file, result)
+    return result
+  }
+
+  return {
+    name: 'vite-plugin-stator',
+
+    resolveId(id, importer) {
+      if (!id.includes('.stator')) return null
+      const qIdx = id.indexOf('?')
+      const path = qIdx === -1 ? id : id.slice(0, qIdx)
+      const query = qIdx === -1 ? '' : id.slice(qIdx)
+      if (path.startsWith('.') && importer) {
+        const dir = importer.replace(/\/[^/]*$/, '')
+        return `${dir}/${path}${query}`
+      }
+      return null
+    },
+
+    async load(id) {
+      if (!id.includes('.stator')) return null
+      const qIdx = id.indexOf('?')
+      const file = qIdx === -1 ? id : id.slice(0, qIdx)
+      const query = qIdx === -1 ? '' : id.slice(qIdx + 1)
+      const result = await compileFile(file)
+
+      if (query.includes('type=style')) {
+        return result.css
+      }
+      if (query.includes('type=client')) {
+        // The generated client entry module (StatorElement subclass + wiring).
+        // It's TS (the author's <script> may have annotations) → strip types.
+        if (!result.isClient) return 'export {}'
+        const transformed = await transform(result.clientCode, {
+          loader: 'ts',
+          format: 'esm',
+          sourcefile: file,
+          sourcemap: true,
+        })
+        return { code: transformed.code, map: transformed.map }
+      }
+
+      // Default: the server render module. Import the style virtual (if any) so
+      // the scoped CSS participates in the module graph — the dev server walks
+      // the graph after render to inject component CSS into <head>.
+      const moduleSource = result.css
+        ? `import ${JSON.stringify(`${file}?${STYLE_QUERY}`)}\n${result.serverCode}`
+        : result.serverCode
+
+      // The emitted module is TypeScript (type-only imports, prop annotations);
+      // Vite won't run its TS transform on a `.stator` id, so strip types here.
+      const transformed = await transform(moduleSource, {
+        loader: 'ts',
+        format: 'esm',
+        sourcefile: file,
+        sourcemap: true,
+      })
+      return { code: transformed.code, map: transformed.map }
+    },
+
+    handleHotUpdate(ctx) {
+      if (!ctx.file.endsWith('.stator')) return
+      cache.delete(ctx.file)
+      const affected = ['', `?${STYLE_QUERY}`, `?${CLIENT_QUERY}`]
+        .map((q) => ctx.server.moduleGraph.getModuleById(ctx.file + q))
+        .filter((m): m is NonNullable<typeof m> => Boolean(m))
+      return affected.length > 0 ? affected : undefined
+    },
+  }
+}

package/src/vite/stub.ts

@@ -0,0 +1,79 @@
+import { dirname, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Plugin } from 'vite'
+
+/**
+ * Identity-import stubbing: in a *browser* module graph, an import of a server
+ * machine resolves to a stub carrying only `{ name }` — the one field client
+ * dispatch needs (`dispatch(Cart, ev)` posts `machine.name` over the wire).
+ * The machine's real module (actions, guards, whatever server-only code it
+ * pulls in) never ships to the client.
+ *
+ * Scoping is environment-based, not syntax-based: SSR resolutions pass
+ * through untouched (the server needs the real machine), and only ids that
+ * resolve inside `machinesDir` are stubbed. Applied in two places:
+ *   - the dev server's Vite instance (browser requests for island imports)
+ *   - the production client build in `buildApp`
+ *
+ * The stub's name is read by importing the machine module in Node at
+ * build/serve time (machine defs are side-effect-free by convention — boot
+ * discovery already imports them all).
+ */
+
+const STUB_PREFIX = '\0stator-machine-stub:'
+
+export function machineStub(opts: { machinesDir: string }): Plugin {
+  const machinesDir = resolve(opts.machinesDir)
+  const inMachinesDir = (abs: string): boolean =>
+    abs === machinesDir || abs.startsWith(machinesDir + sep)
+
+  let root = ''
+
+  return {
+    name: 'vite-plugin-stator-machine-stub',
+    enforce: 'pre',
+
+    configResolved(config) {
+      root = config.root
+    },
+
+    resolveId(id, importer, options) {
+      if (options.ssr) return null
+      if (id.startsWith(STUB_PREFIX)) return id
+      if (!id.startsWith('.') && !id.startsWith('/')) return null
+      const importerPath = importer?.split('?')[0]
+      // A `/`-prefixed id may be a filesystem path (build inputs) or a
+      // vite-root-relative browser URL (dev import analysis) — try both.
+      const candidates = id.startsWith('.')
+        ? importerPath
+          ? [resolve(dirname(importerPath), id)]
+          : []
+        : [resolve(id), ...(root ? [resolve(root, id.slice(1))] : [])]
+      const abs = candidates.find(inMachinesDir)
+      if (!abs) return null
+      return STUB_PREFIX + abs
+    },
+
+    async load(id) {
+      if (!id.startsWith(STUB_PREFIX)) return null
+      const file = id.slice(STUB_PREFIX.length)
+      let name: unknown
+      try {
+        const mod = (await import(pathToFileURL(file).href)) as { default?: { name?: unknown } }
+        name = mod.default?.name
+      } catch (err) {
+        throw new Error(
+          `stator: cannot stub server-machine import "${file}" for the client bundle — ` +
+            `importing it in Node failed: ${(err as Error).message}`,
+        )
+      }
+      if (typeof name !== 'string') {
+        throw new Error(
+          `stator: cannot stub "${file}" — it does not default-export a machine with a name. ` +
+            `Only machine defs may be imported from the machines directory in client code.`,
+        )
+      }
+      return `export default { name: ${JSON.stringify(name)} }\n`
+    },
+  }
+}