@themal/editor 0.17.1 → 0.18.1

package/README.md

@@ -36,7 +36,7 @@ function App() {
 }
 ```
 
-The editor writes CSS custom properties (HSL values) to `:root`, so it works with any framework that consumes CSS variables.
+The editor writes CSS custom properties (HSL values) to `:root` and injects global typography styles, so colors and fonts apply across your entire site.
 
 ## Props
 
@@ -54,6 +54,9 @@ The editor writes CSS custom properties (HSL values) to `:root`, so it works wit
 | `showNavLinks` | `boolean` | `true` | Show page navigation links in the header and mobile menu. |
 | `headerRight` | `React.ReactNode` | — | Custom content rendered on the right side of the header (e.g. auth buttons). |
 | `aboutUrl` | `string` | — | URL for the About page link in the header navigation. |
+| `customIcons` | `CustomIcon[]` | — | Custom icons to display in the Icons preview section. Each entry needs `name` and `icon` (a React component). |
+| `iconMode` | `"append" \| "replace"` | `"append"` | `"append"` adds custom icons after the built-in lucide icons. `"replace"` hides built-ins and shows only custom icons. |
+| `showLogo` | `boolean` | `true` | Show the Themal logo in the header. Set `false` for white-label or plugin usage. |
 
 ## Premium Features
 
@@ -64,7 +67,7 @@ The following features require a valid license key:
 | Harmony schemes | Generate palettes using complementary, analogous, triadic, or split-complementary color relationships. |
 | Color locks | Lock up to 4 colors to preserve them during palette regeneration. |
 | PR integration | Create design system pull requests directly from the editor. |
-| Undo/redo | History management for color changes. |
+| Undo/redo | Up to 10 levels of undo for theme refreshes and image palette applications. |
 | Image palette extraction | Extract color palettes from uploaded images with preview confirmation. |
 | Palette export | Download palette as SVG/PNG, or copy as HEX/RGB/RGBA text. |
 | Interaction states | Style hover, focus, and active states for buttons and components. |
@@ -159,6 +162,37 @@ import { LicenseProvider } from '@themal/editor';
 />
 ```
 
+### With custom icons
+
+```tsx
+import { Rocket, Star, Flame } from 'lucide-react';
+// Or use any React component that accepts className
+import { MyBrandIcon } from './icons';
+
+<DesignSystemEditor
+  customIcons={[
+    { name: "Rocket", icon: Rocket },
+    { name: "Star", icon: Star },
+    { name: "Flame", icon: Flame },
+    { name: "Brand", icon: MyBrandIcon },
+  ]}
+/>
+```
+
+### Replace built-in icons entirely
+
+```tsx
+<DesignSystemEditor
+  customIcons={[
+    { name: "Brand", icon: MyBrandIcon },
+    { name: "Product", icon: ProductIcon },
+  ]}
+  iconMode="replace"
+/>
+```
+
+The Icons section includes a "Hide All" / "Show All" toggle so users can collapse the icon grid.
+
 ### Embedded / headless
 
 ```tsx
@@ -190,7 +224,7 @@ import {
 
   // Card, typography & interaction style utilities
   applyStoredCardStyle,           // Restore card style from localStorage
-  applyStoredTypography,          // Restore typography from localStorage
+  applyStoredTypography,          // Restore typography from localStorage (applies site-wide)
   applyStoredAlertStyle,          // Restore dialog alert style from localStorage
   applyStoredToastStyle,          // Restore toast style from localStorage
   applyStoredInteractionStyle,    // Restore button interaction style from localStorage
@@ -228,6 +262,7 @@ import {
 import type {
   DesignSystemEditorProps,
   TokenDefinition,
+  CustomIcon,
   HarmonyScheme,
   CardStyleState,
   TypographyState,
@@ -245,10 +280,10 @@ import type {
 
 ## How It Works
 
-1. **Color picking** — Click any swatch to open the native color picker. Changing a key color (brand, secondary, accent, background) automatically derives related tokens.
+1. **Color picking** — Click any swatch to scroll the Colors section into view, then open the native color picker. Changing a key color (brand, secondary, accent, background) automatically derives related tokens.
 2. **Harmony schemes** *(Pro)* — Generate palettes using complementary, analogous, triadic, or split-complementary color relationships.
-3. **Contrast enforcement** — Every foreground/background pair is checked against WCAG AA (4.5:1). Failing pairs are auto-corrected by adjusting lightness.
-4. **Typography** — Choose heading and body fonts (including custom Google Fonts), adjust sizes, weights, line height, and letter spacing with live preview. Five built-in presets (System, Modern, Classic, Compact, Editorial).
+3. **Contrast enforcement** — Every foreground/background pair is checked against WCAG AA (4.5:1). Failing pairs are auto-corrected by adjusting lightness. The accessibility audit shows a centered modal with results. On failure, choose "Ignore" to dismiss or "Suggest Alternative" to auto-fix contrast issues. A WCAG On/Off toggle lets you disable auto-correction for marketing or other contexts that don't require WCAG compliance. Locks are still honored when enforcement is off.
+4. **Typography** — Choose heading and body fonts (including custom Google Fonts), adjust sizes, weights, line height, and letter spacing with live preview. Five built-in presets (System, Modern, Classic, Compact, Editorial). Typography applies site-wide, not just within the editor component, so toggling fonts updates the entire page.
 5. **Button interactions** *(Pro)* — Fine-tune hover opacity, hover/active scale, transition duration, and focus ring width with presets (Subtle, Elevated, Bold).
 6. **Typography interactions** *(Pro)* — Customize link hover/active behavior (opacity, scale, underline) and heading hover effects with live preview.
 7. **Persistence** — All settings (colors, typography, card styles, dialog styles, toast styles, interactions) are saved to `localStorage` and restored on reload.
@@ -256,7 +291,7 @@ import type {
 9. **Shareable URLs** — Encode your full theme state in the URL hash and share it with anyone via a single link.
 10. **Palette export** *(Pro)* — Download your palette as SVG or PNG, or copy as a HEX/RGB/RGBA text list.
 11. **Custom fonts** *(Pro)* — Add any Google Font by name. The editor validates the font exists, loads all weights, adds it to heading/body dropdowns, and persists it across sessions.
-12. **Mobile friendly** — Fully responsive UI with mobile-optimized dropdowns, compact swatch labels, and stacked layouts for smaller screens.
+12. **Mobile friendly** — Fully responsive UI with a 2D color spectrum picker (saturation/lightness canvas + hue slider) for intuitive touch-based color selection, mobile-optimized dropdowns, compact swatch labels, and stacked layouts for smaller screens.
 
 ## Package Architecture
 
@@ -284,6 +319,63 @@ Import the main entry point for components and utilities, and `style.css` separa
 
 The editor ships pre-compiled CSS via `@themal/editor/style.css`. Styles are scoped using Tailwind's `important: '.ds-editor'` so they don't conflict with your app's styles. The root element is automatically wrapped in `<div className="ds-editor">`.
 
+## Web Component
+
+The editor is also available as a `<themal-editor>` custom element for non-React sites (WordPress, Shopify, plain HTML).
+
+### Basic usage
+
+```html
+<script src="https://unpkg.com/@themal/editor/dist/themal-editor.js"></script>
+<themal-editor></themal-editor>
+```
+
+### Attributes
+
+All props that accept strings or booleans can be set as HTML attributes using kebab-case:
+
+```html
+<themal-editor
+  license-key="THEMAL-XXXX-XXXX-XXXX"
+  show-header="false"
+  show-nav-links="false"
+  icon-mode="replace"
+  show-logo="true"
+  accessibility-audit="true"
+  upgrade-url="/pricing"
+  sign-in-url="/sign-in"
+  about-url="/about"
+  pr-endpoint-url="/api/create-design-pr"
+></themal-editor>
+```
+
+Note: The Themal logo is hidden by default in the web component. Set `show-logo="true"` to display it.
+
+### Custom icons via JavaScript
+
+Since HTML attributes can only pass strings, custom icons are set programmatically with the `setIcons()` method. Pass an array of `{ name, svg }` objects where `svg` is a raw SVG string:
+
+```html
+<script src="https://unpkg.com/@themal/editor/dist/themal-editor.js"></script>
+<themal-editor icon-mode="replace"></themal-editor>
+
+<script>
+  const editor = document.querySelector('themal-editor');
+  editor.setIcons([
+    {
+      name: "Heart",
+      svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>'
+    },
+    {
+      name: "Star",
+      svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/></svg>'
+    },
+  ]);
+</script>
+```
+
+Set `icon-mode="replace"` to hide the built-in icons and show only your custom set, or omit it (defaults to `"append"`) to add yours alongside the built-ins.
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -64,6 +64,16 @@ export declare interface CustomFontEntry {
     spec: string;
 }
 
+export declare interface CustomIcon {
+    /** Display name for the icon */
+    name: string;
+    /** React component that renders the icon. Receives className and standard SVG props. */
+    icon: default_2.ComponentType<{
+        className?: string;
+        [key: string]: unknown;
+    }>;
+}
+
 export declare function deserializeThemeState(hash: string): {
     colors: Record<string, string>;
     cardStyle: CardStyleState;
@@ -103,6 +113,12 @@ export declare interface DesignSystemEditorProps {
     featuresUrl?: string;
     /** URL for the About page link in the header */
     aboutUrl?: string;
+    /** Custom icons to display in the Icons preview section */
+    customIcons?: CustomIcon[];
+    /** How custom icons interact with built-in icons. "append" adds them after built-ins, "replace" hides built-ins entirely. Default: "append" */
+    iconMode?: "append" | "replace";
+    /** Show the Themal logo in the header. Default: true */
+    showLogo?: boolean;
 }
 
 export declare const EDITABLE_VARS: readonly [{