@parallelworks/ui 0.1.0

package/dist/theme/index.d.ts

@@ -0,0 +1,27 @@
+export declare const THEME_TOKENS: readonly ['--theme-app-bg', '--theme-app', '--theme-panel-bg', '--theme-panel', '--theme-muted-panel-bg', '--theme-muted-panel-color', '--theme-muted-text-color', '--theme-border', '--theme-element', '--theme-element-text', '--theme-hover', '--theme-hover-text', '--theme-link', '--theme-input-bg', '--theme-input', '--theme-input-disabled-bg', '--theme-input-disabled-text', '--theme-card-bg', '--theme-card-border', '--theme-card-hover', '--theme-accent', '--theme-accent-text', '--theme-focus-ring', '--theme-hover-overlay', '--theme-success', '--theme-success-muted', '--theme-error', '--theme-error-muted', '--theme-warning', '--theme-warning-muted', '--theme-info', '--theme-info-muted', '--theme-favorite', '--theme-favorite-muted', '--theme-shadow-sm', '--theme-shadow', '--theme-shadow-lg', '--theme-bg', '--theme-sidebar-text', '--theme-sidebar-hover', '--theme-sidebar-hover-text', '--theme-sidebar-active-bg', '--theme-sidebar-active-text'];
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+export type ThemeVariables = Record<ThemeToken, string>;
+export interface ThemeSeed {
+    /** Accent color as a hex string, e.g. '#06354f'. */
+    accent: string;
+    /** Base background color as a hex string. */
+    background: string;
+    /** How far foregrounds and borders sit from the background. 1 is normal; sensible range is roughly 0.5–1.5. */
+    contrast?: number;
+}
+export interface SurfaceSeeds {
+    interface: ThemeSeed;
+    sidebar?: ThemeSeed;
+}
+export declare function contrastRatio(a: string, b: string): number;
+/** Uses the WCAG luminance threshold 0.179, matching how org themes classify backgrounds. */
+export declare function isDarkColor(hex: string): boolean;
+export declare function deriveTheme(seed: ThemeSeed | SurfaceSeeds): ThemeVariables;
+export interface ThemePreset {
+    name: string;
+    label: string;
+    seed: SurfaceSeeds;
+}
+export declare const THEME_PRESETS: readonly ThemePreset[];
+export declare const DEFAULT_PRESET: ThemePreset;
+export declare function applyTheme(el: HTMLElement, vars: Partial<ThemeVariables>): void;

package/dist/theme/index.js

@@ -0,0 +1,272 @@
+//#region src/theme/index.ts
+var THEME_TOKENS = [
+	"--theme-app-bg",
+	"--theme-app",
+	"--theme-panel-bg",
+	"--theme-panel",
+	"--theme-muted-panel-bg",
+	"--theme-muted-panel-color",
+	"--theme-muted-text-color",
+	"--theme-border",
+	"--theme-element",
+	"--theme-element-text",
+	"--theme-hover",
+	"--theme-hover-text",
+	"--theme-link",
+	"--theme-input-bg",
+	"--theme-input",
+	"--theme-input-disabled-bg",
+	"--theme-input-disabled-text",
+	"--theme-card-bg",
+	"--theme-card-border",
+	"--theme-card-hover",
+	"--theme-accent",
+	"--theme-accent-text",
+	"--theme-focus-ring",
+	"--theme-hover-overlay",
+	"--theme-success",
+	"--theme-success-muted",
+	"--theme-error",
+	"--theme-error-muted",
+	"--theme-warning",
+	"--theme-warning-muted",
+	"--theme-info",
+	"--theme-info-muted",
+	"--theme-favorite",
+	"--theme-favorite-muted",
+	"--theme-shadow-sm",
+	"--theme-shadow",
+	"--theme-shadow-lg",
+	"--theme-bg",
+	"--theme-sidebar-text",
+	"--theme-sidebar-hover",
+	"--theme-sidebar-hover-text",
+	"--theme-sidebar-active-bg",
+	"--theme-sidebar-active-text"
+];
+function parseHex(hex) {
+	const m = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+	if (!m) throw new Error(`Invalid hex color: ${hex}`);
+	return [
+		Number.parseInt(m[1], 16),
+		Number.parseInt(m[2], 16),
+		Number.parseInt(m[3], 16)
+	];
+}
+function toHex([r, g, b]) {
+	const c = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0");
+	return `#${c(r)}${c(g)}${c(b)}`;
+}
+/** Linear interpolation from `a` toward `b` by `t` in sRGB. */
+function mix(a, b, t) {
+	const ca = parseHex(a);
+	const cb = parseHex(b);
+	return toHex([
+		ca[0] + (cb[0] - ca[0]) * t,
+		ca[1] + (cb[1] - ca[1]) * t,
+		ca[2] + (cb[2] - ca[2]) * t
+	]);
+}
+function alpha(hex, a) {
+	const [r, g, b] = parseHex(hex);
+	return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+function relativeLuminance(hex) {
+	const [r, g, b] = parseHex(hex).map((v) => {
+		const s = v / 255;
+		return s <= .03928 ? s / 12.92 : ((s + .055) / 1.055) ** 2.4;
+	});
+	return .2126 * r + .7152 * g + .0722 * b;
+}
+function contrastRatio(a, b) {
+	const la = relativeLuminance(a);
+	const lb = relativeLuminance(b);
+	const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+	return (hi + .05) / (lo + .05);
+}
+/** Uses the WCAG luminance threshold 0.179, matching how org themes classify backgrounds. */
+function isDarkColor(hex) {
+	return relativeLuminance(hex) < .179;
+}
+/** White or black, whichever reads better on the given color. */
+function readableOn(hex) {
+	return contrastRatio(hex, "#ffffff") >= contrastRatio(hex, "#000000") ? "#ffffff" : "#000000";
+}
+/** Nudges `color` toward the readable pole of `bg` until it clears `ratio`. */
+function ensureReadable(color, bg, ratio) {
+	const pole = isDarkColor(bg) ? "#ffffff" : "#000000";
+	let out = color;
+	for (let t = 0; t <= 1 && contrastRatio(out, bg) < ratio; t += .05) out = mix(color, pole, t);
+	return out;
+}
+function clampContrast(contrast) {
+	return Math.max(.25, Math.min(2, contrast ?? 1));
+}
+var STATUS_HUES = {
+	success: {
+		onLight: "#16a34a",
+		onDark: "#22c55e"
+	},
+	error: {
+		onLight: "#dc2626",
+		onDark: "#ef4444"
+	},
+	warning: {
+		onLight: "#d97706",
+		onDark: "#f59e0b"
+	},
+	info: {
+		onLight: "#2563eb",
+		onDark: "#3b82f6"
+	},
+	favorite: {
+		onLight: "#e11d48",
+		onDark: "#f43f5e"
+	}
+};
+function deriveSidebar(seed) {
+	const bg = seed.background;
+	const c = clampContrast(seed.contrast);
+	const dark = isDarkColor(bg);
+	const pole = dark ? "#ffffff" : "#000000";
+	const text = mix(pole, bg, Math.max(0, 1 - c) * .5);
+	const hover = mix(bg, pole, .12 * c);
+	const activeBg = dark ? mix(seed.accent, "#ffffff", .85) : seed.accent;
+	return {
+		bg,
+		text,
+		hover,
+		hoverText: text,
+		activeBg,
+		activeText: readableOn(activeBg)
+	};
+}
+function deriveTheme(seed) {
+	const surfaces = "interface" in seed ? seed : { interface: seed };
+	const { accent, background: bg } = surfaces.interface;
+	const c = clampContrast(surfaces.interface.contrast);
+	const dark = isDarkColor(bg);
+	const pole = dark ? "#ffffff" : "#000000";
+	const fg = mix(pole, bg, Math.max(0, 1 - c) * .5);
+	const panelBg = dark ? mix(bg, "#ffffff", .045) : mix(bg, "#ffffff", .8);
+	const mutedPanelBg = dark ? mix(bg, "#ffffff", .09) : mix(bg, "#ffffff", .5);
+	const border = mix(bg, pole, (dark ? .16 : .16) * c);
+	const mutedText = mix(fg, bg, .42);
+	const hover = dark ? mix(bg, "#ffffff", .08) : mix(bg, "#000000", .04);
+	const inputBg = dark ? mix(bg, "#ffffff", .08) : mix(bg, "#ffffff", .65);
+	const link = ensureReadable(accent, bg, 4.5);
+	const accentText = readableOn(accent);
+	const cardBg = panelBg;
+	let sidebarBg = panelBg;
+	if (!dark) sidebarBg = isDarkColor(accent) ? accent : mix(accent, "#000000", .4);
+	const sidebar = deriveSidebar(surfaces.sidebar ?? {
+		accent,
+		background: sidebarBg,
+		contrast: c
+	});
+	const status = (name) => ensureReadable(dark ? STATUS_HUES[name].onDark : STATUS_HUES[name].onLight, bg, 3);
+	const shadowInk = dark ? .35 : .07;
+	return {
+		"--theme-app-bg": bg,
+		"--theme-app": fg,
+		"--theme-panel-bg": panelBg,
+		"--theme-panel": fg,
+		"--theme-muted-panel-bg": mutedPanelBg,
+		"--theme-muted-panel-color": mutedText,
+		"--theme-muted-text-color": mutedText,
+		"--theme-border": border,
+		"--theme-element": accent,
+		"--theme-element-text": accentText,
+		"--theme-hover": hover,
+		"--theme-hover-text": fg,
+		"--theme-link": link,
+		"--theme-input-bg": inputBg,
+		"--theme-input": link,
+		"--theme-input-disabled-bg": mix(inputBg, bg, .5),
+		"--theme-input-disabled-text": mix(fg, bg, .6),
+		"--theme-card-bg": cardBg,
+		"--theme-card-border": alpha(pole, dark ? .06 : .04),
+		"--theme-card-hover": dark ? mix(cardBg, "#ffffff", .05) : mix(cardBg, "#000000", .02),
+		"--theme-accent": accent,
+		"--theme-accent-text": accentText,
+		"--theme-focus-ring": alpha(link, dark ? .25 : .2),
+		"--theme-hover-overlay": alpha(pole, dark ? .03 : .02),
+		"--theme-success": status("success"),
+		"--theme-success-muted": alpha(status("success"), dark ? .15 : .1),
+		"--theme-error": status("error"),
+		"--theme-error-muted": alpha(status("error"), dark ? .15 : .1),
+		"--theme-warning": status("warning"),
+		"--theme-warning-muted": alpha(status("warning"), dark ? .15 : .1),
+		"--theme-info": status("info"),
+		"--theme-info-muted": alpha(status("info"), dark ? .15 : .1),
+		"--theme-favorite": status("favorite"),
+		"--theme-favorite-muted": alpha(status("favorite"), dark ? .15 : .1),
+		"--theme-shadow-sm": `0 1px 2px rgba(0, 0, 0, ${shadowInk})`,
+		"--theme-shadow": `0 4px 6px -1px rgba(0, 0, 0, ${shadowInk}), 0 2px 4px -2px rgba(0, 0, 0, ${shadowInk})`,
+		"--theme-shadow-lg": `0 10px 15px -3px rgba(0, 0, 0, ${shadowInk}), 0 4px 6px -4px rgba(0, 0, 0, ${shadowInk})`,
+		"--theme-bg": sidebar.bg,
+		"--theme-sidebar-text": sidebar.text,
+		"--theme-sidebar-hover": sidebar.hover,
+		"--theme-sidebar-hover-text": sidebar.hoverText,
+		"--theme-sidebar-active-bg": sidebar.activeBg,
+		"--theme-sidebar-active-text": sidebar.activeText
+	};
+}
+var THEME_PRESETS = [
+	{
+		name: "activate",
+		label: "ACTIVATE",
+		seed: {
+			interface: {
+				accent: "#06354f",
+				background: "#f3f4f6"
+			},
+			sidebar: {
+				accent: "#06354f",
+				background: "#06354f"
+			}
+		}
+	},
+	{
+		name: "light",
+		label: "Light",
+		seed: { interface: {
+			accent: "#0d6efd",
+			background: "#ffffff"
+		} }
+	},
+	{
+		name: "dark",
+		label: "Dark",
+		seed: {
+			interface: {
+				accent: "#2f81f7",
+				background: "#0d1117"
+			},
+			sidebar: {
+				accent: "#2f81f7",
+				background: "#161b22"
+			}
+		}
+	},
+	{
+		name: "rose-pine",
+		label: "Rosé Pine",
+		seed: {
+			interface: {
+				accent: "#c4a7e7",
+				background: "#191724"
+			},
+			sidebar: {
+				accent: "#c4a7e7",
+				background: "#1f1d2e"
+			}
+		}
+	}
+];
+var DEFAULT_PRESET = THEME_PRESETS[0];
+function applyTheme(el, vars) {
+	for (const [token, value] of Object.entries(vars)) if (value !== void 0) el.style.setProperty(token, value);
+}
+//#endregion
+export { DEFAULT_PRESET, THEME_PRESETS, THEME_TOKENS, applyTheme, contrastRatio, deriveTheme, isDarkColor };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@parallelworks/ui",
+  "version": "0.1.0",
+  "description": "Shared UI foundation for Parallel Works packages: theme contract, icons, and core primitives",
+  "license": "MIT",
+  "author": "Parallel Works <support@parallelworks.com>",
+  "homepage": "https://parallelworks.com/docs",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./icons": {
+      "types": "./dist/icons.d.ts",
+      "import": "./dist/icons.js"
+    },
+    "./theme": {
+      "types": "./dist/theme/index.d.ts",
+      "import": "./dist/theme/index.js"
+    },
+    "./theme.css": "./dist/styles/theme.css",
+    "./styles.css": "./dist/styles.css"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "classnames": "^2.5.1",
+    "react-icons": "5.6.0",
+    "react-tooltip": "^6.0.7"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@tailwindcss/cli": "^4.3.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.3.1",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "jsdom": "^26.1.0",
+    "publint": "^0.3.14",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^7.0.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "vite build && pnpm build:types && pnpm build:css",
+    "build:types": "tsc -p tsconfig.build.json && node scripts/declaration-extensions.mjs",
+    "build:css": "mkdir -p dist/styles && cp src/styles/theme.css dist/styles/ && tailwindcss -i ./src/styles.css -o ./dist/styles.css --minify",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "lint:package": "publint --strict",
+    "verify:pack": "node scripts/verify-pack.mjs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}