@redocly/theme 0.47.0 → 0.48.0

package/src/markdoc/tags/code-walkthrough.ts

@@ -0,0 +1,315 @@
+import markdoc, { Node, RenderableTreeNode, ValidationError } from '@markdoc/markdoc';
+
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+import type {
+  CodeWalkthroughConditions,
+  CodeWalkthroughFileset,
+  CodeWalkthroughFilter,
+  CodeWalkthroughStepAttr,
+  CodeWalkthroughFilterItem,
+  TogglesMarkdocAttr,
+  InputsMarkdocAttr,
+} from '@redocly/config';
+
+import { CodeWalkthroughFilesets } from '@redocly/theme/markdoc/attributes/code-walkthrough-filesets';
+import { CodeWalkthroughFilters } from '@redocly/theme/markdoc/attributes/code-walkthrough-filters';
+import { isObject } from '@redocly/theme/core/utils';
+
+export const codeWalkthrough: MarkdocSchemaWrapper = {
+  tagName: 'code-walkthrough',
+  schema: {
+    attributes: {
+      filesets: {
+        type: CodeWalkthroughFilesets,
+        render: false,
+        required: true,
+      },
+      resolvedFilesets: {
+        type: Array,
+        render: false,
+        required: false,
+      },
+      filters: {
+        type: CodeWalkthroughFilters,
+        render: false,
+        required: false,
+      },
+      inputs: {
+        type: Object,
+        render: false,
+        required: false,
+      },
+      toggles: {
+        type: Array,
+        render: false,
+        required: false,
+      },
+    },
+    slots: {
+      preview: { required: false, render: true },
+    },
+    transform: (node, config) => {
+      const attributes = node.transformAttributes(config);
+      const children = node.transformChildren(config);
+      const steps = collectStepsFromChildren(children);
+      const inputs = collectInputsFromChildren(children);
+      const toggles = collectTogglesFromChildren(node.children);
+
+      return new markdoc.Tag(
+        'CodeWalkthrough',
+        {
+          ...attributes,
+          filters: node.attributes.filters || {},
+          filesets: node.attributes.resolvedFilesets || [],
+          steps: steps.map((step) => {
+            return {
+              ...((step as any)?.attributes || {}),
+            } as CodeWalkthroughStepAttr;
+          }),
+          inputs,
+          toggles,
+        },
+        children,
+      );
+    },
+    validate(node) {
+      const errors: ValidationError[] = [];
+      // code-walk-todo: validate when/unless for steps, toggles, inputs, and chunks
+
+      const toggleIds = Object.keys(collectTogglesFromChildren(node.children));
+
+      if (isObject(node.attributes.filters)) {
+        Object.entries(node.attributes.filters).forEach(([id, filter]) => {
+          if (!isObject(filter)) {
+            errors.push({
+              id: 'filter-elements-type-invalid',
+              level: 'error' as const,
+              message: 'The "filters" attribute elements must be of type object.',
+            });
+          } else if (!(filter as CodeWalkthroughFilter).items?.length) {
+            errors.push({
+              id: 'filter-required',
+              level: 'error' as const,
+              message: `The "filters" items attribute for the filter ${id} should have at least one item.`,
+            });
+          }
+        });
+      } else if (node.attributes.filters) {
+        errors.push({
+          id: 'filter-type-invalid',
+          level: 'error' as const,
+          message: 'The "filters" attribute must be of type object.',
+        });
+      }
+
+      if (Array.isArray(node.attributes.filesets)) {
+        node.attributes.filesets.forEach((fileset: CodeWalkthroughFileset, idx) => {
+          if (fileset.when) {
+            const whenErrors = validateCodeWalkthroughCondition(
+              fileset.when,
+              node.attributes.filters || {},
+              toggleIds,
+            );
+
+            if (whenErrors.length > 0) {
+              errors.push({
+                id: 'fileset-when-invalid',
+                level: 'error' as const,
+                message: `Invalid condition at 'filesets.${idx}.when':\n${whenErrors.join('\n')}`,
+              });
+            }
+          }
+
+          if (fileset.unless) {
+            const unlessErrors = validateCodeWalkthroughCondition(
+              fileset.unless,
+              node.attributes.filters || {},
+              toggleIds,
+            );
+
+            if (unlessErrors.length > 0) {
+              errors.push({
+                id: 'fileset-when-invalid',
+                level: 'error' as const,
+                message: `Invalid condition at 'filesets.${idx}.unless':\n${unlessErrors.join('\n')}`,
+              });
+            }
+          }
+        });
+
+        if (!node.attributes.filesets.length) {
+          errors.push({
+            id: 'filesets-required',
+            level: 'error' as const,
+            message: 'The "filesets" attribute should have at least one item.',
+          });
+        }
+      } else {
+        errors.push({
+          id: 'filesets-type-invalid',
+          level: 'error' as const,
+          message: 'The "filesets" attribute must be of type array.',
+        });
+      }
+
+      node.children.forEach((child) => {
+        if (child.tag === 'step') {
+          const isValidFilter = validateStepFilters(
+            node.attributes.filters || {},
+            child.attributes,
+          );
+
+          if (!isValidFilter) {
+            errors.push({
+              id: 'step-filter-invalid',
+              level: 'error' as const,
+              message:
+                'The "step" tag contains invalid filter attributes. Ensure "when" and "unless" conditions reference valid filters.',
+            });
+          }
+        }
+      });
+
+      return errors;
+    },
+    render: 'CodeWalkthrough',
+  },
+};
+
+export function collectStepsFromChildren(
+  children: RenderableTreeNode[],
+  idx = 0,
+): RenderableTreeNode[] {
+  return children.flatMap((child) => {
+    if (child instanceof markdoc.Tag && child.name === 'CodeStep') {
+      child.attributes.stepKey = idx++;
+      return [child];
+    }
+
+    if (child instanceof markdoc.Tag) {
+      return collectStepsFromChildren(child.children, idx);
+    }
+
+    return [];
+  });
+}
+
+export function collectTogglesFromChildren(
+  children: Node[],
+  toggles: TogglesMarkdocAttr = {},
+): TogglesMarkdocAttr {
+  for (const child of children) {
+    if (child.tag === 'toggle') {
+      const id = child.attributes.id as string;
+      if (id) {
+        toggles[id] = {
+          when: child.attributes.when,
+          unless: child.attributes.unless,
+        } as TogglesMarkdocAttr;
+      }
+    }
+
+    collectTogglesFromChildren(child.children, toggles);
+  }
+
+  return toggles;
+}
+
+export function collectInputsFromChildren(
+  children: RenderableTreeNode[],
+  inputs: InputsMarkdocAttr = {},
+): InputsMarkdocAttr {
+  for (const child of children) {
+    if (child instanceof markdoc.Tag && child.name === 'Input') {
+      const id = child.attributes.id as string;
+      if (id) {
+        inputs[id] = {
+          value: child.attributes.value || '',
+          when: child.attributes.when,
+          unless: child.attributes.unless,
+        };
+      }
+      continue;
+    }
+
+    if (child instanceof markdoc.Tag) {
+      collectInputsFromChildren(child.children, inputs);
+    }
+  }
+
+  return inputs;
+}
+
+export function validateCodeWalkthroughCondition(
+  conditions: CodeWalkthroughConditions,
+  filters: Record<string, CodeWalkthroughFilter>,
+  allToggles: string[],
+) {
+  const errors: string[] = [];
+
+  for (const [filterId, filterValue] of Object.entries(conditions)) {
+    if (!filters[filterId] && !allToggles.includes(filterId)) {
+      errors.push('Unknown filter: ' + filterId);
+    } else if (filterValue) {
+      const invalidFilterItems = getInvalidFilterValues(
+        filterValue,
+        filters[filterId]?.items || [],
+      );
+      if (invalidFilterItems.length > 0) {
+        errors.push(
+          `Filter item(s) are not defined on the filter '${filterId}': ${invalidFilterItems.join(', ')}`,
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+function getInvalidFilterValues(
+  filterConditionValue: string | boolean | string[],
+  definedValues: CodeWalkthroughFilterItem[],
+) {
+  const togglesArray = Array.isArray(filterConditionValue)
+    ? filterConditionValue
+    : [filterConditionValue];
+  const items = definedValues.map((item) => item.value);
+
+  return togglesArray.filter((toggle) => typeof toggle !== 'boolean' && !items.includes(toggle));
+}
+
+function validateStepFilters(
+  filters: Record<string, CodeWalkthroughFilter>,
+  obj: Record<string, string>,
+) {
+  function isValidFilter(filterKey: string, filterValue: string | string[]) {
+    if (!Object.prototype.hasOwnProperty.call(filters, filterKey)) {
+      return true;
+    }
+
+    const validItems = filters[filterKey].items.map((item) => item.value);
+
+    if (Array.isArray(filterValue)) {
+      return filterValue.every((value) => validItems.includes(value));
+    } else {
+      return validItems.includes(filterValue);
+    }
+  }
+
+  if (obj.when) {
+    for (const [key, value] of Object.entries(obj.when)) {
+      if (!isValidFilter(key, value)) {
+        return false;
+      }
+    }
+  }
+
+  if (obj.unless) {
+    for (const [key, value] of Object.entries(obj.unless)) {
+      if (!isValidFilter(key, value)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}

package/src/markdoc/tags/input.ts

@@ -0,0 +1,35 @@
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+export const input: MarkdocSchemaWrapper = {
+  tagName: 'input',
+  schema: {
+    attributes: {
+      id: {
+        type: String,
+        required: true,
+      },
+      label: {
+        type: String,
+        required: false,
+      },
+      placeholder: {
+        type: String,
+        required: false,
+      },
+      value: {
+        type: String,
+        required: false,
+      },
+      unless: {
+        type: Object,
+        required: false,
+      },
+      when: {
+        type: Object,
+        required: false,
+      },
+    },
+    selfClosing: true,
+    render: 'Input',
+  },
+};

package/src/plugin.js

@@ -1,3 +1,3 @@
-export default function plugin() {
+module.exports = function plugin() {
   return { id: 'default-theme' };
-}
+};