@neo4j-ndl/react-charts 1.2.11 → 1.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-ndl/react-charts",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "sideEffects": false,
   "description": "React implementation of charts from Neo4j Design System",
   "keywords": [
@@ -56,8 +56,8 @@
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@neo4j-ndl/base": "^4.19.0",
-    "@neo4j-ndl/react": "^4.20.0"
+    "@neo4j-ndl/react": "^4.20.1",
+    "@neo4j-ndl/base": "^4.19.0"
   },
   "dependencies": {
     "classnames": "2.5.1",

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

@@ -41,14 +41,45 @@ Use Neo4j Needle React Charts instead of hand-rolling chart components.
   exists, confirm it in the component's props here or the TypeScript types, and
   consult the ECharts option reference (https://echarts.apache.org/en/option.html)
   for supported behavior.
+- **Customize via component props first.** The same escape-hatch order as
+  `ndl-react` applies to surrounding UI from `@neo4j-ndl/react`: component
+  props → `className` (verify against the stylesheet) → `htmlAttributes` for
+  native HTML/ARIA/`data-*` the component doesn't expose. See the `ndl-react`
+  skill for the full rule.
+- **Tokens only.** Never hardcode `hex`, `rgb()`, `oklch()`, or arbitrary
+  Tailwind color values in chart options or surrounding UI. Chart colors should
+  reference Needle's data-viz tokens (`tokens.categorical`, `tokens.graph`) or
+  the semantic `--theme-color-*` custom properties so they adapt to the active
+  theme. For layout and surrounding UI, use `Flex`, `Box`, `Typography` from
+  `@neo4j-ndl/react` with typed token props rather than utility classes. See
+  [references/styling.md](references/styling.md) for the complete token catalog.
+- **Class names are unchecked strings.** The same rule from the `ndl-react`
+  skill applies: verify any `n-*` utility class against
+  `node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css` before using it. Prefer
+  `Flex`, `Box`, and `Typography` component props over utility classes.
 - Follow the accessibility guidance in each component's doc; don't strip built-in
   roles or keyboard behavior.
 
+## Reuse before you create
+
+Before hand-rolling a chart wrapper or custom visualization, check whether the
+`Chart` component already covers the need. The `Chart` component wraps Apache
+ECharts and supports the full ECharts option API — confirm the capability in
+`components/charts.md` before building custom rendering.
+
+For surrounding UI (buttons, inputs, layout, feedback), reuse components from
+`@neo4j-ndl/react` rather than creating new ones. See the `ndl-react` skill for
+the full component catalog.
+
 ## How to use this skill
 
 1. Find the component in the catalog below to get its docs file and import path.
 2. Read `components/<file>` for that component's props, accessibility
    requirements, and runnable examples; prefer those examples.
+3. For styling — token names, utility class lists, prefix rules — consult
+   [references/styling.md](references/styling.md). It points at the shipped
+   stylesheet so class and token lists can't drift from what the package
+   actually ships.
 
 ## Components
 

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.