@justeattakeaway/pie-textarea 0.16.3 → 0.16.5

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 CHANGED
@@ -1,39 +1,181 @@
1
- <p align="center">
2
- <img align="center" src="../../../readme_image.png" height="200" alt="">
3
- </p>
1
+ # @justeattakeaway/pie-textarea
2
+ [Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-textarea) | [Design Documentation](https://pie.design/components/text-area) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-textarea)
4
3
 
5
- <p align="center">
4
+ <p>
6
5
  <a href="https://www.npmjs.com/@justeattakeaway/pie-textarea">
7
6
  <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-textarea.svg">
8
7
  </a>
9
8
  </p>
10
9
 
11
- ## pie-textarea
12
-
13
- `pie-textarea` is a Web Component built using the Lit library.
10
+ `@justeattakeaway/pie-textarea` is a Web Component built using the Lit library. It offers a simple and accessible textarea component for web applications.
14
11
 
15
- This component can be easily integrated into various frontend frameworks and customized through a set of properties.
12
+ ## Table of Contents
16
13
 
14
+ - [Installation](#installation)
15
+ - [Documentation](#documentation)
16
+ - [Properties](#properties)
17
+ - [Slots](#slots)
18
+ - [CSS Variables](#css-variables)
19
+ - [Events](#events)
20
+ - [Forms Usage](#forms-usage)
21
+ - [Validation](#validation)
22
+ - [Example](#example)
23
+ - [Displaying error messages](#displaying-error-messages)
24
+ - [Usage Examples](#usage-examples)
25
+ - [Questions and Support](#questions-and-support)
26
+ - [Contributing](#contributing)
17
27
 
18
28
  ## Installation
19
29
 
20
- To install `pie-textarea` in your application, run the following on your command line:
30
+ > 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.
31
+
32
+ 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.
33
+
34
+ ## Documentation
35
+
36
+ ### Properties
37
+ | Prop | Options | Description | Default |
38
+ |----------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
39
+ | `assistiveText`| `string` | Allows assistive text to be displayed below the textarea. Must be provided if using a non-default status. | `undefined` |
40
+ | `autocomplete` | `string` | Allows enabling or disabling autocomplete. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for values. | `undefined` |
41
+ | `autoFocus` | `true`, `false` | If true, focuses the textarea on first render. Only one element should have `autofocus`. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus). | `false` |
42
+ | `defaultValue` | `string` | Value used during a form reset to replace the current value. | `undefined` |
43
+ | `disabled` | `true`, `false` | When true, the user cannot edit or interact with the textarea. | `false` |
44
+ | `name` | `string` | Name of the textarea (used in form key/value pairs). | `undefined` |
45
+ | `placeholder` | `string` | Placeholder text shown when textarea is empty. | `""` |
46
+ | `readonly` | `true`, `false` | When true, the user cannot edit the textarea. Not the same as disabled. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly). | `false` |
47
+ | `required` | `true`, `false` | If true, textarea must have a value for valid form submission. Does not block form submission by itself. | `false` |
48
+ | `resize` | `"auto"`, `"manual"` | Controls resizing behavior. `auto` resizes vertically as needed; `manual` allows user resizing but no auto resizing. | `"auto"` |
49
+ | `size` | `"small"`, `"medium"`, `"large"` | Sets the visual size of the textarea. | `"medium"` |
50
+ | `status` | `"default"`, `"error"`, `"success"` | Status of the component. If not `default`, `assistiveText` must be provided for accessibility. | `"default"` |
51
+ | `value` | `string` | Value of the textarea (used in form key/value pairs). | `""` |
52
+
53
+ ### Slots
54
+ This component does not have any slots. All content is controlled through properties.
55
+
56
+ ### CSS Variables
57
+ This component does not expose any CSS variables for style overrides.
58
+
59
+ ### Events
60
+ | Event | Description |
61
+ |----------|---------------------------------------------------------------------------|
62
+ | `change` | Fires when the textarea loses focus after the value has been changed. |
63
+ | `input` | Fires when the textarea value is changed. |
64
+
65
+ ## Forms Usage
66
+ It is essential that when using the textarea inside the form, you provide a `name` attribute. HTML forms create key/value pairs for textarea data based on the `name` attribute, which is crucial for native form submission.
67
+
68
+ ### Validation
69
+ The textarea component utilizes the [constraint validation API](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation) to provide a queryable validity state for consumers. This means that the component's validity can be checked via a `validity` getter.
70
+
71
+ #### Example:
72
+ ```js
73
+ const textarea = document.querySelector('pie-textarea');
74
+ console.log(textarea.validity.valid);
75
+ ```
21
76
 
22
- ```bash
23
- npm i @justeattakeaway/pie-textarea
77
+ This getter can be useful for reducing the amount of validation code in your application. For example, if you want to create a textarea that requires attention, you can set the `required` property on the component. You can then check the validity of the input in your application code:
24
78
 
25
- yarn add @justeattakeaway/pie-textarea
79
+ ```html
80
+ <pie-textarea
81
+ id="my-textarea"
82
+ required>
83
+ </pie-textarea>
26
84
  ```
27
85
 
28
- 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).
86
+ ```js
87
+ const textarea = document.querySelector('pie-textarea');
88
+ const isValid = textarea.validity.valid;
29
89
 
30
- ## Documentation
90
+ // We could use this to drive the status and assistiveText properties on our textarea (this would likely be inside a submit event handler in a real application)
91
+ if (!isValid) {
92
+ textarea.status = 'error';
93
+ textarea.assistiveText = 'This textarea is required';
94
+ }
95
+ ```
96
+
97
+ These concepts work just as well inside a Vue or React application.
98
+
99
+ > Using the constraint validation API we provide is completely optional. Feel free to use whatever form of validation best suits your application's needs. The validity state of a textarea will not interfere with the form submission or page behaviour.
100
+
101
+ #### Displaying error messages
102
+ As mentioned earlier, we suggest consumers disable native HTML validation using the `novalidate` attribute on the form element. This will prevent the browser from displaying its own validation messages, allowing you to control the validation experience for your users.
103
+
104
+ To display validation messages, you can use the `assistiveText` and `status` properties on the textarea component. The `assistiveText` property is used to display a message below the textarea, and the `status` property is used to set the visual state of the textarea. The `status` property can be set to `error` or `success`, or you can omit providing a `status` to display the `assistiveText` in a neutral state.
105
+
106
+ ```html
107
+ <pie-textarea
108
+ name="details"
109
+ assistiveText="Please provide more details"
110
+ status="error">
111
+ </pie-textarea>
112
+ ```
113
+
114
+ Displaying success messages works in the same way, but with the `status` property set to `success`.
31
115
 
32
- Visit [Textarea | PIE Design System](https://pie.design/components/textarea) to view more information on this component.
116
+ ```html
117
+ <pie-textarea
118
+ name="details"
119
+ assistiveText="Please provide more details"
120
+ status="success">
121
+ </pie-textarea>
122
+ ```
123
+
124
+ ## Usage Examples
125
+
126
+ **For HTML:**
127
+
128
+ ```js
129
+ // import as module into a js file e.g. main.js
130
+ import '@justeattakeaway/pie-webc/components/textarea.js';
131
+ ```
132
+
133
+ ```html
134
+ <pie-textarea
135
+ name="my-textarea"
136
+ placeholder="Please enter a value"
137
+ autocomplete="on"
138
+ value=""
139
+ autoFocus
140
+ readonly>
141
+ </pie-textarea>
142
+ <script type="module" src="/main.js"></script>
143
+ ```
144
+
145
+ **For Native JS Applications, Vue, Angular, Svelte etc.:**
146
+
147
+ ```js
148
+ // Vue templates (using Nuxt 3)
149
+ import '@justeattakeaway/pie-webc/components/textarea.js';
150
+
151
+ <pie-textarea
152
+ name="my-textarea"
153
+ placeholder="Please enter a value"
154
+ autocomplete="on"
155
+ value=""
156
+ autoFocus
157
+ readonly>
158
+ </pie-textarea>
159
+ ```
160
+
161
+ **For React Applications:**
162
+
163
+ ```jsx
164
+ import { PieTextarea } from '@justeattakeaway/pie-webc/react/textarea.js';
165
+
166
+ <PieTextarea
167
+ name="my-textarea"
168
+ placeholder="Please enter a value"
169
+ autocomplete="on"
170
+ value=""
171
+ autoFocus
172
+ readonly>
173
+ </PieTextarea>
174
+ ```
33
175
 
34
- ## Questions
176
+ ## Questions and Support
35
177
 
36
- Please head to [FAQs | PIE Design System](https://pie.design/support/contact-us/) to see our FAQs and get in touch.
178
+ 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).
37
179
 
38
180
  ## Contributing
39
181
 
@@ -42,7 +42,7 @@
42
42
  "type": {
43
43
  "text": "DefaultProps"
44
44
  },
45
- "default": "{\r\n disabled: false,\r\n size: 'medium',\r\n resize: 'auto',\r\n value: '',\r\n placeholder: '',\r\n status: 'default',\r\n autoFocus: false,\r\n readonly: false,\r\n required: false,\r\n}",
45
+ "default": "{\n disabled: false,\n size: 'medium',\n resize: 'auto',\n value: '',\n placeholder: '',\n status: 'default',\n autoFocus: false,\n readonly: false,\n required: false,\n}",
46
46
  "description": "Default values for optional properties that have default fallback values in the component."
47
47
  }
48
48
  ],
@@ -230,7 +230,7 @@
230
230
  "text": "ValidityState"
231
231
  },
232
232
  "privacy": "public",
233
- "description": "(Read-only) returns a ValidityState with the validity states that this element is in.\r\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity",
233
+ "description": "(Read-only) returns a ValidityState with the validity states that this element is in.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity",
234
234
  "readonly": true
235
235
  },
236
236
  {
@@ -251,7 +251,7 @@
251
251
  "description": "The latest disabled state of the input."
252
252
  }
253
253
  ],
254
- "description": "Called after the disabled state of the element changes,\r\neither because the disabled attribute of this element was added or removed;\r\nor because the disabled state changed on a <fieldset> that's an ancestor of this element."
254
+ "description": "Called after the disabled state of the element changes,\neither because the disabled attribute of this element was added or removed;\nor because the disabled state changed on a <fieldset> that's an ancestor of this element."
255
255
  },
256
256
  {
257
257
  "kind": "method",
@@ -262,7 +262,7 @@
262
262
  "text": "void"
263
263
  }
264
264
  },
265
- "description": "Called when the form that owns this component is reset.\r\nResets the value to the default value."
265
+ "description": "Called when the form that owns this component is reset.\nResets the value to the default value."
266
266
  },
267
267
  {
268
268
  "kind": "method",
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@ const _ = class _ extends D {
10
10
  this.getAttribute("v") || this.setAttribute("v", _.v);
11
11
  }
12
12
  };
13
- _.v = "0.16.3";
13
+ _.v = "0.16.5";
14
14
  let w = _;
15
15
  var $ = typeof globalThis < "u" ? globalThis : typeof window < "u" ? window : typeof global < "u" ? global : typeof self < "u" ? self : {};
16
16
  function Z(e) {
@@ -102,7 +102,7 @@ function A(e) {
102
102
  return r || ie.test(e) ? oe(e.slice(2), r ? 2 : 8) : re.test(e) ? M : +e;
103
103
  }
104
104
  var ge = fe;
105
- const be = /* @__PURE__ */ Z(ge), me = "*,*:after,*:before{box-sizing:inherit}.c-textareaWrapper{--textarea-line-height: calc(var(--dt-font-body-l-line-height) * 1px);--textarea-border-thickness: 1px;--textarea-resize: none;--textarea-padding-inline: var(--dt-spacing-c);--textarea-padding-block: var(--dt-spacing-b);--textarea-background-color: var(--dt-color-container-default);--textarea-border-color: var(--dt-color-border-form);--textarea-content-color: var(--dt-color-content-default);--textarea-placeholder-color: var(--dt-color-content-placeholder);--textarea-height: calc((var(--textarea-line-height) * 2) + (var(--textarea-padding-block) * 2));line-height:0;padding:var(--dt-spacing-a);border:var(--textarea-border-thickness) solid var(--textarea-border-color);background-color:var(--textarea-background-color);border-radius:var(--dt-radius-rounded-c);inline-size:100%}.c-textareaWrapper textarea{font-size:calc(var(--dt-font-body-l-size) * 1px);line-height:var(--textarea-line-height);font-family:var(--dt-font-body-l-family);resize:var(--textarea-resize);border:none;background-color:var(--textarea-background-color);color:var(--textarea-content-color);block-size:var(--textarea-height);max-block-size:var(--textarea-max-height);min-block-size:var(--textarea-min-height);inline-size:100%;padding-block-start:var(--textarea-padding-block);padding-block-end:var(--textarea-padding-block);padding-inline-start:var(--textarea-padding-inline);padding-inline-end:var(--textarea-padding-inline)}.c-textareaWrapper textarea:focus{box-shadow:none;outline:none}.c-textareaWrapper textarea::placeholder{color:var(--textarea-placeholder-color);opacity:1}.c-textareaWrapper.c-textarea--readonly{--textarea-background-color: var(--dt-color-container-subtle);--textarea-border-color: var(--dt-color-border-form)}.c-textareaWrapper.is-disabled{--textarea-background-color: var(--dt-color-disabled-01);--textarea-border-color: var(--dt-color-disabled-01);--textarea-content-color: var(--dt-color-content-disabled);--textarea-placeholder-color: var(--dt-color-content-disabled)}@media (hover: hover){.c-textareaWrapper:hover:not(.is-disabled,.c-textarea--readonly){--textarea-background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + calc(-1 * var(--dt-color-hover-01))))}@supports (background-color: color-mix(in srgb,black,white)){.c-textareaWrapper:hover:not(.is-disabled,.c-textarea--readonly){--textarea-background-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}}.c-textareaWrapper:focus-within{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-textareaWrapper.c-textarea--large{--textarea-padding-block: var(--dt-spacing-c)}.c-textareaWrapper.c-textarea--small{--textarea-padding-block: var(--dt-spacing-a)}.c-textareaWrapper.c-textarea--resize-manual{--textarea-resize: vertical;--textarea-min-height: calc((var(--textarea-line-height) * 1) + (var(--textarea-padding-block) * 2))}@media (pointer: coarse){.c-textareaWrapper.c-textarea--resize-manual{--textarea-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-min-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-max-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-resize: none}}.c-textareaWrapper.c-textarea--resize-auto{--textarea-max-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-min-height: var(--textarea-height)}.c-textareaWrapper.c-textarea--error{--textarea-border-color: var(--dt-color-support-error)}", ye = ["small", "medium", "large"], ze = ["auto", "manual"], ke = ["default", "success", "error"], u = {
105
+ const be = /* @__PURE__ */ Z(ge), me = "*,*:after,*:before{box-sizing:inherit}:host{display:block}.c-textareaWrapper{--textarea-line-height: calc(var(--dt-font-body-l-line-height) * 1px);--textarea-border-thickness: 1px;--textarea-resize: none;--textarea-padding-inline: var(--dt-spacing-c);--textarea-padding-block: var(--dt-spacing-b);--textarea-background-color: var(--dt-color-container-default);--textarea-border-color: var(--dt-color-border-form);--textarea-content-color: var(--dt-color-content-default);--textarea-placeholder-color: var(--dt-color-content-placeholder);--textarea-height: calc((var(--textarea-line-height) * 2) + (var(--textarea-padding-block) * 2));line-height:0;padding:var(--dt-spacing-a);border:var(--textarea-border-thickness) solid var(--textarea-border-color);background-color:var(--textarea-background-color);border-radius:var(--dt-radius-rounded-c);inline-size:100%}.c-textareaWrapper textarea{font-size:calc(var(--dt-font-body-l-size) * 1px);line-height:var(--textarea-line-height);font-family:var(--dt-font-body-l-family);resize:var(--textarea-resize);border:none;background-color:var(--textarea-background-color);color:var(--textarea-content-color);block-size:var(--textarea-height);max-block-size:var(--textarea-max-height);min-block-size:var(--textarea-min-height);inline-size:100%;padding-block-start:var(--textarea-padding-block);padding-block-end:var(--textarea-padding-block);padding-inline-start:var(--textarea-padding-inline);padding-inline-end:var(--textarea-padding-inline)}.c-textareaWrapper textarea:focus{box-shadow:none;outline:none}.c-textareaWrapper textarea::placeholder{color:var(--textarea-placeholder-color);opacity:1}.c-textareaWrapper.c-textarea--readonly{--textarea-background-color: var(--dt-color-container-subtle);--textarea-border-color: var(--dt-color-border-form)}.c-textareaWrapper.is-disabled{--textarea-background-color: var(--dt-color-disabled-01);--textarea-border-color: var(--dt-color-disabled-01);--textarea-content-color: var(--dt-color-content-disabled);--textarea-placeholder-color: var(--dt-color-content-disabled)}@media (hover: hover){.c-textareaWrapper:hover:not(.is-disabled,.c-textarea--readonly){--textarea-background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + calc(-1 * var(--dt-color-hover-01))))}@supports (background-color: color-mix(in srgb,black,white)){.c-textareaWrapper:hover:not(.is-disabled,.c-textarea--readonly){--textarea-background-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}}.c-textareaWrapper:focus-within{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-textareaWrapper.c-textarea--large{--textarea-padding-block: var(--dt-spacing-c)}.c-textareaWrapper.c-textarea--small{--textarea-padding-block: var(--dt-spacing-a)}.c-textareaWrapper.c-textarea--resize-manual{--textarea-resize: vertical;--textarea-min-height: calc((var(--textarea-line-height) * 1) + (var(--textarea-padding-block) * 2))}@media (pointer: coarse){.c-textareaWrapper.c-textarea--resize-manual{--textarea-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-min-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-max-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-resize: none}}.c-textareaWrapper.c-textarea--resize-auto{--textarea-max-height: calc((var(--textarea-line-height) * 6) + (var(--textarea-padding-block) * 2));--textarea-min-height: var(--textarea-height)}.c-textareaWrapper.c-textarea--error{--textarea-border-color: var(--dt-color-support-error)}", ye = ["small", "medium", "large"], ze = ["auto", "manual"], ke = ["default", "success", "error"], u = {
106
106
  disabled: !1,
107
107
  size: "medium",
108
108
  resize: "auto",
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@justeattakeaway/pie-textarea",
3
3
  "description": "PIE Design System Textarea built using Web Components",
4
- "version": "0.16.3",
4
+ "version": "0.16.5",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "module": "dist/index.js",
@@ -40,7 +40,7 @@
40
40
  "cem-plugin-module-file-extensions": "0.0.5"
41
41
  },
42
42
  "dependencies": {
43
- "@justeattakeaway/pie-assistive-text": "0.10.3",
43
+ "@justeattakeaway/pie-assistive-text": "0.10.5",
44
44
  "@justeattakeaway/pie-webc-core": "1.0.0",
45
45
  "lodash.throttle": "4.1.1"
46
46
  },
package/src/textarea.scss CHANGED
@@ -1,5 +1,9 @@
1
1
  @use '@justeattakeaway/pie-css/scss' as p;
2
2
 
3
+ :host {
4
+ display: block;
5
+ }
6
+
3
7
  // Heights are being defined based on the line height of the text and the padding.
4
8
  // Some of the padding is in the wrapper element to properly position the textarea resize handle.
5
9
  // Changing the `size` property affects the padding and therefore the height of the textarea.