feat(dev): Added react docs for Pattern + refactor

This adds support for not only documenating components, but also
constants and functions that may be exported next to components.

packages/react/components/Pattern/circle.mjs

@@ -1,5 +1,13 @@
 import React from 'react'
 
+/**
+ * A component to render a circle inside a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {object} props.point - The point that holds the circle info
+ * @returns {JSX.Element}
+ */
 export const Circle = ({ point }) =>
   point.attributes.list['data-circle'].map((r, i) => {
     const circleProps = point.attributes.circleProps

packages/react/components/Pattern/defs.mjs

@@ -86,12 +86,20 @@ const PaperlessDefs = ({ units = 'metric', stacks }) =>
     <MetricPaperlessDefs stacks={stacks} />
   )
 
-export const Defs = (props) =>
-  props.svg ? (
+/**
+ * A component to render the defs section of an SVG element inside a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {Svg} props.svg - The FreeSewing Svg object for the pattern
+ * @param {object} props.settings - The settings for the pattern
+ * @param {object} props.stacks - The pattern stacks
+ * @returns {JSX.Element}
+ */
+export const Defs = ({ svg, stacks, settings = {} }) =>
+  svg ? (
     <defs>
-      {props.svg.defs.list ? sanitize(Object.values(props.svg.defs.list).join('')) : null}
-      {props.settings[0].paperless ? (
-        <PaperlessDefs units={props.settings[0].units} stacks={props.stacks} />
-      ) : null}
+      {svg.defs.list ? sanitize(Object.values(svg.defs.list).join('')) : null}
+      {settings[0]?.paperless ? <PaperlessDefs units={settings[0].units} stacks={stacks} /> : null}
     </defs>
   ) : null

packages/react/components/Pattern/grid.mjs

@@ -1,7 +1,14 @@
-//  __SDEFILE__ - This file is a dependency for the stand-alone environment
-// eslint-disable-next-line no-unused-vars
 import React from 'react'
 
+/**
+ * A component to render the grid for a paperless FreeSewing pattern' stack
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {Stack} props.stack - The FreeSewing Stack object for the pattern
+ * @param {string} props.stackName - The name of the FreeSewing Stack
+ * @returns {JSX.Element}
+ */
 export const Grid = ({ stack, stackName }) => (
   <rect
     x={stack.topLeft.x}

packages/react/components/Pattern/group.mjs

@@ -1,7 +1,13 @@
-//  __SDEFILE__ - This file is a dependency for the stand-alone environment
-// eslint-disable-next-line no-unused-vars
 import React, { forwardRef } from 'react'
 
+/**
+ * A component to render an SVG group
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the group
+ * @returns {JSX.Element}
+ */
 export const Group = forwardRef((props, ref) => (
   <g {...props} ref={ref}>
     {props.children}

packages/react/components/Pattern/index.mjs

@@ -16,8 +16,11 @@ import { Circle as DefaultCircle } from './circle.mjs'
 import { getId, getProps, withinPartBounds, translateStrings } from './utils.mjs'
 import { Link as WebLink } from '@freesewing/react/components/Link'
 
-/*
- * Allow people to override these components
+/**
+ * Default pattern components that you can override
+ *
+ * @public
+ * @constant
  */
 const defaultComponents = {
   Svg: DefaultSvg,
@@ -34,9 +37,17 @@ const defaultComponents = {
   Circle: DefaultCircle,
 }
 
-/*
- * The pattern component
- * FIXME: document props
+/**
+ * A component to render a FreeSewing pattern based on its renderProps
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, if they are set, we will not render any stacks
+ * @param {string} [props.className = 'freesewing pattern'] - SVG classes to set on the SVG element
+ * @param {object} [props.components = {}] - Any custom components to use in the pattern
+ * @param {object} [props.string = {}] - Strings to use for translation
+ * @param {object} props.renderProps - The pattern's renderProps as generated by FreeSewing core
+ * @returns {JSX.Element}
  */
 const Pattern = forwardRef((props, ref) => {
   if (!props.renderProps) return null
@@ -102,3 +113,17 @@ export {
   // The Pattern component itself
   Pattern,
 }
+
+// Also export default components
+export const Svg = DefaultSvg
+export const Defs = DefaultDefs
+export const Group = DefaultGroup
+export const Stack = DefaultStack
+export const Part = DefaultPart
+export const Point = DefaultPoint
+export const Path = DefaultPath
+export const Snippet = DefaultSnippet
+export const Grid = DefaultGrid
+export const Text = DefaultText
+export const TextOnPath = DefaultTextOnPath
+export const Circle = DefaultCircle

packages/react/components/Pattern/part.mjs

@@ -2,6 +2,20 @@
 import React, { forwardRef } from 'react'
 import { getId, getProps } from './utils.mjs'
 
+/**
+ * A component to render an inner FreeSewing Part in a pattern (no group)
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.stackName - The name of the stack the part belongs to
+ * @param {string} props.partName - The name of the part
+ * @param {object} props.part - The part object itself
+ * @param {object} props.settings - The pattern settings object
+ * @param {object} props.components - An object holding the pattern compnents to use
+ * @param {object} props.strings - An object holding translations
+ * @param {object} props.drillProps - An object holding extra props to pass down (used in Xray mode)
+ * @returns {JSX.Element}
+ */
 export const PartInner = forwardRef(
   ({ stackName, partName, part, settings, components, strings, drillProps }, ref) => {
     const { Group, Path, Point, Snippet } = components
@@ -50,6 +64,20 @@ export const PartInner = forwardRef(
 
 PartInner.displayName = 'PartInner'
 
+/**
+ * A component to render a FreeSewing Part (group) in a pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.stackName - The name of the stack the part belongs to
+ * @param {string} props.partName - The name of the part
+ * @param {object} props.part - The part object itself
+ * @param {object} props.settings - The pattern settings object
+ * @param {object} props.components - An object holding the pattern compnents to use
+ * @param {object} props.strings - An object holding translations
+ * @param {object} props.drillProps - An object holding extra props to pass down (used in Xray mode)
+ * @returns {JSX.Element}
+ */
 export const Part = ({ stackName, partName, part, settings, components, strings, drillProps }) => {
   const { Group } = components
 

packages/react/components/Pattern/path.mjs

@@ -2,6 +2,20 @@
 import React from 'react'
 import { getId, getProps } from './utils.mjs'
 
+/**
+ * A component to render a FreeSewing Path in a pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.stackName - The name of the stack the part belongs to
+ * @param {string} props.partName - The name of the part
+ * @param {string} props.pathName - The name of the path
+ * @param {object} props.path - The path object itself
+ * @param {object} props.settings - The pattern settings object
+ * @param {object} props.components - An object holding the pattern compnents to use
+ * @param {object} props.strings - An object holding translations
+ * @returns {JSX.Element}
+ */
 export const Path = ({ stackName, pathName, path, partName, settings, components, strings }) => {
   // Don't render hidden paths
   if (path.hidden) return null

packages/react/components/Pattern/point.mjs

@@ -2,10 +2,25 @@
 import React from 'react'
 import { withinPartBounds } from './utils.mjs'
 
+/**
+ * A component to render a FreeSewing Point in a pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.stackName - The name of the stack the part belongs to
+ * @param {string} props.partName - The name of the part
+ * @param {string} props.pointName - The name of the point
+ * @param {object} props.point - The point object itself
+ * @param {object} props.components - An object holding the pattern compnents to use
+ * @param {object} props.strings - An object holding translations
+ * @returns {JSX.Element}
+ */
 export const Point = ({ stackName, partName, pointName, part, point, components, strings }) => {
   /*
    * Don't include points outside the part bounding box
    * Unless the `data-render-always` attribute is set
+   *
+   * FIXME: This is undocumented
    */
   if (!withinPartBounds(point, part) && !point.attributes.list['data-render-always']) return null
 

packages/react/components/Pattern/snippet.mjs

@@ -1,8 +1,16 @@
-//  __SDEFILE__ - This file is a dependency for the stand-alone environment
 // eslint-disable-next-line no-unused-vars
 import React from 'react'
 import { getProps } from './utils.mjs'
 
+/**
+ * A component to render a FreeSewing Snippet in a pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {object} props.snippet - The snippet object itself
+ * @param {object} props.settings - The pattern settings object
+ * @returns {JSX.Element}
+ */
 export const Snippet = ({ snippet, settings }) => {
   if (!snippet?.anchor || !snippet.def) return null
   if (!settings[0].complete && !snippet.attributes.list?.['data-force']?.[0]) return null

packages/react/components/Pattern/stack.mjs

@@ -1,6 +1,19 @@
 import React from 'react'
 import { getProps } from './utils.mjs'
 
+/**
+ * A component to render a FreeSewing Stack inside a pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {string} props.stackName - The name of the stack the part belongs to
+ * @param {object} props.stack - The stack object itself
+ * @param {object} props.settings - The pattern settings object
+ * @param {object} props.components - An object holding the pattern components to use
+ * @param {object} props.strings - An object holding translations
+ * @param {object} props.drillProps - An object holding extra props to pass down (used in Xray mode)
+ * @returns {JSX.Element}
+ */
 export const Stack = ({ stackName, stack, settings, components, strings, drillProps }) => {
   const { Group, Part, Grid } = components
 

packages/react/components/Pattern/svg.mjs

@@ -2,6 +2,21 @@
 import React from 'react'
 import { forwardRef } from 'react'
 
+/**
+ * A component to render an SVG tag to hold a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} props.children - The component children, will be rendered inside the SVG tag
+ * @param {strign} [props.className = 'freesewing pattern'] - The CSS classes to apply to the SVG tag
+ * @param {string} [props.embed = true] - Set this to false to output SVG suitable for printing rather than auto-scaled SVG
+ * @param {number} props.heigth - The pattern height in mm
+ * @param {string} [props.locale = en] - The locale/language to use
+ * @param {object} [props.style = {}] - Any additional style to apply to the SVG tag
+ * @param {object} [props.viewBox = false] - Set this to use a custom viewBox attribute rather than the default  0 0 width height
+ * @param {number} props.width - The pattern width in mm
+ * @returns {JSX.Element}
+ */
 export const Svg = forwardRef(
   (
     {

packages/react/components/Pattern/text.mjs

@@ -2,6 +2,15 @@
 import React from 'react'
 import { translateStrings } from './utils.mjs'
 
+/**
+ * A component to render a tspan tag in a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {object} props.point - The point that the text is defined on
+ * @param {object} strings - The translation strings
+ * @returns {JSX.Element}
+ */
 export const TextSpans = ({ point, strings }) => {
   const translated = translateStrings(point.attributes.list['data-text'], strings)
   const text = []
@@ -27,12 +36,31 @@ export const TextSpans = ({ point, strings }) => {
   return text
 }
 
+/**
+ * A component to render a text tag in a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {object} props.point - The point that the text is defined on
+ * @param {object} strings - The translation strings
+ * @returns {JSX.Element}
+ */
 export const Text = ({ point, strings }) => (
   <text x={point.x} y={point.y} {...point.attributes.textProps}>
     <TextSpans point={point} strings={strings} />
   </text>
 )
 
+/**
+ * A component to render a text along a path in a FreeSewing pattern
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {object} props.path - The path that the text is to be rendered along
+ * @param {string} props.pathId - The ID of the path
+ * @param {object} strings - The translation strings
+ * @returns {JSX.Element}
+ */
 export const TextOnPath = ({ path, pathId, strings }) => {
   const textPathProps = {
     xlinkHref: '#' + pathId,

packages/react/components/Pattern/utils.mjs

@@ -1,5 +1,47 @@
 import React from 'react'
 
+/**
+ * A method to generated an ID for an object part of a FreeSewing pattern
+ *
+ * @public
+ * @param {object} parameters - All parameters passed as an object
+ * @param {object} [parameters.settings = {}] - The pattern settings
+ * @param {string} [parameters.stackName = false] - An optional stack name
+ * @param {string} [parameters.partName = false] - An optional part name
+ * @param {string} [parameters.pathName = false] - An optional path name
+ * @param {string} [parameters.pointName = false] - An optional point name
+ * @param {string} [parameters.snippetName = false] - An optional snippet name
+ * @param {string} [parameters.name = false] - An optional name
+ * @param {Part} parameters.part - The part to check the point against
+ * @returns {string}
+ */
+export const getId = ({
+  settings = {},
+  stackName = false,
+  partName = false,
+  pathName = false,
+  pointName = false,
+  snippetName = false,
+  name = false,
+}) => {
+  let id = settings.idPrefix || ''
+  if (stackName) id += `${stackName}-`
+  if (partName) id += `${partName}-`
+  if (pathName) id += `${pathName}-`
+  if (pointName) id += `${pointName}-`
+  if (snippetName) id += `${snippetName}-`
+  if (name) id += name
+
+  return id
+}
+
+/**
+ * A method to extract React props from an classic object
+ *
+ * @public
+ * @param {object} obj - The object to extract props from
+ * @returns {object}
+ */
 export const getProps = (obj) => {
   /** I can't believe it but there seems to be no method on NPM todo this */
   const cssKey = (key) => {
@@ -38,34 +80,15 @@ export const getProps = (obj) => {
   return props
 }
 
-export const withinPartBounds = (point, part) =>
-  point.x >= part.topLeft.x &&
-  point.x <= part.bottomRight.x &&
-  point.y >= part.topLeft.y &&
-  point.y <= part.bottomRight.y
-    ? true
-    : false
-
-export const getId = ({
-  settings = {},
-  stackName = false,
-  partName = false,
-  pathName = false,
-  pointName = false,
-  snippetName = false,
-  name = false,
-}) => {
-  let id = settings.idPrefix || ''
-  if (stackName) id += `${stackName}-`
-  if (partName) id += `${partName}-`
-  if (pathName) id += `${pathName}-`
-  if (pointName) id += `${pointName}-`
-  if (snippetName) id += `${snippetName}-`
-  if (name) id += name
-
-  return id
-}
-
+/**
+ * A method to translate strings for a FreeSewing pattern
+ *
+ * @public
+ * @param {object} [settings = {}] - The pattern settings
+ * @param {array} list - An array with strings (or arrays of strings) to translate
+ * @param {object} [translations = {}] - An object holding translations
+ * @returns {string}
+ */
 export const translateStrings = (list, translations = {}) => {
   let translated = ''
   if (!list) return translated
@@ -80,3 +103,19 @@ export const translateStrings = (list, translations = {}) => {
 
   return translated
 }
+
+/**
+ * A method to determine whether a FreeSewing point is within the bounding box of a FreeSewing part
+ *
+ * @public
+ * @param {Point} point - The point to check
+ * @param {Part} part - The part to check the point against
+ * @returns {boolean}
+ */
+export const withinPartBounds = (point, part) =>
+  point.x >= part.topLeft.x &&
+  point.x <= part.bottomRight.x &&
+  point.y >= part.topLeft.y &&
+  point.y <= part.bottomRight.y
+    ? true
+    : false