@zenginui/registry 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,71 @@
+import type { ComponentManifest } from "@zenginui/engine";
+export declare const REGISTRY_SCHEMA = "zengin-registry/1";
+export type ItemType = "component" | "template" | "lib" | "definitions" | "theme" | "fonts" | "icons";
+/** One typographic role: a Google Fonts family at the weights the components use. */
+export interface FontRole {
+    family: string;
+    weights: number[];
+    /** A serif face gets a serif fallback stack. */
+    serif?: boolean;
+}
+/** A pairing: headlines, text and code. */
+export interface FontPairing {
+    display: FontRole;
+    sans: FontRole;
+    mono: FontRole;
+}
+export type FileKind = "component" | "style" | "story" | "lib" | "template" | "definitions" | "theme";
+export interface RegistryFile {
+    /** Path relative to the project root the item installs into. */
+    path: string;
+    kind: FileKind;
+    content: string;
+}
+export interface RegistryItem {
+    name: string;
+    type: ItemType;
+    title: string;
+    description: string;
+    /** npm packages the item needs at runtime. */
+    dependencies: Record<string, string>;
+    /** npm packages the item needs at build time. */
+    devDependencies: Record<string, string>;
+    /** Other registry items this one needs, installed first. */
+    registryDependencies: string[];
+    files: RegistryFile[];
+    /** For components: the manifest entry, with `export.from` already pointing at the project alias. */
+    manifest?: ComponentManifest;
+    /** For themes: Google Fonts families the brand file expects, linked into index.html on apply. `Family:400;700` pins weights. */
+    fonts?: string[];
+    /** For fonts items: the pairing. */
+    pairing?: FontPairing;
+    /** For icons items: the react-icons module and the vocabulary name -> export name map. */
+    iconSet?: {
+        module: string;
+        names: Record<string, string>;
+    };
+    /** For templates: the repository directory the template is derived from, which the site builds as its live preview. */
+    source?: string;
+}
+/** The index: every item without its file contents, so a client can list and resolve before fetching. */
+export interface RegistryIndex {
+    schema: typeof REGISTRY_SCHEMA;
+    name: string;
+    /** Version of the system the items were cut from; written into the owned pragma of installed files. */
+    version: string;
+    generatedAt: string;
+    items: Omit<RegistryItem, "files" | "manifest">[];
+}
+export interface Registry extends Omit<RegistryIndex, "items"> {
+    items: RegistryItem[];
+}
+/** Where installed files go inside a project. One convention, so `add` needs no configuration. */
+export declare const LAYOUT: {
+    readonly componentsDir: "src/components/ui";
+    readonly alias: "@/components/ui";
+    readonly libDir: "src/lib";
+    readonly stylesIndex: "src/styles/index.css";
+    readonly storiesDir: "stories";
+    readonly definitionsDir: "zengin";
+};
+export declare function isRegistryIndex(x: unknown): x is RegistryIndex;

package/dist/schema.js

@@ -0,0 +1,13 @@
+export const REGISTRY_SCHEMA = "zengin-registry/1";
+/** Where installed files go inside a project. One convention, so `add` needs no configuration. */
+export const LAYOUT = {
+    componentsDir: "src/components/ui",
+    alias: "@/components/ui",
+    libDir: "src/lib",
+    stylesIndex: "src/styles/index.css",
+    storiesDir: "stories",
+    definitionsDir: "zengin",
+};
+export function isRegistryIndex(x) {
+    return typeof x === "object" && x !== null && x.schema === REGISTRY_SCHEMA && Array.isArray(x.items);
+}

package/dist/theme.d.ts

@@ -0,0 +1,26 @@
+import type { RegistrySource } from "./load.js";
+export interface ThemeSummary {
+    name: string;
+    title: string;
+    description: string;
+    fonts: string[];
+}
+export interface ApplyThemeResult {
+    name: string;
+    /** Project-relative paths written. */
+    files: string[];
+    fonts: string[];
+    html: boolean;
+}
+/** Every theme the registry offers. */
+export declare function listThemes(source: RegistrySource): Promise<ThemeSummary[]>;
+/**
+ * Swaps the project's brand for a theme from the registry: the theme's files replace what is there
+ * (a theme is the whole brand, not an addition), and index.html gets the theme's fonts link, replacing
+ * the previous theme's. Everything else in the project is untouched, which is the point.
+ */
+export declare function applyTheme(opts: {
+    projectDir: string;
+    name: string;
+    source: RegistrySource;
+}): Promise<ApplyThemeResult>;

package/dist/theme.js

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fontsHref, patchIndexHtml } from "./html.js";
+/** Every theme the registry offers. */
+export async function listThemes(source) {
+    const index = await source.index();
+    return index.items.filter((i) => i.type === "theme").map((i) => ({ name: i.name, title: i.title, description: i.description, fonts: i.fonts ?? [] }));
+}
+/**
+ * Swaps the project's brand for a theme from the registry: the theme's files replace what is there
+ * (a theme is the whole brand, not an addition), and index.html gets the theme's fonts link, replacing
+ * the previous theme's. Everything else in the project is untouched, which is the point.
+ */
+export async function applyTheme(opts) {
+    const dir = resolve(opts.projectDir);
+    if (!existsSync(join(dir, "zengin.config.yaml")))
+        throw new Error(`${dir} has no zengin.config.yaml. Run zengin theme inside a project made by zengin create, or pass --dir.`);
+    const index = await opts.source.index();
+    const summary = index.items.find((i) => i.name === opts.name && i.type === "theme");
+    if (!summary) {
+        const names = index.items.filter((i) => i.type === "theme").map((i) => i.name);
+        throw new Error(`No theme "${opts.name}". Themes: ${names.join(", ")}.`);
+    }
+    const item = await opts.source.item(opts.name);
+    const files = [];
+    for (const f of item.files) {
+        const abs = join(dir, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.content);
+        files.push(f.path);
+    }
+    const fonts = item.fonts ?? [];
+    const html = patchIndexHtml(dir, { fonts: fonts.length ? fontsHref(fonts) : null });
+    return { name: item.name, files, fonts, html };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * tokens.json (and tokens.dark.json when present) to a stylesheet of custom properties, using the engine's
+ * own token loader so the variable names are exactly the ones the rules check for. Themes attach to any
+ * element: an explicit data-theme wins; without one, the system preference decides.
+ */
+export declare function buildTokensCss(definitionsDir: string): {
+    css: string;
+    light: number;
+    dark: number;
+};
+export declare function writeTokensCss(definitionsDir: string, outFile: string): {
+    light: number;
+    dark: number;
+};

package/dist/tokens.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadTokens } from "@zenginui/engine";
+/**
+ * tokens.json (and tokens.dark.json when present) to a stylesheet of custom properties, using the engine's
+ * own token loader so the variable names are exactly the ones the rules check for. Themes attach to any
+ * element: an explicit data-theme wins; without one, the system preference decides.
+ */
+export function buildTokensCss(definitionsDir) {
+    const lightPath = join(definitionsDir, "tokens.json");
+    if (!existsSync(lightPath))
+        throw new Error(`No tokens.json in ${definitionsDir}.`);
+    const light = loadTokens(JSON.parse(readFileSync(lightPath, "utf8")));
+    const darkPath = join(definitionsDir, "tokens.dark.json");
+    const dark = existsSync(darkPath) ? loadTokens(JSON.parse(readFileSync(darkPath, "utf8"))) : [];
+    const lightVars = new Set(light.map((t) => t.cssVar));
+    const unknown = dark.filter((t) => !lightVars.has(t.cssVar)).map((t) => t.cssVar);
+    if (unknown.length)
+        throw new Error(`tokens.dark.json defines tokens missing from tokens.json: ${unknown.join(", ")}`);
+    const parts = [
+        "/* Generated from zengin/tokens.json and zengin/tokens.dark.json by `zengin tokens`. Do not edit. */",
+        "",
+        block(':root, [data-theme="light"]', light),
+    ];
+    if (dark.length) {
+        parts.push("", block('[data-theme="dark"]', dark), "", "@media (prefers-color-scheme: dark) {", indent(block(':root:not([data-theme="light"])', dark)), "}");
+    }
+    return { css: parts.join("\n") + "\n", light: light.length, dark: dark.length };
+}
+export function writeTokensCss(definitionsDir, outFile) {
+    const { css, light, dark } = buildTokensCss(definitionsDir);
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, css);
+    return { light, dark };
+}
+function block(selector, tokens) {
+    return `${selector} {\n${tokens.map((t) => `  ${t.cssVar}: ${t.value};`).join("\n")}\n}`;
+}
+function indent(s) {
+    return s
+        .split("\n")
+        .map((l) => (l ? `  ${l}` : l))
+        .join("\n");
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,60 @@
+import type { RegistrySource } from "./load.js";
+/**
+ * What changed upstream since a project copied its components, and whether the project changed them too.
+ * Every owned file carries the hash of what was copied. Comparing that hash with the file as it is now says
+ * whether the project edited it; comparing it with the registry's current file says whether the system
+ * moved. Four answers per file, and only one of them needs a person: both sides changed.
+ */
+export type UpgradeState = 
+/** The file is what the registry ships. */
+"current"
+/** Upstream changed, the project did not: safe to take. */
+ | "upstream"
+/** The project changed it, upstream did not: nothing to do. */
+ | "local"
+/** Both changed: a person merges, or --force takes upstream. */
+ | "conflict"
+/** No hash in the pragma (copied before hashes) and the contents differ: cannot tell which side moved. */
+ | "unknown"
+/** The registry no longer ships this file. */
+ | "gone";
+export interface UpgradeEntry {
+    /** Project-relative path. */
+    path: string;
+    /** Registry item the file belongs to. */
+    item: string;
+    state: UpgradeState;
+    /** The version the file was copied from, when the pragma says. */
+    from?: string;
+    /** Local against upstream, for a conflict or an unknown. */
+    diff?: string;
+}
+export interface UpgradePlan {
+    /** The version the project pins in zengin.config.yaml. */
+    projectVersion: string | undefined;
+    /** The registry's version. */
+    version: string;
+    entries: UpgradeEntry[];
+    /** Registry items the project has files for. */
+    items: string[];
+}
+export interface ApplyResult {
+    written: string[];
+    skipped: UpgradeEntry[];
+    /** True when zengin.config.yaml's system.version was moved to the registry's. */
+    versionBumped: boolean;
+}
+/** Owned files under src/components/ui and the libs under src/lib, mapped to the registry items that ship them. */
+export declare function planUpgrade(opts: {
+    projectDir: string;
+    source: RegistrySource;
+    only?: string[];
+}): Promise<UpgradePlan>;
+/** Takes upstream for every `upstream` entry, and for `conflict`/`unknown` entries only with `force`. Bumps the pinned version when nothing is left behind. */
+export declare function applyUpgrade(plan: UpgradePlan, opts: {
+    projectDir: string;
+    source: RegistrySource;
+    force?: boolean;
+}): Promise<ApplyResult>;
+/** A unified-style diff, local against upstream, three lines of context. Enough to decide; a merge tool does the rest. */
+export declare function diffLines(local: string, upstream: string, context?: number): string;

package/dist/upgrade.js

@@ -0,0 +1,171 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { readOwnedPragma } from "@zenginui/engine";
+import { kebab } from "./build.js";
+import { contentHash, mergeManifest, stripPragma, withPragma } from "./install.js";
+import { LAYOUT } from "./schema.js";
+/** Owned files under src/components/ui and the libs under src/lib, mapped to the registry items that ship them. */
+export async function planUpgrade(opts) {
+    const dir = resolve(opts.projectDir);
+    const configPath = join(dir, "zengin.config.yaml");
+    if (!existsSync(configPath))
+        throw new Error(`${dir} has no zengin.config.yaml. Run zengin upgrade inside a project made by zengin create, or pass --dir.`);
+    const projectVersion = /^\s*version:\s*"?([^"\s#]+)"?/m.exec(readFileSync(configPath, "utf8"))?.[1];
+    const index = await opts.source.index();
+    const only = opts.only?.map((n) => n.replace(/^lib-/, ""));
+    // Which items to look at: every component item with a directory in the project, every lib item with a file.
+    const wanted = index.items.filter((i) => {
+        if (i.type === "component")
+            return existsSync(join(dir, LAYOUT.componentsDir, i.name)) && (!only || only.includes(i.name));
+        if (i.type === "lib")
+            return existsSync(join(dir, LAYOUT.libDir)) && (!only || only.includes(i.name.replace(/^lib-/, "")));
+        return false;
+    });
+    const entries = [];
+    const items = [];
+    for (const summary of wanted) {
+        const item = await opts.source.item(summary.name);
+        let touched = false;
+        for (const f of item.files) {
+            if (f.kind === "story")
+                continue; // the project's from the start
+            const abs = join(dir, f.path);
+            if (!existsSync(abs))
+                continue;
+            touched = true;
+            entries.push(compare(f.path, readFileSync(abs, "utf8"), f.content, item));
+        }
+        if (touched)
+            items.push(item.name);
+    }
+    // Files with a pragma whose item the registry no longer has.
+    for (const p of walk(join(dir, LAYOUT.componentsDir))) {
+        const rel = relative(dir, p).replace(/\\/g, "/");
+        if (entries.some((e) => e.path === rel))
+            continue;
+        const pragma = readOwnedPragma(readFileSync(p, "utf8"));
+        if (!pragma?.component)
+            continue;
+        const name = kebab(pragma.component);
+        if (only && !only.includes(name))
+            continue;
+        if (!index.items.some((i) => i.name === name))
+            entries.push({ path: rel, item: name, state: "gone", ...(pragma.forkedFrom ? { from: pragma.forkedFrom } : {}) });
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { projectVersion, version: index.version, entries, items };
+}
+function compare(path, local, upstreamRaw, item) {
+    const pragma = readOwnedPragma(local);
+    const localBody = stripPragma(local);
+    const upstream = stripPragma(upstreamRaw);
+    const from = pragma?.forkedFrom;
+    const base = { path, item: item.name, state: "current", ...(from ? { from } : {}) };
+    if (localBody === upstream)
+        return base;
+    if (!pragma?.sha)
+        return { ...base, state: "unknown", diff: diffLines(localBody, upstream) };
+    const localChanged = contentHash(localBody) !== pragma.sha;
+    const upstreamChanged = contentHash(upstream) !== pragma.sha;
+    if (upstreamChanged && !localChanged)
+        return { ...base, state: "upstream" };
+    if (localChanged && !upstreamChanged)
+        return { ...base, state: "local" };
+    return { ...base, state: "conflict", diff: diffLines(localBody, upstream) };
+}
+/** Takes upstream for every `upstream` entry, and for `conflict`/`unknown` entries only with `force`. Bumps the pinned version when nothing is left behind. */
+export async function applyUpgrade(plan, opts) {
+    const dir = resolve(opts.projectDir);
+    const written = [];
+    const skipped = [];
+    const byItem = new Map();
+    const load = async (name) => byItem.get(name) ?? (byItem.set(name, await opts.source.item(name)), byItem.get(name));
+    for (const e of plan.entries) {
+        const take = e.state === "upstream" || ((e.state === "conflict" || e.state === "unknown") && opts.force);
+        if (!take) {
+            if (e.state === "conflict" || e.state === "unknown")
+                skipped.push(e);
+            continue;
+        }
+        const item = await load(e.item);
+        const f = item.files.find((x) => x.path === e.path);
+        const owned = item.manifest && (f.kind === "component" || (f.kind === "style" && f.path.startsWith(LAYOUT.componentsDir)));
+        writeFileSync(join(dir, e.path), owned ? withPragma(f.content, item.manifest.name, plan.version) : f.content);
+        written.push(e.path);
+        if (item.manifest && f.kind === "component")
+            mergeManifest(dir, { ...item.manifest, export: item.type === "component" ? { ...item.manifest.export, from: LAYOUT.alias } : item.manifest.export });
+    }
+    // Files the project edited but upstream did not keep their old pragma; they are current by choice. Only a
+    // conflict or an unknown left behind means the project is not on the registry's version yet.
+    let versionBumped = false;
+    if (skipped.length === 0 && plan.projectVersion !== plan.version) {
+        const p = join(dir, "zengin.config.yaml");
+        const before = readFileSync(p, "utf8");
+        const after = before.replace(/^(\s*version:\s*)"?[^"\s#]+"?/m, `$1"${plan.version}"`);
+        if (after !== before) {
+            writeFileSync(p, after);
+            versionBumped = true;
+        }
+    }
+    return { written, skipped, versionBumped };
+}
+function walk(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir).sort()) {
+        const p = join(dir, name);
+        if (statSync(p).isDirectory())
+            out.push(...walk(p));
+        else if (/\.(tsx|ts|css)$/.test(name))
+            out.push(p);
+    }
+    return out;
+}
+/** A unified-style diff, local against upstream, three lines of context. Enough to decide; a merge tool does the rest. */
+export function diffLines(local, upstream, context = 3) {
+    const a = local.split("\n");
+    const b = upstream.split("\n");
+    // Longest common subsequence by dynamic programming; component files are a few hundred lines.
+    const n = a.length;
+    const m = b.length;
+    const table = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j])
+            ops.push({ t: " ", s: a[i] }), i++, j++;
+        else if (table[i + 1][j] >= table[i][j + 1])
+            ops.push({ t: "-", s: a[i] }), i++;
+        else
+            ops.push({ t: "+", s: b[j] }), j++;
+    }
+    while (i < n)
+        ops.push({ t: "-", s: a[i++] });
+    while (j < m)
+        ops.push({ t: "+", s: b[j++] });
+    const keep = new Array(ops.length).fill(false);
+    ops.forEach((op, k) => {
+        if (op.t === " ")
+            return;
+        for (let c = Math.max(0, k - context); c <= Math.min(ops.length - 1, k + context); c++)
+            keep[c] = true;
+    });
+    const lines = ["--- local", "+++ upstream"];
+    let gap = false;
+    ops.forEach((op, k) => {
+        if (!keep[k]) {
+            gap = true;
+            return;
+        }
+        if (gap)
+            lines.push("@@");
+        gap = false;
+        lines.push(`${op.t}${op.s}`);
+    });
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zenginui/registry",
+  "version": "0.1.0",
+  "description": "The Zengin registry: components, templates and definitions as installable items, plus the project generator behind `zengin create` and `zengin add`.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "design-system",
+    "registry",
+    "scaffold",
+    "generator",
+    "zengin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Timurtek/zengin.git",
+    "directory": "packages/registry"
+  },
+  "homepage": "https://github.com/Timurtek/zengin/tree/main/packages/registry#readme",
+  "bugs": "https://github.com/Timurtek/zengin/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zenginui/engine": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "react-icons": "^5.7.0",
+    "typescript": "^5.9.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}