VSinerva/freesewing
1
0
Fork 0
Code Activity

feat(markdown): New docs for various things

Browse source
This commit is contained in:
joostdecock 2023-10-29 17:20:35 +01:00
parent 9fe93e03ce
commit 6b147d81a0
93 changed files with 1274 additions and 589 deletions
Download patch file Download diff file Expand all files Collapse all files

31
markdown/dev/reference/store-methods/\ Normal file
View file

@ -0,0 +1,31 @@
---
title: removeMacroNodes()
---
Removes nodes generated by macro `id`.
By nodes, we mean paths, points, and so on that have been created by the macro.
When a macro properly uses a combination of `generateMacroIds()` and
`storeMacroIds()`, this method will fully handle its removal.
## Signature
```mjs
Object store.removeMacroNodes(
String id,
macro = store.activeMacro,
part = store.activePart,
)
```
The method takes a (macro) id and removes all nodes created by this macro,
It uses the active macro and part from the store, Or you can pass in `macro` and `part` to not use the active macro or part.
## Example
```mjs
undefined store.removeMacroNodes('macroId')
```

27
markdown/dev/reference/store-methods/en.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Store Methods
---
Store methods are typically provided by plugins and attached to
the store to make them available during the drafting process.
Some of FreeSewing's core library functionality is implemented
as store methods to allow plugins to override this functinoality.
Examples include log handling and pattern layout algorithm.
All store methods below are either provided by plugins we maintain,
or are the default store methods as provided by the core library.
## Signature
```js
null method(object Store, object config)
```
A store method receives as its first parameter [the Store object](/reference/api/store), and
as second parameter a single configuration object for the method.
## Store methods we maintain
<ReadMore list />

26
markdown/dev/reference/store-methods/flag.error/en.md Normal file
View file

@ -0,0 +1,26 @@
---
title: flag.error()
---
This flags information at the `error` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.error`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.error({
title: 'Oh no',
desc: 'Something went very wrong'
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

26
markdown/dev/reference/store-methods/flag.fixme/en.md Normal file
View file

@ -0,0 +1,26 @@
---
title: flag.fixme()
---
This flags information at the `fixme` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.fixme`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.fixme({
title: 'Not yet implemented',
desc: 'Something is unfinished'
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

71
markdown/dev/reference/store-methods/flag.info/en.md Normal file
View file

@ -0,0 +1,71 @@
---
title: flag.info()
---
This flags information at the `info` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.info`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.info({
title: 'flag:expandIsOn.t',
desc: 'flag:expandIsOn.d',
suggest: {
text: 'flag:disable',
icon: 'expand',
update: {
settings: ['expand', null],
},
},
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
The example above is from our implementation, which uses the following properties:
## Configuration
| Property | Type | Description |
| ----------:| ------------------- | ----------- |
| `id` | String | An ID for this flag message. If none is provided, `title` will be used |
| `title` | String | The title of the message |
| `desc` | String | The description of the message |
| `suggest.text` | String | Text to go on the button to implement the suggested configuration change |
| `suggest.icon` | String | Icon name to go on the button to implement the suggested configuration change |
| `suggest.update` | Object | Object describing the changes to apply to the configuration if the user accepts the suggestion |
Note that the `suggest` object is optional. Without it, it will merely display a message to the user.
However, when a suggest key is present, a button will be created that the user can click to accept the suggested changes.
## Example
```js
({ store, part }) => {
store.flag.info({
msg: `aaron:cutNeckBinding`,
notes: ['flag:saUnused', 'flag:partHiddenByExpand'],
replace: {
width: units(w),
length: units(l),
},
suggest: {
text: 'flag:show',
icon: 'expand',
update: {
settings: ['expand', 1],
},
},
})
return part
}
```

26
markdown/dev/reference/store-methods/flag.note/en.md Normal file
View file

@ -0,0 +1,26 @@
---
title: flag.note()
---
This flags information at the `note` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.note`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.note({
title: 'Something good to know',
desc: 'Longer message here'
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

41
markdown/dev/reference/store-methods/flag.preset/en.md Normal file
View file

@ -0,0 +1,41 @@
---
title: flag.preset()
---
The `flag.preset()` method is a way to flag a pre-defined flag object.
There are currently two such pre-defined flags provided by the annotations-plugin:
- `expandIsOn`
- `expandIsOff`
They inform the user about the effect of the `expand` setting on the pattern, when `expand`
is on or off respectively.
## Signature
```js
undefined Store.flag.preset(string preset)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implemntation.
The example above is from our implementation, which uses the following properties:
## Configuration
| Property | Type | Description |
| ----------:| ------------------- | ----------- |
| `preset` | String | The ID of an existing preset |
## Example
```js
({ store, expand, part }) => {
store.flag.preset(expand
? 'expandIsOn'
: 'expandIsOff'
)
return part
}
```

26
markdown/dev/reference/store-methods/flag.tip/en.md Normal file
View file

@ -0,0 +1,26 @@
---
title: flag.tip()
---
This flags information at the `tip` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.tip`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.tip({
title: 'Something good to know',
desc: 'Longer message here'
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

26
markdown/dev/reference/store-methods/flag.warn/en.md Normal file
View file

@ -0,0 +1,26 @@
---
title: flag.warn()
---
This flags information at the `warn` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.warn`.
The core library does nothing with this info, it is merely stored, much like logs are.
However, in our own UI on FreeSewing.org, we use this mechanism to allow
designer to flag information to the user, and even suggest changes to the
pattern configuration.
## Signature
```js
undefined Store.flag.warn({
title: 'Something to be mindful of',
desc: 'Longer message here'
})
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

37
markdown/dev/reference/store-methods/generatemacroids/en.md Normal file
View file

@ -0,0 +1,37 @@
---
title: generateMacroIds()
---
The `generateMacroIds()` store method generates IDs to be used in macros.
It is the recommended way for macros that add nodes to the pattern (by nodes we
mean points, paths and so on) to avoid naming clashes.
## Signature
```mjs
Object store.generateMacroIds(
Array keys,
String id,
macro = store.activeMacro
)
```
The method takes a list of strings, and an ID which is typically the ID passed
to the macro. You can optionally specify the macro name via `macro` although
you almost certainly want to rely on the default behavior which is to load the
active macro name from the store.
## Example
```mjs
const ids = store.generateMacroIds(
[
'start',
'end',
'middle'
],
'macroId'
)
```

30
markdown/dev/reference/store-methods/getmacroids/en.md Normal file
View file

@ -0,0 +1,30 @@
---
title: getMacroIds()
---
Retrieve data for macro IDs generated via [`generateMacroIds()`](/reference/store-methods/generatemacroids) and stored
via [`storeMacroIds()`](/reference/store-methods/storemacroids).
## Signature
```mjs
Object store.getMacroIds(
String id,
macro = store.activeMacro,
part = store.activePart,
)
```
The method takes an id and retrieves the data stored under the macro IDs for the active macro and active part.
Or, if you want to, you can pass in `macro` and `part` to not use the active macro or part.
## Example
```mjs
const ids = store.getMacroIds('macroId')
```
It is a best practice to return the result of this method from your macro.

32
markdown/dev/reference/store-methods/log.debug/en.md Normal file
View file

@ -0,0 +1,32 @@
---
title: log.debug()
---
This is the logging method for logs of `debug` level.
## Signature
```js
undefined Store.log.debug(...data)
```
Like all logging methods, this method is _variadic_.
It will add logs to the array at `store.logs.debug`.
## Example
```js
({ log, part }) => {
log.debug('Hey, I am logging')
log.debug(
'I am logging too',
"But you don't see me make a big deal out if it"
)
return part
}
```
## Notes
You can override the default logging methods in the store with a plugin.

37
markdown/dev/reference/store-methods/log.error/en.md Normal file
View file

@ -0,0 +1,37 @@
---
title: log.error()
---
This is the logging method for logs of `error` level.
<Note>
Logging something at the `error` level will stop FreeSewing from completing the draft of the pattern.
</Note>
## Signature
```js
undefined Store.log.error(...data)
```
Like all logging methods, this method is _variadic_.
It will add logs to the array at `store.logs.error`.
## Example
```js
({ log, part }) => {
log.error('Hey, I am logging')
log.error(
'I am logging too',
"But you don't see me make a big deal out if it"
)
return part
}
```
## Notes
You can override the default logging methods in the store with a plugin.

32
markdown/dev/reference/store-methods/log.info/en.md Normal file
View file

@ -0,0 +1,32 @@
---
title: log.info()
---
This is the logging method for logs of `info` level.
## Signature
```js
undefined Store.log.info(...data)
```
Like all logging methods, this method is _variadic_.
It will add logs to the array at `store.logs.info`.
## Example
```js
({ log, part }) => {
log.info('Hey, I am logging')
log.info(
'I am logging too',
"But you don't see me make a big deal out if it"
)
return part
}
```
## Notes
You can override the default logging methods in the store with a plugin.

32
markdown/dev/reference/store-methods/log.warn/en.md Normal file
View file

@ -0,0 +1,32 @@
---
title: log.warn()
---
This is the logging method for logs of `warn` level (warning).
## Signature
```js
undefined Store.log.warn(...data)
```
Like all logging methods, this method is _variadic_.
It will add logs to the array at `store.logs.warn`.
## Example
```js
({ log, part }) => {
log.warn('Hey, I am logging')
log.warn(
'I am logging too',
"But you don't see me make a big deal out if it"
)
return part
}
```
## Notes
You can override the default logging methods in the store with a plugin.

11
markdown/dev/reference/store-methods/pack/en.md Normal file
View file

@ -0,0 +1,11 @@
---
title: pack()
---
The `pack()` store method is used to automatically layout patterns in the core library.
It is implemented as a store method to allow you to override this method and implement
your own algorithm to generate the layout.
<Fixme>
Document this in more detail
</Fixme>

31
markdown/dev/reference/store-methods/removemacronodes/en.md Normal file
View file

@ -0,0 +1,31 @@
---
title: removeMacroNodes()
---
Removes nodes generated by macro `id`.
By nodes, we mean paths, points, and so on that have been created by the macro.
When a macro properly uses a combination of `generateMacroIds()` and
`storeMacroIds()`, this method will fully handle its removal.
## Signature
```mjs
Object store.removeMacroNodes(
String id,
macro = store.activeMacro,
part = store.activePart,
)
```
The method takes a (macro) id and removes all nodes created by this macro,
It uses the active macro and part from the store, Or you can pass in `macro` and `part` to not use the active macro or part.
## Example
```mjs
undefined store.removeMacroNodes('macroId')
```

29
markdown/dev/reference/store-methods/storemacroids/en.md Normal file
View file

@ -0,0 +1,29 @@
---
title: storeMacroIds()
---
Stores data for macro IDs generated via [`generateMacroIds()`](/reference/store-methods/generatemacroids).
## Signature
```mjs
Object store.storeMacroIds(
String id,
Array ids,
macro = store.activeMacro,
part = store.activePart,
)
```
The method takes a (macro) id and an object of ids and stores it in the store under the active macro and part.
Or, if you want to, you can pass in `macro` and `part` to not use the active macro or part.
## Example
```mjs
const ids = store.getMacroIds('macroId', ids)
```
Storing this data is a requirement to allow removal of macros.

19
markdown/dev/reference/store-methods/unflag.error/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.error()
---
This removes a specific piece of information flagged at the `error` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.error`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.error(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

19
markdown/dev/reference/store-methods/unflag.fixme/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.fixme()
---
This removes a specific piece of information flagged at the `fixme` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.fixme`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.fixme(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

19
markdown/dev/reference/store-methods/unflag.info/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.info()
---
This removes a specific piece of information flagged at the `info` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.info`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.info(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

19
markdown/dev/reference/store-methods/unflag.note/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.note()
---
This removes a specific piece of information flagged at the `note` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.note`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.note(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

17
markdown/dev/reference/store-methods/unflag.preset/en.md Normal file
View file

@ -0,0 +1,17 @@
---
title: unflag.preset()
---
This removes a specific piece of information flagged through the [`flag.preset()`](/reference/store-methods/flag.preset) method.
## Signature
```js
undefined Store.unflag.preset(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
See [flag.preset()](/reference/store-methods/flag.preset) for a list of available presets.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

19
markdown/dev/reference/store-methods/unflag.tip/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.tip()
---
This removes a specific piece of information flagged at the `tip` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.tip`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.tip(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).

19
markdown/dev/reference/store-methods/unflag.warn/en.md Normal file
View file

@ -0,0 +1,19 @@
---
title: unflag.warn()
---
This removes a specific piece of information flagged at the `warn` level.
Info that is flagged is stored in the store under `plugins.plugin-annotations.flags.warn`.
When doing so, you can pass an `id` or -- if no `id` is used, the `title` field will be used as the `id`.
This methods allows you to remove this flagged info by passing said `id` (or `title`).
## Signature
```js
undefined Store.unflag.warn(string id)
```
Since these methods are not part of FreeSewing's core API, what you pass to this method does depend on your own implementation.
For a more detailed example of how we use this, see [flag.info()](/reference/store-methods/flag.info).