@neo4j-ndl/base 4.23.7 → 5.0.0-alpha.0.3d763f7

package/lib/types/index.d.ts

@@ -19,6 +19,7 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 export * from './typings';
+export * from './public-class-names';
 export * from './tokens/js/tokens';
 export * from './tailwindTheme.mjs';
 export * from './tailwind-preset.config';

package/lib/types/public-class-names.d.ts

@@ -0,0 +1,95 @@
+/*!
+ *
+ *  Copyright (c) "Neo4j"
+ *  Neo4j Sweden AB [http://neo4j.com]
+ *
+ *  This file is part of Neo4j.
+ *
+ *  Neo4j is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+/**
+ * Typography variants that have a matching `ndl-typography-<variant>` class
+ * in the shipped stylesheet (`src/base/typography.css`). Mirrors the keys of
+ * `tokens.typography`.
+ */
+export declare const NDL_TYPOGRAPHY_VARIANTS: readonly ["code", "display", "title-1", "title-2", "title-3", "title-4", "subheading-large", "subheading-medium", "subheading-small", "body-large", "body-medium", "body-small", "label"];
+export type NdlTypographyVariant = (typeof NDL_TYPOGRAPHY_VARIANTS)[number];
+/** Class name prefix used by the public typography classes. */
+export declare const NDL_TYPOGRAPHY_CLASS_PREFIX = "ndl-typography-";
+/** Theme scope classes, also exposed through `useNeedleTheme().themeClassName`. */
+export declare const NDL_THEME_CLASS_NAMES: readonly ["ndl-theme-light", "ndl-theme-dark"];
+/**
+ * The complete list of `ndl-*` class names that are part of the public API:
+ * every `ndl-typography-<variant>` class and the theme scope classes.
+ *
+ * Exact names rather than prefixes, because internal component classes share
+ * those prefixes (e.g. `ndl-theme-wrapper` from `NeedleThemeProvider`).
+ *
+ * Every other `ndl-*` class in the shipped stylesheet is an implementation
+ * detail of a component and may change without notice. Consumers who want to
+ * prevent accidental reliance on those internals can ban `ndl-*` class names in
+ * their own code and allow only these names. For example, with ESLint's
+ * `no-restricted-syntax`:
+ *
+ * ```js
+ * const { NDL_INTERNAL_CLASS_PATTERN } = require('@neo4j-ndl/base');
+ * const regex = `/${NDL_INTERNAL_CLASS_PATTERN.source}/`;
+ *
+ * module.exports = {
+ *   rules: {
+ *     'no-restricted-syntax': [
+ *       'error',
+ *       {
+ *         selector: `Literal[value=${regex}], TemplateElement[value.raw=${regex}]`,
+ *         message:
+ *           'Do not style against internal ndl-* component classes. Use component props or your own class names.',
+ *       },
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * And with Stylelint's `selector-disallowed-list`:
+ *
+ * ```js
+ * const { NDL_INTERNAL_CLASS_PATTERN } = require('@neo4j-ndl/base');
+ *
+ * module.exports = {
+ *   rules: {
+ *     'selector-disallowed-list': [
+ *       [new RegExp(`\\.${NDL_INTERNAL_CLASS_PATTERN.source}`)],
+ *       { message: 'Do not style against internal ndl-* component classes.' },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export declare const NDL_PUBLIC_CLASS_NAMES: readonly string[];
+/**
+ * Matches exactly one of {@link NDL_PUBLIC_CLASS_NAMES}.
+ */
+export declare const NDL_PUBLIC_CLASS_PATTERN: RegExp;
+/**
+ * Matches an `ndl-*` class name that is **not** part of the public API, i.e.
+ * an internal component class. Intended for lint rules that scan class
+ * strings; the pattern is unanchored so it can match anywhere in a string
+ * such as `"my-class ndl-button"`.
+ */
+export declare const NDL_INTERNAL_CLASS_PATTERN: RegExp;
+/**
+ * Returns `true` when the given class name is part of the public `ndl-*` API.
+ *
+ * @param className - A single class name (not a space separated list).
+ */
+export declare function isNdlPublicClassName(className: string): boolean;

package/lib/types/tailwind-preset.config.d.ts

@@ -19,10 +19,40 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * Builds the safelist that keeps every semantic color utility
+ * (`text-*`, `bg-*`, `border-*` and their `hover:`/`active:` variants)
+ * in the generated CSS, regardless of whether a scanned source file uses it.
+ *
+ * The patterns are matched against the final class name, so they need to
+ * include whatever `prefix` the consuming Tailwind config sets. The preset
+ * ships without a prefix; pass your own prefix if you override it:
+ *
+ * ```js
+ * const { tailwindConfig, createTailwindSafelist } = require('@neo4j-ndl/base');
+ * module.exports = {
+ *   presets: [tailwindConfig],
+ *   prefix: 'tw-',
+ *   safelist: createTailwindSafelist('tw-'),
+ * };
+ * ```
+ *
+ * @param {string} [prefix=''] - The Tailwind `prefix` option in use.
+ * @returns {import('tailwindcss').Config['safelist']}
+ */
+export function createTailwindSafelist(prefix?: string): import("tailwindcss").Config["safelist"];
 /**
  * Tailwind CSS Configuration
  * containing all configurations we need
  * for our components
+ *
+ * The preset does not set a `prefix`, so utilities are generated with
+ * their plain Tailwind names (`flex`, `text-neutral-text-weak`, ...).
+ * Consumers who still want a prefix can set `prefix` in their own config
+ * and pair it with `createTailwindSafelist(prefix)`.
+ *
+ * The preset does not set `content` either: which files to scan depends on
+ * the consuming app, so set it in your own config.
  */
-/** @type {import('tailwindcss').Config} */
-export const tailwindConfig: import("tailwindcss").Config;
+/** @type {Omit<import('tailwindcss').Config, 'content'>} */
+export const tailwindConfig: Omit<import("tailwindcss").Config, "content">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-ndl/base",
-  "version": "4.23.7",
+  "version": "5.0.0-alpha.0.3d763f7",
   "description": "Neo4j base package for the design system",
   "author": "Neo4j Inc.",
   "homepage": "https://www.neo4j.design",