Or 960/add o3 form docs (#1849)

* docs: add initial strucutre for forms documentation

* chore: implement test version of tip component

* chore: initialise guidlines for form elements
craete tip component

* chore: introduce copy, heading and tip content

* fix: fix issues with tsx components in nested folders not compailing

* feat: add optional on text-input and password element
- display optional element with classnames instead of using complicated selector
- update sb demos to display optional next to labels
- update TextInputProps interface to extend BaseinputProps instead of FromFieldprops
- Run code formating on passowrd.tsx and input.tsx

* chore: generate sb-figma links for other brands

* feat: - add new guidelines for required-optional example
- update name of a placement-order guideline so there is some consistency

* chore: add o3-form class wrapper so styles apply correctly

* fix: fix issue with astro build by adding postcss config

* feat: change Tip componene API and use array instead of slots for sources

* feat: add styles to form wrapper so it has proper gap, is always aligned left and is stacked vertically

* docs: - add examples and guidlines for form intro page
- organise folders to make it clear where do preveiws, guidlines and exmaples go

* fix: dont display other brands demos since we dont have tokens for it yet.

* docs: make it clear that o3-forms is coming for other brands but currenlty users can use whitelabel

---------

Co-authored-by: ben.freshwater <[email protected]>

apps/for-everyone-website/package.json

@@ -23,11 +23,14 @@
 		"@financial-times/o3-button": "^2.0.0",
 		"@financial-times/o3-editorial-typography": "^2.0.0",
 		"@financial-times/o3-figma-sb-links": "^0.0.0",
+		"@financial-times/o3-form": "^0.3.2",
 		"@financial-times/o3-foundation": "^2.0.0",
 		"@financial-times/o3-social-sign-in": "^1.0.0",
 		"@financial-times/o3-tooling-token": "^0.0.0",
 		"@financial-times/o3-tooltip": "^2.0.0",
 		"astro": "^4.0.9",
+		"autoprefixer": "^10.4.20",
+		"postcss-preset-env": "^10.0.7",
 		"prettier": "3.2.5",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
@@ -41,6 +44,6 @@
 	"devDependencies": {
 		"globby": "^14.0.1",
 		"html-minifier": "^4.0.0",
-		"jsdom": "^24.1.0"
+		"jsdom": "^25.0.0"
 	}
 }

apps/for-everyone-website/postcss.config.cjs

@@ -0,0 +1,16 @@
+const autoprefixer = require('autoprefixer');
+const postcssPresetEnv = require('postcss-preset-env');
+
+const config = {
+	plugins: [
+		postcssPresetEnv({
+			stage: 3,
+			features: {
+				'nesting-rules': true,
+			},
+		}),
+		autoprefixer(),
+	],
+};
+
+module.exports = config;

apps/for-everyone-website/src/components/form/examples/Disabled-state.astro

@@ -0,0 +1,16 @@
+---
+import Preview from '../../utils/Preview.astro'
+import FigmaSbLinks from '../../utils/FigmaSbLinks.astro';
+
+import * as DisabledInput from '../preview/Input-disabled-state'
+
+const {brand} = Astro.props
+const component = DisabledInput
+const storybookId = `${brand}-o3-form--text-input`
+---
+
+<div>
+	<Preview {component} />
+	<FigmaSbLinks storybook={storybookId} />
+</div>
+

apps/for-everyone-website/src/components/form/examples/Input-validation.astro

@@ -0,0 +1,16 @@
+---
+import Preview from '../../utils/Preview.astro'
+import FigmaSbLinks from '../../utils/FigmaSbLinks.astro';
+
+import * as InputValidatio from '../preview/Input-error'
+
+const {brand} = Astro.props
+const component = InputValidatio
+const storybookId = `${brand}-o3-form--text-input-error-state`
+---
+
+<div>
+	<Preview {component} />
+	<FigmaSbLinks storybook={storybookId} />
+</div>
+

apps/for-everyone-website/src/components/form/examples/Page-level-validation.astro

@@ -0,0 +1,16 @@
+---
+import Preview from '../../utils/Preview.astro'
+import FigmaSbLinks from '../../utils/FigmaSbLinks.astro';
+
+import * as ErrorSummary from '../preview/Error-summary'
+
+const {brand} = Astro.props
+const component = ErrorSummary
+const storybookId = `${brand}-o3-form--error-summary`
+---
+
+<div>
+	<Preview {component} />
+	<FigmaSbLinks storybook={storybookId} />
+</div>
+

apps/for-everyone-website/src/components/form/guidelines/Form-submission.astro

@@ -0,0 +1,22 @@
+---
+import {Form, TextInput} from '@financial-times/o3-form/esm'
+import { Button } from '@financial-times/o3-button/esm';
+import Example from '../../Example.astro';
+
+const {brand} = Astro.props
+---
+
+<Example slot="examples" do title="Include a button with a clear call to action to submit data">
+	<div data-o3-brand={brand}>
+		<Form>
+			<TextInput label="City" attributes={{defaultValue: "London" }} />
+			<TextInput label="Address" attributes={{defaultValue: "1 Friday St"}} optional={true} />
+			<Button label='Save' type='primary' />
+	</Form>
+</Example>
+
+<style>
+	div {
+		width: 50%;
+	}
+</style>

apps/for-everyone-website/src/components/form/guidelines/Labels-grouping.astro

@@ -0,0 +1,25 @@
+---
+import {Form, TextInput} from '@financial-times/o3-form/esm'
+import Example from '../../Example.astro';
+
+const {brand} = Astro.props
+---
+
+<Example slot="examples" do title="Group similar inputs to ease the user">
+	<div data-o3-brand={brand}>
+		<Form>
+			<h4 class="o3-typography-h3 grouping-title">Your Details</h4>
+			<TextInput label="Email address" attributes={{defaultValue: "[email protected]" }} />
+
+			<h4 class="o3-typography-h3 grouping-title">Your address</h4>
+			<TextInput label="Country" attributes={{defaultValue: "United Kingdom" }} />
+			<TextInput label="Address" attributes={{defaultValue: "1 Friday St"}} optional={true} />
+		</form>
+	</Form>
+</Example>
+
+<style>
+	div {
+		width: 50%;
+	}
+</style>

apps/for-everyone-website/src/components/form/guidelines/Placement-order.astro

@@ -0,0 +1,48 @@
+---
+import {Form, TextInput} from '@financial-times/o3-form/esm'
+import Example from '../../Example.astro';
+
+const {brand} = Astro.props
+---
+
+<Example slot="examples" do title="Always left-Align components and stack vertically">
+	<div  class="o3-form-vertical" data-o3-brand={brand}>
+		<Form>
+			<TextInput label="Country" attributes={{defaultValue: "United Kingdom"}} />
+			<TextInput label="City" attributes={{defaultValue: "London" }} />
+			<TextInput label="Address" attributes={{defaultValue: "1 Friday St"}} />
+		</Form>
+	</div>
+</Example>
+
+<Example slot="examples" do={false} title="Avoid putting components next to each other and avoid centering them">
+	<div data-o3-brand={brand}>
+		<form class="o3-form-horizontal">
+			<TextInput label="Country" attributes={{defaultValue: "United Kingdom"}} />
+			<TextInput label="City" attributes={{defaultValue: "London" }} />
+			<TextInput label="Address" attributes={{defaultValue: "1 Friday St"}} />
+		</form>
+	</div>
+</Example>
+
+
+<style>
+	div {
+		width: 100%;
+	}
+
+	.o3-form-vertical {
+		width: 50%;
+	}
+
+	.o3-form-horizontal {
+		display: flex;
+		gap: var(--o3-spacing-s);
+		width: 100%;
+		flex-wrap: wrap;
+	}
+
+	.o3-form-horizontal {
+		justify-content: center;
+	}
+</style>

apps/for-everyone-website/src/components/form/guidelines/Required-optional.astro

@@ -0,0 +1,23 @@
+---
+import {Form, TextInput} from '@financial-times/o3-form/esm'
+import Example from '../../Example.astro';
+
+const {brand} = Astro.props
+---
+
+<Example slot="examples" do title="Mark Optional Components">
+	<div data-o3-brand={brand}>
+
+		<Form>
+			<TextInput label="City" attributes={{defaultValue: "London" }} />
+			<TextInput label="Address" attributes={{defaultValue: "1 Friday St"}} optional={true} />
+		</Form>
+	</div>
+</Example>
+
+<style>
+	div {
+		width: 50%;
+	}
+
+</style>

apps/for-everyone-website/src/components/form/preview/Error-summary.tsx

@@ -0,0 +1,20 @@
+import {Form, ErrorSummary} from '@financial-times/o3-form/esm';
+
+function ButtonPreview() {
+	return (
+		<>
+			<meta itemProp="@preview" />
+			<Form>
+				<ErrorSummary errors={[{
+					id: 'error-summary',
+					fieldName: 'Email',
+					message: 'Please enter a valid email address',
+				}]} />
+			</Form>
+			<meta itemProp="@preview" />
+		</>
+	);
+}
+export const filePath = 'src/components/form/preview/Error-summary.tsx';
+
+export {ButtonPreview as preview};

apps/for-everyone-website/src/components/form/preview/Input-disabled-state.tsx

@@ -0,0 +1,21 @@
+import {Form, TextInput} from '@financial-times/o3-form/esm';
+
+function ButtonPreview() {
+	return (
+		<>
+			<meta itemProp="@preview" />
+			<Form>
+				<TextInput
+					label="Email"
+					description='You need to confirm your email before you can change it'
+					attributes={{defaultValue: '[email protected]'}}
+					disabled={true}
+				/>
+			</Form>
+			<meta itemProp="@preview" />
+		</>
+	);
+}
+export const filePath = 'src/components/form/preview/Input-error.tsx';
+
+export {ButtonPreview as preview};

apps/for-everyone-website/src/components/form/preview/Input-error.tsx

@@ -0,0 +1,23 @@
+import {Form, TextInput} from '@financial-times/o3-form/esm';
+
+function ButtonPreview() {
+	return (
+		<>
+			<meta itemProp="@preview" />
+			<Form>
+				<TextInput
+					label="Email"
+					attributes={{defaultValue: 'john@gmailcom'}}
+					feedback={{
+						message: 'Please enter a valid email address',
+						type: 'error',
+					}}
+				/>
+			</Form>
+			<meta itemProp="@preview" />
+		</>
+	);
+}
+export const filePath = 'src/components/form/preview/Input-error.tsx';
+
+export {ButtonPreview as preview};

apps/for-everyone-website/src/components/utils/Tip.astro

@@ -0,0 +1,84 @@
+---
+import tip from '../../../public/assets/images/documentation/components/tip.svg?raw';
+
+interface Props {
+	sources: {
+	 title: string;
+	 url: string;
+	}[]
+}
+const {sources} = Astro.props;
+---
+
+<div class="not-content tip-container">
+	<div class="tip-description">
+		<div class="icon">
+			<Fragment set:html={tip} />
+		</div>
+		<slot name="tip-content" />
+	</div>
+	{
+		sources?.length > 0 && (
+			<div class="tip-sources">
+				<strong>SOURCES:</strong>
+				<div class="tip-sources-wrapper">
+					{sources.map((source, index) => (
+						<>
+							<a href={source.url}>{source.title}</a>
+							{index < sources.length - 1 && ' | '}
+						</>
+					))}
+				</div>
+			</div>
+		)
+	}
+</div>
+
+<style>
+	.tip-container {
+		--_icon-width: 24px;
+		background-color: #f4f4f5;
+		border: 1px solid var(--slate-white-15, #dedfe0);
+		border-radius: var(--o3-spacing-5xs);
+		box-shadow: var(--o3-spacing-5xs) var(--o3-spacing-5xs)
+			var(--o3-spacing-3xs) 0px rgba(222, 223, 224, 0.08);
+	}
+	.tip-description {
+		padding: var(--o3-spacing-2xs) 0px;
+		position: relative;
+		display: flex;
+		.icon {
+			width: var(--_icon-width);
+			height: var(--_icon-width);
+			margin: 0px var(--o3-spacing-4xs);
+		}
+	}
+
+	.tip-sources {
+		display: flex;
+		/* Icon size plus its margins */
+		padding: var(--o3-spacing-3xs) 0 var(--o3-spacing-3xs)
+			calc(var(--_icon-width) + 2 * var(--o3-spacing-4xs));
+
+		border-radius: 0px 0px var(--o3-spacing-5xs) var(--o3-spacing-5xs);
+		border-right: 1px solid var(--slate-white-15, #dedfe0);
+		border-bottom: 1px solid var(--slate-white-15, #dedfe0);
+		border-left: 1px solid var(--slate-white-15, #dedfe0);
+		background: #ececee;
+		.tip-sources-wrapper {
+			& a {
+				all: unset;
+				cursor: pointer;
+				text-decoration-line: underline;
+			}
+
+			color: #8f8f8f;
+			font-size: var(--o3-font-size-negative-2);
+		}
+		strong {
+			color: #8f8f8f;
+			font-size: var(--o3-font-size-negative-2);
+			margin-right: var(--o3-spacing-5xs);
+		}
+	}
+</style>