@themal/editor 0.17.0

package/README.md

@@ -0,0 +1,338 @@
+# @themal/editor
+
+Interactive design system editor for React apps. Pick colors, generate harmony palettes, enforce WCAG AA contrast, customize typography and interaction states, and export CSS custom properties — all in real time. Fully responsive — works on desktop, tablet, and mobile.
+
+> Free tier available with core features. Pro features ($9/mo or $50/yr) require a subscription.
+
+## Install
+
+```bash
+npm install @themal/editor
+```
+
+### Peer Dependencies
+
+| Package | Version | Required |
+|---------|---------|----------|
+| `react` | `^18.0.0 \|\| ^19.0.0` | Yes |
+| `react-dom` | `^18.0.0 \|\| ^19.0.0` | Yes |
+| `axe-core` | `>=4.0.0` | Optional — enables accessibility auditing |
+| `lucide-react` | `>=0.294.0` | Optional — enables icon previews |
+
+Install optional peers for full functionality:
+
+```bash
+npm install axe-core lucide-react
+```
+
+## Quick Start
+
+```tsx
+import { DesignSystemEditor } from '@themal/editor';
+import '@themal/editor/style.css';
+
+function App() {
+  return <DesignSystemEditor />;
+}
+```
+
+The editor writes CSS custom properties (HSL values) to `:root`, so it works with any framework that consumes CSS variables.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `licenseKey` | `string` | — | License key to unlock premium features. |
+| `upgradeUrl` | `string` | `"/pricing"` | URL shown in premium gate upgrade prompts. |
+| `signInUrl` | `string` | — | URL shown in premium gate sign-in prompts. |
+| `prEndpointUrl` | `string` | — | URL for PR creation endpoint. PR button hidden if omitted. |
+| `accessibilityAudit` | `boolean` | `true` | Enable axe-core color contrast auditing. |
+| `onChange` | `(colors: Record<string, string>) => void` | — | Callback on every color change with the full color map. |
+| `onExport` | `(css: string) => void` | — | Override built-in CSS modal. Receives the generated CSS string. |
+| `className` | `string` | — | Additional CSS class for the wrapper element. |
+| `showHeader` | `boolean` | `true` | Show the editor header with logo and navigation. |
+| `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. |
+
+## Premium Features
+
+The following features require a valid license key:
+
+| Feature | Description |
+|---------|-------------|
+| 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. |
+| 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. |
+| Typography interactions | Customize hover, active, and underline behavior for links and headings. |
+| Custom fonts | Add any Google Font by name — validated, loaded, and persisted across sessions. |
+
+### License Key Format
+
+Keys follow the format `THEMAL-XXXX-XXXX-XXXX` with a checksum-validated third segment. Use `generateLicenseKey()` to create valid keys.
+
+### PremiumGate Component
+
+Wrap any feature in `PremiumGate` to gate it behind a license key. Clicking a gated feature opens a modal with upgrade and sign-in options:
+
+```tsx
+import { PremiumGate } from '@themal/editor';
+
+<PremiumGate feature="harmony-schemes" upgradeUrl="/pricing" signInUrl="/sign-in">
+  <HarmonyControls />
+</PremiumGate>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `feature` | `string` | — | Name of the premium feature being gated. |
+| `variant` | `"section" \| "inline"` | `"section"` | `"section"` dims content with a lock overlay; `"inline"` shows a lock icon inline. Both open a modal on click. |
+| `upgradeUrl` | `string` | `"/pricing"` | URL for the upgrade prompt. |
+| `signInUrl` | `string` | — | URL for the sign-in prompt. |
+
+### LicenseProvider
+
+If using `PremiumGate` or `useLicense` outside of `DesignSystemEditor`, wrap your tree in `LicenseProvider`:
+
+```tsx
+import { LicenseProvider } from '@themal/editor';
+
+<LicenseProvider licenseKey="THEMAL-XXXX-XXXX-XXXX">
+  <App />
+</LicenseProvider>
+```
+
+## Usage Examples
+
+### Basic — color picker only
+
+```tsx
+<DesignSystemEditor accessibilityAudit={false} />
+```
+
+### With PR creation
+
+```tsx
+<DesignSystemEditor prEndpointUrl="/api/create-design-pr" />
+```
+
+### With premium features
+
+```tsx
+<DesignSystemEditor
+  licenseKey="THEMAL-XXXX-XXXX-XXXX"
+  upgradeUrl="/pricing"
+  signInUrl="/sign-in"
+/>
+```
+
+### With custom header content
+
+```tsx
+<DesignSystemEditor
+  headerRight={<button onClick={handleSignIn}>Sign In</button>}
+  aboutUrl="/about"
+/>
+```
+
+### Listen for changes
+
+```tsx
+<DesignSystemEditor
+  onChange={(colors) => {
+    console.log('Brand color:', colors['--brand']);
+  }}
+/>
+```
+
+### Custom export handler
+
+```tsx
+<DesignSystemEditor
+  onExport={(css) => {
+    navigator.clipboard.writeText(css);
+  }}
+/>
+```
+
+### Embedded / headless
+
+```tsx
+<DesignSystemEditor
+  showHeader={false}
+  showNavLinks={false}
+/>
+```
+
+## Exported Utilities
+
+```tsx
+import {
+  // Color utilities
+  hslStringToHex,    // "210 50% 40%" -> "#336699"
+  hexToHslString,    // "#336699" -> "210.0 50.0% 40.0%"
+  contrastRatio,     // WCAG contrast ratio between two HSL strings
+  fgForBg,           // Best foreground (black/white) for a background HSL
+  EDITABLE_VARS,     // Array of { key, label } token definitions
+  HARMONY_SCHEMES,   // ['Complementary', 'Analogous', 'Triadic', 'Split-Complementary']
+  applyStoredThemeColors, // Restore persisted theme from localStorage
+
+  // localStorage key constants
+  CARD_STYLE_KEY,            // Key for card style storage
+  TYPOGRAPHY_KEY,            // Key for typography storage
+  ALERT_STYLE_KEY,           // Key for dialog alert style storage
+  TOAST_STYLE_KEY,           // Key for toast style storage
+  INTERACTION_STYLE_KEY,     // Key for interaction style storage
+
+  // Card, typography & interaction style utilities
+  applyStoredCardStyle,           // Restore card style from localStorage
+  applyStoredTypography,          // Restore typography from localStorage
+  applyStoredAlertStyle,          // Restore dialog alert style from localStorage
+  applyStoredToastStyle,          // Restore toast style from localStorage
+  applyStoredInteractionStyle,    // Restore button interaction style from localStorage
+
+  // Shareable URL utilities
+  serializeThemeState,            // Encode full theme state as base64 string
+  deserializeThemeState,          // Decode base64 string back to theme state
+
+  // Export utilities
+  generateDesignTokens,           // Generate W3C Design Token JSON from theme state
+  exportPaletteAsText,            // Export palette as HEX, RGB, or RGBA text
+  exportPaletteAsSvg,             // Export palette as SVG string
+  exportPaletteAsPng,             // Export palette as PNG Blob
+
+  // Custom font utilities
+  getCustomFonts,       // Load custom fonts from localStorage
+  addCustomFont,        // Validate & add a Google Font by name
+  removeCustomFont,     // Remove a custom font by label
+  initCustomFonts,      // Re-register all custom fonts on startup
+
+  // License utilities
+  validateLicenseKey,   // Validate a THEMAL-XXXX-XXXX-XXXX key
+  generateLicenseKey,   // Generate a valid license key
+
+  // Premium components & hooks
+  LicenseProvider,      // Context provider for license state
+  useLicense,           // Hook: { isValid, isPremium }
+  PremiumGate,          // Gate component for premium features
+} from '@themal/editor';
+```
+
+### Exported Types
+
+```tsx
+import type {
+  DesignSystemEditorProps,
+  TokenDefinition,
+  HarmonyScheme,
+  CardStyleState,
+  TypographyState,
+  AlertStyleState,
+  ToastStyleState,
+  InteractionStyleState,
+  TypoInteractionStyleState,
+  CustomFontEntry,
+  PremiumFeature,
+  LicenseValidation,
+  LicenseProviderProps,
+  PremiumGateProps,
+} from '@themal/editor';
+```
+
+## 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.
+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).
+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.
+8. **Per-section export** — Every section header includes a CSS | Tokens split button to export CSS custom properties with Tailwind config, or W3C Design Token JSON, for that section.
+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.
+
+## Package Architecture
+
+The editor is built with Vite in library mode and published as an ES module:
+
+```
+@themal/editor
+├── dist/index.js      # ESM bundle (all components + utilities)
+├── dist/index.d.ts    # TypeScript declarations
+└── dist/style.css     # Pre-compiled, scoped Tailwind styles
+```
+
+### Exports Map
+
+```json
+{
+  ".":            { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./style.css":  "./dist/style.css"
+}
+```
+
+Import the main entry point for components and utilities, and `style.css` separately for styles. This keeps CSS opt-in and avoids side effects during tree-shaking.
+
+## Tailwind Scoping
+
+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">`.
+
+## Development
+
+```bash
+# From the repo root
+npm install
+
+# Build the package
+cd packages/editor
+npm run build
+
+# Watch mode
+npm run dev
+```
+
+## Testing
+
+The project includes automated accessibility testing:
+
+```bash
+# Run all tests (includes axe-core a11y checks)
+npm run test:run
+
+# Lint for accessibility issues
+npm run lint
+```
+
+The test suite uses **vitest-axe** to run axe-core against rendered components, catching WCAG violations automatically. ESLint with **eslint-plugin-jsx-a11y** provides static analysis for common accessibility anti-patterns.
+
+## Publishing to npm
+
+The package is published as `@themal/editor` on npm. To publish a new version:
+
+```bash
+# 1. Build
+cd packages/editor
+npm run build
+
+# 2. Verify the tarball contents (should only include dist/)
+npm pack --dry-run
+
+# 3. Bump the version
+npm version patch   # or minor / major
+
+# 4. Publish (scoped packages require --access public on first publish)
+npm publish --access public
+```
+
+You must be logged in to npm (`npm login`) with publish access to the `@themal` scope.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+import { default as default_2 } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+export declare function addCustomFont(name: string): Promise<CustomFontEntry>;
+
+export declare const ALERT_STYLE_KEY = "ds-alert-style";
+
+export declare interface AlertStyleState {
+    preset: "filled" | "soft" | "outline" | "minimal" | "custom";
+    borderRadius: number;
+    borderWidth: number;
+    iconStyle: "circle" | "plain";
+    padding: number;
+}
+
+export declare function applyStoredAlertStyle(): AlertStyleState | null;
+
+export declare function applyStoredCardStyle(themeColors: Record<string, string>): CardStyleState | null;
+
+export declare function applyStoredInteractionStyle(): InteractionStyleState | null;
+
+export declare function applyStoredThemeColors(): void;
+
+export declare function applyStoredToastStyle(): ToastStyleState | null;
+
+export declare function applyStoredTypography(): TypographyState | null;
+
+declare interface ButtonStyleState {
+    paddingX: number;
+    paddingY: number;
+    fontSize: number;
+    fontWeight: number;
+    borderRadius: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowBlur: number;
+    shadowSpread: number;
+    shadowColor: string;
+    borderWidth: number;
+}
+
+export declare const CARD_STYLE_KEY = "ds-card-style";
+
+export declare interface CardStyleState {
+    preset: "liquid-glass" | "solid" | "gradient" | "border-only" | "custom";
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowBlur: number;
+    shadowSpread: number;
+    shadowColor: string;
+    borderRadius: number;
+    bgType: "solid" | "gradient" | "transparent";
+    bgGradientAngle: number;
+    borderWidth: number;
+    backdropBlur: number;
+    bgOpacity: number;
+}
+
+export declare function contrastRatio(hsl1: string, hsl2: string): number;
+
+export declare interface CustomFontEntry {
+    label: string;
+    value: string;
+    spec: string;
+}
+
+export declare function deserializeThemeState(hash: string): {
+    colors: Record<string, string>;
+    cardStyle: CardStyleState;
+    typographyState: TypographyState;
+    alertStyle: AlertStyleState;
+    interactionStyle: InteractionStyleState;
+    typoInteractionStyle: TypoInteractionStyleState;
+    buttonStyle: ButtonStyleState;
+} | null;
+
+export declare function DesignSystemEditor({ licenseKey, ...props }: DesignSystemEditorProps): JSX_2.Element;
+
+export declare interface DesignSystemEditorProps {
+    /** URL for the PR creation endpoint. Hides PR button if omitted. */
+    prEndpointUrl?: string;
+    /** Enable accessibility audit via axe-core. Default: true */
+    accessibilityAudit?: boolean;
+    /** Callback fired on every color change with the full color map */
+    onChange?: (colors: Record<string, string>) => void;
+    /** Override built-in CSS export modal - receives the generated CSS string */
+    onExport?: (css: string) => void;
+    /** Additional CSS class for the wrapper element */
+    className?: string;
+    /** Show "How It Works", "README", and "Pricing" nav links. Default: true */
+    showNavLinks?: boolean;
+    /** Show the sticky header bar (logo, nav, PR button). Default: true. Set false for embedded/plugin usage. */
+    showHeader?: boolean;
+    /** License key to unlock premium features */
+    licenseKey?: string;
+    /** Custom URL for the "Upgrade" link shown on gated features */
+    upgradeUrl?: string;
+    /** Custom URL for the "Sign in" link shown on gated features */
+    signInUrl?: string;
+    /** Content rendered at the far right of the header row (e.g. auth buttons) */
+    headerRight?: default_2.ReactNode;
+    /** URL for the "Learn more about features" link */
+    featuresUrl?: string;
+    /** URL for the About page link in the header */
+    aboutUrl?: string;
+}
+
+export declare const EDITABLE_VARS: readonly [{
+    readonly key: "--brand";
+    readonly label: "Brand Blue";
+}, {
+    readonly key: "--secondary";
+    readonly label: "Secondary";
+}, {
+    readonly key: "--background";
+    readonly label: "Background";
+}, {
+    readonly key: "--foreground";
+    readonly label: "Foreground";
+}, {
+    readonly key: "--card";
+    readonly label: "Card";
+}, {
+    readonly key: "--card-foreground";
+    readonly label: "Card FG";
+}, {
+    readonly key: "--popover";
+    readonly label: "Popover";
+}, {
+    readonly key: "--popover-foreground";
+    readonly label: "Popover FG";
+}, {
+    readonly key: "--primary";
+    readonly label: "Primary";
+}, {
+    readonly key: "--primary-foreground";
+    readonly label: "Primary FG";
+}, {
+    readonly key: "--secondary-foreground";
+    readonly label: "Secondary FG";
+}, {
+    readonly key: "--muted";
+    readonly label: "Muted";
+}, {
+    readonly key: "--muted-foreground";
+    readonly label: "Muted FG";
+}, {
+    readonly key: "--accent";
+    readonly label: "Accent";
+}, {
+    readonly key: "--accent-foreground";
+    readonly label: "Accent FG";
+}, {
+    readonly key: "--destructive";
+    readonly label: "Destructive";
+}, {
+    readonly key: "--destructive-foreground";
+    readonly label: "Destructive FG";
+}, {
+    readonly key: "--success";
+    readonly label: "Success";
+}, {
+    readonly key: "--success-foreground";
+    readonly label: "Success FG";
+}, {
+    readonly key: "--warning";
+    readonly label: "Warning";
+}, {
+    readonly key: "--warning-foreground";
+    readonly label: "Warning FG";
+}, {
+    readonly key: "--border";
+    readonly label: "Border";
+}, {
+    readonly key: "--ring";
+    readonly label: "Ring";
+}];
+
+export declare function exportPaletteAsPng(colors: Record<string, string>): Promise<Blob>;
+
+export declare function exportPaletteAsSvg(colors: Record<string, string>): string;
+
+export declare function exportPaletteAsText(colors: Record<string, string>, format: "hex" | "rgb" | "rgba"): string;
+
+export declare function fgForBg(hslBg: string): string;
+
+export declare function generateDesignTokens(colors: Record<string, string>, cardStyle: CardStyleState, typographyState: TypographyState, alertStyle: AlertStyleState, interactionStyle: InteractionStyleState): Record<string, unknown>;
+
+/**
+ * Generate a valid license key (for admin / sales tooling).
+ */
+export declare function generateLicenseKey(): string;
+
+export declare function getCustomFonts(): CustomFontEntry[];
+
+export declare const HARMONY_SCHEMES: readonly ["Complementary", "Analogous", "Triadic", "Split-Complementary"];
+
+export declare type HarmonyScheme = typeof HARMONY_SCHEMES[number];
+
+export declare function hexToHslString(hex: string): string;
+
+export declare function hslStringToHex(hsl: string): string;
+
+export declare function initCustomFonts(): void;
+
+export declare const INTERACTION_STYLE_KEY = "ds-interaction-style";
+
+export declare interface InteractionStyleState {
+    preset: "subtle" | "elevated" | "bold" | "custom";
+    hoverOpacity: number;
+    hoverScale: number;
+    activeScale: number;
+    transitionDuration: number;
+    focusRingWidth: number;
+}
+
+export declare function LicenseProvider({ children }: LicenseProviderProps): JSX_2.Element;
+
+export declare interface LicenseProviderProps {
+    licenseKey?: string;
+    children: default_2.ReactNode;
+}
+
+export declare interface LicenseValidation {
+    isValid: boolean;
+    isPremium: boolean;
+}
+
+/**
+ * License key validation and generation for @themal/editor premium features.
+ *
+ * Key format:  THEMAL-XXXX-XXXX-XXXX
+ *   - Segments use alphanumeric chars excluding ambiguous ones (0/O, 1/I/L).
+ *   - The third segment is a checksum derived from the first two.
+ */
+export declare type PremiumFeature = "harmony-schemes" | "color-locks" | "pr-integration" | "undo" | "palette-export" | "image-palette" | "typography-spacing" | "custom-fonts" | "interaction-states" | "typography-interactions" | "toast-messages";
+
+export declare function PremiumGate({ feature, variant, hideLock, upgradeUrl, signInUrl, children, }: PremiumGateProps): JSX_2.Element;
+
+export declare interface PremiumGateProps {
+    feature: string;
+    /** "section" blocks content; "inline" shows lock inline. Default: "section" */
+    variant?: "section" | "inline";
+    /** Hide the external lock icon (e.g. when the button already has one inside) */
+    hideLock?: boolean;
+    upgradeUrl?: string;
+    signInUrl?: string;
+    children: default_2.ReactNode;
+}
+
+export declare function removeCustomFont(label: string): void;
+
+export declare function serializeThemeState(colors: Record<string, string>, cardStyle: CardStyleState, typographyState: TypographyState, alertStyle: AlertStyleState, interactionStyle: InteractionStyleState, typoInteractionStyle: TypoInteractionStyleState, buttonStyle?: ButtonStyleState): string;
+
+export declare const TOAST_STYLE_KEY = "ds-toast-style";
+
+export declare type ToastStyleState = AlertStyleState;
+
+export declare interface TokenDefinition {
+    key: string;
+    label: string;
+}
+
+export declare const TYPOGRAPHY_KEY = "ds-typography-v2";
+
+export declare interface TypographyState {
+    preset: "system" | "modern" | "classic" | "compact" | "editorial" | "custom";
+    headingFamily: string;
+    bodyFamily: string;
+    baseFontSize: number;
+    headingWeight: number;
+    bodyWeight: number;
+    lineHeight: number;
+    letterSpacing: number;
+    headingLetterSpacing: number;
+}
+
+export declare interface TypoInteractionStyleState {
+    preset: "subtle" | "elevated" | "bold" | "custom";
+    linkHoverOpacity: number;
+    linkHoverScale: number;
+    linkActiveScale: number;
+    linkTransitionDuration: number;
+    linkUnderline: "always" | "hover" | "none";
+    headingHoverOpacity: number;
+    headingHoverScale: number;
+    headingTransitionDuration: number;
+}
+
+export declare function useLicense(): LicenseValidation;
+
+/**
+ * Validate a license key string.
+ * Returns `{ isValid: true, isPremium: true }` for a correct key,
+ * or `{ isValid: false, isPremium: false }` otherwise.
+ */
+export declare function validateLicenseKey(key: string | undefined | null): LicenseValidation;
+
+export { }