@helpway/react 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@helpway/react",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Official React SDK for Helpway — drop-in AI chat support widget with headless hooks for custom UIs.",
 	"keywords": [
 		"helpway",
@@ -40,6 +40,7 @@
 	"scripts": {
 		"build": "tsup",
 		"typecheck": "tsc --noEmit",
+		"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"
@@ -47,14 +48,15 @@
 	"//": "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": {
 		"@trpc/client": "^11.5.1",
-		"zustand": "^5.0.11",
-		"@central-icons-react/round-outlined-radius-2-stroke-2": "^1.1.178"
+		"zustand": "^5.0.11"
 	},
 	"devDependencies": {
 		"@helpway/types": "workspace:*",
 		"@helpway/widget-core": "workspace:*",
 		"@types/react": "^19.1.6",
 		"@types/react-dom": "^19.1.6",
+		"@central-icons-react/round-outlined-radius-2-stroke-2": "^1.1.213",
+		"react-dom": "^19.1.6",
 		"tsup": "^8.3.5",
 		"typescript": "~5.9.3"
 	},

package/src/themed/styles.css

@@ -45,6 +45,15 @@
 .hw-widget {
 	--hw-primary: #171717;
 	--hw-primary-hover: #2a2a2a;
+	/* Brand surface used by team-avatar fallbacks and primary CTAs.
+	   In light mode this is the host brand color (default near-black).
+	   Dark overrides redefine to a high-contrast value so the brand tile
+	   stays visible on dark surfaces. Customers override --hw-brand to
+	   theme team avatars + primary CTAs in one shot. */
+	--hw-brand: #171717;
+	/* Foreground (text/svg) that sits on --hw-brand. Inverts in dark so
+	   light-on-light never happens after the brand-token flip. */
+	--hw-on-brand: #ffffff;
 	/* Focus ring tokens — used by composer + content search + any future
 	   input. Kept as variables so the dark override gets a proper contrast
 	   pair instead of a one-off per-component tweak. */
@@ -304,6 +313,20 @@
 	flex-direction: column;
 	overflow: hidden;
 	animation: hw-window-open 0.35s cubic-bezier(0.34, 1.56, 0.64, 1);
+	/* Smooth size transition for reading-mode expansion. The open animation
+	   is one-shot (transform/opacity) so it doesn't conflict with this. */
+	transition:
+		width 280ms cubic-bezier(0.4, 0, 0.2, 1),
+		height 280ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* Reading mode — applied when the visitor enters a content detail view
+   (help article, changelog entry). Wider + taller for comfortable long-form
+   reading. Mobile (<480px) ignores this — the @media block forces 100% +
+   beats this rule by source order. */
+.hw-window--reading {
+	width: min(720px, calc(100vw - 40px));
+	height: min(800px, calc(100vh - 100px));
 }
 
 @keyframes hw-window-open {
@@ -536,7 +559,7 @@
 }
 .hw-header-bot-icon--team {
 	background: var(--hw-brand, #0a0a0a);
-	color: #fff;
+	color: var(--hw-on-brand, #fff);
 }
 .hw-header-agent-img {
 	width: 100%;
@@ -907,7 +930,7 @@
 }
 .hw-conv-card-avatar--team {
 	background: var(--hw-brand, #0a0a0a);
-	color: #fff;
+	color: var(--hw-on-brand, #fff);
 }
 .hw-conv-card-avatar-initials {
 	font-size: 12px;
@@ -1173,6 +1196,11 @@
 	opacity: 0.3;
 }
 
+.hw-empty-text {
+	font-size: 13px;
+	/* color inherited from .hw-empty (--hw-text-3) — adapts in dark */
+}
+
 /* ── Date Separator ──────────────────────────── */
 .hw-date-sep {
 	display: flex;
@@ -1294,7 +1322,7 @@
 	box-sizing: border-box;
 }
 
-/* Meta (clock always visible; sender/copy reveal on hover) */
+/* Meta (fully hidden; sender label + copy icon reveal on hover) */
 .hw-msg-meta {
 	display: inline-flex;
 	align-items: center;
@@ -1303,29 +1331,25 @@
 	color: var(--hw-text-3);
 	margin-top: 3px;
 	padding: 0 4px;
-	opacity: 1;
-	font-variant-numeric: tabular-nums;
-	min-height: 20px;
-}
-
-.hw-msg-time {
-	opacity: 0.72;
-}
-
-.hw-msg-hover-meta {
-	max-width: 0;
 	opacity: 0;
+	font-variant-numeric: tabular-nums;
+	min-height: 0;
+	height: 0;
 	overflow: hidden;
-	white-space: nowrap;
 	transition:
-		max-width 180ms ease,
-		opacity 140ms ease;
+		opacity 140ms ease,
+		height 140ms ease;
 }
 
-.hw-msg:hover .hw-msg-hover-meta,
-.hw-msg:focus-within .hw-msg-hover-meta {
-	max-width: 180px;
+.hw-msg:hover .hw-msg-meta,
+.hw-msg:focus-within .hw-msg-meta {
 	opacity: 1;
+	height: 20px;
+	min-height: 20px;
+}
+
+.hw-msg-sender-label {
+	white-space: nowrap;
 }
 
 .hw-msg--visitor .hw-msg-meta {
@@ -1556,6 +1580,59 @@
 	background: var(--hw-bg);
 }
 
+/* ── Skeleton: Article detail ──────────────────
+   Designed to be PIXEL-EQUIVALENT to the rendered article so content can land
+   without reflow. Maps 1:1 to:
+     <div class="hw-content-detail">
+       <div class="hw-content-detail-header">  ← title (22px line) + meta row
+       <div class="hw-content-detail-body">
+         <div class="hw-markdown">
+           <h2>...</h2>                        ← section header (~16px line)
+           <ul><li>**Bold:** desc...</li></ul> ← bullet item, 2 visible lines
+           <ul><li>...</li></ul>
+   The skeleton uses the SAME outer classes for padding/spacing, then injects
+   shimmer bars where text would render. */
+
+.hw-skeleton-title {
+	height: 22px;
+	width: 65%;
+	border-radius: 6px;
+}
+
+.hw-skeleton-badge {
+	width: 42px;
+	height: 18px;
+	border-radius: 9px;
+}
+
+.hw-skeleton-date {
+	width: 60px;
+	height: 12px;
+	border-radius: 6px;
+}
+
+.hw-skeleton-h2 {
+	height: 16px;
+	border-radius: 6px;
+}
+
+/* Bullet wrapper — emulates <ul> padding-left: 20px so the skeleton bullet
+   text starts at the same x-coordinate as the real <li>'s text content. */
+.hw-skeleton-bullet {
+	padding-left: 20px;
+	display: flex;
+	flex-direction: column;
+	gap: 8px;
+}
+
+/* Each "line" inside a bullet — line-height: 14 matches the visible text mass
+   of body text (font-size 14 × line-height 1.6 = 22.4 visible bbox, but skeleton
+   bar is the visible-character thickness only). */
+.hw-skeleton-bullet-line {
+	height: 14px;
+	border-radius: 7px;
+}
+
 /* ════════════════════════════════════════════════
    EMAIL COLLECTION CARD (fixed above composer)
    ════════════════════════════════════════════════ */
@@ -1565,7 +1642,7 @@
 	padding: 14px 16px 10px;
 	border: 1px solid var(--hw-border, rgba(0,0,0,0.08));
 	border-radius: 14px;
-	background: var(--hw-surface, #fff);
+	background: var(--hw-bg, #fff);
 	box-shadow: 0 1px 4px rgba(0,0,0,0.06), 0 4px 12px rgba(0,0,0,0.03);
 	animation: hw-email-slide-in 0.25s ease-out;
 }
@@ -1587,11 +1664,11 @@
 	width: 32px;
 	height: 32px;
 	border-radius: 8px;
-	background: var(--hw-brand, #0a0a0a);
+	background: var(--hw-bg-hover, #f5f5f5);
 	display: flex;
 	align-items: center;
 	justify-content: center;
-	color: #fff;
+	color: var(--hw-text, #1a1a1a);
 }
 
 .hw-email-card-title {
@@ -1604,7 +1681,7 @@
 
 .hw-email-card-subtitle {
 	font-size: 12px;
-	color: var(--hw-text-muted, #888);
+	color: var(--hw-text-2, #888);
 	line-height: 1.4;
 	margin: 0;
 }
@@ -1614,18 +1691,22 @@
 	padding: 9px 12px;
 	border-radius: 10px;
 	border: 1px solid var(--hw-border, rgba(0,0,0,0.1));
-	background: var(--hw-bg, #fafafa);
+	background: var(--hw-bg-subtle, #fafafa);
 	color: var(--hw-text, #1a1a1a);
 	font-size: 13px;
 	outline: none;
 	margin-bottom: 8px;
 	box-sizing: border-box;
-	transition: border-color 0.15s;
+	transition: border-color 0.15s, box-shadow 0.15s;
+}
+
+.hw-email-card-input::placeholder {
+	color: var(--hw-text-3, #999);
 }
 
 .hw-email-card-input:focus {
-	border-color: var(--hw-brand, #0a0a0a);
-	box-shadow: 0 0 0 2px rgba(0,0,0,0.06);
+	border-color: var(--hw-focus-border, rgba(0,0,0,0.2));
+	box-shadow: 0 0 0 2px var(--hw-focus-ring, rgba(0,0,0,0.06));
 }
 
 .hw-email-card-input--error {
@@ -1638,7 +1719,7 @@
 	border-radius: 10px;
 	border: none;
 	background: var(--hw-brand, #0a0a0a);
-	color: #fff;
+	color: var(--hw-on-brand, #fff);
 	font-size: 13px;
 	font-weight: 500;
 	cursor: pointer;
@@ -1665,7 +1746,7 @@
 	gap: 6px;
 	padding: 10px 16px;
 	font-size: 13px;
-	color: var(--hw-text-muted, #888);
+	color: var(--hw-text-2, #888);
 	animation: hw-email-slide-in 0.2s ease-out;
 }
 
@@ -2159,8 +2240,8 @@
 	width: 32px;
 	height: 32px;
 	border-radius: 50%;
-	background: #e0e0e0;
-	color: #555;
+	background: var(--hw-bg-hover, #e0e0e0);
+	color: var(--hw-text-2, #555);
 	display: flex;
 	align-items: center;
 	justify-content: center;
@@ -2685,31 +2766,92 @@
 	color: var(--hw-text-1);
 }
 
-/* ── Markdown Rendering ────────────────────────────────── */
+/* ── Markdown Rendering ──────────────────────────────────
+   Heading vertical spacing is governed by the adjacency rules further
+   down (.hw-markdown > * + h2, etc.). Keeping margin: 0 here prevents
+   the heading's own bottom margin from compounding with the sibling's
+   top margin (e.g. h2 8px + p 12px = 20px instead of 12px). */
 .hw-markdown h1 {
 	font-size: 17px;
 	font-weight: 700;
-	margin: 20px 0 8px;
+	margin: 0;
 }
 
 .hw-markdown h2 {
 	font-size: 15px;
 	font-weight: 600;
-	margin: 16px 0 6px;
+	margin: 0;
 }
 
 .hw-markdown h3 {
 	font-size: 14px;
 	font-weight: 600;
-	margin: 12px 0 4px;
+	margin: 0;
 }
 
 .hw-markdown p {
-	margin: 0 0 12px;
+	margin: 0;
+}
+
+/* Rich-text editors (PlateJS, Slate, ProseMirror) emit any of:
+     <p><br></p>           ← visual line break paragraph
+     <p></p>               ← empty paragraph
+     <div><br></div>       ← editor block element (PlateJS default)
+     <div></div>           ← empty block
+   Each contributes line-height + margin twice → 50-70px gap between items.
+   Hide them all so spacing is governed by the adjacency rules below. */
+.hw-markdown p:empty,
+.hw-markdown div:empty,
+.hw-markdown p:has(> br:only-child),
+.hw-markdown div:has(> br:only-child) {
+	display: none;
+}
+
+/* Adjacency-based spacing — works for any block element type the CMS emits
+   (<p>, <div>, custom). Combined with the JS post-render cleanup in
+   simple-markdown.tsx (which strips whitespace-only blocks like <p>&nbsp;</p>
+   that CSS :empty can't match), this gives consistent spacing regardless of
+   editor format. */
+.hw-markdown > * + * {
+	margin-top: 12px;
+}
+
+.hw-markdown > * + h1,
+.hw-markdown > * + h2 {
+	margin-top: 20px;
+}
+
+.hw-markdown > * + h3 {
+	margin-top: 16px;
+}
+
+.hw-markdown > h1 + *,
+.hw-markdown > h2 + *,
+.hw-markdown > h3 + * {
+	margin-top: 8px;
+}
+
+/* First/last child margin reset so the body's outer padding is the only
+   spacing that surrounds the article. */
+.hw-markdown > *:first-child {
+	margin-top: 0;
+}
+
+.hw-markdown > *:last-child {
+	margin-bottom: 0;
+}
+
+/* Better i18n CMS emits standalone <br> elements at the markdown root as
+   visual separators between consecutive <ul> bullet groups. Each <br>
+   contributed ~22px line-height + adjacency margins on both sides, creating
+   the 40-50px gap between items. Hide them — the adjacency rule alone gives
+   the 12px gap we want. */
+.hw-markdown > br {
+	display: none;
 }
 
 .hw-markdown ul {
-	margin: 0 0 12px;
+	margin: 0;
 	padding-left: 20px;
 }
 
@@ -3069,6 +3211,9 @@
 	}
 	.hw-msg-meta {
 		opacity: 1;
+		height: auto;
+		min-height: 20px;
+		overflow: visible;
 	}
 	.hw-msg-copy {
 		opacity: 1;
@@ -3524,6 +3669,10 @@
 	--hw-visitor-bubble-text: #f5f5f5;
 	--hw-focus-border: rgba(255, 255, 255, 0.28);
 	--hw-focus-ring: rgba(255, 255, 255, 0.08);
+	/* Brand inverts in dark — light tile on dark surface keeps team avatars
+	   and primary CTAs readable. Same pattern as iOS dark mode tints. */
+	--hw-brand: #f5f5f5;
+	--hw-on-brand: #1c1c1e;
 }
 
 @media (prefers-color-scheme: dark) {
@@ -3560,6 +3709,9 @@
 		/* Focus ring in dark needs lighter border + subtle halo. */
 		--hw-focus-border: rgba(255, 255, 255, 0.28);
 		--hw-focus-ring: rgba(255, 255, 255, 0.08);
+		/* See --hw-brand comment in [data-theme="dark"] block. */
+		--hw-brand: #f5f5f5;
+		--hw-on-brand: #1c1c1e;
 	}
 }