@ssa-ui-kit/core 3.19.1 → 3.20.1

package/dist/utils/deprecation.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Prop deprecation helpers.
+ *
+ * The library is converging on the DOM/MUI/Radix/Ant prop names (issue #656,
+ * Phase 2). Renames land as *additive aliases first*: the new prop is added,
+ * the old one keeps working, and a dev-only console warning points consumers at
+ * the replacement. The old prop is removed at the next major.
+ *
+ * Warnings are emitted at most once per component/prop pair per process so a
+ * component re-rendering in a list cannot flood the console.
+ */
+/**
+ * Clears the once-per-pair warning cache.
+ *
+ * Only useful in tests, where several cases need to assert on the same warning.
+ *
+ * @internal
+ */
+export declare const resetDeprecationWarnings: () => void;
+/**
+ * Emits a deprecation notice for `component.deprecatedProp`, at most once.
+ *
+ * No-op in production builds.
+ */
+export declare const warnDeprecatedProp: (component: string, deprecatedProp: string, replacementProp: string) => void;
+export interface ResolveDeprecatedPropOptions<T> {
+    /** Component name, used in the warning message. */
+    component: string;
+    /** The supported prop name. */
+    prop: string;
+    /** Value of the supported prop. */
+    value: T | undefined;
+    /** The deprecated prop name. */
+    deprecatedProp: string;
+    /** Value of the deprecated prop. */
+    deprecatedValue: T | undefined;
+}
+/**
+ * Resolves a prop that is mid-rename: returns the new prop's value when it is
+ * defined, otherwise falls back to the deprecated one and warns in dev.
+ *
+ * Passing both is not an error — the new prop wins — but it still warns, since
+ * the deprecated prop was supplied.
+ */
+export declare const resolveDeprecatedProp: <T>({ component, prop, value, deprecatedProp, deprecatedValue, }: ResolveDeprecatedPropOptions<T>) => T | undefined;
+/**
+ * Shorthand for the camelCase-ARIA → native-ARIA renames (issue #656, chunk 3
+ * item 1).
+ *
+ * The library grew bespoke `ariaLabel` / `ariaLabelledby` / `ariaControls` props
+ * in parallel with components that simply accept the native attributes. The
+ * camelCase ones have to be forwarded by hand and are invisible to
+ * `eslint-plugin-jsx-a11y` and the axe gate, so native wins and the camelCase
+ * spelling becomes an alias.
+ *
+ * @example
+ * ```tsx
+ * const label = resolveAriaProp('Pagination', 'aria-label', ariaLabelNative, ariaLabel);
+ * ```
+ */
+export declare const resolveAriaProp: (component: string, ariaProp: string, value: string | undefined, deprecatedValue: string | undefined) => string | undefined;
+/**
+ * The open-state prop family, in the spellings the kit is converging on.
+ *
+ * @see resolveOpenState
+ */
+export interface OpenStateProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * The deprecated spellings the kit grew before {@link OpenStateProps}. Each
+ * component only ever used a subset; passing a key that a given component never
+ * had is harmless.
+ */
+export interface DeprecatedOpenStateProps {
+    /** @deprecated Use `open`. */
+    opened?: boolean;
+    /** @deprecated Use `open`, or `defaultOpen` where it was never controlled. */
+    isOpen?: boolean;
+    /** @deprecated Use `open`, or `defaultOpen` where it was never controlled. */
+    isOpened?: boolean;
+    /** @deprecated Use `defaultOpen`. */
+    defaultOpened?: boolean;
+    /** @deprecated Use `defaultOpen`. */
+    initialOpen?: boolean;
+    /** @deprecated Use `onOpenChange`. */
+    onOpenedChange?: (open: boolean) => void;
+}
+export interface ResolvedOpenState {
+    open: boolean | undefined;
+    defaultOpen: boolean | undefined;
+    onOpenChange: ((open: boolean) => void) | undefined;
+    /** True when the *supported* or the *deprecated* controlled key was passed. */
+    isControlled: boolean;
+}
+/**
+ * Shorthand for the open-state renames (issue #656, chunk 3 item 2), which span
+ * `Drawer`, `Popover`, `Tooltip`, `Accordion`, `Modal`, `ModalDialog` and
+ * `FiltersMultiSelect` — six deprecated spellings between them.
+ *
+ * Resolves all three keys in one call and reports whether the component should
+ * consider itself controlled. Controlled-ness is keyed on the *presence* of a
+ * key rather than its value, for the reason `useControllableState` documents:
+ * `open={undefined}` has to keep meaning "controlled, currently closed".
+ *
+ * Pass the deprecated spellings this component actually had via
+ * `controlledAlias` / `defaultAlias` / `changeAlias` — anything omitted is not
+ * looked for, so a component cannot accidentally accept a spelling it never
+ * shipped.
+ *
+ * @example
+ * ```tsx
+ * const { open, defaultOpen, onOpenChange, isControlled } = resolveOpenState(
+ *   'Drawer',
+ *   props,
+ *   { controlledAlias: 'opened', defaultAlias: 'defaultOpened' },
+ * );
+ * ```
+ */
+export declare const resolveOpenState: (component: string, props: OpenStateProps & DeprecatedOpenStateProps, aliases?: {
+    controlledAlias?: keyof DeprecatedOpenStateProps;
+    defaultAlias?: keyof DeprecatedOpenStateProps;
+    changeAlias?: keyof DeprecatedOpenStateProps;
+}) => ResolvedOpenState;
+/**
+ * Shorthand for the `isDisabled` → `disabled` rename, which spans 15 components.
+ *
+ * @example
+ * ```tsx
+ * const isControlDisabled = resolveDisabled('Button', disabled, isDisabled);
+ * ```
+ */
+export declare const resolveDisabled: (component: string, disabled: boolean | undefined, isDisabled: boolean | undefined) => boolean | undefined;

package/dist/utils/detectDuplicateInstance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Warns, in development, when more than one copy of `@ssa-ui-kit/core` is
+ * loaded into the same runtime.
+ *
+ * The package ships both a CommonJS and an ESM bundle (`exports.require` →
+ * `dist/index.js`, `exports.import` → `dist/index.mjs`). A dependency graph
+ * that reaches core *both* ways — a `require` from one dependency, an `import`
+ * from the app — loads both files, and each gets its own module scope. Every
+ * context the kit creates then exists twice: a `ThemeProvider` from one copy
+ * cannot be read by a `useTheme` from the other, a `PopoverTrigger` cannot find
+ * the `Popover` that wraps it, and so on.
+ *
+ * The symptoms are indirect and expensive to chase — "theme is undefined",
+ * "usePopoverContext must be used within a Popover" on markup that plainly is
+ * — so the point of this module is to name the cause once, up front. It is the
+ * same failure that made `useFormContext()` return null when core was
+ * CommonJS-only and Vite loaded react-hook-form as ESM; the fix shape is the
+ * same too, hence the `resolve.dedupe` hint.
+ *
+ * Fixing it means making the graph resolve to one copy: `resolve.dedupe` in
+ * Vite, `resolve.alias` in webpack, or removing the `npm link` / `file:` /
+ * workspace symlink that gave a linked package its own `node_modules`.
+ *
+ * No-op in production builds — the check costs a global read, but the message
+ * is only actionable to someone with the source in front of them.
+ */
+export declare const detectDuplicateInstance: () => void;

package/dist/utils/environment.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether the kit's development-only diagnostics should run.
+ *
+ * Read at call time, not at module load, and deliberately *not* resolved when
+ * this package is bundled: `webpack.packages.base.js` sets
+ * `optimization.nodeEnv: false` so `process.env.NODE_ENV` survives into
+ * `dist/`, where the consumer's own bundler substitutes it for their build. A
+ * library that bakes in its own `mode` decides the question for everyone —
+ * which is how every deprecation warning in this package ended up compiling to
+ * `if (true) return;` in the published bundle, silently, while still firing in
+ * this repo's Jest runs.
+ *
+ * The expression must be a *bare* `process.env.NODE_ENV`, with nothing guarding
+ * it. Bundlers substitute that literal token sequence and nothing else: a
+ * `typeof process === 'undefined'` check in front of it is left untouched, so
+ * in a browser — where there is no `process` global — the guard returns `false`
+ * before the correctly-substituted value is ever reached, and every diagnostic
+ * goes dark for exactly the consumers they exist for. Same bug as the one
+ * above, entered from the other side.
+ *
+ * `try/catch` keeps the guarantee the guard was there for: a runtime that never
+ * defines `process` *and* whose bundler substituted nothing (a plain
+ * `<script type="module">`, a bare worker) throws a ReferenceError, which is
+ * caught here as silence rather than a crash. Erring toward silence is right —
+ * no diagnostic is worth crashing a consumer over.
+ */
+export declare const isDevEnvironment: () => boolean;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ssa-ui-kit/core",
-  "version": "3.19.1",
+  "version": "3.20.1",
   "main": "dist/index.js",
+  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
+      "import": "./dist/index.mjs",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
     }
@@ -39,8 +40,8 @@
     "luxon": "3.5.0",
     "plotly.js": "3.0.0",
     "react-plotly.js": "2.6.0",
-    "@ssa-ui-kit/hooks": "^3.19.1",
-    "@ssa-ui-kit/utils": "^3.19.1"
+    "@ssa-ui-kit/hooks": "^3.20.1",
+    "@ssa-ui-kit/utils": "^3.20.1"
   },
   "devDependencies": {
     "@emotion/css": "11.13.5",
@@ -57,8 +58,7 @@
     "@rjsf/utils": "5.24.8",
     "@rjsf/validator-ajv8": "5.24.8",
     "@types/luxon": "3.4.2",
-    "@types/react-plotly.js": "2.6.3",
-    "@types/sass": "1.45.0"
+    "@types/react-plotly.js": "2.6.3"
   },
   "browserslist": [
     ">0.1%",
@@ -76,8 +76,8 @@
     "@nivo/treemap": "^0.99.0",
     "@rjsf/core": "^5.0.0",
     "@rjsf/utils": "^5.0.0",
-    "react": "19.x",
-    "react-dom": "19.x",
+    "react": ">=19",
+    "react-dom": ">=19",
     "react-hook-form": "^7.46.1",
     "react-router-dom": "6.x || 7.x"
   },
@@ -87,8 +87,9 @@
     }
   },
   "scripts": {
+    "clean": "node ../../scripts/clean.mjs",
     "test": "jest -i --no-cache",
-    "build": "webpack --mode=production --node-env=production && tsc --build ./tsconfig.build.json && resolve-tspaths -p ./tsconfig.build.json",
+    "build": "node ../../scripts/clean.mjs && webpack --mode=production --node-env=production && tsc --build ./tsconfig.build.json && resolve-tspaths -p ./tsconfig.build.json",
     "build:watch": "webpack --mode=production --node-env=production --watch && tsc --build ./tsconfig.build.json && resolve-tspaths -p ./tsconfig.build.json",
     "sb:dev": "env storybook dev -p 6006",
     "sb:build": "env storybook build",