@guardian/interactive-component-library 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,39 @@
+Copyright (c) [2024] Guardian News and Media
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+The repository is based on this template: https://github.com/IgnacioNMiranda/vite-component-library-template. License included here:
+
+MIT License
+
+Copyright (c) [2023] [Ignacio Andrés Miranda Figueroa]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# `@guardian/interactive-component-library`
+
+A set of reusable components for use in interactive pages, written in Preact using [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/) principles.
+
+## Install the component library in a new client project
+
+From [Github Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry):
+
+1. [Create a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `read:packages` scope.
+2. Create a file called `.npmrc` in the root of your new project and add the following:
+
+```
+@guardian:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
+```
+
+3. Install using npm:
+
+```
+npm i @guardian/interactive-component-library
+```
+
+## Contributing to this repository
+
+> Building the project requires Node v16.18.1 or higher.
+
+1. Clone this repository
+2. Run `corepack enable` to enable pnpm
+3. Install dependencies with `pnpm i`
+4. Run `pnpm dev` to start the local Storybook server
+
+### Atomic design
+
+The component library is structured according to [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/) principles, using the bottom three levels.
+
+1. Particles (renamed from `atoms` for obvious reasons)
+2. Molecules
+3. Organisms
+
+Particles are the lowest level components that form the building blocks for everything else, e.g. a Button. Molecules represent more complex components (e.g. a Table) and often depend on particle components. Organisms combine the previous two levels into distinct sections of an interactive page, e.g. KeySeats.
+
+Folders use the same naming structure, with `particles`, `molecules` and `organisms` folders in `src/lib/components`, to distinguish between the three different levels.
+
+### Adding a new component
+
+Create a folder for your new component in the appropriate directory. The name of the folder should be the name of your component in [Kebab case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case), i.e. `src/lib/components/particles/my-new-component`.
+
+The folder should contain the following:
+
+- `index.jsx` containing the code for the actual component
+- `[component-name].stories.jsx` containing examples of how to use the component, written as [Storybook stories](https://storybook.js.org/docs/writing-stories)
+- `docs.mdx` (optional) additional documentation for the component in Storybook
+
+### Developing and testing locally
+
+During development, you'll often want to see how a component looks in the interactive page that you're working on, without rebuilding and publishing a new version of the component library. To facilitate this workflow, we use [npm-link](https://docs.npmjs.com/cli/v10/commands/npm-link).
+
+Here's how to set that up:
+
+```
+cd ~/projects/interactive-component-library       # go into the package directory
+npm link                                          # creates global link
+cd ~/projects/interactive-project                 # go into your project directory
+npm link @guardian/interactive-component-library  # link-install the package
+```
+
+After you've done that, run `pnpm build:lib:watch` to package the library and rebuild on file changes.
+
+To revert back to the version specified in your project‘s `package.json`:
+
+```
+npm uninstall --no-save @guardian/interactive-component-library && npm install
+```
+
+### Publishing a new version
+
+To publish a new version of the component library, follow these steps:
+
+1. Update the version number in `package.json`
+2. [Create a new release](https://github.com/guardian/interactive-component-library/releases/new) on GitHub (don't forget to write some release notes)
+3. Publishing the release [triggers a workflow](https://github.com/guardian/interactive-component-library/actions) to package the library and publish it to Github Packages. If the publish actions fails, you can also trigger it manually
+
+## Scripts
+
+Always prepending `pnpm`:
+
+- `dev`: Start Storybook for local development
+- `build`: Builds the static storybook project
+- `build:lib`: Builds the component library into the **dist** folder
+- `build:lib:watch`: Same as previous command, but it watches `/src` folder and rebuilds on changes
+
+## Testing for dark mode in Storybook
+Use the sun/moon button in the toolbar to switch between light and dark mode.
+![Screenshot 2024-03-27 at 08 24 43](https://github.com/guardian/interactive-component-library/assets/1107150/3a93adfc-56da-4c1d-b5b8-dc7ff5aedfbf)
+![Screenshot 2024-03-27 at 08 24 32](https://github.com/guardian/interactive-component-library/assets/1107150/bad208aa-7967-446f-b658-e937aa2d114b)
+
+Enabling dark mode applies `.ios` and `.dark-mode` classes to the `<body>` element, which in turn renders the story preview with dark mode colours (this behaviour can be customised in `.storybook/preview.scss`).
+
+> Note that enabling dark mode using this button does not affect the [`prefers-color-scheme` CSS media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). If your component uses `prefers-color-scheme` directly, you will also need to change your system or browser setting to see that styling take effect.
+
+## License
+
+[Apache 2.0](LICENSE)