diff --git a/markdown/dev/reference/api/en.md b/markdown/dev/reference/api/en.md index f9fb71d4d66..957b2da4079 100644 --- a/markdown/dev/reference/api/en.md +++ b/markdown/dev/reference/api/en.md @@ -15,38 +15,26 @@ Please refer to our [tutorials](/tutorials) to get started. +## Core API Documentation + + + ## Named exports - +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. - - - -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**: - - - -You will typically use the `Design()` constructor. -The other constructors and utilities below are exported to -facilitate unit testing and other specific use cases. - - - -| 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 | diff --git a/markdown/dev/reference/api/utils/generatestacktransform/en.md b/markdown/dev/reference/api/utils/generatestacktransform/en.md new file mode 100644 index 00000000000..410ad0907a5 --- /dev/null +++ b/markdown/dev/reference/api/utils/generatestacktransform/en.md @@ -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. + + +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. + + diff --git a/markdown/dev/reference/api/utils/gettransformedbounds/en.md b/markdown/dev/reference/api/utils/gettransformedbounds/en.md new file mode 100644 index 00000000000..6c1b8f7b02d --- /dev/null +++ b/markdown/dev/reference/api/utils/gettransformedbounds/en.md @@ -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 +) +``` + + +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. + diff --git a/markdown/dev/reference/api/utils/mergei18n/en.md b/markdown/dev/reference/api/utils/mergei18n/en.md new file mode 100644 index 00000000000..f7b95ef0d98 --- /dev/null +++ b/markdown/dev/reference/api/utils/mergei18n/en.md @@ -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.