@glasshome/ui 1.1.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@glasshome/ui",
-	"version": "1.1.2",
+	"version": "1.3.0",
 	"description": "SolidJS component library for GlassHome, built on Kobalte",
 	"type": "module",
 	"homepage": "https://github.com/glasshome/ui#readme",
@@ -53,14 +53,16 @@
 		"src/astro",
 		"src/lib",
 		"src/styles",
-		"scripts"
+		"scripts",
+		"SPEC.md"
 	],
 	"scripts": {
-		"build": "vite build && tsc",
+		"build": "rm -rf dist && vite build && tsc",
+		"check:structural": "bun scripts/check-structural-classes.ts",
 		"check:tokens": "bun scripts/check-tokens.ts",
 		"check:types": "tsc --noEmit -p tsconfig.test.json",
 		"check:publish": "publint && attw --pack . --profile esm-only --exclude-entrypoints ./styles ./styles/theme",
-		"dev": "vite build --watch",
+		"dev": "tsc -b --force && vite build --watch",
 		"lint": "biome check .",
 		"test": "vitest run",
 		"test:watch": "vitest",

package/scripts/check-structural-classes.ts

@@ -0,0 +1,43 @@
+// Gate B3 (sdk-contract-hardening.md): a package class string may not depend on the consumer's
+// Tailwind scanning package source. Arbitrary variants like `[&>svg]:` are the
+// tell: unlike plain utilities, no consumer's own code coincidentally
+// generates them, so they silently vanish for any consumer whose build never
+// scans this package (the stacked-carousel break). Structural child styling
+// ships as real CSS in styles/globals.css instead (see .carousel-stack,
+// .gh-alert-*). Escape hatch: a `structural-ok: <reason>` comment on or
+// directly above the offending line.
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const LIB_DIR = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../src/lib");
+const ARBITRARY_VARIANT = /\[&[^\]]*\]:/;
+const COMMENT_LINE = /^\s*(\/\/|\/\*|\*)/;
+
+let findings = 0;
+
+for (const entry of readdirSync(LIB_DIR).sort()) {
+	if (!entry.endsWith(".ts") || entry.endsWith(".test.ts")) continue;
+	const file = path.join(LIB_DIR, entry);
+	const lines = readFileSync(file, "utf8").split("\n");
+	lines.forEach((text, i) => {
+		if (COMMENT_LINE.test(text)) return;
+		if (!ARBITRARY_VARIANT.test(text)) return;
+		if (text.includes("structural-ok:")) return;
+		// Walk the comment block directly above for the escape marker.
+		for (let j = i - 1; j >= 0 && COMMENT_LINE.test(lines[j] ?? ""); j--) {
+			if (lines[j]?.includes("structural-ok:")) return;
+		}
+		findings++;
+		console.error(
+			`src/lib/${entry}:${i + 1}  consumer-generated structural class (arbitrary variant): ${text.trim().slice(0, 120)}`,
+		);
+	});
+}
+
+if (findings > 0) {
+	console.error(
+		`\n${findings} arbitrary variant(s) in lib class modules. Move the styling to real CSS in src/styles/globals.css (see .carousel-stack) or annotate with a \`structural-ok: <reason>\` comment.`,
+	);
+	process.exit(1);
+}
+console.log("check-structural-classes: lib class strings are consumer-independent.");

package/src/lib/alert-tones.ts

@@ -47,10 +47,12 @@ export const alertIconFill = (c: string) => `color-mix(in srgb, ${c} 16%, transp
 
 export const ALERT_CLASS =
 	"relative overflow-hidden flex items-start gap-3 rounded-lg border p-3 backdrop-blur-sm";
+/* gh-alert-* svg chrome lives in globals.css as real CSS: an arbitrary variant
+ * here only works if the consumer's Tailwind scans package source. */
 export const ALERT_ICON_CLASS =
-	"flex size-8 shrink-0 items-center justify-center rounded-md [&>svg]:size-[18px]";
+	"gh-alert-icon flex size-8 shrink-0 items-center justify-center rounded-md";
 export const ALERT_ICON_BG_CLASS =
-	"pointer-events-none absolute -right-3 -bottom-4 [&>svg]:size-28 [&>svg]:[stroke-width:2.5px]";
+	"gh-alert-icon-bg pointer-events-none absolute -right-3 -bottom-4";
 export function alertIconBgStyle(color: string): Record<string, string> {
 	return {
 		color,
@@ -61,5 +63,4 @@ export function alertIconBgStyle(color: string): Record<string, string> {
 }
 export const ALERT_CONTENT_CLASS = "relative z-10 min-w-0 flex-1";
 export const ALERT_TITLE_CLASS = "font-semibold text-base leading-snug";
-export const ALERT_DESCRIPTION_CLASS =
-	"text-foreground/80 text-sm leading-snug [&:not(:first-child)]:mt-0.5";
+export const ALERT_DESCRIPTION_CLASS = "gh-alert-desc text-foreground/80 text-sm leading-snug";

package/src/lib/button-variants.ts

@@ -4,6 +4,9 @@ import { cva } from "cva";
  * muddy over dark heroes/sections. Every class is literal for Tailwind's
  * scanner. `size: none` is sizeless for callers that own height/padding. */
 export const buttonVariants = cva({
+	// structural-ok: the [&_svg]: utilities stay in Tailwind's utility layer so a
+	// caller's own [&_svg]:size-* override can still win; unlayered real CSS in
+	// globals.css would beat every consumer utility regardless of specificity.
 	base: "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-full font-medium text-sm outline-none transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
 	variants: {
 		variant: {

package/src/lib/input-classes.ts

@@ -1,5 +1,20 @@
-/* Recessed (concave) glass field. Opaque --input fill: a translucent field
- * shows whatever sits behind it (worst inside the overlapping Select listbox). */
-export const INPUT_SURFACE = "glass glass-sink [--glass-base:var(--input)] [--glass-light:0.04]";
+/* Recessed (concave) glass field: text inputs, textareas, and the pickers that
+ * wear a field (Select trigger + listbox, EntitySelector, AreaPicker). The fill
+ * and edge come from the theme's --field/--field-edge pair rather than --input
+ * directly, because the two themes need different material: on a dark ground a
+ * dug-out fill reads as depth, on a light one the same drop reads as `disabled`,
+ * so light fields sit at the card and carry a solid border instead. Both are
+ * opaque — a translucent field shows whatever sits behind it (worst inside the
+ * overlapping Select listbox). The recess itself is .glass-sink's rim, which is
+ * theme independent. */
+export const INPUT_SURFACE =
+	"glass glass-sink [--glass-base:var(--field)] [--glass-edge:var(--field-edge)] [--glass-light:0.04]";
+
+/* Toggle-family chrome and rails: checkbox box, radio ring, switch track, slider
+ * rail, chart wells. Same concave glass, but keyed to --input in both themes:
+ * these are not fields you type into, they are unfilled controls whose whole job
+ * is to read as an empty well, so the fill must stay visibly below the card even
+ * in the light theme. */
+export const FIELD_CHROME = "glass glass-sink [--glass-base:var(--input)] [--glass-light:0.04]";
 
 export const INPUT_CLASS = `flex h-9 w-full min-w-0 rounded-md ${INPUT_SURFACE} px-3 py-1 text-base outline-none transition-[color,box-shadow] selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:font-medium file:text-foreground file:text-sm placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40`;

package/src/lib/overlay-classes.ts

@@ -1,7 +1,23 @@
-/* Floating-panel glass: opaque popover fill so menus stay legible over anything. */
-export const OVERLAY_SURFACE =
-	"glass [--glass-base:var(--popover)] [--glass-rim:0.3] [--glass-lift:0.55]";
+/* Rim/sheen raised above card level (0.3/0.05) so the bevel and highlight read
+ * on large panels instead of smearing into a flat matte gray. */
+const OVERLAY_KNOBS =
+	"glass [--glass-rim:1] [--glass-lift:0.6] [--glass-light:0.05] [--glass-edge:color-mix(in_srgb,var(--border)_90%,transparent)]";
+
+/* Split from the surface the way CARD_BLUR is, so a host can gate it off and
+ * paint a precomputed frost instead. */
+export const OVERLAY_BLUR = "backdrop-blur-[var(--glass-blur,20px)] backdrop-saturate-[1.6]";
+
+export const OVERLAY_SURFACE_BASE = `${OVERLAY_KNOBS} [--glass-base:color-mix(in_srgb,var(--popover)_75%,transparent)]`;
+
+/* Floating-panel glass: translucent popover fill over a blur, so a menu reads
+ * as glass and not as a flat plate. */
+export const OVERLAY_SURFACE = `${OVERLAY_SURFACE_BASE} ${OVERLAY_BLUR}`;
+
+/* Opaque fill, no blur: the drag-animated surfaces (BottomSheet), where
+ * backdrop-blur is too slow on mobile and a translucent fill with no blur
+ * behind it would just be see-through. */
+export const OVERLAY_SURFACE_OPAQUE = `${OVERLAY_KNOBS} [--glass-base:var(--popover)]`;
 
 /* Modal scrim behind dialogs/sheets. BottomSheet keeps its own unblurred scrim
  * (backdrop-blur is too slow on mobile). */
-export const SCRIM_CLASS = "bg-background/70 backdrop-blur-sm";
+export const SCRIM_CLASS = "bg-background/70 backdrop-blur-md";

package/src/styles/globals.css

@@ -26,6 +26,15 @@
 	inherits: false;
 	initial-value: 0.05;
 }
+/* Size of the top-left sheen ellipse, `<x> <y>`. Percentages scale with the
+ * element, which is right for cards but leaves an edge-anchored panel (a side
+ * sheet is narrow and viewport-tall) with a small blob over a flat matte field.
+ * Such surfaces pin absolute lengths so the highlight reads the same as on a
+ * dialog. Untyped: two values, so no single @property syntax fits. */
+@property --glass-sheen {
+	syntax: "*";
+	inherits: false;
+}
 @property --glass-shade {
 	syntax: "<number>";
 	inherits: false;
@@ -109,18 +118,29 @@
 	 * children can read it; a nested .glass re-declares it from its own knob,
 	 * which resets the chain and keeps the no-leak guarantee. */
 	--surface-tone: var(--glass-tone);
+	/* Second tint axis. Ordinary (inheriting) properties, so they are re-declared
+	 * on every .glass to reset the chain at each glass boundary (same no-leak
+	 * trick as --surface-tone). Defaults reproduce the single-tone wash exactly;
+	 * override tone-2/wash-2/angle together for a two-tone tint (slider fills). */
+	--glass-tone-2: var(--glass-tone);
+	--glass-wash-2: calc(var(--glass-wash) / 3);
+	--glass-wash-angle: 135deg;
 	border: 1px solid var(--glass-edge);
 	/* Base is a gradient layer (not background-color) so the frost slice can sit
 	 * BELOW it — background-color always paints under every image layer, which
 	 * would put the frost above the fill. Layer order top→bottom: light, shade,
 	 * tone wash, base fill, frost. */
 	background:
-		radial-gradient(120% 120% at 22% 8%, oklch(1 0 0 / var(--glass-light)), transparent 58%),
+		radial-gradient(
+			var(--glass-sheen, 120% 120%) at 22% 8%,
+			oklch(1 0 0 / var(--glass-light)),
+			transparent 58%
+		),
 		radial-gradient(120% 120% at 82% 100%, oklch(0 0 0 / var(--glass-shade)), transparent 58%),
 		linear-gradient(
-			135deg,
+			var(--glass-wash-angle),
 			color-mix(in srgb, var(--glass-tone) var(--glass-wash), transparent),
-			color-mix(in srgb, var(--glass-tone) calc(var(--glass-wash) / 3), transparent)
+			color-mix(in srgb, var(--glass-tone-2) var(--glass-wash-2), transparent)
 		),
 		linear-gradient(var(--glass-base), var(--glass-base)), var(--glass-frost, none);
 	box-shadow:
@@ -130,6 +150,32 @@
 		0 10px 30px -16px oklch(0 0 0 / var(--glass-lift));
 }
 
+/* Two-tone edge: border-color cannot gradient, so the border goes transparent
+ * and a masked 1px ring runs tone-1→tone-2 at the .glass-tint edge alpha.
+ * Must stay unlayered (the formula's border is unlayered and beats any @layer)
+ * and must read the inheriting mirrors, not the inherits:false knobs, which
+ * resolve to initial on a pseudo. Element must be positioned. */
+:where(.glass-edge-gradient) {
+	border-color: transparent;
+}
+:where(.glass-edge-gradient)::before {
+	content: "";
+	position: absolute;
+	inset: 0;
+	border-radius: inherit;
+	padding: 1px;
+	background: linear-gradient(
+		var(--glass-wash-angle),
+		oklch(from var(--surface-tone) l c h / 0.45),
+		oklch(from var(--glass-tone-2) l c h / 0.45)
+	);
+	mask:
+		linear-gradient(#fff 0 0) content-box,
+		linear-gradient(#fff 0 0);
+	mask-composite: exclude;
+	pointer-events: none;
+}
+
 /* PageHeader banner surface: bespoke three-stop card gradient (its material
  * predates the one-glass formula) over the same frost slot .glass uses, so
  * hosts wire the performant-blur engine identically on both. Frost defaults
@@ -171,6 +217,22 @@
 	}
 }
 
+/* Alert/toast icon chrome + description spacing: structural (same rationale as
+ * .carousel-stack below), so real CSS instead of [&>svg]: arbitrary variants.
+ * Values mirror the former utilities: size-[18px], size-28, mt-0.5. */
+.gh-alert-icon > svg {
+	width: 18px;
+	height: 18px;
+}
+.gh-alert-icon-bg > svg {
+	width: 7rem;
+	height: 7rem;
+	stroke-width: 2.5px;
+}
+.gh-alert-desc:not(:first-child) {
+	margin-top: 0.125rem;
+}
+
 /* Stacked carousel modes (fade, wipe) put every slide in one grid cell. This is
  * structural, so it ships as real CSS: a Tailwind arbitrary variant written in
  * package source never reaches a consumer, because Tailwind skips node_modules

package/src/styles/theme.css

@@ -126,15 +126,31 @@
 	--muted-foreground: oklch(0.34 0 0);
 	--accent: oklch(0.6 0.2 195);
 	--accent-foreground: oklch(1 0 0);
-	--success: oklch(0.65 0.17 145);
-	--warning: oklch(0.75 0.14 85);
+	/* Semantic roles are one value per role, used as fill AND as text, so on this
+	 * L=0.975 ground they have to clear 4.5:1 (3:1 for --ring, a focus indicator)
+	 * against --background and --card. The dark theme's high-lightness versions
+	 * measure 2.1-3.6:1 here, so the light theme drops lightness and holds hue;
+	 * chroma comes down only as far as staying near the sRGB gamut edge needs.
+	 * Measured vs --background / --card / white-on-fill:
+	 *   success 5.24 / 5.56 / 5.63, warning 5.17 / 5.49 / 5.55,
+	 *   destructive 5.21 / 5.53 / 5.59, ring 4.68 / 4.97 / 5.03. */
+	--success: oklch(0.5 0.15 145);
+	--warning: oklch(0.52 0.13 85);
 	--primary-tint-foreground: oklch(0.42 0.2 215.221);
 	--accent-tint-foreground: oklch(0.46 0.16 195);
-	--destructive: oklch(0.629 0.1902 23.0704);
+	--destructive: oklch(0.54 0.19 23.0704);
 	--destructive-foreground: oklch(1 0 0);
 	--border: oklch(0.9 0.01 250);
 	--input: oklch(0.9 0.012 250);
-	--ring: oklch(0.6 0.2 195);
+	--ring: oklch(0.53 0.18 195);
+	/* Field material (INPUT_SURFACE). The recess is the .glass-sink rim, not a
+	 * darker fill: on a card of L=0.995 an --input fill of L=0.9 is a nine-point
+	 * drop, the same cue this library spends on `disabled`, so a form of light
+	 * fields reads switched off. Light fields sit AT the card and get a solid
+	 * --border edge instead — the boundary still measures 1.33:1 against the
+	 * card, exactly what the fill drop used to carry, at 1px instead of a slab. */
+	--field: var(--card);
+	--field-edge: var(--border);
 	--chart-1: oklch(0.7459 0.1483 156.4499);
 	--chart-2: oklch(0.48 0.2 215.221);
 	--chart-3: oklch(0.7336 0.1758 50.5517);
@@ -192,11 +208,16 @@
 	--destructive: oklch(0.7106 0.1661 22.2162);
 	--destructive-foreground: oklch(1 0 0);
 	--border: oklch(0.26 0.012 250);
-	/* Recessed fields read DARKER than the card they're dug out of (card is 0.17),
-	 * so a field surface sits below it, matching the slider track. A hair of the
-	 * card's cool tint (chroma 0.01) keeps it from going flat gray. */
+	/* On a dark ground a dug-out surface catches more light than the wall around
+	 * it, so the field sits a touch ABOVE the card (0.17) rather than below, and
+	 * the .glass-sink rim does the rest. A hair of the card's cool tint (chroma
+	 * 0.01) keeps it from going flat gray. Same rail color as the slider track. */
 	--input: oklch(0.19 0.01 250);
 	--ring: oklch(0.6 0.2 195);
+	/* Dark fields keep the dug-out fill (it reads as depth here, not as disabled)
+	 * and the glass formula's own soft edge. See the light block. */
+	--field: var(--input);
+	--field-edge: color-mix(in srgb, var(--border) 60%, transparent);
 	--chart-1: oklch(0.8003 0.1821 151.711);
 	--chart-2: oklch(0.48 0.2 215.221);
 	--chart-3: oklch(0.8077 0.1035 19.5706);