@lushly-dev/fast-element 0.0.0-stage → 3.0.1-preview.1

package/dist/esm/definition-schema/api.js

@@ -0,0 +1,129 @@
+import { getClassByTag, getRegistryTagMap, getSchemaByClass } from "./storage.js";
+/**
+ * Retrieves the schema for a custom element by its tag name.
+ * @param name - The custom element tag name.
+ * @param registry - The custom element registry (defaults to global customElements).
+ * @returns The component schema if found, undefined otherwise.
+ * @public
+ */
+export function getSchema(name, registry = customElements) {
+    const cls = getClassByTag(name, registry);
+    if (!cls)
+        return undefined;
+    const schema = getSchemaByClass(cls);
+    if (!schema)
+        return undefined;
+    // Clone with actual tag name (may differ per registration)
+    return Object.assign(Object.assign({}, schema), { name });
+}
+/**
+ * Retrieves the schema for a custom element by its tag name, throwing if not found.
+ * @param name - The custom element tag name.
+ * @param registry - The custom element registry (defaults to global customElements).
+ * @returns The component schema.
+ * @throws TypeError if no schema is found for the element.
+ * @public
+ */
+export function getSchemaOrThrow(name, registry = customElements) {
+    const schema = getSchema(name, registry);
+    if (!schema) {
+        throw new TypeError(`No schema found for element: ${name}`);
+    }
+    return schema;
+}
+/**
+ * Retrieves the schema for a FASTElement class directly.
+ * @param cls - The FASTElement class constructor.
+ * @returns The component schema.
+ * @throws TypeError if the class is not a registered FASTElement.
+ * @public
+ */
+export function getComponentSchema(cls) {
+    const schema = getSchemaByClass(cls);
+    if (!schema) {
+        throw new TypeError(`Class is not a registered FASTElement`);
+    }
+    return schema;
+}
+/**
+ * Retrieves all registered component schemas for a given registry.
+ * @param registry - The custom element registry (defaults to global customElements).
+ * @returns A Map of tag names to component schemas.
+ * @public
+ */
+export function getAllSchemas(registry = customElements) {
+    const result = new Map();
+    const tagMap = getRegistryTagMap(registry);
+    if (tagMap) {
+        for (const [name, cls] of tagMap) {
+            const schema = getSchemaByClass(cls);
+            if (schema) {
+                result.set(name, Object.assign(Object.assign({}, schema), { name }));
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Compares two component schemas and returns the differences.
+ * Used to detect breaking changes between versions.
+ * @param a - The original schema (before).
+ * @param b - The new schema (after).
+ * @returns A SchemaDiff object describing the changes.
+ * @public
+ */
+export function diffSchemas(a, b) {
+    const added = { properties: [], events: [], slots: [] };
+    const removed = { properties: [], events: [], slots: [] };
+    const changed = { properties: [], events: [] };
+    // Compare properties by name
+    const aProps = new Map(a.properties.map(p => [p.name, p]));
+    const bProps = new Map(b.properties.map(p => [p.name, p]));
+    for (const [name, prop] of bProps) {
+        if (!aProps.has(name)) {
+            added.properties.push(prop);
+        }
+        else if (JSON.stringify(aProps.get(name)) !== JSON.stringify(prop)) {
+            changed.properties.push({ before: aProps.get(name), after: prop });
+        }
+    }
+    for (const [name, prop] of aProps) {
+        if (!bProps.has(name)) {
+            removed.properties.push(prop);
+        }
+    }
+    // Compare events by name
+    const aEvents = new Map(a.events.map(e => [e.name, e]));
+    const bEvents = new Map(b.events.map(e => [e.name, e]));
+    for (const [name, event] of bEvents) {
+        if (!aEvents.has(name)) {
+            added.events.push(event);
+        }
+        else if (JSON.stringify(aEvents.get(name)) !== JSON.stringify(event)) {
+            changed.events.push({ before: aEvents.get(name), after: event });
+        }
+    }
+    for (const [name, event] of aEvents) {
+        if (!bEvents.has(name)) {
+            removed.events.push(event);
+        }
+    }
+    // Compare slots by name
+    const aSlots = new Map(a.slots.map(s => [s.name, s]));
+    const bSlots = new Map(b.slots.map(s => [s.name, s]));
+    for (const [name, slot] of bSlots) {
+        if (!aSlots.has(name)) {
+            added.slots.push(slot);
+        }
+    }
+    for (const [name, slot] of aSlots) {
+        if (!bSlots.has(name)) {
+            removed.slots.push(slot);
+        }
+    }
+    // Breaking changes: removed properties/events, or changed properties
+    const breaking = removed.properties.length > 0 ||
+        removed.events.length > 0 ||
+        changed.properties.length > 0;
+    return { added, removed, changed, breaking };
+}

package/dist/esm/definition-schema/cem.js

@@ -0,0 +1,89 @@
+import { getRegistryTagMap, getSchemaByClass } from "./storage.js";
+/**
+ * Converts a kebab-case string to PascalCase.
+ * @param str - The kebab-case string to convert.
+ * @returns The PascalCase version of the string.
+ * @example
+ * toPascalCase('my-button') // 'MyButton'
+ * toPascalCase('my-cool-element') // 'MyCoolElement'
+ * @public
+ */
+export function toPascalCase(str) {
+    return str
+        .split("-")
+        .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+}
+/**
+ * Converts a ComponentSchema to a ManifestDeclaration.
+ * @param name - The tag name of the component.
+ * @param schema - The component schema to convert.
+ * @returns The manifest declaration.
+ */
+function toManifestDeclaration(name, schema) {
+    const declaration = {
+        kind: "class",
+        customElement: true,
+        name: toPascalCase(name),
+        tagName: name,
+        members: schema.properties.map(p => ({
+            kind: "field",
+            name: p.name,
+            type: { text: p.type },
+        })),
+        events: schema.events.map(e => ({
+            name: e.name,
+            type: { text: "CustomEvent" },
+        })),
+        slots: schema.slots.map(s => ({
+            name: s.name,
+            description: s.description,
+        })),
+        cssProperties: schema.cssProperties.map(c => ({
+            name: c.name,
+            default: c.default,
+        })),
+    };
+    if (schema.description) {
+        declaration.description = schema.description;
+    }
+    return declaration;
+}
+/**
+ * Generates a Custom Elements Manifest (CEM 2.1.0) from registered schemas.
+ *
+ * @param registry - The custom element registry to export from (defaults to global customElements).
+ * @returns A Custom Elements Manifest object conforming to CEM 2.1.0 schema.
+ *
+ * @remarks
+ * The manifest groups each component into its own module with a synthesized path
+ * based on the tag name (e.g., `my-button.js`). This is suitable for documentation
+ * and tooling purposes but may not reflect actual file paths.
+ *
+ * @example
+ * ```typescript
+ * const manifest = toCustomElementsManifest();
+ * console.log(JSON.stringify(manifest, null, 2));
+ * ```
+ * @public
+ */
+export function toCustomElementsManifest(registry) {
+    const tagMap = getRegistryTagMap(registry);
+    const modules = [];
+    if (tagMap) {
+        for (const [name, cls] of tagMap) {
+            const schema = getSchemaByClass(cls);
+            if (schema) {
+                modules.push({
+                    kind: "javascript-module",
+                    path: `${name}.js`,
+                    declarations: [toManifestDeclaration(name, schema)],
+                });
+            }
+        }
+    }
+    return {
+        schemaVersion: "2.1.0",
+        modules,
+    };
+}

package/dist/esm/definition-schema/extension.js

@@ -0,0 +1,53 @@
+import { registerFASTElementExtension, } from "../components/fast-definitions.js";
+import { Observable } from "../observation/observable.js";
+import { buildSchema } from "./extract.js";
+import { registerTag, storeSchema } from "./storage.js";
+const templateSubscribers = new WeakMap();
+function storeDefinitionSchema(definition, registry) {
+    storeSchema(definition.type, buildSchema(definition, definition.type));
+    registerTag(definition.name, definition.type, registry);
+}
+/**
+ * Extracts and stores the Agent Definition Schema for a FAST element.
+ * @internal
+ */
+export const definitionSchemaExtension = (definition, registry) => {
+    storeDefinitionSchema(definition, registry);
+    if (definition.template !== void 0 || templateSubscribers.has(definition)) {
+        return;
+    }
+    const notifier = Observable.getNotifier(definition);
+    const subscriber = {
+        handleChange() {
+            if (definition.template === void 0) {
+                return;
+            }
+            storeDefinitionSchema(definition, registry);
+            notifier.unsubscribe(subscriber, "template");
+            templateSubscribers.delete(definition);
+        },
+    };
+    templateSubscribers.set(definition, subscriber);
+    notifier.subscribe(subscriber, "template");
+};
+let disableRegisteredExtension;
+/**
+ * Enables automatic Definition Schema extraction for subsequently defined FAST elements.
+ * Call this before element definitions are registered.
+ * @returns A callback that disables automatic extraction.
+ * @public
+ */
+export function enableDefinitionSchema() {
+    if (disableRegisteredExtension === void 0) {
+        disableRegisteredExtension = registerFASTElementExtension(definitionSchemaExtension);
+    }
+    return disableDefinitionSchema;
+}
+/**
+ * Disables automatic Definition Schema extraction.
+ * @public
+ */
+export function disableDefinitionSchema() {
+    disableRegisteredExtension === null || disableRegisteredExtension === void 0 ? void 0 : disableRegisteredExtension();
+    disableRegisteredExtension = void 0;
+}

package/dist/esm/definition-schema/extract.js

@@ -0,0 +1,167 @@
+import { getCommandMetadata } from "../command/command.js";
+/**
+ * Maps attribute mode to PropertyType.
+ * @param mode - The attribute mode ('boolean', 'reflect', 'fromView').
+ * @returns The corresponding PropertyType.
+ */
+function modeToPropertyType(mode) {
+    switch (mode) {
+        case "boolean":
+            return "boolean";
+        default:
+            return "string";
+    }
+}
+/**
+ * Extracts property schemas from a FASTElementDefinition's attributes.
+ * @param definition - The FASTElementDefinition to extract properties from.
+ * @returns An array of PropertySchema objects.
+ */
+export function extractProperties(definition) {
+    const properties = [];
+    const attributes = definition.attributes;
+    for (const attr of attributes) {
+        const property = {
+            name: attr.name,
+            type: modeToPropertyType(attr.mode),
+            attribute: attr.attribute,
+        };
+        properties.push(property);
+    }
+    return properties;
+}
+/**
+ * Extracts slot schemas from a template.
+ * Returns empty array in SSR environments where document is undefined.
+ * @param template - The ElementViewTemplate to extract slots from.
+ * @returns An array of SlotSchema objects.
+ */
+export function extractSlots(template) {
+    var _a, _b;
+    // Guard: Return empty array in SSR environment
+    if (typeof document === "undefined" || !template) {
+        return [];
+    }
+    const slots = [];
+    try {
+        // Create a temporary host element to extract template content
+        const tempHost = document.createElement("div");
+        const view = template.create(tempHost);
+        view.appendTo(tempHost);
+        for (const slotElement of Array.from(tempHost.querySelectorAll("slot"))) {
+            const name = (_a = slotElement.getAttribute("name")) !== null && _a !== void 0 ? _a : "";
+            const description = (_b = slotElement.getAttribute("data-description")) !== null && _b !== void 0 ? _b : undefined;
+            slots.push({
+                name,
+                description,
+            });
+        }
+        view.dispose();
+    }
+    catch (_c) {
+        // If template extraction fails, return empty array
+        return [];
+    }
+    return slots;
+}
+/**
+ * Regex pattern to match CSS custom properties.
+ * Matches: --property-name: value;
+ */
+const cssPropertyRegex = /(--[\w-]+):\s*([^;]+)/g;
+/**
+ * Extracts CSS custom property schemas from styles.
+ * Uses naive regex extraction (v1); will upgrade to CSSTree in v2.
+ * @param styles - The ElementStyles to extract CSS properties from.
+ * @returns An array of CSSPropertySchema objects.
+ */
+export function extractCSSProperties(styles) {
+    if (!styles) {
+        return [];
+    }
+    const cssProperties = [];
+    const seenProperties = new Set();
+    for (const style of styles.styles) {
+        let cssText;
+        if (typeof style === "string") {
+            cssText = style;
+        }
+        else if (typeof CSSStyleSheet !== "undefined" &&
+            style instanceof CSSStyleSheet) {
+            // Extract text from CSSStyleSheet rules
+            try {
+                const rules = style.cssRules;
+                const textParts = [];
+                for (let i = 0; i < rules.length; i++) {
+                    textParts.push(rules[i].cssText);
+                }
+                cssText = textParts.join("\n");
+            }
+            catch (_a) {
+                // CSSStyleSheet may not be accessible in some environments
+                continue;
+            }
+        }
+        if (cssText) {
+            let match;
+            // Reset regex lastIndex for each new string
+            cssPropertyRegex.lastIndex = 0;
+            while ((match = cssPropertyRegex.exec(cssText)) !== null) {
+                const name = match[1];
+                const defaultValue = match[2].trim();
+                // Avoid duplicates
+                if (!seenProperties.has(name)) {
+                    seenProperties.add(name);
+                    cssProperties.push({
+                        name,
+                        default: defaultValue,
+                    });
+                }
+            }
+        }
+    }
+    return cssProperties;
+}
+/**
+ * Extracts command schemas from a component class via `command` metadata.
+ * @param type - The class constructor to extract commands from.
+ * @returns An array of CommandSchema objects.
+ */
+export function extractCommands(type) {
+    const metadata = getCommandMetadata(type);
+    return metadata.map(meta => ({
+        id: meta.id,
+        methodName: meta.methodName,
+        label: meta.label,
+        icon: meta.icon,
+        description: meta.description,
+        category: meta.category,
+        keybinding: meta.keybinding,
+        parameters: meta.parameters,
+        when: meta.when,
+        hidden: meta.hidden,
+    }));
+}
+/**
+ * Builds a complete ComponentSchema from a FASTElementDefinition.
+ * Combines property, slot, CSS property, and command extraction.
+ * @param definition - The FASTElementDefinition to build a schema from.
+ * @param type - The class constructor for the component.
+ * @returns A complete ComponentSchema object.
+ */
+export function buildSchema(definition, type) {
+    const properties = extractProperties(definition);
+    const slots = extractSlots(definition.template);
+    const cssProperties = extractCSSProperties(definition.styles);
+    const commands = extractCommands(type);
+    return {
+        name: definition.name,
+        version: undefined, // Phase 2: Extract from decorator or package.json
+        description: undefined, // Phase 2: Extract from JSDoc
+        properties,
+        events: [], // Phase 2: Extract from JSDoc or decorator
+        slots,
+        cssProperties,
+        commands,
+    };
+}

package/dist/esm/definition-schema/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public API for the Definition Schema system.
+ * Enables AI agents to query component capabilities via JSON introspection.
+ */
+// Re-export all API functions
+export { getSchema, getSchemaOrThrow, getComponentSchema, getAllSchemas, diffSchemas, } from "./api.js";
+export { toCustomElementsManifest, toPascalCase } from "./cem.js";
+export { disableDefinitionSchema, enableDefinitionSchema } from "./extension.js";

package/dist/esm/definition-schema/storage.js

@@ -0,0 +1,58 @@
+/**
+ * Schema storage: WeakMap keyed by class.
+ * Uses WeakMap to allow garbage collection when classes are no longer referenced.
+ */
+const schemaMap = new WeakMap();
+/**
+ * Tag-to-class mapping per registry.
+ * Enables lookup of component class by tag name within a specific registry.
+ */
+const registryTagMap = new WeakMap();
+/**
+ * Stores a component schema associated with its class constructor.
+ * @param cls - The class constructor for the component.
+ * @param schema - The component schema to store.
+ */
+export function storeSchema(cls, schema) {
+    schemaMap.set(cls, schema);
+}
+/**
+ * Retrieves a component schema by its class constructor.
+ * @param cls - The class constructor to look up.
+ * @returns The component schema if found, undefined otherwise.
+ */
+export function getSchemaByClass(cls) {
+    return schemaMap.get(cls);
+}
+/**
+ * Registers a tag name to class mapping within a registry.
+ * @param name - The custom element tag name.
+ * @param cls - The class constructor for the component.
+ * @param registry - The custom element registry (defaults to global customElements).
+ */
+export function registerTag(name, cls, registry = customElements) {
+    if (!registryTagMap.has(registry)) {
+        registryTagMap.set(registry, new Map());
+    }
+    registryTagMap.get(registry).set(name, cls);
+}
+/**
+ * Retrieves a class constructor by its tag name within a registry.
+ * @param name - The custom element tag name to look up.
+ * @param registry - The custom element registry (defaults to global customElements).
+ * @returns The class constructor if found, undefined otherwise.
+ */
+export function getClassByTag(name, registry = customElements) {
+    var _a;
+    return (_a = registryTagMap.get(registry)) === null || _a === void 0 ? void 0 : _a.get(name);
+}
+/**
+ * Gets the tag map for a specific registry.
+ * Used internally by getAllSchemas to iterate over registered tags.
+ * @param registry - The custom element registry.
+ * @returns The Map of tag names to classes, or undefined if no tags registered.
+ * @internal
+ */
+export function getRegistryTagMap(registry = customElements) {
+    return registryTagMap.get(registry);
+}

package/dist/esm/definition-schema/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for the Definition Schema system.
+ * Enables AI agents to query component capabilities via JSON introspection.
+ *
+ * @remarks
+ * This module contains types only - no runtime code.
+ */
+export {};

package/dist/esm/dev-mode.js

@@ -0,0 +1,22 @@
+import { getDebugMessageLookup } from "./platform.js";
+/**
+ * Whether development-only diagnostics (warnings, `console.debug`) are enabled.
+ *
+ * @remarks
+ * An explicit `DEV_MODE` define always wins. Without one, diagnostics follow FAST's
+ * own dev/prod distinction: they are on once `enableDebug()` has loaded the debug
+ * messages (the debug entry point) and off in the production entry point, so they do
+ * not ship to production by default. It is a function because `enableDebug()` may run
+ * after this module is evaluated.
+ *
+ * @internal
+ */
+export function isDevMode() {
+    if (typeof DEV_MODE !== "undefined") {
+        return DEV_MODE;
+    }
+    for (const _ in getDebugMessageLookup()) {
+        return true;
+    }
+    return false;
+}