@stack-spot/citric-react 0.22.0 → 0.23.0

package/src/components/SelectBox.tsx

@@ -73,65 +73,95 @@ export type BaseSelectBoxProps<T> = RadioProps<T> | CheckboxProps<T>
 
 export type SelectBoxProps<T> = Omit<React.JSX.IntrinsicElements['div'], 'onChange' | 'children'> & BaseSelectBoxProps<T>
 
-function _SelectBox<T>({
-  multiple,
-  name,
-  value,
-  options,
-  onChange,
-  renderLabel = o => ({ title: defaultRenderLabel(o) }),
-  renderKey = defaultRenderKey,
-  isDisabled,
-  className,
-  style,
-  direction,
-  bgLevel,
-  colorPalette,
-  colorScheme,
-  ...props
-}: SelectBoxProps<T>) {
-  const items = useMemo(() => {
-    const valueAsArray = value ? (Array.isArray(value) ? value : [value]) : []
-    const valueKeys = valueAsArray.map(renderKey)
-    return options.map((o) => {
-      const key = renderKey(o)
-      const label = renderLabel(o)
-      return (
-        <CitricComponent key={key} tag="label" component="select-box" className={bgLevel ? `bg-${bgLevel}` : undefined}>
-          <input
-            type={multiple ? 'checkbox' : 'radio'}
-            name={name}
-            value={key}
-            checked={value ? valueKeys.includes(key) : undefined}
-            disabled={isDisabled?.(o)}
-            onChange={onChange ? (e) => {
-              if (multiple) {
-                onChange(e.target.checked ? [...valueAsArray, o] : valueAsArray.filter(v => renderKey(v) !== key)) 
-              } else {
-                onChange(o)
-              }
-            } : undefined}
-          />
-          <div className="option">
-            {label.icon}
-            <p className="title">{label.title}</p>
-            {label.description && <p className="description">{label.description}</p>}
-          </div>
-        </CitricComponent>
-      )
-    })
-  }, [options, value, name, multiple, bgLevel])
-  return (
-    <div
-      data-color-palette={colorPalette}
-      data-color-scheme={colorScheme}
-      className={listToClass([className, direction === 'vertical' ? layout.column : layout.row])}
-      style={{ gap: '5px', ...style }}
-      {...props}
-    >
-      {items}
-    </div>
-  )
-}
-
-export const SelectBox = withRef(_SelectBox)
+/**
+ * This component does exactly the same thing as "CheckboxGroup" and "RadioGroup", but with different visuals and less customization.
+ * 
+ * Each option is rendered as a selectable card. The user can select a single option (radio buttons) or multiple options (checkboxes),
+ * depending on the value of the property "multiple", which is false by default.
+ * 
+ * Use `renderLabel` to determine what to render inside each card. This is not a free react element, it must return an object containing an
+ * icon, a title and a description.
+ * 
+ * @example
+ * 
+ * ```
+ * const options = useMemo(() => [
+ *   { id: 1, image: 'https://images.com/1.png', name: 'Basic plan', price: 59 },
+ *   { id: 2, image: 'https://images.com/2.png', name: 'Gold plan', price: 69 },
+ *   { id: 3, image: 'https://images.com/3.png', name: 'Safira plan', price: 79' },
+ *   { id: 4, image: 'https://images.com/4.png', name: 'Diamond plan', price: 99 },
+ * ], [])
+ * 
+ * return <SelectBox
+ *   options={options}
+ *   renderKey={o => o.id}
+ *   renderLabel={o => ({
+ *     icon: <img src={o.image} />,
+ *     title: o.name,
+ *     description: `$${price.toFixed(2)}`,
+ *   })}
+ * />
+ * ```
+ */
+export const SelectBox = withRef(
+  function SelectBox<T>({
+    multiple,
+    name,
+    value,
+    options,
+    onChange,
+    renderLabel = o => ({ title: defaultRenderLabel(o) }),
+    renderKey = defaultRenderKey,
+    isDisabled,
+    className,
+    style,
+    direction,
+    bgLevel,
+    colorPalette,
+    colorScheme,
+    ...props
+  }: SelectBoxProps<T>) {
+    const items = useMemo(() => {
+      const valueAsArray = value ? (Array.isArray(value) ? value : [value]) : []
+      const valueKeys = valueAsArray.map(renderKey)
+      return options.map((o) => {
+        const key = renderKey(o)
+        const label = renderLabel(o)
+        return (
+          <CitricComponent key={key} tag="label" component="select-box" className={bgLevel ? `bg-${bgLevel}` : undefined}>
+            <input
+              type={multiple ? 'checkbox' : 'radio'}
+              name={name}
+              value={key}
+              checked={value ? valueKeys.includes(key) : undefined}
+              disabled={isDisabled?.(o)}
+              onChange={onChange ? (e) => {
+                if (multiple) {
+                  onChange(e.target.checked ? [...valueAsArray, o] : valueAsArray.filter(v => renderKey(v) !== key)) 
+                } else {
+                  onChange(o)
+                }
+              } : undefined}
+            />
+            <div className="option">
+              {label.icon}
+              <p className="title">{label.title}</p>
+              {label.description && <p className="description">{label.description}</p>}
+            </div>
+          </CitricComponent>
+        )
+      })
+    }, [options, value, name, multiple, bgLevel])
+    return (
+      <div
+        data-color-palette={colorPalette}
+        data-color-scheme={colorScheme}
+        className={listToClass([className, direction === 'vertical' ? layout.column : layout.row])}
+        style={{ gap: '5px', ...style }}
+        {...props}
+      >
+        {items}
+      </div>
+    )
+  },
+)

package/src/components/Skeleton.tsx

@@ -31,6 +31,17 @@ export interface BaseSkeletonProps {
 
 export type SkeletonProps = React.JSX.IntrinsicElements['div'] & BaseSkeletonProps
 
+/**
+ * A loading feedback with a discrete animation. Use this to replace elements on the page that are still loading and will be replaced by
+ * the same shape when the loading ends.
+ * 
+ * Use the property "bgLevel" to manage how light/dark the background is.
+ * 
+ * @example
+ * ```
+ * <Skeleton width="100%" height="20px" />
+ * ```
+ */
 export const Skeleton = withRef(({ appearance, className, style, width, height, bgLevel, ...props }: SkeletonProps) =>
   <CitricComponent
     tag="div"

package/src/components/Slider.tsx

@@ -35,6 +35,18 @@ export interface BaseSliderProps extends WithColorScheme, WithColorPalette {
 
 export type SliderProps =  ControlledInput & BaseSliderProps
 
+/**
+ * A UI element where the user can slide a knob over a bar to select a number. By default, a number between 0 and 100 can be selected, use
+ * the properties "min" and "max" to change this.
+ * 
+ * Attention: "onChange" receives the new value (number) instead of the event.
+ * 
+ * @example
+ * ```
+ * const [value, setValue] = useState(0)
+ * return <Slider value={value} setValue={setValue} />
+ * ```
+ */
 export const Slider = withRef((
   { value, onChange, min, max, style, showValue, renderValue, colorPalette, colorScheme, className, ...props }: SliderProps,
 ) => {

package/src/components/SmartTable.tsx

@@ -89,63 +89,98 @@ export type BaseSmartTableProps<T extends Record<string, any>> = BaseTableProps
 
 export type SmartTableProps<T extends Record<string, any>> = Omit<TableProps, 'children'> & ExtraSmartTableProps<T>
 
-function _SmartTable<T extends Record<string, any>>(
-  { data, keygen, columns, renderAccordion, accordionTrigger, accordionMaxHeight, id, ...props }: SmartTableProps<T>,
-) {
-  id = useMemo(() => id || `${Math.random()}`, [id])
+/**
+ * Renders a table. Always prefer using this component over the raw Table component.
+ * 
+ * This receives a dataset and renders each item as a row. The columns are determined by the property "columns".
+ * 
+ * To change the overall table style, use the property "appearance".
+ * 
+ * To check more complex table examples, like tables with accordions and sorting, check the storybook.
+ * 
+ * @example
+ * 
+ * ```
+ * const data = useMemo(() => [
+ *   { id: 1, name: 'Yuri Tyson', phone: '1-801-475-4561', country: 'Poland', age: 21 },
+ *   { id: 2, name: 'Amal Mcclure', phone: '(695) 948-4102', country: 'Ukraine', age: 32 },
+ *   { id: 3, name: 'Levi Glass', phone: '1-976-544-4872', country: 'Colombia', age: 45 },
+ * ], [])
+ * const columns = useMemo(() => [
+ *   { key: 'name', label: 'Name', render: item => `${item.name} (${item.age})` },
+ *   { key: 'phone', label: 'Phone' },
+ *   { key: 'country', label: 'Country' },
+ *   {
+ *      key: 'settings',
+ *      render: item => (
+ *        <Row gap={2}>
+ *          <IconButton icon="ExternalLink" title="View" />
+ *          <IconButton icon="Pencil" title="Edit" />
+ *          <IconButton icon="Trash" title="Delete" colorScheme="danger" />
+ *        </Row>
+ *      ),
+ *   },
+ * ], [])
+ * return <SmartTable data={data} columns={columns} />
+ * ```
+ */
+export const SmartTable = withRef(
+  function SmartTable<T extends Record<string, any>>(
+    { data, keygen, columns, renderAccordion, accordionTrigger, accordionMaxHeight, id, ...props }: SmartTableProps<T>,
+  ) {
+    id = useMemo(() => id || `${Math.random()}`, [id])
 
-  const headers = useMemo(
-    () => columns.map((c) => (
-      <Th {...c.th} key={c.key} onSort={c.onSort} direction={c.direction} tabIndex={c.onSort ? 0 : undefined}>
-        {c.label ?? c.key}
-      </Th>
-    )),
-    [columns],
-  )
+    const headers = useMemo(
+      () => columns.map((c) => (
+        <Th {...c.th} key={c.key} onSort={c.onSort} direction={c.direction} tabIndex={c.onSort ? 0 : undefined}>
+          {c.label ?? c.key}
+        </Th>
+      )),
+      [columns],
+    )
 
-  const rows = useMemo(
-    () => data.map((item, index) => {
-      const key = keygen ? keygen(item) : index
-      const accordionContent = renderAccordion?.(item)
-      const row = (
-        <Tr key={key} accordionTrigger={accordionContent ? accordionTrigger : undefined}>
-          {columns.map(c => <td {...c.td} key={c.key}>{c.render ? c.render(item) : (item[c.key] || '')}</td>)}
-          {renderAccordion && (
-            <td>
-              {accordionContent && (
-                <input
-                  type="checkbox"
-                  aria-controls={`${id}-${key}`}
-                  onKeyDown={e => e.key === 'Enter' && e.target instanceof HTMLElement && e.target.click()}
-                />
-              )}
-            </td>
-          )}
-        </Tr>
-      )
-      return renderAccordion ? (
-        <tbody key={`${key}-group`}>
-          {row}
-          <Tr id={`${id}-${key}`} accordion accordionMaxHeight={accordionMaxHeight}>
-            <td colSpan={columns.length + 1}><div>{accordionContent}</div></td>
+    const rows = useMemo(
+      () => data.map((item, index) => {
+        const key = keygen ? keygen(item) : index
+        const accordionContent = renderAccordion?.(item)
+        const row = (
+          <Tr key={key} accordionTrigger={accordionContent ? accordionTrigger : undefined}>
+            {columns.map(c => <td {...c.td} key={c.key}>{c.render ? c.render(item) : (item[c.key] || '')}</td>)}
+            {renderAccordion && (
+              <td>
+                {accordionContent && (
+                  <input
+                    type="checkbox"
+                    aria-controls={`${id}-${key}`}
+                    onKeyDown={e => e.key === 'Enter' && e.target instanceof HTMLElement && e.target.click()}
+                  />
+                )}
+              </td>
+            )}
           </Tr>
-        </tbody>
-      ) : row
-    }),
-    [columns, data, !!renderAccordion, accordionTrigger],
-  )
+        )
+        return renderAccordion ? (
+          <tbody key={`${key}-group`}>
+            {row}
+            <Tr id={`${id}-${key}`} accordion accordionMaxHeight={accordionMaxHeight}>
+              <td colSpan={columns.length + 1}><div>{accordionContent}</div></td>
+            </Tr>
+          </tbody>
+        ) : row
+      }),
+      [columns, data, !!renderAccordion, accordionTrigger],
+    )
 
-  return (
-    <Table id={id} accordionRows={!!renderAccordion} {...props}>
-      <thead>
-        <tr>
-          {headers}
-          {renderAccordion && <th></th>}
-        </tr>
-      </thead>
-      {renderAccordion ? rows : <tbody>{rows}</tbody>}
-    </Table>
-  )
-}
-
-export const SmartTable = withRef(_SmartTable)
+    return (
+      <Table id={id} accordionRows={!!renderAccordion} {...props}>
+        <thead>
+          <tr>
+            {headers}
+            {renderAccordion && <th></th>}
+          </tr>
+        </thead>
+        {renderAccordion ? rows : <tbody>{rows}</tbody>}
+      </Table>
+    )
+  },
+)

package/src/components/Stepper.tsx

@@ -65,66 +65,87 @@ function getTabsWithDisabled<Key extends string>(tabs: Tab<Key>[], value: Key |
   return tabs.map((t, i) => ({ ...t, disabled: i > index }))
 }
 
-function _Stepper<Key extends string>(
-  { tabs: initialTabs, controller: ctrl, value, onChange, buttons = true, className, ...props }: StepperProps<Key>,
-) {
-  const controller = useMemo(
-    () => ctrl ?? new TabController<Key>(initialTabs.map(t => t.key), value || initialTabs[0]?.key),
-    [],
-  )
-  const [tabs, setTabs] = useState(getTabsWithDisabled(initialTabs, value))
-  const [selectedIndex, setSelectedIndex] = useState(findSelectedIndex(tabs, controller.getValue()))
-  const t = useTranslate(dictionary)
+/**
+ * A Stepper is a tab view with a different appearance. To control the current tab (step), retrieve the controller by calling
+ * `useTabsController()` from within a tab (step) content.
+ * 
+ * Besides all the properties in "Tabs", the "Stepper" can create a set of "Previous" and "Next" buttons through the property "buttons". By
+ * default, the buttons are rendered, to disable them, pass `buttons = false`.
+ * 
+ * @example
+ * 
+ * ```
+ * const steps: Tab[] = useMemo(() => [
+ *   { key: 'step1', label: 'Step 1', content: <><h1>First step</h1><p>Content of the first step</p></> },
+ *   { key: 'step2', label: 'Step 2', content: <><h1>Second step</h1><p>Content of the second step</p></> },
+ *   { key: 'step3', label: 'Step 3', content: <><h1>Third step</h1><p>Content of the third step</p></> },
+ * ], [])
+ * 
+ * return <Stepper tabs={steps} />
+ * ```
+ */
+export const Stepper = withRef(
+  function Stepper<Key extends string>(
+    { tabs: initialTabs, controller: ctrl, value, onChange, buttons = true, className, ...props }: StepperProps<Key>,
+  ) {
+    const controller = useMemo(
+      () => ctrl ?? new TabController<Key>(initialTabs.map(t => t.key), value || initialTabs[0]?.key),
+      [],
+    )
+    const [tabs, setTabs] = useState(getTabsWithDisabled(initialTabs, value))
+    const [selectedIndex, setSelectedIndex] = useState(findSelectedIndex(tabs, controller.getValue()))
+    const t = useTranslate(dictionary)
 
-  useEffect(() => controller.onChange((v) => {
-    setSelectedIndex(findSelectedIndex(tabs, v))
-  }), [tabs])
+    useEffect(() => controller.onChange((v) => {
+      setSelectedIndex(findSelectedIndex(tabs, v))
+    }), [tabs])
 
-  useEffect(() => controller.onChange((value) => {
-    setTabs(getTabsWithDisabled(initialTabs, value))
-  }), [])
+    useEffect(() => controller.onChange((value) => {
+      setTabs(getTabsWithDisabled(initialTabs, value))
+    }), [])
 
-  const onPrevious = useCallback(() => {
-    controller.previous()
-    if (typeof buttons === 'object') buttons.onPrevious?.(controller.getValue())
-  }, [])
+    const onPrevious = useCallback(() => {
+      controller.previous()
+      if (typeof buttons === 'object') buttons.onPrevious?.(controller.getValue())
+    }, [])
 
-  const onNext = useCallback(() => {
-    controller.next()
-    if (typeof buttons === 'object') buttons.onNext?.(controller.getValue())
-  }, [])
+    const onNext = useCallback(() => {
+      controller.next()
+      if (typeof buttons === 'object') buttons.onNext?.(controller.getValue())
+    }, [])
 
-  return buttons ? (
-    <Column {...props} className={className} gap="20px">
-      <Tabs tabs={tabs} controller={controller} value={value} onChange={onChange} className="stepper" />
-      <Row justifyContent={(typeof buttons !== 'object' || !buttons.onCancel) && selectedIndex === 0 ? 'end' : 'space-between'}>
-        {selectedIndex === 0 && typeof buttons === 'object' && buttons.onCancel && (
-          <Button onClick={buttons.onCancel} colorScheme="inverse" appearance="outlined">{buttons.cancel || t.cancel}</Button>
-        )}
-        {selectedIndex > 0 && buttons && (
-          <Button onClick={onPrevious} colorScheme="inverse" appearance="outlined">
-            {(typeof buttons === 'object' && buttons.previous) || t.previous}
-          </Button>
-        )}
-        {selectedIndex < tabs.length - 1 && buttons && (
-          <Button onClick={onNext}>
-            {(typeof buttons === 'object' && buttons.next) || t.next}
-          </Button>
-        )}
-        {selectedIndex === tabs.length - 1 && typeof buttons === 'object' && buttons.onFinish && (
-          <Button onClick={buttons.onFinish}>{buttons.finish || t.finish}</Button>
-        )}
-      </Row>
-    </Column>
-  ) : <Tabs
-    tabs={tabs}
-    controller={controller}
-    value={value}
-    onChange={onChange}
-    className={listToClass([className, 'stepper'])}
-    {...props}
-  />
-}
+    return buttons ? (
+      <Column {...props} className={className} gap="20px">
+        <Tabs tabs={tabs} controller={controller} value={value} onChange={onChange} className="stepper" />
+        <Row justifyContent={(typeof buttons !== 'object' || !buttons.onCancel) && selectedIndex === 0 ? 'end' : 'space-between'}>
+          {selectedIndex === 0 && typeof buttons === 'object' && buttons.onCancel && (
+            <Button onClick={buttons.onCancel} colorScheme="inverse" appearance="outlined">{buttons.cancel || t.cancel}</Button>
+          )}
+          {selectedIndex > 0 && buttons && (
+            <Button onClick={onPrevious} colorScheme="inverse" appearance="outlined">
+              {(typeof buttons === 'object' && buttons.previous) || t.previous}
+            </Button>
+          )}
+          {selectedIndex < tabs.length - 1 && buttons && (
+            <Button onClick={onNext}>
+              {(typeof buttons === 'object' && buttons.next) || t.next}
+            </Button>
+          )}
+          {selectedIndex === tabs.length - 1 && typeof buttons === 'object' && buttons.onFinish && (
+            <Button onClick={buttons.onFinish}>{buttons.finish || t.finish}</Button>
+          )}
+        </Row>
+      </Column>
+    ) : <Tabs
+      tabs={tabs}
+      controller={controller}
+      value={value}
+      onChange={onChange}
+      className={listToClass([className, 'stepper'])}
+      {...props}
+    />
+  },
+)
 
 const dictionary = {
   en: {
@@ -140,5 +161,3 @@ const dictionary = {
     finish: 'Finalizar',
   },
 } satisfies Dictionary
-
-export const Stepper = withRef(_Stepper)

package/src/components/Table.tsx

@@ -110,6 +110,16 @@ export type TableProps = React.JSX.IntrinsicElements['table'] & BaseTableProps
 export type ThProps = React.JSX.IntrinsicElements['th'] & BaseThProps
 export type TrProps = React.JSX.IntrinsicElements['tr'] & BaseTrProps
 
+/**
+ * Renders an HTML table. Use its props for customizing the appearance.
+ * 
+ * - If you need to use Accordion rows, use `<Tr>`instead of `<tr>`.
+ * - If you need to sort columns, use `<Th>`instead of `<th>`.
+ * 
+ * This works exactly like the HTML tag "table".
+ * 
+ * Attention: prefer using the component "SmartTable". Use this only if you need full control over the table.
+ */
 export const Table = withRef(({
   appearance, stripped, compressed, showBorders, showHeaderBorders, showRowBorders, rounded, roundedRows, uppercaseHeader, className,
   children, accordionRows, ...props

package/src/components/Tabs/TabController.ts

@@ -12,16 +12,26 @@ export class TabController<Key extends string> extends ValueController<Key> {
     return this.tabOrder.findIndex(t => t === this.value)
   }
 
+  /**
+   * @returns true if there's another tab after the one currently selected. False otherwise.
+   */
   hasNext(): boolean {
     const current = this.getCurrentIndex()
     return current > -1 && current + 1 < this.tabOrder.length
   }
 
+  /**
+   * @returns true if there's a tab before the one currently selected. False otherwise.
+   */
   hasPrevious(): boolean {
     const current = this.getCurrentIndex()
     return current > -1 && current - 1 >= 0
   }
 
+  /**
+   * Selects the tab on the right of the one currently selected. If there's no next tab, nothing happens.
+   * @returns true if the tab is changed, false otherwise.
+   */
   next(): boolean {
     if (this.hasNext()) {
       this.setValue(this.tabOrder[this.getCurrentIndex() + 1])
@@ -30,6 +40,10 @@ export class TabController<Key extends string> extends ValueController<Key> {
     return false
   }
 
+  /**
+   * Selects the tab on the left of the one currently selected. If there's no previous tab, nothing happens.
+   * @returns true if the tab is changed, false otherwise.
+   */
   previous(): boolean {
     if (this.hasPrevious()) {
       this.setValue(this.tabOrder[this.getCurrentIndex() - 1])