@stack-spot/citric-react 0.38.0 → 0.39.0

package/src/components/Card.tsx

@@ -1,68 +1,68 @@
-import { listToClass } from '@stack-spot/portal-theme'
-import { useCitricController } from '../context/hooks'
-import { WithColorScheme, WithStyleShortcuts } from '../types'
-import { applyStyles } from '../utils/css'
-import { withRef } from '../utils/react'
-import { asCitricProps, CitricComponent } from './CitricComponent'
-
-type SupportedTags = 'div' | 'header' | 'ul' | 'ol' | 'dl' | 'section' | 'article' | 'a' | 'button' | 'header'
-
-export interface BaseCardProps<T extends SupportedTags = SupportedTags> extends WithColorScheme, Omit<WithStyleShortcuts, 'bg'> {
-  /**
-   * HTML tag to render.
-   * 
-   * @default 'div'
-   */
-  tag?: T,
-  onClick?: (event: React.MouseEvent<HTMLDivElement>) => void,
-  /**
-   * The size of the card.
-   * 
-   * @default 'md'
-   */
-  size?: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl',
-  /**
-   * The background color level. The main color will depend on the "colorScheme", which is "light" by default.
-   * 
-   * @default 300
-   */
-  bgLevel?: 300 | 400 | 500 | 600,
-  /**
-   * The direction of the items in the card.
-   * 
-   * @default column
-   */
-  direction?: 'column' | 'row',
-}
-
-// 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
-
-/**
- * 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, direction, ...props }: CardProps<T>) {
-    const citric = useCitricController()
-    const clickable = onClick || props.tabIndex === 0 || tag === 'button' || tag === 'a'
-    const componentProps = {
-      tag,
-      component: 'card',
-      onClick,
-      className: listToClass([clickable && 'clickable', size, bgLevel && `bg-${bgLevel}`, direction, className]),
-      ...applyStyles(props),
-    } as const
-    return tag === 'a' && citric?.renderLink
-      ? citric.renderLink(asCitricProps(componentProps))
-      : <CitricComponent {...componentProps}>{children}</CitricComponent>
-  },
-)
+import { listToClass } from '@stack-spot/portal-theme'
+import { useCitricController } from '../context/hooks'
+import { WithColorScheme, WithStyleShortcuts } from '../types'
+import { applyStyles } from '../utils/css'
+import { withRef } from '../utils/react'
+import { asCitricProps, CitricComponent } from './CitricComponent'
+
+type SupportedTags = 'div' | 'header' | 'ul' | 'ol' | 'dl' | 'section' | 'article' | 'a' | 'button' | 'header'
+
+export interface BaseCardProps<T extends SupportedTags = SupportedTags> extends WithColorScheme, Omit<WithStyleShortcuts, 'bg'> {
+  /**
+   * HTML tag to render.
+   * 
+   * @default 'div'
+   */
+  tag?: T,
+  onClick?: (event: React.MouseEvent<HTMLDivElement>) => void,
+  /**
+   * The size of the card.
+   * 
+   * @default 'md'
+   */
+  size?: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl',
+  /**
+   * The background color level. The main color will depend on the "colorScheme", which is "light" by default.
+   * 
+   * @default 300
+   */
+  bgLevel?: 300 | 400 | 500 | 600,
+  /**
+   * The direction of the items in the card.
+   * 
+   * @default column
+   */
+  direction?: 'column' | 'row',
+}
+
+// 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
+
+/**
+ * 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, direction, ...props }: CardProps<T>) {
+    const citric = useCitricController()
+    const clickable = onClick || props.tabIndex === 0 || tag === 'button' || tag === 'a'
+    const componentProps = {
+      tag,
+      component: 'card',
+      onClick,
+      className: listToClass([clickable && 'clickable', size, bgLevel && `bg-${bgLevel}`, direction, className]),
+      ...applyStyles(props),
+    } as const
+    return tag === 'a' && citric?.renderLink
+      ? citric.renderLink(asCitricProps(componentProps))
+      : <CitricComponent {...componentProps}>{children}</CitricComponent>
+  },
+)

package/src/components/Checkbox.tsx

@@ -1,51 +1,51 @@
-import { ControlledInput, WithColorScheme } from '../types'
-import { withRef } from '../utils/react'
-import { CitricComponent } from './CitricComponent'
-
-export interface BaseCheckboxProps extends WithColorScheme {
-  /**
-   * "checkbox" for common check boxes, "switch" for toggles.
-   * @default 'checkbox' 
-   */
-  appearance?: 'checkbox' | 'switch',
-  value?: boolean,
-  onChange?: (value: boolean) => void,
-  children?: React.ReactNode,
-}
-
-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,
-) => {
-  const handleChange = onChange ? () => onChange(!value) : undefined
-  return children ? (
-    <CitricComponent tag="label" component={`${appearance}-row`} colorScheme={colorScheme} style={style} className={className}>
-      <input type="checkbox" checked={value} onChange={handleChange} {...props} />
-      {children}
-    </CitricComponent>
-  ) : <CitricComponent
-    tag="input"
-    type="checkbox"
-    component={appearance}
-    checked={value}
-    onChange={handleChange}
-    className={className}
-    style={style}
-    {...props}
-  />
-})
+import { ControlledInput, WithColorScheme } from '../types'
+import { withRef } from '../utils/react'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseCheckboxProps extends WithColorScheme {
+  /**
+   * "checkbox" for common check boxes, "switch" for toggles.
+   * @default 'checkbox' 
+   */
+  appearance?: 'checkbox' | 'switch',
+  value?: boolean,
+  onChange?: (value: boolean) => void,
+  children?: React.ReactNode,
+}
+
+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,
+) => {
+  const handleChange = onChange ? () => onChange(!value) : undefined
+  return children ? (
+    <CitricComponent tag="label" component={`${appearance}-row`} colorScheme={colorScheme} style={style} className={className}>
+      <input type="checkbox" checked={value} onChange={handleChange} {...props} />
+      {children}
+    </CitricComponent>
+  ) : <CitricComponent
+    tag="input"
+    type="checkbox"
+    component={appearance}
+    checked={value}
+    onChange={handleChange}
+    className={className}
+    style={style}
+    {...props}
+  />
+})

package/src/components/CheckboxGroup.tsx

@@ -1,152 +1,153 @@
-import { isNil } from 'lodash'
-import { useMemo } from 'react'
-import { WithColorScheme } from '../types'
-import { defaultRenderKey, defaultRenderLabel } from '../utils/options'
-import { withRef } from '../utils/react'
-import { CitricComponent } from './CitricComponent'
-import { Column } from './layout'
-
-export interface BaseCheckboxGroupProps<T = any> extends WithColorScheme {
-  /**
-   * "checkbox" for common check boxes, "switch" for toggles.
-   * @default 'checkbox'
-   */
-  appearance?: 'checkbox' | 'switch',
-  /**
-   * The field name.
-   */
-  name?: string,
-  /**
-   * All items corresponding to the selected checkboxes.
-   */
-  value: T[],
-  /**
-   * All the items (checkboxes) to render.
-   */
-  options: T[],
-  /**
-   * Called whenever the selected checkboxes changes.
-   * @param value the currently selected items.
-   */
-  onChange: (value: T[]) => void,
-  /**
-   * A function to render the item label.
-   * 
-   * Attention: ignored if `renderItem` is set.
-   * 
-   * @example
-   * `(option) => option.name`
-   * @default "the item's toString() result."
-   * @param option the item to render.
-   * @returns a React Node to render.
-   */
-  renderLabel?: (option: T) => React.ReactNode,
-  /**
-   * A function to render the item with the checkbox. When set, `renderLabel` is ignored.
-   * @example
-   * ```
-   * (checkbox, option) => <label>{checkbox} {option.name}</label>
-   * ```
-   * @param checkbox the checkbox.
-   * @param option the current item.
-   * @returns a React Node to render.
-   */
-  renderItem?: (checkbox: React.ReactElement, option: T) => React.ReactNode,
-  /**
-   * A function to render the item value, a unique identifier for the option.
-   * @example
-   * `(option) => option.id`
-   * @default "if the item is a string or a number, the stringified item. Otherwise, undefined."
-   * @param option the item to compute a key for.
-   * @returns a string key.
-   */
-  renderKey?: (option: T) => string | number | undefined,
-  /**
-   * If this function returns true for the item, this option is disabled.
-   * @default "nothing is disabled"
-   * @param option the item to calculate "disabled" for.
-   * @returns true if the item should be disabled, false otherwise.
-   */
-  isDisabled?: (option: T) => boolean,
-  /**
-   * The space between options.
-   * 
-   * @default "8px"
-   */
-  gap?: string,
-  /**
-   * If set to false, the checkboxes will have tabIndex = -1.
-   * 
-   * @default true
-   */
-  focusable?: boolean,
-}
-
-export type CheckboxGroupProps<T> = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseCheckboxGroupProps<T>
-
-/**
- * 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`.
- * 
- * Tip: If you need a checkbox group that doesn't occupy much height, consider using a MultiSelect.
- * 
- * @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,
-    gap = '8px',
-    focusable = true,
-    ...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)}
-          tabIndex={focusable ? undefined : -1}
-        />
-        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, ...style }}>{items}</Column>
-  },
-)
+import { isNil } from 'lodash'
+import { useMemo } from 'react'
+import { WithColorScheme } from '../types'
+import { defaultRenderKey, defaultRenderLabel } from '../utils/options'
+import { withRef } from '../utils/react'
+import { CitricComponent } from './CitricComponent'
+import { Column } from './layout'
+
+export interface BaseCheckboxGroupProps<T = any> extends WithColorScheme {
+  /**
+   * "checkbox" for common check boxes, "switch" for toggles.
+   * @default 'checkbox'
+   */
+  appearance?: 'checkbox' | 'switch',
+  /**
+   * The field name.
+   */
+  name?: string,
+  /**
+   * All items corresponding to the selected checkboxes.
+   */
+  value: T[],
+  /**
+   * All the items (checkboxes) to render.
+   */
+  options: T[],
+  /**
+   * Called whenever the selected checkboxes changes.
+   * @param value the currently selected items.
+   */
+  onChange: (value: T[]) => void,
+  /**
+   * A function to render the item label.
+   * 
+   * Attention: ignored if `renderItem` is set.
+   * 
+   * @example
+   * `(option) => option.name`
+   * @default "the item's toString() result."
+   * @param option the item to render.
+   * @returns a React Node to render.
+   */
+  renderLabel?: (option: T) => React.ReactNode,
+  /**
+   * A function to render the item with the checkbox. When set, `renderLabel` is ignored.
+   * @example
+   * ```
+   * (checkbox, option) => <label>{checkbox} {option.name}</label>
+   * ```
+   * @param checkbox the checkbox.
+   * @param option the current item.
+   * @returns a React Node to render.
+   */
+  renderItem?: (checkbox: React.ReactElement, option: T) => React.ReactNode,
+  /**
+   * A function to render the item value, a unique identifier for the option.
+   * @example
+   * `(option) => option.id`
+   * @default "if the item is a string or a number, the stringified item. Otherwise, undefined."
+   * @param option the item to compute a key for.
+   * @returns a string key.
+   */
+  renderKey?: (option: T) => string | number | undefined,
+  /**
+   * If this function returns true for the item, this option is disabled.
+   * @default "nothing is disabled"
+   * @param option the item to calculate "disabled" for.
+   * @returns true if the item should be disabled, false otherwise.
+   */
+  isDisabled?: (option: T) => boolean,
+  /**
+   * The space between options.
+   * 
+   * @default "8px"
+   */
+  gap?: string,
+  /**
+   * If set to false, the checkboxes will have tabIndex = -1.
+   * 
+   * @default true
+   */
+  focusable?: boolean,
+}
+
+export type CheckboxGroupProps<T> = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseCheckboxGroupProps<T>
+
+/**
+ * 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`.
+ * 
+ * Tip: If you need a checkbox group that doesn't occupy much height, consider using a MultiSelect.
+ * 
+ * @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,
+    gap = '8px',
+    focusable = true,
+    ...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)}
+          tabIndex={focusable ? undefined : -1}
+          colorScheme={colorScheme}
+        />
+        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, ...style }}>{items}</Column>
+  },
+)

package/src/components/Circle.tsx

@@ -1,43 +1,43 @@
-import { listToClass } from '@stack-spot/portal-theme'
-import { WithColorPalette, WithColorScheme } from '../types'
-import { withRef } from '../utils/react'
-import { CitricComponent } from './CitricComponent'
-
-export interface BaseCircleProps extends WithColorPalette, WithColorScheme {
-  /**
-   * Whether or not to show borders.
-   * 
-   * @default false
-   */
-  showBorders?: boolean,
-  /**
-   * 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',
-}
-
-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}
-  </CitricComponent>
-))
+import { listToClass } from '@stack-spot/portal-theme'
+import { WithColorPalette, WithColorScheme } from '../types'
+import { withRef } from '../utils/react'
+import { CitricComponent } from './CitricComponent'
+
+export interface BaseCircleProps extends WithColorPalette, WithColorScheme {
+  /**
+   * Whether or not to show borders.
+   * 
+   * @default false
+   */
+  showBorders?: boolean,
+  /**
+   * 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',
+}
+
+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}
+  </CitricComponent>
+))