@mica-js/sdk 0.0.0-stage → 0.2.1

package/dist/metadata/schema.js

@@ -0,0 +1,392 @@
+const DRAFT_2020_12 = 'https://json-schema.org/draft/2020-12/schema';
+const PROPERTY_TYPES = ['number', 'boolean', 'string', 'enum', 'bytes'];
+const PORT_PAYLOAD_TYPES = [
+    'boolean',
+    'number',
+    'string',
+    'vec2d',
+    'vec3d',
+    'bytes',
+    'bytes<rgb565>',
+    'bytes<segments>',
+];
+const PORT_DIRECTIONS = ['input', 'output'];
+const PORT_DELIVERIES = ['level', 'message'];
+const GRAPHIC_FILLS = ['none', 'foreground', 'background'];
+const TEXT_ALIGNS = ['left', 'center', 'right'];
+const SYMBOL_PIN_DIRECTIONS = ['left', 'right', 'up', 'down'];
+const EDITOR_TYPES = ['number', 'text', 'textarea', 'checkbox', 'file', 'select'];
+const GRAPHIC_TYPES = ['line', 'polyline', 'rect', 'circle', 'arc', 'text'];
+function stringEnum(values) {
+    return { type: 'string', enum: [...values] };
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        ...(required.length === 0 ? {} : { required: [...required] }),
+        properties,
+    };
+}
+function stringMap(values, description) {
+    return {
+        type: 'object',
+        description,
+        propertyNames: { minLength: 1 },
+        additionalProperties: values,
+    };
+}
+/** Applies `then` only when the sibling discriminator field equals `value`. */
+function whenEquals(field, value, then) {
+    return {
+        if: { required: [field], properties: { [field]: { const: value } } },
+        then,
+    };
+}
+function whenType(typeName, then) {
+    return whenEquals('type', typeName, then);
+}
+function pointSchema() {
+    return {
+        type: 'array',
+        description: 'A point expressed as [x, y].',
+        prefixItems: [{ type: 'number' }, { type: 'number' }],
+        items: false,
+        minItems: 2,
+        maxItems: 2,
+    };
+}
+function propertySchema() {
+    return {
+        type: 'object',
+        description: 'A persistent configuration value.',
+        additionalProperties: false,
+        required: ['type', 'required'],
+        properties: {
+            type: stringEnum(PROPERTY_TYPES),
+            required: { type: 'boolean' },
+            nullable: { type: 'boolean' },
+            default: { type: ['number', 'boolean', 'string', 'null'] },
+            title: { type: 'string' },
+            description: { type: 'string' },
+            unit: { type: 'string' },
+            group: { type: 'string' },
+            order: { type: 'integer', minimum: 0 },
+            editor: { $ref: '#/$defs/editor' },
+            enumName: { type: 'string', minLength: 1 },
+            values: {
+                type: 'array',
+                minItems: 1,
+                uniqueItems: true,
+                items: { type: 'string', minLength: 1 },
+            },
+        },
+        allOf: [
+            {
+                $comment: 'A required value has no default.',
+                if: { required: ['required'], properties: { required: { const: true } } },
+                then: { properties: { default: false } },
+            },
+            {
+                $comment: 'Bytes defaults need an encoding that is not decided yet.',
+                if: { required: ['type'], properties: { type: { const: 'bytes' } } },
+                then: { properties: { default: false } },
+            },
+            {
+                $comment: 'An explicit null default requires nullable: true.',
+                if: {
+                    required: ['default'],
+                    properties: { default: { const: null }, type: { not: { const: 'bytes' } } },
+                },
+                then: { required: ['nullable'], properties: { nullable: { const: true } } },
+            },
+            {
+                $comment: 'Default values must match the declared type; membership in enum values is checked in code.',
+                if: { required: ['type'], properties: { type: { const: 'number' } } },
+                then: { properties: { default: { type: ['number', 'null'] } } },
+            },
+            {
+                if: { required: ['type'], properties: { type: { const: 'boolean' } } },
+                then: { properties: { default: { type: ['boolean', 'null'] } } },
+            },
+            {
+                if: { required: ['type'], properties: { type: { const: 'string' } } },
+                then: { properties: { default: { type: ['string', 'null'] } } },
+            },
+            {
+                if: { required: ['type'], properties: { type: { const: 'enum' } } },
+                then: {
+                    required: ['enumName', 'values'],
+                    properties: {
+                        default: { type: ['string', 'null'] },
+                        enumName: { type: 'string', minLength: 1 },
+                        values: { type: 'array' },
+                    },
+                },
+            },
+            {
+                $comment: 'Only enum properties carry an enum name and a value list.',
+                if: { required: ['type'], properties: { type: { not: { const: 'enum' } } } },
+                then: { properties: { enumName: false, values: false } },
+            },
+        ],
+    };
+}
+function editorSchema() {
+    return {
+        type: 'object',
+        description: 'Editor hints for a property value.',
+        required: ['kind'],
+        properties: { kind: stringEnum(EDITOR_TYPES) },
+        allOf: [
+            whenEquals('kind', 'number', objectSchema({
+                kind: { type: 'string', const: 'number' },
+                min: { type: 'number' },
+                max: { type: 'number' },
+                step: { type: 'number', exclusiveMinimum: 0 },
+            })),
+            whenEquals('kind', 'text', objectSchema({ kind: { type: 'string', const: 'text' } })),
+            whenEquals('kind', 'textarea', objectSchema({ kind: { type: 'string', const: 'textarea' } })),
+            whenEquals('kind', 'checkbox', objectSchema({ kind: { type: 'string', const: 'checkbox' } })),
+            whenEquals('kind', 'file', objectSchema({
+                kind: { type: 'string', const: 'file' },
+                extensions: {
+                    type: 'array',
+                    description: 'Allowed dotted filename extensions, matched case-insensitively by the host.',
+                    uniqueItems: true,
+                    items: { type: 'string', pattern: '^\\.[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)*$' },
+                },
+                maxSize: {
+                    type: 'integer',
+                    exclusiveMinimum: 0,
+                    description: 'Maximum file size in bytes.',
+                },
+            })),
+            whenEquals('kind', 'select', objectSchema({
+                kind: { type: 'string', const: 'select' },
+                labels: {
+                    type: 'object',
+                    description: 'Option value to display label.',
+                    propertyNames: { minLength: 1 },
+                    additionalProperties: { type: 'string' },
+                },
+            }, ['labels'])),
+        ],
+    };
+}
+function portSchema() {
+    return {
+        type: 'object',
+        description: 'A topic port.',
+        additionalProperties: false,
+        required: ['direction', 'type'],
+        properties: {
+            title: { type: 'string' },
+            description: { type: 'string' },
+            direction: stringEnum(PORT_DIRECTIONS),
+            type: stringEnum(PORT_PAYLOAD_TYPES),
+            delivery: stringEnum(PORT_DELIVERIES),
+        },
+    };
+}
+function pinSchema() {
+    return {
+        type: 'object',
+        description: 'A physical pin.',
+        additionalProperties: false,
+        properties: {
+            label: { type: 'string' },
+            description: { type: 'string' },
+            group: { type: 'string' },
+        },
+    };
+}
+function boundsSchema() {
+    return {
+        ...objectSchema({
+            x: { type: 'number' },
+            y: { type: 'number' },
+            width: { type: 'number', exclusiveMinimum: 0 },
+            height: { type: 'number', exclusiveMinimum: 0 },
+        }, ['x', 'y', 'width', 'height']),
+        description: 'The symbol body box.',
+    };
+}
+function graphicSchema() {
+    return {
+        type: 'object',
+        description: 'A symbol graphic.',
+        required: ['type'],
+        properties: { type: stringEnum(GRAPHIC_TYPES) },
+        allOf: [
+            whenType('line', { $ref: '#/$defs/lineGraphic' }),
+            whenType('polyline', { $ref: '#/$defs/polylineGraphic' }),
+            whenType('rect', { $ref: '#/$defs/rectGraphic' }),
+            whenType('circle', { $ref: '#/$defs/circleGraphic' }),
+            whenType('arc', { $ref: '#/$defs/arcGraphic' }),
+            whenType('text', { $ref: '#/$defs/textGraphic' }),
+        ],
+    };
+}
+function symbolPinSchema() {
+    return objectSchema({
+        position: { $ref: '#/$defs/point' },
+        direction: stringEnum(SYMBOL_PIN_DIRECTIONS),
+        label: { $ref: '#/$defs/pinLabel' },
+    }, ['position', 'direction']);
+}
+function buildDefs(kind) {
+    const fill = stringEnum(GRAPHIC_FILLS);
+    const strokeWidth = { type: 'number', exclusiveMinimum: 0 };
+    const pointRef = { $ref: '#/$defs/point' };
+    const defs = {
+        point: pointSchema(),
+        editor: editorSchema(),
+        property: propertySchema(),
+        properties: stringMap({ $ref: '#/$defs/property' }, 'Property key to property description.'),
+        port: portSchema(),
+        ports: stringMap({ $ref: '#/$defs/port' }, 'Port key to topic port description.'),
+    };
+    if (kind === 'widget')
+        return defs;
+    return {
+        ...defs,
+        pin: pinSchema(),
+        pins: stringMap({ $ref: '#/$defs/pin' }, 'Pin key to physical pin description.'),
+        bounds: boundsSchema(),
+        graphic: graphicSchema(),
+        lineGraphic: objectSchema({
+            type: { type: 'string', const: 'line' },
+            from: pointRef,
+            to: pointRef,
+            fill,
+            strokeWidth,
+        }, ['type', 'from', 'to']),
+        polylineGraphic: objectSchema({
+            type: { type: 'string', const: 'polyline' },
+            points: { type: 'array', minItems: 2, items: pointRef },
+            closed: { type: 'boolean' },
+            fill,
+            strokeWidth,
+        }, ['type', 'points']),
+        rectGraphic: objectSchema({
+            type: { type: 'string', const: 'rect' },
+            x: { type: 'number' },
+            y: { type: 'number' },
+            width: { type: 'number', exclusiveMinimum: 0 },
+            height: { type: 'number', exclusiveMinimum: 0 },
+            fill,
+            strokeWidth,
+        }, ['type', 'x', 'y', 'width', 'height']),
+        circleGraphic: objectSchema({
+            type: { type: 'string', const: 'circle' },
+            center: pointRef,
+            radius: { type: 'number', exclusiveMinimum: 0 },
+            fill,
+            strokeWidth,
+        }, ['type', 'center', 'radius']),
+        arcGraphic: objectSchema({
+            type: { type: 'string', const: 'arc' },
+            center: pointRef,
+            radius: { type: 'number', exclusiveMinimum: 0 },
+            startAngle: { type: 'number' },
+            sweepAngle: {
+                type: 'number',
+                minimum: -360,
+                maximum: 360,
+                not: { const: 0 },
+            },
+            fill,
+            strokeWidth,
+        }, ['type', 'center', 'radius', 'startAngle', 'sweepAngle']),
+        textGraphic: objectSchema({
+            type: { type: 'string', const: 'text' },
+            position: pointRef,
+            text: { type: 'string' },
+            align: stringEnum(TEXT_ALIGNS),
+            fontSize: { type: 'number', exclusiveMinimum: 0 },
+            fill,
+            strokeWidth,
+        }, ['type', 'position', 'text', 'fontSize']),
+        pinLabel: objectSchema({
+            visible: { type: 'boolean' },
+            position: pointRef,
+            align: stringEnum(TEXT_ALIGNS),
+        }, ['visible']),
+        symbolPin: symbolPinSchema(),
+        designatorAnnotation: objectSchema({
+            position: pointRef,
+            align: stringEnum(TEXT_ALIGNS),
+        }, ['position']),
+        annotations: objectSchema({
+            designator: { $ref: '#/$defs/designatorAnnotation' },
+        }),
+        symbol: objectSchema({
+            bounds: { $ref: '#/$defs/bounds' },
+            graphics: { type: 'array', items: { $ref: '#/$defs/graphic' } },
+            pins: stringMap({ $ref: '#/$defs/symbolPin' }, 'Pin key to symbol pin placement.'),
+            annotations: { $ref: '#/$defs/annotations' },
+        }, ['bounds', 'graphics', 'pins']),
+    };
+}
+function headerProperties() {
+    return {
+        id: { type: 'string', pattern: '^[A-Za-z0-9-]+$' },
+        version: { type: 'string', minLength: 1 },
+        displayName: { type: 'string', minLength: 1 },
+        description: { type: 'string' },
+        license: { type: 'string' },
+        tags: {
+            type: 'array',
+            uniqueItems: true,
+            items: { type: 'string', minLength: 1 },
+        },
+    };
+}
+/** Metadata of a single device, independent of any package manifest or DDL source. */
+export const deviceMetadataSchema = {
+    $schema: DRAFT_2020_12,
+    title: 'Mica device metadata',
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind', 'id', 'version', 'displayName'],
+    properties: {
+        kind: { type: 'string', const: 'device' },
+        ...headerProperties(),
+        templates: {
+            type: 'array',
+            description: 'Platform project template IDs in display priority order.',
+            uniqueItems: true,
+            items: { type: 'string', minLength: 1 },
+        },
+        recommends: objectSchema({
+            widgets: {
+                type: 'array',
+                description: 'Recommended full widget IDs in display priority order; not dependencies.',
+                uniqueItems: true,
+                items: { type: 'string', minLength: 1 },
+            },
+        }),
+        designatorPrefix: { type: 'string', pattern: '^\\S+$' },
+        properties: { $ref: '#/$defs/properties' },
+        pins: { $ref: '#/$defs/pins' },
+        ports: { $ref: '#/$defs/ports' },
+        symbol: { $ref: '#/$defs/symbol' },
+    },
+    $defs: buildDefs('device'),
+};
+/** Metadata of a single widget, independent of any package manifest or DDL source. */
+export const widgetMetadataSchema = {
+    $schema: DRAFT_2020_12,
+    title: 'Mica widget metadata',
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind', 'id', 'version', 'displayName'],
+    properties: {
+        kind: { type: 'string', const: 'widget' },
+        ...headerProperties(),
+        properties: { $ref: '#/$defs/properties' },
+        ports: { $ref: '#/$defs/ports' },
+    },
+    $defs: buildDefs('widget'),
+};

package/dist/metadata/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * TypeScript shapes for individual device and widget metadata.
+ *
+ * The types describe the same contract as the JSON schemas in `schema.ts`; runtime validation
+ * remains authoritative because a metadata file is untrusted JSON.
+ */
+export type MetadataKind = 'device' | 'widget';
+/** A two-dimensional point, serialized as `[x, y]`. */
+export type Point = readonly [x: number, y: number];
+export type PropertyType = 'number' | 'boolean' | 'string' | 'enum' | 'bytes';
+export type PortDirection = 'input' | 'output';
+export type PortPayloadType = 'boolean' | 'number' | 'string' | 'vec2d' | 'vec3d' | 'bytes' | 'bytes<rgb565>' | 'bytes<segments>';
+export type PortDelivery = 'level' | 'message';
+export type GraphicFill = 'none' | 'foreground' | 'background';
+export type TextAlign = 'left' | 'center' | 'right';
+export type PinDirection = 'left' | 'right' | 'up' | 'down';
+export interface NumberEditor {
+    readonly kind: 'number';
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+export interface TextEditor {
+    readonly kind: 'text';
+}
+export interface TextareaEditor {
+    readonly kind: 'textarea';
+}
+export interface CheckboxEditor {
+    readonly kind: 'checkbox';
+}
+export interface FileEditor {
+    readonly kind: 'file';
+    readonly extensions?: readonly string[];
+    readonly maxSize?: number;
+}
+export interface SelectEditor {
+    readonly kind: 'select';
+    readonly labels: Readonly<Record<string, string>>;
+}
+export type PropertyEditor = NumberEditor | TextEditor | TextareaEditor | CheckboxEditor | FileEditor | SelectEditor;
+interface PropertyCommon {
+    /** `true` values have no default; `false` values must declare one. */
+    readonly required: boolean;
+    readonly nullable?: boolean;
+    readonly title?: string;
+    readonly description?: string;
+    readonly unit?: string;
+    readonly group?: string;
+    readonly order?: number;
+}
+export interface NumberProperty extends PropertyCommon {
+    readonly type: 'number';
+    readonly default?: number | null;
+    readonly editor?: NumberEditor;
+}
+export interface BooleanProperty extends PropertyCommon {
+    readonly type: 'boolean';
+    readonly default?: boolean | null;
+    readonly editor?: CheckboxEditor;
+}
+export interface StringProperty extends PropertyCommon {
+    readonly type: 'string';
+    readonly default?: string | null;
+    readonly editor?: TextEditor | TextareaEditor;
+}
+export interface EnumProperty extends PropertyCommon {
+    readonly type: 'enum';
+    readonly enumName: string;
+    readonly values: readonly string[];
+    readonly default?: string | null;
+    readonly editor?: SelectEditor;
+}
+/**
+ * Bytes values may omit the default, but bytes defaults are rejected: the byte encoding is not
+ * decided yet, so a default cannot be expressed as plain JSON.
+ */
+export interface BytesProperty extends PropertyCommon {
+    readonly type: 'bytes';
+    readonly editor?: FileEditor;
+}
+export type PropertyMetadata = NumberProperty | BooleanProperty | StringProperty | EnumProperty | BytesProperty;
+export interface PortMetadata {
+    readonly title?: string;
+    readonly description?: string;
+    readonly direction: PortDirection;
+    readonly type: PortPayloadType;
+    readonly delivery?: PortDelivery;
+}
+export interface PinMetadata {
+    readonly label?: string;
+    readonly description?: string;
+    readonly group?: string;
+}
+interface GraphicCommon {
+    readonly fill?: GraphicFill;
+    readonly strokeWidth?: number;
+}
+export interface LineGraphic extends GraphicCommon {
+    readonly type: 'line';
+    readonly from: Point;
+    readonly to: Point;
+}
+export interface PolylineGraphic extends GraphicCommon {
+    readonly type: 'polyline';
+    readonly points: readonly Point[];
+    readonly closed?: boolean;
+}
+export interface RectGraphic extends GraphicCommon {
+    readonly type: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface CircleGraphic extends GraphicCommon {
+    readonly type: 'circle';
+    readonly center: Point;
+    readonly radius: number;
+}
+export interface ArcGraphic extends GraphicCommon {
+    readonly type: 'arc';
+    readonly center: Point;
+    readonly radius: number;
+    readonly startAngle: number;
+    /** Degrees in `[-360, 360]`, excluding `0`. */
+    readonly sweepAngle: number;
+}
+export interface TextGraphic extends GraphicCommon {
+    readonly type: 'text';
+    readonly position: Point;
+    readonly text: string;
+    readonly align?: TextAlign;
+    readonly fontSize: number;
+}
+export type Graphic = LineGraphic | PolylineGraphic | RectGraphic | CircleGraphic | ArcGraphic | TextGraphic;
+export interface SymbolBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface PinLabelMetadata {
+    readonly visible: boolean;
+    readonly position?: Point;
+    readonly align?: TextAlign;
+}
+export interface SymbolPinMetadata {
+    readonly position: Point;
+    readonly direction: PinDirection;
+    readonly label?: PinLabelMetadata;
+}
+export interface DesignatorAnnotationMetadata {
+    readonly position: Point;
+    readonly align?: TextAlign;
+}
+export interface SymbolAnnotationsMetadata {
+    readonly designator?: DesignatorAnnotationMetadata;
+}
+export interface SymbolMetadata {
+    readonly bounds: SymbolBounds;
+    readonly graphics: readonly Graphic[];
+    readonly pins: Readonly<Record<string, SymbolPinMetadata>>;
+    readonly annotations?: SymbolAnnotationsMetadata;
+}
+interface MetadataHeader {
+    readonly id: string;
+    readonly version: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly license?: string;
+    readonly tags?: readonly string[];
+}
+export interface DeviceMetadata extends MetadataHeader {
+    readonly kind: 'device';
+    readonly templates?: readonly string[];
+    readonly recommends?: {
+        readonly widgets?: readonly string[];
+    };
+    readonly designatorPrefix?: string;
+    readonly properties?: Readonly<Record<string, PropertyMetadata>>;
+    readonly pins?: Readonly<Record<string, PinMetadata>>;
+    readonly ports?: Readonly<Record<string, PortMetadata>>;
+    readonly symbol?: SymbolMetadata;
+}
+export interface WidgetMetadata extends MetadataHeader {
+    readonly kind: 'widget';
+    readonly properties?: Readonly<Record<string, PropertyMetadata>>;
+    readonly ports?: Readonly<Record<string, PortMetadata>>;
+}
+export type Metadata = DeviceMetadata | WidgetMetadata;
+export {};

package/dist/metadata/types.js

@@ -0,0 +1,7 @@
+/**
+ * TypeScript shapes for individual device and widget metadata.
+ *
+ * The types describe the same contract as the JSON schemas in `schema.ts`; runtime validation
+ * remains authoritative because a metadata file is untrusted JSON.
+ */
+export {};

package/dist/metadata/validate.d.ts

@@ -0,0 +1,25 @@
+import type { MetadataKind } from './types.js';
+/** One validation problem, addressed by a dot path such as `properties.led.type`. */
+export interface MetadataIssue {
+    /** Path of the offending value; `''` addresses the metadata root. */
+    readonly path: string;
+    readonly message: string;
+    /** JSON Schema keyword, or `expectedId` for the cross-file id check. */
+    readonly keyword: string;
+}
+/** Thrown by {@link validateMetadata} when a metadata document is rejected. */
+export declare class MetadataValidationError extends Error {
+    readonly kind: MetadataKind;
+    readonly issues: readonly MetadataIssue[];
+    readonly metadataId: string | undefined;
+    constructor(kind: MetadataKind, issues: readonly MetadataIssue[], metadataId: string | undefined);
+}
+/**
+ * Validates one device or widget metadata document.
+ *
+ * @param input Untrusted JSON value of the metadata file.
+ * @param kind Metadata kind that selects the contract.
+ * @param expectedId Id the caller expects; a mismatch is reported at `id`.
+ * @throws {MetadataValidationError} with the path of every rejected value.
+ */
+export declare function validateMetadata(input: unknown, kind: MetadataKind, expectedId?: string): void;