clampography 2.0.0-beta.2 → 2.0.0-beta.21

package/src/index.js

@@ -3,99 +3,247 @@ import { themes as builtInThemes } from "./themes.js";
 import baseStyles from "./base.js";
 import extraStyles from "./extra.js";
 
+// Import version from package.json
+import { version } from "../package.json" with { type: "json" };
+
+/**
+ * Helper to resolve boolean options from CSS configuration.
+ * CSS values often come as strings ("true"/"false"), which are both truthy in JS.
+ */
+const resolveBool = (value, defaultValue) => {
+  if (
+    value === "false" || value === false || value === "no" || value === "none"
+  ) return false;
+  if (value === "true" || value === true || value === "yes") return true;
+  return defaultValue;
+};
+
 /**
  * Main plugin function.
  */
-export default plugin.withOptions((options = {}) => {
-  return ({ addBase }) => {
-    // 1. Load Base and Extra styles
-    const includeBase = options.base ?? true;
-    const includeExtra = options.extra ?? false;
-
-    if (includeBase) addBase(baseStyles);
-    if (includeExtra) addBase(extraStyles);
-
-    // 2. Parse themes configuration
-    let configThemes = options.themes;
-
-    // Default values
-    let themesToInclude = [];
-    let defaultThemeName = "light";
-    let prefersDarkTheme = false;
-    let rootSelector = options.root ?? ":root";
-
-    // Normalize input to an array of strings
-    // CSS might pass this as a single long string separated by commas
-    let rawThemeList = [];
-
-    if (typeof configThemes === "string") {
-      if (configThemes.trim() === "all") {
-        // Special case: themes: all
-        rawThemeList = Object.keys(builtInThemes);
-      } else if (configThemes.trim() === "false") {
-        rawThemeList = [];
-      } else {
-        // Split by comma: "light --default, dark --prefersdark"
-        rawThemeList = configThemes.split(",");
-      }
-    } else if (Array.isArray(configThemes)) {
-      rawThemeList = configThemes;
-    } else {
-      // Default fallback if nothing provided
-      rawThemeList = ["light", "dark"];
-    }
-
-    // 3. Process the list and look for flags (--default, --prefersdark)
-    // If "all" was used, we don't look for flags (we use default light/dark logic) unless implemented otherwise.
-    // Here we focus on the explicit list.
-
-    rawThemeList.forEach((rawItem) => {
-      let themeName = rawItem.trim();
-
-      // Ignore empty entries
-      if (!themeName) return;
-
-      // Check for --default flag
-      if (themeName.includes("--default")) {
-        themeName = themeName.replace("--default", "").trim();
-        defaultThemeName = themeName;
-      }
-
-      // Check for --prefersdark flag (case insensitive just in case)
-      if (themeName.toLowerCase().includes("--prefersdark")) {
-        themeName = themeName.replace(/--prefersdark/i, "").trim();
-        prefersDarkTheme = themeName;
-      }
-
-      // Check if theme exists in the database
-      if (builtInThemes[themeName]) {
-        themesToInclude.push(themeName);
-      }
-    });
-
-    // If list is empty after filtering, stop here
-    if (themesToInclude.length === 0) return;
-
-    // 4. Generate CSS
-    const themeStyles = {};
-
-    // A. Default theme (:root)
-    if (builtInThemes[defaultThemeName]) {
-      themeStyles[rootSelector] = builtInThemes[defaultThemeName];
-    }
-
-    // B. Theme for prefers-color-scheme: dark
-    if (prefersDarkTheme && builtInThemes[prefersDarkTheme]) {
-      themeStyles["@media (prefers-color-scheme: dark)"] = {
-        [rootSelector]: builtInThemes[prefersDarkTheme],
+export default plugin.withOptions(
+  (() => {
+    let firstRun = true; // Track first run for logging
+
+    return (options = {}) => {
+      return ({ addBase }) => {
+        // Extract logs option (default: true)
+        const showLogs = resolveBool(options.logs, true);
+
+        // Show startup log only once
+        if (showLogs && firstRun) {
+          console.log(`🍀 Clampography v${version} loaded successfully`);
+          firstRun = false;
+        }
+
+        // 1. Load Base and Extra styles
+        // We use the helper to correctly parse "false" string from CSS
+        const includeBase = resolveBool(options.base, true); // Default: true
+        const includeExtra = resolveBool(options.extra, false); // Default: false
+
+        // Pass options to the style functions to enable scoping
+        includeBase && addBase(baseStyles(options));
+        includeExtra && addBase(extraStyles(options));
+
+        // 2. Parse themes configuration
+        let configThemes = options.themes;
+        let themesToInclude = [];
+        let defaultThemeName = null;
+        let prefersDarkTheme = false;
+        let rootSelector = options.root || ":root";
+        let isAllThemes = false; // Track if user specified "all"
+
+        // Normalize input to an array of strings
+        let rawThemeList = [];
+        if (typeof configThemes === "string") {
+          if (["all", "true", "yes"].includes(configThemes.trim())) {
+            // Special case: themes: all
+            isAllThemes = true;
+            rawThemeList = Object.keys(builtInThemes);
+          } else if (["false", "none", "no"].includes(configThemes.trim())) {
+            // Explicitly disabled themes
+            rawThemeList = [];
+          } else {
+            rawThemeList = configThemes.split(",");
+          }
+        } else if (Array.isArray(configThemes)) {
+          rawThemeList = configThemes;
+        } else {
+          // Default behavior: NO themes loaded automatically.
+          // User must specify themes to load them.
+          rawThemeList = [];
+        }
+
+        // 3. Process the list and look for flags (--default, --prefersdark)
+        rawThemeList.forEach((rawItem) => {
+          let themeName = rawItem.trim();
+
+          // Ignore empty entries
+          if (!themeName) return;
+
+          // Check for --default flag
+          if (themeName.includes("--default")) {
+            themeName = themeName.replace("--default", "").trim();
+            defaultThemeName = themeName;
+          }
+
+          // Check for --prefersdark flag
+          if (themeName.toLowerCase().includes("--prefersdark")) {
+            themeName = themeName.replace(/--prefersdark/i, "").trim();
+            prefersDarkTheme = themeName;
+          }
+
+          // Check if theme exists in the database
+          if (builtInThemes[themeName]) {
+            themesToInclude.push(themeName);
+          }
+        });
+
+        // 4. Auto-configure defaults for "themes: all"
+        if (isAllThemes) {
+          if (!defaultThemeName) {
+            if (themesToInclude.includes("light")) {
+              defaultThemeName = "light";
+            } else if (themesToInclude.length > 0) {
+              defaultThemeName = themesToInclude[0];
+            }
+          }
+          if (!prefersDarkTheme && themesToInclude.includes("dark")) {
+            prefersDarkTheme = "dark";
+          }
+        }
+
+        // LOGGING: Built-in themes summary
+        if (showLogs) {
+          const explicitlyDisabled = ["false", "no", "none"].includes(
+            String(options.themes).trim(),
+          );
+
+          if (themesToInclude.length > 0) {
+            const themesList = themesToInclude.map((theme) => {
+              const flags = [];
+              if (theme === defaultThemeName) flags.push("default");
+              if (theme === prefersDarkTheme) flags.push("prefersdark");
+
+              const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+              return `${theme}${flagStr}`;
+            });
+
+            console.log(
+              `🍀 Clampography: Loaded ${themesToInclude.length} built-in themes: ${
+                themesList.join(", ")
+              }`,
+            );
+          } else if (!explicitlyDisabled) {
+            console.info("ℹ️ Clampography: No built-in themes loaded.");
+          }
+        }
+
+        // Final check before generating CSS
+        if (
+          themesToInclude.length === 0 && !defaultThemeName && !prefersDarkTheme
+        ) return;
+
+        // 5. Generate CSS
+        const themeStyles = {};
+
+        // A. Default theme - uses :where() for lower specificity
+        // Helper to combine root and data-theme
+        // If root is ":root", we use "html[data-theme...]" for backwards compatibility.
+        // If root is custom (e.g. "#morda"), we generate "#morda[data-theme...]"
+        const getThemeSelector = (themeName) => {
+          if (rootSelector === ":root") {
+            return `html[data-theme="${themeName}"], [data-theme="${themeName}"]`;
+          }
+          // For custom root, attach data-theme directly to it
+          // AND allow a nested data-theme inside it (optional, but good for nesting)
+          return `${rootSelector}[data-theme="${themeName}"], ${rootSelector} [data-theme="${themeName}"]`;
+        };
+
+        // A. Default theme
+        if (defaultThemeName && builtInThemes[defaultThemeName]) {
+          // Default variables applied to the root element itself without data-theme attribute
+          // uses :where() for lower specificity so it can be overridden
+          const defaultSelector = `:where(${rootSelector})`;
+
+          // Also apply if explicitly selected
+          const explicitSelector = getThemeSelector(defaultThemeName);
+
+          themeStyles[`${defaultSelector}, ${explicitSelector}`] =
+            builtInThemes[defaultThemeName];
+        }
+
+        // B. Theme for prefers-color-scheme: dark
+        if (prefersDarkTheme && builtInThemes[prefersDarkTheme]) {
+          themeStyles["@media (prefers-color-scheme: dark)"] = {
+            [rootSelector]: builtInThemes[prefersDarkTheme],
+          };
+        }
+
+        // C. All themes available via [data-theme] attribute
+        themesToInclude.forEach((themeName) => {
+          if (themeName === defaultThemeName) return;
+          const selector = getThemeSelector(themeName);
+          themeStyles[selector] = builtInThemes[themeName];
+        });
+
+        // D. Override media query with data-theme selectors
+        if (prefersDarkTheme) {
+          themeStyles["@media (prefers-color-scheme: dark)"] = {
+            ...themeStyles["@media (prefers-color-scheme: dark)"],
+          };
+
+          themesToInclude.forEach((themeName) => {
+            if (themeName === prefersDarkTheme) return;
+            const selector = getThemeSelector(themeName);
+
+            if (!themeStyles["@media (prefers-color-scheme: dark)"][selector]) {
+              themeStyles["@media (prefers-color-scheme: dark)"][selector] =
+                builtInThemes[themeName];
+            }
+          });
+        }
+
+        addBase(themeStyles);
       };
-    }
-
-    // C. Scoped styles [data-theme="..."]
-    themesToInclude.forEach((themeName) => {
-      themeStyles[`[data-theme="${themeName}"]`] = builtInThemes[themeName];
-    });
-
-    addBase(themeStyles);
-  };
-});
+    };
+  })(),
+  // Theme extension - enables utilities like bg-surface, text-heading, etc.
+  (options = {}) => {
+    // ✅ Extract prefix option (default: "clampography")
+    // This prefix is ONLY used for Tailwind utility classes (e.g., bg-clampography-primary)
+    // CSS variables remain unchanged (always --clampography-*)
+    const prefixEnabled = resolveBool(options.prefix, true);
+    const prefix = prefixEnabled
+      ? (typeof options.prefix === "string" &&
+          !["false", "no", "none", "true"].includes(options.prefix)
+        ? options.prefix
+        : "clampography")
+      : "";
+
+    // Helper to add prefix with separator
+    const addPrefix = (name) => prefix ? `${prefix}-${name}` : name;
+
+    return {
+      theme: {
+        extend: {
+          colors: {
+            [addPrefix("background")]: "var(--clampography-background)",
+            [addPrefix("border")]: "var(--clampography-border)",
+            [addPrefix("error")]: "var(--clampography-error)",
+            [addPrefix("heading")]: "var(--clampography-heading)",
+            [addPrefix("info")]: "var(--clampography-info)",
+            [addPrefix("link")]: "var(--clampography-link)",
+            [addPrefix("muted")]: "var(--clampography-muted)",
+            [addPrefix("primary")]: "var(--clampography-primary)",
+            [addPrefix("secondary")]: "var(--clampography-secondary)",
+            [addPrefix("success")]: "var(--clampography-success)",
+            [addPrefix("surface")]: "var(--clampography-surface)",
+            [addPrefix("text")]: "var(--clampography-text)",
+            [addPrefix("warning")]: "var(--clampography-warning)",
+          },
+        },
+      },
+    };
+  },
+);

package/src/theme-plugin.js

@@ -1,70 +1,130 @@
 import plugin from "tailwindcss/plugin";
-
-// List of required color keys for validation (optional but good practice)
-const REQUIRED_KEYS = [
-  "--clampography-background",
-  "--clampography-text",
-  "--clampography-link",
-  "--clampography-primary",
-  "--clampography-secondary",
-];
+import { themes as builtInThemes } from "./themes.js";
 
 export default plugin.withOptions((options = {}) => {
   return ({ addBase }) => {
     // 1. Extract metadata
     const themeName = options.name;
     const isDefault = options.default ?? false;
-    const isPrefersDark = options.prefersdark ?? false; // lowercase because CSS might force it
-    const rootSelector = options.root ?? ":root";
+    const isPrefersDark = options.prefersdark ?? false;
+    const rootSelector = options.root || ":root";
+    const colorScheme = options["color-scheme"] ?? "light";
+
+    // This option is completely separate from the main plugin's logs option
+    const showLogs = options.logs !== false;
 
     if (!themeName) {
-      console.warn("Clampography: Theme definition missing 'name' property.");
+      if (showLogs) {
+        console.warn(
+          "🍀 Clampography: Theme definition missing 'name' property.",
+        );
+      }
       return;
     }
 
-    // 2. Extract colors from options
-    // We iterate over the options object and pick anything that looks like our CSS variable
-    // or simply take all known keys.
-    const themeColors = {};
+    // LOGGING: Custom theme loaded
+    if (showLogs) {
+      const flags = [];
+      if (isDefault) flags.push("Default");
+      if (isPrefersDark) flags.push("Dark Pref");
+      const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+
+      console.log(
+        `✨ Clampography: Loaded custom theme "${themeName}"${flagStr}`,
+      );
+    }
 
-    // You can also support short aliases here if you want (e.g., 'primary' -> '--clampography-primary')
-    // For now, let's assume user passes full variable names or mapped keys.
+    // 2. Prepare Base Colors (Fallback)
+    // We fetch the full palette of the requested color scheme (light/dark)
+    // to fill in any missing gaps in the user's definition.
+    const fallbackTheme = builtInThemes[colorScheme] || builtInThemes["light"];
 
-    // Helper to map simplified keys to full CSS vars (optional convenience)
+    // 3. Extract & Merge Colors
+    const themeColors = {};
+
+    // Mapping of simplified keys to full CSS variable names
     const keyMap = {
       "background": "--clampography-background",
-      "surface": "--clampography-surface",
       "border": "--clampography-border",
+      "error": "--clampography-error",
       "heading": "--clampography-heading",
-      "text": "--clampography-text",
-      "muted": "--clampography-muted",
+      "info": "--clampography-info",
       "link": "--clampography-link",
+      "muted": "--clampography-muted",
       "primary": "--clampography-primary",
       "secondary": "--clampography-secondary",
+      "success": "--clampography-success",
+      "surface": "--clampography-surface",
+      "text": "--clampography-text",
+      "warning": "--clampography-warning",
     };
 
+    // First, populate with fallback colors
+    Object.keys(fallbackTheme).forEach((key) => {
+      themeColors[key] = fallbackTheme[key];
+    });
+
+    // Then override with user provided values
     Object.keys(options).forEach((key) => {
-      // Check if it's one of our mapped short keys
+      // Ignore metadata keys
+      if (
+        ["name", "default", "prefersdark", "root", "color-scheme", "logs"]
+          .includes(key)
+      ) return;
+
+      const value = options[key];
+
       if (keyMap[key]) {
-        themeColors[keyMap[key]] = options[key];
-      } // Or if it is already a custom property key (starts with --)
-      else if (key.startsWith("--")) {
-        themeColors[key] = options[key];
+        // Validate color format (only if logs enabled)
+        if (showLogs && value && typeof value === "string") {
+          // Check if value starts with oklch() or is a valid CSS color
+          const isOklch = value.trim().startsWith("oklch(");
+          const isHex = /^#[0-9A-Fa-f]{3,8}$/.test(value.trim());
+          const isRgb = value.trim().startsWith("rgb(") ||
+            value.trim().startsWith("rgba(");
+
+          if (!isOklch && !isHex && !isRgb) {
+            console.warn(
+              `Clampography (${themeName}): Color "${key}" has value "${value}" which may not be a valid color format. ` +
+                `For best compatibility with opacity modifiers (e.g., bg-${key}/20), use full OKLCH format: ` +
+                `oklch(70% 0.2 180) or oklch(0.7 0.2 180)`,
+            );
+          }
+
+          if (isHex || isRgb) {
+            console.info(
+              `🍀 Clampography (${themeName}): Color "${key}" uses ${
+                isHex ? "HEX" : "RGB"
+              } format. ` +
+                `Consider using OKLCH format for better color space support and smoother gradients.`,
+            );
+          }
+        }
+
+        themeColors[keyMap[key]] = value;
+      } else if (key.startsWith("--")) {
+        themeColors[key] = value;
       }
     });
 
-    // 3. Generate Styles
+    // Add the CSS property 'color-scheme' for browser UI adaptation (scrollbars, etc.)
+    themeColors["color-scheme"] = colorScheme;
+
+    // 4. Generate Styles
     const styles = {};
 
-    // A. Define the theme as a named data-theme (always available)
-    styles[`[data-theme="${themeName}"]`] = themeColors;
+    // Build selector based on flags
+    let selector = `[data-theme="${themeName}"]`;
 
-    // B. If marked as default, apply to :root
+    // If default, prepend :where(root) with lower specificity
     if (isDefault) {
-      styles[rootSelector] = themeColors;
+      selector = `:where(${rootSelector}),${selector}`;
     }
 
-    // C. If marked as prefers-dark, apply to media query
+    // Apply theme to the constructed selector
+    styles[selector] = themeColors;
+
+    // If prefers-dark, apply only to root selector in media query
     if (isPrefersDark) {
       styles["@media (prefers-color-scheme: dark)"] = {
         [rootSelector]: themeColors,

package/src/themes.js

@@ -1,47 +1,67 @@
 export const themes = {
   light: {
-    "--clampography-background": "#ffffff",
-    "--clampography-surface": "#f3f4f6",
-    "--clampography-border": "#e5e7eb",
-    "--clampography-heading": "#111827",
-    "--clampography-text": "#374151",
-    "--clampography-muted": "#6b7280",
-    "--clampography-link": "#2563eb",
-    "--clampography-primary": "#3b82f6",
-    "--clampography-secondary": "#9333ea",
+    "color-scheme": "light",
+    "--clampography-background": "oklch(100% 0 0)",
+    "--clampography-border": "oklch(92% 0.003 264)",
+    "--clampography-error": "oklch(63% 0.22 27)",
+    "--clampography-heading": "oklch(15% 0.02 264)",
+    "--clampography-info": "oklch(63% 0.258 262)",
+    "--clampography-link": "oklch(43% 0.19 264)",
+    "--clampography-muted": "oklch(52% 0.014 258)",
+    "--clampography-primary": "oklch(63% 0.258 262)",
+    "--clampography-secondary": "oklch(55% 0.28 300)",
+    "--clampography-success": "oklch(65% 0.17 165)",
+    "--clampography-surface": "oklch(96% 0.003 264)",
+    "--clampography-text": "oklch(31% 0.02 257)",
+    "--clampography-warning": "oklch(72% 0.17 65)",
   },
   dark: {
-    "--clampography-background": "#0f172a",
-    "--clampography-surface": "#1e293b",
-    "--clampography-border": "#334155",
-    "--clampography-heading": "#f8fafc",
-    "--clampography-text": "#cbd5e1",
-    "--clampography-muted": "#94a3b8",
-    "--clampography-link": "#60a5fa",
-    "--clampography-primary": "#3b82f6",
-    "--clampography-secondary": "#a855f7",
+    "color-scheme": "dark",
+    "--clampography-background": "oklch(10% 0 0)",
+    "--clampography-border": "oklch(31% 0.03 254)",
+    "--clampography-error": "oklch(63% 0.22 27)",
+    "--clampography-heading": "oklch(98% 0.003 264)",
+    "--clampography-info": "oklch(72% 0.17 254)",
+    "--clampography-link": "oklch(72% 0.17 254)",
+    "--clampography-muted": "oklch(68% 0.024 254)",
+    "--clampography-primary": "oklch(63% 0.258 262)",
+    "--clampography-secondary": "oklch(63% 0.25 300)",
+    "--clampography-success": "oklch(65% 0.17 165)",
+    "--clampography-surface": "oklch(12% 0 0)",
+    "--clampography-text": "oklch(95% 0 0)",
+    "--clampography-warning": "oklch(72% 0.17 65)",
   },
   retro: {
-    "--clampography-background": "#ece3ca",
-    "--clampography-surface": "#e0d6b6",
-    "--clampography-border": "#cbbd99",
-    "--clampography-heading": "#2c2420",
-    "--clampography-text": "#4a3b32",
-    "--clampography-muted": "#756354",
-    "--clampography-link": "#d97757",
-    "--clampography-primary": "#e45f2b",
-    "--clampography-secondary": "#f6c342",
+    "color-scheme": "light",
+    "--clampography-background": "oklch(91% 0.03 85)",
+    "--clampography-border": "oklch(78% 0.05 85)",
+    "--clampography-error": "oklch(52% 0.15 35)",
+    "--clampography-heading": "oklch(18% 0.02 35)",
+    "--clampography-info": "oklch(60% 0.06 230)",
+    "--clampography-link": "oklch(63% 0.13 40)",
+    "--clampography-muted": "oklch(44% 0.03 45)",
+    "--clampography-primary": "oklch(60% 0.19 35)",
+    "--clampography-secondary": "oklch(80% 0.14 85)",
+    "--clampography-success": "oklch(62% 0.10 130)",
+    "--clampography-surface": "oklch(87% 0.04 85)",
+    "--clampography-text": "oklch(28% 0.03 40)",
+    "--clampography-warning": "oklch(80% 0.14 85)",
   },
   cyberpunk: {
-    "--clampography-background": "#000b1e",
-    "--clampography-surface": "#051630",
-    "--clampography-border": "#0f3661",
-    "--clampography-heading": "#ffffff",
-    "--clampography-text": "#00f0ff",
-    "--clampography-muted": "#008f99",
-    "--clampography-link": "#ff0099",
-    "--clampography-primary": "#fcee0a",
-    "--clampography-secondary": "#05ffa1",
+    "color-scheme": "dark",
+    "--clampography-background": "oklch(8% 0.04 264)",
+    "--clampography-border": "oklch(27% 0.09 254)",
+    "--clampography-error": "oklch(60% 0.29 340)",
+    "--clampography-heading": "oklch(100% 0 0)",
+    "--clampography-info": "oklch(88% 0.16 195)",
+    "--clampography-link": "oklch(60% 0.29 340)",
+    "--clampography-muted": "oklch(55% 0.07 200)",
+    "--clampography-primary": "oklch(93% 0.22 105)",
+    "--clampography-secondary": "oklch(87% 0.20 165)",
+    "--clampography-success": "oklch(87% 0.20 165)",
+    "--clampography-surface": "oklch(12% 0.05 264)",
+    "--clampography-text": "oklch(88% 0.16 195)",
+    "--clampography-warning": "oklch(93% 0.22 105)",
   },
 };
 

package/src/types/index.d.ts

@@ -0,0 +1,14 @@
+import type { Config, PluginCreator } from "tailwindcss/types/config";
+
+interface ClampographyOptions {
+  themes?: string | string[] | boolean;
+  base?: boolean;
+  extra?: boolean;
+  root?: string;
+  prefix?: string | boolean;
+  logs?: boolean;
+}
+
+declare const clampographyPlugin: PluginCreator<ClampographyOptions>;
+
+export default clampographyPlugin;