Proposal: @neodx/cva

[secundant]

Problems

cva.style isn't strong solution

• package development is frozen and the most valuable update has been abandoned for year
• cva doesn't introduce any complex concepts on top of the Variants AP. Its beta version only offers the compose API.

We have no other options :)

Without CVA-like solutions, we are obligated to constantly write tons of boilerplate code just for styling our components.
But even with the current cva state, we remain too far from the boiler-free workflow.

Key aspects

• Slots API
• Extendability
• Access to internal schema
• Partial extraction
• Seamless integration with UI libraries
• Restrictions for impossible combinations

Concept

Simple usage

const tab = cva({
  base: 'text-md font-medium border-bottom-2',
  variants: {
    disabled: cva.boolean(
      'cursor-default text-gray-400',
      [
        'cursor-pointer text-sky-600',
        'transition-colors hover:bg-sky-100 focus-visible:border-sky-400'
      ]
    ),
    size: {
      sm: 'px-4 py-2',
      md: 'px-6 py-3'
    }
  },
  defaults: {
    size: 'md'
  }
});

tab() // === tab({ disabled: false, size: 'md' });

compound API

Use case - huge amount of crossing nested rules:

export const button = cva({
  base: 'border-none flex align-center gap-2',
  variants: {
    size: {
      sm: 'p-2 rounded-sm',
      md: 'p-3 rounded-md',
    },
    color: {
      primary: 'outline-sky-600',
      danger: 'outline-red-600',
    },
    disabled: cva.boolean(
      'cursor-default',
      'cursor-pointer transition-colors focus-visible:outline-2',
    ),
    appearance: {
      outlined: 'border bg-transparent',
      filled: 'text-white',
      flat: 'bg-transparent',
    },
  },
  compounds: [
    {
      disabled: false,
      appearance: 'filled',
      className: 'shadow-sm hover:shadow-md focus-visible:shadow-lg',
    },
    {
      disabled: false,
      color: 'primary',
      appearance: 'outlined',
      className: [
        'border-sky-600',
        'hover:border-sky-800 hover:bg-sky-100 focus:border-sky-800 focus:bg-sky-100',
      ],
    },
    {
      disabled: false,
      color: 'primary',
      appearance: 'filled',
      className: ['bg-sky-500 hover:bg-sky-600 focus:bg-sky-600'],
    },
    {
      disabled: false,
      color: 'primary',
      appearance: 'flat',
      className: 'text-sky-600 hover:bg-sky-100 active:bg-sky-200 focus-visible:bg-sky-200',
    },
    {
      disabled: false,
      color: 'danger',
      appearance: 'outlined',
      className: [
        'border-red-600',
        'hover:border-red-800 hover:bg-red-100 focus:border-red-800 focus:bg-red-100',
      ],
    },
    {
      disabled: false,
      color: 'danger',
      appearance: 'filled',
      className: 'bg-red-500 hover:bg-red-600 focus:bg-red-600',
    },
    {
      disabled: false,
      color: 'danger',
      appearance: 'flat',
      className: 'text-red-600 hover:bg-red-100 active:bg-red-200 focus-visible:bg-red-200',
    },
    {
      disabled: true,
      appearance: 'filled',
      className: 'bg-gray-100',
    },
    {
      disabled: true,
      appearance: 'outlined',
      className: 'border-gray-100',
    },
  ],
  defaults: {
    size: 'md',
    color: 'primary',
    appearance: 'outlined',
  },
});

Could be redesigned as

export const button = cva({
  base: 'border-none flex align-center gap-2',
  variants: {
    size: {
      sm: 'p-2 rounded-sm',
      md: 'p-3 rounded-md',
    },
    color: {
      primary: 'outline-sky-600',
      danger: 'outline-red-600',
    },
    disabled: cva.boolean(
      'cursor-default',
      'cursor-pointer transition-colors focus-visible:outline-2',
    ),
    appearance: {
      outlined: 'border bg-transparent',
      filled: 'text-white',
      flat: 'bg-transparent',
    },
  },
  compounds: c => [
    c.when(
      { disabled: false },
      c.when(
        { appearance: 'filled' },
        'shadow-sm hover:shadow-md focus-visible:shadow-lg',
      ),
      c.when(
        { color: 'primary' },
        c.when(
          { appearance: 'outlined' },
          'text-sky-600 border-sky-600',
          'hover:border-sky-800 hover:bg-sky-100 focus:border-sky-800 focus:bg-sky-100',
        ),
        c.when(
          { appearance: 'filled' },
          'bg-sky-500 hover:bg-sky-600 focus:bg-sky-600',
        ),
        c.when(
          { appearance: 'flat' },
          'text-sky-600 hover:bg-sky-100 active:bg-sky-200 focus-visible:bg-sky-200',
        ),
      ),
      c.when(
        { color: 'danger' },
        c.when(
          { appearance: 'outlined' },
          'border-red-600',
          'hover:border-red-800 hover:bg-red-100 focus:border-red-800 focus:bg-red-100',
        ),
        c.when(
          { appearance: 'filled' },
          'bg-red-500 hover:bg-red-600 focus:bg-red-600',
        ),
        c.when(
          { appearance: 'flat' },
          'text-red-600 hover:bg-red-100 active:bg-red-200 focus-visible:bg-red-200',
        ),
      ),
    ),
    c.when(
      { disabled: true },
      c.when({ appearance: 'outlined' }, 'border-gray-100'),
      c.when({ appearance: 'filled' }, 'bg-gray-100'),
    ),
  ],
  defaults: {
    size: 'md',
    color: 'primary',
    appearance: 'outlined',
  },
});

Slots API

export const button = cva({
  base: 'border-none',
  variants: {
    size: {
      sm: 'p-2 rounded-sm',
      md: 'p-3 rounded-md'
    },
    color: {
      accent: 'text-white bg-green-500',
    }
  }
});
// to be continued...

Extendability

const button = cva({ /* ... */ });
const xxx = xxx; // to be continued...

Comparison

Case 1: Simple component

Let's start from writing the easiest variadic component:

const simpleExample = cva({
  base: 'text-gray-900 text-sm p-1 rounded-full flex items-center gap-1',
  variants: {
    size: {
      sm: 'text-xs',
      md: 'text-sm',
      lg: 'text-base'
    }
  }
});

export type SimpleExampleProps = VariantProps<typeof simpleExample> & {
  className?: string;
  children?: ReactNode;
};
export const SimpleExample = ({ size = 'md', className, children }: SimpleExampleProps) => (
  <div className={simpleExample({ size, className })}>{children}</div>
);

SimpleExample.displayName = 'SimpleExample';

Even for that simple example, there are a few obvious issues.
To set up our component, we should:

• write props type based on cva scheme,
• add className and children props,
• duplicate all variants-related props and forward them to our cva instance
• pass className to cva instance
• add displayName

The source problem indicates that the common patterns mentioned can be automated, but they currently are not.

Proposed alternative

export const SimpleExample = cva({
  base: 'text-gray-900 text-sm p-1 rounded-full flex items-center gap-1',
  variants: {
    size: {
      sm: 'text-xs',
      md: 'text-sm',
      lg: 'text-base'
    }
  }
}).ui('SimpleExample', ({ props }) => <div {...props} />);

The idea is simple:

1. We already know all variants
2. We know how to connect them and our UI
3. We can do it automatically!

Case 2: Forward ref and custom props

Usually, we aren't satisfied with using only the directly defined props, but we want to provide all possible HTML attributes and React ref to our component.

const forwardRefExample = cva({
  base: 'text-gray-900 text-sm p-1 rounded-full flex items-center gap-1',
  variants: {
    size: {
      sm: 'text-xs',
      md: 'text-sm',
      lg: 'text-base'
    }
  }
});

export type ForwardRefExampleProps = 
  // 1 - Extract variants
  VariantProps<typeof forwardRefExample> &
  // 2 - Inherit all props from native 'div' element
  ComponentPropsWithoutRef<'div'> &
  // 3 - Describe additional props (specifically these props inherit from 'div', but let's keep them)
  {
    children?: ReactNode;
    className?: string;
  };
export const ForwardRefExample = forwardRef<HTMLDivElement, ForwardRefExampleProps>(
  ({ size = 'md', className, children, checked, ...props }, ref) => (
    <div className={forwardRefExample({ size, className })} {...props} ref={ref}>
      {children}
    </div>
  )
);

ForwardRefExample.displayName = 'ForwardRefExample';

The problem is growing with the following parts:

• ref declaration and forwarding,
• using forwardRef with hardcoded HTMLDivElement,
• native props are inherited by ComponentPropsWithoutRef<'div'>

All of these parts are unnecessary.

Proposed alternative

Let's start from the simplest variant:

export const ForwardRefExample = cva({
  base: 'text-gray-900 text-sm p-1 rounded-full flex items-center gap-1',
  variants: {
    size: {
      sm: 'text-xs',
      md: 'text-sm',
      lg: 'text-base'
    }
  }
}).ui('ForwardRefExample', 'div');

The main idea here is automatic inheriting div behaviour without any additional code.

I've been mention additional props previously, but the proposal covers only 1-1 inheritance.
The next session will provide a detailed and illustrative overview of the scale of the problem.

Case 3: Composition of multiple elements that inherit common properties

The previous examples were just an introduction to illustrate the problem at the core level. However, our design system components (which are the crucial case for cva) usually require additional features and internal composition. For these reasons, I'm proposing the following concepts:

• "slots" in cva configuration for defining styles of internal elements
• chained cva.ui API for high-level describing our component implementation
• "slots" for seamlessly providing props forwarding, polymorphic components, and hidden integration with "slots" from cva scheme
• "props" for lightweight overriding and extending auto-detected props from the original schema
• "render" function as an overcharged component implementation API

But let's look at the original variant:

//#region Styles definition

const listItem = cva({
  base: 'flex items-center text-black',
  variants: {
    selected: cva.boolean('bg-blue-100', 'bg-transparent'),
    disabled: cva.boolean('opacity-90', 'transition-colors'),
    size: {
      sm: 'text-sm py-2 px-1 gap-1',
      md: 'text-md py-2.5 px-2 gap-1.5'
    }
  },
  compoundVariants: [
    {
      selected: true,
      disabled: false,
      className: 'hover:bg-blue-100'
    },
    {
      selected: false,
      disabled: false,
      className: 'hover:bg-gray-100'
    }
  ],
  defaultVariants: {
    selected: false,
    disabled: false
  }
});

const listItemIcon = cva({
  variants: {
    size: {
      sm: 'size-4',
      md: 'size-5'
    } satisfies Record<VariantProps<typeof listItem>['size'], string>
  }
});

const listItemAvatar = cva({
  base: 'bg-gray-100 rounded-full flex items-center justify-center',
  variants: {
    size: {
      sm: 'size-4',
      md: 'size-5'
    } satisfies Record<VariantProps<typeof listItem>['size'], string>
  }
});

const listItemDescription = cva({
  base: 'text-gray-500',
  variants: {
    size: {
      sm: 'text-xs',
      md: 'text-sm'
    } satisfies Record<VariantProps<typeof listItem>['size'], string>
  }
});

//#endregion

//#region SIMPLE version

// - no props forwarding,
// - no polymorphic components,
// - no refs forwarding

export type BaseListItemProps = VariantProps<typeof listItem> &
  ComponentPropsWithoutRef<'li'> & {
    description?: ReactNode;
    className?: string;
    children?: ReactNode;
    avatar?: ReactNode;
    icon?: IconName;
  };
export const BaseListItem = forwardRef<HTMLLIElement, BaseListItemProps>(
  (
    { size = 'md', avatar, className, selected, disabled, children, description, icon, ...props },
    ref
  ) => (
    <li className={listItem({ size, selected, disabled, className })} {...props} ref={ref}>
      {avatar && <div className={listItemAvatar({ size })}>{avatar}</div>}
      {icon && <Icon name={icon} className={listItemIcon({ size })} />}
      <div className="flex flex-col gap-1">
        <span>{children}</span>
        {description && <span className={listItemDescription({ size })}>{description}</span>}
      </div>
    </li>
  )
);

//#endregion

Tremendous boilerplate!
(here will be explanation...)

Full version

(here will be explanation...)

export type ListItemProps = VariantProps<typeof listItem> &
  ComponentPropsWithoutRef<'li'> & {
    as?: ComponentType<ComponentPropsWithRef<'li'>>;
    children?: ReactNode;
    className?: string;
    // Description
    description?: ReactNode;
    descriptionProps?: ComponentPropsWithRef<'span'>;
    DescriptionComponent?: ComponentType<ComponentPropsWithRef<'span'>>;
    // Icon
    icon?: IconName;
    iconProps?: ComponentProps<typeof Icon>;
    IconComponent?: ComponentType<ComponentProps<typeof Icon>>;
    // Avatar
    avatar?: ReactNode;
    avatarProps?: ComponentPropsWithRef<'div'>;
    AvatarComponent?: ComponentType<ComponentPropsWithRef<'div'>>;
  };
export const ListItem = forwardRef<HTMLLIElement, ListItemProps>(
  (
    {
      as: RootComponent = 'li',
      size = 'md',
      className,
      selected,
      disabled,
      children,
      description,
      descriptionProps,
      DescriptionComponent = 'span',
      icon,
      iconProps,
      IconComponent = Icon,
      avatar,
      avatarProps,
      AvatarComponent = 'div',
      ...props
    },
    ref
  ) => (
    <RootComponent
      {...props}
      className={listItem({ size, selected, disabled, className })}
      ref={ref}
    >
      {icon && (
        <IconComponent
          {...iconProps}
          name={icon}
          className={listItemIcon({ size, className: iconProps?.className })}
        />
      )}
      {avatar && (
        <AvatarComponent
          {...avatarProps}
          className={listItemAvatar({ size, className: avatarProps?.className })}
        >
          {avatar}
        </AvatarComponent>
      )}
      <div className="flex flex-col gap-1">
        <span>{children}</span>
        {description && (
          <DescriptionComponent
            {...descriptionProps}
            className={listItemDescription({ size, className: descriptionProps?.className })}
          >
            {description}
          </DescriptionComponent>
        )}
      </div>
    </RootComponent>
  )
);

ListItem.displayName = 'ListItem';

Proposal alternative

export const ListItem = cva({
  base: 'flex items-center text-black',
  variants: {
    selected: cva.boolean('bg-blue-100', 'bg-transparent'),
    disabled: cva.boolean('opacity-90', 'transition-colors'),
    size: {
      sm: 'text-sm py-2 px-1 gap-1',
      md: 'text-md py-2.5 px-2 gap-1.5'
    }
  },
  compounds: c =>
    c.when(
      { disabled: false },
      { selected: true, className: 'hover:bg-blue-100' },
      { selected: false, className: 'hover:bg-gray-100' }
    ),
  defaults: {
    selected: false,
    disabled: false
  },
  slots: {
    icon: {
      variants: {
        size: {
          sm: 'size-4',
          md: 'size-5'
        }
      }
    },
    avatar: {
      base: 'bg-gray-100 rounded-full flex items-center justify-center',
      variants: {
        size: {
          sm: 'size-4',
          md: 'size-5'
        }
      }
    },
    description: {
      variants: {
        size: {
          sm: 'text-xs',
          md: 'text-sm'
        }
      }
    }
  }
}).ui('ListItem', {
  // 1. Define components for all required slots
  slots: {
    root: 'li',
    icon: cva.slot<{ name: IconName }, IconProps>(Icon),
    avatar: 'div',
    description: 'span'
  },
  // 2. Describe additional props for type safety and ensure valid props are forwarded to the root component
  props: cva.props<{ avatar?: ReactNode; icon?: IconName; description?: ReactNode }>([
    'icon',
    'avatar',
    'description'
  ]),
  // 3. Define how to render the component
  render: ({ avatar, icon, description, children, slots }) => (
    <slots.root>
      {avatar && <slots.avatar>{avatar}</slots.avatar>}
      {icon && <slots.icon name={icon} />}
      <div className="flex flex-col gap-1">
        <span>{children}</span>
        {description && <slots.description>{description}</slots.description>}
      </div>
    </slots.root>
  )
});

[The73756]

Братан, хорош, давай, давай, вперёд! Контент в кайф, можно ещё? Вообще красавчик! Можно вот этого вот почаще?

[secundant]

Additional reference: https://www.tailwind-variants.org/