@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_nunjucks.md

@@ -0,0 +1,117 @@
+# _nunjucks
+
+```
+(template: string): string
+(arguments: {template: string, on: object}): string
+```
+
+The `_nunjucks` hydrates a [Nunjucks](https://mozilla.github.io/nunjucks/) template.
+
+If called with a string argument, the template variables are the values in `state`. Otherwise template variables can be specified using the `on` argument.
+
+#### Arguments
+
+###### string
+The template to hydrate. The template variables used are the values in state
+
+###### object
+  - `template: string`: The template to hydrate.
+  - `on: object`: The template variables to use when hydrating the template.
+
+#### Examples
+
+###### Populate a template from values in `state`:
+```yaml
+_nunjucks: Hello {{ name }}
+```
+Returns: `"Hello Steven"` if the value of name in state is `"Steven"`.
+
+###### Populate a markdown template with different values:
+Assuming `get_items` returns:
+```yaml
+- name: Coca Cola
+  description: The original.
+- name: Pepsi
+  description: The same but different.
+```
+
+```yaml
+_nunjucks:
+  template: |
+    ### {{ title }}
+
+    {% for item in item_list %}
+    - {{ item.name }}: {{ item.description }}
+    {% endfor %}
+  on:
+    title: Soft drinks
+    items:
+      _request: get_items
+```
+Returns:
+```markdown
+### Soft drinks
+
+- Coca Cola: The original.
+- Pepsi: The same but different.
+```
+
+###### Make use of the _nunjucks date filter:
+
+```yaml
+_nunjucks:
+  template: {{ date | date('D MMM YYYY') }}
+  on:
+    date:
+      _date: 2022-08-01
+```
+
+Returns:  `"1 Aug 2022"`
+
+The `_nunjucks` date filter formats dates using the [Day.js](https://day.js.org/docs/en/display/format) library.
+
+###### Use the _nunjucks unique filter:
+
+```yaml
+_nunjucks:
+  template: |
+    <div>
+      {% set uniqueArray = array | unique %}
+      {% for item in uniqueArray %}
+        <p>{{ item }}</p>
+      {% endfor %}
+    </div>
+  on:
+    array:
+      - South Africa
+      - New Zealand
+      - Australia
+      - South Africa
+      - Pakistan
+      - India
+      - India
+```
+Returns:
+```html
+<div>
+  <p>South Africa</p>
+  <p>New Zealand</p>
+  <p>Australia</p>
+  <p>Pakistan</p>
+  <p>India</p>
+</div>
+```
+
+###### Make use of the _nunjucks urlQuery filter:
+
+```yaml
+_nunjucks:
+  template: {{ url | urlQuery(params) | safe }}
+  on:
+    url: www.lowdefy.com
+    params:
+      id: 1234
+      type: example
+```
+
+Returns: `"www.lowdefy.com?id=1234&type=example"`

package/content/operators/_object.md

@@ -0,0 +1,253 @@
+# _object
+
+The `_object` operator can be used to run javascript [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) methods.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _object.assign
+
+```
+(objs: obj[]): object
+```
+
+The `_object.assign` method copies the values of one ore more source objects to a target objects. The first object in the arguments array is the target object, and the rest are source objects. Keys in the target object are overwritten. The result of `_object.assign` can be seen as a "shallow-merge" of all the objects in the array, with the values in later objects taken preferentially.
+
+#### Arguments
+
+###### array
+An array of objects.
+
+#### Examples
+
+###### Merge three objects:
+```yaml
+_object.assign:
+  - firstName: Rachel
+    lastName: Green
+    series: Friends
+  - firstName: Monica
+    lastName: Geller
+    address:
+      street: 90 Bedford St
+      city: New York
+      zipCode: '10014'
+      country: US
+  - friends:
+      - Ross Geller
+      - Rachel Green
+      - Chandler Bing
+      - Phoebe Buffay
+      - Joey Tribbiani
+```
+Returns:
+```yaml
+firstName: Monica
+lastName: Geller
+series: Friends
+address:
+  street: 90 Bedford St
+  city: New York
+  zipCode: '10014'
+  country: US
+friends:
+  - Ross Geller
+  - Rachel Green
+  - Chandler Bing
+  - Phoebe Buffay
+  - Joey Tribbiani
+```
+
+## _object.defineProperty
+
+```
+(arguments: {
+  on: object,
+  key: string,
+  descriptor: {
+    value: any,
+    configurable?: boolean,
+    enumerable?: boolean,
+    writable?: boolean
+  }
+}): any
+(arguments: [
+  on: object,
+  key: string,
+  descriptor: {
+    value: any,
+    configurable?: boolean,
+    enumerable?: boolean,
+    writable?: boolean
+  }
+]): any
+```
+
+The `_object.defineProperty` method defines a new property directly on an object, or modifies an existing property on an object, and returns the object. The first object in the arguments array, or the `on` parameter, is the target object to which the property will be applied. The second argument, or the `key` parameter, is the property name or key which will be applied to the target object. The third and last object argument, or the `descriptor` parameter, has serval options to consider, however, for the most common application set the `value` object key to the value that should be applied to the target object key. See [Object.defineProperty](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) for a more detailed description.
+
+> The `_object.defineProperty` method is handy when the `key` to set is variable.
+
+#### Examples
+
+###### Set a value to a object key:
+```yaml
+_object.defineProperty:
+  on:
+    firstName: Rachel
+    series: Friends
+  key: lastName
+  descriptor:
+    value: Green
+```
+Returns:
+```yaml
+firstName: Rachel
+lastName: Green
+series: Friends
+```
+
+## _object.entries
+
+```
+(obj: object): any[]
+```
+
+The `_object.entries` method returns an array with an array of key-values pairs of all the fields in an object.
+
+#### Arguments
+
+###### object
+The object to get entries from.
+
+#### Examples
+
+###### Get the entries of an object:
+```yaml
+_object.entries:
+  firstName: Monica
+  lastName: Geller
+```
+Returns:
+```yaml
+- - firstName
+  - Monica
+- - lastName
+  - Geller
+```
+
+## _object.fromEntries
+
+```
+(array: any[][]): object
+```
+
+The `_object.fromEntries` method creates an object from an array of key-value pairs.
+
+#### Arguments
+
+###### array
+The array of key-value pairs.
+
+#### Examples
+
+###### Get the entries of an object:
+```yaml
+_object.fromEntries:
+  - - firstName
+    - Monica
+  - - lastName
+    - Geller
+```
+Returns:
+```yaml
+firstName: Monica
+lastName: Geller
+```
+
+## _object.keys
+
+```
+(obj: object): string[]
+```
+
+The `_object.keys` method returns an array with the objects keys.
+
+#### Arguments
+
+###### object
+The object to get keys from.
+
+#### Examples
+
+###### Get the keys of an object:
+```yaml
+_object.keys:
+  firstName: Monica
+  lastName: Geller
+  address:
+    street: 90 Bedford St
+    city: New York
+    zipCode: '10014'
+    country: US
+  friends:
+    - Ross Geller
+    - Rachel Green
+    - Chandler Bing
+    - Phoebe Buffay
+    - Joey Tribbiani
+```
+Returns:
+```yaml
+- firstName
+- lastName
+- address
+- friends
+```
+
+## _object.values
+
+```
+(obj: object): any[]
+```
+
+The `_object.values` method returns an array with the values of all the fields in an object.
+
+#### Arguments
+
+###### object
+The object to get values from.
+
+#### Examples
+
+###### Get the values of an object:
+```yaml
+_object.values:
+  firstName: Monica
+  lastName: Geller
+  address:
+    street: 90 Bedford St
+    city: New York
+    zipCode: '10014'
+    country: US
+  friends:
+    - Ross Geller
+    - Rachel Green
+    - Chandler Bing
+    - Phoebe Buffay
+    - Joey Tribbiani
+```
+Returns:
+```yaml
+- Monica
+- Geller
+- street: 90 Bedford St
+  city: New York
+  zipCode: '10014'
+  country: US
+- - Ross Geller
+  - Rachel Green
+  - Chandler Bing
+  - Phoebe Buffay
+  - Joey Tribbiani
+```

package/content/operators/_operator.md

@@ -0,0 +1,33 @@
+# _operator
+
+```
+(arguments: {operator: string, params: any): any
+```
+
+The `_operator` operator evaluates an operator with the given params. This is useful if the operator needs to be chosen dynamically. The `_operator` cannot evaluate itself.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### object
+  - `operator: string`: The name of the operator to evaluate.
+  - `params: any`: The params to give to the operator.
+
+#### Examples
+
+###### Get a value from `urlQuery` if specified, else use the value in `state`:
+```yaml
+_operator:
+  operator:
+    _if:
+      test:
+        _eq:
+          - _state: location_selector
+          - url_query
+      then: _url_query
+      else: _state
+  params:
+    key: field_to_get
+```
+Returns: Value from `urlQuery` if `location_selector == url_query`, else the value from `state`.

package/content/operators/_or.md

@@ -0,0 +1,67 @@
+# _or
+
+```
+(values: any[]): boolean
+```
+
+The `_or` operator performs a logical `or` over an array of inputs, using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules.
+
+It returns true if any of the values in the array are truthy (not `false`, `0`, `null`, `undefined`, or the empty string `""`). If all the values are falsy, it returns `false`.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### array
+An array of values over which to perform a logical or.
+
+#### Examples
+
+###### `true` and `false` values:
+```yaml
+_or:
+  - true
+  - false
+```
+Returns: `true`
+
+###### Array of `true` and `false` values:
+```yaml
+_or:
+  - true
+  - false
+  - false
+  - false
+```
+Returns: `true`
+
+###### Falsy values values:
+```yaml
+_or:
+  - null
+  - 0
+  - ''
+```
+Returns: `false`
+
+###### Truthy values:
+```yaml
+_or:
+  - false
+  - "Hello"
+```
+Returns: `true`
+
+```yaml
+_or:
+  - false
+  - 99
+```
+Returns: `true`
+
+```yaml
+_or:
+  - false
+  - [1,2,3]
+```
+Returns: `true`

package/content/operators/_product.md

@@ -0,0 +1,45 @@
+# _product
+
+```
+(values: any[]): number
+```
+
+The `_product` operator takes the product of the values given as input. If a value is not a number, the value is skipped.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### array
+An array of values to multiply.
+
+#### Examples
+
+###### Two numbers:
+```yaml
+_product:
+  - 3
+  - 4
+```
+Returns: `12`
+
+###### Array of numbers:
+```yaml
+_product:
+  - 1
+  - 2
+  - 3
+  - 4
+```
+Returns: `24`
+
+###### Non-numbers are skipped:
+```yaml
+_product:
+  - 1
+  - null
+  - 3
+  - "four"
+  - 5
+```
+Returns: `15`

package/content/operators/_random.md

@@ -0,0 +1,90 @@
+# _random
+
+```
+(type: string): string | number
+(arguments: {
+  type: string,
+  length?: number,
+  max?: number,
+  min?: number
+}): string | number
+```
+
+The `_random` operator returns a random string or number. The types it accepts are `string`, `integer`, or `float`.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### string
+The type to generate. One of `string`, `integer`, or `float`.
+
+###### object
+  - `type: string`: __Required__ - The type to generate. One of `string`, `integer`, or `float`.
+  - `length: string`: The length of the string to generate if type is `string`. Default is `8`.
+  - `max: number`: The maximum possible number if type is one of `integer` or `float`. Default is `100` if `integer` or `1` if `float`.
+  - `min: number`: The minimum possible number if type is one of `integer` or `float`. Default is `0`.
+
+#### Examples
+
+###### Random string:
+```yaml
+_random: string
+```
+Returns: Random string of length 8.
+
+```yaml
+_random:
+  type: string
+```
+Returns: Random string of length 8.
+
+###### Random integer:
+```yaml
+_random: integer
+```
+Returns: Random integer between 0 and 100 inclusive.
+
+```yaml
+_random:
+  type: integer
+```
+Returns: Random integer between 0 and 100 inclusive.
+
+###### Random float:
+```yaml
+_random: float
+```
+Returns: Random float between 0 and 1 inclusive.
+
+```yaml
+_random:
+  type: float
+```
+Returns: Random float between 0 and 1 inclusive.
+
+###### Random string of length 12:
+```yaml
+_random:
+  type: string
+  length: 12
+```
+Returns: Random string of length 12.
+
+###### Random integer between 1 and 6 (Dice roll):
+```yaml
+_random:
+  type: integer
+  min: 1
+  max: 6
+```
+Returns: Random integer between 1 and 6 inclusive.
+
+###### Random float between 34.2 and 42.89:
+```yaml
+_random:
+  type: float
+  min: 34.2
+  max: 42.89
+```
+Returns: Random float between 34.2 and 42.89 inclusive.

package/content/operators/_ref.md

@@ -0,0 +1,80 @@
+# _ref
+
+```
+(path: string): any
+(arguments: {
+  path?: string,
+  key?: string,
+  resolver?: string,
+  transformer?: string,
+  vars?: object,
+}): any
+(arguments: {
+  module: string,
+  component: string,
+  vars?: object,
+  key?: string,
+}): any
+(arguments: {
+  module: string,
+  menu: string,
+}): object[]
+```
+
+The `_ref` operator can be used to reference a configuration file, in order to split the Lowdefy configuration into multiple files. More information on references and the Lowdefy configuration schema can be found [here](/lowdefy-schema).
+
+> The `_ref` operator is a build time operator: it is evaluated when the app configuration is being built. This means it is not evaluated dynamically as the app is running, and can be used anywhere in the configuration as long as the resulting configuration files are valid YAML.
+
+The `_ref` operator requires a file path to the file to be referenced, relative to the root directory of the project.
+
+If this file is a YAML or JSON file, and has file extension `.yaml`, `.yml`, or `.json`, the file is parsed as YAML/JSON, and the parsed result is included in the configuration.
+
+If this file is a Nunjucks template file, with file extension `.njk`, the file is parsed as a Nunjucks template, using any variables provided in the `vars` argument. If the file extension is `.yaml.njk`, `.yml.njk` or `.json.njk`, the template output is also parsed as YAML/JSON.
+
+If the file is not parsed (for example has an extension like `.txt`, `.md`, or `.html`), the file contents are included in the configuration as a string.
+
+If the referenced file is a YAML or JSON file, the `key` argument can be used to reference a specific key inside that file, instead of the whole file.
+
+###### Variables
+
+Variables defined in the `vars` argument can be accessed in the referenced file using the [`_var`](/_var), and as template variables in Nunjucks files.
+
+###### Resolver
+
+A resolver is a JavaScript function that overwrites the default way configuration files are read from the filesystem. It does not need to read from the filesystem, it could generate a value to return programmatically, or it could fetch the configuration using HTTP (from Github for example). The `resolver` argument should be the file path (relative to the root of the project) to a JavaScript file that exports a resolver function.
+
+The resolver function receives the `path`, `vars`, and a `context` object as arguments. If a resolver function is specified, the `path` argument to the `_ref` operator is optional, and does not need to correspond to a path to a file. If `path` ends with `.yaml`, `.yml`, `.json`, `.njk`, `.yaml.njk`, `.yml.njk`, or `.json.njk`, the returned result will be parsed as YAML/JSON/Nunjucks template.
+
+A default `_ref` resolver can be specified in the `lowdefy.yaml` `cli` section (as `refResolver`), or as a command-line option when running the CLI (as `--ref-resolver`). This resolver will then be used for all references in the app, unless another resolver is specified.
+
+###### Transformer
+
+A transformer is a JavaScript function that receives the result of the `_ref` operator, and its `vars` as arguments. The value returned by this function will be included in the configuration as the final result of the `_ref` operator. The `transformer` argument should be the file path (relative to the root of the project) to a JavaScript file that exports a transformer function.
+
+###### CommonJS and ES Modules
+
+Both [CommonJS](https://nodejs.org/api/modules.html) and [ES Modules](https://nodejs.org/api/esm.html) are supported for in resolver and transformer functions. By default the functions are imported as CommonJs modules, and the function should be exported as a default export (`module.exports = transformer`). Files can also use the `.cjs` file extension to indicate they are CommonJs modules.
+
+To use ES Modules, either use files with `.mjs` file extension, or add a `package.json` in the project directory file with `"type": "module"` set. When using ES Modules, the functions should also be a default export (`export default transformer;`)
+
+#### Arguments
+
+###### string
+The file path to the referenced file, from the root of the project directory.
+
+###### object
+  - `path: string`:  The file path to the referenced file, from the root of the project directory. If no `resolver` is specified, `path` is required.
+  - `key: string`: Only include the content at the specified key, instead of the entire file content. Dot notation is supported. This can only be used with YAML or JSON files.
+  - `resolver: string`: The file path to a JavaScript file, from the root of the project directory, that exports a resolver function.
+  - `transformer: string`: The file path to a JavaScript file, from the root of the project directory, that exports a transformer function.
+  - `vars: object`: An object to be used as variables for the `_var` operator in the referenced file, and as template variables in Nunjucks template files.
+  - `module: string`: The module entry ID (as defined in `lowdefy.yaml` `modules` array). When `module` is specified, `path` is not used — the reference resolves from the module's exported components or menus. See [Modules](/modules).
+  - `component: string`: The component name exported by the module (defined in `module.lowdefy.yaml` `components` array). Used with `module`.
+  - `menu: string`: The menu ID exported by the module (defined in `module.lowdefy.yaml` `menus` array). Used with `module`. Returns the menu's `links` array.
+  - `key: string`: Dot-notation path to extract from the resolved content. Works for both file refs and module component refs.
+
+> When referencing a module component, `vars` are accessed via `_var` inside the component (same as standard `_ref`). Module-level configuration is accessed via [`_module.var`](/_module). Both are available simultaneously.
+
+> Within module content, the `module` field can reference a declared dependency name (from the module's `dependencies` in `module.lowdefy.yaml`). The build resolves abstract names to concrete entry IDs via the dependency wiring. From app-level config, `module` is always a concrete entry ID.
+
+#### Examples