@justeattakeaway/pie-button 0.30.0 → 0.32.0

package/README.md

@@ -11,46 +11,42 @@
 # Table of Contents
 
 1. [Introduction](#pie-button)
-2. [Local Development](#local-development)
-3. [Props](#props)
+2. [Installation](#installation)
+3. [Importing the component](#importing-the-component)
 4. [Peer Dependencies](#peer-dependencies)
-5. [Events](#events)
+5. [Local Development](#local-development)
+6. [Props](#props)
+7. [Events](#events)
    - [HTML example](#html)
    - [Vue example (using Nuxt 3)](#vue-templates-using-nuxt-3)
    - [React example (using Next 13)](#react-templates-using-next-13)
-6. [Testing](#testing)
+6. [Forms usage](#forms-usage)
+7. [Testing](#testing)
    - [Browser Tests](#browser-tests)
    - [Visual Tests](#visual-tests)
 
 
-## `pie-button`
+## pie-button
 
 `pie-button` is a Web Component built using the Lit library. It offers a simple and accessible button component for web applications.
 
 This component can be easily integrated into various frontend frameworks and customized through a set of properties.
 
-## Local development
-
-Install the dependencies. Note that this, and the following commands below, should be run from the **root of the monorepo**:
 
-```bash
-yarn
-```
+## Installation
 
-To build the `pie-button` package, run the following command:
+To install `pie-button` in your application, run the following on your command line:
 
 ```bash
-yarn build --filter=pie-button
+# npm
+$ npm i @justeattakeaway/pie-button
+
+# yarn
+$ yarn add @justeattakeaway/pie-button
 ```
 
-If you'd like to develop using the component storybook, then you should build the component in `watch` mode, and run storybook in a separate terminal tab:
+For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
 
-```bash
-yarn watch --filter=pie-button
-
-# in a separate terminal tab, run
-yarn dev --filter=pie-storybook
-```
 
 ### Importing the component
 
@@ -67,23 +63,57 @@ import { PieButton } from '@justeattakeaway/pie-button';
 
 import { PieButton } from '@justeattakeaway/pie-button/dist/react';
 ```
+
+
 ## Peer Dependencies
 
-> **Note**
-> Before using `@justeattakeaway/pie-button`, please make sure you have the following peer dependencies installed in your project:
-> - `react` (for integration with React apps only)
+> [!IMPORTANT]
+> When using `pie-button`, you will also need to include a couple of dependencies to ensure the component renders as expected. See [the PIE Wiki for more information and how to include these in your application](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components#expected-dependencies).
+
+
+## Local development
+
+Install the dependencies. Note that this, and the following commands below, should be run from the **root of the monorepo**:
+
+```bash
+yarn
+```
+
+To build the `pie-button` package, run the following command:
+
+```bash
+yarn build --filter=pie-button
+```
+
+If you'd like to develop using the component storybook, then you should build the component in `watch` mode, and run storybook in a separate terminal tab:
+
+```bash
+yarn watch --filter=pie-button
+
+# in a separate terminal tab, run
+yarn dev --filter=pie-storybook
+```
+
 
 ## Props
 
-| Property    | Type      | Default   | Description                                                                                                       |
-|-------------|-----------|-----------|-------------------------------------------------------------------------------------------------------------------|
-| size        | `String`  | `medium`  | Size of the button, one of `sizes` – `xsmall`, `small-expressive`, `small-productive`, `medium`, `large`          |
-| type        | `String`  | `submit`  | Type of the button, one of `types` – `submit`, `button`, `reset`, `menu`                                          |
-| variant     | `String`  | `primary` | Variant of the button, one of `variants` – `primary`, `secondary`, `outline`, `ghost`, `destructive`, `destructive-ghost`, `inverse`, `ghost-inverse` or `outline-inverse` |
-| disabled    | `Boolean` | `false`   | If `true`, disables the button.                                                                                   |
-| isFullWidth | `Boolean` | `false`   | If `true`, sets the button width to 100% of its container.                                                       |
-| isLoading   | `Boolean` | `false`   | If `true`, displays a loading indicator inside the button.                                                        |
-| iconPlacement | `String`  | `leading`   | Icon placements of the icon slot, if provided, one of `iconPlacements` - `leading`, `trailing` |
+| Property       | Type      | Default    | Description                                                                                                          |
+|----------------|-----------|------------|----------------------------------------------------------------------------------------------------------------------|
+| size           | `String`  | `medium`   | Size of the button, one of `sizes` – `xsmall`, `small-expressive`, `small-productive`, `medium`, `large`             |
+| type           | `String`  | `submit`   | Type of the button, one of `types` – `submit`, `button`, `reset`. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type)|
+| variant        | `String`  | `primary`  | Variant of the button, one of `variants` – `primary`, `secondary`, `outline`, `ghost`, `destructive`, `destructive-ghost`, `inverse`, `ghost-inverse`, `outline-inverse` |
+| disabled       | `Boolean` | `false`    | If `true`, disables the button.                                                                                      |
+| isFullWidth    | `Boolean` | `false`    | If `true`, sets the button width to 100% of its container.                                                          |
+| isLoading      | `Boolean` | `false`    | If `true`, displays a loading indicator inside the button.                                                           |
+| iconPlacement  | `String`  | `leading`  | Icon placements of the icon slot, if provided, one of `iconPlacements` - `leading`, `trailing`                       |
+| name           | `String`  | `undefined`| The name of the button, to be submitted with form data. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-name) |
+| value          | `String`  | `undefined`| The value of the button, to be submitted with form data. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-value) |
+| formaction     | `String`  | `undefined`| Designates an alternative URL for form data submission. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formaction) |
+| formenctype    | `String`  | `undefined`| Specifies the form data encoding type. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formenctype) |
+| formmethod     | `String`  | `undefined`| Sets the HTTP method for form data. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formmethod) |
+| formnovalidate | `Boolean` | `undefined`    | Ensures the form is submitted without native HTML validation. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formnovalidate) |
+| formtarget     | `String`  | `undefined`| Dictates where to display the response after form submission. [Read further on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-formtarget) |
+
 
 In your markup or JSX, you can then use these to set the properties for the `pie-button` component:
 
@@ -95,6 +125,7 @@ In your markup or JSX, you can then use these to set the properties for the `pie
 <PieButton size='medium' type='button' variant='primary'>Click me!</PieButton>
 ```
 
+
 ## Slots
 
 | Slot          | Description                                                                                                                        |
@@ -146,6 +177,48 @@ For example, to add a click handler in various templates:
 
 ```
 
+## Forms usage
+
+The `pie-button` web component is designed to integrate with standard HTML forms just like a native HTML button. When positioned inside a form, the component will automatically associate itself, enabling it to directly interact with the form context.
+
+### Button Attributes
+
+The `pie-button` provides a set of attributes to customize its behavior within forms:
+
+- `type`: Determines the button's function. Set to `submit` for form submissions or `reset` to clear form fields.
+- `formaction`: Designates an alternative URL for form data submission when this specific button is clicked.
+- `formenctype`: Specifies the form data encoding type during submission via this button.
+- `formmethod`: Sets the HTTP method (e.g., GET or POST) for form data when initiated by this button.
+- `formnovalidate`: If present, ensures the form is submitted without validation checks.
+- `formtarget`: Dictates where to display the response after form submission.
+
+Please see the [MDN docs]((https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)) for more information on these attributes.
+
+### Integration Example
+
+```html
+<form action="/default-endpoint" method="post">
+    <input type="text" name="username" required>
+    <pie-button
+        type="submit"
+        formaction="/alternate-endpoint"
+        formenctype="multipart/form-data"
+        formmethod="post"
+        formnovalidate
+        formtarget="_blank">
+        Submit
+    </pie-button>
+</form>
+```
+
+In this example:
+
+- The pie-button, when clicked, will send the form data to /alternate-endpoint instead of the form's default /default-endpoint.
+- It uses the multipart/form-data encoding type for form submission.
+- The form will submit using the POST method.
+- No validation will be performed during submission, thanks to formnovalidate.
+- The form's submission response will be opened in a new browser tab/window because of the formtarget="_blank" attribute.
+
 ## Testing
 
 ### Browser tests

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export declare interface ButtonProps {
      */
     size: typeof sizes[number];
     /**
-     * What type attribute should be applied to the button. For example submit, button or menu.
+     * What type attribute should be applied to the button. For example submit, button.
      */
     type: typeof types[number];
     /**
@@ -31,8 +31,52 @@ export declare interface ButtonProps {
      * When true, displays a loading indicator inside the button.
      */
     isLoading: boolean;
+    /**
+     * The name of the button, submitted as a pair with the button's value as part of the form data, when that button is used to submit the form.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    name?: string;
+    /**
+     * Defines the value associated with the button's name when it's submitted with the form data. This value is passed to the server in params when the form is submitted using this button.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    value?: string;
+    /**
+     * The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner. Does nothing if there is no form owner.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    formaction?: string;
+    /**
+     * If the button is a submit button (it's inside/associated with a <form> and doesn't have type="button"), specifies how to encode the form data that is submitted.
+     * If this attribute is specified, it overrides the enctype attribute of the button's form owner.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    formenctype?: typeof formEncodingtypes[number];
+    /**
+     * If the button is a submit button (it's inside/associated with a <form> and doesn't have type="button"), this attribute specifies the HTTP method used to submit the form.
+     * If specified, this attribute overrides the method attribute of the button's form owner.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    formmethod?: typeof formMethodTypes[number];
+    /**
+     * If the button is a submit button, this Boolean attribute specifies that the form is not to be validated when it is submitted.
+     * If this attribute is specified, it overrides the novalidate attribute of the button's form owner.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    formnovalidate?: boolean;
+    /**
+     * If the button is a submit button, this attribute is an author-defined name or standardized, underscore-prefixed keyword indicating where to display the response from submitting the form.
+     * [MDN reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes)
+     */
+    formtarget?: typeof formTargetTypes[number];
 }
 
+export declare const formEncodingtypes: readonly ["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"];
+
+export declare const formMethodTypes: readonly ["post", "get", "dialog"];
+
+export declare const formTargetTypes: readonly ["_self", "_blank", "_parent", "_top"];
+
 export declare const iconPlacements: readonly ["leading", "trailing"];
 
 /**
@@ -40,6 +84,10 @@ export declare const iconPlacements: readonly ["leading", "trailing"];
  * @slot - Default slot
  */
 export declare class PieButton extends LitElement implements ButtonProps {
+    static formAssociated: boolean;
+    private readonly _internals;
+    get form(): HTMLFormElement | null;
+    constructor();
     size: ButtonProps['size'];
     type: ButtonProps['type'];
     variant: ButtonProps['variant'];
@@ -47,6 +95,23 @@ export declare class PieButton extends LitElement implements ButtonProps {
     disabled: boolean;
     isLoading: boolean;
     isFullWidth: boolean;
+    name?: string;
+    value?: string;
+    formaction: ButtonProps['formaction'];
+    formenctype: ButtonProps['formenctype'];
+    formmethod: ButtonProps['formmethod'];
+    formnovalidate: ButtonProps['formnovalidate'];
+    formtarget: ButtonProps['formtarget'];
+    /**
+     * This method creates an invisible button of the same type as pie-button. It is then clicked, and immediately removed from the DOM.
+     * This is done so that we trigger native form actions, such as submit and reset in the browser. The performance impact of adding and removing a single button to the DOM
+     * should be neglible, however this should be monitored.
+     * This is the only viable way of guaranteeing native button behaviour when using a web component in place of an actual HTML button.
+     *
+     * TODO: if we need to repeat this logic elsewhere, then we should consider moving this code to a shared class or mixin.
+     */
+    private _simulateNativeButtonClick;
+    private _handleClick;
     render(): TemplateResult<1>;
     focus(): void;
     static styles: CSSResult;
@@ -54,7 +119,7 @@ export declare class PieButton extends LitElement implements ButtonProps {
 
 export declare const sizes: readonly ["xsmall", "small-productive", "small-expressive", "medium", "large"];
 
-export declare const types: readonly ["submit", "button", "reset", "menu"];
+export declare const types: readonly ["submit", "button", "reset"];
 
 export declare type Variant = typeof variants[number];