docs(site): add component-description component (#1547)

packages/docs/components/component-description/component-description.module.css

@@ -0,0 +1,9 @@
+.description {
+  color: var(--sl-fg-base-soft);
+  font-family: var(--sl-font-family-sans);
+  font-size: 18px;
+  font-style: normal;
+  font-weight: 500;
+  line-height: 32px;
+  letter-spacing: -0.96px;
+}

packages/docs/components/component-description/component-description.tsx

@@ -0,0 +1,19 @@
+import React from 'react'
+import allProps from '../../__props__'
+import styles from './component-description.module.css'
+
+export function ComponentDescription(props: PropsDocsProps) {
+  const { name } = props
+
+  const reference = allProps[name]
+
+  if (!reference) {
+    return <></>
+  }
+
+  return <p className={styles.description}>{reference.description}</p>
+}
+
+interface PropsDocsProps {
+  name: string
+}

packages/docs/components/component-description/index.ts

@@ -0,0 +1 @@
+export * from './component-description'

packages/docs/components/preview/preview.module.css

@@ -3,6 +3,7 @@
   --max-h: 30rem;
   --space: var(--sl-space-3);
   --radii: var(--sl-border-radius-large);
+  margin-top: var(--sl-space-5);
 }
 
 .previewWrapper {

packages/docs/components/props-docs/props-docs.module.css

@@ -7,6 +7,8 @@
 
 .prop {
   padding: var(--sl-space-0) var(--sl-space-3);
+  overflow-x: auto;
+  overflow-y: hidden;
 }
 
 .tag {

packages/docs/components/props-docs/props-docs.tsx

@@ -34,8 +34,8 @@ export function PropsDocs(props: PropsDocsProps) {
           String(prop.defaultValue).trim().replace(/'/g, '') ?? 'undefined'
 
         return (
-          <Fragment>
-            <div key={prop.name} className={styles.prop}>
+          <Fragment key={prop.name}>
+            <div className={styles.prop}>
               <h4 className="nx-font-semibold nx-tracking-tight nx-text-slate-900 dark:nx-text-slate-100 ">
                 {prop.name}
               </h4>

packages/docs/examples/accessible-icon.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import { AccessibleIcon, IconTrash } from '@vtex/shoreline'
+
+export default function Example() {
+  return (
+    <AccessibleIcon label="Delete">
+      <IconTrash />
+    </AccessibleIcon>
+  )
+}

packages/docs/pages/components/accessible-icon.mdx

@@ -1,5 +1,13 @@
 # AccessibleIcon
 
-Makes icons accessible by adding a label.
+<ComponentDescription name="accessible-icon" />
 
-![AccessibleIcon example](public/assets/overview-accessibleicon.webp)
+<Preview name="accessible-icon" />
+
+## Required props
+
+<PropsDocs name="accessible-icon" required />
+
+## Optional props
+
+<PropsDocs name="accessible-icon" />

packages/docs/pages/components/alert.mdx

@@ -1,10 +1,25 @@
 # Alert
 
-Alerts call attention to a semantic message and load alongside the rest of the page content. They can optionally be dismissed upon user action.
+<ComponentDescription name="alert" />
 
-![Alert example](public/assets/overview-alert.webp)
+<Preview name="alert" />
+
+## Examples
+
+### Variants
+
+<Preview name="alert-variants" />
+
+### Action
+
+<Preview name="alert-action" />
+
+## Optional props
+
+<PropsDocs name="alert" />
+
+## Related components
 
-### Related components
 <RelatedComponentList>
   <RelatedComponent
     title="Toast"

packages/docs/pages/components/alert/_meta.json

@@ -1 +1 @@
-{ "api-reference": "API Reference", "best-practices": "Best Practices" }
+{ "best-practices": "Best Practices" }

packages/docs/pages/components/bleed.mdx

@@ -1,5 +1,9 @@
 # Bleed
 
-Sometimes a component needs to trespass the parent padding to achieve alignment harmony and visual compensation to the layout. You can accomplish this with Bleed, which applies a negative margin to represent the amount of trespassing desired.
+<ComponentDescription name="bleed" />
 
-![Bleed example](public/assets/overview-bleed.webp)
+<Preview name="bleed" />
+
+## Optional props
+
+<PropsDocs name="bleed" />

packages/docs/pages/components/button.mdx

@@ -1,10 +1,33 @@
 # Button
 
-Buttons with labels represent the most important actions that users frequently trigger. They can vary in prominence and can include an icon.
+<ComponentDescription name="button" />
 
-![Button example](public/assets/overview-button.webp)
+<Preview name="button" />
+
+## Examples
+
+### Variants
+
+<Preview name="button-variants" />
+
+### Sizes
+
+<Preview name="button-sizes" />
+
+### Upload
+
+<Preview name="button-upload" />
+
+## Required props
+
+<PropsDocs name="button" required />
+
+## Optional props
+
+<PropsDocs name="button" />
+
+## Related components
 
-### Related components
 <RelatedComponentList>
   <RelatedComponent
     title="Link"

packages/docs/pages/components/button/_meta.json

@@ -1 +1 @@
-{ "api-reference": "API Reference", "best-practices": "Best Practices" }
+{ "best-practices": "Best Practices" }

packages/docs/scripts/build-props.mjs

@@ -8,6 +8,7 @@ const outputDirectory = `${dirname('')}/__props__`
 const outputFile = 'index.ts'
 
 const files = [
+  getPath('primitives', 'accessible-icon', 'accessible-icon'),
   getPath('components', 'alert', 'alert'),
   getPath('components', 'bleed', 'bleed'),
   getPath('components', 'button', 'button'),

packages/docs/theme.config.tsx

@@ -10,6 +10,7 @@ import {
 } from './components/related-component'
 import { Preview } from './components/preview'
 import { PropsDocs } from './components/props-docs'
+import { ComponentDescription } from './components/component-description'
 
 const config: DocsThemeConfig = {
   logo: <Logo />,
@@ -31,6 +32,7 @@ const config: DocsThemeConfig = {
     RelatedComponent: RelatedComponent as React.FC,
     Preview: Preview as React.FC,
     PropsDocs: PropsDocs as React.FC,
+    ComponentDescription: ComponentDescription as React.FC,
   },
   sidebar: {
     defaultMenuCollapseLevel: 1,

packages/primitives/src/accessible-icon/accessible-icon.tsx

@@ -1,11 +1,10 @@
-import type { ReactElement, ReactNode } from 'react'
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react'
 import React, { Children, cloneElement, forwardRef } from 'react'
 
 import { VisuallyHidden } from '../visually-hidden'
 
 /**
- * Makes icons accessible by adding a label
- *
+ * Makes icons accessible by adding a label. It can be used with Shoreline icons or other svg.
  * @kind primitives
  * @example
  * <AccessibleIcon>
@@ -63,10 +62,16 @@ export const AccessibleIcon = forwardRef<HTMLDivElement, AccessibleIconProps>(
   }
 )
 
-export interface AccessibleIconProps {
+export interface AccessibleIconOptions {
   /**
-   * Describe the icon
+   * Icon description
    */
   label: ReactNode
+  /**
+   * Component children, normally a <svg />.
+   */
   children?: ReactNode
 }
+
+export type AccessibleIconProps = AccessibleIconOptions &
+  ComponentPropsWithoutRef<'div'>