From 76cae673eb5bf289b3e90da2a0d59f1421f4ed64 Mon Sep 17 00:00:00 2001 From: Lyza Danger Gardner Date: Wed, 17 May 2023 14:28:50 -0400 Subject: [PATCH] Update `Using Components` page --- .../patterns/UsingComponentsPage.tsx | 571 +++++++++--------- 1 file changed, 280 insertions(+), 291 deletions(-) diff --git a/src/pattern-library/components/patterns/UsingComponentsPage.tsx b/src/pattern-library/components/patterns/UsingComponentsPage.tsx index 9fdeff74b..9f765b66c 100644 --- a/src/pattern-library/components/patterns/UsingComponentsPage.tsx +++ b/src/pattern-library/components/patterns/UsingComponentsPage.tsx @@ -1,331 +1,320 @@ -import { - Button, - Card, - CardContent, - EditIcon, - ReplyIcon, - CheckIcon, - ScrollBox, -} from '../../../'; import Library from '../Library'; -import { SampleListElements } from './samples'; export default function UsingComponentsPage() { return ( -

- This package provides several categories of components. Which - category a component belongs to defines its general role and the - kinds of props it takes. -

- - - } - > - - Presentational components have a common props API - and provide some flexibility for customization. Example:{' '} - Button, Link. -

- } - > - -

- Presentational components take these common props - unless documented otherwise: -

- ; -};`} - title="Common presentational-component props" - /> - -

- Presentational components also take HTML attributes{' '} - applicable to their primary element, typically the outermost element - rendered by the component. -

- - - -

- Base components are similar to presentational - components, but apply minimal styling. They are intended for use cases - that require customization flexibility. + This package provides several categories of components. Which category + a component belongs to indicates its general role and common props + API.

+ } + > +

- Example: ButtonBase, LinkBase. + Presentational components{' '} + are the most common type of component. They are composable components + that encapsulate design patterns and UI behavior.

- By default, base components apply some core styling.{' '} - Base styling might include things like basic layout - (e.g. establishing a flex layout), focus rings, - establishing transition properties (but not the property values of the - transitioned properties) or preventing text from wrapping inside a - button. -

-

- However, base styling does not include things like - colors, dimensions (padding, spacing, gaps, margins or sizing), text - styling (size, style, weight, decoration) or borders. -

-

- Alternately, base components can be configured to disable all base - styles. + Examples:{' '} + + Button + + ,{' '} + + Link +

- +

- Base components extend presentational component - props with an optional boolean unstyled prop. When set, - the component will have no styling at all, allowing for complete - customization. + All presentational components provide this API unless documented + otherwise.

- - + + + + preact.ComponentChildren + + + + + + + CSS class(es) that will be appended to the CSS classes applied + to the {"component's"} outermost or most significant element. + This can be used independently or in conjunction with the + Styling API props. + + + string + + + + + + + A Ref applied to the {"component's"} outermost or + most significant element. + + + {'preact.Ref'} + + + + + + + Presentational components accept HTML attributes applicable to + the element type of the {"component's"} outermost or most + significant element. + + + A Link with attributes`} + size="sm" + /> + + + + {'preact.JSX.HTMLAttributes'} + + + + + - -

- Composite components compose and style - presentational components in a particular way to satisfy a use - case and sometimes support more nuanced or advanced behavior. -

-

- Example: ScrollBox, Panel. -

- - } - > - +

- Composite components accept the same common props - as presentational components with the exception of{' '} - classes. + + These props extend the common presentational-component API. They + are new and not supported by all presentational components yet. + See individual component API documentation for details. +

- - - - -

- Simple components are opinionated, simple - components that apply design patterns. They provide minimal, if - any, options for customization. -

-

- Example: Spinner. -

- - } - > - - Simple components only accept component-specific props. - - - -

- Transition components have a common props API to - represent their visibility and allows to hook some callbacks for - when it changes. -

-

- Example: Slider. -

- - } - > -

- Transition components take these common props - unless documented otherwise: + See also the{' '} + + styling guide + {' '} + that details how to use these props to customize components.

- void; -};`} - title="Common transition-component props" - /> - - - - -

- Many components provide stylistic variants. - Variants are mutually exclusive and may affect several different - aspects of styling. -

-

- In contrast, other props like underline or{' '} - size impact a single aspect of styling and may be - combined in various ways. -

- - - - This is content inside of a Card with the - default, raised variant. - - + + + Many presentational components have multiple variants. Variants{' '} + {'"theme"'} a component, affecting such aspects as color, + transitions, shadows, etc. Set to {"'custom'"} to + disable variant styling. + + + {`'custom' | string`} + + + +

This will EXTEND the "secondary" variant styles with a pink background

+ - - - This is content inside of a Card with the{' '} - flat variant. - - - + +

This will REPLACE all theming styles with a pink background

+`} + size="sm" + /> + + -

- size takes size abbreviations (strings) as values and - impacts spacing and padding. Typically, accepted values are{' '} - {"'sm', 'md', 'lg'"}. Components generally inherit - font sizing, unless documented otherwise. -

- - - - - - + + + Many, but not all, presentational components provide multiple + sizes. The size value affects size, padding, + margins, etc. Set to {"'custom'"} to disable + size-related styling. + + + {`'custom' | string`} + + + + This will EXTEND size styling with a top margin + - -

- Boolean props are named for their truthy state. For example,{' '} - ScrollBox has borders by default. Thus the associated - boolean prop to disable them is named borderless (not{' '} - border={'{false}'}). -

- -
- -
    - -
- -
- + + This will REPLACE size styling with a top margin +`} + size="sm" + /> + + - - -

- To aid with in-browser inspecting, all components add a{' '} - data-component and, sometimes, a{' '} - data-composite-component attribute to their outermost - elements. -

- -

- Presentational and simple components set{' '} - data-component only. -

- + + + Set this to disable all styling. This is a {'"master switch"'}{' '} + that will supersede size and variant{' '} + values. Note that some components have core (typically + behavioral) CSS classes that cannot be disabled. + + + boolean + + + false + + + + This will replace all styles with a pink background (only) +`} + size="sm" /> - } - size="sm" - title="Rendered outer div for Card" - /> + + + + + + +

+ Composite components{' '} + compose and style presentational components in a particular way to + satisfy a use case and sometimes support more complex or widget-like + behavior. +

+ +

+ Examples:{' '} + + ScrollBox + + ,{' '} + + Panel + +

- -

- Composite components set data-composite-component. - For example, the outermost element of Panel is both a{' '} - Card (data-component) and a{' '} - Panel (data-composite-component). -

- + + + + Some, but not all, composite components accept{' '} + children. + + + preact.ComponentChildren + + + + + + + + A Ref applied to the {"component's"} outermost or + most significant element. + + + {'preact.Ref'} + + + + + + + + Some, but not all, composite components accept HTML attributes + applicable to the element type of the {"component's"} outermost + or most significant element. + + + A Link with attributes`} + size="sm" /> - } - size="sm" - title="Rendered outer div for Panel" - /> + + + + {'preact.JSX.HTMLAttributes'} + + + + + + + + +

+ Transition components are + components with an in/out transition which can be used standalone or + wrapped by other components. +

+ +

+ Example:{' '} + + Slider + +

+ + + + + Sets the current direction of the component transition. + + + {"'in' | 'out' "} + + + {"'in'"} + + - + + + + + Callback invoked when the {"component's"} transition has + completed. + + + {`(direction: 'in' | 'out') => void`} + + + + + + + +

+ Simple components are + opinionated, simple components that apply design patterns. These + components have a minimal, component-specific API. +

+ + + +

+ + Base components are deprecated. Use the styling API on presentational + components instead. +

+

+ Base components are are + similar to presentational components but allow more styling + flexibility. +

);