@stack-spot/citric-react 0.22.0 → 0.23.0

package/src/components/Tabs/index.tsx

@@ -12,46 +12,67 @@ import { findSelectedIndex } from './utils'
 
 const ctx = createContext<TabController<any> | undefined>(undefined)
 
-function _Tabs<Key extends string>({ tabs, value, equallySized, onChange, controller: ctrl, className, ...props }: TabsProps<Key>) {
-  const controller = useMemo(() => ctrl ?? new TabController<Key>(tabs.map(t => t.key), value || tabs[0]?.key), [])
-  const t = useTranslate(dictionary)
-  const [selectedIndex, setSelectedIndex] = useState(findSelectedIndex(tabs, controller.getValue()))
+/**
+ * Builds a Tab selector. The content of a tab is a React component and it can suspend, i.e. tabs can be asynchronously loaded.
+ * 
+ * @example
+ * 
+ * ```
+ * const tabs: Tab[] = useMemo(() => [
+ *   { key: 'tab1', label: 'Tab 1', content: <><h1>First tab</h1><p>Content of the first tab</p></> },
+ *   { key: 'tab2', label: 'Tab 2', content: <><h1>Second tab</h1><p>Content of the second tab</p></> },
+ *   { key: 'tab3', label: 'Tab 3', content: <><h1>Third tab</h1><p>Content of the third tab</p></> },
+ * ], [])
+ * 
+ * return <Tabs tabs={tabs} />
+ * ```
+ */
+export const Tabs = withRef(
+  function Tabs<Key extends string>({ tabs, value, equallySized, onChange, controller: ctrl, className, ...props }: TabsProps<Key>) {
+    const controller = useMemo(() => ctrl ?? new TabController<Key>(tabs.map(t => t.key), value || tabs[0]?.key), [])
+    const t = useTranslate(dictionary)
+    const [selectedIndex, setSelectedIndex] = useState(findSelectedIndex(tabs, controller.getValue()))
 
-  useEffect(() => {
-    if (value) controller.setValue(value)
-  }, [value])
+    useEffect(() => {
+      if (value) controller.setValue(value)
+    }, [value])
 
-  useEffect(() => controller.onChange((v) => {
-    setSelectedIndex(findSelectedIndex(tabs, v))
-    onChange?.(v)
-  }), [tabs])
+    useEffect(() => controller.onChange((v) => {
+      setSelectedIndex(findSelectedIndex(tabs, v))
+      onChange?.(v)
+    }), [tabs])
 
-  const nav = useMemo(
-    () => tabs.map(({ key, label, disabled }, index) => (
-      <label key={key}>
-        <input type="radio" role="tab" checked={index === selectedIndex} onChange={() => controller.setValue(key)} disabled={disabled} />
-        {label || key}
-      </label>
-    )),
-    [tabs, selectedIndex],
-  )
+    const nav = useMemo(
+      () => tabs.map(({ key, label, disabled }, index) => (
+        <label key={key}>
+          <input type="radio" role="tab" checked={index === selectedIndex} onChange={() => controller.setValue(key)} disabled={disabled} />
+          {label || key}
+        </label>
+      )),
+      [tabs, selectedIndex],
+    )
 
-  return (
-    <ctx.Provider value={controller}>
-      <CitricComponent tag="div" component="tabs" className={listToClass([className, equallySized && 'equally-sized'])} {...props}>
-        <nav>{nav}</nav>
-        <section>
-          <ErrorBoundary key={selectedIndex} message={t.error}>
-            <Suspense fallback={<Center style={{ padding: '20px' }}><ProgressCircular /></Center>}>
-              {selectedIndex === -1 ? null : tabs[selectedIndex]?.content}
-            </Suspense>
-          </ErrorBoundary>
-        </section>
-      </CitricComponent>
-    </ctx.Provider>
-  )
-}
+    return (
+      <ctx.Provider value={controller}>
+        <CitricComponent tag="div" component="tabs" className={listToClass([className, equallySized && 'equally-sized'])} {...props}>
+          <nav>{nav}</nav>
+          <section>
+            <ErrorBoundary key={selectedIndex} message={t.error}>
+              <Suspense fallback={<Center style={{ padding: '20px' }}><ProgressCircular /></Center>}>
+                {selectedIndex === -1 ? null : tabs[selectedIndex]?.content}
+              </Suspense>
+            </ErrorBoundary>
+          </section>
+        </CitricComponent>
+      </ctx.Provider>
+    )
+  },
+)
 
+/**
+ * Request the tab controller of the current context. Use this to control the tabs in the parent components. This returns undefined when
+ * no tab context is found.
+ */
 export function useTabController<Key extends string = string>(): TabController<Key> | undefined {
   return useContext(ctx)
 }
@@ -64,5 +85,3 @@ const dictionary = {
     error: 'Ocorreu um erro ao carregar a aba.',
   },
 } satisfies Dictionary
-
-export const Tabs = withRef(_Tabs)

package/src/components/Text.ts

@@ -73,24 +73,39 @@ const appearanceToTag: Record<TextAppearance, SupportedTags> = {
   subtitle4: 'p',
 }
 
-function _Text<T extends SupportedTags>(
-  { tag, appearance, color, showMargins, weight, align, nowrapEllipsis, style, className, children, ...props }: TextProps<T>,
-) {
-  const renderedTag = tag || appearanceToTag[appearance || 'body2']
-  const renderedAppearance = appearance || (tag ? tagToAppearance[tag] : undefined)
-  if (!appearance && !showMargins) style = { margin: 0, ...style }
-  if (weight) style = { fontWeight: weight, ...style }
-  if (align) style = { textAlign: align, ...style }
-  if (nowrapEllipsis) style = { whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', ...style }
-  return createElement(
-    renderedTag,
-    {
-      className: applyTextAppearance(listToClass([className, showMargins && 'text-with-margins']), renderedAppearance),
-      style: applyColor(style, color),
-      ...props,
-    },
-    children,
-  )
-}
-
-export const Text = withRef(_Text)
+/**
+ * Renders a text. The tag can be set by the property "tag". If unset, the tag rendered will be based on the property "appearance". If
+ * "appearance" is also unset, the tag "p" is rendered.
+ * 
+ * Texts have no margin by default, to enable margins, use `showMargins = true`.
+ * 
+ * If the appearance is not set, it will be inherited from the parent.
+ * 
+ * A font can be applied to a text without this component, just use `{ font: theme.font.$textAppearance }` in your style.
+ * 
+ * @example
+ * ```
+ * <Text appearance="body2">Hello World!</Text>
+ * ```
+ */
+export const Text = withRef(
+  function Text<T extends SupportedTags>(
+    { tag, appearance, color, showMargins, weight, align, nowrapEllipsis, style, className, children, ...props }: TextProps<T>,
+  ) {
+    const renderedTag = tag || appearanceToTag[appearance || 'body2']
+    const renderedAppearance = appearance || (tag ? tagToAppearance[tag] : undefined)
+    if (!appearance && !showMargins) style = { margin: 0, ...style }
+    if (weight) style = { fontWeight: weight, ...style }
+    if (align) style = { textAlign: align, ...style }
+    if (nowrapEllipsis) style = { whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', ...style }
+    return createElement(
+      renderedTag,
+      {
+        className: applyTextAppearance(listToClass([className, showMargins && 'text-with-margins']), renderedAppearance),
+        style: applyColor(style, color),
+        ...props,
+      },
+      children,
+    )
+  },
+)

package/src/components/Textarea.tsx

@@ -11,7 +11,17 @@ export interface BaseTextareaProps extends WithColorScheme {
 
 export type TextareaProps = ControlledTextarea & BaseTextareaProps
 
-export const _Textarea = ({ value, onChange, ...props }: TextareaProps) =>
-  <CitricComponent tag="textarea" component="textarea" value={value} onChange={e => onChange?.(e.target.value)} {...props} />
-
-export const Textarea = withRef(_Textarea)
+/**
+ * Renders a textarea HTML element. With the difference that the value is not determined by the children, but the property "value" instead.
+ * 
+ * Attention: "onChange" receives the new value, not the event.
+ * 
+ * @example
+ * ```
+ * const [value, setValue] = useState('')
+ * return <Textarea value={value} onChange={setValue} />
+ * ```
+ */
+export const Textarea = withRef(({ value, onChange, ...props }: TextareaProps) =>
+  <CitricComponent tag="textarea" component="textarea" value={value} onChange={e => onChange?.(e.target.value)} {...props} />,
+)

package/src/components/Tooltip.tsx

@@ -32,8 +32,21 @@ export interface BaseTooltipProps extends
   disabled?: boolean,
 }
 
-export type TooltipProps = React.JSX.IntrinsicElements['div'] & BaseTooltipProps
+export type TooltipProps = Omit<React.JSX.IntrinsicElements['div'], 'content'> & BaseTooltipProps
 
+/**
+ * Renders a tooltip overlay for its child. By default, the tooltip is rendered on hover, but this can be changed through the property
+ * "triggerOn".
+ * 
+ * The content of the tooltip can be any React element.
+ * 
+ * @example
+ * ```
+ * <Tooltip content="This is some help for you">
+ *   <IconButton icon="Question" />
+ * </Tooltip>
+ * ```
+ */
 export const Tooltip = (
   { tooltipId, children, showArrow = true, compact = true, attributes, colorScheme, colorPalette, disabled, ...props }: TooltipProps,
 ) => {

package/src/components/layout.tsx

@@ -41,18 +41,61 @@ export type CenterProps<T extends keyof HTMLTag> = HTMLTag[T] & BaseLayoutProps<
 export type RowProps<T extends keyof HTMLTag> = HTMLTag[T] & BaseRowProps<T>
 export type ColumnProps<T extends keyof HTMLTag> = HTMLTag[T] & BaseColumnProps<T>
 
-function _Center<T extends keyof HTMLTag = 'div'>({ tag, className, ...props }: CenterProps<T>) {
-  return createElement(tag || 'div', { className: listToClass(['center', className]), ...applyStyles(props) })
-}
-
-function _Row<T extends keyof HTMLTag = 'div'>({ tag, className, center, ...props }: RowProps<T>) {
-  return createElement(tag || 'div', { className: listToClass(['row', center === false && 'no-center', className]), ...applyStyles(props) })
-}
+/**
+ * Centers the content both vertically and horizontally. Elements are placed in a column (flex).
+ * 
+ * This element accepts many style shortcuts as attributes: bg, fg, border, radius, justifyContent, alignItems, flex, gap, m, mt, mb, ml,
+ * mr, p, pt, pb, pl, pr, w, h.
+ * 
+ * @example
+ * ```
+ * <Center w="200px" h="200px" gap="10px">
+ *   <img src="/an-image.png" />
+ *   <Text>This content is centered!</Text>
+ * </Center>
+ * ```
+ */
+export const Center = withRef(
+  function Center<T extends keyof HTMLTag = 'div'>({ tag, className, ...props }: CenterProps<T>) {
+    return createElement(tag || 'div', { className: listToClass(['center', className]), ...applyStyles(props) })
+  },
+)
 
-function _Column<T extends keyof HTMLTag = 'div'>({ tag, className, center, ...props }: ColumnProps<T>) {
-  return createElement(tag || 'div', { className: listToClass(['column', center && 'center', className]), ...applyStyles(props) })
-}
+/**
+ * Creates a row (flex). The elements in this row are horizontally centered unless `center = false`.
+ * 
+ * @example
+ * ```
+ * <Row gap={3}>
+ *   <Icon icon="Stack" />
+ *   <Text>Stacks</Text>
+ * </Row>
+ * ```
+ */
+export const Row = withRef(
+  function Row<T extends keyof HTMLTag = 'div'>({ tag, className, center, ...props }: RowProps<T>) {
+    return createElement(
+      tag || 'div',
+      { className: listToClass(['row', center === false && 'no-center', className]), ...applyStyles(props) },
+    )
+  },
+)
 
-export const Center = withRef(_Center)
-export const Row = withRef(_Row)
-export const Column = withRef(_Column)
+/**
+ * Creates a column (flex). The elements in this row are placed at the start of the horizontal axis, unless `center = true`, in this case,
+ * they're centered.
+ * 
+ * @example
+ * ```
+ * <Column gap={5}>
+ *   <Text>Item 1</Text>
+ *   <Text>Item 2</Text>
+ *   <Text>Item 3</Text>
+ * </Row>
+ * ```
+ */
+export const Column = withRef(
+  function Column<T extends keyof HTMLTag = 'div'>({ tag, className, center, ...props }: ColumnProps<T>) {
+    return createElement(tag || 'div', { className: listToClass(['column', center && 'center', className]), ...applyStyles(props) })
+  },
+)

package/src/index.ts

@@ -40,7 +40,6 @@ export * from './components/Skeleton'
 export * from './components/Slider'
 export * from './components/SmartTable'
 export * from './components/Stepper'
-export * from './components/Switch'
 export * from './components/Table'
 export * from './components/Tabs'
 export * from './components/Tabs/TabController'

package/dist/components/Switch.d.ts

@@ -1,10 +0,0 @@
-import { ControlledInput, WithColorScheme } from '../types.js';
-interface Props extends WithColorScheme {
-    value?: boolean;
-    onChange?: (value: boolean) => void;
-    children?: React.ReactNode;
-}
-export type SwitchProps = ControlledInput & Props;
-export declare const Switch: ({ value, onChange, children, className, style, ...props }: SwitchProps) => import("react/jsx-runtime").JSX.Element;
-export {};
-//# sourceMappingURL=Switch.d.ts.map

package/dist/components/Switch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../../src/components/Switch.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAI3D,UAAU,KAAM,SAAQ,eAAe;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,KAAK,CAAA;AAEjD,eAAO,MAAM,MAAM,8DAAuE,WAAW,4CAiBnG,CAAA"}

package/dist/components/Switch.js

@@ -1,8 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { withRef } from '../utils/react.js';
-import { CitricComponent } from './CitricComponent.js';
-export const Switch = withRef(({ value, onChange, children, className, style, ...props }) => {
-    const handleChange = onChange ? () => onChange(!value) : undefined;
-    return children ? (_jsxs(CitricComponent, { tag: "label", component: "switch-row", style: style, className: className, children: [_jsx("input", { type: "checkbox", checked: value, onChange: handleChange, ...props }), children] })) : _jsx(CitricComponent, { tag: "input", type: "checkbox", component: "switch", checked: value, onChange: handleChange, className: className, style: style, ...props });
-});
-//# sourceMappingURL=Switch.js.map

package/dist/components/Switch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Switch.js","sourceRoot":"","sources":["../../src/components/Switch.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAUnD,MAAM,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,KAAK,EAAe,EAAE,EAAE;IACvG,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAClE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAChB,MAAC,eAAe,IAAC,GAAG,EAAC,OAAO,EAAC,SAAS,EAAC,YAAY,EAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,aACpF,gBAAO,IAAI,EAAC,UAAU,EAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,KAAM,KAAK,GAAI,EAC3E,QAAQ,IACO,CACnB,CAAC,CAAC,CAAC,KAAC,eAAe,IAClB,GAAG,EAAC,OAAO,EACX,IAAI,EAAC,UAAU,EACf,SAAS,EAAC,QAAQ,EAClB,OAAO,EAAE,KAAK,EACd,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,KAAK,KACR,KAAK,GACT,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/src/components/Switch.tsx

@@ -1,30 +0,0 @@
-import { ControlledInput, WithColorScheme } from '../types'
-import { withRef } from '../utils/react'
-import { CitricComponent } from './CitricComponent'
-
-interface Props extends WithColorScheme {
-  value?: boolean,
-  onChange?: (value: boolean) => void,
-  children?: React.ReactNode,
-}
-
-export type SwitchProps = ControlledInput & Props
-
-export const Switch = withRef(({ value, onChange, children, className, style, ...props }: SwitchProps) => {
-  const handleChange = onChange ? () => onChange(!value) : undefined
-  return children ? (
-    <CitricComponent tag="label" component="switch-row" style={style} className={className}>
-      <input type="checkbox" checked={value} onChange={handleChange} {...props} />
-      {children}
-    </CitricComponent>
-  ) : <CitricComponent
-    tag="input"
-    type="checkbox"
-    component="switch"
-    checked={value}
-    onChange={handleChange}
-    className={className}
-    style={style}
-    {...props}
-  />
-})