npm - @evolution-james/evolution-theme-engine - Versions diffs - 1.0.0 - Mend

@evolution-james/evolution-theme-engine 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/LICENSE.txt +13 -0
package/README.md +407 -0
package/dist/components/ThemeNavBar.js +99 -0
package/dist/components/ThemeSelector.js +86 -0
package/dist/context/ThemeContext.js +175 -0
package/dist/index.js +44 -0
package/dist/styles/themes.css +278 -0
package/package.json +46 -0
package/src/components/ThemeNavBar.jsx +86 -0
package/src/components/ThemeSelector.jsx +68 -0
package/src/context/ThemeContext.jsx +159 -0
package/src/index.js +20 -0
package/src/styles/themes.css +278 -0

package/dist/context/ThemeContext.js ADDED Viewed

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.THEMES = void 0;
+exports.ThemeProvider = ThemeProvider;
+exports.registerTheme = registerTheme;
+exports.useTheme = useTheme;
+var _react = require("react");
+var _jsxRuntime = require("react/jsx-runtime");
+function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t["return"] && (u = t["return"](), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(r) { if (Array.isArray(r)) return r; } /*
+ * ============================================================
+ * ThemeContext.jsx — Evolution Theme Engine
+ * ============================================================
+ * This file is the heart of the theme engine. It provides:
+ *
+ *   THEMES           — A map of human-readable keys to the exact
+ *                      string values used as the `data-theme`
+ *                      attribute on <html>. These strings must
+ *                      match selectors in themes.css exactly.
+ *
+ *   ThemeProvider    — A React context provider that:
+ *                      • Reads the persisted theme from localStorage
+ *                        on first render (no flash on reload).
+ *                      • Sets `data-theme` on <html> whenever the
+ *                        theme changes so CSS kicks in site-wide.
+ *                      • Exposes `theme` and `setTheme` to all
+ *                        descendant components via context.
+ *
+ *   useTheme         — Convenience hook. Call inside any component
+ *                      wrapped by ThemeProvider to read or change
+ *                      the active theme.
+ *
+ *   registerTheme    — Runtime utility. Injects a new [data-theme]
+ *                      CSS block at runtime so consumers can add
+ *                      custom themes without editing themes.css.
+ *
+ * Data flow:
+ *   User picks theme → setTheme() → React state updates
+ *   → useEffect fires → data-theme attribute set on <html>
+ *   → CSS [data-theme="..."] block takes effect site-wide.
+ * ============================================================
+ */ /*
+ * THEMES maps a friendly JS key to the exact string written
+ * into the HTML `data-theme` attribute. Add an entry here and
+ * a matching [data-theme="..."] block in themes.css to create
+ * a new built-in theme.
+ */
+var THEMES = exports.THEMES = {
+  light: 'light',
+  dark: 'dark',
+  forest: 'forest',
+  tron: 'tron',
+  midnight: 'midnight'
+};
+var ThemeContext = /*#__PURE__*/(0, _react.createContext)({
+  theme: THEMES.light,
+  setTheme: function setTheme() {}
+});
+/*
+ * ThemeProvider wraps your application root (e.g. in index.jsx).
+ *
+ * It reads the user's last-saved theme from localStorage so the
+ * correct theme is applied before the first paint, preventing a
+ * flash back to the default Light theme on page refresh.
+ *
+ * Props:
+ *   children        — React subtree to receive theme context.
+ *   defaultTheme    — (optional) Override the fallback when no
+ *                     localStorage value exists. Defaults to 'light'.
+ *   storageKey      — (optional) localStorage key used to persist
+ *                     the selected theme. Defaults to 'etn-theme'.
+ */
+function ThemeProvider(_ref) {
+  var children = _ref.children,
+    _ref$defaultTheme = _ref.defaultTheme,
+    defaultTheme = _ref$defaultTheme === void 0 ? THEMES.light : _ref$defaultTheme,
+    _ref$storageKey = _ref.storageKey,
+    storageKey = _ref$storageKey === void 0 ? 'etn-theme' : _ref$storageKey;
+  var _useState = (0, _react.useState)(function () {
+      return localStorage.getItem(storageKey) || defaultTheme;
+    }),
+    _useState2 = _slicedToArray(_useState, 2),
+    theme = _useState2[0],
+    setThemeState = _useState2[1];
+  /*
+   * Sync the `data-theme` attribute on <html> whenever theme changes.
+   * This is what triggers the CSS variable overrides in themes.css.
+   */
+  (0, _react.useEffect)(function () {
+    document.documentElement.setAttribute('data-theme', theme);
+  }, [theme]);
+  /*
+   * setTheme updates React state AND persists to localStorage so
+   * the selection survives page refreshes and new tabs.
+   */
+  var setTheme = function setTheme(newTheme) {
+    setThemeState(newTheme);
+    localStorage.setItem(storageKey, newTheme);
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(ThemeContext.Provider, {
+    value: {
+      theme: theme,
+      setTheme: setTheme
+    },
+    children: children
+  });
+}
+/*
+ * useTheme — convenience hook.
+ * Returns { theme, setTheme } from the nearest ThemeProvider.
+ * Must be called inside a component that is a descendant of ThemeProvider.
+ */
+function useTheme() {
+  return (0, _react.useContext)(ThemeContext);
+}
+/*
+ * registerTheme — runtime theme registration.
+ *
+ * Dynamically injects a new [data-theme="name"] CSS block into the
+ * document <head> at runtime. This lets consumers define custom themes
+ * in JavaScript without modifying themes.css.
+ *
+ * Parameters:
+ *   name  (string)  — The theme key, e.g. 'ocean'. This value is used
+ *                     as the data-theme attribute value.
+ *   vars  (object)  — A plain object mapping CSS variable names to values.
+ *                     Keys should NOT include the leading '--'.
+ *
+ * Example:
+ *   registerTheme('ocean', {
+ *     'color-bg':          '#0a1628',
+ *     'color-text':        '#e0f0ff',
+ *     'color-primary':     '#00b4d8',
+ *     'color-on-primary':  '#0a1628',
+ *     'color-card-bg':     '#0d2137',
+ *     'color-card-border': '#1a3a5c',
+ *     'color-divider':     '#1a3a5c',
+ *     'color-link':        '#90e0ef',
+ *     'color-hover-bg':    'rgba(0,180,216,0.1)',
+ *     'color-code-bg':     '#070f1a',
+ *     'color-code-text':   '#e0f0ff',
+ *   });
+ *
+ * After calling registerTheme, add the key to your own THEMES-like object
+ * and pass it to <ThemeSelector> via the `themes` prop to surface it in
+ * the UI.
+ */
+function registerTheme(name, vars) {
+  var existingId = "etn-theme-".concat(name);
+  var existing = document.getElementById(existingId);
+  if (existing) existing.remove();
+  var declarations = Object.entries(vars).map(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 2),
+      key = _ref3[0],
+      value = _ref3[1];
+    return "  --".concat(key, ": ").concat(value, ";");
+  }).join('\n');
+  var css = "[data-theme=\"".concat(name, "\"] {\n").concat(declarations, "\n}");
+  var styleEl = document.createElement('style');
+  styleEl.id = existingId;
+  styleEl.textContent = css;
+  document.head.appendChild(styleEl);
+}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "THEMES", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeContext.THEMES;
+  }
+});
+Object.defineProperty(exports, "ThemeNavBar", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeNavBar.ThemeNavBar;
+  }
+});
+Object.defineProperty(exports, "ThemeProvider", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeContext.ThemeProvider;
+  }
+});
+Object.defineProperty(exports, "ThemeSelector", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeSelector.ThemeSelector;
+  }
+});
+Object.defineProperty(exports, "registerTheme", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeContext.registerTheme;
+  }
+});
+Object.defineProperty(exports, "useTheme", {
+  enumerable: true,
+  get: function get() {
+    return _ThemeContext.useTheme;
+  }
+});
+var _ThemeContext = require("./context/ThemeContext.js");
+var _ThemeSelector = require("./components/ThemeSelector.js");
+var _ThemeNavBar = require("./components/ThemeNavBar.js");

package/dist/styles/themes.css ADDED Viewed

@@ -0,0 +1,278 @@
+/*
+ * ============================================================
+ * themes.css — Evolution Theme Engine
+ * ============================================================
+ * This file contains:
+ *   1. All built-in theme variable blocks.
+ *   2. Base html/body reset.
+ *   3. Component styles for .etn-navbar and .etn-theme-selector.
+ *
+ * HOW THEMES WORK
+ * ───────────────
+ * Each theme is a CSS block that overrides the CSS custom
+ * properties declared in :root. The active theme is selected
+ * by setting a `data-theme` attribute on the <html> element:
+ *
+ *   document.documentElement.setAttribute('data-theme', 'dark');
+ *
+ * ThemeProvider does this automatically whenever the theme changes.
+ *
+ * WHY :root MUST COME FIRST
+ * ─────────────────────────
+ * Both `:root` and `[data-theme="..."]` selectors have equal
+ * CSS specificity (0,1,0). When both selectors match the same
+ * element, the one declared LATER in the file wins. Therefore
+ * :root (the Light/default theme) MUST appear before all
+ * [data-theme] blocks so that any active theme can override it.
+ *
+ * CSS VARIABLE REFERENCE
+ * ──────────────────────
+ *   --color-bg            Page / app background
+ *   --color-text          Primary body text
+ *   --color-card-bg       Card / panel surface background
+ *   --color-card-border   Card / panel border colour
+ *   --color-btn-dark-bg   Background for "dark" style buttons
+ *   --color-btn-dark-text Text on "dark" style buttons
+ *   --color-btn-light-bg  Background for "light" style buttons
+ *   --color-btn-light-text Text on "light" style buttons
+ *   --color-divider       Horizontal rules / separators
+ *   --color-primary       Primary accent / brand colour
+ *   --color-on-primary    Text drawn on top of --color-primary
+ *   --color-link          Hyperlink colour
+ *   --color-hover-bg      Subtle hover-state background tint
+ *   --color-code-bg       Code block background
+ *   --color-code-text     Code block text colour
+ *
+ * ADDING A CUSTOM THEME (CSS approach)
+ * ─────────────────────────────────────
+ * Copy the block below, change the selector to your theme name,
+ * and update the variable values. Then add the name to your
+ * themes object and pass it to <ThemeSelector>.
+ *
+ *   [data-theme="ocean"] {
+ *     --color-bg:          #0a1628;
+ *     --color-text:        #e0f0ff;
+ *     --color-primary:     #00b4d8;
+ *     ... etc.
+ *   }
+ *
+ * Alternatively, use registerTheme() from ThemeContext.jsx to
+ * inject a theme at runtime without touching this file at all.
+ * ============================================================
+ */
+/* ============================================================
+ * 1. BUILT-IN THEMES
+ * ============================================================ */
+/* --- Light Theme (default) ---
+ * :root MUST appear first in this file so that every
+ * [data-theme] block below can override it.
+ */
+:root {
+  --color-bg:             #f8f9fa;
+  --color-text:           #212529;
+  --color-card-bg:        #ffffff;
+  --color-card-border:    #dee2e6;
+  --color-btn-dark-bg:    #f8f9fa;
+  --color-btn-dark-text:  #212529;
+  --color-btn-light-bg:   #ffffff;
+  --color-btn-light-text: #212529;
+  --color-divider:        #dee2e6;
+  --color-primary:    #1976d2;
+  --color-on-primary: #ffffff;
+  --color-link:       #a435f0;
+  --color-hover-bg:   rgba(25, 118, 210, 0.08);
+  --color-code-bg:    #282c34;
+  --color-code-text:  #ffffff;
+}
+/* --- Dark Theme --- */
+[data-theme="dark"] {
+  --color-bg:             #212529;
+  --color-text:           #f8f9fa;
+  --color-card-bg:        #343a40;
+  --color-card-border:    #444444;
+  --color-btn-dark-bg:    #f8f9fa;
+  --color-btn-dark-text:  #212529;
+  --color-btn-light-bg:   #343a40;
+  --color-btn-light-text: #f8f9fa;
+  --color-divider:        #444444;
+  --color-primary:    #90caf9;
+  --color-on-primary: #212529;
+  --color-link:       #a435f0;
+  --color-hover-bg:   rgba(144, 202, 249, 0.08);
+  --color-code-bg:    #232b36;
+  --color-code-text:  #f8f9fa;
+}
+/* --- Forest Theme ---
+ * A comforting deep-green palette with sage text and
+ * a natural green primary accent.
+ */
+[data-theme="forest"] {
+  --color-bg:             #1b2e22;
+  --color-text:           #cde8d4;
+  --color-card-bg:        #243c2b;
+  --color-card-border:    #3a5c44;
+  --color-btn-dark-bg:    #3a5c44;
+  --color-btn-dark-text:  #cde8d4;
+  --color-btn-light-bg:   #243c2b;
+  --color-btn-light-text: #cde8d4;
+  --color-divider:        #3a5c44;
+  --color-primary:    #4caf70;
+  --color-on-primary: #1b2e22;
+  --color-link:       #7dd8a0;
+  --color-hover-bg:   rgba(76, 175, 112, 0.12);
+  --color-code-bg:    #111e17;
+  --color-code-text:  #cde8d4;
+}
+/* --- Tron Theme ---
+ * Inspired by the Tron: Legacy aesthetic — dark navy background
+ * with electric cyan text and sky-blue accents.
+ */
+[data-theme="tron"] {
+  --color-bg:             #0f172a;
+  --color-text:           #67e8f9;
+  --color-card-bg:        #1e293b;
+  --color-card-border:    #67e8f9;
+  --color-btn-dark-bg:    #0ea5e9;
+  --color-btn-dark-text:  #0f172a;
+  --color-btn-light-bg:   #1e293b;
+  --color-btn-light-text: #67e8f9;
+  --color-divider:        #0ea5e9;
+  --color-primary:    #0ea5e9;
+  --color-on-primary: #0f172a;
+  --color-link:       #67e8f9;
+  --color-hover-bg:   rgba(14, 165, 233, 0.08);
+  --color-code-bg:    #232b36;
+  --color-code-text:  #67e8f9;
+}
+/* --- Midnight Theme ---
+ * A deep night-sky palette: near-black background, muted
+ * blue-grey text, teal (#5ce1b5) primary accent, and
+ * light-blue (#8bd4ff) link colour.
+ */
+[data-theme="midnight"] {
+  --color-bg:             #0b1016;
+  --color-text:           #e7edf2;
+  --color-card-bg:        #131c28;
+  --color-card-border:    #263141;
+  --color-btn-dark-bg:    #263141;
+  --color-btn-dark-text:  #e7edf2;
+  --color-btn-light-bg:   #0f151e;
+  --color-btn-light-text: #e7edf2;
+  --color-divider:        #263141;
+  --color-primary:    #5ce1b5;
+  --color-on-primary: #0b1016;
+  --color-link:       #8bd4ff;
+  --color-hover-bg:   rgba(92, 225, 181, 0.12);
+  --color-code-bg:    #0f151e;
+  --color-code-text:  #e7edf2;
+}
+/* ============================================================
+ * 2. BASE RESET
+ * Sets the theme background on <html> to prevent a flash of
+ * white before React mounts and ThemeProvider runs.
+ * ============================================================ */
+html {
+  background-color: var(--color-bg);
+  color: var(--color-text);
+  transition: background-color 0.3s ease, color 0.3s ease;
+}
+/* ============================================================
+ * 3. COMPONENT STYLES
+ * All classes are prefixed with 'etn-' (Evolution Theme eNgine)
+ * to avoid collisions with the consumer application's CSS.
+ * ============================================================ */
+/* --- ThemeNavBar (.etn-navbar) --- */
+.etn-navbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 24px;
+  height: 56px;
+  background-color: var(--color-card-bg);
+  border-bottom: 1px solid var(--color-card-border);
+  gap: 16px;
+  /* Stays at the top when used as a sticky header */
+  position: sticky;
+  top: 0;
+  z-index: 1000;
+}
+.etn-navbar-brand {
+  font-size: 1.1rem;
+  font-weight: 700;
+  color: var(--color-text);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.etn-navbar-links {
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  flex: 1;
+}
+.etn-navbar-link {
+  color: var(--color-text);
+  text-decoration: none;
+  font-size: 0.95rem;
+  opacity: 0.85;
+  transition: opacity 0.15s ease, color 0.15s ease;
+}
+.etn-navbar-link:hover {
+  opacity: 1;
+  color: var(--color-primary);
+}
+/* --- ThemeSelector (.etn-theme-selector) --- */
+.etn-theme-selector {
+  padding: 6px 10px;
+  background-color: var(--color-card-bg);
+  color: var(--color-text);
+  border: 1px solid var(--color-card-border);
+  border-radius: 4px;
+  font-size: 0.875rem;
+  cursor: pointer;
+  /* Prevent the select from shrinking inside a flex navbar */
+  flex-shrink: 0;
+  transition: border-color 0.15s ease;
+}
+.etn-theme-selector:hover {
+  border-color: var(--color-primary);
+}
+.etn-theme-selector:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 3px var(--color-hover-bg);
+}
+/* Responsive: hide nav links on small screens */
+@media (max-width: 600px) {
+  .etn-navbar-links {
+    display: none;
+  }
+}

package/package.json ADDED Viewed

@@ -0,0 +1,46 @@
+{
+  "name": "@evolution-james/evolution-theme-engine",
+  "version": "1.0.0",
+  "description": "A plug-and-play React theme engine with CSS variable-based theming, localStorage persistence, and optional navbar component.",
+  "keywords": [
+    "react",
+    "theme",
+    "dark-mode",
+    "css-variables",
+    "theme-engine",
+    "evolution"
+  ],
+  "author": {
+    "name": "James Evolution (Evolution Coding Academy)",
+    "url": "https://github.com/james-evolution"
+  },
+  "license": "SEE LICENSE.txt",
+  "//": "BUILD NOTES: Source files are JSX (src/). The build script (build.js) uses Babel to pre-compile them into plain CommonJS JS (dist/) so consumers never need to transpile this package themselves. @babel/preset-react is configured with { runtime: 'automatic' } which uses the new JSX transform — it imports from react/jsx-runtime automatically instead of requiring React to be in scope (the classic runtime would inject React.createElement() calls that fail if React is not globally imported). @babel/preset-env compiles ESM imports/exports and modern syntax to CommonJS-compatible output. The 'exports' field below takes strict precedence over 'main' in webpack 5 and Node 12+. Without it, npm link + webpack symlink resolution can bypass 'main' and resolve to raw JSX source files the consumer's bundler cannot parse.",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@babel/cli": "^7.0.0",
+    "@babel/core": "^7.0.0",
+    "@babel/preset-env": "^7.0.0",
+    "@babel/preset-react": "^7.0.0"
+  },
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/james-evolution/evolution-theme-engine.git"
+  },
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "node build.js"
+  }
+}

package/src/components/ThemeNavBar.jsx ADDED Viewed

@@ -0,0 +1,86 @@
+/*
+ * ============================================================
+ * ThemeNavBar.jsx — Evolution Theme Engine
+ * ============================================================
+ * An optional, barebones navigation bar with the ThemeSelector
+ * component already rendered inside it.
+ *
+ * This is the "batteries included" option — import ThemeNavBar
+ * if you want a ready-made header without wiring up ThemeSelector
+ * yourself. Under the hood it simply renders <ThemeSelector />,
+ * so everything still flows through ThemeContext.
+ *
+ * The navbar is intentionally minimal and styled purely via
+ * CSS variables (no Bootstrap, no third-party UI libraries).
+ * Customize it by passing props or overriding .etn-navbar CSS
+ * classes in your own stylesheet.
+ *
+ * Props:
+ *   title       (string)         — Brand/title text shown on the
+ *                                  left side of the navbar.
+ *                                  Defaults to 'My App'.
+ *   links       (Array<object>)  — Navigation links rendered to
+ *                                  the right of the title. Each
+ *                                  entry: { label, href }.
+ *                                  Defaults to a few placeholder
+ *                                  links.
+ *   themes      (object)         — Forwarded to <ThemeSelector>.
+ *                                  Defaults to all 5 built-in themes.
+ *   className   (string)         — Extra class(es) added to the
+ *                                  root <nav> element alongside
+ *                                  'etn-navbar'.
+ *   style       (object)         — Inline styles for the root <nav>.
+ *
+ * Usage:
+ *   import { ThemeNavBar } from 'evolution-theme-engine';
+ *
+ *   <ThemeNavBar
+ *     title="My Cool App"
+ *     links={[
+ *       { label: 'Home',  href: '/' },
+ *       { label: 'About', href: '/about' },
+ *     ]}
+ *   />
+ * ============================================================
+ */
+import { ThemeSelector } from './ThemeSelector.jsx';
+import '../styles/themes.css';
+const DEFAULT_LINKS = [
+  { label: 'Home',  href: '#' },
+  { label: 'About', href: '#' },
+  { label: 'Docs',  href: '#' },
+];
+export function ThemeNavBar({
+  title = 'My App',
+  links = DEFAULT_LINKS,
+  themes,
+  className = '',
+  style = {},
+}) {
+  return (
+    <nav
+      className={`etn-navbar${className ? ` ${className}` : ''}`}
+      style={style}
+    >
+      {/* Left side: brand/title */}
+      <span className="etn-navbar-brand">{title}</span>
+      {/* Center: navigation links */}
+      <ul className="etn-navbar-links">
+        {links.map(({ label, href }) => (
+          <li key={label}>
+            <a href={href} className="etn-navbar-link">
+              {label}
+            </a>
+          </li>
+        ))}
+      </ul>
+      {/* Right side: ThemeSelector dropdown */}
+      <ThemeSelector themes={themes} />
+    </nav>
+  );
+}

package/src/components/ThemeSelector.jsx ADDED Viewed

@@ -0,0 +1,68 @@
+/*
+ * ============================================================
+ * ThemeSelector.jsx — Evolution Theme Engine
+ * ============================================================
+ * A standalone, dependency-free <select> dropdown that lets
+ * users switch between themes.
+ *
+ * This component has NO required props — it reads the current
+ * theme and setter from ThemeContext via useTheme(). All you
+ * need to do is render it anywhere inside a <ThemeProvider>.
+ *
+ * Props:
+ *   themes      (object)  — Map of { label: themeKey } entries
+ *                           displayed in the dropdown.
+ *                           Defaults to all 5 built-in themes.
+ *   className   (string)  — Extra CSS class(es) added to the
+ *                           <select> element alongside the
+ *                           default 'etn-theme-selector' class.
+ *   style       (object)  — Inline styles applied to the select.
+ *
+ * Usage:
+ *   import { ThemeSelector } from 'evolution-theme-engine';
+ *
+ *   // Standalone — render anywhere inside ThemeProvider:
+ *   <ThemeSelector />
+ *
+ *   // With custom theme list:
+ *   <ThemeSelector
+ *     themes={{ 'Light': 'light', 'Dark': 'dark', 'Ocean': 'ocean' }}
+ *   />
+ * ============================================================
+ */
+import { useTheme } from '../context/ThemeContext.jsx';
+import '../styles/themes.css';
+/*
+ * DEFAULT_THEMES is what shows up in the dropdown when no
+ * `themes` prop is passed. Keys are display labels; values
+ * are the data-theme attribute strings defined in themes.css.
+ */
+const DEFAULT_THEMES = {
+  'Light Theme':    'light',
+  'Dark Theme':     'dark',
+  'Forest':         'forest',
+  'Tron':           'tron',
+  'Midnight':       'midnight',
+};
+export function ThemeSelector({ themes = DEFAULT_THEMES, className = '', style = {} }) {
+  const { theme, setTheme } = useTheme();
+  return (
+    <select
+      className={`etn-theme-selector${className ? ` ${className}` : ''}`}
+      value={theme}
+      onChange={(e) => setTheme(e.target.value)}
+      aria-label="Select theme"
+      style={style}
+    >
+      {Object.entries(themes).map(([label, value]) => (
+        <option key={value} value={value}>
+          {label}
+        </option>
+      ))}
+    </select>
+  );
+}