@lariocpt/flawless-react 0.0.0-stage → 0.3.0

package/src/analyse/hostProps.ts

@@ -0,0 +1,185 @@
+import type { PropsShape, PropValue } from "../types.ts";
+
+/**
+ * A curated, closed table of host-element props — deliberately NOT a model of
+ * the DOM. `ComponentProps<"div">` is the dominant props shape in shadcn/base-ui
+ * codebases, and without this every such component synthesises zero props and
+ * gets an assertion-free smoke test.
+ *
+ * Three rules are baked in, each because breaking them produces *false test
+ * failures* rather than missing coverage:
+ *
+ * 1. Never synthesise `value`/`checked` — a value without an onChange makes
+ *    React warn about a controlled input and turns `userEvent.type` into a
+ *    silent no-op. Always `defaultValue`.
+ * 2. Never synthesise `placeholder`/`name`/`required` — an empty-string default
+ *    is useless to the scaffolder and `getByPlaceholderText("")` throws.
+ * 3. `type` is always a valid literal, never `""` — `<button type="">` is
+ *    invalid HTML.
+ */
+
+export interface HostElementProps {
+  shape: PropsShape;
+  variantOptions?: Record<string, PropValue[]>;
+  acceptsChildren: boolean;
+  /** Implicit ARIA role, only where unambiguous. */
+  role?: string;
+  /** Handler props the scaffolder stubs with vi.fn(). */
+  handlers: string[];
+}
+
+/** Present on every HTML element — safe for any tag, known or not. */
+const BASE: PropsShape = { className: "", id: "" };
+
+export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+const CONTAINER_TAGS = [
+  "div",
+  "span",
+  "p",
+  "section",
+  "article",
+  "header",
+  "footer",
+  "main",
+  "aside",
+  "figure",
+  "blockquote",
+  "table",
+  "thead",
+  "tbody",
+  "tr",
+  "td",
+  "th",
+  "dl",
+  "dt",
+  "dd",
+  "pre",
+  "code",
+  "em",
+  "strong",
+  "small",
+  "fieldset",
+  "legend",
+];
+
+function container(role?: string): HostElementProps {
+  return { shape: { ...BASE }, acceptsChildren: true, handlers: [], ...(role ? { role } : {}) };
+}
+
+const TABLE: Record<string, HostElementProps> = {};
+for (const tag of CONTAINER_TAGS) TABLE[tag] = container();
+
+TABLE.nav = container("navigation");
+TABLE.ul = container("list");
+TABLE.ol = container("list");
+TABLE.li = container("listitem");
+for (const h of ["h1", "h2", "h3", "h4", "h5", "h6"]) TABLE[h] = container("heading");
+
+TABLE.label = {
+  shape: { ...BASE, htmlFor: "" },
+  acceptsChildren: true,
+  handlers: [],
+};
+
+TABLE.button = {
+  shape: { ...BASE, type: "button", disabled: false },
+  variantOptions: { type: ["button", "submit", "reset"] },
+  acceptsChildren: true,
+  role: "button",
+  handlers: ["onClick"],
+};
+
+TABLE.a = {
+  shape: { ...BASE, href: "/" },
+  acceptsChildren: true,
+  role: "link",
+  handlers: ["onClick"],
+};
+
+TABLE.input = {
+  shape: { ...BASE, type: "text", defaultValue: "", disabled: false },
+  variantOptions: { type: ["text", "email", "password", "number"] },
+  acceptsChildren: false,
+  role: "textbox",
+  handlers: ["onChange"],
+};
+
+TABLE.textarea = {
+  shape: { ...BASE, defaultValue: "", disabled: false, rows: 3 },
+  acceptsChildren: false,
+  role: "textbox",
+  handlers: ["onChange"],
+};
+
+TABLE.select = {
+  shape: { ...BASE, defaultValue: "", disabled: false },
+  acceptsChildren: true,
+  role: "combobox",
+  handlers: ["onChange"],
+};
+
+TABLE.form = {
+  shape: { ...BASE },
+  acceptsChildren: true,
+  role: "form",
+  handlers: ["onSubmit"],
+};
+
+TABLE.img = {
+  shape: { ...BASE, src: "/flawless.png", alt: "placeholder" },
+  acceptsChildren: false,
+  role: "img",
+  handlers: [],
+};
+
+for (const tag of ["svg", "path", "circle", "rect", "g"]) {
+  TABLE[tag] = {
+    shape: { ...BASE },
+    acceptsChildren: !VOID_ELEMENTS.has(tag),
+    handlers: [],
+  };
+}
+
+export const HOST_ELEMENT_PROPS: Readonly<Record<string, HostElementProps>> = TABLE;
+
+/** Tag → implicit ARIA role, shared with the selector emitters so they cannot drift. */
+export const TAG_TO_ROLE: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(TABLE)
+    .filter(([, v]) => v.role !== undefined)
+    .map(([k, v]) => [k, v.role as string]),
+);
+
+export function isHostTagRecognised(tag: string): boolean {
+  return tag in TABLE;
+}
+
+/**
+ * Never undefined. An unknown tag still gets `className`/`id` (present on every
+ * HTML element) and a children flag from the closed void-element list — both
+ * are facts about HTML, not guesses about this component.
+ */
+export function hostPropsFor(tag: string): HostElementProps {
+  const known = TABLE[tag];
+  if (known) return { ...known, shape: { ...known.shape } };
+  return {
+    shape: { ...BASE },
+    acceptsChildren: !VOID_ELEMENTS.has(tag),
+    handlers: [],
+  };
+}

package/src/analyse/hostTag.ts

@@ -0,0 +1,72 @@
+import { detectHostDialect, type HostDialect } from "./nativeDialect.ts";
+import { nativeElementFor } from "./nativeProps.ts";
+import type { ImportBinding } from "./parseFile.ts";
+
+/**
+ * Whether a JSX tag names a host element, and which one.
+ *
+ * ONE predicate, replacing the `/^[a-z][a-z0-9-]*$/` test that was written out
+ * five times — extractRootTag, extractRenderMode, extractFlows, extractChildAttrs
+ * and selectors.ts. Five copies of a rule is the defect class this project keeps
+ * finding in its own docs, and it was about to become ten.
+ *
+ * The rule is EVIDENCE-BASED in both directions:
+ *
+ *   - lowercase          -> a DOM intrinsic. Byte-identical to the old test.
+ *   - Capitalised        -> a host element IF AND ONLY IF this file imports that
+ *                           name from a specifier in the closed native table.
+ *   - anything else      -> undefined, meaning "this is a component" — exactly
+ *                           the state every uppercase tag is in today.
+ *
+ * Never a guess from the name. `<IconButton>` is not a button, `<TicketRow>` is
+ * not a row, and shadcn's `<ButtonPrimitive>` must keep answering undefined on
+ * the web path or the DOM regression this predicate was extracted from returns.
+ */
+export interface ResolvedHostTag {
+  /**
+   * The canonical element name: the MODULE-SIDE export, never the local alias.
+   *
+   * `import { View as Box }` gives tag "Box" and name "View". This is the same
+   * refusal extractRootTag already makes for `<UI.Badge/>` — "Badge" and
+   * "UI.Badge" are both lies about the emitted element — applied in the other
+   * direction, and it is what makes rootTag comparable across files.
+   */
+  name: string;
+  dialect: HostDialect;
+}
+
+export type HostTagResolver = (tag: string) => ResolvedHostTag | undefined;
+
+const LOWERCASE_INTRINSIC = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Today's rule, exactly: lowercase intrinsics only.
+ *
+ * The default everywhere, so every existing call site behaves byte-identically
+ * until it is handed a native resolver on purpose.
+ */
+export const domOnlyResolver: HostTagResolver = (tag) =>
+  LOWERCASE_INTRINSIC.test(tag) ? { name: tag, dialect: "dom" } : undefined;
+
+/**
+ * A resolver for one file, built from that file's own imports.
+ *
+ * Returns `domOnlyResolver` unchanged for a DOM file — not a wrapper around it,
+ * the same function object — so the web path cannot pick up so much as an extra
+ * closure.
+ */
+export function makeHostTagResolver(imports: Map<string, ImportBinding>): HostTagResolver {
+  if (detectHostDialect(imports) === "dom") return domOnlyResolver;
+  return (tag) => {
+    // A lowercase tag in a React Native file is still a DOM intrinsic as far as
+    // this predicate is concerned. It cannot render on a device, but saying so
+    // is extractRenderMode's job, not this one's.
+    if (LOWERCASE_INTRINSIC.test(tag)) return { name: tag, dialect: "dom" };
+    if (!/^[A-Z]/.test(tag)) return undefined;
+    const binding = imports.get(tag);
+    if (!binding || binding.isTypeOnly || binding.kind === "namespace") return undefined;
+    const exported = binding.importedName ?? tag;
+    if (nativeElementFor(binding.specifier, exported) === undefined) return undefined;
+    return { name: exported, dialect: "native" };
+  };
+}

package/src/analyse/htmlContentModel.ts

@@ -0,0 +1,94 @@
+/**
+ * Facts about HTML's content model that a generated harness has to respect.
+ *
+ * This is not inference about the analysed app — it is the specification. A
+ * `<tbody>` is only valid inside a `<table>`, so mounting `TableBody` straight
+ * into the host's `#root` div made React 19 log
+ *
+ *   In HTML, <tbody> cannot be a child of <div>. This will cause a hydration error.
+ *
+ * on seven of the dogfood app's table primitives. The spec then failed them for
+ * a warning the harness itself provoked. Wrapping the mount in the required
+ * ancestors keeps those components covered instead of excluding them, and it is
+ * a lookup rather than a guess.
+ */
+
+/** Ancestors a tag must be nested in, outermost first. */
+const REQUIRED_ANCESTORS: Record<string, string[]> = {
+  thead: ["table"],
+  tbody: ["table"],
+  tfoot: ["table"],
+  caption: ["table"],
+  colgroup: ["table"],
+  col: ["table", "colgroup"],
+  tr: ["table", "tbody"],
+  td: ["table", "tbody", "tr"],
+  th: ["table", "tbody", "tr"],
+  option: ["select"],
+  optgroup: ["select"],
+  li: ["ul"],
+  dt: ["dl"],
+  dd: ["dl"],
+  figcaption: ["figure"],
+  legend: ["fieldset"],
+  source: ["video"],
+  track: ["video"],
+  area: ["map"],
+  param: ["object"],
+  summary: ["details"],
+};
+
+/**
+ * The chain a component's root tag must be mounted inside, or [] when it can
+ * stand alone. Unknown tags (every component name, every custom element) return
+ * [] — the harness only wraps where HTML demands it.
+ */
+export function requiredAncestors(rootTag: string | undefined): string[] {
+  if (!rootTag) return [];
+  return REQUIRED_ANCESTORS[rootTag] ?? [];
+}
+
+/** Elements a user can type into. Anything else rejects .fill()/.type() outright. */
+const FILLABLE_TAGS = new Set(["input", "textarea", "select"]);
+
+/**
+ * Whether a change/input event target is something a test can type into.
+ *
+ * React's onChange bubbles, so it is idiomatic to put it on the `<form>` and
+ * read `event.target`. Driving that literally emitted
+ * `page.locator("form").fill("x")`, which Playwright rejects with "Element is
+ * not an <input>, <textarea>, <select> or [contenteditable]" — the generator
+ * describing event delegation as if it were a text box.
+ */
+export function isFillableTag(tag: string): boolean {
+  return FILLABLE_TAGS.has(tag);
+}
+
+/** Input types that hold no user-suppliable text (or none a blind fill can supply). */
+const UNFILLABLE_INPUT_TYPES = new Set([
+  "hidden",
+  "checkbox",
+  "radio",
+  "file",
+  "image",
+  "submit",
+  "reset",
+  "button",
+  "range",
+  "color",
+]);
+
+export type FillKind = "text" | "toggle" | "select" | "skip";
+
+/** How (or whether) a form field can be driven, from its tag and type alone. */
+export function fillKind(tag: string, type: string | undefined): FillKind {
+  if (tag === "select") return "select";
+  if (tag === "textarea") return "text";
+  if (tag !== "input") return "skip";
+  if (!type) return "text";
+  if (type === "checkbox" || type === "radio") return "toggle";
+  // A hidden input carries a value the component chose; typing into it asserts
+  // nothing and, when several share a name, cannot even be addressed uniquely.
+  if (UNFILLABLE_INPUT_TYPES.has(type)) return "skip";
+  return "text";
+}