@widgetic/creator 0.3.72 → 0.3.73

package/dist/utils/designIntentResolver.js

@@ -0,0 +1,509 @@
+/**
+ * designIntentResolver — deterministic "user wants to change a design property"
+ * resolution, for the canvas chat.
+ *
+ * The canvas chat normally sends every message to codegen (an LLM turn). A large
+ * share of messages are really just design-property tweaks ("make the background
+ * #1a1a2e", "increase the padding by 8", "turn on the border"). Those are fully
+ * decidable in code against the widget's already-loaded `design.json` schema: the
+ * property set is a closed set, and the value is either explicit (hex / number /
+ * boolean / a dropdown option) or an arithmetic transform of the current value.
+ *
+ * This module is intentionally PURE and MODEL-FREE. It never calls JEV or an LLM;
+ * it returns `null` whenever the message needs semantic understanding ("make it
+ * pop", "give it more breathing room") so the caller can fall through to the
+ * existing codegen path. Arithmetic lives here, in code — never in the model.
+ *
+ * Scope: values that are unambiguous and safe to apply to the live preview:
+ *   - colors   (hex, rgb(), and a table of common named colors)
+ *   - numbers  (explicit, or delta/multiplier of the current value; clamped to constraints)
+ *   - booleans (switch/checkbox/radiogroup on|off)
+ *   - dropdown options (by option label/value token)
+ *   - quoted free text (textInput/textArea) — only when explicitly quoted
+ *
+ * Anything else returns null, by design.
+ */
+const COLOR_CONTROLLERS = new Set(['colorpicker']);
+const NUMBER_CONTROLLERS = new Set(['slider', 'number', 'angle']);
+const BOOLEAN_CONTROLLERS = new Set(['switch', 'checkbox']);
+const OPTION_CONTROLLERS = new Set(['dropdown', 'radiogroup']);
+const TEXT_CONTROLLERS = new Set(['textinput', 'textarea']);
+/** Common CSS named colors → hex. Deliberately a small, unambiguous subset. */
+const NAMED_COLORS = {
+    black: '#000000',
+    white: '#ffffff',
+    red: '#ff0000',
+    green: '#008000',
+    blue: '#0000ff',
+    yellow: '#ffff00',
+    orange: '#ffa500',
+    purple: '#800080',
+    pink: '#ffc0cb',
+    brown: '#a52a2a',
+    grey: '#808080',
+    gray: '#808080',
+    navy: '#000080',
+    teal: '#008080',
+    cyan: '#00ffff',
+    aqua: '#00ffff',
+    magenta: '#ff00ff',
+    fuchsia: '#ff00ff',
+    lime: '#00ff00',
+    mint: '#98ff98',
+    beige: '#f5f5dc',
+    gold: '#ffd700',
+    silver: '#c0c0c0',
+    maroon: '#800000',
+    olive: '#808000',
+    coral: '#ff7f50',
+    salmon: '#fa8072',
+    turquoise: '#40e0d0',
+    lavender: '#e6e6fa',
+    indigo: '#4b0082',
+    crimson: '#dc143c',
+    transparent: '#00000000'
+};
+/**
+ * Synonym expansion for property names. Keys are the words a user is likely to
+ * say; values are words that appear in schema property ids/labels. Matching is
+ * symmetric (a message token may be either side).
+ */
+const WORD_SYNONYMS = {
+    background: ['background', 'bg', 'backdrop'],
+    color: ['color', 'colour', 'tint', 'hue'],
+    radius: ['radius', 'corner', 'corners', 'rounded', 'roundness', 'curve'],
+    padding: ['padding', 'spacing', 'inset'],
+    margin: ['margin', 'gap', 'outer'],
+    font: ['font', 'typeface', 'type', 'typography'],
+    size: ['size', 'scale'],
+    border: ['border', 'stroke', 'outline', 'frame'],
+    width: ['width', 'thickness', 'weight'],
+    opacity: ['opacity', 'transparency', 'alpha'],
+    shadow: ['shadow', 'elevation', 'glow'],
+    spacing: ['spacing', 'gap', 'space'],
+    title: ['title', 'heading', 'header'],
+    text: ['text', 'label', 'copy', 'content'],
+    icon: ['icon', 'glyph'],
+    columns: ['columns', 'column', 'cols'],
+    layout: ['layout', 'arrangement'],
+    align: ['align', 'alignment'],
+    hover: ['hover'],
+    accent: ['accent', 'highlight', 'primary'],
+    secondary: ['secondary']
+};
+const INCREASE_VERBS = new Set([
+    'increase', 'bump', 'raise', 'grow', 'expand', 'add', 'more', 'bigger',
+    'larger', 'taller', 'wider', 'thicker', 'looser', 'up', 'boost', 'enlarge'
+]);
+const DECREASE_VERBS = new Set([
+    'decrease', 'reduce', 'lower', 'shrink', 'subtract', 'remove', 'less',
+    'smaller', 'shorter', 'narrower', 'thinner', 'tighter', 'down', 'cut', 'trim'
+]);
+/** Words that carry no property signal when they show up in a schema label. */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'your', 'you', 'this', 'that', 'from', 'into',
+    'widget', 'element', 'value', 'option', 'input', 'setting', 'settings', 'use',
+    'when', 'will', 'are', 'all', 'its', 'out', 'off', 'not', 'own'
+]);
+function splitIdentifier(raw) {
+    return String(raw || '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_\-.]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .split(' ')
+        .filter(Boolean);
+}
+function normalizeHex(hex) {
+    let h = hex.replace('#', '').trim().toLowerCase();
+    if (h.length === 3)
+        h = h.split('').map((c) => c + c).join('');
+    return `#${h}`;
+}
+function rgbToHex(r, g, b) {
+    const to = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0');
+    return `#${to(r)}${to(g)}${to(b)}`;
+}
+function clampAndSnap(value, min, max, step) {
+    let v = value;
+    if (typeof min === 'number' && v < min)
+        v = min;
+    if (typeof max === 'number' && v > max)
+        v = max;
+    if (typeof step === 'number' && step > 0) {
+        const base = typeof min === 'number' ? min : 0;
+        v = base + Math.round((v - base) / step) * step;
+        // Round to a sane number of decimals for float steps.
+        v = Math.round(v * 1e6) / 1e6;
+        if (typeof min === 'number' && v < min)
+            v = min;
+        if (typeof max === 'number' && v > max)
+            v = max;
+    }
+    return v;
+}
+function toNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    return null;
+}
+/** Flatten whatever schema shape the codegen produced into a flat property list. */
+export function collectDesignProperties(schema) {
+    const out = [];
+    if (!schema)
+        return out;
+    const root = Array.isArray(schema)
+        ? { componentGroups: schema }
+        : schema;
+    const groups = (root.componentGroups ?? root.components);
+    const groupList = Array.isArray(groups) ? groups : [];
+    const pushProperty = (raw) => {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const p = raw;
+        const id = String(p.name ?? p.id ?? '').trim();
+        if (!id)
+            return;
+        const ic = (p.inputController ?? {});
+        const config = (ic.config ?? {});
+        const rawOptions = ic.options ?? config.options ?? p.options;
+        const options = Array.isArray(rawOptions)
+            ? rawOptions
+                .map((o) => {
+                if (o && typeof o === 'object') {
+                    const oo = o;
+                    return { label: String(oo.label ?? oo.value ?? ''), value: String(oo.value ?? oo.label ?? '') };
+                }
+                return { label: String(o), value: String(o) };
+            })
+                .filter((o) => o.value !== '')
+            : [];
+        const constraints = (p.constraints ?? {});
+        const pickNum = (...vals) => {
+            for (const v of vals) {
+                const n = toNumber(v);
+                if (n !== null)
+                    return n;
+            }
+            return undefined;
+        };
+        out.push({
+            id,
+            label: String(ic.description ?? ic.label ?? p.label ?? id),
+            controllerType: String(ic.type ?? p.type ?? '').toLowerCase(),
+            value: p.value ?? p.defaultValue,
+            defaultValue: p.defaultValue,
+            options,
+            min: pickNum(config.min, constraints.min),
+            max: pickNum(config.max, constraints.max),
+            step: pickNum(config.step, constraints.step),
+            helpText: typeof ic.helpText === 'string' ? ic.helpText : undefined
+        });
+    };
+    for (const group of groupList) {
+        if (!group || typeof group !== 'object')
+            continue;
+        const components = (group.components ?? []);
+        const componentList = Array.isArray(components) ? components : [];
+        for (const component of componentList) {
+            if (!component || typeof component !== 'object')
+                continue;
+            const c = component;
+            const direct = c.properties;
+            if (Array.isArray(direct))
+                direct.forEach(pushProperty);
+            const propertyGroups = c.propertyGroups;
+            if (Array.isArray(propertyGroups)) {
+                for (const pg of propertyGroups) {
+                    const props = pg?.properties;
+                    if (Array.isArray(props))
+                        props.forEach(pushProperty);
+                }
+            }
+        }
+    }
+    return out;
+}
+/** Extract a numeric operand + mode from the message (code side owns arithmetic). */
+function extractNumberOperand(message) {
+    const text = message.toLowerCase();
+    // Direction verb, scanned over the whole message (word order is unreliable).
+    let sign = 0;
+    for (const word of text.match(/\b[a-z]+\b/g) ?? []) {
+        if (INCREASE_VERBS.has(word))
+            sign = 1;
+        else if (DECREASE_VERBS.has(word))
+            sign = -1;
+    }
+    const multiply = text.match(/\b(double|twice|triple|quadruple)\b/);
+    if (multiply) {
+        const factor = { double: 2, twice: 2, triple: 3, quadruple: 4 }[multiply[1]] ?? 2;
+        return { mode: 'multiply', value: factor, sign: 1 };
+    }
+    if (/\b(half|halve)\b/.test(text)) {
+        return { mode: 'divide', value: 2, sign: 1 };
+    }
+    // Percentage delta: "increase by 20%", "20% smaller", "reduce padding 25%".
+    const pct = text.match(/(\d+(?:\.\d+)?)\s*%/);
+    if (pct) {
+        return { mode: 'percent', value: Number(pct[1]), sign: sign === 0 ? 1 : sign };
+    }
+    // Absolute delta: a delta verb near a number ("increase padding by 8", "reduce 4").
+    const absDelta = text.match(/\b(increase|decrease|reduce|bump|raise|lower|grow|shrink|expand|add|subtract|remove|boost|trim|cut|more|less|bigger|smaller)\b[^0-9]{0,16}(\d+(?:\.\d+)?)/);
+    if (absDelta) {
+        const dir = INCREASE_VERBS.has(absDelta[1]) ? 1 : -1;
+        return { mode: 'delta', value: Number(absDelta[2]), sign: dir };
+    }
+    // Trailing delta: "8 more", "4 smaller".
+    const trailing = text.match(/(\d+(?:\.\d+)?)\s*(more|less|bigger|smaller)\b/);
+    if (trailing) {
+        return { mode: 'delta', value: Number(trailing[1]), sign: INCREASE_VERBS.has(trailing[2]) ? 1 : -1 };
+    }
+    // Signed delta: "+8" / "-4" (a hex color has no '+'/'-', so no collision).
+    const signed = text.match(/(?:^|[\s(])([+-])\s*(\d+(?:\.\d+)?)(?![\w.])/);
+    if (signed) {
+        return { mode: 'delta', value: Number(signed[2]), sign: signed[1] === '-' ? -1 : 1 };
+    }
+    // Explicit set: the first bare number.
+    const plain = text.match(/(\d+(?:\.\d+)?)/);
+    if (plain) {
+        return { mode: 'set', value: Number(plain[1]), sign: 1 };
+    }
+    return null;
+}
+function extractColor(message) {
+    const hex = message.match(/#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})\b/);
+    if (hex)
+        return { hex: normalizeHex(hex[0]), named: false };
+    const rgb = message.match(/rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})/);
+    if (rgb)
+        return { hex: rgbToHex(Number(rgb[1]), Number(rgb[2]), Number(rgb[3])), named: false };
+    const words = message.toLowerCase().match(/\b[a-z]+\b/g) ?? [];
+    for (const w of words) {
+        if (NAMED_COLORS[w])
+            return { hex: NAMED_COLORS[w], named: true };
+    }
+    return null;
+}
+function extractQuotedText(message) {
+    const m = message.match(/["“”'‘’]([^"“”'‘’]{1,200})["“”'‘’]/);
+    return m ? m[1].trim() : null;
+}
+/** Score how strongly the message names this property. 0 means "not named". */
+function nameMatchScore(message, property) {
+    const msgWords = new Set(message.toLowerCase().match(/[a-z]+/g) ?? []);
+    if (msgWords.size === 0)
+        return 0;
+    const propWords = new Set([
+        ...splitIdentifier(property.id),
+        ...splitIdentifier(property.label)
+    ]);
+    let score = 0;
+    for (const pw of propWords) {
+        if (!pw || pw.length < 3 || STOPWORDS.has(pw))
+            continue;
+        // Direct word hit.
+        if (msgWords.has(pw)) {
+            score += 2;
+            continue;
+        }
+        // Synonym hit (either direction).
+        const syns = WORD_SYNONYMS[pw] ?? [];
+        if (syns.some((s) => msgWords.has(s)))
+            score += 1;
+    }
+    // A whole-id substring hit is a strong signal ("backgroundcolor").
+    const compact = property.id.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const msgCompact = message.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (compact.length >= 6 && msgCompact.includes(compact))
+        score += 3;
+    return score;
+}
+function booleanFromMessage(message) {
+    const text = message.toLowerCase();
+    const flip = /\b(turn|switch|set)\b/.test(text);
+    const hasOn = /\b(enable[ds]?|show|visible|true|yes|add)\b/.test(text) || (flip && /\bon\b/.test(text));
+    const hasOff = /\b(disable[ds]?|hide|hidden|false|no|remove)\b/.test(text) || (flip && /\boff\b/.test(text));
+    if (hasOn && hasOff)
+        return null;
+    if (hasOn)
+        return true;
+    if (hasOff)
+        return false;
+    return null;
+}
+function buildCandidate(property, message) {
+    const type = property.controllerType;
+    const current = property.value !== undefined ? property.value : property.defaultValue;
+    if (COLOR_CONTROLLERS.has(type)) {
+        const color = extractColor(message);
+        if (color)
+            return { property, value: color.hex, reason: color.named ? 'named-color' : 'explicit-color' };
+        return null;
+    }
+    if (NUMBER_CONTROLLERS.has(type)) {
+        const operand = extractNumberOperand(message);
+        if (!operand)
+            return null;
+        if (operand.mode === 'set') {
+            return {
+                property,
+                value: clampAndSnap(operand.value, property.min, property.max, property.step),
+                reason: 'explicit-number'
+            };
+        }
+        const cur = toNumber(current);
+        if (cur === null)
+            return null;
+        let next;
+        if (operand.mode === 'multiply')
+            next = cur * operand.value;
+        else if (operand.mode === 'divide')
+            next = cur / operand.value;
+        else if (operand.mode === 'percent')
+            next = cur * (1 + (operand.sign * operand.value) / 100);
+        else
+            next = cur + operand.sign * operand.value;
+        return {
+            property,
+            value: clampAndSnap(next, property.min, property.max, property.step),
+            reason: 'delta-number'
+        };
+    }
+    if (BOOLEAN_CONTROLLERS.has(type)) {
+        const b = booleanFromMessage(message);
+        if (b === null)
+            return null;
+        return { property, value: b, reason: 'boolean' };
+    }
+    if (OPTION_CONTROLLERS.has(type)) {
+        const msgWords = new Set(message.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+        for (const opt of property.options) {
+            const optWords = [
+                ...splitIdentifier(opt.label),
+                ...splitIdentifier(opt.value)
+            ].filter((w) => w.length >= 3);
+            if (optWords.length > 0 && optWords.every((w) => msgWords.has(w))) {
+                return { property, value: opt.value, reason: 'option' };
+            }
+        }
+        return null;
+    }
+    if (TEXT_CONTROLLERS.has(type)) {
+        const text = extractQuotedText(message);
+        if (text)
+            return { property, value: text, reason: 'explicit-text' };
+        return null;
+    }
+    return null;
+}
+/**
+ * Properties the message names (directly or by synonym), strongest first.
+ * Used by the shadow-mode telemetry classifier to bucket a command without
+ * resolving a value for it.
+ */
+export function scoreDesignProperties(message, schema) {
+    const raw = String(message ?? '').trim();
+    return collectDesignProperties(schema)
+        .map((property) => ({ property, score: nameMatchScore(raw, property) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Resolve a chat message into concrete design-property changes, deterministically.
+ * Returns `null` when the message is not an unambiguous, in-scope design tweak —
+ * the caller should then fall through to the existing codegen path.
+ */
+export function resolveDesignIntent(message, schema, currentValues) {
+    const raw = String(message ?? '').trim();
+    if (!raw || raw.length > 400)
+        return null;
+    const properties = collectDesignProperties(schema);
+    if (properties.length === 0)
+        return null;
+    const scored = [];
+    for (const property of properties) {
+        const withScore = buildCandidate(property, raw);
+        if (!withScore)
+            continue;
+        const score = nameMatchScore(raw, property);
+        if (score <= 0)
+            continue;
+        scored.push({ ...withScore, score });
+    }
+    if (scored.length === 0)
+        return null;
+    // Deterministic ordering: score desc, then schema order for stability.
+    scored.sort((a, b) => b.score - a.score);
+    // Ambiguity guard: a tie between two different, equally-named properties means
+    // we cannot be sure which one the user meant — bail to the codegen path.
+    const top = scored.filter((c) => c.score === scored[0].score);
+    const distinctIds = new Set(top.map((c) => c.property.id));
+    if (distinctIds.size > 1)
+        return null;
+    const winner = scored[0];
+    // If the caller passed live current values, prefer them over the schema default.
+    if (currentValues && Object.prototype.hasOwnProperty.call(currentValues, winner.property.id)) {
+        winner.property = { ...winner.property, value: currentValues[winner.property.id] };
+    }
+    const previousValue = winner.property.value;
+    const change = {
+        propertyId: winner.property.id,
+        label: winner.property.label,
+        controllerType: winner.property.controllerType,
+        previousValue,
+        value: winner.value,
+        reason: winner.reason
+    };
+    return {
+        changes: [change],
+        summary: buildSummary(change)
+    };
+}
+function formatValue(value) {
+    if (typeof value === 'boolean')
+        return value ? 'on' : 'off';
+    if (value === null || value === undefined)
+        return '—';
+    return String(value);
+}
+function buildSummary(change) {
+    const verb = {
+        'explicit-color': 'Set',
+        'named-color': 'Set',
+        'explicit-number': 'Set',
+        'delta-number': 'Adjusted',
+        boolean: 'Turned',
+        option: 'Changed',
+        'explicit-text': 'Set'
+    };
+    return `${verb[change.reason]} ${change.label} to ${formatValue(change.value)}.`;
+}
+/** Build the chat card payload from a resolution (used to render inline controls). */
+export function toDesignControlRequest(resolution, schema, _currentValues, compositionId) {
+    const byId = new Map(collectDesignProperties(schema).map((p) => [p.id, p]));
+    const properties = resolution.changes.map((change) => {
+        const schemaProp = byId.get(change.propertyId);
+        return {
+            id: change.propertyId,
+            label: change.label,
+            controllerType: change.controllerType,
+            // The value the change resolved to — the card shows what was just applied.
+            value: change.value,
+            options: schemaProp?.options,
+            min: schemaProp?.min,
+            max: schemaProp?.max,
+            step: schemaProp?.step,
+            helpText: schemaProp?.helpText
+        };
+    });
+    return {
+        summary: resolution.summary,
+        properties,
+        ...(compositionId ? { compositionId } : {})
+    };
+}

package/dist/utils/designIntentResolver.test.d.ts

@@ -0,0 +1 @@
+export {};