@assure-one/design-system 1.35.0 → 1.36.0

package/codemods/transforms/cm-10-date-picker-value-change.mjs

@@ -0,0 +1,416 @@
+/**
+ * CM-10 — `DatePicker onChange={e => f(e.target.value)}` →
+ * `onValueChange={value => f(value)}` (class R; plan §29 seq 9, registry
+ * `C-DATE-FAKEEVENT`).
+ *
+ * W4-18 gave `DatePicker` the value callback of target architecture §25,
+ * `onValueChange(iso | null)`, and kept the legacy fake-event `onChange`
+ * (`{ target: { name, value } }`, `value` the ISO string or `""` when
+ * cleared) as a deprecated alias that fires after it. The event was never a
+ * DOM event: every consumer handler unwraps `.target.value` and nothing else,
+ * so the handlers whose shape makes that visible are rewritten and every
+ * other handler is listed for a human.
+ *
+ * ## What it rewrites
+ *
+ * Only an inline arrow function whose parameter is used **exclusively** as
+ * the value, in one of these shapes:
+ *
+ * | handler                                       | becomes                              |
+ * | --------------------------------------------- | ------------------------------------ |
+ * | `(e) => f(e.target.value)` (typed or not)      | `(value) => f(value)`                |
+ * | `e => setX(e.target.value)`                    | `value => setX(value)`               |
+ * | `({ target }) => f(target.value)`              | `(value) => f(value)`                |
+ * | `({ target: { value } }) => f(value)`          | `(value) => f(value)`                |
+ * | `() => refetch()`                              | unchanged body, attribute renamed    |
+ *
+ * The parameter is renamed `value` (`v`, then `next`, when the handler
+ * already binds that name); the body keeps its text and formatting, and only
+ * the `.target.value` accesses are replaced. `e.target.value` typed as a
+ * string becomes `string | null`: **a cleared picker now passes `null`, not
+ * `""`** — that is why the rewrite is reviewed (severity medium) and why a
+ * handler that reads a member of the value (`e.target.value.trim()`) is not
+ * rewritten: it would throw on clear.
+ *
+ * ## What it reports and leaves alone
+ *
+ * | rule                   | action  | severity | when                                                                                   |
+ * | ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
+ * | `fake-event-unwrapped` | applied | medium   | one of the shapes above was rewritten; confirm `null` on clear is what the state wants |
+ * | `handler-reference`    | review  | high     | the handler is passed by reference (`onChange={handleChange}`, `{field.onChange}`, a factory call): its body is elsewhere |
+ * | `handler-shape`        | review  | high     | an inline handler that reads more than `.target.value` (`e.target.name`, the event itself, a member of the value) or is not an arrow |
+ * | `has-value-change`     | review  | low      | `onValueChange` is already wired; `onChange` still fires after it — delete it by hand  |
+ * | `spread-props`         | review  | medium   | `{...props}` may carry either callback; which one wins depends on attribute order      |
+ *
+ * `DateRangePicker` is not touched: its `onChange` is already a value
+ * callback. Local components called `DatePicker` and test files are skipped,
+ * as by the scanner that measures C-DATE-FAKEEVENT.
+ */
+import { analyseForms } from "../lib/forms.mjs";
+import { applyEdits, attributeNamed, openingOf, renameAttribute } from "../lib/jsx-edit.mjs";
+
+export const meta = {
+  id: "CM-10",
+  title: "DatePicker: fake-event onChange → onValueChange",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-DATE-FAKEEVENT"],
+};
+
+/** The design-system components with the fake-event `onChange` (W4-18). */
+export const FAKE_EVENT_PICKERS = new Set(["DatePicker"]);
+
+export const LEGACY_PROP = "onChange";
+export const PROP = "onValueChange";
+
+/** Rule → what the report says a human must do with it. */
+export const RULES = {
+  "fake-event-unwrapped": { action: "applied", severity: "medium" },
+  "handler-reference": { action: "review", severity: "high" },
+  "handler-shape": { action: "review", severity: "high" },
+  "has-value-change": { action: "review", severity: "low" },
+  "spread-props": { action: "review", severity: "medium" },
+};
+
+const NAME_CANDIDATES = ["value", "v", "next"];
+
+const unparenthesize = (ts, node) => {
+  let current = node;
+  while (current && ts.isParenthesizedExpression(current)) current = current.expression;
+  return current;
+};
+
+/**
+ * Every identifier the node binds or reads, by text. Member names, object
+ * keys, JSX attribute names and destructuring keys are not bindings and are
+ * excluded.
+ */
+function identifierNames(ts, node, out = new Set(), skip = () => false) {
+  if (skip(node)) return out;
+  if (ts.isIdentifier(node)) {
+    const parent = node.parent;
+    const isMemberName = parent && ts.isPropertyAccessExpression(parent) && parent.name === node;
+    const isKey =
+      parent &&
+      (ts.isPropertyAssignment(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isJsxAttribute(parent)) &&
+      parent.name === node;
+    const isBindingKey = parent && ts.isBindingElement(parent) && parent.propertyName === node;
+    if (!isMemberName && !isKey && !isBindingKey) out.add(node.text);
+  }
+  ts.forEachChild(node, (child) => {
+    identifierNames(ts, child, out, skip);
+  });
+  return out;
+}
+
+/** Whether a nested function inside `node` binds `name` again (then a reference is ambiguous). */
+function rebinds(ts, node, name) {
+  let found = false;
+  const visit = (n) => {
+    if (found) return;
+    if (ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n)) {
+      for (const p of n.parameters) {
+        if (identifierNames(ts, p.name).has(name)) found = true;
+      }
+    }
+    if (ts.isVariableDeclaration(n) && identifierNames(ts, n.name).has(name)) found = true;
+    ts.forEachChild(n, visit);
+  };
+  visit(node);
+  return found;
+}
+
+/** The identifier references to `name` inside `node` (reads, not member names or keys). */
+function referencesTo(ts, node, name) {
+  const refs = [];
+  const visit = (n) => {
+    if (ts.isIdentifier(n) && n.text === name) {
+      const parent = n.parent;
+      const isMemberName = parent && ts.isPropertyAccessExpression(parent) && parent.name === n;
+      const isKey = parent && ts.isPropertyAssignment(parent) && parent.name === n;
+      // A shorthand property `{ e }` reads the binding.
+      if (!isMemberName && !isKey) refs.push(n);
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(node);
+  return refs;
+}
+
+const isAccessOf = (ts, node, member) =>
+  node && ts.isPropertyAccessExpression(node) && node.name.text === member;
+
+/**
+ * Whether the expression `node` is itself read further — a member, a call, an
+ * index — which would throw on `null`.
+ */
+function isReadFurther(ts, node) {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (ts.isPropertyAccessExpression(parent) && parent.expression === node) return true;
+  if (ts.isElementAccessExpression(parent) && parent.expression === node) return true;
+  if (ts.isCallExpression(parent) && parent.expression === node) return true;
+  if (ts.isNonNullExpression(parent)) return isReadFurther(ts, parent);
+  return false;
+}
+
+/**
+ * Classifies the handler expression of `onChange`.
+ *
+ * @returns {{ kind: "reference" } | { kind: "other", reason: string } |
+ *   { kind: "unwrap", shape: string, param: Node, name: string, keepName: boolean, values: Node[] }}
+ */
+export function analyseHandler(ts, expression) {
+  const expr = unparenthesize(ts, expression);
+  if (!expr) return { kind: "other", reason: "empty expression" };
+  if (
+    ts.isIdentifier(expr) ||
+    ts.isPropertyAccessExpression(expr) ||
+    ts.isElementAccessExpression(expr) ||
+    ts.isCallExpression(expr) ||
+    ts.isNonNullExpression(expr) ||
+    ts.isAsExpression(expr)
+  ) {
+    return { kind: "reference" };
+  }
+  if (ts.isFunctionExpression(expr)) {
+    return { kind: "other", reason: "a `function` expression; only arrow functions are rewritten" };
+  }
+  if (!ts.isArrowFunction(expr)) {
+    return { kind: "other", reason: "not an arrow function" };
+  }
+  if (expr.parameters.length === 0) {
+    return {
+      kind: "unwrap",
+      shape: "ignores-event",
+      param: null,
+      name: null,
+      keepName: false,
+      values: [],
+    };
+  }
+  if (expr.parameters.length > 1) {
+    return { kind: "other", reason: "more than one parameter" };
+  }
+  const param = expr.parameters[0];
+  if (param.dotDotDotToken || param.initializer) {
+    return { kind: "other", reason: "a rest or defaulted parameter" };
+  }
+
+  const body = expr.body;
+  /**
+   * The `.value` reads of the binding `local` inside the body. `depth` is how
+   * many member accesses separate the binding from the value: 2 for the event
+   * (`e.target.value`), 1 for the target (`target.value`), 0 for the value.
+   * Every read must be exactly that access and nothing beyond it.
+   */
+  const valueReads = (local, depth) => {
+    if (rebinds(ts, body, local))
+      return { reason: `\`${local}\` is bound again inside the handler` };
+    const values = [];
+    for (const ref of referencesTo(ts, body, local)) {
+      let node = ref;
+      for (const member of ["target", "value"].slice(2 - depth)) {
+        const access = node.parent;
+        if (!isAccessOf(ts, access, member) || access.expression !== node) {
+          return {
+            reason: `reads \`${node.getText()}\` as more than \`${node.getText()}.${member}\``,
+          };
+        }
+        node = access;
+      }
+      if (isReadFurther(ts, node)) {
+        return {
+          reason: `reads a member of the value (\`${node.parent.getText()}\`); the new callback passes \`null\` when cleared`,
+        };
+      }
+      values.push(node);
+    }
+    return { values };
+  };
+
+  if (ts.isIdentifier(param.name)) {
+    const local = param.name.text;
+    const result = valueReads(local, 2);
+    if (result.reason) return { kind: "other", reason: result.reason };
+    return {
+      kind: "unwrap",
+      shape: result.values.length ? "event-target-value" : "ignores-event",
+      param,
+      name: local,
+      keepName: false,
+      values: result.values,
+    };
+  }
+
+  if (ts.isObjectBindingPattern(param.name)) {
+    const elements = param.name.elements;
+    if (elements.length !== 1) return { kind: "other", reason: "destructures more than `target`" };
+    const [element] = elements;
+    if (element.dotDotDotToken || element.initializer) {
+      return { kind: "other", reason: "a rest or defaulted destructuring" };
+    }
+    const key = element.propertyName ? element.propertyName.getText() : element.name.getText();
+    if (key !== "target")
+      return { kind: "other", reason: `destructures \`${key}\`, not \`target\`` };
+
+    if (ts.isIdentifier(element.name)) {
+      // `({ target })` or `({ target: t })`: every read must be `t.value`.
+      const result = valueReads(element.name.text, 1);
+      if (result.reason) return { kind: "other", reason: result.reason };
+      return {
+        kind: "unwrap",
+        shape: "target-value",
+        param,
+        name: element.name.text,
+        keepName: false,
+        values: result.values,
+      };
+    }
+    if (ts.isObjectBindingPattern(element.name)) {
+      // `({ target: { value } })` or `({ target: { value: v } })`.
+      const inner = element.name.elements;
+      if (inner.length !== 1 || inner[0].dotDotDotToken || inner[0].initializer) {
+        return { kind: "other", reason: "destructures more than `target.value`" };
+      }
+      const innerKey = inner[0].propertyName
+        ? inner[0].propertyName.getText()
+        : inner[0].name.getText();
+      if (innerKey !== "value" || !ts.isIdentifier(inner[0].name)) {
+        return {
+          kind: "other",
+          reason: `destructures \`target.${innerKey}\`, not \`target.value\``,
+        };
+      }
+      const local = inner[0].name.text;
+      const result = valueReads(local, 0);
+      if (result.reason) return { kind: "other", reason: result.reason };
+      return {
+        kind: "unwrap",
+        shape: "destructured-value",
+        param,
+        name: local,
+        keepName: true,
+        values: [],
+      };
+    }
+  }
+  return { kind: "other", reason: "an unrecognised parameter shape" };
+}
+
+/**
+ * A parameter name that nothing in the enclosing function (the component
+ * rendering the picker) binds or reads, so the new parameter shadows
+ * nothing: `value`, else `v`, else `next`.
+ */
+export function freshName(ts, arrow) {
+  const isFunction = (n) =>
+    ts.isArrowFunction(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isFunctionDeclaration(n) ||
+    ts.isMethodDeclaration(n);
+  const ancestors = new Set([arrow]);
+  let scope = arrow.parent;
+  while (scope && !ts.isSourceFile(scope) && !isFunction(scope)) {
+    ancestors.add(scope);
+    scope = scope.parent;
+  }
+  // Sibling functions bind their own names; what they read is bound in the
+  // scope and seen at its declaration.
+  const used = identifierNames(
+    ts,
+    scope ?? arrow,
+    new Set(),
+    (n) => isFunction(n) && n !== scope && !ancestors.has(n),
+  );
+  return NAME_CANDIDATES.find((name) => !used.has(name)) ?? "nextValue";
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const findings = [];
+  const edits = [];
+
+  for (const el of facts.elements) {
+    if (!el.isDs || !FAKE_EVENT_PICKERS.has(el.base) || el.component !== el.base) continue;
+    const legacy = el.props.get(LEGACY_PROP);
+    if (!legacy) continue;
+
+    const base = {
+      registryId: "C-DATE-FAKEEVENT",
+      match: `<${el.tag} ${LEGACY_PROP}>`,
+      component: el.component,
+      gate: null,
+    };
+    const review = (rule, detail) =>
+      findings.push({ ...base, line: legacy.line, rule, ...RULES[rule], detail });
+
+    if (el.props.has(PROP)) {
+      review("has-value-change", {
+        reason: `\`${PROP}\` is already passed; delete \`${LEGACY_PROP}\``,
+      });
+      continue;
+    }
+    if (el.spread) {
+      review("spread-props", { reason: `the spread may carry \`${LEGACY_PROP}\` or \`${PROP}\`` });
+      continue;
+    }
+
+    const opening = openingOf(ts, el.node);
+    const attr = attributeNamed(ts, opening, LEGACY_PROP);
+    const init = attr?.initializer;
+    const expression = init && ts.isJsxExpression(init) ? init.expression : null;
+    if (!expression) {
+      review("handler-shape", { reason: "no handler expression" });
+      continue;
+    }
+    const handler = analyseHandler(ts, expression);
+    if (handler.kind === "reference") {
+      review("handler-reference", { handler: expression.getText(facts.sf) });
+      continue;
+    }
+    if (handler.kind === "other") {
+      review("handler-shape", { reason: handler.reason });
+      continue;
+    }
+
+    const arrow = unparenthesize(ts, expression);
+    const name = handler.keepName ? handler.name : freshName(ts, arrow);
+    edits.push(renameAttribute(ts, facts.sf, opening, LEGACY_PROP, PROP));
+    if (handler.param) {
+      edits.push({
+        pos: handler.param.getStart(facts.sf),
+        end: handler.param.getEnd(),
+        text: name,
+      });
+    }
+    for (const valueNode of handler.values) {
+      edits.push({ pos: valueNode.getStart(facts.sf), end: valueNode.getEnd(), text: name });
+    }
+    findings.push({
+      ...base,
+      line: legacy.line,
+      rule: "fake-event-unwrapped",
+      ...RULES["fake-event-unwrapped"],
+      detail: {
+        shape: handler.shape,
+        param: name,
+        cleared: 'the new callback passes `null` where `onChange` passed `""`',
+      },
+    });
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-14-hidden-mirrors.mjs

@@ -97,9 +97,9 @@ export const NAME_CAPABILITY = {
   SearchSelect: "planned", // W4-12 (adapter over Combobox)
   TeamMemberSelect: "planned", // W4-08/W4-12
   MultiSelectField: "planned", // W4-08
-  ToggleGroup: "planned", // W4-16
+  ToggleGroup: "yes", // W4-16: FormBridge (`name?: string`)
   PhoneCountryInput: "planned", // W4-04
-  OtpInput: "planned", // W4-04
+  OtpInput: "yes", // src/primitives/otp-input.tsx — the `input-otp` input carries `name` (optional since W4-23: a Field can supply it)
   Questions: "planned", // W4-04 (answer widgets)
 };