@seanyeh77/ui-cli 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hsiu-An Yeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+// src/measure.ts
+function measure() {
+	const out = {
+		overflow: [],
+		small: [],
+		inline: [],
+		nested: [],
+		markdown: [],
+		native: [],
+		wrapped: []
+	};
+	const describe = (el) => {
+		let s = el.tagName.toLowerCase();
+		const cls = [...el.classList].filter((c) => c.startsWith("ui-")).slice(0, 2);
+		if (cls.length) s += "." + cls.join(".");
+		const label = el.getAttribute("aria-label") || (el.textContent || "").trim();
+		if (label) s += " \"" + label.slice(0, 24) + "\"";
+		return s;
+	};
+	const isInline = (el, cs) => {
+		if (!cs.display.startsWith("inline")) return false;
+		const p = el.parentElement;
+		return !!p && [...p.childNodes].some((n) => n.nodeType === 3 && !!n.textContent?.trim());
+	};
+	const visible = (el) => {
+		const cs = getComputedStyle(el);
+		const r = el.getBoundingClientRect();
+		return cs.visibility !== "hidden" && cs.display !== "none" && r.width > 0 && r.height > 0;
+	};
+	const vw = document.documentElement.clientWidth;
+	if (document.documentElement.scrollWidth > vw + 1) {
+		for (const el of document.body.querySelectorAll("*")) {
+			const r = el.getBoundingClientRect();
+			if (r.width && r.right > vw + 1 && getComputedStyle(el).position !== "fixed") {
+				const parent = el.parentElement?.getBoundingClientRect();
+				if (!parent || parent.right <= vw + 1) out.overflow.push(`${describe(el)} right ${Math.round(r.right)} px`);
+			}
+			if (out.overflow.length >= 8) break;
+		}
+		if (!out.overflow.length) out.overflow.push(`page scrollWidth ${document.documentElement.scrollWidth} px`);
+	}
+	for (const el of new Set(document.querySelectorAll("a[href], button, input:not([type=hidden]), select, textarea, summary, [role=button], [role=tab], [role=switch], [role=checkbox], [role=radio], [role=option], [role=menuitem], [role=link], [tabindex]:not([tabindex=\"-1\"])"))) {
+		if (el.closest("[aria-hidden=\"true\"], [inert]")) continue;
+		const cs = getComputedStyle(el);
+		if (cs.visibility === "hidden" || cs.display === "none" || cs.pointerEvents === "none") continue;
+		const r = el.getBoundingClientRect();
+		if (!r.width || !r.height) continue;
+		const input = el;
+		if ((input.type === "checkbox" || input.type === "radio") && el.closest("label")) continue;
+		const box = el.tagName === "INPUT" && el.closest(".ui-pwfield, .ui-datefield, .ui-ms, .ui-searchfield");
+		if (box) {
+			const br = box.getBoundingClientRect();
+			if (br.height >= 47.5 && br.width >= 47.5) continue;
+		}
+		let w = r.width;
+		let h = r.height;
+		for (const pe of ["::before", "::after"]) {
+			const ps = getComputedStyle(el, pe);
+			if (ps.content && ps.content !== "none" && ps.position === "absolute" && ps.pointerEvents !== "none") {
+				w = Math.max(w, parseFloat(ps.width) || 0);
+				h = Math.max(h, parseFloat(ps.height) || 0);
+			}
+		}
+		if (w >= 47.5 && h >= 47.5) continue;
+		(isInline(el, cs) ? out.inline : out.small).push(`${describe(el)} ${Math.round(w)} x ${Math.round(h)} px`);
+	}
+	const cardLike = (el) => {
+		const sh = getComputedStyle(el).boxShadow;
+		if (!sh || sh === "none") return false;
+		return sh.split(/,(?![^(]*\))/).some((x) => {
+			const px = x.match(/(-?[\d.]+)px/g) || [];
+			return !/inset/.test(x) && px.length >= 3 && parseFloat(px[2]) >= 4;
+		});
+	};
+	for (const el of document.body.querySelectorAll("*")) {
+		if (out.nested.length >= 6) break;
+		if (!cardLike(el) || !visible(el)) continue;
+		for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+			if (getComputedStyle(a).position === "fixed") break;
+			if (cardLike(a)) {
+				out.nested.push(`${describe(el)} inside ${describe(a)}`);
+				break;
+			}
+		}
+	}
+	const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+	for (let n = walker.nextNode(); n && out.markdown.length < 6; n = walker.nextNode()) {
+		const t = n.textContent || "";
+		const parent = n.parentElement;
+		if (!parent || parent.closest("pre, code, script, style, textarea, .ui-cv") || !visible(parent)) continue;
+		if (/`[^`]+`|\*\*[^*]+\*\*|^\s*#{1,6}\s/.test(t)) out.markdown.push(`${describe(parent)}: ${t.trim().slice(0, 40)}`);
+	}
+	for (const [q, use] of Object.entries({
+		select: "Select",
+		table: "DataTable",
+		dialog: "Dialog",
+		"input[type=checkbox]": "Checkbox",
+		"input[type=radio]": "RadioGroup",
+		"input[type=date]": "DatePicker",
+		progress: "ProgressBar",
+		"input[type=search]": "SearchField",
+		"input[type=file]": "FileUpload",
+		"input[type=color]": "AccentPicker"
+	})) for (const el of document.querySelectorAll(q)) if (visible(el) && !el.matches("[class^=\"ui-\"], [class*=\" ui-\"]")) out.native.push(`<${q}> → use ${use}`);
+	for (const el of document.querySelectorAll(".ui-btn, .ui-tab, [role=columnheader], .ui-field-label, h1, h2, h3, h4")) {
+		if (out.wrapped.length >= 8 || !visible(el)) continue;
+		if ([...el.querySelectorAll("*"), el].some((node) => [...node.childNodes].some((t) => {
+			if (t.nodeType !== 3 || !t.textContent?.trim()) return false;
+			const range = document.createRange();
+			range.selectNodeContents(t);
+			return new Set([...range.getClientRects()].filter((r) => r.width > 1).map((r) => Math.round(r.top / 4))).size > 1;
+		}))) out.wrapped.push(describe(el));
+	}
+	return out;
+}
+// src/cli.ts
+const HELP = `ui check <file or URL>... [--shots DIR] [--strict] [--wait MS]
+  Opens each page at 390 px and 1280 px, light and dark, and fails (exit 1) on:
+  console errors, horizontal overflow at 390 px, touch targets under 48 px, a card inside a card,
+  raw Markdown, native controls the design system replaces, and wrapped buttons, tabs, headers or headings.
+  Exits 2 when a page cannot be checked at all: it does not load, or the check itself crashes.
+ui docs [Name]   prints the README of a component (Button, DataTable…) or a guide (guidelines, layout, motion)
+ui list          lists every component`;
+function docsDir() {
+	const require = createRequire(import.meta.url);
+	return join(dirname(require.resolve("@seanyeh77/ui/package.json")), "docs");
+}
+function docs(name) {
+	const dir = docsDir();
+	const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+	if (!name) return console.log(files.map((f) => f.slice(0, -3)).join("\n"));
+	const hit = files.find((f) => f.slice(0, -3).toLowerCase() === name.toLowerCase());
+	if (!hit) {
+		console.error(`No docs for "${name}". Run "ui docs" for the list.`);
+		process.exit(1);
+	}
+	console.log(readFileSync(join(dir, hit), "utf8"));
+}
+function list() {
+	const dir = docsDir();
+	for (const f of readdirSync(dir).filter((x) => x.endsWith(".md") && /^[A-Z]/.test(x))) {
+		const first = readFileSync(join(dir, f), "utf8").split("\n").find((l) => l.trim() && !l.startsWith("#")) ?? "";
+		console.log(`${f.slice(0, -3).padEnd(18)} ${first.trim()}`);
+	}
+}
+/** The page itself could not be opened: a wrong path, no server, or an HTTP error. */
+var Unreachable = class extends Error {};
+async function check(targets, opts) {
+	const { chromium } = await import("playwright");
+	const browser = await chromium.launch(process.env.CHROMIUM_PATH ? { executablePath: process.env.CHROMIUM_PATH } : {}).catch((e) => {
+		console.error(String(e).split("\n")[0]);
+		console.error("No Chromium for ui check. Run `npx playwright install chromium`, or set CHROMIUM_PATH to an installed Chrome or Chromium.");
+		process.exit(2);
+	});
+	const stems = /* @__PURE__ */ new Map();
+	const jobs = targets.map((target) => {
+		const url = target.includes("://") ? new URL(target).href : pathToFileURL(resolve(target)).href;
+		const base = decodeURIComponent(url.replace(/[?#].*$/, "").replace(/\/$/, "").split("/").pop() || "page").replace(/\.[^.]*$/, "");
+		const n = (stems.get(base) ?? 0) + 1;
+		stems.set(base, n);
+		return {
+			url,
+			stem: n > 1 ? `${base}-${n}` : base
+		};
+	});
+	const checkOne = async ({ url, stem }) => {
+		const out = [url];
+		let bad = false;
+		for (const width of [390, 1280]) for (const theme of ["light", "dark"]) {
+			const phone = width === 390;
+			const ctx = await browser.newContext({
+				viewport: {
+					width,
+					height: phone ? 844 : 900
+				},
+				colorScheme: theme,
+				hasTouch: phone,
+				isMobile: phone,
+				deviceScaleFactor: phone ? 2 : 1
+			});
+			try {
+				const page = await ctx.newPage();
+				const errors = [];
+				page.on("pageerror", (e) => errors.push(String(e)));
+				page.on("console", (m) => {
+					if (m.type() !== "error") return;
+					const src = m.location().url;
+					if (/\/favicon\.ico$/.test(src)) return;
+					errors.push(src && src !== url ? `${m.text()} (${src})` : m.text());
+				});
+				const resp = await page.goto(url, { waitUntil: "load" }).catch((e) => {
+					throw new Unreachable(String(e).split("\n")[0]);
+				});
+				if (resp && !resp.ok()) throw new Unreachable(`HTTP ${resp.status()}`);
+				const run = async (evaluate) => {
+					for (let tries = 0;; tries++) try {
+						return await evaluate();
+					} catch (e) {
+						if (tries >= 2 || !String(e).includes("Execution context was destroyed")) throw e;
+						await page.waitForLoadState("load");
+					}
+				};
+				await run(() => page.evaluate((t) => {
+					const r = document.documentElement;
+					if (r.hasAttribute("data-theme") || "UI" in window) r.setAttribute("data-theme", t);
+				}, theme));
+				await page.waitForTimeout(opts.wait);
+				await page.waitForLoadState("load");
+				const res = await run(() => page.evaluate(measure));
+				if (page.url() !== url && width === 390 && theme === "light") out.push(`  (redirected to ${page.url()})`);
+				const problems = [];
+				if (errors.length) problems.push("console errors: " + errors.slice(0, 5).join(" | "));
+				if (res.nested.length) problems.push("card inside a card (two shadows): " + res.nested.join("; "));
+				if (res.markdown.length) problems.push("raw Markdown shown: " + res.markdown.join("; "));
+				if (res.native.length) problems.push("native controls: " + [...new Set(res.native)].join("; "));
+				if (res.wrapped.length) problems.push("text that must stay on one line wraps: " + res.wrapped.join("; "));
+				if (phone) {
+					if (res.overflow.length) problems.push("horizontal overflow: " + res.overflow.join("; "));
+					if (res.small.length) problems.push(`touch targets under 48 px: ${res.small.slice(0, 12).join("; ")}${res.small.length > 12 ? ` (+${res.small.length - 12} more)` : ""}`);
+					if (res.inline.length && opts.strict) problems.push("inline targets under 48 px: " + res.inline.slice(0, 12).join("; "));
+				}
+				out.push(`  ${width} px ${theme}: ${problems.length ? "" : "ok"}`);
+				for (const p of problems) out.push("    - " + p);
+				if (phone && theme === "light" && res.inline.length && !opts.strict) out.push(`    (inline text targets, exempt: ${res.inline.length})`);
+				bad ||= problems.length > 0;
+				if (opts.shots) await page.screenshot({
+					path: join(opts.shots, `${stem}-${width}-${theme}.png`),
+					fullPage: true
+				});
+			} finally {
+				await ctx.close();
+			}
+		}
+		return {
+			out,
+			bad
+		};
+	};
+	if (opts.shots) mkdirSync(opts.shots, { recursive: true });
+	let unchecked = false;
+	const lanes = Array(4).fill(Promise.resolve());
+	const results = jobs.map((job, i) => {
+		const r = lanes[i % 4].then(() => checkOne(job)).catch((e) => {
+			unchecked = true;
+			if (!(e instanceof Unreachable)) return {
+				out: [job.url, `  check crashed: ${String(e).split("\n")[0]}`],
+				bad: true
+			};
+			return {
+				out: [job.url, `  could not load: ${e.message}. Check the path, or start the server first.`],
+				bad: true
+			};
+		});
+		lanes[i % 4] = r;
+		return r;
+	});
+	let failed = false;
+	for (const r of results) {
+		const { out, bad } = await r;
+		console.log(out.join("\n"));
+		failed ||= bad;
+	}
+	await browser.close();
+	process.exit(unchecked ? 2 : failed ? 1 : 0);
+}
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === "check") {
+	const { values, positionals } = parseArgs({
+		args: rest,
+		allowPositionals: true,
+		options: {
+			shots: { type: "string" },
+			strict: {
+				type: "boolean",
+				default: false
+			},
+			wait: {
+				type: "string",
+				default: "800"
+			}
+		}
+	});
+	if (!positionals.length) {
+		console.error(HELP);
+		process.exit(2);
+	}
+	for (const t of positionals) if (!t.includes("://") && !existsSync(t)) {
+		console.error(`${t}: no such file. Pass a file path or a URL.`);
+		process.exit(2);
+	} else if (t.includes("://") && !URL.canParse(t)) {
+		console.error(`${t}: not a valid URL. Write it in full, e.g. http://localhost:5173/.`);
+		process.exit(2);
+	}
+	const wait = Number(values.wait);
+	if (!Number.isFinite(wait) || wait < 0) {
+		console.error(`--wait ${values.wait}: give the milliseconds to wait after load, e.g. --wait 800.`);
+		process.exit(2);
+	}
+	await check(positionals, {
+		shots: values.shots,
+		strict: !!values.strict,
+		wait
+	});
+} else if (cmd === "docs") docs(rest[0]);
+else if (cmd === "list") list();
+else {
+	console.log(HELP);
+	process.exit(cmd ? 2 : 0);
+}
+export {};

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@seanyeh77/ui-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Checks a page against SeanYeh's design system and prints component docs: ui check, ui docs, ui list.",
+  "license": "MIT",
+  "author": "Hsiu-An Yeh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanyeh77/ui-design-system.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "ui": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "playwright": "^1.65.0",
+    "@seanyeh77/ui": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p ."
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.