@appsemble/utils 0.20.45 → 0.21.0

package/reference-schemas/remappers/data.js

@@ -0,0 +1,321 @@
+export const dataRemappers = {
+    array: {
+        enum: ['index', 'length'],
+        description: `Get the current array.map’s index or length.
+
+Returns nothing when not in the context of \`array.map’s\`.
+`,
+    },
+    app: {
+        enum: ['id', 'locale', 'url'],
+        description: `Gives actual information about the current app. Using this remapper you will have access to the
+following information:
+
+- \`id\`: App ID
+- \`locale\`: Current locale (user selected language) of the app
+- \`url\`: Base URL of the app
+
+Example:
+
+\`\`\`json
+{
+  "id": 11,
+  "locale": "en",
+  "url": "https://example-app.examplecompany.appsemble.app"
+}
+\`\`\`
+`,
+    },
+    context: {
+        type: 'string',
+        description: `Gets a property from custom context passed by blocks. This property is specific to each block. To
+understand what the context of a certain block does, check the block’s description.
+
+For this example, we will take the [\`table\`](/blocks/@appsemble/table/0.20.39) block. As of now,
+this block provides two options for context: \`index\` and \`repeatedIndex\`. Whenever you click on an
+item in the table, it gives the index of that table row in the associated action.
+
+So with the following example:
+
+\`\`\`yaml
+type: table
+version: 0.20.39
+events:
+  listen:
+    data: contextData
+parameters:
+  fields:
+    - label: Name
+      value: { prop: name }
+      onClick: clickName
+    - label: Age
+      value: { prop: age }
+actions:
+  clickName:
+    remapBefore:
+      context: index
+    type: log
+\`\`\`
+
+Clicking on the first item would log \`0\`, the second item \`1\` and so on.
+`,
+    },
+    history: {
+        type: 'integer',
+        description: `> **Note:** This remapper is explained more in depth in the [History](/docs/remapper/history) page
+
+Gives the data at the history entry at the specified history index. The history at specified index
+is the data that is passed to that action.
+
+\`\`\`yaml
+remapBefore:
+  object.from:
+    title: Most influential bands of all time
+    content: ...
+type: noop # history 0
+onSuccess:
+  type: resource.query # history 1
+  resource: people
+  onSuccess:
+    type: noop # history 2
+    onSuccess:
+      remapBefore:
+        history: 1
+      type: log # history 3
+\`\`\`
+
+Result:
+
+\`\`\`json
+{
+  "title": "Most influential bands of all time",
+  "content": ...
+}
+\`\`\`
+    `,
+    },
+    step: {
+        type: 'string',
+        description: `
+
+While in a loop page, this remapper allows you to get properties from the data at the current index.
+
+\`\`\`yaml
+name: Survey
+type: loop
+actions:
+  onLoad:
+    type: resource.query
+    resource: questions
+foreach:
+  blocks:
+    - type: detail-viewer
+      version: 0.20.39
+      parameters:
+        fields:
+          - label: { step: title }
+\`\`\`
+
+With this example, we load an array of questions that have the \`title\` property. What the \`step\`
+remapper does in this case is show the title of the current question in the loop.
+
+The result of this is a flow page where each page shows the question’s title.
+
+`,
+    },
+    page: {
+        enum: ['data', 'url'],
+        description: `Gives actual information about the current page. This remapper gives access to the following
+information:
+
+- \`data\`: Current page data (FlowPage)
+- \`url\`: Full URL of the current page
+
+Example:
+
+\`\`\`json
+{
+  "data": {
+    "name": "Peter"
+  },
+  "url": "https://example-app.examplecompany.appsemble.app/en/example-page-a"
+}
+\`\`\`
+
+The page data only works in the context of a flow page. Let’s say you have a
+[“FlowPage”](/docs/reference/app#-flow-page-definition) type with multiple subpages. Whenever you
+navigate to the next page it adds the data from that page to the flow page’s data. The page remapper
+allows you to access this cumulative data.
+
+The following page definition shows a page definition for a flow page where the user has to fill in
+some user information. For each subpage the result of \`page: data\` is shown.
+
+
+\`\`\`yaml
+name: PageDataFlow
+type: flow
+steps:
+  # page: data = {}
+  - blocks:
+      - type: form
+        version: 0.20.39
+        parameters:
+          fields:
+            - name: name
+              type: string
+        actions:
+          onSubmit:
+            type: flow.next
+  # page: data = { name: "Peter" }
+  - blocks:
+      - type: form
+        version: 0.20.39
+        parameters:
+          fields:
+            - name: age
+              type: string
+        actions:
+          onSubmit:
+            type: flow.next
+  # page: data = { name: "Peter", age: "47" }
+  - blocks:
+      - type: data-loader
+        version: 0.20.39
+        actions:
+          onLoad:
+            remapBefore:
+              page: data
+            type: log
+\`\`\`
+
+The result of the final page’s log would then be:
+
+\`\`\`json
+{
+  "name": "Peter",
+  "age": "47"
+}
+\`\`\`
+
+`,
+    },
+    prop: {
+        anyOf: [
+            { type: 'string' },
+            { type: 'integer' },
+            { type: 'array', minItems: 1, items: { anyOf: [{ type: 'string' }, { type: 'integer' }] } },
+        ],
+        description: `Gets the chosen property from an object.
+
+\`\`\`json
+{
+  "name": "John",
+  "age": 52
+}
+\`\`\`
+
+\`\`\`yaml
+prop: name
+\`\`\`
+
+Result:
+
+\`\`\`json
+"John"
+\`\`\`
+`,
+    },
+    root: {
+        enum: [null],
+        description: `Gets the input data as it was initially passed to the remapper function.
+
+\`\`\`yaml
+type: resource.query
+resource: people
+query:
+  object.from:
+    $filter: city eq 'Eindhoven'
+onSuccess:
+  remapBefore:
+    object.from:
+      name: Residents of Eindhoven
+      people:
+        root: null
+\`\`\`
+
+Result:
+
+\`\`\`json
+{
+  "name": "Residents of Eindhoven",
+  "people": [
+    {
+      "name": ...,
+      "city": "Eindhoven"
+    },
+    ...
+  ]
+}
+\`\`\`
+    `,
+    },
+    static: {
+        description: 'Use a static value.',
+    },
+    translate: {
+        type: 'string',
+        description: `> **Note:** This is explained much more in depth at [Translating](/docs/03-guide/translating)
+
+This remapper allows you to easily add translations to your app. To make this remapper work, replace
+any static text with \`translate: {name}\`. Then, in your app’s Translations page pick the language
+you want to translate. You will see a list of names with input text below. Translations you manually
+put in the app using the \`translate\` remapper are found under “Custom messages”.
+
+After putting the translation in, any user that logs in with that language selected will see the
+translated message.
+
+Example:
+
+\`\`\`yaml
+type: detail-viewer
+version: 0.20.39
+parameters:
+  fields:
+    - label: { translate: weatherTitle }
+      value: { translate: weatherBody }
+\`\`\`
+
+`,
+    },
+    user: {
+        enum: ['sub', 'name', 'email', 'email_verified', 'picture', 'profile', 'locale'],
+        description: `
+> **Note:** For this remapper to work, the user that activated the remapper has to be logged in to
+> the app
+
+Provides some fields of user information taken from the OpenID user info. These fields are:
+
+- \`email\`: User’s **primary** email address
+- \`email_verified\`: Whether the user’s primary email address is verified or not (\`boolean\`)
+- \`locale\`: The user’s default language [\`BCP47\`](https://en.wikipedia.org/wiki/IETF_language_tag)
+  language tag (ex. \`en\`) (Broken)
+- \`name\`: The user’s name
+- \`picture\`: Full URL to the user’s profile picture web address
+- \`sub\`: The user’s identifier
+
+Example:
+
+\`\`\`json
+{
+  "email": "example@hotmail.nl",
+  "email_verified": true,
+  "locale": "en",
+  "name": "Test User",
+  "picture": "https://www.gravatar.com/avatar/f46b82357ce29bcd1099915946cda468?s=128&d=mp",
+  "sub": "5c6270e2-ad31-414f-bcab-6752a2c4dcfd"
+}
+\`\`\`
+    `,
+    },
+};
+//# sourceMappingURL=data.js.map

package/reference-schemas/remappers/dates.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const dateRemappers: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject>;

package/reference-schemas/remappers/dates.js

@@ -0,0 +1,38 @@
+export const dateRemappers = {
+    'date.add': {
+        type: 'string',
+        description: 'Add the specified value to a given date.',
+    },
+    'date.format': {
+        enum: [null],
+        description: 'Format a date according to rfc3339.',
+    },
+    'date.now': {
+        enum: [null],
+        description: 'Returns the current date.',
+    },
+    'date.parse': {
+        type: 'string',
+        description: `Convert a string to a date using a given format.
+
+For example:
+\`\`\`yaml
+- static: 02/11/2014     # The date string to parse
+- date.parse: MM/dd/yyyy # The given format to parse the date with
+            # => Tue Feb 11 2014 00:00:00
+\`\`\`
+
+See [date-fns](https://date-fns.org/v2.29.3/docs/parse) for the supported formats.
+
+Leaving the format empty will try to parse the date using the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+For example:
+\`\`\`yaml
+date.parse:
+- static: 2014-02-11T11:30:30 # The date string to parse
+- date.parse: ''              # The given format to parse the date with
+                      # => Tue Feb 11 2014 11:30:30
+\`\`\`
+`,
+    },
+};
+//# sourceMappingURL=dates.js.map

package/reference-schemas/remappers/history.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const historyRemappers: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject>;

package/reference-schemas/remappers/history.js

@@ -0,0 +1,246 @@
+export const historyRemappers = {
+    'from.history': {
+        type: 'object',
+        required: ['index', 'props'],
+        description: `Creates a new object based on the specified properties in the given history index. This can be very
+useful when you want to combine two sources of data together. It’s also cleaner than separately
+using \`object.from\` together with \`history\`.
+
+In the following example, you can see why this might be handy. Let’s say you get the details about a
+concert from a source like an action or a block. You have this information and then you want to get
+some additional data like the attendees of the concert. With \`from.history\` you can combine the
+older data like the name and date, and add the new \`attendees\` data. The result will be an object
+with this combined data.
+
+History index 1:
+
+\`\`\`json
+{
+  "name": "Rolling stones at Amsterdam Arena",
+  "artist": "Rolling Stones",
+  "location": "Amsterdam Arena",
+  "date": "07-07-2022",
+  "price": 120
+}
+\`\`\`
+
+Input:
+
+\`\`\`json
+[ .. ]
+\`\`\`
+
+\`\`\`yaml
+object.from:
+  concertDetails:
+    from.history:
+      index: 1
+      props:
+        name: { prop: name }
+        date: { prop: date }
+        attendees: { root: null }
+\`\`\`
+
+Result:
+
+\`\`\`json
+{
+  "concertDetails": {
+    "attendees": [ .. ],
+    "date": "07-07-2022",
+    "name": "Rolling stones at Amsterdam Arena"
+  }
+}
+\`\`\`
+`,
+        additionalProperties: false,
+        properties: {
+            index: {
+                type: 'integer',
+                description: `The index of the history stack item to assign.
+
+0 is the index of the first item in the history stack.
+`,
+            },
+            props: {
+                description: 'Predefined mapper keys to choose what properties to apply.',
+                additionalProperties: {
+                    $ref: '#/components/schemas/RemapperDefinition',
+                },
+            },
+        },
+    },
+    'assign.history': {
+        type: 'object',
+        required: ['index', 'props'],
+        description: `Assigns properties from the specified history stack index to an existing object.
+Similarly to the \`from.history\` remapper, this allows you to get a property from a place in the
+history and give it to a new object. The only difference here is that you are not creating an
+entirely new object, but you are taking an existing object and assigning new values to it.
+
+So, we can take the example from \`from.history\` and flip it.
+
+History index 1:
+
+\`\`\`json
+{
+  "peopleAmount": 3000
+}
+\`\`\`
+
+Input:
+
+\`\`\`json
+{
+  "name": "Rolling stones at Amsterdam Arena",
+  "artist": "Rolling Stones",
+  "location": "Amsterdam Arena",
+  "date": "07-07-2022",
+  "price": 120
+}
+\`\`\`
+
+\`\`\`yaml
+object.from:
+  concertDetails:
+    assign.history:
+      index: 1
+      props:
+        attendees: { prop: peopleAmount }
+\`\`\`
+
+Result:
+
+\`\`\`json
+{
+  "concertDetails": {
+    "name": "Rolling stones at Amsterdam Arena",
+    "artist": "Rolling Stones",
+    "location": "Amsterdam Arena",
+    "date": "07-07-2022",
+    "price": 120,
+    "attendees": 3000
+  }
+}
+\`\`\`
+`,
+        additionalProperties: false,
+        properties: {
+            index: {
+                type: 'integer',
+                description: `The index of the history stack item to assign.
+
+0 is the index of the first item in the history stack.
+`,
+            },
+            props: {
+                description: 'Predefined mapper keys to choose what properties to assign.',
+                additionalProperties: {
+                    $ref: '#/components/schemas/RemapperDefinition',
+                },
+            },
+        },
+    },
+    'omit.history': {
+        type: 'object',
+        required: ['index', 'keys'],
+        description: `Assigns properties from the specified history stack index to the current value and excludes the
+given properties.
+
+Similarly to the other history remappers, this gives you the data from a certain point in the
+history stack and allows you to modify it before adding to the current value. This one, however,
+allows you to take the complete specified history data and omit certain values.
+
+This remapper can be extremely helpful for re-using data you got before in the history stack while
+filtering certain properties.
+
+For example, let’s say you have the information for a concert but don’t want normal users to see
+sensitive data about it. Using \`omit.history\` you can take this concert data but exclude the
+sensitive parts.
+
+History index 1:
+
+\`\`\`json
+{
+  "name": "Rolling stones at Amsterdam Arena",
+  "artist": "Rolling Stones",
+  "location": "Amsterdam Arena",
+  "date": "07-07-2022",
+  "bandPasswords": [ .. ],
+  "bankDetailsAttendees": [ .. ]
+}
+\`\`\`
+
+Input:
+
+\`\`\`json
+[ .. ]
+\`\`\`
+
+\`\`\`yaml
+object.from:
+  concertDetails:
+    omit.history:
+      index: 1
+      keys:
+        - bandPasswords
+        - bankDetailsAttendees
+\`\`\`
+
+Result:
+
+\`\`\`json
+{
+  "concertDetails": {
+    "name": "Rolling stones at Amsterdam Arena",
+    "artist": "Rolling Stones",
+    "location": "Amsterdam Arena",
+    "date": "07-07-2022",
+    "attendees": [ .. ]
+  }
+}
+\`\`\`
+`,
+        additionalProperties: false,
+        properties: {
+            index: {
+                type: 'integer',
+                description: `The index of the history stack item to assign.
+
+0 is the index of the first item in the history stack.
+`,
+            },
+            keys: {
+                description: `Exclude properties from the history stack item, based on the given object keys.
+
+Nested properties can be excluded using arrays of keys.
+
+For example:
+\`\`\`yaml
+omit.history:
+  index: 0
+  keys:
+    - foo   # Excludes the property foo
+    - - bar # Excludes the property baz inside of bar
+      - baz
+\`\`\`
+`,
+                type: 'array',
+                items: {
+                    minItems: 1,
+                    anyOf: [
+                        { type: 'string' },
+                        {
+                            type: 'array',
+                            minItems: 2,
+                            items: {
+                                type: 'string',
+                            },
+                        },
+                    ],
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=history.js.map

package/reference-schemas/remappers/index.d.ts

@@ -0,0 +1,9 @@
+export * from './arrays.js';
+export * from './conditionals.js';
+export * from './data.js';
+export * from './dates.js';
+export * from './history.js';
+export * from './objects.js';
+export * from './randoms.js';
+export * from './strings.js';
+export * from './unsorted.js';

package/reference-schemas/remappers/index.js

@@ -0,0 +1,10 @@
+export * from './arrays.js';
+export * from './conditionals.js';
+export * from './data.js';
+export * from './dates.js';
+export * from './history.js';
+export * from './objects.js';
+export * from './randoms.js';
+export * from './strings.js';
+export * from './unsorted.js';
+//# sourceMappingURL=index.js.map

package/reference-schemas/remappers/objects.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const objectRemappers: Record<string, OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject>;