@juspay/svelte-ui-components 3.2.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/svelte-ui-components",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "A themeable Svelte 5 UI component library with CSS custom property driven styling",
   "keywords": [
     "svelte",
@@ -27,7 +27,7 @@
     "package": "svelte-kit sync && svelte-package && publint",
     "prepublishOnly": "npm run build:wc && npm run package",
     "test": "npm run test:integration && npm run test:unit",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json && npm run check:codemod && npm run check:migrate",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json && npm run check:codemod && npm run check:migrate && npm run check:wc-parity",
     "check:codemod": "tsc -p scripts/codemod/tsconfig.json",
     "codemod": "node scripts/codemod/cli.ts",
     "check:wc": "svelte-check --tsconfig ./tsconfig.wc.json --compiler-warnings \"options_missing_custom_element:ignore\"",
@@ -40,7 +40,9 @@
     "test:visual": "scripts/visual-test.sh",
     "test:visual:update": "scripts/visual-test.sh --update-snapshots",
     "migrate": "node scripts/migrate/cli.ts",
-    "check:migrate": "tsc -p scripts/migrate/tsconfig.json"
+    "check:migrate": "tsc -p scripts/migrate/tsconfig.json",
+    "check:wc-parity": "tsc -p scripts/wc-parity/tsconfig.json",
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "exports": {
     ".": {
@@ -56,13 +58,17 @@
     "dist",
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*",
-    "dist-wc"
+    "dist-wc",
+    "scripts/codemod",
+    "!scripts/codemod/*.test.ts",
+    "scripts/postinstall.mjs"
   ],
   "peerDependencies": {
     "lottie-web": ">=5.0.0",
     "marked": "^18.0.0",
     "svelte": "^5.41.2",
-    "type-decoder": "^2.1.0"
+    "type-decoder": "^2.1.0",
+    "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "lottie-web": {
@@ -70,6 +76,9 @@
     },
     "marked": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -183,5 +192,11 @@
     "replaceText": {
       "(ABC-\\d+)": "[`$1`](https://juspay.atlassian.net/browse/$1)"
     }
+  },
+  "bin": {
+    "sui-codemod": "./scripts/codemod/cli.ts"
+  },
+  "engines": {
+    "node": ">=22.18"
   }
 }

package/scripts/codemod/README.md

@@ -0,0 +1,76 @@
+# polymorph → SUI consumer migration codemod
+
+Also reports the one breaking change in the 4.0.0 custom-element surface:
+`children` is no longer a declared property on `sui-chat-bubble`,
+`sui-draggable` or `sui-resizable`, so assigning it silently loses the content.
+That check runs on every forward migration and in dry runs, reports rather than
+rewrites (moving content into markup is a decision, not a rename), and only
+fires in files that also mention one of the three elements. See
+`wc-children.ts`.
+
+This package is published, so consumers can run it without a checkout:
+
+```sh
+npx sui-codemod --dry-run ./src
+```
+
+Mechanically migrates a consumer codebase from `polymorph-ui-components` to
+`@juspay/svelte-ui-components`:
+
+- rewrites import/export/dynamic-import specifiers (subpaths like `/wc` are
+  preserved), in `.svelte`, `.ts` and `.js` files;
+- renames the 28 synthetic event props (see `map.ts`) on library components in
+  `.svelte` markup. All but one differ from the fork only in case; Stepper's
+  `onhandlestepclick` becomes `onstepclick`, stepping over the deprecated
+  `onhandleStepClick` alias that the casing match would otherwise have picked.
+  Renaming is component-aware: `onsort` is renamed on a
+  `<Table>` imported from the library (through aliases,
+  `import { Table as DataTable }`, namespace imports and
+  `<svelte:component this={Table}>`), and left alone on your own components
+  and on native elements.
+
+## Usage
+
+Run from a checkout of this repo (dependencies resolve here), pointing at the
+consumer project. Requires Node >= 22.18 (runs TypeScript directly).
+
+```sh
+# preview
+npm run codemod -- --dry-run ../consumer-app/src
+
+# apply
+npm run codemod -- ../consumer-app/src
+
+# migrate in the other direction (SUI -> polymorph)
+npm run codemod -- --reverse ../consumer-app/src
+```
+
+Directories are walked recursively; `node_modules`, `.git`, `.svelte-kit`,
+`dist`, `dist-wc`, `build`, `coverage`, `playwright-report` and `test-results`
+are skipped.
+
+## What it will not do (by design)
+
+Anything it cannot prove safe is reported as a `WARN` with `file:line:column`
+instead of being rewritten — silent wrong rewrites are worse than reported
+skips:
+
+- **Spread attributes.** `<Table {...props} />` may carry a renamed prop
+  inside `props`; the object is defined elsewhere, so it is warned about, not
+  rewritten.
+- **Unresolvable components.** `const Picked = Table;` then
+  `<Picked onsort={...} />` — the tag does not resolve to an import, so a
+  warning is emitted when it carries a renameable prop name.
+- **Default imports** from the library cannot be resolved to a component.
+- **Semantic renames** — same event, different word — are not casing pairs
+  and need a human: Gallery `onclose`→`onDismiss`, `onchange`→`onIndexChange`;
+  MediaUpload `onchange`→`onFilesChange`, `onerror`→`onRejected`.
+- Props typed against library types in `<script>` (e.g. an object literal fed
+  to a spread) are not rewritten — the spread warning covers the usage site.
+
+Shorthand attributes are expanded when renamed (`{onsort}` →
+`onSort={onsort}`), so a `--reverse` round trip restores the original names
+but not the shorthand form.
+
+`map.ts` documents how the pair list was derived and verified against both
+libraries' sources.

package/scripts/codemod/cli.ts

@@ -0,0 +1,206 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import type { Direction } from './map.ts';
+import { transformModuleSpecifiers, transformSvelte } from './transform.ts';
+import type { TransformResult } from './transform.ts';
+import { findChildrenAssignments } from './wc-children.ts';
+
+export type CliSummary = {
+  readonly exitCode: number;
+  readonly filesScanned: number;
+  readonly filesChanged: number;
+  readonly propsRenamed: number;
+  readonly importsRewritten: number;
+  readonly warnings: number;
+};
+
+const USAGE = [
+  'Usage: node scripts/codemod/cli.ts [--reverse] [--dry-run] <path...>',
+  '',
+  'Migrates consumer sources from polymorph-ui-components to',
+  '@juspay/svelte-ui-components: rewrites import specifiers and renames the',
+  'casing-only synthetic event props on library components (see map.ts).',
+  '',
+  '  --reverse   migrate @juspay/svelte-ui-components -> polymorph-ui-components',
+  '  --dry-run   print every change as a diff without writing any file',
+  '  --help      show this help',
+  '',
+  'Paths may be files or directories; directories are walked recursively,',
+  'skipping node_modules, .git, .svelte-kit, dist, dist-wc, build, coverage,',
+  'playwright-report and test-results.'
+].join('\n');
+
+const SKIPPED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  '.svelte-kit',
+  'dist',
+  'dist-wc',
+  'build',
+  'coverage',
+  'playwright-report',
+  'test-results'
+]);
+
+const SCRIPT_FILE = /\.(ts|js|mts|mjs|cts|cjs)$/;
+
+function collectFiles(path: string, out: Set<string>): void {
+  const stats = statSync(path);
+  if (stats.isFile()) {
+    if (path.endsWith('.svelte') || SCRIPT_FILE.test(path)) {
+      out.add(path);
+    }
+    return;
+  }
+  if (!stats.isDirectory()) {
+    return;
+  }
+  const entries = [...readdirSync(path, { withFileTypes: true })].sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIPPED_DIRECTORIES.has(entry.name)) {
+        collectFiles(join(path, entry.name), out);
+      }
+    } else if (entry.isFile()) {
+      collectFiles(join(path, entry.name), out);
+    }
+  }
+}
+
+/**
+ * Every edit the transform makes stays on a single line, so old and new text
+ * always have the same line count and a pairwise comparison is an exact diff.
+ */
+function printLineDiff(
+  file: string,
+  before: string,
+  after: string,
+  log: (line: string) => void
+): void {
+  const oldLines = before.split('\n');
+  const newLines = after.split('\n');
+  log(`--- ${file}`);
+  if (oldLines.length !== newLines.length) {
+    log('  (line counts differ; showing full replacement)');
+    for (const line of oldLines) {
+      log(`- ${line}`);
+    }
+    for (const line of newLines) {
+      log(`+ ${line}`);
+    }
+    return;
+  }
+  oldLines.forEach((oldLine, index) => {
+    const newLine = newLines.at(index) ?? '';
+    if (oldLine !== newLine) {
+      log(`@@ ${file}:${index + 1}`);
+      log(`- ${oldLine}`);
+      log(`+ ${newLine}`);
+    }
+  });
+}
+
+export function runCodemod(argv: ReadonlyArray<string>, log: (line: string) => void): CliSummary {
+  const failure = {
+    exitCode: 2,
+    filesScanned: 0,
+    filesChanged: 0,
+    propsRenamed: 0,
+    importsRewritten: 0,
+    warnings: 0
+  };
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: [...argv],
+      options: {
+        reverse: { type: 'boolean' },
+        'dry-run': { type: 'boolean' },
+        help: { type: 'boolean' }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (error) {
+    log(error instanceof Error ? error.message : String(error));
+    log(USAGE);
+    return failure;
+  }
+  if (parsed.values.help === true) {
+    log(USAGE);
+    return { ...failure, exitCode: 0 };
+  }
+  if (parsed.positionals.length === 0) {
+    log(USAGE);
+    return failure;
+  }
+  for (const path of parsed.positionals) {
+    if (!existsSync(path)) {
+      log(`path does not exist: ${path}`);
+      return failure;
+    }
+  }
+  const direction: Direction = parsed.values.reverse === true ? 'to-poly' : 'to-sui';
+  const dryRun = parsed.values['dry-run'] === true;
+
+  const files = new Set<string>();
+  for (const path of parsed.positionals) {
+    collectFiles(resolve(path), files);
+  }
+
+  let filesChanged = 0;
+  let propsRenamed = 0;
+  let importsRewritten = 0;
+  let warnings = 0;
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8');
+    const result: TransformResult = file.endsWith('.svelte')
+      ? transformSvelte(source, file, direction)
+      : transformModuleSpecifiers(source, file, direction);
+    // Reported in both directions and in dry runs: it is a 4.0.0 breaking change
+    // to report, not a rename to apply, so it never contributes to filesChanged.
+    const childrenWarnings = direction === 'to-sui' ? findChildrenAssignments(source, file) : [];
+    for (const warning of [...result.warnings, ...childrenWarnings]) {
+      log(`${warning.file}:${warning.line}:${warning.column} WARN ${warning.message}`);
+    }
+    warnings += result.warnings.length + childrenWarnings.length;
+    if (!result.changed) {
+      continue;
+    }
+    filesChanged += 1;
+    propsRenamed += result.propsRenamed;
+    importsRewritten += result.importsRewritten;
+    if (dryRun) {
+      printLineDiff(file, source, result.code, log);
+    } else {
+      writeFileSync(file, result.code);
+      log(
+        `${file}: ${result.propsRenamed} prop(s) renamed, ${result.importsRewritten} import(s) rewritten`
+      );
+    }
+  }
+  log(
+    `${dryRun ? '[dry run] ' : ''}scanned ${files.size} file(s), changed ${filesChanged}, ` +
+      `renamed ${propsRenamed} prop(s), rewrote ${importsRewritten} import(s), ${warnings} warning(s)`
+  );
+  return {
+    exitCode: 0,
+    filesScanned: files.size,
+    filesChanged,
+    propsRenamed,
+    importsRewritten,
+    warnings
+  };
+}
+
+const entryPoint = process.argv.at(1) ?? '';
+if (entryPoint !== '' && import.meta.url === pathToFileURL(entryPoint).href) {
+  const summary = runCodemod(process.argv.slice(2), (line) => {
+    console.log(line);
+  });
+  process.exitCode = summary.exitCode;
+}

package/scripts/codemod/map.ts

@@ -0,0 +1,118 @@
+/**
+ * Casing-only prop pairs between this library (SUI) and its fork
+ * `polymorph-ui-components` (poly). Poly renamed synthesized event props to
+ * all-lowercase; these are the props whose names differ ONLY in case between
+ * the two libraries.
+ *
+ * Derived mechanically (not copied from docs): the `$props()` destructure of
+ * every component exported by both `src/lib/index.ts` (SUI @ release) and
+ * `dist/index.js` of polymorph-ui-components@0.7.0 was parsed with
+ * `svelte/compiler`, and a pair was accepted only when
+ * `lower(suiName) === lower(polyName)`, the names differ, and neither side
+ * also declares the other side's spelling (which would make a rewrite
+ * ambiguous or unnecessary). Cross-checked against each component's
+ * `properties.ts` / `properties.d.ts`.
+ *
+ * That derivation is deprecation-blind, and one pair had to be corrected by
+ * hand afterwards: where a component keeps a deprecated alias whose lowercase
+ * spelling matches the fork's, the alias wins the case-insensitive match and
+ * outranks the canonical prop. Stepper is the only such pair. `map.test.ts`
+ * now asserts no target is `@deprecated`, so a future alias cannot repeat it.
+ *
+ * Deliberately excluded (same event, different word — a semantic rename, not
+ * a casing pair; these need a human):
+ *   Gallery:     poly `onclose`  vs SUI `onDismiss`,  poly `onchange` vs SUI `onIndexChange`
+ *   MediaUpload: poly `onchange` vs SUI `onFilesChange`, poly `onerror` vs SUI `onRejected`
+ * Props spelled identically on both sides (e.g. `onkeydown` on ListItem or
+ * Modal) are intentionally absent: they need no rewrite. `onkeydown` on Input
+ * IS listed because SUI's Input only accepts `onKeyDown`.
+ */
+
+export type PropPair = {
+  readonly component: string;
+  readonly sui: string;
+  readonly poly: string;
+  /**
+   * Superseded SUI spellings that still work. Never a rewrite target, but
+   * recognized as a source when rewriting back to the fork.
+   */
+  readonly suiDeprecatedAliases?: readonly string[];
+};
+
+export const SUI_PACKAGE = '@juspay/svelte-ui-components';
+export const POLY_PACKAGE = 'polymorph-ui-components';
+
+export const PROP_PAIRS: ReadonlyArray<PropPair> = [
+  { component: 'Gallery', sui: 'onDeleteClick', poly: 'ondeleteclick' },
+  { component: 'Gallery', sui: 'onEditClick', poly: 'oneditclick' },
+  { component: 'Gallery', sui: 'onImageClick', poly: 'onimageclick' },
+  { component: 'Gallery', sui: 'onOpen', poly: 'onopen' },
+  { component: 'Input', sui: 'onBlur', poly: 'onblur' },
+  { component: 'Input', sui: 'onClick', poly: 'onclick' },
+  { component: 'Input', sui: 'onFocus', poly: 'onfocus' },
+  { component: 'Input', sui: 'onFocusout', poly: 'onfocusout' },
+  { component: 'Input', sui: 'onInput', poly: 'oninput' },
+  { component: 'Input', sui: 'onKeyDown', poly: 'onkeydown' },
+  { component: 'Input', sui: 'onPaste', poly: 'onpaste' },
+  { component: 'Input', sui: 'onStateChange', poly: 'onstatechange' },
+  { component: 'ListItem', sui: 'oncenterTextClick', poly: 'oncentertextclick' },
+  { component: 'ListItem', sui: 'onitemClick', poly: 'onitemclick' },
+  { component: 'ListItem', sui: 'onleftImageClick', poly: 'onleftimageclick' },
+  { component: 'ListItem', sui: 'onrightImageClick', poly: 'onrightimageclick' },
+  { component: 'ListItem', sui: 'ontopSectionClick', poly: 'ontopsectionclick' },
+  { component: 'MediaUpload', sui: 'onRemove', poly: 'onremove' },
+  { component: 'Modal', sui: 'onheaderLeftImageClick', poly: 'onheaderleftimageclick' },
+  { component: 'Modal', sui: 'onheaderRightImageClick', poly: 'onheaderrightimageclick' },
+  { component: 'Modal', sui: 'onoverlayClick', poly: 'onoverlayclick' },
+  { component: 'Modal', sui: 'onprimaryButtonClick', poly: 'onprimarybuttonclick' },
+  { component: 'Modal', sui: 'onsecondaryButtonClick', poly: 'onsecondarybuttonclick' },
+  // The lowercase match here is `onhandleStepClick`, which SUI deprecates in
+  // favour of `onstepclick`. Rewriting to the alias would be case-correct and
+  // still wrong: it is the one spelling of this event scheduled for removal.
+  {
+    component: 'Stepper',
+    sui: 'onstepclick',
+    poly: 'onhandlestepclick',
+    suiDeprecatedAliases: ['onhandleStepClick']
+  },
+  { component: 'Table', sui: 'onRowClick', poly: 'onrowclick' },
+  { component: 'Table', sui: 'onSort', poly: 'onsort' },
+  { component: 'Toast', sui: 'onToastHide', poly: 'ontoasthide' },
+  { component: 'Toolbar', sui: 'onbackClick', poly: 'onbackclick' }
+];
+
+export type Direction = 'to-sui' | 'to-poly';
+
+export type DirectionConfig = {
+  readonly fromPackage: string;
+  readonly toPackage: string;
+  /** component name -> (source prop name -> target prop name) */
+  readonly renames: ReadonlyMap<string, ReadonlyMap<string, string>>;
+  /** every source prop name across all components, for unresolved-tag warnings */
+  readonly allFromProps: ReadonlySet<string>;
+};
+
+export function directionConfig(direction: Direction): DirectionConfig {
+  const renames = new Map<string, Map<string, string>>();
+  const allFromProps = new Set<string>();
+  for (const pair of PROP_PAIRS) {
+    const table = renames.get(pair.component) ?? new Map<string, string>();
+    // Deprecated aliases are sources, never targets: a consumer moving to SUI
+    // lands on the canonical prop, while one moving back to the fork is
+    // recognized whichever spelling they are currently on.
+    const sources =
+      direction === 'to-sui' ? [pair.poly] : [pair.sui, ...(pair.suiDeprecatedAliases ?? [])];
+    const to = direction === 'to-sui' ? pair.sui : pair.poly;
+    for (const from of sources) {
+      table.set(from, to);
+      allFromProps.add(from);
+    }
+    renames.set(pair.component, table);
+  }
+  return {
+    fromPackage: direction === 'to-sui' ? POLY_PACKAGE : SUI_PACKAGE,
+    toPackage: direction === 'to-sui' ? SUI_PACKAGE : POLY_PACKAGE,
+    renames,
+    allFromProps
+  };
+}