Merge pull request #1173 from vivid-planet/merge-main-into-next

Merge main into next

.changeset/calm-rules-rescue.md

@@ -0,0 +1,5 @@
+---
+"@comet/cms-api": patch
+---
+
+get file stats from uploaded file in filestorage

.github/workflows/build-docs.yml

@@ -0,0 +1,40 @@
+name: Build Docs
+
+on:
+    pull_request:
+        paths:
+            - docs/**
+        branches:
+            - main
+            - next
+    push:
+        paths:
+            - docs/**
+        branches:
+            - main
+            - next
+
+jobs:
+    build:
+        name: Build
+        runs-on: ubuntu-latest
+        steps:
+            - run: echo "${{ github.actor }}"
+
+            - uses: actions/checkout@v3
+
+            - uses: pnpm/action-setup@v2
+              with:
+                  version: 8
+
+            - name: Use Node.js 18.x
+              uses: actions/setup-node@v3
+              with:
+                  node-version: 18
+                  registry-url: "https://registry.npmjs.org"
+                  cache: "pnpm" # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-dependencies
+
+            - run: pnpm install --frozen-lockfile
+
+            - name: Build docs
+              run: pnpm run build:docs

README.md

@@ -74,6 +74,14 @@ pnpm run storybook
 
 Storybook will be available at [http://localhost:26638/](http://localhost:26638/)
 
+#### Start Docs
+
+```bash
+pnpm run docs
+```
+
+The docs will be available at [http://localhost:3000/](http://localhost:3000/)
+
 ### Stop Processes
 
 ```bash

docs/.eslintrc.json

@@ -0,0 +1,4 @@
+{
+    "extends": "@comet/eslint-config/react",
+    "ignorePatterns": [".docusaurus", "build"]
+}

docs/.gitignore

@@ -0,0 +1,6 @@
+# Production
+build
+
+# Generated files
+.docusaurus
+.cache-loader

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
+};

docs/docs/asset-management/index.md

@@ -0,0 +1,6 @@
+---
+title: Asset Management (DAM)
+sidebar_position: 9
+---
+
+COMET DXP has a built-in digital asset management interface (DAM). The DAM's purpose is the management of all files used on a website. That comprises media files (images, videos, audios), PDFs, zip-Files, and documents.

docs/docs/blocks/block-best-practices.mdx

@@ -0,0 +1,103 @@
+---
+title: Best practices
+sidebar_position: 2
+---
+
+This page covers best practices on how to design pleasant-to-use blocks.
+
+## Allow saving a block with its default values
+
+Adding a new block to a document should not prevent a document's saving – even if the block is incomplete.
+Consider the following example:
+
+```ts title="headline.block.ts"
+class HeadlineBlockInput extends BlockData {
+    @BlockField()
+    @IsString()
+    @IsNotEmpty()
+    eyebrow: string;
+
+    @ChildBlockInput(RichTextBlock)
+    @ValidateNested()
+    headline: ExtractBlockInput<typeof RichTextBlock>;
+}
+```
+
+This headline block has a required `eyebrow` field.
+Consequently, the block can only be saved after the user enters a text in the eyebrow field.
+If they forget to add an eyebrow text in a headline block deep down in the page content block, saving is impossible.
+They must navigate to the respective block, enter some text, and then save.
+Furthermore, they may not even want to have an eyebrow for the specific headline block.
+
+To improve the user experience, make sure that the user can save the block without having to enter an eyebrow text:
+
+```ts title="headline.block.ts"
+class HeadlineBlockInput extends BlockData {
+    @BlockField({ nullable: true })
+    @IsString()
+    @IsOptional()
+    eyebrow?: string;
+
+    ...
+}
+```
+
+Make sure to consider all three aspects of the field:
+First, add `nullable: true` to the `@BlockField` decorator for the block meta (and, therefore, the generated TypeScript interfaces).
+Second, add a `@IsOptional` decorator for the validation of the block input.
+Finally, denote the property as optional using `?` for TypeScript.
+
+:::note
+
+This best practice doesn't mean you should _never_ validate blocks.
+For instance, you should validate an email for correctness.
+However, you should only validate if the user has entered some text.
+
+:::
+
+## Expect incomplete block data
+
+As we have seen above, blocks should never prevent users from saving.
+Therefore, the clients of our API may receive incomplete block data.
+For instance, in the above-mentioned headline block example, the eyebrow text may still be missing.
+The client should handle the missing eyebrow text accordingly.
+
+```tsx title="HeadlineBlock.tsx"
+export const HeadlineBlock = withPreview(
+    ({ data: { eyebrow, headline } }: PropsWithData<HeadlineBlockData>) => {
+        return (
+            <>
+                // highlight-next-line
+                {eyebrow && <small>{eyebrow}</small>}
+                <RichTextBlock data={headline} />
+            </>
+        );
+    },
+    { label: "Headline" },
+);
+```
+
+Note how we only render the eyebrow if the user has entered a text.
+
+## React to empty states over using toggles/switches
+
+Parts of a block can be optional in some instances.
+For instance, a teaser block may have an optional call to action button.
+One may be tempted to use the OptionalBlock factory to achieve this behavior.
+However, using the factory introduces additional complexity for users by requiring them to toggle the visibility.
+A better solution is only displaying the button if it is maintained completely.
+
+```tsx title="TeaserBlock.tsx"
+export const TeaserBlock = withPreview(
+    ({ data: { image, callToAction } }: PropsWithData<TeaserBlockData>) => {
+        return (
+            <>
+                <ImageBlock data={image} />
+                // highlight-next-line
+                {callToAction.text.length > 0 && <button>{callToAction.text}</button>}
+            </>
+        );
+    },
+    { label: "Teaser" },
+);
+```