@kondeio/kdf 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { type ClassValue } from "clsx";
+import type { DesignAccessor, GetDesignOptions } from "./types.js";
+export type { DesignAccessor, DesignTokenFile, DesignTokenValue, GetDesignOptions, KdfCacheMode, } from "./types.js";
+export { clearKdfCache } from "./resolver.js";
+export type ClassMergeFunction = (className: string) => string;
+export interface ClassComposerOptions {
+    /**
+     * Optional app-defined semantic merge step.
+     *
+     * KDF's default merge only removes exact duplicate classes. If an app wants
+     * semantic rules such as "keep the last class in this project-specific group",
+     * inject that logic here.
+     */
+    merge?: ClassMergeFunction;
+}
+/**
+ * Get design accessor for a page.
+ *
+ * Usage:
+ *   const d = getDesign("homepage");
+ *   <h1 data-kdf="hero.title" className={d("hero.title")}>{t("hero.headline")}</h1>
+ *
+ * Resolution order: kdf/<page>.json -> kdf/shared/
+ */
+export declare function getDesign(page: string, options?: GetDesignOptions): DesignAccessor;
+/**
+ * Remove exact duplicate class names while preserving first-seen order.
+ *
+ * This is intentionally semantic-free: it does not try to understand any CSS
+ * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
+ */
+export declare function dedupeClasses(className: string): string;
+/**
+ * Create a UI-library agnostic class composer.
+ *
+ * Default behavior:
+ * - flatten strings, arrays, and objects through clsx
+ * - drop falsy values
+ * - normalize whitespace
+ * - remove exact duplicate class names
+ *
+ * Apps that need semantic class conflict handling can inject their own merge
+ * function. KDF does not ship CSS-framework-specific class rules.
+ */
+export declare function createClassComposer(options?: ClassComposerOptions): (...inputs: ClassValue[]) => string;
+export declare const composeClasses: (...inputs: ClassValue[]) => string;
+export declare const cx: (...inputs: ClassValue[]) => string;
+export declare const cn: (...inputs: ClassValue[]) => string;

package/dist/index.js

@@ -0,0 +1,62 @@
+import { clsx } from "clsx";
+import { loadFile, resolveClassName, resolveCSS } from "./resolver.js";
+export { clearKdfCache } from "./resolver.js";
+/**
+ * Get design accessor for a page.
+ *
+ * Usage:
+ *   const d = getDesign("homepage");
+ *   <h1 data-kdf="hero.title" className={d("hero.title")}>{t("hero.headline")}</h1>
+ *
+ * Resolution order: kdf/<page>.json -> kdf/shared/
+ */
+export function getDesign(page, options) {
+    const accessor = ((path) => {
+        const pageTokens = loadFile(page, options);
+        return resolveClassName(path, pageTokens, options);
+    });
+    accessor.css = (path) => {
+        const pageTokens = loadFile(page, options);
+        return resolveCSS(path, pageTokens);
+    };
+    return accessor;
+}
+/**
+ * Remove exact duplicate class names while preserving first-seen order.
+ *
+ * This is intentionally semantic-free: it does not try to understand any CSS
+ * framework. It only turns "btn btn btn-primary" into "btn btn-primary".
+ */
+export function dedupeClasses(className) {
+    const seen = new Set();
+    const output = [];
+    for (const part of className.trim().split(/\s+/)) {
+        if (!part || seen.has(part))
+            continue;
+        seen.add(part);
+        output.push(part);
+    }
+    return output.join(" ");
+}
+/**
+ * Create a UI-library agnostic class composer.
+ *
+ * Default behavior:
+ * - flatten strings, arrays, and objects through clsx
+ * - drop falsy values
+ * - normalize whitespace
+ * - remove exact duplicate class names
+ *
+ * Apps that need semantic class conflict handling can inject their own merge
+ * function. KDF does not ship CSS-framework-specific class rules.
+ */
+export function createClassComposer(options = {}) {
+    const merge = options.merge ?? dedupeClasses;
+    return (...inputs) => {
+        const joined = clsx(...inputs);
+        return merge(joined);
+    };
+}
+export const composeClasses = createClassComposer();
+export const cx = composeClasses;
+export const cn = composeClasses;

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+/** Minimal Next.js config shape — avoids hard dependency on next */
+interface NextConfig {
+    env?: Record<string, string>;
+    webpack?: (config: Record<string, unknown>, context: {
+        dev: boolean;
+    }) => Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface KDFPluginOptions {
+    /** KDF directory path (default: "./kdf"). Rename to anything: "./design", "./designs/lander" */
+    dir?: string;
+}
+/**
+ * Next.js plugin for @kondeio/kdf.
+ *
+ * Single config — everything follows from `dir`:
+ *   - JSON tokens: <dir>/shared/, <dir>/homepage.json
+ *   - konde-server.css: <dir>/konde-server.css (import in layout.tsx)
+ *   - konde.css: <dir>/konde.css
+ *
+ * The plugin only exposes paths via env (KDF_DIR, KDF_SERVER_CSS,
+ * KDF_CLIENT_CSS). It does NOT inject CSS — wire the <link>/import in your app.
+ *
+ * Usage:
+ *   export default withKDF()(nextConfig);                        // default: ./kdf
+ *   export default withKDF({ dir: "./design" })(nextConfig);     // rename folder
+ *   export default withKDF({ dir: "./designs/lander" })(nextConfig); // multi-template
+ */
+export default function withKDF(options?: KDFPluginOptions): (nextConfig?: NextConfig) => NextConfig;
+export {};

package/dist/plugin.js

@@ -0,0 +1,40 @@
+import { existsSync } from "fs";
+import { join } from "path";
+/**
+ * Next.js plugin for @kondeio/kdf.
+ *
+ * Single config — everything follows from `dir`:
+ *   - JSON tokens: <dir>/shared/, <dir>/homepage.json
+ *   - konde-server.css: <dir>/konde-server.css (import in layout.tsx)
+ *   - konde.css: <dir>/konde.css
+ *
+ * The plugin only exposes paths via env (KDF_DIR, KDF_SERVER_CSS,
+ * KDF_CLIENT_CSS). It does NOT inject CSS — wire the <link>/import in your app.
+ *
+ * Usage:
+ *   export default withKDF()(nextConfig);                        // default: ./kdf
+ *   export default withKDF({ dir: "./design" })(nextConfig);     // rename folder
+ *   export default withKDF({ dir: "./designs/lander" })(nextConfig); // multi-template
+ */
+export default function withKDF(options) {
+    return (nextConfig = {}) => {
+        const kdfDir = options?.dir || "./kdf";
+        const serverCssPath = join(process.cwd(), kdfDir, "konde-server.css");
+        const clientCssPath = join(process.cwd(), kdfDir, "konde.css");
+        return {
+            ...nextConfig,
+            env: {
+                ...nextConfig.env,
+                KDF_DIR: kdfDir,
+                ...(existsSync(serverCssPath) ? { KDF_SERVER_CSS: join(kdfDir, "konde-server.css") } : {}),
+                ...(existsSync(clientCssPath) ? { KDF_CLIENT_CSS: join(kdfDir, "konde.css") } : {}),
+            },
+            webpack(config, context) {
+                if (typeof nextConfig.webpack === "function") {
+                    return nextConfig.webpack(config, context);
+                }
+                return config;
+            },
+        };
+    };
+}

package/dist/postinstall.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/postinstall.js

@@ -0,0 +1,48 @@
+/**
+ * postinstall — runs automatically after installing @kondeio/kdf.
+ *
+ * Creates kdf/ folder + konde CSS files in user's project root.
+ * All writes are safe — never overwrites existing files.
+ * Uses INIT_CWD (project root), not package directory.
+ *
+ * Set KDF_SKIP_INIT=1 to install the package without scaffolding files.
+ */
+import { mkdirSync, existsSync, copyFileSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { writeKondeCSS } from "./css-generator.js";
+// INIT_CWD = project root (set by npm/bun during install)
+// Fallback to cwd for direct execution
+const projectRoot = process.env.INIT_CWD || process.cwd();
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, "..", "kdf");
+if (process.env.KDF_SKIP_INIT === "1" || process.env.KDF_SKIP_INIT === "true") {
+    process.exit(0);
+}
+const targetDir = join(projectRoot, "kdf");
+// Skip if already initialized
+if (existsSync(targetDir)) {
+    process.exit(0);
+}
+// Create kdf/ and kdf/shared/
+mkdirSync(join(targetDir, "shared"), { recursive: true });
+// Copy shared token files
+const sharedDir = join(TEMPLATES_DIR, "shared");
+if (existsSync(sharedDir)) {
+    for (const file of readdirSync(sharedDir).filter((f) => f.endsWith(".json"))) {
+        copyFileSync(join(sharedDir, file), join(targetDir, "shared", file));
+    }
+}
+// Copy homepage.json as starter
+const homepageSrc = join(TEMPLATES_DIR, "homepage.json");
+if (existsSync(homepageSrc)) {
+    copyFileSync(homepageSrc, join(targetDir, "homepage.json"));
+}
+// Generate empty CSS files inside kdf/ folder
+writeKondeCSS(targetDir);
+console.log("@kondeio/kdf initialized:");
+console.log("  kdf/");
+console.log("    shared/            ← design tokens");
+console.log("    homepage.json");
+console.log("    konde-server.css   ← critical overrides (import in layout.tsx)");
+console.log("    konde.css          ← non-critical overrides (load after framework CSS)");

package/dist/resolver.d.ts

@@ -0,0 +1,11 @@
+import type { DesignTokenFile, GetDesignOptions } from "./types.js";
+/** Returns KDF root path — reads env at call time, not module load time */
+declare function getKdfRoot(): string;
+export declare function clearKdfCache(): void;
+declare function loadFile(name: string, options?: GetDesignOptions): DesignTokenFile | null;
+/** Resolve className for a token path.
+ *  Looks in page JSON first. @references resolve from shared/ files. */
+export declare function resolveClassName(path: string, pageTokens: DesignTokenFile | null, options?: GetDesignOptions): string;
+/** Resolve CSS custom properties for a token path */
+export declare function resolveCSS(path: string, pageTokens: DesignTokenFile | null): Record<string, string>;
+export { loadFile, getKdfRoot };

package/dist/resolver.js

@@ -0,0 +1,184 @@
+import { readFileSync, statSync } from "fs";
+import { isAbsolute, join } from "path";
+/** Returns KDF root path — reads env at call time, not module load time */
+function getKdfRoot() {
+    const dir = process.env.KDF_DIR || "kdf";
+    return isAbsolute(dir) ? dir : join(process.cwd(), dir);
+}
+const DEFAULT_DEV_CACHE_MAX_AGE_MS = 250;
+/** Cache: path -> parsed JSON plus lightweight file identity */
+const cache = new Map();
+function getCacheMode(options) {
+    return options?.cache ?? "auto";
+}
+function getDevMaxAgeMs(options) {
+    if (typeof options?.maxAgeMs === "number" && options.maxAgeMs >= 0) {
+        return options.maxAgeMs;
+    }
+    const fromEnv = Number(process.env.KDF_CACHE_MAX_AGE_MS);
+    if (Number.isFinite(fromEnv) && fromEnv >= 0) {
+        return fromEnv;
+    }
+    return DEFAULT_DEV_CACHE_MAX_AGE_MS;
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function loadJsonFile(filePath, options) {
+    const mode = getCacheMode(options);
+    if (mode === "none") {
+        return readJsonFile(filePath);
+    }
+    const cached = cache.get(filePath);
+    if (mode === "always" || process.env.NODE_ENV === "production") {
+        if (cached)
+            return cached.value;
+        const value = readJsonFile(filePath);
+        cache.set(filePath, { value, mtimeMs: -1, size: -1, checkedAt: Date.now() });
+        return value;
+    }
+    const now = Date.now();
+    const maxAgeMs = getDevMaxAgeMs(options);
+    if (cached && now - cached.checkedAt < maxAgeMs) {
+        return cached.value;
+    }
+    try {
+        const stat = statSync(filePath);
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            cached.checkedAt = now;
+            return cached.value;
+        }
+        const value = readJsonFile(filePath);
+        cache.set(filePath, {
+            value,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+            checkedAt: now,
+        });
+        return value;
+    }
+    catch {
+        cache.set(filePath, { value: null, mtimeMs: -1, size: -1, checkedAt: now });
+        return null;
+    }
+}
+export function clearKdfCache() {
+    cache.clear();
+}
+function loadFile(name, options) {
+    const filePath = join(getKdfRoot(), `${name}.json`);
+    return loadJsonFile(filePath, options);
+}
+/** Load JSON from absolute path (for root shared fallback) */
+function loadFileAbsolute(filePath, options) {
+    return loadJsonFile(filePath, options);
+}
+/** Get value from nested object by dot-path */
+function getByPath(obj, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}
+/**
+ * Resolve a single @reference: "@button.cta"
+ * @button.cta -> load shared/button.json -> key "cta"
+ */
+function resolveSingleRef(ref, pageTokens, depth, options) {
+    if (depth > 5)
+        return "";
+    const refPart = ref.slice(1); // remove @
+    const dotIdx = refPart.indexOf(".");
+    const component = dotIdx > 0 ? refPart.slice(0, dotIdx) : refPart;
+    const key = dotIdx > 0 ? refPart.slice(dotIdx + 1) : "";
+    // Reject path-traversal in the component name: it becomes part of a file path
+    // (shared/<component>.json). A ref like "@../../secret.x" must never escape the
+    // shared/ folder. Allow only safe filename chars.
+    if (!/^[A-Za-z0-9_-]+$/.test(component)) {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn(`[kdf] ignoring unsafe @ref component: "${component}"`);
+        }
+        return "";
+    }
+    // Load shared/<component>.json — cascade: template shared → root shared
+    let resolved = undefined;
+    // 1. Template-specific shared (e.g., designs/lander/shared/button.json)
+    const templateShared = loadFile(`shared/${component}`, options);
+    if (key && templateShared) {
+        resolved = getByPath(templateShared, key);
+    }
+    // 2. Root shared fallback (e.g., designs/shared/button.json)
+    if (resolved === undefined && key) {
+        const rootShared = loadFileAbsolute(join(getKdfRoot(), "..", "shared", `${component}.json`), options);
+        if (rootShared) {
+            resolved = getByPath(rootShared, key);
+        }
+    }
+    // 3. Fallback: check page-level tokens
+    if (resolved === undefined && pageTokens) {
+        resolved = getByPath(pageTokens, refPart);
+    }
+    if (typeof resolved === "string") {
+        // Resolved value might itself contain @refs
+        return resolveTokenString(resolved, pageTokens, depth + 1, options);
+    }
+    if (resolved && typeof resolved === "object" && "className" in resolved) {
+        const cn = resolved.className;
+        return resolveTokenString(cn, pageTokens, depth + 1, options);
+    }
+    return "";
+}
+/**
+ * Resolve a token string that may contain multiple @refs and plain classes.
+ * Examples:
+ *   "@button.cta"                         -> resolves single ref
+ *   "@button.cta shadow-xl"               -> resolves ref + appends classes
+ *   "@button.base @button.ghost @button.sm" -> resolves all three refs
+ */
+function resolveTokenString(value, pageTokens, depth = 0, options) {
+    if (depth > 5)
+        return value;
+    const parts = value.split(/\s+/).filter(Boolean);
+    const resolved = parts.map((part) => {
+        if (part.startsWith("@")) {
+            return resolveSingleRef(part, pageTokens, depth, options);
+        }
+        return part;
+    });
+    return resolved.filter(Boolean).join(" ");
+}
+/** Resolve className for a token path.
+ *  Looks in page JSON first. @references resolve from shared/ files. */
+export function resolveClassName(path, pageTokens, options) {
+    const val = pageTokens
+        ? getByPath(pageTokens, path)
+        : undefined;
+    if (val === undefined)
+        return "";
+    if (typeof val === "string") {
+        return resolveTokenString(val, pageTokens, 0, options);
+    }
+    if (typeof val === "object" && val && "className" in val) {
+        const cn = val.className;
+        return resolveTokenString(cn, pageTokens, 0, options);
+    }
+    return "";
+}
+/** Resolve CSS custom properties for a token path */
+export function resolveCSS(path, pageTokens) {
+    const val = pageTokens
+        ? getByPath(pageTokens, path)
+        : undefined;
+    if (val && typeof val === "object" && "css" in val) {
+        return val.css;
+    }
+    return {};
+}
+export { loadFile, getKdfRoot };

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/** A design token value — className string, @reference, or object with component binding */
+export type DesignTokenValue = string | {
+    /** Component binding — WHAT to render: "Button", "h1", "Image" */
+    $?: string;
+    /** CSS class string. Supports @refs: "@button.cta shadow-xl" */
+    className?: string;
+    /** CSS custom properties generated into konde.css */
+    css?: Record<string, string>;
+    /** Pass-through props for the bound component (variant, size, etc.) */
+    [key: string]: unknown;
+};
+/** A design token file — nested keys to values */
+export interface DesignTokenFile {
+    /** Page section ordering — which sections appear and in what order */
+    $layout?: string[];
+    [key: string]: DesignTokenValue | DesignTokenGroup | string[] | undefined;
+}
+export interface DesignTokenGroup {
+    [key: string]: DesignTokenValue | DesignTokenGroup;
+}
+/** Resolved design accessor for a page */
+export interface DesignAccessor {
+    /** Get className for a dot-path: d("hero.title") */
+    (path: string): string;
+    /** Get CSS custom properties for a dot-path */
+    css(path: string): Record<string, string>;
+}
+export type KdfCacheMode = "auto" | "always" | "none";
+export interface GetDesignOptions {
+    /**
+     * Cache policy for design JSON files.
+     *
+     * - auto: production caches forever; development caches with mtime revalidation.
+     * - always: cache for the lifetime of the process until clearKdfCache() is called.
+     * - none: read from disk on every access.
+     */
+    cache?: KdfCacheMode;
+    /**
+     * Development revalidation window for cache="auto".
+     * Defaults to 250ms to avoid render-time disk-read storms while keeping
+     * design JSON edits responsive during local development.
+     */
+    maxAgeMs?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};