@volter/editor-core 0.5.57

package/src/ui-source/ts-ast.ts

@@ -0,0 +1,171 @@
+/**
+ * THE MECHANICAL TypeScript-AST HELPERS every `ui-source/` reader repeats.
+ *
+ * Not an abstraction over the TypeScript compiler API — each function here
+ * hands back the compiler's OWN node and gets out of the way, and every caller
+ * keeps programming against `ts.*`. What they remove is the retyping: the
+ * eleven modules in this directory that read a TSX module each spelled the same
+ * four or five little walks out again, and the copies had begun to disagree
+ * about things that matter.
+ *
+ * What "matters" means, concretely — this is the drift these functions existed
+ * in nine, three, three, two and two copies of, and what each copy got wrong:
+ *
+ *   - {@link parseAuthoringTsx}: `ts.createSourceFile(file, code,
+ *     ScriptTarget.Latest, true, ScriptKind.TSX)` appeared at NINE sites, two of
+ *     them already wrapped in a local `parseTsx`/`sourceFile` whose only
+ *     difference was argument order. Both of the last two arguments are silent
+ *     if wrong: `setParentNodes: false` leaves `node.parent` undefined, which
+ *     breaks every upward walk here (including {@link enclosingScope}) at
+ *     runtime rather than at compile time, and a missing `ScriptKind.TSX`
+ *     parses JSX as type assertions.
+ *   - {@link hasModifier}: two copies, ALREADY drifted —
+ *     `plan-fork-component.ts`'s guarded with `ts.canHaveModifiers` and
+ *     `r3f-project-contracts.ts`'s cast the node to `ts.HasModifiers` and hoped.
+ *     The guarded form is the one kept.
+ *   - {@link enclosingScope}: three copies of one loop, returning
+ *     `FunctionLikeDeclaration` in two and `SignatureDeclaration` in the third
+ *     for the same four node kinds.
+ *   - {@link numericLiteral}: three copies (`numeric`, `numericLiteral`) of the
+ *     unary-sign rule — the part a fourth author would plausibly write without,
+ *     silently losing every negative literal.
+ *   - {@link jsxAttribute} / {@link refIdentifier}: two and three copies of
+ *     "find this attribute", one of the `refIdentifier`s returning `undefined`
+ *     where the others return `null`.
+ *
+ * Deliberately NOT here: anything whose two versions differ for a caller's own
+ * reason. `plan-fork-component.ts`'s `jsxAtOffset` and `reparent-guard.ts`'s
+ * `jsxElementAt` look like twins and are not — one wants the OPENING element to
+ * read its tag, the other wants the whole `ts.JsxElement` to move it, and the
+ * second prunes the walk by span while the first does not.
+ */
+
+import * as ts from 'typescript';
+
+/**
+ * Parse one authored TSX/TS module the way every reader in this directory
+ * needs it: newest syntax, parent pointers set, JSX enabled.
+ *
+ * `file` is the module's path — it is what the compiler reports in positions
+ * and what `node.getText(sf)` reads against, so pass the real one where there
+ * is one.
+ */
+/**
+ * ONE parse per (file, bytes) — the same source is parsed several times over
+ * for one bundle otherwise.
+ *
+ * `ProjectContractResolver` calls this three times for a single file
+ * (`importedForSource`, `typeAliasesForSource`, `propSpecsForSource`), the
+ * stamping transform parses it again, and every one of those runs on EVERY
+ * structural edit.
+ * Measured on `examples/third-person`, the contract walk alone costs 380ms of
+ * the ~1.1s an edit spends on CPU.
+ *
+ * Keyed on the BYTES, so it is sound in a way an analysis cache is not: a
+ * parse is a pure function of its input, while what a file MEANS also depends
+ * on the files it imports. Edited bytes miss the cache and re-parse; the entry
+ * for the old bytes is dropped, so the map holds one node tree per live file
+ * rather than one per revision.
+ */
+const parsedByFile = new Map<
+  string,
+  { readonly code: string; readonly sourceFile: ts.SourceFile }
+>();
+
+export function parseAuthoringTsx(file: string, code: string): ts.SourceFile {
+  const cached = parsedByFile.get(file);
+  if (cached && cached.code === code) return cached.sourceFile;
+  const sourceFile = ts.createSourceFile(
+    file,
+    code,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+    ts.ScriptKind.TSX,
+  );
+  parsedByFile.set(file, { code, sourceFile });
+  return sourceFile;
+}
+
+/** Drop every cached parse — for a project switch, where the next project's
+ *  files may reuse these paths with different bytes. Bytes are compared on
+ *  every hit anyway, so this is hygiene against unbounded growth, not
+ *  correctness. */
+export function clearAuthoringParseCache(): void {
+  parsedByFile.clear();
+}
+
+/** Whether `node` carries a given modifier (`export`, `default`, …). False for
+ *  a node kind that cannot carry modifiers at all, rather than throwing. */
+export function hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean {
+  if (!ts.canHaveModifiers(node)) return false;
+  return (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === kind);
+}
+
+/**
+ * The nearest function-like ancestor of `node` — the scope a hook call, a ref
+ * declaration or a JSX element belongs to.
+ *
+ * Requires parent pointers, so the source must come from
+ * {@link parseAuthoringTsx} (or another parse that set them).
+ */
+export function enclosingScope(node: ts.Node): ts.FunctionLikeDeclaration | null {
+  let current: ts.Node | undefined = node.parent;
+  while (current) {
+    if (
+      ts.isArrowFunction(current) ||
+      ts.isFunctionExpression(current) ||
+      ts.isFunctionDeclaration(current) ||
+      ts.isMethodDeclaration(current)
+    ) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+/**
+ * The number an expression literally IS, or `undefined` when it is anything
+ * computed. A leading `-`/`+` counts: `position={[-1, 0, 2]}` is authored
+ * constantly and its first entry is a `PrefixUnaryExpression`, not a numeric
+ * literal.
+ */
+export function numericLiteral(expression: ts.Expression): number | undefined {
+  if (ts.isNumericLiteral(expression)) return Number(expression.text);
+  if (
+    ts.isPrefixUnaryExpression(expression) &&
+    (expression.operator === ts.SyntaxKind.MinusToken ||
+      expression.operator === ts.SyntaxKind.PlusToken) &&
+    ts.isNumericLiteral(expression.operand)
+  ) {
+    const value = Number(expression.operand.text);
+    return expression.operator === ts.SyntaxKind.MinusToken ? -value : value;
+  }
+  return undefined;
+}
+
+/** The named attribute on a JSX opening element, or `undefined`. Spread
+ *  attributes are not attributes and are skipped. */
+export function jsxAttribute(
+  element: ts.JsxOpeningLikeElement,
+  name: string,
+): ts.JsxAttribute | undefined {
+  return element.attributes.properties.find(
+    (candidate): candidate is ts.JsxAttribute =>
+      ts.isJsxAttribute(candidate) && candidate.name.getText() === name,
+  );
+}
+
+/**
+ * The identifier a `ref={x}` attribute binds on this element, or `null`.
+ *
+ * `null` for both "no `ref`" and "a `ref` bound to something that is not a bare
+ * identifier" (`ref={(n) => …}`, `ref={refs[i]}`): every caller is matching the
+ * ref against a `useRef` declaration by NAME, and neither case has one.
+ */
+export function refIdentifier(element: ts.JsxOpeningLikeElement): string | null {
+  const ref = jsxAttribute(element, 'ref');
+  const initializer = ref?.initializer;
+  if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression) return null;
+  return ts.isIdentifier(initializer.expression) ? initializer.expression.text : null;
+}

package/src/ui-source/utility-class-support.ts

@@ -0,0 +1,169 @@
+/**
+ * "Does THIS project interpret utility classes?" — the evidence gate in front of
+ * `writeStyleAuto`'s className route.
+ *
+ * Why it exists: the router used to pick the Tailwind arbitrary-value class
+ * (`bg-[#059669]`) whenever an element merely HAD a literal `className`, with no
+ * evidence anything would ever compile that class. On a plain-CSS project the
+ * write lands in source and paints NOTHING — measured on the vendored pmndrs
+ * racing-game (plain Vite + `src/styles.css`, no tailwind in its tree or ours):
+ * the editor's visible result was only the adapter's optimistic inline patch, a
+ * cold remount rendered `rgba(0, 0, 0, 0)`, and the game's own build has no
+ * transformer for it either. Inert bytes in someone's source that tell a lie
+ * about their game.
+ *
+ * The fix is the same observation-over-inference rule the OID dialect decision
+ * follows: route on what was OBSERVED about the project, not on what the
+ * element's shape suggests. A tier gathers evidence with whatever I/O it has
+ * (`node:fs` on the dev server, `StorageBackend` in the hosted browser) and
+ * hands the bytes here; the decision itself is pure and lives ONLY here, so the
+ * two tiers cannot drift into different answers.
+ *
+ * **The probe is deliberately strict, and the asymmetry is why.** A false
+ * NEGATIVE costs an inline `style={{…}}` write — a less idiomatic expression of
+ * the same edit that paints correctly in every project, in and out of the
+ * editor. A false POSITIVE costs a write that is a lie. So "a dependency is
+ * listed" is not enough on its own: something must also show the pipeline is
+ * actually wired (a config file, a postcss/vite/astro plugin mention, or a css
+ * entry that imports the framework). A CDN/runtime interpreter in HTML stands
+ * alone because it needs no build step at all.
+ */
+
+/** The routing answer, plus what was actually observed to produce it. */
+export interface UtilityClassSupport {
+  /** True only when the project was OBSERVED to interpret utility classes. */
+  readonly supported: boolean;
+  /** What was (or was not) found — quoted verbatim in a refusal message. */
+  readonly evidence: string;
+}
+
+/**
+ * The answer when nothing was probed at all. It is `supported: false` because
+ * an unprobed project is an unproven one, and the honest route for an unproven
+ * project is the inline style that works everywhere.
+ */
+export const UTILITY_CLASSES_UNPROVEN: UtilityClassSupport = {
+  supported: false,
+  evidence: 'no utility-class pipeline was probed for this project',
+};
+
+/**
+ * Root-relative files a tier should read when it can. Config files are listed
+ * by exact name (a probe should not have to guess extensions); the css/html
+ * evidence is found by extension instead — see {@link isUtilityClassEvidenceFile}.
+ */
+export const UTILITY_CLASS_EVIDENCE_FILES: readonly string[] = [
+  'package.json',
+  'tailwind.config.js',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs',
+  'tailwind.config.ts',
+  'uno.config.js',
+  'uno.config.ts',
+  'unocss.config.js',
+  'unocss.config.ts',
+  'postcss.config.js',
+  'postcss.config.cjs',
+  'postcss.config.mjs',
+  'postcss.config.ts',
+  'vite.config.js',
+  'vite.config.ts',
+  'astro.config.mjs',
+  'astro.config.ts',
+];
+
+/** Extensions worth scanning for a framework entry marker (`@tailwind`, a CDN script). */
+export const UTILITY_CLASS_EVIDENCE_EXTENSIONS: readonly string[] = ['.css', '.html'];
+
+/** True when `path`'s content can carry evidence — the filter a directory walk uses. */
+export function isUtilityClassEvidenceFile(path: string): boolean {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  if (UTILITY_CLASS_EVIDENCE_FILES.includes(name)) return true;
+  return UTILITY_CLASS_EVIDENCE_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+
+/** Package names whose presence means a utility-class compiler is a dependency. */
+const UTILITY_PACKAGE_PREFIXES: readonly string[] = [
+  'tailwindcss',
+  '@tailwindcss/',
+  'unocss',
+  '@unocss/',
+];
+
+const CONFIG_FILE_RE = /(^|\/)(tailwind|uno|unocss)\.config\.[cm]?[jt]s$/;
+const PLUGIN_HOST_RE = /(^|\/)(postcss|vite|astro)\.config\.[cm]?[jt]s$/;
+const PLUGIN_MENTION_RE = /tailwindcss|unocss/;
+/** Tailwind v3 directives, the v4 css import, `@apply`, and UnoCSS's own entry. */
+const CSS_ENTRY_RE =
+  /@tailwind\s+(base|components|utilities|variants)|@import\s+['"](tailwindcss|unocss)|@apply\s|@unocss\b/;
+/** Interpreters that need no build step — the class is compiled in the page itself. */
+const RUNTIME_RE = /cdn\.tailwindcss\.com|@unocss\/runtime|unocss\/runtime/;
+
+function dependencyNames(packageJson: string): readonly string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(packageJson);
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== 'object') return [];
+  const names: string[] = [];
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!/dependencies$/i.test(key) || !value || typeof value !== 'object') continue;
+    names.push(...Object.keys(value as Record<string, unknown>));
+  }
+  return names;
+}
+
+/**
+ * Decide from gathered evidence. `files` maps a root-relative path to that
+ * file's text; a tier includes whatever it could read and omits the rest
+ * (absence is simply less evidence, never an error).
+ */
+export function detectUtilityClassSupport(files: ReadonlyMap<string, string>): UtilityClassSupport {
+  let dependency: string | null = null;
+  let config: string | null = null;
+  let plugin: string | null = null;
+  let cssEntry: string | null = null;
+  let runtime: string | null = null;
+
+  for (const [path, content] of files) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    if (name === 'package.json') {
+      const hit = dependencyNames(content).find((dep) =>
+        UTILITY_PACKAGE_PREFIXES.some((prefix) =>
+          prefix.endsWith('/') ? dep.startsWith(prefix) : dep === prefix,
+        ),
+      );
+      if (hit) dependency ??= `"${hit}" in ${path}`;
+      continue;
+    }
+    if (CONFIG_FILE_RE.test(path)) {
+      config ??= path;
+      continue;
+    }
+    if (PLUGIN_HOST_RE.test(path) && PLUGIN_MENTION_RE.test(content)) {
+      plugin ??= path;
+      continue;
+    }
+    if (name.endsWith('.css') && CSS_ENTRY_RE.test(content)) {
+      cssEntry ??= path;
+      continue;
+    }
+    if (name.endsWith('.html') && RUNTIME_RE.test(content)) runtime ??= path;
+  }
+
+  if (runtime) {
+    return { supported: true, evidence: `a utility-class runtime is loaded by ${runtime}` };
+  }
+  const wiring = config ?? plugin ?? cssEntry;
+  if (dependency && wiring) {
+    return { supported: true, evidence: `${dependency}, wired by ${wiring}` };
+  }
+  const partial = dependency
+    ? `${dependency} is declared but nothing wires it (no tailwind/uno config, no postcss/vite/astro plugin, no css entry)`
+    : wiring
+      ? `${wiring} mentions one but no tailwind/uno dependency is declared`
+      : 'no tailwind/uno dependency, config, css entry or CDN runtime';
+  return { supported: false, evidence: `${partial} — utility classes are not compiled here` };
+}

package/src/ui-source/write-component-default.ts

@@ -0,0 +1,133 @@
+/**
+ * Surgical native TypeScript edit for “Apply to Component”. The selected
+ * instance supplies a literal value; the OID index supplies the component
+ * declaration name. Only an existing literal destructuring default is
+ * writable — computed defaults are source-owned logic and are refused.
+ */
+
+import ts from 'typescript';
+import { parseAuthoringTsx } from './ts-ast';
+
+export interface ComponentDefaultEditResult {
+  readonly code: string;
+  readonly changed: boolean;
+  readonly dynamic: boolean;
+  readonly error?: string;
+}
+
+function componentParameter(node: ts.Node, componentName: string): ts.ParameterDeclaration | null {
+  if (ts.isFunctionDeclaration(node) && node.name?.text === componentName) {
+    return node.parameters[0] ?? null;
+  }
+  if (
+    ts.isVariableDeclaration(node) &&
+    ts.isIdentifier(node.name) &&
+    node.name.text === componentName &&
+    node.initializer &&
+    (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))
+  ) {
+    return node.initializer.parameters[0] ?? null;
+  }
+  return null;
+}
+
+function findComponentParameter(
+  node: ts.Node,
+  componentName: string,
+): ts.ParameterDeclaration | null {
+  const direct = componentParameter(node, componentName);
+  if (direct) return direct;
+  let nested: ts.ParameterDeclaration | null = null;
+  node.forEachChild((child) => {
+    if (!nested) nested = findComponentParameter(child, componentName);
+  });
+  return nested;
+}
+
+function stringReplacement(initializer: ts.Expression, value: string): string | null {
+  if (!ts.isStringLiteral(initializer) && !ts.isNoSubstitutionTemplateLiteral(initializer)) {
+    return null;
+  }
+  const quote = initializer.getText()[0];
+  if (quote === "'") {
+    return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n')}'`;
+  }
+  if (quote === '`') {
+    return `\`${value
+      .replaceAll('\\', '\\\\')
+      .replaceAll('`', '\\`')
+      .replaceAll('${', '\\${')
+      .replaceAll('\n', '\\n')}\``;
+  }
+  return JSON.stringify(value);
+}
+
+function literalReplacement(initializer: ts.Expression, value: string): string | null {
+  const stringLiteral = stringReplacement(initializer, value);
+  if (stringLiteral !== null) return stringLiteral;
+  if (
+    ts.isNumericLiteral(initializer) ||
+    (ts.isPrefixUnaryExpression(initializer) && ts.isNumericLiteral(initializer.operand))
+  ) {
+    return Number.isFinite(Number(value)) ? value : null;
+  }
+  if (
+    initializer.kind === ts.SyntaxKind.TrueKeyword ||
+    initializer.kind === ts.SyntaxKind.FalseKeyword
+  ) {
+    return value === 'true' || value === 'false' ? value : null;
+  }
+  if (ts.isArrayLiteralExpression(initializer)) {
+    const trimmed = value.trim();
+    return /^\[\s*-?(?:\d+(?:\.\d+)?|\.\d+)(?:\s*,\s*-?(?:\d+(?:\.\d+)?|\.\d+))*\s*\]$/.test(
+      trimmed,
+    )
+      ? trimmed
+      : null;
+  }
+  return null;
+}
+
+export function writeComponentDefault(
+  code: string,
+  fileName: string,
+  componentName: string,
+  prop: string,
+  value: string,
+): ComponentDefaultEditResult {
+  const source = parseAuthoringTsx(fileName, code);
+  const parameter = findComponentParameter(source, componentName);
+  if (!parameter || !ts.isObjectBindingPattern(parameter.name)) {
+    return {
+      code,
+      changed: false,
+      dynamic: true,
+      error: `${componentName} does not declare literal destructured defaults.`,
+    };
+  }
+  const binding = parameter.name.elements.find((element) => {
+    const authoredName = element.propertyName ?? element.name;
+    return ts.isIdentifier(authoredName) && authoredName.text === prop;
+  });
+  if (!binding?.initializer) {
+    return {
+      code,
+      changed: false,
+      dynamic: true,
+      error: `${componentName}.${prop} has no declared default initializer.`,
+    };
+  }
+  const replacement = literalReplacement(binding.initializer, value);
+  if (replacement === null) {
+    return {
+      code,
+      changed: false,
+      dynamic: true,
+      error: `${componentName}.${prop} uses a computed or incompatible default.`,
+    };
+  }
+  const start = binding.initializer.getStart(source);
+  const end = binding.initializer.getEnd();
+  const next = code.slice(0, start) + replacement + code.slice(end);
+  return { code: next, changed: next !== code, dynamic: false };
+}