Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .changeset/uncontrolled-wrappers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@oneschema/react": major
"@oneschema/vue": major
"@oneschema/angular": major
---

Let the wrappers manage the importer's visibility, and register the React listeners once

`isOpen` is now optional on `<OneSchemaImporter />`. Omit it and the component runs uncontrolled: the host launches through the component's `ref` — `launch()` returns the importer's promise, plus `close()` and `status` — and the importer closes itself when the import completes, the user cancels, or a fatal error occurs. Supplying `isOpen` keeps today's controlled behavior unchanged, including `onRequestClose`, which is only called in that mode.

React handlers are read through a ref, so the listeners are registered once per importer instead of being torn off with `removeAllListeners()` and re-registered whenever an inline handler's identity changes. That re-registration dropped listeners the importer was in the middle of emitting to, which is what made an `onSuccess` defined inline in the render body miss a `success` that landed on the same commit. `onSuccess` and `onCancel` may now return a promise, which the importer awaits before it closes the session. The duplicate-launch warning keys off the importer's `status` rather than the serialized launch params, so it no longer fires for a re-render that changed nothing.

The Vue plugin destroys its importer when the app unmounts, releasing the window message listener and, under `manageDOM`, the iframe; `useOneSchemaImporter()` throws a named error when the plugin was never installed instead of returning `undefined` typed as an importer. Vue and Angular were already uncontrolled — they hand the core importer to the host — so their only behavior change is that `launch()` now returns a promise: `@oneschema/angular`'s `OneSchemaButton` handles its rejection rather than leaving it unhandled, and a host that calls `launch()` itself has to do the same.
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { OneSchemaService } from './oneschema.service'

@Component({
selector: 'lib-oneschema-button',
template: `<button id="oneschema-launch-button" (click)="oneschema.launch()">
template: `<button id="oneschema-launch-button" (click)="launch()">
Open OneSchema
</button>`,
styles: [],
Expand All @@ -12,4 +12,10 @@ import { OneSchemaService } from './oneschema.service'
// eslint-disable-next-line @angular-eslint/component-class-suffix
export class OneSchemaButton {
constructor(public oneschema: OneSchemaService) {}

launch() {
// Launch failures reach the host through the launched and error events, so
// the rejection has no other reader here.
this.oneschema.launch().catch(() => undefined)
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ export class OneSchemaButtonComponent {
constructor(public oneschema: OneSchemaService) {}

launch() {
this.oneschema.launch()
this.oneschema.launch().catch((failure) => {
// handle the launch failure; the launched and error events report it too
console.error(failure)
})
}
}

Expand Down
95 changes: 76 additions & 19 deletions packages/importer-react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,51 @@ The importer class this component wraps extends `EventEmitter` from `eventemitte

### Sample usage

Omit `isOpen` and the importer manages its own visibility: launch it through the
component's ref, and it closes itself when the import completes, the user
cancels, or a fatal error occurs.

```javascript
import React, { useRef } from "react"
import OneSchemaImporter from "@oneschema/react"

function OneSchemaExample() {
const importer = useRef(null)

const launch = async () => {
try {
const { embedId } = await importer.current.launch()
console.log(embedId)
} catch (failure) {
console.error(failure)
}
}

return (
<div>
<button onClick={launch}>Import</button>

<OneSchemaImporter
ref={importer}
clientId={clientId}
userJwt={token}
templateKey={templateKey}
importConfig={{ type: "local", metadataOnly: false }}
onSuccess={async (data) => {
/* the importer stays open until this resolves */
await saveRows(data)
}}
onCancel={() => console.log("cancelled")}
onError={(error) => console.log(error)}
/>
</div>
)
}
```

Supplying `isOpen` opts into controlled visibility instead: your application
owns the flag, and the importer asks to be closed through `onRequestClose`.

```javascript
import React, { useState } from "react"
import OneSchemaImporter from "@oneschema/react"
Expand Down Expand Up @@ -86,30 +131,42 @@ params.

<!-- BEGIN GENERATED react-props -->

| Prop | Type | Required | Default | Description |
| ---------------- | ----------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isOpen` | `boolean` | yes | | Whether to show the iframe or not |
| `inline` | `boolean` | | `true` | Whether the iframe should be rendered in the component tree. When false, the iframe is appended to document.body |
| `clientId` | `string` | yes | | The client id from your OneSchema developer dashboard |
| `className` | `string` | | | CSS class for the iframe |
| `devMode` | `boolean` | | | Whether to launch the importer in dev mode, which shows the iframe even when launching fails |
| `languageCode` | `string` | | | Language code (like 'en' or 'zh') to force the importer language. By default, uses the user's set language. Requires enterprise licensing |
| `saveSession` | `boolean` | | | Whether to save session information to local storage and enable resuming |
| `baseUrl` | `string` | | | The base URL for the iframe. By default uses OneSchema's production instance |
| `style` | `React.CSSProperties` | | | CSS styles that should be applied to the iframe |
| `onRequestClose` | `() => void` | | | Handler for when the importer wants to close should set isOpen prop to false |
| `onSuccess` | `(data: OneSchemaImportResult) => void` | | | Handler for when the importing flow completes successfully |
| `onCancel` | `() => void` | | | Handler for when the importing flow is cancelled by user |
| `onError` | `(error: OneSchemaError) => void` | | | Handler for when an error occurs during the import |
| `onPageLoad` | `() => void` | | | Handler for when the embedded Importer page is loaded behind the scenes. |
| `onLaunched` | `(result: OneSchemaLaunchStatus) => void` | | | Handler for when the importer is launched (aka is ready to be shown) Or when launching fails, based on result |
| `onUserActivity` | `() => void` | | | Handler for when user activity is detected inside the importer iframe. Useful for resetting session idle timers in the host application. This event is throttled (fired at most once every 30 seconds). |
| Prop | Type | Required | Default | Description |
| ------------------ | -------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isOpen` | `boolean` | | | Whether to show the iframe or not. Omit it to let the importer manage its own visibility: it then closes itself when the import completes, the user cancels, or a fatal error occurs, and the host launches it through the component's `ref` |
| `inline` | `boolean` | | `true` | Whether the iframe should be rendered in the component tree. When false, the iframe is appended to document.body |
| `clientId` | `string` | yes | | The client id from your OneSchema developer dashboard |
| `className` | `string` | | | CSS class for the iframe |
| `devMode` | `boolean` | | | Whether to launch the importer in dev mode, which shows the iframe even when launching fails |
| `languageCode` | `string` | | | Language code (like 'en' or 'zh') to force the importer language. By default, uses the user's set language. Requires enterprise licensing |
| `saveSession` | `boolean` | | | Whether to save session information to local storage and enable resuming |
| `baseUrl` | `string` | | | The base URL for the iframe. By default uses OneSchema's production instance |
| `initTimeoutMs` | `number` | | | How long a launch may stay pending before it fails with `OneSchemaLaunchError.Timeout`, in milliseconds. Raise it for hosts on slow or distant connections. Defaults to 20000 |
| `handlerTimeoutMs` | `number` | | | How long the importer waits for `onSuccess` and `onCancel` to settle before it clears the resume token and closes, in milliseconds. Raise it for handlers that ship rows to a slow or distant backend. `0` waits forever. Defaults to 30000 |
| `style` | `React.CSSProperties` | | | CSS styles that should be applied to the iframe |
| `onRequestClose` | `() => void` | | | Handler for when the importer wants to close should set isOpen prop to false. Only called when `isOpen` is supplied |
| `onSuccess` | `(data: OneSchemaImportResult) => void \| Promise<void>` | | | Handler for when the importing flow completes successfully. The importer waits for a returned promise to settle before it closes |
| `onCancel` | `() => void \| Promise<void>` | | | Handler for when the importing flow is cancelled by user. The importer waits for a returned promise to settle before it closes |
| `onError` | `(error: OneSchemaError) => void` | | | Handler for when an error occurs during the import |
| `onPageLoad` | `() => void` | | | Handler for when the embedded Importer page is loaded behind the scenes. |
| `onLaunched` | `(result: OneSchemaLaunchStatus) => void` | | | Handler for when the importer is launched (aka is ready to be shown) Or when launching fails, based on result |
| `onUserActivity` | `() => void` | | | Handler for when user activity is detected inside the importer iframe. Useful for resetting session idle timers in the host application. This event is throttled (fired at most once every 30 seconds). |

<!-- END GENERATED react-props -->

### Ref handle

| Member | Type | Description |
| -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `launch` | `(overrides?) => Promise<OneSchemaLaunchInfo>` | Launches the importer, resolving once the session is running and rejecting with a `OneSchemaLaunchFailure` when it cannot start, or with a plain `Error` before the component has mounted its importer |
| `close` | `(clean?: boolean) => void` | Closes the importer, discarding the session in progress |
| `status` | `"idle" \| "launching" \| "launched" \| "destroyed"` | Lifecycle state of the underlying importer |

`launch()` accepts the same launch params as props, overriding them for that launch.

### Launch props

These are forwarded to the importer when `isOpen` becomes true.
These are forwarded to the importer on launch.

<!-- BEGIN GENERATED importer-launch-options -->

Expand Down
Loading
Loading