From 0a4be85a676e20441f934c171d4b534df8c9da27 Mon Sep 17 00:00:00 2001 From: Charles de Dreuille Date: Mon, 27 Jan 2025 17:59:23 +0000 Subject: [PATCH] Update props Signed-off-by: Charles de Dreuille --- packages/canon/report.api.md | 420 ++++++++++++++++-- .../canon/src/components/Box/Box.props.ts | 28 +- packages/canon/src/components/Box/Box.tsx | 2 + packages/canon/src/components/Box/index.tsx | 2 + packages/canon/src/components/Box/types.ts | 3 +- .../Container/Container.stories.tsx | 1 - .../src/components/Container/Container.tsx | 30 +- .../src/components/Grid/Grid.stories.tsx | 2 - .../src/components/Inline/Inline.stories.tsx | 1 - packages/canon/src/index.ts | 2 + packages/canon/src/props/display.props.ts | 37 ++ packages/canon/src/props/height.props.ts | 35 +- packages/canon/src/props/index.ts | 22 + packages/canon/src/props/margin.props.ts | 88 +--- packages/canon/src/props/padding.props.ts | 88 +--- packages/canon/src/props/position.props.ts | 26 +- packages/canon/src/props/prop-def.ts | 81 ++-- packages/canon/src/props/width.props.ts | 35 +- 18 files changed, 532 insertions(+), 371 deletions(-) create mode 100644 packages/canon/src/props/display.props.ts create mode 100644 packages/canon/src/props/index.ts diff --git a/packages/canon/report.api.md b/packages/canon/report.api.md index 8899f6ad45..64a1482867 100644 --- a/packages/canon/report.api.md +++ b/packages/canon/report.api.md @@ -17,6 +17,13 @@ import { RefAttributes } from 'react'; // @public (undocumented) export type AlignItems = 'stretch' | 'start' | 'center' | 'end'; +// @public (undocumented) +export type ArbitraryStylingPropDef = { + className: string; + customProperties: `--${string}`[]; + parseValue?: (value: string) => string | undefined; +}; + // @public (undocumented) export type AsProps = | 'div' @@ -36,6 +43,14 @@ export type AsProps = | 'dl' | 'dt'; +// @public (undocumented) +export type BooleanPropDef = { + type: 'boolean'; + default?: boolean; + required?: boolean; + className?: string; +}; + // @public (undocumented) export type Border = 'none' | 'base' | 'error' | 'warning' | 'selected'; @@ -56,20 +71,51 @@ export const Box: ForwardRefExoticComponent< >; // @public (undocumented) -export interface BoxProps extends UtilityProps { +export type BoxOwnProps = GetPropDefTypes; + +// @public (undocumented) +export const boxPropDefs: { + as: { + type: 'enum'; + values: readonly ['div', 'span']; + default: 'div'; + }; +}; + +// @public (undocumented) +export interface BoxProps extends SpaceProps { // (undocumented) - as?: keyof JSX.IntrinsicElements; + as?: BoxOwnProps['as']; // (undocumented) children?: React.ReactNode; // (undocumented) className?: string; // (undocumented) + display?: DisplayProps['display']; + // (undocumented) + height?: HeightProps['height']; + // (undocumented) + maxHeight?: HeightProps['maxHeight']; + // (undocumented) + maxWidth?: WidthProps['maxWidth']; + // (undocumented) + minHeight?: HeightProps['minHeight']; + // (undocumented) + minWidth?: WidthProps['minWidth']; + // (undocumented) + position?: PositionProps['position']; + // (undocumented) style?: React.CSSProperties; + // (undocumented) + width?: WidthProps['width']; } // @public (undocumented) export type Breakpoint = 'initial' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'; +// @public (undocumented) +export const breakpoints: Breakpoint[]; + // @public (undocumented) export const Button: React_2.ForwardRefExoticComponent< ButtonProps & React_2.RefAttributes @@ -149,8 +195,8 @@ export interface CheckboxProps { export type Columns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'auto'; // @public (undocumented) -export const Container: React_2.ForwardRefExoticComponent< - ContainerProps & React_2.RefAttributes +export const Container: ForwardRefExoticComponent< + ContainerProps & RefAttributes >; // @public (undocumented) @@ -160,17 +206,17 @@ export interface ContainerProps { // (undocumented) className?: string; // (undocumented) - marginBottom?: SpaceProps['marginBottom']; + mb?: SpaceProps['mb']; // (undocumented) - marginTop?: SpaceProps['marginTop']; + mt?: SpaceProps['mt']; // (undocumented) - marginY?: SpaceProps['marginY']; + my?: SpaceProps['my']; // (undocumented) - paddingBottom?: SpaceProps['paddingBottom']; + pb?: SpaceProps['pb']; // (undocumented) - paddingTop?: SpaceProps['paddingTop']; + pt?: SpaceProps['pt']; // (undocumented) - paddingY?: SpaceProps['paddingY']; + py?: SpaceProps['py']; // (undocumented) style?: React.CSSProperties; } @@ -178,6 +224,35 @@ export interface ContainerProps { // @public (undocumented) export type Display = 'none' | 'flex' | 'block' | 'inline'; +// @public (undocumented) +export const displayPropDefs: { + display: { + type: 'enum'; + className: string; + values: readonly ['none', 'inline', 'inline-block', 'block']; + responsive: true; + }; +}; + +// @public (undocumented) +export type DisplayProps = GetPropDefTypes; + +// @public (undocumented) +export type EnumOrStringPropDef = { + type: 'enum | string'; + values: readonly T[]; + default?: T | string; + required?: boolean; +}; + +// @public (undocumented) +export type EnumPropDef = { + type: 'enum'; + values: readonly T[]; + default?: T; + required?: boolean; +}; + // @public (undocumented) export const Field: { Root: React_2.ForwardRefExoticComponent< @@ -214,6 +289,34 @@ export type FlexDirection = 'row' | 'column'; // @public (undocumented) export type FlexWrap = 'wrap' | 'nowrap' | 'wrap-reverse'; +// @public (undocumented) +export type GetPropDefType = Def extends BooleanPropDef + ? Def extends ResponsivePropDef + ? Responsive + : boolean + : Def extends StringPropDef + ? Def extends ResponsivePropDef + ? Responsive + : string + : Def extends ReactNodePropDef + ? Def extends ResponsivePropDef + ? Responsive + : React_2.ReactNode + : Def extends EnumOrStringPropDef + ? Def extends ResponsivePropDef + ? Responsive + : string | Type + : Def extends EnumPropDef + ? Def extends ResponsivePropDef + ? Responsive + : Type + : never; + +// @public (undocumented) +export type GetPropDefTypes

= { + [K in keyof P]?: GetPropDefType; +}; + // @public (undocumented) export const Grid: ForwardRefExoticComponent< GridProps & RefAttributes @@ -286,6 +389,31 @@ export interface HeadingProps { >; } +// @public (undocumented) +export const heightPropDefs: { + height: { + type: 'string'; + className: string; + customProperties: '--height'[]; + responsive: true; + }; + minHeight: { + type: 'string'; + className: string; + customProperties: '--min-height'[]; + responsive: true; + }; + maxHeight: { + type: 'string'; + className: string; + customProperties: '--max-height'[]; + responsive: true; + }; +}; + +// @public (undocumented) +export type HeightProps = GetPropDefTypes; + // @public (undocumented) export const Icon: (props: IconProps) => React_2.JSX.Element; @@ -378,38 +506,216 @@ export type JustifyContent = | 'between'; // @public (undocumented) -export type Space = 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'; +export const marginPropDefs: (spacingValues: string[]) => { + m: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: '--m'[]; + responsive: true; + }; + mx: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: ('--ml' | '--mr')[]; + responsive: true; + }; + my: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: ('--mt' | '--mb')[]; + responsive: true; + }; + mt: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: '--mt'[]; + responsive: true; + }; + mr: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: '--mr'[]; + responsive: true; + }; + mb: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: '--mb'[]; + responsive: true; + }; + ml: { + type: 'enum | string'; + values: string[]; + className: string; + customProperties: '--ml'[]; + responsive: true; + }; +}; + +// @public (undocumented) +export type MarginProps = GetPropDefTypes; + +// @public (undocumented) +export type NonStylingPropDef = { + className?: never; + customProperties?: never; + parseValue?: never; +}; + +// @public (undocumented) +export const paddingPropDefs: (spacingValues: string[]) => { + p: { + type: 'enum | string'; + className: string; + customProperties: '--p'[]; + values: string[]; + responsive: true; + }; + px: { + type: 'enum | string'; + className: string; + customProperties: ('--pl' | '--pr')[]; + values: string[]; + responsive: true; + }; + py: { + type: 'enum | string'; + className: string; + customProperties: ('--pt' | '--pb')[]; + values: string[]; + responsive: true; + }; + pt: { + type: 'enum | string'; + className: string; + customProperties: '--pt'[]; + values: string[]; + responsive: true; + }; + pr: { + type: 'enum | string'; + className: string; + customProperties: '--pr'[]; + values: string[]; + responsive: true; + }; + pb: { + type: 'enum | string'; + className: string; + customProperties: '--pb'[]; + values: string[]; + responsive: true; + }; + pl: { + type: 'enum | string'; + className: string; + customProperties: '--pl'[]; + values: string[]; + responsive: true; + }; +}; + +// @public (undocumented) +export type PaddingProps = GetPropDefTypes; + +// @public (undocumented) +export const positionPropDefs: { + position: { + type: 'enum'; + className: string; + values: readonly ['static', 'relative', 'absolute', 'fixed', 'sticky']; + responsive: true; + }; +}; + +// @public (undocumented) +export type PositionProps = GetPropDefTypes; + +// @public (undocumented) +export type PropDef = RegularPropDef | ResponsivePropDef; + +// @public (undocumented) +export type ReactNodePropDef = { + type: 'ReactNode'; + default?: React_2.ReactNode; + required?: boolean; +}; + +// @public (undocumented) +export type RegularPropDef = + | ReactNodePropDef + | BooleanPropDef + | (StringPropDef & ArbitraryStylingPropDef) + | (StringPropDef & NonStylingPropDef) + | (EnumPropDef & StylingPropDef) + | (EnumPropDef & NonStylingPropDef) + | (EnumOrStringPropDef & ArbitraryStylingPropDef) + | (EnumOrStringPropDef & NonStylingPropDef); + +// @public (undocumented) +export type Responsive = T | Partial>; + +// @public (undocumented) +export type ResponsivePropDef = RegularPropDef & { + responsive: true; +}; + +// @public (undocumented) +export type Space = + | '0.5' + | '1' + | '1.5' + | '2' + | '3' + | '4' + | '5' + | '6' + | '7' + | '8' + | '9' + | '10' + | '11' + | '12' + | '13' + | '14' + | string; // @public (undocumented) export interface SpaceProps { // (undocumented) - margin?: Space | Partial>; + m?: Responsive; // (undocumented) - marginBottom?: Space | Partial>; + mb?: Responsive; // (undocumented) - marginLeft?: Space | Partial>; + ml?: Responsive; // (undocumented) - marginRight?: Space | Partial>; + mr?: Responsive; // (undocumented) - marginTop?: Space | Partial>; + mt?: Responsive; // (undocumented) - marginX?: Space | Partial>; + mx?: Responsive; // (undocumented) - marginY?: Space | Partial>; + my?: Responsive; // (undocumented) - padding?: Space | Partial>; + p?: Responsive; // (undocumented) - paddingBottom?: Space | Partial>; + pb?: Responsive; // (undocumented) - paddingLeft?: Space | Partial>; + pl?: Responsive; // (undocumented) - paddingRight?: Space | Partial>; + pr?: Responsive; // (undocumented) - paddingTop?: Space | Partial>; + pt?: Responsive; // (undocumented) - paddingX?: Space | Partial>; + px?: Responsive; // (undocumented) - paddingY?: Space | Partial>; + py?: Responsive; } // @public (undocumented) @@ -437,6 +743,19 @@ export interface StackProps extends SpaceProps { style?: React.CSSProperties; } +// @public (undocumented) +export type StringPropDef = { + type: 'string'; + default?: string; + required?: boolean; +}; + +// @public (undocumented) +export type StylingPropDef = { + className: string; + parseValue?: (value: string) => string | undefined; +}; + // @public (undocumented) export const Table: React_3.ForwardRefExoticComponent< React_3.HTMLAttributes & @@ -510,30 +829,55 @@ export const useCanon: () => CanonContextProps; // @public (undocumented) export interface UtilityProps extends SpaceProps { // (undocumented) - alignItems?: AlignItems | Partial>; + alignItems?: Responsive; // (undocumented) - border?: Border | Partial>; + border?: Responsive; // (undocumented) - borderRadius?: BorderRadius | Partial>; + borderRadius?: Responsive; // (undocumented) - colEnd?: Columns | 'auto' | Partial>; + colEnd?: Responsive; // (undocumented) - colSpan?: Columns | 'full' | Partial>; + colSpan?: Responsive; // (undocumented) - colStart?: Columns | 'auto' | Partial>; + colStart?: Responsive; // (undocumented) - columns?: Columns | Partial>; + columns?: Responsive; // (undocumented) - display?: Display | Partial>; + display?: Responsive; // (undocumented) - flexDirection?: FlexDirection | Partial>; + flexDirection?: Responsive; // (undocumented) - flexWrap?: FlexWrap | Partial>; + flexWrap?: Responsive; // (undocumented) - gap?: Space | Partial>; + gap?: Responsive; // (undocumented) - justifyContent?: JustifyContent | Partial>; + justifyContent?: Responsive; // (undocumented) - rowSpan?: Columns | 'full' | Partial>; + rowSpan?: Responsive; } + +// @public (undocumented) +export const widthPropDefs: { + width: { + type: 'string'; + className: string; + customProperties: '--width'[]; + responsive: true; + }; + minWidth: { + type: 'string'; + className: string; + customProperties: '--min-width'[]; + responsive: true; + }; + maxWidth: { + type: 'string'; + className: string; + customProperties: '--max-width'[]; + responsive: true; + }; +}; + +// @public (undocumented) +export type WidthProps = GetPropDefTypes; ``` diff --git a/packages/canon/src/components/Box/Box.props.ts b/packages/canon/src/components/Box/Box.props.ts index 68e011ad93..3cf0291e43 100644 --- a/packages/canon/src/components/Box/Box.props.ts +++ b/packages/canon/src/components/Box/Box.props.ts @@ -17,40 +17,16 @@ import type { PropDef, GetPropDefTypes } from '../../props/prop-def'; const as = ['div', 'span'] as const; -const displayValues = ['none', 'inline', 'inline-block', 'block'] as const; +/** @public */ const boxPropDefs = { - /** - * Controls whether to render **div** or **span** - * - * @example - * as="div" - * as="span" - */ as: { type: 'enum', values: as, default: 'div' }, - /** - * Sets the CSS **display** property. - * Supports a subset of the corresponding CSS values and responsive objects. - * - * @example - * display="inline-block" - * display={{ sm: 'none', lg: 'block' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/display - */ - display: { - type: 'enum', - className: 'cu-display', - values: displayValues, - responsive: true, - }, } satisfies { as: PropDef<(typeof as)[number]>; - display: PropDef<(typeof displayValues)[number]>; }; // Use all of the imported prop defs to ensure that JSDoc works +/** @public */ type BoxOwnProps = GetPropDefTypes; export { boxPropDefs }; diff --git a/packages/canon/src/components/Box/Box.tsx b/packages/canon/src/components/Box/Box.tsx index 9a92d26de1..27f8a3046f 100644 --- a/packages/canon/src/components/Box/Box.tsx +++ b/packages/canon/src/components/Box/Box.tsx @@ -23,6 +23,7 @@ import { boxPropDefs } from './Box.props'; import { widthPropDefs } from '../../props/width.props'; import { heightPropDefs } from '../../props/height.props'; import { positionPropDefs } from '../../props/position.props'; +import { displayPropDefs } from '../../props/display.props'; /** @public */ export const Box = forwardRef((props, ref) => { @@ -34,6 +35,7 @@ export const Box = forwardRef((props, ref) => { ...widthPropDefs, ...heightPropDefs, ...positionPropDefs, + ...displayPropDefs, ...boxPropDefs, }; const { className, style } = extractProps(props, propDefs); diff --git a/packages/canon/src/components/Box/index.tsx b/packages/canon/src/components/Box/index.tsx index d47e653dfd..087a940a2d 100644 --- a/packages/canon/src/components/Box/index.tsx +++ b/packages/canon/src/components/Box/index.tsx @@ -15,3 +15,5 @@ */ export { Box } from './Box'; export type * from './types'; +export type { BoxOwnProps } from './Box.props'; +export { boxPropDefs } from './Box.props'; diff --git a/packages/canon/src/components/Box/types.ts b/packages/canon/src/components/Box/types.ts index 6105de0a97..c70012dd56 100644 --- a/packages/canon/src/components/Box/types.ts +++ b/packages/canon/src/components/Box/types.ts @@ -17,13 +17,14 @@ import type { HeightProps } from '../../props/height.props'; import type { WidthProps } from '../../props/width.props'; import type { PositionProps } from '../../props/position.props'; +import type { DisplayProps } from '../../props/display.props'; import type { SpaceProps } from '../../types'; import type { BoxOwnProps } from './Box.props'; /** @public */ export interface BoxProps extends SpaceProps { + display?: DisplayProps['display']; as?: BoxOwnProps['as']; - display?: BoxOwnProps['display']; width?: WidthProps['width']; minWidth?: WidthProps['minWidth']; maxWidth?: WidthProps['maxWidth']; diff --git a/packages/canon/src/components/Container/Container.stories.tsx b/packages/canon/src/components/Container/Container.stories.tsx index c9f468048e..f6b0fab8ba 100644 --- a/packages/canon/src/components/Container/Container.stories.tsx +++ b/packages/canon/src/components/Container/Container.stories.tsx @@ -37,7 +37,6 @@ type Story = StoryObj; const DecorativeBox = () => ( ( (props, ref) => { - const { children, className, style, ...restProps } = props; + const { children } = props; - // Generate utility class names - const utilityClassNames = getClassNames(restProps); + // Extract utility class names and styles + const propDefs = { + ...displayPropDefs, + }; + const { className, style } = extractProps(props, propDefs); - return ( -

- {children} -
- ); + return createElement('div', { + ref, + className: clsx('canon-Container', className), + style, + children, + }); }, ); diff --git a/packages/canon/src/components/Grid/Grid.stories.tsx b/packages/canon/src/components/Grid/Grid.stories.tsx index 9aeec52d00..8d235cd736 100644 --- a/packages/canon/src/components/Grid/Grid.stories.tsx +++ b/packages/canon/src/components/Grid/Grid.stories.tsx @@ -42,7 +42,6 @@ type Story = StoryObj; const FakeBox = () => ( ( ; +}; + +/** @public */ +type DisplayProps = GetPropDefTypes; + +export { displayPropDefs }; +export type { DisplayProps }; diff --git a/packages/canon/src/props/height.props.ts b/packages/canon/src/props/height.props.ts index a4c2c3f87f..b42f965e54 100644 --- a/packages/canon/src/props/height.props.ts +++ b/packages/canon/src/props/height.props.ts @@ -15,52 +15,20 @@ */ import type { PropDef, GetPropDefTypes } from './prop-def'; +/** @public */ const heightPropDefs = { - /** - * Sets the CSS **height** property. - * Supports CSS strings and responsive objects. - * - * @example - * height="100px" - * height={{ md: '100vh', xl: '600px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/height - */ height: { type: 'string', className: 'cu-h', customProperties: ['--height'], responsive: true, }, - /** - * Sets the CSS **min-height** property. - * Supports CSS strings and responsive objects. - * - * @example - * minHeight="100px" - * minHeight={{ md: '100vh', xl: '600px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/min-height - */ minHeight: { type: 'string', className: 'cu-min-h', customProperties: ['--min-height'], responsive: true, }, - /** - * Sets the CSS **max-height** property. - * Supports CSS strings and responsive objects. - * - * @example - * maxHeight="100px" - * maxHeight={{ md: '100vh', xl: '600px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/max-height - */ maxHeight: { type: 'string', className: 'cu-max-h', @@ -73,6 +41,7 @@ const heightPropDefs = { maxHeight: PropDef; }; +/** @public */ type HeightProps = GetPropDefTypes; export { heightPropDefs }; diff --git a/packages/canon/src/props/index.ts b/packages/canon/src/props/index.ts new file mode 100644 index 0000000000..79093974b3 --- /dev/null +++ b/packages/canon/src/props/index.ts @@ -0,0 +1,22 @@ +/* + * Copyright 2025 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +export type { DisplayProps, displayPropDefs } from './display.props'; +export type { HeightProps, heightPropDefs } from './height.props'; +export type { MarginProps, marginPropDefs } from './margin.props'; +export type { PaddingProps, paddingPropDefs } from './padding.props'; +export type { PositionProps, positionPropDefs } from './position.props'; +export type { WidthProps, widthPropDefs } from './width.props'; +export * from './prop-def'; diff --git a/packages/canon/src/props/margin.props.ts b/packages/canon/src/props/margin.props.ts index 69baf08ab7..94ec01cfc8 100644 --- a/packages/canon/src/props/margin.props.ts +++ b/packages/canon/src/props/margin.props.ts @@ -15,20 +15,9 @@ */ import type { PropDef, GetPropDefTypes } from './prop-def'; +/** @public */ const marginPropDefs = (spacingValues: string[]) => ({ - /** - * Sets the CSS **margin** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * m="4" - * m="100px" - * m={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin - */ m: { type: 'enum | string', values: spacingValues, @@ -36,19 +25,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--m'], responsive: true, }, - /** - * Sets the CSS **margin-left** and **margin-right** properties. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * mx="4" - * mx="100px" - * mx={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right - */ mx: { type: 'enum | string', values: spacingValues, @@ -56,19 +32,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--ml', '--mr'], responsive: true, }, - /** - * Sets the CSS **margin-top** and **margin-bottom** properties. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * my="4" - * my="100px" - * my={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom - */ my: { type: 'enum | string', values: spacingValues, @@ -76,18 +39,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--mt', '--mb'], responsive: true, }, - /** - * Sets the CSS **margin-top** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * mt="4" - * mt="100px" - * mt={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top - */ mt: { type: 'enum | string', values: spacingValues, @@ -95,18 +46,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--mt'], responsive: true, }, - /** - * Sets the CSS **margin-right** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * mr="4" - * mr="100px" - * mr={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right - */ mr: { type: 'enum | string', values: spacingValues, @@ -114,18 +53,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--mr'], responsive: true, }, - /** - * Sets the CSS **margin-bottom** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * mb="4" - * mb="100px" - * mb={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom - */ mb: { type: 'enum | string', values: spacingValues, @@ -133,18 +60,6 @@ const marginPropDefs = (spacingValues: string[]) => customProperties: ['--mb'], responsive: true, }, - /** - * Sets the CSS **margin-left** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * ml="4" - * ml="100px" - * ml={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left - */ ml: { type: 'enum | string', values: spacingValues, @@ -162,6 +77,7 @@ const marginPropDefs = (spacingValues: string[]) => ml: PropDef<(typeof spacingValues)[number]>; }); +/** @public */ type MarginProps = GetPropDefTypes; export { marginPropDefs }; diff --git a/packages/canon/src/props/padding.props.ts b/packages/canon/src/props/padding.props.ts index 5c145ee6fd..4ae686adb9 100644 --- a/packages/canon/src/props/padding.props.ts +++ b/packages/canon/src/props/padding.props.ts @@ -16,20 +16,9 @@ import { PropDef } from './prop-def'; import { GetPropDefTypes } from './prop-def'; +/** @public */ const paddingPropDefs = (spacingValues: string[]) => ({ - /** - * Sets the CSS **padding** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * p="4" - * p="100px" - * p={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding - */ p: { type: 'enum | string', className: 'cu-p', @@ -37,19 +26,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-left** and **padding-right** properties. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * px="4" - * px="100px" - * px={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right - */ px: { type: 'enum | string', className: 'cu-px', @@ -57,19 +33,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-top** and **padding-bottom** properties. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * py="4" - * py="100px" - * py={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom - */ py: { type: 'enum | string', className: 'cu-py', @@ -77,18 +40,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-top** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * pt="4" - * pt="100px" - * pt={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top - */ pt: { type: 'enum | string', className: 'cu-pt', @@ -96,18 +47,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-right** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * pr="4" - * pr="100px" - * pr={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right - */ pr: { type: 'enum | string', className: 'cu-pr', @@ -115,18 +54,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-bottom** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * pb="4" - * pb="100px" - * pb={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom - */ pb: { type: 'enum | string', className: 'cu-pb', @@ -134,18 +61,6 @@ const paddingPropDefs = (spacingValues: string[]) => values: spacingValues, responsive: true, }, - /** - * Sets the CSS **padding-left** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * pl="4" - * pl="100px" - * pl={{ sm: '6', lg: '9' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left - */ pl: { type: 'enum | string', className: 'cu-pl', @@ -163,6 +78,7 @@ const paddingPropDefs = (spacingValues: string[]) => pl: PropDef<(typeof spacingValues)[number]>; }); +/** @public */ type PaddingProps = GetPropDefTypes; export { paddingPropDefs }; diff --git a/packages/canon/src/props/position.props.ts b/packages/canon/src/props/position.props.ts index 7c7e0b3b28..048e3b13ce 100644 --- a/packages/canon/src/props/position.props.ts +++ b/packages/canon/src/props/position.props.ts @@ -15,6 +15,7 @@ */ import type { PropDef, GetPropDefTypes } from './prop-def'; +/** @public */ const positionValues = [ 'static', 'relative', @@ -23,41 +24,20 @@ const positionValues = [ 'sticky', ] as const; +/** @public */ const positionPropDefs = { - /** - * Sets the CSS **position** property. - * Supports the corresponding CSS values and responsive objects. - * - * @example - * position="absolute" - * position={{ sm: 'absolute', lg: 'sticky' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/position - */ position: { type: 'enum', className: 'cu-position', values: positionValues, responsive: true, }, - /** - * Sets the CSS **top** property. - * Supports space scale values, CSS strings, and responsive objects. - * - * @example - * top="4" - * top="100px" - * top={{ sm: '0', lg: '50%' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/top - */ } satisfies { position: PropDef<(typeof positionValues)[number]>; }; // Use all of the imported prop defs to ensure that JSDoc works +/** @public */ type PositionProps = GetPropDefTypes; export { positionPropDefs }; diff --git a/packages/canon/src/props/prop-def.ts b/packages/canon/src/props/prop-def.ts index b4689a13ca..eb721aa115 100644 --- a/packages/canon/src/props/prop-def.ts +++ b/packages/canon/src/props/prop-def.ts @@ -14,62 +14,71 @@ * limitations under the License. */ import type React from 'react'; +import type { Breakpoint, Responsive } from '../types'; -// Creates a union type of string literals with strings, but retains intellisense for the literals. -// Union => string | Omit -type Union = T | Omit; +/** @public */ +const breakpoints = ['initial', 'xs', 'sm', 'md', 'lg', 'xl'] as Breakpoint[]; -const breakpoints = ['initial', 'xs', 'sm', 'md', 'lg', 'xl'] as const; -type Breakpoint = (typeof breakpoints)[number]; -type Responsive = T | Partial>; - -type BooleanPropDef = { +/** @public */ +export type BooleanPropDef = { type: 'boolean'; default?: boolean; required?: boolean; className?: string; }; -type StringPropDef = { + +/** @public */ +export type StringPropDef = { type: 'string'; default?: string; required?: boolean; }; -type ReactNodePropDef = { + +/** @public */ +export type ReactNodePropDef = { type: 'ReactNode'; default?: React.ReactNode; required?: boolean; }; -type EnumPropDef = { + +/** @public */ +export type EnumPropDef = { type: 'enum'; values: readonly T[]; default?: T; required?: boolean; }; -type EnumOrStringPropDef = { + +/** @public */ +export type EnumOrStringPropDef = { type: 'enum | string'; values: readonly T[]; default?: T | string; required?: boolean; }; -type NonStylingPropDef = { +/** @public */ +export type NonStylingPropDef = { className?: never; customProperties?: never; parseValue?: never; }; -type StylingPropDef = { +/** @public */ +export type StylingPropDef = { className: string; parseValue?: (value: string) => string | undefined; }; -type ArbitraryStylingPropDef = { +/** @public */ +export type ArbitraryStylingPropDef = { className: string; customProperties: `--${string}`[]; parseValue?: (value: string) => string | undefined; }; -type RegularPropDef = +/** @public */ +export type RegularPropDef = | ReactNodePropDef | BooleanPropDef | (StringPropDef & ArbitraryStylingPropDef) @@ -78,19 +87,39 @@ type RegularPropDef = | (EnumPropDef & NonStylingPropDef) | (EnumOrStringPropDef & ArbitraryStylingPropDef) | (EnumOrStringPropDef & NonStylingPropDef); -type ResponsivePropDef = RegularPropDef & { responsive: true }; + +/** @public */ +type ResponsivePropDef = RegularPropDef & { + responsive: true; +}; + +/** @public */ type PropDef = RegularPropDef | ResponsivePropDef; -// prettier-ignore -type GetPropDefType = - Def extends BooleanPropDef ? (Def extends ResponsivePropDef ? Responsive : boolean) - : Def extends StringPropDef ? (Def extends ResponsivePropDef ? Responsive : string) - : Def extends ReactNodePropDef ? (Def extends ResponsivePropDef ? Responsive : React.ReactNode) - : Def extends EnumOrStringPropDef ? - Def extends ResponsivePropDef ? Responsive> : Type - : Def extends EnumPropDef ? (Def extends ResponsivePropDef ? Responsive : Type) +/** @public */ +export type GetPropDefType = Def extends BooleanPropDef + ? Def extends ResponsivePropDef + ? Responsive + : boolean + : Def extends StringPropDef + ? Def extends ResponsivePropDef + ? Responsive + : string + : Def extends ReactNodePropDef + ? Def extends ResponsivePropDef + ? Responsive + : React.ReactNode + : Def extends EnumOrStringPropDef + ? Def extends ResponsivePropDef + ? Responsive + : string | Type + : Def extends EnumPropDef + ? Def extends ResponsivePropDef + ? Responsive + : Type : never; +/** @public */ type GetPropDefTypes

= { [K in keyof P]?: GetPropDefType; }; @@ -100,8 +129,6 @@ export type { PropDef, GetPropDefTypes, ResponsivePropDef, - // Breakpoint, Responsive, - Union, }; diff --git a/packages/canon/src/props/width.props.ts b/packages/canon/src/props/width.props.ts index 2f549012f7..fdd8f3fdd4 100644 --- a/packages/canon/src/props/width.props.ts +++ b/packages/canon/src/props/width.props.ts @@ -15,52 +15,20 @@ */ import type { GetPropDefTypes, PropDef } from './prop-def'; +/** @public */ const widthPropDefs = { - /** - * Sets the CSS **width** property. - * Supports CSS strings and responsive objects. - * - * @example - * width="100px" - * width={{ md: '100vw', xl: '1400px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/width - */ width: { type: 'string', className: 'cu-w', customProperties: ['--width'], responsive: true, }, - /** - * Sets the CSS **min-width** property. - * Supports CSS strings and responsive objects. - * - * @example - * minWidth="100px" - * minWidth={{ md: '100vw', xl: '1400px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/min-width - */ minWidth: { type: 'string', className: 'cu-min-w', customProperties: ['--min-width'], responsive: true, }, - /** - * Sets the CSS **max-width** property. - * Supports CSS strings and responsive objects. - * - * @example - * maxWidth="100px" - * maxWidth={{ md: '100vw', xl: '1400px' }} - * - * @link - * https://developer.mozilla.org/en-US/docs/Web/CSS/max-width - */ maxWidth: { type: 'string', className: 'cu-max-w', @@ -73,6 +41,7 @@ const widthPropDefs = { maxWidth: PropDef; }; +/** @public */ type WidthProps = GetPropDefTypes; export { widthPropDefs };