@helpway/react 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@helpway/react",
-	"version": "0.17.0",
+	"version": "0.17.2",
 	"description": "Official React SDK for Helpway — drop-in AI chat support widget with headless hooks for custom UIs.",
 	"keywords": [
 		"helpway",
@@ -43,8 +43,9 @@
 		"test": "bun test",
 		"sync:icons": "bun scripts/sync-icons.ts",
 		"prepublishOnly": "bun run build",
-		"prepack": "bun run build && bun scripts/apply-publish-config.ts",
-		"postpack": "bun scripts/apply-publish-config.ts --restore"
+		"prepack": "bun scripts/sync-icons.ts --check && bun run build && bun scripts/apply-publish-config.ts",
+		"postpack": "bun scripts/apply-publish-config.ts --restore",
+		"check:icons": "bun scripts/sync-icons.ts --check"
 	},
 	"//": "publishConfig swaps main/types/exports to the built dist on publish. Workspace consumers get raw src (fast HMR, no build step); npm consumers get compiled dist with .d.ts. Standard monorepo pattern.",
 	"dependencies": {

package/src/themed/styles.css

@@ -41,6 +41,20 @@
 	padding: 0;
 }
 
+/* Text takes its colour from the widget, not from the page.
+   Outside the script embed's shadow root the widget is ordinary DOM, and a
+   host stylesheet's prose rules reach in: Carna's `p strong { color:
+   var(--ink-1) }` drew every bold word of an answer in near-black on the
+   landing's blue panel (Ali, 2026-10-12: "renklerde sorunlar var"). The
+   widget never set a colour on these elements — it expected them to inherit —
+   so anything the page said won.
+   `:where()` keeps this at one class of specificity: it beats a host's
+   element rules (`strong`, `p strong`, `.x`-less prose) and still loses to
+   every widget rule that follows, so no component colour changes. */
+.hw-widget :where(p, li, strong, b, em, i, u, s, small, a, code, pre, blockquote, h1, h2, h3, h4, h5, h6) {
+	color: inherit;
+}
+
 /* ── Tokens ──────────────────────────────────────
    Wrapped in :where() so the default token block has zero specificity.
    That way `applyTheme()` (which writes inline styles onto the host
@@ -370,6 +384,48 @@
 	height: min(800px, calc(100vh - 112px));
 }
 
+/* The mobile SDK's sheet (widget.js mobile mode, #268): the native sheet IS
+   the window, at every width. An iPad's page sheet is wider than the 480px
+   phone breakpoint, and without this the floating panel would sit in a
+   corner of it. No open animation either — the sheet already slid up, and
+   a second slide inside it reads as the app stuttering. :host only matches
+   inside the embed's shadow root, so @helpway/react consumers never see it. */
+:host([data-hw-mode="mobile"]) .hw-window,
+:host([data-hw-mode="mobile"]) .hw-window--reading {
+	position: fixed;
+	inset: 0;
+	width: 100%;
+	height: var(--hw-visible-height, 100%);
+	border-radius: 0;
+	box-shadow: none;
+	animation: none;
+}
+/* The bubble is the launcher, and the app's own Help row is the launcher
+   here. hideLauncher does not remove it (it only stops click-outside from
+   closing the panel), so without this a black × sat over the send button. */
+/* The hero is a gradient (background-image), so its computed
+   background-color was transparent and the SDK could not tell the native
+   sheet what colour sits under iOS's grabber. The gradient's own top-left
+   stop, as a solid underneath it: invisible here, measurable there
+   (widget-embed mobile-chrome.ts). */
+:host([data-hw-mode="mobile"]) .hw-hero {
+	background-color: color-mix(in srgb, var(--hw-primary) 60%, black);
+}
+:host([data-hw-mode="mobile"]) .hw-bubble {
+	display: none;
+}
+
+/* Keyboard open (default-widget.tsx sets data-hw-keyboard from
+   visualViewport). The home-indicator inset is under the keyboard, so
+   padding for it leaves an empty band between composer and keys; and the
+   "Powered by" line costs a row the conversation needs more. */
+.hw-window[data-hw-keyboard] .hw-composer {
+	padding-bottom: 8px;
+}
+.hw-window[data-hw-keyboard] .hw-powered {
+	display: none;
+}
+
 @keyframes hw-window-open {
 	from {
 		opacity: 0;
@@ -1241,6 +1297,14 @@
 	min-width: 0;
 	scrollbar-color: rgba(0, 0, 0, 0.2) transparent;
 	scrollbar-width: thin;
+	/* The header has no rule under it and shares the thread's ground, so a
+	   message scrolled half out of view was cut along a line nobody could see
+	   and looked broken rather than scrolled. The last 12px dissolve instead.
+	   12, because the list's own top padding is 16: at rest the first message
+	   starts below the fade and is untouched. (The docked placement has had
+	   this since it was built, at 16px.) */
+	-webkit-mask-image: linear-gradient(180deg, transparent 0, #000 12px);
+	mask-image: linear-gradient(180deg, transparent 0, #000 12px);
 }
 
 .hw-messages::-webkit-scrollbar {
@@ -1603,6 +1667,10 @@
 	color: inherit;
 	margin-top: 6px;
 	transition: background 0.15s;
+	/* A card you can hit with a thumb, even when it is a title and nothing else. */
+	min-height: 44px;
+	max-width: 100%;
+	text-align: start;
 }
 
 .hw-link-preview:hover {
@@ -1634,9 +1702,29 @@
 }
 
 .hw-link-preview-favicon {
-	width: 16px;
-	height: 16px;
-	border-radius: 2px;
+	width: 14px;
+	height: 14px;
+	flex: 0 0 14px;
+	border-radius: 3px;
+}
+/* On glass the site's mark is somebody else's colour on ours: Carna's blue
+   knot on the blue panel was a smudge. A small white chip under it, the way a
+   browser tab holds a favicon. White and not a token on purpose: a favicon is
+   drawn for a light ground, whatever the panel around it is. */
+.hw-widget[data-hw-placement="docked"] .hw-link-preview-favicon {
+	box-sizing: content-box;
+	padding: 2px;
+	background: #ffffff;
+}
+
+.hw-link-preview-host {
+	/* A hostname reads left to right in every language. It WRAPS and is never
+	   cut here: the end of a host is what says whose site it is, and an
+	   ellipsis there would hide it (link-preview.ts shortens it from the start). */
+	direction: ltr;
+	min-width: 0;
+	overflow-wrap: anywhere;
+	word-break: break-all;
 }
 
 .hw-link-preview-title {
@@ -1652,6 +1740,8 @@
 	-webkit-line-clamp: 2;
 	-webkit-box-orient: vertical;
 	overflow: hidden;
+	/* A title with no spaces (a URL, a hash) breaks instead of widening the card. */
+	overflow-wrap: anywhere;
 }
 
 .hw-link-preview-desc {
@@ -1662,9 +1752,15 @@
 	-webkit-line-clamp: 2;
 	-webkit-box-orient: vertical;
 	overflow: hidden;
+	overflow-wrap: anywhere;
 }
 
 .hw-link-preview-url {
+	/* The site, first: a small mark and the host on one quiet line. */
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	min-width: 0;
 	font-size: 11px;
 	/* --hw-text-muted is referenced in seven rules and defined in none, so every
 	   one of them silently falls back to a hardcoded grey and stops following
@@ -2540,22 +2636,6 @@
 	color: var(--hw-text-2);
 }
 
-/* ════════════════════════════════════════════════
-   RESOLVED BANNER
-   ════════════════════════════════════════════════ */
-
-.hw-resolved-banner {
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	padding: 12px 16px;
-	border-top: 1px solid var(--hw-border);
-	background: var(--hw-bg-subtle);
-	color: var(--hw-text-2);
-	font-size: 13px;
-	flex-shrink: 0;
-}
-
 /* ════════════════════════════════════════════════
    NEW CONVERSATION FORM
    ════════════════════════════════════════════════ */
@@ -2687,6 +2767,16 @@
 	.hw-powered {
 		padding-bottom: calc(5px + env(safe-area-inset-bottom, 0px));
 	}
+	/* The inset belongs to whatever is LAST in the window. With "Powered by"
+	   under the composer (or the tabs), both were padding for the same home
+	   indicator — the empty band above "Powered by" in Ali's simulator run of
+	   the mobile SDK. The line carries it; what sits above it does not. */
+	.hw-window:has(.hw-powered) .hw-composer {
+		padding-bottom: 8px;
+	}
+	.hw-window:has(.hw-powered) .hw-tabs {
+		padding-bottom: 0;
+	}
 
 	/* Touch targets */
 	.hw-header-close,
@@ -3978,6 +4068,31 @@
    currentColor, so it inherits the row's measured ink instead of carrying a
    second colour decision. The 3/4 arc uses `transparent` rather than color-mix:
    this bundle runs on whatever browser a customer's visitor brought. */
+/* The one action of the "lost" state. Text-weight, not a pill: the band stays
+   a band. Underlined so it reads as pressable without a colour of its own —
+   it takes the panel's ink, which holds on glass and on any brand surface. */
+.hw-disconnect-retry {
+	flex: none;
+	padding: 2px 4px;
+	margin: -2px 0;
+	border: 0;
+	border-radius: 4px;
+	background: none;
+	color: var(--hw-text);
+	font: inherit;
+	font-weight: 600;
+	text-decoration: underline;
+	text-underline-offset: 2px;
+	cursor: pointer;
+}
+.hw-disconnect-retry:hover {
+	text-decoration-thickness: 2px;
+}
+.hw-disconnect-retry:focus-visible {
+	outline: 2px solid var(--hw-text);
+	outline-offset: 1px;
+}
+
 .hw-disconnect-spinner {
 	width: 9px;
 	height: 9px;
@@ -4094,94 +4209,98 @@
 }
 
 /* ════════════════════════════════════════════════
-   RESOLVED CONVERSATION — REOPEN + CSAT
+   RESOLVED CONVERSATION — STATUS + RATING
+   One status row, then the rating on a single line. Every colour is a
+   token: the block has no tone of its own, and the brand colour only
+   edges the pressed option — it never sits behind or under the text, so
+   contrast does not depend on what the customer picked.
+   (DESIGN-DECISIONS rule/widget-resolved-block)
    ════════════════════════════════════════════════ */
 
 .hw-resolved {
 	display: flex;
 	flex-direction: column;
-	align-items: center;
-	gap: 12px;
-	padding: 16px 20px;
+	gap: 8px;
+	padding: 10px 14px;
 	border-top: 1px solid var(--hw-border);
 	flex-shrink: 0;
 }
 
-.hw-resolved-text {
-	font-size: 13px;
-	color: var(--hw-text-3);
-	font-weight: 500;
-}
-
-.hw-resolved-actions {
+.hw-resolved-status {
 	display: flex;
-	gap: 8px;
-}
-
-.hw-resolved-reopen {
-	padding: 6px 16px;
-	border: 1px solid var(--hw-border-md);
-	border-radius: 8px;
-	background: var(--hw-bg);
+	align-items: center;
+	gap: 6px;
+	font-size: 12.5px;
+	font-weight: 550;
 	color: var(--hw-text);
-	font-size: 13px;
-	font-weight: 500;
-	cursor: pointer;
-	transition: background 0.15s;
 }
 
-.hw-resolved-reopen:hover {
-	background: var(--hw-bg-hover);
+.hw-resolved-status svg {
+	flex: none;
+	color: var(--hw-text-2);
 }
 
-/* CSAT Rating */
 .hw-csat {
 	display: flex;
-	flex-direction: column;
 	align-items: center;
-	gap: 8px;
+	justify-content: space-between;
+	flex-wrap: wrap;
+	gap: 6px 10px;
 }
 
-.hw-csat-label {
+/* text-2, not text-3: at 12px text-3 is under 4.5:1 on both surfaces (the
+   same measurement as .hw-msg-meta). */
+.hw-csat-label,
+.hw-csat-error {
 	font-size: 12px;
-	color: var(--hw-text-3);
+	color: var(--hw-text-2);
+}
+
+.hw-csat-error {
+	color: var(--hw-text);
 }
 
 .hw-csat-buttons {
 	display: flex;
-	gap: 8px;
+	gap: 6px;
 }
 
 .hw-csat-btn {
-	width: 36px;
-	height: 36px;
+	display: inline-flex;
+	align-items: center;
+	gap: 5px;
+	height: 30px;
+	padding: 0 11px;
 	border: 1px solid var(--hw-border-md);
-	border-radius: 8px;
+	border-radius: 999px;
 	background: var(--hw-bg);
+	color: var(--hw-text);
+	font: inherit;
+	font-size: 12px;
+	font-weight: 550;
 	cursor: pointer;
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	font-size: 18px;
-	transition: transform 0.15s, border-color 0.15s, background 0.15s;
+	transition: background 0.15s, border-color 0.15s;
 }
 
-.hw-csat-btn:hover {
-	transform: scale(1.1);
-	border-color: var(--hw-text-3);
+.hw-csat-btn svg {
+	flex: none;
 }
 
-.hw-csat-btn--selected {
-	border-color: var(--hw-primary);
+.hw-csat-btn:hover {
 	background: var(--hw-bg-hover);
-	transform: scale(1.15);
 }
 
-.hw-csat-thanks {
-	font-size: 12px;
-	color: #22c55e;
-	font-weight: 500;
-	animation: hw-msg-appear 0.25s ease-out;
+.hw-csat-btn:focus-visible {
+	outline: 2px solid var(--hw-text);
+	outline-offset: 2px;
+}
+
+/* The answer, kept. Pressed and read-only: the server takes one rating. */
+.hw-csat-btn[aria-pressed="true"] {
+	background: var(--hw-bg-hover);
+	border-color: var(--hw-brand, var(--hw-primary));
+	box-shadow: inset 0 0 0 1px var(--hw-brand, var(--hw-primary));
+	cursor: default;
 }
 
 /* ════════════════════════════════════════════════
@@ -4542,16 +4661,6 @@
 		color: #f87171;
 	}
 
-	.hw-resolved {
-		border-color: var(--hw-border);
-	}
-
-	.hw-resolved-reopen,
-	.hw-csat-btn {
-		background: var(--hw-bg-hover);
-		border-color: var(--hw-border-md);
-		color: var(--hw-text);
-	}
 
 	.hw-hover-preview {
 		background: #1c1c1e;
@@ -5696,18 +5805,30 @@
 
 /* Sources. A numbered row per entry rather than a card — the answer is the
    content, these are the receipts, and receipts should be quiet. */
-.hw-sources { display: flex; flex-direction: column; gap: 2px; margin-top: 8px; }
+/* Attached to the answer they belong to. They sat 8px under the bubble and
+   10px in, so the number lined up with neither the bubble's edge nor its
+   text, and the row read as a separate thing floating above the name line
+   (Ali, 2026-10-12). 4px under it now, and the number starts where the
+   bubble's text starts: 14px in, the bubble's own padding. */
+.hw-sources { display: flex; flex-direction: column; gap: 2px; margin-top: 4px; }
 .hw-source {
 	display: flex;
 	align-items: center;
 	gap: 9px;
-	padding: 7px 10px;
+	padding: 5px 14px;
 	border-radius: 9px;
 	background: transparent;
 	color: var(--hw-text);
 	text-decoration: none;
 	transition: background 0.15s;
 }
+/* In the docked placement an answer has no bubble and its text starts at the
+   column's edge, so the number does too. The hover ground still gets its 8px
+   of air: it is pulled out by the same amount it is padded. */
+.hw-widget[data-hw-placement="docked"] .hw-source {
+	margin-inline: -8px;
+	padding-inline: 8px;
+}
 a.hw-source { cursor: pointer; }
 a.hw-source:hover { background: var(--hw-bg-hover); }
 .hw-source-n {
@@ -5732,3 +5853,145 @@ a.hw-source:hover { background: var(--hw-bg-hover); }
 	text-overflow: ellipsis;
 	white-space: nowrap;
 }
+
+/* ── Docked, brand surface ─────────────────────────────────────────────────
+   `theme.dockSurface: "brand"`: the panel, the bar under it and the reply
+   preview are filled with the customer's colour instead of neutral glass.
+
+   Everything here is built from four values that `applyTheme` writes on the
+   host from the brand colour (widget-core dock-ink.ts): the tint, the ink
+   chosen for it, the shade (the far end from the ink) and the quiet inks. Two
+   rules, and both are tested there for 4,096 colours:
+
+     - text is the ink, and the ink clears 4.5:1 on the tint;
+     - the surface only moves toward the SHADE, never toward the ink, so the
+       tint itself is the worst ground any text meets.
+
+   That second rule is why the light patch at the top right is the tint and
+   the rest settles away from it. A patch lifted toward white under white
+   text is how body copy fell to 2.9:1 on the first brand panel.
+
+   The fallbacks (white ink on --hw-primary) are what the panel does when the
+   colour could not be read: a named colour, oklch(), a var(). */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] {
+	--hw-dock-tint: var(--hw-primary);
+	--hw-dock-ink: #ffffff;
+	--hw-dock-shade: #000000;
+	--hw-dock-wash: var(--hw-dock-shade);
+	--hw-dock-ink-2: color-mix(in srgb, var(--hw-dock-ink) 86%, var(--hw-dock-tint));
+	--hw-dock-ink-3: color-mix(in srgb, var(--hw-dock-ink) 78%, var(--hw-dock-tint));
+	--hw-dock-ink-4: color-mix(in srgb, var(--hw-dock-ink) 60%, var(--hw-dock-tint));
+	--hw-dock-pill-bg: var(--hw-dock-tint);
+	--hw-dock-pill-fg: var(--hw-dock-ink);
+	--hw-dock-pill-border: color-mix(in srgb, var(--hw-dock-ink) 30%, transparent);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] :is(.hw-window, .hw-dock-bar, .hw-preview) {
+	--hw-text: var(--hw-dock-ink);
+	--hw-text-1: var(--hw-dock-ink);
+	--hw-text-2: var(--hw-dock-ink-2);
+	--hw-text-3: var(--hw-dock-ink-3);
+	--hw-text-4: var(--hw-dock-ink-4);
+	--hw-text-muted: var(--hw-dock-ink-2);
+	--hw-bg: color-mix(in srgb, var(--hw-dock-wash) 12%, transparent);
+	--hw-bg-subtle: transparent;
+	--hw-bg-hover: color-mix(in srgb, var(--hw-dock-wash) 18%, transparent);
+	--hw-border: color-mix(in srgb, var(--hw-dock-ink) 22%, transparent);
+	--hw-border-md: color-mix(in srgb, var(--hw-dock-ink) 34%, transparent);
+	--hw-focus-border: color-mix(in srgb, var(--hw-dock-ink) 60%, transparent);
+	--hw-focus-ring: color-mix(in srgb, var(--hw-dock-ink) 18%, transparent);
+	/* The agent's bubble (the token is misnamed) is unboxed in this placement;
+	   where it does show, it is a wash, with the ink on it. */
+	--hw-visitor-bubble-bg: color-mix(in srgb, var(--hw-dock-wash) 14%, transparent);
+	--hw-visitor-bubble-text: var(--hw-dock-ink);
+	/* A solid object on the brand surface is the inverse pair: ink ground,
+	   brand-coloured text. Same two colours as the body text, same ratio. */
+	--hw-primary: var(--hw-dock-ink);
+	--hw-primary-hover: var(--hw-dock-ink);
+	--hw-brand: var(--hw-dock-ink);
+	--hw-on-brand: var(--hw-dock-tint);
+	--hw-dock-surface: transparent;
+	--hw-dock-on-surface: var(--hw-dock-ink);
+	color: var(--hw-dock-ink);
+	background:
+		radial-gradient(70% 60% at 86% 8%, var(--hw-dock-tint), transparent 64%),
+		linear-gradient(
+			165deg,
+			color-mix(in srgb, var(--hw-dock-shade) 12%, var(--hw-dock-tint)) 0%,
+			color-mix(in srgb, var(--hw-dock-shade) 30%, var(--hw-dock-tint)) 100%
+		);
+	backdrop-filter: none;
+	-webkit-backdrop-filter: none;
+	box-shadow:
+		0 24px 60px -20px rgba(12, 11, 10, 0.5),
+		inset 0 0 0 1px color-mix(in srgb, var(--hw-dock-ink) 16%, transparent);
+}
+/* The visitor's own message. A 16%-white pill on the panel measured 1.49:1
+   against it — it was nearly not there. It is the solid object of the thread. */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-msg--visitor .hw-msg-bubble {
+	background: var(--hw-dock-ink);
+	color: var(--hw-dock-tint);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-msg--visitor .hw-msg-bubble a,
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-msg--visitor .hw-msg-bubble a:hover {
+	color: inherit;
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"]
+	:is(
+		.hw-dock-send:not(:disabled),
+		.hw-quick-reply-btn,
+		.hw-quick-reply-btn:hover:not(:disabled),
+		.hw-email-card-submit,
+		.hw-offer,
+		.hw-offer:hover
+	) {
+	background: var(--hw-dock-ink);
+	color: var(--hw-dock-tint);
+}
+/* Places the glass block wrote white by hand. They take the ink. */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"]
+	:is(
+		.hw-preview-body,
+		.hw-header-close:hover,
+		.hw-header-menu-btn:hover,
+		.hw-preview-close:hover,
+		.hw-quick-reply-btn[data-tapped="true"]
+	) {
+	color: var(--hw-dock-ink);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] :is(.hw-preview-close, .hw-preview-footer) {
+	color: var(--hw-dock-ink-2);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-quick-reply-btn[data-tapped="true"] {
+	background: color-mix(in srgb, var(--hw-dock-wash) 22%, transparent);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-window :focus-visible {
+	outline-color: var(--hw-dock-ink);
+}
+/* Code and the email row sat on a black wash. Under dark ink that is the
+   wrong direction; the shade is always the right one. */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-msg-bubble :is(pre, code),
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-email-card-row {
+	background: color-mix(in srgb, var(--hw-dock-shade) 26%, transparent);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-header-menu {
+	background: color-mix(in srgb, var(--hw-dock-shade) 34%, var(--hw-dock-tint));
+	color: var(--hw-dock-ink);
+}
+/* Initials are a solid object too. A 12%-white disc with white letters is a
+   faint ring on a brand colour, and nothing at all on a light one. */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] :is(.hw-header-bot-icon--team, .hw-event-avatar) {
+	background: var(--hw-dock-ink);
+	color: var(--hw-dock-tint);
+}
+/* The bar's placeholder is an instruction ("Reply to reopen…"), so it is
+   held to the text floor, not to the 45% a hint gets on glass. */
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-dock-input::placeholder {
+	color: var(--hw-dock-ink-3);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-typing-dot {
+	background: var(--hw-dock-ink-2);
+}
+.hw-widget[data-hw-placement="docked"][data-hw-dock-surface="brand"] .hw-disconnect {
+	background: color-mix(in srgb, var(--hw-dock-shade) 16%, transparent);
+	color: var(--hw-dock-ink-2);
+}