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

package/dist/client-script.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Client Script Processor
+ *
+ * Transforms <script client> blocks in SFC (.stx) components:
+ * 1. Auto-imports from 'stx' and '@stacksjs/browser' (no import statements needed)
+ * 2. Resolves `import { store } from '@stores'` to runtime store access
+ * 3. Transpiles TypeScript to JavaScript (strips type annotations, interfaces, import type)
+ * 4. Injects event binding code (from @click, @input, etc.) into the script scope
+ * 5. Auto-wraps in a scoped IIFE for isolation
+ *
+ * This enables clean component authoring:
+ * ```stx
+ * <template>
+ *   <button @click="handleClick()">Count: {{ count() }}</button>
+ * </template>
+ *
+ * <script>
+ * // No imports needed! state, onMount, Trail, etc. are auto-imported
+ * const count = state(0)
+ *
+ * onMount(async () => {
+ *   const trails = await Trail.all()
+ *   console.log(trails)
+ * })
+ *
+ * function handleClick() {
+ *   count.set(count() + 1)
+ * }
+ * </script>
+ * ```
+ *
+ * @module client-script
+ */
+import type { ParsedEvent } from './events';
+export { findInterpolationEnd, stripCommentsAndLiterals } from './strip-literals';
+export interface VendorCssImport {
+    /** The original specifier as written in the import — kept verbatim for the data attribute. */
+    source: string;
+    /** The resolved absolute filesystem path — used for dedupe and reads. */
+    resolvedPath: string;
+    /** The CSS file contents at build time. */
+    contents: string;
+}
+/**
+ * Strip side-effect `.css` imports from a `<script client>` body and read
+ * their contents off disk.
+ *
+ * Bun.build doesn't know what to do with `import 'foo.css'` in a JS entry —
+ * it either errors or returns the original code unchanged, which leaks the
+ * unresolved import into the browser payload. So we intercept those imports
+ * before bundling, resolve them ourselves (bare specifiers via Bun's resolver,
+ * relative paths against the template's directory), and surface the file
+ * contents to the caller so they can be emitted as `<style>` tags wrapped in
+ * `@layer vendor { … }`.
+ *
+ * Missing or unresolvable files emit a single warn-level log and are left
+ * out of the result; the original import is still stripped so the bundler
+ * never sees it. The trade-off is a silent style miss vs. a broken JS bundle —
+ * the former is recoverable, the latter takes the whole component down.
+ *
+ * Dedupe is by absolute resolved path, so two components importing the same
+ * `medium-editor.css` only emit one `<style>` block per `processClientScript`
+ * call. Cross-component dedupe still relies on the caller's HTML response
+ * (CSS rules collapse harmlessly at the browser level either way).
+ */
+export declare function extractAndStripCssImports(code: string, options: {
+    filePath?: string;
+    projectRoot?: string;
+}): {
+    code: string;
+    styles: VendorCssImport[];
+    unresolved: string[];
+};
+/**
+ * Render collected vendor CSS as one `<style>` tag per resolved source,
+ * each wrapped in `@layer vendor { … }` so the styles can never out-specificity
+ * utility classes (assuming the consuming app declares the layer order in
+ * its global stylesheet, e.g. `@layer vendor, components, utilities;`).
+ *
+ * Wrapping in a layer at emit time means consumers get correct ordering even
+ * if they forget to declare the layer order — anonymous layers still rank
+ * below un-layered rules, so vendor styles default to lowest precedence.
+ */
+export declare function renderVendorStyleTags(styles: VendorCssImport[]): string;
+/**
+ * Exports from 'stx' auto-imported into classic `<script>` / `<script client>`
+ * blocks.
+ *
+ * Derived from {@link STX_RUNTIME_GLOBALS} rather than hand-maintained (#1804).
+ * This was a separate 82-name literal, and it had drifted: 16 of those names
+ * were not on `window.stx` at all. Because the generated prologue destructures
+ * (`var { … } = window.stx`), a missing name is not an error — it binds
+ * `undefined`, and the author sees "undefined is not a function" at the call
+ * site with nothing naming the identifier or saying why. `provide` worked and
+ * `inject` did not; `onMounted` worked and `onUpdated` did not.
+ *
+ * Five of the 16 (`isDerived`, `inject`, `useSlots`, `watchMultiple`,
+ * `onBeforeMount`) are now implemented in the runtime and live in the shared
+ * list. The remaining 11 are server- or compile-time only — `h` and `Fragment`
+ * belong to the JSX runtime, `useMeta`/`getCurrentInstance`/`useAttrs`/
+ * `onErrorCaptured`/`onBeforeUpdate`/`onUpdated`/`createStore`/`createSelector`
+ * are module exports with no client counterpart, and `action` has no
+ * implementation anywhere — so they are no longer offered. A `ReferenceError`
+ * naming the identifier beats a silent `undefined`.
+ */
+export declare const STX_AUTO_IMPORTS: readonly string[];
+/**
+ * Core exports from '@stacksjs/browser' that are auto-imported.
+ * App-specific models are detected dynamically (PascalCase identifiers
+ * used with query methods like .all(), .find(), .where(), etc.)
+ */
+export { BROWSER_CORE_IMPORTS } from './browser-core-imports';
+export interface BrowserCoreAutoImportResult {
+    code: string;
+    imports: string[];
+    models: string[];
+}
+/**
+ * Turn bare core browser helper usage into a real module import before the
+ * client bundler runs.
+ *
+ * Inline signal scripts execute synchronously while the document is parsed.
+ * Loading `window.StacksBrowser` from a later module script is therefore too
+ * late. A real import lets Bun inline and tree-shake the selected browser
+ * helpers together with the component, exactly like an explicit user import.
+ */
+export declare function injectBrowserCoreAutoImports(code: string): BrowserCoreAutoImportResult;
+export interface ClientScriptOptions {
+    /** Event bindings collected from template @event attributes */
+    eventBindings?: ParsedEvent[];
+    /** Whether to enable auto-imports (default: true) */
+    autoImports?: boolean;
+    /** Original script tag attributes (e.g., 'type="module"') */
+    attrs?: string;
+    /** Whether the component template contains : prefix directives */
+    hasColonDirectives?: boolean;
+    /** Template HTML content for auto-binding analysis (Phase 2: auto-detect which scripts need stx.mount()) */
+    templateContent?: string;
+    /** File path of the template (for relative import resolution in bundler) */
+    filePath?: string;
+    /** Project root directory (for @/ path resolution in bundler) */
+    projectRoot?: string;
+    /** Whether this is a production build (enables minification in bundler) */
+    production?: boolean;
+    /**
+     * Server → client data bridge. Top-level `<script server>` variables (and
+     * other template-context values) made available to `<script client>` code:
+     * any JSON-serializable value referenced — but not redeclared — by the client
+     * script is serialized into the client bundle, so reactive state can be seeded
+     * from build-time data (e.g. `const items = state(serverItems)`) without a
+     * round-trip fetch. Functions/non-serializable values are skipped.
+     */
+    serverData?: Record<string, unknown>;
+}
+interface AutoImportResult {
+    code: string;
+    stxImports: string[];
+    browserImports: string[];
+}
+/**
+ * Transform auto-imports from 'stx' and '@stacksjs/browser'
+ *
+ * This detects usage of auto-importable symbols and generates the
+ * necessary import statements if they're not already present.
+ *
+ * Users can write code without imports:
+ * ```
+ * const count = state(0)  // 'state' is auto-imported from 'stx'
+ * const trails = await Trail.all()  // 'Trail' is auto-imported from '@stacksjs/browser'
+ * ```
+ */
+export declare function transformAutoImports(code: string): AutoImportResult;
+/**
+ * Generate destructuring statements for auto-imported symbols
+ * These access globals set up by the STX runtime and @stacksjs/browser
+ */
+export declare function generateAutoImportDestructuring(stxImports: string[], browserImports: string[]): string;
+/**
+ * Generate the browser-runtime bindings needed by a signal setup wrapper.
+ *
+ * Signal pages and Vue-like signal components use specialized scoped wrappers
+ * instead of {@link processClientScript}. They already pull every STX runtime
+ * global from `window.stx`, but still need the selected Stacks browser helpers
+ * used by their script. Keeping detection here makes classic scripts, signal
+ * pages, and signal components share the same browser auto-import contract.
+ */
+export declare function generateBrowserAutoImportDestructuring(code: string, exclude?: readonly string[]): string;
+/**
+ * Build the server → client bridge payload from a template context: the
+ * top-level, JSON-serializable values (excluding internal `__`/`$` keys and
+ * functions) that a `<script client>` may seed reactive state from. Pass the
+ * result as {@link ClientScriptOptions.serverData}.
+ */
+export declare function extractBridgeData(context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Generate the server → client data bridge: `var <name> = <json>;` for each
+ * template-context value referenced — but NOT redeclared — by the client script.
+ * Lets `<script client>` seed reactive state from `<script server>` data without
+ * a fetch. Only JSON-serializable values cross the boundary; declared names are
+ * skipped so client-owned variables are never clobbered.
+ */
+export declare function generateServerDataBridge(code: string, serverData?: Record<string, unknown>): string;
+/**
+ * Transform a <script client> block's content into a fully processed <script> tag.
+ *
+ * - Auto-imports from 'stx' and '@stacksjs/browser' (no explicit imports needed)
+ * - Resolves `import { x } from '@stores'` to runtime store access
+ * - Appends event binding code inside the script scope
+ * - Wraps everything in a scoped IIFE
+ *
+ * @param scriptContent - The raw content inside <script client>...</script>
+ * @param options - Event bindings and other processing options
+ * @returns A complete `<script>...</script>` tag ready for browser injection
+ */
+export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): Promise<string>;