@fuzdev/fuz_ui 0.181.1 → 0.182.1

package/dist/svelte_preprocess_mdz.js

@@ -0,0 +1,513 @@
+/**
+ * Svelte preprocessor that compiles static `Mdz` content to Svelte markup at build time.
+ *
+ * Detects `Mdz` components with static string `content` props, parses the mdz content,
+ * renders each `MdzNode` to equivalent Svelte markup via `mdz_to_svelte`, and replaces
+ * the `Mdz` with `MdzPrecompiled` containing pre-rendered children.
+ *
+ * Also handles ternary chains (`content={a ? 'x' : b ? 'y' : 'z'}`) where all leaf
+ * values are statically resolvable strings, emitting `{#if a}markup_x{:else if b}markup_y{:else}markup_z{/if}`
+ * as children of a single `MdzPrecompiled`.
+ *
+ * Truly dynamic `content` props are left untouched.
+ *
+ * @module
+ */
+import { parse } from 'svelte/compiler';
+import MagicString from 'magic-string';
+import { walk } from 'zimmerframe';
+import { should_exclude_path } from '@fuzdev/fuz_util/path.js';
+import { find_attribute, extract_static_string, try_extract_conditional_chain, build_static_bindings, resolve_component_names, has_identifier_in_tree, find_import_insert_position, generate_import_lines, remove_variable_declaration, remove_import_declaration, remove_import_specifier, handle_preprocess_error, } from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
+import { mdz_parse } from './mdz.js';
+import { mdz_to_svelte } from './mdz_to_svelte.js';
+const PRECOMPILED_NAME = 'MdzPrecompiled';
+/**
+ * Creates a Svelte preprocessor that compiles static `Mdz` content at build time.
+ *
+ * @param options Configuration for component/element resolution and file filtering.
+ * @returns A Svelte `PreprocessorGroup` for use in `svelte.config.js`.
+ */
+export const svelte_preprocess_mdz = (options = {}) => {
+    const { exclude = [], components = {}, elements: elements_array = [], component_imports = ['@fuzdev/fuz_ui/Mdz.svelte'], compiled_component_import = '@fuzdev/fuz_ui/MdzPrecompiled.svelte', on_error = process.env.CI === 'true' ? 'throw' : 'log', } = options;
+    const elements = new Set(elements_array);
+    return {
+        name: 'fuz-mdz',
+        markup: ({ content, filename }) => {
+            if (should_exclude_path(filename, exclude)) {
+                return { code: content };
+            }
+            // Quick bail: does file mention any known Mdz import source?
+            if (!component_imports.some((source) => content.includes(source))) {
+                return { code: content };
+            }
+            const ast = parse(content, { filename, modern: true });
+            // Resolve which local names map to the Mdz component
+            const mdz_names = resolve_component_names(ast, component_imports);
+            if (mdz_names.size === 0) {
+                return { code: content };
+            }
+            // Check for MdzPrecompiled name collision
+            if (has_name_collision(ast, compiled_component_import)) {
+                return { code: content };
+            }
+            const s = new MagicString(content);
+            const bindings = build_static_bindings(ast);
+            // Find and transform Mdz usages with static content
+            const { transformations, total_usages, transformed_usages } = find_mdz_usages(ast, mdz_names, {
+                components,
+                elements,
+                filename,
+                source: content,
+                bindings,
+                on_error,
+            });
+            if (transformations.length === 0) {
+                return { code: content };
+            }
+            // Apply transformations
+            for (const t of transformations) {
+                s.overwrite(t.start, t.end, t.replacement);
+            }
+            // Remove dead const bindings that were consumed by transformations
+            remove_dead_const_bindings(s, ast, transformations, content);
+            // Determine which Mdz imports can be removed
+            const removable_imports = find_removable_mdz_imports(ast, mdz_names, total_usages, transformed_usages);
+            // Add required imports and remove unused Mdz imports
+            manage_imports(s, ast, transformations, removable_imports, compiled_component_import, content);
+            return {
+                code: s.toString(),
+                map: s.generateMap({ hires: true }),
+            };
+        },
+    };
+};
+/**
+ * Checks if `MdzPrecompiled` is already imported from a different source.
+ * If so, the preprocessor bails to avoid name collisions.
+ */
+const has_name_collision = (ast, compiled_component_import) => {
+    for (const script of [ast.instance, ast.module]) {
+        if (!script)
+            continue;
+        for (const node of script.content.body) {
+            if (node.type !== 'ImportDeclaration')
+                continue;
+            const source_path = node.source.value;
+            for (const spec of node.specifiers) {
+                if (spec.local.name === PRECOMPILED_NAME && source_path !== compiled_component_import) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+};
+/**
+ * Collects identifiers from an expression that resolved through bindings.
+ * Only collects top-level Identifier nodes that appear in the bindings map.
+ *
+ * TODO: support transitive dead const removal — currently only directly-consumed
+ * bindings (identifiers in the expression AST) are tracked. Transitive dependencies
+ * (e.g., `const a = 'x'; const b = a; content={b}` — `a` is not removed) are not
+ * traced. After removing a dead const, re-check whether identifiers in its
+ * initializer became dead too.
+ */
+const collect_consumed_bindings = (value, bindings) => {
+    const consumed = new Set();
+    if (value === true || Array.isArray(value))
+        return consumed;
+    const collect_from_expr = (expr) => {
+        if (expr.type === 'Identifier' && bindings.has(expr.name)) {
+            consumed.add(expr.name);
+        }
+        else if (expr.type === 'BinaryExpression' && expr.operator === '+') {
+            collect_from_expr(expr.left);
+            collect_from_expr(expr.right);
+        }
+        else if (expr.type === 'TemplateLiteral') {
+            for (const e of expr.expressions) {
+                collect_from_expr(e);
+            }
+        }
+        else if (expr.type === 'ConditionalExpression') {
+            collect_from_expr(expr.consequent);
+            collect_from_expr(expr.alternate);
+        }
+    };
+    collect_from_expr(value.expression);
+    return consumed;
+};
+/**
+ * Walks the AST to find `Mdz` component usages with static `content` props
+ * and generates transformations to replace them with `MdzPrecompiled` children.
+ */
+const find_mdz_usages = (ast, mdz_names, context) => {
+    const transformations = [];
+    const total_usages = new Map();
+    const transformed_usages = new Map();
+    // zimmerframe types visitors against {type: string}, requiring explicit annotations
+    // on the callback parameters for Svelte-specific AST types like AST.Component
+    walk(ast.fragment, null, {
+        Component(node, ctx) {
+            // Always recurse into children so nested Mdz components are found
+            ctx.next();
+            if (!mdz_names.has(node.name))
+                return;
+            // Track total usages per name
+            total_usages.set(node.name, (total_usages.get(node.name) ?? 0) + 1);
+            // Skip if spread attributes present — can't determine content statically
+            if (node.attributes.some((attr) => attr.type === 'SpreadAttribute'))
+                return;
+            const content_attr = find_attribute(node, 'content');
+            if (!content_attr)
+                return;
+            // Extract static string value
+            const content_value = extract_static_string(content_attr.value, context.bindings);
+            if (content_value !== null) {
+                // Parse mdz content and render to Svelte markup
+                let result;
+                try {
+                    const nodes = mdz_parse(content_value);
+                    result = mdz_to_svelte(nodes, context.components, context.elements);
+                }
+                catch (error) {
+                    handle_preprocess_error(error, '[fuz-mdz]', context.filename, context.on_error);
+                    return;
+                }
+                // If content has unconfigured tags, skip this usage (fall back to runtime)
+                if (result.has_unconfigured_tags)
+                    return;
+                const consumed = collect_consumed_bindings(content_attr.value, context.bindings);
+                const replacement = build_replacement(node, content_attr, result.markup, context.source);
+                transformed_usages.set(node.name, (transformed_usages.get(node.name) ?? 0) + 1);
+                transformations.push({
+                    start: node.start,
+                    end: node.end,
+                    replacement,
+                    required_imports: result.imports,
+                    consumed_bindings: consumed,
+                    component_node: node,
+                });
+                return;
+            }
+            // Try conditional chain (handles both simple and nested ternaries)
+            const chain = try_extract_conditional_chain(content_attr.value, context.source, context.bindings);
+            if (chain === null)
+                return;
+            // Parse and render each branch
+            const branch_results = [];
+            try {
+                for (const branch of chain) {
+                    const nodes = mdz_parse(branch.value);
+                    const result = mdz_to_svelte(nodes, context.components, context.elements);
+                    if (result.has_unconfigured_tags)
+                        return;
+                    branch_results.push({ markup: result.markup, imports: result.imports });
+                }
+            }
+            catch (error) {
+                handle_preprocess_error(error, '[fuz-mdz]', context.filename, context.on_error);
+                return;
+            }
+            // Build {#if}/{:else if}/{:else} markup
+            let children_markup = '';
+            for (let i = 0; i < chain.length; i++) {
+                const branch = chain[i];
+                const result = branch_results[i];
+                if (i === 0) {
+                    children_markup += `{#if ${branch.test_source}}${result.markup}`;
+                }
+                else if (branch.test_source !== null) {
+                    children_markup += `{:else if ${branch.test_source}}${result.markup}`;
+                }
+                else {
+                    children_markup += `{:else}${result.markup}`;
+                }
+            }
+            children_markup += '{/if}';
+            const replacement = build_replacement(node, content_attr, children_markup, context.source);
+            // Merge imports from all branches
+            const merged_imports = new Map();
+            for (const result of branch_results) {
+                for (const [name, info] of result.imports) {
+                    merged_imports.set(name, info);
+                }
+            }
+            const consumed = collect_consumed_bindings(content_attr.value, context.bindings);
+            transformed_usages.set(node.name, (transformed_usages.get(node.name) ?? 0) + 1);
+            transformations.push({
+                start: node.start,
+                end: node.end,
+                replacement,
+                required_imports: merged_imports,
+                consumed_bindings: consumed,
+                component_node: node,
+            });
+        },
+    });
+    return { transformations, total_usages, transformed_usages };
+};
+/**
+ * Removes dead `const` bindings from the instance script that were consumed
+ * by transformations and are no longer referenced anywhere else in the file.
+ *
+ * Only handles single-declarator `const` statements. Skips `const a = 'x', b = 'y'`
+ * and module script variables (which could be exported/imported by other files).
+ */
+const remove_dead_const_bindings = (s, ast, transformations, source) => {
+    // Collect all consumed binding names across transformations
+    const all_consumed = new Set();
+    for (const t of transformations) {
+        for (const name of t.consumed_bindings) {
+            all_consumed.add(name);
+        }
+    }
+    if (all_consumed.size === 0)
+        return;
+    // Only remove from instance script (module script variables could be exported)
+    const instance = ast.instance;
+    if (!instance)
+        return;
+    // Build a skip set of transformed component nodes so their attribute
+    // expressions (which still contain the old identifiers) don't false-match
+    const skip = new Set();
+    for (const t of transformations) {
+        skip.add(t.component_node);
+    }
+    for (const name of all_consumed) {
+        // Find the VariableDeclaration containing this binding in instance script
+        let declaration_node = null;
+        for (const node of instance.content.body) {
+            if (node.type !== 'VariableDeclaration' || node.kind !== 'const')
+                continue;
+            for (const decl of node.declarations) {
+                if (decl.id.type === 'Identifier' && decl.id.name === name) {
+                    declaration_node = node;
+                    break;
+                }
+            }
+            if (declaration_node)
+                break;
+        }
+        if (!declaration_node)
+            continue;
+        // Only handle single-declarator statements
+        if (declaration_node.declarations.length !== 1)
+            continue;
+        // Check if the identifier is referenced anywhere else
+        const id_skip = new Set([...skip, declaration_node]);
+        // Check instance script (excluding the declaration itself)
+        if (has_identifier_in_tree(instance.content, name, id_skip))
+            continue;
+        // Check module script
+        if (ast.module?.content && has_identifier_in_tree(ast.module.content, name))
+            continue;
+        // Check template — skip transformed component nodes whose attribute expressions
+        // still contain the old identifier references in the AST
+        if (has_identifier_in_tree(ast.fragment, name, id_skip))
+            continue;
+        remove_variable_declaration(s, declaration_node, source);
+        // Add to skip set so chained dead const checks don't find references to this removed node
+        skip.add(declaration_node);
+    }
+};
+/**
+ * Builds the replacement string for a transformed Mdz component.
+ *
+ * Reconstructs the opening tag as `<MdzPrecompiled` with all attributes except `content`,
+ * using source text slicing to preserve exact formatting and dynamic expressions.
+ */
+const build_replacement = (node, content_attr, children_markup, source) => {
+    // Collect source ranges of all attributes EXCEPT content
+    const other_attr_ranges = [];
+    for (const attr of node.attributes) {
+        if (attr === content_attr)
+            continue;
+        other_attr_ranges.push({ start: attr.start, end: attr.end });
+    }
+    // Build opening tag with MdzPrecompiled name
+    let opening = `<${PRECOMPILED_NAME}`;
+    for (const range of other_attr_ranges) {
+        opening += ' ' + source.slice(range.start, range.end);
+    }
+    opening += '>';
+    return `${opening}${children_markup}</${PRECOMPILED_NAME}>`;
+};
+/**
+ * Determines which Mdz import declarations can be safely removed or trimmed.
+ *
+ * An import is removable when:
+ * 1. All template usages of that name were successfully transformed.
+ * 2. The identifier is not referenced elsewhere in script or template expressions.
+ *
+ * For multi-specifier imports, only the Mdz specifier is removed (partial removal).
+ * For single-specifier imports, the entire declaration is removed.
+ */
+const find_removable_mdz_imports = (ast, mdz_names, total_usages, transformed_usages) => {
+    const removable = new Map();
+    for (const [name, { import_node, specifier }] of mdz_names) {
+        const total = total_usages.get(name) ?? 0;
+        const transformed = transformed_usages.get(name) ?? 0;
+        // Only remove if ALL template usages were transformed
+        if (total === 0 || transformed < total)
+            continue;
+        // Check if identifier is referenced elsewhere in the AST
+        const skip = new Set([import_node]);
+        // Check instance script body (excluding the import itself)
+        if (ast.instance?.content && has_identifier_in_tree(ast.instance.content, name, skip)) {
+            continue;
+        }
+        // Check module script body (excluding the import itself)
+        if (ast.module?.content && has_identifier_in_tree(ast.module.content, name, skip)) {
+            continue;
+        }
+        // Check template for expression references (Component.name is a string, not Identifier)
+        if (has_identifier_in_tree(ast.fragment, name)) {
+            continue;
+        }
+        const positioned_node = import_node;
+        if (import_node.specifiers.length === 1) {
+            removable.set(name, { node: positioned_node, kind: 'full' });
+        }
+        else {
+            removable.set(name, {
+                node: positioned_node,
+                kind: 'partial',
+                specifier_to_remove: specifier,
+            });
+        }
+    }
+    return removable;
+};
+/**
+ * Manages import additions and removals.
+ *
+ * Adds the `MdzPrecompiled` import and other required imports (DocsLink, Code, resolve).
+ * Removes Mdz import declarations that are no longer referenced.
+ *
+ * Handles both full removal (single-specifier imports) and partial removal
+ * (multi-specifier imports where only the Mdz specifier is removed).
+ *
+ * To avoid MagicString boundary conflicts when the insertion position falls inside
+ * a removal range, one removable Mdz import is overwritten with the MdzPrecompiled
+ * import line instead of using separate remove + appendLeft.
+ */
+const manage_imports = (s, ast, transformations, removable_imports, compiled_component_import, source) => {
+    // Collect all required imports across transformations
+    const required = new Map();
+    for (const t of transformations) {
+        for (const [name, info] of t.required_imports) {
+            required.set(name, info);
+        }
+    }
+    // Always need MdzPrecompiled when transformations occur
+    required.set(PRECOMPILED_NAME, { path: compiled_component_import, kind: 'default' });
+    const script = ast.instance;
+    // Separate full removals from partial removals
+    const full_removals = new Set();
+    const partial_removals = [];
+    for (const [, action] of removable_imports) {
+        if (action.kind === 'full') {
+            full_removals.add(action.node);
+        }
+        else {
+            partial_removals.push(action);
+        }
+    }
+    if (!script) {
+        // No instance script — removable_imports won't apply (imports are in module script if any)
+        // Just add all required imports
+        const lines = generate_import_lines(required);
+        if (ast.module) {
+            s.appendLeft(ast.module.end, `\n\n<script lang="ts">\n${lines}\n</script>`);
+        }
+        else {
+            s.prepend(`<script lang="ts">\n${lines}\n</script>\n\n`);
+        }
+        // Remove Mdz imports from module script if removable
+        for (const node of full_removals) {
+            remove_import_declaration(s, node, source);
+        }
+        // Apply partial removals
+        for (const action of partial_removals) {
+            remove_import_specifier(s, action.node, action.specifier_to_remove, source);
+        }
+        return;
+    }
+    // Check existing imports to avoid duplicates — tracks both name AND source path
+    const existing = new Map();
+    for (const node of script.content.body) {
+        if (node.type === 'ImportDeclaration') {
+            const source_path = node.source.value;
+            for (const spec of node.specifiers) {
+                existing.set(spec.local.name, source_path);
+            }
+        }
+    }
+    const to_add = new Map();
+    for (const [name, info] of required) {
+        const existing_path = existing.get(name);
+        if (existing_path === undefined) {
+            to_add.set(name, info);
+        }
+    }
+    // Strategy: if we're both adding MdzPrecompiled and removing an Mdz import,
+    // overwrite one full-removable import with the MdzPrecompiled line to avoid
+    // MagicString boundary conflicts. Other imports use normal appendLeft.
+    let overwrite_target = null;
+    if (to_add.has(PRECOMPILED_NAME) && full_removals.size > 0) {
+        // Pick the first removable import to overwrite
+        overwrite_target = full_removals.values().next().value ?? null;
+    }
+    // Generate the MdzPrecompiled import line separately if using overwrite
+    if (overwrite_target) {
+        const node_start = overwrite_target.start;
+        const node_end = overwrite_target.end;
+        // Find the start of the line (consume leading whitespace)
+        let line_start = node_start;
+        while (line_start > 0 && (source[line_start - 1] === '\t' || source[line_start - 1] === ' ')) {
+            line_start--;
+        }
+        // Extract indentation from the original import line rather than hardcoding a tab.
+        // The import node's start is after any leading whitespace, so the indentation is
+        // the characters between the line start and the node start.
+        const original_indent = source.slice(line_start, node_start);
+        const precompiled_line = `${original_indent}import ${PRECOMPILED_NAME} from '${compiled_component_import}';`;
+        s.overwrite(line_start, node_end, precompiled_line);
+        to_add.delete(PRECOMPILED_NAME);
+    }
+    // When there are partial removals but no full-removal overwrite target,
+    // the appendLeft at find_import_insert_position can conflict with the
+    // partial removal's overwrite (they share the same node.end boundary).
+    // Bundle the new imports into the first partial removal's overwrite instead.
+    const insert_pos = find_import_insert_position(script);
+    let partial_carrier = null;
+    if (to_add.size > 0 && partial_removals.length > 0) {
+        for (const action of partial_removals) {
+            if (action.node.end === insert_pos) {
+                partial_carrier = action;
+                break;
+            }
+        }
+    }
+    // Add remaining imports — either bundled with a partial removal or via appendLeft
+    let carrier_lines = '';
+    if (partial_carrier && to_add.size > 0) {
+        carrier_lines = '\n' + generate_import_lines(to_add);
+        to_add.clear();
+    }
+    if (to_add.size > 0) {
+        const lines = generate_import_lines(to_add);
+        s.appendLeft(insert_pos, '\n' + lines);
+    }
+    // Remove remaining full Mdz imports (skip the overwrite target)
+    for (const node of full_removals) {
+        if (node === overwrite_target)
+            continue;
+        remove_import_declaration(s, node, source);
+    }
+    // Apply partial import removals
+    for (const action of partial_removals) {
+        remove_import_specifier(s, action.node, action.specifier_to_remove, source, action === partial_carrier ? carrier_lines : '');
+    }
+};

package/dist/tsdoc_mdz.d.ts

@@ -18,7 +18,7 @@
  * - Bare identifiers → wrapped in backticks
  *
  * @param content Raw `@see` tag content in TSDoc format
- * @returns mdz-formatted string ready for `<Mdz>` component
+ * @returns mdz-formatted string ready for `Mdz` component
  *
  * @example
  * ```ts

package/dist/tsdoc_mdz.js

@@ -21,7 +21,7 @@ const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
  * - Bare identifiers → wrapped in backticks
  *
  * @param content Raw `@see` tag content in TSDoc format
- * @returns mdz-formatted string ready for `<Mdz>` component
+ * @returns mdz-formatted string ready for `Mdz` component
  *
  * @example
  * ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.181.1",
+  "version": "0.182.1",
   "description": "Svelte UI library",
   "motto": "friendly user zystem",
   "glyph": "🧶",
@@ -26,6 +26,7 @@
     "build": "gro build",
     "check": "gro check",
     "test": "gro test",
+    "fixtures:update": "gro src/test/fixtures/update",
     "preview": "vite preview",
     "deploy": "gro deploy"
   },
@@ -34,12 +35,13 @@
     "node": ">=22.15"
   },
   "peerDependencies": {
-    "@fuzdev/fuz_code": ">=0.41.0",
-    "@fuzdev/fuz_css": ">=0.45.0",
-    "@fuzdev/fuz_util": ">=0.48.2",
+    "@fuzdev/fuz_code": ">=0.44.0",
+    "@fuzdev/fuz_css": ">=0.47.0",
+    "@fuzdev/fuz_util": ">=0.49.2",
     "@jridgewell/trace-mapping": "^0.3",
-    "@ryanatkn/gro": ">=0.186.0",
+    "@ryanatkn/gro": ">=0.191.0",
     "@sveltejs/kit": "^2.47.3",
+    "@types/estree": "^1",
     "esm-env": "^1",
     "svelte": "^5",
     "svelte2tsx": "^0.7.45",
@@ -49,44 +51,59 @@
     "@fuzdev/fuz_code": {
       "optional": true
     },
+    "@fuzdev/fuz_util": {
+      "optional": true
+    },
     "@jridgewell/trace-mapping": {
       "optional": true
     },
     "@ryanatkn/gro": {
       "optional": true
     },
+    "@types/estree": {
+      "optional": true
+    },
     "esm-env": {
       "optional": true
+    },
+    "svelte2tsx": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_code": "^0.41.0",
+    "@fuzdev/fuz_code": "^0.44.1",
     "@fuzdev/fuz_css": "^0.47.0",
-    "@fuzdev/fuz_util": "^0.48.3",
+    "@fuzdev/fuz_util": "^0.50.1",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.190.0",
+    "@ryanatkn/gro": "^0.191.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
     "@types/node": "^24.10.1",
     "@webref/css": "^8.2.0",
     "eslint": "^9.39.1",
     "eslint-plugin-svelte": "^3.13.1",
     "esm-env": "^1.2.2",
     "jsdom": "^27.2.0",
+    "magic-string": "^0.30.21",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
     "svelte": "^5.49.1",
     "svelte-check": "^4.3.6",
-    "svelte2tsx": "^0.7.46",
+    "svelte2tsx": "^0.7.47",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
     "vitest": "^4.0.15",
-    "zod": "^4.1.13"
+    "zimmerframe": "^1.1.4",
+    "zod": "^4.3.6"
   },
   "prettier": {
     "plugins": [