Skip to content

Take control over your live stream video by running it yourself. Streaming + chat out of the box.

feat(plugins): make plugin iframe content blend with the native UI

Gabe Kangas26bb35f5fdb8
diff --git a/web/components/ui/PluginTabFrame/PluginStylesheet.stories.tsx b/web/components/ui/PluginTabFrame/PluginStylesheet.stories.tsx
new file mode 100644
index 0000000000..222767503b
--- /dev/null
+++ b/web/components/ui/PluginTabFrame/PluginStylesheet.stories.tsx
@@ -0,0 +1,237 @@
+import { Meta, StoryFn } from '@storybook/nextjs';
+import { FC, useEffect, useRef } from 'react';
+
+// The served baseline stylesheet (web/public/styles/plugin.css), which
+// Storybook serves at /styles/plugin.css via its staticDirs. Editing that file
+// and reloading the story reflects here immediately, so this story is a live
+// sandbox for iterating on the plugin stylesheet.
+const PLUGIN_STYLESHEET = '/styles/plugin.css';
+
+// A self-contained mirror of PluginTabFrame's rendering: a srcdoc iframe with
+// the baseline linked into its head, a transparent background so the host
+// panel shows through, and auto-sizing to content. It deliberately omits
+// PluginTabFrame's Recoil reads (appearanceVariables / customStyles) so the
+// story has no store dependency and stays a pure stylesheet preview.
+const PluginFramePreview: FC<{ html: string }> = ({ html }) => {
+ const frameRef = useRef<HTMLIFrameElement>(null);
+ const observerRef = useRef<ResizeObserver | null>(null);
+
+ const handleLoad = () => {
+ const iframe = frameRef.current;
+ const doc = iframe?.contentDocument;
+ const win = iframe?.contentWindow as (Window & typeof globalThis) | null | undefined;
+ if (!iframe || !doc || !win) return;
+
+ // <base target="_top"> so links/forms behave; href gives relative URLs a
+ // real base (srcdoc otherwise resolves against about:srcdoc).
+ const base = doc.createElement('base');
+ base.setAttribute('target', '_top');
+ base.setAttribute('href', window.location.href);
+ doc.head.insertBefore(base, doc.head.firstChild);
+
+ // The baseline, prepended so the author's own head styles would win.
+ const link = doc.createElement('link');
+ link.setAttribute('rel', 'stylesheet');
+ link.setAttribute('href', PLUGIN_STYLESHEET);
+ doc.head.insertBefore(link, doc.head.firstChild);
+
+ // Let the panel behind the frame paint the background.
+ doc.documentElement.style.background = 'transparent';
+ doc.body.style.background = 'transparent';
+
+ // Match the frame height to its content so it reads as part of the page.
+ observerRef.current?.disconnect();
+ const resize = () => {
+ iframe.style.height = `${doc.documentElement.scrollHeight}px`;
+ };
+ resize();
+ const observer = new win.ResizeObserver(resize);
+ observer.observe(doc.documentElement);
+ observerRef.current = observer;
+
+ iframe.style.visibility = 'visible';
+ };
+
+ useEffect(() => () => observerRef.current?.disconnect(), []);
+
+ return (
+ <iframe
+ ref={frameRef}
+ srcDoc={html}
+ onLoad={handleLoad}
+ title="Plugin stylesheet preview"
+ sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
+ style={{ border: 'none', width: '100%', display: 'block', visibility: 'hidden' }}
+ />
+ );
+};
+
+// Sample content exercising every element the baseline styles plus all the
+// opt-in helper classes (card, card-grid, tag, stack, row, muted). Plain
+// semantic HTML, no inline styles, so what you see is entirely the stylesheet.
+const SAMPLE_HTML = `
+<h1>Plugin stylesheet preview</h1>
+<p>
+ This is how plain semantic HTML renders inside a plugin tab. Everything below
+ is styled only by the injected baseline. Edit
+ <code>web/public/styles/plugin.css</code> and reload to iterate.
+</p>
+
+<h2>Typography</h2>
+<p>
+ Body copy with a <a href="#">link</a>, some <code>inline code</code>, and
+ <span class="muted">muted secondary text</span> for captions.
+</p>
+<h3>Heading level 3</h3>
+<h4>Heading level 4</h4>
+<ul>
+ <li>Unordered list item one</li>
+ <li>Unordered list item two</li>
+</ul>
+<pre><code>// preformatted block
+const answer = 42;</code></pre>
+<hr />
+
+<h2>Helper: cards &amp; grid</h2>
+<div class="card-grid">
+ <article class="card interactive">
+ <h3>Album A</h3>
+ <p class="muted">Artist A</p>
+ <div class="row"><span class="tag">jazz</span><span class="tag">2024</span></div>
+ </article>
+ <article class="card interactive">
+ <h3>Album B</h3>
+ <p class="muted">Artist B</p>
+ <div class="row"><span class="tag">ambient</span></div>
+ </article>
+ <article class="card interactive">
+ <h3>Album C</h3>
+ <p class="muted">Artist C</p>
+ </article>
+</div>
+
+<h2>Helper: stack</h2>
+<div class="card">
+ <div class="stack">
+ <strong>Vertical stack</strong>
+ <span>First item</span>
+ <span>Second item</span>
+ <span>Third item</span>
+ </div>
+</div>
+
+<h2>Forms</h2>
+<form>
+ <label>
+ Text field
+ <input type="text" placeholder="Type here" />
+ </label>
+ <label>
+ Select
+ <select>
+ <option>Option A</option>
+ <option>Option B</option>
+ </select>
+ </label>
+ <label>
+ Textarea
+ <textarea placeholder="Notes"></textarea>
+ </label>
+ <label class="row"><input type="checkbox" /> Checkbox option</label>
+ <div class="row">
+ <button type="button">Primary button</button>
+ <button type="button" class="secondary">Secondary button</button>
+ <button type="button" disabled>Disabled</button>
+ </div>
+</form>
+
+<h2>Table</h2>
+<table>
+ <thead>
+ <tr><th>Name</th><th>Role</th></tr>
+ </thead>
+ <tbody>
+ <tr><td>Ada</td><td>Engineer</td></tr>
+ <tr><td>Lin</td><td>Designer</td></tr>
+ <tr><td>Sam</td><td>Streamer</td></tr>
+ </tbody>
+</table>
+
+<h2>Fieldset</h2>
+<fieldset>
+ <legend>Group</legend>
+ <p>A fieldset groups related controls with a light bordered box.</p>
+</fieldset>
+`;
+
+const meta = {
+ title: 'owncast/Plugins/Plugin Stylesheet',
+ component: PluginFramePreview,
+ parameters: {
+ docs: {
+ description: {
+ component: `Live sandbox for the plugin baseline stylesheet (\`web/public/styles/plugin.css\`),
+the CSS Owncast injects into plugin tab and admin-page iframes. The frame here mirrors
+how PluginTabFrame renders real plugin content: the baseline is linked in, the body is
+transparent so the host panel shows through, and the frame auto-sizes to its content.
+
+The sample HTML uses only plain semantic elements and the opt-in helper classes
+(\`card\`, \`card-grid\`, \`tag\`, \`stack\`, \`row\`, \`muted\`), so everything you see comes from
+the stylesheet. Edit \`plugin.css\` and reload to iterate.`,
+ },
+ },
+ },
+} satisfies Meta<typeof PluginFramePreview>;
+
+export default meta;
+
+// Renders the frame on a backdrop that mimics the viewer content panel
+// (--theme-color-components-content-background) sitting inside the page, so the
+// flush-on-panel effect the baseline relies on is visible.
+const Template: StoryFn<typeof PluginFramePreview> = args => (
+ <div
+ style={{
+ background: 'var(--theme-color-background-main)',
+ padding: 24,
+ minHeight: '100vh',
+ }}
+ >
+ <div
+ style={{
+ background: 'var(--theme-color-components-content-background)',
+ borderRadius: 'var(--theme-rounded-corners)',
+ padding: 32,
+ maxWidth: 1100,
+ margin: '0 auto',
+ }}
+ >
+ <PluginFramePreview {...args} />
+ </div>
+ </div>
+);
+
+// The default preview: full sample content on the content panel.
+export const Default = {
+ render: Template,
+ args: {
+ html: SAMPLE_HTML,
+ },
+};
+
+// Just the helper classes, for iterating on cards / grid / tags in isolation.
+export const HelperClasses = {
+ render: Template,
+ args: {
+ html: `
+<h2>Cards &amp; grid</h2>
+<div class="card-grid">
+ <article class="card interactive"><h3>Card one</h3><p class="muted">Hover for the lift</p><div class="row"><span class="tag">tag</span><span class="tag">tag</span></div></article>
+ <article class="card interactive"><h3>Card two</h3><p class="muted">Secondary detail</p></article>
+ <article class="card"><h3>Static card</h3><p class="muted">No hover</p></article>
+</div>
+<h2>Stack &amp; row</h2>
+<div class="card"><div class="stack"><strong>Stack</strong><span>One</span><span>Two</span></div></div>
+<div class="row"><span class="tag">one</span><span class="tag">two</span><span class="tag">three</span></div>
+`,
+ },
+};
diff --git a/web/public/styles/plugin.css b/web/public/styles/plugin.css
index 374d17c93f..67aebcbf9f 100644
--- a/web/public/styles/plugin.css
+++ b/web/public/styles/plugin.css
@@ -195,11 +195,16 @@
* those stacks — acceptable, and the same as the prior admin stylesheet.
*/
+/* Transparent so the host panel/page paints the background and the plugin
+ * content reads as part of the page rather than a boxed-in white pane. The
+ * viewer frame sits on the soft content panel; the admin frame sits on the
+ * admin page background. Keeping this in the stylesheet (rather than only the
+ * viewer's JS) means the admin frame blends in too. */
html,
body {
margin: 0;
padding: 0;
- background: var(--theme-color-background-main);
+ background: transparent;
color: var(--theme-color-components-text-on-light);
font-family: var(--theme-text-body-font-family);
font-size: 14px;
@@ -406,11 +411,13 @@ input[type='reset']:hover {
color: var(--theme-color-components-primary-button-text);
}
-/* Tables — minimal, readable. */
+/* Tables — minimal, readable. Card-toned background (not opaque white) so
+ * tables sit on the panel the way native content does. */
table {
border-collapse: collapse;
width: 100%;
- background: var(--theme-color-components-form-field-background);
+ background: var(--theme-color-background-main);
+ border: 1px solid rgb(0 0 0 / 12%);
border-radius: var(--theme-rounded-corners);
overflow: hidden;
}
@@ -432,12 +439,21 @@ tr:last-child td {
border-bottom: none;
}
-/* Cards — semantic <section>/<article>/<fieldset> get a soft container. */
+/* Sectioning content sits flush on the host panel, exactly like native tab
+ * content (the About tab, etc.) does. No card chrome: a plugin that wraps its
+ * markup in a <section>/<article> shouldn't pick up a stray colored box with a
+ * border and a second layer of padding nested inside the panel. Just vertical
+ * rhythm between blocks. */
section,
-article,
+article {
+ margin: 0 0 16px;
+}
+
+/* <fieldset> is a genuine form-grouping element, so keep it as a light bordered
+ * box — but transparent, so it groups without painting its own panel color. */
fieldset {
- background: var(--theme-color-components-form-field-background);
- border: 1px solid var(--theme-color-palette-14);
+ background: transparent;
+ border: 1px solid rgb(0 0 0 / 12%);
border-radius: var(--theme-rounded-corners);
padding: 16px;
margin: 0 0 16px;
@@ -451,3 +467,73 @@ fieldset legend {
.muted {
color: var(--theme-color-palette-10);
}
+
+/* ---------------------------------------------------------------------------
+ * Opt-in helper classes.
+ *
+ * The element baseline above already makes plain semantic HTML look native, so
+ * a plugin needs none of these. They exist for authors who want the native
+ * building blocks — a card surface, a responsive card grid, pill tags, simple
+ * layout — without hand-copying theme values. Everything references theme
+ * tokens, so it re-themes along with the host. Documented at
+ * https://owncast.online/docs/plugins/ui.
+ * ------------------------------------------------------------------------ */
+
+/* Card — the native card surface (the same look as the followers and featured
+ * streams cards). Opt in with class="card"; a plain <section>/<article> stays
+ * flush on the panel by design. */
+.card {
+ background: var(--theme-color-background-main);
+ border: 1px solid rgb(0 0 0 / 12%);
+ border-radius: var(--theme-rounded-corners);
+ padding: 16px;
+}
+
+/* Add "interactive" to a clickable card for the native hover lift. */
+.card.interactive {
+ cursor: pointer;
+ transition:
+ transform 120ms ease,
+ box-shadow 120ms ease;
+}
+
+.card.interactive:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+
+/* Responsive card grid, mirroring the native followers/streams layout: fills
+ * as many ~260px columns as fit and collapses to one column on a narrow
+ * frame. Drop .card children straight in. */
+.card-grid {
+ display: grid;
+ gap: 16px;
+ grid-template-columns: repeat(auto-fit, minmax(min(260px, 100%), 1fr));
+}
+
+/* Pill tag/badge, matching the tags on the native stream cards. */
+.tag {
+ display: inline-block;
+ height: 20px;
+ padding: 0 8px;
+ font-size: 11px;
+ line-height: 20px;
+ color: var(--theme-color-components-text-on-dark);
+ background: var(--theme-color-palette-10);
+ border-radius: 10px;
+}
+
+/* Layout — a vertical stack and a horizontal row, each with a sensible gap.
+ * Compose them for most plugin layouts without writing flexbox by hand. */
+.stack {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+}
+
+.row {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 8px;
+}
diff --git a/web/style-definitions/templates/plugin-elements.css b/web/style-definitions/templates/plugin-elements.css
index 71482f3a8b..d061767a98 100644
--- a/web/style-definitions/templates/plugin-elements.css
+++ b/web/style-definitions/templates/plugin-elements.css
@@ -19,11 +19,16 @@
* those stacks — acceptable, and the same as the prior admin stylesheet.
*/
+/* Transparent so the host panel/page paints the background and the plugin
+ * content reads as part of the page rather than a boxed-in white pane. The
+ * viewer frame sits on the soft content panel; the admin frame sits on the
+ * admin page background. Keeping this in the stylesheet (rather than only the
+ * viewer's JS) means the admin frame blends in too. */
html,
body {
margin: 0;
padding: 0;
- background: var(--theme-color-background-main);
+ background: transparent;
color: var(--theme-color-components-text-on-light);
font-family: var(--theme-text-body-font-family);
font-size: 14px;
@@ -230,11 +235,13 @@ input[type='reset']:hover {
color: var(--theme-color-components-primary-button-text);
}
-/* Tables — minimal, readable. */
+/* Tables — minimal, readable. Card-toned background (not opaque white) so
+ * tables sit on the panel the way native content does. */
table {
border-collapse: collapse;
width: 100%;
- background: var(--theme-color-components-form-field-background);
+ background: var(--theme-color-background-main);
+ border: 1px solid rgb(0 0 0 / 12%);
border-radius: var(--theme-rounded-corners);
overflow: hidden;
}
@@ -256,12 +263,21 @@ tr:last-child td {
border-bottom: none;
}
-/* Cards — semantic <section>/<article>/<fieldset> get a soft container. */
+/* Sectioning content sits flush on the host panel, exactly like native tab
+ * content (the About tab, etc.) does. No card chrome: a plugin that wraps its
+ * markup in a <section>/<article> shouldn't pick up a stray colored box with a
+ * border and a second layer of padding nested inside the panel. Just vertical
+ * rhythm between blocks. */
section,
-article,
+article {
+ margin: 0 0 16px;
+}
+
+/* <fieldset> is a genuine form-grouping element, so keep it as a light bordered
+ * box — but transparent, so it groups without painting its own panel color. */
fieldset {
- background: var(--theme-color-components-form-field-background);
- border: 1px solid var(--theme-color-palette-14);
+ background: transparent;
+ border: 1px solid rgb(0 0 0 / 12%);
border-radius: var(--theme-rounded-corners);
padding: 16px;
margin: 0 0 16px;
@@ -275,3 +291,73 @@ fieldset legend {
.muted {
color: var(--theme-color-palette-10);
}
+
+/* ---------------------------------------------------------------------------
+ * Opt-in helper classes.
+ *
+ * The element baseline above already makes plain semantic HTML look native, so
+ * a plugin needs none of these. They exist for authors who want the native
+ * building blocks — a card surface, a responsive card grid, pill tags, simple
+ * layout — without hand-copying theme values. Everything references theme
+ * tokens, so it re-themes along with the host. Documented at
+ * https://owncast.online/docs/plugins/ui.
+ * ------------------------------------------------------------------------ */
+
+/* Card — the native card surface (the same look as the followers and featured
+ * streams cards). Opt in with class="card"; a plain <section>/<article> stays
+ * flush on the panel by design. */
+.card {
+ background: var(--theme-color-background-main);
+ border: 1px solid rgb(0 0 0 / 12%);
+ border-radius: var(--theme-rounded-corners);
+ padding: 16px;
+}
+
+/* Add "interactive" to a clickable card for the native hover lift. */
+.card.interactive {
+ cursor: pointer;
+ transition:
+ transform 120ms ease,
+ box-shadow 120ms ease;
+}
+
+.card.interactive:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+
+/* Responsive card grid, mirroring the native followers/streams layout: fills
+ * as many ~260px columns as fit and collapses to one column on a narrow
+ * frame. Drop .card children straight in. */
+.card-grid {
+ display: grid;
+ gap: 16px;
+ grid-template-columns: repeat(auto-fit, minmax(min(260px, 100%), 1fr));
+}
+
+/* Pill tag/badge, matching the tags on the native stream cards. */
+.tag {
+ display: inline-block;
+ height: 20px;
+ padding: 0 8px;
+ font-size: 11px;
+ line-height: 20px;
+ color: var(--theme-color-components-text-on-dark);
+ background: var(--theme-color-palette-10);
+ border-radius: 10px;
+}
+
+/* Layout — a vertical stack and a horizontal row, each with a sensible gap.
+ * Compose them for most plugin layouts without writing flexbox by hand. */
+.stack {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+}
+
+.row {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 8px;
+}