@justeattakeaway/pie-button 1.5.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -16
- package/dist/index.d.ts +2 -2
- package/dist/index.js +290 -295
- package/dist/react.d.ts +2 -2
- package/package.json +5 -5
- package/src/index.ts +2 -3
- package/declaration.d.ts +0 -9
package/README.md
CHANGED
|
@@ -1,38 +1,145 @@
|
|
|
1
|
-
|
|
2
|
-
<img align="center" src="../../../readme_image.png" height="200" alt="">
|
|
3
|
-
</p>
|
|
1
|
+
# @justeattakeaway/pie-button
|
|
4
2
|
|
|
5
|
-
<p
|
|
3
|
+
<p>
|
|
6
4
|
<a href="https://www.npmjs.com/@justeattakeaway/pie-button">
|
|
7
5
|
<img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-button.svg">
|
|
8
6
|
</a>
|
|
9
7
|
</p>
|
|
10
8
|
|
|
9
|
+
`@justeattakeaway/pie-button` is a Web Component built using the Lit library. It offers a simple and accessible button component for web applications.
|
|
11
10
|
|
|
12
|
-
##
|
|
11
|
+
## Table of Contents
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [Documentation](#documentation)
|
|
15
|
+
- [Properties](#properties)
|
|
16
|
+
- [Slots](#slots)
|
|
17
|
+
- [CSS Variables](#css-variables)
|
|
18
|
+
- [Events](#events)
|
|
19
|
+
- [Forms Usage](#forms-usage)
|
|
20
|
+
- [Button Attributes](#button-attributes)
|
|
21
|
+
- [Form Integration Example](#form-integration-example)
|
|
22
|
+
- [Usage Examples](#usage-examples)
|
|
23
|
+
- [Questions and Support](#questions-and-support)
|
|
24
|
+
- [Contributing](#contributing)
|
|
15
25
|
|
|
16
|
-
|
|
26
|
+
## Installation
|
|
17
27
|
|
|
28
|
+
> To install any of our web components in your application, we would suggest following the [getting started guide](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) to set up your project.
|
|
18
29
|
|
|
19
|
-
|
|
30
|
+
Ideally, you should install the component using the **`@justeattakeaway/pie-webc`** package, which includes all of the components. Or you can install the individual component package.
|
|
31
|
+
|
|
32
|
+
## Documentation
|
|
33
|
+
|
|
34
|
+
### Properties
|
|
35
|
+
| Prop | Options | Description | Default |
|
|
36
|
+
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
|
|
37
|
+
| `size` | `"xsmall"`, `"small-productive"`, `"small-expressive"`, `"medium"`, `"large"` | Sets the size of the button. | `"medium"` |
|
|
38
|
+
| `isResponsive` | `true`, `false` | If true, uses the next larger size on wide viewports. | `false` |
|
|
39
|
+
| `responsiveSize` | `"productive"`, `"expressive"` | Sets which `"small-"` size an xsmall button should grow to when `isResponsive` is true. | `"productive"` |
|
|
40
|
+
| `type` | `"button"`, `"reset"`, `"submit"` | Sets the type of the button. | `"submit"` |
|
|
41
|
+
| `variant` | `"primary"`, `"primary-alternative"`, `"secondary"`, `"outline"`, `"outline-inverse"`, `"ghost"`, `"inverse"`, `"ghost-inverse"`, `"destructive"`, `"destructive-ghost"` | Sets the variant of the button. | `"primary"` |
|
|
42
|
+
| `disabled` | `true`, `false` | If true, disables the button. | `false` |
|
|
43
|
+
| `isFullWidth` | `true`, `false` | If true, sets the button's width to 100% of its container. | `false` |
|
|
44
|
+
| `isLoading` | `true`, `false` | If true, displays a loading indicator inside the button. | `false` |
|
|
45
|
+
| `iconPlacement` | `"leading"`, `"trailing"` | Sets the position of the icon relative to the text. Leading comes before the text and trailing comes after, taking writing direction into account. To use this, you must pass an icon into the [icon slot](#slots). | `"leading"` |
|
|
46
|
+
| `name` | – | 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. | `undefined` |
|
|
47
|
+
| `value` | – | 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. | `undefined` |
|
|
48
|
+
| `formaction` | – | 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. | `undefined` |
|
|
49
|
+
| `formenctype` | `"application/x-www-form-urlencoded"`, `"multipart/form-data"`, `"text/plain"` | If the button is a submit button, specifies how to encode the form data that is submitted. | `undefined` |
|
|
50
|
+
| `formmethod` | `"post"`, `"get"`, `"dialog"` | If the button is a submit button, this attribute specifies the HTTP method used to submit the form. | `undefined` |
|
|
51
|
+
| `formnovalidate` | `true`, `false` | If the button is a submit button, this Boolean attribute specifies that the form is not to be validated when it is submitted. | `undefined` |
|
|
52
|
+
| `formtarget` | `"_self"`, `"_blank"`, `"_parent"`, `"_top"` | 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. | `undefined` |
|
|
53
|
+
|
|
54
|
+
### Slots
|
|
55
|
+
|
|
56
|
+
| Slot | Description |
|
|
57
|
+
|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
58
|
+
| `default`| The default slot is used to pass text into the button component. |
|
|
59
|
+
| `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. |
|
|
60
|
+
|
|
61
|
+
### CSS Variables
|
|
62
|
+
This component does not expose any CSS variables for style overrides.
|
|
63
|
+
|
|
64
|
+
### Events
|
|
65
|
+
|
|
66
|
+
This component does not emit any custom events. In order to add event listening to this component, you can treat it like a native HTML element in your application.
|
|
67
|
+
|
|
68
|
+
## Forms Usage
|
|
69
|
+
|
|
70
|
+
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.
|
|
71
|
+
|
|
72
|
+
### Button Attributes
|
|
73
|
+
|
|
74
|
+
The `pie-button` provides a set of attributes to customise its behaviour within forms:
|
|
75
|
+
|
|
76
|
+
- `type`: Determines the button's function. Set to `submit` for form submissions or `reset` to clear form fields.
|
|
77
|
+
- `formaction`: Designates an alternative URL for form data submission when this specific button is clicked.
|
|
78
|
+
- `formenctype`: Specifies the form data encoding type during submission via this button.
|
|
79
|
+
- `formmethod`: Sets the HTTP method (e.g., GET or POST) for form data when initiated by this button.
|
|
80
|
+
- `formnovalidate`: If present, ensures the form is submitted without validation checks.
|
|
81
|
+
- `formtarget`: Dictates where to display the response after form submission.
|
|
82
|
+
|
|
83
|
+
### Form Integration Example
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<form action="/default-endpoint" method="post">
|
|
87
|
+
<input type="text" name="username" required>
|
|
88
|
+
<pie-button
|
|
89
|
+
type="submit"
|
|
90
|
+
formaction="/alternate-endpoint"
|
|
91
|
+
formenctype="multipart/form-data"
|
|
92
|
+
formmethod="post"
|
|
93
|
+
formnovalidate
|
|
94
|
+
formtarget="_blank">
|
|
95
|
+
Submit
|
|
96
|
+
</pie-button>
|
|
97
|
+
</form>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
In this example:
|
|
101
|
+
|
|
102
|
+
- The pie-button, when clicked, will send the form data to /alternate-endpoint instead of the form's default /default-endpoint.
|
|
103
|
+
- It uses the multipart/form-data encoding type for form submission.
|
|
104
|
+
- The form will submit using the POST method.
|
|
105
|
+
- No validation will be performed during submission, thanks to formnovalidate.
|
|
106
|
+
- The form's submission response will be opened in a new browser tab/window because of the formtarget="_blank" attribute.
|
|
20
107
|
|
|
21
|
-
|
|
108
|
+
## Usage Examples
|
|
22
109
|
|
|
23
|
-
|
|
24
|
-
npm i @justeattakeaway/pie-button
|
|
110
|
+
**For HTML:**
|
|
25
111
|
|
|
26
|
-
|
|
112
|
+
```js
|
|
113
|
+
// import as module into a js file e.g. main.js
|
|
114
|
+
import '@justeattakeaway/pie-webc/components/button.js'
|
|
27
115
|
```
|
|
28
116
|
|
|
29
|
-
|
|
117
|
+
```html
|
|
118
|
+
<!-- pass js file into <script> tag -->
|
|
119
|
+
<pie-button type="reset" isFullWidth="true" onclick="e => console.log(e)">Click me!</pie-button>
|
|
120
|
+
<script type="module" src="/main.js"></script>
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**For Native JS Applications, Vue, Angular, Svelte etc.:**
|
|
30
124
|
|
|
31
|
-
|
|
125
|
+
```js
|
|
126
|
+
// Vue templates (using Nuxt 3)
|
|
127
|
+
import '@justeattakeaway/pie-webc/components/button.js';
|
|
128
|
+
|
|
129
|
+
<pie-button @click="handleClick" size="large" type="button" variant="secondary">Click me!</pie-button>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**For React Applications:**
|
|
133
|
+
|
|
134
|
+
```jsx
|
|
135
|
+
import { PieButton } from '@justeattakeaway/pie-webc/react/button.js';
|
|
136
|
+
|
|
137
|
+
<PieButton onClick={handleClick}>increment</PieButton>
|
|
138
|
+
```
|
|
32
139
|
|
|
33
|
-
## Questions
|
|
140
|
+
## Questions and Support
|
|
34
141
|
|
|
35
|
-
|
|
142
|
+
If you work at Just Eat Takeaway.com, please contact us on **#help-designsystem**. Otherwise, please raise an issue on [Github](https://github.com/justeattakeaway/pie/issues).
|
|
36
143
|
|
|
37
144
|
## Contributing
|
|
38
145
|
|
package/dist/index.d.ts
CHANGED
|
@@ -125,9 +125,9 @@ export declare class PieButton extends PieButton_base implements ButtonProps {
|
|
|
125
125
|
disconnectedCallback(): void;
|
|
126
126
|
updated(changedProperties: PropertyValues<this>): void;
|
|
127
127
|
tag: "button" | "a";
|
|
128
|
-
size: "xsmall" | "
|
|
128
|
+
size: "xsmall" | "small-productive" | "small-expressive" | "medium" | "large";
|
|
129
129
|
type: "button" | "submit" | "reset";
|
|
130
|
-
variant: "
|
|
130
|
+
variant: "primary" | "primary-alternative" | "secondary" | "outline" | "outline-inverse" | "ghost" | "inverse" | "ghost-inverse" | "destructive" | "destructive-ghost";
|
|
131
131
|
iconPlacement: "leading" | "trailing";
|
|
132
132
|
disabled: boolean;
|
|
133
133
|
isLoading: boolean;
|