Merge pull request #6 from c1rrus/docs-and-tests

Added API docs & tests

.changeset/calm-phones-talk.md

@@ -0,0 +1,5 @@
+---
+"dtcg-partial-parser": patch
+---
+
+Updated `@udt/parser-utils` dependency to v0.3.0

.changeset/dry-snails-peel.md

@@ -0,0 +1,5 @@
+---
+"dtcg-partial-parser": patch
+---
+
+Added `removeUndefinedProps()` function

.changeset/spotty-dingos-confess.md

@@ -0,0 +1,5 @@
+---
+"dtcg-partial-parser": patch
+---
+
+Added extensive TSDoc documentation blocks

.changeset/tricky-seahorses-sip.md

@@ -0,0 +1,5 @@
+---
+"dtcg-partial-parser": minor
+---
+
+BREAKING CHANGE: Renamed `applyInheritedProps()` to `combineWithInheritedProps()`

package.json

@@ -41,6 +41,6 @@
     "vitest": "^2.1.6"
   },
   "dependencies": {
-    "@udt/parser-utils": "^0.2.0"
+    "@udt/parser-utils": "^0.3.0"
   }
 }

src/_parseDesignTokenData.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { type DesignTokenDataHandlerFn } from "./parseDtcg.js";
+import { type DtcgFormatConfig } from "./formatConfigs/DtcgFormatConfig.js";
+import { preferOwnValue } from "./inheritableProps.js";
+import { type NormaliseDesignTokenPropsFn } from "./normalisedProps.js";
+import { parseDesignTokenData } from "./_parseDesignTokenData.js";
+
+const mockNormaliseDesignTokenData = vi.fn<NormaliseDesignTokenPropsFn>(
+  (originalProps) => {
+    const { _type, _value } = originalProps;
+    return {
+      $type: _type,
+      $value: _value,
+    };
+  }
+);
+
+const mockFormatConfig: DtcgFormatConfig = {
+  groupProps: [],
+  extraneousGroupProps: [],
+  designTokenProps: ["_value", "_type"],
+  inheritableProps: {
+    $type: preferOwnValue,
+  },
+
+  isDesignTokenData: (data) => data._value !== undefined,
+
+  normaliseDesignTokenProps: mockNormaliseDesignTokenData,
+};
+
+const mockHandleDesignToken = vi.fn<DesignTokenDataHandlerFn<string>>(
+  (path, combinedProps, ownProps, inheritedProps, extraneousProps) => {
+    return "huzzah!";
+  }
+);
+
+describe("parseDesignTokenData()", () => {
+  let testConfig: DtcgFormatConfig;
+
+  beforeEach(() => {
+    // Restore testConfig
+    testConfig = { ...mockFormatConfig };
+
+    // Reset mocks
+    mockHandleDesignToken.mockClear();
+    mockNormaliseDesignTokenData.mockClear();
+  });
+
+  it("extracts designTokenProps specified in the formatConfig passes them to normaliseDesignTokenData, if set", () => {
+    parseDesignTokenData(
+      { _value: 123, _extraneous: 321 },
+      ["foo"],
+      undefined,
+      testConfig,
+      mockHandleDesignToken
+    );
+    expect(mockNormaliseDesignTokenData).toHaveBeenCalledWith({
+      _value: 123,
+    });
+  });
+
+  it("passes normalised designTokenProps to the designTokenDataHandler", () => {
+    parseDesignTokenData(
+      { _value: 123 },
+      ["foo"],
+      undefined,
+      testConfig,
+      mockHandleDesignToken
+    );
+    expect(mockHandleDesignToken).toHaveBeenCalledWith(
+      // path:
+      ["foo"],
+      // combined props:
+      {
+        $value: 123,
+      },
+      // own props:
+      {
+        $value: 123,
+      },
+      // inherited props:
+      {},
+      // extraneous props:
+      {}
+    );
+  });
+
+  it("passes combined inheritableProps to the designTokenDataHandler", () => {
+    parseDesignTokenData(
+      { _value: 123 },
+      ["foo"],
+      { $type: "color" },
+      testConfig,
+      mockHandleDesignToken
+    );
+    expect(mockHandleDesignToken).toHaveBeenCalledWith(
+      // path:
+      ["foo"],
+      // combined props:
+      {
+        $value: 123,
+        $type: "color",
+      },
+      // own props:
+      {
+        $value: 123,
+      },
+      // inherited props:
+      {
+        $type: "color",
+      },
+      // extraneous props:
+      {}
+    );
+  });
+
+  it("passes extraneous props to the designTokenDataHandler unchanged", () => {
+    parseDesignTokenData(
+      { _value: 123, _extraneous: 123 },
+      ["foo"],
+      undefined,
+      testConfig,
+      mockHandleDesignToken
+    );
+    expect(mockHandleDesignToken).toHaveBeenCalledWith(
+      // path:
+      ["foo"],
+      // combined props:
+      { $value: 123 },
+      // own props:
+      { $value: 123 },
+      // inherited props:
+      {},
+      // extraneous props:
+      {
+        _extraneous: 123,
+      }
+    );
+  });
+
+  it("passes extracted designTokenProps as is to the designTokenDataHandler, if no normaliseDesignTokenProps() function is provided", () => {
+    delete testConfig.normaliseDesignTokenProps;
+
+    parseDesignTokenData(
+      { _value: 123 },
+      ["foo"],
+      undefined,
+      testConfig,
+      mockHandleDesignToken
+    );
+    expect(mockHandleDesignToken).toHaveBeenCalledWith(
+      // path:
+      ["foo"],
+      // combined props:
+      {
+        _value: 123,
+      },
+      // own props:
+      {
+        _value: 123,
+      },
+      // inherited props:
+      {},
+      // extraneous props:
+      {}
+    );
+  });
+
+  it("returns and the return value of the handleDesignToken()", () => {
+    expect(
+      parseDesignTokenData(
+        { _value: 123 },
+        ["foo"],
+        undefined,
+        testConfig,
+        mockHandleDesignToken
+      )
+    ).toBe("huzzah!");
+  });
+});

src/_parseDesignTokenData.ts

@@ -0,0 +1,57 @@
+import { extractProperties, type PlainObject } from "@udt/parser-utils";
+import { combineWithInheritedProps } from "./inheritableProps.js";
+import {
+  type NormalisedDtcgDesignTokenProps,
+  type NormalisedDtcgGroupProps,
+} from "./normalisedProps.js";
+import { type DtcgFormatConfig } from "./formatConfigs/DtcgFormatConfig.js";
+import { removeUndefinedProps } from "./removeUndefinedProps.js";
+import { type DesignTokenDataHandlerFn } from "./parseDtcg.js";
+
+/**
+ * Normalises the input design token data, combines it with inherited
+ * props and passes the results into a user-defined design token data
+ * hander function.
+ *
+ * @private
+ *
+ * @param data  The raw input data for a single design token.
+ * @param path  The design token's path.
+ * @param inheritedProps  Inheritable props passed down from the
+ *              parent group.
+ * @param formatConfig  The format config being used by the parser.
+ * @param handleDesignToken The user-defined design token data
+ *              handler function.
+ * @returns The output of the design token data handler function.
+ */
+export function parseDesignTokenData<ParsedDesignToken>(
+  data: PlainObject,
+  path: string[],
+  inheritedProps: NormalisedDtcgGroupProps | undefined,
+  formatConfig: DtcgFormatConfig,
+  handleDesignToken: DesignTokenDataHandlerFn<ParsedDesignToken>
+): ParsedDesignToken {
+  const { extracted: originalOwnProps, rest: extraneousProps } =
+    extractProperties(data, formatConfig.designTokenProps);
+
+  const normalisedOwnProps = formatConfig.normaliseDesignTokenProps
+    ? (removeUndefinedProps(
+        formatConfig.normaliseDesignTokenProps(originalOwnProps)
+      ) as NormalisedDtcgDesignTokenProps)
+    : (originalOwnProps as unknown as NormalisedDtcgDesignTokenProps);
+
+  return handleDesignToken(
+    path,
+    {
+      ...normalisedOwnProps,
+      ...combineWithInheritedProps(
+        normalisedOwnProps,
+        inheritedProps ?? {},
+        formatConfig.inheritableProps
+      ),
+    },
+    normalisedOwnProps,
+    inheritedProps ?? {},
+    extraneousProps
+  );
+}