@grantcodes/ui 2.11.1 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [2.12.0](https://github.com/grantcodes/ui/compare/ui-v2.11.2...ui-v2.12.0) (2026-05-03)
+
+
+### Features
+
+* **22-button-face-native-behavior:** add FACE static properties and ElementInternals wiring ([b6ee7f4](https://github.com/grantcodes/ui/commit/b6ee7f4084f2916cd6799c0a79ec13cf87c3c0e5))
+* **22-button-face-native-behavior:** add form lifecycle callbacks and initial setFormValue ([e3f015c](https://github.com/grantcodes/ui/commit/e3f015c40c1d67cfb970d028745bad2c126eb976))
+* **22-button-face-native-behavior:** fix FACE form behavior implementation ([c7b8caa](https://github.com/grantcodes/ui/commit/c7b8caa534b1d85049c89b5121cb67c39914f9f2))
+* **22-button-face-native-behavior:** wire form click handler for submit/reset ([4c9ef53](https://github.com/grantcodes/ui/commit/4c9ef535f8d2a5df711042036b8c855cf23f3ce5))
+
+## [2.11.2](https://github.com/grantcodes/ui/compare/ui-v2.11.1...ui-v2.11.2) (2026-05-03)
+
+
+### Bug Fixes
+
+* **ui:** add horizontal property to form field ([1a0bbfa](https://github.com/grantcodes/ui/commit/1a0bbfa1ed69e341c5e43ee0678bcb9d0f0469a7))
+
 ## [2.11.1](https://github.com/grantcodes/ui/compare/ui-v2.11.0...ui-v2.11.1) (2026-05-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantcodes/ui",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "A personal component system built with Lit web components",
   "type": "module",
   "main": "src/main.js",

package/src/components/button/button.component.js

@@ -10,12 +10,15 @@ export class GrantCodesButton extends LitElement {
 	// via CSS custom properties.
 	static styles = [focusRingStyles, buttonStyles];
 
+	static formAssociated = true;
+
 	static properties = {
 		href: { type: String },
 		type: { type: String },
 		name: { type: String },
 		value: { type: String },
 		disabled: { type: Boolean, reflect: true },
+		form: { type: String, reflect: true },
 	};
 
 	constructor() {
@@ -25,9 +28,65 @@ export class GrantCodesButton extends LitElement {
 		this.type = "button";
 		this.name = "";
 		this.value = "";
+		// Do NOT set form="" — an empty form attribute overrides ancestor form association
+		this._fieldsetDisabled = false;
+
+		// Attach ElementInternals for form participation.
+		// try/catch because happy-dom (DOM-shim test env) may not support attachInternals()
+		try {
+			this.internals = this.attachInternals();
+		} catch (e) {
+			this.internals = null;
+		}
 		this.disabled = false;
 	}
 
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		if (this.internals) {
+			if (changedProperties.has("name") || changedProperties.has("value")) {
+				this.internals.setFormValue(this.name ? this.value : null);
+			}
+		}
+	}
+
+	connectedCallback() {
+		super.connectedCallback();
+		this.addEventListener("click", this._handleFormClick);
+	}
+
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.removeEventListener("click", this._handleFormClick);
+	}
+
+	_handleFormClick(e) {
+		// href mode renders a link — do not intercept form actions
+		if (this.href) return;
+		// Only handle form actions when we have internals and are inside a form
+		if (!this.internals || !this.internals.form || this.disabled) return;
+
+		const t = this.type.toLowerCase();
+		if (t === "submit") {
+			this.internals.form.requestSubmit();
+		} else if (t === "reset") {
+			this.internals.form.reset();
+		}
+		// type === "button" or any other value: no form action (default no-op)
+	}
+
+	formDisabledCallback(disabled) {
+		this._fieldsetDisabled = disabled;
+		this.requestUpdate();
+	}
+
+	formResetCallback() {
+		// Called by the browser when the associated form is reset.
+		// Reset the value to an empty string (default state).
+		// If a future version tracks an initial value, restore it here.
+		this.value = "";
+	}
+
 	// The render() method is called any time reactive properties change.
 	// Return HTML in a string template literal tagged with the `html`
 	// tag function to describe the component's internal DOM.
@@ -42,7 +101,7 @@ export class GrantCodesButton extends LitElement {
 				<a
 					class="button focus-ring"
 					href=${this.href}
-					?disabled=${this.disabled}
+					?disabled=${this.disabled || this._fieldsetDisabled}
 				>
 					<span><slot></slot></span>
 				</a>
@@ -52,10 +111,10 @@ export class GrantCodesButton extends LitElement {
 		return html`
 			<button
 				class="button focus-ring"
-				type=${this.type}
+				type="button"
 				name=${this.name ?? ""}
 				value=${this.value ?? ""}
-				?disabled=${this.disabled}
+				?disabled=${this.disabled || this._fieldsetDisabled}
 			>
 				<span><slot></slot></span>
 			</button>

package/src/components/button/button.test.js

@@ -1,6 +1,7 @@
 import { describe, it, afterEach } from "node:test";
 import { strict as assert } from "node:assert";
 import { fixture, cleanup, click } from "../../test-utils/index.js";
+import { GrantCodesButton } from "./button.component.js";
 import "./button.js";
 
 describe("Button Component", () => {
@@ -84,8 +85,11 @@ describe("Button Component", () => {
 
 		for (const type of types) {
 			const testElement = await fixture("grantcodes-button", { type });
+			// Internal button is always type="button" — form behavior is handled
+			// by the host element via FACE (requestSubmit/reset on ElementInternals)
 			const button = testElement.shadowRoot.querySelector("button");
-			assert.strictEqual(button.type, type, `Button type should be ${type}`);
+			assert.strictEqual(button.type, "button", `Internal button should always be type="button"`);
+			assert.strictEqual(testElement.type, type, `Host type property should be ${type}`);
 			cleanup(testElement);
 		}
 	});
@@ -100,3 +104,246 @@ describe("Button Component", () => {
 		assert.ok(slot, "Slot should exist");
 	});
 });
+
+describe("Form Context", () => {
+	let element;
+	let form;
+
+	afterEach(() => {
+		cleanup(element);
+		cleanup(form);
+	});
+
+	it("should render button inside a form element", async () => {
+		form = document.createElement("form");
+		document.body.appendChild(form);
+
+		element = document.createElement("grantcodes-button");
+		form.appendChild(element);
+		await element.updateComplete;
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Button should exist in shadow DOM when inside form");
+		const link = element.shadowRoot.querySelector("a");
+		assert.strictEqual(link, null, "Should not render a link when inside form");
+	});
+
+	it("should use type='button' as default on internal button", async () => {
+		element = await fixture("grantcodes-button");
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.strictEqual(button.type, "button", "Default type should be 'button'");
+	});
+
+	it("should keep internal button as type='button' when host type is submit", async () => {
+		element = await fixture("grantcodes-button", { type: "submit" });
+
+		const button = element.shadowRoot.querySelector("button");
+		// Internal button is always type="button" — FACE handles submit via requestSubmit()
+		assert.strictEqual(button.type, "button", "Internal button should be type='button'");
+		assert.strictEqual(element.type, "submit", "Host type property should be 'submit'");
+	});
+
+	it("should keep internal button as type='button' when host type is reset", async () => {
+		element = await fixture("grantcodes-button", { type: "reset" });
+
+		const button = element.shadowRoot.querySelector("button");
+		// Internal button is always type="button" — FACE handles reset via form.reset()
+		assert.strictEqual(button.type, "button", "Internal button should be type='button'");
+		assert.strictEqual(element.type, "reset", "Host type property should be 'reset'");
+	});
+
+	it("should reflect name property on internal button", async () => {
+		element = await fixture("grantcodes-button", { name: "myButton" });
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.strictEqual(
+			button.getAttribute("name"),
+			"myButton",
+			"Internal button name attribute should be 'myButton'",
+		);
+	});
+
+	it("should reflect value property on internal button", async () => {
+		element = await fixture("grantcodes-button", { value: "send" });
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.strictEqual(
+			button.getAttribute("value"),
+			"send",
+			"Internal button value attribute should be 'send'",
+		);
+	});
+
+	it("should reflect disabled property on internal button", async () => {
+		element = await fixture("grantcodes-button", { disabled: true });
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.strictEqual(button.disabled, true, "Internal button should be disabled");
+		assert.ok(
+			button.hasAttribute("disabled"),
+			"Internal button should have disabled attribute",
+		);
+	});
+
+	it("should render as link not button when href is set", async () => {
+		element = await fixture("grantcodes-button", {
+			href: "https://example.com",
+		});
+		await element.updateComplete;
+
+		const button = element.shadowRoot.querySelector("button");
+		const link = element.shadowRoot.querySelector("a");
+		assert.strictEqual(button, null, "Should not render a button when href is set");
+		assert.ok(link, "Should render a link when href is set");
+		const href = link.getAttribute("href");
+		assert.ok(
+			href === "https://example.com" || href.includes("example.com"),
+			"Link href should contain example.com",
+		);
+	});
+});
+
+describe("FACE Infrastructure", () => {
+	let element;
+
+	afterEach(() => {
+		cleanup(element);
+	});
+
+	it("should declare formAssociated as true", () => {
+		assert.strictEqual(
+			GrantCodesButton.formAssociated,
+			true,
+			"GrantCodesButton.formAssociated should be true",
+		);
+	});
+
+	it("should have internals property after construction", async () => {
+		element = await fixture("grantcodes-button");
+		// internals may be null in happy-dom (attachInternals throws), but the
+		// property must exist — it was assigned in the constructor's try/catch.
+		assert.ok(
+			"internals" in element,
+			"Element should have internals property",
+		);
+		// In happy-dom: element.internals === null (expected — DOM shim limitation)
+		// In real browser: element.internals instanceof ElementInternals
+	});
+
+	it("should reflect form attribute when set as property", async () => {
+		element = await fixture("grantcodes-button", {
+			form: "myForm",
+		});
+		await element.updateComplete;
+
+		assert.strictEqual(
+			element.getAttribute("form"),
+			"myForm",
+			"form attribute should reflect property value 'myForm'",
+		);
+		assert.strictEqual(
+			element.form,
+			"myForm",
+			"element.form property should be 'myForm'",
+		);
+	});
+
+	it("should not have form attribute by default", async () => {
+		element = await fixture("grantcodes-button");
+		await element.updateComplete;
+
+		const formAttr = element.getAttribute("form");
+		assert.ok(
+			formAttr === null || formAttr === "",
+			"form attribute should be null or empty by default",
+		);
+	});
+
+	it("should use type='button' on internal button after FACE changes", async () => {
+		element = await fixture("grantcodes-button", { type: "submit" });
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Internal button should exist");
+		assert.strictEqual(
+			button.type,
+			"button",
+			"Internal button should be type='button' — FACE handles submit via requestSubmit()",
+		);
+	});
+
+	it("should still render as link not button when href is set", async () => {
+		element = await fixture("grantcodes-button", {
+			href: "https://example.com",
+		});
+		await element.updateComplete;
+
+		const button = element.shadowRoot.querySelector("button");
+		const link = element.shadowRoot.querySelector("a");
+		assert.strictEqual(button, null, "Should not render a button when href is set");
+		assert.ok(link, "Should render a link when href is set");
+	});
+
+	it("should have disabled attribute on internal button when disabled", async () => {
+		element = await fixture("grantcodes-button", {
+			disabled: true,
+		});
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Internal button should exist");
+		assert.strictEqual(
+			button.disabled,
+			true,
+			"Internal button should be disabled when element.disabled is true",
+		);
+		assert.ok(
+			button.hasAttribute("disabled"),
+			"Internal button should have disabled attribute",
+		);
+	});
+
+	it("should not throw when clicking internal button while disabled", async () => {
+		element = await fixture("grantcodes-button", {
+			disabled: true,
+			type: "submit",
+		});
+		await element.updateComplete;
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Internal button should exist");
+
+		// _handleFormClick should early-return when this.disabled is true.
+		// Verify clicking does not throw (no internals.form access attempted).
+		let threw = false;
+		try {
+			button.click();
+		} catch (e) {
+			threw = true;
+		}
+		assert.strictEqual(threw, false, "Clicking disabled button should not throw");
+	});
+
+	it("should keep internal button as type='button' when host type is reset", async () => {
+		element = await fixture("grantcodes-button", { type: "reset" });
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Internal button should exist");
+		assert.strictEqual(
+			button.type,
+			"button",
+			"Internal button should be type='button' — FACE handles reset via form.reset()",
+		);
+	});
+
+	it("should have type='button' as default on internal button", async () => {
+		element = await fixture("grantcodes-button");
+
+		const button = element.shadowRoot.querySelector("button");
+		assert.ok(button, "Internal button should exist");
+		assert.strictEqual(
+			button.type,
+			"button",
+			"Default internal button type should be 'button'",
+		);
+	});
+});

package/src/components/form-field/form-field.component.js

@@ -1,5 +1,6 @@
 import { LitElement } from "lit";
 import { html } from "lit/static-html.js";
+import { classMap } from "lit/directives/class-map.js";
 import formFieldStyles from "./form-field.css" with { type: "css" };
 import { generateId } from "../../lib/generate-id.js";
 
@@ -8,7 +9,8 @@ export class GrantCodesFormField extends LitElement {
 	static styles = [formFieldStyles];
 
 	static properties = {
-		label: { type: String, reflect: true },
+    label: { type: String, reflect: true },
+		direction: { type: String },
 		error: { type: String },
 		help: { type: String },
 	};
@@ -20,7 +22,13 @@ export class GrantCodesFormField extends LitElement {
 		this.error = undefined;
 		this.help = undefined;
 
-		this.groupInput = false;
+    this.groupInput = false;
+
+    /**
+		 * Direction of the field. Generally want horizontal for checkboxes and radios.
+		 * @type {'vertical' | 'horizontal'}
+		 */
+		this.direction = "vertical";
 
 		/** @type {NodeListOf<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>} */
 		this.inputElements;
@@ -123,19 +131,23 @@ export class GrantCodesFormField extends LitElement {
     `;
 	}
 
-	render() {
+  render() {
+    const wrapperClass = classMap({
+      'form-field': true,
+      'form-field--horizontal': this.direction === 'horizontal'
+    })
 		if (this.groupInput) {
 			return html`
-      <fieldset class="form-field">
+      <fieldset class=${wrapperClass}>
         <legend class="form-field__label">${this.label}</legend>
         <slot></slot>
         ${this.errorTemplate()}
       </fieldset>
     `;
-		}
+    }
 
 		return html`
-      <div class="form-field">
+      <div class=${wrapperClass}>
         <label>
           <span class="form-field__label" @click=${this.handleLabelClick}
             >${this.label}</span

package/src/components/form-field/form-field.css

@@ -20,10 +20,11 @@
 	gap: inherit;
 }
 
-:host(:has(> input[type="checkbox"], > input[type="radio"])) .form-field label {
+.form-field--horizontal label {
 	flex-direction: row-reverse;
 	align-items: center;
 	justify-content: flex-end;
+	gap: var(--g-theme-spacing-sm);
 }
 
 .form-field__label {

package/src/components/form-field/form-field.stories.js

@@ -42,7 +42,7 @@ export const FormFieldWithHelp = {
 };
 
 export const FormFieldWithSelect = {
-	args: {
+  args: {
 		slot: html`
       <select>
         <option value="1">Option 1</option>
@@ -60,13 +60,15 @@ export const FormFieldWithTextArea = {
 };
 
 export const FormFieldWithCheckbox = {
-	args: {
+  args: {
+    direction: 'horizontal',
 		slot: html`<input type="checkbox" value="1" name="name" />`,
 	},
 };
 
 export const FormFieldWithRadio = {
-	args: {
+  args: {
+    direction: 'horizontal',
 		slot: html`<input type="radio" />`,
 	},
 };
@@ -74,13 +76,13 @@ export const FormFieldWithRadio = {
 export const FormFieldWithRadioGroup = {
 	args: {
 		slot: html`
-      <grantcodes-form-field label="Radio number 1">
+      <grantcodes-form-field label="Radio number 1" direction="horizontal">
         <input type="radio" name="radio-group" value="1" />
       </grantcodes-form-field>
-      <grantcodes-form-field label="Radio number 2">
+      <grantcodes-form-field label="Radio number 2" direction="horizontal">
         <input type="radio" name="radio-group" value="2" />
       </grantcodes-form-field>
-      <grantcodes-form-field label="Radio number 3">
+      <grantcodes-form-field label="Radio number 3" direction="horizontal">
         <input type="radio" name="radio-group" value="3" />
       </grantcodes-form-field>
     `,
@@ -90,13 +92,13 @@ export const FormFieldWithRadioGroup = {
 export const FormFieldWithCheckboxGroup = {
 	args: {
 		slot: html`
-      <grantcodes-form-field label="Checkbox number 1"
+      <grantcodes-form-field label="Checkbox number 1" direction="horizontal"
         ><input type="checkbox"
       /></grantcodes-form-field>
-      <grantcodes-form-field label="Checkbox number 2"
+      <grantcodes-form-field label="Checkbox number 2" direction="horizontal"
         ><input type="checkbox"
       /></grantcodes-form-field>
-      <grantcodes-form-field label="Checkbox number 3"
+      <grantcodes-form-field label="Checkbox number 3" direction="horizontal"
         ><input type="checkbox"
       /></grantcodes-form-field>
     `,