@reuters-graphics/graphics-components 2.0.2 → 3.0.0

package/dist/components/Table/{Pagination.svelte → components/Pagination.svelte}

@@ -1,27 +1,53 @@
-<script>import { intcomma } from "journalize";
-import LeftArrow from "./LeftArrow.svelte";
-import RightArrow from "./RightArrow.svelte";
-export let pageNumber = 1;
-export let pageSize = 25;
-export let pageLength = null;
-export let n = null;
-$: minRow = pageNumber * pageSize - pageSize + 1;
-$: maxRow = pageNumber * pageSize - pageSize + pageLength;
-$: numPages = Math.ceil(n / pageSize);
-function goToPreviousPage() {
-  if (pageNumber > 1) {
-    pageNumber -= 1;
+<script lang="ts">
+  import { intcomma } from 'journalize';
+  import LeftArrow from './LeftArrow.svelte';
+  import RightArrow from './RightArrow.svelte';
+
+  interface Props {
+    /**
+     * The current page number.
+     */
+    pageNumber?: number;
+    /**
+     * The default page size.
+     */
+    pageSize?: number;
+    /**
+     * The number of records in the current page.
+     */
+    pageLength?: number;
+    /**
+     * The total number of records in the data set.
+     */
+    n?: number;
   }
-}
-function goToNextPage() {
-  if (pageNumber < numPages) {
-    pageNumber += 1;
+
+  let {
+    pageNumber = $bindable(1),
+    pageSize = $bindable(25),
+    pageLength = 1,
+    n = 1,
+  }: Props = $props();
+
+  let minRow = $derived(pageNumber * pageSize - pageSize + 1);
+  let maxRow = $derived(pageNumber * pageSize - pageSize + pageLength);
+  let numPages = $derived(Math.ceil(n / pageSize));
+
+  function goToPreviousPage() {
+    if (pageNumber > 1) {
+      pageNumber -= 1;
+    }
+  }
+
+  function goToNextPage() {
+    if (pageNumber < numPages) {
+      pageNumber += 1;
+    }
   }
-}
 </script>
 
 <nav aria-label="pagination" class="pagination fmt-4">
-  <button on:click="{goToPreviousPage}" disabled="{pageNumber === 1}"
+  <button onclick={goToPreviousPage} disabled={pageNumber === 1}
     ><div class="icon-wrapper">
       <LeftArrow />
       <span class="visually-hidden">Previous page</span>
@@ -33,8 +59,8 @@ function goToNextPage() {
     </div>
   </div>
   <button
-    on:click="{goToNextPage}"
-    disabled="{pageNumber === Math.ceil(n / pageSize)}"
+    onclick={goToNextPage}
+    disabled={pageNumber === Math.ceil(n / pageSize)}
     ><div class="icon-wrapper">
       <RightArrow />
       <span class="visually-hidden">Next page</span>
@@ -89,6 +115,7 @@ nav.pagination .label {
   width: auto;
   min-width: 5rem;
 }
+
 .visually-hidden {
   clip: rect(0 0 0 0);
   clip-path: inset(50%);

package/dist/components/Table/components/Pagination.svelte.d.ts

@@ -0,0 +1,21 @@
+interface Props {
+    /**
+     * The current page number.
+     */
+    pageNumber?: number;
+    /**
+     * The default page size.
+     */
+    pageSize?: number;
+    /**
+     * The number of records in the current page.
+     */
+    pageLength?: number;
+    /**
+     * The total number of records in the data set.
+     */
+    n?: number;
+}
+declare const Pagination: import("svelte").Component<Props, {}, "pageNumber" | "pageSize">;
+type Pagination = ReturnType<typeof Pagination>;
+export default Pagination;

package/dist/components/Table/components/RightArrow.svelte.d.ts

@@ -0,0 +1,26 @@
+export default RightArrow;
+type RightArrow = SvelteComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}> & {
+    $$bindings?: string | undefined;
+};
+declare const RightArrow: $$__sveltets_2_IsomorphicComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}

package/dist/components/Table/{Select.svelte → components/Select.svelte}

@@ -1,25 +1,37 @@
-<script>import { createEventDispatcher } from "svelte";
-export let label = "";
-export let options = [];
-const dispatch = createEventDispatcher();
-function input(event) {
-  const value = event.target.value;
-  dispatch("select", { value });
-}
+<script lang="ts">
+  import type { Option } from '../../@types/global';
+
+  interface Props {
+    /**
+     * The label that appears above the select input.
+     */
+    label?: string;
+    /**
+     * The label that appears above the select input.
+     */
+    options?: Option[];
+    /** Optional function that runs when the selected value changes. */
+    onselect?: (newValue: string) => void;
+  }
+
+  let { label = '', options = [], onselect }: Props = $props();
+
+  function input(event: Event) {
+    const value = (event.target as HTMLInputElement).value;
+
+    if (onselect) onselect(value); // Call the prop to update the parent when selected
+  }
 </script>
 
 <div class="select">
-  {#if label}
-    <label class="body-caption block" for="select--input">{label}</label>
-  {/if}
   <select
     class="select--input body-caption fpx-2"
     name="select--input"
     id="select--input"
-    on:input="{input}"
+    oninput={input}
   >
     {#each options as obj}
-      <option value="{obj.value}">{obj.text}</option>
+      <option value={obj.value}>{obj.text} {label.toLowerCase()}</option>
     {/each}
   </select>
 </div>

package/dist/components/Table/components/Select.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Option } from '../../@types/global';
+interface Props {
+    /**
+     * The label that appears above the select input.
+     */
+    label?: string;
+    /**
+     * The label that appears above the select input.
+     */
+    options?: Option[];
+    /** Optional function that runs when the selected value changes. */
+    onselect?: (newValue: string) => void;
+}
+declare const Select: import("svelte").Component<Props, {}, "">;
+type Select = ReturnType<typeof Select>;
+export default Select;

package/dist/components/Table/{SortArrow.svelte → components/SortArrow.svelte}

@@ -1,5 +1,20 @@
-<script>export let sortDirection = "ascending";
-export let active = false;
+<script lang="ts">
+  /**
+   * The direction of the sort. By default it's ascending.
+   * @type {SortDirection}
+   */
+  type SortDirection = 'ascending' | 'descending';
+
+  interface Props {
+    sortDirection?: SortDirection;
+    /**
+     * Whether or not this arrow is currently sorting. It is false by default.
+     * @type {boolean}
+     */
+    active?: boolean;
+  }
+
+  let { sortDirection = 'ascending', active = false }: Props = $props();
 </script>
 
 <svg
@@ -11,11 +26,11 @@ export let active = false;
   class="avoid-clicks"
 >
   <path
-    class:active="{sortDirection === 'descending' && active}"
+    class:active={sortDirection === 'descending' && active}
     d="M6.76474 20.2244L0.236082 13.4649C-0.0786943 13.139 -0.0786943 12.6104 0.236082 12.2845C0.550521 11.959 1.19794 11.96 1.51305 12.2845L7.33483 12.2845L13 12.2845C13.43 11.8545 14.1195 11.9593 14.4339 12.2849C14.7487 12.6107 14.7487 13.1394 14.4339 13.4653L7.90492 20.2244C7.59015 20.5503 7.07952 20.5503 6.76474 20.2244Z"
   ></path>
   <path
-    class:active="{sortDirection === 'ascending' && active}"
+    class:active={sortDirection === 'ascending' && active}
     d="M7.90518 0.244414L14.4338 7.00385C14.7486 7.32973 14.7486 7.85838 14.4338 8.18427C14.1194 8.50981 13.472 8.50876 13.1569 8.18427L7.33509 8.18427L1.66992 8.18427C1.23992 8.61427 0.550443 8.50946 0.236003 8.18392C-0.0787725 7.85803 -0.0787725 7.32938 0.236003 7.0035L6.765 0.244414C7.07978 -0.0814713 7.5904 -0.0814713 7.90518 0.244414Z"
   ></path>
 </svg>

package/dist/components/Table/components/SortArrow.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The direction of the sort. By default it's ascending.
+ * @type {SortDirection}
+ */
+type SortDirection = 'ascending' | 'descending';
+interface Props {
+    sortDirection?: SortDirection;
+    /**
+     * Whether or not this arrow is currently sorting. It is false by default.
+     * @type {boolean}
+     */
+    active?: boolean;
+}
+declare const SortArrow: import("svelte").Component<Props, {}, "">;
+type SortArrow = ReturnType<typeof SortArrow>;
+export default SortArrow;

package/dist/components/Table/utils.d.ts

@@ -1,3 +1,39 @@
-export function filterArray(data: any, searchText: any, filterField: any, filterValue: any): any;
-export function paginateArray(array: any, pageSize: any, pageNumber: any): any;
-export function getOptions(data: any, attr: any): any;
+type FilterableDatum<T extends Record<string, unknown>> = T & {
+    searchStr: string;
+};
+export declare function filterArray<T extends Record<string, unknown>>(data: FilterableDatum<T>[], searchText: string, filterField: keyof FilterableDatum<T>, filterValue: FilterableDatum<T>[keyof FilterableDatum<T>]): FilterableDatum<T>[];
+export declare function paginateArray<T>(array: T[], pageSize: number, pageNumber: number): T[];
+export declare function getOptions<T>(data: T[], attr: keyof T): {
+    text: string | T[keyof T];
+    value: string | T[keyof T];
+}[];
+interface SortableItem {
+    [key: string]: unknown;
+}
+/**
+ * Sorts an array of objects based on a specified column and direction.
+ */
+export declare function sortArray<T extends SortableItem>(
+/** The array to sort. */
+array: T[], 
+/** The column to sort by. */
+column: keyof T, 
+/** The sorting direction ('ascending' or 'descending'). */
+direction: 'ascending' | 'descending', 
+/** Whether or not sorting is turned on */
+sortable: boolean): T[];
+export type Formatter<T> = (value: T) => string;
+export type FieldFormatters<T> = {
+    [K in keyof T]?: Formatter<T[K]>;
+};
+/**
+ * Formats a value based on a field and a dictionary of formatters.
+ */
+export declare function formatValue<T extends Record<string, unknown>>(
+/** The object containing the field. */
+item: FilterableDatum<T>, 
+/** The field to format. */
+field: keyof T, 
+/** An optional dictionary of formatters. */
+fieldFormatters?: FieldFormatters<T>): string | FilterableDatum<T>[keyof T];
+export {};

package/dist/components/Table/utils.js

@@ -1,36 +1,90 @@
 export function filterArray(data, searchText, filterField, filterValue) {
-  if (searchText) {
-    data = data.filter((item) => {
-      return item.searchStr.includes(searchText.toLowerCase());
-    });
-  }
-  if (filterValue && filterValue) {
-    data = data.filter((item) => {
-      return item[filterField] === filterValue;
-    });
-  }
-  return data;
+    if (searchText) {
+        data = data.filter((item) => {
+            return item.searchStr.includes(searchText.toLowerCase());
+        });
+    }
+    if (filterValue) {
+        data = data.filter((item) => {
+            if (!filterField)
+                return true; // or handle the undefined case as appropriate
+            return item[filterField] === filterValue;
+        });
+    }
+    return data;
 }
-
 export function paginateArray(array, pageSize, pageNumber) {
-  return array.slice((pageNumber - 1) * pageSize, pageNumber * pageSize);
+    return array.slice((pageNumber - 1) * pageSize, pageNumber * pageSize);
 }
-
+/**
+ *  We specify the output type here by adding `string` to the union because we want to explicitly define the output array as accepting strings.
+ *
+ * This is to get rid of the type error from `attrList.unshift('All')`
+ */
 function uniqueAttr(array, attr) {
-  return array.map((e) => e[attr]).filter(unique);
+    return array.map((e) => e[attr]).filter(unique);
 }
-
 function unique(value, index, array) {
-  return array.indexOf(value) === index;
+    return array.indexOf(value) === index;
 }
-
 export function getOptions(data, attr) {
-  // Get all the unique values in the provided field. Sort it.
-  const attrList = uniqueAttr(data, attr).sort((a, b) => a.localeCompare(b));
-
-  // Tack 'All' as the front as the first option.
-  attrList.unshift('All');
-
-  // Convert the list into Option typed objects ready for our Select component
-  return attrList.map((a) => ({ text: a, value: a }));
+    // Get all the unique values in the provided field. Sort it.
+    const attrList = uniqueAttr(data, attr).sort((a, b) => {
+        // Throw errors if a and b are not strings.
+        // a and b should be strings since they are keys of T.
+        if (typeof a !== 'string' || typeof b !== 'string') {
+            throw new Error(`Expected string, got ${typeof a} and ${typeof b}`);
+        }
+        return a.localeCompare(b);
+    });
+    // Tack 'All' at the start of `attrList`, making it the first option.
+    attrList.unshift('All');
+    // Convert the list into Option typed objects ready for our Select component
+    return attrList.map((a) => ({ text: a, value: a }));
+}
+/**
+ * Sorts an array of objects based on a specified column and direction.
+ */
+export function sortArray(
+/** The array to sort. */
+array, 
+/** The column to sort by. */
+column, 
+/** The sorting direction ('ascending' or 'descending'). */
+direction, 
+/** Whether or not sorting is turned on */
+sortable) {
+    if (!sortable)
+        return array;
+    const sorted = [...array].sort((a, b) => {
+        if (a[column] < b[column]) {
+            return direction === 'ascending' ? -1 : 1;
+        }
+        else if (a[column] > b[column]) {
+            return direction === 'ascending' ? 1 : -1;
+        }
+        else {
+            return 0;
+        }
+    });
+    return sorted;
+}
+/**
+ * Formats a value based on a field and a dictionary of formatters.
+ */
+export function formatValue(
+/** The object containing the field. */
+item, 
+/** The field to format. */
+field, 
+/** An optional dictionary of formatters. */
+fieldFormatters) {
+    const value = item[field];
+    if (fieldFormatters && field in fieldFormatters && fieldFormatters[field]) {
+        const formatter = fieldFormatters[field];
+        return formatter(value);
+    }
+    else {
+        return value;
+    }
 }

package/dist/components/Theme/@types/component.d.ts

@@ -1,4 +1,4 @@
-interface Colour {
+export interface Colour {
     background: string;
     'text-primary': string;
     'text-secondary': string;
@@ -7,7 +7,7 @@ interface Colour {
     'brand-rules': string;
     'brand-shadow': string;
 }
-interface FontFamily {
+export interface FontFamily {
     serif: string;
     'sans-serif': string;
     monospace: string;
@@ -16,7 +16,7 @@ interface FontFamily {
     body: string;
     note: string;
 }
-interface FontSize {
+export interface FontSize {
     xxs: string;
     xs: string;
     sm: string;
@@ -29,11 +29,11 @@ interface FontSize {
     '5xl': string;
     '6xl': string;
 }
-interface Font {
+export interface Font {
     family: FontFamily;
     size: FontSize;
 }
-interface CustomFont {
+export interface CustomFont {
     family?: Partial<FontFamily>;
     size?: Partial<FontSize>;
 }
@@ -45,4 +45,3 @@ export interface CustomTheme {
     colour?: Partial<Colour>;
     font?: Partial<CustomFont>;
 }
-export {};

package/dist/components/Theme/Theme.mdx

@@ -0,0 +1,164 @@
+import { Meta, Canvas } from '@storybook/blocks';
+
+import * as ThemeStories from './Theme.stories.svelte';
+
+<Meta of={ThemeStories} />
+
+# 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`.
+
+<Canvas of={ThemeStories.Demo} />
+
+## 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: 'FreightText, 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;
+> }
+> ```
+
+<Canvas of={ThemeStories.CustomTheme} />
+
+## 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>
+```
+
+<Canvas of={ThemeStories.CustomFont} />
+
+## 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;
+}
+```
+
+<Canvas of={ThemeStories.BackgroundPatterns} />
+
+## 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>
+```
+
+<Canvas of={ThemeStories.Inheritance} />