@zenginui/registry 0.1.0

package/dist/build.js

@@ -0,0 +1,344 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { LAYOUT, REGISTRY_SCHEMA } from "./schema.js";
+import { ICON_SETS, REACT_ICONS_VERSION, renderIconsModule } from "./icons.js";
+import { buildTokensCss } from "./tokens.js";
+/**
+ * Builds the registry from the repository: every component in packages/ui, the shared lib and foundation
+ * files, and the example apps as templates. Imports are rewritten from the package layout to the project
+ * layout (`@/components/ui`, `@/lib/cx`), so what a project receives is what it would have written itself.
+ */
+export function buildRegistry(opts) {
+    const ui = join(opts.root, "packages", "ui");
+    const version = opts.version ?? JSON.parse(read(join(ui, "package.json"))).version;
+    const uiPkg = JSON.parse(read(join(ui, "package.json")));
+    const manifests = JSON.parse(read(join(ui, "zengin", "components.json")));
+    const items = [];
+    // Every file in src/internal is a lib item; components depend on the ones they import.
+    const LIB_DESCRIPTIONS = {
+        cx: "Joins class names, dropping falsy values. Every component imports it.",
+        icons: "The icon vocabulary: one component per name, drawn by Zengin UI until zengin icons <set> points the names at a react-icons set.",
+        chart: "Scales, paths and the width hook the chart components share.",
+        markdown: "The markdown subset models produce, parsed into blocks for the Markdown component.",
+    };
+    for (const file of readdirSync(join(ui, "src", "internal")).sort()) {
+        if (!/\.tsx?$/.test(file))
+            continue;
+        const name = file.replace(/\.tsx?$/, "");
+        // The icons lib carries the Icon manifest: it shadows the icon packages, so the project draws from the vocabulary.
+        const manifest = name === "icons" ? manifests.find((m) => m.name === "Icon") : undefined;
+        items.push({
+            name: `lib-${name}`,
+            type: "lib",
+            title: name,
+            description: LIB_DESCRIPTIONS[name] ?? `${name} helpers from Zengin UI.`,
+            dependencies: {},
+            devDependencies: {},
+            registryDependencies: [],
+            files: [{ path: `${LAYOUT.libDir}/${file}`, kind: "lib", content: rewriteComponent(read(join(ui, "src", "internal", file))) }],
+            ...(manifest ? { manifest: { ...manifest, export: { from: "@/lib/icons", name: "Icon" } } } : {}),
+        });
+    }
+    items.push({
+        name: "foundation",
+        type: "definitions",
+        title: "Foundation",
+        description: "The token definitions (light and dark) and the base stylesheet every component assumes.",
+        dependencies: {},
+        devDependencies: {},
+        registryDependencies: [],
+        files: [
+            { path: `${LAYOUT.definitionsDir}/tokens.json`, kind: "definitions", content: read(join(ui, "zengin", "tokens.json")) },
+            { path: `${LAYOUT.definitionsDir}/tokens.dark.json`, kind: "definitions", content: read(join(ui, "zengin", "tokens.dark.json")) },
+            { path: "src/styles/base.css", kind: "style", content: read(join(ui, "src", "styles", "base.css")) },
+            { path: "src/styles/chart.css", kind: "style", content: read(join(ui, "src", "styles", "chart.css")) },
+            { path: "src/styles/motion.css", kind: "style", content: read(join(ui, "src", "styles", "motion.css")) },
+        ],
+    });
+    const componentsDir = join(ui, "src", "components");
+    for (const dir of readdirSync(componentsDir).sort()) {
+        const tsxPath = join(componentsDir, dir, `${dir}.tsx`);
+        if (!existsSync(tsxPath))
+            continue;
+        const tsx = read(tsxPath);
+        const manifest = manifests.find((m) => kebab(m.name) === dir);
+        if (!manifest)
+            throw new Error(`packages/ui component "${dir}" has no manifest entry`);
+        const dependencies = {};
+        for (const m of tsx.matchAll(/from\s+"(@radix-ui\/[^"]+|radix-ui)"/g)) {
+            const pkg = m[1];
+            const v = uiPkg.dependencies?.[pkg];
+            if (!v)
+                throw new Error(`packages/ui/package.json has no version for ${pkg}, used by ${dir}`);
+            dependencies[pkg] = v;
+        }
+        const registryDependencies = ["foundation"];
+        for (const m of tsx.matchAll(/from\s+"\.\.\/\.\.\/internal\/([\w-]+)\.js"/g))
+            registryDependencies.push(`lib-${m[1]}`);
+        for (const m of tsx.matchAll(/from\s+"\.\.\/([\w-]+)\/[\w-]+\.js"/g))
+            registryDependencies.push(m[1]);
+        const files = [
+            { path: `${LAYOUT.componentsDir}/${dir}/${dir}.tsx`, kind: "component", content: rewriteComponent(tsx) },
+        ];
+        const cssPath = join(componentsDir, dir, `${dir}.css`);
+        if (existsSync(cssPath))
+            files.push({ path: `${LAYOUT.componentsDir}/${dir}/${dir}.css`, kind: "style", content: read(cssPath) });
+        const storyPath = join(ui, "stories", `${dir}.stories.tsx`);
+        if (existsSync(storyPath))
+            files.push({ path: `${LAYOUT.storiesDir}/${dir}.stories.tsx`, kind: "story", content: rewriteStory(read(storyPath)) });
+        items.push({
+            name: dir,
+            type: "component",
+            title: manifest.name,
+            description: describe(tsx) ?? `${manifest.name} from Zengin UI.`,
+            dependencies,
+            devDependencies: {},
+            registryDependencies,
+            files,
+            manifest: { ...manifest, export: { ...manifest.export, from: LAYOUT.alias } },
+        });
+    }
+    const componentNames = new Set(items.filter((i) => i.type === "component").map((i) => i.name));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/blank",
+        name: "blank",
+        title: "Blank",
+        description: "A page with one card and one button, ready to be replaced.",
+        rootFiles: ["index.html"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/marketing-site",
+        name: "marketing",
+        title: "Marketing page",
+        description: "A product page: hero with a live panel, tabs, a rules table, specimens, and a brand as one token file. Archivo, black rules, cobalt.",
+        rootFiles: ["index.html", "vercel.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/review-workspace",
+        name: "review",
+        title: "Review workspace",
+        description: "An application workflow: a review queue with filtering, status badges, a confirmation dialog, and a theme toggle.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/saas",
+        name: "saas",
+        title: "SaaS dashboard",
+        description: "An admin app: overview with stat cards and charts, a customers table with row actions and a detail sheet, billing with quotas, settings that save with a toast. Sidebar, top bar, both schemes.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/chat",
+        name: "chat",
+        title: "AI chat",
+        description: "An assistant: conversation with streamed markdown, reasoning, tool calls and sources, a prompt with suggestions, a model picker. On the Vercel AI SDK, with a scripted transport so it runs without a key.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/auth",
+        name: "auth",
+        title: "Auth",
+        description: "Sign in, create account, reset and verify, one card on @zenginui/ui with real validation against mock accounts.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/docs",
+        name: "docs",
+        title: "Docs",
+        description: "A sidebar of sections, markdown pages with code and tables, an on-this-page outline, search, previous and next, on @zenginui/ui.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    items.push(templateFrom({
+        root: opts.root,
+        dir: "examples/storefront",
+        name: "storefront",
+        title: "Storefront",
+        description: "A product grid with search, filters and sort, a cart sheet with quantities and totals, and a checkout dialog that places the order, on @zenginui/ui.",
+        rootFiles: ["index.html", "mock.json"],
+        componentNames,
+    }));
+    // Themes: one directory each under packages/ui/themes, a theme.json beside a brand.css.
+    const themesDir = join(ui, "themes");
+    for (const dir of existsSync(themesDir) ? readdirSync(themesDir).sort() : []) {
+        const meta = join(themesDir, dir, "theme.json");
+        const css = join(themesDir, dir, "brand.css");
+        if (!existsSync(meta) || !existsSync(css))
+            continue;
+        const t = JSON.parse(read(meta));
+        // The default theme is the system's own tokens, spelled out, so applying it over any brand is a real reset.
+        const content = dir === "default"
+            ? `/*\n * The default theme: Zengin UI's own tokens, every one, so that applying it over another brand resets\n * everything. Generated from zengin/tokens.json and tokens.dark.json. Edit freely, or run \`zengin brand\`.\n */\n\n${buildTokensCss(join(ui, "zengin")).css.replace(/^\/\*.*\*\/\n\n/, "")}`
+            : read(css);
+        items.push({
+            name: dir,
+            type: "theme",
+            title: t.title,
+            description: t.description,
+            dependencies: {},
+            devDependencies: {},
+            registryDependencies: [],
+            files: [{ path: "src/theme/brand.css", kind: "theme", content }],
+            fonts: t.fonts ?? [],
+        });
+    }
+    // Font pairings: one directory each under packages/ui/fonts, a fonts.json naming the three roles.
+    const fontsDir = join(ui, "fonts");
+    for (const dir of existsSync(fontsDir) ? readdirSync(fontsDir).sort() : []) {
+        const meta = join(fontsDir, dir, "fonts.json");
+        if (!existsSync(meta))
+            continue;
+        const f = JSON.parse(read(meta));
+        items.push({
+            name: `fonts-${dir}`,
+            type: "fonts",
+            title: f.title,
+            description: f.description,
+            dependencies: {},
+            devDependencies: {},
+            registryDependencies: [],
+            files: [],
+            pairing: { display: f.display, sans: f.sans, mono: f.mono },
+        });
+    }
+    // Icon sets: the vocabulary drawn by a react-icons module. Installing one replaces src/lib/icons.tsx.
+    for (const [name, set] of Object.entries(ICON_SETS)) {
+        items.push({
+            name: `icons-${name}`,
+            type: "icons",
+            title: set.title,
+            description: set.description,
+            dependencies: { "react-icons": REACT_ICONS_VERSION },
+            devDependencies: {},
+            registryDependencies: [],
+            files: [{ path: `${LAYOUT.libDir}/icons.tsx`, kind: "lib", content: renderIconsModule(name, set) }],
+            iconSet: { module: set.module, names: set.names },
+        });
+    }
+    return { schema: REGISTRY_SCHEMA, name: "zengin", version, generatedAt: new Date().toISOString(), items };
+}
+/** Writes index.json and items/<name>.json so the registry can be served as static files. */
+export function writeRegistry(registry, outDir) {
+    mkdirSync(join(outDir, "items"), { recursive: true });
+    const index = {
+        ...registry,
+        items: registry.items.map(({ files: _f, manifest: _m, ...rest }) => rest),
+    };
+    const written = [join(outDir, "index.json")];
+    writeFileSync(written[0], JSON.stringify(index, null, 2) + "\n");
+    for (const item of registry.items) {
+        const p = join(outDir, "items", `${item.name}.json`);
+        writeFileSync(p, JSON.stringify(item, null, 2) + "\n");
+        written.push(p);
+    }
+    return written;
+}
+function templateFrom(opts) {
+    const base = join(opts.root, opts.dir);
+    const files = [];
+    const used = new Set();
+    for (const f of opts.rootFiles) {
+        const p = join(base, f);
+        if (existsSync(p))
+            files.push({ path: f, kind: "template", content: read(p) });
+    }
+    for (const p of walk(join(base, "src"))) {
+        const rel = relative(base, p).replace(/\\/g, "/");
+        if (rel.startsWith("src/styles/generated/"))
+            continue;
+        if (rel === "src/preview-theme.ts")
+            continue; // the site's preview harness, not part of the template
+        let content = read(p);
+        if (rel === "src/main.tsx")
+            content = content.replace(/import "\.\/preview-theme";\r?\n/, "");
+        if (/\.(tsx?|css)$/.test(rel)) {
+            for (const m of content.matchAll(/import\s*\{([^}]+)\}\s*from\s*"@zenginui\/ui"/g)) {
+                for (const name of m[1].split(",")) {
+                    const clean = name.replace(/^\s*type\s+/, "").replace(/\s+as\s+\w+\s*$/, "").trim(); // `type X` and `X as Y` both name X
+                    if (!clean)
+                        continue;
+                    const k = kebab(clean);
+                    if (opts.componentNames.has(k))
+                        used.add(k);
+                }
+            }
+            content = content.replace(/"@zenginui\/ui\/styles\.css"/g, '"./styles/index.css"').replace(/"@zenginui\/ui"/g, `"${LAYOUT.alias}"`);
+        }
+        // The entry point must load the brand file, or themes and brands change nothing. The examples that
+        // consume the package have no brand file; the project has one.
+        if (rel === "src/main.tsx" && !content.includes("theme/brand.css")) {
+            content = content.includes('import "./styles/index.css";')
+                ? content.replace('import "./styles/index.css";', 'import "./styles/index.css";\nimport "./theme/brand.css";')
+                : `import "./theme/brand.css";\n${content}`;
+        }
+        files.push({ path: rel, kind: "template", content });
+    }
+    return {
+        name: opts.name,
+        type: "template",
+        title: opts.title,
+        description: opts.description,
+        dependencies: {},
+        devDependencies: {},
+        registryDependencies: ["foundation", "lib-cx", ...[...used].sort()],
+        files,
+        source: opts.dir,
+    };
+}
+/** Package-relative imports become project-alias imports; `.js` suffixes on relative imports go. */
+function rewriteComponent(tsx) {
+    return tsx.replace(/"\.\.\/\.\.\/internal\/([\w-]+)\.js"/g, '"@/lib/$1"').replace(/from\s+"(\.\.?\/[^"]+)\.js"/g, 'from "$1"');
+}
+function rewriteStory(tsx) {
+    return tsx.replace(/from\s+"\.\.\/src"/g, `from "${LAYOUT.alias}"`);
+}
+/** The first doc comment in the file, one paragraph. */
+function describe(tsx) {
+    const m = /\/\*\*\s*([\s\S]*?)\*\//.exec(tsx);
+    if (!m)
+        return undefined;
+    const text = m[1]
+        .split("\n")
+        .map((l) => l.replace(/^\s*\*\s?/, "").trim())
+        .filter(Boolean)
+        .join(" ");
+    return text.length > 220 ? `${text.slice(0, 217)}...` : text;
+}
+function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir).sort()) {
+        const p = join(dir, entry);
+        if (statSync(p).isDirectory())
+            out.push(...walk(p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+function read(p) {
+    return readFileSync(p, "utf8").replace(/\r\n/g, "\n");
+}
+export function kebab(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function pascal(name) {
+    return name
+        .split(/[-_]/)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+}

package/dist/color.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Color math for palette derivation: sRGB hex to OKLCH and back, gamut clipping by chroma, and WCAG
+ * contrast. OKLCH is used because equal steps in L look equal, which is what a hover or a soft tint needs.
+ */
+export interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+export declare function hexToRgb(hex: string): [number, number, number];
+export declare function rgbToHex([r, g, b]: [number, number, number]): string;
+export declare function rgbToOklch([r, g, b]: [number, number, number]): Oklch;
+/** OKLCH to hex, lowering chroma until the color fits sRGB so hue and lightness survive. */
+export declare function oklchToHex(color: Oklch): string;
+export declare function hexToOklch(hex: string): Oklch;
+/** WCAG 2 relative luminance of a hex color. */
+export declare function luminance(hex: string): number;
+/** WCAG 2 contrast ratio, 1 to 21. */
+export declare function contrast(a: string, b: string): number;
+/**
+ * Moves `color` in lightness, step by step in `direction`, until it reaches `ratio` against `against`.
+ * Returns the hex reached, or the furthest tried when the ratio cannot be met.
+ */
+export declare function pushForContrast(color: Oklch, against: string, ratio: number, direction: "darker" | "lighter"): string;

package/dist/color.js

@@ -0,0 +1,88 @@
+/**
+ * Color math for palette derivation: sRGB hex to OKLCH and back, gamut clipping by chroma, and WCAG
+ * contrast. OKLCH is used because equal steps in L look equal, which is what a hover or a soft tint needs.
+ */
+export function hexToRgb(hex) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(hex.trim());
+    if (!m)
+        throw new Error(`Not a hex color: ${hex}`);
+    let s = m[1];
+    if (s.length === 3)
+        s = s.split("").map((ch) => ch + ch).join("");
+    return [parseInt(s.slice(0, 2), 16) / 255, parseInt(s.slice(2, 4), 16) / 255, parseInt(s.slice(4, 6), 16) / 255];
+}
+export function rgbToHex([r, g, b]) {
+    const to = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, "0").toUpperCase();
+    return `#${to(r)}${to(g)}${to(b)}`;
+}
+const toLinear = (v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+const toGamma = (v) => (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055);
+export function rgbToOklch([r, g, b]) {
+    const lr = toLinear(r), lg = toLinear(g), lb = toLinear(b);
+    const l_ = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m_ = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s_ = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+    const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+    const bb = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+    const c = Math.hypot(a, bb);
+    let h = (Math.atan2(bb, a) * 180) / Math.PI;
+    if (h < 0)
+        h += 360;
+    return { l: L, c, h: c < 1e-4 ? 0 : h };
+}
+function oklchToLinearRgb({ l, c, h }) {
+    const a = c * Math.cos((h * Math.PI) / 180);
+    const bb = c * Math.sin((h * Math.PI) / 180);
+    const l_ = (l + 0.3963377774 * a + 0.2158037573 * bb) ** 3;
+    const m_ = (l - 0.1055613458 * a - 0.0638541728 * bb) ** 3;
+    const s_ = (l - 0.0894841775 * a - 1.291485548 * bb) ** 3;
+    return [
+        4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+        -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+        -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+    ];
+}
+const inGamut = (rgb) => rgb.every((v) => v >= -0.0005 && v <= 1.0005);
+/** OKLCH to hex, lowering chroma until the color fits sRGB so hue and lightness survive. */
+export function oklchToHex(color) {
+    let c = color.c;
+    let lin = oklchToLinearRgb({ ...color, c });
+    for (let i = 0; i < 24 && !inGamut(lin); i++) {
+        c *= 0.9;
+        lin = oklchToLinearRgb({ ...color, c });
+    }
+    if (!inGamut(lin))
+        lin = oklchToLinearRgb({ ...color, c: 0 });
+    return rgbToHex([toGamma(clamp01(lin[0])), toGamma(clamp01(lin[1])), toGamma(clamp01(lin[2]))]);
+}
+export function hexToOklch(hex) {
+    return rgbToOklch(hexToRgb(hex));
+}
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/** WCAG 2 relative luminance of a hex color. */
+export function luminance(hex) {
+    const [r, g, b] = hexToRgb(hex);
+    return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+/** WCAG 2 contrast ratio, 1 to 21. */
+export function contrast(a, b) {
+    const la = luminance(a), lb = luminance(b);
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * Moves `color` in lightness, step by step in `direction`, until it reaches `ratio` against `against`.
+ * Returns the hex reached, or the furthest tried when the ratio cannot be met.
+ */
+export function pushForContrast(color, against, ratio, direction) {
+    let l = color.l;
+    let hex = oklchToHex({ ...color, l });
+    for (let i = 0; i < 60 && contrast(hex, against) < ratio; i++) {
+        l += direction === "darker" ? -0.01 : 0.01;
+        if (l < 0 || l > 1)
+            break;
+        hex = oklchToHex({ ...color, l });
+    }
+    return hex;
+}

package/dist/create.d.ts

@@ -0,0 +1,55 @@
+import { type InstallResult } from "./install.js";
+import type { RegistrySource } from "./load.js";
+export interface CreateOptions {
+    /** Directory to create; must not exist or must be empty. */
+    dir: string;
+    /** Package name; defaults to the directory's basename. */
+    name?: string;
+    template?: string;
+    /** A theme from the registry to apply after the template; the template's own brand file otherwise. */
+    theme?: string;
+    source: RegistrySource;
+    /** Write the Storybook config and the stories that come with the components. Default true. */
+    storybook?: boolean;
+    /**
+     * Path to a Zengin repository checkout. The Zengin packages are then linked with `file:` instead of
+     * pulled from npm, which is how the generator is exercised before the first release.
+     */
+    local?: string;
+    /**
+     * `vite` (default): an SPA with index.html and src/main.tsx. `next`: the App Router under src/app, the
+     * template's App mounted client-side from page.tsx, its head in layout.tsx. Everything else is the same.
+     */
+    framework?: "vite" | "next";
+}
+export interface CreateResult {
+    dir: string;
+    name: string;
+    template: string;
+    framework: "vite" | "next";
+    version: string;
+    install: InstallResult;
+    tokens: {
+        light: number;
+        dark: number;
+    };
+    /** The engine on the fresh project. Zero, or something is wrong with the registry. */
+    violations: number;
+}
+/** Versions pinned into a generated package.json. One place to bump. */
+export declare const VERSIONS: {
+    readonly react: "^19.3.0";
+    readonly "react-dom": "^19.3.0";
+    readonly "@types/react": "^19.3.0";
+    readonly "@types/react-dom": "^19.3.0";
+    readonly "@vitejs/plugin-react": "^6.1.1";
+    readonly typescript: "^5.9.2";
+    readonly vite: "^8.3.0";
+    readonly next: "^16.1.0";
+    readonly storybook: "^10.6.0";
+    readonly "@storybook/react-vite": "^10.6.0";
+    readonly "@storybook/addon-docs": "^10.6.0";
+    readonly "@storybook/addon-a11y": "^10.6.0";
+    readonly zengin: "^0.1.0";
+};
+export declare function createProject(opts: CreateOptions): Promise<CreateResult>;