feat: introduce o-private-foundation (#1863)

* feat: introduce o-private-foundation

* feat: introduce o-private-foundation

* backstage: Add Sass token target

* backstage: Delete oPrivateFoundation mixin use, as it does not exist

---------

Co-authored-by: Lee Moody <[email protected]>

.github/labeler.yml

@@ -82,6 +82,8 @@ o-normalise:
   - components/o-normalise/**/*
 o-overlay:
   - components/o-overlay/**/*
+o-private-foundation:
+  - components/o-private-foundation/**/*
 o-quote:
   - components/o-quote/**/*
 o-share:

.github/workflows/test.yml

@@ -85,6 +85,8 @@ jobs:
             - 'components/o-normalise/**'
           components/o-overlay:
             - 'components/o-overlay/**'
+          components/o-private-foundation:
+            - 'components/o-private-foundation/**'
           components/o-quote:
             - 'components/o-quote/**'
           components/o-share:

.release-please-manifest.json

@@ -32,6 +32,7 @@
 	"components/o-multi-select": "2.2.7",
 	"components/o-normalise": "3.3.2",
 	"components/o-overlay": "4.2.13",
+	"components/o-private-foundation": "0.0.0",
 	"components/o-quote": "5.3.4",
 	"components/o-share": "10.0.2",
 	"components/o-social-follow": "1.0.11",

apps/dictionary/src/build.js

@@ -1,6 +1,7 @@
 import {StyleDictionaryPackageWithTransforms} from './config/styledictionary.js';
 import {getBrandSourcesAndIncludes, getBrandNames} from './utils.js';
 import {cssConfigForBrand} from './config/platforms/css.js';
+import {sassConfigForBrand} from './config/platforms/sass.js';
 import {toolingConfigForBrand} from './config/platforms/tooling.js';
 
 const brands = getBrandNames();
@@ -32,6 +33,7 @@ export async function buildForBrand(brand) {
 		},
 		platforms: {
 			css: cssConfigForBrand(brand),
+			sass: sassConfigForBrand(brand),
 			tooling: toolingConfigForBrand(brand),
 		},
 	};

apps/dictionary/src/config/platforms/sass.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import {sharedTransformers} from '../transformers.js';
+
+function sassConfigForBrand(brand) {
+	const parentBrand = brand.split('/').slice(-1);
+	return {
+		transformGroup: 'scss',
+		transforms: [
+			...sharedTransformers,
+			'value/figma-shadow-shorthand',
+			'value/transformSVG',
+		],
+		buildPath: path.join(process.cwd(), '../../components/'),
+		files: [
+			{
+				destination: `o-private-foundation/src/scss/tokens/${parentBrand}.scss`,
+				format: 'scss/map-flat',
+				options: {
+					outputReferences: false,
+				},
+			},
+		],
+	};
+}
+
+export {sassConfigForBrand};

components/o-private-foundation/.eslintignore

@@ -0,0 +1 @@
+demos/local/**

components/o-private-foundation/.eslintrc.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+	"extends": "origami-component"
+};

components/o-private-foundation/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.env
+/.sass-cache/
+/bower_components/
+/node_modules/
+/build/
+.idea/
+/demos/local
+/coverage

components/o-private-foundation/.npmignore

@@ -0,0 +1,15 @@
+.env
+.gitignore
+.npmignore
+.eslintrc.cjs
+.remarkrc.cjs
+.stylelintrc.cjs
+.prettierrc.toml
+.eslintignore
+.stylelintignore
+stories/
+src/tsx/
+.github/
+test/
+demos/local/
+

components/o-private-foundation/.remarkrc.cjs

@@ -0,0 +1 @@
+module.exports.plugins = [require("remark-preset-lint-origami-component")]

components/o-private-foundation/.stylelintignore

@@ -0,0 +1 @@
+demos/local/**

components/o-private-foundation/.stylelintrc.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+    "extends": "stylelint-config-origami-component"
+};

components/o-private-foundation/README.md

@@ -0,0 +1,108 @@
+# o-private-foundation
+
+> :warning: NOTE: this package should ONLY be used in Origami components. If you are not developing a component that is part of Origami, please do not use this package. 
+
+A collection of Origami components for use in other Origami components.
+
+- [Usage](#usage)
+- [Behaviour](#behaviour)
+- [Markup](#markup)
+- [Sass](#sass)
+- [JavaScript](#javascript)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Migration](#migration)
+- [Contact](#contact)
+- [Licence](#licence)
+
+_Instructions for the component. We've broken this down by Markup, JavaScript, Sass, etc. You may add more sections as needed._
+
+## Usage
+
+Check out [how to include Origami components in your project](https://origami.ft.com/docs/components/#including-components-in-your-project) to get started with `o-private-foundation`.
+
+## Behaviour
+
+`o-private-foundation` Behaviour description.
+
+## Markup
+
+_Markup documentation for the component. Including css classes, data attributes, and tags for variations of the component._
+_Demo markup is also shown in the registry. For complex markup it can be useful to describe the markup and link to the registry demos for a full example._
+_Remember to start your codeblocks with three backticks and "html" so your markup is syntax highlighted correctly._
+```html
+<div data-o-component="o-private-foundation" class='o-private-foundation'>
+</div>
+```
+
+## Sass
+
+_Sass documentation. With instructions to include styles with a primary mixin, what options are available, brand support where applicable._
+_For complex components it may be helpful to document apis with SassDoc and link to the components SassDoc in the Origami Registry._
+_Remember to start your codeblocks with three backticks and "scss" so your markup is syntax highlighted correctly._
+
+Use `@include oPrivateFoundation()` to include styles for all `o-private-foundation` features.
+
+```scss
+@import "@financial-times/o-private-foundation";
+
+@include oPrivateFoundation();
+```
+
+
+## JavaScript
+
+_JavaScript documentation. Including how to initialise the component, available options, and common usecases._
+_For complex components it may be helpful to document apis with JSDoc and link to the components JSDocs in the Origami Registry._
+_Remember to start your codeblocks with three backticks and "js" so your js is syntax highlighted correctly._
+
+JavaScript is initialised automatically for [Origami Build Service](https://www.ft.com/__origami/service/build/v2/) users. If your project is using a manual build process, [initialise  `o-private-foundation` manually](https://origami.ft.com/docs/tutorials/manual-build/).
+
+For example call the `init` method to initialise all `o-private-foundation` instances in the document:
+
+```js
+import oPrivateFoundation from 'o-private-foundation';
+oPrivateFoundation.init();
+```
+
+Or pass an element to initialise a specific `o-private-foundation` instance:
+
+```js
+import oPrivateFoundation from 'o-private-foundation';
+const oPrivateFoundationElement = document.getElementById('#my-o-private-foundation-element');
+oPrivateFoundation.init(oPrivateFoundationElement);
+```
+
+
+
+## Troubleshooting
+
+_Answers to questions or problems that come up repeatedly._
+_It's likely you can delete this section for now. Remember to remove it from the table of contents._
+
+## Contributing
+
+_Contributing documentation for non typical components._
+_It's likely you can delete this section if your component conforms with other components._
+_Remember to update the table of contents is you remove this section._
+
+## Migration
+
+_Guides to upgrade from one major version of a component to another._
+_This section includes a table of major versions with links to `MIGRATION.md`._
+_`MIGRATION.md` would provide upgrade instructions, but since this is a new component there is no `MIGRATION.md`._
+_Delete this section, including from the table of contents, until there is a second major version of this component._
+
+State | Major Version | Last Minor Release | Migration guide |
+:---: | :---: | :---: | :---:
+✨ active | 3 | N/A | [migrate to v3](MIGRATION.md#migrating-from-v2-to-v3) |
+⚠ maintained | 2 | 2.0 | [migrate to v2](MIGRATION.md#migrating-from-v1-to-v2) |
+╳ deprecated | 1 | 1.0 | N/A |
+
+## Contact
+If you have any questions or comments about this component, or need help using it, please either [raise an issue](https://github.com/Financial-Times/origami/issues/new?labels=o-private-foundation,components), visit [#origami-support](https://financialtimes.slack.com/messages/#origami-support/) or email [[email protected]](mailto:[email protected]).
+
+## Licence
+This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).
+`;
+};

components/o-private-foundation/origami.json

@@ -0,0 +1,27 @@
+{
+	"origamiType": "component",
+	"origamiVersion": "2.0",
+	"brands": ["core","internal","whitelabel"],
+	"support": "https://github.com/Financial-Times/origami/issues/new?labels=o-private-foundation,components",
+	"supportContact": {
+		"email":  "[email protected]",
+		"slack": "#origami-support"
+	},
+	"supportStatus": "experimental",
+	"browserFeatures": {},
+	"demosDefaults": {
+		"sass": "demos/src/demo.scss", 
+		"js": "demos/src/demo.js", 
+		"template": "demos/src/demo.mustache",
+		"documentClasses": "",
+		"dependencies": []
+	},
+	"demos": [
+		{
+			"title": "A Useful Demo",
+			"name": "demo",
+			"template": "demos/src/demo.mustache",
+			"description": "Description of the demo"
+		}
+	]
+}

components/o-private-foundation/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@financial-times/o-private-foundation",
+  "version": "0.0.0",
+  "description": "Foundation components for use in Origami components only.",
+  "keywords": [],
+  "homepage": "https://registry.origami.ft.com/components/o-private-foundation",
+  "bugs": {
+    "url": "https://github.com/Financial-Times/origami/issues/new?labels=o-private-foundation,components",
+    "email": "[email protected]"
+  },
+  "license": "MIT",
+  "type": "module",
+  "browser": "main.js",
+  "scripts": {
+    "build": "bash ../../scripts/component/build.bash",
+    "test": "bash ../../scripts/component/test.bash",
+    "lint": "bash ../../scripts/component/lint.bash",
+    "watch": "bash ../../scripts/component/watch.bash"
+  },
+	"peerDependencies": {
+			"@financial-times/o-brand": "^4.1.0"
+	},
+	  "devDependencies": {},
+  "engines": {
+    "npm": "^7 || ^8"
+  },
+  "volta": {
+    "node": "14.16.1",
+    "npm": "7.11.1"
+  },
+  "percy": true,
+  "private": false
+}

components/o-private-foundation/src/scss/_brand.scss

@@ -0,0 +1,10 @@
+/// Helper for `o-brand` function.
+/// @access private
+@function _oPrivateFoundationGet($variables, $from: null) {
+	@return oBrandGet($component: 'o-private-foundation', $variables: $variables, $from: $from);
+}
+/// Helper for `o-brand` function.
+/// @access private
+@function _oPrivateFoundationSupports($variant) {
+	@return oBrandSupportsVariant($component: 'o-private-foundation', $variant: $variant);
+}

components/o-private-foundation/src/scss/_variables.scss

@@ -0,0 +1 @@
+// Add any global Sass variables for o-private-foundation here.