diff --git a/.changeset/neat-lies-relax.md b/.changeset/neat-lies-relax.md new file mode 100644 index 0000000000..86c5c54db3 --- /dev/null +++ b/.changeset/neat-lies-relax.md @@ -0,0 +1,5 @@ +--- +"pie-docs": minor +--- + +[Changed] - Updates Engineering copy and adds new Web Components index guide to current documentation in Github Wiki. diff --git a/apps/pie-docs/README.md b/apps/pie-docs/README.md index 334b5402ec..cf947baac4 100644 --- a/apps/pie-docs/README.md +++ b/apps/pie-docs/README.md @@ -59,16 +59,23 @@ Our primary concerns are: 4. Our shortcodes return the expected HTML ### Page testing + We have route navigation tests that ensure all existing pages can be correctly navigated to. When you add new pages, these tests will fail as there are new unexpected pages (this is by design). -In order to fix the tests, you will need to register the routes to your newly added pages by running from the root of the monorepo: `yarn test:generate-routes`. This will update the JSON file named `expected-routes.snapshot.json` with the URLs to your new page. +Route tests need a production build so that they do not fail with `draft` page routes. For this, we recommend to: +1. Stop any local instance of the doc site +2. Delete your `dist` folder +3. Create a production build with `yarn build --filter=pie-docs` +Once this is done, you can run the route tests with `yarn test --filter=pie-docs`. From here, we run navigation, accessibility and visual tests against each route. -#### Running the route tests -Route tests are ran as part of `yarn test`. +#### Adding new routes + +In order to fix the tests, you will need to register the routes to your newly added pages by running the following command from the root of the monorepo: `yarn test:generate-routes`. This will update the JSON file named `expected-routes.snapshot.json` with the paths to your new pages. + +### Testing navigation responses -#### Testing navigation responses Running `yarn test:browsers` will ensure that navigating to the routes stored in `expected-routes.snapshot.json` result in Status Code `200` responses. In order to run this command you will need the site to be served to localhost by running `yarn dev --filter=pie-docs` in another terminal. diff --git a/apps/pie-docs/src/_11ty/shortcodes/index.js b/apps/pie-docs/src/_11ty/shortcodes/index.js index 5f68ddbfbd..63f19b8a47 100644 --- a/apps/pie-docs/src/_11ty/shortcodes/index.js +++ b/apps/pie-docs/src/_11ty/shortcodes/index.js @@ -11,6 +11,7 @@ const mediaElement = require('./mediaElementList'); const notification = require('./notification'); const resourceTable = require('./resourceTable'); const simpleTable = require('./simpleTable'); +const tag = require('./tag'); const termsAndDescriptions = require('./termsAndDescriptions'); const tokensTable = require('./tokensTable'); const usage = require('./usage'); @@ -36,8 +37,9 @@ const addAllShortCodes = (eleventyConfig) => { eleventyConfig.addShortcode('notification', (shortcodeArgs) => deindentHTML(notification(shortcodeArgs))); eleventyConfig.addShortcode('resourceTable', (shortcodeArgs) => deindentHTML(resourceTable(shortcodeArgs))); eleventyConfig.addShortcode('simpleTable', (shortcodeArgs) => deindentHTML(simpleTable(shortcodeArgs))); - eleventyConfig.addShortcode('tokensTable', (shortcodeArgs) => deindentHTML(tokensTable(shortcodeArgs))); + eleventyConfig.addShortcode('tag', (shortcodeArgs) => deindentHTML(tag(shortcodeArgs))); eleventyConfig.addShortcode('termsAndDescriptions', (shortcodeArgs) => deindentHTML(termsAndDescriptions(shortcodeArgs))); + eleventyConfig.addShortcode('tokensTable', (shortcodeArgs) => deindentHTML(tokensTable(shortcodeArgs))); eleventyConfig.addShortcode('usage', (shortcodeArgs) => deindentHTML(usage(shortcodeArgs))); }; diff --git a/apps/pie-docs/src/_11ty/shortcodes/tag.js b/apps/pie-docs/src/_11ty/shortcodes/tag.js new file mode 100644 index 0000000000..52f11c96a0 --- /dev/null +++ b/apps/pie-docs/src/_11ty/shortcodes/tag.js @@ -0,0 +1,13 @@ +// @TODO DSW-2258: be replaced once web components are integrated +/** + * Generate an HTML tag component. It duplicates pie tag variants. + * Can be replaced by pie tag when we include pie web components + * @param {string} label - string that renders within the tag + * @param {string} variant - variant name: neutral, blue, green, + * yellow, red, brand, neutral-alternative, outline, ghost + * @returns {string} + */ +module.exports = ({ + label, + variant, +}) => `${label}`; diff --git a/apps/pie-docs/src/assets/styles/_dependencies.scss b/apps/pie-docs/src/assets/styles/_dependencies.scss index 2552387813..248642e5ad 100644 --- a/apps/pie-docs/src/assets/styles/_dependencies.scss +++ b/apps/pie-docs/src/assets/styles/_dependencies.scss @@ -59,6 +59,7 @@ @use 'components/simpleTable'; @use 'components/table'; @use 'components/tabs'; +@use 'components/tag'; @use 'components/termsAndDescriptions'; @use 'components/toggle'; @use 'components/tokensTable'; diff --git a/apps/pie-docs/src/assets/styles/components/_tag.scss b/apps/pie-docs/src/assets/styles/components/_tag.scss new file mode 100644 index 0000000000..2ddebad3a0 --- /dev/null +++ b/apps/pie-docs/src/assets/styles/components/_tag.scss @@ -0,0 +1,85 @@ +@use '@justeattakeaway/pie-css/scss/settings' as *; +@use '@justeattakeaway/pie-css/scss' as p; + +.c-tag { + --tag-bg-color: var(--dt-color-container-strong); + --tag-color: var(--dt-color-content-default); + --tag-border-radius: var(--dt-radius-rounded-b); + --tag-padding-block: 2px; + --tag-padding-inline: var(--dt-spacing-b); + --tag-font-family: var(--dt-font-body-s-family); + --tag-font-weight: var(--dt-font-body-s-weight); + --tag-font-size: #{p.font-size(--dt-font-body-s-size)}; + --tag-line-height: #{p.line-height(--dt-font-body-s-line-height)}; + + // transparent to variable to function properly in component tests + --tag-transparent-bg-color: transparent; + + // Pie Webc Icon var that is used to ensure the correctly sized icon passed in a slot + --icon-display-override: block; + --icon-size-override: 16px; + + display: inline-flex; + vertical-align: middle; + align-items: center; + justify-content: center; + gap: var(--dt-spacing-a); + padding: var(--tag-padding-block) var(--tag-padding-inline); + border-radius: var(--tag-border-radius); + background-color: var(--tag-bg-color); + color: var(--tag-color); + font-family: var(--tag-font-family); + font-weight: var(--tag-font-weight); + font-size: var(--tag-font-size); + line-height: var(--tag-line-height); + + + &[variant='neutral'] { + // same as default styles + } + + &[variant='blue'] { + --tag-bg-color: var(--dt-color-support-info-02); + --tag-color: var(--dt-color-content-default); + } + + &[variant='green'] { + --tag-bg-color: var(--dt-color-support-positive-02); + --tag-color: var(--dt-color-content-default); + } + + &[variant='yellow'] { + --tag-bg-color: var(--dt-color-support-warning-02); + --tag-color: var(--dt-color-content-default); + } + + &[variant='red'] { + --tag-bg-color: var(--dt-color-support-error-02); + --tag-color: var(--dt-color-content-default); + } + + &[variant='brand'] { + --tag-bg-color: var(--dt-color-support-brand-02); + --tag-color: var(--dt-color-content-default); + } + + &[variant='neutral-alternative'] { + --tag-bg-color: var(--dt-color-container-default); + --tag-color: var(--dt-color-content-default); + } + + &[variant='outline'] { + --tag-bg-color: var(--tag-transparent-bg-color); + --tag-color: var(--dt-color-content-default); + + // the outline in design specs is part of the total component + // height calculation, thus, we use box-shadow to mimic borders + // and avoid the extra 2px from "border: 1px solid" as shadows are applied "internally" + box-shadow: 0 0 0 1px var(--dt-color-border-strong); + } + + &[variant='ghost'] { + --tag-bg-color: var(--tag-transparent-bg-color); + --tag-color: var(--dt-color-content-default); + } +} diff --git a/apps/pie-docs/src/engineers/getting-started/overview.md b/apps/pie-docs/src/engineers/getting-started/overview.md index bfa0e88664..77c18c007f 100644 --- a/apps/pie-docs/src/engineers/getting-started/overview.md +++ b/apps/pie-docs/src/engineers/getting-started/overview.md @@ -10,17 +10,11 @@ permalink: engineers/getting-started/ One of the core aims of the **PIE Design System** is to provide engineers with a consistent set of components and best practices for creating and maintaining UIs across JET. -If you're just starting out with PIE, here's a list of recommended resources to get you started. - ---- - -## Code and Project Structure - -All of our PIE components, tools and documentation (including this site) are maintained on the open-source [PIE Monorepo on Github](https://github.com/justeattakeaway/pie). +We develop and maintain several component libraries that implement the PIE design language. Please follow [this guide](/engineers/getting-started/structure/#which-library-should-i-use) to find out which library to use based on your tech stack. For a more detailed look at the **component systems** the PIE team maintain, the PIE monorepo and how it’s structured, see the [structure section of our engineering docs](/engineers/getting-started/structure). -We also help to maintain a number of other projects that incorporate the PIE Design Language (such as [Fozzie](https://github.com/justeattakeaway/fozzie-components) for **VueJS components**, or [Snacks](https://snacks.takeaway.com/) and [Skip PIE](https://github.com/justeat/pie-project) for **React components**). +For a list of which components are supported in each of our libraries, please refer to the [Component Status page](/components/component-status/). --- @@ -30,6 +24,11 @@ If you'd like to contribute to PIE, check out our [contributing guide](/engineer We also maintain **guides** for global front-end best practices across JET. These can be found in the [engineering guidelines section of our docs](/engineers/guidelines/). +### Code and Project Structure + +PIE Web Components, tools and documentation (including this site) are maintained on the open-source [PIE Monorepo on Github](https://github.com/justeattakeaway/pie). + +We support and maintain a number of other projects that incorporate the PIE Design Language (such as [Fozzie](https://github.com/justeattakeaway/fozzie-components) for **VueJS components**, or [Snacks](https://snacks.takeaway.com/) and [Skip PIE](https://github.com/justeat/pie-project) for **React components**).