@justeattakeaway/pie-button 0.0.0-snapshot-release-20231212141542

package/README.md

@@ -0,0 +1,207 @@
+<p align="center">
+  <img align="center" src="../../../readme_image.png" height="200" alt="">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/@justeattakeaway/pie-button">
+    <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-button.svg">
+  </a>
+</p>
+
+# Table of Contents
+
+1. [Introduction](#pie-button)
+2. [Installation](#installation)
+3. [Importing the component](#importing-the-component)
+4. [Peer Dependencies](#peer-dependencies)
+5. [Props](#props)
+6. [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)
+7. [Forms usage](#forms-usage)
+8. [Contributing](#contributing)
+
+
+## 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.
+
+
+## Installation
+
+To install `pie-button` in your application, run the following on your command line:
+
+```bash
+# npm
+$ npm i @justeattakeaway/pie-button
+
+# yarn
+$ yarn add @justeattakeaway/pie-button
+```
+
+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).
+
+
+### Importing the component
+
+#### JavaScript
+```js
+// Default – for Native JS Applications, Vue, Angular, Svelte, etc.
+import { PieButton } from '@justeattakeaway/pie-button';
+
+// If you don't need to reference the imported object, you can simply
+// import the module which registers the component as a custom element.
+import '@justeattakeaway/pie-button';
+```
+
+#### React
+```js
+// React
+// For React, you will need to import our React-specific component build
+// which wraps the web component using ​@lit/react
+import { PieButton } from '@justeattakeaway/pie-button/dist/react';
+```
+
+> [!NOTE]
+> When using the React version of the component, please make sure to also
+> include React as a [peer dependency](#peer-dependencies) in your project.
+
+
+## Peer Dependencies
+
+> [!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).
+
+
+## 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`. [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.                                                           |
+| isResponsive   | `Boolean` | `false`    | If `true`, uses the next larger size on wide viewports.                                                              |
+| 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) |
+| responsiveSize | `String`  | `productive`| Sets a specific size for xsmall button when rendered as responsive. It can be `productive` or `expressive`.         |
+
+
+In your markup or JSX, you can then use these to set the properties for the `pie-button` component:
+
+```html
+<!-- Native HTML -->
+<pie-button size='medium' type='button' variant='primary'>Click me!</pie-button>
+
+<!-- JSX -->
+<PieButton size='medium' type='button' variant='primary'>Click me!</PieButton>
+```
+
+
+## Slots
+
+| Slot          | Description                                                                                                                        |
+|---------------|------------------------------------------------------------------------------------------------------------------------------------|
+| Default slot  | The default slot is used to pass text into the button component.                                                                   |
+| icon         | Used to pass in an icon to the button component. The icon placement can be controlled via the `iconPlacement` prop and we recommend using `pie-icons-webc` for defining this icon, but this can also accept an SVG icon. |
+
+### Using `pie-icons-webc` with `pie-button` icon slot
+
+We recommend using `pie-icons-webc` when using the `icon` slot. Here is an example of how you would do this:
+
+```html
+<!--
+  Note that pie-button and the icon that you want to use will need to be imported as components into your application.
+  See the `pie-icons-webc` README for more info on importing these icons.
+-->
+<pie-button>
+    <icon-plus-circle slot="icon"></icon-plus-circle>
+    Search
+</pie-button>
+```
+
+
+## Events
+
+This component does not use any custom event handlers. In order to add event listening to this component, you can treat it like a native HTML element in your application.
+
+For example, to add a click handler in various templates:
+
+### HTML
+
+```html
+<!-- Other attributes omitted for clarity -->
+<pie-button onclick="e => console.log(e)">Click me!</pie-button>
+```
+
+### Vue templates (using Nuxt 3)
+
+```html
+<!-- Other attributes omitted for clarity -->
+<pie-button @click="handleClick">Click me!</pie-button>
+```
+
+### React templates (using Next 13)
+
+```html
+<!-- Other attributes omitted for clarity -->
+<PieButton onClick={handleClick}>increment</PieButton>
+
+```
+
+## 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.
+
+## Contributing
+
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

package/declaration.d.ts

@@ -0,0 +1,9 @@
+declare module '*.scss' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module '*.scss?inline' {
+    const content: Record<string, string>;
+    export default content;
+}

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import type { CSSResult } from 'lit';
+import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
+import type { TemplateResult } from 'lit';
+
+export declare interface ButtonProps {
+    /**
+     * What size the button should be.
+     */
+    size: typeof sizes[number];
+    /**
+     * What type attribute should be applied to the button. For example submit, button.
+     */
+    type: typeof types[number];
+    /**
+     * What style variant the button should be such as primary, outline or ghost.
+     */
+    variant: Variant;
+    /**
+     * The placement of the icon slot, if provided, such as leading or trailing
+     */
+    iconPlacement?: typeof iconPlacements[number];
+    /**
+     * When true, the button element is disabled.
+     */
+    disabled: boolean;
+    /**
+     * When true, the button element will occupy the full width of its container.
+     */
+    isFullWidth: boolean;
+    /**
+     * When true, displays a loading indicator inside the button.
+     */
+    isLoading: boolean;
+    /**
+     * When true, enables the responsive size feature.
+     */
+    isResponsive: 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];
+    /**
+     * What size should be attributed to the button when isResponsive is true and the screen is wide.
+     */
+    responsiveSize?: typeof responsiveSizes[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"];
+
+/**
+ * @tagname pie-button
+ * @slot icon - The icon slot
+ * @slot - Default slot
+ */
+export declare class PieButton extends LitElement implements ButtonProps {
+    static formAssociated: boolean;
+    private readonly _internals;
+    get form(): HTMLFormElement | null;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changedProperties: PropertyValues<this>): void;
+    size: ButtonProps['size'];
+    type: ButtonProps['type'];
+    variant: ButtonProps['variant'];
+    iconPlacement: ButtonProps['iconPlacement'];
+    disabled: boolean;
+    isLoading: boolean;
+    isFullWidth: boolean;
+    isResponsive: boolean;
+    name?: string;
+    value?: string;
+    formaction: ButtonProps['formaction'];
+    formenctype: ButtonProps['formenctype'];
+    formmethod: ButtonProps['formmethod'];
+    formnovalidate: ButtonProps['formnovalidate'];
+    formtarget: ButtonProps['formtarget'];
+    responsiveSize?: ButtonProps['responsiveSize'];
+    /**
+     * 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;
+    private _handleFormKeyDown;
+    /**
+     * Template for the loading state
+     *
+     * @private
+     */
+    private renderSpinner;
+    render(): TemplateResult<1>;
+    focus(): void;
+    static styles: CSSResult;
+}
+
+export declare const responsiveSizes: readonly ["productive", "expressive"];
+
+export declare const sizes: readonly ["xsmall", "small-productive", "small-expressive", "medium", "large"];
+
+export declare const types: readonly ["submit", "button", "reset"];
+
+export declare type Variant = typeof variants[number];
+
+export declare const variants: readonly ["primary", "secondary", "outline", "outline-inverse", "ghost", "inverse", "ghost-inverse", "destructive", "destructive-ghost"];
+
+export { }