docs[DST-189]: write utils documentation (#3340)

* save

* added cva in docs

* Create silver-coats-report.md

* add review changes

* added badge

.changeset/silver-coats-report.md

@@ -0,0 +1,5 @@
+---
+"@marigold/docs": patch
+---
+
+chore[DST-189]: write utils documentation

docs/app/_components/Navigation.tsx

@@ -36,12 +36,14 @@ const useNavigation = (): NavigationSection[] => {
     const sectionPages = allContentPages.filter(
       page => page.section === slug && !page.subsection
     );
+
     sectionPages.sort((a, b) => (a.order || 1000) - (b.order || 1000));
     return {
       name,
       links: sectionPages.map(page => ({
         name: page.title,
         href: `/${page.slug}`,
+        badge: page.badge,
       })),
       subsections: subsections.map(subsection => ({
         name: subsection.name,
@@ -78,14 +80,16 @@ export const Navigation = ({ onClick }: NavigationProps) => {
         <div key={section.name} className="flex flex-col gap-2">
           <div className="font-semibold">{section.name}</div>
           <div className="border-secondary-300 ml-0.5 flex flex-col gap-2 border-l">
-            {section.links.map(({ name, href }) => (
+            {section.links.map(({ name, href, badge }) => (
               <NavLink
+                className="flex items-center gap-4"
                 key={href}
                 current={pathname === href}
                 href={href}
                 onClick={onClick}
               >
                 {name}
+                {badge && <Badge variant="dark">{badge}</Badge>}
               </NavLink>
             ))}
           </div>

docs/content/hooks-and-utils/cn/cn.mdx

@@ -0,0 +1,33 @@
+---
+title: cn
+caption: Helper that combines classnames together.
+badge: new
+---
+
+To combine Tailwind CSS classes with other classes, utilize the `cn` function within the className attribute to merge them seamlessly. The inputs of the `className` accept nearly every type. The function itself uses `tailwind-merge` which is a utility function to easily merge the given tailwind classes. We also use `cx` function from [cva](https://cva.style/docs/api-reference), which combines the class names together. You can pass in arrays, boolean conditions, strings or numbers.
+
+### Import
+
+To import the function you just have to use this code below.
+
+```tsx
+import { cn } from '@marigold/system';
+```
+
+### Examples
+
+In this example you can see how to use the `cn` function on a `<div>` element. Here are written down some Tailwind CSS class names which will be merged with the ones before. So in the end the class names will be rendered (if `myValue` will be true) as `className='flex flex-col cursor-pointer p-4'`
+
+```tsx
+const myOtherValue = 'p-4'
+...
+<div
+  className={cn(
+    'flex flex-col p-3',
+    myValue ? 'cursor-pointer' : 'cursor-not-allowed',
+    myOtherValue
+  )}
+/>
+```
+
+In this code you can see that `p-3` will be overwritten by `p-4`, so keep in mind the order of your class names.

docs/content/hooks-and-utils/cva/cva.demo.tsx

@@ -0,0 +1,16 @@
+import { cva } from '@marigold/system';
+
+export default () => {
+  const styledDiv = cva('p-4 text-4xl', {
+    variants: {
+      variant: {
+        myOwnVariant: 'bg-lime-200',
+      },
+    },
+  });
+  return (
+    <div className={styledDiv({ variant: 'myOwnVariant' })}>
+      this is some text
+    </div>
+  );
+};

docs/content/hooks-and-utils/cva/cva.mdx

@@ -0,0 +1,22 @@
+---
+title: cva
+caption: Helper to write styles for an element.
+badge: new
+---
+
+To write our styles for a component we use [cva](https://cva.style/docs). This library comes with a great utility function which we use to write styles for our components.
+If you want to style your own component you can use this function which we updated with some additional style checks, for example it resolves conflicts in class names with `tailwind-merge`. With this the class names will be merged together.
+
+### Import
+
+To import the function you just have to use this code below.
+
+```tsx
+import { cva } from '@marigold/system';
+```
+
+### Examples
+
+This example shows how to use the function inside a `div` element. You can add some variants and sizes if you want.
+
+<ComponentDemo file="./cva.demo.tsx" />

docs/lib/config.ts

@@ -44,8 +44,8 @@ export const siteConfig = {
       ],
     },
     {
-      name: 'Hooks',
-      slug: 'hooks',
+      name: 'Hooks and Utils',
+      slug: 'hooks-and-utils',
     },
     {
       name: 'Recipes',

package.json

@@ -44,7 +44,7 @@
     "build:docs": "turbo run --filter @marigold/docs... build",
     "build:storybook": "turbo run --filter @marigold/storybook-config... build",
     "build:themes": "turbo run --filter \"@marigold/theme*...\" build",
-    "registry": "turbo run --filter @marigold/docs registry",
+    "registry": "pnpm --filter @marigold/docs registry",
     "test": "jest --config jest.config.js",
     "test:coverage": "jest --config jest.config.js --coverage --coverageReporters html",
     "test:ci": "jest --config jest.config.js --coverage --ci --no-cache",