FormidableLabs / FormidableLabs/react-live

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

Open
#419 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4.6k
Forks
260
PR merge metrics
No merged PRs in 30d

Description

`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.

Contributor guide

Open the contributing guide

Research direction

Start with docs/api.md and audit its four prop tables against the TypeScript declarations and the LiveProvider transformCode call site. Update the documented types and defaults, correct the transformCode return type, and account for LiveEditor’s Partial surface. A changeset is needed for the published declaration change.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
documentation, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.