@exdst-sitecore-content-sdk/astro 0.0.1

package/src/components/Placeholder/models.ts

@@ -0,0 +1,82 @@
+import { Page } from '@sitecore-content-sdk/core/client';
+import { AstroContentSdkComponent } from '../../sharedTypes/component-props';
+import { ComponentRendering, Field, Item, RouteData } from '@sitecore-content-sdk/core/layout';
+
+/** Provided for the component which represents rendering data */
+export type ComponentProps = {
+  [key: string]: unknown;
+  rendering: ComponentRendering;
+};
+
+export interface PlaceholderProps {
+  [key: string]: unknown;
+  /** Name of the placeholder to render. */
+  name: string;
+  /** Rendering data to be used when rendering the placeholder. */
+  rendering: ComponentRendering | RouteData;
+  /**
+   * An object of field names/values that are aggregated and propagated through the component tree created by a placeholder.
+   * Any component or placeholder rendered by a placeholder will have access to this data via `props.fields`.
+   */
+  fields?: {
+    [name: string]: Field | Item | Item[];
+  };
+  /**
+   * An object of rendering parameter names/values that are aggregated and propagated through the component tree created by a placeholder.
+   * Any component or placeholder rendered by a placeholder will have access to this data via `props.params`.
+   */
+  params?: {
+    [name: string]: string;
+  };
+  /**
+   * Modify final props of component (before render) provided by rendering data.
+   * Can be used in case when you need to insert additional data into the component.
+   * @param {ComponentProps} componentProps component props to be modified
+   * @returns {ComponentProps} modified or initial props
+   */
+  modifyComponentProps?: (componentProps: ComponentProps) => ComponentProps;
+  /**
+   * A component that is rendered in place of any components that are in this placeholder,
+   * but do not have a definition in the componentMap (i.e. don't have an implementation)
+   */
+  missingComponentComponent?: AstroContentSdkComponent;
+
+  /**
+   * A component that is rendered in place of any components that are hidden
+   */
+  hiddenRenderingComponent?: AstroContentSdkComponent;
+
+  /**
+   * A component that is rendered in place of the placeholder when an error occurs rendering
+   * the placeholder
+   */
+  errorComponent?: AstroContentSdkComponent;
+  /**
+   * Page data.
+   * This data is passed by the SitecoreProvider.
+   */
+  page: Page;
+
+  /**
+   * Render HTML or an Astro component when the placeholder contains no content components.
+   */
+  renderEmpty?: string | AstroContentSdkComponent;
+
+  /**
+   * Render HTML or an Astro component wrapped around the placeholder and components.
+   * For HTML wrapper use ${component} string placeholder to set where the placeholder and components should be rendered.
+   */
+  render?: string | AstroContentSdkComponent;
+
+  /**
+   * Render HTML or an Astro component wrapped around each non-system component added to the placeholder.
+   * For HTML wrapper use ${component} string placeholder to set where the component should be rendered.
+   * Mutually exclusive with `render`.
+   */
+  renderEach?: string | AstroContentSdkComponent;
+}
+
+export interface ComponentForRendering {
+  component: AstroContentSdkComponent;
+  isEmpty: boolean;
+}

package/src/components/Placeholder/placeholder-utils.test.ts

@@ -0,0 +1,162 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable no-unused-expressions */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { expect } from 'chai';
+import { createSandbox } from 'sinon';
+import { getPlaceholderRenderings, getSXAParams } from './placeholder-utils';
+import { ComponentRendering } from '@sitecore-content-sdk/core/layout';
+
+describe('placeholder-utils', () => {
+  const sandbox = createSandbox();
+  let consoleWarnStub: any;
+
+  beforeEach(() => {
+    consoleWarnStub = sandbox.stub(console, 'warn');
+  });
+
+  afterEach(() => {
+    sandbox.restore();
+  });
+
+  describe('getPlaceholderRenderings', () => {
+    it('should return null if rendering does not have placeholders', () => {
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+      };
+
+      const result = getPlaceholderRenderings(rendering, 'test-placeholder', false);
+
+      expect(result).to.deep.equal([]);
+      expect(consoleWarnStub.calledOnce).to.be.true;
+      expect(consoleWarnStub.firstCall.args[0]).to.include('test-placeholder');
+    });
+
+    it('should return renderings from placeholder by name', () => {
+      const expectedRenderings = [
+        {
+          componentName: 'Component1',
+          uid: 'comp1-uid',
+        },
+        {
+          componentName: 'Component2',
+          uid: 'comp2-uid',
+        },
+      ];
+
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+        placeholders: {
+          'test-placeholder': expectedRenderings,
+          'other-placeholder': [{ componentName: 'OtherComponent', uid: 'other-uid' }],
+        },
+      };
+
+      const result = getPlaceholderRenderings(rendering, 'test-placeholder', false);
+
+      expect(result).to.deep.equal(expectedRenderings);
+      expect(consoleWarnStub.called).to.be.false;
+    });
+
+    it('should parse dynamic SXA placeholder names correctly', () => {
+      const expectedRenderings = [
+        {
+          componentName: 'DynamicComponent',
+          uid: 'dynamic-uid',
+        },
+      ];
+
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+        placeholders: {
+          'container-{*}': expectedRenderings,
+          'other-placeholder': [{ componentName: 'OtherComponent', uid: 'other-uid' }],
+        },
+      };
+
+      // Test non-editing mode - should replace dynamic placeholder
+      const result = getPlaceholderRenderings(rendering, 'container-1', false);
+      expect(result).to.deep.equal(expectedRenderings);
+      expect(rendering.placeholders['container-1']).to.deep.equal(expectedRenderings);
+      expect(rendering.placeholders['container-{*}']).to.be.undefined;
+
+      // Reset rendering for editing mode test
+      rendering.placeholders = {
+        'container-{*}': expectedRenderings,
+        'other-placeholder': [{ componentName: 'OtherComponent', uid: 'other-uid' }],
+      };
+
+      // Test editing mode - should keep original placeholder name
+      const editResult = getPlaceholderRenderings(rendering, 'container-1', true);
+      expect(editResult).to.deep.equal(expectedRenderings);
+      expect(rendering.placeholders['container-{*}']).to.deep.equal(expectedRenderings);
+    });
+  });
+
+  describe('getSXAParams', () => {
+    it('should return GridParameters and Styles when present', () => {
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+        params: {
+          GridParameters: 'col-lg-6',
+          Styles: 'custom-class',
+          OtherParam: 'other-value',
+        },
+      };
+
+      const result = getSXAParams(rendering);
+
+      expect(result).to.deep.equal({
+        styles: 'col-lg-6 custom-class',
+      });
+    });
+
+    it('should return only GridParameters when Styles not present', () => {
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+        params: {
+          GridParameters: 'col-lg-8',
+          OtherParam: 'other-value',
+        },
+      };
+
+      const result = getSXAParams(rendering);
+
+      expect(result).to.deep.equal({
+        styles: 'col-lg-8 ',
+      });
+    });
+
+    it('should return only Styles when GridParameters not present', () => {
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+        params: {
+          Styles: 'custom-styles',
+          OtherParam: 'other-value',
+        },
+      };
+
+      const result = getSXAParams(rendering);
+
+      expect(result).to.deep.equal({
+        styles: ' custom-styles',
+      });
+    });
+
+    it('should return empty object when no params', () => {
+      const rendering: ComponentRendering = {
+        componentName: 'TestComponent',
+        uid: 'test-uid',
+      };
+
+      const result = getSXAParams(rendering);
+
+      expect(result).to.deep.equal({});
+    });
+  });
+});

package/src/components/Placeholder/placeholder-utils.ts

@@ -0,0 +1,80 @@
+import {
+  ComponentRendering,
+  RouteData,
+  isDynamicPlaceholder,
+  getDynamicPlaceholderPattern,
+} from '@sitecore-content-sdk/core/layout';
+
+/**
+ * Get the renderings for the specified placeholder from the rendering data.
+ * @param {ComponentRendering | RouteData } rendering rendering data
+ * @param {string} name placeholder name
+ * @param {boolean} isEditing whether components should be rendered in editing mode
+ * @returns {ComponentRendering[]} array of component renderings
+ */
+export const getPlaceholderRenderings = (
+  rendering: ComponentRendering | RouteData,
+  name: string,
+  isEditing: boolean
+) => {
+  let result;
+  let phName = name.slice();
+
+  /**
+   * Process (SXA) dynamic placeholders
+   * Find and replace the matching dynamic placeholder e.g 'nameOfContainer-{*}' with the requested e.g. 'nameOfContainer-1'.
+   * For Metadata EditMode, we need to keep the raw placeholder name in place.
+   */
+  if (rendering?.placeholders) {
+    Object.keys(rendering.placeholders).forEach((placeholder) => {
+      const patternPlaceholder = isDynamicPlaceholder(placeholder)
+        ? getDynamicPlaceholderPattern(placeholder)
+        : null;
+
+      if (patternPlaceholder && patternPlaceholder.test(phName)) {
+        if (isEditing) {
+          phName = placeholder;
+        } else {
+          // @ts-ignore
+          rendering.placeholders[phName] = rendering.placeholders[placeholder];
+          // @ts-ignore
+          delete rendering.placeholders[placeholder];
+        }
+      }
+    });
+  }
+
+  if (rendering && rendering.placeholders && Object.keys(rendering.placeholders).length > 0) {
+    result = rendering.placeholders[phName];
+  } else {
+    result = null;
+  }
+
+  if (!result) {
+    console.warn(
+      `Placeholder '${phName}' was not found in the current rendering data`,
+      JSON.stringify(rendering, null, 2)
+    );
+
+    return [];
+  }
+
+  return result;
+};
+
+/**
+ * Get SXA specific params from Sitecore rendering params
+ * @param {ComponentRendering} rendering rendering object
+ * @returns {object} converted SXA params
+ */
+export const getSXAParams = (rendering: ComponentRendering) => {
+  if (!rendering.params) return {};
+
+  const { GridParameters, Styles } = rendering.params;
+
+  return (
+    (GridParameters || Styles) && {
+      styles: `${GridParameters || ''} ${Styles || ''}`,
+    }
+  );
+};

package/src/components/RenderWrapper.astro

@@ -0,0 +1,31 @@
+---
+import { AstroContentSdkComponent } from '../sharedTypes/component-props';
+
+interface RenderWrapperProps {
+  wrapper?: AstroContentSdkComponent | string;
+}
+
+const { wrapper } = Astro.props as RenderWrapperProps;
+
+let html;
+let WrapperComponent = wrapper as AstroContentSdkComponent;
+
+const isHtmlWrapper = wrapper && typeof wrapper === 'string';
+
+if (isHtmlWrapper) {
+  const componentHtml = await Astro.slots.render('default');
+  html = wrapper.replace('${component}', componentHtml);
+}
+---
+
+<>
+  {!wrapper && <slot />}
+  {
+    wrapper && !isHtmlWrapper && (
+      <WrapperComponent>
+        <slot />
+      </WrapperComponent>
+    )
+  }
+  {isHtmlWrapper && <Fragment set:html={html} />}
+</>

package/src/components/RichText.astro

@@ -0,0 +1,59 @@
+---
+import { EditableFieldProps } from './sharedTypes';
+import {
+  FieldMetadata,
+  isFieldValueEmpty,
+} from '@sitecore-content-sdk/core/layout';
+import WithEmptyFieldEditingComponent from '../enhancers/WithEmptyFieldEditingComponent.astro';
+import WithFieldMetadata from '../enhancers/WithFieldMetadata.astro';
+import DefaultEmptyFieldEditingComponentText from './DefaultEmptyFieldEditingComponentText.astro';
+
+export interface RichTextField extends FieldMetadata {
+  value?: string;
+}
+
+export interface RichTextProps extends EditableFieldProps {
+  [htmlAttributes: string]: unknown;
+  /** The text field data. */
+  field: RichTextField;
+  /**
+   * The HTML element that will wrap the contents of the field.
+   */
+  tag?: string;
+}
+
+const {
+  field,
+  tag = 'div',
+  editable = true,
+  emptyFieldEditingComponent,
+} = Astro.props as RichTextProps;
+
+const isEmptyField = isFieldValueEmpty(field);
+
+const Tag = tag;
+
+const attrs = (function () {
+  const { field, ...attrs } = Astro.props;
+  const { tag, ...finalAttrs } = attrs;
+  return finalAttrs;
+})();
+---
+
+{
+  (
+    <WithFieldMetadata field={field} editable={editable}>
+      <WithEmptyFieldEditingComponent
+        field={field}
+        editable={editable}
+        defaultEmptyFieldEditingComponent={
+          DefaultEmptyFieldEditingComponentText
+        }
+        emptyFieldEditingComponent={emptyFieldEditingComponent}
+        {...attrs}
+      >
+        {!isEmptyField && <Tag {...attrs} set:html={field.value} />}
+      </WithEmptyFieldEditingComponent>
+    </WithFieldMetadata>
+  )
+}

package/src/components/Text.astro

@@ -0,0 +1,97 @@
+---
+import {
+  FieldMetadata,
+  isFieldValueEmpty,
+} from '@sitecore-content-sdk/core/layout';
+import { EditableFieldProps } from './sharedTypes';
+import WithFieldMetadata from '../enhancers/WithFieldMetadata.astro';
+import WithEmptyFieldEditingComponent from '../enhancers/WithEmptyFieldEditingComponent.astro';
+import DefaultEmptyFieldEditingComponentText from './DefaultEmptyFieldEditingComponentText.astro';
+
+export interface TextField extends FieldMetadata {
+  value?: string | number;
+}
+
+export interface TextProps extends EditableFieldProps {
+  [htmlAttributes: string]: unknown;
+  /** The text field data. */
+  field: TextField;
+  /**
+   * The HTML element that will wrap the contents of the field.
+   */
+  tag?: string;
+  /**
+   * If false, HTML-encoding of the field value is disabled and the value is rendered as-is.
+   */
+  encode?: boolean;
+}
+
+const {
+  field,
+  tag,
+  editable = true,
+  encode = true,
+  emptyFieldEditingComponent,
+  ...otherProps
+} = Astro.props as TextProps;
+
+const isEmptyField = isFieldValueEmpty(field);
+
+// can't use editable value if we want to output unencoded
+const isEditable = !encode ? false : editable;
+
+let output: string | number | string[] = '';
+if (!isEmptyField) {
+  output = field.value === undefined ? '' : field.value;
+
+  // when string value isn't formatted, we should format line breaks
+  const splitted = String(output).split('\n');
+
+  if (splitted.length) {
+    const formatted: string[] = [];
+
+    splitted.forEach((str, i) => {
+      const isLast = i === splitted.length - 1;
+
+      formatted.push(str);
+
+      if (!isLast) {
+        formatted.push('<br />');
+      }
+    });
+
+    output = formatted;
+  }
+}
+
+const Tag = tag || 'span';
+
+const attrs: {
+  [htmlAttributes: string]: unknown;
+} = {
+  ...otherProps,
+};
+---
+
+{
+  (
+    <WithFieldMetadata field={field} editable={isEditable}>
+      <WithEmptyFieldEditingComponent
+        field={field}
+        editable={isEditable}
+        defaultEmptyFieldEditingComponent={
+          DefaultEmptyFieldEditingComponentText
+        }
+        emptyFieldEditingComponent={emptyFieldEditingComponent}
+        {...attrs}
+      >
+        {!isEmptyField && (
+          <>
+            {(tag || !encode) && <Tag {...attrs} set:html={output} />}
+            {(!tag || encode) && <Fragment {...attrs} set:html={output} />}
+          </>
+        )}
+      </WithEmptyFieldEditingComponent>
+    </WithFieldMetadata>
+  )
+}

package/src/components/sharedTypes/index.ts

@@ -0,0 +1 @@
+export * from './props';

package/src/components/sharedTypes/props.ts

@@ -0,0 +1,17 @@
+import { AstroContentSdkComponent } from "../../sharedTypes/component-props";
+
+/**
+ * Shared editing field props
+ */
+export interface EditableFieldProps {
+  /**
+   * Can be used to explicitly disable inline editing.
+   * @default true
+   */
+  editable?: boolean;
+  /**
+   * Custom element to render in Pages in edit mode if field value is empty
+   */
+  emptyFieldEditingComponent?: AstroContentSdkComponent;
+}
+