Add possibility for utilities whitelist/blacklist on JSX

[ianvieira]

On the JSX syntax, Panda CSS supports 3 different filters for the utilities on the jsxStyleProps config:

• All: All utilities are allowed
• Minimal: Only CSS prop is allowed
• None: No customization is allowed

From my understanding, the utilities are not only used for the JSX props, but it's how Panda knows the connection between a property and its allowed values.

When creating a Design System, we don't want to allow all the CSS properties to be customizable, usually we want only a set of them available for the consumers. The "All" is too permissive. At the same time, the "Minimal" is too restrictive, as it allows no prop customization and limits cases where you want to set direct values (as width, for example).

The alternative would be to eject from the default utilities, but they are really good and already links all the tokens to the correct values, if we add only the utilities we would like to expose, we would loose the token connection on properties as color, which usually is something you don't want to expose on a DS.

My proposal is to be able to on the "All" approach to allow/block specific utilities from being accessible through JSX prop syntax, on the configuration level (for all components) and even on component level if needed:

Configuration object:

{
   jsxStylePropsInclude?: string[],
   jsxStylePropsExclude?: string[],
}

On a styled component:

const Button = styled('button', {
  base: {},
  utilities?: {
      include?: string[],
      exclude?: string[]
  }
})

With this flexibility, when creating the button, by default it will assume the values from the config include/exclude. If needed you can expose more utilities on a component based approach, all this without loosing the ability of using the same utility when creating the base for it.

[astahmer]

I kinda did that as a panda plugin here (@pandabox/panda-plugins):
https://github.com/astahmer/pandabox/tree/main/packages/panda-plugins

import { defineConfig } from '@pandacss/dev'
import { pluginRestrictStyledProps } from '@pandabox/panda-plugins'

export default defineConfig({
  plugins: [pluginRestrictStyledProps()],
  jsxFramework: 'react',
  // ...
})

[cgatian]

I tried for awhile to make this plugin work with atomic recipes without much luck. I ended up doing the following:

import { buttonRecipe, ButtonRecipeProps } from './Button.recipe';

// Create a styled button with a recipe attached
const StyledButton = styled('button', buttonRecipe, {
  defaultProps: {
    type: 'button',
  },
});

// Describe the StyledComponent props I want to support
type StyleProps = Pick<
  HTMLStyledProps<'button'>,
  | 'margin'
  | 'm'
  | 'mx'
  | 'my'
  | 'ml'
  | 'mr'
  | 'mt'
  | 'mb'
  | 'margin'
  | 'marginX'
  | 'marginY'
  | 'marginLeft'
  | 'marginRight'
  | 'marginTop'
  | 'marginBottom'
>;

export type ButtonProps = StyleProps &
  ButtonRecipeProps &
  PatchHtmlProps<ButtonHTMLAttributes<HTMLButtonElement>>;

I found a patch method in chakra-ui

import { DistributiveOmit } from 'styled-system/types';

export type HtmlProp =
  | 'color'
  | 'size'
  | 'translate'
  | 'transition'
  | 'width'
  | 'height'
  | 'content';

/**
 * Removes html properties that intersect with an StyledComponent.
 */
export type PatchHtmlProps<T> = DistributiveOmit<T, HtmlProp>;