diff --git a/site/pages/components/byline.mdx b/site/pages/components/byline.mdx deleted file mode 100644 index f4acde1b6e..0000000000 --- a/site/pages/components/byline.mdx +++ /dev/null @@ -1,195 +0,0 @@ -import Layout from '../../components/layout'; -import Playground from '../../components/playground'; -import {Prop} from '../../components/prop'; -import {TextBoxSwatch} from '../../components/theming-values/colors'; -import {LegacyBlock} from '../../components/legacy-block'; -import { - CodeFromDefaultPresets, - Code, -} from '../../components/code'; -import {CommonLogicalPropsMDX} from '../../components/component-api/common-logical-props'; - - -import {Byline} from 'newskit'; - -export default Layout; - -# Byline - -## Overview - -The byline is a small line of text which lists the authors of an article, along with their titles if provided. - -### Usage - -The `Byline` component requires an array of bylineData. Each bylineData object in the array must contain an author. You can optionally provide a `href` property to link to that author's page and a title for that author. - -### Theming - -The byline uses a typography preset `meta02` and inherits its font color from its parent, apart from author links which use the default Link theme color tokens. - -## Props - - - - An array of byline data to populate the byline authors. Byline data objects - must contain an author string, and can contain optional href and title - strings. - - {` -interface BylineData { - author: string; - href?: string; - title?: string; - location?: string; - ariaLabel?: string; -} - `} - - - - If provided, overrides the respective presets for the component and provided - elements. - - If provided, this overrides the style preset of the component. - - - If provided, this overrides the typography preset of the component. - - - If provided, this overrides the vertical space between each line when the - bylines items wrap onto a new line. - - - - If provided, this overrides the style preset applied to the passed link. - - - If provided, this overrides the typography preset applied to the passed - link. - - - - - If provided, this overrides the style preset applied to the divider. - - - If provided, this overrides the horizontal space between the divider and - the text. - - - - Refer to the defaults below for the full object structure: - - - - -## Playground - - - -For more information on overriding component defaults, see the docs here. diff --git a/site/pages/components/byline.tsx b/site/pages/components/byline.tsx new file mode 100644 index 0000000000..576ea58b4d --- /dev/null +++ b/site/pages/components/byline.tsx @@ -0,0 +1,336 @@ +import React from 'react'; +import {styled, Byline} from 'newskit'; +import {BylineProps} from '../../../src/byline/types'; +import {InlineCode} from '../../components/markdown-elements'; +import {MetaStatus} from '../../components/meta/types'; +import {LayoutProps} from '../../components/layout'; +import {ComponentPageTemplate} from '../../templates/component-page-template/component-page-template'; +import {getIllustrationComponent} from '../../components/illustrations/illustration-loader'; +import {OverridesRowsProps} from '../../components/component-api'; +import {commonLogicalProps} from '../../components/component-api/common-logical-props'; + +const PlaygroundContainer = styled.div` + display: flex; + width: 100%; + height: 200px; + align-items: center; + justify-content: center; +`; + +const BYLINE_DATA = [ + { + author: 'Alex Lowe', + href: 'https://www.thetimes.co.uk/profile/alex-lowe', + title: 'Deputy Rugby Correspondent', + }, + { + author: 'Tom Knowles', + href: 'https://www.thetimes.co.uk/profile/tom-knowles', + title: 'West Coast Technology Reporter', + location: 'London', + }, + { + author: 'David Aaronovitch', + href: 'https://www.thetimes.co.uk/profile/david-aaronovitch', + title: 'Columnist', + }, +]; + +const DividerComponent = (layoutProps: LayoutProps) => ( + ( + + + + )) as React.ComponentType, + knobs: [ + { + name: 'Byline Data', + propName: 'bylineData', + value: BYLINE_DATA, + }, + { + name: 'Typography Preset Overrides', + propName: 'overrides', + options: [ + { + label: 'Default', + value: { + typographyPreset: 'utilityMeta020', + link: { + typographyPreset: 'utilityMeta020', + }, + }, + isDefault: true, + }, + { + label: 'utilityButton020', + value: { + typographyPreset: 'utilityButton020', + link: { + typographyPreset: 'utilityButton020', + }, + }, + }, + ], + }, + { + name: 'Style Preset Overrides', + propName: 'overrides', + options: [ + { + label: 'Default', + value: { + stylePreset: 'inkBase', + }, + isDefault: true, + }, + { + label: 'inkPositive', + value: { + stylePreset: 'inkPositive', + }, + }, + { + label: 'inkNegative', + value: { + stylePreset: 'inkNegative', + }, + }, + ], + }, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + ] as any, + }, + }} + anatomy={{ + introduction: + 'The byline contains one required element and one optional element.', + rows: [ + { + name: 'Byline', + description: + 'The author’s name. Option to provide the author’s title and location, and pass an href property to link from the author’s name.', + component: 'Text Block', + optional: undefined, + }, + { + name: 'Divider', + description: 'Vertical divider that visually separates each author', + component: 'Divider', + optional: true, + }, + ], + media: getIllustrationComponent('components/byline/anatomy/anatomy'), + }} + options={{ + introduction: 'The byline has options for different use cases:', + cards: [ + { + title: 'Author’s title', + description: + 'Option to add the author’s title, following their name.', + media: getIllustrationComponent( + 'components/byline/options/job-title', + ), + }, + { + title: 'Author’s location', + description: + 'Option to add the author’s location, following their name and title.', + media: getIllustrationComponent('components/byline/options/location'), + }, + { + title: 'Divider', + description: + 'A vertical divider between each author allows visual separation.', + media: getIllustrationComponent('components/byline/options/divider'), + }, + { + title: 'Link', + description: ( + <> + If supplied, adds a link to the author’s name. This typically goes + to the author’s page. +
+
+ If the link is external, the external link trailing icon is shown. + + ), + media: getIllustrationComponent('components/byline/options/link'), + }, + ], + }} + behaviors={{ + introduction: 'The following guidance describes how the byline behaves.', + cards: [ + { + title: 'Breaks responsively', + description: + 'When viewed responsively, the byline breaks onto a new line for each author.', + media: getIllustrationComponent( + 'components/byline/behaviours/responsive', + ), + }, + ], + }} + accessibility={{ + introduction: + 'The byline has the following accessibility considerations:', + focusOrder: { + title: 'Focus order', + tableRows: [ + { + order: 1, + element: 'Byline', + role: 'Focusses to the first link, if a link is supplied', + }, + ], + }, + interaction: { + title: 'Keyboard Interactions', + tableRows: [ + { + command: ['Tab'], + description: + 'When focus is outside of the byline, moves focus to the first author link. If focus is on an active author link, moves focus to the next author link, or the next element in the keyboard focus.', + }, + ], + }, + aria: { + title: 'WAI-ARIA', + tableRows: [ + { + element: 'Byline', + attribute: 'ariaLabel', + value: '', + description: + 'The author’s name does not describe where the link is taking the user. Adding an ariaLabel can provide more context.', + userSupplied: true, + }, + ], + }, + }} + componentAPI={{ + introduction: + 'The byline has a range of props that can be used to define an appropriate experience for different use cases.', + components: [ + { + title: 'Byline', + propsRows: [ + { + name: 'bylineData', + type: 'BylineData[]', + required: true, + description: ( + <> + An array of data to populate the byline authors. Byline data + objects must contain an author string, and can contain + optional href, title and location strings. An optional + ariaLabel can provide more context to the link destination. +
+
+ + BylineData {
+  author: string;
+  href?: string; +
+  title?: string;
+  location?: string;
+  ariaLabel?: string;
+  key?: string | number; +
+ } + + + ), + }, + ], + overridesRows: [ + { + attribute: 'stylePreset', + type: 'MQ', + default: 'inkSubtle', + description: + 'If provided, this overrides the style preset of the component', + }, + { + attribute: 'typographyPreset', + type: 'MQ', + default: 'utilityMeta020', + description: + 'If provided, this overrides the typography preset of the component', + }, + { + attribute: 'spaceStack (deprecated)', + type: 'MQ', + default: 'space020', + description: + 'If provided, this overrides the vertical space between each line when the bylines items wrap onto a new line', + }, + { + attribute: 'link.stylePreset', + type: 'MQ', + default: 'linkInline', + description: + 'If provided, this overrides the style preset applied to the passed link', + }, + { + attribute: 'link.typographyPreset', + type: 'MQ', + default: 'utilityMeta020', + description: + 'If provided, this overrides the typography preset applied to the passed link', + }, + { + attribute: 'divider.stylePreset', + type: 'MQ', + default: 'inkNonEssential', + description: + 'If provided, this overrides the style preset applied to the divider', + }, + { + attribute: 'divider.spaceInline (deprecated)', + type: 'MQ', + default: 'space020', + description: + 'If provided, this overrides the horizontal space between the divider and the text', + }, + ...(commonLogicalProps() as OverridesRowsProps[]), + ], + }, + ], + }} + related={{ + related: ['Text Block'], + }} + /> +); + +export default DividerComponent; diff --git a/site/public/static/illustrations/components/byline/anatomy/anatomy.svg b/site/public/static/illustrations/components/byline/anatomy/anatomy.svg new file mode 100644 index 0000000000..2e640c03bc --- /dev/null +++ b/site/public/static/illustrations/components/byline/anatomy/anatomy.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/site/public/static/illustrations/components/byline/behaviours/responsive.svg b/site/public/static/illustrations/components/byline/behaviours/responsive.svg new file mode 100644 index 0000000000..ca656125db --- /dev/null +++ b/site/public/static/illustrations/components/byline/behaviours/responsive.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/site/public/static/illustrations/components/byline/options/divider.svg b/site/public/static/illustrations/components/byline/options/divider.svg new file mode 100644 index 0000000000..82ad9788fc --- /dev/null +++ b/site/public/static/illustrations/components/byline/options/divider.svg @@ -0,0 +1,47 @@ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/site/public/static/illustrations/components/byline/options/job-title.svg b/site/public/static/illustrations/components/byline/options/job-title.svg new file mode 100644 index 0000000000..c60bfba78d --- /dev/null +++ b/site/public/static/illustrations/components/byline/options/job-title.svg @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/site/public/static/illustrations/components/byline/options/link.svg b/site/public/static/illustrations/components/byline/options/link.svg new file mode 100644 index 0000000000..4467ea30ff --- /dev/null +++ b/site/public/static/illustrations/components/byline/options/link.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/site/public/static/illustrations/components/byline/options/location.svg b/site/public/static/illustrations/components/byline/options/location.svg new file mode 100644 index 0000000000..6df320c3aa --- /dev/null +++ b/site/public/static/illustrations/components/byline/options/location.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file