design system core documentation (#2311)

* chore(): doc

* chore():

* chore():

* chore():

* chore():

* chore():

* [CodeFactor] Apply fixes to commit 423f78a

* chore():

* chore(): more edits

* chore(): update

---------

Co-authored-by: codefactor-io <[email protected]>
Co-authored-by: Josemaria Nriagu <[email protected]>

libs/design-system-core/README.md

@@ -1,7 +1,70 @@
 # Design System Core
 
-> Base level components built with TailwindCSS using [Twind](https://twind.style)
+> A library of core UI components built with [Twind](https://twind.dev/), a tailwind-in-js solution.
+ 
+The components implement the visual design language of AKASHA, and can be customised with tailwind style directives through the `customStyle` property.
+
+For a showcase of the components you can visit our [storybook](https://storybook-awf.netlify.app/), and check out the DSCORE section.
 
 ## Usage
 
 Visit the [Akasha Storybook](https://storybook-awf.netlify.app/) page for a visual demonstration of how the Design System Core components look. Code examples of how to start using these components in your app are also available. 
+
+To use a component import it from the **design-system-core** package:
+
+```tsx
+import Stack from '@akashaorg/design-system-core/lib/components/Stack';
+```
+
+### Stack
+
+A container that lays out its content in one direction using flexbox.
+Can be used to arrange other components:
+
+```tsx
+  <Stack direction="row" spacing="gap-4" padding="p-4" fullWidth>
+    <ExampleComponent1>
+    <ExampleComponent2>
+  </Stack>
+```
+
+### Card
+
+A container of information that has predefined styles following the AKASHA design language.
+Has rounded borders and displays a box-shadow by default, making it useful for structuring
+elements in apps.
+Can be used as an entry point for other, more detailed elements:
+
+```tsx
+  <Card elevation={1} padding={'p-4'}>
+    <ExampleComponent1>
+    <ExampleComponent2>
+  </Card>
+```
+
+### Button
+
+A button component with rounded borders. Has 3 variants: `primary` for the call-to-action
+use case, `secondary` for normal usage, and `text` only when you need clickable texts that don't look like a button. It can also be displayed as an icon.
+
+```tsx
+ <Button variant="secondary" label="Click me" onClick={handleClick}>
+```
+
+### Toggle
+
+A toggle component with multiple sizes. Can be disabled.
+
+```tsx
+ <Toggle checked={isChecked} onChange={handleToggle} size="small">
+```
+
+### Checkbox
+
+A checkbox component.
+
+```tsx
+<Checkbox label={'Checkbox'} name="check1" value="check1" handleChange={handleCheckbox} isSelected={isChecked} isDisabled={disableCheckbox} />
+```
+
+There are multiple other components in the package that can be customised to fit your needs.

libs/design-system-core/src/components/Accordion/index.tsx

@@ -17,6 +17,33 @@ export type AccordionProps = {
   handleClick: (id: string) => void;
 };
 
+/**
+ * An accordion provides a fast and easy way to create expandable and collapsible sections
+ * anywhere in your app. Its container and content can be easily customized using the
+ * `customStyle` and `contentStyle` props.
+ * #### Usage
+ * @example
+ * ```tsx
+ * const title = (
+ * <Stack align="center" direction="row">
+ *  <Avatar
+ *   profileId={profileId}
+ *   avatar={{ src: 'https://placebeard.it/360x360', height: 360, width: 360 }}
+ *   />
+ *   <Text customStyle="ml-2.5">Item name</Text>
+ * </Stack>
+ * );
+ *
+ * const content = (
+ * <Stack>
+ *   <Text>some interesting items</Text>
+ *   <Text>could be placed</Text>
+ *   <Text>inside the accordion</Text>
+ * </Stack>
+ * );
+ * <Accordion open={true} accordionId='someId' titleNode={title} contentNode={content} customStyle='w-[15%]' />
+ * ```
+ **/
 const Accordion: React.FC<AccordionProps> = props => {
   const {
     customStyle = '',

libs/design-system-core/src/components/AppAvatar/index.tsx

@@ -13,6 +13,19 @@ export type AppAvatarProps = AvatarProps & {
   appType: IntegrationTypes;
 };
 
+/**
+ * An AppAvatar provides a fast and easy way to create an avatar component.
+ * You can easily customize its size, border, background color, clickability and
+ * apply custom styling using the corresponding props.
+ * #### Usage
+ * @example
+ * ```tsx
+ * const profileId = 'did:pkh:eip155:5:0x36c703c42dfa2437dc883e2e0884e57404e16493';
+ * const avatar = { src: 'https://placebeard.it/360x360', height: 360, width: 360 };
+ *
+ * <AppAvatar avatar={avatar} appType={IntegrationTypes.APP} profileId={profileId} />
+ * ```
+ **/
 const AppAvatar: React.FC<AppAvatarProps> = props => {
   const {
     appType,

libs/design-system-core/src/components/AppIcon/index.tsx

@@ -34,6 +34,25 @@ export type AppIconProps = {
   customStyle?: string;
 };
 
+/**
+ * An AppIcon component provides a fast and easy way to include a custom app icon
+ * for your application.
+ * You can easily customize its icon, size, border, background color, etc. and
+ * apply custom styling using the corresponding props. A boolean `hasNewNotifs` prop can
+ * also be passed to indicate whether that app has new notifications.
+ * #### Usage
+ * @example
+ * ```tsx
+ *  <AppIcon
+ *    placeholderIcon={<Walletconnect />}
+ *    background={{ gradient: 'gradient-to-b', from: 'orange-50', to: 'orange-200' }}
+ *    radius={24}
+ *    size={{ width: 80, height: 80 }}
+ *    backgroundSize={80}
+ *    iconColor="self-color"
+ *   />
+ * ```
+ **/
 const AppIcon: React.FC<AppIconProps> = props => {
   const {
     appImg,

libs/design-system-core/src/components/AutoComplete/index.tsx

@@ -24,6 +24,25 @@ export type AutoCompleteProps = {
   onSelected?: ({ value, index }: Selected) => void;
 } & Pick<TextFieldProps, 'label' | 'caption' | 'status'>;
 
+/**
+ * An AutoComplete component improves the user experience by suggesting possible
+ * completions as the user types.
+ * @param options - string
+ * @param placeholder - placeholder text (optional)
+ * @param disabled - (optional) whether to disable the text input
+ * @param value - string (optional) set the value for the input
+ * @param customStyle - (optional) custom styling to apply if any
+ * @param multiple - boolean (optional) whether to delay suggestion because it is a phrase with multiple words
+ * @param separators - (optional) a list of keystrokes that separate the words and start the action
+ * @param tags - (optional) a set of string
+ * @param onChange - (optional) handler on text input change
+ * @param onSelected - (optional) handler when user selects a suggestion
+ *
+ * @example
+ * ```tsx
+ *  <AutoComplete placeholder={'Start searching...'} options={['a','b','c']} separators={['Comma', 'Space', 'Enter']} />
+ * ```
+ **/
 const AutoComplete: React.FC<AutoCompleteProps> = props => {
   const {
     options,

libs/design-system-core/src/components/Avatar/index.tsx

@@ -84,6 +84,30 @@ const AvatarContent: React.FC<AvatarContentProps> = props => {
   );
 };
 
+/**
+ * An Avatar component provides an easy and fast way to include an avatar in your app.
+ * @param alt - alt text (optional)
+ * @param avatar -image source (optional)
+ * @param alternativeAvatars - (optional) a list of alternative images for the avatar
+ * @param active - boolean (optional) whether the avatar is active
+ * @param border - (optional) custom sizing for the border
+ * @param size - (optional) custom sizing for the avatar
+ * @param borderColor - (optional) custom styling for the border color
+ * @param backgroundColor - (optional) custom styling for the background color
+ * @param faded - boolean (optional) whether the avatar should have faded style
+ * @param isClickable - boolean (optional) whether the avatar should be clickable
+ * @param profileId - string (optional) the profile id the avatar belongs to
+ * @param publicImgPath - string (optional) the public image path of the avatar
+ * @param customStyle - (optional) custom styling if any
+ * @param onClick - (optional) click handler
+ * @param dataTestId - (optional) for test writing purpose
+ * @param href - (optional) href if any
+ *
+ * @example
+ * ```tsx
+ *  <Avatar size="md" avatar={avatar} profileId={profileId} />
+ * ```
+ **/
 const Avatar: React.FC<AvatarProps> = props => {
   const { dataTestId, href, onClick, ...rest } = props;
 

libs/design-system-core/src/components/BasicPopover/index.tsx

@@ -10,6 +10,26 @@ export type BasicPopoverProps = PropsWithChildren<{
   closePopover: () => void;
 }>;
 
+/**
+ * A BasicPopover component provides an easy and fast way to include a popover in your app.
+ * @param target - HTML Element
+ * @param gap - custom gap (optional)
+ * @param overflow - (optional) custom overflow styling
+ * @param closePopover - click handler for closing the popover
+ *
+ * @example
+ * ```tsx
+ * const targetNode = document.createElement('div');
+ * const Contents = (
+ * <React.Fragment>
+ *  <div>Popover content</div>
+ *   <div>Popover content</div>
+ *  <div>Popover content</div>
+ * </React.Fragment>
+ * );
+ *  <BasicPopover target={targetNode} children={Contents} />
+ * ```
+ **/
 const BasicPopover: React.FC<BasicPopoverProps> = ({ children, ...props }) => {
   const { gap, overflow = 'hidden' } = props;
 

libs/design-system-core/src/components/Button/index.tsx

@@ -9,6 +9,37 @@ import { ButtonProps, ButtonSize } from './types';
 import { getTextClasses } from './getTextClasses';
 import { getContainerClasses } from './getContainerClasses';
 
+/**
+ * A Button allows users to take actions when appropriate with a tap(on touch-screen devices)
+ * or click of a mouse.
+ * A Button component comes with three variants: primary, secondary (default), and text.
+ * A Button component accepts all the props that a native html button accepts plus
+ * additional customization props, such as those listed below:
+ * @param label - button label (optional)
+ * @param icon - React.ReactElement button icon if any (optional)
+ * @param iconDirection - 'left' | 'right' (optional) where the icon will be placed
+ * @param size - button size (optional)
+ * @param variant - button variant (optional) the default is 'secondary'
+ * @param disabled - boolean (optional) whether the button is disabled or not
+ * @param loading - boolean (optional) whether to apply loading state to the button
+ * @param iconOnly - boolean (optional) whether it is an icon-only button with no label
+ * @param greyBg - boolean (optional) whether to apply grey background styling
+ * @param plainIcon - boolean (optional) whether to apply plain-icon styling to the icon
+ * @param solidIcon - boolean (optional) whether to apply solid-icon styling to the icon
+ * @param plain - boolean (optional) a plain button has no styling applied, can be used as a
+ * click wrapper
+ * @param breakPointSize - (optional) customize sizes for the break points
+ * @param customStyle - (optional) custom styling if any
+ * @param active - boolean (optional) whether the buttton is active
+ * @param hover - boolean (optional)
+ * @param hoverColors - (optional) styling for hover state
+ * @param ref - (optional)
+ *
+ * @example
+ * ```tsx
+ *  <Button variant={'primary'} label={'Primary button'} size={'sm'} onClick={onclickHandler} />
+ * ```
+ **/
 const Button: React.FC<ButtonProps> = forwardRef((props, ref) => {
   const {
     plain,

libs/design-system-core/src/components/Card/index.tsx

@@ -31,6 +31,29 @@ export type TCardProps = PropsWithChildren<
   CommonCardProps & ({ type: 'plain' } | (RegularCardType & { type?: 'regular' }))
 >;
 
+/**
+ * A Card component contains content and actions pertaining to a single subject.
+ * There are two types of cards: regular and plain. A regular card looks like a
+ * normal card with customizable border and elevation. A plain card doesn't look
+ * like a card and can act as an invisible wrapper around other components.
+ * @param elevation - (optional) adjust the elevation property
+ * @param background - (optional) customize the background color
+ * @param dashedBorder - boolean (optional) whether the border should have dashed style
+ * @param accentBorder - boolean (optional) whether the border should have accent style
+ * @param padding - (optional) customize the padding
+ * @param margin - (optional) customize the margin
+ * @param radius - (optional) customize the radius
+ * @param border - boolean (optional) whether the card should have border
+ * @param noBorderRadius - boolean (optional) whether the card should have rounded corner
+ * @param fullWidth - boolean (optional) whether the card should occupy the full width of the parent element
+ * @param customStyle - (optional) custom styling if any
+ * @param dataTestId - (optional) useful identifier when writing tests
+ * @param ref - (optional)
+ * @example
+ * ```tsx
+ *  <Card background={{ dark: 'grey3', light: 'grey9' }} onClick={clickHandler} padding="p-4" />
+ * ```
+ **/
 const Card: React.FC<TCardProps> = forwardRef((props, ref) => {
   if (props.type === 'plain') {
     const { dataTestId, customStyle = '', ...rest } = props;

libs/design-system-core/src/components/Checkbox/index.tsx

@@ -39,6 +39,35 @@ before:left-2
 after:left-2
 `;
 
+/**
+ * A Checkbox component allows users to select one or more options from a list.
+ * Checkboxes are most useful when you have multiple options to present. When there
+ * is only one option available, consider using a toggle instead.
+ * @param id - assign an ID to the checkbox
+ * @param label - (optional) checkbox label
+ * @param labelDirection - (optional) control where the label will be placed
+ * @param labelColor - (optional) customize the label color
+ * @param value - checkbox value
+ * @param name - checkbox's name
+ * @param size - (optional) customize checkbox' size
+ * @param indeterminate - boolean (optional) whether the checkbox is in indeterminate state
+ * @param error - boolean (optional) whether the checkbox is in error state
+ * @param isSelected - boolean (optional) whether the checkbox is selected
+ * @param isDisabled - boolean (optional) whether the checkbox is disabled
+ * @param customStyle - (optional) custom styling if any
+ * @param handleChange - (optional) change handler
+ * @example
+ * ```tsx
+ *  <Checkbbox
+ *    id='nsfw'
+ *    label="NSFW"
+ *    name="nsfw"
+ *    value="nsfw"
+ *    handleChange={onSelectCheckbox}
+ *    isSelected={false}
+ *   />
+ * ```
+ **/
 const Checkbox: React.FC<CheckboxProps> = ({
   id,
   label,

libs/design-system-core/src/components/ContentBlock/index.tsx

@@ -14,6 +14,27 @@ export type ContentBlockProps = {
   showDivider?: boolean;
 };
 
+/**
+ * A ContentBlock component is a specific type of container that display content in a pre-determined
+ * style. You can find examples of Content Block usage when browsing a specific app inside
+ * the Extensions app in Akasha World.
+ * @param blockTitle - assign a title to be displayed
+ * @param viewMoreLabel - (optional) text that a user can click to view more content
+ * @param viewMoreIcon - (optional) icon that a user can click to view more content. Only
+ * a viewMoreLabel or viewMoreIcon should be provided at a time.
+ * @param onClickviewMoreLabel - (optional) click handler for the viewMoreLabel/viewMoreIcon props
+ * @param blockVariant - (optional) customize the text variant
+ * @param showDivider - boolean (optional) whether to show a divider at the bottom of the block
+ * @example
+ * ```tsx
+ *  <ContentBlock
+ *    blockTitle='Version History'
+ *    viewMoreIcon={<ChevronRightIcon />}
+ *    showDivider={false}
+ *    onClickviewMoreLabel={viewMoreClickHandler}
+ *   />
+ * ```
+ **/
 const ContentBlock: React.FC<PropsWithChildren<ContentBlockProps>> = ({
   blockTitle,
   viewMoreLabel,

libs/design-system-core/src/components/CopyToClipboard/index.tsx

@@ -9,6 +9,21 @@ export type CopyToClipboardProps = PropsWithChildren<{
   copyText?: string;
   copiedText?: string;
 }>;
+
+/**
+ * A CopyToClipboard component serves a specific purpose: display a tooltip on hover to explain to
+ * the user the purpose of the component and copy the content of component to the Clipboard.
+ * The user can then paste the copied content elsewhere. The copied content remains in memory
+ * until the user copies something else.
+ * @param value - the value to be copied
+ * @param copyText - (optional) text that will be displayed in the tooltip before copying
+ * @param copiedText - (optional) text that will be displayed in the tooltip after copying
+ * ```tsx
+ *  <CopyToClipboard
+ *    value='0x003410490050000320006570034567114572000'
+ *   />
+ * ```
+ **/
 const CopyToClipboard: React.FC<CopyToClipboardProps> = ({
   value,
   copyText = 'Copy to clipboard',