[PoC][Preview] Bpk layout PoC Preview

.storybook/main.ts

@@ -20,7 +20,7 @@ import type { StorybookConfig } from '@storybook/react-webpack5';
 
 const config: StorybookConfig = {
   stories: [
-    '../examples/**/stories.@(ts|tsx|js|jsx)',
+    '../examples/**/{stories,*.stories}.@(ts|tsx|js|jsx)',
   ],
   addons: [
     '@storybook/addon-a11y',

examples/bpk-component-layout/box-examples.tsx

@@ -0,0 +1,203 @@
+/*
+ * 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 {
+  BpkBox,
+  BpkSpacing,
+} from '../../packages/bpk-component-layout';
+
+import Wrapper from './layout-wrapper';
+
+import STYLES from './examples.module.scss';
+
+/**
+ * Core layout example – demonstrates basic spacing usage.
+ *
+ * @returns {JSX.Element} A box with padding and margin using Backpack spacing tokens.
+ */
+export const SpacingExample = () => (
+  <Wrapper>
+    <BpkBox padding={BpkSpacing.MD} margin={BpkSpacing.MD}>
+      <span className={STYLES['bpk-layout-examples__outline']}>
+        Default box with padding and margin using Backpack spacing tokens.
+      </span>
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * RTL-friendly spacing example – demonstrates margin/padding logical props.
+ *
+ * @returns {JSX.Element} Box using marginInline & paddingInline in RTL context.
+ */
+export const RtlSpacingExample = () => (
+  <Wrapper>
+    <div dir="rtl">
+      <BpkBox
+        paddingInline={BpkSpacing.MD}
+        marginInline={BpkSpacing.MD}
+        paddingTop={BpkSpacing.MD}
+        paddingBottom={BpkSpacing.Base}
+      >
+        <span className={STYLES['bpk-layout-examples__outline']}>
+          Box using marginInline &amp; paddingInline in RTL context.
+        </span>
+      </BpkBox>
+    </div>
+  </Wrapper>
+);
+
+/**
+ * Size example – demonstrates width/height using semantic values.
+ *
+ * @returns {JSX.Element} Box with 50% width and 6rem minHeight.
+ */
+export const SizeExample = () => (
+  <Wrapper>
+    <BpkBox width="50%" minHeight="6rem">
+      <span className={STYLES['bpk-layout-examples__outline']}>
+        Box with 50% width and 6rem minHeight.
+      </span>
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * Responsive example – demonstrates breakpoint-based responsive layout props.
+ *
+ * @returns {JSX.Element} A box whose spacing changes across breakpoints.
+ */
+export const ResponsiveExample = () => (
+  <Wrapper>
+    <BpkBox
+      display="flex"
+      padding={{
+        base: BpkSpacing.SM,
+        mobile: BpkSpacing.Base,
+        tablet: BpkSpacing.MD,
+        desktop: BpkSpacing.LG,
+      }}
+      gap={{
+        base: BpkSpacing.SM,
+        mobile: BpkSpacing.Base,
+        tablet: BpkSpacing.MD,
+        desktop: BpkSpacing.LG,
+      }}
+    >
+      <BpkBox>
+        <span className={STYLES['bpk-layout-examples__outline']}>
+          Responsive item 1
+        </span>
+      </BpkBox>
+      <BpkBox>
+        <span className={STYLES['bpk-layout-examples__outline']}>
+          Responsive item 2
+        </span>
+      </BpkBox>
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * Position example – demonstrates top/left offsets using allowed values.
+ *
+ * @returns {JSX.Element} A relative box with an absolutely positioned child.
+ */
+export const PositionExample = () => (
+  <Wrapper>
+    <BpkBox padding={BpkSpacing.MD}>
+      <BpkBox position="relative" width="10rem" minHeight="6rem">
+        <span className={STYLES['bpk-layout-examples__outline']}>
+          Relative box (10rem x 6rem)
+        </span>
+        <BpkBox position="absolute" top="12rem" left="6rem">
+          <span className={STYLES['bpk-layout-examples__outline']}>
+            Positioned child (top/left from 12rem, 6rem)
+          </span>
+        </BpkBox>
+      </BpkBox>
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * Flexbox example – demonstrates using BpkBox as a flex container.
+ *
+ * @returns {JSX.Element} A flex row with evenly spaced items.
+ */
+export const FlexExample = () => (
+  <Wrapper>
+    <BpkBox
+      display="flex"
+      flexDirection="row"
+      justifyContent="space-between"
+      padding={BpkSpacing.MD}
+    >
+      {[1, 2, 3].map((i) => (
+        <BpkBox key={i} padding={BpkSpacing.SM}>
+          <span className={STYLES['bpk-layout-examples__outline']}>
+            Flex item {i}
+          </span>
+        </BpkBox>
+      ))}
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * Grid example – demonstrates using BpkBox as a grid container.
+ *
+ * @returns {JSX.Element} A simple three-column grid.
+ */
+export const GridExample = () => (
+  <Wrapper>
+    <BpkBox
+      display="grid"
+      gridTemplateColumns="repeat(3, minmax(0, 1fr))"
+      gap={BpkSpacing.MD}
+      padding={BpkSpacing.MD}
+    >
+      {[1, 2, 3, 4, 5, 6].map((i) => (
+        <BpkBox key={i} padding={BpkSpacing.SM}>
+          <span className={STYLES['bpk-layout-examples__outline']}>
+            Grid cell {i}
+          </span>
+        </BpkBox>
+      ))}
+    </BpkBox>
+  </Wrapper>
+);
+
+/**
+ * Mixed visual regression example – used for Percy/visual tests.
+ *
+ * @returns {JSX.Element} A wrapper containing all Box examples for visual regression.
+ */
+export const MixedExample = () => (
+  <Wrapper>
+    <SpacingExample />
+    <RtlSpacingExample />
+    <SizeExample />
+    <ResponsiveExample />
+    <PositionExample />
+    <FlexExample />
+    <GridExample />
+  </Wrapper>
+);
+
+

examples/bpk-component-layout/box.stories.tsx

@@ -0,0 +1,67 @@
+/*
+ * 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 { ArgTypes, Title, Markdown } from '@storybook/addon-docs/blocks';
+
+import { BpkProvider, BpkBox } from '../../packages/bpk-component-layout';
+
+import {
+  SpacingExample,
+  RtlSpacingExample,
+  SizeExample,
+  ResponsiveExample,
+  PositionExample,
+  FlexExample,
+  GridExample,
+} from './box-examples';
+
+export default {
+  title: 'bpk-component-layout/Box',
+  component: BpkBox,
+  decorators: [
+    (Story: any) => (
+      <BpkProvider>
+        <Story />
+      </BpkProvider>
+    ),
+  ],
+  parameters: {
+    docs: {
+      page: () => (
+        <>
+          <Title />
+          <ArgTypes exclude={['zoomEnabled']} />
+          <Markdown>
+            Notes: `BpkBox` is the base layout primitive. It exposes a curated,
+            structural prop surface and tokenised spacing.
+          </Markdown>
+        </>
+      ),
+    },
+  },
+};
+
+export const Spacing = () => <SpacingExample />;
+export const RtlSpacing = () => <RtlSpacingExample />;
+export const Size = () => <SizeExample />;
+export const Responsive = () => <ResponsiveExample />;
+export const Position = () => <PositionExample />;
+export const FlexViaBox = () => <FlexExample />;
+export const GridViaBox = () => <GridExample />;
+
+

examples/bpk-component-layout/examples.module.scss

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+
+@use '../../packages/bpk-mixins/tokens';
+@use '../../packages/bpk-mixins/typography';
+
+.bpk-layout-examples {
+  &__frame {
+    padding: tokens.bpk-spacing-base();
+    background-color: tokens.$bpk-canvas-contrast-day;
+    border-radius: tokens.$bpk-border-radius-md;
+
+    // Subtle grid to make layout boundaries easier to see.
+   background-size: 8px 8px;
+
+    // Outline the root element of each example (not the inner content).
+    // This avoids needing border props on layout primitives.
+    > :where(*) {
+      outline: tokens.$bpk-border-size-sm solid tokens.$bpk-line-day;
+      outline-offset: tokens.bpk-spacing-sm();
+      background-color: tokens.$bpk-canvas-day;
+    }
+  }
+
+  // Generic “item boundary” styling for Storybook examples.
+  // Use this on regular DOM elements (not layout primitives) to avoid exposing
+  // border props on the layout surface.
+  &__item {
+    outline: tokens.$bpk-border-size-sm solid tokens.$bpk-line-day;
+    outline-offset: 0;
+    border-radius: tokens.$bpk-border-radius-sm;
+    background-color: tokens.$bpk-canvas-day;
+    box-sizing: border-box;
+  }
+
+  &__outline {
+    @include typography.bpk-body-default;
+
+    display: block;
+    width: 100%;
+    padding: tokens.bpk-spacing-sm();
+
+    color: tokens.$bpk-text-primary-day;
+    background-color: tokens.$bpk-surface-highlight-day;
+
+    outline: tokens.$bpk-border-size-sm dashed tokens.$bpk-line-day;
+    outline-offset: 0;
+    border-radius: tokens.$bpk-border-radius-sm;
+    box-sizing: border-box;
+  }
+}