this.gui 1.0.17 → 1.1.0

package/src/registry/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./factory";
+export { GuiRegistry } from "./GuiRegistry";

package/src/registry/types.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+export type RegistryEntry = {
+  type: string;
+  resolve: (spec: any, ctx?: ResolveCtx) => React.ReactElement | null;};
+export type GuiRegistry = Record<string, RegistryEntry>;
+export type ResolveCtx = { theme?: any; [key: string]: any };

package/src/stories/01.Home.mdx

@@ -0,0 +1,22 @@
+<div
+  style={{
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '70vh',
+    background: 'var(--gui-bg-default)',
+    color: 'var(--gui-text-primary)',
+    padding: '40px',
+  }}
+>
+  <img
+    src="/this.GUI.png"
+    alt="This.GUI"
+    style={{ width: '300px', height: 'auto', imageRendering: 'auto', marginBottom: '10px', marginTop: '-34px' }}
+  />
+  <h1 style={{ fontSize: '4rem', margin: '0 0 5px 0' }}>.GUI</h1>
+  <p style={{ maxWidth: '600px', textAlign: 'center', fontSize: '1.2rem', lineHeight: '1.3', marginTop: '-8px' }}>
+    A collection of components and building blocks for the neurons.me environment, enabling declarative GUI generation powered by AI.
+  </p>
+</div>

package/src/stories/02.Understanding.This.GUI.md

@@ -0,0 +1,149 @@
+# Declarative GUI with `this.GUI`
+`this.GUI` is designed as a **declarative layout system**, where all building blocks (NavBar, Drawers, StickyOptions, Footer) expose **clear JSON-friendly props**.  
+This **allows UIs to be described** and even generated by tools like **LLMs**, using nothing more than structured data.
+
+---
+
+## 🔑 Core Idea
+- Every component exposes a **schema-like props API**.
+- Layout respects **insets** (nav height, drawer widths) reported into the theme via `CustomThemeProvider`.
+- The provider also mirrors these values into CSS variables (`--gui-inset-left`, `--gui-inset-right`, `--gui-nav-height`).
+- With this contract, GUIs can be built from **JSON specs** instead of imperative React code.
+
+Example JSON spec:
+
+```json
+{
+  "route": "/dashboard",
+  "layout": {
+    "navbar": { "title": "Dashboard", "position": "fixed" },
+    "stickyOptions": {
+      "items": [
+        { "icon": "mui:BarChart", "label": "Stats", "href": "/stats" },
+        { "icon": "lucide:bolt", "label": "Power", "href": "/power" }
+      ]
+    },
+    "drawerLeft": { "title": "Menu", "items": [...] },
+    "drawerRight": { "title": "Context", "items": [...] },
+    "footer": { "text": "© 2025 neurons.me" }
+  }
+}
+
+Your renderer simply hydrates this into React components.
+
+
+---
+
+## 📦 Components
+
+### NavBar
+
+**Props:**
+- `title`: string
+- `logo`: string (URL)
+- `NavBarLinks`: array of `{ label, href, icon?, children? }`
+- `position`: `"fixed"` | `"static"` | `"sticky"` (default: `"fixed"`)
+- `showMenuButton`, `showThemeToggle`
+
+NavBar measures its height and updates `theme.layout.insets.nav`.
+
+```jsx
+<NavBar title="Demo" position="fixed" />
+```
+
+---
+
+### LeftDrawer & RightDrawer
+
+**Props:**
+- `drawerWidth`: number (default: 260)
+- `variant`: `"permanent"` | `"temporary"` (auto-chooses based on screen size)
+- `title`: optional with label + icon
+
+Each drawer updates `theme.layout.insets.left` or `theme.layout.insets.right` when permanent.
+
+```jsx
+<LeftDrawer title="Menu" items={[{ icon: 'mui:Home', label: 'Home' }]} />
+<RightDrawer title="Context" items={[{ icon: 'mui:Info', label: 'Details' }]} />
+```
+
+---
+
+### StickyOptionsTop
+
+Compact quick-actions bar that lives under the NavBar.
+
+**Props:**
+- `items`: actions `{ icon, label?, href?, iconColor?, variant? }`
+- `positioning`: `{ mode: 'sticky' | 'fixed', topOffset, reserveSpace }`
+- `mobileVariant`: `"auto"` | `"fab"` | `"inline"`
+- `dense`: boolean
+
+```jsx
+<StickyOptionsTop
+  items={[
+    { icon: 'mui:Settings', label: 'Settings', href: '/settings' },
+    { icon: 'lucide:bolt', label: 'Power', href: '/power', iconColor: 'primary' }
+  ]}
+  positioning={{ mode: 'sticky' }}
+/>
+```
+
+---
+
+### Footer
+
+**Props:**
+- `text`: string or ReactNode
+- Automatically respects left/right insets from permanent drawers.
+
+```jsx
+<Footer text="© 2025 neurons.me" />
+```
+
+---
+
+## 🌐 Why Declarative?
+
+Every prop is JSON-serializable, so LLMs or external systems can generate full UIs declaratively:
+- “Add a right drawer with a title and an insights icon”
+- “Place a sticky options bar under the navbar with capture + settings”
+- “On /reports, show the drawer and a compact navbar”
+
+These map directly into JSON specs that your app hydrates into React.
+
+---
+
+## 🚀 Benefits
+- **Schema-driven:** easy to serialize, validate, and diff.
+- **LLM-ready:** prompt-to-UI becomes natural.
+- **Layout-safe:** insets keep everything aligned automatically.
+- **Composable:** any route can declare its layout in one object.
+
+---
+
+## Example: Full Route Layout
+
+```jsx
+<NavBar title="Dashboard" />
+<LeftDrawer title="Menu" />
+<StickyOptionsTop items={items} />
+<PageContent />
+<Footer text="© 2025 neurons.me" />
+```
+
+Or as JSON:
+
+```json
+{
+  "navbar": { "title": "Dashboard" },
+  "drawerLeft": { "title": "Menu" },
+  "stickyOptions": { "items": [ ... ] },
+  "footer": { "text": "© 2025 neurons.me" }
+}
+```
+
+---
+That’s the philosophy: declarative contracts for every GUI building block, so your UI can be described, generated, and remixed by humans, scripts, or LLMs.
+---
+

package/src/stories/03.Themes.mdx

@@ -0,0 +1,235 @@
+# This.GUI — Theme Engine (v2)
+**Token‑first. Manifest‑driven.**  
+Compiles **JSON tokens** into an MUI theme at runtime. Each **theme** now has **modes** (typically `light` and `dark`) defined by a **manifest**; we also export **CSS variables** and coordinate **insets** (bars/drawers) via `GuiProvider`.
+
+---
+
+## TL;DR
+- **Tokens**: describe design values (colors, spacing, motion, …).  
+- **Manifest**: describes the *theme* (id, name, icon, modes and where their tokens live).  
+- **fromTokens**: `makeMuiTheme(globalTokens, modeTokens, mode)` produces an MUI theme.  
+- **getTheme**: builds a theme from `tokens`, from a `manifest`, or from **built‑ins**.  
+- **GuiProvider**: stores the active `family+mode`, injects **CSS vars** and coordinates **insets**.  
+- **Selector/Toggle**: UI to switch between `light`/`dark` of the active theme.  
+- **AppBar note**: MUI only supports `default | primary | secondary | transparent`. Other colors → use `sx`.
+
+---
+
+## Recommended structure
+
+```
+src/themes/
+  tokens/
+    global.tokens.json               # shared base (radius, spacing, motion…)
+    neurons/
+      manifest.json                  # describes the "neurons.me" theme
+      light.tokens.json              # light‑mode tokens (values only, no metadata)
+      dark.tokens.json               # dark‑mode tokens  (values only, no metadata)
+  fromTokens.ts                      # compiler tokens → MUI theme
+  index.js                           # built‑in registry + public factories
+  theme.d.ts                         # optional DX types
+```
+
+### Manifest (what it is and what it contains)
+- **Identity**: `id`, `name`, `description`, `author`, `version`, etc.
+- **Where tokens are**: `modes.light.path` and `modes.dark.path`.
+- **Theme icon**: `icon` (optional).  
+  - Supported:
+    ```ts
+    type ThemeIcon =
+      | { type: 'mui' | 'lucide'; value: string } // icon-set name
+      | { type: 'url'; value: string }            // path to .svg/.png
+      | { type: 'svg'; value: string }            // inline SVG
+      | { type: 'data'; value: string };          // data URI
+    ```
+- **Important**: we **no longer** keep `preview` or metadata inside token files; the preview is **derived** from the theme (e.g. `palette.background.default`, `palette.primary.main`, `palette.link.main`, etc.).
+
+**Example `manifest.json`:**
+```json
+{
+  "id": "neurons.me",
+  "name": "neurons.me",
+  "description": "A modern, flexible theme for Neuroverse.",
+  "author": "suiGn",
+  "version": "1.0.0",
+  "license": "MIT",
+  "icon": { "type": "mui", "value": "Palette" },
+  "modes": {
+    "light": { "path": "./light.tokens.json" },
+    "dark":  { "path": "./dark.tokens.json" }
+  }
+}
+```
+
+---
+
+## Tokens (what goes inside)
+Token files contain **values only**. If you use Tokens Studio, keep the `{"$value": ...}` shape; the compiler understands it.
+
+**Example `light.tokens.json` (trimmed):**
+```json
+{
+  "color": {
+    "primary":       { "$value": "#0a3a42" },
+    "secondary":     { "$value": "#e5396f" },
+    "icon":          { "$value": "#5e5e5e" },
+    "bgDefault":     { "$value": "#f8f9fa" },
+    "bgPaper":       { "$value": "#ffffff" },
+    "bgNav":         { "$value": "#fdfdfd" },
+    "textPrimary":   { "$value": "#111111" },
+    "textSecondary": { "$value": "#444444" },
+    "link":          { "$value": "#008c7d" },
+    "linkVisited":   { "$value": "#006e64" },
+    "border":        { "$value": "rgba(0,0,0,0.08)" }
+  }
+}
+```
+
+---
+
+## Compiler (`fromTokens.ts`)
+**Primary API**
+```ts
+makeMuiTheme(globalTokens: any, modeTokens: any, mode: 'light'|'dark'): Theme
+```
+
+- Maps colors into `theme.palette`:
+  - `color.primary` → `palette.primary.main`
+  - `color.secondary` → `palette.secondary.main`
+  - `color.bgDefault` → `palette.background.default`
+  - `color.bgPaper` → `palette.background.paper`
+  - `color.bgNav` → `palette.background.nav` *(custom key)*
+  - `color.textPrimary` / `color.textSecondary` → `palette.text.*`
+  - `color.link` / `color.linkVisited` → `palette.link.*` *(custom key)*
+  - Semantic (`extendedColors.*`): `success`, `warning`, `error`, `info`
+- Exposes **all** tokens again under `theme.custom.*` for a stable access surface.
+- Builds `breakpoints`, `zIndex`, `typography`, `shadows`, `transitions`, etc.
+- Injects **CSS variables** via `MuiCssBaseline`:
+  - `--gui-primary`, `--gui-secondary`, `--gui-bg-default`, `--gui-bg-paper`,  
+    `--gui-bg-nav`, `--gui-text-primary`, `--gui-text-secondary`,  
+    `--gui-link`, `--gui-link-visited`, `--gui-border`, etc.
+
+**Manifest mode (optional)**  
+When needed, `makeMuiThemeFromManifest(manifest, { mode })` reads tokens from `manifest.modes[mode].tokens` and calls `makeMuiTheme(...)` internally.
+
+---
+
+## Registry & factories (`themes/index.js`)
+- **Built‑ins**: we register `neurons` with its `manifest` and `light/dark` tokens.
+- **createThemeFromTokens(tokens, mode)**: thin shortcut to `makeMuiTheme(...)`.
+- **createThemeFromManifest(manifest, mode, tokensByMode?)**: uses manifest + (optional) map `{ light, dark }`.
+- **getTheme**  
+  ```ts
+  // options: { key?: string; manifest?: any; tokens?: any; mode: 'light' | 'dark' }
+  ```
+  - If you pass `tokens`: it prioritizes `createThemeFromTokens`.
+  - If you pass a `manifest`: it prioritizes `createThemeFromManifest`.
+  - If you pass a built‑in `key`: it resolves from the registry (`neurons` + `mode`).
+- **AVAILABLE_THEMES**: flat list derived from built‑ins:
+  ```ts
+  type AvailableTheme = {
+    id: string;         // e.g. "neurons-light"
+    family: string;     // e.g. "neurons"
+    name: string;       // e.g. "neurons.me Light"
+    mode: 'light'|'dark';
+    manifest: any;
+  }
+  ```
+
+---
+
+## GuiProvider (coordination & context)
+`GuiProvider`:
+
+1) **Active theme state**  
+   - Stores `themeKey` (e.g. `neurons-dark`) in `localStorage` (`this.gui:theme`).  
+   - Derives `family` + `mode` from `AVAILABLE_THEMES`.  
+   - Exposes helpers: `setMode('light'|'dark')`, `setFamilyAndMode(family, mode)`, `toggleMode()`.
+
+2) **Compiles and extends the theme**  
+   - Calls `getTheme({ key: active.id })`.  
+   - Injects `theme.layout.insets` and `theme.updateInsets(cb)`.  
+   - Syncs CSS vars: `--gui-inset-left/right` and `--gui-nav-height`.
+
+3) **How components consume it**  
+   - Use MUI’s `useTheme()` → you get **MUI + GuiProvider extensions**.  
+   - Use `useMediaQuery(theme.breakpoints.*)` for consistent responsiveness.  
+   - Read/update insets via `theme.layout.insets` and `theme.updateInsets`.
+
+**Hook**
+```ts
+import { useThemeContext } from '@/context/GuiProvider';
+
+const { family, mode, toggleMode, setMode, setFamilyAndMode, availableFamilies } = useThemeContext();
+```
+
+---
+
+## Selector & Toggle
+- **ThemeSelector**: shows the *theme name* (family), a derived **preview**, and a **toggle** (🌞/🌙) aligned to the right.  
+- **Previews**: derived from the active theme (e.g. `background.default`, `primary.main`, `secondary.main`, `link.main`, etc.). You can increase the grid and show tooltips with the token name.
+
+---
+
+## Compatibility notes (MUI)
+- **AppBar `color`** supports `default | primary | secondary | transparent`.  
+  - If you want `success | info | warning | error` or any custom color, use `sx`:
+    ```jsx
+    <AppBar
+      color="transparent"
+      sx={{
+        bgcolor: (t) => t.palette.success.main,
+        color:  (t) => t.palette.getContrastText(t.palette.success.main)
+      }}
+    />
+    ```
+- The rest of the components respect your `palette` and accept granular `sx`.
+
+---
+
+## Examples
+### 1) Use a built‑in (neurons dark)
+```ts
+import { getTheme } from '@/themes';
+const theme = getTheme({ key: 'neurons', mode: 'dark' });
+```
+
+### 2) Use “ad‑hoc” tokens (no manifest)
+```ts
+import { getTheme } from '@/themes';
+import myTokens from './my.light.tokens.json';
+
+const theme = getTheme({ tokens: myTokens, mode: 'light' });
+```
+
+### 3) Switch mode from UI
+```tsx
+import { useThemeContext } from '@/context/GuiProvider';
+
+function ModeToggle() {
+  const { mode, toggleMode } = useThemeContext();
+  return <Switch checked={mode === 'dark'} onChange={toggleMode} />;
+}
+```
+
+---
+
+## Troubleshooting
+**“I don’t see my themes in the selector.”**  
+- Make sure `themes/index.js` registers your theme in `BUILT_IN` and that `AVAILABLE_THEMES` includes it.  
+- For an external theme, use `getTheme({ manifest, tokensByMode })` or `getTheme({ tokens })`.
+
+**“AppBar won’t change to ‘success’.”**  
+- That’s expected: use `sx` as shown above.
+
+**“I want pre‑painted CSS to avoid FOUC.”**  
+- You can generate a `tokens.css` at *build time* with default variables; `GuiProvider` will re‑hydrate at runtime.
+
+---
+
+## Final mental model
+- **JSON tokens** define the design truth.  
+- **Manifest** describes the theme (icon, modes, and token locations).  
+- **fromTokens** compiles to **MUI theme** + `theme.custom.*` + **CSS vars**.  
+- **GuiProvider** selects `family+mode`, persists it, adds **insets**, and exposes helpers.  
+- **Components** consume the theme and style granularly with `sx` — mature, flexible, no lock‑in, ready for AI.

package/src/stories/04.GuiProvider.md

@@ -0,0 +1,126 @@
+# GuiProvider
+	•	Introduction & Features
+	•	API table with props and context values
+	•	Usage example with useThemeContext
+	•	Notes on CSS vars, insets, and theme toggling
+## Introduction
+`GuiProvider` is a React context provider component that extends Material-UI's (`@mui/material`) `ThemeProvider` with custom logic to manage themes. 
+It provides a centralized way to handle theme persistence, dynamic insets for layout adjustments, and theme toggling with support for multiple theme variants.
+This component is designed to simplify theming in complex applications by combining theme state management, localStorage persistence, and CSS variable synchronization.
+
+## Features
+- **Theme Persistence:** Automatically saves and loads the last selected theme using `localStorage`.
+- **Insets Management:** Manages layout insets (left, right, navigation bar height) with synchronization to CSS variables for consistent styling.
+- **Multi-Variant Theme Support:** Supports multiple themes beyond simple light/dark modes.
+- **Theme Toggling:** Provides a toggle function to cycle through available themes or set a specific theme.
+- **Integration with MUI Theme:** Injects custom layout insets and update callbacks into the MUI theme object for seamless access via `useTheme()`.
+
+## API
+### `GuiProvider`
+
+#### Props
+
+<table>
+  <thead>
+    <tr>
+      <th style="text-align:left;">Name</th>
+      <th style="text-align:left;">Type</th>
+      <th style="text-align:left;">Default</th>
+      <th style="text-align:left;">Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>initialTheme</code></td>
+      <td><code>string</code></td>
+      <td><code>'neurons-dark'</code></td>
+      <td>The initial theme key to use on mount.</td>
+    </tr>
+    <tr>
+      <td><code>children</code></td>
+      <td><code>ReactNode</code></td>
+      <td>—</td>
+      <td>Child components to render within the provider.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Context Value
+
+<p>The provider exposes the following context values via <code>useThemeContext()</code> hook:</p>
+
+<table>
+  <thead>
+    <tr>
+      <th style="text-align:left;">Name</th>
+      <th style="text-align:left;">Type</th>
+      <th style="text-align:left;">Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>themeName</code></td>
+      <td><code>string</code></td>
+      <td>The current active theme key.</td>
+    </tr>
+    <tr>
+      <td><code>setThemeName</code></td>
+      <td><code>function</code></td>
+      <td>Set the active theme by key.</td>
+    </tr>
+    <tr>
+      <td><code>availableThemes</code></td>
+      <td><code>Array</code></td>
+      <td>List of available theme metadata objects.</td>
+    </tr>
+    <tr>
+      <td><code>toggleTheme</code></td>
+      <td><code>function</code></td>
+      <td>Toggle between themes or set a specific theme.</td>
+    </tr>
+    <tr>
+      <td><code>getThemeMeta</code></td>
+      <td><code>function</code></td>
+      <td>Get metadata for a given theme key.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Usage Example
+
+```jsx
+import React from 'react';
+import { GuiProvider, useThemeContext } from './context/GuiProvider';
+
+function ThemeSwitcher() {
+  const { themeName, toggleTheme, availableThemes } = useThemeContext();
+
+    <div>
+      <p>Current theme: {themeName}</p>
+      <button onClick={() => toggleTheme()}>Toggle Theme</button>
+      <ul>
+        {availableThemes.map(({ key, name }) => (
+          <li key={key}>
+            <button onClick={() => toggleTheme(key)}>{name}</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+
+export default function App() {
+  return (
+    <GuiProvider initialTheme="neurons-dark">
+      <ThemeSwitcher />
+      {/* Your app components here */}
+    </GuiProvider>
+  );
+}
+```
+
+## Notes
+
+- The `GuiProvider` component internally manages CSS variables (`--gui-inset-left`, `--gui-inset-right`, `--gui-nav-height`) to allow non-MUI components to adapt to the current layout insets.
+- The theme toggle function cycles through all available themes, or can directly set a theme by its key.
+- The available themes are derived from the `AVAILABLE_THEMES` array imported from the theme tokens, and include metadata such as name, mode, icon, and preview.
+- Use the `useThemeContext()` hook to access theme-related state and functions within your components.
+- This provider replaces the older `useThemeToggle` hook to avoid confusion and supports multi-variant theming beyond simple light/dark toggling.

package/src/stories/04.GuiProvider.mdx

@@ -0,0 +1,129 @@
+# GuiProvider
+
+- Introduction & Features
+- API table with props and context values
+- Usage example with useThemeContext
+- Notes on CSS vars, insets, and theme toggling
+## Introduction
+`GuiProvider` provides a centralized way to handle theme persistence, dynamic insets for layout adjustments, and theme toggling with support for multiple theme variants.
+This component is designed to simplify theming in complex applications by combining theme state management, localStorage persistence, and CSS variable synchronization.
+
+## Features
+- **Theme Persistence:** Automatically saves and loads the last selected theme using `localStorage`.
+- **Insets Management:** Manages layout insets (left, right, navigation bar height) with synchronization to CSS variables for consistent styling.
+- **Multi-Variant Theme Support:** Supports multiple themes beyond simple light/dark modes.
+- **Theme Toggling:** Provides a toggle function to cycle through available themes or set a specific theme.
+- **Integration with MUI Theme:** Injects custom layout insets and update callbacks into the MUI theme object for seamless access via `useTheme()`.
+
+## API
+### `GuiProvider`
+There are only two props:
+	1.	initialTheme: Defines which theme key should be active when the provider first mounts. 
+    If a value is stored in localStorage, that takes precedence.
+	2.	children: This is a standard React pattern.
+	•	children means whatever JSX elements you wrap inside GuiProvider will be rendered there.
+	•	For example:
+```jsx
+<GuiProvider initialTheme="neurons-dark">
+  <App />
+</GuiProvider>
+```
+
+#### Props
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>initialTheme</code></td>
+      <td><code>string</code></td>
+      <td><code>'neurons-dark'</code></td>
+      <td>The initial theme key to use on mount.</td>
+    </tr>
+    <tr>
+      <td><code>children</code></td>
+      <td><code>ReactNode</code></td>
+      <td>—</td>
+      <td>Child components to render within the provider.</td>
+    </tr>
+  </tbody>
+</table>
+---
+#### Context Value
+The context value refers to the collection of state and functions that the `GuiProvider` makes available to any component within its React tree. 
+This context is exposed through a custom hook called `useThemeContext()`, which allows components to easily access and interact with the current theme state, available themes, and theme-related actions such as toggling or setting a theme directly.
+ By using this hook, components can remain decoupled from the provider's internal implementation while still responding dynamically to theme changes and layout insets.
+<p>The provider exposes the following context values via <code>useThemeContext()</code> hook:</p>
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>themeName</code></td>
+      <td><code>string</code></td>
+      <td>The current active theme key.</td>
+    </tr>
+    <tr>
+      <td><code>setThemeName</code></td>
+      <td><code>function</code></td>
+      <td>Set the active theme by key.</td>
+    </tr>
+    <tr>
+      <td><code>availableThemes</code></td>
+      <td><code>Array</code></td>
+      <td>List of available theme metadata objects.</td>
+    </tr>
+    <tr>
+      <td><code>toggleTheme</code></td>
+      <td><code>function</code></td>
+      <td>Toggle between themes or set a specific theme.</td>
+    </tr>
+    <tr>
+      <td><code>getThemeMeta</code></td>
+      <td><code>function</code></td>
+      <td>Get metadata for a given theme key.</td>
+    </tr>
+  </tbody>
+</table>
+
+Here is a simple example demonstrating how to consume the context using the `useThemeContext()` hook:
+
+```jsx
+import React from 'react';
+import { useThemeContext } from 'this.gui';
+
+function ThemeInfo() {
+  const { themeName, setThemeName, availableThemes, toggleTheme, getThemeMeta } = useThemeContext();
+  return (
+    <div>
+      <p>Current Theme: {themeName}</p>
+      <button onClick={() => toggleTheme()}>Toggle Theme</button>
+      <ul>
+        {availableThemes.map(({ key, name }) => (
+          <li key={key}>
+            <button onClick={() => setThemeName(key)}>{name}</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+- `themeName`: The key of the currently active theme.
+- `setThemeName`: Function to change the active theme by specifying its key.
+- `availableThemes`: Array containing metadata about all themes available.
+- `toggleTheme`: Function to cycle through available themes or set a specific theme.
+- `getThemeMeta`: Function to retrieve metadata for a given theme key.