feat(markdon): Document missing named exports in core
This commit is contained in:
Joost De Cock
parent
8132ade628
commit
05fd153237
4 changed files with 166 additions and 25 deletions
|
|
@ -15,38 +15,26 @@ Please refer to our [tutorials](/tutorials) to get started.
|
|||
|
||||
</Tip>
|
||||
|
||||
## Core API Documentation
|
||||
|
||||
<ReadMore recurse />
|
||||
|
||||
## Named exports
|
||||
|
||||
<Note>
|
||||
In general, software published under the FreeSewing namespaces prefers named
|
||||
exports over default exports, and the `@freesewing/core` package provides several of them.
|
||||
I have grouped them below in different categories:
|
||||
|
||||
Ever since version 3 of FreeSewing, we use only named exports, and no default exports.
|
||||
|
||||
Refer to [the migration guide](/guides/v3) for more details.
|
||||
|
||||
</Note>
|
||||
|
||||
The `@freesewing/core` package provides the following named exports:
|
||||
- [Constructors](#constructors)
|
||||
- [Constants](#constants)
|
||||
- [Utilities](#utilities)
|
||||
|
||||
### Constructors
|
||||
|
||||
| Named export | Description |
|
||||
| ------------ | ------------|
|
||||
| version | The version of `@freesewing/core` |
|
||||
| Bezier | A re-export of [the bezier-js dependency](https://www.npmjs.com/package/bezier-js) |
|
||||
|
||||
The following named exports are **constructors**:
|
||||
|
||||
<Note>
|
||||
|
||||
You will typically use the `Design()` constructor.
|
||||
The other constructors and utilities below are exported to
|
||||
facilitate unit testing and other specific use cases.
|
||||
|
||||
</Note>
|
||||
|
||||
| Named export | Description |
|
||||
| ------------ | ------------|
|
||||
| `Design` | The [Design](/reference/api/design) constructor |
|
||||
| `Attributes` | The [Attributes](/reference/api/attributes) constructor |
|
||||
| `Design` | The [Design](/reference/api/design) constructor |
|
||||
| `Pattern` | The [Pattern](/reference/api/pattern) constructor |
|
||||
| `Point` | The [Point](/reference/api/point) constructor |
|
||||
| `Path` | The [Path](/reference/api/path) constructor |
|
||||
|
|
@ -54,8 +42,17 @@ facilitate unit testing and other specific use cases.
|
|||
| `Snippet` | The [Snippet](/reference/api/snippet) constructor |
|
||||
| `Store` | The [Store](/reference/api/store) constructor |
|
||||
|
||||
### Constants
|
||||
|
||||
The following named exports are **utility methods**:
|
||||
| Named export | Description |
|
||||
| -------------- | ------------|
|
||||
| `cbqc` | The Cubic Bezier Quarter Circle constant: `0.55191502449351` FIXME: include link |
|
||||
| `hidePresets` | Presets you can use to [configure your part `hide` option](/reference/api/part/config/hide). |
|
||||
| `goldenRatio` | The golden ratio constant: `1.618034` FIXME: include link |
|
||||
| `version` | The version of `@freesewing/core` |
|
||||
|
||||
|
||||
### Utilities
|
||||
|
||||
| Named export | Description |
|
||||
| ------------ | ------------|
|
||||
|
|
@ -64,6 +61,7 @@ The following named exports are **utility methods**:
|
|||
| `beamIntersectsX` | See the [beamIntersectsX](/reference/api/utils/beamintersectsx) documentation |
|
||||
| `beamIntersectsY` | See the [beamIntersectsY](/reference/api/utils//beamintersectsy) documentation |
|
||||
| `beamsIntersect` | See the [beamsIntersect](/reference/api/utils/beamsintersect) documentation |
|
||||
| `Bezier` | A re-export of [the bezier-js dependency](https://www.npmjs.com/package/bezier-js) |
|
||||
| `capitalize` | See the [capitalize](/reference/api/utils/capitalize) documentation |
|
||||
| `circlesIntersect` | See the [circlesIntersect](/reference/api/utils/circlesintersect) documentation |
|
||||
| `curveEdge` | See the [curveEdge](/reference/api/utils/curveedge) documentation |
|
||||
|
|
@ -71,9 +69,12 @@ The following named exports are **utility methods**:
|
|||
| `curveIntersectsY` | See the [curveIntersectsY](/reference/api/utils/curveintersectsy) documentation |
|
||||
| `curvesIntersect` | See the [curvesIntersect](/reference/api/utils/curvesintersect) documentation |
|
||||
| `deg2rad` | See the [deg2rad](/reference/api/utils/deg2rad) documentation |
|
||||
| `generateStackTransform` | See the [generateStackTransform](/reference/api/utils/generatestacktransform) documentation |
|
||||
| `getTransformedBounds` | See the [getTransformedBounds](/reference/api/utils/gettransformedbounds) documentation |
|
||||
| `lineIntersectsCircle` | See the [lineIntersectsCircle](/reference/api/utils/lineintersectscircle) documentation |
|
||||
| `lineIntersectsCurve` | See the [lineIntersectsCurve](/reference/api/utils/lineintersectscurve) documentation |
|
||||
| `linesIntersect` | See the [linesIntersect](/reference/api/utils/linesintersect) documentation |
|
||||
| `mergeIi18n` | See the [mergeI18n](/reference/api/utils/mergei18n) documentation |
|
||||
| `mergeOptions` | See the [mergeOptions](/reference/api/utils/mergeoptions) documentation |
|
||||
| `pctBasedOn` | See the [pctBasedOn](/reference/api/utils/pctbasedon) documentation |
|
||||
| `pointOnBeam` | See the [pointOnBeam](/reference/api/utils/pointonbeam) documentation |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: generateStackTransform
|
||||
---
|
||||
|
||||
This method will generate the SVG transform to implement a given layout configuration on [a stack](/reference/api/stack).
|
||||
|
||||
## Signature
|
||||
|
||||
```js
|
||||
Array generateStackTransform(
|
||||
Number x = 0,
|
||||
Number y = 0,
|
||||
Number rotate = 0,
|
||||
Boolean flipX = false,
|
||||
Boolean flipY = false,
|
||||
Stack stack
|
||||
)
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
The first and second paramter set the value of the *translate transform* along the X and Y axis in millimeter.
|
||||
In other words, it moves the stack.
|
||||
|
||||
The third parameter sets the *rotate transform* in degrees.
|
||||
In other words, it rotates the stack.
|
||||
|
||||
The fourth and fifth parameter flip the part along the X or Y axis respectively.
|
||||
|
||||
<Note compact>
|
||||
This is a low-level method to facilitate intervening in the pattern layout late in the draft process.
|
||||
It is unlikely you will want to use this.
|
||||
</Note>
|
||||
|
||||
22
markdown/dev/reference/api/utils/gettransformedbounds/en.md
Normal file
22
markdown/dev/reference/api/utils/gettransformedbounds/en.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: getTransformedBounds
|
||||
---
|
||||
|
||||
This methods re-calculates the bounding box of an object (a stack or a part) after applying the passed-in transform(s).
|
||||
|
||||
The object passed in should have its `topLeft` and `bottomRight` properties set.
|
||||
It will return on object that with (only) the updated `topLeft` and `bottomRight` properties set.
|
||||
|
||||
## Signature
|
||||
|
||||
```js
|
||||
Object getTransformedBounds(
|
||||
Object stack,
|
||||
Array transforms
|
||||
)
|
||||
```
|
||||
|
||||
<Note compact>
|
||||
This is a low-level method to facilitate intervening in the pattern layout late in the draft process.
|
||||
It is unlikely you will want to use this.
|
||||
</Note>
|
||||
84
markdown/dev/reference/api/utils/mergei18n/en.md
Normal file
84
markdown/dev/reference/api/utils/mergei18n/en.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
title: mergeI18n
|
||||
---
|
||||
|
||||
The `mergeI18n` method merges translation files from different designs.
|
||||
|
||||
When your design re-uses parts from other designs, it should provide
|
||||
translation for those parts and any strings or options they use. Rather than
|
||||
re-creating this content in your own design, you can pull it out of of the
|
||||
design you are using the part from by importing the `i18n` named export, and
|
||||
then use this method to merge it with your own translations.
|
||||
|
||||
## Signature
|
||||
|
||||
```js
|
||||
Object mergeI18n({
|
||||
Array designs,
|
||||
Object options
|
||||
})
|
||||
```
|
||||
|
||||
## Use
|
||||
|
||||
In its simplest form, this method will receive an Array of translation data
|
||||
(typically the `i18n` named export of a design) and merge them:
|
||||
|
||||
```js
|
||||
import { i18n as brianI18n } from '@freesewing/brian'
|
||||
import { i18n as simonI18n } from '../i18n/index.mjs'
|
||||
|
||||
// Merge translations
|
||||
const i18n = mergeI18n([brianI18n, simonI18n])
|
||||
```
|
||||
|
||||
This simple approach is typically what you want when you are extending a design
|
||||
and you are keeping all the parts and options of the design you are extending.
|
||||
In the example above, Simon extends Brian in this way.
|
||||
|
||||
## Configuration
|
||||
|
||||
If you don't want to keep all options or parts, you can further control how the
|
||||
translation data will be merged by passing in a second parameter which is an
|
||||
object holding the configuration that describes how to merge the translation
|
||||
data.
|
||||
|
||||
The configuration object takes 3 top-level properties:
|
||||
|
||||
- `s`: Specifies configuration for how to merge the translation of strings (under `s` in the translation files)
|
||||
- `p`: Specifies configuration for how to merge the part name translations (under `p` in the translation files)
|
||||
- `o`: Specifies configuration for how to merge the option translations (under `p` in the translation files)
|
||||
|
||||
For **each of the `s`, `p`, and `o` keys** you can specificy the followig properties:
|
||||
|
||||
- `drop`: An Array with the keys of entries to not merge (drop). Keys that are not in this array will be merged.
|
||||
- `keep`: An Array with the keys of entries to merge (keep). Keys that are not in this array will not be merged.
|
||||
|
||||
### Example
|
||||
|
||||
```js
|
||||
import { i18n as brianI18n } from '@freesewing/brian'
|
||||
import { i18n as otherI18n } from '../i18n/index.mjs'
|
||||
|
||||
// Merge translations
|
||||
const i18n = mergeI18n(
|
||||
[brianI18n, otherI18n],
|
||||
{
|
||||
p: {
|
||||
keep: ['sleevecap'],
|
||||
},
|
||||
o: {
|
||||
drop: ['waistEase', 'chestEase']
|
||||
}
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
The method will check each key under the `s`, `p`, and `o` top-level keys in the translation files.
|
||||
For each it will:
|
||||
|
||||
- Check whether there is a `drop` array configured. If there is, it will remove the entry if its key is included in the `drop` Array.
|
||||
- Check whether there is a `keep` array configured. If there is, it will remove the entry if its key is not included in the `keep` Array.
|
||||
|
||||
If the entry is not explicitly removed by including it in `drop` or excluding it from a list set in `keep` it will be kept.
|
||||
Loading…
Add table
Add a link
Reference in a new issue