@adobe/spectrum-component-api-schemas 5.0.1 → 6.1.0

package/moon.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Adobe. All rights reserved.
+# Copyright 2026 Adobe. All rights reserved.
 # This file is licensed to you under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License. You may obtain a copy
 # of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -10,8 +10,6 @@
 $schema: "https://moonrepo.dev/schemas/project.json"
 layer: library
 fileGroups:
-  schemas:
-    - "schemas/**/*.{yaml,yml,json}"
   tests:
     - "test/**/*"
 tasks:
@@ -20,7 +18,6 @@ tasks:
       - pnpm
       - ava
     inputs:
-      - "@globs(schemas)"
       - "@globs(tests)"
       - "index.js"
       - "ava.config.js"

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "@adobe/spectrum-component-api-schemas",
-  "version": "5.0.1",
+  "version": "6.1.0",
   "description": "",
   "type": "module",
   "main": "index.js",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/adobe/spectrum-tokens.git"
+    "url": "git+https://github.com/adobe/spectrum-design-data.git"
   },
   "author": "Garth Braithwaite <garthdb@gmail.com> (https://garthdb.com/)",
   "bugs": {
-    "url": "https://github.com/adobe/spectrum-tokens/issues"
+    "url": "https://github.com/adobe/spectrum-design-data/issues"
   },
   "publishConfig": {
     "provenance": true
   },
-  "homepage": "https://github.com/adobe/spectrum-tokens/tree/main/packages/component-schemas#readme",
+  "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/packages/component-schemas#readme",
   "license": "Apache-2.0",
   "dependencies": {
-    "glob": "^10.3.12"
+    "glob": "^10.3.12",
+    "@adobe/design-data-spec": "0.4.0"
   },
   "devDependencies": {
     "ajv": "^8.12.0",

package/scripts/convert-to-spec-format.mjs

@@ -0,0 +1,136 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * One-time conversion script: old component-schemas format → new design-data-spec format.
+ *
+ * Reads packages/component-schemas/schemas/components/*.json (old format)
+ * and writes packages/design-data-spec/components/{name}.json (new format).
+ *
+ * Skips button.json (hand-crafted in Phase 6.4).
+ * Run: node packages/component-schemas/scripts/convert-to-spec-format.mjs
+ */
+
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { glob } from "glob";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "../../..");
+const sourceDir = resolve(repoRoot, "packages/component-schemas/schemas/components");
+const destDir = resolve(repoRoot, "packages/design-data-spec/components");
+
+const SKIP = new Set(["button.json"]);
+
+// States that are driven by runtime interaction (vs persistent prop).
+const INTERACTION_STATES = new Set([
+  "hover",
+  "focus",
+  "focus-visible",
+  "active",
+  "pressed",
+  "down",
+  "keyboard-focus",
+  "dragging",
+]);
+
+function toKebabCase(str) {
+  return str.trim().toLowerCase().replace(/\s+/g, "-");
+}
+
+function getSlugFromDocumentationUrl(url) {
+  return url
+    .split("/")
+    .filter((p) => p !== "")
+    .pop();
+}
+
+function convertStateEnum(stateEnum) {
+  if (!Array.isArray(stateEnum)) return [];
+  return stateEnum
+    .filter((v) => v !== "default")
+    .map((v) => {
+      const name = toKebabCase(v);
+      const trigger = INTERACTION_STATES.has(name) ? "interaction" : "prop";
+      return { name, trigger };
+    });
+}
+
+async function convertFile(srcPath, fileName) {
+  const raw = await readFile(srcPath, "utf8");
+  const old = JSON.parse(raw);
+
+  const name = getSlugFromDocumentationUrl(old.meta.documentationUrl);
+  const displayName = old.title;
+
+  // properties → options (remove state; keep everything else)
+  const { state: stateProperty, ...remainingProperties } = old.properties ?? {};
+  const options = Object.keys(remainingProperties).length > 0 ? remainingProperties : undefined;
+
+  // Derive states from old state.enum
+  const stateList = convertStateEnum(stateProperty?.enum);
+  const states = stateList.length > 0 ? stateList : undefined;
+
+  // Build new $id and $schema
+  const newId = (old.$id ?? "").replace(
+    "https://opensource.adobe.com/spectrum-design-data/schemas/components/",
+    "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/",
+  );
+
+  const newDoc = {
+    $schema:
+      "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+    $id: newId,
+    specVersion: "1.0.0-draft",
+    name,
+    displayName,
+    ...(old.description ? { description: old.description } : {}),
+    meta: old.meta,
+    ...(options ? { options } : {}),
+    ...(states ? { states } : {}),
+    lifecycle: { introduced: "1.0.0-draft" },
+  };
+
+  return newDoc;
+}
+
+async function main() {
+  await mkdir(destDir, { recursive: true });
+
+  const srcFiles = (await glob(`${sourceDir}/*.json`)).sort();
+  let converted = 0;
+  let skipped = 0;
+
+  for (const srcPath of srcFiles) {
+    const fileName = srcPath.split("/").pop();
+
+    if (SKIP.has(fileName)) {
+      console.log(`  skip  ${fileName} (hand-crafted)`);
+      skipped++;
+      continue;
+    }
+
+    const newDoc = await convertFile(srcPath, fileName);
+    const destPath = resolve(destDir, fileName);
+    await writeFile(destPath, JSON.stringify(newDoc, null, 2) + "\n", "utf8");
+    console.log(`  write ${fileName} → ${newDoc.name}`);
+    converted++;
+  }
+
+  console.log(`\nDone: ${converted} converted, ${skipped} skipped.`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/test/index.test.js

@@ -1,5 +1,5 @@
 /*
-Copyright 2024 Adobe. All rights reserved.
+Copyright 2026 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy
 of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -16,63 +16,93 @@ import {
   getAllSchemas,
   getSlugFromDocumentationUrl,
   getAllSlugs,
-  __dirname,
+  componentsDir,
   getSchemaBySlug,
 } from "../index.js";
 import test from "ava";
 import { glob } from "glob";
 import { resolve, parse } from "path";
 
-test("the number of schema returned by getAllSchemas should match the number of schema returned by schemaFileNames", async (t) => {
+test("the number of schemas returned by getAllSchemas should match the number of schemaFileNames", async (t) => {
   const allSchemas = await getAllSchemas();
   t.is(schemaFileNames.length, allSchemas.length);
 });
-test("getSchemaFile should fetch schema data", async (t) => {
-  const relativeSchemaComponent = await getSchemaFile("component.json");
-  t.is(relativeSchemaComponent.title, "Component");
 
-  const relativeSchemaActionBar = await getSchemaFile(
-    "components/action-bar.json",
-  );
-  t.is(relativeSchemaActionBar.title, "Action bar");
+test("getSchemaFile should fetch schema data using a relative filename", async (t) => {
+  const schema = await getSchemaFile("action-bar.json");
+  // new-format field
+  t.is(schema.displayName, "Action bar");
+  // backward-compat alias
+  t.is(schema.title, "Action bar");
+  t.truthy(schema.name);
+  t.truthy(schema.meta?.documentationUrl);
+});
 
-  const absoluteSchemaComponent = await getSchemaFile(
-    resolve(__dirname, "schemas", "component.json"),
-  );
-  t.is(absoluteSchemaComponent.title, "Component");
+test("getSchemaFile should fetch schema data using an absolute path", async (t) => {
+  const schema = await getSchemaFile(resolve(componentsDir, "action-bar.json"));
+  t.is(schema.displayName, "Action bar");
+  t.is(schema.title, "Action bar");
+});
 
-  const absoluteSchemaActionBar = await getSchemaFile(
-    resolve(__dirname, "schemas", "components", "action-bar.json"),
-  );
-  t.is(absoluteSchemaActionBar.title, "Action bar");
-  // t.snapshot(await getSchemaFile(schemaFileNames[0]));
+test("getSchemaFile returned objects include backward-compat properties alias", async (t) => {
+  const schema = await getSchemaFile("checkbox.json");
+  // options is the new-format field
+  t.truthy(schema.options);
+  // properties is the compat alias
+  t.is(schema.properties, schema.options);
 });
+
 test("getSlugFromDocumentationUrl should return last part of documentationUrl", (t) => {
   t.is(
     getSlugFromDocumentationUrl("https://spectrum.adobe.com/page/tooltip/"),
     "tooltip",
   );
 });
+
 test("getSlugFromDocumentationUrl should return last part of documentationUrl even without trailing slash", (t) => {
   t.is(
     getSlugFromDocumentationUrl("https://spectrum.adobe.com/page/tooltip"),
     "tooltip",
   );
 });
-test("getAllSlugs should return all component slugs", async (t) => {
-  const slugs = await glob(
-    `${resolve(__dirname, "./schemas/components")}/**/*.json`,
-  );
-  t.deepEqual(
-    await getAllSlugs(),
-    slugs.map((slug) => parse(slug).name).sort(),
-  );
+
+test("getAllSlugs should return all component slugs sorted", async (t) => {
+  // getAllSlugs() extracts slugs from documentationUrl. This asserts that
+  // URL slugs match filename stems — a required invariant for all components.
+  const files = await glob(`${componentsDir}/*.json`);
+  const expected = files.map((f) => parse(f).name).sort();
+  t.deepEqual(await getAllSlugs(), expected);
 });
-test("getSchemaBySlug should return a schema", async (t) => {
-  t.deepEqual(
-    await getSchemaBySlug("tooltip"),
-    await getSchemaFile(
-      resolve(__dirname, "./schemas/components/tooltip.json"),
-    ),
-  );
+
+test("getAllSchemas should include slug, title, displayName, properties, and options on each schema", async (t) => {
+  const schemas = await getAllSchemas();
+  for (const schema of schemas) {
+    if (
+      Object.hasOwn(schema, "meta") &&
+      Object.hasOwn(schema.meta, "documentationUrl")
+    ) {
+      t.truthy(schema.slug, `${schema.name}: missing slug`);
+      t.truthy(schema.displayName, `${schema.name}: missing displayName`);
+      t.is(
+        schema.title,
+        schema.displayName,
+        `${schema.name}: title alias mismatch`,
+      );
+      t.truthy(schema.name, `${schema.name}: missing name`);
+    }
+  }
+});
+
+test("getSchemaBySlug should return a schema without a slug field", async (t) => {
+  const schema = await getSchemaBySlug("tooltip");
+  t.is(schema.displayName, "Tooltip");
+  t.is(schema.title, "Tooltip");
+  t.is(schema.name, "tooltip");
+  t.false(Object.hasOwn(schema, "slug"));
+});
+
+test("getSchemaBySlug should throw for unknown slug", async (t) => {
+  await t.throwsAsync(async () => getSchemaBySlug("not-a-real-component"), {
+    message: /Schema not found for slug: not-a-real-component/,
+  });
 });

package/test/integration.test.js

@@ -5,9 +5,9 @@ import {
   getAllSlugs,
   getSlugFromDocumentationUrl,
   schemaFileNames,
+  componentsDir,
 } from "../index.js";
-import { getSchemaFiles } from "./utils/test-helpers.js";
-import { relative } from "path";
+import { glob } from "glob";
 
 test("getAllSchemas should return all schemas with slugs", async (t) => {
   const schemas = await getAllSchemas();
@@ -83,15 +83,13 @@ test("getSlugFromDocumentationUrl should handle various URL formats", (t) => {
 });
 
 test("schemaFileNames should match actual files on disk", async (t) => {
-  const actualFiles = await getSchemaFiles();
+  const actualFiles = await glob(`${componentsDir}/*.json`);
 
   t.is(schemaFileNames.length, actualFiles.length);
 
-  // Verify all files in schemaFileNames exist
   for (const fileName of schemaFileNames) {
-    const relativePath = relative(process.cwd(), fileName);
     t.true(
-      actualFiles.includes(relativePath),
+      actualFiles.includes(fileName),
       `File ${fileName} not found on disk`,
     );
   }

package/test/performance.test.js

@@ -49,24 +49,24 @@ test("getSchemaBySlug should complete within reasonable time", async (t) => {
   const end = performance.now();
   const duration = end - start;
 
-  // Should complete within 100ms
+  // Should complete within 250ms (increased for CI environments)
   t.true(
-    duration < 100,
-    `getSchemaBySlug took ${duration.toFixed(2)}ms, expected < 100ms`,
+    duration < 250,
+    `getSchemaBySlug took ${duration.toFixed(2)}ms, expected < 250ms`,
   );
   t.truthy(schema);
 });
 
 test("getSchemaFile should complete within reasonable time", async (t) => {
   const start = performance.now();
-  const schema = await getSchemaFile("component.json");
+  const schema = await getSchemaFile("button.json");
   const end = performance.now();
   const duration = end - start;
 
-  // Should complete within 200ms (increased for CI environment stability)
+  // Should complete within 500ms (generous for CI runner variability)
   t.true(
-    duration < 200,
-    `getSchemaFile took ${duration.toFixed(2)}ms, expected < 200ms`,
+    duration < 500,
+    `getSchemaFile took ${duration.toFixed(2)}ms, expected < 500ms`,
   );
   t.truthy(schema);
 });
@@ -89,10 +89,10 @@ test("multiple concurrent getSchemaBySlug calls should complete efficiently", as
   const end = performance.now();
   const duration = end - start;
 
-  // Should complete within 200ms for 3 concurrent calls
+  // Should complete within 500ms for 3 concurrent calls (generous for CI runner variability)
   t.true(
-    duration < 200,
-    `Concurrent getSchemaBySlug calls took ${duration.toFixed(2)}ms, expected < 200ms`,
+    duration < 500,
+    `Concurrent getSchemaBySlug calls took ${duration.toFixed(2)}ms, expected < 500ms`,
   );
   t.is(results.length, 3);
   t.true(results.every((schema) => schema !== null));

package/test/schema-validation.test.js

@@ -1,131 +1,90 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
 import test from "ava";
-import {
-  readJSON,
-  getSchemaFiles,
-  createAjvInstance,
-  validateSchema,
-  validateExamples,
-} from "./utils/test-helpers.js";
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { glob } from "glob";
+import { createRequire } from "module";
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import * as url from "url";
 
-// Setup Ajv instance once for all tests
-let ajv;
-
-test.before(async () => {
-  ajv = await createAjvInstance();
-});
-
-test("component schema should be valid", async (t) => {
-  const componentSchema = await readJSON("schemas/component.json");
-  const result = validateSchema(componentSchema, ajv);
+const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
 
-  t.true(
-    result.valid,
-    `Component schema validation failed: ${JSON.stringify(result.errors, null, 2)}`,
-  );
-});
+const specPkgPath = createRequire(import.meta.url).resolve(
+  "@adobe/design-data-spec/package.json",
+);
+const specPkgDir = resolve(specPkgPath, "..");
+const componentsDir = resolve(specPkgDir, "components");
 
-test("all component schemas should validate against the definition", async (t) => {
-  const componentFiles = await getSchemaFiles("schemas/components/*.json");
-  const validationResults = [];
+const readJSON = async (filePath) =>
+  JSON.parse(await readFile(filePath, "utf8"));
 
-  for (const filePath of componentFiles) {
-    const schema = await readJSON(filePath);
-    const result = validateSchema(schema, ajv);
-
-    if (!result.valid) {
-      validationResults.push({
-        file: filePath,
-        errors: result.errors,
-      });
-    }
-  }
+let ajv;
+let componentSchema;
 
-  t.is(
-    validationResults.length,
-    0,
-    `Schema validation failed for:\n${validationResults
-      .map((r) => `${r.file}:\n${JSON.stringify(r.errors, null, 2)}`)
-      .join("\n\n")}`,
+test.before(async () => {
+  componentSchema = await readJSON(
+    resolve(specPkgDir, "schemas/component.schema.json"),
   );
-});
-
-test("all component examples should validate against their schemas", async (t) => {
-  const componentFiles = await getSchemaFiles("schemas/components/*.json");
-  const validationResults = [];
-
-  for (const filePath of componentFiles) {
-    const schema = await readJSON(filePath);
-    const result = validateExamples(schema, ajv);
 
-    if (!result.valid) {
-      validationResults.push({
-        file: filePath,
-        errors: result.errors,
-      });
-    }
-  }
-
-  t.is(
-    validationResults.length,
-    0,
-    `Example validation failed for:\n${validationResults
-      .map((r) => `${r.file}:\n${JSON.stringify(r.errors, null, 2)}`)
-      .join("\n\n")}`,
+  ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  ajv.addSchema(
+    await readJSON(resolve(specPkgDir, "schemas/anatomy-part.schema.json")),
+  );
+  ajv.addSchema(
+    await readJSON(
+      resolve(specPkgDir, "schemas/state-declaration.schema.json"),
+    ),
   );
 });
 
-test("all type schemas should be valid JSON Schema", async (t) => {
-  const typeFiles = await getSchemaFiles("schemas/types/*.json");
-  const validationResults = [];
-
-  for (const filePath of typeFiles) {
-    const schema = await readJSON(filePath);
-    const result = validateSchema(schema, ajv);
+test("all component files should validate against component.schema.json", async (t) => {
+  const componentFiles = (await glob(`${componentsDir}/*.json`)).sort();
+  const validate = ajv.compile(componentSchema);
+  const failures = [];
 
-    if (!result.valid) {
-      validationResults.push({
-        file: filePath,
-        errors: result.errors,
-      });
+  for (const filePath of componentFiles) {
+    const data = await readJSON(filePath);
+    const valid = validate(data);
+    if (!valid) {
+      failures.push({ file: filePath, errors: validate.errors });
     }
   }
 
   t.is(
-    validationResults.length,
+    failures.length,
     0,
-    `Type schema validation failed for:\n${validationResults
-      .map((r) => `${r.file}:\n${JSON.stringify(r.errors, null, 2)}`)
+    `Schema validation failed:\n${failures
+      .map((f) => `${f.file}:\n${JSON.stringify(f.errors, null, 2)}`)
       .join("\n\n")}`,
   );
 });
 
-test("component schemas should have required metadata", async (t) => {
-  const componentFiles = await getSchemaFiles("schemas/components/*.json");
-  const missingMetadata = [];
+test("all component files should have required metadata", async (t) => {
+  const componentFiles = (await glob(`${componentsDir}/*.json`)).sort();
+  const missing = [];
 
   for (const filePath of componentFiles) {
-    const schema = await readJSON(filePath);
-
-    if (!schema.meta?.category) {
-      missingMetadata.push(`${filePath}: missing category`);
-    }
-
-    if (!schema.meta?.documentationUrl) {
-      missingMetadata.push(`${filePath}: missing documentationUrl`);
-    }
-
-    if (!schema.title) {
-      missingMetadata.push(`${filePath}: missing title`);
-    }
-
-    if (!Object.hasOwn(schema, "description")) {
-      missingMetadata.push(`${filePath}: missing description`);
-    }
+    const data = await readJSON(filePath);
+
+    if (!data.name) missing.push(`${filePath}: missing name`);
+    if (!data.displayName) missing.push(`${filePath}: missing displayName`);
+    if (!data.meta?.category)
+      missing.push(`${filePath}: missing meta.category`);
+    if (!data.meta?.documentationUrl)
+      missing.push(`${filePath}: missing meta.documentationUrl`);
   }
 
-  t.is(
-    missingMetadata.length,
-    0,
-    `Missing required metadata:\n${missingMetadata.join("\n")}`,
-  );
+  t.is(missing.length, 0, `Missing required metadata:\n${missing.join("\n")}`);
 });