Iframe Controls

[bluwy]

TLDR: See "Proposal" section

Today, whyframe only handles component isolation side of things, which is good for specific tasks, but if you need more from it it'll involve a lot of work. For example:

• Clicking a button in a frame, we want to show the event logs.
• Change props for the button, we want a control panel that automatically detect the button props and allow us to customize in the browser.

Proposal

iframe keys

Optional:

<iframe data-why="some-unique-id" />

Import metadata via key

<script>
  import { rawSource, dynamicSource, ... } from 'whyframe:metadata:some-unique-id'
</script>

<iframe data-why="some-unique-id" />

Framework component metadata API

import buttonMetadata from './Button.jsx?metadata'

console.log(buttonMetadata)
// {
//   name: 'Button',
//   props: {},
//   events: {},
//   slots: {},
// }

Control panel

Basic:

<script setup>
import { ControlPanel } from '@whyframe/control-panel/vue'
import Button from './Button.vue'
</script>

<template>
  <iframe data-why="some-unique-id">
    <Button />
  </iframe>
  <!-- link via unique id, automatically generate controls for the iframe -->
  <ControlPanel why="some-unique-id" />
</template>

Modify:

<script setup>
import { ControlPanel } from '@whyframe/control-panel/vue'
import Button from './Button.vue'

function removeExtraControls(controls) {
  return controls.filter((control) => control.name !== 'id')
}
</script>

<template>
  <iframe data-why="some-unique-id">
    <Button />
  </iframe>
  <ControlPanel why="some-unique-id" :controls="removeExtraControls" />
</template>

Configure:

<script setup>
import { ControlPanel } from '@whyframe/control-panel/vue'
import Button from './Button.vue'

function configureControls(controls) {
  return [
    ...controls,
    {
      name: 'Custom',
      type: 'text',
      target: '$ > div[class]'
    }
  ]
}
</script>

<template>
  <iframe data-why="some-unique-id">
    <div class="test">
      <Button />
    </div>
  </iframe>
  <ControlPanel why="some-unique-id" :controls="configureControls" />
</template>

Event log

import { EventLog } from '@whyframe/event-log/react'

export default function App() {
  return (
    <div>
      <iframe data-why="some-unique-id" />
      <EventLog why="some-unique-id" />
    </div>
  )
}

Explanation

iframe keys are introduced as a way to link itself with another component seamlessly. It needs to be static so it can be analyzed to generate the necessary code to pass metadata to the component. It needs to be unique within that file only.

This also opens up the whyframe:metadata:some-unique-id module so raw source can be imported and rendered in SSR. Plus the potential of providing metadata that can't be serialized as an attribute. (Previously whyframe would inject the raw source into the iframe internal data-why-source attribute)

The control panel and event log can also take advantage of the key to prevent boilerplate when passing metadata between them and the iframe. This also allows them to have direct communication to the iframe to send fine-grained update events.

Implementation

Deprecate the old way of handling source.

Implement iframe keys. Optional only. This would break the Astro plugin convention but luckily not many are using it.

Implement metadata API for each framework. This would be the hardest but previewjs did a great job supporting this so far. Investigate if this can be done as a pure Vite plugin.

Implement control panels and event logs as a custom element. Create framework-specific wrapper. The libraries need to register with @whyframe/core to inform @whyframe/svelte, @whyframe/vue, and @whyframe/jsx how to handle these special components. The API will be a contract between the special components and @whyframe/core.

Settle on a control API if other libraries intend to build an alternative. The target: '$ > div[class]' property may need further design thoughts, but this will allow a generic way to target elements with the iframe, and allow whyframe to surgically update the application state instead of re-rendering everything. Same goes to events API.

Notes

If possible, make sure the special components implementation is generic enough that someone could technically implement all by themselves today with the only downside of boilerplate, which whyframe only providing syntax sugar.

Alternatives

Hooks

It's also important to think of the API in the framework's natural pattern. In React and Vue, hooks are more commonly used. It may look like:

import { useWhyframe } from '@whyframe/react'

export default function App() {
  const { whyframe, iframe } = useWhyframe()

  return (
    <div>
      <iframe ref={iframe} />
      <EventLog whyframe={whyframe} />
    </div>
  )
}

The issue is that since the API is runtime, it's harder to treeshake things. For example, you can't treeshake the raw source unless we implement useWhyframe({ rawSource: true }).

iframe variable also implies that we can forward it down to the children, but if that happens the compilation wouldn't be able to know which exact iframe element to process.