@stack-spot/citric-react 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stack-spot/citric-react",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "author": "StackSpot",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -15,7 +15,7 @@
     "url": "https://github.com/stack-spot/citric"
   },
   "peerDependencies": {
-    "@stack-spot/citric-icons": ">=0.2.1",
+    "@stack-spot/citric-icons": ">=0.2.2",
     "@stack-spot/portal-theme": ">=1.2.1",
     "@stack-spot/portal-translate": ">=1.2.2",
     "lodash": ">=4.17.21",

package/src/components/Accordion.tsx

@@ -37,6 +37,40 @@ export interface BaseAccordionProps {
 
 export type AccordionProps = Omit<React.JSX.IntrinsicElements['div'], 'onChange'> & BaseAccordionProps
 
+/**
+ * Creates an accordion, showing/hiding the children according to the state of the expand/collapse checkbox.
+ * 
+ * The accordion must define a max height, which is 300 by default (measured in pixels). Whenever the content surpasses "maxHeight", a 
+ * vertical scroll is created. If your content is much shorter than "maxHeight", consider reducing its value for a better animation.
+ * 
+ * @example
+ * A simple accordion, styled like a card:
+ * ```
+ * <Accordion appearance="card" header="This is the title of the accordion" maxHeight={80}>
+ *   <p>This is the content of the accordion</p>
+ * </Accordion>
+ * ```
+ * 
+ * A more complex accordion:
+ * ```
+ * const header = (toggle: React.ReactElement) => (
+ *   <Row justifyContent="space-between" bg="cyan.500" border="cyan.700" radius="sm">
+ *     <ImageBox><img src="/my-image.png" /></ImageBox>
+ *     <Text>Joseph Clinton</Text>
+ *     <Text>40 years old</Text>
+ *     {toggle}
+ *   </Row>
+ * )
+ * return (
+ *   <Accordion header={header}>
+ *     <Center>
+ *       <img src="/an-image.png" />
+ *       <p>This is the content of the accordion</p>
+ *     </Center>
+ *   </Accordion>
+ * )
+ * ```
+ */
 export const Accordion = withRef((
   { id, appearance, expanded, onChange, header, maxHeight = 300, className, style, children, ...props }: AccordionProps,
 ) => {

package/src/components/Alert.tsx

@@ -12,5 +12,13 @@ export interface BaseAlertProps {
 
 export type AlertProps = React.JSX.IntrinsicElements['div'] & BaseAlertProps
 
+/**
+ * Renders an alert message with an icon and a background. This may be an error, warning or a success feedback.
+ * 
+ * @example
+ * ```
+ * <Alert type="warning">My warning!</Alert>
+ * ```
+ */
 export const Alert = withRef(({ type, className, children, ...props }: AlertProps) =>
   <CitricComponent tag="div" component="alert" className={listToClass([type, className])} {...props}>{children}</CitricComponent>)

package/src/components/AsyncContent.tsx

@@ -25,11 +25,25 @@ interface Props {
 }
 
 /**
- * Renders a component that provides user feedback on async requests.
- * It renders either a loading component, an error component (which is received as prop)
- * or the received children props.
+ * Renders a component that provides user feedback on async requests. It renders either a loading component, an error component or its
+ * children.
  * 
- * @param options the props for rendering the component: {@link Props}. 
+ * The loading and error views can be customized through a CitricController.
+ * 
+ * Errors can be watched through the function `onError` of a CitricController.
+ * 
+ * Attention: for React Suspense, use the component "FallbackBoundary" instead.
+ * 
+ * @example
+ * ```
+ * const [data, isLoading, error] = useRemoteData()
+ * 
+ * return (
+ *   <AsyncContent loading={isLoading} error={error}>
+ *     {data}
+ *   </AsyncContent>
+ * )
+ * ```
  */
 
 export const AsyncContent = withRef(({ loading, error, autofocus, children }: Props) => {

package/src/components/Avatar.tsx

@@ -2,6 +2,7 @@ import { listToClass } from '@stack-spot/portal-theme'
 import { WithColorPalette } from '../types'
 import { withRef } from '../utils/react'
 import { CitricComponent } from './CitricComponent'
+import { ImageWithFallback } from './ImageWithFallback'
 
 export interface BaseAvatarProps extends WithColorPalette {
   /**
@@ -24,12 +25,21 @@ export interface BaseAvatarProps extends WithColorPalette {
 
 export type AvatarProps = React.JSX.IntrinsicElements['div'] & BaseAvatarProps
 
+/**
+ * Renders an avatar. If an image is provided it's rendered within the space reserved to the avatar, otherwise, the initial of the names
+ * are used.
+ * 
+ * @example
+ * ```
+ * <Avatar name="Rick Sanchez" />
+ * ```
+ */
 export const Avatar = withRef(({ size, name, appearance, className, image, ...props }: AvatarProps) => {
   const parts = name?.split(' ') ?? ['']
   const acronym = parts.length >= 2 ? `${parts[0][0]}${parts[1][0]}` : parts[0][0]
   return (
     <CitricComponent tag="div" component="avatar" className={listToClass([size, appearance, className])} {...props}>
-      {image ? <img src={image} /> : acronym}
+      <ImageWithFallback src={image} fallback={acronym} />
     </CitricComponent>
   )
 })

package/src/components/AvatarGroup.tsx

@@ -25,6 +25,14 @@ export interface BaseAvatarGroupProps extends WithColorPalette {
 
 export type AvatarGroupProps = React.JSX.IntrinsicElements['div'] & BaseAvatarGroupProps
 
+/**
+ * Stacks a group of avatars horizontally.
+ * 
+ * @example
+ * ```
+ * <AvatarGroup items={[{ name: 'John Smith' }, { name: 'Mary Anne', image: 'https://profile.com/123.png' }]} />
+ * ```
+ */
 export const AvatarGroup = withRef(({ size, items, appearance, maxItems, className, ...props }: AvatarGroupProps) => {
   const avatars = items.map(({ name, image }) => <Avatar key={name} name={name} image={image} />, [items])
   return (

package/src/components/Badge.tsx

@@ -20,12 +20,28 @@ export interface BaseBadgeProps<T extends ValidTags = ValidTags> extends WithCol
 
 export type BadgeProps<T extends ValidTags> = HTMLTag[T] & BaseBadgeProps<T>
 
-function _Badge<T extends ValidTags>({ tag, appearance, className, children, ...props }: BadgeProps<T>) {
-  return (
-    <CitricComponent tag={tag || 'div'} component="badge" className={listToClass([appearance, className])} {...props as any}>
-      {children}
-    </CitricComponent>
-  )
-}
+/**
+ * Renders a badge. Badges have different color grades depending if they're focusable or not. Use `colorPalette` do determine the main
+ * color.
+ * 
+ * @example
+ * ```
+ * <Badge>
+ *   <Icon icon="PlusMini" />
+ *   My first badge
+ * </Badge>
+ * ```
+ */
+export const Badge = withRef(
+  function Badge<T extends ValidTags>({ tag, appearance, className, children, ...props }: BadgeProps<T>) {
+    return (
+      <CitricComponent tag={tag || 'div'} component="badge" className={listToClass([appearance, className])} {...props as any}>
+        {children}
+      </CitricComponent>
+    )
+  },
+)
+
+
+// export const Badge = withRef(_Badge)
 
-export const Badge = withRef(_Badge)

package/src/components/Blockquote.tsx

@@ -6,5 +6,13 @@ export type BaseBlockquoteProps = WithColorScheme & WithColorPalette
 
 export type BlockquoteProps = React.JSX.IntrinsicElements['blockquote'] & BaseBlockquoteProps
 
+/**
+ * Renders a quote.
+ * 
+ * @example
+ * ```
+ * <Blockquote>To be or not to be, that's the question</Blockquote>
+ * ```
+ */
 export const Blockquote = withRef(({ children, ...props }: BlockquoteProps) =>
   <CitricComponent tag="blockquote" component="blockquote" {...props}>{children}</CitricComponent>)

package/src/components/Breadcrumb.tsx

@@ -1,6 +1,7 @@
 import { useMemo } from 'react'
 import { withRef } from '../utils/react'
 import { CitricComponent } from './CitricComponent'
+import { Link } from './Link'
 
 interface BreadCrumbItem {
   label: string,
@@ -13,10 +14,18 @@ export interface BaseBreadcrumbProps {
 
 export type BreadcrumbProps = React.JSX.IntrinsicElements['nav'] & BaseBreadcrumbProps
 
+/**
+ * Renders a simple navigation bar with links to the previous pages.
+ * 
+ * @example
+ * ```
+ * <Breadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Settings', href: '/settings' }, { label: 'Profile' }]} />
+ * ```
+ */
 export const Breadcrumb = withRef(({ items, ...props }: BreadcrumbProps) => {
   const children = useMemo(
     () => items.map(
-      (item, index) => item.href ? <li key={index}><a href={item.href}>{item.label}</a></li> : <li key={index}>{item.label}</li>,
+      (item, index) => item.href ? <li key={index}><Link href={item.href}>{item.label}</Link></li> : <li key={index}>{item.label}</li>,
     ),
     [items],
   )

package/src/components/Button.tsx

@@ -1,5 +1,5 @@
 import { listToClass } from '@stack-spot/portal-theme'
-import { useState } from 'react'
+import { Children, useMemo, useState } from 'react'
 import { useCitricController } from '../context/hooks'
 import { WithColorScheme } from '../types'
 import { withRef } from '../utils/react'
@@ -48,12 +48,27 @@ export interface BaseButtonProps extends WithColorScheme {
 
 export type ButtonProps = Omit<React.JSX.IntrinsicElements['button'], 'onClick'> & BaseButtonProps
 
+/**
+ * Renders a button. The type is "button" by default.
+ * 
+ * Whenever a button is clicked, the function `onClickButton` of the nearest CitricController is called with the event and the value of the
+ * prop `analytics`.
+ * 
+ * @example
+ * ```
+ * <Button>My Button</MyButton>
+ * ```
+ */
 export const Button = withRef((
   { appearance, size, feedback, loading, disabled, onClick, className, children, type = 'button', analytics, ...props }: ButtonProps,
 ) => {
   const citric = useCitricController()
   const [waiting, setWaiting] = useState(false)
   const busy = loading || waiting
+  const isAllLowercase = useMemo(
+    () => !Children.toArray(children).some(c => typeof c === 'string' && c.toLocaleLowerCase() !== c),
+    [children],
+  )
 
   async function handleClick(e: React.MouseEvent<HTMLButtonElement, MouseEvent>) {
     const result = onClick?.(e)
@@ -71,7 +86,7 @@ export const Button = withRef((
     <CitricComponent
       tag="button"
       component="button"
-      className={listToClass([size, appearance, className])}
+      className={listToClass([size, appearance, isAllLowercase && 'short-text', className])}
       data-feedback={feedback || undefined}
       onClick={handleClick}
       aria-busy={busy}

package/src/components/Card.tsx

@@ -3,13 +3,15 @@ import { WithColorScheme } from '../types'
 import { withRef } from '../utils/react'
 import { CitricComponent } from './CitricComponent'
 
-export interface BaseCardProps extends WithColorScheme {
+type SupportedTags = 'div' | 'header' | 'ul' | 'ol' | 'dl' | 'section' | 'article' | 'a' | 'button'
+
+export interface BaseCardProps<T extends SupportedTags = SupportedTags> extends WithColorScheme {
   /**
    * HTML tag to render.
    * 
    * @default 'div'
    */
-  tag?: 'div' | 'header' | 'ul' | 'ol' | 'dl' | 'section' | 'article',
+  tag?: T,
   onClick?: (event: React.MouseEvent<HTMLDivElement>) => void,
   /**
    * The size of the card.
@@ -25,16 +27,34 @@ export interface BaseCardProps extends WithColorScheme {
   bgLevel?: 300 | 400 | 500 | 600, 
 }
 
-export type CardProps = React.JSX.IntrinsicElements['div'] & BaseCardProps
+// applying conditionals to the type in order to increase TS performance. Ideally we'd use React.JSX.IntrinsicElements[T].
+export type CardProps<T extends SupportedTags> = (
+  T extends 'a' ? React.JSX.IntrinsicElements['a'] : (
+    T extends 'button' ? React.JSX.IntrinsicElements['button'] :
+      React.JSX.IntrinsicElements['div'])) & BaseCardProps
 
-export const Card = withRef(({ tag = 'div', onClick, size, bgLevel, className, children, ...props }: CardProps) => (
-  <CitricComponent
-    tag={tag}
-    component="card"
-    onClick={onClick}
-    className={listToClass([onClick && 'clickable', size, bgLevel && `bg-${bgLevel}`, className])}
-    {...props}
-  >
-    {children}
-  </CitricComponent>
-))
+/**
+ * Renders a box with padding, border and background-color. If the card is focusable or has an onClick listener, hover events are also
+ * present.
+ * 
+ * @example
+ * ```
+ * <Card>The card content</Card>
+ * ```
+ */
+export const Card = withRef(
+  function Card<T extends SupportedTags>({ tag = 'div', onClick, size, bgLevel, className, children, ...props }: CardProps<T>) {
+    const clickable = onClick || props.tabIndex === 0 || tag === 'button' || tag === 'a'
+    return (
+      <CitricComponent
+        tag={tag}
+        component="card"
+        onClick={onClick}
+        className={listToClass([clickable && 'clickable', size, bgLevel && `bg-${bgLevel}`, className])}
+        {...props}
+      >
+        {children}
+      </CitricComponent>
+    )
+  },
+)

package/src/components/Checkbox.tsx

@@ -15,6 +15,20 @@ export interface BaseCheckboxProps extends WithColorScheme {
 
 export type CheckboxProps = ControlledInput & BaseCheckboxProps
 
+/**
+ * Renders a simple checkbox. If you want to render multiple checkboxes to control the value of multi-selectable field, prefer using the
+ * component `CheckboxGroup`.
+ * 
+ * Attention: the prop `onChange` receives a boolean (current value) instead of the event.
+ * 
+ * A checkbox can also be a switch! Just change the property "appearance".
+ * 
+ * @example
+ * ```
+ * const [value, setValue] = useState(false)
+ * return <Checkbox value={value} setValue={setValue}>This is the checkbox label</Checkbox>
+ * ```
+ */
 export const Checkbox = withRef((
   { appearance = 'checkbox', value, onChange, colorScheme, children, className, style, ...props }: CheckboxProps,
 ) => {

package/src/components/CheckboxGroup.tsx

@@ -72,43 +72,64 @@ export interface BaseCheckboxGroupProps<T = any> extends WithColorScheme {
 
 export type CheckboxGroupProps<T> = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseCheckboxGroupProps<T>
 
-function _CheckboxGroup<T>({
-  appearance = 'checkbox',
-  name,
-  value = [],
-  options,
-  onChange,
-  renderLabel = defaultRenderLabel,
-  renderKey = defaultRenderKey,
-  renderItem,
-  isDisabled,
-  colorScheme,
-  style,
-  ...props
-}: CheckboxGroupProps<T>) {
-  const items = useMemo(() => {
-    const valueKeys = value.map(renderKey)
-    return options.map((o) => {
-      const key = renderKey(o)
-      const checkbox = <CitricComponent
-        tag="input"
-        component={appearance}
-        type="checkbox"
-        name={name}
-        value={key}
-        checked={value.includes(o) || (!isNil(key) && valueKeys.includes(key))}
-        onChange={(e) => onChange?.(e.target.checked ? [...(value ?? []), o] : (value?.filter(item => item != o) ?? []))}
-        disabled={isDisabled?.(o)}
-      />
-      return renderItem ? renderItem(checkbox, o) : (
-        <CitricComponent tag="label" component={`${appearance}-row`} key={key} colorScheme={colorScheme}>
-          {checkbox}
-          {renderLabel(o)}
-        </CitricComponent>
-      )
-    })
-  }, [options, value, name, colorScheme, appearance])
-  return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
-}
-
-export const CheckboxGroup = withRef(_CheckboxGroup)
+/**
+ * Renders a list of checkbox for multi-selection. One checkbox is rendered for each option.
+ * 
+ * This component can be heavily customized via its properties. Check the storybook for complex examples.
+ * 
+ * Tip: if you need to implement features like "search" and "select all", use the hook `useCheckboxGroupControls`.
+ * 
+ * @example
+ * 
+ * ```
+ * const options = useMemo(() => [
+ *   { id: 1, name: 'Option 1' },
+ *   { id: 2, name: 'Option 2' },
+ *   { id: 3, name: 'Option 3' },
+ * ], [])
+ * 
+ * const [value, setValue] = useState<typeof options>([])
+ * 
+ * return <CheckboxGroup options={options} renderLabel={o => o.name} renderKey={o => o.id} value={value} setValue={setValue} />
+ * ```
+ */
+export const CheckboxGroup = withRef(
+  function CheckboxGroup<T>({
+    appearance = 'checkbox',
+    name,
+    value = [],
+    options,
+    onChange,
+    renderLabel = defaultRenderLabel,
+    renderKey = defaultRenderKey,
+    renderItem,
+    isDisabled,
+    colorScheme,
+    style,
+    ...props
+  }: CheckboxGroupProps<T>) {
+    const items = useMemo(() => {
+      const valueKeys = value.map(renderKey)
+      return options.map((o) => {
+        const key = renderKey(o)
+        const checkbox = <CitricComponent
+          tag="input"
+          component={appearance}
+          type="checkbox"
+          name={name}
+          value={key}
+          checked={value.includes(o) || (!isNil(key) && valueKeys.includes(key))}
+          onChange={(e) => onChange?.(e.target.checked ? [...(value ?? []), o] : (value?.filter(item => item != o) ?? []))}
+          disabled={isDisabled?.(o)}
+        />
+        return renderItem ? renderItem(checkbox, o) : (
+          <CitricComponent tag="label" component={`${appearance}-row`} key={key} colorScheme={colorScheme}>
+            {checkbox}
+            {renderLabel(o)}
+          </CitricComponent>
+        )
+      })
+    }, [options, value, name, colorScheme, appearance])
+    return <Column {...props} style={{ gap: '8px', ...style }}>{items}</Column>
+  },
+)

package/src/components/Circle.tsx

@@ -13,6 +13,14 @@ export interface BaseCircleProps extends WithColorPalette, WithColorScheme {
   /**
    * The size of the circle.
    * 
+   * - xxs: 8px;
+   * - xs: 12px;
+   * - sm: 18px;
+   * - md: 27px;
+   * - lg: 40px;
+   * - xl: 60px;
+   * - xxl: 90px.
+   * 
    * @default 'xs'
    */
   size?: 'xxs' | 'xs' | 'sm' | 'lg' | 'xl' | 'xxl',
@@ -20,6 +28,14 @@ export interface BaseCircleProps extends WithColorPalette, WithColorScheme {
 
 export type CircleProps = React.JSX.IntrinsicElements['div'] & BaseCircleProps
 
+/**
+ * Renders a simple circle. If the circle has any children, it gets cropped by the circle borders. The content of the circle is centered.
+ * 
+ * @example
+ * ```
+ * <Circle colorScheme="success" />
+ * ```
+ */
 export const Circle = withRef(({ showBorders, className, size, children, ...props }: CircleProps) => (
   <CitricComponent tag="div" component="circle" className={listToClass([className, showBorders && 'bordered', size])} {...props}>
     {children}

package/src/components/CitricComponent.ts

@@ -24,6 +24,20 @@ export function asCitricProps({ colorScheme, colorPalette, component, ...props }
   return citricProps
 }
 
+/**
+ * Renders any tag or component with the appearance of a Citric Component.
+ * 
+ * @example
+ * An anchor that looks like a card.
+ * ```
+ * <CitricComponent tag="a" component="card" href="https://www.google.com" target="_blank">This is a card link</CitricComponent>
+ * ```
+ * 
+ * Suppose we have a component called "MyComponent" that accepts the property "myProp". We can make it look like a citric component:
+ * ```
+ * <CitricComponent render={MyComponent} component="card" myProp="my value" />
+ * ```
+ */
 // eslint-disable-next-line react/display-name
 export const CitricComponent: CitricComponentType = forwardRef<any, any>(
   (props, ref) => {

package/src/components/Divider.tsx

@@ -16,8 +16,9 @@ export interface BaseDividerProps extends WithColorScheme {
 
 export type DividerProps = React.JSX.IntrinsicElements['hr'] & BaseDividerProps
 
-export const Divider = withRef(({ size, direction, className, children, ...props }: DividerProps) => (
-  <CitricComponent tag="hr" component="divider" className={listToClass([className, size, direction])} {...props}>
-    {children}
-  </CitricComponent>
-))
+/**
+ * Renders a divider (hr). "size" determines how thick the ruler is and "direction" places it on the vertical or horizontal axis.
+ */
+export const Divider = withRef(({ size, direction, className, ...props }: DividerProps) =>
+  <CitricComponent tag="hr" component="divider" className={listToClass([className, size, direction])} {...props} />,
+)

package/src/components/ErrorBoundary.tsx

@@ -18,6 +18,19 @@ interface Props {
 
 /**
  * An Error Boundary that renders an error feedback instead of its content if any of its children throws.
+ * 
+ * You can customize the appearance of the error through the function `renderError` of a CitricController.
+ * 
+ * Errors can be watched through the function `onError` of a CitricController.
+ * 
+ * Attention: if you're using React Suspense, consider using the component "FallbackBoundary" instead.
+ * 
+ * @example
+ * ```
+ * <ErrorBoundary>
+ *   {content}
+ * </ErrorBoundary>
+ * ```
  */
 export class ErrorBoundary extends Component<Props, State> {
   static contextType = CitricContext

package/src/components/ErrorMessage.tsx

@@ -6,6 +6,6 @@ import { Text } from './Text'
 export const ErrorMessage = ({ error }: { error: any }) => (
   <Row gap="18px" p="20px" justifyContent="center">
     <Icon icon="TimesCircle" size="xl" style={{ color: theme.color.danger[500] }} />
-    <Text style={{ margin: '80px' }}>{error.message || `${error}`}</Text>
+    <Text>{error.message || `${error}`}</Text>
   </Row>
 )

package/src/components/FallbackBoundary.tsx

@@ -18,7 +18,18 @@ const loading = (
 )
 
 /**
- * Fallbacks for errors and loadings (suspense).
+ * A Boundary that renders an error feedback if a child throws an error or a loading feedback if it suspends.
+ * 
+ * You can customize the appearance of the loading and error views through a CitricController.
+ * 
+ * Errors can be watched through the function `onError` of a CitricController.
+ * 
+ * @example
+ * ```
+ * <FallbackBoundary>
+ *   {content}
+ * </FallbackBoundary>
+ * ```
  */
 export const FallbackBoundary = ({ children, message }: Props) => (
   <ErrorBoundary message={message}>

package/src/components/Favorite.tsx

@@ -30,6 +30,18 @@ export interface BaseFavoriteProps {
 
 export type FavoriteProps = Omit<ControlledInput, 'size'> & BaseFavoriteProps
 
+/**
+ * Renders a checkbox with the appearance of a favorite button. If unchecked, the stroke of a star is rendered, when checked, a filled
+ * yellow star is rendered.
+ * 
+ * You can also set a loading state to indicate the component is busy.
+ * 
+ * @example
+ * ```
+ * const { isFavorite, setFavorite, isLoading } = useRemoteFavoriteStatus()
+ * return <Favorite value={isFavorite} onChange={setFavorite} loading={isLoading} />
+ * ``` 
+ */
 export const Favorite = withRef(({ value, size, appearance, onChange, loading, disabled, className, ...props }: FavoriteProps) =>
   <CitricComponent
     tag="input"

package/src/components/FieldGroup.tsx

@@ -21,6 +21,19 @@ export interface BaseFieldGroupProps {
 
 export type FieldGroupProps = React.JSX.IntrinsicElements['div'] & BaseFieldGroupProps
 
+/**
+ * A FieldGroup is used to concatenate an input with other UI elements, like icons and buttons.
+ * 
+ * @example
+ * A search field, with a search icon and a button to submit the search.
+ * ```
+ * <FieldGroup>
+ *   <Icon icon="Search" />
+ *   <Input type="search" />
+ *   <Button colorScheme="light">Submit</Button>
+ * </FieldGroup>
+ * ```
+ */
 export const FieldGroup = withRef(({ auto = true, fullWidth, className, children, ...props }: FieldGroupProps) => (
   <CitricComponent
     tag="div"