@commercetools/nimbus 0.0.2 → 0.0.3

package/package.json

@@ -1,59 +1,83 @@
 {
   "name": "@commercetools/nimbus",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "main": "./dist/index.umd.cjs",
   "module": "./dist/index.js",
   "type": "module",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.umd.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
+  "source": "src/index.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/index.d.ts"
+      ]
+    }
+  },
   "devDependencies": {
-    "@chakra-ui/cli": "^3.15.1",
-    "@pandacss/types": "^0.53.3",
-    "@storybook/addon-a11y": "^8.6.12",
-    "@storybook/addon-essentials": "^8.6.12",
-    "@storybook/experimental-addon-test": "^8.6.12",
-    "@storybook/preview-api": "^8.6.12",
-    "@storybook/react": "^8.6.12",
-    "@storybook/react-vite": "^8.6.12",
-    "@storybook/test": "^8.6.12",
-    "@testing-library/react": "^16.3.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
-    "@types/testing-library__dom": "^7.5.0",
-    "@vitejs/plugin-react": "^4.3.4",
-    "@vitest/browser": "^3.1.1",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@chakra-ui/cli": "catalog:react",
+    "@pandacss/types": "catalog:react",
+    "@storybook/addon-a11y": "catalog:tooling",
+    "@storybook/addon-essentials": "catalog:tooling",
+    "@storybook/experimental-addon-test": "catalog:tooling",
+    "@storybook/preview-api": "catalog:tooling",
+    "@storybook/react": "catalog:tooling",
+    "@storybook/react-vite": "catalog:tooling",
+    "@storybook/test": "catalog:tooling",
+    "@testing-library/react": "catalog:tooling",
+    "@testing-library/user-event": "catalog:tooling",
+    "@types/react": "catalog:react",
+    "@types/react-dom": "catalog:react",
+    "@vitejs/plugin-react": "catalog:tooling",
+    "@vitest/browser": "catalog:tooling",
+    "@vitest/coverage-v8": "catalog:tooling",
     "apca-w3": "^0.1.9",
     "axe-core": "^4.10.2",
-    "playwright": "^1.51.1",
-    "storybook": "^8.6.12",
-    "storybook-dark-mode": "^4.0.2",
-    "vite": "^6.2.6",
-    "vite-plugin-dts": "^4.5.3",
-    "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.1.1"
+    "playwright": "catalog:tooling",
+    "storybook": "catalog:tooling",
+    "storybook-dark-mode": "catalog:tooling",
+    "vite": "catalog:tooling",
+    "vite-plugin-dts": "catalog:tooling",
+    "vite-tsconfig-paths": "catalog:tooling",
+    "vitest": "catalog:tooling"
   },
   "peerDependencies": {
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "~5.8.3"
+    "react": "catalog:react",
+    "react-dom": "catalog:react",
+    "typescript": "catalog:tooling"
   },
   "dependencies": {
-    "@chakra-ui/react": "^3.15.1",
-    "@emotion/is-prop-valid": "^1.3.1",
+    "@commercetools/nimbus-icons": "workspace:^",
+    "@commercetools/nimbus-tokens": "workspace:^",
+    "@chakra-ui/react": "catalog:react",
+    "@emotion/is-prop-valid": "catalog:react",
     "@react-aria/optimize-locales-plugin": "^1.1.4",
-    "next-themes": "^0.4.6",
-    "react-aria": "^3.37.0",
-    "react-aria-components": "1.6.0",
+    "next-themes": "catalog:react",
+    "react-aria": "catalog:react",
+    "react-aria-components": "catalog:react",
     "react-hotkeys-hook": "^4.6.1",
-    "react-stately": "^3.35.0",
-    "react-use": "^17.5.1",
-    "@commercetools/nimbus-icons": "^0.0.2",
-    "@commercetools/nimbus-tokens": "^0.0.2"
+    "react-stately": "catalog:react",
+    "react-use": "^17.5.1"
   },
   "scripts": {
     "build": "pnpm run build-theme-typings && pnpm run build-lib",
@@ -64,4 +88,4 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"
   }
-}
+}

package/.storybook/apca-check/index.ts

@@ -1,150 +0,0 @@
-import axe, { type Check, Rule } from "axe-core";
-import { calcAPCA } from "apca-w3";
-
-type ConformanceLevel = "custom";
-
-type ConformanceThresholdFn = (
-  fontSize: string,
-  fontWeight: string
-) => number | null;
-
-// Augment Axe types to include the color utilities we use in this file
-// https://github.com/dequelabs/axe-core/blob/develop/lib/commons/color/color.js
-type Color = {
-  red: number;
-  green: number;
-  blue: number;
-  alpha: number;
-  toHexString: () => string;
-};
-declare module "axe-core" {
-  interface Commons {
-    color: {
-      getForegroundColor: (
-        node: HTMLElement,
-        _: unknown,
-        bgColor: Color | null
-      ) => Color | null;
-      getBackgroundColor: (node: HTMLElement) => Color | null;
-    };
-  }
-}
-
-const generateColorContrastAPCAConformanceCheck = (
-  conformanceLevel: string,
-  conformanceThresholdFn: ConformanceThresholdFn
-): Check => ({
-  id: `color-contrast-apca-${conformanceLevel}-conformance`,
-  metadata: {
-    impact: "serious",
-    messages: {
-      pass:
-        "Element has sufficient APCA " +
-        conformanceLevel +
-        " level lightness contrast (Lc) of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Expected minimum APCA contrast of ${data.apcaThreshold}}",
-      fail: {
-        default:
-          "Element has insufficient APCA " +
-          conformanceLevel +
-          " level contrast of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Expected minimum APCA lightness contrast of ${data.apcaThreshold}Lc",
-        increaseFont:
-          "Element has insufficient APCA " +
-          conformanceLevel +
-          " level contrast of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Increase font size and/or font weight to meet APCA conformance minimums",
-        placeholder:
-          "Element has insufficient APCA " +
-          conformanceLevel +
-          " level contrast of ${data.apcaContrast}Lc (foreground color: ${data.fgColor}, background color: ${data.bgColor}, font size: ${data.fontSize}, font weight: ${data.fontWeight}). Using reduced threshold of 30Lc for placeholder",
-      },
-      incomplete: "Unable to determine APCA lightness contrast (Lc)",
-    },
-  },
-  evaluate(n) {
-    const node = n as HTMLElement;
-    const nodeStyle = window.getComputedStyle(node);
-    const fontSize = nodeStyle.getPropertyValue("font-size");
-    const fontWeight = nodeStyle.getPropertyValue("font-weight");
-
-    const bgColor: Color | null = axe.commons.color.getBackgroundColor(node);
-    const fgColor: Color | null = axe.commons.color.getForegroundColor(
-      node,
-      false,
-      bgColor
-    );
-
-    // missing data to determine APCA contrast for this node
-    if (!bgColor || !fgColor || !fontSize || !fontWeight) {
-      return undefined;
-    }
-
-    const toRGBA = (color: Color) => {
-      return `rgba(${color.red}, ${color.green}, ${color.blue}, ${color.alpha})`;
-    };
-
-    const apcaContrast = Math.abs(
-      calcAPCA(toRGBA(fgColor), toRGBA(bgColor)) as number
-    );
-
-    // Check if element has data-placeholder attribute
-    const hasPlaceholderAttr = node.hasAttribute("data-placeholder");
-    const originalThreshold = conformanceThresholdFn(fontSize, fontWeight);
-
-    // Use reduced threshold of 30 for placeholders, otherwise use original threshold
-    const apcaThreshold = hasPlaceholderAttr ? 30 : originalThreshold;
-
-    this.data({
-      fgColor: fgColor.toHexString(),
-      bgColor: bgColor.toHexString(),
-      fontSize: `${((parseFloat(fontSize) * 72) / 96).toFixed(
-        1
-      )}pt (${parseFloat(fontSize)}px)`,
-      fontWeight: fontWeight,
-      apcaContrast: Math.round(apcaContrast * 100) / 100,
-      apcaThreshold: apcaThreshold,
-      messageKey:
-        apcaThreshold === null
-          ? "increaseFont"
-          : hasPlaceholderAttr
-            ? "placeholder"
-            : "default",
-    });
-
-    return apcaThreshold ? apcaContrast >= apcaThreshold : false;
-  },
-});
-
-const generateColorContrastAPCARule = (conformanceLevel: string): Rule => ({
-  id: `color-contrast-apca-${conformanceLevel}`,
-  impact: "serious",
-  matches: "color-contrast-matches",
-  metadata: {
-    description: `Ensures the contrast between foreground and background colors meets APCA ${conformanceLevel} level conformance minimums thresholds`,
-    help: "Elements must meet APCA conformance minimums thresholds",
-    helpUrl:
-      "https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion",
-  },
-  all: [`color-contrast-apca-${conformanceLevel}-conformance`],
-  tags: ["apca", "wcag3", `apca-${conformanceLevel}`],
-});
-
-const registerAPCACheck = (
-  conformanceLevel: ConformanceLevel,
-  conformanceThresholdFn: ConformanceThresholdFn
-) => {
-  if (typeof conformanceThresholdFn !== "function") {
-    throw new Error("Conformance threshold function is required");
-  }
-
-  return {
-    rules: [generateColorContrastAPCARule(conformanceLevel)],
-    checks: [
-      generateColorContrastAPCAConformanceCheck(
-        conformanceLevel,
-        conformanceThresholdFn
-      ),
-    ],
-  };
-};
-
-export type { ConformanceLevel, ConformanceThresholdFn };
-export default registerAPCACheck;

package/.storybook/main.ts

@@ -1,64 +0,0 @@
-import type { StorybookConfig } from "@storybook/react-vite";
-
-import { join, dirname } from "path";
-
-/**
- * This function is used to resolve the absolute path of a package.
- * It is needed in projects that use Yarn PnP or are set up within a monorepo.
- */
-function getAbsolutePackagePath(value: string): any {
-  return dirname(require.resolve(join(value, "package.json")));
-}
-
-const config: StorybookConfig = {
-  stories: ["../src/**/*.stories.tsx"],
-  addons: [
-    getAbsolutePackagePath("@storybook/addon-essentials"),
-    getAbsolutePackagePath("@storybook/addon-a11y"),
-    getAbsolutePackagePath("storybook-dark-mode"),
-    getAbsolutePackagePath("@storybook/experimental-addon-test"),
-  ],
-  framework: {
-    name: getAbsolutePackagePath("@storybook/react-vite"),
-    options: {},
-  },
-  refs: {
-    "@chakra-ui/react": {
-      disable: true,
-    },
-  },
-  core: {
-    disableTelemetry: true,
-  },
-  typescript: {
-    reactDocgen: "react-docgen-typescript",
-    // Provide your own options if necessary.
-    // See https://storybook.js.org/docs/configure/typescript for more information.
-    reactDocgenTypescriptOptions: {
-      compilerOptions: {
-        allowSyntheticDefaultImports: false,
-        esModuleInterop: false,
-      },
-
-      // Extend if needed...
-      propFilter: (prop) => {
-        // ... common props that every component may have
-        const whitelistedProps = ["ref", "colorScheme", "asChild"];
-
-        // ... props coming from the nimbus package
-        const isOneOfOurTypes = !!prop.parent?.fileName.includes("nimbus/src");
-
-        // ... props coming from the react-aria package
-        const isReactAriaProp =
-          !!prop.parent?.fileName.includes("@react-types");
-
-        return (
-          isOneOfOurTypes ||
-          isReactAriaProp ||
-          whitelistedProps.includes(prop.name)
-        );
-      },
-    },
-  },
-};
-export default config;

package/.storybook/preview.tsx

@@ -1,92 +0,0 @@
-import React, { useEffect, useState } from "react";
-import type { Preview } from "@storybook/react";
-import { NimbusProvider } from "../src";
-import { DARK_MODE_EVENT_NAME } from "storybook-dark-mode";
-import { addons } from "@storybook/preview-api";
-
-import APCACheck from "./apca-check";
-
-const apca = APCACheck("custom", (fontSize: string) => {
-  const size = parseFloat(fontSize);
-  switch (true) {
-    case size >= 32:
-      return 45;
-    default:
-      return 60;
-  }
-});
-
-// get channel to listen to event emitter
-const channel = addons.getChannel();
-
-const ThemeDecorator = ({ children }) => {
-  const [isDark, setDark] = useState(false);
-  const theme = isDark ? "dark" : "light";
-
-  useEffect(() => {
-    const { current } = JSON.parse(
-      // TODO: find out if there is a more elegant solution
-      localStorage.getItem("sb-addon-themes-3") || "{}"
-    );
-
-    setDark(current === "dark");
-
-    channel.on(DARK_MODE_EVENT_NAME, (darkMode) => {
-      setDark(darkMode);
-    });
-
-    return () => channel.off(DARK_MODE_EVENT_NAME, setDark);
-  }, [channel]);
-
-  useEffect(() => {
-    document.documentElement.classList.remove("light", "dark");
-    document.documentElement.classList.add(theme);
-  }, [theme]);
-
-  return <NimbusProvider defaultTheme={theme}>{children}</NimbusProvider>;
-};
-
-const preview: Preview = {
-  parameters: {
-    darkMode: {
-      stylePreview: true,
-      classTarget: "html",
-    },
-    backgrounds: {
-      disable: true,
-    },
-    a11y: {
-      config: {
-        checks: [...apca.checks],
-        rules: [
-          {
-            // disabled, as radix is using APCA algorithm while Storybook uses WCAG
-            // @see https://web.dev/articles/color-and-contrast-accessibility#apca)
-
-            id: "color-contrast",
-            enabled: false,
-          },
-          ...apca.rules,
-        ],
-      },
-      /*
-       * Axe's options parameter
-       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
-       * to learn more about the available options.
-       */
-      options: {},
-    },
-  },
-  tags: ["autodocs", "a11y-test"],
-  decorators: [
-    (Story) => {
-      return (
-        <ThemeDecorator>
-          <Story />
-        </ThemeDecorator>
-      );
-    },
-  ],
-};
-
-export default preview;

package/.storybook/vitest.setup.ts

@@ -1,13 +0,0 @@
-import * as a11yAddonAnnotations from "@storybook/addon-a11y/preview";
-import { beforeAll } from "vitest";
-import { setProjectAnnotations } from "@storybook/react";
-import * as projectAnnotations from "./preview";
-
-// This is an important step to apply the right configuration when testing your stories.
-// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
-const project = setProjectAnnotations([
-  a11yAddonAnnotations,
-  projectAnnotations,
-]);
-
-beforeAll(project.beforeAll);

package/docs/architecture-decisions/adr-0001-consumer-component-apis.md

@@ -1,177 +0,0 @@
-# ADR: On Consumer Component API's
-
-## Context
-
-We needed an Alert component to show informational or warning messages. The
-component should allow:
-
-- A title and description.
-- An optional dismiss button.
-- Additional buttons or controls.
-- Spacing/styling overrides (e.g. px, py).
-
-In early explorations, we tried to expose everything via props on the main
-`Alert`—this seemed convenient but would quickly became unwieldy when
-requirements changed. This led to a discussion about how to structure the API
-for components in a way that is both flexible and maintainable.
-
-## Early Attempts
-
-### Attempt A: One Big Alert with Child Buttons
-
-```jsx
-<Alert
-  title="title"
-  description="description"
-  onDismiss={() => void}
-  px="4"
-  py="2"
->
-  <button>Dismiss</button>
-  <button>Click me</button>
-</Alert>
-```
-
-1. title and description are top-level props.
-2. children are the alert's buttons.
-
-**Issue**: If we need new kinds of controls (e.g., a link, extra text, or
-re-positioned buttons), we must keep adding or repurposing props. The line
-between "belongs in children" vs. "belongs in dedicated props" can become
-blurry.
-
-### Attempt B: Specialized Props for Each Slot
-
-```jsx
-<Alert
-  alertTitleStyle="bold"
-  title="title"
-  description="description"
-  onDismiss={() => void}
-  px="4"
-  py="2"
-  alertControls={
-    <>
-      <button>Dismiss</button>
-      <button>Click me</button>
-    </>
-  }
-/>
-```
-
-1. We introduced an alertControls prop for the buttons.
-2. We also added alertTitleStyle to control how the title looks.
-
-**Issue**: As the design evolves (e.g., "Now we need the title right‐aligned, or
-a sub‐title below the main title"), we keep adding ad-hoc props like
-titlePosition, alertControlsAlignment, etc. The `<Alert>` props list grows large
-and messy.
-
-### Attempt C: Even More Props for Layout / Positioning
-
-```jsx
-<Alert
-  alertTitleStyle="bold"
-  title="title"
-  titlePosition="right"
-  description="description"
-  onDismiss={() => void}
-  px="4"
-  py="2"
-  alertControls={
-    <>
-      <button>Dismiss</button>
-      <button>Click me</button>
-    </>
-  }
-/>
-```
-
-**Issue**: The top-level `<Alert>` component now has numerous styling, layout,
-and content props all jumbled together. If a new design wants a second dismiss
-button or a multi-line description, we must add more props. This is non-scalable
-and not very semantic.
-
-## Final Decision: Compound Components
-
-We decided to adopt compound components (a pattern in which sub-elements are
-also React components). The final API looks like:
-
-```jsx
-<Alert px="4" py="2">
-  <Alert.Title fontStyle="bold">
-    Alert Title
-  </Alert.Title>
-  <Alert.Description>
-    A short alert description.
-  </Alert.Description>
-  <Alert.DismissButton onClick={() => void} />
-</Alert>
-```
-
-### Key Changes:
-
-1. Children become semantic slots: `<Alert.Title>`, `<Alert.Description>`, and
-   `<Alert.DismissButton>`.
-2. Each slot can handle its own styling or props. For instance, Alert.Title
-   might accept a fontStyle prop, Alert.DismissButton handles its own click
-   event.
-3. The root `<Alert>` only handles general layout or high-level variant props
-   (e.g., px, py, severity).
-
-### Why this is better:
-
-- **Clear separation of concerns**: Layout/styling for each slot belongs to that
-  slot. The main `<Alert>` only handles spacing or theming.
-- **Easier to extend**: If we need a second sub-element (e.g., `<Alert.Icon>` or
-  `<Alert.Footer>`), we just introduce a new subcomponent. We don't clog
-  `<Alert>` with more props.
-- **Semantic**: `<Alert.Title>` and `<Alert.Description>` are more descriptive
-  than `title="..."` or `alertControls={...}`.
-
-## Consequences
-
-- We have a more verbose but much more flexible API.
-- Consumers build their alert in a semantic, composable way.
-- We can add or rearrange subcomponents without rewriting the main `<Alert>`
-  props or code.
-- If developers want quick usage (like a single short message), they might find
-  passing a couple props simpler – but we've prioritized long-term
-  maintainability and clarity.
-
-## Examples in Practice
-
-### 1. Basic Alert
-
-```jsx
-<Alert>
-  <Alert.Title>Warning!</Alert.Title>
-  <Alert.Description>Please fill out all required fields.</Alert.Description>
-  <Alert.DismissButton onClick={onClose} />
-</Alert>
-```
-
-### 2. Alert with Extra Controls
-
-```jsx
-<Alert px="4" py="3">
-  <Alert.Title fontStyle="bold">Network Error</Alert.Title>
-  <Alert.Description>
-    We could not reach the server. Please try again.
-  </Alert.Description>
-  <Alert.DismissButton onClick={onClose} />
-  <Alert.Controls>
-    <Button onClick={onRetry}>Retry</Button>
-  </Alert.Controls>
-</Alert>
-```
-
-## Summary
-
-- Inline props for major sections quickly lead to "prop creep."
-- Compound components keep `<Alert>` minimal and delegate content/markup details
-  to semantically named subcomponents.
-- Layout changes or extra features do not require new top-level props on
-  `<Alert>`.
-
-This approach scales better and is more maintainable as the design evolves.