chart-factory 0.1.2

package/src/core/example-nav.js

@@ -0,0 +1,249 @@
+/**
+ * Shared Example Navigation
+ *
+ * Usage: Include this script and call initExampleNav() with the current page name.
+ *
+ * Example:
+ *   <script src="../../src/core/example-nav.js"></script>
+ *   <script>initExampleNav('scatter-plot', 'basic-example.html');</script>
+ */
+
+const EXAMPLE_NAV_CONFIG = {
+    'histogram-chart': [
+        { href: 'basic-example.html', label: 'Basic + Overlay' }
+    ],
+    'donut-chart': [
+        { href: 'basic-example.html', label: 'Donut + Pie' }
+    ],
+    'box-plot': [
+        { href: 'basic-example.html', label: 'Vertical + Horizontal' }
+    ],
+    'calendar-heatmap': [
+        { href: 'basic-example.html', label: 'Three layouts' }
+    ],
+    'sankey': [
+        { href: 'basic-example.html', label: 'Basic + Aligned' }
+    ],
+    'scatter-plot': [
+        { href: 'basic-example.html', label: 'Basic' },
+        { href: 'logos-example.html', label: 'Logos' },
+        { href: 'animated-example.html', label: 'Animated' },
+        { href: 'trajectory-example.html', label: 'Trajectory' },
+        { href: 'comet-example.html', label: 'Comet' },
+        { href: 'dot-labels-example.html', label: 'Dot Labels' },
+        { href: 'beeswarm-example.html', label: 'Beeswarm' },
+        { href: 'beeswarm-vertical-example.html', label: 'Vertical' },
+        { href: 'beeswarm-logos-example.html', label: 'Swarm Logos' },
+        { href: 'beeswarm-horizontal-example.html', label: 'Horizontal' },
+        { href: 'heatmap-example.html', label: 'Heatmap' },
+        { href: 'hexbin-example.html', label: 'Hexbin' },
+        { href: 'contour-example.html', label: 'Contour' },
+        { href: 'quadrant-example.html', label: 'Quadrant' },
+        { href: 'diagonal-example.html', label: 'Diagonal' },
+        { href: 'marginal-example.html', label: 'Marginal' },
+        { href: 'marginal-simple-example.html', label: 'Simple' },
+        { href: 'kde-example.html', label: 'KDE' }
+    ],
+    'line-chart': [
+        { href: 'showcase.html', label: 'Showcase' },
+        { href: 'basic-example.html', label: 'Basic' },
+        { href: 'yearly-example.html', label: 'Yearly' },
+        { href: 'smoothed-example.html', label: 'Smoothed' },
+        { href: 'combined-example.html', label: 'Combined' },
+        { href: 'yoy-example.html', label: 'YoY' },
+        { href: 'textures-example.html', label: 'Textures' },
+        { href: 'area-gradient-example.html', label: 'Area' },
+        { href: 'growth-example.html', label: 'Growth' },
+        { href: 'forecast-example.html', label: 'Forecast' },
+        { href: 'events-example.html', label: 'Events' },
+        { href: 'dynamic-band-example.html', label: 'Dynamic' },
+        { href: 'pulse-example.html', label: 'Pulse' },
+        { href: 'cumulative-vs-moving-example.html', label: 'Cumulative' },
+        { href: 'bump-example.html', label: 'Bump' }
+    ],
+    'area-chart': [
+        { href: 'showcase.html', label: 'Showcase' },
+        { href: 'basic-example.html', label: 'Basic' },
+        { href: 'stacked-example.html', label: 'Stacked' },
+        { href: 'normalized-example.html', label: '100%' },
+        { href: 'smoothed-example.html', label: 'Smoothed' },
+        { href: 'diverging-example.html', label: 'Diverging' },
+        { href: 'streamgraph-example.html', label: 'Stream' }
+    ],
+    'slope-chart': [
+        { href: 'showcase.html', label: 'Showcase' },
+        { href: 'basic-example.html', label: 'Trend' },
+        { href: 'categorical-example.html', label: 'Categorical' },
+        { href: 'highlight-example.html', label: 'Highlight' },
+        { href: 'animated-example.html', label: 'Animated' },
+        { href: 'bands-example.html', label: 'Bands' },
+        { href: 'indexed-example.html', label: 'Indexed' }
+    ],
+    'dot-chart': [
+        { href: 'showcase.html', label: 'Showcase' },
+        { href: 'basic-example.html', label: 'Basic' },
+        { href: 'dumbbell-example.html', label: 'Dumbbell' },
+        { href: 'gradient-example.html', label: 'Gradient' },
+        { href: 'comet-example.html', label: 'Comet' },
+        { href: 'confidence-example.html', label: 'Confidence' },
+        { href: 'percentile-example.html', label: 'Percentile' },
+        { href: 'unit-histogram-example.html', label: 'Histogram' }
+    ],
+    'bar-chart': [
+        { href: 'basic-example.html', label: 'Basic' },
+        { href: 'inline-example.html', label: 'Inline' },
+        { href: 'label-above-example.html', label: 'Label Above' },
+        { href: 'stacked-example.html', label: 'Stacked' },
+        { href: 'grouped-example.html', label: 'Grouped' },
+        { href: 'progress-example.html', label: 'Progress' },
+        { href: 'bullet-example.html', label: 'Bullet' },
+        { href: 'diverging-example.html', label: 'Diverging' },
+        { href: 'likert-example.html', label: 'Likert' },
+        { href: 'gantt-example.html', label: 'Gantt' },
+        { href: 'range-example.html', label: 'Range' },
+        { href: 'waterfall-example.html', label: 'Waterfall' },
+        { href: 'pyramid-example.html', label: 'Pyramid' },
+        { href: 'vertical-example.html', label: 'Vertical' },
+        { href: 'vertical-stacked-example.html', label: 'V-Stacked' },
+        { href: 'vertical-normalized-example.html', label: 'V-100%' }
+    ],
+    'table': [
+        { href: 'showcase.html', label: 'Showcase' },
+        { href: 'percent-bar-example.html', label: 'Percent Bar' },
+        { href: 'sparkline-example.html', label: 'Sparkline' },
+        { href: 'logos-example.html', label: 'Logos & Images' },
+        { href: 'expandable-example.html', label: 'Expandable Rows' },
+        { href: 'sticky-example.html', label: 'Sticky, Caps & Totals' },
+        { href: 'column-groups-example.html', label: 'Column Groups' }
+    ]
+};
+
+/**
+ * Initialize the example navigation bar
+ * @param {string} chartType - The chart type folder name (e.g., 'scatter-plot')
+ * @param {string} currentPage - The current page filename (e.g., 'basic-example.html')
+ */
+function initExampleNav(chartType, currentPage) {
+    // Check if we're in modal view - don't render nav, report height to parent
+    if (location.search.includes('modal=1')) {
+        document.body.classList.add('modal-view');
+        initModalSizeReporting();
+        return;
+    }
+
+    const config = EXAMPLE_NAV_CONFIG[chartType];
+    if (!config) {
+        console.warn(`No navigation config found for chart type: ${chartType}`);
+        return;
+    }
+
+    // Create nav element
+    const nav = document.createElement('nav');
+    nav.className = 'example-nav';
+
+    // Generate links
+    config.forEach(item => {
+        const link = document.createElement('a');
+        link.href = item.href;
+        link.textContent = item.label;
+        if (item.href === currentPage) {
+            link.className = 'active';
+        }
+        nav.appendChild(link);
+    });
+
+    // Insert at the beginning of body
+    document.body.insertBefore(nav, document.body.firstChild);
+
+    // Add body padding for fixed nav
+    document.body.style.paddingTop = '60px';
+}
+
+/**
+ * Enforce the modal layout with inline styles (belt and braces alongside
+ * body.modal-view CSS — inline styles win even over a stale cached
+ * stylesheet): the chart container must be the iframe's entire content.
+ * Must run BEFORE the page's chart script so the responsive chart renders at
+ * its final (unpadded) width on the first pass — no post-load size jump.
+ */
+function applyModalLayout() {
+    const b = document.body.style;
+    b.setProperty('padding', '0', 'important');
+    b.setProperty('margin', '0', 'important');
+    b.setProperty('min-height', '0', 'important');
+    b.setProperty('display', 'block', 'important');
+    b.setProperty('overflow', 'hidden', 'important');
+    const container = document.querySelector('.chart-container');
+    if (container) {
+        container.style.setProperty('width', '100%', 'important');
+        container.style.setProperty('max-width', 'none', 'important');
+        container.style.setProperty('box-shadow', 'none', 'important');
+    }
+}
+
+/**
+ * Modal size reporting: the parent showcase owns the iframe WIDTH; the child
+ * reports its rendered HEIGHT so the iframe can fit the chart. Charts are
+ * responsive, so they render at whatever width the parent gave the iframe.
+ */
+function initModalSizeReporting() {
+    if (window.parent === window) return;
+
+    applyModalLayout();
+
+    const report = () => {
+        const container = document.querySelector('.chart-container') || document.body;
+        window.parent.postMessage({
+            type: 'chartSize',
+            height: Math.ceil(container.getBoundingClientRect().height)
+        }, '*');
+    };
+
+    // Layout is measurable synchronously; report now and again after the
+    // responsive first render / webfonts settle. (Deliberately timer-based:
+    // rAF can be throttled inside iframes.)
+    const start = () => {
+        report();
+        setTimeout(report, 150);
+        setTimeout(report, 500);
+    };
+    if (document.readyState === 'complete') {
+        start();
+    } else {
+        window.addEventListener('load', start);
+    }
+
+    // Re-report if content height settles later (fonts, debounced re-renders)
+    if (typeof ResizeObserver !== 'undefined') {
+        new ResizeObserver(() => report()).observe(document.body);
+    }
+}
+
+/**
+ * Auto-initialize if data attributes are present on script tag
+ * Usage: <script src="example-nav.js" data-chart-type="scatter-plot" data-current="basic-example.html"></script>
+ */
+(function() {
+    // In modal mode, neutralize the standalone-page layout IMMEDIATELY —
+    // this script tag sits before the chart script, so the chart's first
+    // render happens at the final modal width (no resize jump after load).
+    if (location.search.includes('modal=1') && document.body) {
+        document.body.classList.add('modal-view');
+        applyModalLayout();
+    }
+
+    const scripts = document.getElementsByTagName('script');
+    const currentScript = scripts[scripts.length - 1];
+
+    const chartType = currentScript.getAttribute('data-chart-type');
+    const currentPage = currentScript.getAttribute('data-current');
+
+    if (chartType && currentPage) {
+        // Wait for DOM to be ready
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => initExampleNav(chartType, currentPage));
+        } else {
+            initExampleNav(chartType, currentPage);
+        }
+    }
+})();

package/src/core/palettes.js

@@ -0,0 +1,310 @@
+/**
+ * Color palettes for Chart Factory.
+ *
+ * A curated palette library organized by use case, with accessibility (CVD-safe)
+ * metadata and D3 scale helpers. Exposed on the factory as `ChartFactory.palettes`.
+ *
+ * A palette name is a plain string, so it drops into the option people already
+ * reach for: `colors: 'Set2'` (categorical → array) or `colorScheme: 'Viridis'`
+ * (sequential/diverging → interpolator). Configs stay pure JSON.
+ *
+ *   ChartFactory.palettes.get('Set2')            // ['#66c2a5', ...]
+ *   ChartFactory.palettes.ordinalScale('Set2')   // d3.scaleOrdinal
+ *   ChartFactory.palettes.colorScale('Viridis', [0, 100])  // d3.scaleSequential
+ *   ChartFactory.palettes.isColorblindSafe('Set2')         // true
+ *
+ * Sequential/diverging ramps re-anchor their pale end toward the container
+ * surface under `[data-theme="dark"]` (mirroring the built-in --scale-* tokens),
+ * so a light-ended ramp doesn't glare on a dark background. Categorical palettes
+ * are distinct hues and pass through unchanged on both themes.
+ *
+ * @module chart-factory/core/palettes
+ */
+
+import * as d3 from 'd3';
+import { getCSSVar } from './d3-base.js';
+
+// =============================================================================
+// SEQUENTIAL — ordered continuous data (heatmaps, density, intensity)
+// =============================================================================
+
+export const SEQUENTIAL_PALETTES = {
+  Viridis: ['#fde725','#dde318','#bade28','#95d840','#75d054','#56c667','#3dbc74','#29af7f','#20a386','#1f968b','#238a8d','#287d8e','#2d718e','#33638d','#39558c','#404688','#453781','#482576','#481467','#440154'],
+  Inferno: ['#fcffa4','#f1ed71','#f6d543','#fbba1f','#fca108','#f8870e','#f1711f','#e55c30','#d74b3f','#c43c4e','#b1325a','#9b2964','#87216b','#71196e','#5c126e','#450a69','#2f0a5b','#180c3c','#08051d','#000004'],
+  Magma: ['#fcfdbf','#fde5a7','#fecd90','#feb47b','#fd9b6b','#fa815f','#f4695c','#e85362','#d6456c','#c03a76','#ab337c','#942c80','#802582','#6a1c81','#56147d','#3f0f72','#29115a','#150e38','#07061c','#000004'],
+  Plasma: ['#f0f921','#f7e225','#fccd25','#feb72d','#fca338','#f79044','#f07f4f','#e76e5b','#dd5e66','#d14e72','#c5407e','#b6308b','#a72197','#9511a1','#8305a7','#6e00a8','#5901a5','#43039e','#2c0594','#0d0887'],
+  Blues: ['#f7fbff','#deebf7','#c6dbef','#9ecae1','#6baed6','#4292c6','#2171b5','#08519c','#08306b'],
+  BluesDark: ['#08306b','#08519c','#2171b5','#4292c6','#6baed6','#9ecae1','#c6dbef','#deebf7','#f7fbff'],
+  Greens: ['#f7fcf5','#e5f5e0','#c7e9c0','#a1d99b','#74c476','#41ab5d','#238b45','#006d2c','#00441b'],
+  Greys: ['#ffffff','#f0f0f0','#d9d9d9','#bdbdbd','#969696','#737373','#525252','#252525','#000000'],
+  Oranges: ['#fff5eb','#fee6ce','#fdd0a2','#fdae6b','#fd8d3c','#f16913','#d94801','#a63603','#7f2704'],
+  Purples: ['#fcfbfd','#efedf5','#dadaeb','#bcbddc','#9e9ac8','#807dba','#6a51a3','#54278f','#3f007d'],
+  Reds: ['#fff5f0','#fee0d2','#fcbba1','#fc9272','#fb6a4a','#ef3b2c','#cb181d','#a50f15','#67000d'],
+  BuGn: ['#f7fcfd','#e5f5f9','#ccece6','#99d8c9','#66c2a4','#41ae76','#238b45','#006d2c','#00441b'],
+  BuPu: ['#f7fcfd','#e0ecf4','#bfd3e6','#9ebcda','#8c96c6','#8c6bb1','#88419d','#810f7c','#4d004b'],
+  GnBu: ['#f7fcf0','#e0f3db','#ccebc5','#a8ddb5','#7bccc4','#4eb3d3','#2b8cbe','#0868ac','#084081'],
+  OrRd: ['#fff7ec','#fee8c8','#fdd49e','#fdbb84','#fc8d59','#ef6548','#d7301f','#b30000','#7f0000'],
+  PuBu: ['#fff7fb','#ece7f2','#d0d1e6','#a6bddb','#74a9cf','#3690c0','#0570b0','#045a8d','#023858'],
+  PuBuGn: ['#fff7fb','#ece2f0','#d0d1e6','#a6bddb','#67a9cf','#3690c0','#02818a','#016c59','#014636'],
+  PuRd: ['#f7f4f9','#e7e1ef','#d4b9da','#c994c7','#df65b0','#e7298a','#ce1256','#980043','#67001f'],
+  RdPu: ['#fff7f3','#fde0dd','#fcc5c0','#fa9fb5','#f768a1','#dd3497','#ae017e','#7a0177','#49006a'],
+  YlGn: ['#ffffe5','#f7fcb9','#d9f0a3','#addd8e','#78c679','#41ab5d','#238443','#006837','#004529'],
+  YlGnBu: ['#ffffd9','#edf8b1','#c7e9b4','#7fcdbb','#41b6c4','#1d91c0','#225ea8','#253494','#081d58'],
+  YlOrBr: ['#ffffe5','#fff7bc','#fee391','#fec44f','#fe9929','#ec7014','#cc4c02','#993404','#662506'],
+  YlOrRd: ['#ffffcc','#ffeda0','#fed976','#feb24c','#fd8d3c','#fc4e2a','#e31a1c','#bd0026','#800026'],
+  Spectral: ['#9e0142','#d53e4f','#f46d43','#fdae61','#fee08b','#ffffbf','#e6f598','#abdda4','#66c2a5','#3288bd','#5e4fa2'],
+};
+
+// =============================================================================
+// DIVERGING — data with a meaningful midpoint (positive vs negative)
+// =============================================================================
+
+export const DIVERGING_PALETTES = {
+  BrBG: ['#543005','#8c510a','#bf812d','#dfc27d','#f6e8c3','#f5f5f5','#c7eae5','#80cdc1','#35978f','#01665e','#003c30'],
+  PRGn: ['#40004b','#762a83','#9970ab','#c2a5cf','#e7d4e8','#f7f7f7','#d9f0d3','#a6dba0','#5aae61','#1b7837','#00441b'],
+  PiYG: ['#8e0152','#c51b7d','#de77ae','#f1b6da','#fde0ef','#f7f7f7','#e6f5d0','#b8e186','#7fbc41','#4d9221','#276419'],
+  PuOr: ['#7f3b08','#b35806','#e08214','#fdb863','#fee0b6','#f7f7f7','#d8daeb','#b2abd2','#8073ac','#542788','#2d004b'],
+  RdBu: ['#67001f','#b2182b','#d6604d','#f4a582','#fddbc7','#f7f7f7','#d1e5f0','#92c5de','#4393c3','#2166ac','#053061'],
+  RdGy: ['#67001f','#b2182b','#d6604d','#f4a582','#fddbc7','#ffffff','#e0e0e0','#bababa','#878787','#4d4d4d','#1a1a1a'],
+  RdYlBu: ['#a50026','#d73027','#f46d43','#fdae61','#fee090','#ffffbf','#e0f3f8','#abd9e9','#74add1','#4575b4','#313695'],
+  RdYlGn: ['#a50026','#d73027','#f46d43','#fdae61','#fee08b','#ffffbf','#d9ef8b','#a6d96a','#66bd63','#1a9850','#006837'],
+  Temperature: ['#7ab8ff','#9ccaff','#b8d9ff','#d6e8ff','#f2f7ff','#fff1c1','#ffd27f','#ffb347','#ff8c1a','#ff6a00'],
+  MaroonMidnight: ['#8C1932','#FF6437','#E8E8E8','#509BF5','#1E3264'],
+  SunsetOcean: ['#FF6437','#F98563','#F78C6C','#EDC7BB','#E8E8E8','#C2D4EB','#8EBAEE','#76AEF1','#509BF5'],
+  MaroonForest: ['#8C1932','#FF6437','#E8E8E8','#4B917D','#006450'],
+};
+
+// =============================================================================
+// CATEGORICAL — nominal categories with no inherent order
+// =============================================================================
+
+export const CATEGORICAL_PALETTES = {
+  Set1: ['#e41a1c','#377eb8','#4daf4a','#984ea3','#ff7f00','#ffff33','#a65628','#f781bf','#999999'],
+  Set2: ['#66c2a5','#fc8d62','#8da0cb','#e78ac3','#a6d854','#ffd92f','#e5c494','#b3b3b3'],
+  Set3: ['#8dd3c7','#ffffb3','#bebada','#fb8072','#80b1d3','#fdb462','#b3de69','#fccde5','#d9d9d9','#bc80bd','#ccebc5','#ffed6f'],
+  Paired: ['#a6cee3','#1f78b4','#b2df8a','#33a02c','#fb9a99','#e31a1c','#fdbf6f','#ff7f00','#cab2d6','#6a3d9a','#ffff99','#b15928'],
+  Dark2: ['#1b9e77','#d95f02','#7570b3','#e7298a','#66a61e','#e6ab02','#a6761d','#666666'],
+  Accent: ['#7fc97f','#beaed4','#fdc086','#ffff99','#386cb0','#f0027f','#bf5b17','#666666'],
+  Pastel1: ['#fbb4ae','#b3cde3','#ccebc5','#decbe4','#fed9a6','#ffffcc','#e5d8bd','#fddaec','#f2f2f2'],
+  Pastel2: ['#b3e2cd','#fdcdac','#cbd5e8','#f4cae4','#e6f5c9','#fff2ae','#f1e2cc','#cccccc'],
+  ChartDefault: ['#3b82f6','#22c55e','#f97316','#a855f7','#ef4444'],
+  OkabeIto: ['#E69F00','#56B4E9','#009E73','#F0E442','#0072B2','#D55E00','#CC79A7','#000000'],
+  Status: ['#22c55e','#f59e0b','#ef4444','#3b82f6'],
+  Binary: ['#3b82f6','#e5e7eb'],
+};
+
+// =============================================================================
+// ALERT — highlight values at one end of the scale
+// =============================================================================
+
+export const ALERT_PALETTES = {
+  AquaAlert: ['#E8E8E8','#b4b4b4','#4100F5'],
+  OrangeAlert: ['#E8E8E8','#b4b4b4','#FF4632'],
+  SalmonAlert: ['#E8E8E8','#b4b4b4','#F037A5'],
+  ForestAlert: ['#E8E8E8','#b4b4b4','#19E68C'],
+};
+
+// =============================================================================
+// COUNTRY COLORS — consistent per-country colors, loosely inspired by flags
+// =============================================================================
+
+export const COUNTRY_COLORS = {
+  US: '#1f78b4', CA: '#e31a1c', GB: '#a6cee3', UK: '#a6cee3', BR: '#33a02c',
+  DE: '#ff7f00', MX: '#eab308', FR: '#6a3d9a', JP: '#fb9a99', AU: '#cab2d6',
+  IT: '#b2df8a', ES: '#fdbf6f', IN: '#b15928', CN: '#c41e3a', NL: '#ff7f00',
+  SE: '#1f78b4', NO: '#e31a1c', CH: '#e31a1c', AT: '#e31a1c', PL: '#e31a1c',
+  BE: '#eab308', KR: '#a6cee3', AR: '#a6cee3', RoW: '#6b7280', ROW: '#6b7280',
+};
+
+// Unique country colors only (for legends), exposed in ALL_PALETTES as "Countries"
+export const COUNTRY_PALETTE = [
+  '#1f78b4','#e31a1c','#a6cee3','#33a02c','#ff7f00','#eab308','#6a3d9a',
+  '#fb9a99','#cab2d6','#b2df8a','#fdbf6f','#b15928','#c41e3a','#6b7280',
+];
+
+// =============================================================================
+// COMBINED LOOKUP + METADATA
+// =============================================================================
+
+export const ALL_PALETTES = {
+  ...SEQUENTIAL_PALETTES,
+  ...DIVERGING_PALETTES,
+  ...CATEGORICAL_PALETTES,
+  ...ALERT_PALETTES,
+  Countries: COUNTRY_PALETTE,
+};
+
+/** @type {Record<string, {type:'sequential'|'diverging'|'categorical'|'alert', tags:string[], colorblindSafe:boolean, maxCategories?:number, description:string}>} */
+export const PALETTE_METADATA = {
+  Viridis: { type: 'sequential', tags: ['heatmap','density','continuous','perceptually-uniform','scientific'], colorblindSafe: true, description: 'Perceptually uniform, colorblind-safe. Best for scientific visualization.' },
+  Inferno: { type: 'sequential', tags: ['heatmap','density','continuous','perceptually-uniform','dark-theme','intensity'], colorblindSafe: true, description: 'High contrast, works well on dark backgrounds.' },
+  Magma: { type: 'sequential', tags: ['heatmap','density','continuous','perceptually-uniform','warm'], colorblindSafe: true, description: 'Warm tones, good for density plots and heatmaps.' },
+  Plasma: { type: 'sequential', tags: ['heatmap','density','continuous','perceptually-uniform','vibrant'], colorblindSafe: true, description: 'Vibrant purple-to-yellow, high visual impact.' },
+  Blues: { type: 'sequential', tags: ['single-hue','water','cold','corporate','neutral','print-friendly'], colorblindSafe: true, description: 'Classic blue gradient. Safe, professional choice.' },
+  BluesDark: { type: 'sequential', tags: ['single-hue','dark-mode','dark-background','inverted'], colorblindSafe: true, description: 'Inverted Blues for dark backgrounds (dark to light).' },
+  Greens: { type: 'sequential', tags: ['single-hue','nature','growth','environmental','positive','print-friendly'], colorblindSafe: true, description: 'Nature/growth associations. Good for environmental data.' },
+  Greys: { type: 'sequential', tags: ['single-hue','neutral','monochrome','print-friendly','background'], colorblindSafe: true, description: 'Neutral grayscale. Best for secondary/background data.' },
+  Oranges: { type: 'sequential', tags: ['single-hue','warm','energy','attention','print-friendly'], colorblindSafe: true, description: 'Warm orange tones. Good for energy/activity metrics.' },
+  Purples: { type: 'sequential', tags: ['single-hue','elegant','premium','creative','print-friendly'], colorblindSafe: true, description: 'Elegant purple gradient. Good for premium/creative contexts.' },
+  Reds: { type: 'sequential', tags: ['single-hue','heat','intensity','danger','attention','print-friendly'], colorblindSafe: false, description: 'Intensity/heat associations. Use sparingly (red-green confusion).' },
+  BuGn: { type: 'sequential', tags: ['multi-hue','water','nature','cool'], colorblindSafe: true, description: 'Blue to green. Good for water/environmental data.' },
+  BuPu: { type: 'sequential', tags: ['multi-hue','cool','elegant'], colorblindSafe: true, description: 'Blue to purple. Cool, elegant progression.' },
+  GnBu: { type: 'sequential', tags: ['multi-hue','nature','water','cool'], colorblindSafe: true, description: 'Green to blue. Nature-to-water transition.' },
+  OrRd: { type: 'sequential', tags: ['multi-hue','warm','heat','intensity'], colorblindSafe: false, description: 'Orange to red. Heat/intensity scale.' },
+  PuBu: { type: 'sequential', tags: ['multi-hue','cool','calm'], colorblindSafe: true, description: 'Purple to blue. Cool, calming tones.' },
+  PuBuGn: { type: 'sequential', tags: ['multi-hue','cool','nature'], colorblindSafe: true, description: 'Purple to blue to green. Wide cool range.' },
+  PuRd: { type: 'sequential', tags: ['multi-hue','warm','intensity'], colorblindSafe: false, description: 'Purple to red. Intensity with warm endpoint.' },
+  RdPu: { type: 'sequential', tags: ['multi-hue','warm','feminine'], colorblindSafe: false, description: 'Red to purple. Warm, vibrant tones.' },
+  YlGn: { type: 'sequential', tags: ['multi-hue','nature','growth','positive'], colorblindSafe: true, description: 'Yellow to green. Growth/nature associations.' },
+  YlGnBu: { type: 'sequential', tags: ['multi-hue','nature','water','versatile'], colorblindSafe: true, description: 'Yellow to green to blue. Versatile, natural feel.' },
+  YlOrBr: { type: 'sequential', tags: ['multi-hue','warm','earth','desert'], colorblindSafe: true, description: 'Yellow to orange to brown. Earth/desert tones.' },
+  YlOrRd: { type: 'sequential', tags: ['multi-hue','warm','heat','intensity','fire'], colorblindSafe: false, description: 'Yellow to orange to red. Fire/heat associations.' },
+  Spectral: { type: 'sequential', tags: ['multi-hue','rainbow','full-spectrum','scientific'], colorblindSafe: false, description: 'Full spectrum rainbow. Use for specific scientific contexts.' },
+  BrBG: { type: 'diverging', tags: ['earth','nature','land-water','environmental'], colorblindSafe: true, description: 'Brown to blue-green. Land vs water, dry vs wet.' },
+  PRGn: { type: 'diverging', tags: ['purple-green','contrast','neutral-midpoint'], colorblindSafe: true, description: 'Purple to green. High contrast diverging scale.' },
+  PiYG: { type: 'diverging', tags: ['pink-green','contrast','vibrant'], colorblindSafe: true, description: 'Pink to yellow-green. Vibrant diverging scale.' },
+  PuOr: { type: 'diverging', tags: ['purple-orange','warm-cool','contrast'], colorblindSafe: true, description: 'Purple to orange. Strong warm/cool contrast.' },
+  RdBu: { type: 'diverging', tags: ['red-blue','hot-cold','classic','political'], colorblindSafe: false, description: 'Red to blue. Classic hot/cold, also political mapping.' },
+  RdGy: { type: 'diverging', tags: ['red-gray','positive-neutral','muted'], colorblindSafe: false, description: 'Red to gray. Good when one direction is "neutral".' },
+  RdYlBu: { type: 'diverging', tags: ['red-yellow-blue','traffic-light','intuitive'], colorblindSafe: false, description: 'Red to yellow to blue. Intuitive bad-neutral-good.' },
+  RdYlGn: { type: 'diverging', tags: ['red-yellow-green','traffic-light','performance','intuitive'], colorblindSafe: false, description: 'Red to yellow to green. Traffic light / performance scale.' },
+  Temperature: { type: 'diverging', tags: ['temperature','kelvin','cold-warm','percentile','custom'], colorblindSafe: true, description: 'Kelvin-inspired cold blue to warm amber. Good for percentiles.' },
+  MaroonMidnight: { type: 'diverging', tags: ['warm-cool','maroon-blue','contrast','editorial'], colorblindSafe: false, description: 'Maroon to midnight blue through neutral gray.' },
+  SunsetOcean: { type: 'diverging', tags: ['warm-cool','orange-blue','granular','editorial'], colorblindSafe: true, description: '9-step warm orange to cool blue through neutral gray.' },
+  MaroonForest: { type: 'diverging', tags: ['warm-green','maroon-forest','contrast','editorial'], colorblindSafe: false, description: 'Maroon to forest green through neutral gray.' },
+  Set1: { type: 'categorical', tags: ['bold','saturated','high-contrast','colorbrewer'], colorblindSafe: false, maxCategories: 9, description: 'Bold, saturated colors. High visual impact.' },
+  Set2: { type: 'categorical', tags: ['muted','pastel','area-fills','soft','colorbrewer','house-default'], colorblindSafe: true, maxCategories: 8, description: 'Softer, muted colors. Good for filled areas. Chart Factory house default.' },
+  Set3: { type: 'categorical', tags: ['pastel','light','many-categories','colorbrewer'], colorblindSafe: false, maxCategories: 12, description: 'Light pastels. Use when you need many categories.' },
+  Paired: { type: 'categorical', tags: ['paired','light-dark','grouped','comparison','colorbrewer'], colorblindSafe: true, maxCategories: 12, description: 'Light/dark pairs. Great for grouped comparisons.' },
+  Dark2: { type: 'categorical', tags: ['bold','saturated','dark','high-contrast','colorbrewer'], colorblindSafe: true, maxCategories: 8, description: 'Bold, dark colors. Good contrast on light backgrounds.' },
+  Accent: { type: 'categorical', tags: ['accent','highlight','mixed','colorbrewer'], colorblindSafe: false, maxCategories: 8, description: 'Mixed saturation. Good for highlights.' },
+  Pastel1: { type: 'categorical', tags: ['pastel','soft','light','feminine','colorbrewer'], colorblindSafe: false, maxCategories: 9, description: 'Very soft pastels. Low contrast, gentle aesthetic.' },
+  Pastel2: { type: 'categorical', tags: ['pastel','soft','light','colorbrewer'], colorblindSafe: false, maxCategories: 8, description: 'Soft pastels. Similar to Pastel1, slightly different hues.' },
+  ChartDefault: { type: 'categorical', tags: ['chart-factory','balanced','general-purpose','legacy'], colorblindSafe: false, maxCategories: 5, description: 'Legacy Chart Factory line palette (blue/green/orange/purple/red).' },
+  OkabeIto: { type: 'categorical', tags: ['colorblind-safe','accessibility','scientific','inclusive'], colorblindSafe: true, maxCategories: 8, description: 'Okabe-Ito colorblind-safe palette. Best for accessibility.' },
+  Status: { type: 'categorical', tags: ['semantic','status','success-warning-error','ui'], colorblindSafe: false, maxCategories: 4, description: 'Semantic status: success, warning, error, info.' },
+  Binary: { type: 'categorical', tags: ['binary','boolean','yes-no','simple','toggle'], colorblindSafe: true, maxCategories: 2, description: 'Simple yes/no, true/false, on/off visualization.' },
+  Countries: { type: 'categorical', tags: ['geo','countries','markets','flags','regional'], colorblindSafe: false, maxCategories: 14, description: 'Country-specific colors loosely inspired by flags.' },
+  AquaAlert: { type: 'alert', tags: ['alert','action','urgent','purple','attention'], colorblindSafe: true, description: 'Neutral to purple. Action required / urgent items.' },
+  OrangeAlert: { type: 'alert', tags: ['alert','warning','danger','red','attention'], colorblindSafe: false, description: 'Neutral to red. Warnings and danger indicators.' },
+  SalmonAlert: { type: 'alert', tags: ['alert','attention','highlight','pink'], colorblindSafe: true, description: 'Neutral to pink. General attention/highlight.' },
+  ForestAlert: { type: 'alert', tags: ['alert','positive','success','green','good'], colorblindSafe: true, description: 'Neutral to green. Positive outcomes / success.' },
+};
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/** Get a palette's color array by name (undefined if unknown). */
+export function getPalette(name) {
+  return ALL_PALETTES[name];
+}
+
+/** Palette type ('sequential' | 'diverging' | 'categorical' | 'alert' | undefined). */
+export function paletteType(name) {
+  return PALETTE_METADATA[name]?.type;
+}
+
+/** List palette names, optionally filtered by type. */
+export function listPalettes(type) {
+  const names = Object.keys(ALL_PALETTES);
+  return type ? names.filter(n => paletteType(n) === type) : names;
+}
+
+/** Whether a palette is safe for color vision deficiency. */
+export function isColorblindSafe(name) {
+  return PALETTE_METADATA[name]?.colorblindSafe ?? false;
+}
+
+/** Sample n evenly-spaced colors from a palette (name or array). */
+export function samplePalette(palette, n) {
+  const colors = typeof palette === 'string' ? getPalette(palette) : palette;
+  if (!colors) return [];
+  if (n >= colors.length) return [...colors];
+  if (n <= 1) return [colors[0]];
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    out.push(colors[Math.round((i * (colors.length - 1)) / (n - 1))]);
+  }
+  return out;
+}
+
+/** Consistent per-country color (case-insensitive, trimmed). */
+export function getCountryColor(code, fallback = '#6b7280') {
+  if (!code) return fallback;
+  return COUNTRY_COLORS[code.toUpperCase().trim()] || fallback;
+}
+
+// --- Dark-mode ramp re-anchoring --------------------------------------------
+// Sequential/diverging ramps carry a pale end (or a light diverging center).
+// On dark backgrounds those glare, so pull the light stops toward the container
+// surface — the more a stop's lightness exceeds the surface, the harder it is
+// pulled. Categorical palettes are NOT re-anchored: they are distinct hues and
+// blending them toward the surface would muddy them. Mirrors how the built-in
+// --scale-* lo-ends re-anchor under [data-theme="dark"].
+
+function isDarkTheme() {
+  return typeof document !== 'undefined'
+    && document.documentElement.getAttribute('data-theme') === 'dark';
+}
+
+/**
+ * Return a palette's colors, re-anchored for the current theme.
+ * Categorical palettes (and light themes) pass through unchanged.
+ */
+export function themeRamp(colors, name) {
+  if (!Array.isArray(colors) || !isDarkTheme()) return colors;
+  if (name && paletteType(name) === 'categorical') return colors;
+  const surface = getCSSVar('--color-bg-container', '#171b22');
+  const sL = d3.lab(surface).l;
+  return colors.map(c => {
+    const cl = d3.lab(c).l;
+    if (cl <= sL + 12) return c;              // already dark enough
+    const t = Math.min(0.72, ((cl - sL) / 100) * 0.95);
+    return d3.interpolateLab(c, surface)(t);
+  });
+}
+
+/** A palette's colors as a theme-aware ramp (by name). */
+export function paletteRamp(name) {
+  const colors = getPalette(name);
+  return colors ? themeRamp(colors, name) : undefined;
+}
+
+// --- D3 scale factories ------------------------------------------------------
+
+/** Ordinal scale over a categorical palette (raw hues, no re-anchor). */
+export function ordinalScale(palette, domain) {
+  const colors = typeof palette === 'string' ? getPalette(palette) : palette;
+  const scale = d3.scaleOrdinal().range(colors || []);
+  if (domain) scale.domain(domain);
+  return scale;
+}
+
+/**
+ * Color scale from a palette. Categorical → ordinal; sequential/diverging/alert
+ * → sequential interpolator over the theme-aware ramp.
+ */
+export function colorScale(palette, domain = [0, 1]) {
+  const name = typeof palette === 'string' ? palette : undefined;
+  const colors = name ? getPalette(name) : palette;
+  if (!colors) throw new Error(`Unknown palette: ${palette}`);
+  if (name && paletteType(name) === 'categorical') return ordinalScale(name);
+  return d3.scaleSequential(d3.interpolateRgbBasis(themeRamp(colors, name))).domain(domain);
+}
+
+// Public surface bundled onto ChartFactory.palettes
+export const palettes = {
+  all: ALL_PALETTES,
+  metadata: PALETTE_METADATA,
+  countryColors: COUNTRY_COLORS,
+  get: getPalette,
+  type: paletteType,
+  list: listPalettes,
+  isColorblindSafe,
+  sample: samplePalette,
+  ramp: paletteRamp,
+  ordinalScale,
+  colorScale,
+  getCountryColor,
+};