@wippy-fe/theme 0.0.10 → 0.0.12

package/README.md

@@ -59,6 +59,25 @@ Import PrimeVue component styles in your CSS:
 | `@wippy-fe/theme/primevue-plugin` | Vue plugin that installs PrimeVue with `{ theme: 'none' }` |
 | `@wippy-fe/theme/primevue/*` | PrimeVue component CSS files (Tailwind @apply-based) |
 
+## Host UI Customization
+
+The Wippy host exposes `--wippy-host-*` CSS variables and BEM class names for restyling the chat UI, sidebar, splitter, and message bubbles without forking. See [THEMING.md](./THEMING.md) §6 for the full reference.
+
+**Key principle:** Always scope host-only selectors to `.wippy-host-app` — `customCSS` is injected into both the host and nested child iframes, so unscoped rules will leak.
+
+```css
+/* Variables are already prefixed — no scoping needed */
+:root { --wippy-host-message-radius: 0.5rem; }
+
+/* Class selectors MUST be scoped to .wippy-host-app */
+.wippy-host-app .chat-message__content { border-radius: 4px; }
+
+/* Bad — leaks into child iframes */
+.chat-message__content { border-radius: 4px; }
+```
+
+**Available variable groups:** `--wippy-host-message-*` (bubbles), `--wippy-host-tool-*` (tool calls), `--wippy-host-avatar-*`, `--wippy-host-sidebar-*`, `--wippy-host-splitter-*`.
+
 ## Theming Reference
 
-See [THEMING.md](./THEMING.md) for the full reference on CSS variables, Tailwind utility classes, dark mode behavior, and PrimeVue component styling.
+See [THEMING.md](./THEMING.md) for the full reference on CSS variables, Tailwind utility classes, dark mode behavior, PrimeVue component styling, and host UI customization.

package/THEMING.md

@@ -348,3 +348,145 @@ Contrast ratio = (L_lighter + 0.05) / (L_darker + 0.05)
 ```
 
 WCAG AA requires 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+ regular).
+
+## 6. Host UI Customization (CSS Variables & BEM Classes)
+
+The Wippy host exposes CSS custom properties and BEM class names on its core UI components. Override these via `AppConfig.customization.cssVariables` or `customCSS` to restyle the host without forking.
+
+> **Important:** Because `customCSS` and `cssVariables` are injected into both the host AND all nested child iframes, always scope host-only overrides to `.wippy-host-app`. For example, use `.wippy-host-app .chat-message { ... }` — never `.chat-message { ... }` alone, or the styles will leak into child iframes.
+
+### Layout & Sidebar
+
+| Variable | Default | Description |
+|---|---|---|
+| `--wippy-host-sidebar-width-open` | `16rem` | Sidebar width when expanded |
+| `--wippy-host-sidebar-width-closed` | `3.5rem` | Sidebar width when collapsed |
+
+**BEM classes** (scope with `.wippy-host-app`):
+
+| Class | Element |
+|---|---|
+| `.layout` | Root layout wrapper |
+| `.layout__sidebar` | Sidebar container |
+| `.layout__sidebar-header` | Sidebar header (logo + toggle) |
+| `.layout__sidebar-nav` | Navigation list area |
+| `.layout__main` | Main content area (right of sidebar) |
+
+### Splitter Gutter
+
+The resizable panel divider between main content and the right panel.
+
+| Variable | Default | Description |
+|---|---|---|
+| `--wippy-host-splitter-width` | `1px` | Visible line width |
+| `--wippy-host-splitter-hit-area` | `10px` | Draggable hit area width (transparent) |
+| `--wippy-host-splitter-color` | `var(--p-surface-200)` (light) / `var(--p-surface-600)` (dark) | Line color |
+
+### Chat Messages
+
+| Variable | Default | Description |
+|---|---|---|
+| `--wippy-host-message-radius` | `1rem` | Message bubble border radius |
+| `--wippy-host-message-padding-x` | `1rem` | Message horizontal padding |
+| `--wippy-host-message-padding-y` | `0.5rem` | Message vertical padding |
+| `--wippy-host-message-user-bg` | `var(--p-primary-50)` | User message background |
+| `--wippy-host-message-agent-bg` | `var(--p-yellow-50)` (light) / `var(--p-surface-800)` (dark) | Agent message background |
+| `--wippy-host-tool-bg` | `var(--p-help-50)` | Tool call background |
+| `--wippy-host-tool-border` | `var(--p-help-300)` | Tool call left border |
+| `--wippy-host-avatar-size` | `2rem` | Message avatar diameter |
+
+**BEM classes** (scope with `.wippy-host-app`):
+
+| Class | Element |
+|---|---|
+| `.chat-message` | Message row container |
+| `.chat-message--user` | User message modifier |
+| `.chat-message--agent-message` | Agent message modifier |
+| `.chat-message--tool` | Tool call message modifier |
+| `.chat-message--error` | Error message modifier |
+| `.chat-message__avatar` | Avatar wrapper |
+| `.chat-message__avatar-icon` | Avatar icon circle |
+| `.chat-message__content` | Message bubble |
+| `.chat-message__body` | Message text content |
+| `.chat-message__footer` | Timestamp row |
+| `.chat-message__tool-name` | Tool name label |
+| `.chat-message__tool-icon` | Tool icon |
+| `.chat-message__agent-content` | Agent name system line |
+| `.chat-message__model-content` | Model name system line |
+| `.chat-message__files` | Attached files row |
+| `.chat-tool-group` | Inline tool call badge group |
+| `.chat-tool-group__badge` | Individual tool badge |
+| `.chat-tool-group__badge--success` | Completed tool badge |
+| `.chat-tool-group__badge--error` | Failed tool badge |
+| `.chat-tool-group__badge--processing` | In-progress tool badge |
+| `.chat-tool-group__icon` | Badge icon |
+
+### Chat Input
+
+**BEM classes** (scope with `.wippy-host-app`):
+
+| Class | Element |
+|---|---|
+| `.chat-input` | Input bar container |
+| `.chat-input__group` | Input field + buttons wrapper |
+| `.chat-input__textarea` | Message textarea |
+| `.chat-input__attach-button` | Attachment button |
+| `.chat-input__send-button` | Send button |
+| `.chat-input__stop-button` | Stop generation button |
+| `.chat-input__upload-list` | Upload queue list |
+| `.chat-input__prompts` | Suggested prompts area |
+
+### Chat Container
+
+**BEM classes** (scope with `.wippy-host-app`):
+
+| Class | Element |
+|---|---|
+| `.chat-container` | Outer chat wrapper |
+| `.chat-container--selected` | Has active session |
+| `.chat-container--non-selected` | No session selected |
+| `.chat-container__empty-state` | Empty state wrapper |
+| `.chat-container__empty-state-icon` | Empty state icon |
+| `.chat-container__empty-state-title` | Empty state heading |
+| `.chat-container__empty-state-description` | Empty state text |
+| `.chat-container__drop-zone` | File drag-and-drop overlay |
+| `.chat-container__drop-zone-icon` | Drop zone icon |
+
+### Session Selector
+
+**BEM classes** (scope with `.wippy-host-app`):
+
+| Class | Element |
+|---|---|
+| `.session-selector` | Selector wrapper |
+| `.session-selector__dropdown` | Dropdown component |
+| `.session-selector__option` | Session option row |
+| `.session-selector__active-dot` | Active session indicator |
+
+### Root
+
+| Class | Element |
+|---|---|
+| `.wippy-host-app` | Application root element — scope all host-only CSS overrides to this |
+
+### Example: Custom-Styled Host
+
+```css
+/* Via AppConfig.customization.customCSS */
+
+/* Variables are already prefixed — no scoping needed */
+:root {
+  --wippy-host-message-radius: 0.5rem;
+  --wippy-host-message-user-bg: #e0f2fe;
+  --wippy-host-sidebar-width-open: 20rem;
+}
+
+/* Class selectors MUST be scoped to .wippy-host-app */
+.wippy-host-app .chat-message__footer {
+  display: none; /* hide timestamps */
+}
+
+.wippy-host-app .session-selector {
+  display: none; /* hide session picker */
+}
+```

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "@wippy-fe/theme",
-  "version": "0.0.10",
-  "description": "Theme variables, shared Tailwind config, and PrimeVue styling for Wippy web components.",
-  "type": "module",
-  "main": "theme-config.css",
-  "exports": {
-    ".": "./theme-config.css",
-    "./theme-config.css": "./theme-config.css",
-    "./tailwind.config": "./tailwind.config.ts",
-    "./primevue-plugin": "./primevue-plugin.ts",
-    "./primevue/*": "./primevue/*"
-  },
-  "files": [
-    "theme-config.css",
-    "tailwind.config.ts",
-    "primevue-plugin.ts",
-    "primevue/",
-    "THEMING.md",
-    "README.md"
-  ],
-  "dependencies": {
-    "tailwindcss-primeui": "^0.6.1",
-    "tailwind-scrollbar": "^3.0.0"
-  },
-  "peerDependencies": {
-    "primevue": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "primevue": {
-      "optional": true
-    }
-  },
-  "license": "UNLICENSED"
-}
+{
+  "name": "@wippy-fe/theme",
+  "version": "0.0.12",
+  "description": "Theme variables, shared Tailwind config, and PrimeVue styling for Wippy web components.",
+  "type": "module",
+  "main": "theme-config.css",
+  "exports": {
+    ".": "./theme-config.css",
+    "./theme-config.css": "./theme-config.css",
+    "./tailwind.config": "./tailwind.config.ts",
+    "./primevue-plugin": "./primevue-plugin.ts",
+    "./primevue/*": "./primevue/*"
+  },
+  "files": [
+    "theme-config.css",
+    "tailwind.config.ts",
+    "primevue-plugin.ts",
+    "primevue/",
+    "THEMING.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "tailwindcss-primeui": "^0.6.1",
+    "tailwind-scrollbar": "^3.0.0"
+  },
+  "peerDependencies": {
+    "primevue": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "primevue": {
+      "optional": true
+    }
+  },
+  "license": "UNLICENSED"
+}