@frontify/guideline-blocks-settings 0.27.0 → 0.28.0

package/.eslintrc.js

@@ -1,7 +1,7 @@
 /* (c) Copyright Frontify Ltd., all rights reserved. */
 
 module.exports = {
-    extends: ['@frontify/eslint-config-typescript'],
+    extends: ['@frontify/eslint-config-react'],
     plugins: ['notice'],
     overrides: [
         {

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @frontify/guideline-blocks-settings
 
+## 0.28.0
+
+### Minor Changes
+
+- [#453](https://github.com/Frontify/brand-sdk/pull/453) [`0807349`](https://github.com/Frontify/brand-sdk/commit/0807349856fe972953493c253ac8e4ce352d3ede) Thanks [@fulopdaniel](https://github.com/fulopdaniel)! - Added components, helpers and utilities to simplify Blocks development
+
+- [#466](https://github.com/Frontify/brand-sdk/pull/466) [`9f81a23`](https://github.com/Frontify/brand-sdk/commit/9f81a2363cd3c842d0ac5c014e0b07c46a3a1cca) Thanks [@triggertoo](https://github.com/triggertoo)! - Remove downloadAsset helper since it's unrelated to the settings
+
+### Patch Changes
+
+- [#482](https://github.com/Frontify/brand-sdk/pull/482) [`6b18a74`](https://github.com/Frontify/brand-sdk/commit/6b18a74794612f61bd2e34ea8fdd4572ebb5274e) Thanks [@fulopdaniel](https://github.com/fulopdaniel)! - feat(\*): update shared folder with latest changes
+
+- Updated dependencies [[`4105251`](https://github.com/Frontify/brand-sdk/commit/4105251969f8ae639014a013a2cbc88df8e4935d), [`af49f65`](https://github.com/Frontify/brand-sdk/commit/af49f6572592522a550f970c98e3d8fd2d377cc3)]:
+  - @frontify/sidebar-settings@0.6.0
+
 ## 0.27.0
 
 ### Minor Changes

package/README.md

@@ -7,10 +7,9 @@ Provides the block settings types for the guideline-blocks.
 ```ts
 /* (c) Copyright Frontify Ltd., all rights reserved. */
 
-import { BlockSettings, Bundle } from '@frontify/guideline-blocks-settings';
-import { IconEnum } from '@frontify/fondue';
+import { IconEnum, defineSettings } from '@frontify/guideline-blocks-settings';
 
-export const settings: BlockSettings = {
+export const settings = defineSettings({
     main: [
         {
             id: 'example',
@@ -29,7 +28,7 @@ export const settings: BlockSettings = {
                     label: 'Line',
                 },
             ],
-            onChange: (bundle: Bundle): void => {
+            onChange: (bundle): void => {
                 const blockWidth = Number(bundle.getBlock('widthCustom')?.value);
                 if (!Number.isNaN(blockWidth)) {
                     bundle.setBlockValue('widthCustom', `${blockWidth}%`);
@@ -37,5 +36,25 @@ export const settings: BlockSettings = {
             },
         },
     ],
-};
+});
 ```
+
+# Block development helpers
+
+## Code Structure
+
+-   `components` (React components which are reused across multiple blocks)
+-   `utilities` (functionality without business logic)
+-   `helpers` (functionality with business logic)
+
+## Using components
+
+To use React components, you need to add the styles import from the `@frontify/guideline-blocks-settings` package:
+
+```
+import '@frontify/guideline-blocks-settings/styles';
+```
+
+## Development
+
+Run `pnpm build` to make changes directly available to the linked packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontify/guideline-blocks-settings",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Provides types and helpers for the guideline block development",
   "sideEffects": false,
   "main": "dist/index.umd.js",
@@ -14,22 +14,56 @@
     "url": "https://github.com/Frontify/brand-sdk",
     "directory": "packages/guideline-blocks-settings"
   },
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.js"
+    },
+    "./styles": "./dist/style.css"
+  },
   "devDependencies": {
-    "@frontify/eslint-config-typescript": "^0.15.7",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.1",
-    "eslint": "^8.39.0",
+    "@babel/core": "^7.22.5",
+    "@frontify/eslint-config-typescript": "^0.15.8",
+    "@testing-library/react": "^14.0.0",
+    "@types/escape-html": "^1.0.2",
+    "@types/node": "^18.7.21",
+    "@types/react": "^18.2.14",
+    "@types/react-dom": "^18.2.6",
+    "@types/sinon": "^10.0.15",
+    "@vitejs/plugin-react": "^4.0.1",
+    "autoprefixer": "^10.4.14",
+    "cypress": "^12.16.0",
+    "cypress-real-events": "^1.8.1",
+    "eslint": "^8.43.0",
     "eslint-plugin-notice": "^0.9.10",
+    "happy-dom": "^9.20.3",
+    "mitt": "^3.0.0",
+    "msw": "^1.2.2",
+    "postcss": "^8.4.24",
     "prettier": "^2.8.8",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "typescript": "^5.0.4",
-    "vite": "^4.3.2",
-    "vite-plugin-dts": "^2.3.0"
+    "sinon": "15.2.0",
+    "tailwindcss": "^3.3.2",
+    "typescript": "^5.1.5",
+    "vite": "^4.3.9",
+    "vite-plugin-dts": "^2.3.0",
+    "vitest": "^0.32.2"
   },
   "dependencies": {
-    "@frontify/app-bridge": "^3.0.0-beta.66",
-    "@frontify/sidebar-settings": "^0.5.0"
+    "@ctrl/tinycolor": "^3.6.0",
+    "@dnd-kit/core": "^6.0.8",
+    "@dnd-kit/modifiers": "^6.0.1",
+    "@dnd-kit/sortable": "^7.0.2",
+    "@frontify/fondue": "^12.0.0-beta.287",
+    "@react-aria/focus": "^3.13.0",
+    "@react-stately/overlays": "^3.6.0",
+    "@udecode/plate": "^21",
+    "escape-html": "^1.0.3",
+    "slate": "^0.94.1",
+    "slate-react": "^0.97.1",
+    "@frontify/app-bridge": "3.0.0-beta.86",
+    "@frontify/sidebar-settings": "0.6.0"
   },
   "peerDependencies": {
     "react": "^18",
@@ -41,6 +75,8 @@
     "lint:fix": "eslint --fix .",
     "prettier": "prettier --check .",
     "prettier:fix": "prettier --write .",
+    "test": "vitest run --silent",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
   }
 }

package/postcss.config.js

@@ -0,0 +1,8 @@
+/* (c) Copyright Frontify Ltd., all rights reserved. */
+
+module.exports = {
+    plugins: {
+        tailwindcss: {},
+        autoprefixer: {},
+    },
+};

package/setupTests.ts

@@ -0,0 +1,13 @@
+/* (c) Copyright Frontify Ltd., all rights reserved. */
+
+import { afterEach, vi } from 'vitest';
+
+vi.stubGlobal('crypto', {
+    getRandomValues: vi.fn(),
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+globalThis.structuredClone = (data: unknown) => JSON.parse(JSON.stringify(data));

package/src/components/Attachments/AttachmentItem.tsx

@@ -0,0 +1,257 @@
+/* (c) Copyright Frontify Ltd., all rights reserved. */
+
+import { MutableRefObject, forwardRef, useEffect, useState } from 'react';
+import { Asset, useAssetUpload, useFileInput } from '@frontify/app-bridge';
+import { useSortable } from '@dnd-kit/sortable';
+import { useFocusRing } from '@react-aria/focus';
+
+import {
+    ActionMenu,
+    Button,
+    ButtonEmphasis,
+    FOCUS_STYLE,
+    Flyout,
+    FlyoutPlacement,
+    IconArrowCircleUp20,
+    IconDocument24,
+    IconGrabHandle20,
+    IconImage24,
+    IconImageStack20,
+    IconMusicNote24,
+    IconPen20,
+    IconPlayFrame24,
+    IconTrashBin20,
+    LoadingCircle,
+    LoadingCircleSize,
+    MenuItemContentSize,
+    MenuItemStyle,
+} from '@frontify/fondue';
+import { AttachmentItemProps, SortableAttachmentItemProps } from './types';
+import { joinClassNames } from '../../utilities';
+
+const getDecorator = (type: string) => {
+    if (type === 'IMAGE') {
+        return <IconImage24 />;
+    } else if (type === 'VIDEO') {
+        return <IconPlayFrame24 />;
+    } else if (type === 'AUDIO') {
+        return <IconMusicNote24 />;
+    } else {
+        return <IconDocument24 />;
+    }
+};
+
+export const AttachmentItem = forwardRef<HTMLButtonElement, AttachmentItemProps>(
+    (
+        {
+            item,
+            isEditing,
+            draggableProps,
+            transformStyle,
+            isDragging,
+            isOverlay,
+            isLoading,
+            onDelete,
+            onReplaceWithBrowse,
+            onReplaceWithUpload,
+        },
+        ref
+    ) => {
+        const [selectedAsset, setSelectedAsset] = useState<Asset | undefined>();
+        const [openFileDialog, { selectedFiles }] = useFileInput({ multiple: true, accept: 'image/*' });
+        const [uploadFile, { results: uploadResults, doneAll }] = useAssetUpload();
+        const { focusProps, isFocusVisible } = useFocusRing();
+
+        useEffect(() => {
+            if (selectedFiles) {
+                uploadFile(selectedFiles[0]);
+            }
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [selectedFiles]);
+
+        useEffect(() => {
+            if (doneAll) {
+                onReplaceWithUpload(uploadResults[0]);
+            }
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [doneAll, uploadResults]);
+
+        const download = (url: string, filename: string) => {
+            fetch(url).then((response) => {
+                response.blob().then((blob) => {
+                    const url = URL.createObjectURL(blob);
+                    const a = document.createElement('a');
+                    a.href = url;
+                    a.download = filename;
+                    a.click();
+                });
+            });
+        };
+
+        const showLoadingCircle = isLoading || (selectedFiles && !doneAll);
+
+        return (
+            <button
+                aria-label="Download attachment"
+                data-test-id="attachments-item"
+                onClick={() => download(item.genericUrl, item.fileName)}
+                ref={ref}
+                style={{
+                    ...transformStyle,
+                    opacity: isDragging && !isOverlay ? 0.3 : 1,
+                    fontFamily: 'var(-f-theme-settings-body-font-family)',
+                }}
+                className={joinClassNames([
+                    'tw-cursor-pointer tw-text-left tw-w-full tw-relative tw-flex tw-gap-3 tw-px-5 tw-py-3 tw-items-center tw-group hover:tw-bg-box-neutral-hover',
+                    isDragging ? 'tw-bg-box-neutral-hover' : '',
+                ])}
+            >
+                <div className="tw-text-text-weak group-hover:tw-text-box-neutral-inverse-hover">
+                    {showLoadingCircle ? (
+                        <LoadingCircle size={LoadingCircleSize.Small} />
+                    ) : (
+                        getDecorator(item.objectType)
+                    )}
+                </div>
+                <div className="tw-text-s tw-flex-1 tw-min-w-0">
+                    <div className="tw-whitespace-nowrap tw-overflow-hidden tw-text-ellipsis tw-font-bold tw-text-text-weak group-hover:tw-text-box-neutral-inverse-hover">
+                        {item.title}
+                    </div>
+                    <div className="tw-text-text-weak">{`${item.fileSizeHumanReadable} - ${item.extension}`}</div>
+                </div>
+                {isEditing && (
+                    <div
+                        data-test-id="attachments-actionbar"
+                        className={joinClassNames([
+                            'tw-flex tw-gap-0.5 group-focus:tw-opacity-100 focus-visible:tw-opacity-100 focus-within:tw-opacity-100 group-hover:tw-opacity-100',
+                            isOverlay || selectedAsset?.id === item.id ? 'tw-opacity-100' : 'tw-opacity-0',
+                        ])}
+                    >
+                        <button
+                            {...focusProps}
+                            {...draggableProps}
+                            aria-label="Drag attachment"
+                            className={joinClassNames([
+                                ' tw-border-button-border tw-bg-button-background active:tw-bg-button-background-pressed tw-group tw-border tw-box-box tw-relative tw-flex tw-items-center tw-justify-center tw-outline-none tw-font-medium tw-rounded tw-h-9 tw-w-9 ',
+                                isDragging || isOverlay
+                                    ? 'tw-cursor-grabbing tw-bg-button-background-pressed hover:tw-bg-button-background-pressed'
+                                    : 'tw-cursor-grab hover:tw-bg-button-background-hover',
+                                isFocusVisible && FOCUS_STYLE,
+                                isFocusVisible && 'tw-z-[2]',
+                            ])}
+                        >
+                            <IconGrabHandle20 />
+                        </button>
+                        <div data-test-id="attachments-actionbar-flyout">
+                            <Flyout
+                                placement={FlyoutPlacement.Right}
+                                isOpen={selectedAsset?.id === item.id}
+                                fitContent
+                                legacyFooter={false}
+                                onOpenChange={(isOpen) => setSelectedAsset(isOpen ? item : undefined)}
+                                trigger={(_, ref) => (
+                                    <Button
+                                        ref={ref as MutableRefObject<HTMLButtonElement>}
+                                        icon={<IconPen20 />}
+                                        emphasis={ButtonEmphasis.Default}
+                                        onClick={() => setSelectedAsset(item)}
+                                    />
+                                )}
+                            >
+                                <ActionMenu
+                                    menuBlocks={[
+                                        {
+                                            id: 'menu',
+                                            menuItems: [
+                                                {
+                                                    id: 'upload',
+                                                    size: MenuItemContentSize.XSmall,
+                                                    title: 'Replace with upload',
+                                                    onClick: () => {
+                                                        openFileDialog();
+                                                        setSelectedAsset(undefined);
+                                                    },
+
+                                                    initialValue: true,
+                                                    decorator: (
+                                                        <div className="tw-mr-2">
+                                                            <IconArrowCircleUp20 />
+                                                        </div>
+                                                    ),
+                                                },
+
+                                                {
+                                                    id: 'asset',
+                                                    size: MenuItemContentSize.XSmall,
+                                                    title: 'Replace with asset',
+                                                    onClick: () => {
+                                                        onReplaceWithBrowse();
+                                                        setSelectedAsset(undefined);
+                                                    },
+                                                    initialValue: true,
+                                                    decorator: (
+                                                        <div className="tw-mr-2">
+                                                            <IconImageStack20 />
+                                                        </div>
+                                                    ),
+                                                },
+                                            ],
+                                        },
+                                        {
+                                            id: 'menu-delete',
+                                            menuItems: [
+                                                {
+                                                    id: 'delete',
+                                                    size: MenuItemContentSize.XSmall,
+                                                    title: 'Delete',
+                                                    style: MenuItemStyle.Danger,
+                                                    onClick: () => {
+                                                        onDelete();
+                                                        setSelectedAsset(undefined);
+                                                    },
+
+                                                    initialValue: true,
+                                                    decorator: (
+                                                        <div className="tw-mr-2">
+                                                            <IconTrashBin20 />
+                                                        </div>
+                                                    ),
+                                                },
+                                            ],
+                                        },
+                                    ]}
+                                />
+                            </Flyout>
+                        </div>
+                    </div>
+                )}
+            </button>
+        );
+    }
+);
+
+AttachmentItem.displayName = 'AttachmentItem';
+
+export const SortableAttachmentItem = (props: SortableAttachmentItemProps) => {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+        id: props.item.id,
+    });
+
+    const transformStyle = {
+        transform: transform ? `translate(${transform.x}px, ${transform.y}px)` : '',
+        transition,
+        zIndex: isDragging ? 2 : 1,
+    };
+
+    const draggableProps = { ...attributes, ...listeners };
+
+    return (
+        <AttachmentItem
+            ref={setNodeRef}
+            isDragging={isDragging}
+            transformStyle={transformStyle}
+            draggableProps={draggableProps}
+            {...props}
+        />
+    );
+};

package/src/components/Attachments/Attachments.spec.ct.tsx

@@ -0,0 +1,151 @@
+/* (c) Copyright Frontify Ltd., all rights reserved. */
+
+import { AssetDummy, getAppBridgeBlockStub } from '@frontify/app-bridge';
+import { mount } from 'cypress/react18';
+import { Attachments as AttachmentsComponent } from './Attachments';
+import { AttachmentsProps } from './types';
+import { SinonStub } from 'cypress/types/sinon';
+
+const FlyoutButtonSelector = '[data-test-id="attachments-flyout-button"]';
+const AssetInputSelector = '[data-test-id="asset-input-placeholder"]';
+const ActionBarSelector = '[data-test-id="attachments-actionbar"]';
+const DragHandleSelector = '[data-test-id="attachments-actionbar"] > button';
+const FlyoutTriggerSelector = '[data-test-id="attachments-actionbar-flyout"] button';
+const AttachmentItemSelector = '[data-test-id="attachments-item"]';
+const MenuItemSelector = '[data-test-id="menu-item"]';
+const LoadingCircleSelector = '[data-test-id="loading-circle"]';
+
+const Attachments = ({
+    appBridge = getAppBridgeBlockStub(),
+    onDelete = cy.stub(),
+    items,
+    onReplaceWithBrowse = cy.stub(),
+    onReplaceWithUpload = cy.stub(),
+    onSorted = cy.stub(),
+    onBrowse = cy.stub(),
+    onUpload = cy.stub(),
+}: Partial<AttachmentsProps>) => {
+    return (
+        <AttachmentsComponent
+            appBridge={appBridge}
+            onDelete={onDelete}
+            items={items}
+            onReplaceWithBrowse={onReplaceWithBrowse}
+            onReplaceWithUpload={onReplaceWithUpload}
+            onSorted={onSorted}
+            onBrowse={onBrowse}
+            onUpload={onUpload}
+        />
+    );
+};
+
+describe('Attachments', () => {
+    it('renders attachments flyout if it is in edit mode', () => {
+        mount(<Attachments appBridge={getAppBridgeBlockStub({ editorState: true })} />);
+        cy.get(FlyoutButtonSelector).should('exist');
+    });
+
+    it('renders attachments flyout if it has attachments', () => {
+        mount(<Attachments items={[AssetDummy.with(1)]} />);
+        cy.get(FlyoutButtonSelector).should('exist');
+    });
+
+    it('does not render attachments flyout if there are no attachments', () => {
+        mount(<Attachments items={[]} />);
+        cy.get(FlyoutButtonSelector).should('not.exist');
+    });
+
+    it('renders asset input if in edit mode', () => {
+        mount(<Attachments appBridge={getAppBridgeBlockStub({ editorState: true })} items={[AssetDummy.with(1)]} />);
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(AssetInputSelector).should('exist');
+    });
+
+    it('does not render asset input if in view mode', () => {
+        mount(<Attachments items={[AssetDummy.with(1)]} />);
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(AssetInputSelector).should('not.exist');
+    });
+
+    it('renders asset action buttons if in edit mode', () => {
+        mount(<Attachments appBridge={getAppBridgeBlockStub({ editorState: true })} items={[AssetDummy.with(1)]} />);
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(ActionBarSelector).should('exist');
+    });
+
+    it('does not render asset action buttons if in view mode', () => {
+        mount(<Attachments items={[AssetDummy.with(1)]} />);
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(ActionBarSelector).should('not.exist');
+    });
+
+    it('renders an attachment item for each asset', () => {
+        mount(<Attachments items={[AssetDummy.with(1), AssetDummy.with(2), AssetDummy.with(3)]} />);
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(AttachmentItemSelector).should('have.length', 3);
+    });
+
+    it('renders loading circle for attachment item', () => {
+        const appBridge = getAppBridgeBlockStub({
+            editorState: true,
+        });
+        (appBridge.openAssetChooser as SinonStub) = cy.stub().callsArgWith(0, AssetDummy.with(4));
+
+        cy.clock();
+        const replaceStub = () =>
+            new Promise<void>((resolve) =>
+                setTimeout(() => {
+                    resolve();
+                }, 2000)
+            );
+
+        mount(
+            <Attachments
+                onReplaceWithBrowse={replaceStub}
+                items={[AssetDummy.with(1), AssetDummy.with(2), AssetDummy.with(3)]}
+                appBridge={appBridge}
+            />
+        );
+
+        cy.get(FlyoutButtonSelector).click();
+        cy.get(AttachmentItemSelector).eq(0).focus();
+        cy.get(FlyoutTriggerSelector).eq(1).click();
+        cy.get(MenuItemSelector).eq(1).click();
+        cy.get(LoadingCircleSelector).should('exist');
+        cy.tick(2000);
+        cy.get(LoadingCircleSelector).should('not.exist');
+    });
+
+    it('renders focus ring on flyout button while tabbing and open it', () => {
+        mount(
+            <Attachments
+                appBridge={getAppBridgeBlockStub({ editorState: true })}
+                items={[AssetDummy.with(1), AssetDummy.with(2), AssetDummy.with(3)]}
+            />
+        );
+        cy.get(FlyoutButtonSelector).click();
+        cy.realPress('Tab');
+        cy.realPress('Tab');
+        cy.realPress('Tab');
+        cy.get(FlyoutTriggerSelector).eq(0).should('have.class', 'focus-visible:tw-ring-blue');
+        cy.get(FlyoutTriggerSelector).eq(0).type('{enter}');
+        cy.get(MenuItemSelector).should('exist');
+    });
+
+    it('reorders items using only keyboard events', () => {
+        const onSortStub = cy.stub();
+        mount(
+            <Attachments
+                appBridge={getAppBridgeBlockStub({ editorState: true })}
+                items={[{ ...AssetDummy.with(1), title: 'Moved item' }, AssetDummy.with(2), AssetDummy.with(3)]}
+                onSorted={onSortStub}
+            />
+        );
+        cy.get(FlyoutButtonSelector).click();
+        cy.realPress('Tab');
+        cy.realPress('Tab');
+        cy.realPress('Tab');
+        cy.get(DragHandleSelector).eq(0).type(' {downarrow}{downarrow} ');
+        cy.get(AttachmentItemSelector).eq(1).should('contain.text', 'Moved item');
+    });
+});