@adobe/spectrum-component-api-schemas 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @adobe/spectrum-component-api-schemas
 
+## 1.0.1
+
+### Patch Changes
+
+- [#523](https://github.com/adobe/spectrum-tokens/pull/523) [`9c5a2ac`](https://github.com/adobe/spectrum-tokens/commit/9c5a2ac5fccb29b6f106396b21d91aab949043d4) Thanks [@GarthDB](https://github.com/GarthDB)! - S2 components batch 1 (part 2)
+
+  ## Changes
+
+  ### Properties added
+  - component: select-box
+    - `body`
+
+  ### Properties updated
+  - component: text-area
+    - `errorMessage`
+      - removed: `"default": null`
+
 ## 1.0.0
 
 ### Major Changes
@@ -9,7 +26,6 @@
   ## Changes
 
   ### Properties Added
-
   - component: search-field
     - `helpText`
     - `placeholder`
@@ -29,7 +45,6 @@
     - `helpText`
 
   ### Properties removed
-
   - component: search-field
     - `isQuiet`
   - component: text-area
@@ -40,7 +55,6 @@
     - `isReadOnly`
 
   ### Properties updated
-
   - component: meter
     - `size`:
       - `enum`: `["small", "large"]` -> `["s", "m", "l", "xl"]`
@@ -54,7 +68,6 @@
       - `default`: `6` -> `8`
 
   ### New Component
-
   - select-box
 
 ## 0.0.0

package/ava.config.js

@@ -0,0 +1,9 @@
+export default {
+  files: ["test/**/*.test.js"],
+  environmentVariables: {
+    NODE_ENV: "test",
+  },
+  verbose: true,
+  failFast: false,
+  failWithoutAssertions: true,
+};

package/index.js

@@ -87,6 +87,9 @@ export const getSchemaBySlug = async (slug) => {
       return Object.hasOwn(schema, "slug") && schema.slug === slug;
     }),
   );
+  if (schema === undefined) {
+    throw new Error(`Schema not found for slug: ${slug}`);
+  }
   delete schema.slug;
   return schema;
 };

package/moon.yml

@@ -22,7 +22,8 @@ tasks:
     inputs:
       - "@globs(schemas)"
       - "@globs(tests)"
-      - index.js
+      - "index.js"
+      - "ava.config.js"
     platform: node
   test-watch:
     command:
@@ -30,3 +31,27 @@ tasks:
       - --watch
     local: true
     platform: node
+  test-coverage:
+    command:
+      - c8
+      - ava
+    local: true
+    platform: node
+  test-schema-validation:
+    command:
+      - ava
+      - test/schema-validation.test.js
+    local: true
+    platform: node
+  test-integration:
+    command:
+      - ava
+      - test/integration.test.js
+    local: true
+    platform: node
+  test-performance:
+    command:
+      - ava
+      - test/performance.test.js
+    local: true
+    platform: node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spectrum-component-api-schemas",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "type": "module",
   "main": "index.js",

package/schemas/components/select-box.json

@@ -17,6 +17,9 @@
       "enum": ["horizontal", "vertical"],
       "default": "horizontal"
     },
+    "body": {
+      "type": "string"
+    },
     "isSelected": {
       "type": "boolean",
       "default": false

package/schemas/components/text-area.json

@@ -34,9 +34,6 @@
       "enum": ["text", "icon"],
       "default": "icon"
     },
-    "helpText": {
-      "type": "string"
-    },
     "isRequired": {
       "type": "boolean",
       "default": false
@@ -65,13 +62,11 @@
       "type": "number",
       "description": "If undefined, height is dynamic and grows with input text."
     },
-    "description": {
-      "type": "string",
-      "default": null
+    "helpText": {
+      "type": "string"
     },
     "errorMessage": {
-      "type": "string",
-      "default": null
+      "type": "string"
     },
     "inputType": {
       "type": "string",

package/schemas/components/text-field.json

@@ -34,9 +34,6 @@
       "enum": ["text", "icon"],
       "default": "icon"
     },
-    "helpText": {
-      "type": "string"
-    },
     "isRequired": {
       "type": "boolean",
       "default": false
@@ -58,13 +55,11 @@
       "type": "boolean",
       "default": false
     },
-    "description": {
-      "type": "string",
-      "default": null
+    "helpText": {
+      "type": "string"
     },
     "errorMessage": {
-      "type": "string",
-      "default": null
+      "type": "string"
     },
     "state": {
       "type": "string",

package/test/README.md

@@ -0,0 +1,97 @@
+# Component Schemas Testing
+
+This directory contains comprehensive tests for the component-schemas package.
+
+## Test Structure
+
+### Core Tests
+
+- `index.test.js` - Tests for the main API functions
+- `componentSchemaValidator.test.js` - Legacy schema validation tests
+
+### New Test Suite
+
+- `schema-validation.test.js` - Comprehensive schema validation using test utilities
+- `integration.test.js` - Integration tests for full workflow
+- `performance.test.js` - Performance benchmarks
+- `utils/test-helpers.js` - Shared test utilities
+
+## Running Tests
+
+### Using Moon (Recommended)
+
+```bash
+# Run all tests
+moon run component-schemas:test
+
+# Run specific test suites
+moon run component-schemas:test-schema-validation
+moon run component-schemas:test-integration
+moon run component-schemas:test-performance
+
+# Run with coverage
+moon run component-schemas:test-coverage
+
+# Watch mode
+moon run component-schemas:test-watch
+```
+
+## Test Categories
+
+### 1. Schema Validation Tests
+
+- Validates all component schemas against the base component definition
+- Ensures all examples in schemas are valid
+- Checks that type schemas are valid JSON Schema
+- Verifies required metadata is present
+
+### 2. Integration Tests
+
+- Tests the full workflow of schema loading and processing
+- Validates API function behavior with real data
+- Ensures data consistency across functions
+- Tests error handling and edge cases
+
+### 3. Performance Tests
+
+- Benchmarks function execution times
+- Monitors memory usage
+- Tests concurrent operations
+- Ensures performance meets requirements
+
+## Test Utilities
+
+The `utils/test-helpers.js` file provides common utilities:
+
+- `readJSON()` - Read and parse JSON files
+- `getSchemaFiles()` - Get schema files using glob patterns
+- `createAjvInstance()` - Create configured Ajv instance
+- `validateSchema()` - Validate schemas with detailed error reporting
+- `validateExamples()` - Validate examples in schemas
+
+## Coverage
+
+Test coverage includes:
+
+- ✅ All exported functions
+- ✅ Schema validation logic
+- ✅ Error handling
+- ✅ Edge cases
+- ✅ Performance benchmarks
+
+## Adding New Tests
+
+1. Create test file in the appropriate category
+2. Use test utilities from `utils/test-helpers.js`
+3. Add descriptive test names and assertions
+4. Update this README if adding new test categories
+5. Consider adding performance tests for new functions
+
+## Best Practices
+
+- Use descriptive test names that explain the expected behavior
+- Group related tests together
+- Use test utilities for common operations
+- Include both positive and negative test cases
+- Add performance tests for new functions
+- Keep tests focused and independent

package/test/integration.test.js

@@ -0,0 +1,118 @@
+import test from "ava";
+import {
+  getAllSchemas,
+  getSchemaBySlug,
+  getAllSlugs,
+  getSlugFromDocumentationUrl,
+  schemaFileNames,
+} from "../index.js";
+import { getSchemaFiles } from "./utils/test-helpers.js";
+import { relative } from "path";
+
+test("getAllSchemas should return all schemas with slugs", async (t) => {
+  const schemas = await getAllSchemas();
+
+  t.true(Array.isArray(schemas));
+  t.true(schemas.length > 0);
+
+  // Check that schemas with documentation URLs have slugs
+  const schemasWithSlugs = schemas.filter((schema) => schema.slug);
+  t.true(schemasWithSlugs.length > 0);
+
+  // Verify slug format
+  for (const schema of schemasWithSlugs) {
+    t.true(typeof schema.slug === "string");
+    t.true(schema.slug.length > 0);
+  }
+});
+
+test("getAllSlugs should return all component slugs", async (t) => {
+  const slugs = await getAllSlugs();
+
+  t.true(Array.isArray(slugs));
+  t.true(slugs.length > 0);
+
+  // Verify all slugs are unique
+  const uniqueSlugs = new Set(slugs);
+  t.is(uniqueSlugs.size, slugs.length, "All slugs should be unique");
+
+  // Verify slug format (should be kebab-case)
+  for (const slug of slugs) {
+    t.true(/^[a-z0-9-]+$/.test(slug), `Slug "${slug}" should be kebab-case`);
+  }
+});
+
+test("getSchemaBySlug should return correct schema", async (t) => {
+  const slugs = await getAllSlugs();
+
+  if (slugs.length === 0) {
+    t.skip("No slugs available for testing");
+    return;
+  }
+
+  const testSlug = slugs[0];
+  const schema = await getSchemaBySlug(testSlug);
+
+  t.truthy(schema);
+  t.true(typeof schema === "object");
+  t.true(Object.hasOwn(schema.meta, "documentationUrl"));
+
+  // Verify the slug was extracted correctly
+  const expectedSlug = getSlugFromDocumentationUrl(
+    schema.meta.documentationUrl,
+  );
+  t.is(expectedSlug, testSlug);
+});
+
+test("getSlugFromDocumentationUrl should handle various URL formats", (t) => {
+  const testCases = [
+    { url: "https://spectrum.adobe.com/page/tooltip/", expected: "tooltip" },
+    { url: "https://spectrum.adobe.com/page/tooltip", expected: "tooltip" },
+    {
+      url: "https://spectrum.adobe.com/page/action-bar/",
+      expected: "action-bar",
+    },
+    { url: "https://spectrum.adobe.com/page/button/", expected: "button" },
+    { url: "https://spectrum.adobe.com/page/button", expected: "button" },
+  ];
+
+  for (const { url, expected } of testCases) {
+    const result = getSlugFromDocumentationUrl(url);
+    t.is(result, expected, `Failed for URL: ${url}`);
+  }
+});
+
+test("schemaFileNames should match actual files on disk", async (t) => {
+  const actualFiles = await getSchemaFiles();
+
+  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),
+      `File ${fileName} not found on disk`,
+    );
+  }
+});
+
+test("getAllSchemas should return same number as schemaFileNames", async (t) => {
+  const allSchemas = await getAllSchemas();
+
+  t.is(schemaFileNames.length, allSchemas.length);
+});
+
+test("getSchemaBySlug should throw for non-existent slug", async (t) => {
+  const nonExistentSlug = "non-existent-component";
+
+  await t.throwsAsync(
+    async () => {
+      const schema = await getSchemaBySlug(nonExistentSlug);
+      if (!schema) {
+        throw new Error("Schema not found");
+      }
+    },
+    { message: /Schema not found/ },
+  );
+});

package/test/performance.test.js

@@ -0,0 +1,121 @@
+import test from "ava";
+import { performance } from "perf_hooks";
+import {
+  getAllSchemas,
+  getSchemaBySlug,
+  getAllSlugs,
+  getSchemaFile,
+} from "../index.js";
+
+test("getAllSchemas should complete within reasonable time", async (t) => {
+  const start = performance.now();
+  const schemas = await getAllSchemas();
+  const end = performance.now();
+  const duration = end - start;
+
+  // Should complete within 1 second
+  t.true(
+    duration < 1000,
+    `getAllSchemas took ${duration.toFixed(2)}ms, expected < 1000ms`,
+  );
+  t.true(schemas.length > 0);
+});
+
+test("getAllSlugs should complete within reasonable time", async (t) => {
+  const start = performance.now();
+  const slugs = await getAllSlugs();
+  const end = performance.now();
+  const duration = end - start;
+
+  // Should complete within 500ms
+  t.true(
+    duration < 500,
+    `getAllSlugs took ${duration.toFixed(2)}ms, expected < 500ms`,
+  );
+  t.true(slugs.length > 0);
+});
+
+test("getSchemaBySlug should complete within reasonable time", async (t) => {
+  const slugs = await getAllSlugs();
+
+  if (slugs.length === 0) {
+    t.skip("No slugs available for testing");
+    return;
+  }
+
+  const testSlug = slugs[0];
+  const start = performance.now();
+  const schema = await getSchemaBySlug(testSlug);
+  const end = performance.now();
+  const duration = end - start;
+
+  // Should complete within 100ms
+  t.true(
+    duration < 100,
+    `getSchemaBySlug took ${duration.toFixed(2)}ms, expected < 100ms`,
+  );
+  t.truthy(schema);
+});
+
+test("getSchemaFile should complete within reasonable time", async (t) => {
+  const start = performance.now();
+  const schema = await getSchemaFile("component.json");
+  const end = performance.now();
+  const duration = end - start;
+
+  // Should complete within 50ms
+  t.true(
+    duration < 50,
+    `getSchemaFile took ${duration.toFixed(2)}ms, expected < 100ms`,
+  );
+  t.truthy(schema);
+});
+
+test("multiple concurrent getSchemaBySlug calls should complete efficiently", async (t) => {
+  const slugs = await getAllSlugs();
+
+  if (slugs.length < 3) {
+    t.skip("Not enough slugs for concurrent testing");
+    return;
+  }
+
+  const testSlugs = slugs.slice(0, 3);
+  const start = performance.now();
+
+  const results = await Promise.all(
+    testSlugs.map((slug) => getSchemaBySlug(slug)),
+  );
+
+  const end = performance.now();
+  const duration = end - start;
+
+  // Should complete within 200ms for 3 concurrent calls
+  t.true(
+    duration < 200,
+    `Concurrent getSchemaBySlug calls took ${duration.toFixed(2)}ms, expected < 200ms`,
+  );
+  t.is(results.length, 3);
+  t.true(results.every((schema) => schema !== null));
+});
+
+test("memory usage should be reasonable", async (t) => {
+  const initialMemory = process.memoryUsage().heapUsed;
+
+  // Perform multiple operations
+  const schemas = await getAllSchemas();
+  const slugs = await getAllSlugs();
+
+  if (slugs.length > 0) {
+    await getSchemaBySlug(slugs[0]);
+  }
+
+  const finalMemory = process.memoryUsage().heapUsed;
+  const memoryIncrease = finalMemory - initialMemory;
+
+  // Memory increase should be less than 10MB
+  const memoryIncreaseMB = memoryIncrease / 1024 / 1024;
+  t.true(
+    memoryIncreaseMB < 10,
+    `Memory usage increased by ${memoryIncreaseMB.toFixed(2)}MB, expected < 10MB`,
+  );
+});

package/test/schema-validation.test.js

@@ -0,0 +1,131 @@
+import test from "ava";
+import {
+  readJSON,
+  getSchemaFiles,
+  createAjvInstance,
+  validateSchema,
+  validateExamples,
+} from "./utils/test-helpers.js";
+
+// 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);
+
+  t.true(
+    result.valid,
+    `Component schema validation failed: ${JSON.stringify(result.errors, null, 2)}`,
+  );
+});
+
+test("all component schemas should validate against the definition", async (t) => {
+  const componentFiles = await getSchemaFiles("schemas/components/*.json");
+  const validationResults = [];
+
+  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,
+      });
+    }
+  }
+
+  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("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")}`,
+  );
+});
+
+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);
+
+    if (!result.valid) {
+      validationResults.push({
+        file: filePath,
+        errors: result.errors,
+      });
+    }
+  }
+
+  t.is(
+    validationResults.length,
+    0,
+    `Type schema validation failed for:\n${validationResults
+      .map((r) => `${r.file}:\n${JSON.stringify(r.errors, null, 2)}`)
+      .join("\n\n")}`,
+  );
+});
+
+test("component schemas should have required metadata", async (t) => {
+  const componentFiles = await getSchemaFiles("schemas/components/*.json");
+  const missingMetadata = [];
+
+  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`);
+    }
+  }
+
+  t.is(
+    missingMetadata.length,
+    0,
+    `Missing required metadata:\n${missingMetadata.join("\n")}`,
+  );
+});

package/test/utils/test-helpers.js

@@ -0,0 +1,89 @@
+import { readFile } from "fs/promises";
+import { glob } from "glob";
+import { resolve } from "path";
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+
+/**
+ * Read and parse a JSON file
+ * @param {string} filePath - Path to the JSON file
+ * @returns {Promise<Object>} Parsed JSON object
+ */
+export const readJSON = async (filePath) =>
+  JSON.parse(await readFile(filePath, "utf8"));
+
+/**
+ * Get all schema files matching a pattern
+ * @param {string} pattern - Glob pattern for schema files
+ * @returns {Promise<string[]>} Array of file paths
+ */
+export const getSchemaFiles = async (pattern = "schemas/**/*.json") =>
+  await glob(pattern);
+
+/**
+ * Create a configured Ajv instance with common schemas
+ * @returns {Promise<Ajv>} Configured Ajv instance
+ */
+export const createAjvInstance = async () => {
+  const ajv = new Ajv({
+    allErrors: true,
+    verbose: true,
+    strict: false,
+  });
+
+  addFormats(ajv);
+
+  // Add component schema as meta schema
+  const componentSchema = await readJSON("schemas/component.json");
+  ajv.addMetaSchema(componentSchema);
+
+  // Add type schemas
+  const typeSchemaFiles = await glob("schemas/types/*.json");
+  for (const schemaFile of typeSchemaFiles) {
+    const schema = await readJSON(schemaFile);
+    ajv.addSchema(schema);
+  }
+
+  return ajv;
+};
+
+/**
+ * Validate a schema against the component definition
+ * @param {Object} schema - Schema to validate
+ * @param {Ajv} ajv - Ajv instance
+ * @returns {Object} Validation result with errors if any
+ */
+export const validateSchema = (schema, ajv) => {
+  const valid = ajv.validateSchema(schema);
+  return {
+    valid,
+    errors: ajv.errors || [],
+  };
+};
+
+/**
+ * Validate examples in a schema
+ * @param {Object} schema - Schema containing examples
+ * @param {Ajv} ajv - Ajv instance
+ * @returns {Object} Validation result with errors if any
+ */
+export const validateExamples = (schema, ajv) => {
+  const validate = ajv.compile(schema);
+  const examples = schema.examples || [];
+  const errors = [];
+
+  for (const example of examples) {
+    const valid = validate(example);
+    if (!valid) {
+      errors.push({
+        example,
+        errors: validate.errors,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+};