Create @guardian/source-development-kitchen (#1459)

Co-authored-by: Oliver Abrahams <ollie.abrahams@guardian.co.uk>

.changeset/config.json

@@ -8,7 +8,7 @@
 	"baseBranch": "main",
 	"updateInternalDependencies": "patch",
 	"bumpVersionsWithWorkspaceProtocolOnly": true,
-	"ignore": ["github-pages", "configs"],
+	"ignore": ["github-pages", "@configs/*"],
 	"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
 		"onlyUpdatePeerDependentsWhenOutOfRange": true
 	}

.changeset/shy-timers-bow.md

@@ -0,0 +1,5 @@
+---
+'@guardian/source-development-kitchen': minor
+---
+
+Create `@guardian/source-development-kitchen`

Makefile

@@ -445,6 +445,38 @@ install: check-node-version
 @guardian/source\:verify-dist: env
 	@corepack pnpm --filter @guardian/source verify-dist
 
+.PHONY: @guardian/source-development-kitchen\:build
+@guardian/source-development-kitchen\:build: env
+	@corepack pnpm --filter @guardian/source-development-kitchen build
+
+.PHONY: @guardian/source-development-kitchen\:build-storybook
+@guardian/source-development-kitchen\:build-storybook: env
+	@corepack pnpm --filter @guardian/source-development-kitchen build-storybook
+
+.PHONY: @guardian/source-development-kitchen\:dev
+@guardian/source-development-kitchen\:dev: env
+	@corepack pnpm --filter @guardian/source-development-kitchen dev
+
+.PHONY: @guardian/source-development-kitchen\:fix
+@guardian/source-development-kitchen\:fix: env
+	@corepack pnpm --filter @guardian/source-development-kitchen fix
+
+.PHONY: @guardian/source-development-kitchen\:lint
+@guardian/source-development-kitchen\:lint: env
+	@corepack pnpm --filter @guardian/source-development-kitchen lint
+
+.PHONY: @guardian/source-development-kitchen\:storybook
+@guardian/source-development-kitchen\:storybook: env
+	@corepack pnpm --filter @guardian/source-development-kitchen storybook
+
+.PHONY: @guardian/source-development-kitchen\:test
+@guardian/source-development-kitchen\:test: env
+	@corepack pnpm --filter @guardian/source-development-kitchen test
+
+.PHONY: @guardian/source-development-kitchen\:verify-dist
+@guardian/source-development-kitchen\:verify-dist: env
+	@corepack pnpm --filter @guardian/source-development-kitchen verify-dist
+
 .PHONY: @guardian/source-foundations\:build
 @guardian/source-foundations\:build: env
 	@corepack pnpm --filter @guardian/source-foundations build

README.md

@@ -28,6 +28,7 @@ The following packages live in `libs/@guardian/*` and are published to NPM:
 - [@guardian/newsletter-types](libs/@guardian/newsletter-types)
 - [@guardian/prettier](libs/@guardian/prettier)
 - [@guardian/source](libs/@guardian/source)
+- [@guardian/source-development-kitchen](libs/@guardian/source-development-kitchen)
 - [@guardian/source-foundations](libs/@guardian/source-foundations)
 - [@guardian/source-react-components](libs/@guardian/source-react-components)
 - [@guardian/source-react-components-development-kitchen](libs/@guardian/source-react-components-development-kitchen)
@@ -199,6 +200,17 @@ Project-specific tasks are defined as `scripts` in a `package.json` or `targets`
 - `make @guardian/source:test`
 - `make @guardian/source:verify-dist`
 
+#### @guardian/source-development-kitchen
+
+- `make @guardian/source-development-kitchen:build`
+- `make @guardian/source-development-kitchen:build-storybook`
+- `make @guardian/source-development-kitchen:dev`
+- `make @guardian/source-development-kitchen:fix`
+- `make @guardian/source-development-kitchen:lint`
+- `make @guardian/source-development-kitchen:storybook`
+- `make @guardian/source-development-kitchen:test`
+- `make @guardian/source-development-kitchen:verify-dist`
+
 #### @guardian/source-foundations
 
 - `make @guardian/source-foundations:build`

apps/storybooks/.storybook/main.js

@@ -39,6 +39,11 @@ module.exports = {
 				// port set in libs/@guardian/source/package.json
 				url: 'http://localhost:4404',
 			},
+			'source-development-kitchen': {
+				title: 'source-development-kitchen',
+				// port set in libs/@guardian/source-development-kitchen/package.json
+				url: 'http://localhost:4405',
+			},
 		};
 	},
 };

libs/@guardian/source-development-kitchen/.eslintrc.cjs

@@ -0,0 +1,45 @@
+module.exports = {
+	extends: ['../../../.eslintrc.cjs'],
+	ignorePatterns: [
+		'!**/*',
+		'node_modules',
+		'jest.dist.*', // depends on build output, so don't lint it
+		'dist',
+		'storybook-static',
+		'.wireit',
+	],
+	overrides: [
+		{
+			files: ['*.ts', '*.tsx'],
+			parserOptions: {
+				tsconfigRootDir: __dirname,
+			},
+			rules: {},
+		},
+		{
+			files: ['*.js', '*.jsx'],
+			rules: {},
+		},
+		{
+			files: ['*.test.ts'],
+			rules: {
+				'@typescript-eslint/no-unsafe-call': 'off',
+				'@typescript-eslint/no-unsafe-assignment': 'off',
+				'@typescript-eslint/restrict-template-expressions': 'off',
+				'@typescript-eslint/no-unsafe-member-access': 'off',
+			},
+		},
+		{
+			// these are only internal files, so we don't need to check them so
+			// rigorously they often use things like JSON which are `any`s too,
+			// we can be more lenient
+			files: ['scripts/**/*'],
+			rules: {
+				'@typescript-eslint/no-unsafe-assignment': 'off',
+				'@typescript-eslint/no-unsafe-member-access': 'off',
+				'@typescript-eslint/explicit-module-boundary-types': 'off',
+				'@typescript-eslint/no-unsafe-return': 'off',
+			},
+		},
+	],
+};

libs/@guardian/source-development-kitchen/.storybook/main.js

@@ -0,0 +1,22 @@
+const rootMain = require('../../../../configs/storybook/main');
+
+// To customise your Storybook config for this project, update this file
+
+module.exports = {
+	...rootMain,
+
+	core: { ...rootMain.core },
+
+	stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+	addons: [...rootMain.addons],
+	webpackFinal: async (config, { configType }) => {
+		// apply any global webpack configs that might have been specified in .storybook/main.js
+		if (rootMain.webpackFinal) {
+			config = await rootMain.webpackFinal(config, { configType });
+		}
+
+		// add your own webpack tweaks if needed
+
+		return config;
+	},
+};

libs/@guardian/source-development-kitchen/.storybook/manager.ts

@@ -0,0 +1,6 @@
+import { addons } from '@storybook/manager-api';
+import { createTheme } from '../../../../configs/storybook/theme';
+
+addons.setConfig({
+	theme: createTheme('@guardian/source-development-kitchen'),
+});

libs/@guardian/source-development-kitchen/.storybook/preview.ts

@@ -0,0 +1 @@
+export { decorators, parameters } from '../../../../configs/storybook/preview';

libs/@guardian/source-development-kitchen/README.md

@@ -0,0 +1,76 @@
+# `@guardian/source-development-kitchen`
+
+[![npm](https://img.shields.io/npm/v/@guardian/source-development-kitchen)](https://www.npmjs.com/package/@guardian/source-development-kitchen)
+
+The Source Development Kitchen is where new components and patterns can be cooked up, tested and shared. There are minimal acceptance criteria. It’s okay to duplicate and break things. If a Kitchen component proves valuable, it may be promoted to `@guardian/source`.
+
+This package is part of the [Source design system](/docs/source/README.md).
+
+## Install
+
+```sh
+$ pnpm add @guardian/source-development-kitchen
+```
+
+or
+
+```sh
+$ yarn add @guardian/source-development-kitchen
+```
+
+or
+
+```sh
+$ npm install @guardian/source-development-kitchen
+```
+
+## Example
+
+```tsx
+import { Lines } from '@guardian/source-development-kitchen/react-components';
+
+const Section = () => (
+	<>
+		<Lines count={8} />
+		<Lines effect="squiggly" />
+	</>
+);
+```
+
+## Documentation
+
+Full documentation is available in the [Source Development Kitchen storybook](https://guardian.github.io/storybooks).
+
+## Ownership
+
+Kitchen components are unsupported by CSTI. They are owned by the team or teams consuming them.
+
+Owners are defined in [CODEOWNERS](https://github.com/guardian/csnx/tree/main/.github/CODEOWNERS).
+
+If you wish to start consuming a Kitchen component, add your team as CODEOWNERS. This ensures you are notified of changes to the component.
+
+## Evolution
+
+Changes to Kitchen components are to be expected. Components in the Kitchen should be considered experimental and likely to change in ways that break things.
+
+Components that prove valuable may be promoted to `@guardian/source`. In order to achieve this, the component must meet Source’s [acceptance criteria](https://theguardian.design/2a1e5182b/p/11c92e-acceptance-criteria). The best way to meet these is for developers to work in close collaboration with design and UX when building and evolving a component. Components should express some pattern, rule or aspect of design that is governed by Source.
+
+## Motivation
+
+Source is a library where teams can expect to find high quality shared components. Adding new components to Source requires deep work and collaboration across disciplines – design, UX and engineering. It takes a long time and substantial effort for components to land in Source.
+
+Potential contributors are put off contributing directly to Source, as they find it hard to balance the time investment against their team's priorities. The cost of this is two-fold:
+
+- The number of high quality components available in Source is lower than it could be.
+- Potentially shareable components are built directly into applications, leading to fragmentation, inconsistency and duplication.
+
+We believe there is value in moving quickly, experimenting with new ideas and sharing those ideas for wider input. The Source Development Kitchen helps teams achieve this by lowering the barrier to entry. It allows teams to get fast feedback on new components, both from users and from other developers.
+
+By providing an agile mechanism for iterating and improving, components can be brought up to the level of quality expected of Source, and everyone can benefit from the work put into them.
+
+## Publishing
+
+The Source Development Kitchen is published as its own package, independent of the stable components in `@guardian/source`. This:
+
+- Allows the Kitchen to move fast.
+- Allows us to make frequent breaking changes to the Source Development Kitchen whilst preserving semver in Source. The stable library changes at a slower pace, in order to set expectations and preserve developer confidence.

libs/@guardian/source-development-kitchen/jest.config.js

@@ -0,0 +1,12 @@
+/* eslint-disable import/no-default-export -- that's what jest likes */
+
+import { config as baseConfig } from '../../../configs/jest.config.js';
+
+/** @typedef {import("jest").Config} Config  */
+const config = {
+	...baseConfig,
+	displayName: '@guardian/source-development-kitchen',
+	testEnvironment: 'node',
+};
+
+export default config;

libs/@guardian/source-development-kitchen/jest.dist.setup.js

@@ -0,0 +1,7 @@
+// Mock `src/index` with whatever the dist `package.json` points at.
+// This means we can run `src/index.test.ts` against `dist` instead.
+
+// @ts-ignore
+import * as dist from '.';
+
+jest.mock('./src/index', () => dist);

libs/@guardian/source-development-kitchen/main.js

@@ -0,0 +1,22 @@
+const rootMain = require('../../../../configs/storybook/main');
+
+// To customise your Storybook config for this project, update this file
+
+module.exports = {
+	...rootMain,
+
+	core: { ...rootMain.core },
+
+	stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+	addons: [...rootMain.addons],
+	webpackFinal: async (config, { configType }) => {
+		// apply any global webpack configs that might have been specified in .storybook/main.js
+		if (rootMain.webpackFinal) {
+			config = await rootMain.webpackFinal(config, { configType });
+		}
+
+		// add your own webpack tweaks if needed
+
+		return config;
+	},
+};