@neo4j-ndl/react-charts 1.2.11 → 1.2.13

package/skills/ndl-react-charts/components/charts.md

@@ -103,18 +103,24 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'b' },
             name: 'first (dataset 0, dimension b)',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'c' },
             name: 'second (dataset 0, dimension c)',
             type: 'line',
           },
           {
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'third (dataset 1, dimension y)',
             symbol: 'emptyCircle',
@@ -130,6 +136,8 @@ const Component = () => {
               [390, 180],
               [470, 220],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fourth (inlined data)',
             type: 'line',
@@ -145,6 +153,8 @@ const Component = () => {
               [450, 200],
               [500, 100],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fifth (inlined data)',
             symbol: 'emptyCircle',
@@ -231,6 +241,8 @@ const Component = () => {
               origin: 'start',
             },
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'min',
             stack: 'the stack id',
@@ -239,6 +251,8 @@ const Component = () => {
           {
             areaStyle: {},
             datasetIndex: 2,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'average',
             stack: 'the stack id',
@@ -249,6 +263,8 @@ const Component = () => {
               origin: 'start',
             },
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'max',
             stack: 'the stack id',
@@ -299,10 +315,9 @@ const Component = () => {
         }}
         series={[
           {
-            encode: {
-              x: 'month',
-              y: 'Revenue',
-            },
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
+            encode: { x: 'month', y: 'Revenue' },
             name: 'Revenue',
             type: 'line',
           },
@@ -368,26 +383,23 @@ const Component = () => {
         }}
         series={[
           {
-            encode: {
-              x: 'First',
-              y: 'day',
-            },
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
+            encode: { x: 'First', y: 'day' },
             name: 'First',
             type: 'bar',
           },
           {
-            encode: {
-              x: 'Second',
-              y: 'day',
-            },
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
+            encode: { x: 'Second', y: 'day' },
             name: 'Second',
             type: 'bar',
           },
           {
-            encode: {
-              x: 'Third',
-              y: 'day',
-            },
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
+            encode: { x: 'Third', y: 'day' },
             name: 'Third',
             type: 'bar',
           },
@@ -444,12 +456,16 @@ const Component = () => {
         }}
         series={[
           {
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'People', y: 'day' },
             name: 'People',
             stack: 'total',
             type: 'bar',
           },
           {
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'Beer', y: 'day' },
             itemStyle: { color: '#f28e1c' },
             name: 'Beer',
@@ -625,10 +641,9 @@ const Component = () => {
         }}
         series={[
           {
-            encode: {
-              x: 'Country',
-              y: 'Sales',
-            },
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
+            encode: { x: 'Country', y: 'Sales' },
             name: 'Sales',
             type: 'bar' as const,
           },
@@ -684,30 +699,40 @@ const Component = () => {
         series={[
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'a' },
             name: 'Alpha',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'b' },
             name: 'Beta',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'c' },
             name: 'Gamma',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'd' },
             name: 'Delta',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'e' },
             name: 'Epsilon',
             type: 'line',
@@ -742,7 +767,7 @@ const outliers = new Map<number, [number, number]>([
 
 const sampleData = [
   ['time', 'response time', 'request volume'],
-  ...Array.from({ length: 180 }, (_, index) => {
+  ...Array.from({ length: 180 }, (_unused, index) => {
     const normalResponseTime =
       38 + Math.sin(index / 6) * 13 + Math.cos(index / 17) * 7;
     const normalRequestVolume =
@@ -801,11 +826,15 @@ const Component = () => {
             yAxis: 110,
           },
           {
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'time', y: 'response time' },
             name: 'Response time',
             type: 'line',
           },
           {
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'time', y: 'request volume' },
             name: 'Request volume',
             type: 'line',
@@ -925,18 +954,24 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'b' },
             name: 'first (dataset 0, dimension b)',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'c' },
             name: 'second (dataset 0, dimension c)',
             type: 'line',
           },
           {
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'third (dataset 1, dimension y)',
             symbol: 'emptyCircle',
@@ -952,6 +987,8 @@ const Component = () => {
               [390, 180],
               [470, 220],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fourth (inlined data)',
             type: 'line',
@@ -967,6 +1004,8 @@ const Component = () => {
               [450, 200],
               [500, 100],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fifth (inlined data)',
             symbol: 'emptyCircle',
@@ -1129,18 +1168,24 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'b' },
             name: 'first (dataset 0, dimension b)',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'c' },
             name: 'second (dataset 0, dimension c)',
             type: 'line',
           },
           {
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'third (dataset 1, dimension y)',
             symbol: 'emptyCircle',
@@ -1156,6 +1201,8 @@ const Component = () => {
               [390, 180],
               [470, 220],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fourth (inlined data)',
             type: 'line',
@@ -1171,6 +1218,8 @@ const Component = () => {
               [450, 200],
               [500, 100],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fifth (inlined data)',
             symbol: 'emptyCircle',
@@ -1265,18 +1314,24 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'b' },
             name: 'first (dataset 0, dimension b)',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'c' },
             name: 'second (dataset 0, dimension c)',
             type: 'line',
           },
           {
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'third (dataset 1, dimension y)',
             symbol: 'emptyCircle',
@@ -1292,6 +1347,8 @@ const Component = () => {
               [390, 180],
               [470, 220],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             markArea: {
               data: [
@@ -1324,6 +1381,8 @@ const Component = () => {
               [450, 200],
               [500, 100],
             ],
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'fifth (inlined data)',
             symbol: 'emptyCircle',
@@ -1416,7 +1475,7 @@ const Component = () => {
   const handleToggleYDimension = (yDimension: (typeof yDimensions)[number]) => {
     setCheckedYDimensions(
       (checkedYDimensions.includes(yDimension)
-        ? checkedYDimensions.filter((d) => d !== yDimension)
+        ? checkedYDimensions.filter((dimension) => dimension !== yDimension)
         : [...checkedYDimensions, yDimension]
       ).sort(),
     );
@@ -1447,6 +1506,8 @@ const Component = () => {
       },
     },
     series: checkedYDimensions.map((yDimension) => ({
+      // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+      // oxlint-disable-next-line id-length
       encode: { x: 'x', y: yDimension },
       id: yDimension,
       name: yDimensionNames[yDimension],
@@ -1845,12 +1906,16 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'a', y: 'b' },
             name: 'this is one',
             type: 'line',
           },
           {
             datasetIndex: 1,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'x', y: 'y' },
             name: 'This is two',
             symbol: 'emptyCircle',
@@ -2011,12 +2076,16 @@ const Component = () => {
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'time', y: 'querySuccessRate' },
             name: 'Query success rate',
             type: 'line',
           },
           {
             datasetIndex: 0,
+            // E-Charts uses encode.x and encode.y - https://echarts.apache.org/en/option.html#series-line.encode
+            // oxlint-disable-next-line id-length
             encode: { x: 'time', y: 'pageCacheHitRate' },
             name: 'Page cache hit rate',
             type: 'line',

package/skills/ndl-react-charts/references/styling.md

@@ -0,0 +1,142 @@
+# Styling reference
+
+The stylesheet is the source of truth for which classes and custom properties
+exist. **Never hardcode a class name or token value from memory** — verify it
+against the shipped CSS first.
+
+## Where the stylesheet lives
+
+```
+node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css
+```
+
+When checking whether a class or custom property exists, grep the built file —
+not the source `.pcss` — because Tailwind tree-shakes classes that no source
+file uses.
+
+### Quick verification
+
+```sh
+CSS=node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css
+grep -qE '\.n-flex\b' "$CSS" && echo "exists" || echo "MISSING"
+grep -qE -- '--space-8:' "$CSS" && echo "exists" || echo "MISSING"
+```
+
+## Tokens only — never raw color values
+
+Chart colors and surrounding UI must **never** contain hardcoded `hex`,
+`rgb()`, `oklch()`, or arbitrary Tailwind color values. All colors come from
+Needle's token system:
+
+### Chart-specific tokens
+
+For ECharts color options, import the token object and reference data-viz
+tokens:
+
+```tsx
+import { tokens } from '@neo4j-ndl/base';
+
+// Categorical series colors
+const seriesColors = Object.values(tokens.categorical);
+
+// Graph palette
+const nodeColor = tokens.graph.nodeDefault;
+```
+
+These are raw palette values appropriate for chart series, not theme-aware
+semantic colors.
+
+### Semantic theme tokens (for surrounding UI)
+
+For layout, labels, and controls around the chart, use semantic custom
+properties that adapt to light/dark theme:
+
+```css
+/* ✅ Token — adapts to theme */
+color: var(--theme-color-neutral-text-default);
+background: var(--theme-color-primary-bg-weak);
+
+/* ❌ Hardcoded — breaks dark mode */
+color: #1a1b1d;
+background: rgb(10 97 144);
+```
+
+| Family | CSS custom property prefix |
+|--------|---------------------------|
+| Neutral | `--theme-color-neutral-*` |
+| Primary | `--theme-color-primary-*` |
+| Danger | `--theme-color-danger-*` |
+| Warning | `--theme-color-warning-*` |
+| Success | `--theme-color-success-*` |
+| Discovery | `--theme-color-discovery-*` |
+
+Each family provides: `text`, `icon`, `bg-weak`, `bg-strong`, `bg-status`,
+`border-strong`, `border-weak` (primary/danger also have `hover-*`,
+`pressed-*`).
+
+### Space and border-radius tokens
+
+| Token | Value |
+|-------|-------|
+| `--space-2` | 2px |
+| `--space-4` | 4px |
+| `--space-6` | 6px |
+| `--space-8` | 8px |
+| `--space-12` | 12px |
+| `--space-16` | 16px |
+| `--space-20` | 20px |
+| `--space-24` | 24px |
+| `--space-32` | 32px |
+| `--space-48` | 48px |
+| `--space-64` | 64px |
+
+| Token | Value |
+|-------|-------|
+| `--border-radius-none` | 0 |
+| `--border-radius-sm` | 4px |
+| `--border-radius-md` | 6px |
+| `--border-radius-lg` | 8px |
+| `--border-radius-xl` | 12px |
+| `--border-radius-2xl` | 16px |
+| `--border-radius-3xl` | 24px |
+| `--border-radius-full` | 9999px |
+
+Prefer `Flex`, `Box`, and `Typography` from `@neo4j-ndl/react` with typed token
+props over raw utility classes for layout.
+
+## The `n-` prefix
+
+The Tailwind preset sets `prefix: 'n-'`. With the published preset and no
+override, `n-flex`, `n-gap-4`, `n-bg-primary-bg-weak` work. If the consuming
+app sets its own `prefix` (including `prefix: ''`), the app's config wins.
+Check the app's `tailwind.config` before assuming `n-` is correct.
+
+## How to verify before writing
+
+1. **Check component props first.** `Flex`, `Box`, `Typography` from
+   `@neo4j-ndl/react` accept typed token values — prefer them over classes or
+   `htmlAttributes`. See the customization hierarchy below.
+2. **Check the stylesheet**: grep `neo4j-ds-styles.css` for the exact class
+   or property.
+3. **Never copy a class from another library** (MUI, Radix, Chakra, plain
+   Tailwind). They won't exist in the Needle stylesheet.
+
+## Customization hierarchy
+
+When adjusting surrounding UI from `@neo4j-ndl/react`, work through these in
+order. Each level is more error-prone than the one before it:
+
+1. **Component props** — typed, token-constrained, and type-checked. Always the
+   first choice. Examples: `gap="8"`, `padding="12"`, `variant="danger"`,
+   `size="small"`, `ariaLabel`.
+
+2. **`className`** — for utility classes the component doesn't cover. Verify
+   every class against
+   `node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css`. A wrong class compiles
+   and silently renders nothing.
+
+3. **`htmlAttributes`** — escape hatch for native HTML attributes, `aria-*`, and
+   `data-*` the component doesn't expose as props (e.g. `id` for
+   `aria-controls` references, `aria-haspopup` on a trigger, `type="email"` on
+   a `TextInput`, `href` on `Typography` with `as="a"`). Do **not** use it to
+   override behavior the component already provides via props, or for styling.