@hydraharness/harness-client-ui-theme 0.0.0-stage → 0.1.1-rc.7

package/lib/index.js

@@ -0,0 +1,79 @@
+import { settingsNamespace } from "@hydraharness/harness-settings";
+import z from "@hydraharness/schemastery";
+//#region lib/types/theme-settings.js
+/** Theme preferences stored in the Host user-settings document. */
+/** Built-in preferences accepted at the registry and settings boundaries. */
+const THEME_PREFERENCES = [
+	"light",
+	"dark",
+	"system"
+];
+/** Settings namespace owned by the theme plugin. */
+const THEME_SETTINGS_NAMESPACE = "ui-theme";
+/** Field carrying the selected built-in theme preference. */
+const THEME_PREFERENCE_FIELD = "preference";
+/** Default preference when the user-settings document has no override. */
+const DEFAULT_PREFERENCE = "system";
+/** Durable theme schema; also the wire envelope the browser scope validates against. */
+const ThemeSettingsSchema = z.object({ [THEME_PREFERENCE_FIELD]: z.union([...THEME_PREFERENCES]).default(DEFAULT_PREFERENCE) });
+//#endregion
+//#region lib/types/boot-theme.js
+/**
+* Theme bootstrap row for the browser's pre-plugin interval. Each index
+* render embeds the current durable built-in preference; the browser resolves
+* only `system`, then writes the same DOM fields ui-layout's ThemePresenter
+* owns after the client plugin tree activates.
+*/
+/** Build the inline script body for one schema-validated built-in preference. */
+function bootThemeScript(preference) {
+	return `(() => {
+  const preference = ${JSON.stringify(preference)}
+  const systemDark = preference === 'system'
+    && typeof matchMedia !== 'undefined'
+    && matchMedia('(prefers-color-scheme: dark)').matches
+  const dark = preference === 'dark' || systemDark
+  document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+  document.body.toggleAttribute('data-ds-dark-theme', dark)
+})()`;
+}
+/**
+* The theme bootstrap as an injection row: an inline script immediately after
+* the opening body tag, before the shell mount and module script.
+* @param preference - Current Host-backed built-in preference.
+* @returns the body script row.
+*/
+function bootThemeInjection(preference = DEFAULT_PREFERENCE) {
+	return {
+		kind: "script",
+		placement: "body",
+		text: bootThemeScript(preference)
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Host registration for the browser theme preference and pre-plugin palette. */
+const THEME_NAMESPACE = settingsNamespace(THEME_SETTINGS_NAMESPACE);
+/** Read the registered preference or use the schema default without a settings provider. */
+function readPreference(ctx) {
+	const settings = ctx.get("settings");
+	if (settings === void 0) return DEFAULT_PREFERENCE;
+	const section = settings.get(THEME_NAMESPACE);
+	if (section === void 0) return DEFAULT_PREFERENCE;
+	return section.preference;
+}
+/**
+* Register the durable theme section when the optional settings service is
+* composed, and answer every index injection collection with the current
+* theme bootstrap row.
+* @param ctx - Host context that may acquire the settings service.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(THEME_NAMESPACE, ThemeSettingsSchema);
+	});
+	ctx.on("webserver/index-inject", (table) => {
+		table.push(bootThemeInjection(readPreference(ctx)));
+	});
+}
+//#endregion
+export { DEFAULT_PREFERENCE, THEME_PREFERENCES, THEME_PREFERENCE_FIELD, THEME_SETTINGS_NAMESPACE, apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-client-ui-theme`.
+* @module @hydraharness/harness-client-ui-theme/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-client-ui-theme";
+/** Cordis companion plugin name. */
+const name = "client-ui-theme-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the settings scope validates and publishes the durable
+* theme section, while the registry emits `theme/change` synchronously with
+* its own mutations. Store/registry agreement is covered directly by this
+* package's Host, scope, and service behavior specs.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/boot-theme.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Theme bootstrap row for the browser's pre-plugin interval. Each index
+ * render embeds the current durable built-in preference; the browser resolves
+ * only `system`, then writes the same DOM fields ui-layout's ThemePresenter
+ * owns after the client plugin tree activates.
+ */
+import type { IndexInjection } from '@hydraharness/harness-host-webserver';
+import { type ThemePreference } from './theme-settings.ts';
+/**
+ * The theme bootstrap as an injection row: an inline script immediately after
+ * the opening body tag, before the shell mount and module script.
+ * @param preference - Current Host-backed built-in preference.
+ * @returns the body script row.
+ */
+export declare function bootThemeInjection(preference?: ThemePreference): IndexInjection;
+//# sourceMappingURL=boot-theme.d.ts.map

package/lib/types/client/AppearanceRow.d.ts

@@ -0,0 +1,17 @@
+import type { PropsLocale, PropsRuntime, PropsStore } from '@hydraharness/harness-client-ui-slots';
+import type { ThemePreference } from '../theme-settings.ts';
+import type { createAppearanceRowStore } from './settings-store.ts';
+/** Injected business face: the preference write (t rides the standard locale seat). */
+export interface AppearanceRowInjected {
+    /** Switch the theme preference. */
+    setTheme: (id: ThemePreference) => void;
+}
+/** Full component props: runtime share + store share + locale seat + injected face. */
+export type AppearanceRowComponentProps = PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createAppearanceRowStore>> & PropsLocale<'settings.theme'> & AppearanceRowInjected;
+/**
+ * Render the Appearance row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function AppearanceRow({ t, setTheme, useStore }: AppearanceRowComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=AppearanceRow.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Browser theme registry over the `--dsw-*` token stylesheets. The service
+ * owns the live theme preference (light/dark/system), resolves `system` through
+ * `prefers-color-scheme`, and publishes immutable snapshots; it never touches
+ * the DOM — ui-layout's presenter consumes the resolved snapshot. The Host
+ * settings scope loads and stores the preference in the user-settings
+ * document. The plugin also registers the Appearance preference row into the
+ * settings General section — the theme feature owns its own settings surface.
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { ClientContext, SettingsScope } from '@hydraharness/harness-client-runtime/client';
+import { type ThemeKey } from './locales.ts';
+import { type ThemePreference, type ThemeSettings } from '../theme-settings.ts';
+export type { AppearanceRowComponentProps, AppearanceRowInjected } from './AppearanceRow.tsx';
+export type { AppearanceRowState } from './settings-store.ts';
+export type { ThemeKey } from './locales.ts';
+export type { ThemePreference, ThemeSettings } from '../theme-settings.ts';
+/** Namespace owning this feature's settings-row copy. */
+export declare const SETTINGS_NS = "settings.theme";
+declare module '@hydraharness/harness-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The Appearance settings row's copy. */
+        'settings.theme': ThemeKey;
+    }
+}
+/** Theme token dictionary: --dsw-alias-* overrides keyed by variable name. */
+export type ThemeTokens = Record<string, string>;
+/**
+ * One override-layer token value: both palette modes are mandatory (repeat
+ * the same value when the token is scheme-invariant) so an override never
+ * goes illegible when the user switches to the other scheme.
+ */
+export interface ThemeTokenModes {
+    /** Value applied while the light base palette is active. */
+    light: string;
+    /** Value applied while the dark base palette is active. */
+    dark: string;
+}
+/** Override-layer dictionary: token names to per-mode value pairs. */
+export type ThemeTokenOverrides = Record<string, ThemeTokenModes>;
+/** One selectable theme: id, dark/light semantics, and alias-token overrides. */
+export interface ThemeDefinition {
+    /** Theme id (the setTheme argument for concrete themes). */
+    id: string;
+    /**
+     * Which base palette this theme builds on. The presenter switches
+     * `body[data-ds-dark-theme]` from this field — never from the id.
+     */
+    colorScheme: 'light' | 'dark';
+    /** Alias-layer overrides applied as inline CSS variables over the base palette. */
+    tokens: ThemeTokens;
+}
+/** Immutable theme state published on every change. */
+export interface ThemeSnapshot {
+    /** The persisted preference (may be `system`). */
+    preference: ThemePreference;
+    /**
+     * The resolved active theme (`system` resolved via prefers-color-scheme)
+     * with override layers folded into its tokens (seq order, later layers win
+     * per-token; each value picked for the active color scheme).
+     */
+    active: ThemeDefinition;
+    /** Registered themes in registration order. */
+    themes: readonly ThemeDefinition[];
+    /** Monotonic change counter (registry or active changes). */
+    revision: number;
+}
+/** One theme token exposed to pre-definition Cordis inspection. */
+export interface ThemeTokenInspection {
+    /** Token name accepted by {@link ThemeService.overrideTokens}. */
+    name: string;
+    /** Intended visual role. */
+    description: string;
+    /** CSS value category. */
+    valueType: string;
+    /** Whether override layers must supply both palette modes. */
+    requiresLightAndDark: boolean;
+    /** CSS custom property consumed by UI styles. */
+    cssVariable?: string;
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        theme: ThemeRuntime;
+    }
+    interface Events {
+        /**
+         * Theme state changed (preference switched, registry updated, or the OS
+         * color scheme changed while the preference is `system`).
+         * @param snapshot - Current immutable theme snapshot.
+         * @mode emit
+         */
+        'theme/change'(snapshot: ThemeSnapshot): void;
+    }
+}
+/**
+ * Theme registry and preference owner. `light`/`dark` are built in (the base
+ * stylesheets carry both palettes); third-party themes register alias-layer
+ * overrides. Reads go through {@link getTheme}; preference writes only
+ * through {@link setTheme}; continuous sync only through the `theme/change`
+ * event. {@link overrideTokens} stacks partial token layers over the active
+ * theme without touching the registry.
+ * The service holds the `prefers-color-scheme` media query (environment
+ * sensing, not presentation) and re-emits when the OS scheme flips while the
+ * preference is `system`.
+ */
+export declare class ThemeRuntime {
+    private readonly ctx;
+    private readonly host;
+    private themes;
+    private preference;
+    private revision;
+    private snapshot;
+    private readonly media;
+    /** Override layers by source; seq (monotonic) is the stacking order. */
+    private readonly overrides;
+    private overrideSeq;
+    /**
+     * @param ctx - owning context (change events are emitted on it; the
+     * media-query and scope listeners are released through ctx.effect on dispose).
+     * @param host - durable preference scope owned by the same plugin.
+     */
+    constructor(ctx: Context, host: SettingsScope<ThemeSettings>);
+    /**
+     * Read the current immutable theme snapshot.
+     * @returns the current snapshot (stable reference until the next change).
+     */
+    getTheme(): ThemeSnapshot;
+    /**
+     * Export the current token directory without reading DOM or computed styles.
+     * @returns stable JSON-safe token descriptions, including registered and override-only names.
+     */
+    exportInspectTokens(): ThemeTokenInspection[];
+    /**
+     * Switch the theme preference — the only user preference write entry.
+     * Built-in preferences are written through the settings scope and every
+     * accepted value emits `theme/change`.
+     * @param id - a registered theme id or `system`; unknown ids throw.
+     */
+    setTheme(id: string): void;
+    /** Adopt the scope's accepted durable preference without writing it back. */
+    private adopt;
+    /**
+     * Register a theme. Duplicate id throws (single occupant per id; the
+     * built-in pair counts; `system` is a preference, not a registrable id).
+     * @param definition - theme id, colorScheme, and alias-token overrides.
+     * @returns disposer. Disposing the theme backing the active preference
+     * resets the preference to the default so the UI never keeps tokens of an
+     * unregistered theme.
+     */
+    register(definition: ThemeDefinition): () => void;
+    /**
+     * Stack a token override layer on top of the active theme — the token-level
+     * analogue of slot shading: the base theme stays untouched, layers compose
+     * in seq order with later layers winning per-token, and removing a layer
+     * restores whatever it covered. Calling again with the same source replaces
+     * that source's whole layer and restacks it on top (effect re-registration
+     * semantics). Emits `theme/change` with the recomposed snapshot.
+     * @param source - layer identity; one layer per source (dynamic packages
+     * pass their package id — the façade pins it, so it also names the layer's
+     * origin for inspection).
+     * @param tokens - token-name → `{ light, dark }` value pairs. Validated at
+     * runtime (model-authored callers reach this boundary with untyped JS);
+     * a bare string value throws a teaching error.
+     * @returns disposer removing exactly the layer this call created; a no-op
+     * once the source has re-overridden (the newer layer is not torn down).
+     */
+    overrideTokens(source: string, tokens: ThemeTokenOverrides): () => void;
+    private buildSnapshot;
+    /**
+     * Fold the override layers into the active definition: seq order, later
+     * layers win per-token, each value picked for the active color scheme (the
+     * presenter consumes the composed snapshot and needs no override awareness).
+     * Without layers the registered definition passes through by identity.
+     */
+    private composeActive;
+    private publish;
+}
+/**
+ * Required services: settings transport plus slots/locale for the Appearance
+ * row. `remote` carries the forwarded settings invalidation that
+ * `ctx.settingsScope.bind(spec)` subscribes to on this context.
+ */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide the theme service and register the
+ * feature-owned Appearance preference row into the General section's item
+ * slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,11 @@
+/** `settings.theme` namespace dictionaries (the Appearance row's copy). */
+/** English dictionary (the key-set source of truth). */
+export declare const en: {
+    'appearance.title': string;
+    'appearance.light': string;
+    'appearance.dark': string;
+    'appearance.system': string;
+};
+/** The settings.theme namespace key union. */
+export type ThemeKey = keyof typeof en;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/settings-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Appearance row slot store: a mirror of the theme service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { type EngineStoreHandle } from '@hydraharness/harness-client-runtime/client';
+import type { ThemePreference } from '../theme-settings.ts';
+/** Store state mirrored from the theme snapshot. */
+export interface AppearanceRowState {
+    /** Persisted preference (selection state reads this, never the resolved active theme). */
+    preference: ThemePreference;
+    /** Service revision; -1 until first sync so revision 0 lands as a change. */
+    revision: number;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+type AppearanceRowActions = {
+    sync: (draft: AppearanceRowState, preference: ThemePreference, revision: number) => void;
+};
+/**
+ * Declares the Appearance row state and write surface.
+ * @returns the store handle.
+ */
+export declare function createAppearanceRowStore(): EngineStoreHandle<AppearanceRowState, AppearanceRowActions>;
+export {};
+//# sourceMappingURL=settings-store.d.ts.map

package/lib/types/client/styles.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from '@hydraharness/cordis';
+/**
+ * Mount the global theme sheets for exactly the owning plugin lifetime.
+ * @param ctx - Owning plugin context.
+ */
+export declare function installThemeStyles(ctx: Context): void;
+//# sourceMappingURL=styles.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/** Host registration for the browser theme preference and pre-plugin palette. */
+import type { Context } from '@hydraharness/cordis';
+export { DEFAULT_PREFERENCE, THEME_PREFERENCE_FIELD, THEME_PREFERENCES, THEME_SETTINGS_NAMESPACE, type ThemePreference, type ThemeSettings, } from './theme-settings.ts';
+/**
+ * Register the durable theme section when the optional settings service is
+ * composed, and answer every index injection collection with the current
+ * theme bootstrap row.
+ * @param ctx - Host context that may acquire the settings service.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-client-ui-theme`.
+ * @module @hydraharness/harness-client-ui-theme/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-theme-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/theme-settings.d.ts

@@ -0,0 +1,26 @@
+/** Theme preferences stored in the Host user-settings document. */
+import z from '@hydraharness/schemastery';
+/** Built-in preferences accepted at the registry and settings boundaries. */
+export declare const THEME_PREFERENCES: readonly ["light", "dark", "system"];
+/** Settings namespace owned by the theme plugin. */
+export declare const THEME_SETTINGS_NAMESPACE = "ui-theme";
+/** Field carrying the selected built-in theme preference. */
+export declare const THEME_PREFERENCE_FIELD = "preference";
+/** Theme preference persisted by the product Appearance row. */
+export type ThemePreference = typeof THEME_PREFERENCES[number];
+/** Default preference when the user-settings document has no override. */
+export declare const DEFAULT_PREFERENCE: ThemePreference;
+/** Durable theme section shared by the Host schema and the browser scope. */
+export interface ThemeSettings {
+    /** Selected built-in preference. */
+    preference: ThemePreference;
+}
+/** Durable theme schema; also the wire envelope the browser scope validates against. */
+export declare const ThemeSettingsSchema: z<ThemeSettings>;
+/**
+ * Narrow one wire or registry value to a persistable preference.
+ * @param value - value crossing the settings or registry boundary.
+ * @returns whether the value is a built-in preference.
+ */
+export declare function isThemePreference(value: unknown): value is ThemePreference;
+//# sourceMappingURL=theme-settings.d.ts.map

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@hydraharness/harness-client-ui-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Theme plugin: Host bootstrap for the pre-plugin palette; DOM-free ThemeRuntime for light/dark/system state; --dsw-* token styles and Appearance settings row",
+  "version": "0.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/client/ui-theme"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "hydra": {
+    "plugin": {
+      "application": "Choose light, dark, or system appearance and apply a consistent palette throughout the app."
+    },
+    "client": {
+      "inject": [
+        "@hydraharness/harness-client-connection",
+        "@hydraharness/harness-client-runtime",
+        "@hydraharness/harness-client-locale",
+        "@hydraharness/harness-client-ui-settings",
+        "@hydraharness/harness-api-remotes"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-client-connection": "^0.1.1-rc.7",
+    "@hydraharness/harness-api-remotes": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-locale": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-runtime": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-ui-settings": "^0.1.1-rc.7",
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-settings": "^0.1.1-rc.7"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@hydraharness/harness-api-remotes": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-client-connection": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-locale": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-runtime": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-ui-primitives": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-ui-settings": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-test-runtime": "^0.1.1-rc.7",
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.7",
+    "@hydraharness/harness-client-ui-slots": "^0.1.1-rc.7",
+    "@hydraharness/harness-settings": "^0.1.1-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/styles",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }