[ARGG-806] Add withScrimmedPortal component (#3041)

* Add withScrimmedPortal component

* update scrimmed portal

* Add tests and fix types

* add licenses

* enable automatic API table for scrim utils

* Update style to use spacing tokens

examples/bpk-scrim-utils/examples.css

@@ -0,0 +1,18 @@
+/*
+ * Backpack - Skyscanner's Design System
+ * 
+ * Copyright 2016 Skyscanner Ltd
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+@keyframes bpk-keyframe-spin{100%{transform:rotate(1turn)}}.bpk-scrim-utils-example__dialog{z-index:1100;width:100%;max-width:32rem;margin:auto;outline:0;background-color:#fff;opacity:1;box-shadow:0px 12px 50px 0px rgba(37,32,31,0.25);border-radius:.5rem}.bpk-scrim-utils-example__dialog-content{padding:1rem;flex:1;overflow-y:auto}.bpk-scrim-utils-example__dialog-container{display:flex;padding:1.5rem}

examples/bpk-scrim-utils/examples.scss

@@ -0,0 +1,45 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@import '../../packages/bpk-mixins/index.scss';
+
+.bpk-scrim-utils-example {
+  &__dialog {
+    z-index: $bpk-zindex-modal;
+    width: 100%;
+    max-width: $bpk-modal-max-width;
+    margin: auto;
+    outline: 0;
+    background-color: $bpk-modal-background-color;
+    opacity: $bpk-modal-opacity;
+
+    @include bpk-box-shadow-xl;
+    @include bpk-border-radius-sm;
+
+    &-content {
+      padding: $bpk-modal-content-padding;
+      flex: 1;
+      overflow-y: auto;
+    }
+
+    &-container {
+      display: flex;
+      padding: bpk-spacing-lg();
+    }
+  }
+}

examples/bpk-scrim-utils/examples.tsx

@@ -0,0 +1,74 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { withScrimmedPortal } from '../../packages/bpk-scrim-utils';
+import { BpkButtonV2 } from '../../packages/bpk-component-button';
+import { cssModules } from '../../packages/bpk-react-utils';
+
+import STYLES from './examples.scss';
+
+const getClassName = cssModules(STYLES);
+
+const DialogContent = () => (
+    <section
+        tabIndex={-1}
+        role="dialog"
+        className={getClassName('bpk-scrim-utils-example__dialog')}>
+        <div className={getClassName('bpk-scrim-utils-example__dialog-content')}>
+            <div>Dialog content here.</div>
+            <BpkButtonV2>Some button</BpkButtonV2>
+        </div>
+    </section>
+)
+const DialogContentWithScrim = withScrimmedPortal(DialogContent);
+
+const WithPortalScrimExample = () => (
+    <div id="pagewrap">
+        <div>
+            This element should be hidden from AT by the scrim.
+            It should also not be possible to tab to it.
+        </div>
+        <DialogContentWithScrim
+            getApplicationElement={() => document.getElementById('pagewrap')}
+            closeOnScrimClick={false}
+            containerClassName={getClassName('bpk-scrim-utils-example__dialog-container')}
+        />
+    </div>
+);
+
+const WithCustomElementAndPortalScrimExample = () => (
+    <div>
+        <div id="portalElement">
+            Dialog attached here.
+        </div>
+        <div id="pagewrap">
+            <div>
+            This element should be hidden from AT by the scrim.
+            It should also not be possible to tab to it.
+            </div>
+            <DialogContentWithScrim
+                getApplicationElement={() => document.getElementById('pagewrap')}
+                closeOnScrimClick={false}
+                containerClassName={getClassName('bpk-scrim-utils-example__dialog-container')}
+                renderTarget={() => document.getElementById('portalElement')}
+            />
+        </div>
+    </div>
+)
+
+export { WithPortalScrimExample, WithCustomElementAndPortalScrimExample };

examples/bpk-scrim-utils/stories.tsx

@@ -0,0 +1,52 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+import { Title, Markdown, PRIMARY_STORY } from '@storybook/blocks';
+import { ArgsTable } from '@storybook/addon-docs';
+
+import BpkScrim from '../../packages/bpk-scrim-utils/src/BpkScrim';
+
+import { withScrimMock, withScrimmedPortalMock } from './stories.utils';
+import {
+  WithPortalScrimExample,
+  WithCustomElementAndPortalScrimExample
+ } from './examples';
+
+export default {
+  title: 'bpk-scrim-utils',
+  component: BpkScrim,
+  subcomponents: { withScrimMock, withScrimmedPortalMock },
+  parameters: {
+    docs: {
+      page: () => (
+        <>
+          <Title />
+          <ArgsTable of={PRIMARY_STORY} />
+          <Markdown>
+          {`\`withScrim\` sends all props it receives down to the component, except \`getApplicationElement\` and \`padded\`. It also adds some props that are used for a11y and closing the modal:
+          \`dialogRef\` should be set as the ref on the visible container on top of the scrim; it is used to set focus, \`onClose\` , \`isIphone\``}
+          </Markdown>
+        </>
+      )
+    }
+  }
+};
+
+export const Example = WithPortalScrimExample;
+export const ExampleWithCustomRenderTarget = WithCustomElementAndPortalScrimExample;

examples/bpk-scrim-utils/stories.utils.tsx

@@ -0,0 +1,32 @@
+/*
+ * Backpack - Skyscanner's Design System
+ *
+ * Copyright 2016 Skyscanner Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This file is a workaround for Storybook not supporting HOCs API table generation in v7 by creating mock components that can be used to generate the API table
+ * They plan on adding support in v8
+ * https://github.com/storybookjs/storybook/issues/12558#issuecomment-1288834879
+ * @todo remove this file once we upgrade to Storybook v8
+ */
+
+import type { Props as withScrimProps } from '../../packages/bpk-scrim-utils/src/withScrim';
+import type { Props as withScrimmedPortalProps } from '../../packages/bpk-scrim-utils/src/withScrimmedPortal';
+
+const withScrimMock = (props: withScrimProps) => <div />;
+const withScrimmedPortalMock = (props: withScrimmedPortalProps) => <div />;
+
+export { withScrimMock, withScrimmedPortalMock };

packages/bpk-scrim-utils/README.md

@@ -17,31 +17,4 @@ const Box = props => (
 );
 
 const BoxWithScrim = withScrim(Box);
-```
-
-`withScrim` sends all props it receives down to the component, except `getApplicationElement` and `padded`. It also adds some props that are used for a11y and closing the modal:
-
-* `dialogRef` should be set as the ref on the visible container on top of the scrim; it is used to set focus
-* `onClose` should be set as the `onClick` action on a button or a link
-* `isIphone` can be used to apply iPhone only styles or behaviour, as it has different scrolling behaviour
-
-`containerClassName` can be used to apply styles to the full-screen container into which the enriched component is inserted
-(e.g. `display: flex` or `display: grid`)
-
-> **Note:** the `pagewrap` element id is a convention we use internally at Skyscanner. In most cases it should "just work".
-
-### Props
-
-| Property              | PropType | Required | Default Value                                                                    |
-| --------------------- | -------- | -------- | -------------------------------------------------------------------------------- |
-| onClose               | func     | true     | See prop details                                                                 |
-| getApplicationElement | func     | true     | -                                                                                |
-| isIphone              | bool     | false    | `/iPhone/i.test(typeof window !== 'undefined' ? window.navigator.platform : '')` |
-| containerClassName    | string   | false    | ''                                                                               |
-| closeOnScrimClick     | bool     | false    | true                                                                             |
-
-### Prop Details
-
-#### onClose
-
-This is required unless `closeOnScrimClick` is false.
+```