From f957753c2ce0547f48e6f675a1c0c0ff30fca6f0 Mon Sep 17 00:00:00 2001 From: oliver-reload Date: Wed, 26 Apr 2023 17:48:14 +0200 Subject: [PATCH 1/2] Added docs folder and modified README to support documentation site --- README.md | 733 +---------------- docs/README.md | 739 ++++++++++++++++++ .../architecture}/adr-001-rehydration.md | 0 .../architecture}/adr-002-ui-text-handling.md | 0 .../architecture}/adr-003-downshift.md | 0 .../architecture}/adr-004-relative-ci.md | 0 .../architecture}/adr-005-react-use.md | 0 .../architecture}/adr-006-unit-tests.md | 0 docs/code_guidelines.md | 2 +- docs/ui_text_handling.md | 2 +- 10 files changed, 743 insertions(+), 733 deletions(-) create mode 100644 docs/README.md rename {architecture => docs/architecture}/adr-001-rehydration.md (100%) rename {architecture => docs/architecture}/adr-002-ui-text-handling.md (100%) rename {architecture => docs/architecture}/adr-003-downshift.md (100%) rename {architecture => docs/architecture}/adr-004-relative-ci.md (100%) rename {architecture => docs/architecture}/adr-005-react-use.md (100%) rename {architecture => docs/architecture}/adr-006-unit-tests.md (100%) diff --git a/README.md b/README.md index 88df3ae4ba..1e5037dcce 100644 --- a/README.md +++ b/README.md @@ -6,734 +6,5 @@ A set of React components and applications providing self-service features for Danish public libraries. - - - - -- [Development](#development) - - [Requirements](#requirements) - - [Development - alternative (no docker)](#development---alternative-no-docker) - - [Howto](#howto) - - [Step Debugging in Visual Studio Code (no docker)](#step-debugging-in-visual-studio-code-no-docker) - - [Access tokens](#access-tokens) - - [Library token](#library-token) - - [Installation](#installation) - - [Standard and style](#standard-and-style) - - [JavaScript + JSX](#javascript--jsx) - - [Named functions Vs. Anonymous arrow functions](#named-functions-vs-anonymous-arrow-functions) - - [Create a new application](#create-a-new-application) - - [Application state-machine](#application-state-machine) - - [Style your application](#style-your-application) - - [Style using the DPL design system](#style-using-the-dpl-design-system) - - [Using unreleased design](#using-unreleased-design) - - [Cross application components](#cross-application-components) - - [Creating an atom](#creating-an-atom) - - [Creating a component](#creating-a-component) - - [Editor example configuration](#editor-example-configuration) -- [Usage](#usage) - - [Naive app mount](#naive-app-mount) - - [Data attributes and props](#data-attributes-and-props) -- [Extending the project](#extending-the-project) - - - - - -## Development - -### Requirements - -- [go-task](https://github.com/go-task/task) -- [Docker](https://www.docker.com/products/docker-desktop) -- [Dory](https://github.com/FreedomBen/dory) - -### Development - alternative (no docker) - -#### Howto - -- Run: sudo vim /etc/hosts -- Add as the last line in the doc: 127.0.0.1 dpl-react.docker -- Now storybook can be started by sudo yarn start:storybook:dev - -- Now you need to make sure that your node version is the right one - for the project whenever a terminal is opened -- (it is specified in the package.json file) -- if you then wish to log in through adgangsplatformen, you need to change - your url to: - this avoids getting log in errors -- (note: if you enter adgangsplatform again after signing it, you will get - signed out, and need to log in again. This is not a bug, as you stay logged - in otherwise.) - -#### Step Debugging in Visual Studio Code (no docker) - -If you want to enable step debugging you need to: - -- Copy .vscode.example/launch.json into .vscode/ -- Mark 1 or more breakpoints on a line in the left gutter on an open file -- In the top menu in VS Code choose: Run -> Start Debugging -- Type in your user password if ask to -- Start debugging πŸ€–βˆΏπŸ’» - -#### Access tokens - -Access token must be retrieved from [Adgangsplatformen](https://github.com/DBCDK/hejmdal/blob/master/docs/oauth2.md), -a single sign-on solution for public libraries in Denmark, and [OpenPlatform](https://openplatform.dbc.dk/v3/), -an API for danish libraries. - -Usage of these systems require a valid client id and secret which must be -obtained from your library partner or directly from DBC, the company responsible -for running Adgangsplatformen and OpenPlatform. - -This project include a client id that matches the storybook setup which can be -used for development purposes. You can use the `/auth` story to sign in to -Adgangsplatformen for the storybook context. - -#### Library token - -To test the apps that is indifferent to wether the user is authenticated or not -it is possible to set a library token via the library component in Storybook. -Workflow: - -- Retrieve a library token via [OpenPlatform](https://openplatform.dbc.dk/v3/) -- Insert the library token in the Library Token story in storybook - -### Installation - -Using go-task to handle the project. Before you can install the project you need -to create the file `~/.npmrc` to access the github package registry as described -[here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token) -using a personal access token. - -```bash -task dev:start -``` - -When storybook is started, you can access it at: [dpl-react.docker](http://dpl-react.docker) - -### Standard and style - -#### JavaScript + JSX - -For static code analysis we make use of the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) -and for formatting we make use of [Prettier](https://github.com/prettier/prettier) -with the default configuration. The above choices have been influenced by a -multitude of factors: - -- Historically Drupal core have been making use of the Airbnb JavaScript Style - Guide. -- Airbnb's standard is comparatively the [best known](https://github.com/airbnb/javascript/stargazers) - and one of the [most used](https://github.com/airbnb/javascript/network/dependents?package_id=UGFja2FnZS0xODIxMTAxOA%3D%3D) - in the JavaScript coding standard landscape. - -This makes future adoption easier for onboarding contributors and support is to -be expected for a long time. - -##### Named functions Vs. Anonymous arrow functions - -AirBnB's only guideline towards this is that anonymous arrow function are -preferred over the normal anonymous function notation. - -When you must use an anonymous function (as when passing an inline callback), -use arrow function notation. - -> Why? It creates a version of the function that executes in the context of -> this, which is usually what you want, and is a more concise syntax. -> -> Why not? If you have a fairly complicated function, you might move that logic -> out into its own named function expression. - -[Reference](https://github.com/airbnb/javascript#arrows--use-them) - -This project stick to the above guideline as well. If we need to pass a function -as part of a callback or in a promise chain and we on top of that need to pass -some contextual variables that is not passed implicit from either the callback -or the previous link in the promise chain we want to make use of an anonymous -arrow function as our default. - -This comes with the build in disclaimer that if an anonymous function isn't -required the implementer should heavily consider moving the logic out into it's -own named function expression. - -The named function is primarily desired due to it's easier to debug nature in -stacktraces. - -### Create a new application - -
- 1. Create a new application component - -```javascript -// ./src/apps/my-new-application/my-new-application.jsx -import React from "react"; -import PropTypes from "prop-types"; - -export function MyNewApplication({ text }) { - return ( -

{text}

- ); -} - -MyNewApplication.defaultProps = { - text: "The fastest man alive!" -}; - -MyNewApplication.propTypes = { - text: PropTypes.string -}; - -export default MyNewApplication; -``` - -
- -
- 2. Create the entry component - -```javascript -// ./src/apps/my-new-application/my-new-application.entry.jsx -import React from "react"; -import PropTypes from "prop-types"; -import MyNewApplication from "./my-new-application"; - -// The props of an entry is all of the data attributes that were -// set on the DOM element. See the section on "Naive app mount." for -// an example. -export function MyNewApplicationEntry(props) { - return ; -} - -export default MyNewApplicationEntry; -``` - -
- -
- 3. Create the mount - -```javascript -// ./src/apps/my-new-application/my-new-application.mount.js -import addMount from "../../core/addMount"; -import MyNewApplication from "./my-new-application.entry"; - -addMount({ appName: "my-new-application", app: MyNewApplication }); -``` - -
- -
- 4. Add a story for local development - -```javascript -// ./src/apps/my-new-application/my-new-application.dev.jsx -import React from "react"; -import MyNewApplicationEntry from "./my-new-application.entry"; -import MyNewApplication from "./my-new-application"; - -export default { title: "Apps|My new application" }; - -export function Entry() { - // Testing the version that will be shipped. - return ; -} - -export function WithoutData() { - // Play around with the application itself without server side data. - return ; -} - -``` - -
- -
- 5. Run the development environment - -```bash - yarn dev -``` - -OR depending on your dev environment (docker or not) - -```bash - sudo yarn dev -``` - -
- -__Voila!__ You browser should have opened and a storybook environment is ready -for you to tinker around. - -#### Application state-machine - -Most applications will have multiple internal states, so to aid consistency, -it's recommended to: - -``` javascript - const [status, setStatus] = useState(""); -``` - -and use the following states where appropriate: - -`initial`: Initial state for applications that require some sort of -initialization, such as making a request to see if a material can be ordered, -before rendering the order button. Errors in initialization can go directly to -the failed state, or add custom states for communication different error -conditions to the user. Should render either nothing or as a -skeleton/spinner/message. - -`ready`: The general "ready state". Applications that doesn't need -initialization (a generic button for instance) can use `ready` as the initial -state set in the `useState` call. This is basically the main waiting state. - -`processing`: The application is taking some action. For buttons this will be -the state used when the user has clicked the button and the application is -waiting for reply from the back end. More advanced applications may use it while -doing backend requests, if reflecting the processing in the UI is desired. -Applications using optimistic feedback will render this state the same as the -`finished` state. - -`failed`: Processing failed. The application renders an error message. - -`finished`: End state for one-shot actions. Communicates success to the user. - -Applications can use additional states if desired, but prefer the above if -appropriate. - -### Style your application - -
- 1. Create an application specific stylesheet - -```scss -// ./src/apps/my-new-application/my-new-application.scss -.dpl-warm { - color: maroon; -} -``` - -
- -
- 2. Add the class to your application - -```javascript -// ./src/apps/my-new-application/my-new-application.jsx -import React from "react"; -import PropTypes from "prop-types"; - -export function MyNewApplication({ text }) { - return ( -

{text}

- ); -} - -MyNewApplication.defaultProps = { - text: "The fastest man alive!" -}; - -MyNewApplication.propTypes = { - text: PropTypes.string -}; - -export default MyNewApplication; -``` - -
- -
- 3. Import the scss into your story - -```javascript -// ./src/apps/my-new-application/my-new-application.dev.jsx -import React from "react"; -import MyNewApplicationEntry from "./my-new-application.entry"; -import MyNewApplication from "./my-new-application"; - -import './my-new-application.scss'; - -export default { title: "Apps|My new application" }; - -export function Entry() { - // Testing the version that will be shipped. - return ; -} - -export function WithoutData() { - // Play around with the application itself without server side data. - return ; -} -``` - -
- -__Cowabunga!__ You now got styling in your application - -### Style using the DPL design system - -This project includes styling created by its sister repository - -[the design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) -as a npm package. - -By default the project should include a release of the design system matching -the current state of the project. - -To update the design system to the latest stable release of the design system -run: - -```bash -yarn add @danskernesdigitalebibliotek/dpl-design-system@latest -``` - -This command installs the latest released version of the package. Whenever a -new version of the design system package is released, it is necessary -to reinstall the package in this project using the same command to get the -newest styling, because yarn adds a specific version number to the package name -in package.json. - -#### Using unreleased design - -If you need to work with published but unreleased code from a specific branch -of the design system, you can also use the branch name as the tag for the npm -package, replacing all special characters with dashes (`-`). - -Example: To use the latest styling from a branch in the design system called -`feature/availability-label`, run: - -```bash -yarn add @danskernesdigitalebibliotek/dpl-design-system@feature-availability-label -``` - -If the branch resides in a fork (usually before a pull request is merged) you -can use [aliasing](https://classic.yarnpkg.com/lang/en/docs/cli/add/#toc-yarn-add-alias) -and run: - -```bash -yarn config set "@my-fork:registry" "https://npm.pkg.github.com" -yarn add @danskernesdigitalebibliotek/dpl-design-system@npm:@my-fork/dpl-design-system@feature-availability-label -``` - -If the branch is updated and you want the latest changes to take effect locally -update the release used: - -```bash -yarn upgrade @danskernesdigitalebibliotek/dpl-design-system -``` - -Note that references to unreleased code should never make it into official -versions of the project. - -### Cross application components - -If the component is simple enough to be a primitive you would use in multiple -occasions it's called an 'atom'. Such as a button or a link. If it's more -specific that that and to be used across apps we just call it a component. An -example would be some type of media presented alongside a header and some text. - -The process when creating an atom or a component is more or less similar, but -some structural differences might be needed. - -#### Creating an atom - -
- 1. Create the atom - -```javascript -// ./src/components/atoms/my-new-atom/my-new-atom.jsx -import React from "react"; -import PropTypes from 'prop-types'; - -/** - * A simple button. - * - * @export - * @param {object} props - * @returns {ReactNode} - */ -export function MyNewAtom({ className, children }) { - return ; -} - -MyNewAtom.propTypes = { - className: PropTypes.string, - children: PropTypes.node.isRequired -} - -MyNewAtom.defaultProps = { - className: "" -} - -export default MyNewAtom; -``` - -
- -
- 2. Create styles for the atom - -```scss -// ./src/components/atoms/my-new-atom/my-new-atom.scss -.dpl-btn { - color: blue; -} -``` - -
- -
- 3. Import the atom's styles into the component stylesheet - -```scss -// ./src/components/components.scss -@import 'atoms/button/button.scss'; -@import 'atoms/my-new-atom/my-new-atom.scss'; -``` - -
- -
- 4. Create a story for your atom - -```javascript -// ./src/components/atoms/my-new-atom/my-new-atom.dev.jsx -import React from "react"; -import MyNewAtom from "./my-new-atom"; - -export default { title: "Atoms|My new atom" }; - -export function WithText() { - return Cick me!; -} -``` - -
- -
- 5. Import the atom into the applications or other components where -you would want to use it - -```javascript -// ./src/apps/my-new-application/my-new-application.jsx -import React, {Fragment} from "react"; -import PropTypes from "prop-types"; - -import MyNewAtom from "../../components/atom/my-new-atom/my-new-atom" - -export function MyNewApplication({ text }) { - return ( - -

{text}

- - - ); -} - -MyNewApplication.defaultProps = { - text: "The fastest man alive!" -}; - -MyNewApplication.propTypes = { - text: PropTypes.string -}; - -export default MyNewApplication; -``` - -
- -__Finito!__ You now know how to share code across applications - -#### Creating a component - -Repeat all of the same steps as with an atom but place it in it's own directory -inside `components`. - -Such as `./src/components/my-new-component/my-new-component.jsx` - -### Editor example configuration - -If you use [Code](https://github.com/microsoft/vscode) we provide some easy to -use and nice defaults for this project. They are located in `.vscode.example`. -Simply rename the directory from `.vscode.example` to `.vscode` and you are good -to go. This overwrites your global user settings for this workspace and suggests -som extensions you might want. - -## Usage - -There are two ways to use the components provided by this project: - -1. As standalone JavaScript applications mounted within HTML pages generated by - a separate system. -2. As components within a larger JavaScript application (Under development) - -### Naive app mount - -So let's say you wanted to make use of an application within an existing HTML -page such as what might be generated serverside by platforms like Drupal, -WordPress etc. - -For this use case you should download the `dist.zip` package from -[the latest release of the project](/danskernesdigitalebibliotek/dpl-react/releases/latest) -and unzip somewhere within the web root of your project. The package contains a -set of artifacts needed to use one or more applications within an HTML page. - -
- HTML Example - -A simple example of the required artifacts and how they are used looks like -this: - -```html - - - - - - - Naive mount - - - - - Here be dragons! - -
-
- - - - - - - - - - -``` - -
- -As a minimum you will need the `runtime.js` and `bundle.js`. For styling -of atoms and components you will need to import `components.css`. - -Each application also has its own JavaScript artifact and it might have a CSS -artifact as well. Such as `add-to-checklist.js` and `add-to-checklist.css`. - -To mount the application you need an HTML element with the correct data -attribute. - -```html -
-``` - -The name of the data attribute should be `data-dpl-app` and the value should be -the name of the application - the value of the `appName` parameter assigned in -the application `.mount.js` file. - -#### Data attributes and props - -As stated above, every application needs the corresponding `data-dpl-app` -attribute to even be mounted and shown on the page. Additional data attributes -can be passed if necessary. Examples would be contextual ids etc. Normally these -would be passed in by the serverside platform e.g. Drupal, Wordpress etc. - -```html -
-``` - -The above `data-id` would be accessed as `props.id` and `data-error-text` as -`props.errorText` in the entrypoint of an application. - -
- Example - -```javascript -// ./src/apps/my-new-application/my-new-application.entry.jsx -import React from "react"; -import PropTypes from "prop-types"; -import MyNewApplication from './my-new-application.jsx'; - -export function MyNewApplicationEntry({ id }) { - return ( - -} - -export default MyNewApplicationEntry; -``` - -
- -To fake this in our development environment we need to pass these same data -attributes into our entrypoint. - -
- Example - -```javascript -// ./src/apps/my-new-application/my-new-application.dev.jsx -import React from "react"; -import MyNewApplicationEntry from "./my-new-application.entry"; -import MyNewApplication from "./my-new-application"; - -export default { title: "Apps|My new application" }; - -export function Entry() { - // Testing the version that will be shipped. - return ; -} - -export function WithoutData() { - // Play around with the application itself without server side data. - return ; -} - -``` - -
- -## Extending the project - -If you want to extend this project - either by introducing new components or -expand the functionality of the existing ones - and your changes can be -implemented in a way that is valuable to users in general, please submit pull -requests. - -Even if that is not the case and you have special needs the infrastructure of -the project should also be helpful to you. - -In such a situation you should fork this project and extend it to your own needs -by [implementing new applications](#create-a-new-application). New applications -can reuse various levels of infrastructure provided by the project such as: - -1. [Integration with various webservices](src/core) -2. [User authentication and token management](src/core) -3. [Visual atoms or components](#cross-application-components) -4. Visual representations of [existing applications](src/apps) -5. [Styling using SCSS](#style-your-application) -6. Test infrastructure -7. [Application mounting](src/core) - -Once the customization is complete the result can be packaged for distribution -by pushing the changes to the forked repository: - -1. Changes pushed to the `master` branch of the forked repository will - automatically update the latest release of the fork. -2. Tags pushed to the forked repository also will be published as new releases - in the fork. - -The result can be [used in the same ways as the original project](#usage). +Read more about DPL React by visiting our +[Documentation site](https://danskernesdigitalebibliotek.github.io/dpl-docs) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..88df3ae4ba --- /dev/null +++ b/docs/README.md @@ -0,0 +1,739 @@ + +![https://raw.githubusercontent.com/danskernesdigitalebibliotek/dpl-react/master/logo.png](https://raw.githubusercontent.com/danskernesdigitalebibliotek/dpl-react/master/logo.png) + +[![codecov](https://codecov.io/gh/danskernesdigitalebibliotek/dpl-react/branch/master/graph/badge.svg)](https://codecov.io/gh/danskernesdigitalebibliotek/dpl-react) + +A set of React components and applications providing self-service features for +Danish public libraries. + + + + + +- [Development](#development) + - [Requirements](#requirements) + - [Development - alternative (no docker)](#development---alternative-no-docker) + - [Howto](#howto) + - [Step Debugging in Visual Studio Code (no docker)](#step-debugging-in-visual-studio-code-no-docker) + - [Access tokens](#access-tokens) + - [Library token](#library-token) + - [Installation](#installation) + - [Standard and style](#standard-and-style) + - [JavaScript + JSX](#javascript--jsx) + - [Named functions Vs. Anonymous arrow functions](#named-functions-vs-anonymous-arrow-functions) + - [Create a new application](#create-a-new-application) + - [Application state-machine](#application-state-machine) + - [Style your application](#style-your-application) + - [Style using the DPL design system](#style-using-the-dpl-design-system) + - [Using unreleased design](#using-unreleased-design) + - [Cross application components](#cross-application-components) + - [Creating an atom](#creating-an-atom) + - [Creating a component](#creating-a-component) + - [Editor example configuration](#editor-example-configuration) +- [Usage](#usage) + - [Naive app mount](#naive-app-mount) + - [Data attributes and props](#data-attributes-and-props) +- [Extending the project](#extending-the-project) + + + + + +## Development + +### Requirements + +- [go-task](https://github.com/go-task/task) +- [Docker](https://www.docker.com/products/docker-desktop) +- [Dory](https://github.com/FreedomBen/dory) + +### Development - alternative (no docker) + +#### Howto + +- Run: sudo vim /etc/hosts +- Add as the last line in the doc: 127.0.0.1 dpl-react.docker +- Now storybook can be started by sudo yarn start:storybook:dev + +- Now you need to make sure that your node version is the right one + for the project whenever a terminal is opened +- (it is specified in the package.json file) +- if you then wish to log in through adgangsplatformen, you need to change + your url to: - this avoids getting log in errors +- (note: if you enter adgangsplatform again after signing it, you will get + signed out, and need to log in again. This is not a bug, as you stay logged + in otherwise.) + +#### Step Debugging in Visual Studio Code (no docker) + +If you want to enable step debugging you need to: + +- Copy .vscode.example/launch.json into .vscode/ +- Mark 1 or more breakpoints on a line in the left gutter on an open file +- In the top menu in VS Code choose: Run -> Start Debugging +- Type in your user password if ask to +- Start debugging πŸ€–βˆΏπŸ’» + +#### Access tokens + +Access token must be retrieved from [Adgangsplatformen](https://github.com/DBCDK/hejmdal/blob/master/docs/oauth2.md), +a single sign-on solution for public libraries in Denmark, and [OpenPlatform](https://openplatform.dbc.dk/v3/), +an API for danish libraries. + +Usage of these systems require a valid client id and secret which must be +obtained from your library partner or directly from DBC, the company responsible +for running Adgangsplatformen and OpenPlatform. + +This project include a client id that matches the storybook setup which can be +used for development purposes. You can use the `/auth` story to sign in to +Adgangsplatformen for the storybook context. + +#### Library token + +To test the apps that is indifferent to wether the user is authenticated or not +it is possible to set a library token via the library component in Storybook. +Workflow: + +- Retrieve a library token via [OpenPlatform](https://openplatform.dbc.dk/v3/) +- Insert the library token in the Library Token story in storybook + +### Installation + +Using go-task to handle the project. Before you can install the project you need +to create the file `~/.npmrc` to access the github package registry as described +[here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token) +using a personal access token. + +```bash +task dev:start +``` + +When storybook is started, you can access it at: [dpl-react.docker](http://dpl-react.docker) + +### Standard and style + +#### JavaScript + JSX + +For static code analysis we make use of the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) +and for formatting we make use of [Prettier](https://github.com/prettier/prettier) +with the default configuration. The above choices have been influenced by a +multitude of factors: + +- Historically Drupal core have been making use of the Airbnb JavaScript Style + Guide. +- Airbnb's standard is comparatively the [best known](https://github.com/airbnb/javascript/stargazers) + and one of the [most used](https://github.com/airbnb/javascript/network/dependents?package_id=UGFja2FnZS0xODIxMTAxOA%3D%3D) + in the JavaScript coding standard landscape. + +This makes future adoption easier for onboarding contributors and support is to +be expected for a long time. + +##### Named functions Vs. Anonymous arrow functions + +AirBnB's only guideline towards this is that anonymous arrow function are +preferred over the normal anonymous function notation. + +When you must use an anonymous function (as when passing an inline callback), +use arrow function notation. + +> Why? It creates a version of the function that executes in the context of +> this, which is usually what you want, and is a more concise syntax. +> +> Why not? If you have a fairly complicated function, you might move that logic +> out into its own named function expression. + +[Reference](https://github.com/airbnb/javascript#arrows--use-them) + +This project stick to the above guideline as well. If we need to pass a function +as part of a callback or in a promise chain and we on top of that need to pass +some contextual variables that is not passed implicit from either the callback +or the previous link in the promise chain we want to make use of an anonymous +arrow function as our default. + +This comes with the build in disclaimer that if an anonymous function isn't +required the implementer should heavily consider moving the logic out into it's +own named function expression. + +The named function is primarily desired due to it's easier to debug nature in +stacktraces. + +### Create a new application + +
+ 1. Create a new application component + +```javascript +// ./src/apps/my-new-application/my-new-application.jsx +import React from "react"; +import PropTypes from "prop-types"; + +export function MyNewApplication({ text }) { + return ( +

{text}

+ ); +} + +MyNewApplication.defaultProps = { + text: "The fastest man alive!" +}; + +MyNewApplication.propTypes = { + text: PropTypes.string +}; + +export default MyNewApplication; +``` + +
+ +
+ 2. Create the entry component + +```javascript +// ./src/apps/my-new-application/my-new-application.entry.jsx +import React from "react"; +import PropTypes from "prop-types"; +import MyNewApplication from "./my-new-application"; + +// The props of an entry is all of the data attributes that were +// set on the DOM element. See the section on "Naive app mount." for +// an example. +export function MyNewApplicationEntry(props) { + return ; +} + +export default MyNewApplicationEntry; +``` + +
+ +
+ 3. Create the mount + +```javascript +// ./src/apps/my-new-application/my-new-application.mount.js +import addMount from "../../core/addMount"; +import MyNewApplication from "./my-new-application.entry"; + +addMount({ appName: "my-new-application", app: MyNewApplication }); +``` + +
+ +
+ 4. Add a story for local development + +```javascript +// ./src/apps/my-new-application/my-new-application.dev.jsx +import React from "react"; +import MyNewApplicationEntry from "./my-new-application.entry"; +import MyNewApplication from "./my-new-application"; + +export default { title: "Apps|My new application" }; + +export function Entry() { + // Testing the version that will be shipped. + return ; +} + +export function WithoutData() { + // Play around with the application itself without server side data. + return ; +} + +``` + +
+ +
+ 5. Run the development environment + +```bash + yarn dev +``` + +OR depending on your dev environment (docker or not) + +```bash + sudo yarn dev +``` + +
+ +__Voila!__ You browser should have opened and a storybook environment is ready +for you to tinker around. + +#### Application state-machine + +Most applications will have multiple internal states, so to aid consistency, +it's recommended to: + +``` javascript + const [status, setStatus] = useState(""); +``` + +and use the following states where appropriate: + +`initial`: Initial state for applications that require some sort of +initialization, such as making a request to see if a material can be ordered, +before rendering the order button. Errors in initialization can go directly to +the failed state, or add custom states for communication different error +conditions to the user. Should render either nothing or as a +skeleton/spinner/message. + +`ready`: The general "ready state". Applications that doesn't need +initialization (a generic button for instance) can use `ready` as the initial +state set in the `useState` call. This is basically the main waiting state. + +`processing`: The application is taking some action. For buttons this will be +the state used when the user has clicked the button and the application is +waiting for reply from the back end. More advanced applications may use it while +doing backend requests, if reflecting the processing in the UI is desired. +Applications using optimistic feedback will render this state the same as the +`finished` state. + +`failed`: Processing failed. The application renders an error message. + +`finished`: End state for one-shot actions. Communicates success to the user. + +Applications can use additional states if desired, but prefer the above if +appropriate. + +### Style your application + +
+ 1. Create an application specific stylesheet + +```scss +// ./src/apps/my-new-application/my-new-application.scss +.dpl-warm { + color: maroon; +} +``` + +
+ +
+ 2. Add the class to your application + +```javascript +// ./src/apps/my-new-application/my-new-application.jsx +import React from "react"; +import PropTypes from "prop-types"; + +export function MyNewApplication({ text }) { + return ( +

{text}

+ ); +} + +MyNewApplication.defaultProps = { + text: "The fastest man alive!" +}; + +MyNewApplication.propTypes = { + text: PropTypes.string +}; + +export default MyNewApplication; +``` + +
+ +
+ 3. Import the scss into your story + +```javascript +// ./src/apps/my-new-application/my-new-application.dev.jsx +import React from "react"; +import MyNewApplicationEntry from "./my-new-application.entry"; +import MyNewApplication from "./my-new-application"; + +import './my-new-application.scss'; + +export default { title: "Apps|My new application" }; + +export function Entry() { + // Testing the version that will be shipped. + return ; +} + +export function WithoutData() { + // Play around with the application itself without server side data. + return ; +} +``` + +
+ +__Cowabunga!__ You now got styling in your application + +### Style using the DPL design system + +This project includes styling created by its sister repository - +[the design system](https://github.com/danskernesdigitalebibliotek/dpl-design-system) +as a npm package. + +By default the project should include a release of the design system matching +the current state of the project. + +To update the design system to the latest stable release of the design system +run: + +```bash +yarn add @danskernesdigitalebibliotek/dpl-design-system@latest +``` + +This command installs the latest released version of the package. Whenever a +new version of the design system package is released, it is necessary +to reinstall the package in this project using the same command to get the +newest styling, because yarn adds a specific version number to the package name +in package.json. + +#### Using unreleased design + +If you need to work with published but unreleased code from a specific branch +of the design system, you can also use the branch name as the tag for the npm +package, replacing all special characters with dashes (`-`). + +Example: To use the latest styling from a branch in the design system called +`feature/availability-label`, run: + +```bash +yarn add @danskernesdigitalebibliotek/dpl-design-system@feature-availability-label +``` + +If the branch resides in a fork (usually before a pull request is merged) you +can use [aliasing](https://classic.yarnpkg.com/lang/en/docs/cli/add/#toc-yarn-add-alias) +and run: + +```bash +yarn config set "@my-fork:registry" "https://npm.pkg.github.com" +yarn add @danskernesdigitalebibliotek/dpl-design-system@npm:@my-fork/dpl-design-system@feature-availability-label +``` + +If the branch is updated and you want the latest changes to take effect locally +update the release used: + +```bash +yarn upgrade @danskernesdigitalebibliotek/dpl-design-system +``` + +Note that references to unreleased code should never make it into official +versions of the project. + +### Cross application components + +If the component is simple enough to be a primitive you would use in multiple +occasions it's called an 'atom'. Such as a button or a link. If it's more +specific that that and to be used across apps we just call it a component. An +example would be some type of media presented alongside a header and some text. + +The process when creating an atom or a component is more or less similar, but +some structural differences might be needed. + +#### Creating an atom + +
+ 1. Create the atom + +```javascript +// ./src/components/atoms/my-new-atom/my-new-atom.jsx +import React from "react"; +import PropTypes from 'prop-types'; + +/** + * A simple button. + * + * @export + * @param {object} props + * @returns {ReactNode} + */ +export function MyNewAtom({ className, children }) { + return ; +} + +MyNewAtom.propTypes = { + className: PropTypes.string, + children: PropTypes.node.isRequired +} + +MyNewAtom.defaultProps = { + className: "" +} + +export default MyNewAtom; +``` + +
+ +
+ 2. Create styles for the atom + +```scss +// ./src/components/atoms/my-new-atom/my-new-atom.scss +.dpl-btn { + color: blue; +} +``` + +
+ +
+ 3. Import the atom's styles into the component stylesheet + +```scss +// ./src/components/components.scss +@import 'atoms/button/button.scss'; +@import 'atoms/my-new-atom/my-new-atom.scss'; +``` + +
+ +
+ 4. Create a story for your atom + +```javascript +// ./src/components/atoms/my-new-atom/my-new-atom.dev.jsx +import React from "react"; +import MyNewAtom from "./my-new-atom"; + +export default { title: "Atoms|My new atom" }; + +export function WithText() { + return Cick me!; +} +``` + +
+ +
+ 5. Import the atom into the applications or other components where +you would want to use it + +```javascript +// ./src/apps/my-new-application/my-new-application.jsx +import React, {Fragment} from "react"; +import PropTypes from "prop-types"; + +import MyNewAtom from "../../components/atom/my-new-atom/my-new-atom" + +export function MyNewApplication({ text }) { + return ( + +

{text}

+ + + ); +} + +MyNewApplication.defaultProps = { + text: "The fastest man alive!" +}; + +MyNewApplication.propTypes = { + text: PropTypes.string +}; + +export default MyNewApplication; +``` + +
+ +__Finito!__ You now know how to share code across applications + +#### Creating a component + +Repeat all of the same steps as with an atom but place it in it's own directory +inside `components`. + +Such as `./src/components/my-new-component/my-new-component.jsx` + +### Editor example configuration + +If you use [Code](https://github.com/microsoft/vscode) we provide some easy to +use and nice defaults for this project. They are located in `.vscode.example`. +Simply rename the directory from `.vscode.example` to `.vscode` and you are good +to go. This overwrites your global user settings for this workspace and suggests +som extensions you might want. + +## Usage + +There are two ways to use the components provided by this project: + +1. As standalone JavaScript applications mounted within HTML pages generated by + a separate system. +2. As components within a larger JavaScript application (Under development) + +### Naive app mount + +So let's say you wanted to make use of an application within an existing HTML +page such as what might be generated serverside by platforms like Drupal, +WordPress etc. + +For this use case you should download the `dist.zip` package from +[the latest release of the project](/danskernesdigitalebibliotek/dpl-react/releases/latest) +and unzip somewhere within the web root of your project. The package contains a +set of artifacts needed to use one or more applications within an HTML page. + +
+ HTML Example + +A simple example of the required artifacts and how they are used looks like +this: + +```html + + + + + + + Naive mount + + + + + Here be dragons! + +
+
+ + + + + + + + + + +``` + +
+ +As a minimum you will need the `runtime.js` and `bundle.js`. For styling +of atoms and components you will need to import `components.css`. + +Each application also has its own JavaScript artifact and it might have a CSS +artifact as well. Such as `add-to-checklist.js` and `add-to-checklist.css`. + +To mount the application you need an HTML element with the correct data +attribute. + +```html +
+``` + +The name of the data attribute should be `data-dpl-app` and the value should be +the name of the application - the value of the `appName` parameter assigned in +the application `.mount.js` file. + +#### Data attributes and props + +As stated above, every application needs the corresponding `data-dpl-app` +attribute to even be mounted and shown on the page. Additional data attributes +can be passed if necessary. Examples would be contextual ids etc. Normally these +would be passed in by the serverside platform e.g. Drupal, Wordpress etc. + +```html +
+``` + +The above `data-id` would be accessed as `props.id` and `data-error-text` as +`props.errorText` in the entrypoint of an application. + +
+ Example + +```javascript +// ./src/apps/my-new-application/my-new-application.entry.jsx +import React from "react"; +import PropTypes from "prop-types"; +import MyNewApplication from './my-new-application.jsx'; + +export function MyNewApplicationEntry({ id }) { + return ( + +} + +export default MyNewApplicationEntry; +``` + +
+ +To fake this in our development environment we need to pass these same data +attributes into our entrypoint. + +
+ Example + +```javascript +// ./src/apps/my-new-application/my-new-application.dev.jsx +import React from "react"; +import MyNewApplicationEntry from "./my-new-application.entry"; +import MyNewApplication from "./my-new-application"; + +export default { title: "Apps|My new application" }; + +export function Entry() { + // Testing the version that will be shipped. + return ; +} + +export function WithoutData() { + // Play around with the application itself without server side data. + return ; +} + +``` + +
+ +## Extending the project + +If you want to extend this project - either by introducing new components or +expand the functionality of the existing ones - and your changes can be +implemented in a way that is valuable to users in general, please submit pull +requests. + +Even if that is not the case and you have special needs the infrastructure of +the project should also be helpful to you. + +In such a situation you should fork this project and extend it to your own needs +by [implementing new applications](#create-a-new-application). New applications +can reuse various levels of infrastructure provided by the project such as: + +1. [Integration with various webservices](src/core) +2. [User authentication and token management](src/core) +3. [Visual atoms or components](#cross-application-components) +4. Visual representations of [existing applications](src/apps) +5. [Styling using SCSS](#style-your-application) +6. Test infrastructure +7. [Application mounting](src/core) + +Once the customization is complete the result can be packaged for distribution +by pushing the changes to the forked repository: + +1. Changes pushed to the `master` branch of the forked repository will + automatically update the latest release of the fork. +2. Tags pushed to the forked repository also will be published as new releases + in the fork. + +The result can be [used in the same ways as the original project](#usage). diff --git a/architecture/adr-001-rehydration.md b/docs/architecture/adr-001-rehydration.md similarity index 100% rename from architecture/adr-001-rehydration.md rename to docs/architecture/adr-001-rehydration.md diff --git a/architecture/adr-002-ui-text-handling.md b/docs/architecture/adr-002-ui-text-handling.md similarity index 100% rename from architecture/adr-002-ui-text-handling.md rename to docs/architecture/adr-002-ui-text-handling.md diff --git a/architecture/adr-003-downshift.md b/docs/architecture/adr-003-downshift.md similarity index 100% rename from architecture/adr-003-downshift.md rename to docs/architecture/adr-003-downshift.md diff --git a/architecture/adr-004-relative-ci.md b/docs/architecture/adr-004-relative-ci.md similarity index 100% rename from architecture/adr-004-relative-ci.md rename to docs/architecture/adr-004-relative-ci.md diff --git a/architecture/adr-005-react-use.md b/docs/architecture/adr-005-react-use.md similarity index 100% rename from architecture/adr-005-react-use.md rename to docs/architecture/adr-005-react-use.md diff --git a/architecture/adr-006-unit-tests.md b/docs/architecture/adr-006-unit-tests.md similarity index 100% rename from architecture/adr-006-unit-tests.md rename to docs/architecture/adr-006-unit-tests.md diff --git a/docs/code_guidelines.md b/docs/code_guidelines.md index af998ead79..2d07cfff1c 100644 --- a/docs/code_guidelines.md +++ b/docs/code_guidelines.md @@ -167,7 +167,7 @@ ones which provide similar functionality. This ensures consistency and avoids unnecessary increases in the package size of the project. The reasoning behind the choice of key dependencies have been documented in -[the architecture directory](../architecture). +[the architecture directory](./architecture). ### Altering third party code diff --git a/docs/ui_text_handling.md b/docs/ui_text_handling.md index 1b4d9b631a..8b7f648cf8 100644 --- a/docs/ui_text_handling.md +++ b/docs/ui_text_handling.md @@ -9,7 +9,7 @@ The main purpose of the functionality is to be able to access strings defined at app level inside of sub components without passing them all the way down via props. You can read more about the decision -and considerations [here](../architecture/adr-002-ui-text-handling.md). +and considerations [here](../docs/architecture/adr-002-ui-text-handling.md). ## How to use it From 0a99417883c6f3252172382c4f97fad4fcf23de7 Mon Sep 17 00:00:00 2001 From: oliver-reload Date: Mon, 1 May 2023 16:38:27 +0200 Subject: [PATCH 2/2] Removed doctoc & updated documentation --- .github/workflows/pull_request.yml | 21 -- docs/README.md | 38 +--- docs/ui_text_handling.md | 2 +- package.json | 2 - yarn.lock | 295 +---------------------------- 5 files changed, 5 insertions(+), 353 deletions(-) diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index a255903586..74940516a8 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -75,27 +75,6 @@ jobs: - name: Lint Javascript run: yarn lint:js - validate_docs: - name: Validate documentation - if: '!github.event.deleted' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Setup Node - uses: actions/setup-node@v3 - with: - node-version-file: '.nvmrc' - cache: 'yarn' - registry-url: 'https://npm.pkg.github.com' - env: - NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Install Dependencies - run: yarn install - - name: Build documentation - run: yarn build:doc - - name: Validate TOC - run: git diff --exit-code - markdownlint: name: Lint markdown if: '!github.event.deleted' diff --git a/docs/README.md b/docs/README.md index 88df3ae4ba..a99a5e5888 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,44 +1,8 @@ - -![https://raw.githubusercontent.com/danskernesdigitalebibliotek/dpl-react/master/logo.png](https://raw.githubusercontent.com/danskernesdigitalebibliotek/dpl-react/master/logo.png) - -[![codecov](https://codecov.io/gh/danskernesdigitalebibliotek/dpl-react/branch/master/graph/badge.svg)](https://codecov.io/gh/danskernesdigitalebibliotek/dpl-react) +# DPL React A set of React components and applications providing self-service features for Danish public libraries. - - - - -- [Development](#development) - - [Requirements](#requirements) - - [Development - alternative (no docker)](#development---alternative-no-docker) - - [Howto](#howto) - - [Step Debugging in Visual Studio Code (no docker)](#step-debugging-in-visual-studio-code-no-docker) - - [Access tokens](#access-tokens) - - [Library token](#library-token) - - [Installation](#installation) - - [Standard and style](#standard-and-style) - - [JavaScript + JSX](#javascript--jsx) - - [Named functions Vs. Anonymous arrow functions](#named-functions-vs-anonymous-arrow-functions) - - [Create a new application](#create-a-new-application) - - [Application state-machine](#application-state-machine) - - [Style your application](#style-your-application) - - [Style using the DPL design system](#style-using-the-dpl-design-system) - - [Using unreleased design](#using-unreleased-design) - - [Cross application components](#cross-application-components) - - [Creating an atom](#creating-an-atom) - - [Creating a component](#creating-a-component) - - [Editor example configuration](#editor-example-configuration) -- [Usage](#usage) - - [Naive app mount](#naive-app-mount) - - [Data attributes and props](#data-attributes-and-props) -- [Extending the project](#extending-the-project) - - - - - ## Development ### Requirements diff --git a/docs/ui_text_handling.md b/docs/ui_text_handling.md index 8b7f648cf8..608d00d6de 100644 --- a/docs/ui_text_handling.md +++ b/docs/ui_text_handling.md @@ -9,7 +9,7 @@ The main purpose of the functionality is to be able to access strings defined at app level inside of sub components without passing them all the way down via props. You can read more about the decision -and considerations [here](../docs/architecture/adr-002-ui-text-handling.md). +and considerations [here](./architecture/adr-002-ui-text-handling.md). ## How to use it diff --git a/package.json b/package.json index c492ee1dbb..654029a1b1 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,6 @@ "watch:css": "postcss ./src/apps/**/*.scss ./src/components/components.scss --ext css --dir ./dist --watch", "watch:lint:scss": "chokidar \"./src/**/*.scss\" -c \"yarn lint:scss:fix\"", "watch:lint:js": "chokidar \"./src/**/*.{js,jsx,ts,tsx}\" -c \"yarn lint:js\"", - "build:doc": "doctoc README.md", "build:storybook": "build-storybook -c .storybook -o dev", "start:storybook:test": "NODE_ENV=test start-storybook --port 57021 --quiet --ci", "start:storybook:dev": "NODE_ENV=development start-storybook --port 80", @@ -92,7 +91,6 @@ "css-loader": "^6.7.1", "cssnano": "^5.1.7", "cypress": "^9.6.1", - "doctoc": "^2.2.0", "eslint": "^8.15.0", "eslint-config-airbnb": "^19.0.4", "eslint-config-airbnb-typescript": "^17.0.0", diff --git a/yarn.lock b/yarn.lock index cae9781d12..a60903d35e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4506,25 +4506,6 @@ "@babel/runtime" "^7.12.5" react-error-boundary "^3.1.0" -"@textlint/ast-node-types@^12.1.1": - version "12.1.1" - resolved "https://registry.npmjs.org/@textlint/ast-node-types/-/ast-node-types-12.1.1.tgz" - integrity sha512-5/XK9S1177UYetOY6407o1RDuNVndaYfuzsZwhmo52V367s4ZuUD2064WhbmCd6TPyKD4dVr2zoWjfNDfzUZQg== - -"@textlint/markdown-to-ast@^12.1.1": - version "12.1.1" - resolved "https://registry.npmjs.org/@textlint/markdown-to-ast/-/markdown-to-ast-12.1.1.tgz" - integrity sha512-TmqFyNqi68YpkqKabrkMlPzeSJMfY/+Wsv1/r43uDFgSYyM9GiD0eIpP12uKyL8xLW+rgfbqXxeFwSo26Conqw== - dependencies: - "@textlint/ast-node-types" "^12.1.1" - debug "^4.3.3" - remark-footnotes "^3.0.0" - remark-frontmatter "^3.0.0" - remark-gfm "^1.0.0" - remark-parse "^9.0.0" - traverse "^0.6.6" - unified "^9.2.2" - "@tootallnate/once@1": version "1.1.2" resolved "https://registry.npmjs.org/@tootallnate/once/-/once-1.1.2.tgz" @@ -5694,13 +5675,6 @@ ajv@^8.0.0, ajv@^8.0.1, ajv@^8.6.0, ajv@^8.6.3, ajv@^8.8.0, ajv@^8.8.2: require-from-string "^2.0.2" uri-js "^4.2.2" -anchor-markdown-header@^0.5.7: - version "0.5.7" - resolved "https://registry.npmjs.org/anchor-markdown-header/-/anchor-markdown-header-0.5.7.tgz" - integrity sha1-BFBj125qH5zTJ6V6ASaqD97Dcac= - dependencies: - emoji-regex "~6.1.0" - ansi-align@^3.0.0: version "3.0.0" resolved "https://registry.npmjs.org/ansi-align/-/ansi-align-3.0.0.tgz" @@ -8479,7 +8453,7 @@ debug@2.6.9, debug@^2.2.0, debug@^2.3.3, debug@^2.6.0, debug@^2.6.9: dependencies: ms "2.0.0" -debug@4, debug@^4.0.0, debug@^4.1.0, debug@^4.1.1, debug@^4.3.1, debug@^4.3.2, debug@^4.3.3, debug@^4.3.4: +debug@4, debug@^4.1.0, debug@^4.1.1, debug@^4.3.1, debug@^4.3.2, debug@^4.3.3, debug@^4.3.4: version "4.3.4" resolved "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz" integrity sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ== @@ -8783,18 +8757,6 @@ dir-glob@^3.0.1: dependencies: path-type "^4.0.0" -doctoc@^2.2.0: - version "2.2.0" - resolved "https://registry.npmjs.org/doctoc/-/doctoc-2.2.0.tgz" - integrity sha512-PtiyaS+S3kcMbpx6x2V0S+PeDKisxmjEFnZsuYkkj4Lh3ObozJuuYh9dM4+sX02Ouuty8RF2LOCnIbpu/hWy/A== - dependencies: - "@textlint/markdown-to-ast" "^12.1.1" - anchor-markdown-header "^0.5.7" - htmlparser2 "^7.2.0" - minimist "^1.2.6" - underscore "^1.13.2" - update-section "^0.3.3" - doctrine@^2.1.0: version "2.1.0" resolved "https://registry.npmjs.org/doctrine/-/doctrine-2.1.0.tgz" @@ -8865,7 +8827,7 @@ domhandler@^2.3.0: dependencies: domelementtype "1" -domhandler@^4.0.0, domhandler@^4.2.0, domhandler@^4.2.2, domhandler@^4.3.1: +domhandler@^4.0.0, domhandler@^4.2.0, domhandler@^4.3.1: version "4.3.1" resolved "https://registry.npmjs.org/domhandler/-/domhandler-4.3.1.tgz" integrity sha512-GrwoxYN+uWlzO8uhUXRl0P+kHE4GtVPfYzVLcUxPL7KNdHKj66vvlhiweIHqYYXWlw+T8iLMp42Lm67ghw4WMQ== @@ -9061,11 +9023,6 @@ emoji-regex@^9.2.2: resolved "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz" integrity sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg== -emoji-regex@~6.1.0: - version "6.1.3" - resolved "https://registry.npmjs.org/emoji-regex/-/emoji-regex-6.1.3.tgz" - integrity sha1-7HmjlpsC0uzytyJUJ5v5m8eoOTI= - emojis-list@^2.0.0: version "2.1.0" resolved "https://registry.npmjs.org/emojis-list/-/emojis-list-2.1.0.tgz" @@ -9147,11 +9104,6 @@ entities@^2.0.0: resolved "https://registry.npmjs.org/entities/-/entities-2.0.0.tgz" integrity sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw== -entities@^3.0.1: - version "3.0.1" - resolved "https://registry.npmjs.org/entities/-/entities-3.0.1.tgz" - integrity sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q== - entities@~2.1.0: version "2.1.0" resolved "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz" @@ -11551,16 +11503,6 @@ htmlparser2@^6.1.0: domutils "^2.5.2" entities "^2.0.0" -htmlparser2@^7.2.0: - version "7.2.0" - resolved "https://registry.npmjs.org/htmlparser2/-/htmlparser2-7.2.0.tgz" - integrity sha512-H7MImA4MS6cw7nbyURtLPO1Tms7C5H602LRETv95z1MxO/7CP7rDVROehUYeYBUYEON94NXXDEPmZuq+hX4sog== - dependencies: - domelementtype "^2.0.1" - domhandler "^4.2.2" - domutils "^2.8.0" - entities "^3.0.1" - http-basic@^8.1.1: version "8.1.3" resolved "https://registry.yarnpkg.com/http-basic/-/http-basic-8.1.3.tgz#a7cabee7526869b9b710136970805b1004261bbf" @@ -13530,11 +13472,6 @@ log-update@^4.0.0: slice-ansi "^4.0.0" wrap-ansi "^6.2.0" -longest-streak@^2.0.0: - version "2.0.4" - resolved "https://registry.npmjs.org/longest-streak/-/longest-streak-2.0.4.tgz" - integrity sha512-vM6rUVCVUJJt33bnmHiZEvr7wPT78ztX7rojL+LW51bHtLh6HTjx84LA5W4+oa6aKEJA7jJu5LR6vQRBpA5DVg== - loose-envify@^1.0.0, loose-envify@^1.1.0, loose-envify@^1.4.0: version "1.4.0" resolved "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz" @@ -13716,13 +13653,6 @@ markdown-it@12.3.2: mdurl "^1.0.1" uc.micro "^1.0.5" -markdown-table@^2.0.0: - version "2.0.0" - resolved "https://registry.npmjs.org/markdown-table/-/markdown-table-2.0.0.tgz" - integrity sha512-Ezda85ToJUBhM6WGaG6veasyym+Tbs3cMAw/ZhOPqXiYsr0jgocBV3j3nx+4lk47plLlIqjwuTm/ywVI+zjJ/A== - dependencies: - repeat-string "^1.0.0" - markdown-to-jsx@^7.1.0: version "7.1.7" resolved "https://registry.npmjs.org/markdown-to-jsx/-/markdown-to-jsx-7.1.7.tgz" @@ -13801,83 +13731,6 @@ mdast-util-definitions@^4.0.0: dependencies: unist-util-visit "^2.0.0" -mdast-util-find-and-replace@^1.1.0: - version "1.1.1" - resolved "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-1.1.1.tgz" - integrity sha512-9cKl33Y21lyckGzpSmEQnIDjEfeeWelN5s1kUW1LwdB0Fkuq2u+4GdqcGEygYxJE8GVqCl0741bYXHgamfWAZA== - dependencies: - escape-string-regexp "^4.0.0" - unist-util-is "^4.0.0" - unist-util-visit-parents "^3.0.0" - -mdast-util-footnote@^0.1.0: - version "0.1.7" - resolved "https://registry.npmjs.org/mdast-util-footnote/-/mdast-util-footnote-0.1.7.tgz" - integrity sha512-QxNdO8qSxqbO2e3m09KwDKfWiLgqyCurdWTQ198NpbZ2hxntdc+VKS4fDJCmNWbAroUdYnSthu+XbZ8ovh8C3w== - dependencies: - mdast-util-to-markdown "^0.6.0" - micromark "~2.11.0" - -mdast-util-from-markdown@^0.8.0: - version "0.8.5" - resolved "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-0.8.5.tgz" - integrity sha512-2hkTXtYYnr+NubD/g6KGBS/0mFmBcifAsI0yIWRiRo0PjVs6SSOSOdtzbp6kSGnShDN6G5aWZpKQ2lWRy27mWQ== - dependencies: - "@types/mdast" "^3.0.0" - mdast-util-to-string "^2.0.0" - micromark "~2.11.0" - parse-entities "^2.0.0" - unist-util-stringify-position "^2.0.0" - -mdast-util-frontmatter@^0.2.0: - version "0.2.0" - resolved "https://registry.npmjs.org/mdast-util-frontmatter/-/mdast-util-frontmatter-0.2.0.tgz" - integrity sha512-FHKL4w4S5fdt1KjJCwB0178WJ0evnyyQr5kXTM3wrOVpytD0hrkvd+AOOjU9Td8onOejCkmZ+HQRT3CZ3coHHQ== - dependencies: - micromark-extension-frontmatter "^0.2.0" - -mdast-util-gfm-autolink-literal@^0.1.0: - version "0.1.3" - resolved "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-0.1.3.tgz" - integrity sha512-GjmLjWrXg1wqMIO9+ZsRik/s7PLwTaeCHVB7vRxUwLntZc8mzmTsLVr6HW1yLokcnhfURsn5zmSVdi3/xWWu1A== - dependencies: - ccount "^1.0.0" - mdast-util-find-and-replace "^1.1.0" - micromark "^2.11.3" - -mdast-util-gfm-strikethrough@^0.2.0: - version "0.2.3" - resolved "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-0.2.3.tgz" - integrity sha512-5OQLXpt6qdbttcDG/UxYY7Yjj3e8P7X16LzvpX8pIQPYJ/C2Z1qFGMmcw+1PZMUM3Z8wt8NRfYTvCni93mgsgA== - dependencies: - mdast-util-to-markdown "^0.6.0" - -mdast-util-gfm-table@^0.1.0: - version "0.1.6" - resolved "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-0.1.6.tgz" - integrity sha512-j4yDxQ66AJSBwGkbpFEp9uG/LS1tZV3P33fN1gkyRB2LoRL+RR3f76m0HPHaby6F4Z5xr9Fv1URmATlRRUIpRQ== - dependencies: - markdown-table "^2.0.0" - mdast-util-to-markdown "~0.6.0" - -mdast-util-gfm-task-list-item@^0.1.0: - version "0.1.6" - resolved "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-0.1.6.tgz" - integrity sha512-/d51FFIfPsSmCIRNp7E6pozM9z1GYPIkSy1urQ8s/o4TC22BZ7DqfHFWiqBD23bc7J3vV1Fc9O4QIHBlfuit8A== - dependencies: - mdast-util-to-markdown "~0.6.0" - -mdast-util-gfm@^0.1.0: - version "0.1.2" - resolved "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-0.1.2.tgz" - integrity sha512-NNkhDx/qYcuOWB7xHUGWZYVXvjPFFd6afg6/e2g+SV4r9q5XUcCbV4Wfa3DLYIiD+xAEZc6K4MGaE/m0KDcPwQ== - dependencies: - mdast-util-gfm-autolink-literal "^0.1.0" - mdast-util-gfm-strikethrough "^0.2.0" - mdast-util-gfm-table "^0.1.0" - mdast-util-gfm-task-list-item "^0.1.0" - mdast-util-to-markdown "^0.6.1" - mdast-util-to-hast@10.0.1: version "10.0.1" resolved "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-10.0.1.tgz" @@ -13892,28 +13745,11 @@ mdast-util-to-hast@10.0.1: unist-util-position "^3.0.0" unist-util-visit "^2.0.0" -mdast-util-to-markdown@^0.6.0, mdast-util-to-markdown@^0.6.1, mdast-util-to-markdown@~0.6.0: - version "0.6.5" - resolved "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-0.6.5.tgz" - integrity sha512-XeV9sDE7ZlOQvs45C9UKMtfTcctcaj/pGwH8YLbMHoMOXNNCn2LsqVQOqrF1+/NU8lKDAqozme9SCXWyo9oAcQ== - dependencies: - "@types/unist" "^2.0.0" - longest-streak "^2.0.0" - mdast-util-to-string "^2.0.0" - parse-entities "^2.0.0" - repeat-string "^1.0.0" - zwitch "^1.0.0" - mdast-util-to-string@^1.0.0: version "1.1.0" resolved "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-1.1.0.tgz" integrity sha512-jVU0Nr2B9X3MU4tSK7JP1CMkSvOj7X5l/GboG1tKRw52lLF1x2Ju92Ms9tNetCcbfX3hzlM73zYo2NKkWSfF/A== -mdast-util-to-string@^2.0.0: - version "2.0.0" - resolved "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-2.0.0.tgz" - integrity sha512-AW4DRS3QbBayY/jJmD8437V1Gombjf8RSOUCMFBuo5iHi58AGEgVCKQ+ezHkZZDpAQS75hcBMpLqjpJTjtUL7w== - mdn-data@2.0.14: version "2.0.14" resolved "https://registry.npmjs.org/mdn-data/-/mdn-data-2.0.14.tgz" @@ -14036,73 +13872,6 @@ microevent.ts@~0.1.1: resolved "https://registry.npmjs.org/microevent.ts/-/microevent.ts-0.1.1.tgz" integrity sha512-jo1OfR4TaEwd5HOrt5+tAZ9mqT4jmpNAusXtyfNzqVm9uiSYFZlKM1wYL4oU7azZW/PxQW53wM0S6OR1JHNa2g== -micromark-extension-footnote@^0.3.0: - version "0.3.2" - resolved "https://registry.npmjs.org/micromark-extension-footnote/-/micromark-extension-footnote-0.3.2.tgz" - integrity sha512-gr/BeIxbIWQoUm02cIfK7mdMZ/fbroRpLsck4kvFtjbzP4yi+OPVbnukTc/zy0i7spC2xYE/dbX1Sur8BEDJsQ== - dependencies: - micromark "~2.11.0" - -micromark-extension-frontmatter@^0.2.0: - version "0.2.2" - resolved "https://registry.npmjs.org/micromark-extension-frontmatter/-/micromark-extension-frontmatter-0.2.2.tgz" - integrity sha512-q6nPLFCMTLtfsctAuS0Xh4vaolxSFUWUWR6PZSrXXiRy+SANGllpcqdXFv2z07l0Xz/6Hl40hK0ffNCJPH2n1A== - dependencies: - fault "^1.0.0" - -micromark-extension-gfm-autolink-literal@~0.5.0: - version "0.5.7" - resolved "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-0.5.7.tgz" - integrity sha512-ePiDGH0/lhcngCe8FtH4ARFoxKTUelMp4L7Gg2pujYD5CSMb9PbblnyL+AAMud/SNMyusbS2XDSiPIRcQoNFAw== - dependencies: - micromark "~2.11.3" - -micromark-extension-gfm-strikethrough@~0.6.5: - version "0.6.5" - resolved "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-0.6.5.tgz" - integrity sha512-PpOKlgokpQRwUesRwWEp+fHjGGkZEejj83k9gU5iXCbDG+XBA92BqnRKYJdfqfkrRcZRgGuPuXb7DaK/DmxOhw== - dependencies: - micromark "~2.11.0" - -micromark-extension-gfm-table@~0.4.0: - version "0.4.3" - resolved "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-0.4.3.tgz" - integrity sha512-hVGvESPq0fk6ALWtomcwmgLvH8ZSVpcPjzi0AjPclB9FsVRgMtGZkUcpE0zgjOCFAznKepF4z3hX8z6e3HODdA== - dependencies: - micromark "~2.11.0" - -micromark-extension-gfm-tagfilter@~0.3.0: - version "0.3.0" - resolved "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-0.3.0.tgz" - integrity sha512-9GU0xBatryXifL//FJH+tAZ6i240xQuFrSL7mYi8f4oZSbc+NvXjkrHemeYP0+L4ZUT+Ptz3b95zhUZnMtoi/Q== - -micromark-extension-gfm-task-list-item@~0.3.0: - version "0.3.3" - resolved "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-0.3.3.tgz" - integrity sha512-0zvM5iSLKrc/NQl84pZSjGo66aTGd57C1idmlWmE87lkMcXrTxg1uXa/nXomxJytoje9trP0NDLvw4bZ/Z/XCQ== - dependencies: - micromark "~2.11.0" - -micromark-extension-gfm@^0.3.0: - version "0.3.3" - resolved "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-0.3.3.tgz" - integrity sha512-oVN4zv5/tAIA+l3GbMi7lWeYpJ14oQyJ3uEim20ktYFAcfX1x3LNlFGGlmrZHt7u9YlKExmyJdDGaTt6cMSR/A== - dependencies: - micromark "~2.11.0" - micromark-extension-gfm-autolink-literal "~0.5.0" - micromark-extension-gfm-strikethrough "~0.6.5" - micromark-extension-gfm-table "~0.4.0" - micromark-extension-gfm-tagfilter "~0.3.0" - micromark-extension-gfm-task-list-item "~0.3.0" - -micromark@^2.11.3, micromark@~2.11.0, micromark@~2.11.3: - version "2.11.4" - resolved "https://registry.npmjs.org/micromark/-/micromark-2.11.4.tgz" - integrity sha512-+WoovN/ppKolQOFIAajxi7Lu9kInbPxFuTBVEavFcL8eAfVstoc5MocPmqBeAdBOJV00uaVjegzH4+MA0DN/uA== - dependencies: - debug "^4.0.0" - parse-entities "^2.0.0" - micromatch@4.0.4, micromatch@^4.0.4: version "4.0.4" resolved "https://registry.npmjs.org/micromatch/-/micromatch-4.0.4.tgz" @@ -17389,30 +17158,6 @@ remark-footnotes@2.0.0: resolved "https://registry.npmjs.org/remark-footnotes/-/remark-footnotes-2.0.0.tgz" integrity sha512-3Clt8ZMH75Ayjp9q4CorNeyjwIxHFcTkaektplKGl2A1jNGEUey8cKL0ZC5vJwfcD5GFGsNLImLG/NGzWIzoMQ== -remark-footnotes@^3.0.0: - version "3.0.0" - resolved "https://registry.npmjs.org/remark-footnotes/-/remark-footnotes-3.0.0.tgz" - integrity sha512-ZssAvH9FjGYlJ/PBVKdSmfyPc3Cz4rTWgZLI4iE/SX8Nt5l3o3oEjv3wwG5VD7xOjktzdwp5coac+kJV9l4jgg== - dependencies: - mdast-util-footnote "^0.1.0" - micromark-extension-footnote "^0.3.0" - -remark-frontmatter@^3.0.0: - version "3.0.0" - resolved "https://registry.npmjs.org/remark-frontmatter/-/remark-frontmatter-3.0.0.tgz" - integrity sha512-mSuDd3svCHs+2PyO29h7iijIZx4plX0fheacJcAoYAASfgzgVIcXGYSq9GFyYocFLftQs8IOmmkgtOovs6d4oA== - dependencies: - mdast-util-frontmatter "^0.2.0" - micromark-extension-frontmatter "^0.2.0" - -remark-gfm@^1.0.0: - version "1.0.0" - resolved "https://registry.npmjs.org/remark-gfm/-/remark-gfm-1.0.0.tgz" - integrity sha512-KfexHJCiqvrdBZVbQ6RopMZGwaXz6wFJEfByIuEwGf0arvITHjiKKZ1dpXujjH9KZdm1//XJQwgfnJ3lmXaDPA== - dependencies: - mdast-util-gfm "^0.1.0" - micromark-extension-gfm "^0.3.0" - remark-mdx@1.6.22: version "1.6.22" resolved "https://registry.npmjs.org/remark-mdx/-/remark-mdx-1.6.22.tgz" @@ -17449,13 +17194,6 @@ remark-parse@8.0.3: vfile-location "^3.0.0" xtend "^4.0.1" -remark-parse@^9.0.0: - version "9.0.0" - resolved "https://registry.npmjs.org/remark-parse/-/remark-parse-9.0.0.tgz" - integrity sha512-geKatMwSzEXKHuzBNU1z676sGcDcFoChMK38TgdHJNAYfFtsfHDQG7MoJAjs6sgYMqyLduCYWDIWZIxiPeafEw== - dependencies: - mdast-util-from-markdown "^0.8.0" - remark-slug@^6.0.0: version "6.0.0" resolved "https://registry.npmjs.org/remark-slug/-/remark-slug-6.0.0.tgz" @@ -17519,7 +17257,7 @@ repeat-element@^1.1.2: resolved "https://registry.npmjs.org/repeat-element/-/repeat-element-1.1.3.tgz" integrity sha512-ahGq0ZnV5m5XtZLMb+vP76kcAM5nkLqk0lpqAuojSKGgQtn4eRi4ZZGm2olo2zKFH+sMsWaqOCW1dqAnOru72g== -repeat-string@^1.0.0, repeat-string@^1.5.4, repeat-string@^1.6.1: +repeat-string@^1.5.4, repeat-string@^1.6.1: version "1.6.1" resolved "https://registry.npmjs.org/repeat-string/-/repeat-string-1.6.1.tgz" integrity sha1-jcrkcOHIirwtYA//Sndihtp15jc= @@ -19658,11 +19396,6 @@ tr46@~0.0.3: resolved "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz" integrity sha1-gYT9NH2snNwYWZLzpmIuFLnZq2o= -traverse@^0.6.6: - version "0.6.6" - resolved "https://registry.npmjs.org/traverse/-/traverse-0.6.6.tgz" - integrity sha1-y99WD9e5r2MlAv7UD5GMFX6pcTc= - tree-kill@^1.2.2: version "1.2.2" resolved "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz" @@ -19968,11 +19701,6 @@ undeclared-identifiers@^1.1.2: simple-concat "^1.0.0" xtend "^4.0.1" -underscore@^1.13.2: - version "1.13.3" - resolved "https://registry.npmjs.org/underscore/-/underscore-1.13.3.tgz" - integrity sha512-QvjkYpiD+dJJraRA8+dGAU4i7aBbb2s0S3jA45TFOvg2VgqvdCDd/3N6CqA8gluk1W91GLoXg5enMUx560QzuA== - underscore@~1.6.0: version "1.6.0" resolved "https://registry.npmjs.org/underscore/-/underscore-1.6.0.tgz" @@ -20054,18 +19782,6 @@ unified@9.2.0: trough "^1.0.0" vfile "^4.0.0" -unified@^9.2.2: - version "9.2.2" - resolved "https://registry.npmjs.org/unified/-/unified-9.2.2.tgz" - integrity sha512-Sg7j110mtefBD+qunSLO1lqOEKdrwBFBrR6Qd8f4uwkhWNlbkaqwHse6e7QvD3AP/MNoJdEDLaf8OxYyoWgorQ== - dependencies: - bail "^1.0.0" - extend "^3.0.0" - is-buffer "^2.0.0" - is-plain-obj "^2.0.0" - trough "^1.0.0" - vfile "^4.0.0" - union-value@^1.0.0: version "1.0.1" resolved "https://registry.npmjs.org/union-value/-/union-value-1.0.1.tgz" @@ -20244,11 +19960,6 @@ update-notifier@^4.1.3: semver-diff "^3.1.1" xdg-basedir "^4.0.0" -update-section@^0.3.3: - version "0.3.3" - resolved "https://registry.npmjs.org/update-section/-/update-section-0.3.3.tgz" - integrity sha1-RY8Xgg03gg3GDiC4bZQ5GwASMVg= - upper-case-first@^2.0.2: version "2.0.2" resolved "https://registry.npmjs.org/upper-case-first/-/upper-case-first-2.0.2.tgz"