diff --git a/README.md b/README.md index ddd3440d3c..eb427830b0 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,10 @@ ripple storybook - - ripple ui core npm + + build status - - ripple develop branch build status - # Ripple 2.0 @@ -25,6 +22,8 @@ **Table of Contents** - [About the project](#about-the-project) - [Ripple Framework](#ripple-framework) + - [Usage](#usage) + - [Availability](#availability) - [Documentation](#documentation) - [Contributing](#contributing) - [License](#license) @@ -42,11 +41,27 @@ Ripple is a system of reusable styles, components, patterns and tools for buildi Over 50 government websites use Ripple to date, including our main vic.gov.au platform. These sites attract the visitation of millions of views per month. - ### Ripple Framework -The Ripple design system consists of the design elements and components used to build websites using the Victorian government brand and Ripple _framework_, a collection of [Nuxt 3](https://www.ripple.sdp.vic.gov.au/framework/key-concepts/nuxt/) modules and [layers](https://www.ripple.sdp.vic.gov.au/framework/key-concepts/nuxt-layers) primarily used to create headless SDP websites using the [Tide Drupal CMS](https://github.com/dpc-sdp/tide). +The Ripple design system consists of the design elements and components used to build websites using the Victorian government brand and Ripple _framework_, a collection of [Nuxt](https://www.ripple.sdp.vic.gov.au/framework/key-concepts/nuxt/) modules and [layers](https://www.ripple.sdp.vic.gov.au/framework/key-concepts/nuxt-layers) primarily used to create headless SDP websites using the [Tide Drupal CMS](https://github.com/dpc-sdp/tide). + +Ripple components are built using Vue 3 and [TypeScript](https://github.com/dpc-sdp/ripple-framework/blob/develop/tsconfig.json). + +The monorepo is managed with pnpm [workspaces](https://github.com/dpc-sdp/ripple-framework/blob/develop/pnpm-workspace.yaml), using [Node.js](.nvmrc). + +Tests use [Jest](https://github.com/dpc-sdp/ripple-framework/blob/develop/jest.config.js), [Axe-core](https://github.com/dpc-sdp/ripple-framework/blob/develop/packages/ripple-ui-core/stories/interactions.js) and [Cypress](packages/ripple-test-utils). + +We use custom rules for [ESLint](https://github.com/dpc-sdp/ripple-framework/blob/develop/packages/eslint-config-ripple/index.js) and [Stylelint](https://github.com/dpc-sdp/ripple-framework/blob/develop/packages/stylelint-config-ripple/index.js). +### Usage + +Ripple was built as a whole to implement front end sites for SDP using a framework of Vue 3 and Nuxt 3, but parts of the modular architecture can be used independently: `ripple-ui-core` and `ripple-ui-forms` can be used as UI component libraries for any Vue 3 project. + +There is also an experimental web components implementation, and a standalone export of all Ripple design system CSS. See the [relevant section](https://ripple.sdp.vic.gov.au/design-system/develop/usage/) on the Ripple documentation site for more details. + +### Availability + +Note: Ripple 2 will only be hosted on Github Packages, any packages still published to npm are either pre-release or deprecated, and should not be used. Please see the section [Access to Github Packages repos](https://www.ripple.vic.gov.au/design-system/develop/usage#access-to-github-packages-repos) for instructions on how to set up a personal access token, and where to use it. ## Documentation @@ -54,7 +69,6 @@ See https://www.ripple.sdp.vic.gov.au/ for more information about the Ripple des For information about using Ripple in SDP websites see the [Ripple Framework](https://www.ripple.sdp.vic.gov.au/framework) section. - ## Contributing Please see [CONTRIBUTING.md](CONTRIBUTING.md) as well as https://www.ripple.sdp.vic.gov.au/design-system/develop/contributing/ for information about how to submit changes to Ripple. diff --git a/docs/content/design-system/3.develop/3.usage.md b/docs/content/design-system/3.develop/3.usage.md index 70fd8ee599..d75fbb0fa0 100644 --- a/docs/content/design-system/3.develop/3.usage.md +++ b/docs/content/design-system/3.develop/3.usage.md @@ -16,101 +16,21 @@ Whilst Ripple is built to implement sites using a framework built on Vue JS and ![ripple is made up of Figma design, CSS styles, Vue JS components and Nuxt JS Sites](/assets/img/modules/rpl-modules.png) - Ripple UI libraries are usable in the following contexts: -| Library | CSS styles | Vue Components | Ripple Framework (Nuxt) | Web components | +| Library | CSS styles | Vue Components | Ripple Framework (Nuxt) | Web components | | --------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------- | | Ripple UI Core | supported | supported |supported | Partial support | | Ripple UI Forms | supported | supported |supported | not supported | - - - ### Using in an SDP website > If you are using Ripple 2 to build a site on the SDP platform, the UI libraries will be included automatically when scaffolding your project. > > For documentation on using Ripple with Nuxt in SDP sites, visit the [Ripple Framework documentation](/framework) -### Using in a Vue app - -To install Ripple UI in your project, run: - -`npm install @dpc-sdp/ripple-ui-core --save` - -In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue or index.js file): - -```js -import '@dpc-sdp/ripple-ui-core/style'; -import '@dpc-sdp/ripple-ui-core/style/components'; -``` - -To use a component, import it from `@dpc-sdp/ripple-ui-core/vue`, note the addition of `/vue`. - -```js - - - -``` - -### Using in a Nuxt app - -To install Ripple UI in your project, run: - -`npm install @dpc-sdp/ripple-ui-core --save` - -Ripple UI exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`: - -```js -export default defineNuxtConfig({ - modules: [ - '@dpc-sdp/ripple-ui-core/nuxt' - ] -}) -``` - -In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue file): - -```js -import '@dpc-sdp/ripple-ui-core/style'; -import '@dpc-sdp/ripple-ui-core/style/components'; -``` - -There is no need to import the components as they will be registered globally by the nuxt module - -```js - -``` - -### Webcomponents - -> Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML. -> -> Web components are based on existing web standards. Features to support web components are currently being added to the HTML and DOM specs, letting web developers easily extend HTML with new elements with encapsulated styling and custom behavior. -> https://www.webcomponents.org/ - -Ripple exports a limited set of components as standard browser native webcomponents. The advantage of using Webcomponents is they can be dropped straight into traditional webpages and CMS's that do not have javascript build pipeline such as Squiz Matrix and Salesforce. - -Support for this output target is currently experimental, if you think you have a use case for using Webcomponents in your project please add a comment [here](https://github.com/dpc-sdp/ripple-framework/discussions/658). - -### Using Ripple CSS styles only - -Ripple UI core exports it's CSS stylesheets directly. If you have a use case where you can't use any of the other outputs, you can use our styles directly and provide your own markup based upon the rendered examples in Storybook. - -To import CSS styles only you can import them from the ripple-ui-core package. - -```js -import '@dpc-sdp/ripple-ui-core/style'; -import '@dpc-sdp/ripple-ui-core/style/components'; -``` +### Github Packages -We recommend that you lock the version of `@dpc-sdp/ripple-ui-core` so that any future changes of styles without changes to markup do not break your application. +Ripple 2 is hosted publicly on Github Packages (ghcr) under the **@dpc/sdp** namespace, please read these [setup instructions for accessing Github Packages](/design-system/develop/usage/access-to-github-packages). diff --git a/docs/content/design-system/3.develop/4.usage/1.access-to-github-packages.md b/docs/content/design-system/3.develop/4.usage/1.access-to-github-packages.md new file mode 100644 index 0000000000..d206afdf0b --- /dev/null +++ b/docs/content/design-system/3.develop/4.usage/1.access-to-github-packages.md @@ -0,0 +1,48 @@ +--- +title: Access to Github Packages +description: How to access and use repos hosted on Github Packages. +layout: page +--- + +NPM allows the use of multiple repo hosts, as long as they can be identified by namespace. + +Ripple 2 is hosted publicly on Github Packages (ghcr) under the **@dpc/sdp** namespace, so a few steps need to be followed access these packages, while also co-existing with the npm ecosystem. + +First, create a Personal Access Token on Github: + +1. Visit https://github.com/settings/tokens and select **Generate new token** > **Generate new token (classic)** + +::DocsImageExample +--- +src: /img/generate.jpg +alt: "Screenshot of a clicked button (title Generate new token) that has opened a drop-down menu with two options: fine-grained and classic" +style: "width:360px" +--- +:: + +2. Fill in the **Note** and choose an **Expiration** - the 30 day default is generally fine, you'll receive a reminder to regenerate the token just before expiry + +::DocsImageExample +--- +src: /img/token.jpg +alt: "Screenshot of personal access token setup form, with 'Note' filled in as 'public ghcr access' and 'Expiration' set to default of 30 days" +style: "width:505px" +--- +:: + +3. Set the scope to only allow `read:packages`, and **Generate** token + +::DocsImageExample +--- +src: /img/permissions.jpg +alt: "Screenshot of scope, with only read:packages selected" +style: "width:827px" +--- +:: + +4. Store the resulting token somewhere secure, and add it to either a user `.npmrc` (recommended) or the project-level `.npmrc` (the url on line 2 below is protocol-less, not a comment): + +``` +@dpc-sdp:registry=https://npm.pkg.github.com +//npm.pkg.github.com/:_authToken= +``` diff --git a/docs/content/design-system/3.develop/4.usage/2.vue.md b/docs/content/design-system/3.develop/4.usage/2.vue.md new file mode 100644 index 0000000000..3a15c56986 --- /dev/null +++ b/docs/content/design-system/3.develop/4.usage/2.vue.md @@ -0,0 +1,32 @@ +--- +title: Vue +description: How to use Ripple components with Vue. +layout: page +--- + +First, set up [access to Github Packages](access-to-github-packages). + +Next, install Ripple UI in your project: + +`npm install @dpc-sdp/ripple-ui-core --save` + +In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue or index.js file): + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +To use a component, import it from `@dpc-sdp/ripple-ui-core/vue`, note the addition of `/vue`. + +```js + + + +``` + +Please see this [example app](https://github.com/dpc-sdp/ripple-vue-example) for a basic demonstration of how to use Ripple components in a Vue app. diff --git a/docs/content/design-system/3.develop/4.usage/3.nuxt.md b/docs/content/design-system/3.develop/4.usage/3.nuxt.md new file mode 100644 index 0000000000..69b2335f65 --- /dev/null +++ b/docs/content/design-system/3.develop/4.usage/3.nuxt.md @@ -0,0 +1,38 @@ +--- +title: Nuxt +description: How to use Ripple components with Nuxt in a non-SDP context. +layout: page +--- + +First, set up [access to Github Packages](access-to-github-packages). + +Next, install Ripple UI in your project: + +`npm install @dpc-sdp/ripple-ui-core --save` + +Ripple UI exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`: + +```js +export default defineNuxtConfig({ + modules: [ + '@dpc-sdp/ripple-ui-core/nuxt' + ] +}) +``` + +In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue file): + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +There is no need to import the components as they will be registered globally by the nuxt module + +```js + +``` + +Even if you are not using SDP, the [Ripple Framework documentation](/framework) is a good starting point for any Nuxt development using Ripple. diff --git a/docs/content/design-system/3.develop/4.usage/4.webcomponents.md b/docs/content/design-system/3.develop/4.usage/4.webcomponents.md new file mode 100644 index 0000000000..4cdc5d8189 --- /dev/null +++ b/docs/content/design-system/3.develop/4.usage/4.webcomponents.md @@ -0,0 +1,23 @@ +--- +title: Web components +description: How to use the web component exports with other front-end systems. +layout: page +--- + +> Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML. +> +> Web components are based on existing web standards. Features to support web components are currently being added to the HTML and DOM specs, letting web developers easily extend HTML with new elements with encapsulated styling and custom behavior. +> https://www.webcomponents.org/ + + + + +Ripple exports a limited set of components as standard browser native web components. The advantage of using Web components is they can be dropped straight into conventional webpages and any CMS without a javascript build pipeline, such as Squiz Matrix and Salesforce. + +Support for this output target is currently experimental, if you think you have a use case for using Web components in your project please add a comment [here](https://github.com/dpc-sdp/ripple-framework/discussions/658). + +As with the other methods, set up [access to Github Packages](access-to-github-packages) and then install Ripple UI in your project: + +`npm install @dpc-sdp/ripple-ui-core --save` + +A basic example of how to use the web component exports can be found under [examples/webcomponents](https://github.com/dpc-sdp/ripple-framework/tree/develop/examples/webcomponents) in the ripple-framework monorepo. diff --git a/docs/content/design-system/3.develop/4.usage/5.css-only.md b/docs/content/design-system/3.develop/4.usage/5.css-only.md new file mode 100644 index 0000000000..1a8a8c501f --- /dev/null +++ b/docs/content/design-system/3.develop/4.usage/5.css-only.md @@ -0,0 +1,22 @@ +--- +title: Styles only +description: Using the design system styles without a front-end framework. +layout: page +--- + +Ripple UI core exports it's CSS stylesheets directly. If you have a use case where you can't use any of the other outputs, you can use our styles directly and provide your own markup based upon the rendered examples in Storybook. + +First, set up [access to Github Packages](access-to-github-packages). + +Next, install Ripple UI in your project: + +`npm install @dpc-sdp/ripple-ui-core --save` + +You can import CSS styles from the ripple-ui-core package. + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +We recommend that you lock the version of `@dpc-sdp/ripple-ui-core` so that any future changes of styles without changes to markup do not break your application. diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts index d4c1dc0506..79191706ae 100644 --- a/docs/nuxt.config.ts +++ b/docs/nuxt.config.ts @@ -30,6 +30,9 @@ export default defineNuxtConfig({ vite: { plugins: [ViteYaml()] }, + experimental: { + inlineSSRStyles: (id) => !id?.includes('entry') + }, nitro: { prerender: { ignore: ['/storybook'] diff --git a/docs/public/img/generate.jpg b/docs/public/img/generate.jpg new file mode 100644 index 0000000000..73efedb3f4 Binary files /dev/null and b/docs/public/img/generate.jpg differ diff --git a/docs/public/img/permissions.jpg b/docs/public/img/permissions.jpg new file mode 100644 index 0000000000..c122203d5b Binary files /dev/null and b/docs/public/img/permissions.jpg differ diff --git a/docs/public/img/token.jpg b/docs/public/img/token.jpg new file mode 100644 index 0000000000..4a8737f5b1 Binary files /dev/null and b/docs/public/img/token.jpg differ diff --git a/packages/ripple-ui-core/README.md b/packages/ripple-ui-core/README.md index 9466da509a..bf5faaa524 100644 --- a/packages/ripple-ui-core/README.md +++ b/packages/ripple-ui-core/README.md @@ -1,6 +1,6 @@ -# Ripple UI Core +# Ripple UI Core -> A UI component library built with Vue.js. [View the Ripple storybook](https://www.ripple.sdp.vic.gov.au/storybook) to start exploring available components. +> A Vue 3 UI component library. [View the Ripple storybook](https://www.ripple.sdp.vic.gov.au/storybook) to start exploring available components. ## SDP Platform (Tide) @@ -22,7 +22,7 @@ npm install @dpc-sdp/ripple-ui-core ## Usage (Nuxt) -Ripple UI Core exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`. +Ripple UI Core exports a Nuxt 3 module that you can add to your nuxt config, note the addition of `/nuxt`. ```js export default defineNuxtConfig({ @@ -32,6 +32,8 @@ export default defineNuxtConfig({ }) ``` +Note: Nuxt 2 is not supported. + There is no need to import the components as they will be registered globally by the nuxt module. ```vue diff --git a/packages/ripple-ui-forms/README.md b/packages/ripple-ui-forms/README.md index 2826e0bc60..12ca9431b9 100644 --- a/packages/ripple-ui-forms/README.md +++ b/packages/ripple-ui-forms/README.md @@ -1,6 +1,6 @@ # Ripple UI Forms -> A form component library built with [Formkit](https://formkit.com/). [View the Ripple storybook](https://www.ripple.sdp.vic.gov.au/storybook/?path=/story/forms-form--default-story) to start exploring available components. +> A Vue 3 form component library built with [Formkit](https://formkit.com/). [View the Ripple storybook](https://www.ripple.sdp.vic.gov.au/storybook/?path=/story/forms-form--default-story) to start exploring available components. Form fields can be used individually `` to handcraft form experiences. However, using the `` component and providing a form schema provides a simpler way to define and generate forms. @@ -48,7 +48,7 @@ npm install @dpc-sdp/ripple-ui-forms ## Usage (Nuxt) -Ripple UI Forms exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`. +Ripple UI Forms exports a Nuxt 3 module that you can add to your nuxt config, note the addition of `/nuxt`. ```js export default defineNuxtConfig({ @@ -58,6 +58,8 @@ export default defineNuxtConfig({ }) ``` +Note: Nuxt 2 is not supported. + There is no need to import the components as they will be registered globally by the nuxt module. ```vue