VSinerva/freesewing
1
0
Fork 0
Code Activity

fix(dev:docs): Improvements to path-utils plugin and macros

Browse source
This commit is contained in:
Benjamin Fan 2025-05-21 11:43:36 -07:00 • committed by Joost De Cock
parent e7c3447322
commit 7f4c04308c
5 changed files with 106 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

10
sites/dev/docs/reference/macros/hem/readme.mdx
View file

@ -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):

56
sites/dev/docs/reference/macros/join/readme.mdx
View file

@ -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.

47
sites/dev/docs/reference/macros/offset/readme.mdx
View file

@ -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.
:::

47
sites/dev/docs/reference/macros/sa/readme.mdx
View file

@ -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.

10
sites/dev/docs/reference/plugins/path-utils/readme.mdx
View file

@ -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