@pharos-ds/charts 0.0.0-bootstrap.0 → 1.0.10

package/dist/webgl.js

@@ -0,0 +1,235 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file webgl.ts
+ * @output Shared WebGL utilities for chart components
+ * @position Internal helpers; consumed by all GL mark components
+ *
+ * Provides:
+ * - Canvas mounting outside SVG (avoids foreignObject DPR blur)
+ * - Premultiplied alpha setup (correct compositing over page)
+ * - Shader compilation helpers
+ * - Smoothstep circle fragment for crisp point sprites
+ * - Hex-to-GL color conversion via the shared @pharos-ds/core/utils/color
+ *   parsers (fallback instead of NaN)
+ * - Context-loss registration + eager context teardown helpers
+ */
+
+import { parseHex, toGLFloats } from '@pharos-ds/core/utils';
+
+/** Compile a WebGL shader, returns null on failure */
+export function compileShader(gl, type, src) {
+  const s = gl.createShader(type);
+  if (!s) {
+    return null;
+  }
+  gl.shaderSource(s, src);
+  gl.compileShader(s);
+  if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
+    gl.deleteShader(s);
+    return null;
+  }
+  return s;
+}
+
+/** Link a vertex + fragment shader into a program */
+export function createProgram(gl, vertSrc, fragSrc) {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vertSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fragSrc);
+  if (!vs || !fs) {
+    // One shader may have compiled while the other failed — free the survivor
+    // so the failure path never leaks a shader object.
+    if (vs) {
+      gl.deleteShader(vs);
+    }
+    if (fs) {
+      gl.deleteShader(fs);
+    }
+    return null;
+  }
+  const p = gl.createProgram();
+  if (!p) {
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    return null;
+  }
+  gl.attachShader(p, vs);
+  gl.attachShader(p, fs);
+  gl.linkProgram(p);
+  // The shaders are now linked into the program; flag them for deletion so the
+  // GPU frees them once the program is deleted instead of leaving them attached
+  // (and allocated) for the program's whole lifetime.
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
+    gl.deleteProgram(p);
+    return null;
+  }
+  return p;
+}
+
+/**
+ * Parse a hex color to [r, g, b] floats in 0-1.
+ *
+ * Accepts `#rgb`, `#rgba`, `#rrggbb`, and `#rrggbbaa`, with or without the
+ * leading `#` (any alpha byte is ignored). Non-hex input — CSS custom
+ * properties, `rgb()`, named colors, or malformed strings — returns a neutral
+ * fallback rather than producing NaN, so the GPU never receives a bad uniform.
+ */
+export function hexToGL(hex) {
+  return toGLFloats(parseHex(hex));
+}
+
+/** DPR with 2x supersampling for crisp circles. SSR-safe (falls back to 2). */
+export function getCanvasDPR() {
+  const base = typeof window !== 'undefined' ? window.devicePixelRatio : 0;
+  return (base || 2) * 2;
+}
+
+/**
+ * Create or get a WebGL context with correct alpha settings.
+ * Uses premultiplied alpha for correct compositing over the page.
+ */
+export function getWebGLContext(canvas) {
+  return canvas.getContext('webgl', {
+    alpha: true,
+    premultipliedAlpha: true,
+    antialias: true
+  });
+}
+
+/**
+ * Set up standard GL state for chart rendering:
+ * - Clear with transparent
+ * - Enable premultiplied alpha blending
+ */
+export function setupGLState(gl) {
+  gl.clearColor(0, 0, 0, 0);
+  gl.clear(gl.COLOR_BUFFER_BIT);
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+}
+
+/**
+ * Size a canvas for sharp rendering, accounting for DPR.
+ * Returns the DPR used.
+ */
+export function sizeCanvas(canvas, width, height) {
+  const dpr = getCanvasDPR();
+  // The drawing buffer must be a positive integer — a 0-sized (or fractional)
+  // buffer makes GL viewport/draw calls silently fail.
+  canvas.width = Math.max(1, Math.round(width * dpr));
+  canvas.height = Math.max(1, Math.round(height * dpr));
+  canvas.style.width = `${Math.max(0, width)}px`;
+  canvas.style.height = `${Math.max(0, height)}px`;
+  return dpr;
+}
+
+/**
+ * Mount a canvas as an absolute-positioned sibling to an SVG element.
+ * Automatically aligns with the SVG marker's position — no manual margin
+ * offset needed. This is a Tier 1 guarantee: the canvas lands exactly
+ * where the SVG content area is, regardless of chart margins or transforms.
+ *
+ * Call from a useEffect. Returns a cleanup function.
+ */
+export function mountCanvasOverSVG(svgMarker, canvas, width, height) {
+  const svg = svgMarker.ownerSVGElement;
+  if (!svg) {
+    return;
+  }
+  const parent = svg.parentElement;
+  if (!parent) {
+    return;
+  }
+  if (getComputedStyle(parent).position === 'static') {
+    parent.style.position = 'relative';
+  }
+  canvas.style.position = 'absolute';
+  canvas.style.pointerEvents = 'none';
+
+  // Compute offset from the SVG marker's actual screen position.
+  // The marker sits inside the chart's <g transform="translate(margin)">
+  // so its bounding rect includes the margin offset automatically.
+  // This is a Tier 1 guarantee — we derive position from the SVG, not from props.
+  const parentRect = parent.getBoundingClientRect();
+  const markerCTM = svgMarker.getScreenCTM();
+  if (markerCTM) {
+    canvas.style.left = `${markerCTM.e - parentRect.left}px`;
+    canvas.style.top = `${markerCTM.f - parentRect.top}px`;
+  } else {
+    canvas.style.left = '0';
+    canvas.style.top = '0';
+  }
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  parent.appendChild(canvas);
+  return () => {
+    if (canvas.parentElement === parent) {
+      parent.removeChild(canvas);
+    }
+  };
+}
+
+/**
+ * Register WebGL context-loss/restore handlers on a canvas.
+ *
+ * Calling `preventDefault()` on the lost event is REQUIRED — without it the
+ * browser will never fire `webglcontextrestored`. `onLost` should drop any
+ * cached GL handles (they are all invalid after loss); `onRestored` should
+ * trigger a rebuild + redraw.
+ *
+ * Returns a cleanup that removes both listeners.
+ */
+export function registerContextLossHandlers(canvas, onLost, onRestored) {
+  const handleLost = e => {
+    e.preventDefault();
+    onLost();
+  };
+  canvas.addEventListener('webglcontextlost', handleLost, false);
+  canvas.addEventListener('webglcontextrestored', onRestored, false);
+  return () => {
+    canvas.removeEventListener('webglcontextlost', handleLost, false);
+    canvas.removeEventListener('webglcontextrestored', onRestored, false);
+  };
+}
+
+/**
+ * Eagerly release a WebGL context and its GPU resources on teardown.
+ *
+ * Browsers cap the number of live contexts (~16), so freeing on unmount rather
+ * than waiting for GC prevents "too many active WebGL contexts" failures when
+ * many charts mount/unmount over a session.
+ */
+export function loseContext(gl) {
+  const ext = gl.getExtension('WEBGL_lose_context');
+  if (ext) {
+    ext.loseContext();
+  }
+}
+
+/**
+ * GLSL fragment for premultiplied-alpha circle with smoothstep AA.
+ * Use in fragment shaders that render point sprites.
+ *
+ * Expects:
+ * - varying float v_alpha (the final alpha before edge AA)
+ * - uniform vec3 u_color
+ *
+ * Returns: gl_FragColor with premultiplied alpha
+ */
+export const CIRCLE_FRAG_BODY = `
+    vec2 coord = gl_PointCoord - vec2(0.5);
+    float dist = length(coord);
+    if (dist > 0.5) discard;
+    float edge = 1.0 - smoothstep(0.48, 0.5, dist);
+    float a = v_alpha * edge;
+    gl_FragColor = vec4(u_color * a, a);
+`;
+
+/**
+ * Smoothstep compensation factor for gl_PointSize.
+ * The visible circle radius is 0.48 of the point sprite (smoothstep starts there),
+ * so we scale up by 1/0.96 to match SVG circle radius exactly.
+ */
+export const POINT_SIZE_COMPENSATION = 1.0 / 0.96;

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@pharos-ds/charts",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Reserva do nome; a versão real sai pelo release do alexandria-ds.",
-  "repository": {"type": "git", "url": "git+https://github.com/Lex-Energia/alexandria-ds.git"}
-}
+  "version": "1.0.10",
+  "displayName": "Pharos Charts",
+  "private": false,
+  "description": "Pharos charts — a config-model data visualization library (d3-based) with bar, line, area and more, themed by Pharos tokens and accessible by default.",
+  "author": "Caio Silvestre",
+  "license": "MIT",
+  "homepage": "https://github.com/Lex-Energia/alexandria-ds#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lex-Energia/alexandria-ds.git",
+    "directory": "packages/charts"
+  },
+  "bugs": {
+    "url": "https://github.com/Lex-Energia/alexandria-ds/issues"
+  },
+  "keywords": [
+    "pharos",
+    "charts",
+    "data-visualization",
+    "design-system"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./charts.css": {
+      "types": "./src/charts.css.d.ts",
+      "default": "./dist/charts.css"
+    }
+  },
+  "peerDependencies": {
+    "@pharos-ds/core": "1.0.10",
+    "@stylexjs/stylex": "^0.19.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "dependencies": {
+    "d3-array": "^3.2.4",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0"
+  },
+  "devDependencies": {
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-shape": "^3.1.8"
+  },
+  "scripts": {
+    "build": "rm -rf dist && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && node ../../scripts/check-no-dev-jsx.mjs",
+    "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.cjs",
+    "build:css": "node ../../scripts/build-css.mjs --package charts",
+    "dev": "babel src --watch --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css*\" --config-file ./babel.config.cjs",
+    "test": "vitest run --root ../..",
+    "test:watch": "vitest --root ../..",
+    "lint": "eslint src",
+    "typecheck:docs": "tsc --project tsconfig.docs.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}

package/src/Chart.doc.mjs

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Chart',
+  displayName: 'Chart',
+  group: 'Charts',
+  category: 'Data Visualization',
+  keywords: [
+    'chart',
+    'graph',
+    'bar',
+    'line',
+    'area',
+    'horizontal bar',
+    'data visualization',
+    'dataviz',
+    'accessible chart',
+  ],
+
+  usage: {
+    description:
+      'Config-model chart: pass `data`, the `xKey` that identifies each row and a `series` array of mark factories (`bar`, `line`, `area`, `dot`, `band`, `referenceLine`, `errorBar`, `candlestick` and WebGL variants). One x/y scale is shared by every mark, axis and grid line. Series without an explicit `color` take the theme categorical palette in order (Pharos: azul, roxo, laranja, amarelo, chumbo), resolved for the active light/dark mode. Accessible by default: the SVG is `role="img"` named by `aria-label` → `title` → series labels, `subtitle`/`description` become its description, and a visually hidden data table carries the values for screen readers. Dist consumers import `@pharos-ds/core/pharos.css` and `@pharos-ds/charts/charts.css`; no StyleX compiler is needed.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Give every chart a `title` (or `aria-label` when the visible heading lives outside the chart, e.g. in a Card header).',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a `description` that states the takeaway ("Instagram lidera com 120 leads") — the hidden table has the numbers, the description has the meaning.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use `orientation="horizontal"` for long category names or rankings; pair it with `<ChartAxis position="left" />` (categories) and `<ChartAxis position="bottom" />` (values), and widen `margin.left` to fit the labels.',
+      },
+      {
+        guidance: true,
+        description:
+          'Let series take palette colors (omit `color`) so light/dark mode and the brand order work automatically.',
+      },
+      {
+        guidance: false,
+        description:
+          'Turn off `dataTable` unless the same data is already on the page as a real table — it is the text alternative for screen-reader users.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on the tooltip to convey values: it is pointer-only (no keyboard focus), so anything essential must be in the table, the description or visible labels.',
+      },
+      {
+        guidance: false,
+        description:
+          'Share one series array between charts: each `<Chart>` annotates its series defs, so build a fresh array per chart.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'data',
+      type: 'Record<string, unknown>[]',
+      description: 'Rows to plot. Each row has the x value under `xKey` plus one value per series data key.',
+      required: true,
+    },
+    {
+      name: 'xKey',
+      type: 'string',
+      description: 'Key of the x value. Strings make a categorical (band) axis, numbers a linear one.',
+      required: true,
+    },
+    {
+      name: 'series',
+      type: 'SeriesDef[]',
+      description: 'Marks to draw, built with the mark factories (`bar("leads")`, `line("meta", {label: "Meta"})`, …). Order sets palette order and draw order.',
+      required: true,
+    },
+    {
+      name: 'title',
+      type: 'string',
+      description: 'Visible heading above the chart. Also the accessible name and the hidden table caption unless `aria-label` is set.',
+    },
+    {
+      name: 'subtitle',
+      type: 'string',
+      description: 'Visible supporting line under the title; part of the SVG description (`aria-describedby`).',
+    },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description: 'Accessible name of the chart image. Defaults to `title`, then to the data series labels joined by commas.',
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: 'Text alternative summarizing the chart (trend, highlights). Not visible; exposed through `aria-describedby` after `subtitle`.',
+    },
+    {
+      name: 'dataTable',
+      type: 'boolean | { xLabel?: string; formatX?: (value) => string; formatValue?: (value, series, dataKey) => string; maxRows?: number }',
+      description: 'Visually hidden `<table>` generated from `data`: caption = accessible name, header row = x label + series labels, one row per x value. Utility marks (band, errorBar, referenceLine) get no column. Omitted above `maxRows` rows (default 1000). Pass `false` to opt out.',
+      default: 'true',
+    },
+    {
+      name: 'orientation',
+      type: "'vertical' | 'horizontal'",
+      description: 'Horizontal puts categories on the y-axis and grows values to the right (horizontal bars). Axes and grid follow; use the `tooltip` prop rather than a `ChartTooltip` child.',
+      default: "'vertical'",
+    },
+    {
+      name: 'height',
+      type: 'number',
+      description: 'Height of the plot SVG in px. Width always fills the container.',
+      default: '300',
+    },
+    {
+      name: 'margin',
+      type: 'Partial<{top: number; right: number; bottom: number; left: number}>',
+      description: 'Space reserved around the plot for axis labels.',
+      default: '{top: 24, right: 24, bottom: 32, left: 48}',
+    },
+    {
+      name: 'grid',
+      type: 'ReactNode',
+      description: 'Grid slot, usually `<ChartGrid />` (follows the value axis by default).',
+    },
+    {
+      name: 'axes',
+      type: 'ReactNode',
+      description: 'Axis slot, usually `<ChartAxis position="bottom" />` and `<ChartAxis position="left" />`.',
+    },
+    {
+      name: 'legend',
+      type: 'boolean | ChartLegendProps',
+      description: 'Shows a legend derived from the series (labels + swatches); pass an object for position and alignment.',
+    },
+    {
+      name: 'tooltip',
+      type: 'boolean | Omit<ChartTooltipProps, "series">',
+      description: 'Pointer tooltip with every series value at the hovered x. Pointer-only and never focusable.',
+    },
+    {
+      name: 'yBaseline',
+      type: "'auto' | 'zero' | 'data'",
+      description: 'How the value domain is derived when `yDomain` is not set: bars/areas pin zero (`auto`), symmetric around zero (`zero`) or tight to the data (`data`).',
+      default: "'auto'",
+    },
+    {
+      name: 'yDomain',
+      type: '[number, number]',
+      description: 'Explicit value domain. Authoritative — disables baseline and headroom.',
+    },
+    {
+      name: 'xDomain',
+      type: '[number, number]',
+      description: 'Explicit numeric x domain (streaming windows). Ignored for categorical x.',
+    },
+    {
+      name: 'interactions',
+      type: 'ReactNode',
+      description: 'Slot for interaction layers that read the chart context (`useChart`).',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Escape hatch rendered last inside the plot group.',
+    },
+  ],
+};