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

package/dist/component-processing.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Component processing functions extracted from process.ts.
+ *
+ * Handles component tag parsing, attribute parsing, built-in STX components,
+ * @import directives, @component directives, and custom element resolution
+ * (kebab-case and PascalCase).
+ */
+import type { StxOptions } from './types';
+/**
+ * Convert PascalCase to kebab-case with proper handling of consecutive uppercase letters.
+ *
+ * Examples:
+ * - `UserCard` → `user-card`
+ * - `XMLParser` → `xml-parser` (not `x-m-l-parser`)
+ * - `HTMLElement` → `html-element`
+ * - `MyURLParser` → `my-url-parser`
+ * - `IOStream` → `io-stream`
+ *
+ * The algorithm:
+ * 1. Insert hyphen before uppercase letters that follow lowercase letters
+ * 2. Insert hyphen before the last uppercase in a sequence of uppercase letters (before lowercase)
+ * 3. Convert to lowercase
+ */
+export declare function pascalToKebab(str: string): string;
+import { restoreStashedScripts, stashScriptElements } from './html-masking';
+export { restoreStashedScripts, stashScriptElements };
+/**
+ * Parse HTML/JSX-like attributes from a string.
+ *
+ * Properly handles:
+ * - Simple attributes: `name="value"`
+ * - Boolean attributes: `disabled`
+ * - Dynamic values: `prop="{{ expr }}"` (evaluated at SSR)
+ * - Attributes with `=` in values: `url="https://example.com?a=1&b=2"`
+ * - Single and double quoted values
+ * - Escaped quotes within values
+ *
+ * ## Dynamic Data Syntax
+ *
+ * Use `{{ }}` for all dynamic data interpolation:
+ * ```html
+ * <Component title="{{ pageTitle }}" count="{{ items.length }}" />
+ * <div class="{{ isActive ? 'active' : '' }}">{{ content }}</div>
+ * ```
+ *
+ * ## Event Syntax (Alpine-style)
+ *
+ * ```html
+ * <button @click="handleClick()">Click me</button>
+ * <form @submit.prevent="handleSubmit()">...</form>
+ * <input @keydown.enter="send()" @keydown.escape="cancel()">
+ * ```
+ *
+ * @param attributesStr - The attributes portion of a tag (between tag name and closing)
+ * @returns Array of parsed attributes with name and value
+ */
+export interface ParsedAttribute {
+    name: string;
+    value: string | true;
+}
+/**
+ * Component tag match result
+ */
+export interface ComponentTagMatch {
+    fullMatch: string;
+    tagName: string;
+    attributes: string;
+    content: string;
+    startIndex: number;
+    endIndex: number;
+    isSelfClosing: boolean;
+}
+/**
+ * Skip predicate for the PascalCase pass: an HTML element SHOUTED in caps.
+ *
+ * HTML tag names are case-insensitive, so `<STYLE>`, `<DIV>` and `<H1>` are
+ * ordinary elements — but they also match the PascalCase component pattern
+ * (an initial capital followed by letters and digits), and that pass was the
+ * only one given no skip set. It therefore resolved `<STYLE>` to `style.stx`,
+ * found nothing, and spliced an ENOENT error (with absolute server paths) into
+ * the page — a user-visible failure on valid HTML input.
+ *
+ * Handing the pass the full `htmlTags` set is NOT the fix: it is a purely
+ * case-insensitive membership test, so it would also swallow `<Table>`,
+ * `<Button>`, `<Image>`, `<Video>`, `<Select>`, `<Progress>`, `<Form>` and
+ * `<Dialog>` — every one of which `@stacksjs/components` actually ships.
+ *
+ * The discriminator is SPELLING, and it is decided without touching the disk:
+ *
+ *   - stx components are PascalCase (`MyComponent`), never SCREAMING_CASE. So
+ *     `Table` (component) and `TABLE` (element) never collide, and this stays
+ *     a pure syntax rule — a name does not change meaning because a file
+ *     appeared or vanished next to it, and a genuinely missing `<Table>` still
+ *     reports itself instead of silently rendering an empty HTML table.
+ *   - The all-caps namespace only overlaps PascalCase for single-letter names
+ *     (`<A>`, `<B>`, `<I>`, `<P>`, `<Q>`, `<S>`, `<U>`). Those are HTML tags;
+ *     a one-letter component is not a convention anyone uses, and the
+ *     lowercase pass already treats `<a>`/`<b>` as HTML.
+ *   - Membership in `htmlTags` is still required, so all-caps names that are
+ *     NOT elements — `<FAQ />`, `<CTA />`, `<SEO />` — keep resolving as
+ *     components.
+ *
+ * Mixed-case spellings of an element (`<Div>`, `<Br>`) deliberately remain
+ * component references: they are indistinguishable from a PascalCase component
+ * name, so guessing either way would break someone.
+ */
+export declare function uppercaseHtmlTagSkip(htmlTags: Set<string>): (tagName: string) => boolean;
+/**
+ * Find component tags in HTML, properly handling quoted strings
+ * This solves the issue where `>` inside attribute values would incorrectly end the tag
+ *
+ * @param html - The HTML string to search
+ * @param tagPattern - Regex pattern for tag name (for PascalCase components)
+ * @param skipTags - Optional set of tag names to skip (matched case-insensitively),
+ *   or a predicate receiving the tag name exactly as it was written. The
+ *   PascalCase pass needs the predicate form: it must skip `<STYLE>` while
+ *   still claiming `<Style>` (see `uppercaseHtmlTagSkip`).
+ * @returns Array of found component tags
+ */
+export declare function findComponentTags(html: string, tagPattern: RegExp, skipTags?: Set<string> | ((tagName: string) => boolean)): ComponentTagMatch[];
+/**
+ * Decode a pre-evaluated `__stx_` prop value produced by loop processing.
+ *
+ * Loop iterations serialise component prop values so they survive until the
+ * component directive is processed. The current wire format is base64-encoded
+ * JSON — chosen because base64 contains no quotes, backslashes or angle
+ * brackets, so it passes through `parseMultilineAttributes` (which strips
+ * backslash escapes) and HTML attribute quoting completely intact.
+ *
+ * A legacy HTML-entity-escaped JSON format is still accepted as a fallback so
+ * that any externally-produced markup keeps working.
+ */
+/**
+ * Decode the entities in a static attribute value.
+ *
+ * An attribute in a template is HTML source, so `title="Tom &amp; Jerry"` names
+ * the string `Tom & Jerry`, and a component that receives it as a prop should
+ * see that string rather than the encoding of it.
+ *
+ * The narrowness is the point. This runs on attribute values, at parse time, and
+ * on nothing else: a value that reached a component any other way - from the
+ * component's own script, from the parent's context, from a `:bound="expression"`
+ * - was never encoded, so decoding it can only destroy escaping somebody meant.
+ * That is exactly what a blanket "this looks like HTML, unescape it" pass over
+ * the component context used to do, and it turned escaped user text back into
+ * live markup.
+ */
+export declare function decodeAttributeEntities(value: string): string;
+export declare function decodeStxProp(attrValue: string, options?: {
+    debug?: boolean;
+}): unknown;
+/**
+ * Parse multiline attributes from a component tag
+ * Handles HTML content inside attribute values correctly
+ *
+ * @param attributesStr - The attributes string (may be multiline)
+ * @returns Object mapping attribute names to values
+ */
+/**
+ * Read a `{...}` attribute value whole, from `start`, matching nested braces and
+ * ignoring braces inside quotes. Returns the text including both outer braces;
+ * an unterminated value returns the rest of the string rather than throwing,
+ * so a malformed tag degrades to one bad prop instead of a shattered tag.
+ */
+export declare function readBracedValue(source: string, start: number): string;
+/**
+ * The expression inside a `prop={expr}` value, or null when `value` is not a
+ * braced expression. `{handler}` unwraps to `handler`; the JSX double-brace
+ * `{{ a: 1 }}` unwraps to the object literal `{ a: 1 }` (stacksjs/stx#1956).
+ */
+export declare function unwrapBracedExpression(value: string): string | null;
+export declare function parseMultilineAttributes(attributesStr: string): Record<string, string>;
+export declare function parseAttributes(attributesStr: string): ParsedAttribute[];
+/**
+ * Process built-in STX components like <stx-loading-indicator>
+ */
+export declare function processBuiltInComponents(template: string, _context: Record<string, any>, _filePath: string, _options: StxOptions): Promise<string>;
+/**
+ * Process @import directives for explicit component imports.
+ *
+ * Syntax:
+ *   @import('components/Card')
+ *   @import('ui/Button', 'ui/Modal')
+ *   @import('Card', 'Button', 'Modal')
+ *
+ * This allows explicit importing of components from any path,
+ * overriding the auto-import from the components directory.
+ */
+export declare function processImportDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Process @component directives
+ */
+export declare function processComponentDirectives(template: string, context: Record<string, any>, filePath: string, componentsDir: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Process custom element components (both kebab-case and PascalCase)
+ * Uses a proper parser that handles HTML content inside attribute values
+ */
+export declare function processCustomElements(template: string, context: Record<string, any>, filePath: string, componentsDir: string, options: StxOptions, dependencies: Set<string>): Promise<string>;