@nordcraft/core 1.0.78 → 1.0.80

package/src/component/schemas/api-schema.ts

@@ -0,0 +1,255 @@
+import { z } from 'zod'
+import type {
+  ApiParserMode,
+  ApiRequest,
+  ComponentAPI,
+  LegacyComponentAPI,
+} from '../../api/apiTypes'
+import { EventModelSchema } from './event-schema'
+import { FormulaSchema } from './formula-schema'
+import { MetadataSchema } from './zod-schemas'
+
+// API Models
+const ApiMethodSchema: z.ZodType<any> = z
+  .enum(['GET', 'POST', 'DELETE', 'PUT', 'PATCH', 'HEAD', 'OPTIONS'])
+  .describe('HTTP method for the API request.')
+
+const ApiParserModeSchema: z.ZodType<ApiParserMode> = z
+  .enum(['auto', 'text', 'json', 'event-stream', 'json-stream', 'blob'])
+  .describe('Available modes for parsing API responses.')
+
+const RedirectStatusCodes = {
+  '300': 300,
+  '301': 301,
+  '302': 302,
+  '303': 303,
+  '304': 304,
+  '307': 307,
+  '308': 308,
+}
+const RedirectStatusCodeSchema: z.ZodType<any> = z
+  .enum(RedirectStatusCodes)
+  .describe('HTTP status code to use for the redirect.')
+
+const ApiRequestSchema: z.ZodType<ApiRequest> = z
+  .object({
+    '@nordcraft/metadata': MetadataSchema.nullish().describe(
+      'Metadata for the API request',
+    ),
+    version: z
+      .literal(2)
+      .describe('Version of the API request schema. This should always be 2.'),
+    name: z.string().describe('Name of the API request.'),
+    type: z.enum(['http', 'ws']).describe('Type of the API request.'),
+    method: ApiMethodSchema.nullish().describe(
+      'HTTP method for the API request.',
+    ),
+    url: FormulaSchema.nullish().describe(
+      'Base URL for the API request. Params and query strings are added when this API is called.',
+    ),
+    service: z
+      .string()
+      .nullish()
+      .describe(
+        'Name of the service to use for the API request. Only Services defined in the project can be used here.',
+      ),
+    servicePath: z
+      .string()
+      .nullish()
+      .describe(
+        'File path to the service definition. If service is defined, servicePath must also be defined.',
+      ),
+    inputs: z
+      .record(
+        z.string().describe('Name of the input'),
+        z
+          .object({
+            formula: FormulaSchema.nullish(),
+          })
+          .describe('Formula evaluating to the input value.'),
+      )
+      .describe(
+        'Inputs to the API request. Inputs have a default value that can be overridden when the API is started from a workflow. Inputs can be used inside any Formula in the API request definition.',
+      ),
+    path: z
+      .record(
+        z.string().describe('Name of the path segment'),
+        z.object({
+          formula: FormulaSchema.describe(
+            'Formula evaluating to the value of the path segment',
+          ),
+          index: z
+            .number()
+            .describe('Index defining the order of the path segments.'),
+        }),
+      )
+      .nullish()
+      .describe('Path segments to include in the API request.'),
+    queryParams: z
+      .record(
+        z.string().describe('Name of the query parameter'),
+        z.object({
+          formula: FormulaSchema.describe(
+            'Formula evaluating to the value of the query parameter',
+          ),
+          enabled: FormulaSchema.nullish().describe(
+            'Formula evaluating to whether the query parameter is included or not. If included it should evaluate to true.',
+          ),
+        }),
+      )
+      .nullish()
+      .describe('Query parameters to include in the API request.'),
+    headers: z
+      .record(
+        z.string().describe('Name of the header'),
+        z.object({
+          formula: FormulaSchema.describe(
+            'Formula evaluating to the header value',
+          ),
+          enabled: FormulaSchema.nullish().describe(
+            'Formula evaluating to whether the header is included or not. If included it should evaluate to true.',
+          ),
+        }),
+      )
+      .nullish()
+      .describe('Headers to include in the API request.'),
+    body: FormulaSchema.nullish().describe('Body of the API request.'),
+    autoFetch: FormulaSchema.nullish().describe(
+      'Indicates if the API request should be automatically fetched when the component or page loads.',
+    ),
+    client: z
+      .object({
+        parserMode: ApiParserModeSchema.describe(
+          'Defines how the API response should be parsed.',
+        ),
+        credentials: z
+          .enum(['include', 'same-origin', 'omit'])
+          .nullish()
+          .describe(
+            'Indicates whether credentials such as cookies or authorization headers should be sent with the request.',
+          ),
+        debounce: z
+          .object({ formula: FormulaSchema })
+          .nullish()
+          .describe(
+            'Debounce time in milliseconds for the API request. Useful for limiting the number of requests made when inputs change rapidly.',
+          ),
+        onCompleted: EventModelSchema.nullish().describe(
+          'Event triggered when the API request completes successfully.',
+        ),
+        onFailed: EventModelSchema.nullish().describe(
+          'Event triggered when the API request fails. This is also triggered when the isError formula evaluates to true.',
+        ),
+        onMessage: EventModelSchema.nullish().describe(
+          'Event triggered when a message is received from the API. Only applicable for WebSocket and streaming APIs.',
+        ),
+      })
+      .nullish()
+      .describe('Client-side settings for the API request.'),
+    server: z
+      .object({
+        proxy: z
+          .object({
+            enabled: z
+              .object({ formula: FormulaSchema })
+              .describe(
+                'Indicates if the API request should be proxied through the Nordcraft backend server. This is useful for avoiding CORS issues or hiding sensitive information in the request. It is also useful if the request needs access to http-only cookies.',
+              ),
+            useTemplatesInBody: z
+              .object({ formula: FormulaSchema })
+              .nullish()
+              .describe(
+                'Indicates if templates in the body should be processed when proxying the request. A template could be a http-only cookie that needs to be included in the proxied request. Enabling this flag will ensure that templates in the body are processed before sending the proxied request.',
+              ),
+          })
+          .nullish()
+          .describe('Proxy settings for the API request.'),
+        ssr: z
+          .object({
+            enabled: z
+              .object({ formula: FormulaSchema })
+              .nullish()
+              .describe(
+                'Indicates if server-side rendering is enabled for this API request. This means the API will be executed on the server during the initial page load. Note: This can have performance implications for the loading of a page on slow APIs.',
+              ),
+          })
+          .nullish()
+          .describe('Server-side rendering settings.'),
+      })
+      .nullish()
+      .describe('Server-side settings for the API request.'),
+    timeout: z
+      .object({ formula: FormulaSchema })
+      .nullish()
+      .describe('Timeout for the API request in milliseconds.'),
+    hash: z.object({ formula: FormulaSchema }).nullish(),
+    isError: z
+      .object({ formula: FormulaSchema })
+      .nullish()
+      .describe(
+        'Indicates if the last API response was an error. Useful for forcing a response to be treated as an error even if status code is 200.',
+      ),
+    redirectRules: z
+      .record(
+        z.string().describe('The key of the redirect rule.'),
+        z
+          .object({
+            formula: FormulaSchema.describe(
+              'Formula evaluating to the URL. If a URL is returned, the redirect will be triggered. If null is returned, no redirect will happen.',
+            ),
+            index: z
+              .number()
+              .describe('Index defining the order of the redirect rules.'),
+            statusCode: RedirectStatusCodeSchema.nullish().describe(
+              'HTTP status code to use for the redirect.',
+            ),
+          })
+          .describe('Defines a single redirect rule.'),
+      )
+      .nullish()
+      .describe(
+        'Rules for redirecting based on response data. The key is a unique identifier for the rule.',
+      ),
+  })
+  .describe('Schema defining an API request from a component or a page.')
+
+const LegacyComponentAPISchema: z.ZodType<LegacyComponentAPI> = z
+  .object({
+    type: z.literal('REST'),
+    name: z.string(),
+    method: z.enum(['GET', 'POST', 'DELETE', 'PUT']),
+    url: FormulaSchema.nullish(),
+    path: z.array(z.object({ formula: FormulaSchema })).nullish(),
+    queryParams: z
+      .record(
+        z.string(),
+        z.object({
+          name: z.string(),
+          formula: FormulaSchema,
+        }),
+      )
+      .nullish(),
+    headers: z
+      .union([z.record(z.string(), FormulaSchema), FormulaSchema])
+      .nullish(),
+    body: FormulaSchema.nullish(),
+    autoFetch: FormulaSchema.nullish(),
+    proxy: z.boolean().nullish(),
+    debounce: z.number().nullish(),
+    throttle: z.number().nullish(),
+    onCompleted: EventModelSchema.nullish(),
+    onFailed: EventModelSchema.nullish(),
+    auth: z
+      .object({
+        type: z.enum(['Bearer id_token', 'Bearer access_token']),
+      })
+      .nullish(),
+  })
+  .describe(
+    'Legacy API schema for backward compatibility. Never use this for new APIs.',
+  )
+
+export const ComponentAPISchema: z.ZodType<ComponentAPI> = z.union([
+  LegacyComponentAPISchema,
+  ApiRequestSchema,
+])

package/src/component/schemas/attribute-schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+import type { ComponentAttribute } from '../component.types'
+import { MetadataSchema, SCHEMA_DESCRIPTIONS } from './zod-schemas'
+
+export const ComponentAttributeSchema: z.ZodType<ComponentAttribute> = z
+  .object({
+    '@nordcraft/metadata': MetadataSchema.nullish().describe(
+      SCHEMA_DESCRIPTIONS.metadata('component attribute'),
+    ),
+    name: z.string().describe('Name of the component attribute'),
+    testValue: z
+      .any()
+      .describe(SCHEMA_DESCRIPTIONS.testData('component attribute')),
+  })
+  .describe('Schema for a component attribute.')

package/src/component/schemas/component-schema.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod'
+import type { Component, PageComponent } from '../component.types'
+import { ActionModelSchema } from './action-schema'
+import { ComponentAPISchema } from './api-schema'
+import { ComponentAttributeSchema } from './attribute-schema'
+import { ComponentContextSchema } from './context-schema'
+import { ComponentEventSchema } from './event-schema'
+import { ComponentFormulaSchema } from './formula-schema'
+import { NodeModelSchema } from './node-schema'
+import { RouteSchema } from './route-schema'
+import { ComponentVariableSchema } from './variable-schema'
+import { ComponentWorkflowSchema } from './workflow-schema'
+import { SCHEMA_DESCRIPTIONS } from './zod-schemas'
+
+const commonComponentSchema = (type: 'component' | 'page') =>
+  z
+    .object({
+      name: z.string().describe(`Name of the ${type}`),
+      exported: z
+        .boolean()
+        .nullish()
+        .describe(
+          `Whether the ${type} is exported in a package project for use in other projects. Do not change this value. It should be managed by the user.`,
+        ),
+      nodes: z
+        .record(z.string(), NodeModelSchema)
+        .nullish()
+        .describe(
+          `All nodes in the ${type}, indexed by their unique IDs. Nodes represent HTML elements, text, slots, or ${type === 'component' ? 'other components' : 'components'}. They defined the UI structure of the ${type}.`,
+        ),
+      variables: z
+        .record(z.string(), ComponentVariableSchema)
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.variables(type)),
+      formulas: z
+        .record(z.string(), ComponentFormulaSchema)
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.formulas(type)),
+      workflows: z
+        .record(z.string(), ComponentWorkflowSchema)
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.workflows(type)),
+      apis: z
+        .record(z.string(), ComponentAPISchema)
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.apis(type)),
+      events: z
+        .array(ComponentEventSchema)
+        .nullish()
+        .describe(
+          'All events this the component can emit. Events allow the component to communicate with its parent or other components. They can be triggered via actions.',
+        ),
+      contexts: z
+        .record(z.string(), ComponentContextSchema)
+        .nullish()
+        .describe(
+          'Defines which contexts this component is subscribed to. Contexts allow the component to access formulas and workflows from other components, enabling reusability and modular design.',
+        ),
+      onLoad: z
+        .object({
+          trigger: z.literal('Load'),
+          actions: z.array(ActionModelSchema),
+        })
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.onLoad(type)),
+      onAttributeChange: z
+        .object({
+          trigger: z.literal('Attribute change'),
+          actions: z.array(ActionModelSchema),
+        })
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.onAttributeChange(type)),
+    })
+    .describe('Schema defining a reusable Nordcraft component.')
+
+export const ComponentSchema: z.ZodType<Component> = commonComponentSchema(
+  'component',
+).extend({
+  attributes: z
+    .record(z.string(), ComponentAttributeSchema)
+    .nullish()
+    .describe(
+      'All attributes that can be passed into the component when it is used. Attributes allow for customization and configuration of the component instance. When the value of an attribute changes, any formulas depending on it will automatically recalculate and the onAttributeChange lifecycle event is triggered.',
+    ),
+})
+
+export const PageSchema: z.ZodType<PageComponent> = commonComponentSchema(
+  'page',
+).extend({
+  attributes: z
+    .object({})
+    .nullish()
+    .describe(
+      'Attributes for the page (currently none). Should always be an empty object.',
+    ),
+  route: RouteSchema.describe(
+    'Route information for the page, including path segments, query parameters, and metadata such as title and description.',
+  ),
+})
+
+const shallowCommonComponentSchema = (type: 'component' | 'page') =>
+  z
+    .object({
+      name: z.string().describe(`Name of the ${type}`),
+      exported: z
+        .boolean()
+        .nullish()
+        .describe(
+          `Whether the ${type} is exported in a package project for use in other projects. Do not change this value. It should be managed by the user.`,
+        ),
+      nodes: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(
+          `All nodes in the ${type}, indexed by their unique IDs. Nodes represent HTML elements, text, slots, or ${type === 'component' ? 'other components' : 'components'}. They defined the UI structure of the ${type}.`,
+        ),
+      variables: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.variables(type)),
+      formulas: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.formulas(type)),
+      workflows: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.workflows(type)),
+      apis: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.apis(type)),
+      events: z
+        .array(z.any())
+        .nullish()
+        .describe(
+          'All events this the component can emit. Events allow the component to communicate with its parent or other components. They can be triggered via actions.',
+        ),
+      contexts: z
+        .record(z.string(), z.any())
+        .nullish()
+        .describe(
+          'Defines which contexts this component is subscribed to. Contexts allow the component to access formulas and workflows from other components, enabling reusability and modular design.',
+        ),
+      onLoad: z.any().nullish().describe(SCHEMA_DESCRIPTIONS.onLoad(type)),
+      onAttributeChange: z
+        .any()
+        .nullish()
+        .describe(SCHEMA_DESCRIPTIONS.onAttributeChange(type)),
+    })
+    .describe('Schema defining a reusable Nordcraft component.')
+
+export const ShallowComponentSchema: z.ZodType<Component> =
+  shallowCommonComponentSchema('component').extend({
+    attributes: z
+      .record(z.string(), z.any())
+      .nullish()
+      .describe(
+        'All attributes that can be passed into the component when it is used. Attributes allow for customization and configuration of the component instance. When the value of an attribute changes, any formulas depending on it will automatically recalculate and the onAttributeChange lifecycle event is triggered.',
+      ),
+  })
+
+export const ShallowPageSchema: z.ZodType<PageComponent> =
+  shallowCommonComponentSchema('page').extend({
+    attributes: z
+      .any()
+      .nullish()
+      .describe(
+        'Attributes for the page (currently none). Should always be an empty object.',
+      ),
+    route: RouteSchema.describe(
+      'Route information for the page, including path segments, query parameters, and metadata such as title and description.',
+    ),
+  })

package/src/component/schemas/context-schema.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod'
+import type { ComponentContext } from '../component.types'
+
+export const ComponentContextSchema: z.ZodType<ComponentContext> = z
+  .object({
+    package: z
+      .string()
+      .nullish()
+      .describe('Package name of the component providing the context'),
+    componentName: z
+      .string()
+      .nullish()
+      .describe('Name of the component providing the context'),
+    formulas: z
+      .array(z.string())
+      .describe('Names of the formulas from the context to subscribe to'),
+    workflows: z
+      .array(z.string())
+      .describe('Names of the workflows from the context to subscribe to'),
+  })
+  .describe('Schema defining a component context subscription.')

package/src/component/schemas/event-schema.ts

@@ -0,0 +1,35 @@
+/* eslint-disable inclusive-language/use-inclusive-words */
+import { z } from 'zod'
+import type { ComponentEvent, EventModel } from '../component.types'
+import { ActionModelSchema } from './action-schema'
+import { MetadataSchema, SCHEMA_DESCRIPTIONS } from './zod-schemas'
+
+// Event Model
+export const EventModelSchema: z.ZodType<EventModel> = z
+  .lazy(() =>
+    z.object({
+      trigger: z
+        .string()
+        .describe(
+          'Name of the event trigger. Nordcraft does not prefix events with "on", fx a click event is just called: "click".',
+        ),
+      actions: z
+        .array(ActionModelSchema)
+        .describe('List of actions to execute.'),
+    }),
+  )
+  .describe(
+    'Model describing an event. Events are used to define actions that should be executed in response to specific triggers, such as user interactions or lifecycle events.',
+  )
+
+export const ComponentEventSchema: z.ZodType<ComponentEvent> = z
+  .object({
+    '@nordcraft/metadata': MetadataSchema.nullish().describe(
+      SCHEMA_DESCRIPTIONS.metadata('component event'),
+    ),
+    name: z.string().describe('Name of the component event'),
+    dummyEvent: z
+      .any()
+      .describe(SCHEMA_DESCRIPTIONS.testData('component event')),
+  })
+  .describe('Schema for a component event.')