clampography 2.0.0-beta.9 → 2.0.0

package/src/kbd.js

@@ -0,0 +1,88 @@
+export default (options = {}) => {
+  const root = options.root || ":root";
+
+  // Helper to scope selectors safely (ignoring commas inside parentheses)
+  const scope = (selector) => {
+    const parts = [];
+    let current = "";
+    let depth = 0;
+
+    for (let i = 0; i < selector.length; i++) {
+      const char = selector[i];
+      if (char === "(") depth++;
+      if (char === ")") depth--;
+      if (char === "," && depth === 0) {
+        parts.push(current.trim());
+        current = "";
+      } else {
+        current += char;
+      }
+    }
+    parts.push(current.trim());
+
+    return parts
+      .filter(Boolean)
+      .map((part) => {
+        if (part === ":root" || part === "body") return root;
+        return `${root} ${part}`;
+      })
+      .join(", ");
+  };
+
+  return {
+    // ── <kbd> — 3D isometric keyboard key effect ──────────────────────────────
+    //
+    // The illusion is built from three layers:
+    //   1. Key face  → background-color of the element itself
+    //   2. Key depth → first box-shadow layer (the visible "side" of the key)
+    //   3. Key cast  → second box-shadow layer (subtle drop shadow)
+    //
+    // rgba() overlays are used for the depth/cast so the effect adapts
+    // automatically to any background (works on light AND dark themes).
+    // Theme variables are used for the face/border when available.
+
+    [scope("kbd")]: {
+      "display": "inline-block",
+      "padding": "0.1em 0.45em",
+      "min-width": "2em",
+      "text-align": "center",
+      "font-size": "0.8em",
+      "font-weight": "700",
+      "line-height": "1.5",
+      "white-space": "nowrap",
+      "vertical-align": "0.1em",
+      "cursor": "default",
+      "user-select": "none",
+
+      // Key face
+      "background-color": "var(--clampography-surface, oklch(94% 0.004 264))",
+      "color": "var(--clampography-text, oklch(18% 0.015 264))",
+
+      // Key outline
+      "border": "1px solid var(--clampography-border, oklch(76% 0.008 264))",
+      "border-radius": "4px",
+
+      // 3D depth layers:
+      //   layer 1 — the key "body" (side face, seen in isometric view)
+      //   layer 2 — the soft drop shadow beneath
+      "box-shadow": [
+        "0 2px 0 color-mix(in oklab, var(--clampography-border, oklch(60% 0.008 264)) 100%, black 18%)",
+        "0 3px 2px rgba(0, 0, 0, 0.15)",
+        "inset 0 1px 0 rgba(255, 255, 255, 0.5)",
+      ].join(", "),
+
+      "transition-property": "box-shadow, transform, border-bottom-width",
+      "transition-duration": "80ms",
+    },
+
+    // Pressed state — key travels down by 2px
+    [scope("kbd:active")]: {
+      "transform": "translateY(2px)",
+      "box-shadow": [
+        "0 0 0 color-mix(in oklab, var(--clampography-border, oklch(60% 0.008 264)) 100%, black 18%)",
+        "0 1px 1px rgba(0, 0, 0, 0.1)",
+        "inset 0 1px 0 rgba(255, 255, 255, 0.3)",
+      ].join(", "),
+    },
+  };
+};

package/src/print.js

@@ -0,0 +1,92 @@
+export default (options = {}) => {
+  const root = options.root || ":root";
+
+  // Helper to scope selectors safely (ignoring commas inside parentheses)
+  const scope = (selector) => {
+    const parts = [];
+    let current = "";
+    let depth = 0;
+
+    for (let i = 0; i < selector.length; i++) {
+      const char = selector[i];
+      if (char === "(") depth++;
+      if (char === ")") depth--;
+
+      if (char === "," && depth === 0) {
+        parts.push(current.trim());
+        current = "";
+      } else {
+        current += char;
+      }
+    }
+    parts.push(current.trim());
+
+    const typographyPrefix = options.typography && options.typography !== "global" ? ` ${options.typography}` : "";
+
+    return parts
+      .filter(Boolean)
+      .map((part) => {
+        if (part === ":root" || part === "body") return root;
+        if (typographyPrefix) {
+          return `${root}${typographyPrefix} ${part}`;
+        }
+        return `${root} ${part}`;
+      })
+      .join(", ");
+  };
+
+  return {
+    // PRINT OPTIMIZATION: Force clean, ink-friendly output for printing and PDF export.
+    // Overrides all theme colors, removes backgrounds, and converts fluid vw units to
+    // static sizes so text renders correctly on physical paper (A4/Letter).
+    "@media print": {
+      [(() => {
+        const typographyPrefix = options.typography && options.typography !== "global" ? ` ${options.typography}` : "";
+        const bodyBase = root === ":root" ? "body" : root;
+        return typographyPrefix ? `${bodyBase}${typographyPrefix}` : bodyBase;
+      })()]: {
+        // Static sizes — vw-based clamp() is meaningless on paper
+        "font-size": "12pt",
+        "line-height": "1.6",
+        // Force black-on-white for max legibility and ink saving
+        "color": "black",
+        "background": "white",
+        // Disable all transitions
+        "transition": "none",
+      },
+      [scope(":where(h1, h2, h3, h4, h5, h6)")]: {
+        "color": "black",
+        "page-break-after": "avoid",
+      },
+      [scope("h1")]: { "font-size": "28pt" },
+      [scope("h2")]: { "font-size": "22pt" },
+      [scope("h3")]: { "font-size": "18pt" },
+      [scope("h4")]: { "font-size": "14pt" },
+      [scope("h5")]: { "font-size": "12pt" },
+      [scope("h6")]: { "font-size": "11pt" },
+      [scope("a")]: {
+        // Force readable link styling on paper
+        "color": "black",
+        "text-decoration": "underline",
+      },
+      [scope("pre, blockquote")]: {
+        // Avoid cutting code blocks and blockquotes across page breaks
+        "page-break-inside": "avoid",
+        "border": "1px solid #ccc",
+        "background": "#f5f5f5",
+      },
+      [scope("table")]: {
+        "page-break-inside": "avoid",
+        "border": "1px solid #ccc",
+      },
+      [scope("th, td")]: {
+        "border": "1px solid #ccc",
+      },
+      [scope("img, figure")]: {
+        // Prevent images from overflowing the page
+        "max-width": "100%",
+        "page-break-inside": "avoid",
+      },
+    },
+  };
+};

package/src/theme-plugin.js

@@ -7,15 +7,33 @@ export default plugin.withOptions((options = {}) => {
     const themeName = options.name;
     const isDefault = options.default ?? false;
     const isPrefersDark = options.prefersdark ?? false;
-    const rootSelector = options.root ?? ":root";
-    // Defaults to light scheme if not specified
+    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;
     }
 
+    // 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}`,
+      );
+    }
+
     // 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.
@@ -27,14 +45,18 @@ export default plugin.withOptions((options = {}) => {
     // 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
@@ -46,13 +68,42 @@ export default plugin.withOptions((options = {}) => {
     Object.keys(options).forEach((key) => {
       // Ignore metadata keys
       if (
-        ["name", "default", "prefersdark", "root", "color-scheme"].includes(key)
+        ["name", "default", "prefersdark", "root", "color-scheme", "logs"]
+          .includes(key)
       ) return;
 
+      const value = options[key];
+
       if (keyMap[key]) {
-        themeColors[keyMap[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] = options[key];
+        themeColors[key] = value;
       }
     });
 
@@ -62,15 +113,18 @@ export default plugin.withOptions((options = {}) => {
     // 4. Generate Styles
     const styles = {};
 
-    // A. Define the theme as a named data-theme
-    styles[`[data-theme="${themeName}"]`] = themeColors;
+    // Build selector based on flags
+    let selector = `[data-theme="${themeName}"]`;
 
-    // B. If default, apply to root
+    // If default, prepend :where(root) with lower specificity
     if (isDefault) {
-      styles[rootSelector] = themeColors;
+      selector = `:where(${rootSelector}),${selector}`;
     }
 
-    // C. If 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/theme.js

@@ -0,0 +1,34 @@
+import { themes } from "./themes.js";
+
+/**
+ * CDN Theme Generator
+ * Extracts all themes from themes.js and structures them
+ * for the Vanilla CSS build process.
+ */
+export default (options = {}) => {
+  const root = options.root || ":root";
+  const themeStyles = {};
+
+  // 1. Default Theme (Light)
+  if (themes["light"]) {
+    // :where() lowers specificity so users can override it easily
+    themeStyles[`:where(${root})`] = themes["light"];
+  }
+
+  // 2. Dark Mode (prefers-color-scheme)
+  if (themes["dark"]) {
+    themeStyles["@media (prefers-color-scheme: dark)"] = {
+      // Default to dark if system prefers dark
+      [root]: themes["dark"]
+    };
+  }
+
+  // 3. Explicit Data Themes (Handles all themes, including light and dark)
+  // Because these are generated after the media query, they have equal
+  // specificity to :root but appear later in the CSS, thus overriding system preference.
+  for (const [name, themeData] of Object.entries(themes)) {
+    themeStyles[`[data-theme="${name}"]`] = themeData;
+  }
+
+  return themeStyles;
+};

package/src/themes.js

@@ -1,52 +1,47 @@
+/**
+ * Built-in Themes
+ * 
+ * Auto-generated by Clampography Dev Server.
+ * Do not manually edit this file unless you know what you're doing.
+ */
+
+export const dark = {
+  "color-scheme": "dark",
+  "--clampography-background": "oklch(13.3% 0.016 284.0)",
+  "--clampography-border": "oklch(43.4% 0.006 258.3)",
+  "--clampography-error": "oklch(62.9% 0.220 27.0)",
+  "--clampography-heading": "oklch(94.6% 0.000 89.9)",
+  "--clampography-info": "oklch(71.2% 0.155 251.4)",
+  "--clampography-link": "oklch(75.3% 0.133 248.6)",
+  "--clampography-muted": "oklch(68.9% 0.006 264.5)",
+  "--clampography-primary": "oklch(75.3% 0.133 248.6)",
+  "--clampography-secondary": "oklch(62.6% 0.243 301.2)",
+  "--clampography-success": "oklch(66.3% 0.148 160.6)",
+  "--clampography-surface": "oklch(21.2% 0.009 255.6)",
+  "--clampography-text": "oklch(88.8% 0.007 268.5)",
+  "--clampography-warning": "oklch(72.1% 0.164 63.1)",
+};
+
+export const light = {
+  "color-scheme": "light",
+  "--clampography-background": "oklch(100.0% 0.000 89.9)",
+  "--clampography-border": "oklch(94.6% 0.000 89.9)",
+  "--clampography-error": "oklch(65.4% 0.229 27.0)",
+  "--clampography-heading": "oklch(15.0% 0.021 264.3)",
+  "--clampography-info": "oklch(68.3% 0.166 259.7)",
+  "--clampography-link": "oklch(60.3% 0.216 259.8)",
+  "--clampography-muted": "oklch(51.9% 0.014 259.8)",
+  "--clampography-primary": "oklch(60.3% 0.216 259.8)",
+  "--clampography-secondary": "oklch(54.9% 0.280 300.0)",
+  "--clampography-success": "oklch(75.8% 0.166 161.7)",
+  "--clampography-surface": "oklch(98.5% 0.000 89.9)",
+  "--clampography-text": "oklch(31.1% 0.020 257.3)",
+  "--clampography-warning": "oklch(79.9% 0.136 72.2)",
+};
+
 export const themes = {
-  light: {
-    "color-scheme": "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",
-  },
-  dark: {
-    "color-scheme": "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",
-  },
-  retro: {
-    "color-scheme": "light",
-    "--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",
-  },
-  cyberpunk: {
-    "color-scheme": "dark",
-    "--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",
-  },
+  "dark": dark,
+  "light": light
 };
 
 export const themesList = Object.keys(themes);

package/src/types/index.d.ts

@@ -0,0 +1,24 @@
+import plugin from "tailwindcss/plugin";
+
+interface ClampographyOptions {
+  themes?: string | string[] | boolean;
+  base?: boolean;
+  extra?: boolean;
+  forms?: boolean;
+  kbd?: boolean;
+  print?: boolean;
+  "fluid-min"?: string | number;
+  fluidMin?: string | number;
+  "fluid-max"?: string | number;
+  fluidMax?: string | number;
+  typography?: string;
+  root?: string;
+  prefix?: string | boolean;
+  logs?: boolean;
+}
+
+declare const clampographyPlugin: ReturnType<typeof plugin.withOptions<ClampographyOptions>>;
+
+export default clampographyPlugin;
+
+export type { ClampographyVars } from "./vars.js";

package/src/types/theme-plugin.d.ts

@@ -0,0 +1,32 @@
+import plugin from "tailwindcss/plugin";
+
+interface ThemePluginOptions {
+  name: string;
+  default?: boolean;
+  prefersdark?: boolean;
+  "color-scheme"?: "light" | "dark";
+  root?: string;
+  logs?: boolean;
+
+  // Color options
+  background?: string;
+  border?: string;
+  error?: string;
+  heading?: string;
+  info?: string;
+  link?: string;
+  muted?: string;
+  primary?: string;
+  secondary?: string;
+  success?: string;
+  surface?: string;
+  text?: string;
+  warning?: string;
+
+  // Allow custom CSS variables
+  [key: `--${string}`]: string | undefined;
+}
+
+declare const themePlugin: ReturnType<typeof plugin.withOptions<ThemePluginOptions>>;
+
+export default themePlugin;

package/src/types/themes.d.ts

@@ -0,0 +1,28 @@
+declare module "clampography/themes" {
+  export interface ThemeColors {
+    "color-scheme": "light" | "dark";
+    "--clampography-background": string;
+    "--clampography-border": string;
+    "--clampography-error": string;
+    "--clampography-heading": string;
+    "--clampography-info": string;
+    "--clampography-link": string;
+    "--clampography-muted": string;
+    "--clampography-primary": string;
+    "--clampography-secondary": string;
+    "--clampography-success": string;
+    "--clampography-surface": string;
+    "--clampography-text": string;
+    "--clampography-warning": string;
+    [key: string]: string;
+  }
+
+  export interface Themes {
+    light: ThemeColors;
+    dark: ThemeColors;
+    [themeName: string]: ThemeColors;
+  }
+
+  export const themes: Themes;
+  export const themesList: string[];
+}

package/src/types/vars.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Auto-generated by Clampography
+ * TypeScript definitions for Clampography CSS Variables
+ */
+
+export type ClampographyVars = 
+  | "--clampography-background"
+  | "--clampography-border"
+  | "--clampography-error"
+  | "--clampography-fluid-max"
+  | "--clampography-fluid-min"
+  | "--clampography-font-base"
+  | "--clampography-font-mono"
+  | "--clampography-h1-base"
+  | "--clampography-h1-max"
+  | "--clampography-h1-min"
+  | "--clampography-h1-scale"
+  | "--clampography-h1-size"
+  | "--clampography-h1-slope"
+  | "--clampography-h2-base"
+  | "--clampography-h2-max"
+  | "--clampography-h2-min"
+  | "--clampography-h2-scale"
+  | "--clampography-h2-size"
+  | "--clampography-h2-slope"
+  | "--clampography-h3-base"
+  | "--clampography-h3-max"
+  | "--clampography-h3-min"
+  | "--clampography-h3-scale"
+  | "--clampography-h3-size"
+  | "--clampography-h3-slope"
+  | "--clampography-h4-base"
+  | "--clampography-h4-max"
+  | "--clampography-h4-min"
+  | "--clampography-h4-scale"
+  | "--clampography-h4-size"
+  | "--clampography-h4-slope"
+  | "--clampography-h5-base"
+  | "--clampography-h5-max"
+  | "--clampography-h5-min"
+  | "--clampography-h5-scale"
+  | "--clampography-h5-size"
+  | "--clampography-h5-slope"
+  | "--clampography-h6-base"
+  | "--clampography-h6-max"
+  | "--clampography-h6-min"
+  | "--clampography-h6-scale"
+  | "--clampography-h6-size"
+  | "--clampography-h6-slope"
+  | "--clampography-heading"
+  | "--clampography-heading-scale"
+  | "--clampography-info"
+  | "--clampography-link"
+  | "--clampography-list-indent"
+  | "--clampography-muted"
+  | "--clampography-primary"
+  | "--clampography-scroll-offset"
+  | "--clampography-secondary"
+  | "--clampography-spacing-lg"
+  | "--clampography-spacing-md"
+  | "--clampography-spacing-sm"
+  | "--clampography-spacing-xl"
+  | "--clampography-spacing-xs"
+  | "--clampography-success"
+  | "--clampography-surface"
+  | "--clampography-text"
+  | "--clampography-transition-duration"
+  | "--clampography-warning";