ink-cartridge 3.6.1

package/dist/theme/provider.js

@@ -0,0 +1,308 @@
+import React, { useState, useMemo, useCallback } from 'react';
+import { readFileSync, readdirSync } from 'fs';
+import { resolve } from 'path';
+import { ThemeContext } from './context.js';
+/**
+ * Extract unique non-id keys from a list of themes.
+ * All themes must have identical keys after removing 'id'.
+ */
+function extractKeys(themes) {
+    if (themes.length === 0)
+        return [];
+    const first = themes[0];
+    const keys = Object.keys(first).filter((k) => k !== 'id');
+    for (let i = 1; i < themes.length; i++) {
+        const current = Object.keys(themes[i]).filter((k) => k !== 'id');
+        const missing = keys.filter((k) => !current.includes(k));
+        const extra = current.filter((k) => !keys.includes(k));
+        if (missing.length > 0 || extra.length > 0) {
+            const details = [];
+            if (missing.length > 0)
+                details.push(`missing from "${themes[i].id}": ${missing.join(', ')}`);
+            if (extra.length > 0)
+                details.push(`extra in "${themes[i].id}": ${extra.join(', ')}`);
+            throw new Error(`[Ink-Cartridge] Theme key mismatch in "${themes[i].id}". ` +
+                `All themes must have identical keys (excluding 'id'). ${details.join('; ')}`);
+        }
+    }
+    return keys;
+}
+function loadFromPath(dirPath) {
+    const themes = [];
+    let files;
+    try {
+        files = readdirSync(dirPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`[Ink-Cartridge] ThemeProvider failed to read directory "${dirPath}": ${msg}`);
+    }
+    for (const file of files) {
+        if (file.endsWith('.json')) {
+            const fullPath = resolve(dirPath, file);
+            let raw;
+            try {
+                raw = readFileSync(fullPath, 'utf-8');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Ink-Cartridge] ThemeProvider failed to read "${fullPath}": ${msg}`);
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.id !== 'string') {
+                    throw new Error(`[Ink-Cartridge] Theme file "${file}" is missing a required "id" field (string).`);
+                }
+                // Build a ThemeDefinition: strip the id field from the flat map
+                const theme = { id: parsed.id };
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (k === 'id')
+                        continue;
+                    if (typeof v === 'string' || typeof v === 'boolean') {
+                        theme[k] = v;
+                    }
+                }
+                themes.push(theme);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Ink-Cartridge] ThemeProvider failed to parse "${file}": ${msg}`);
+            }
+        }
+    }
+    return themes;
+}
+/**
+ * Load themes from multiple directory paths with filename-based deduplication.
+ *
+ * Processes paths in order — later paths override earlier ones when the
+ * same filename appears in multiple directories (within the batch).
+ *
+ * Returns the deduplicated list of ThemeDefinitions.
+ */
+function loadFromPaths(paths) {
+    // Map: filename → ThemeDefinition. Same filename → later overwrites earlier.
+    const fileMap = new Map();
+    for (const dirPath of paths) {
+        let files;
+        try {
+            files = readdirSync(dirPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`[Ink-Cartridge] ThemeProvider failed to read directory "${dirPath}": ${msg}`);
+        }
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const fullPath = resolve(dirPath, file);
+            let raw;
+            try {
+                raw = readFileSync(fullPath, 'utf-8');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Ink-Cartridge] ThemeProvider failed to read "${fullPath}": ${msg}`);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`[Ink-Cartridge] ThemeProvider failed to parse "${file}": ${msg}`);
+            }
+            if (typeof parsed.id !== 'string') {
+                throw new Error(`[Ink-Cartridge] Theme file "${file}" is missing a required "id" field (string).`);
+            }
+            const theme = { id: parsed.id };
+            for (const [k, v] of Object.entries(parsed)) {
+                if (k === 'id')
+                    continue;
+                if (typeof v === 'string' || typeof v === 'boolean') {
+                    theme[k] = v;
+                }
+            }
+            // Filename dedup: later paths win for same filename
+            fileMap.set(file, theme);
+        }
+    }
+    return Array.from(fileMap.values());
+}
+/**
+ * Context provider for theming.
+ *
+ * Loads theme definitions either from a directory of `{id}.json` files
+ * (via the `path` prop) or from pre-built inline objects (via `themes`).
+ *
+ * Descendant components can use the {@link useTheme} hook to access
+ * `color()` and `style()` functions, and `setTheme()` to switch themes.
+ */
+export function ThemeProvider({ children, themes: inlineThemes = [], path, defaultTheme, }) {
+    const rawThemes = useMemo(() => {
+        if (path)
+            return loadFromPath(path);
+        return inlineThemes;
+    }, [inlineThemes, path]);
+    // Overlay state for mergeTheme — avoids mutating rawThemes
+    const [mergedThemes, setMergedThemes] = useState(null);
+    const effectiveThemes = mergedThemes ?? rawThemes;
+    // Validate key consistency — only on initial load; merged themes are
+    // validated separately at merge time
+    if (rawThemes.length > 0) {
+        extractKeys(rawThemes);
+    }
+    const themeIds = useMemo(() => effectiveThemes.map((t) => t.id), [effectiveThemes]);
+    const [currentThemeId, setCurrentThemeId] = useState(defaultTheme ?? themeIds[0] ?? '');
+    const currentTheme = useMemo(() => effectiveThemes.find((t) => t.id === currentThemeId), [effectiveThemes, currentThemeId]);
+    const color = useCallback((key) => {
+        if (!currentTheme)
+            return undefined;
+        const val = currentTheme[key];
+        if (typeof val === 'string')
+            return val;
+        return undefined;
+    }, [currentTheme]);
+    const style = useCallback((key) => {
+        if (!currentTheme)
+            return undefined;
+        const val = currentTheme[key];
+        if (typeof val === 'boolean')
+            return val;
+        return undefined;
+    }, [currentTheme]);
+    const setTheme = useCallback((id) => {
+        if (!effectiveThemes.find((t) => t.id === id)) {
+            const available = themeIds.join(', ');
+            throw new Error(`[Ink-Cartridge] Theme "${id}" is not available. ` +
+                `Available themes: ${available}`);
+        }
+        setCurrentThemeId(id);
+    }, [effectiveThemes, themeIds]);
+    const mergeTheme = useCallback((paths) => {
+        const base = mergedThemes ?? rawThemes;
+        // Build a lookup of existing themes by id
+        const lookup = new Map();
+        for (const t of base) {
+            const copy = { id: t.id };
+            for (const [k, v] of Object.entries(t)) {
+                if (k !== 'id')
+                    copy[k] = v;
+            }
+            lookup.set(t.id, copy);
+        }
+        let hadChanges = false;
+        for (const dirPath of paths) {
+            const incoming = loadFromPath(dirPath);
+            for (const inc of incoming) {
+                const existing = lookup.get(inc.id);
+                if (!existing)
+                    continue; // ignore themes not in base
+                for (const [k, v] of Object.entries(inc)) {
+                    if (k === 'id')
+                        continue;
+                    existing[k] = v;
+                }
+                hadChanges = true;
+            }
+        }
+        if (hadChanges) {
+            const merged = Array.from(lookup.values());
+            extractKeys(merged); // re-validate after merge
+            setMergedThemes(merged);
+        }
+    }, [mergedThemes, rawThemes]);
+    // ── addThemes ────────────────────────────────────────────────
+    const addThemes = useCallback((paths) => {
+        const base = mergedThemes ?? rawThemes;
+        const existingIds = new Set(base.map((t) => t.id));
+        // Load from all paths with filename-based dedup
+        const incoming = loadFromPaths(paths);
+        // Detect id conflicts within the incoming batch (different filenames
+        // claiming the same id — filename dedup already resolved same-file cases).
+        // Re-scan all files to build a mapping of id → [source filenames],
+        // then flag any id claimed by more than one filename.
+        const idSourceFiles = new Map(); // id → [filenames]
+        for (const dirPath of paths) {
+            let files;
+            try {
+                files = readdirSync(dirPath);
+            }
+            catch {
+                continue; // loadFromPaths already validates, should not reach here
+            }
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const fullPath = resolve(dirPath, file);
+                let parsed;
+                try {
+                    parsed = JSON.parse(readFileSync(fullPath, 'utf-8'));
+                }
+                catch {
+                    continue;
+                }
+                if (typeof parsed.id !== 'string')
+                    continue;
+                if (!idSourceFiles.has(parsed.id)) {
+                    idSourceFiles.set(parsed.id, []);
+                }
+                const list = idSourceFiles.get(parsed.id);
+                if (!list.includes(file)) {
+                    list.push(file);
+                }
+            }
+        }
+        // Check: same id claimed by multiple filenames → error
+        for (const [id, filenames] of idSourceFiles) {
+            if (filenames.length > 1) {
+                throw new Error(`[Ink-Cartridge] addThemes detected duplicate theme id "${id}" ` +
+                    `in files: ${filenames.join(', ')}. Theme ids must be unique.`);
+            }
+        }
+        // Expected key set from existing themes
+        const expectedKeys = base.length > 0
+            ? Object.keys(base[0]).filter((k) => k !== 'id')
+            : [];
+        // Validate each incoming theme
+        for (const theme of incoming) {
+            // Id conflict with base → error
+            if (existingIds.has(theme.id)) {
+                throw new Error(`[Ink-Cartridge] addThemes cannot add theme "${theme.id}" ` +
+                    `because a theme with this id already exists. ` +
+                    `Use mergeTheme() to update existing themes.`);
+            }
+            // Only validate keys if we have a reference set
+            if (expectedKeys.length > 0) {
+                const incKeys = Object.keys(theme).filter((k) => k !== 'id');
+                const missing = expectedKeys.filter((k) => !incKeys.includes(k));
+                const extra = incKeys.filter((k) => !expectedKeys.includes(k));
+                const details = [];
+                if (missing.length > 0)
+                    details.push(`missing: ${missing.join(', ')}`);
+                if (extra.length > 0)
+                    details.push(`extra: ${extra.join(', ')}`);
+                if (details.length > 0) {
+                    throw new Error(`[Ink-Cartridge] addThemes theme "${theme.id}" has mismatched keys. ` +
+                        `All themes must have identical keys (excluding 'id'). ${details.join('; ')}`);
+                }
+            }
+            existingIds.add(theme.id);
+        }
+        if (incoming.length > 0) {
+            const combined = [...base, ...incoming];
+            extractKeys(combined); // final safety check
+            setMergedThemes(combined);
+        }
+    }, [mergedThemes, rawThemes]);
+    const ctx = useMemo(() => ({
+        color,
+        style,
+        themeId: currentThemeId,
+        themes: themeIds,
+        setTheme,
+        mergeTheme,
+        addThemes,
+    }), [color, style, currentThemeId, themeIds, setTheme, mergeTheme, addThemes]);
+    return React.createElement(ThemeContext.Provider, { value: ctx }, children);
+}

package/dist/theme/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A single theme definition — a flat map of key-value pairs plus a unique id.
+ */
+export interface ThemeDefinition {
+    /** Unique identifier for this theme (e.g. "dark", "light"). */
+    id: string;
+    /** Flat key-value pairs where values are Ink color names or style booleans. */
+    [key: string]: string | boolean;
+}
+/**
+ * Props for the {@link ThemeProvider} component.
+ */
+export interface ThemeProviderProps {
+    children: React.ReactNode;
+    /** Directory path containing `{id}.json` files. */
+    path?: string;
+    /** Inline theme definitions (alternative to `path`). */
+    themes?: ThemeDefinition[];
+    /** Id of the theme to activate initially. Defaults to the first available. */
+    defaultTheme?: string;
+}
+/**
+ * Value provided by {@link ThemeProvider} via React context.
+ * Accessed via the {@link useTheme} hook.
+ */
+export interface ThemeContextValue {
+    /** Get a color value from the current theme (returns the raw string or undefined). */
+    color: (key: string) => string | undefined;
+    /** Get a style value (boolean) from the current theme (returns undefined if not set). */
+    style: (key: string) => boolean | undefined;
+    /** Currently active theme id. */
+    themeId: string;
+    /** List of all available theme ids. */
+    themes: string[];
+    /** Switch to a different theme by id. */
+    setTheme: (id: string) => void;
+    /**
+     * Merge additional theme files from one or more directory paths.
+     * Later paths override earlier paths for matching keys.
+     * Only themes whose id already exists are merged; new ids are ignored.
+     */
+    mergeTheme: (paths: string[]) => void;
+    /**
+     * Add new themes from one or more directory paths.
+     *
+     * Unlike {@link mergeTheme}, this adds **new** themes to the pool.
+     * - Same filename across paths → later overwrites earlier.
+     * - Same id as existing base theme → throws immediately.
+     * - Same id across different filenames within the batch → throws.
+     * - Missing or extra keys vs. existing themes → throws.
+     */
+    addThemes: (paths: string[]) => void;
+}

package/dist/theme/types.js

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

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "ink-cartridge",
+    "version": "3.6.1",
+    "description": "Ready-to-use Ink components and screen management system for building terminal UIs.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "bin": {
+        "ink-cartridge": "./dist/cli/index.js"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BAIGAOa/ink-cartridge.git"
+    },
+    "scripts": {
+        "build": "tsc --locale zh-CN",
+        "watch": "tsc --watch --locale zh-CN",
+        "clean": "rm -rf dist",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "demo:dev": "tsx examples/dev/dev.tsx"
+    },
+    "keywords": [
+        "ink",
+        "ink-component",
+        "react",
+        "tui",
+        "cli",
+        "terminal",
+        "screen-management"
+    ],
+    "author": "BAIGAO",
+    "license": "MIT",
+    "engines": {
+        "node": ">=22"
+    },
+    "peerDependencies": {
+        "ink": ">=5",
+        "react": ">=18"
+    },
+    "devDependencies": {
+        "@testing-library/react": "^16.3.0",
+        "@types/node": "^20.19.39",
+        "@types/react": "^19.2.14",
+        "ink": "^7.0.1",
+        "ink-testing-library": "^4.0.0",
+        "jsdom": "^26.0.0",
+        "react": "^19.2.4",
+        "tsx": "^4.22.4",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.5"
+    },
+    "bugs": {
+        "url": "https://github.com/BAIGAOa/ink-cartridge/issues"
+    },
+    "homepage": "https://github.com/BAIGAOa/ink-cartridge#readme",
+    "dependencies": {
+        "zod": "^4.4.3"
+    }
+}