this.gui 1.0.18 → 1.1.0

package/src/themes/icons/registry.tsx

@@ -0,0 +1,178 @@
+//src/themes/icons/registry.tsx
+import * as React from 'react';
+import lucidePack, { LUCIDE_PREFIX, getLucideIcon, normalizeLucideName } from './packs/Lucide';
+import muiPack, { MUI_PREFIX } from './packs/Material';
+
+export type LazyIconComp = React.LazyExoticComponent<React.ComponentType<any>>;
+
+export interface IconProvider {
+  key: string;
+  resolve: (name: string) => LazyIconComp;
+  exists?: (name: string) => boolean;
+}
+
+/**
+ * Icon registry (pluggable)
+ * -------------------------
+ * Providers supported out of the box:
+ *  - lucide:*  → lucide-react (tree-shakable, lightweight)
+ *  - mui:*     → @mui/icons-material (richer set; heavier)
+ *
+ * You can register more providers from your app:
+ *   import { registerIconProvider } from '@this-gui/icons/registry';
+ *   registerIconProvider('custom', {
+ *     resolve: (name) => React.lazy(() => import('./MyIcon').then(m => ({ default: m.MyIcon }))),
+ *     // optional: exists(name): boolean
+ *   });
+ *
+ * All resolvers return a React element type (via React.lazy) so consumers can
+ * render them in a Suspense boundary uniformly.
+ */
+
+// ---------- fallback / placeholder ----------
+function emptyIconFactory(name: string = 'unknown'): LazyIconComp {
+  type PlaceholderProps = {
+    size?: number;
+    color?: string;
+    style?: React.CSSProperties;
+    title?: string;
+    [key: string]: any;
+  };
+  const Placeholder: React.FC<PlaceholderProps> = ({ size = 20, color = 'currentColor', style, title, ...rest }) => (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role={title ? 'img' : 'presentation'}
+      aria-hidden={title ? undefined : true}
+      aria-label={title || undefined}
+      style={{ display: 'inline-block', verticalAlign: 'middle', ...style }}
+      {...rest}
+    >
+      {title ? <title>{title}</title> : null}
+      <circle cx="12" cy="12" r="9" opacity="0.25" />
+      <path d="M9.5 9a3 3 0 0 1 5 2c0 2-3 2-3 4" />
+      <circle cx="12" cy="17" r="0.75" />
+    </svg>
+  );
+  Placeholder.displayName = `IconPlaceholder(${String(name)})`;
+  const Lazy = React.lazy(() => Promise.resolve({ default: Placeholder }));
+  return Lazy as LazyIconComp;
+}
+
+// ---------- helpers ----------
+const hasPrefix = (raw: string, prefix: string): boolean =>
+  raw.toLowerCase().startsWith(prefix.toLowerCase() + ':') ||
+  raw.toLowerCase().startsWith(prefix.toLowerCase() + '/');
+
+const stripPrefix = (raw: string, prefix: string): string =>
+  raw.replace(new RegExp(`^${prefix}[:/.-]\\s*`, 'i'), '');
+
+// ---------- built-in providers ----------
+/**
+ * Lucide provider adapter
+ *  - Dynamically import lucide-react and resolve the named export at runtime.
+ */
+const lucideLazyCache = new Map<string, LazyIconComp>();
+
+const lucideProvider: IconProvider = {
+  key: LUCIDE_PREFIX,
+  resolve: (rawName: string) => {
+    const key = stripPrefix(rawName, LUCIDE_PREFIX);
+    const pascal = normalizeLucideName(key);
+
+    if (lucideLazyCache.has(pascal)) {
+      return lucideLazyCache.get(pascal)!;
+    }
+
+    const Lazy = React.lazy(async () => {
+      const mod: any = await import('lucide-react');
+      const lib: Record<string, any> = (typeof mod.default === 'object' && mod.default) ? mod.default : mod;
+      const Comp = lib[pascal] ?? lib.HelpCircle;
+      return { default: Comp };
+    });
+
+    lucideLazyCache.set(pascal, Lazy);
+    return Lazy as LazyIconComp;
+  },
+  exists: (name: string) => {
+    // Best-effort check using the already-imported pack (fast path)
+    try {
+      const Comp = getLucideIcon(stripPrefix(name, LUCIDE_PREFIX));
+      return Boolean(Comp);
+    } catch {
+      return false;
+    }
+  },
+};
+
+/**
+ * MUI provider adapter
+ *  - Material pack already returns React.lazy components via get(name)
+ */
+const muiProvider: IconProvider = {
+  key: MUI_PREFIX,
+  resolve: (rawName: string) => {
+    const Comp = muiPack.get(rawName) as LazyIconComp | undefined;
+    return Comp ?? emptyIconFactory(rawName);
+  },
+  exists: (name: string) => Boolean(muiPack.has?.(name)),
+};
+
+// ---------- pluggable registry ----------
+const _providers: Map<string, IconProvider> = new Map([
+  [lucideProvider.key, lucideProvider],
+  [muiProvider.key, muiProvider],
+]);
+
+export function registerIconProvider(key: string, provider: IconProvider): void {
+  if (!key || !provider || typeof provider.resolve !== 'function') {
+    throw new Error('[icons/registry] registerIconProvider(key, { resolve }) requires a valid resolver');
+  }
+  _providers.set(String(key).toLowerCase(), { ...provider, key });
+}
+
+export function getRegisteredProviders(): string[] {
+  return Array.from(_providers.keys());
+}
+
+// ---------- main resolver ----------
+export function lazyIcon(name: string): LazyIconComp {
+  const raw = String(name || '');
+  if (!raw) return emptyIconFactory('empty');
+
+  // Try prefixed first (e.g., mui:CameraAlt, lucide:home)
+  for (const [key, provider] of _providers) {
+    if (hasPrefix(raw, key)) {
+      try {
+        return provider.resolve(raw);
+      } catch {
+        return emptyIconFactory(raw);
+      }
+    }
+  }
+
+  // No prefix → choose a default order: prefer MUI (richer set), then Lucide
+  try {
+    return muiProvider.resolve(raw);
+  } catch {
+    try {
+      return lucideProvider.resolve(raw);
+    } catch {
+      return emptyIconFactory(raw);
+    }
+  }
+}
+
+export const PROVIDERS: { lucide: string; mui: string } = {
+  lucide: lucideProvider.key,
+  mui: muiProvider.key,
+};
+
+export { lucidePack, muiPack };
+export default { lazyIcon, registerIconProvider, getRegisteredProviders, PROVIDERS };

package/src/themes/index.js

@@ -0,0 +1,116 @@
+// src/themes/index.js
+// Global tokens shared by all themes (radius, spacing, zIndex, etc.)
+import globalTokens from './tokens/global.tokens.json';
+import { makeMuiTheme } from './fromTokens';
+// --- Built-in theme: neurons (manifest-driven) -------------------------------
+import neuronsManifest from './tokens/neurons/manifest.json';
+import neuronsLight from './tokens/neurons/light.tokens.json';
+import neuronsDark from './tokens/neurons/dark.tokens.json';
+/**
+ * Registry of built-in themes shipped with the library.
+ * Each entry couples a human-readable manifest (metadata) with the concrete
+ * token payloads for its available modes.
+ *
+ * NOTE: We import token JSONs statically so bundlers (Vite) can include them.
+ * The manifest gives us metadata (name, description, author, preview) and
+ * declares the available modes. If you add another built-in theme, mirror this
+ * structure.
+ */
+const BUILT_IN = {
+  neurons: {
+    manifest: neuronsManifest,
+    tokensByMode: {
+      light: neuronsLight,
+      dark: neuronsDark,
+    },
+  },
+};
+// -----------------------------------------------------------------------------
+// Factories
+// -----------------------------------------------------------------------------
+/** Create a MUI theme straight from token JSON + a mode. */
+export const createThemeFromTokens = (tokens, mode = 'light') => {
+  return makeMuiTheme(globalTokens, tokens, mode);
+};
+/**
+ * Create a MUI theme from a manifest entry and an optional preloaded map
+ * { light, dark, ... } of token JSON objects. For built-ins we pass them
+ * statically; for custom themes you can resolve them however you prefer.
+ */
+export const createThemeFromManifest = (manifest, mode = 'light', tokensByMode) => {
+  const m = manifest || {};
+  const chosenMode = mode || m.defaultMode || 'light';
+  // Prefer explicitly provided tokensByMode (preloaded).
+  const tokens =
+    tokensByMode?.[chosenMode] ??
+    // Optional: if your manifest inlines tokens under modes[mode].inlineTokens
+    m?.modes?.[chosenMode]?.inlineTokens ??
+    null;
+
+  if (!tokens) {
+    // Fallback to light/dark if available; last resort throw a helpful error.
+    const fallback =
+      tokensByMode?.light ??
+      tokensByMode?.dark ??
+      null;
+    if (!fallback) {
+      throw new Error(
+        `[themes] No tokens found for mode "${chosenMode}". ` +
+          `Provide a tokensByMode map or inline tokens in the manifest.`
+      );
+    }
+    return createThemeFromTokens(fallback, chosenMode);
+  }
+  return createThemeFromTokens(tokens, chosenMode);
+};
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * getTheme
+ * - Prefer passing a manifest and (optionally) a tokensByMode map for custom themes.
+ * - For built-ins, use key: 'neurons' with a mode, or legacy keys 'neurons-light'/'neurons-dark'.
+ *
+ * Examples:
+ *   getTheme({ key: 'neurons', mode: 'dark' })
+ *   getTheme({ manifest, mode: 'light', tokensByMode: { light, dark } })
+ *   getTheme({ tokens, mode: 'light' }) // direct tokens
+ */
+export const getTheme = ({ key, mode, manifest, tokens, tokensByMode } = {}) => {
+  // 1) Direct tokens take precedence
+  if (tokens) return createThemeFromTokens(tokens, mode || 'light');
+  // 2) Manifest-driven (custom or built-in)
+  if (manifest) return createThemeFromManifest(manifest, mode || 'light', tokensByMode);
+  // 3) Built-ins by key (preferred: 'neurons' + mode)
+  if (key && BUILT_IN[key]) {
+    const entry = BUILT_IN[key];
+    return createThemeFromManifest(entry.manifest, mode || 'light', entry.tokensByMode);
+  }
+  // 4) Legacy keys support ('neurons-light' | 'neurons-dark')
+  if (key === 'neurons-light') {
+    return createThemeFromManifest(BUILT_IN.neurons.manifest, 'light', BUILT_IN.neurons.tokensByMode);
+  }
+  if (key === 'neurons-dark') {
+    return createThemeFromManifest(BUILT_IN.neurons.manifest, 'dark', BUILT_IN.neurons.tokensByMode);
+  }
+  // 5) Default fallback → neurons dark
+  return createThemeFromManifest(BUILT_IN.neurons.manifest, 'dark', BUILT_IN.neurons.tokensByMode);
+};
+
+/**
+ * AVAILABLE_THEMES
+ * - Minimal info for theme pickers / galleries. Pulled from each manifest.
+ */
+export const AVAILABLE_THEMES = Object.entries(BUILT_IN).flatMap(([familyId, entry]) => {
+  const m = entry.manifest || {};
+  const modes = Object.keys(m.modes || { light: {}, dark: {} });
+  return modes.map((mode) => ({
+    key: familyId,                        // ← Add this line
+    id: `${familyId}-${mode}`,           
+    family: familyId,                    
+    name: `${m.name || familyId} ${mode === 'light' ? 'Light' : 'Dark'}`,
+    mode,
+    // opcional: pasa el manifest completo si tu selector lo usa
+    manifest: m,
+  }));
+});

package/src/themes/theme.d.ts

@@ -0,0 +1,116 @@
+// src/themes/theme.d.ts
+// src/themes/theme.d.ts
+// ---------- This.GUI Theme Manifest types (library-level, not part of MUI) ----------
+export type ThemeIcon =
+  | { type: 'mui' | 'lucide'; value: string }    // icon token from a known set
+  | { type: 'url'; value: string }               // URL to an image (svg/png)
+  | { type: 'svg'; value: string }               // inline SVG markup
+  | { type: 'data'; value: string };             // data URI
+
+/**
+ * ThemeManifest
+ * Describes a theme package and the paths to its light/dark token files.
+ * This is metadata for discovery/marketplace; it is intentionally separate
+ * from the runtime MUI Theme type augmentation below.
+ */
+export type ThemeManifest = {
+  id: string;
+  name: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  license?: string;
+  homepage?: string;
+  repository?: { type: string; url: string };
+  tags?: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  icon?: ThemeIcon;  // Optional theme icon for listings
+  modes: {
+    light: { path: string };
+    dark: { path: string };
+  };
+};
+import '@mui/material/styles';
+declare module '@mui/material/styles' {
+  // -----------------------------
+  // Palette extensions
+  // -----------------------------
+  interface TypeBackground {
+    /** Custom background color for navigation surfaces (e.g., AppBar). */
+    nav?: string;
+  }
+
+  interface Palette {
+    /** Default/iconic color separate from text/action semantics. */
+    icon: Palette['primary'];
+    /** Link colors (normal + optional visited). */
+    link: { main: string; visited?: string };
+  }
+  interface PaletteOptions {
+    icon?: PaletteOptions['primary'];
+    link?: { main: string; visited?: string };
+  }
+
+  // -----------------------------
+  // Typography extensions
+  // -----------------------------
+  interface TypographyVariants {
+    /** Optional helper scale for line-heights used by generators/utilities. */
+    lineHeights?: {
+      tight?: number;
+      normal?: number;
+      relaxed?: number;
+      [key: string]: number | undefined;
+    };
+  }
+  interface TypographyVariantsOptions {
+    lineHeights?: {
+      tight?: number;
+      normal?: number;
+      relaxed?: number;
+      [key: string]: number | undefined;
+    };
+  }
+
+  // -----------------------------
+  // Theme extensions
+  // -----------------------------
+  interface Theme {
+    /** Runtime layout insets coordinated by NavBar/Drawers (pixels). */
+    layout: {
+      insets: { left: number; right: number; nav: number };
+    };
+    /** Callback exposed by GuiProvider to update insets at runtime. */
+    updateInsets?: (v: Partial<{ left: number; right: number; nav: number }>) => void;
+    /** Bag for tokens that don't map 1:1 to MUI. */
+    custom?: {
+      border?: string;
+      gradients?: unknown;
+      overlays?: unknown;
+      iconSizes?: Record<string, unknown>;
+      lineHeights?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+    /** (Optional) legacy insets for backwards compatibility. */
+    insets?: { left?: number; right?: number; nav?: number };
+  }
+
+  interface ThemeOptions {
+    layout?: {
+      insets?: Partial<{ left: number; right: number; nav: number }>;
+    };
+    updateInsets?: (v: Partial<{ left: number; right: number; nav: number }>) => void;
+    custom?: {
+      border?: string;
+      gradients?: unknown;
+      overlays?: unknown;
+      iconSizes?: Record<string, unknown>;
+      lineHeights?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+    insets?: Partial<{ left: number; right: number; nav: number }>;
+  }
+}
+
+export {};

package/src/themes/tokens/global.tokens.json

@@ -0,0 +1,107 @@
+{
+  "$description": "Global design tokens for This.GUI — base values shared across all themes.",
+  "radius": {
+    "md": {
+      "$type": "radius",
+      "$value": "10px"
+    }
+  },
+  "spacing": {
+    "base": {
+      "$type": "spacing",
+      "$value": "8"
+    }
+  },
+  "border": {
+    "default": {
+      "$type": "color",
+      "$value": "rgba(0, 0, 0, 0.08)"
+    }
+  },
+  "font": {
+    "family": {
+      "$type": "fontFamily",
+      "$value": "Roboto, sans-serif"
+    },
+    "weightBold": {
+      "$type": "fontWeight",
+      "$value": "700"
+    },
+    "weightSemibold": {
+      "$type": "fontWeight",
+      "$value": "600"
+    },
+    "sizeBase": {
+      "$type": "fontSize",
+      "$value": "16"
+    },
+    "letterTight": {
+      "$type": "letterSpacing",
+      "$value": "-0.01em"
+    }
+  },
+  "color": {
+    "$description": "Extended semantic colors, gradients, overlays",
+    "success": { "$type": "color", "$value": "#4caf50" },
+    "warning": { "$type": "color", "$value": "#ff9800" },
+    "error": { "$type": "color", "$value": "#f44336" },
+    "info": { "$type": "color", "$value": "#2196f3" },
+    "gradientPrimary": { "$type": "gradient", "$value": "linear-gradient(135deg, #00aa96 0%, #008c7d 100%)" }
+  },
+  "insets": {
+    "$description": "Offsets reserved for permanent drawers",
+    "$type": "object",
+    "left": {
+      "$type": "size",
+      "$value": "0px"
+    },
+    "right": {
+      "$type": "size",
+      "$value": "0px"
+    }
+  },
+  "shadows": {
+    "$description": "Consistent elevation levels, AR/3D ready",
+    "sm": { "$type": "shadow", "$value": "0px 1px 2px rgba(0, 0, 0, 0.05)" },
+    "md": { "$type": "shadow", "$value": "0px 3px 6px rgba(0, 0, 0, 0.1)" },
+    "lg": { "$type": "shadow", "$value": "0px 8px 16px rgba(0, 0, 0, 0.15)" }
+  },
+  "zIndex": {
+    "$description": "Advanced layering control",
+    "nav": { "$type": "number", "$value": 1100 },
+    "modal": { "$type": "number", "$value": 1300 },
+    "tooltip": { "$type": "number", "$value": 1500 }
+  },
+  "breakpoints": {
+    "$description": "Declarative responsive interfaces",
+    "xs": { "$type": "breakpoint", "$value": "0px" },
+    "sm": { "$type": "breakpoint", "$value": "600px" },
+    "md": { "$type": "breakpoint", "$value": "900px" },
+    "lg": { "$type": "breakpoint", "$value": "1200px" },
+    "xl": { "$type": "breakpoint", "$value": "1536px" }
+  },
+  "motion": {
+    "$description": "Animation and transition tokens",
+    "durationFast": { "$type": "duration", "$value": "150ms" },
+    "durationBase": { "$type": "duration", "$value": "300ms" },
+    "easingStandard": { "$type": "easing", "$value": "cubic-bezier(0.4, 0, 0.2, 1)" }
+  },
+  "opacity": {
+    "$description": "Universal interaction effects",
+    "disabled": { "$type": "opacity", "$value": "0.38" },
+    "hover": { "$type": "opacity", "$value": "0.08" },
+    "focus": { "$type": "opacity", "$value": "0.12" }
+  },
+  "icon": {
+    "$description": "Scalable icon sizes for generated GUIs",
+    "sm": { "$type": "size", "$value": "16px" },
+    "md": { "$type": "size", "$value": "24px" },
+    "lg": { "$type": "size", "$value": "32px" }
+  },
+  "lineHeight": {
+    "$description": "Better typographic control",
+    "tight": { "$type": "lineHeight", "$value": "1.1" },
+    "base": { "$type": "lineHeight", "$value": "1.5" },
+    "relaxed": { "$type": "lineHeight", "$value": "1.75" }
+  }
+}

package/src/themes/tokens/neurons/dark.tokens.json

@@ -0,0 +1,45 @@
+{
+  "$description": "Neurons Dark Theme Tokens — overrides applied on top of global.tokens.json",
+  "id": "neurons-dark",
+  "color": {
+    "primary": {
+      "$type": "color",
+      "$value": "#90caf9"
+    },
+    "secondary": {
+      "$type": "color",
+      "$value": "#f48fb1"
+    },
+    "icon": {
+      "$type": "color",
+      "$value": "#a8a8a8"
+    },
+
+    "background": {
+      "default": { "$type": "color", "$value": "#121214" },
+      "paper":   { "$type": "color", "$value": "#181a1c" },
+      "nav": { "$type": "color", "$value": "rgba(18,18,20,0.95)" }
+    },
+
+    "textPrimary": {
+      "$type": "color",
+      "$value": "#ffffff"
+    },
+    "textSecondary": {
+      "$type": "color",
+      "$value": "rgba(255,255,255,0.75)"
+    },
+    "link": {
+      "$type": "color",
+      "$value": "#00aa96"
+    },
+    "linkVisited": {
+      "$type": "color",
+      "$value": "#008278"
+    },
+    "border": {
+      "$type": "color",
+      "$value": "rgb(45,45,55)"
+    }
+  }
+}

package/src/themes/tokens/neurons/light.tokens.json

@@ -0,0 +1,51 @@
+{
+  "$description": "Design tokens for neurons.light theme — part of This.GUI ecosystem",
+  "id": "neurons-light",
+  "extends": "global.tokens.json",
+  "color": {
+    "primary": {
+      "$type": "color",
+      "$value": "#0a3a42"
+    },
+    "secondary": {
+      "$type": "color",
+      "$value": "#e5396f"
+    },
+    "icon": {
+      "$type": "color",
+      "$value": "#5e5e5e"
+    },
+    "default": {
+      "$type": "color",
+      "$value": "#f8f9fa"
+    },
+    "paper": {
+      "$type": "color",
+      "$value": "#ffffff"
+    },
+    "nav": {
+      "$type": "color",
+      "$value": "#fdfdfd"
+    },
+    "textPrimary": {
+      "$type": "color",
+      "$value": "#111111"
+    },
+    "textSecondary": {
+      "$type": "color",
+      "$value": "#444444"
+    },
+    "link": {
+      "$type": "color",
+      "$value": "#008c7d"
+    },
+    "linkVisited": {
+      "$type": "color",
+      "$value": "#006e64"
+    },
+    "border": {
+      "$type": "color",
+      "$value": "rgba(0,0,0,0.08)"
+    }
+  }
+}

package/src/themes/tokens/neurons/manifest.json

@@ -0,0 +1,23 @@
+{
+  "id": "neurons.me",
+  "name": "neurons.me",
+  "description": "A modern, flexible theme for Neuroverse.",
+  "author": "suiGn",
+  "version": "1.0.0",
+  "license": "MIT",
+  "homepage": "https://neurons.me/themes/neurons",
+  "repository": { "type": "git", "url": "https://github.com/neurons/me-themes.git" },
+  "tags": ["official", "default"],
+  "createdAt": "2025-09-16T00:00:00.000Z",
+  "updatedAt": "2025-09-16T00:00:00.000Z",
+
+  "icon": {
+    "type": "mui",
+    "value": "Palette"
+  },
+
+  "modes": {
+    "light": { "path": "./light.tokens.json" },
+    "dark":  { "path": "./dark.tokens.json" }
+  }
+}

package/src/types/theme.d.ts

@@ -0,0 +1,32 @@
+// src/types/theme.d.ts
+import '@mui/material/styles';
+// Module augmentation so TS knows about our theme extensions injected by GuiProvider
+declare module '@mui/material/styles' {
+  /** Insets reported at runtime by NavBar/Drawers and read by layout components */
+  interface Insets {
+    left: number;
+    right: number;
+    nav: number;
+  }
+
+  /** Runtime theme (what useTheme() returns) */
+  interface Theme {
+    layout: { insets: Insets };
+    /** Callback to update insets; injected by GuiProvider */
+    updateInsets?: (next: Partial<Insets>) => void;
+    /** Optional legacy field for back-compat (some code reads theme.insets) */
+    insets?: Partial<Insets>;
+    /** Parking spot for all design tokens not mapped natively to MUI */
+    custom: Record<string, any>;
+  }
+
+  /** Accepted options when creating the theme */
+  interface ThemeOptions {
+    layout?: { insets?: Partial<Insets> };
+    updateInsets?: (next: Partial<Insets>) => void;
+    /** Optional legacy field for back-compat */
+    insets?: Partial<Insets>;
+    /** Parking spot for all design tokens not mapped natively to MUI */
+    custom?: Record<string, any>;
+  }
+}