diff --git a/src/third-party/gutenberg.stories.mdx b/src/third-party/gutenberg.stories.mdx new file mode 100644 index 000000000..c5c52c032 --- /dev/null +++ b/src/third-party/gutenberg.stories.mdx @@ -0,0 +1,562 @@ +import { Story, Preview, Meta } from '@storybook/addon-docs/blocks'; +import codeBlockDemo from '../design/typography/demo/code-block.twig'; + + + +# WordPress Gutenberg Blocks + +The Wordpress [Gutenberg editor](https://wordpress.org/gutenberg/) is a block-based +page builder. The editor comes with a variety of core blocks. Of those, a subset +automatically generate markup with one or more `wp-block-`-prefixed classes. +These are the blocks documented below. + +Each block has controls that can modify the generated output. Where relevant, the +additional markup and/or classes that may be generated are also documented. + +### Editor Controls + +Block editor controls vary, but many have Styles and Color settings. The effects +of other controls are described in specific block stories. + +#### Styles + +These controls offer 2 or more options for particular stylistic variations, and +the ability to set one as a default for new blocks of the same type. For example, +images can have a circular mask or not. These options add an `is-style-`-type class +to the block. + +#### Color settings + +These controls enable setting of the block's `background-color` and `color`. + +The base class for a block with a main (background) color is `has-background` and +selecting a text color adds a `has-text-color` class. If one of a set of predefined +colors is chosen, additional classes are added, such as `has-subtle-background-background-color` +for `background-color` or `has-secondary-color` for text. + +If user-defined colors are chosen, instead, inline styles will set `color` and/or +`background-color`. + +## Audio + +The audio block wraps an `audio` and optional `figcaption` element in a layout +container. + + + {` +
+ +
My audio clip
+
+ `}
+
+ +## Button + +The button block adds call-to-action-style links to a post. Container elements provide +layout. + +If chosen, a button can have only an outline (no fill color), which adds the `is-style-outline` +class on the `.wp-block-button` element. + +Controls allow each button to have custom text color, background color or gradient, +and border radius. + + + + {`
+ +
`} +
+
+ +## Code + +The code block adds the class `wp-block-code` to a `pre` tag wrapping content inside +`code` tags. + + + + {codeBlockDemo({ + language: 'javascript', + })} + + + +## Columns + +The columns block creates a set of nested `div`s. The top wrapper `div` has a class +of `wp-block-columns` and each `div` below that has a class of `wp-block-column`. +Each column can contain arbitrary content. + +Controls set up the sizing of columns by adding an inline style with a `flex-basis` +declaration. Therefore, it's assumed that the `.wp-block-columns` wrapper must be +set to `display: flex`. + + + + {`
+
+

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros + eu felis. +

+
+ +
+

Suspendisse commodo neque lacus, a dictum orci interdum et.

+
+
+

+ Etiam et egestas lorem. Vivamus sagittis sit amet dolor quis lobortis. + Integer sed fermentum arcu, id vulputate lacus. Etiam fermentum sem eu + quam hendrerit. +

+

+ Nam risus massa, ullamcorper consectetur eros fermentum, porta aliquet + ligula. Sed vel mauris nec enim. +

+
+
`} +
+
+ +## Cover + +Adds an image or video with a text overlay. The cover block is a `div` with a class +of `wp-block-cover`. This `div` has a `style` attribute by default that sets its +`background-image` and `-color`. + +Controls set classes on the wrapper that adjust the opacity of the `background-color`. +The base class for this control is `has-background-dim`, and a percentage is specified +in a modifier class, e.g., `has-background-dim-40`. + +Another control results in setting `background-attachment` to `fixed`, by adding +the class `has-parallax`. + +The text overlay inside the cover block its own `div` wrapper with a class of +`wp-block_cover__inner-container`. + + + + {`
+
+

+ Snow Patrol +

+
+
`} +
+
+ +### Cover - Video Variant + + + + {`
+
+
+ +
+

Waterfall

+
+
`} +
+
+ +## Embed + +The embed block wraps any embedded content in a `figure` element with class +`wp-block-embed` and an inner `div` with class `wp-block-embed__wrapper`. Many +specific embed block types build on this core embed block, wrapping a specific embedded +content and adding `is-type-embedType-embed`, `wp-block-embed-embedType` and +`is-provider-providerType` classes to the parent wrapper element. + +Adding a caption in the editor includes a `figcaption` element before the closing +`figure` tag. + + + + {`
+
+ + +
+
`} +
+
+ +## File + +The file block allows downloading or opening media or page attachment content. + +This block creates a `div` with class `wp-block-file`, which wraps one or two +`a` elements, the second of which (toggled in the editor) is meant to be styled +as a button, adding the class `wp-block-file__button`. + + + + {``} + + + +## Gallery (images) + +The gallery block is wrapped in a `figure` element with the `wp-block-gallery` class. + +In the block's settings, the user can choose a number of columns, which adds a `columns-x` class. + +The gallery itself is a `ul` element with the class `blocks-gallery-grid` and each +item has a class of `blocks-gallery-item` + +A single control sets whether image thumbnails within the gallery are cropped to align +within the grid, adding an `is-cropped` class to the wrapper element + +Controls can update items to link to either either their source or their +attachment page. Either selection wraps the media element in an `a` tag. By default, +items are not wrapped in links. + +Adding a caption creates a `figcaption` element before the closing wrapper tag. + + + + {``} + + + +## Group + +A block that groups other (arbitrary) blocks. + +The group block is wrapped by a `div` with the class `wp-block-group`. + +A secondary wrapper `div` has the class `wp-block-group__inner-container`, and provides +a way to set padding on the grouped content within the parent wrapper. + +The group block has controls for setting both `background-color` and text `color`. +See [color-settings](#color-settings). + +By default, grouped blocks that don't set their own `background-color` and `color` +will inherit from the group block wrapper, but otherwise they will retain their +own styles. + + + + {`
+
+

One.

+

Two.

+

+ Three. +

+

+ Four. +

+

+ Five. +

+

Six.

+
+
`} +
+
+ +## Image + +The image block is wrapped in a `figure` element with the `wp-block-image` class. + +Inputs are available to set `alt` text, `width`, and `height` attributes. + +Controls set either the `is-style-default` (no masking) or `is-style-circle-mask` +class on the wrapper element. One of these classes is always present. + +Additional controls can add wrapper classes based on generated `srcset` options: +`size-full`, `size-large`, `size-medium`, or `size-thumbnail`. Further resizing +adds the `is-resized` class to the wrapper. + +Adding caption text to the image generates a `figcaption` element before the closing +wrapper tag. + + + + {`
+ Mont Blanc +
Mont Blanc appears—still, snowy, and serene.
+
`} +
+
+ +## Media-Text + +Combines media and textual content in a wrapper with a class of `wp-block-media-text`. +The media content is contained in a wrapper with class `wp-block-media-text__media` +and its text sibling has a class of `wp-block-media-text__content`. + +As with the group block, a control can set the parent wrapper's pre-selected or +custom `background-color`. See [color settings](#color-settings). + +Controls allow the horizontal and vertical alignment and arrangement of the media +and text elements. Choices result in the insertion of additional parent wrapper classes +such as `is-vertically-aligned-center` and `has-media-on-the-right`, as well as either +an `alignwide` (assumes horizontal padding) or `alignfull` (assumes no horizontal +padding) class. + +Another control toggles the class `is-stacked-on-mobile`. + + + + {`
+
+ +
+
+

The wren
Earns his living
Noiselessly.

+

— Kobayashi Issa (一茶)

+
+
`} +
+
+ +## Preformatted + +The preformatted block allows theming of content within `pre` tags using the `wp-block-preformatted` +class. + + + {/* eslint-disable no-useless-escape */} + + {`
+       ___________________________
+     < I'm an expert in my field. >
+       ---------------------------
+           \\  ^__^
+            \\ (oo)\\_______
+              (__)\\       )\\\/\\
+                  ||----w |
+                  ||     ||
+      
`} +
+ {/* eslint-enable no-useless-escape */} +
+ +## Pullquote + +The pullquote block wraps a `blockquote` element in a `figure` element with the class +`wp-block-pullquote`. + +[Color controls](#color-settings) allow the setting of pre-defined or custom `background-color` and +text `color`. A styles control adds one of two wrapper classes, `is-style-default` or +`is-style-solid-color`. By default, any user-selected `background-color` will be +applied only if the solid color background is toggled on. + + + + {`
+
+

One of the hardest things to do in technology is disrupt yourself.

+ Matt Mullenweg +
+
`} +
+
+ +## Quote + +The quote block adds class of `wp-block-quote` directly to a `blockquote` element. +It has a control to add an optional `is-style-large` class. + + + + {`
+

In quoting others, we cite ourselves.

+ Julio Cortázar +
`} +
+
+ +## Separator + +The separator block adds the `wp-block-separator` class to an `hr` element. + +Styles controls add `is-style-default`, `is-style-wide` or `is-style-dots` classes. + +The color controls, if used, can add both `has-text-color` and `has-background` +classes, as well as modifier classes for predefined color choices. + + + + {`
`} +
+
+ +## Spacer + +The spacer block is a `div` with a class of `wp-block-spacer`. + + + + {`

Content before spacer.

+ +

Content after spacer.

`} +
+
+ +## Table + +The table block renders a table wrapped in a `figure` element with the class +`wp-block-table`. Controls for this block render optional `thead` and `tfoot` sections. +A caption input renders a `figcaption` element within the wrapper and below the +`table` element. + +Right, left, or center alignment of cell content can be set at the column level, +and adds a `has-text-align-` class to each affected cell. + +Styles controls add one of 2 classes, `is-style-default` or `is-style-stripes` to +the parent wrapper, for controlling zebra-striping on alternate rows. + +Another control optionally adds the `has-fixed-layout` class to the `table` element. + + + + {`
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Heading 1Heading 2Heading 3
contentcontentcontent
contentcontentcontent
contentcontentcontent
FooterFooterFooter
+
A caption can be added but is not rendered as a caption element
+
+ `} +
+
+ +## Verse + +The verse block adds the `wp-block-verse` class to a `pre` element. + + + + {`
WHAT was he doing, the great god Pan,
Down in the reeds by the river?
Spreading ruin and scattering ban,
Splashing and paddling with hoofs of a goat,
And breaking the golden lilies afloat
With the dragon-fly on the river.
`} +
+
diff --git a/static/media/Biologia_Centrali-Americana_-_Cantorchilus_semibadius_1902.jpg b/static/media/Biologia_Centrali-Americana_-_Cantorchilus_semibadius_1902.jpg new file mode 100644 index 000000000..eb1e1d212 Binary files /dev/null and b/static/media/Biologia_Centrali-Americana_-_Cantorchilus_semibadius_1902.jpg differ diff --git a/static/media/Glacial_lakes_Bhutan.jpg b/static/media/Glacial_lakes_Bhutan.jpg new file mode 100644 index 000000000..d74a5f2e7 Binary files /dev/null and b/static/media/Glacial_lakes_Bhutan.jpg differ diff --git a/static/media/MtBlanc1-300x225.jpg b/static/media/MtBlanc1-300x225.jpg new file mode 100644 index 000000000..61a1e8ce4 Binary files /dev/null and b/static/media/MtBlanc1-300x225.jpg differ diff --git a/static/media/MtBlanc1.jpg b/static/media/MtBlanc1.jpg new file mode 100644 index 000000000..01a7a73eb Binary files /dev/null and b/static/media/MtBlanc1.jpg differ diff --git a/static/media/Sediment_off_the_Yucatan_Peninsula.jpg b/static/media/Sediment_off_the_Yucatan_Peninsula.jpg new file mode 100644 index 000000000..513a166f9 Binary files /dev/null and b/static/media/Sediment_off_the_Yucatan_Peninsula.jpg differ diff --git a/static/media/Squares.jpg b/static/media/Squares.jpg new file mode 100644 index 000000000..2cc642da6 Binary files /dev/null and b/static/media/Squares.jpg differ diff --git a/static/media/Windbuchencom.jpg b/static/media/Windbuchencom.jpg new file mode 100644 index 000000000..d93f84355 Binary files /dev/null and b/static/media/Windbuchencom.jpg differ diff --git a/static/media/piano.ogg b/static/media/piano.ogg new file mode 100644 index 000000000..e5c81d287 Binary files /dev/null and b/static/media/piano.ogg differ diff --git a/static/media/waterfall_edit.mp4 b/static/media/waterfall_edit.mp4 new file mode 100644 index 000000000..69c8e1db0 Binary files /dev/null and b/static/media/waterfall_edit.mp4 differ