diff --git a/sites/dev/docs/reference/macros/hem/readme.mdx b/sites/dev/docs/reference/macros/hem/readme.mdx index ba2d52dc4d8..4f7468dd466 100644 --- a/sites/dev/docs/reference/macros/hem/readme.mdx +++ b/sites/dev/docs/reference/macros/hem/readme.mdx @@ -4,6 +4,14 @@ title: hem The `hem` macro drafts a hem allowance with fold lines. +:::note +##### Not a core-plugins macro + +The `hem` macro is not provided by the [core plugins](/reference/plugins/core), +so you need to load the [path-utils plugin](/reference/plugins/path-utils) +explicitly if you want to use it. +::: + ## Signature ```js @@ -68,7 +76,7 @@ Path macro('hem', { | `prefix` | `'hemMacro'` | `number` | The name prefix used for paths created by this macro. | | `cssClass` | `'fabric'` | `number` | The CSS class added to the fold lines and the hem outline. Should usually match the CSS class for the part outline | -## Detailed Description +## Notes This macro will create the following paths (assuming the default `'hemMacro'` prefix is used): diff --git a/sites/dev/docs/reference/macros/join/readme.mdx b/sites/dev/docs/reference/macros/join/readme.mdx index f9024f7866d..001c9f33b47 100644 --- a/sites/dev/docs/reference/macros/join/readme.mdx +++ b/sites/dev/docs/reference/macros/join/readme.mdx @@ -4,31 +4,19 @@ title: join The `join` macro joins multiple paths together. -Unlike the core `path.join(...)` function, the `join` macro can extend line ends to meet in a sharp corner and will automatically -trim useless path ends when adjacent paths in the array are intersecting. +Unlike the core [`Path.join()`](/reference/api/path/join) function, +the `join` macro can extend line ends to meet in a sharp corner and +will automatically trim useless path ends when adjacent paths in the +array are intersecting. -The join function accepts an array of `Path` objects -(either names in the `paths` array or direct references to `Path` objects). -This array can contain `null` values or hidden paths (created with `path.hide()`) to create gaps. - -:::warning - -Since hidden paths will create gaps in the resulting paths, make sure that all the paths you want to -include in the join are visible before calling the macro. - -You can hide them afterwards again, if needed. +:::note +##### Not a core-plugins macro +The `join` macro is not provided by the [core plugins](/reference/plugins/core), +so you need to load the [path-utils plugin](/reference/plugins/path-utils) +explicitly if you want to use it. ::: -By default, the `join` macro will join the paths in a circular fashion, joining the end -of the last path in the array to the start of the first path, creating a full outline. -If this is not desired, insert a `null` element between paths where you want the gap -(or at the end of the `paths` parameter). - -Note that a `null` value will create a basic gap in the output, -if you instead include a hidden path, this method will still create sharp corners as if the path were present, -but the actual path will be skipped in the output. - ## Signature ```js @@ -72,5 +60,29 @@ Path macro('join', { | Property | Default | Type | Description | | -------: | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paths` | | `array` | An array of pathnames, the names of Paths in the `paths` array to join (you can also reference `Path` objects directly, or insert `null` elements to create gaps) | -| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly without extending them (like `path.join(...)`). | +| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly without extending them (like `Path.join()`). | | `limit` | `null` | `number` | Allows limiting the length of corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`. | + +## Notes + +The `join` macro accepts an array of `Path` objects +(either names in the `paths` array or direct references to `Path` objects). +This array can contain `null` values or hidden paths (created with `Path.hide()`) to create gaps. + +:::warning + +Since hidden paths will create gaps in the resulting paths, make sure that all the paths you want to +include in the join are visible before calling the macro. + +You can hide them afterwards again, if needed. + +::: + +By default, the `join` macro will join the paths in a circular fashion, joining the end +of the last path in the array to the start of the first path, creating a full outline. +If this is not desired, insert a `null` element between paths where you want the gap +(or at the end of the `paths` parameter). + +Note that a `null` value will create a basic gap in the output. +If you instead include a hidden path, this method will still create sharp corners as if the path were present, +but the actual path will be skipped in the output. diff --git a/sites/dev/docs/reference/macros/offset/readme.mdx b/sites/dev/docs/reference/macros/offset/readme.mdx index 22e60f4fac5..1a9b51a3242 100644 --- a/sites/dev/docs/reference/macros/offset/readme.mdx +++ b/sites/dev/docs/reference/macros/offset/readme.mdx @@ -4,25 +4,17 @@ title: offset The `offset` macro will offset and join paths. -Unlike the core `path.join(...)` and `path.offset(...)` functions, the `offset` macro can extend line ends to meet in a sharp corner and will automatically +Unlike the core [`Path.join()`](/reference/api/path/join) and +[`Path.offset()`](/reference/api/path/offset) functions, the `offset` +macro can extend line ends to meet in a sharp corner and will automatically trim useless path ends when adjacent paths in the array are intersecting. -The offset macro accepts an array of `Path` objects with their offset, like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}`. -For the paths in the `p` attribute, you can reference either names in the `paths` array or insert direct references to `Path` objects. -The array can contain `null` values to create gaps (e.g., for cuts on the fold or for other sections that don't need seam allowance). - -By default, the `offset` macro will offset the paths in a circular fashion, joining the end -of the last path in the array to the start of the first path, creating a full outline. -If this is not desired, insert `null` elements where you want to create gaps. - -You can use `offset: 0` to include paths which don't need an additional offset. - -You can use `hidden: true` to omit path segments from the output, but still build corner joins as if they were there. -This can be used for cut-on-fold lines, where no seam allowance is needed. - :::note -To create a seam allowance, prefer the `sa` macro instead of the `offset` macro. It does pretty much the same, -but the `sa` macro defaults to offsetting paths by the user defined seam allowance. +##### Not a core-plugins macro + +The `offset` macro is not provided by the [core plugins](/reference/plugins/core), +so you need to load the [path-utils plugin](/reference/plugins/path-utils) +explicitly if you want to use it. ::: ## Signature @@ -79,6 +71,27 @@ Path macro('offset', { | Property | Default | Type | Description | | -------: | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paths` | | `array` | An array of paths with their offset and visibility. You can use path names in the `paths` array or reference `Path` objects directly, or insert `null` elements to create gaps. | -| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `path.join(...)`) without extending the corners. | +| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `Path.join()`) without extending the corners. | | `limit` | `null` | `number` | Allows limiting the length of extended path corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`. | | `class` | `'offset'` | `string` | CSS class that is automatically applied to the resulting path. | + +## Notes + +The `offset` macro accepts an array of `Path` objects with their offset, like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}`. +For the paths in the `p` attribute, you can reference either names in the `paths` array or insert direct references to `Path` objects. +The array can contain `null` values to create gaps (e.g., for cuts on the fold or for other sections that don't need seam allowance). + +By default, the `offset` macro will offset the paths in a circular fashion, joining the end +of the last path in the array to the start of the first path, creating a full outline. +If this is not desired, insert `null` elements where you want to create gaps. + +You can use `offset: 0` to include paths which don't need an additional offset. + +You can use `hidden: true` to omit path segments from the output, but still build corner joins as if they were there. +This can be used for cut-on-fold lines, where no seam allowance is needed. + +:::note +To create a seam allowance, prefer the [`sa`](/reference/macros/sa) macro +instead of the `offset` macro. It does pretty much the same, +but the `sa` macro defaults to offsetting paths by the user defined seam allowance. +::: diff --git a/sites/dev/docs/reference/macros/sa/readme.mdx b/sites/dev/docs/reference/macros/sa/readme.mdx index 5ba5b434a67..8870c3daf28 100644 --- a/sites/dev/docs/reference/macros/sa/readme.mdx +++ b/sites/dev/docs/reference/macros/sa/readme.mdx @@ -4,24 +4,19 @@ title: sa The `sa` macro will create seam allowance paths. -Unlike the core `path.join(...)` and `path.offset(...)` functions, the `sa` macro can extend line ends to meet in a sharp corner and will automatically -trim useless path ends when adjacent paths in the array are intersecting. +Unlike the core [`Path.join()`](/reference/api/path/join) and +[`Path.offset()`](/reference/api/path/offset) functions, the +`sa` macro can extend line ends to meet in a sharp corner and +will automatically trim useless path ends when adjacent paths +in the array are intersecting. -The sa macro accepts an array of `Path` objects -(either names in the `paths` array or direct references to `Path` objects). -This array can contain `null` values to create gaps (e.g. for cuts on the fold or for other sections that don't need seam allowance). +:::note +##### Not a core-plugins macro -By default, the `sa` macro will sa the paths in a circular fashion, joining the end -of the last path in the array to the start of the first path, creating a full outline. -If this is not desired, insert `null` elements where you want to create gaps. - -You can optionally override the offset and invisibility for individual paths. -To do so, insert an object literal like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}` into the `paths` array. - -You can use `offset: 0` to include paths which have already build-in the seam allowance (e.g. the result of the `hem` macro). - -You can use `hidden: true` to hide path segments from the output, but still build corner joins as if they were there. -This can be used for cut-on-fold lines, where no seam allowance is needed. +The `sa` macro is not provided by the [core plugins](/reference/plugins/core), +so you need to load the [path-utils plugin](/reference/plugins/path-utils) +explicitly if you want to use it. +::: ## Signature @@ -76,7 +71,25 @@ macro('sa', { | Property | Default | Type | Description | | -------: | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paths` | | `array` | An array of paths. You can use path names in the `paths` array or reference `Path` objects directly, or insert `null` elements to create gaps. You can also override offset and visibility for individual paths in the same way as with the `offset` macro. | -| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `path.join(...)`) without extending the corners. | +| `mode` | `'corner'` | `string` | Mode for joining paths. Either `'corner'` or `'cut'`. `'cut'` will join the paths directly (like `Path.join()`) without extending the corners. | | `limit` | `null` | `number` | Allows limiting the length of extended path corners in `'corner'` mode. Prevents overly long joins on very sharp angles. Ignored if `null` or `false`. | | `sa` | (seam allowance) | `number` | Allows you to override the seam allowance used for this macro. Defaults to the standard seam allowance (`sa` parameter in draft function). | | `class` | `'sa'` | `string` | CSS class that is automatically applied to the resulting path. | + +## Notes + +The `sa` macro accepts an array of `Path` objects +(either names in the `paths` array or direct references to `Path` objects). +This array can contain `null` values to create gaps (e.g. for cuts on the fold or for other sections that don't need seam allowance). + +By default, the `sa` macro will sa the paths in a circular fashion, joining the end +of the last path in the array to the start of the first path, creating a full outline. +If this is not desired, insert `null` elements where you want to create gaps. + +You can optionally override the offset and invisibility for individual paths. +To do so, insert an object literal like `{p: 'somePath', offset: 30}` or `{p: ['path1', 'path2'], offset: sa * 3, hidden: true}` into the `paths` array. + +You can use `offset: 0` to include paths which have already build-in the seam allowance (e.g. the result of the `hem` macro). + +You can use `hidden: true` to hide path segments from the output, but still build corner joins as if they were there. +This can be used for cut-on-fold lines, where no seam allowance is needed. diff --git a/sites/dev/docs/reference/plugins/path-utils/readme.mdx b/sites/dev/docs/reference/plugins/path-utils/readme.mdx index 5efdd903991..3c1459d6f2c 100644 --- a/sites/dev/docs/reference/plugins/path-utils/readme.mdx +++ b/sites/dev/docs/reference/plugins/path-utils/readme.mdx @@ -2,7 +2,9 @@ title: plugin-path-utils --- -Published as [@freesewing/plugin-path-utils][1], this plugin provides the [hem](/reference/macros/hem), [sa](/reference/macros/sa), [offset](/reference/macros/offset) and [sa](/reference/macros/join) macros, +Published as [@freesewing/plugin-path-utils][1], this plugin provides the +[hem](/reference/macros/hem), [join](/reference/macros/join), +[offset](/reference/macros/offset), and [sa](/reference/macros/sa) macros, whose main purpose is to make it easier to construct seam allowance paths. ## Installation @@ -25,10 +27,4 @@ import { pathUtilsPlugin } from '@freesewing/plugin-path-utils' import { pluginPathUtils } from '@freesewing/plugin-path-utils' ``` -## Notes - -This plugin is part of the [core-plugins bundle](/reference/plugins/core), -so there is no need to install or import it manually unless you wish to forego -loading of core plugins yet still want to load this plugin. - [1]: https://www.npmjs.com/package/@freesewing/plugin-path-utils