@financial-times/o-private-foundation 1.0.0

package/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 [origami.support@ft.com](mailto:origami.support@ft.com).
+
+## Licence
+This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).
+`;
+};

package/demos/src/demo.scss

@@ -0,0 +1 @@
+@import '../../main.scss';

package/main.js

@@ -0,0 +1,60 @@
+/* eslint-disable no-console */
+const missingDataMessage = 'Could not find layout information. ' +
+	'You may need to include o-grid css. See the README (https://registry.origami.ft.com/components/o-grid/readme) ' +
+	'for more information.';
+
+/**
+ * Grab the current layout.
+ * CSS must be included so JavaScript can retrieve layout information.
+ * See the README for more information.
+ *
+ * @returns {string} Layout name
+ */
+function getCurrentLayout() {
+	return getGridProperties().layout;
+}
+
+/**
+ * Grab grid properties
+ *
+ * @returns {object} layout names and gutter widths
+ */
+function getGridProperties() {
+	const properties = getGridFromDoc('after');
+	if (Object.keys(properties).length === 0) {
+		console.warn(missingDataMessage);
+	}
+	return properties;
+}
+
+/**
+ * Grab grid properties surfaced in html:after and html:before's content
+ *
+ * @param {string} position Whether to get all properties in :before, or current properties in :after
+ * @returns {object} layout names and gutter widths
+ */
+function getGridFromDoc(position) {
+	// Contained in a try/catch as it should not error if o-grid styles are not (deliberately or accidentally) loaded
+	// e.g. o-tracking will always try to read this property, but the page is not obliged to use o-grid for layout
+	try {
+		let gridProperties = window.getComputedStyle(document.documentElement, ':' + position).getPropertyValue('content');
+		// Firefox computes: "{\"foo\": \"bar\"}"
+		// We want readable JSON: {"foo": "bar"}
+		gridProperties = gridProperties.replace(/'/g, '').replace(/\\/g, '').replace(/^"/, '').replace(/"$/, '');
+		return JSON.parse(gridProperties);
+	} catch (e) {
+		return {};
+	}
+}
+
+const oPrivateGrid = {
+	getCurrentLayout,
+};
+
+export {
+	oPrivateGrid,
+};
+
+export default {
+	oPrivateGrid,
+};

package/main.scss

@@ -0,0 +1,32 @@
+@import './src/scss/brand';
+
+@import './src/scss/variables';
+
+@import './src/scss/o-spacing/main';
+@import './src/scss/o-colors/main';
+@import './src/scss/o-normalise/main';
+@import "./src/scss/o-icons/main";
+@import './src/scss/o-visual-effects/main';
+@import './src/scss/o-buttons/main';
+@import './src/scss/o-grid/main';
+@import './src/scss/o-typography/main';
+
+@mixin oPrivateFoundation() {
+	@font-face {
+		src: url('https://www.ft.com/__origami/service/build/v3/font?version=1.13&font_name=Metric2-VF&system_code=origami&font_format=woff2')
+			format('woff2-variations');
+		font-family: 'metric 2 VF';
+		font-weight: 300 800;
+		font-style: normal;
+		font-display: swap;
+	}
+
+	@font-face {
+		src: url('https://www.ft.com/__origami/service/build/v3/font?version=1.13&font_name=FinancierDisplay-VF&system_code=origami&font_format=woff2')
+			format('woff2-variations');
+		font-family: 'financier display VF';
+		font-weight: 300 800;
+		font-style: normal;
+		font-display: swap;
+	}
+}

package/origami.json

@@ -0,0 +1,26 @@
+{
+	"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": "origami.support@ft.com",
+		"slack": "#origami-support"
+	},
+	"supportStatus": "experimental",
+	"browserFeatures": {},
+	"demosDefaults": {
+		"sass": "demos/src/demo.scss",
+		"template": "demos/src/demo.mustache",
+		"documentClasses": "",
+		"dependencies": []
+	},
+	"demos": [
+		{
+			"title": "A Useful Demo",
+			"name": "demo",
+			"template": "demos/src/demo.mustache",
+			"description": "Description of the demo"
+		}
+	]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@financial-times/o-private-foundation",
+	"version": "1.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": "origami.support@ft.com"
+	},
+	"license": "MIT",
+	"type": "module",
+	"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"
+	},
+	"browser": "main.js",
+	"peerDependencies": {
+		"@financial-times/o-brand": "^4.1.0"
+	},
+	"devDependencies": {},
+	"engines": {
+		"npm": ">7"
+	},
+	"volta": {
+		"node": "14.16.1",
+		"npm": "7.11.1"
+	},
+	"percy": true,
+	"private": false
+}

package/src/scss/_brand.scss

@@ -0,0 +1,68 @@
+// Fetch tokens and use to configure brands
+// following the existing Origami v2 pattern.
+@use '_tokens.scss' as tokens;
+@import '@financial-times/o-brand/main';
+$o-private-foundation-tokens: tokens.forBrand(oBrandGetCurrent());
+
+/// Helper for `o-brand` function.
+@function oPrivateFoundationGet($variables, $from: null) {
+	$value: oBrandGet(
+		$component: 'o-private-foundation',
+		$variables: $variables,
+		$from: $from,
+	);
+	@if ($value == null) {
+		@error 'oPrivateFoundationGet: design token not found: #{$variables}';
+	}
+	@return $value;
+}
+
+/// Helper for `o-brand` function.
+@function oPrivateFoundationSupports($variant) {
+	@return oBrandSupportsVariant(
+		$component: 'o-private-foundation',
+		$variant: $variant
+	);
+}
+
+@if oBrandIs('core') {
+	@include oBrandDefine(
+		'o-private-foundation',
+		'core',
+		(
+			'variables':
+				map-merge(
+					$o-private-foundation-tokens,
+					(
+						// FT professional is treated as a theme in Origami v2.
+						'professional': tokens.forBrand('professional')
+					)
+				),
+			'supports-variants': (
+				'professional',
+			),
+		)
+	);
+}
+
+@if oBrandIs('internal') {
+	@include oBrandDefine(
+		'o-private-foundation',
+		'internal',
+		(
+			'variables': $o-private-foundation-tokens,
+			'supports-variants': (),
+		)
+	);
+}
+
+@if oBrandIs('whitelabel') {
+	@include oBrandDefine(
+		'o-private-foundation',
+		'whitelabel',
+		(
+			'variables': $o-private-foundation-tokens,
+			'supports-variants': (),
+		)
+	);
+}

package/src/scss/_tokens.scss

@@ -0,0 +1,15 @@
+@use 'tokens/core.scss' as coreTokens;
+@use 'tokens/professional.scss' as professionalTokens;
+@use 'tokens/internal.scss' as internalTokens;
+@use 'tokens/whitelabel.scss' as whitelabelTokens;
+
+$_by-brand: (
+	'core': coreTokens.$tokens,
+	'professional': professionalTokens.$tokens,
+	'internal': internalTokens.$tokens,
+	'whitelabel': whitelabelTokens.$tokens,
+);
+
+@function forBrand($brand) {
+	@return map-get($_by-brand, $brand);
+}

package/src/scss/_variables.scss

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