@notty/theme-api 0.7.1 → 1.0.0

package/README.md

@@ -1,13 +1,36 @@
 # @notty/theme-api
 
-Theme API for customizing Notty CMS admin panel appearance.
+Public SDK for building Notty admin themes.
 
-## Installation
+## Current Status
 
-```bash
-npm install @notty/theme-api
+- Theme authoring workflow is available through `defineTheme()`
+- Includes theme manifest types, branding tokens, layout overrides, and white-label metadata
+- Active theme branding now flows into the admin `ui-config` endpoint and white-label branding pipeline
+- The API is usable now, but should still be treated as early-stage and evolving, especially for full token/layout runtime application
+- Distribution remains restricted to the `@notty` npm scope
+
+## Usage
+
+```ts
+import { defineTheme } from '@notty/theme-api';
+
+export default defineTheme({
+  manifest: {
+    name: '@acme/theme-brand',
+    displayName: 'Brand Theme',
+    version: '0.1.0',
+    kind: 'theme',
+    engines: { notty: '>=0.16.0' },
+    branding: {
+      title: 'Acme CMS',
+    },
+  },
+});
 ```
 
+For scaffolding, use `create-notty --theme`.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -20,11 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  THEME_API_VERSION: () => THEME_API_VERSION
+  defineTheme: () => import_types.defineTheme
 });
 module.exports = __toCommonJS(index_exports);
-var THEME_API_VERSION = "0.1.0";
+var import_types = require("@notty/types");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  THEME_API_VERSION
+  defineTheme
 });

package/dist/index.d.cts

@@ -1,7 +1 @@
-/**
- * @notty/theme-api
- * Theme SDK for ACms
- */
-declare const THEME_API_VERSION = "0.1.0";
-
-export { THEME_API_VERSION };
+export { ManifestValidationResult, PluginAuthor, PluginConfigSchema, PluginContext, PluginEngines, PluginLifecycleHooks, PluginManifest, PluginSettingField, ThemeBranding, ThemeColorToken, ThemeConfig, ThemeDefinition, ThemeManifest, ThemeRadiusToken, ThemeShadowToken, ThemeSpacingToken, ThemeTokens, ThemeTypographyToken, defineTheme } from '@notty/types';

package/dist/index.d.ts

@@ -1,7 +1 @@
-/**
- * @notty/theme-api
- * Theme SDK for ACms
- */
-declare const THEME_API_VERSION = "0.1.0";
-
-export { THEME_API_VERSION };
+export { ManifestValidationResult, PluginAuthor, PluginConfigSchema, PluginContext, PluginEngines, PluginLifecycleHooks, PluginManifest, PluginSettingField, ThemeBranding, ThemeColorToken, ThemeConfig, ThemeDefinition, ThemeManifest, ThemeRadiusToken, ThemeShadowToken, ThemeSpacingToken, ThemeTokens, ThemeTypographyToken, defineTheme } from '@notty/types';

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var THEME_API_VERSION = "0.1.0";
+import { defineTheme } from "@notty/types";
 export {
-  THEME_API_VERSION
+  defineTheme
 };

package/dist/testing/index.cjs

@@ -0,0 +1,321 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var testing_exports = {};
+__export(testing_exports, {
+  assertValidBranding: () => assertValidBranding,
+  assertValidTokens: () => assertValidTokens,
+  createTestThemeContext: () => createTestThemeContext,
+  createTestThemeHarness: () => createTestThemeHarness,
+  makeTestThemeDefinition: () => makeTestThemeDefinition,
+  makeTestThemeManifest: () => makeTestThemeManifest
+});
+module.exports = __toCommonJS(testing_exports);
+function createMockLogger() {
+  const entries = [];
+  function log(level) {
+    return (message, ...args) => {
+      entries.push({ level, message, args });
+    };
+  }
+  return {
+    info: log("info"),
+    warn: log("warn"),
+    error: log("error"),
+    debug: log("debug"),
+    get entries() {
+      return entries;
+    },
+    entriesOf: (level) => entries.filter((e) => e.level === level),
+    clear: () => {
+      entries.length = 0;
+    }
+  };
+}
+function noop() {
+}
+function createNoopRouteRegistrar() {
+  return { get: noop, post: noop, put: noop, delete: noop, patch: noop, add: noop };
+}
+function createNoopServiceRegistrar() {
+  return { register: noop, get: () => void 0, has: () => false };
+}
+function createNoopHookRegistrar() {
+  return {
+    on: noop,
+    once: noop,
+    emit: (_name, payload) => Promise.resolve(payload)
+  };
+}
+function createNoopMiddlewareRegistrar() {
+  return { addAdmin: noop, addContent: noop, addSystem: noop };
+}
+function createNoopPolicyRegistrar() {
+  return { register: noop };
+}
+function createNoopDataLayerRegistrar() {
+  return {
+    contributeContentType: noop,
+    contributeComponent: noop,
+    addMigration: noop,
+    addSeed: noop
+  };
+}
+function createCapturingAdminRegistrar() {
+  const captured = {
+    navigationItems: [],
+    pages: [],
+    settingsSections: [],
+    dashboardWidgets: [],
+    injectionZones: [],
+    fieldExtensions: []
+  };
+  return {
+    captured,
+    addNavigationItem: (item) => {
+      captured.navigationItems.push(item);
+    },
+    addPage: (page) => {
+      captured.pages.push(page);
+    },
+    addSettingsSection: (section) => {
+      captured.settingsSections.push(section);
+    },
+    addDashboardWidget: (widget) => {
+      captured.dashboardWidgets.push(widget);
+    },
+    addInjectionZoneEntry: (entry) => {
+      captured.injectionZones.push(entry);
+    },
+    addFieldExtension: (ext) => {
+      captured.fieldExtensions.push(ext);
+    }
+  };
+}
+var DEFAULT_THEME_MANIFEST = {
+  name: "@test/theme",
+  displayName: "Test Theme",
+  version: "1.0.0",
+  kind: "theme",
+  engines: { notty: ">=0.14.0" },
+  tokens: {
+    colors: {
+      brand: { primary: { value: "#3b82f6" } },
+      surface: {
+        background: { value: "#ffffff" },
+        foreground: { value: "#1a1a2e" }
+      }
+    }
+  }
+};
+function makeTestThemeManifest(overrides) {
+  return { ...DEFAULT_THEME_MANIFEST, ...overrides };
+}
+function makeTestThemeDefinition(overrides) {
+  const { manifest: manifestOverrides, ...hooks } = overrides ?? {};
+  return {
+    manifest: makeTestThemeManifest(manifestOverrides),
+    ...hooks
+  };
+}
+function createTestThemeContext(options) {
+  const manifest = makeTestThemeManifest(options?.manifest);
+  const config = options?.config ?? {};
+  const admin = createCapturingAdminRegistrar();
+  return {
+    manifest,
+    config,
+    log: createMockLogger(),
+    routes: createNoopRouteRegistrar(),
+    services: createNoopServiceRegistrar(),
+    hooks: createNoopHookRegistrar(),
+    middleware: createNoopMiddlewareRegistrar(),
+    policies: createNoopPolicyRegistrar(),
+    dataLayer: createNoopDataLayerRegistrar(),
+    admin
+  };
+}
+function createTestThemeHarness(definition, options) {
+  const mergedManifest = {
+    ...DEFAULT_THEME_MANIFEST,
+    ...definition.manifest,
+    ...options?.manifest
+  };
+  const mergedDefinition = {
+    ...definition,
+    manifest: mergedManifest
+  };
+  const s = {
+    ctx: createTestThemeContext({ manifest: mergedManifest, config: options?.config }),
+    phase: "discovered",
+    errors: []
+  };
+  function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+  }
+  function hasFailed() {
+    return s.phase === "failed";
+  }
+  function runRegister() {
+    if (s.phase !== "discovered") return;
+    try {
+      if (mergedDefinition.register) mergedDefinition.register(s.ctx);
+      s.phase = "registered";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runInit() {
+    if (s.phase === "discovered") runRegister();
+    if (s.phase !== "registered") return;
+    try {
+      if (mergedDefinition.init) await mergedDefinition.init(s.ctx);
+      s.phase = "initialized";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runBoot() {
+    if (s.phase === "discovered") runRegister();
+    if (s.phase === "registered") await runInit();
+    if (s.phase !== "initialized") return;
+    try {
+      if (mergedDefinition.boot) await mergedDefinition.boot(s.ctx);
+      s.phase = "active";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runAll() {
+    runRegister();
+    if (hasFailed()) return;
+    await runInit();
+    if (hasFailed()) return;
+    await runBoot();
+  }
+  async function runDestroy() {
+    const startPhase = s.phase;
+    try {
+      if (mergedDefinition.destroy) {
+        await mergedDefinition.destroy(s.ctx);
+      }
+      if (startPhase !== "failed") {
+        s.phase = "disabled";
+      }
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  function reset() {
+    s.ctx = createTestThemeContext({ manifest: mergedManifest, config: options?.config });
+    s.phase = "discovered";
+    s.errors = [];
+  }
+  return {
+    get ctx() {
+      return s.ctx;
+    },
+    get definition() {
+      return mergedDefinition;
+    },
+    get phase() {
+      return s.phase;
+    },
+    get errors() {
+      return s.errors;
+    },
+    runRegister,
+    runInit,
+    runBoot,
+    runDestroy,
+    runAll,
+    reset
+  };
+}
+function assertValidTokens(tokens) {
+  const issues = [];
+  if (!tokens) {
+    return { valid: true, issues: [] };
+  }
+  if (tokens.colors) {
+    for (const [group, colorGroup] of Object.entries(tokens.colors)) {
+      if (!colorGroup || typeof colorGroup !== "object") continue;
+      for (const [name, token] of Object.entries(colorGroup)) {
+        if (!token) continue;
+        if (!token.value || typeof token.value !== "string" || token.value.trim() === "") {
+          issues.push(`colors.${group}.${name}: missing or empty value`);
+        }
+      }
+    }
+  }
+  if (tokens.typography) {
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      if (!token) continue;
+      const hasAny = token.fontFamily || token.fontSize || token.fontWeight || token.lineHeight || token.letterSpacing;
+      if (!hasAny) {
+        issues.push(`typography.${name}: no properties set`);
+      }
+    }
+  }
+  const valueSections = [
+    ["spacing", tokens.spacing],
+    ["shadows", tokens.shadows],
+    ["radii", tokens.radii]
+  ];
+  for (const [section, sectionTokens] of valueSections) {
+    if (!sectionTokens) continue;
+    for (const [name, token] of Object.entries(sectionTokens)) {
+      if (!token) continue;
+      if (!token.value || typeof token.value !== "string" || token.value.trim() === "") {
+        issues.push(`${section}.${name}: missing or empty value`);
+      }
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+function assertValidBranding(branding) {
+  const issues = [];
+  if (!branding) {
+    return { valid: true, issues: [] };
+  }
+  if (branding.logo && typeof branding.logo !== "string") {
+    issues.push("branding.logo: must be a string URL/path");
+  }
+  if (branding.favicon && typeof branding.favicon !== "string") {
+    issues.push("branding.favicon: must be a string URL/path");
+  }
+  if (branding.title && typeof branding.title !== "string") {
+    issues.push("branding.title: must be a string");
+  }
+  return { valid: issues.length === 0, issues };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertValidBranding,
+  assertValidTokens,
+  createTestThemeContext,
+  createTestThemeHarness,
+  makeTestThemeDefinition,
+  makeTestThemeManifest
+});

package/dist/testing/index.d.cts

@@ -0,0 +1,150 @@
+import { AdminNavigationItem, AdminPage, AdminSettingsSection, AdminDashboardWidget, AdminInjectionZoneEntry, AdminFieldExtension, PluginContext, ThemeManifest, ThemeDefinition, PluginLifecyclePhase, ThemeTokens, ThemeBranding } from '@notty/types';
+
+/**
+ * @notty/theme-api/testing
+ *
+ * Test utilities for Notty theme authors.
+ *
+ * Re-exports core plugin testing utilities from @notty/plugin-api/testing
+ * plus theme-specific helpers for design tokens and branding.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createTestThemeContext,
+ *   createTestThemeHarness,
+ *   makeTestThemeManifest,
+ *   assertValidTokens,
+ * } from '@notty/theme-api/testing';
+ * ```
+ */
+
+interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    message: string;
+    args: unknown[];
+}
+interface MockLogger {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+    readonly entries: ReadonlyArray<LogEntry>;
+    entriesOf(level: LogEntry['level']): LogEntry[];
+    clear(): void;
+}
+/** Captured admin extensions for theme testing */
+interface CapturedAdminExtensions {
+    navigationItems: AdminNavigationItem[];
+    pages: AdminPage[];
+    settingsSections: AdminSettingsSection[];
+    dashboardWidgets: AdminDashboardWidget[];
+    injectionZones: AdminInjectionZoneEntry[];
+    fieldExtensions: AdminFieldExtension[];
+}
+interface TestThemeContext extends PluginContext {
+    log: MockLogger;
+    admin: PluginContext['admin'] & {
+        captured: CapturedAdminExtensions;
+    };
+}
+interface CreateTestThemeContextOptions {
+    manifest?: Partial<ThemeManifest>;
+    config?: Record<string, unknown>;
+}
+/**
+ * Create a valid ThemeManifest with sensible defaults including design tokens.
+ */
+declare function makeTestThemeManifest(overrides?: Partial<ThemeManifest>): ThemeManifest;
+/**
+ * Create a valid ThemeDefinition with sensible defaults.
+ */
+declare function makeTestThemeDefinition(overrides?: Partial<ThemeDefinition> & {
+    manifest?: Partial<ThemeManifest>;
+}): ThemeDefinition;
+/**
+ * Create a mock PluginContext tailored for theme testing.
+ *
+ * Backend registrars (routes, services, hooks, etc.) are no-op stubs.
+ * The admin registrar captures calls so you can verify theme admin extensions.
+ * The logger captures entries for inspection.
+ *
+ * @example
+ * ```ts
+ * import { createTestThemeContext } from '@notty/theme-api/testing';
+ *
+ * test('theme registers settings section', () => {
+ *   const ctx = createTestThemeContext({ manifest: { name: '@my/dark-theme' } });
+ *
+ *   myTheme.register(ctx);
+ *
+ *   expect(ctx.admin.captured.settingsSections).toHaveLength(1);
+ * });
+ * ```
+ */
+declare function createTestThemeContext(options?: CreateTestThemeContextOptions): TestThemeContext;
+interface ThemeTestHarness {
+    readonly ctx: TestThemeContext;
+    readonly definition: ThemeDefinition;
+    readonly phase: PluginLifecyclePhase;
+    readonly errors: ReadonlyArray<Error>;
+    /** Run register phase */
+    runRegister(): void;
+    /** Run init phase (auto-registers if needed) */
+    runInit(): Promise<void>;
+    /** Run boot phase (auto-registers and inits if needed) */
+    runBoot(): Promise<void>;
+    /** Run destroy phase from any current phase */
+    runDestroy(): Promise<void>;
+    /** Run all phases */
+    runAll(): Promise<void>;
+    /** Reset to initial state */
+    reset(): void;
+}
+/**
+ * Create a test harness for a theme definition.
+ *
+ * @example
+ * ```ts
+ * import { createTestThemeHarness } from '@notty/theme-api/testing';
+ * import myTheme from '../src/index';
+ *
+ * test('theme lifecycle completes', async () => {
+ *   const harness = createTestThemeHarness(myTheme);
+ *   await harness.runAll();
+ *   expect(harness.phase).toBe('active');
+ * });
+ * ```
+ */
+declare function createTestThemeHarness(definition: ThemeDefinition, options?: CreateTestThemeContextOptions): ThemeTestHarness;
+interface TokenValidationResult {
+    valid: boolean;
+    issues: string[];
+}
+/**
+ * Validate that theme tokens follow expected structure.
+ *
+ * Checks:
+ * - Color tokens have non-empty `value` strings
+ * - Typography tokens have at least one property set
+ * - Spacing/shadow/radius tokens have non-empty `value` strings
+ *
+ * @example
+ * ```ts
+ * const result = assertValidTokens(myTheme.manifest.tokens);
+ * expect(result.valid).toBe(true);
+ * ```
+ */
+declare function assertValidTokens(tokens?: ThemeTokens): TokenValidationResult;
+/**
+ * Validate that theme branding has required fields set.
+ *
+ * @example
+ * ```ts
+ * const result = assertValidBranding(myTheme.manifest.branding);
+ * expect(result.valid).toBe(true);
+ * ```
+ */
+declare function assertValidBranding(branding?: ThemeBranding): TokenValidationResult;
+
+export { type CapturedAdminExtensions, type CreateTestThemeContextOptions, type LogEntry, type MockLogger, type TestThemeContext, type ThemeTestHarness, type TokenValidationResult, assertValidBranding, assertValidTokens, createTestThemeContext, createTestThemeHarness, makeTestThemeDefinition, makeTestThemeManifest };

package/dist/testing/index.d.ts

@@ -0,0 +1,150 @@
+import { AdminNavigationItem, AdminPage, AdminSettingsSection, AdminDashboardWidget, AdminInjectionZoneEntry, AdminFieldExtension, PluginContext, ThemeManifest, ThemeDefinition, PluginLifecyclePhase, ThemeTokens, ThemeBranding } from '@notty/types';
+
+/**
+ * @notty/theme-api/testing
+ *
+ * Test utilities for Notty theme authors.
+ *
+ * Re-exports core plugin testing utilities from @notty/plugin-api/testing
+ * plus theme-specific helpers for design tokens and branding.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createTestThemeContext,
+ *   createTestThemeHarness,
+ *   makeTestThemeManifest,
+ *   assertValidTokens,
+ * } from '@notty/theme-api/testing';
+ * ```
+ */
+
+interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    message: string;
+    args: unknown[];
+}
+interface MockLogger {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+    readonly entries: ReadonlyArray<LogEntry>;
+    entriesOf(level: LogEntry['level']): LogEntry[];
+    clear(): void;
+}
+/** Captured admin extensions for theme testing */
+interface CapturedAdminExtensions {
+    navigationItems: AdminNavigationItem[];
+    pages: AdminPage[];
+    settingsSections: AdminSettingsSection[];
+    dashboardWidgets: AdminDashboardWidget[];
+    injectionZones: AdminInjectionZoneEntry[];
+    fieldExtensions: AdminFieldExtension[];
+}
+interface TestThemeContext extends PluginContext {
+    log: MockLogger;
+    admin: PluginContext['admin'] & {
+        captured: CapturedAdminExtensions;
+    };
+}
+interface CreateTestThemeContextOptions {
+    manifest?: Partial<ThemeManifest>;
+    config?: Record<string, unknown>;
+}
+/**
+ * Create a valid ThemeManifest with sensible defaults including design tokens.
+ */
+declare function makeTestThemeManifest(overrides?: Partial<ThemeManifest>): ThemeManifest;
+/**
+ * Create a valid ThemeDefinition with sensible defaults.
+ */
+declare function makeTestThemeDefinition(overrides?: Partial<ThemeDefinition> & {
+    manifest?: Partial<ThemeManifest>;
+}): ThemeDefinition;
+/**
+ * Create a mock PluginContext tailored for theme testing.
+ *
+ * Backend registrars (routes, services, hooks, etc.) are no-op stubs.
+ * The admin registrar captures calls so you can verify theme admin extensions.
+ * The logger captures entries for inspection.
+ *
+ * @example
+ * ```ts
+ * import { createTestThemeContext } from '@notty/theme-api/testing';
+ *
+ * test('theme registers settings section', () => {
+ *   const ctx = createTestThemeContext({ manifest: { name: '@my/dark-theme' } });
+ *
+ *   myTheme.register(ctx);
+ *
+ *   expect(ctx.admin.captured.settingsSections).toHaveLength(1);
+ * });
+ * ```
+ */
+declare function createTestThemeContext(options?: CreateTestThemeContextOptions): TestThemeContext;
+interface ThemeTestHarness {
+    readonly ctx: TestThemeContext;
+    readonly definition: ThemeDefinition;
+    readonly phase: PluginLifecyclePhase;
+    readonly errors: ReadonlyArray<Error>;
+    /** Run register phase */
+    runRegister(): void;
+    /** Run init phase (auto-registers if needed) */
+    runInit(): Promise<void>;
+    /** Run boot phase (auto-registers and inits if needed) */
+    runBoot(): Promise<void>;
+    /** Run destroy phase from any current phase */
+    runDestroy(): Promise<void>;
+    /** Run all phases */
+    runAll(): Promise<void>;
+    /** Reset to initial state */
+    reset(): void;
+}
+/**
+ * Create a test harness for a theme definition.
+ *
+ * @example
+ * ```ts
+ * import { createTestThemeHarness } from '@notty/theme-api/testing';
+ * import myTheme from '../src/index';
+ *
+ * test('theme lifecycle completes', async () => {
+ *   const harness = createTestThemeHarness(myTheme);
+ *   await harness.runAll();
+ *   expect(harness.phase).toBe('active');
+ * });
+ * ```
+ */
+declare function createTestThemeHarness(definition: ThemeDefinition, options?: CreateTestThemeContextOptions): ThemeTestHarness;
+interface TokenValidationResult {
+    valid: boolean;
+    issues: string[];
+}
+/**
+ * Validate that theme tokens follow expected structure.
+ *
+ * Checks:
+ * - Color tokens have non-empty `value` strings
+ * - Typography tokens have at least one property set
+ * - Spacing/shadow/radius tokens have non-empty `value` strings
+ *
+ * @example
+ * ```ts
+ * const result = assertValidTokens(myTheme.manifest.tokens);
+ * expect(result.valid).toBe(true);
+ * ```
+ */
+declare function assertValidTokens(tokens?: ThemeTokens): TokenValidationResult;
+/**
+ * Validate that theme branding has required fields set.
+ *
+ * @example
+ * ```ts
+ * const result = assertValidBranding(myTheme.manifest.branding);
+ * expect(result.valid).toBe(true);
+ * ```
+ */
+declare function assertValidBranding(branding?: ThemeBranding): TokenValidationResult;
+
+export { type CapturedAdminExtensions, type CreateTestThemeContextOptions, type LogEntry, type MockLogger, type TestThemeContext, type ThemeTestHarness, type TokenValidationResult, assertValidBranding, assertValidTokens, createTestThemeContext, createTestThemeHarness, makeTestThemeDefinition, makeTestThemeManifest };

package/dist/testing/index.js

@@ -0,0 +1,291 @@
+// src/testing/index.ts
+function createMockLogger() {
+  const entries = [];
+  function log(level) {
+    return (message, ...args) => {
+      entries.push({ level, message, args });
+    };
+  }
+  return {
+    info: log("info"),
+    warn: log("warn"),
+    error: log("error"),
+    debug: log("debug"),
+    get entries() {
+      return entries;
+    },
+    entriesOf: (level) => entries.filter((e) => e.level === level),
+    clear: () => {
+      entries.length = 0;
+    }
+  };
+}
+function noop() {
+}
+function createNoopRouteRegistrar() {
+  return { get: noop, post: noop, put: noop, delete: noop, patch: noop, add: noop };
+}
+function createNoopServiceRegistrar() {
+  return { register: noop, get: () => void 0, has: () => false };
+}
+function createNoopHookRegistrar() {
+  return {
+    on: noop,
+    once: noop,
+    emit: (_name, payload) => Promise.resolve(payload)
+  };
+}
+function createNoopMiddlewareRegistrar() {
+  return { addAdmin: noop, addContent: noop, addSystem: noop };
+}
+function createNoopPolicyRegistrar() {
+  return { register: noop };
+}
+function createNoopDataLayerRegistrar() {
+  return {
+    contributeContentType: noop,
+    contributeComponent: noop,
+    addMigration: noop,
+    addSeed: noop
+  };
+}
+function createCapturingAdminRegistrar() {
+  const captured = {
+    navigationItems: [],
+    pages: [],
+    settingsSections: [],
+    dashboardWidgets: [],
+    injectionZones: [],
+    fieldExtensions: []
+  };
+  return {
+    captured,
+    addNavigationItem: (item) => {
+      captured.navigationItems.push(item);
+    },
+    addPage: (page) => {
+      captured.pages.push(page);
+    },
+    addSettingsSection: (section) => {
+      captured.settingsSections.push(section);
+    },
+    addDashboardWidget: (widget) => {
+      captured.dashboardWidgets.push(widget);
+    },
+    addInjectionZoneEntry: (entry) => {
+      captured.injectionZones.push(entry);
+    },
+    addFieldExtension: (ext) => {
+      captured.fieldExtensions.push(ext);
+    }
+  };
+}
+var DEFAULT_THEME_MANIFEST = {
+  name: "@test/theme",
+  displayName: "Test Theme",
+  version: "1.0.0",
+  kind: "theme",
+  engines: { notty: ">=0.14.0" },
+  tokens: {
+    colors: {
+      brand: { primary: { value: "#3b82f6" } },
+      surface: {
+        background: { value: "#ffffff" },
+        foreground: { value: "#1a1a2e" }
+      }
+    }
+  }
+};
+function makeTestThemeManifest(overrides) {
+  return { ...DEFAULT_THEME_MANIFEST, ...overrides };
+}
+function makeTestThemeDefinition(overrides) {
+  const { manifest: manifestOverrides, ...hooks } = overrides ?? {};
+  return {
+    manifest: makeTestThemeManifest(manifestOverrides),
+    ...hooks
+  };
+}
+function createTestThemeContext(options) {
+  const manifest = makeTestThemeManifest(options?.manifest);
+  const config = options?.config ?? {};
+  const admin = createCapturingAdminRegistrar();
+  return {
+    manifest,
+    config,
+    log: createMockLogger(),
+    routes: createNoopRouteRegistrar(),
+    services: createNoopServiceRegistrar(),
+    hooks: createNoopHookRegistrar(),
+    middleware: createNoopMiddlewareRegistrar(),
+    policies: createNoopPolicyRegistrar(),
+    dataLayer: createNoopDataLayerRegistrar(),
+    admin
+  };
+}
+function createTestThemeHarness(definition, options) {
+  const mergedManifest = {
+    ...DEFAULT_THEME_MANIFEST,
+    ...definition.manifest,
+    ...options?.manifest
+  };
+  const mergedDefinition = {
+    ...definition,
+    manifest: mergedManifest
+  };
+  const s = {
+    ctx: createTestThemeContext({ manifest: mergedManifest, config: options?.config }),
+    phase: "discovered",
+    errors: []
+  };
+  function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+  }
+  function hasFailed() {
+    return s.phase === "failed";
+  }
+  function runRegister() {
+    if (s.phase !== "discovered") return;
+    try {
+      if (mergedDefinition.register) mergedDefinition.register(s.ctx);
+      s.phase = "registered";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runInit() {
+    if (s.phase === "discovered") runRegister();
+    if (s.phase !== "registered") return;
+    try {
+      if (mergedDefinition.init) await mergedDefinition.init(s.ctx);
+      s.phase = "initialized";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runBoot() {
+    if (s.phase === "discovered") runRegister();
+    if (s.phase === "registered") await runInit();
+    if (s.phase !== "initialized") return;
+    try {
+      if (mergedDefinition.boot) await mergedDefinition.boot(s.ctx);
+      s.phase = "active";
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  async function runAll() {
+    runRegister();
+    if (hasFailed()) return;
+    await runInit();
+    if (hasFailed()) return;
+    await runBoot();
+  }
+  async function runDestroy() {
+    const startPhase = s.phase;
+    try {
+      if (mergedDefinition.destroy) {
+        await mergedDefinition.destroy(s.ctx);
+      }
+      if (startPhase !== "failed") {
+        s.phase = "disabled";
+      }
+    } catch (err) {
+      s.phase = "failed";
+      s.errors.push(toError(err));
+    }
+  }
+  function reset() {
+    s.ctx = createTestThemeContext({ manifest: mergedManifest, config: options?.config });
+    s.phase = "discovered";
+    s.errors = [];
+  }
+  return {
+    get ctx() {
+      return s.ctx;
+    },
+    get definition() {
+      return mergedDefinition;
+    },
+    get phase() {
+      return s.phase;
+    },
+    get errors() {
+      return s.errors;
+    },
+    runRegister,
+    runInit,
+    runBoot,
+    runDestroy,
+    runAll,
+    reset
+  };
+}
+function assertValidTokens(tokens) {
+  const issues = [];
+  if (!tokens) {
+    return { valid: true, issues: [] };
+  }
+  if (tokens.colors) {
+    for (const [group, colorGroup] of Object.entries(tokens.colors)) {
+      if (!colorGroup || typeof colorGroup !== "object") continue;
+      for (const [name, token] of Object.entries(colorGroup)) {
+        if (!token) continue;
+        if (!token.value || typeof token.value !== "string" || token.value.trim() === "") {
+          issues.push(`colors.${group}.${name}: missing or empty value`);
+        }
+      }
+    }
+  }
+  if (tokens.typography) {
+    for (const [name, token] of Object.entries(tokens.typography)) {
+      if (!token) continue;
+      const hasAny = token.fontFamily || token.fontSize || token.fontWeight || token.lineHeight || token.letterSpacing;
+      if (!hasAny) {
+        issues.push(`typography.${name}: no properties set`);
+      }
+    }
+  }
+  const valueSections = [
+    ["spacing", tokens.spacing],
+    ["shadows", tokens.shadows],
+    ["radii", tokens.radii]
+  ];
+  for (const [section, sectionTokens] of valueSections) {
+    if (!sectionTokens) continue;
+    for (const [name, token] of Object.entries(sectionTokens)) {
+      if (!token) continue;
+      if (!token.value || typeof token.value !== "string" || token.value.trim() === "") {
+        issues.push(`${section}.${name}: missing or empty value`);
+      }
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+function assertValidBranding(branding) {
+  const issues = [];
+  if (!branding) {
+    return { valid: true, issues: [] };
+  }
+  if (branding.logo && typeof branding.logo !== "string") {
+    issues.push("branding.logo: must be a string URL/path");
+  }
+  if (branding.favicon && typeof branding.favicon !== "string") {
+    issues.push("branding.favicon: must be a string URL/path");
+  }
+  if (branding.title && typeof branding.title !== "string") {
+    issues.push("branding.title: must be a string");
+  }
+  return { valid: issues.length === 0, issues };
+}
+export {
+  assertValidBranding,
+  assertValidTokens,
+  createTestThemeContext,
+  createTestThemeHarness,
+  makeTestThemeDefinition,
+  makeTestThemeManifest
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@notty/theme-api",
-  "version": "0.7.1",
-  "description": "Notty Theme SDK for building themes",
+  "version": "1.0.0",
+  "description": "Theme API and testing toolkit for Notty CMS themes",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -11,27 +11,33 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "require": "./dist/testing/index.cjs"
     }
   },
   "files": [
     "dist"
   ],
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/testing/index.ts --format cjs,esm --dts",
+    "build:libs": "tsup src/index.ts src/testing/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/testing/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@notty/types": "0.7.1"
+    "@notty/types": "1.0.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",
     "typescript": "^5.6.3"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "build:libs": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "eslint src",
-    "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
 }