colorsbymax 0.1.0 → 0.2.0

package/dist/pdf.js

@@ -0,0 +1,9 @@
+//#region src/pdf.js
+/** Loads PDF.js, running it on the page so there's no separate worker file to host. */
+async function loadPdf() {
+	const pdfjs = await import("pdfjs-dist");
+	await import("pdfjs-dist/build/pdf.worker.min.mjs");
+	return pdfjs;
+}
+//#endregion
+export { loadPdf };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "colorsbymax",
-  "version": "0.1.0",
-  "description": "colorsbymax™ by mrmaxdesigns: a runtime theme switcher with presets, a 715-theme library, custom palettes and WCAG contrast checks.",
+  "version": "0.2.0",
+  "description": "A live theme switcher for any website: site themes, 700+ palettes, for light/dark modes and WCAG contrast checks.",
   "keywords": [
     "theme",
     "theme-switcher",
@@ -25,47 +25,87 @@
     "url": "https://github.com/MaxMuyalwa/colorsbymax/issues"
   },
   "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "pdf": [
+        "./types/pdf.d.ts"
+      ],
+      "auto": [
+        "./types/auto.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./auto": {
+      "types": "./types/auto.d.ts",
+      "import": "./dist/auto.js",
+      "default": "./dist/auto.js"
+    },
+    "./pdf": {
+      "types": "./types/pdf.d.ts",
+      "import": "./dist/pdf.js",
+      "default": "./dist/pdf.js"
+    },
     "./tokens.css": "./src/tokens.css",
     "./package.json": "./package.json"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/auto.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "dist",
+    "types/index.d.ts",
+    "types/auto.d.ts",
+    "types/pdf.d.ts",
     "src/tokens.css",
     "LICENSE",
-    "THIRD_PARTY_NOTICES.md"
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "dev": "vite",
     "build": "node scripts/build-css.mjs && vite build --config vite.lib.config.js",
-    "prepare": "vite build --config vite.lib.config.js",
+    "typecheck": "tsc -p types && node scripts/check-types.mjs",
+    "prepublishOnly": "npm run build && npm run typecheck",
     "build:demo": "vite build",
     "css": "node scripts/build-css.mjs",
+    "icons": "node scripts/build-icons.mjs",
     "presets": "node scripts/generate-presets.mjs"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
-    "react-dom": "^18.2.0 || ^19.0.0"
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "pdfjs-dist": ">=4"
   },
-  "dependencies": {
-    "lucide-react": "^1.48.0",
-    "pdfjs-dist": "^6.3.289"
+  "peerDependenciesMeta": {
+    "pdfjs-dist": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
+    "lucide-react": "^1.48.0",
     "nice-color-palettes": "^4.0.0",
+    "pdfjs-dist": "^6.3.289",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3",
     "vite": "^8.3.1"
   },
   "license": "MIT"

package/types/auto.d.ts

@@ -0,0 +1,10 @@
+// Type declarations for 'colorsbymax/auto'. Importing the module mounts the colour button by
+// itself once the page has rendered: `import 'colorsbymax/auto'`.
+
+import type { ColorsByMaxConfig } from './index.js'
+
+/**
+ * Mounts the colour button and panel with settings, instead of the automatic mount. Calling it
+ * again replaces the previous mount. Returns a function that removes it.
+ */
+export function autoMount(config?: ColorsByMaxConfig): () => void

package/types/index.d.ts

@@ -0,0 +1,285 @@
+// Type declarations for colorsbymax. The package is written in JavaScript; these describe its
+// public API and are checked against real usage by types/check.tsx (npm run typecheck).
+
+import type { ReactElement, ReactNode } from 'react'
+
+// ---------------------------------------------------------------- tokens and themes
+
+/** Every themeable colour. Each is exposed to CSS as `--color-<key>`. */
+export type TokenKey =
+  | 'primary' | 'primary-dark' | 'primary-alt' | 'on-primary'
+  | 'background' | 'surface' | 'secondary' | 'on-secondary' | 'accent' | 'on-accent' | 'border' | 'shadow'
+  | 'ink' | 'ink-secondary' | 'ink-muted'
+  | 'success' | 'warning' | 'danger' | 'info'
+  | 'data-1' | 'data-2' | 'data-3' | 'data-4' | 'data-5' | 'data-6' | 'data-7' | 'data-8'
+  | 'app-background' | 'app-input' | 'app-border' | 'app-primary' | 'app-shadow-dark' | 'app-shadow-light' | 'app-ink' | 'app-ink-muted'
+
+/** Token key → `"#rrggbb"`. */
+export type ThemeTokens = Record<TokenKey, string>
+
+export interface Theme {
+  id: string
+  name: string
+  tokens: ThemeTokens
+  /** A palette the visitor created or imported. */
+  custom?: boolean
+  /** From the generated library. */
+  library?: boolean
+  /** One of the host site's own themes (including scan suggestions). */
+  site?: boolean
+  /** Suggested by a site scan. */
+  scanned?: boolean
+  /** A generated dark twin of a light theme. */
+  derived?: boolean
+  /** Library categories, for library themes. */
+  tags?: string[]
+}
+
+export interface TokenGroup {
+  group: string
+  tokens: { key: TokenKey; label: string; usage: string }[]
+}
+
+export const TOKEN_GROUPS: TokenGroup[]
+export const TOKEN_KEYS: TokenKey[]
+/** The neutral default theme's tokens (Slate). */
+export const BASE_TOKENS: ThemeTokens
+/** The hand-tuned themes shown as "Max's picks". */
+export const PRESETS: Theme[]
+
+/** Fills missing tokens from `base` (the neutral default unless given), deriving the secondary-area ones. */
+export function completeTokens(partial: Partial<ThemeTokens>, base?: ThemeTokens): ThemeTokens
+/** Derives the secondary-area (`app-*`) tokens from a theme's main palette. */
+export function deriveAppTokens(tokens: ThemeTokens): Pick<ThemeTokens, Extract<TokenKey, `app-${string}`>>
+
+// ---------------------------------------------------------------- React API
+
+export interface ColorsByMaxConfig {
+  /** Name of the first theme group, e.g. "Tsungi". Detected from the page if left out. */
+  siteName?: string
+  /** localStorage key; must match the pre-paint script. Defaults to "colorsbymax". */
+  storageKey?: string
+  /** The site's own colours. Missing tokens are filled in. */
+  defaultTheme?: { name: string; tokens: Partial<ThemeTokens> }
+  /** Extra themes made for the site. */
+  themes?: { id: string; name: string; tokens: Partial<ThemeTokens> }[]
+  /** Where each token is used on the site, shown in the colour editors. */
+  usage?: Partial<Record<TokenKey, string>>
+  /** Colour the page's scrollbars from the theme. Default true. */
+  scrollbars?: boolean
+  /** Enables PDF uploads: pass `loadPdf` from 'colorsbymax/pdf' (needs pdfjs-dist installed). */
+  pdf?: () => Promise<unknown>
+  /**
+   * Re-colour a site that doesn't paint with the --color-* variables, by swapping the colours
+   * actually on the page. 'auto' (the default) does it only when the site doesn't define
+   * --color-primary itself; false never does.
+   */
+  recolour?: boolean | 'auto'
+  /**
+   * Where the colour button starts. Default 'bottom-right', like chat and help widgets;
+   * 'top-right' sits just under a floating nav bar. Visitors can still drag it anywhere.
+   */
+  position?: 'bottom-right' | 'bottom-left' | 'top-left' | 'top-right'
+}
+
+export interface ThemeProviderProps {
+  config?: ColorsByMaxConfig
+  children?: ReactNode
+}
+
+/** Applies the saved or chosen theme to the page and provides it to the switcher and useTheme(). */
+export function ThemeProvider(props: ThemeProviderProps): ReactElement
+
+/** The floating colour button and panel. Render it once, inside ThemeProvider. */
+export function ThemeSwitcher(): ReactElement | null
+
+export interface ScanResult {
+  at: number
+  palette: string[]
+  themes: Theme[]
+}
+
+export interface ThemeState {
+  activeId: string
+  overrides: Partial<ThemeTokens>
+  customs: Theme[]
+  snapshot: Pick<Theme, 'id' | 'name' | 'tokens'> | null
+  scanned: ScanResult | null
+}
+
+export interface ThemeApi {
+  state: ThemeState
+  storageKey: string
+  siteName: string
+  usage: Partial<Record<TokenKey, string>>
+  loadPdf: (() => Promise<unknown>) | null
+  position: 'bottom-right' | 'bottom-left' | 'top-left' | 'top-right'
+  /** True when colorsbymax is swapping the page's own colours (the site isn't using the variables). */
+  recolouring: boolean
+  /** The site's own themes, then any scan suggestions. */
+  siteThemes: Theme[]
+  defaultTheme: Theme
+  presets: Theme[]
+  customs: Theme[]
+  /** Site themes, presets and custom palettes (not the library). */
+  themes: Theme[]
+  /** The applied theme. */
+  active: Theme
+  /** The applied colours: the active theme plus any overrides. */
+  tokens: ThemeTokens
+  /** Contrast problems in the applied colours. */
+  issues: ContrastIssue[]
+
+  /** Selects a theme by id; pass the theme itself for library themes and dark twins. */
+  selectTheme(id: string, theme?: Theme): void
+  /** Creates a custom palette from the current colours and applies it. Returns its id. */
+  createCustom(name: string): string
+  updateCustomToken(id: string, key: TokenKey, value: string): void
+  renameCustom(id: string, name: string): void
+  deleteCustom(id: string): void
+  /** Adds tokens as a new custom palette and applies it. Returns its id. */
+  addPalette(name: string, tokens: Partial<ThemeTokens>): string
+
+  setOverride(key: TokenKey, value: string): void
+  clearOverride(key: TokenKey): void
+  clearOverrides(): void
+  resetToDefault(): void
+
+  scanned: ScanResult | null
+  /** Reads the page's colours and adds themes built around them. Resolves to counts for the UI. */
+  runScan(): Promise<{ colours: number; themes: number }>
+  clearScan(): void
+
+  /** Fixes one issue by adjusting lightness. Returns false if no single change could. */
+  fixIssue(issue: ContrastIssue): boolean
+  fixAllIssues(): void
+
+  /** The applied theme as `{ name, tokens }` JSON. */
+  exportTheme(): string
+  /** Imports `{ name, tokens }` JSON as a custom palette. Returns an error message, or null. */
+  importTheme(json: string): string | null
+}
+
+/** The theme state and actions. Must be called inside ThemeProvider. */
+export function useTheme(): ThemeApi
+
+/** Writes each token to `--color-<key>` on `<html>`. */
+export function applyTokens(tokens: ThemeTokens): void
+
+// ---------------------------------------------------------------- pre-paint and settings
+
+export const DEFAULT_STORAGE_KEY: 'colorsbymax'
+/** Source of an inline `<script>` for `<head>` that applies the saved theme before first paint. */
+export function prePaintScript(storageKey?: string): string
+
+export interface PanelSettings {
+  mode: 'light' | 'dark' | 'system'
+  showPicks: boolean
+  showLibrary: boolean
+  showCustom: boolean
+  showOverrides: boolean
+  showImportExport: boolean
+  draggable: boolean
+  animateDot: boolean
+  panelWidth: number | null
+  panelHeight: number | 'full' | null
+  libraryCollapsed: boolean
+}
+/** The visitor settings the panel starts with. */
+export const DEFAULT_SETTINGS: PanelSettings
+
+// ---------------------------------------------------------------- contrast
+
+export type PairingKind = 'text' | 'large-text' | 'non-text'
+
+export interface Pairing {
+  id: string
+  label: string
+  kind: PairingKind
+  fg(tokens: ThemeTokens): string
+  bg(tokens: ThemeTokens): string
+  /** Tokens auto-fix may adjust, in preference order. */
+  fixable: TokenKey[]
+}
+
+export interface ContrastIssue {
+  pairing: Pairing
+  ratio: number
+  required: number
+  /** e.g. "Primary text on background: 2.7:1 — text will be hard to read (needs 4.5:1)" */
+  message: string
+}
+
+/** Every foreground/background pairing colorsbymax checks. */
+export const PAIRINGS: Pairing[]
+export const MIN_CONTRAST_TEXT: number
+export const MIN_CONTRAST_LARGE_TEXT: number
+export const MIN_CONTRAST_NON_TEXT: number
+export const MIN_RAMP_STEP_DELTA_E: number
+
+/** Every failing pairing in a theme. */
+export function checkTheme(tokens: ThemeTokens): ContrastIssue[]
+/** The smallest lightness change to one token that makes a pairing pass, or null. */
+export function suggestFix(pairing: Pairing, tokens: ThemeTokens): { key: TokenKey; value: string } | null
+/** Fixes failing pairings until the theme passes or nothing more helps. Returns the changed tokens. */
+export function fixAll(tokens: ThemeTokens): Partial<ThemeTokens>
+/** Problems with an ordered colour ramp drawn on `surface`, as sentences. */
+export function checkRamp(colors: string[], surface: string): string[]
+
+// ---------------------------------------------------------------- colour helpers
+
+/** WCAG 2 contrast ratio between two hex colours, 1–21. */
+export function contrastRatio(a: string, b: string): number
+/** "#abc", "abc" or "#AABBCC" → "#aabbcc"; null for anything else. */
+export function normalizeHex(input: unknown): string | null
+
+// ---------------------------------------------------------------- light and dark
+
+/** True when a theme's page background is dark. */
+export function isDarkTheme(tokens: ThemeTokens): boolean
+/** Dark versions of a light theme's tokens, adjusted to pass contrast. */
+export function darkTokens(tokens: ThemeTokens): ThemeTokens
+/** The dark twin of a light theme (themes that are already dark come back unchanged). */
+export function toDark<T extends Theme>(theme: T): T
+
+// ---------------------------------------------------------------- site scan
+
+export interface ColourTally {
+  hex: string
+  /** Area painted as a background. */
+  bg: number
+  /** Weighted amount of text in this colour. */
+  text: number
+  /** Border length in this colour. */
+  border: number
+}
+
+export type Roles = Partial<Record<TokenKey, string>>
+
+/** The page's painted colours, ignoring any applied theme. `exclude` is a selector to skip. */
+export function collectColors(options?: { exclude?: string }): ColourTally[]
+/** Works out token roles from collected colours. */
+export function inferRoles(colors: ColourTally[]): { roles: Roles; palette: string[] }
+/** A complete theme from detected roles, deriving whatever wasn't found. */
+export function themeFromRoles(
+  roles: Roles,
+  variant?: { softness?: number; boldness?: number; complementary?: boolean },
+): ThemeTokens
+/** Themes suggested for a scanned site, named after it, plus the closest library themes. */
+export function suggestThemes(scan: { roles: Roles }, siteName: string, library?: Theme[]): Theme[]
+/** Best guess at the site's name: og:site_name, then the title, then the host. */
+export function detectSiteName(doc?: Document): string
+
+// ---------------------------------------------------------------- palettes from files
+
+/** The main colours in an image (or a PDF, with `loadPdf`), most important first. */
+export function coloursFromFile(
+  file: File,
+  options?: { loadPdf?: (() => Promise<unknown>) | null },
+): Promise<{ colours: string[]; from: 'image' | 'pdf-text' | 'pdf' }>
+/** The dominant colours in sets of RGBA pixels, edge blends removed. */
+export function dominantColours(pixelSets: Uint8ClampedArray[]): string[]
+/** Assigns a palette's colours to theme roles. */
+export function rolesFromPalette(colours: string[]): Roles
+/** A complete, contrast-checked theme built around a palette. */
+export function themeFromPalette(colours: string[]): ThemeTokens

package/types/pdf.d.ts

@@ -0,0 +1,7 @@
+// Type declarations for 'colorsbymax/pdf'.
+
+/**
+ * Loads PDF.js for PDF uploads. Pass it as `pdf` in the ThemeProvider config; needs the
+ * pdfjs-dist package installed. PDF.js downloads only when a visitor picks a PDF.
+ */
+export function loadPdf(): Promise<unknown>