FormidableLabs / FormidableLabs/react-live

docs/api.md documents props as `PropTypes`, and several entries are wrong

Offen
#419 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
TypeScript
Sterne
4.6k
Forks
260
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

`docs/api.md` types every prop as `PropTypes.string`, `PropTypes.bool`, and so on — 16 rows
across four tables. There is no `prop-types` dependency in the repo. The props are
TypeScript, so the notation describes runtime validation that does not happen.

The file is already inconsistent with itself: the `withLive()` table types `element` as
`React.Element`, which is not a real type either (`React.ReactElement`).

Auditing the tables to convert them turned up three entries that are wrong on the facts, not
just the notation.

### `language` default is documented as `jsx`

```
| language | `PropTypes.string` | ... (Default: `jsx`) |
```

`LiveProvider` defaults it to `tsx`:

```ts
language = "tsx",
```

### `LivePreview`'s `Component` is not a node

Documented as `PropTypes.node`. It is `React.ElementType` — a tag name or component, not
rendered output. `node` would be the wrong choice even in PropTypes terms (`elementType`).

### `transformCode`'s declared type contradicts its own call site

The docs say "accepts and returns the code to be transpiled", which matches what
`LiveProvider` actually does:

```ts
const transformResult = transformCode ? transformCode(newCode) : newCode;
const transformedCode = await Promise.resolve(transformResult);
if (typeof transformedCode !== "string") {
throw new Error("Code failed to transform");
}
```

The type says the return value is discarded:

```ts
transformCode?(code: string): void;
```

Here the docs are right and the source is wrong. TypeScript permits returning a value where
`void` is expected, so callers are not broken — but anyone reading the declarations sees a
mutator. Should be `string | Promise`.

### Order

1. Fix `transformCode`'s return type. Separate from the docs work: it ships in the published
declarations and needs a changeset.
2. Convert the four tables to TypeScript types, correcting `language`, `Component`, and
`element` along the way.
3. While in there, `LiveEditor` takes `Partial`, so the three documented props
are not its whole surface.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit docs/api.md und prüfe die vier Prop-Tabellen anhand der TypeScript-Deklarationen und der transformCode-Aufrufstelle von LiveProvider. Aktualisiere die dokumentierten Typen und Standardwerte, korrigiere den Rückgabetyp von transformCode und berücksichtige die Partial-Oberfläche von LiveEditor. Für die veröffentlichte Deklarationsänderung ist ein Changeset erforderlich.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
react, typescript
Bereich
documentation, frontend
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
55/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.