@reuters-graphics/graphics-components 3.10.0 → 4.0.0

package/dist/llm-docs/components/Table.md

@@ -0,0 +1,298 @@
+# Table
+
+**Category:** Components/Graphics/Table
+
+**Import:** `import { Table } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `data` | `T[]` | — | ✓ | Data for the table as an array. |
+| `title` | `string` | — |  | A title that runs above the table. |
+| `dek` | `string` | — |  | A block of text that runs above the table. |
+| `notes` | `string` | — |  | A footnote that runs below the table. |
+| `source` | `string` | — |  | A source line that runs below the table. |
+| `includedFields` | `string[]` | `Object.keys(data[0]).filter((f) => f !== 'searchStr')` |  | List of the fields to include in the table. By default everything goes. |
+| `truncated` | `boolean` | `false` |  | Whether or not the table is cutoff after a set number of rows. |
+| `truncateLength` | `number` | `5` |  | If the table is truncated, how many rows to allow before the cutoff. |
+| `paginated` | `boolean` | `false` |  | Whether or not the table is paginated after a set number of rows. |
+| `pageSize` | `number` | `25` |  | The default page size. |
+| `searchable` | `boolean` | `false` |  | Whether or not searches are allowed. |
+| `searchPlaceholder` | `string` | `'Search in table'` |  | The placeholder text that appears in the search box. |
+| `filterField` | `string` | `''` |  | A field to offer uses as an interactive filter. |
+| `filterLabel` | `string` | — |  | The label to place above the filter box. |
+| `sortable` | `boolean` | `false` |  | Whether or not sorts are allowed. |
+| `sortField` | `string` | `Object.keys(data[0])[0]` |  | The column to sort by. By default it's the first header. |
+| `sortableFields` | `string[]` | `Object.keys(data[0]).filter((f) => f !== 'searchStr')` |  | The columns that are allowed to sort. It's all of them by default. |
+| `sortDirection` | `'ascending' \| 'descending'` | `$bindable('ascending')` |  | The direction of the sort. By default it's ascending. |
+| `fieldFormatters` | `FieldFormatters<T>` | — |  | Custom field formatting functions. Should be keyed to the name of the field. |
+| `width` | `'normal' \| 'wide' \| 'wider' \| 'widest' \| 'fluid'` | `'normal'` |  | Width of the component within the text well. Options: `normal`, `wide`, `wider`, `widest`, `fluid` |
+| `id` | `string` | `''` |  | Add an ID to target with SCSS. |
+| `class` | `string` | `''` |  | Add a class to target with SCSS. |
+
+## Examples
+
+### Demo
+
+```svelte
+<Table width="normal" data={/* homeRuns */} />
+```
+
+### Text elements
+
+```svelte
+<Table
+  data={/* homeRuns */}
+  title="Career home run leaders"
+  dek="In baseball, a home run (also known as a "dinger" or "tater") occurs when a batter hits the ball over the outfield fence. When a home run is hit, the batter and any runners on base are able to score."
+  notes="Note: As of Opening Day 2023"
+  source="Source: Baseball Reference"
+/>
+```
+
+### Truncated
+
+```svelte
+<Table data={/* homeRuns */} truncated={true} source="Source: Baseball Reference" />
+```
+
+### Paginated
+
+```svelte
+<Table
+  data={/* pressFreedom */}
+  paginated={true}
+  title="Press Freedom Index"
+  source="Source: Reporters Without Borders"
+/>
+```
+
+### Search bar
+
+```svelte
+<Table
+  data={/* pressFreedom */}
+  searchable={true}
+  paginated={true}
+  searchPlaceholder="Search press freedom data"
+  title="Press Freedom Index"
+  source="Source: Reporters Without Borders"
+/>
+```
+
+### Filter
+
+```svelte
+<Table
+  data={/* pressFreedom */}
+  paginated={true}
+  filterField="Region"
+  filterLabel="regions"
+  title="Press Freedom Index"
+  notes="Source: Reporters Without Borders"
+/>
+```
+
+### Search and filter
+
+```svelte
+<Table
+  data={/* pressFreedom */}
+  searchable={true}
+  paginated={true}
+  filterField="Region"
+  filterLabel="regions"
+  title="Press Freedom Index"
+  dek="Reporters Without Borders ranks countries based on their level of press freedom using criteria such as the degree of media pluralism and violence against journalists."
+  source="Source: Reporters Without Borders"
+/>
+```
+
+### Sort
+
+```svelte
+<Table
+  data={/* pressFreedom */}
+  sortable={true}
+  paginated={true}
+  sortField="Score"
+  sortDirection="descending"
+  title="Press Freedom Index"
+  notes="Note: data as of 2018"
+  source="Source: Reporters Without Borders"
+/>
+```
+
+### Format
+
+```svelte
+<Table
+  data={/* richestWomen */}
+  fieldFormatters={{
+      'Net worth (in billions)': currencyFormat as Formatter<unknown>,
+    }}
+  sortable={true}
+  sortField="Net worth (in billions)"
+  sortDirection="descending"
+  title="The Richest Women in the World"
+  source="Source: Forbes"
+/>
+```
+
+## Documentation
+
+# Table
+
+The `Table` component presents data as a table that you can make searchable, filtereable, sortable, or paginated.
+
+```svelte
+<script>
+  import { Table } from '@reuters-graphics/graphics-components';
+
+  import data from './data.json'; // Import your data
+</script>
+
+<Table {data} />
+```
+
+## Text elements
+
+Set the `title`, `dek`, `notes` and `source` options to add supporting metadata above and below the table.
+
+```svelte
+<Table
+  data={yourData}
+  title="Career home run leaders"
+  dek={`In baseball,
+a home run (also known as a "dinger" or "tater") occurs when a batter hits the
+ball over the outfield fence. When a home run is hit, the batter and any runners
+on base are able to score.`}
+  notes="Note: As of Opening Day 2023"
+  source="Source: Baseball Reference"
+/>
+```
+
+## Truncated
+
+When your table has 10 or more rows, consider clipping it by setting the `truncated` option. When it is enabled, the table is clipped and readers must click a button below the table to see all rows.
+
+By default, this configuration will limit the table to 5 records. Change the cutoff point by adjusting the `truncateLength` option.
+
+This is a good option for simple tables with between 10 and 30 rows. It works best when the table doesn't require interactivity.
+
+```svelte
+<Table data={yourData} truncated={true} source="Source: Baseball Reference" />
+```
+
+## Paginated
+
+When your table has many rows, you should consider breaking it up into pages by setting `paginated` to `true`. When it is enabled, readers can leaf through the data using a set of buttons below the table.
+
+By default, there are 25 records per page. Change the number by adjusting the `pageSize` option.
+
+This is a good option when publishing large tables for readers to explore. It works well with interactive features like searching and filters.
+
+```svelte
+<Table
+  data={yourData}
+  paginated={true}
+  title="Press Freedom Index"
+  source="Reporters Without Borders"
+/>
+```
+
+## Search bar
+
+Allow users to search the table by setting the optional `searchable` option to `true`. Modify the default text that appears in the box by setting `searchPlaceholder` to a different placeholder text.
+
+```svelte
+<Table
+  data={yourData}
+  searchable={true}
+  paginated={true}
+  searchPlaceholder="Search press freedom data"
+  ,
+  title="Press Freedom Index"
+  notes="Source: Reporters Without Borders"
+/>
+```
+
+## Filter
+
+Allow users to filter the table by providing one of the attributes as the `filterField`. This works best with categorical columns.
+
+Set `filterLabel` to make the category name more readable. For example, if the column is `Region`, set `filterLabel` to `regions` or `regions of the world`.
+
+```svelte
+<Table
+  data={yourData}
+  filterField="Region"
+  filterLabel="regions"
+  paginated={true}
+  title="Press Freedom Index"
+  notes="Source: Reporters Without Borders"
+/>
+```
+
+## Search and filter
+
+Feel free to both search and filter.
+
+```svelte
+<Table
+  data={yourData}
+  searchable={true}
+  paginated={true}
+  filterField="Region"
+  filterLabel="regions"
+  title="Press Freedom Index"
+  dek="Reporters Without Borders ranks countries based on their level of press freedom using criteria such as the degree of media pluralism and violence against journalists."
+  source="Source: Reporters Without Borders"
+/>
+```
+
+````
+
+## Sort
+
+Allow users to sort the table by setting `sortable` to `true`. Specify the starting order by setting `sortField` to a column name and `sortDirection` to `ascending` or `descending`.
+
+By default, all fields are sortable. If you'd like to limit the columns where sorting is allowed, provide a list to the `sortableFields` option.
+
+```svelte
+<Table
+  data={yourData}
+  sortable={true}
+  paginated={true}
+  sortField="Score"
+  sortDirection="descending"
+  title="Press Freedom Index"
+  source="Source: Reporters Without Borders"
+/>
+````
+
+## Format
+
+Format column values by supplying functions keyed to field names with the `fieldFormatters` option. Columns are still sorted using the raw, underlying values.
+
+Among other things, this feature can be used to provide a unit of measurement, such as `$` or `%`, with numeric fields.
+
+```svelte
+<script lang="ts">
+  const fieldFormatters = {
+    // The key must match the column name in the data exactly
+    'Net worth (in billions)': (v) => '$' + v.toFixed(1),
+  };
+</script>
+
+<Table
+  data={yourData}
+  {fieldFormatters}
+  sortable={true}
+  sortField="Net worth (in billions)"
+  sortDirection="descending"
+  title="The Richest Women in the World"
+  source="Source: Forbes"
+/>
+```

package/dist/llm-docs/components/Theme.md

@@ -0,0 +1,266 @@
+# Theme
+
+**Category:** Components/Theming/Theme
+
+**Import:** `import { Theme } from '@reuters-graphics/graphics-components'`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|:--------:|-------------|
+| `theme` | `CustomThemeConfig \| ThemeConfig` | `{}` |  | Custom theme object. Can be a partial theme with just what you want to change. |
+| `base` | `Base` | `'light'` |  | Base theme is one of `light` or `dark` and will be merged with your custom theme to fill in any values you don't explicitly set. Options: `light`, `dark` |
+| `children` | `Snippet` | — | ✓ | Content wrapped inside `Theme` |
+
+## Examples
+
+### Demo
+
+```svelte
+<div class="reset-article">
+  <Theme theme={themes.light} base="light">
+    <ThemedPage />
+  </Theme>
+</div>
+```
+
+### Custom theme
+
+```svelte
+<Theme
+  base="dark"
+  theme={{
+    colour: { accent: 'var(--tr-light-orange)' },
+    font: { family: { hed: '"Newsreader Text", serif' } },
+  }}
+>
+  <ThemedPage />
+</Theme>
+```
+
+### Custom font
+
+```svelte
+<Theme
+  base="light"
+  theme={{
+    font: { family: { hed: 'Indie Flower', body: 'Indie Flower' } },
+  }}
+>
+  <div class="gfont">
+    <Headline
+      hed={'Reuters Graphics Interactive'}
+      dek={'The beginning of a beautiful page'}
+      section={'Global news'}
+    />
+    <BodyText
+      text={'Bacon ipsum dolor amet cupim porchetta chuck buffalo sirloin beef. Biltong ham brisket tenderloin hamburger doner.'}
+    />
+  </div>
+</Theme>
+```
+
+### Background patterns
+
+```svelte
+<div id="pattern-bg">
+  <Theme
+    base="dark"
+    theme={{
+      colour: { background: 'transparent' },
+    }}
+  >
+    <SiteHeader />
+    <Headline
+      hed={'Reuters Graphics Interactive'}
+      dek={'The beginning of a beautiful page'}
+      section={'Global news'}
+    />
+    <BodyText
+      text={'Bacon ipsum dolor amet cupim porchetta chuck buffalo sirloin beef. Biltong ham brisket tenderloin hamburger doner.'}
+    />
+  </Theme>
+</div>
+```
+
+### Inheritance
+
+```svelte
+<Theme theme={themes.light}>
+  <div class="themed">
+    <p>Theme</p>
+    <Theme theme={themes.dark}>
+      <div class="themed">
+        <p>Sub-theme</p>
+        <Theme theme={themes.light}>
+          <div class="themed">
+            <p>Sub-sub</p>
+          </div>
+        </Theme>
+        <Theme
+          theme={{
+            colour: { background: 'steelblue', 'text-primary': '#fff' },
+            font: { family: { note: '"Newsreader Text", serif' } },
+          }}
+          base="dark"
+        >
+          <div class="themed">
+            <p>Sub-sub sibling</p>
+          </div>
+        </Theme>
+      </div>
+    </Theme>
+  </div>
+</Theme>
+```
+
+## Documentation
+
+# Theme
+
+The `Theme` component wraps your page content and uses [CSS variables](../?path=/docs/scss-css-variables--page) to set major colour and typography styles for your page. All the components from this library that are added to your page will use the CSS variables set by `Theme`.
+
+Use the [theme builder](?path=/docs/components-theming-theme-builder--docs) to test custom themes.
+
+```svelte
+<script>
+  import { Theme } from '@reuters-graphics/graphics-components';
+</script>
+
+<Theme base="light">
+  <!-- Page content, now styled according to your theme! -->
+</Theme>
+```
+
+> In the graphics kit, the `Theme` is set in both `pages/+page.svelte` and in `App.svelte`.
+
+## Custom theme
+
+You can customise your page's theme in two ways:
+
+- Choose the `base` theme, either `light` or `dark`
+- Pass a custom theme object to the `theme` prop, which will override styles in the `base` theme.
+
+Use the [theme builder](?path=/docs/components-theming-theme-builder--docs) to see what properties you can customise.
+
+```svelte
+<Theme
+  base="dark"
+  theme={{
+    colour: { accent: 'var(--tr-light-orange)' },
+    font: { family: { hed: '"Newsreader Text", serif' } },
+  }}
+>
+  <!-- Page content -->
+</Theme>
+```
+
+> **Note:** The `Theme` component only styles child components or elements, so if you're changing the background colour of your page, make sure to also set the `background-color` on your `body` element in global SCSS.
+>
+> ```scss
+> // global.scss
+> body {
+>   background-color: #2e3440;
+> }
+> ```
+
+## Custom font
+
+To use typefaces other than the defaults provided by the graphics kit, download the font files from services such as [Google Fonts](https://fonts.google.com/) or [Adobe Typekit](https://fonts.adobe.com/). Make a folder called `fonts` inside `statics/` and put the font file -- for example, `IndieFlower-Regular.ttf` downloaded from [Google Fonts](https://fonts.google.com/share?selection.family=Indie+Flower) -- in `statics/fonts/`.
+
+Then, declare it as a `@font-face` in `global.scss`:
+
+```scss
+/* global.scss in the graphics kit */
+@font-face {
+  // If you're unsure of the font-family name,
+  // click on "Get embed code" on the Google font page and check the CSS class.
+  font-family: 'Indie Flower';
+
+  // Path to the font file. Change format depending on the font file type.
+  src: url('/fonts/IndieFlower-Regular.ttf') format('truetype');
+  font-weight: normal; // Optional
+  font-style: normal; // Optional
+}
+```
+
+Finally, pass the font to the appropriate text type in `Theme`:
+
+```svelte
+<Theme
+  base="light"
+  theme={{
+    font: {
+      family: {
+        hed: 'IndieFlower', // Set header text font to `IndieFlower`
+        body: 'IndieFlower', // Set body text font to `IndieFlower`
+        // etc...
+      },
+    },
+  }}
+>
+  <!-- Page content -->
+</Theme>
+```
+
+## Background patterns
+
+To use a background pattern or image, set the background colour property in `Theme` to `transparent`:
+
+```svelte
+<Theme
+  base="dark"
+  theme={{
+    colour: { background: 'transparent' },
+  }}
+>
+  <!-- Page content -->
+</Theme>
+```
+
+Then in `global.scss`, set your image, which should be stored in `statics/images/`, as `background-image`:
+
+```scss
+/* global.scss */
+body {
+  background-image: url('/images/my-pattern.png');
+}
+```
+
+You may also want to override the background on the header nav if it conflicts with your background, especially the dropdown menu:
+
+```scss
+/* global.scss
+Main nav container */
+.nav-container .inner {
+  background: darkblue !important;
+  /* Dropdown menu */
+  .dropdown {
+    background: darkblue !important;
+  }
+}
+/* Mobile nav overlay */
+header + .overlay {
+  background: darkblue !important;
+}
+```
+
+## Inheritance
+
+Styles that use `Theme`'s CSS variables will always use those set by the nearest parent `Theme`. That lets you change the theme for parts of your page by simply wrapping that bit in a new `Theme` with different styles.
+
+The demo below shows a more complex example of nesting themes, but more likely you'll so something like this:
+
+```svelte
+<script>
+  import { Theme } from '@reuters-graphics/graphics-components';
+</script>
+
+<Theme>
+  <!-- Page content styled with the default light theme. -->
+  <Theme theme={{ colour: { background: 'lightgrey' } }}>
+    <!-- A darker background for this section. -->
+  </Theme>
+  <!-- Back to normal here... -->
+</Theme>
+```