@mochabug/adapt-web 1.0.1-rc.12 → 1.0.1-rc.13

package/README.md

@@ -132,6 +132,7 @@ Set via element reference — not available as HTML attributes.
 | `styles` | `Partial<CSSStyleDeclaration>` |
 | `persistOptions` | `{ storage?: 'session' \| 'local'; ttl?: number; key?: string }` |
 | `text` | `StatusText` |
+| `theme` | `AdaptTheme` |
 
 ### Events
 
@@ -228,172 +229,128 @@ el.addEventListener('adapt-cap-solve', (e) => {
 
 ## Styling
 
-All visuals are controlled via CSS custom properties on `.mb-adapt`. The `dark-mode` attribute on the element automatically switches to dark defaults, but you can override any variable for either mode.
+Three ways to theme, from simplest to most powerful:
 
-### Matching your site's toolbar
+### 1. `theme` prop (recommended)
 
-Map your site's existing design tokens to the panel toolbar. These six variables control almost everything you see in the tab bar:
+Set the `theme` JS property for semantic theming. Derives 30+ CSS variables from a few tokens.
 
-```css
-/* Light mode — derive from your site's surface/text colors */
-.mb-adapt {
-  --mb-adapt-fork-bg: #ffffff;              /* panel content background */
-  --mb-adapt-fork-tab-bg: #f5f5f5;         /* inactive tab / toolbar background */
-  --mb-adapt-fork-tab-active-bg: #ffffff;   /* active tab background */
-  --mb-adapt-fork-tab-color: #1a1a1a;      /* active tab text */
-  --mb-adapt-fork-tab-inactive-color: #888; /* inactive tab text */
-  --mb-adapt-fork-separator: #e0e0e0;      /* borders between tabs & panels */
-}
-
-/* Dark mode — add `dark-mode` attribute, then override */
-.mb-adapt[dark-mode] {
-  --mb-adapt-fork-bg: #1e1e1e;
-  --mb-adapt-fork-tab-bg: #2a2a2a;
-  --mb-adapt-fork-tab-active-bg: #1e1e1e;
-  --mb-adapt-fork-tab-color: #e0e0e0;
-  --mb-adapt-fork-tab-inactive-color: #777;
-  --mb-adapt-fork-separator: #3a3a3a;
-}
+```javascript
+const el = document.querySelector('adapt-automation');
+el.theme = {
+  mode: 'dark',
+  primary: '#6366f1',
+  background: '#0f172a',
+  surface: '#1e293b',
+  text: '#f1f5f9',
+  border: '#334155',
+  font: '"Inter", sans-serif',
+};
 ```
 
-**Typical mapping from your site's design system:**
+**`AdaptTheme` interface:**
 
-| Your site has | Maps to |
-|---|---|
-| Surface / card background | `--mb-adapt-fork-bg` |
-| Secondary / muted background | `--mb-adapt-fork-tab-bg` |
-| Primary text color | `--mb-adapt-fork-tab-color` |
-| Muted / secondary text | `--mb-adapt-fork-tab-inactive-color` |
-| Border / divider color | `--mb-adapt-fork-separator` |
-| Accent color | `--mb-adapt-separator-active` (resize handle highlight) |
-| Interactive hover tint | `--mb-adapt-button-hover-bg` |
+| Token | Effect |
+|-------|--------|
+| `mode` | `'light'` or `'dark'` — toggles dark mode class |
+| `primary` | Accent color — derives separator, drop target, spinner colors |
+| `background` | Root bg, active tab bg, status card bg |
+| `surface` | Panel content bg, tab bar bg |
+| `text` | Active tab text, status text, cap widget text |
+| `textSecondary` | Inactive tab text |
+| `border` | Tab separators, status card border, cap border |
+| `font` | All panel UI text + cap widget |
+| `vars` | `Record<string, string>` — direct variable overrides (key = name without `--mb-adapt-` prefix) |
+
+The `vars` escape hatch lets you override any variable:
+
+```javascript
+el.theme = {
+  primary: '#6366f1',
+  vars: {
+    'floating-shadow': 'none',
+    'floating-border': '2px solid #6366f1',
+    'cap-border-radius': '0px',
+  },
+};
+```
 
-### Custom theme (light & dark)
+### 2. CSS custom properties
 
-A more complete example mapping a full brand palette — primary, secondary, and accent colors — to Adapt's CSS variables for both light and dark modes:
+Set `--mb-adapt-*` variables on `.mb-adapt` or any ancestor. No Shadow DOM — standard CSS inheritance works.
 
 ```css
-/*
- * Example: brand theme using primary / secondary / accent colors.
- * Maps your design-system tokens to Adapt's CSS variables for both modes.
- */
-
-/* ── Light mode ────────────────────────────────── */
 .mb-adapt {
-  /* Brand palette */
-  --mb-adapt-fork-bg:               #ffffff;           /* surface          */
-  --mb-adapt-fork-tab-bg:           #f0f4ff;           /* primary-50       */
-  --mb-adapt-fork-tab-active-bg:    #ffffff;           /* surface          */
-  --mb-adapt-fork-tab-color:        #1e293b;           /* on-surface       */
-  --mb-adapt-fork-tab-inactive-color: #64748b;         /* on-surface-muted */
-  --mb-adapt-fork-separator:        #cbd5e1;           /* outline          */
-
-  /* Accent — resize handle highlight */
-  --mb-adapt-separator-active:      rgba(79, 70, 229, 0.5);  /* primary    */
-
-  /* Cap widget */
-  --mb-adapt-cap-background:        #ffffff;
-  --mb-adapt-cap-border-color:      #e2e8f0;
-  --mb-adapt-cap-color:             #1e293b;
-  --mb-adapt-cap-spinner-color:     #4f46e5;           /* primary          */
-
-  /* Status cards */
-  --mb-adapt-status-card-bg:        #ffffff;
-  --mb-adapt-status-card-border:    #e2e8f0;
-  --mb-adapt-status-text:           #334155;
+  --mb-adapt-fork-bg: #ffffff;
+  --mb-adapt-fork-tab-bg: #f5f5f5;
+  --mb-adapt-fork-tab-color: #1a1a1a;
+  --mb-adapt-fork-separator: #e0e0e0;
 }
 
-/* ── Dark mode ─────────────────────────────────── */
-.mb-adapt[dark-mode] {
-  --mb-adapt-fork-bg:               #0f172a;           /* surface-dark     */
-  --mb-adapt-fork-tab-bg:           #1e293b;           /* primary-900      */
-  --mb-adapt-fork-tab-active-bg:    #0f172a;           /* surface-dark     */
-  --mb-adapt-fork-tab-color:        #f1f5f9;           /* on-surface-dark  */
-  --mb-adapt-fork-tab-inactive-color: #94a3b8;         /* muted-dark       */
-  --mb-adapt-fork-separator:        #334155;           /* outline-dark     */
-
-  --mb-adapt-separator-active:      rgba(129, 140, 248, 0.6); /* primary-light */
-
-  --mb-adapt-cap-background:        #1e293b;
-  --mb-adapt-cap-border-color:      #334155;
-  --mb-adapt-cap-color:             #f1f5f9;
-  --mb-adapt-cap-spinner-color:     #818cf8;           /* primary-light    */
-
-  --mb-adapt-status-card-bg:        #1e293b;
-  --mb-adapt-status-card-border:    #334155;
-  --mb-adapt-status-text:           #e2e8f0;
+.mb-adapt--dark {
+  --mb-adapt-fork-bg: #1e1e1e;
+  --mb-adapt-fork-tab-bg: #2a2a2a;
+  --mb-adapt-fork-tab-color: #e0e0e0;
+  --mb-adapt-fork-separator: #3a3a3a;
 }
 ```
 
-### Font
+### 3. Direct CSS on internal classes
 
-Set `--mb-adapt-font` to match your site's typeface. This applies to tab labels, status messages, drag ghosts, and all panel UI text.
+No Shadow DOM — all internal elements use plain CSS classes. Target them directly for effects that CSS variables can't express: animations, pseudo-elements, transitions, media queries.
 
-```css
-.mb-adapt {
-  --mb-adapt-font: "Inter", sans-serif;
-}
-```
-
-### Elevation and borders
-
-Floating panels, status cards, and drag ghosts each have independent shadow, border, and radius variables. Use these to match your site's elevation system.
+**Animated gradient toolbar (liquid glass):**
 
 ```css
-/* Subtle, modern elevation */
-.mb-adapt {
-  --mb-adapt-floating-shadow: 0 8px 32px rgba(0, 0, 0, 0.08);
-  --mb-adapt-floating-border: 1px solid rgba(0, 0, 0, 0.06);
-  --mb-adapt-floating-radius: 12px;
-  --mb-adapt-floating-backdrop: none;
-
-  --mb-adapt-status-card-shadow: 0 2px 12px rgba(0, 0, 0, 0.06);
-  --mb-adapt-drag-ghost-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  --mb-adapt-border-radius: 8px;  /* iframe border radius */
+@keyframes toolbar-glow {
+  0%, 100% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
 }
 
-/* Dark mode — increase shadow density, add subtle light border */
-.mb-adapt[dark-mode] {
-  --mb-adapt-floating-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
-  --mb-adapt-floating-border: 1px solid rgba(255, 255, 255, 0.08);
-  --mb-adapt-status-card-shadow: 0 2px 12px rgba(0, 0, 0, 0.3);
-  --mb-adapt-drag-ghost-shadow: 0 2px 8px rgba(0, 0, 0, 0.4);
+/* Light mode — warm aurora */
+.mb-adapt .mb-group-header {
+  background: linear-gradient(
+    135deg,
+    rgba(99, 102, 241, 0.08) 0%,
+    rgba(168, 85, 247, 0.08) 25%,
+    rgba(236, 72, 153, 0.06) 50%,
+    rgba(99, 102, 241, 0.08) 100%
+  ) !important;
+  background-size: 300% 300%;
+  animation: toolbar-glow 8s ease infinite;
 }
-```
 
-**Frosted glass effect** — set a translucent background and enable `backdrop-filter`:
-
-```css
-.mb-adapt {
-  --mb-adapt-fork-bg: rgba(255, 255, 255, 0.7);
-  --mb-adapt-fork-tab-bg: rgba(245, 245, 245, 0.5);
-  --mb-adapt-floating-backdrop: blur(16px) saturate(180%);
-  --mb-adapt-floating-border: 1px solid rgba(255, 255, 255, 0.2);
-  --mb-adapt-floating-shadow: 0 4px 24px rgba(0, 0, 0, 0.06);
+/* Dark mode — deep neon */
+.mb-adapt--dark .mb-group-header {
+  background: linear-gradient(
+    135deg,
+    rgba(99, 102, 241, 0.15) 0%,
+    rgba(168, 85, 247, 0.12) 25%,
+    rgba(236, 72, 153, 0.10) 50%,
+    rgba(99, 102, 241, 0.15) 100%
+  ) !important;
+  background-size: 300% 300%;
+  animation: toolbar-glow 8s ease infinite;
 }
 ```
 
-**Flat / borderless** — remove all elevation:
-
-```css
-.mb-adapt {
-  --mb-adapt-floating-shadow: none;
-  --mb-adapt-floating-border: 1px solid var(--mb-adapt-fork-separator);
-  --mb-adapt-floating-radius: 4px;
-  --mb-adapt-status-card-shadow: none;
-  --mb-adapt-drag-ghost-shadow: none;
-}
-```
+**Key classes you can target:**
 
-**Typical mapping from your site's design system:**
+| Class | Element |
+|-------|---------|
+| `.mb-group-header` | Tab toolbar |
+| `.mb-tab` | Individual tab |
+| `.mb-tab[data-active="true"]` | Active tab |
+| `.mb-group-content` | Panel content area |
+| `.mb-floating-overlay` | Floating panel container |
+| `.mb-layout-separator` | Resize handle between panels |
+| `.mb-drag-ghost` | Tab drag preview |
+| `.mb-adapt__status-card` | Error/stopped status card |
+| `.mb-adapt__status-icon` | Status card icon |
+| `.mb-adapt-minimized-tab` | Minimized panel tab |
+| `.mb-drop-overlay` | Drop target highlight |
 
-| Your site has | Maps to |
-|---|---|
-| Card shadow / `--shadow-lg` | `--mb-adapt-floating-shadow` |
-| Card border / `--border-subtle` | `--mb-adapt-floating-border` |
-| Card radius / `--radius-lg` | `--mb-adapt-floating-radius` |
-| Tooltip/popover shadow | `--mb-adapt-status-card-shadow`, `--mb-adapt-drag-ghost-shadow` |
-| Glass/blur effect | `--mb-adapt-floating-backdrop` |
+All three approaches compose — use `theme` for colors, CSS variables for fine-tuning, and direct class targeting for animations.
 
 <details>
 <summary>Full CSS variable reference</summary>
@@ -418,6 +375,16 @@ Floating panels, status cards, and drag ghosts each have independent shadow, bor
 | `--mb-adapt-fork-tab-color` | `rgb(51,51,51)` | `#ffffff` | Active tab text |
 | `--mb-adapt-fork-tab-inactive-color` | `rgba(51,51,51,0.7)` | `#969696` | Inactive tab text |
 | `--mb-adapt-fork-separator` | `rgba(128,128,128,0.35)` | `rgb(68,68,68)` | Tab/panel borders |
+| `--mb-adapt-tab-radius` | `0` | | Tab border-radius (use `999px` for pill shape) |
+| `--mb-adapt-tab-shadow` | `none` | | Tab box-shadow |
+| `--mb-adapt-tab-active-shadow` | `none` | | Active tab box-shadow |
+| `--mb-adapt-tab-gap` | `0px` | | Tab margin (spacing between tabs) |
+| `--mb-adapt-tab-padding` | `0 14px` | | Tab padding |
+| `--mb-adapt-tab-font-size` | `13px` | | Tab label font size |
+| `--mb-adapt-toolbar-height` | `40px` | | Toolbar / tab bar height |
+| `--mb-adapt-toolbar-padding` | `0` | | Toolbar inner padding (standard CSS shorthand) |
+| `--mb-adapt-tab-min-width` | `100px` | | Tab minimum width |
+| `--mb-adapt-tab-spacing` | `6px` | | Gap between tab label and action buttons |
 
 ### Floating panels (elevation)