@cadit-app/script-params

Type-safe parameter definitions for CADit parametric scripts.

Installation

npm install @cadit-app/script-params

Quick Start

import { defineParams } from '@cadit-app/script-params';

export default defineParams({
  params: {
    size: { type: 'number', default: 10, min: 1, max: 100 },
    label: { type: 'text', default: 'Hello' },
    hollow: { type: 'boolean', default: false },
  },
  main: (params) => {
    // params.size is number
    // params.label is string
    // params.hollow is boolean
    return createModel(params.size, params.label, params.hollow);
  },
});

Features

• Type-safe parameters - Full TypeScript inference without as const
• Default values - Scripts work standalone when params are undefined
• UI generation - Schema can be converted to UI controls
• Exporters - Define custom export formats (SVG, PNG, etc.)
• Simple API - Just one function to learn

Parameter Types

| Type | Value Type | Additional Options | |------|------------|-------------------| | number | number | min, max, step | | int | number | min, max, step | | text | string | maxLength, placeholder | | boolean | boolean | - | | choice | string | options: string[] or options: { value, label }[] | | slider | number | min, max, step (required: min, max) | | buttonGrid | string | options: { value, image?, caption? }[] | | image | ImageFileValue \| null | - | | embedded | EmbeddedParamValue | params, enabled?, showSettings? |

API Reference

defineParams(config)

Define parameters for a script. Pass a config object with params (required), and optionally main and exporters.

Basic usage:

export default defineParams({
  params: {
    size: { type: 'number', default: 10 },
  },
  main: (params) => Manifold.cube([params.size, params.size, params.size]),
});
// Returns a callable ScriptModule

With exporters:

export default defineParams({
  params: {
    size: { type: 'number', default: 10 },
  },
  exporters: {
    svg: {
      name: 'SVG',
      label: 'Download SVG',
      export: async (params) => ({
        mimeType: 'image/svg+xml',
        fileName: 'model.svg',
        data: generateSvg(params),
      }),
    },
  },
  main: (params) => Manifold.cube([params.size, params.size, params.size]),
});

Without main (add main separately):

const script = defineParams({
  params: { size: { type: 'number', default: 10 } },
  exporters: { svg: svgExporter },
});

export default createMain(script, myMainFunction);

createMain(scriptModule, main)

Add a main function to a ScriptModule. Preserves any exporters.

const script = defineParams({
  params: { size: { type: 'number', default: 10 } },
  exporters: { svg: svgExporter },
});

export default createMain(script, (p) => Manifold.cube([p.size, ...]));

Params<S>

Type helper to get the params object type from a schema.

const script = defineParams({
  params: {
    size: { type: 'number', default: 10 },
  },
});

type MyParams = Params<typeof script.params>;
// { size: number }

schemaToArray(schema)

Convert object-based schema to array format for legacy UI compatibility.

const array = schemaToArray({
  size: { type: 'number', default: 10 },
});
// [{ name: 'size', type: 'number', initial: 10, caption: 'size' }]

getDefaults(schema)

Extract default values from a schema.

const defaults = getDefaults({
  size: { type: 'number', default: 10 },
  label: { type: 'text', default: 'Hi' },
});
// { size: 10, label: 'Hi' }

isScriptModule(value)

Check if a value is a ScriptModule created by defineParams.

const mod = await import('./script.ts');
if (isScriptModule(mod.default)) {
  const result = mod.default({ size: 20 });
}

getParams(source)

Extract the parameter schema from a ScriptModule.

const qrParams = getParams(qrCodeScript);

getExporters(module)

Extract exporters from a ScriptModule.

const exporters = getExporters(script);
// { svg: { name: 'SVG', ... }, png: { name: 'PNG', ... } }

Exporters

Exporters allow scripts to define custom download formats:

import { defineParams, Exporter, ExportResult } from '@cadit-app/script-params';

const svgExporter: Exporter = {
  name: 'SVG',
  label: 'Download SVG',
  description: 'Export as scalable vector graphic',
  export: async (params): Promise<ExportResult> => ({
    mimeType: 'image/svg+xml',
    fileName: 'output.svg',
    data: generateSvgFromParams(params),
  }),
};

export default defineParams({
  params: {
    size: { type: 'number', default: 10 },
  },
  exporters: { svg: svgExporter },
  main: (params) => generateGeometry(params),
});

License

MIT