wineater-bot 4.0.0-beta.7 → 4.1.0

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,133 @@
+# ADR: Widget Customization System
+
+**Date:** 26.11.2025  
+**PR:** https://github.com/Wineater/wineater-bot/pull/2
+
+## Context
+
+Clients increasingly request widget customization for their specific brands and use cases. Typical requests include:
+
+- Changing colors and overall color scheme.
+- Adjusting fonts and typography.
+- Tweaking styles of individual UI elements (buttons, inputs, popups, etc.).
+- Customizing translations and text copy.
+
+Previously, such changes were mostly implemented as one‑off, manual style overrides or ad‑hoc modifications in the codebase. This approach has several drawbacks:
+
+- Poor scalability when multiple clients require different customizations.
+- High risk of regressions when editing styles for a single client.
+- No clear system for naming, organizing, or reusing styles and components.
+- Limited ability to evolve towards a proper design system and reusable components.
+
+We want to move away from manual, one‑by‑one style hacking and instead provide:
+
+- A component library that can be configured at the level of components, not individual DOM elements.
+- A token‑based color scheme and shared design primitives.
+- A single configuration entry point where client‑specific overrides can be described declaratively.
+
+## Decision
+
+We introduced a **customization system** for the widget with the following key aspects:
+
+1. **Class naming system using BEM**
+   - A consistent naming convention was introduced for widget elements based on the BEM methodology.
+   - This makes it easier to:
+     - Identify and target elements for styling.
+     - Maintain styles over time.
+     - Reason about component structure and responsibilities.
+
+2. **Centralized client configuration**
+   - Client‑specific behavior and appearance are now configured from a single configuration object.
+   - The configuration contains:
+     - General options that control various parts of the system (e.g. feature toggles and UI behavior flags).
+     - A `customCss` field that allows providing custom CSS for a client.
+
+3. **Custom CSS entry point**
+   - The `customCss` property is designed for injecting client‑specific style overrides.
+   - To increase specificity and avoid conflicts with default styles, all overrides must start from the `#wr-Custom` root selector.
+   - Example pattern:
+     - `#wr-Custom .wr-Button { /* client-specific overrides */ }`
+
+4. **Direction towards tokens and components**
+   - The current implementation is a first step towards:
+     - A shared color system expressed via tokens.
+     - A reusable set of components that can support variants (e.g. primary/secondary buttons, different input styles).
+   - The long‑term goal is to customize **component variants and design tokens** rather than patching arbitrary DOM elements with manual CSS.
+
+## Alternatives
+
+1. **Styling approach: Tailwind instead of BEM**
+   - We considered using Tailwind CSS (utility‑first classes) instead of the BEM naming convention.
+   - Pros:
+     - Potentially smaller final CSS payload due to tree‑shaking.
+     - Easier merging of classes to avoid shipping unused styles.
+   - Cons:
+     - Would require a full rewrite of existing styles into utility classes.
+     - Requires an additional class‑merge utility and Tailwind tooling in the build pipeline.
+     - Makes the resulting HTML/CSS less predictable for client‑side overrides, especially when clients are not familiar with Tailwind.
+   - Given the current state of the project and the need for predictable element names for customization, BEM was chosen over Tailwind.
+
+2. **Configuration approach: separate CSS file per client**
+   - We also considered storing custom styles for each client in a dedicated CSS file.
+   - Pros:
+     - Clear physical separation of styles per client.
+     - Simpler for some hosting scenarios.
+   - Cons:
+     - Requires injecting a client identifier into the HTML to load the correct file.
+     - Increases deployment and configuration complexity (managing many CSS files per environment).
+     - Harder to keep styles and other configuration (translations, feature flags) in sync in a single place.
+   - Instead, we opted for a single configuration entry with an inline `customCss` field.
+
+## Expectations
+
+From this decision we expect the following benefits:
+
+1. **More flexible customization for clients**
+   - Ability to adjust translations, color schemes, and key UI elements (buttons, inputs, basic layout) per client.
+   - A clear mechanism for styling without touching internal implementation details of the widget.
+
+2. **Move towards a design‑system approach**
+   - Over time, introduce configurable component variants instead of ad‑hoc overrides.
+   - Establish color tokens and a configurable theme, instead of manually redefining colors in many places.
+
+3. **Safer and more maintainable styling changes**
+   - BEM class naming makes selectors more predictable and less fragile.
+   - Centralized configuration reduces the chance of forgetting to apply a setting in some part of the system.
+
+## Technical Debt and Planned Improvements
+
+The current customization system is intentionally minimal and leaves several areas as explicit technical debt:
+
+1. **Global configuration shared across projects**
+   - A single configuration model is used across multiple projects/clients, which means some unused options are shipped everywhere.
+   - We plan to introduce a more modular configuration structure so that clients only receive relevant settings.
+
+2. **Manual style rewrites and lack of a change strategy**
+   - Many styles are still written and updated manually without a clear evolution path.
+   - We need a defined process and guidelines for introducing and deprecating style rules.
+
+3. **Missing color system**
+   - There is no dedicated color token system yet.
+   - Colors are not centralized, making it hard to define themes and variants.
+
+4. **No component‑level design tokens**
+   - Components (buttons, inputs, etc.) do not expose design tokens for spacing, radii, typography, and interaction states.
+   - A future step is to define tokens per component and allow them to be configured per client.
+
+5. **Lack of component variants**
+   - Components do not yet expose standardized variants (e.g. `primary`, `secondary`, `ghost`).
+   - Introducing variants will make customization more structured and reduce the need for one‑off overrides.
+
+6. **Font customization limitations**
+   - At the moment, fonts are effectively tied to Google Fonts.
+   - There is no supported mechanism for loading custom font files or non‑Google font providers per client.
+
+7. **Icon customization limitations**
+   - It is not yet possible to change icon colors or replace icons via configuration.
+   - Future work should define an icon system (e.g. via tokens or an icon registry) that can be overridden per client.
+
+8. **No first‑class configuration for core UI elements**
+   - Core components such as buttons and inputs are not yet configurable via a structured theme API.
+   - Future improvements should expose configuration options for these components (sizes, radii, colors, typography, and states) instead of relying solely on `customCss`.
+
+These items are expected to be addressed iteratively as we mature the customization system and move closer to a full design‑system and token‑based theming approach.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "wineater-bot",
-  "version": "4.0.0-beta.7",
+  "version": "4.1.0",
   "description": "",
-  "main": "dist/wineater-chatbot.umd.js",
+  "main": "dist/wineater-chatbot.mjs",
   "module": "src/index.js",
   "type": "module",
   "scripts": {

package/src/App.svelte

@@ -12,6 +12,7 @@
 	import WineTile from './components/WineTile.svelte';
 	import { appStore } from './services/store/app-store.svelte';
 	import { getTranslation, translateTexts } from './services/i18n/i18n';
+	import { generateInlineStyle } from './services/ui-config/utils';
 
 	function initCookies() {
 		setCookie('chatbotToken', window.wineaterData?.CLIENT_TOKEN || DEMO_TOKEN, 365);
@@ -41,6 +42,7 @@
 	let apiKey = $derived(appStore.getApiKey());
 	let storeId = $derived(appStore.getStoreId());
 	let isStoreInitialized = $derived(appStore.isInitialized());
+	let uiConfig = $derived(appStore.getUiConfig());
 
 	function setSearchError() {
 		errorMessage = getTranslation({ key: 'errorMessage', lang: appLanguage });
@@ -225,7 +227,7 @@
 
 	function onTileClick(event, wine: Wine | RecommendedWine) {
 		// Don't track clicks on buy buttons or close buttons
-		if (event.target.closest('.buy-btn') || event.target.closest('.card-popup-close')) {
+		if (event.target.closest('.js-WineTileAction') || event.target.closest('.js-WinePopupClose')) {
 			return;
 		}
 
@@ -237,7 +239,7 @@
 
 	function handleClickOutside(event: MouseEvent) {
 		const target = event.target as HTMLElement;
-		const isInsidePopup = target.closest('.card-popup') || target.closest('.buy-btn');
+		const isInsidePopup = target.closest('.js-WinePopup') || target.closest('.js-WineTileAction');
 
 		if (!isInsidePopup) {
 			selectedWineId = null;
@@ -249,6 +251,10 @@
 		await appStore.initializeStore();
 		if (!isStoreInitialized) return;
 
+		uiConfig = appStore.getUiConfig();
+		if (uiConfig.customCss) {
+			generateInlineStyle(uiConfig.customCss);
+		}
 		// Set dynamic color variable from widget data
 		const customColor = window?.wineaterData?.COLOR || '#7B2BEB';
 		document.documentElement.style.setProperty('--wineater-color', customColor);
@@ -267,54 +273,57 @@
 </script>
 
 {#if isStoreInitialized}
-	<div id="wine-widget-container" class="svelte-wineater-widget-container">
-		<div class="wine-widget-wrapper">
-			<Header />
-
-			<Search bind:searchQuery onSubmit={handleSearch} {initialized} />
-
-			{#if isLoading}
-				<Loader />
-			{/if}
-
-			<div id="wine-widget-right">
-				{#if errorMessage}
-					<div class="error-message">
-						<p>{errorMessage}</p>
-					</div>
-				{:else if results && results.length > 0}
-					<div id="wine-placeholder">
-						{#each results as wine, index}
-							<WineTile
-								{wine}
-								{index}
-								{hoveredWineId}
-								{selectedWineId}
-								{isAnimating}
-								translatedPopup={translatedPopups[index]}
-								onBuyClick={handleBuyBtnClick}
-								onPopupClose={closePopup}
-								{onTileEnter}
-								{onTileLeave}
-								{onTileClick}
-							/>
-						{/each}
-					</div>
-				{/if}
+	<!-- wr-Custom is used only for custom styling -->
+	<!-- id is used to increase specificity -->
+	<div id="wr-Custom" class="wr-App">
+		{#if uiConfig.logoUrl}
+			<div class="wr-App-picture">
+				<img class="wr-App-logo" src={uiConfig.logoUrl} alt="" />
 			</div>
-
-			<Footer {countryCode} />
+		{/if}
+		<Header />
+
+		<Search bind:searchQuery onSubmit={handleSearch} {initialized} />
+
+		{#if isLoading}
+			<Loader />
+		{/if}
+
+		<div class="wr-App-content">
+			{#if errorMessage}
+				<div class="wr-App-error">
+					<p>{errorMessage}</p>
+				</div>
+			{:else if results && results.length > 0}
+				<div class="wr-App-placeholder">
+					{#each results as wine, index}
+						<WineTile
+							{wine}
+							{index}
+							{hoveredWineId}
+							{selectedWineId}
+							{isAnimating}
+							translatedPopup={translatedPopups[index]}
+							onBuyClick={handleBuyBtnClick}
+							onPopupClose={closePopup}
+							{onTileEnter}
+							{onTileLeave}
+							{onTileClick}
+						/>
+					{/each}
+				</div>
+			{/if}
 		</div>
+
+		<Footer {countryCode} />
 	</div>
 {/if}
 
 <style>
-	/* ===================== 0) Font Import ===================== */
-	@import url('https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,200..800&display=swap');
-
 	/* ===================== 1) CSS Variables ===================== */
 	:global(:root) {
 		--wineater-corp-color: #0044ff;
+		/* TODO: get color from config */
 		--wineater-color: #7b2beb;
 	}
 
@@ -327,11 +336,15 @@
 		display: none;
 	}
 
+	:global(body) {
+		margin: 0;
+		padding: 0;
+
+		font-family: var(--wineater-font-primary, sans-serif);
+	}
+
 	/* ===================== 3) Widget Container ===================== */
-	#wine-widget-container {
-		display: flex;
-		gap: 24px;
-		font-family: 'Bricolage Grotesque', sans-serif;
+	.wr-App {
 		padding: 12px 12px 0px;
 		border-radius: 16px;
 		background-color: #fff;
@@ -341,24 +354,28 @@
 		min-height: 500px;
 		margin: 40px auto;
 		position: relative;
-		box-sizing: border-box;
 	}
 
-	#wine-widget-container :global([class^='icon-']),
-	#wine-widget-container :global([class*=' icon-']) {
-		font-family: 'Bricolage Grotesque', sans-serif !important;
+	.wr-App-picture {
+		display: flex;
+		justify-content: center;
+		align-items: center;
+		margin-bottom: 12px;
 	}
 
-	.wine-widget-wrapper {
-		width: 100%;
+	.wr-App-logo {
+		max-width: 100%;
+		height: auto;
+		width: auto;
+		max-height: 60px;
 	}
 
-	#wine-widget-right {
+	.wr-App-content {
 		position: relative;
 		min-height: 300px;
 	}
 
-	#wine-placeholder {
+	.wr-App-placeholder {
 		display: grid;
 		grid-template-columns: repeat(4, 1fr);
 		gap: 0;
@@ -367,7 +384,7 @@
 	}
 
 	/* ===================== 12) Error Message ===================== */
-	.error-message {
+	.wr-App-error {
 		text-align: center;
 		padding: 24px;
 		color: #666;
@@ -375,13 +392,13 @@
 
 	/* ===================== 13) Mobile Styles ===================== */
 	@media screen and (max-width: 768px) {
-		#wine-widget-container {
+		.wr-App {
 			flex-direction: column;
 			padding: 0px 16px;
 			min-width: 100vw;
 		}
 
-		#wine-placeholder {
+		.wr-App-placeholder {
 			display: flex;
 			gap: 8px;
 			overflow-x: auto;

package/src/components/Footer.svelte

@@ -27,81 +27,70 @@
 	}
 </script>
 
-<div id="powered-by-widget">
-	<div class="powered-by-center">
-		<a href="https://wineater.com" target="_blank">
-			<span>{getTranslation({ key: 'poweredBy', lang: appLanguage })}</span>
+<footer class="wr-Footer">
+	<div class="wr-Footer-center">
+		<a href="https://wineater.com" class="wr-Footer-link" target="_blank">
+			<span class="wr-Footer-text">{getTranslation({ key: 'poweredBy', lang: appLanguage })}</span>
 			<img
+				class="wr-Footer-logo"
 				src={countryCode === 'ru'
 					? 'https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media/divino_logo.svg?x=5'
 					: 'https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media/logo_medium_gray.svg'}
 				alt="Wineater Logo"
 			/>
-			<span class="powered-by-sommelier"
-				>{getTranslation({ key: 'ai_sommelier', lang: appLanguage })}</span
-			>
+			<span class="wr-Footer-text wr-Footer-text--sommelier">
+				{getTranslation({ key: 'ai_sommelier', lang: appLanguage })}
+			</span>
 		</a>
 	</div>
-	<div class="powered-by-lang">
-		{#if supportedLanguages.length > 1}
-			<select
-				id="language-dropdown"
-				class="language-dropdown"
-				value={appLanguage}
-				onchange={handleLanguageChange}
-			>
-				{#each supportedLanguages as lang}
-					<option value={lang} selected={lang === appLanguage}>
-						{lang.toUpperCase()}
-					</option>
-				{/each}
-			</select>
-		{/if}
-	</div>
-</div>
+	{#if supportedLanguages.length > 1}
+		<select class="wr-Footer-dropdown" value={appLanguage} onchange={handleLanguageChange}>
+			{#each supportedLanguages as lang}
+				<option class="wr-Footer-lang" value={lang} selected={lang === appLanguage}>
+					{lang.toUpperCase()}
+				</option>
+			{/each}
+		</select>
+	{/if}
+</footer>
 
 <style>
-	#powered-by-widget {
+	.wr-Footer {
 		position: relative;
 		border-top: 2px solid #f6f7fd;
-		font-family: 'Bricolage Grotesque', sans-serif;
 		font-weight: 200;
 		padding: 12px 24px;
 		min-height: 40px;
 	}
 
-	#powered-by-widget .powered-by-center {
+	.wr-Footer-center {
 		position: absolute;
 		left: 50%;
 		transform: translateX(-50%);
 		text-align: center;
 	}
 
-	#powered-by-widget .powered-by-lang {
+	.wr-Footer-dropdown {
 		position: absolute;
 		right: 0px;
 		top: 50%;
 		transform: translateY(-50%);
-	}
-
-	.language-dropdown {
 		padding: 4px;
 		border-radius: 6px;
 		border: 2px solid var(--wineater-color);
 		background-color: white;
 		color: var(--wineater-color);
 		font-weight: 500;
-		font-family: 'Bricolage Grotesque', sans-serif;
 		font-size: 12px;
 		cursor: pointer;
 		transition: all 0.2s ease;
 	}
 
-	.language-dropdown:hover {
+	.wr-Footer-dropdown:hover {
 		box-shadow: 0 4px 8px rgba(123, 43, 235, 0.2);
 	}
 
-	#powered-by-widget a {
+	.wr-Footer-link {
 		text-decoration: none;
 		display: flex;
 		align-items: center;
@@ -113,18 +102,18 @@
 		transition: opacity 0.2s ease;
 	}
 
-	#powered-by-widget a:hover {
+	.wr-Footer-link:hover {
 		opacity: 0.8;
 	}
 
-	#powered-by-widget img {
+	.wr-Footer-logo {
 		height: 16px;
 		width: auto;
 		color: #a8a8a8;
 	}
 
 	@media screen and (max-width: 768px) {
-		.powered-by-sommelier {
+		.wr-Footer-text--sommelier {
 			display: none;
 		}
 	}

package/src/components/Header.svelte

@@ -6,29 +6,27 @@
 	const titleText = window?.wineaterData?.TITLE_TEXT || null;
 </script>
 
-<div id="wine-widget-header">
+<div class="wr-Header">
 	{#if titleText}
-		<h1 class="wine-widget-big-title">{titleText}</h1>
+		<h1 class="wr-Header-title">{titleText}</h1>
 	{:else}
-		<!-- TODO: translation is not working -->
-		<h1 class="wine-widget-big-title">
+		<h1 class="wr-Header-title">
 			{getTranslation({ key: 'headerLine1', lang })}
-			<span class="icon icon-meal"></span>
-			<span class="icon-label">{getTranslation({ key: 'headerMeal', lang })}</span>,
-			<span class="icon icon-mood"></span>
-			<span class="icon-label">{getTranslation({ key: 'headerMood', lang })}</span>
+			<span class="wr-Header-icon wr-Header-icon--meal"></span>
+			<span class="wr-Header-label">{getTranslation({ key: 'headerMeal', lang })}</span>,
+			<span class="wr-Header-icon wr-Header-icon--mood"></span>
+			<span class="wr-Header-label">{getTranslation({ key: 'headerMood', lang })}</span>
 			<br />
 			{getTranslation({ key: 'headerOr', lang })}
-			<span class="icon icon-occasion"></span>
-			<span class="icon-label">{getTranslation({ key: 'headerOccasion', lang })}</span>
+			<span class="wr-Header-icon wr-Header-icon--occasion"></span>
+			<span class="wr-Header-label">{getTranslation({ key: 'headerOccasion', lang })}</span>
 			{getTranslation({ key: 'headerLine2', lang })}
 		</h1>
 	{/if}
 </div>
 
 <style>
-	#wine-widget-header h1 {
-		font-family: 'Bricolage Grotesque', serif;
+	.wr-Header-title {
 		font-weight: 600;
 		font-size: 24px;
 		margin: 0 auto;
@@ -37,15 +35,7 @@
 		text-align: center;
 	}
 
-	#wine-widget-header p {
-		font-size: 16px;
-		color: #666;
-		margin-top: 8px;
-		text-align: center;
-		padding: 0 15%;
-	}
-
-	.icon {
+	.wr-Header-icon {
 		display: inline-block;
 		width: 1.2em;
 		height: 1.2em;
@@ -55,37 +45,34 @@
 		background-size: contain;
 	}
 
-	.icon-meal {
+	.wr-Header-icon--meal {
 		background-image: url('https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media//meal1.svg');
 	}
 
-	.icon-meal:hover {
+	.wr-Header-icon--meal:hover {
 		background-image: url('https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media//meal3.svg');
 	}
 
-	.icon-mood {
+	.wr-Header-icon--mood {
 		background-image: url('https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media//mood.svg');
 	}
 
-	.icon-budget {
+	/* Not used, old icon */
+	.wr-Header-icon--budget {
 		background-image: url('https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media//budget.svg');
 	}
 
-	.icon-occasion {
+	.wr-Header-icon--occasion {
 		background-image: url('https://czvgkhagwvmknscoerfy.supabase.co/storage/v1/object/public/static-media//ocasion.svg');
 	}
 
-	.icon-label {
+	.wr-Header-label {
 		color: var(--wineater-color);
 		font-weight: 500;
 	}
 
 	@media screen and (max-width: 768px) {
-		#wine-widget-header h1 {
-			display: none;
-		}
-
-		#wine-widget-header p {
+		.wr-Header-title {
 			display: none;
 		}
 	}

package/src/components/Loader.svelte

@@ -1,5 +1,5 @@
-<div id="loading-indicator">
-	<div id="typing-indicator" class="typing-indicator">
+<div class="wr-Loader">
+	<div class="wr-Loader-indicator">
 		<span></span>
 		<span></span>
 		<span></span>
@@ -7,7 +7,7 @@
 </div>
 
 <style>
-	#loading-indicator {
+	.wr-Loader {
 		position: absolute;
 		top: 50%;
 		left: 50%;
@@ -16,7 +16,7 @@
 		text-align: center;
 	}
 
-	.typing-indicator {
+	.wr-Loader-indicator {
 		display: flex;
 		justify-content: center;
 		align-items: center;
@@ -25,7 +25,7 @@
 		background-color: white;
 	}
 
-	.typing-indicator span {
+	.wr-Loader-indicator span {
 		display: block;
 		width: 8px;
 		height: 8px;
@@ -48,15 +48,15 @@
 		}
 	}
 
-	.typing-indicator span:nth-child(1) {
+	.wr-Loader-indicator span:nth-child(1) {
 		animation-delay: 0s;
 	}
 
-	.typing-indicator span:nth-child(2) {
+	.wr-Loader-indicator span:nth-child(2) {
 		animation-delay: 0.15s;
 	}
 
-	.typing-indicator span:nth-child(3) {
+	.wr-Loader-indicator span:nth-child(3) {
 		animation-delay: 0.3s;
 	}
 </style>