@cognitiv/components-web 1.0.4 → 1.1.0

package/README.md

@@ -0,0 +1,266 @@
+# @cognitiv/components-web
+
+A modern React UI component library built with Tailwind CSS v4, React Aria Components, and TypeScript. Ships 87 accessible, composable components following compound component patterns inspired by Radix UI.
+
+## Tech Stack
+
+| Category        | Technology                                            |
+| --------------- | ----------------------------------------------------- |
+| Framework       | React 19+                                             |
+| Styling         | Tailwind CSS 4.2, tailwind-variants, tailwind-merge   |
+| Accessibility   | React Aria Components (Adobe)                         |
+| Language        | TypeScript 6.0                                        |
+| Bundler         | Rollup 4                                              |
+| Dev Environment | Storybook 10                                          |
+| Package Manager | npm                                                   |
+| Node            | v22+ (see `.nvmrc`)                                   |
+| Icons           | Iconify + @gravity-ui/icons                           |
+
+## Prerequisites
+
+- **Node.js v22+** — install via [nvm](https://github.com/nvm-sh/nvm):
+  ```bash
+  nvm install
+  nvm use
+  ```
+- **npm** (ships with Node)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook dev server (http://127.0.0.1:6006)
+npm run dev
+
+# Build the package
+npm run build
+```
+
+## Scripts
+
+| Command                  | Description                              |
+| ------------------------ | ---------------------------------------- |
+| `npm run dev`            | Start Storybook on port 6006             |
+| `npm run build`          | Build with TypeScript declarations       |
+| `npm run build:fast`     | Build without type declarations (faster) |
+| `npm run build:storybook`| Build static Storybook site              |
+| `npm run lint`           | Run ESLint                               |
+| `npm run lint:fix`       | Run ESLint with auto-fix                 |
+| `npm run format`         | Check formatting with Prettier           |
+| `npm run format:fix`     | Fix formatting with Prettier             |
+| `npm run typecheck`      | Run TypeScript type-checking             |
+| `npm run clean`          | Remove `dist/` and `node_modules/`       |
+
+## Project Structure
+
+```
+├── src/
+│   ├── components/          # 87 UI components
+│   ├── css/                 # Global CSS, theme layers, component CSS imports
+│   ├── styles/              # Utility styles
+│   ├── utils/               # Shared utilities (composeTwRenderProps, etc.)
+│   └── index.ts             # Package entry point
+├── storybook/
+│   ├── .storybook/          # Storybook config (main.ts, preview.tsx)
+│   ├── stories/             # Global/demo stories
+│   └── public/              # Static assets
+├── config/                  # Shared ESLint, Prettier, TypeScript configs
+├── scripts/                 # Build and scaffolding scripts
+├── infra/                   # AWS CDK infrastructure (S3 + CloudFront)
+├── .claude/                 # Claude Code agents and guides
+├── .agents/                 # Installable agent skills
+├── rollup.config.mjs        # Build configuration
+└── package.json
+```
+
+## Component Architecture
+
+Each component follows this file structure:
+
+```
+src/components/button/
+├── button.tsx               # Component implementation (React Aria + compound pattern)
+├── styles.ts                # Tailwind Variants definitions (tv())
+├── styles.css               # BEM CSS implementation (co-located)
+├── button.stories.tsx       # Storybook stories
+└── index.ts                 # Barrel exports
+```
+
+### Key Patterns
+
+- **Compound components** — Complex components export composable parts (Root, Item, Trigger, Content, etc.) connected via React Context
+- **React Aria foundation** — All components use React Aria for accessibility (ARIA patterns, keyboard navigation, screen reader support)
+- **BEM CSS naming** — `.block`, `.block--modifier`, `.block__element`
+- **Default size pattern** — Base classes include `--md` dimensions; size variants override them
+- **Dual styling** — Components use both `tv()` (tailwind-variants) for variant mapping and co-located `.css` files for BEM classes
+
+### Creating a New Component
+
+```bash
+npm run add:component ComponentName
+```
+
+This scaffolds all files and adds the export to `src/components/index.ts`. Then implement following the patterns in `src/components/accordion/` (compound) or `src/components/button/` (simple).
+
+## Git Conventions
+
+This repo enforces [Conventional Commits](https://www.conventionalcommits.org/) via Husky + commitlint.
+
+```
+<type>(<scope>): <message>
+```
+
+**Allowed types:** `feat`, `feature`, `fix`, `refactor`, `docs`, `build`, `test`, `ci`, `chore`, `revert`, `style`
+
+```bash
+# Examples
+git commit -m "feat(components): add Tooltip component"
+git commit -m "fix(button): resolve focus ring not showing"
+git commit -m "refactor(card): migrate to CSS-based styles"
+```
+
+Commits that don't match this format are rejected by the pre-commit hook. Staged files are also auto-linted and formatted via lint-staged.
+
+## Code Quality
+
+Before committing, always run:
+
+```bash
+npm run lint && npm run typecheck
+```
+
+### Linting & Formatting
+
+- **ESLint 9** (flat config) with plugins for React, TypeScript, accessibility, import ordering, and Storybook
+- **Prettier** with `prettier-plugin-tailwindcss` and `prettier-plugin-css-order`
+- **Husky** pre-commit hooks run lint-staged on all staged files
+
+### Tailwind CSS Rules
+
+Tailwind scans files as plain text. **Never construct class names dynamically:**
+
+```tsx
+// BAD — Tailwind can't detect these
+<div className={`text-${color}-600`} />
+<span className={`button--${size}`} />
+
+// GOOD — Use complete class name mappings
+const colorMap = { red: "text-red-600", blue: "text-blue-600" };
+<div className={colorMap[color]} />
+```
+
+## Storybook
+
+Storybook is the primary development environment. It runs on [http://127.0.0.1:6006](http://127.0.0.1:6006).
+
+```bash
+npm run dev
+```
+
+### Story Conventions
+
+- All component stories use the title format: `"Components/ComponentName"`
+- Stories live next to their component: `src/components/button/button.stories.tsx`
+- Global/demo stories live in `storybook/stories/`
+
+### Addons
+
+- **@storybook/addon-a11y** — Accessibility auditing
+- **@storybook/addon-docs** — Auto-generated documentation
+- **@storybook/addon-mcp** — MCP server integration (see below)
+- Custom decorators: React Strict Mode, Theme switcher, Reduce Motion, React Scan
+
+## Storybook MCP Server
+
+The project includes an MCP (Model Context Protocol) server that exposes Storybook component data to AI agents like Claude Code.
+
+### Setup
+
+1. Start Storybook:
+   ```bash
+   npm run dev
+   ```
+
+2. The MCP server is automatically available at `http://localhost:6006/mcp` (configured in `.mcp.json`).
+
+3. Claude Code will automatically connect to the Storybook MCP when the dev server is running, giving it access to component stories, documentation, and live component context.
+
+### Configuration
+
+The MCP server is defined in `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "storybook-mcp": {
+      "url": "http://localhost:6006/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+This is powered by `@storybook/addon-mcp` (v0.4.2) configured in `storybook/.storybook/main.ts`.
+
+## Claude Code Agent Skills
+
+This project includes specialized Claude Code agents for common development tasks. These are defined in `.claude/agents/` and are automatically available when using Claude Code in this repository.
+
+### Available Agents
+
+| Agent | Color | Purpose |
+| ----- | ----- | ------- |
+| **component-builder** | Blue | Creates new components or updates existing ones. Handles compound component patterns, React Aria integration, variants, and Storybook stories. |
+| **style-migrator** | Orange | Migrates component styles from TypeScript-based `tv()` definitions to CSS-based BEM classes. Preserves all variants and visual styles. |
+| **tailwind-v4-css-expert** | Green | Analyzes, creates, and debugs Tailwind CSS v4 component CSS files. Assists with `@apply` directives, CSS nesting, and Lightning CSS. |
+| **storybook-debugger** | Cyan | Debugs Storybook runtime issues — CSS transformation errors, Tailwind v4 compatibility, and component styling problems. |
+
+### Guides
+
+- `.claude/guides/tailwindcss-v4-css-guide.md` — Comprehensive Tailwind CSS v4 reference used by the style-migrator and tailwind-v4-css-expert agents.
+
+### Installed Skills
+
+- **npm-updater** (`.agents/skills/npm-updater/`) — Workflow for safely updating npm dependencies with changelog analysis and migration guide discovery.
+
+### Using Agents
+
+Agents are invoked automatically by Claude Code when relevant tasks are detected. You can also reference them directly:
+
+- Ask Claude Code to "create a new Select component" → triggers **component-builder**
+- Ask to "migrate the chip styles to CSS" → triggers **style-migrator**
+- Ask to "fix the button.css file" → triggers **tailwind-v4-css-expert**
+- Ask to "debug why tooltip is broken in Storybook" → triggers **storybook-debugger**
+
+## CI/CD
+
+GitHub Actions workflows in `.github/workflows/`:
+
+| Workflow | Trigger | What it does |
+| -------- | ------- | ------------ |
+| `ci.yml` | Pull requests to `main` | Runs ESLint + Prettier checks |
+| `deploy-storybook.yml` | Push to `main` / manual | Builds & deploys Storybook to S3 + CloudFront |
+| `release.yml` | Manual (workflow_dispatch) | Bumps version, builds, publishes to npm |
+
+## Package Consumption
+
+Install in a consuming project:
+
+```bash
+npm install @cognitiv/components-web
+```
+
+**Peer dependencies:** React >=19.0.0, React DOM >=19.0.0, Tailwind CSS >=4.0.0
+
+Import components and styles:
+
+```tsx
+import { Button } from "@cognitiv/components-web";
+import "@cognitiv/components-web/styles";
+```
+
+## License
+
+MIT

package/dist/components/accordion/accordion.d.ts

@@ -0,0 +1,30 @@
+import type { AccordionVariants } from "./styles";
+import type { ComponentPropsWithRef } from "react";
+import { Button, Disclosure, DisclosureGroup, Heading as DisclosureHeading, DisclosurePanel } from "react-aria-components";
+interface AccordionRootProps extends ComponentPropsWithRef<typeof DisclosureGroup>, AccordionVariants {
+    hideSeparator?: boolean;
+}
+declare const AccordionRoot: ({ children, className, hideSeparator, variant, ...props }: AccordionRootProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionItemProps extends ComponentPropsWithRef<typeof Disclosure> {
+}
+declare const AccordionItem: ({ className, ...props }: AccordionItemProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionIndicatorProps extends ComponentPropsWithRef<"svg"> {
+    className?: string;
+}
+declare const AccordionIndicator: ({ children, className, ...props }: AccordionIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionHeadingProps extends ComponentPropsWithRef<typeof DisclosureHeading> {
+    className?: string;
+}
+declare const AccordionHeading: ({ className, ...props }: AccordionHeadingProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionTriggerProps extends ComponentPropsWithRef<typeof Button> {
+}
+declare const AccordionTrigger: ({ className, ...props }: AccordionTriggerProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionBodyProps extends ComponentPropsWithRef<"div"> {
+    className?: string;
+}
+declare const AccordionBody: ({ children, className, ...props }: AccordionBodyProps) => import("react/jsx-runtime").JSX.Element;
+interface AccordionPanelProps extends ComponentPropsWithRef<typeof DisclosurePanel> {
+}
+declare const AccordionPanel: ({ children, className, ...props }: AccordionPanelProps) => import("react/jsx-runtime").JSX.Element;
+export { AccordionRoot, AccordionItem, AccordionTrigger, AccordionPanel, AccordionIndicator, AccordionBody, AccordionHeading, };
+export type { AccordionRootProps, AccordionItemProps, AccordionTriggerProps, AccordionPanelProps, AccordionIndicatorProps, AccordionBodyProps, AccordionHeadingProps, };

package/dist/components/accordion/accordion.js

@@ -0,0 +1,191 @@
+"use client";
+import React__default, { useContext, createContext } from 'react';
+import { DisclosureGroup, Button, DisclosureStateContext, DisclosurePanel, Disclosure, Heading } from 'react-aria-components';
+import { dataAttr } from '../../utils/assertion.js';
+import { composeTwRenderProps, composeSlotClassName } from '../../utils/compose.js';
+import { IconChevronDown } from '../icons.js';
+import { accordionVariants } from './styles.js';
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { SurfaceContext } from '../surface/surface.js';
+
+const AccordionContext = /*#__PURE__*/createContext({});
+
+/* -------------------------------------------------------------------------------------------------
+ * Accordion Root
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionRoot = ({
+  children,
+  className,
+  hideSeparator = false,
+  variant,
+  ...props
+}) => {
+  const slots = React__default.useMemo(() => accordionVariants({
+    variant
+  }), [variant]);
+  const content = /*#__PURE__*/jsx(DisclosureGroup, {
+    className: composeTwRenderProps(className, slots.base()),
+    "data-slot": "accordion",
+    ...props,
+    children: values => /*#__PURE__*/jsx(Fragment, {
+      children: typeof children === "function" ? children(values) : children
+    })
+  });
+  return /*#__PURE__*/jsx(AccordionContext, {
+    value: {
+      hideSeparator,
+      slots
+    },
+    children: variant === "surface" ?
+    /*#__PURE__*/
+    // Allows inner components to apply "on-surface" colors for proper contrast
+    jsx(SurfaceContext, {
+      value: {
+        variant: "default"
+      },
+      children: content
+    }) : content
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionItem
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionItem = ({
+  className,
+  ...props
+}) => {
+  const {
+    hideSeparator,
+    slots
+  } = useContext(AccordionContext);
+  return /*#__PURE__*/jsx(Disclosure, {
+    className: composeTwRenderProps(className, slots?.item()),
+    "data-hide-separator": hideSeparator ? "true" : undefined,
+    "data-slot": "accordion-item",
+    ...props,
+    children: props.children
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionIndicator
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionIndicator = ({
+  children,
+  className,
+  ...props
+}) => {
+  const {
+    slots
+  } = useContext(AccordionContext);
+  const {
+    isExpanded
+  } = useContext(DisclosureStateContext);
+  if (children && /*#__PURE__*/React__default.isValidElement(children)) {
+    return /*#__PURE__*/React__default.cloneElement(children, {
+      ...props,
+      className: composeSlotClassName(slots?.indicator, className),
+      "data-expanded": dataAttr(isExpanded),
+      "data-slot": "accordion-indicator"
+    });
+  }
+  return /*#__PURE__*/jsx(IconChevronDown, {
+    className: composeSlotClassName(slots?.indicator, className),
+    "data-expanded": dataAttr(isExpanded),
+    "data-slot": "accordion-indicator",
+    ...props
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionHeading
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionHeading = ({
+  className,
+  ...props
+}) => {
+  const {
+    slots
+  } = useContext(AccordionContext);
+  return /*#__PURE__*/jsx(Heading, {
+    className: composeSlotClassName(slots?.heading, className),
+    "data-slot": "accordion-heading",
+    ...props
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionTrigger
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionTrigger = ({
+  className,
+  ...props
+}) => {
+  const {
+    slots
+  } = useContext(AccordionContext);
+  return /*#__PURE__*/jsx(Button, {
+    className: composeTwRenderProps(className, slots?.trigger()),
+    "data-slot": "accordion-trigger",
+    slot: "trigger",
+    ...props,
+    children: values => /*#__PURE__*/jsx(Fragment, {
+      children: typeof props.children === "function" ? props.children(values) : props.children
+    })
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionBody
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionBody = ({
+  children,
+  className,
+  ...props
+}) => {
+  const {
+    slots
+  } = useContext(AccordionContext);
+  return /*#__PURE__*/jsx("div", {
+    className: slots?.body({}),
+    "data-slot": "accordion-body",
+    ...props,
+    children: /*#__PURE__*/jsx("div", {
+      className: composeSlotClassName(slots?.bodyInner, className),
+      children: children
+    })
+  });
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * AccordionPanel
+ * -----------------------------------------------------------------------------------------------*/
+
+const AccordionPanel = ({
+  children,
+  className,
+  ...props
+}) => {
+  const {
+    slots
+  } = useContext(AccordionContext);
+  const {
+    isExpanded
+  } = useContext(DisclosureStateContext);
+  return /*#__PURE__*/jsx(DisclosurePanel, {
+    className: composeTwRenderProps(className, slots?.panel()),
+    "data-expanded": dataAttr(isExpanded),
+    "data-slot": "accordion-panel",
+    ...props,
+    children: children
+  });
+};
+
+export { AccordionBody, AccordionHeading, AccordionIndicator, AccordionItem, AccordionPanel, AccordionRoot, AccordionTrigger };

package/dist/components/accordion/index.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentProps } from "react";
+import { AccordionBody, AccordionHeading, AccordionIndicator, AccordionItem, AccordionPanel, AccordionRoot, AccordionTrigger } from "./accordion";
+export declare const Accordion: (({ children, className, hideSeparator, variant, ...props }: import("./accordion").AccordionRootProps) => import("react/jsx-runtime").JSX.Element) & {
+    Body: ({ children, className, ...props }: import("./accordion").AccordionBodyProps) => import("react/jsx-runtime").JSX.Element;
+    Heading: ({ className, ...props }: import("./accordion").AccordionHeadingProps) => import("react/jsx-runtime").JSX.Element;
+    Indicator: ({ children, className, ...props }: import("./accordion").AccordionIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+    Item: ({ className, ...props }: import("./accordion").AccordionItemProps) => import("react/jsx-runtime").JSX.Element;
+    Panel: ({ children, className, ...props }: import("./accordion").AccordionPanelProps) => import("react/jsx-runtime").JSX.Element;
+    Root: ({ children, className, hideSeparator, variant, ...props }: import("./accordion").AccordionRootProps) => import("react/jsx-runtime").JSX.Element;
+    Trigger: ({ className, ...props }: import("./accordion").AccordionTriggerProps) => import("react/jsx-runtime").JSX.Element;
+};
+export type Accordion = {
+    Props: ComponentProps<typeof AccordionRoot>;
+    RootProps: ComponentProps<typeof AccordionRoot>;
+    ItemProps: ComponentProps<typeof AccordionItem>;
+    HeadingProps: ComponentProps<typeof AccordionHeading>;
+    TriggerProps: ComponentProps<typeof AccordionTrigger>;
+    PanelProps: ComponentProps<typeof AccordionPanel>;
+    IndicatorProps: ComponentProps<typeof AccordionIndicator>;
+    BodyProps: ComponentProps<typeof AccordionBody>;
+};
+export { AccordionRoot, AccordionItem, AccordionHeading, AccordionTrigger, AccordionPanel, AccordionIndicator, AccordionBody, };
+export type { AccordionRootProps, AccordionRootProps as AccordionProps, AccordionItemProps, AccordionHeadingProps, AccordionTriggerProps, AccordionPanelProps, AccordionIndicatorProps, AccordionBodyProps, } from "./accordion";
+export { accordionVariants } from "./styles";
+export type { AccordionVariants } from "./styles";

package/dist/components/accordion/index.js

@@ -0,0 +1,18 @@
+"use strict";
+import { AccordionRoot, AccordionTrigger, AccordionPanel, AccordionItem, AccordionIndicator, AccordionHeading, AccordionBody } from './accordion.js';
+export { accordionVariants } from './styles.js';
+
+/* -------------------------------------------------------------------------------------------------
+ * Compound Component
+ * -----------------------------------------------------------------------------------------------*/
+const Accordion = Object.assign(AccordionRoot, {
+  Body: AccordionBody,
+  Heading: AccordionHeading,
+  Indicator: AccordionIndicator,
+  Item: AccordionItem,
+  Panel: AccordionPanel,
+  Root: AccordionRoot,
+  Trigger: AccordionTrigger
+});
+
+export { Accordion, AccordionBody, AccordionHeading, AccordionIndicator, AccordionItem, AccordionPanel, AccordionRoot, AccordionTrigger };

package/dist/components/accordion/styles.d.ts

@@ -0,0 +1,53 @@
+import type { VariantProps } from "tailwind-variants";
+export declare const accordionVariants: import("tailwind-variants").TVReturnType<{
+    variant: {
+        default: {};
+        surface: {
+            base: string;
+        };
+    };
+}, {
+    base: string;
+    body: string;
+    bodyInner: string;
+    heading: string;
+    indicator: string;
+    item: string;
+    panel: string;
+    trigger: string;
+}, undefined, {
+    variant: {
+        default: {};
+        surface: {
+            base: string;
+        };
+    };
+}, {
+    base: string;
+    body: string;
+    bodyInner: string;
+    heading: string;
+    indicator: string;
+    item: string;
+    panel: string;
+    trigger: string;
+}, import("tailwind-variants").TVReturnType<{
+    variant: {
+        default: {};
+        surface: {
+            base: string;
+        };
+    };
+}, {
+    base: string;
+    body: string;
+    bodyInner: string;
+    heading: string;
+    indicator: string;
+    item: string;
+    panel: string;
+    trigger: string;
+}, undefined, unknown, unknown, undefined>>;
+type DisclosureRenderPropsKeys = "isExpanded" | "isDisabled" | "state";
+export type AccordionVariants = Omit<VariantProps<typeof accordionVariants>, DisclosureRenderPropsKeys>;
+export {};

package/dist/components/accordion/styles.js

@@ -0,0 +1,27 @@
+"use strict";
+import { tv } from 'tailwind-variants';
+
+const accordionVariants = tv({
+  slots: {
+    base: "accordion",
+    body: "accordion__body",
+    bodyInner: "accordion__body-inner",
+    heading: "accordion__heading",
+    indicator: "accordion__indicator",
+    item: "accordion__item",
+    panel: "accordion__panel",
+    trigger: "accordion__trigger"
+  },
+  variants: {
+    variant: {
+      default: {},
+      surface: {
+        base: "accordion--surface"
+      }
+    }
+  }
+});
+
+// Render props that should be excluded from AccordionVariants (framework-specific)
+
+export { accordionVariants };

package/dist/components/alert/alert.d.ts

@@ -0,0 +1,15 @@
+import type { AlertVariants } from "./styles";
+import type { ComponentPropsWithRef } from "react";
+interface AlertRootProps extends ComponentPropsWithRef<"div">, AlertVariants {
+}
+declare const AlertRoot: ({ children, className, status, ...rest }: AlertRootProps) => import("react/jsx-runtime").JSX.Element;
+type AlertIndicatorProps = ComponentPropsWithRef<"div">;
+declare const AlertIndicator: ({ children, className, ...rest }: AlertIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+type AlertContentProps = ComponentPropsWithRef<"div">;
+declare const AlertContent: ({ children, className, ...rest }: AlertContentProps) => import("react/jsx-runtime").JSX.Element;
+type AlertTitleProps = ComponentPropsWithRef<"p">;
+declare const AlertTitle: ({ children, className, ...rest }: AlertTitleProps) => import("react/jsx-runtime").JSX.Element;
+type AlertDescriptionProps = ComponentPropsWithRef<"span">;
+declare const AlertDescription: ({ children, className, ...rest }: AlertDescriptionProps) => import("react/jsx-runtime").JSX.Element;
+export { AlertRoot, AlertIndicator, AlertContent, AlertTitle, AlertDescription };
+export type { AlertRootProps, AlertIndicatorProps, AlertContentProps, AlertTitleProps, AlertDescriptionProps, };