wires/hypnagaga
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

finished docs

Browse source
This commit is contained in:
MinamiFunakoshiTR 2025-03-17 14:00:58 -07:00
parent cfeb4a6de2
commit ae9522ce5c
Failed to extract signature
4 changed files with 156 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
src/components/Block/Block.mdx
View file

@ -6,37 +6,43 @@ import * as BlockStories from './Block.stories.svelte';
# Block # Block
The `Block` component is the basic building block of stories, a responsive container that wraps each section of your piece. The `Block` component is the basic building block of pages, a responsive container that wraps around each section of your piece. The contents of each block are rendered as [snippets](https://svelte.dev/docs/svelte/snippet).
Blocks are stacked vertically within the well created by the [`Article`](./?path=/docs/layout-article) component. They can have different widths on larger screens depending on the `width` prop. 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. > 📌 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 ```svelte
<script> <script>
import { Block } from '@reuters-graphics/graphics-components'; import { Block } from '@reuters-graphics/graphics-components';
</script> </script>
<Block width="normal"> <Block>
<!-- Your stuff for this block --> {#snippet content()}
<!-- Contents for this block goes here -->
{/snippet}
</Block> </Block>
``` ```
<Canvas of={BlockStories.Demo} />
## Custom layouts ## Custom layouts
Our article well is designed to provide a basic responsive layout for you, but it's also made to get out of the way quickly when you need to do something custom. Our article well is designed to provide a basic responsive layout for you, but it also lets you customise.
If you need to get really radical, the easiest way 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 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 ```svelte
<Block width="fluid"> <Block width="fluid">
<div class="my-radical-container"> <div class="my-radical-container">
<!-- Now, you have full control! --> <!-- Now, you have full control over layout! -->
</div> </div>
</Block> </Block>
``` ```
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/). <Canvas of={BlockStories.CustomLayout} />
## Snap widths ## Snap widths
@ -46,35 +52,44 @@ You can use the `snap` prop to force the container to snap to each block width s
```svelte ```svelte
<Block width="wider" snap={true}> <Block width="wider" snap={true}>
<!-- Your stuff for this block --> {#snippet content()}
<!-- Contents for this block -->
{/snippet}
</Block> </Block>
``` ```
<Canvas of={BlockStories.SnapWidthsBasic} />
If you want to skip certain block widths entirely, you can add one or more class of `skip-{block width class}` to the `Block`. 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 ```svelte
<!-- Will skip wide and go straight to normal column width on resize. --> <!-- Will skip wide and go straight to normal column width on resize. -->
<Block width="wider" snap={true} class="skip-wide"> <Block width="wider" snap={true} class="skip-wide">
<!-- Your stuff for this block --> {#snippet content()}
<!-- Contents for this block -->
{/snippet}
</Block> </Block>
``` ```
This is probably easier to see in action than explain in words, so resize the window to get a better picture of how it all works. 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.
> **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. ## Using with custom column widths
#### 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.
Snap width breakpoints are hard-coded to the default article well column widths, so if you set custom `columnWidths` on the `Article` tag (**rare!**), you can't use this functionality without a little extra work. 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.
Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you can target it with some custom SCSS. Now, defined 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 ```svelte
<Block width="wider" snap={true} class="custom-blocks"> <Block width="wider" snap={true} class="custom-blocks">
<!-- Your stuff for this block --> {#snippet content()}
<!-- Contents for this block -->
{/snippet}
</Block> </Block>
<style lang="scss"> <style lang="scss">
// Define custom column widths
$column-width-narrower: 310px; $column-width-narrower: 310px;
$column-width-narrow: 450px; $column-width-narrow: 450px;
$column-width-normal: 600px; $column-width-normal: 600px;
@ -85,7 +100,7 @@ Luckily, it's still pretty easy. Just add a `cls` or `id` to your `Block` so you
:global { :global {
div.custom-blocks { div.custom-blocks {
@include mixins.block-snap-widths; @include mixins.block-snap-widths; // Use the `block-snap-widths` mixin
} }
} }
</style> </style>

134
src/components/Block/Block.stories.svelte
View file

@ -23,89 +23,136 @@
}); });
</script> </script>
<!--
<script> <script>
import Article from '../Article/Article.svelte'; import Article from '../Article/Article.svelte';
</script> --> </script>
<!-- {#snippet template()}
{#snippet children({ args })}
<Article id="block-demo-article"> <Article id="block-demo-article">
<div class="article-boundaries"> <div class="article-boundaries">
<div class="label">Article</div> <div class="label">Article</div>
<Block {...args}> <Block>
<div class="label">Block</div> {#snippet content()}
<div class="label">Block</div>
{/snippet}
</Block> </Block>
</div> </div>
</Article> </Article>
{/snippet} --> {/snippet}
<Story name="Demo" /> <Story name="Demo" children={template} />
<Story name="Custom layout" exportName="CustomLayout"> <Story name="Custom layout" exportName="CustomLayout">
<Block width="fluid"> <Block width="fluid">
<!-- Enter bootstrap grid! --> {#snippet content()}
<div id="block-flex-example"> <!-- Enter bootstrap grid! -->
<div class="row"> <div id="block-flex-example">
<div class="col">Column</div> <div class="row">
<div class="col-6">Column</div> <div class="col">Column</div>
<div class="col">Column</div> <div class="col-6">Column</div>
<div class="col">Column</div>
</div>
<div class="row">
<div class="col">Column</div>
<div class="col">Column</div>
</div>
</div> </div>
<div class="row"> {/snippet}
<div class="col">Column</div>
<div class="col">Column</div>
</div>
</div>
</Block> </Block>
</Story> </Story>
<!-- <Story name="Snap widths" exportName="SnapWidthsBasic">
<Story name="Snap widths">
<Article id="block-demo-article"> <Article id="block-demo-article">
<div class="article-boundaries"> <div class="article-boundaries">
<div class="label">Article</div> <div class="label">Article</div>
<Block width="narrower" snap={true} class="block-snap-widths-demo" <h4>snap widths</h4>
>narrower</Block <Block snap={true}>
{#snippet content()}
<div class="label">Block</div>
{/snippet}
</Block>
</div>
</Article>
</Story>
<Story name="Snap and skip widths" exportName="SnapSkipWidths">
<Article id="block-demo-article">
<div class="article-boundaries">
<div class="label">Article</div>
<h4>Regular layout</h4>
<Block width="narrower" snap={true} class="block-snap-widths-demo">
{#snippet content()}
narrower
{/snippet}
</Block>
<Block width="narrow" snap={true} class="block-snap-widths-demo">
{#snippet content()}
narrow
{/snippet}</Block
> >
<Block width="narrow" snap={true} class="block-snap-widths-demo" <Block width="normal" snap={true} class="block-snap-widths-demo">
>narrow</Block {#snippet content()}
> normal
<Block width="normal" snap={true} class="block-snap-widths-demo" {/snippet}
>normal</Block </Block>
> <Block width="wide" snap={true} class="block-snap-widths-demo">
<Block width="wide" snap={true} class="block-snap-widths-demo">wide</Block {#snippet content()}
> wide
<Block width="wider" snap={true} class="block-snap-widths-demo" {/snippet}
>wider</Block </Block>
> <Block width="wider" snap={true} class="block-snap-widths-demo">
<Block width="narrower" snap={true} class="block-snap-widths-demo even" {#snippet content()}
>narrower</Block wider
> {/snippet}
<Block width="narrow" snap={true} class="block-snap-widths-demo even" </Block>
>narrow</Block
<h4>with snap and skip</h4>
<Block width="narrower" snap={true} class="block-snap-widths-demo even">
{#snippet content()}
narrower
{/snippet}
</Block>
<Block width="narrow" snap={true} class="block-snap-widths-demo even">
{#snippet content()}
narrow
{/snippet}</Block
> >
<Block <Block
width="normal" width="normal"
snap={true} snap={true}
class="block-snap-widths-demo even skip-narrow" class="block-snap-widths-demo even skip-narrow"
>normal.skip-narrow</Block
> >
{#snippet content()}
normal.skip-narrow
{/snippet}
</Block>
<Block <Block
width="wide" width="wide"
snap={true} snap={true}
class="block-snap-widths-demo even skip-normal skip-narrow" class="block-snap-widths-demo even skip-normal skip-narrow"
>wide.skip-normal.skip-narrow</Block
> >
{#snippet content()}
wide.skip-normal.skip-narrow
{/snippet}
</Block>
<Block <Block
width="wider" width="wider"
snap={true} snap={true}
class="block-snap-widths-demo even skip-wide">wider.skip-wide</Block class="block-snap-widths-demo even skip-wide"
>
{#snippet content()}
wider.skip-wide
{/snippet}</Block
> >
</div> </div>
</Article> </Article>
</Story> --> </Story>
<style lang="scss"> <style lang="scss">
h4 {
text-align: center;
}
:global(#block-demo-article) { :global(#block-demo-article) {
background-color: #ddd; background-color: #ddd;
position: relative; position: relative;
@ -136,6 +183,7 @@
) { ) {
padding-left: 3px; padding-left: 3px;
color: white; color: white;
font-weight: 500;
} }
div#block-flex-example { div#block-flex-example {

52
src/components/Block/Block.svelte
View file

@ -1,37 +1,45 @@
<!-- @migration-task Error while migrating Svelte code: Cannot set properties of undefined (setting 'next') -->
<!-- @component `Block` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-block--docs) --> <!-- @component `Block` [Read the docs.](https://reuters-graphics.github.io/graphics-components/?path=/docs/components-page-layout-block--docs) -->
<script lang="ts"> <script lang="ts">
import type { Snippet } from 'svelte';
import type { ContainerWidth } from '../@types/global'; import type { ContainerWidth } from '../@types/global';
/** Width of the block within the article well. */ interface Props {
export let width: ContainerWidth = 'normal'; /** Content that goes inside `<Block>`*/
content: Snippet;
/** Width of the block within the article well. */
width?: ContainerWidth;
/** Add an id to the block tag to target it with custom CSS. */
id?: string;
/** Add custom classes to the block tag to target it with custom CSS. */
class?: string;
/** Snap block to column widths, rather than fluidly resizing them. */
snap?: boolean;
/** ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block */
role?: string;
/** ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block */
ariaLabel?: string;
}
/** Add an id to the block tag to target it with custom CSS. */ let {
export let id: string = ''; content,
width = 'normal',
/** Add extra classes to the block tag to target it with custom CSS. */ id = '',
let cls: string = ''; class: cls = '',
export { cls as class }; snap = false,
role,
/** Snap block to column widths, rather than fluidly resizing them. */ ariaLabel,
export let snap: boolean = false; }: Props = $props();
/** ARIA [role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles) for the block */
export let role: string | null = null;
/** ARIA [label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) for the block */
export let ariaLabel: string | null = null;
</script> </script>
<div <div
{id} {id}
class="article-block fmx-auto {width} {cls}" class="article-block fmx-auto {width} {cls}"
class:snap="{snap && width !== 'fluid' && width !== 'widest'}" class:snap={snap && width !== 'fluid' && width !== 'widest'}
{role} {role}
aria-label="{ariaLabel}" aria-label={ariaLabel}
> >
<!-- block content --> <!-- block content -->
<slot /> {@render content()}
</div> </div>
<style lang="scss"> <style lang="scss">
@ -66,7 +74,7 @@
max-width: none; max-width: none;
} }
// Only setup for the default column widths, b/c can't use // Only setup for the default column widths, b/c we can't use
// CSS vars in media queries. // CSS vars in media queries.
&.snap { &.snap {
@include mixins.block-snap-widths; @include mixins.block-snap-widths;

2
src/components/BodyText/BodyText.mdx
View file

@ -30,7 +30,7 @@ Venison shoulder *ham hock ham leberkas*. Flank beef ribs fatback, jerky meatbal
## Using with ArchieML docs ## Using with ArchieML docs
With the graphics kit, you'll likely get your text value from an ArchieML doc. With the Graphics Kit, you'll likely get your text value from an ArchieML doc.
```yaml ```yaml
# Archie ML doc # Archie ML doc