diff --git a/src/components/Block/Block.mdx b/src/components/Block/Block.mdx new file mode 100644 index 00000000..3ec8a139 --- /dev/null +++ b/src/components/Block/Block.mdx @@ -0,0 +1,99 @@ +import { Meta, Canvas } from '@storybook/blocks'; + +import * as BlockStories from './Block.stories.svelte'; + + + +# Block + +The `Block` component is the basic building block of pages, a responsive container that wraps around each section of your piece. + +Blocks are stacked vertically within the well created by the [Article](./?path=/docs/components-page-layout-article--docs) component. They can have different widths on larger screens depending on the `width` prop. + +> 📌 Many of our other components already use the `Block` component internally. You'll usually only need to use it yourself if you're making something custom. + +```svelte + + + + + +``` + + + +## Custom layouts + +Our article well is designed to provide a basic responsive layout for you, but it also lets you customise. + +The radical but easiest way to do this is to create a `Block` with a `fluid` width -- which basically cancels out the article well dimensions -- and then code whatever you need from scratch or with another framework. + +The demo below does exactly that to create an edge-to-edge grid with [flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/). + +```svelte + +
+ +
+ +``` + + + +## Snap widths + +Normally, `Block` containers resize fluidly below the original `width`. Sometimes, though, you may want the container to snap to the next breakpoint -- for example, if you have a static graphic that looks fine at the set block breakpoints, but isn't so great at widths inbetween. + +You can use the `snap` prop to force the container to snap to each block width successively as the window sizes down. + +```svelte + + + +``` + + + +If you want to skip certain block widths entirely, you can add one or more class of `skip-{block width class}` to the `Block`. + +> **NOTE:** The snap width breakpoints only work on `Block` components with widths `wider` and below. `widest` and `fluid` are both **always** fluid, since they go edge-to-edge. + +```svelte + + + + +``` + +This is probably easier to see in action than explain in words, so [resize the demo](./?path=/docs/components-page-layout-block--snap-skip-widths) to get a better picture of how it all works. + +## Using with custom column widths + +Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the [Article](./?path=/docs/components-page-layout-article--docs) component (**rare!**), you need to do a littie work to use this functionality. + +Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you can target it with some custom SCSS. Then define a few SCSS variables corresponding to your custom column widths, and use the `block-snap-widths` SCSS mixin to get the same functionality at your custom breakpoints. + +```svelte + + + + + +``` diff --git a/src/components/Block/Block.stories.svelte b/src/components/Block/Block.stories.svelte index a13a0411..9c985c91 100644 --- a/src/components/Block/Block.stories.svelte +++ b/src/components/Block/Block.stories.svelte @@ -1,19 +1,11 @@ - +{#snippet template()} +
+
+
Article
+ +
Block
+ +
+
+{/snippet} - + - +
@@ -73,53 +57,76 @@ - +
Article
- narrower - narrow - normal - wide - wider - narrower - narrow +

snap widths

+ +
Block
+ +
+
+ + + +
+
+
Article
+

Regular layout

+ + + narrower + + + narrow + + + normal + + + wide + + + wider + + +

with snap and skip

+ + narrower + + + narrow + normal.skip-narrow + normal.skip-narrow + wide.skip-normal.skip-narrow + wide.skip-normal.skip-narrow + wider.skip-wide + wider.skip-wide +
-```