From 90b66366024b75740e50584c62f975e1a06f57eb Mon Sep 17 00:00:00 2001 From: Kai Vandivier Date: Mon, 13 Jan 2025 17:40:24 +0100 Subject: [PATCH] docs: update plugin docs --- docs/components/Plugin.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/components/Plugin.md b/docs/components/Plugin.md index 94107bbc..3274fcde 100644 --- a/docs/components/Plugin.md +++ b/docs/components/Plugin.md @@ -51,14 +51,16 @@ const MyPlugin = (propsFromParent) => { ## Plugin Props (reserved props) -| Name | Type | Required | Description | -| :--------------------: | :------------: | :---------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **pluginShortName** | _string_ | _required_ if `pluginSource` is not provided | The shortName of the app/plugin you wish to load (matching the result from api/apps). Used to look up the plugin entry point. If this is not provided, `pluginSource` must be provided. `pluginSource` will take precedence if provided. | -| **pluginSource** | _string_ (url) | _required_ if `pluginShortName` is not provided | The URL of the plugin. If this is not provided, `pluginShortName` must be provided. | -| **onError** | _Function_ | _optional_ | Callback function to be called when an error in the plugin triggers an error boundary. You can use this to pass an error back up to the app and create a custom handling/UX if errors occur in the plugin. In general, it is recommended that you use the plugin's built-in error boundaries | -| **showAlertsInPlugin** | _boolean_ | _optional_ | If `true`, any alerts within the plugin (defined with the `useAlert` hook) will be rendered within the iframe. By default, this is `false`. It is recommended, in general, that you do not override this and allow alerts to be hoisted up to the app level | -| **height** | _string_ | _optional_ | If a height is provided, the iframe will be fixed to the specified height. If no height is provided, the iframe will automatically resize its height based on its contents. The value of `height` will not be passed to the plugin, as it is in an internal implementation detail. If you do need to also pass the height to the plugin, you can pass another variable (e.g. `pluginHeight`). | -| **width** | _string_ | _optional_ | If a width is provided, the iframe will be fixed to the specified width. If no width is provided, the iframe will automatically resize its width based on its contents. The value of `width` will not be passed to the plugin, as it is in an internal implementation detail. If you do need to also pass the width to the plugin, you can pass another variable (e.g. `pluginWidth`). | +| Name | Type | Required | Description | +| :--------------------: | :----------------: | :---------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **pluginShortName** | _string_ | _required_ if `pluginSource` is not provided | The shortName of the app/plugin you wish to load (matching the result from api/apps). Used to look up the plugin entry point. If this is not provided, `pluginSource` must be provided. `pluginSource` will take precedence if provided. | +| **pluginSource** | _string_ (url) | _required_ if `pluginShortName` is not provided | The URL of the plugin. If this is not provided, `pluginShortName` must be provided. | +| **onError** | _Function_ | _optional_ | Callback function to be called when an error in the plugin triggers an error boundary. You can use this to pass an error back up to the app and create a custom handling/UX if errors occur in the plugin. In general, it is recommended that you use the plugin's built-in error boundaries | +| **showAlertsInPlugin** | _boolean_ | _optional_ | If `true`, any alerts within the plugin (defined with the `useAlert` hook) will be rendered within the iframe. By default, this is `false`. It is recommended, in general, that you do not override this and allow alerts to be hoisted up to the app level | +| **height** | _string or number_ | _optional_ | If a height is provided, the iframe will be fixed to the specified height. It can be any valid CSS dimension. By default, if no height is provided, the iframe will automatically resize its height based on its contents, in order to match the behavior of a normal block element. The value of `height` will not be passed to the plugin, as it is in an internal implementation detail. If you do need to also pass the height to the plugin, you can pass another variable (e.g. `pluginHeight`). | +| **width** | _string or number_ | _optional_ | Width for the `iframe` element to use; can be any valid CSS dimension. The default is `100%` to approximate the behavior of a normal block element (but not quite, since `auto` is the default for blocks, but that doesn't work for `iframe`s). If you want the width to resize based on the size of the Plugin's contents, use the `contentWidth` prop instead. The value of `width` will not be passed to the plugin, as it is in an internal implementation detail. If you do need to also pass the width to the plugin, you can pass another variable (e.g. `pluginWidth`). | +| **contentWidth** | _string_ | _optional_ | Set this if you want the width of the iframe to be driven by the contents inside the plugin. The value provided here will be used as the `width` of a `div` wrapping the plugin contents, which will be watched with a resize observer to update the size of the iframe according to the plugin content width. Therefore, **`'max-content'`** is probably the value you want to use for this prop. `'fit-content'` or `'min-content'` may also work, depending on your use case. | +| **className** | _string_ | _optional_ | A `className` value to be used on the `iframe` element to add styles. Sizing styles will take precedence over `width` and `height` props. Flex styles can be used, for example. **NB:** If you want to use this to add a margin, and you're using default width (or have set it `100%` yourself), you should instead wrap the `Plugin` with a div and add the margin on that div to approximate normal behavior of a block element | ## Plugin Props (custom props)