From b011c626b03725803777d7391f89c457c876d400 Mon Sep 17 00:00:00 2001
From: joostdecock <joost@joost.at>
Date: Sat, 24 May 2025 15:28:43 +0200
Subject: [PATCH] [react] feat: Added docs for components/Link

---
 packages/react/components/Link/index.mjs      | 76 ++++++++++++-------
 packages/react/mkdocs.sh                      |  1 +
 .../react/components/link/_examples.js        | 30 ++++++++
 .../packages/react/components/link/readme.mdx | 46 ++++++++++-
 4 files changed, 123 insertions(+), 30 deletions(-)
 create mode 100644 sites/dev/docs/reference/packages/react/components/link/_examples.js

diff --git a/packages/react/components/Link/index.mjs b/packages/react/components/Link/index.mjs
index 8c7c9ddd17b..adf5e1156c6 100644
--- a/packages/react/components/Link/index.mjs
+++ b/packages/react/components/Link/index.mjs
@@ -4,10 +4,12 @@ import { linkClasses } from '@freesewing/utils'
 /**
  * An anchor link component
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
- * @param {array} props.id - The ID of the anchor to link to
- * @param {array} props.title - An optional link title
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the link
+ * @param {string} [props.id = ''] - The ID of the anchor to link to
+ * @param {string} [props.title = false] - An optional link title
+ * @returns {JSX.Element}
  */
 export const AnchorLink = ({ children, id = '', title = false }) => (
   <a href={`#${id}`} className={linkClasses} title={title ? title : ''}>
@@ -18,20 +20,23 @@ export const AnchorLink = ({ children, id = '', title = false }) => (
 /**
  * A regular link component
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
- * @param {array} props.href - The target to link to
- * @param {array} props.title - An optional link title
- * @param {string} props.className - Any non-default CSS classes to apply
- * @param {string} props.style - Any non-default styles to apply
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the link
+ * @param {string} [props.className = @freesewing/utils/linkClasses] - Any non-default CSS classes to apply
+ * @param {string} props.href - The URL to link to
+ * @param {object} [props.style = {}] - Any non-default styles to apply
+ * @param {string} [props.target = undefined] - An optional link title
+ * @param {string} [props.title = false] - An optional link title
+ * @returns {JSX.Element}
  */
 export const Link = ({
-  href,
-  title = false,
   children,
   className = linkClasses,
-  target,
+  href,
   style = {},
+  target,
+  title = false,
 }) => (
   <a href={href} target={target} className={className} title={title ? title : ''} style={style}>
     {children}
@@ -41,34 +46,49 @@ export const Link = ({
 const BaseLink = Link
 
 /**
- * A regular link, but on a success background
+ * A regular link, but intended to be used on a success background
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
- * @param {array} props.href - The target to link to
- * @param {array} props.title - An optional link title
- * @param {string} props.className - Any non-default CSS classes to apply
- * @param {string} props.style - Any non-default styles to apply
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the link
+ * @param {string} props.href - The URL to link to
+ * @param {string} [props.target = undefined] - An optional link title
+ * @param {string} [props.title = false] - An optional link title
+ * @param {React.FC} [Link = undefined] - An optional framework-specific Link component
+ * @returns {JSX.Element}
  */
 export const SuccessLink = ({
-  href,
-  title = false,
   children,
-  className = `${linkClasses} tw:text-success-content tw:hover:text-success-content`,
-  style = {},
+  href,
+  target,
+  title = false,
+  Link,
 }) => (
-  <a href={href} className={className} title={title ? title : ''} style={style}>
-    {children}
+  <a href={href} className={linkClasses} title={title ? title : ''}>
+    <span className="tw:text-success-content tw:hover:text-success-content">{children}</span>
   </a>
 )
 
+/**
+ * A link styled as a card
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the link
+ * @param {string} [props.className = @freesewing/utils/linkClasses + "tw:text-success-content tw:hover:text-success-content"] - Any non-default CSS classes to apply
+ * @param {string} props.href - The URL to link to
+ * @param {string} [props.title = false] - An optional link title
+ * @param {JSX.Element} props.icon - An icon to render
+ * @param {React.FC} [Link = undefined] - An optional framework-specific Link component
+ * @returns {JSX.Element}
+ */
 export const CardLink = ({
+  children,
+  className = 'tw:bg-base-200 tw:text-base-content',
   href,
   title,
   icon,
-  children,
   Link,
-  className = 'tw:bg-base-200 tw:text-base-content',
 }) => {
   if (!Link) Link = BaseLink
 
diff --git a/packages/react/mkdocs.sh b/packages/react/mkdocs.sh
index 301f74432fe..8de280480b0 100755
--- a/packages/react/mkdocs.sh
+++ b/packages/react/mkdocs.sh
@@ -19,3 +19,4 @@ jsdoc -c jsdoc.json components/Json/* > ../../sites/dev/prebuild/jsdoc/react/com
 jsdoc -c jsdoc.json components/KeyVal/* > ../../sites/dev/prebuild/jsdoc/react/components/keyval.json
 jsdoc -c jsdoc.json components/Layout/* > ../../sites/dev/prebuild/jsdoc/react/components/layout.json
 jsdoc -c jsdoc.json components/LineDrawing/* > ../../sites/dev/prebuild/jsdoc/react/components/linedrawing.json
+jsdoc -c jsdoc.json components/Link/* > ../../sites/dev/prebuild/jsdoc/react/components/link.json
diff --git a/sites/dev/docs/reference/packages/react/components/link/_examples.js b/sites/dev/docs/reference/packages/react/components/link/_examples.js
new file mode 100644
index 00000000000..2bd733031db
--- /dev/null
+++ b/sites/dev/docs/reference/packages/react/components/link/_examples.js
@@ -0,0 +1,30 @@
+import React from 'react'
+import {
+  AnchorLink,
+  CardLink,
+  Link,
+  SuccessLink,
+} from '@freesewing/react/components/Link'
+import { WarningIcon } from '@freesewing/react/components/Icon'
+
+export const AnchorLinkExample = () => <AnchorLink id="cardlink">This is a AnchorLink</AnchorLink>
+export const CardLinkExample = () => (
+  <CardLink
+    id="cardlink"
+    icon={<WarningIcon />}
+    href="/"
+    title="This is the title"
+  >
+    This is a CardLink with a WarningIcon
+  </CardLink>
+)
+export const LinkExample = () => <Link href="/">This is a Link</Link>
+export const SuccessLinkExample = () => (
+  <>
+    <SuccessLink href="/">This is a SuccessLink, you should not use it on a regular background</SuccessLink> (there is a link on this line)
+    <div className="tw:bg-success tw:p-2 tw:rounded">
+      <SuccessLink href="/">This is a SuccessLink on a success background</SuccessLink>
+    </div>
+  </>
+)
+
diff --git a/sites/dev/docs/reference/packages/react/components/link/readme.mdx b/sites/dev/docs/reference/packages/react/components/link/readme.mdx
index 1156c5aa1ef..9275c1c5874 100644
--- a/sites/dev/docs/reference/packages/react/components/link/readme.mdx
+++ b/sites/dev/docs/reference/packages/react/components/link/readme.mdx
@@ -2,6 +2,48 @@
 title: Link
 ---
 
-:::note
-This page is yet to be created
+import { DocusaurusDoc } from '@freesewing/react/components/Docusaurus'
+import { ComponentDocs } from '@site/src/components/component-docs.js'
+import * as jsdoc from '@site/prebuild/jsdoc/components.link.mjs'
+import {
+  AnchorLinkExample,
+  CardLinkExample,
+  LinkExample,
+  SuccessLinkExample,
+} from './_examples.js'
+
+
+<DocusaurusDoc>
+
+:::tip Styling and link behaviour
+##### Styling
+Due to the CSS reset used by Tailwind, one cannot assume links will be styled like you expect them to.
+Use a component from this For this and other reasons, Link components exist.
+##### Link behaviour
+Withing a single-page application (SPA) --- like Docusaurus or NextJS and so on --- there is often a
+`Link` component provided by the framework that provides client-side routing so that clicking a link
+does not completely reload the page/application.
+
+You can pass such a component in some of FreeSewing components to use it for links rather than a traditional `<a>` tag.
 :::
+
+The __Link__ component family provides the following components:
+
+- [AnchorLink](#anchorlink)
+- [CardLink](#cardlink)
+- [Link](#link)
+- [SuccessLink](#successlink)
+
+## AnchorLink
+<ComponentDocs docs={jsdoc.jsdocAnchorLink} example={AnchorLinkExample} />
+
+## CardLink
+<ComponentDocs docs={jsdoc.jsdocCardLink} example={CardLinkExample} />
+
+## Link
+<ComponentDocs docs={jsdoc.jsdocLink} example={LinkExample} />
+
+## SuccessLink
+<ComponentDocs docs={jsdoc.jsdocSuccessLink} example={SuccessLinkExample} />
+
+</DocusaurusDoc>