@cadit-app/script-params 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CADit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @cadit-app/script-params
+
+Type-safe parameter definitions for CADit parametric scripts.
+
+## Installation
+
+```bash
+npm install @cadit-app/script-params
+```
+
+## Quick Start
+
+```typescript
+import { defineParams } from '@cadit-app/script-params';
+
+export default defineParams({
+  size: { type: 'number', default: 10, min: 1, max: 100 },
+  label: { type: 'text', default: 'Hello' },
+  hollow: { type: 'boolean', default: false },
+}, (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
+- **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[]` |
+| `slider` | `number` | `min`, `max`, `step` (required: `min`, `max`) |
+| `image` | `ImageData \| null` | - |
+
+## API Reference
+
+### `defineParams(schema)` / `defineParams(schema, main)`
+
+Define parameters for a script.
+
+**Schema only:**
+```typescript
+const params = defineParams({
+  size: { type: 'number', default: 10 },
+});
+// Returns the schema itself
+```
+
+**With callback:**
+```typescript
+export default defineParams({
+  size: { type: 'number', default: 10 },
+}, (params) => {
+  return Manifold.cube([params.size, params.size, params.size]);
+});
+// Returns a callable module with .params property
+```
+
+### `createMain(schema, main)`
+
+Create an executable script from a schema and main function. Useful when defining the main function separately.
+
+```typescript
+const params = defineParams({
+  size: { type: 'number', default: 10 },
+});
+
+function main(p: Params<typeof params>) {
+  return Manifold.cube([p.size, p.size, p.size]);
+}
+
+export default createMain(params, main);
+```
+
+### `Params<S>`
+
+Type helper to get the params object type from a schema.
+
+```typescript
+const schema = defineParams({
+  size: { type: 'number', default: 10 },
+});
+
+type MyParams = Params<typeof schema>;
+// { size: number }
+```
+
+### `schemaToArray(schema)`
+
+Convert object-based schema to array format for legacy UI compatibility.
+
+```typescript
+const array = schemaToArray({
+  size: { type: 'number', default: 10 },
+});
+// [{ name: 'size', type: 'number', default: 10 }]
+```
+
+### `getDefaults(schema)`
+
+Extract default values from a schema.
+
+```typescript
+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 script module created by `defineParams`.
+
+```typescript
+const mod = await import('./script.ts');
+if (isScriptModule(mod.default)) {
+  const result = mod.default({ size: 20 });
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,332 @@
+/**
+ * @cadit-app/script-params
+ *
+ * Type-safe parameter definitions for CADit parametric scripts.
+ *
+ * @example
+ * ```typescript
+ * import { defineParams } from '@cadit-app/script-params';
+ *
+ * export default defineParams({
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hello' },
+ * }, (params) => {
+ *   // params.size is number, params.label is string
+ *   return Manifold.cube([params.size, params.size, params.size]);
+ * });
+ * ```
+ */
+/**
+ * Base properties shared by all parameter types.
+ */
+interface ParamDefBase {
+    /** Human-readable label for the parameter. If omitted, the key is used. */
+    label?: string;
+    /** Description shown as tooltip or help text. */
+    description?: string;
+}
+/**
+ * Number parameter - floating point values.
+ */
+export interface NumberParamDef extends ParamDefBase {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Integer parameter - whole number values.
+ */
+export interface IntParamDef extends ParamDefBase {
+    type: 'int';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Text parameter - string values.
+ */
+export interface TextParamDef extends ParamDefBase {
+    type: 'text';
+    default: string;
+    maxLength?: number;
+    placeholder?: string;
+}
+/**
+ * Boolean parameter - true/false toggle.
+ */
+export interface BooleanParamDef extends ParamDefBase {
+    type: 'boolean';
+    default: boolean;
+}
+/**
+ * Choice parameter - select from predefined options.
+ */
+export interface ChoiceParamDef extends ParamDefBase {
+    type: 'choice';
+    default: string;
+    options: readonly string[];
+}
+/**
+ * Slider parameter - number with visual slider control.
+ */
+export interface SliderParamDef extends ParamDefBase {
+    type: 'slider';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+}
+/**
+ * Image parameter - ImageData for image-based operations.
+ */
+export interface ImageParamDef extends ParamDefBase {
+    type: 'image';
+    default: ImageData | null;
+}
+/**
+ * Option for buttonGrid parameter.
+ * Each option can have an image, caption, or both.
+ */
+export interface ButtonGridOption {
+    /** The value returned when this option is selected. */
+    value: string;
+    /** Optional image URL (absolute or relative to script location). */
+    image?: string;
+    /** Optional caption/label for the button. Used as alt text if image is present. */
+    caption?: string;
+}
+/**
+ * ButtonGrid parameter - visual grid of buttons with images/captions.
+ * Useful for pattern selection, style options, etc.
+ *
+ * @example
+ * ```typescript
+ * pattern: {
+ *   type: 'buttonGrid',
+ *   default: 'style1',
+ *   options: [
+ *     { value: 'style1', image: './images/style1.svg', caption: 'Style 1' },
+ *     { value: 'style2', image: './images/style2.svg', caption: 'Style 2' },
+ *   ]
+ * }
+ * ```
+ */
+export interface ButtonGridParamDef extends ParamDefBase {
+    type: 'buttonGrid';
+    default: string;
+    options: readonly ButtonGridOption[];
+}
+/**
+ * Embedded parameter - nests another script's parameters.
+ * The embedded params can be enabled/disabled and expanded/collapsed.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * export default defineParams({
+ *   size: { type: 'number', default: 10 },
+ *   qrCode: {
+ *     type: 'embedded',
+ *     label: 'QR Code (Optional)',
+ *     params: qrCodeScript.params,
+ *     enabled: false,
+ *     showSettings: false
+ *   }
+ * }, (p) => {
+ *   if (p.qrCode.enabled) {
+ *     const qrMesh = qrCodeScript(p.qrCode.params);
+ *     // combine meshes...
+ *   }
+ * });
+ * ```
+ */
+export interface EmbeddedParamDef extends ParamDefBase {
+    type: 'embedded';
+    /** The nested parameter schema. */
+    params: ParamSchema;
+    /** Whether the embedded feature is initially enabled. */
+    enabled?: boolean;
+    /** Whether the settings panel is initially expanded. */
+    showSettings?: boolean;
+}
+/**
+ * Value type for embedded parameters.
+ * Contains the enabled state, showSettings state, and the resolved param values.
+ */
+export interface EmbeddedParamValue<S extends ParamSchema = ParamSchema> {
+    enabled: boolean;
+    showSettings: boolean;
+    params: Params<S>;
+}
+/**
+ * Union of all parameter definition types.
+ */
+export type ParamDef = NumberParamDef | IntParamDef | TextParamDef | BooleanParamDef | ChoiceParamDef | SliderParamDef | ImageParamDef | ButtonGridParamDef | EmbeddedParamDef;
+/**
+ * A schema defining all parameters for a script.
+ * Keys are parameter names, values are parameter definitions.
+ */
+export type ParamSchema = Record<string, ParamDef>;
+/**
+ * Infer the runtime value type from a parameter definition.
+ *
+ * @example
+ * ```typescript
+ * type T = ParamValue<{ type: 'number'; default: 10 }>; // number
+ * type S = ParamValue<{ type: 'text'; default: 'hi' }>;  // string
+ * ```
+ */
+export type ParamValue<P extends ParamDef> = P['type'] extends 'number' | 'int' | 'slider' ? number : P['type'] extends 'text' | 'choice' | 'buttonGrid' ? string : P['type'] extends 'boolean' ? boolean : P['type'] extends 'image' ? ImageData | null : P['type'] extends 'embedded' ? P extends EmbeddedParamDef ? EmbeddedParamValue<P['params']> : EmbeddedParamValue : never;
+/**
+ * Infer the full params object type from a schema.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hi' },
+ * } as const;
+ *
+ * type P = Params<typeof schema>;
+ * // { size: number; label: string }
+ * ```
+ */
+export type Params<S extends ParamSchema> = {
+    [K in keyof S]: ParamValue<S[K]>;
+};
+/**
+ * The result returned by defineParams when a main function is provided.
+ * Contains both the schema (for UI) and the executable function.
+ */
+export interface ScriptModule<S extends ParamSchema, R> {
+    /** The parameter schema for UI generation. */
+    params: S;
+    /**
+     * Execute the script with optional parameter overrides.
+     * Missing parameters use their default values.
+     */
+    (inputParams?: Partial<Params<S>>): R;
+}
+/**
+ * Define parameters for a parametric script.
+ *
+ * This function has two overloads:
+ * 1. Schema only - returns the schema for use with `createMain`
+ * 2. Schema + callback - returns an executable module with defaults
+ *
+ * @example Schema only (for separate main function)
+ * ```typescript
+ * const params = defineParams({
+ *   size: { type: 'number', default: 10 },
+ * });
+ *
+ * function main(p: Params<typeof params>) {
+ *   return Manifold.cube([p.size, p.size, p.size]);
+ * }
+ *
+ * export default createMain(params, main);
+ * ```
+ *
+ * @example With callback (recommended)
+ * ```typescript
+ * export default defineParams({
+ *   size: { type: 'number', default: 10 },
+ * }, (params) => {
+ *   return Manifold.cube([params.size, params.size, params.size]);
+ * });
+ * ```
+ */
+export declare function defineParams<const S extends ParamSchema>(schema: S): S;
+export declare function defineParams<const S extends ParamSchema, R>(schema: S, main: (params: Params<S>) => R): ScriptModule<S, R>;
+/**
+ * Create an executable script module from a schema and main function.
+ *
+ * Use this when you want to define your main function separately,
+ * for example when it's complex or needs to be tested independently.
+ *
+ * @example
+ * ```typescript
+ * const params = defineParams({
+ *   size: { type: 'number', default: 10 },
+ * });
+ *
+ * function main(p: Params<typeof params>) {
+ *   return Manifold.cube([p.size, p.size, p.size]);
+ * }
+ *
+ * export default createMain(params, main);
+ * ```
+ */
+export declare function createMain<S extends ParamSchema, R>(schema: S, main: (params: Params<S>) => R): ScriptModule<S, R>;
+/**
+ * Convert an object-based schema to array format for legacy UI compatibility.
+ *
+ * This function transforms the script-params schema format into the
+ * ObjectMakerParam[] format expected by the Core UI.
+ *
+ * @example
+ * ```typescript
+ * const schema = { size: { type: 'number', default: 10 } };
+ * const array = schemaToArray(schema);
+ * // [{ name: 'size', type: 'number', initial: 10, caption: 'size' }]
+ * ```
+ */
+export declare function schemaToArray<S extends ParamSchema>(schema: S): Array<Record<string, unknown>>;
+/**
+ * Extract defaults from a schema as a plain object.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hi' },
+ * };
+ * const defaults = getDefaults(schema);
+ * // { size: 10, label: 'Hi' }
+ * ```
+ */
+export declare function getDefaults<S extends ParamSchema>(schema: S): Params<S>;
+/**
+ * Check if a module export uses the defineParams format.
+ *
+ * @example
+ * ```typescript
+ * const mod = await import('./script.ts');
+ * if (isScriptModule(mod.default)) {
+ *   const result = mod.default({ size: 20 });
+ * }
+ * ```
+ */
+export declare function isScriptModule(value: unknown): value is ScriptModule<ParamSchema, unknown>;
+/**
+ * Extract the parameter schema from a ScriptModule or plain schema.
+ * Useful for embedding another script's parameters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * // Works with ScriptModule
+ * const qrParams = getParams(qrCodeScript);
+ *
+ * // Also works with plain schema
+ * const schema = { size: { type: 'number', default: 10 } } as const;
+ * const plainParams = getParams(schema);
+ *
+ * // Use in embedded param definition
+ * export default defineParams({
+ *   qrCode: {
+ *     type: 'embedded',
+ *     params: getParams(qrCodeScript),
+ *     enabled: false,
+ *   }
+ * });
+ * ```
+ */
+export declare function getParams<S extends ParamSchema>(source: ScriptModule<S, unknown> | S): S;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,209 @@
+/**
+ * @cadit-app/script-params
+ *
+ * Type-safe parameter definitions for CADit parametric scripts.
+ *
+ * @example
+ * ```typescript
+ * import { defineParams } from '@cadit-app/script-params';
+ *
+ * export default defineParams({
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hello' },
+ * }, (params) => {
+ *   // params.size is number, params.label is string
+ *   return Manifold.cube([params.size, params.size, params.size]);
+ * });
+ * ```
+ */
+// =============================================================================
+// Core Functions
+// =============================================================================
+/**
+ * Build default values object from a schema.
+ * @internal
+ */
+function buildDefaults(schema) {
+    const defaults = {};
+    for (const [key, def] of Object.entries(schema)) {
+        if (def.type === 'embedded') {
+            // For embedded params, build a nested default object
+            const embeddedDef = def;
+            defaults[key] = {
+                enabled: embeddedDef.enabled ?? false,
+                showSettings: embeddedDef.showSettings ?? false,
+                params: buildDefaults(embeddedDef.params),
+            };
+        }
+        else {
+            defaults[key] = def.default;
+        }
+    }
+    return defaults;
+}
+export function defineParams(schema, main) {
+    if (!main) {
+        return schema;
+    }
+    const defaults = buildDefaults(schema);
+    const scriptModule = ((inputParams) => {
+        const merged = { ...defaults, ...inputParams };
+        return main(merged);
+    });
+    scriptModule.params = schema;
+    return scriptModule;
+}
+/**
+ * Create an executable script module from a schema and main function.
+ *
+ * Use this when you want to define your main function separately,
+ * for example when it's complex or needs to be tested independently.
+ *
+ * @example
+ * ```typescript
+ * const params = defineParams({
+ *   size: { type: 'number', default: 10 },
+ * });
+ *
+ * function main(p: Params<typeof params>) {
+ *   return Manifold.cube([p.size, p.size, p.size]);
+ * }
+ *
+ * export default createMain(params, main);
+ * ```
+ */
+export function createMain(schema, main) {
+    return defineParams(schema, main);
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Convert a single param def to ObjectMakerParam format.
+ * Handles special cases like embedded params that need recursive conversion.
+ * @internal
+ */
+function convertParamDef(name, def) {
+    const base = {
+        name,
+        type: def.type,
+        caption: def.label ?? name,
+    };
+    // Copy common properties
+    if ('default' in def) {
+        base.initial = def.default;
+    }
+    if ('min' in def)
+        base.min = def.min;
+    if ('max' in def)
+        base.max = def.max;
+    if ('step' in def)
+        base.step = def.step;
+    if ('maxLength' in def)
+        base.maxLength = def.maxLength;
+    // Handle type-specific conversions
+    switch (def.type) {
+        case 'choice':
+            base.values = def.options;
+            break;
+        case 'buttonGrid': {
+            // Convert buttonGrid options to ObjectMakerButtonGridParam format
+            base.options = def.options.map((opt) => ({
+                value: opt.value,
+                image: opt.image,
+                caption: opt.caption,
+            }));
+            break;
+        }
+        case 'embedded': {
+            // Convert embedded params recursively
+            const embeddedDef = def;
+            base.parameters = schemaToArray(embeddedDef.params);
+            base.enabled = embeddedDef.enabled ?? false;
+            base.showSettings = embeddedDef.showSettings ?? false;
+            break;
+        }
+    }
+    return base;
+}
+/**
+ * Convert an object-based schema to array format for legacy UI compatibility.
+ *
+ * This function transforms the script-params schema format into the
+ * ObjectMakerParam[] format expected by the Core UI.
+ *
+ * @example
+ * ```typescript
+ * const schema = { size: { type: 'number', default: 10 } };
+ * const array = schemaToArray(schema);
+ * // [{ name: 'size', type: 'number', initial: 10, caption: 'size' }]
+ * ```
+ */
+export function schemaToArray(schema) {
+    return Object.entries(schema).map(([name, def]) => convertParamDef(name, def));
+}
+/**
+ * Extract defaults from a schema as a plain object.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hi' },
+ * };
+ * const defaults = getDefaults(schema);
+ * // { size: 10, label: 'Hi' }
+ * ```
+ */
+export function getDefaults(schema) {
+    return buildDefaults(schema);
+}
+/**
+ * Check if a module export uses the defineParams format.
+ *
+ * @example
+ * ```typescript
+ * const mod = await import('./script.ts');
+ * if (isScriptModule(mod.default)) {
+ *   const result = mod.default({ size: 20 });
+ * }
+ * ```
+ */
+export function isScriptModule(value) {
+    return (typeof value === 'function' &&
+        'params' in value &&
+        typeof value.params === 'object' &&
+        value.params !== null);
+}
+/**
+ * Extract the parameter schema from a ScriptModule or plain schema.
+ * Useful for embedding another script's parameters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * // Works with ScriptModule
+ * const qrParams = getParams(qrCodeScript);
+ *
+ * // Also works with plain schema
+ * const schema = { size: { type: 'number', default: 10 } } as const;
+ * const plainParams = getParams(schema);
+ *
+ * // Use in embedded param definition
+ * export default defineParams({
+ *   qrCode: {
+ *     type: 'embedded',
+ *     params: getParams(qrCodeScript),
+ *     enabled: false,
+ *   }
+ * });
+ * ```
+ */
+export function getParams(source) {
+    if (isScriptModule(source)) {
+        return source.params;
+    }
+    return source;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cadit-app/script-params",
+  "version": "0.1.0",
+  "description": "Type-safe parameter definitions for CADit scripts",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "cad",
+    "parametric",
+    "3d",
+    "manifold",
+    "scripts"
+  ],
+  "author": "CADit",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest"
+  }
+}