@neo4j-ndl/react-charts 1.3.15 → 1.3.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-ndl/react-charts",
-  "version": "1.3.15",
+  "version": "1.3.17",
   "sideEffects": false,
   "description": "React implementation of charts from Neo4j Design System",
   "keywords": [
@@ -57,8 +57,8 @@
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@neo4j-ndl/base": "^4.23.2",
-    "@neo4j-ndl/react": "^4.25.1"
+    "@neo4j-ndl/base": "^4.23.4",
+    "@neo4j-ndl/react": "^4.25.3"
   },
   "dependencies": {
     "classnames": "2.5.1",

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

@@ -2,7 +2,7 @@
 name: ndl-react-charts
 metadata:
   package: '@neo4j-ndl/react-charts'
-  version: '1.3.15'
+  version: '1.3.17'
 description: >-
   Build data visualizations with the Neo4j Needle React Charts library
   (@neo4j-ndl/react-charts), an Apache ECharts-based charting layer. Use when
@@ -15,7 +15,7 @@ description: >-
 
 # Neo4j Needle React Charts (@neo4j-ndl/react-charts)
 
-> 📌 Shipped with `@neo4j-ndl/react-charts` v1.3.15. Once installed into your repo (e.g. via
+> 📌 Shipped with `@neo4j-ndl/react-charts` v1.3.17. Once installed into your repo (e.g. via
 > `npx skills add`) this folder is detached from the package — the installed
 > package (TypeScript types in `node_modules/@neo4j-ndl/react-charts`) is the source of
 > truth.

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

@@ -14,11 +14,30 @@ 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.
 
+### What the prebuilt stylesheet contains
+
+Besides the `ndl-*` component classes and the CSS custom properties, the
+prebuilt stylesheet ships only two groups of `n-` classes:
+
+- **Typography** — `n-display`, `n-title-1` … `n-title-4`,
+  `n-subheading-large/medium/small`, `n-body-large/medium/small`, `n-label`,
+  `n-code`.
+- **Semantic colors** — `n-text-*`, `n-bg-*`, `n-border-*` for the color
+  families below, plus `hover:` variants (and `active:` for `n-bg-*`). These
+  are safelisted in the Tailwind preset.
+
+**No other Tailwind utility is guaranteed to be in the prebuilt stylesheet.**
+A utility only ships if Needle's component source uses it, and component
+source no longer uses Tailwind utilities. Layout, spacing, sizing, radius and
+shadow utilities (`n-flex`, `n-items-center`, `n-gap-token-8`, `n-p-4`,
+`n-w-full`, `n-rounded-lg`, …) are absent and silently render nothing unless
+the consuming app runs its own Tailwind build with the Needle preset.
+
 ### 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 '\.n-body-medium\b' "$CSS" && echo "exists" || echo "MISSING"
 grep -qE -- '--space-8:' "$CSS" && echo "exists" || echo "MISSING"
 ```
 
@@ -102,23 +121,36 @@ Each family provides: `text`, `icon`, `bg-weak`, `bg-strong`, `bg-status`,
 | `--border-radius-full` | 9999px |
 
 Prefer `Flex`, `Box`, and `Typography` from `@neo4j-ndl/react` with typed token
-props over raw utility classes for layout.
+props over raw utility classes for layout. Without an app Tailwind build they
+are the only reliable option; for anything they don't cover, use an inline
+`style` with a token, e.g. `style={{ margin: 'var(--space-8)' }}`.
+
+## Tailwind builds and the `n-` prefix
+
+Whether a utility class works depends on the consuming app:
 
-## The `n-` prefix
+- **No Tailwind build** — the app only imports `neo4j-ds-styles.css`, so only
+  the [typography and color classes](#what-the-prebuilt-stylesheet-contains)
+  exist.
+- **Tailwind build with the Needle preset** — any standard utility is generated
+  on demand. The preset sets `prefix: 'n-'`, so `n-flex`, `n-gap-4` and
+  `n-bg-primary-bg-weak` work. If the app sets its own `prefix` (including
+  `prefix: ''`), the app's config wins.
 
-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.
+Check the app's `tailwind.config` — whether it exists, and its `prefix` —
+before writing any utility class.
 
 ## 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
+2. **Check whether the app has its own Tailwind build** and which `prefix` it
+   uses. Without one, only typography and color utilities exist.
+3. **Check the stylesheet**: grep the installed
+   `node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css` for the exact class
    or property.
-3. **Never copy a class from another library** (MUI, Radix, Chakra, plain
+4. **Never copy a class from another library** (MUI, Radix, Chakra, plain
    Tailwind). They won't exist in the Needle stylesheet.
 
 ## Customization hierarchy
@@ -130,10 +162,11 @@ order. Each level is more error-prone than the one before it:
    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.
+2. **`className`** — for utility classes the component doesn't cover (e.g.
+   `n-text-neutral-text-weak` or `n-body-small`). Verify every class against
+   `node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css`, or against the app's
+   own Tailwind build. Layout utilities such as `n-flex` work only with an app
+   Tailwind build. 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