feat: Add Breakout component that lets a figure stick out of a Spotli…

…ght (#1397)

Co-authored-by: Aram <[email protected]>

documentation/storybook.md

@@ -84,10 +84,12 @@ argTypes: {
 
 ## Best practices for stories
 
-1. Use decorators and / or `args.children` before reaching for `render`. `render` can easily mess up the stories’ code view.
+1. Import the Story’s component from the `src` directory so that Storybook can display its types.
+   Import other components from the package as usual.
+2. Use decorators and / or `args.children` before reaching for `render`. `render` can easily mess up the stories’ code view.
    Decorators are not shown in the code view, `args.children` are.
-2. Always check your stories’ code view.
-3. `args.children` can be an array, separated by commas and given ascending numbers as keys.
+3. Always check your stories’ code view.
+4. `args.children` can be an array, separated by commas and given ascending numbers as keys.
 
 ## Future plans
 

packages/css/src/components/breakout/README.md

@@ -0,0 +1,5 @@
+<!-- @license CC0-1.0 -->
+
+# Breakout
+
+A composition that lets a figure – e.g. an image, video or map – break out of a Spotlight.

packages/css/src/components/breakout/breakout.scss

@@ -0,0 +1,163 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@import "../../common/breakpoint";
+@import "../grid/grid";
+@import "../grid/mixins";
+
+$ams-breakout-row-span-max: 4;
+
+.ams-breakout {
+  @include ams-grid;
+}
+
+// Grid gap
+
+.ams-breakout--gap-vertical--none {
+  @include ams-grid--gap-vertical--none;
+}
+
+.ams-breakout--gap-vertical--small {
+  @include ams-grid--gap-vertical--small;
+}
+
+.ams-breakout--gap-vertical--large {
+  @include ams-grid--gap-vertical--large;
+}
+
+// Grid padding
+
+.ams-breakout--padding-bottom--small {
+  @include ams-grid--padding-bottom--small;
+}
+
+.ams-breakout--padding-bottom--medium {
+  @include ams-grid--padding-bottom--medium;
+}
+
+.ams-breakout--padding-bottom--large {
+  @include ams-grid--padding-bottom--large;
+}
+
+.ams-breakout--padding-top--small {
+  @include ams-grid--padding-top--small;
+}
+
+.ams-breakout--padding-top--medium {
+  @include ams-grid--padding-top--medium;
+}
+
+.ams-breakout--padding-top--large {
+  @include ams-grid--padding-top--large;
+}
+
+.ams-breakout--padding-vertical--small {
+  @include ams-grid--padding-vertical--small;
+}
+
+.ams-breakout--padding-vertical--medium {
+  @include ams-grid--padding-vertical--medium;
+}
+
+.ams-breakout--padding-vertical--large {
+  @include ams-grid--padding-vertical--large;
+}
+
+// Column span
+// The order of these declaration blocks ensures the intended specificity.
+
+.ams-breakout__cell--col-span-all {
+  @include ams-grid__cell--span-all;
+}
+
+@for $i from 1 through $ams-grid-column-count {
+  .ams-breakout__cell--col-span-#{$i} {
+    @include ams-grid__cell--span($i);
+  }
+
+  .ams-breakout__cell--col-start-#{$i} {
+    @include ams-grid__cell--start($i);
+  }
+}
+
+@media screen and (min-width: $ams-breakpoint-medium) {
+  @for $i from 1 through $ams-grid-column-count {
+    .ams-breakout__cell--col-span-#{$i}-medium {
+      @include ams-grid__cell--span-medium($i);
+    }
+
+    .ams-breakout__cell--col-start-#{$i}-medium {
+      @include ams-grid__cell--start-medium($i);
+    }
+  }
+}
+
+@media screen and (min-width: $ams-breakpoint-wide) {
+  @for $i from 1 through $ams-grid-column-count {
+    .ams-breakout__cell--col-span-#{$i}-wide {
+      @include ams-grid__cell--span-wide($i);
+    }
+
+    .ams-breakout__cell--col-start-#{$i}-wide {
+      @include ams-grid__cell--start-wide($i);
+    }
+  }
+}
+
+// Has content
+
+.ams-breakout__cell--has-figure {
+  align-self: end;
+}
+
+.ams-breakout__cell--has-spotlight {
+  display: grid; /* Stretches the empty Spotlight vertically. */
+  margin-block: calc(var(--ams-space-grid-md) * -1);
+  margin-inline: calc(var(--ams-space-grid-lg) * -1);
+
+  .ams-breakout--gap-vertical--small > & {
+    margin-block: calc(var(--ams-space-grid-sm) * -1);
+  }
+
+  .ams-breakout--gap-vertical--large > & {
+    margin-block: calc(var(--ams-space-grid-lg) * -1);
+  }
+}
+
+// Row span
+
+@for $i from 1 through $ams-breakout-row-span-max {
+  .ams-breakout__cell--row-span-#{$i} {
+    grid-row-end: span $i;
+  }
+
+  .ams-breakout__cell--row-start-#{$i} {
+    grid-row-start: $i;
+  }
+}
+
+@media screen and (min-width: $ams-breakpoint-medium) {
+  @for $i from 1 through $ams-breakout-row-span-max {
+    .ams-breakout__cell--row-span-#{$i}-medium {
+      grid-row-end: span $i;
+    }
+
+    .ams-breakout__cell--row-start-#{$i}-medium {
+      grid-row-start: $i;
+    }
+  }
+}
+
+@media screen and (min-width: $ams-breakpoint-wide) {
+  @for $i from 1 through $ams-breakout-row-span-max {
+    .ams-breakout__cell--row-span-#{$i}-wide {
+      grid-row-end: span $i;
+    }
+
+    .ams-breakout__cell--row-start-#{$i}-wide {
+      grid-row-start: $i;
+    }
+  }
+}

packages/css/src/components/grid/_mixins.scss

@@ -0,0 +1,110 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@mixin ams-grid {
+  column-gap: var(--ams-grid-column-gap);
+  display: grid;
+  grid-template-columns: repeat(var(--ams-grid-column-count), 1fr);
+  padding-inline: var(--ams-grid-padding-inline);
+  row-gap: var(--ams-grid-row-gap-md);
+
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-template-columns: repeat(var(--ams-grid-medium-column-count), 1fr);
+  }
+
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-template-columns: repeat(var(--ams-grid-wide-column-count), 1fr);
+  }
+}
+
+// Grid gap
+
+@mixin ams-grid--gap-vertical--none {
+  row-gap: initial;
+}
+
+@mixin ams-grid--gap-vertical--small {
+  row-gap: var(--ams-grid-row-gap-sm);
+}
+
+@mixin ams-grid--gap-vertical--large {
+  row-gap: var(--ams-grid-row-gap-lg);
+}
+
+// Grid padding
+
+@mixin ams-grid--padding-bottom--small {
+  padding-block-end: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-bottom--medium {
+  padding-block-end: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-bottom--large {
+  padding-block-end: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid--padding-top--small {
+  padding-block-start: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-top--medium {
+  padding-block-start: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-top--large {
+  padding-block-start: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid--padding-vertical--small {
+  padding-block: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-vertical--medium {
+  padding-block: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-vertical--large {
+  padding-block: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid__cell--span-all {
+  grid-column: 1 / -1;
+}
+
+// Column span
+
+@mixin ams-grid__cell--span($i) {
+  grid-column-end: span $i;
+}
+
+@mixin ams-grid__cell--start($i) {
+  grid-column-start: $i;
+}
+
+@mixin ams-grid__cell--span-medium($i) {
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-column-end: span $i;
+  }
+}
+
+@mixin ams-grid__cell--start-medium($i) {
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-column-start: $i;
+  }
+}
+
+@mixin ams-grid__cell--span-wide($i) {
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-column-end: span $i;
+  }
+}
+
+@mixin ams-grid__cell--start-wide($i) {
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-column-start: $i;
+  }
+}