uni-textarea-field 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# uni-textarea-field
+
+[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/uni-input-field) [![DeepScan grade](https://deepscan.io/api/teams/16372/projects/31962/branches/1038048/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=16372&pid=31962&bid=1038048)
+
+<uni-textarea-field /> is an encapsulated Web Component built upon the foundation of the uniopen design language.
+
+Implementation is straightforward: simply slot a standard textarea element inside <uni-textarea-field />. The component instantly applies a user interface that aligns seamlessly with the uniopen design language guidelines. Furthermore, its visual styles can be dynamically adapted via native HTML attributes or JavaScript properties.
+
+The component also exposes comprehensive character count and textarea length metadata, providing users with a clear and intuitive understanding of predefined character constraints.
+
+![<uni-textarea-field />](https://blog.lalacube.com/mei/img/preview/uni-textarea-field.png)
+
+## Basic Usage
+
+&lt;uni-textarea-field /> is a web component. All we need to do is put the required script into your HTML document. Then follow &lt;uni-textarea-field />'s html structure and everything will be all set.
+
+- Required Script
+
+  ```html
+  <script
+    type="module"
+    src="https://unpkg.com/uni-textarea-field/mjs/wc-uni-textarea-field.js">        
+  </script>
+  ```
+
+- Structure
+
+  Put &lt;uni-textarea-field /> into HTML document. It will have different functions and looks with attribute mutation.
+  
+  ```html
+  <uni-textarea-field subject="Subject" message="Supporting text">
+    <textarea
+      slot="textarea"
+      placeholder="placeholder"
+      required
+      maxlength="30"
+    ></textarea>
+  </uni-textarea-field>
+  ```
+
+&lt;uni-textarea-field /> dynamically adjusts its user interface and core functionality by strictly adhering to the attributes of the encapsulated `textarea` element. Developers can leverage these capabilities and observe the corresponding behavioral shifts by modifying standard attributes—such as `readonly`, `disabled`, `required`, and `maxlength`—directly on the textarea element.
+
+```html
+<uni-textarea-field>
+  <textarea
+    slot="textarea"
+    readonly
+    required
+  ><textarea>
+</uni-textarea-field>
+```
+
+## JavaScript Instantiation
+
+&lt;uni-textarea-field /> could also use JavaScript to create DOM element. Here comes some examples.
+
+```html
+<script type="module">
+import { UniTextareaField } from 'https://unpkg.com/uni-textarea-field/mjs/wc-uni-textarea-field.js';
+
+const textareaTemplate = document.querySelector('.my-textarea-template');
+
+// use DOM api
+const nodeA = document.createElement('uni-textarea-field');
+nodeA.appendChild(textareaTemplate.content.cloneNode(true));
+document.body.appendChild(nodeA);
+
+// new instance with Class
+const nodeB = new UniTextareaField();
+nodeB.appendChild(textareaTemplate.content.cloneNode(true));
+document.body.appendChild(nodeB);
+</script>
+```
+
+## Style Customization
+
+Developers could apply styles to decorate &lt;uni-textarea-field />'s looking.
+
+```html
+<style>
+uni-textarea-field {
+  --uni-textarea-field-border-color-normal: transparent;
+  --uni-textarea-field-border-color-readonly: var(--ct_input-general_dim_container_default);
+  --uni-textarea-field-border-color-disabled: var(--ct_input-general_dim_container_default);
+  --uni-textarea-field-border-color-valid: var(--ct_text_success_general);
+  --uni-textarea-field-border-color-invalid: var(--ct_text_danger_general);
+  --uni-textarea-field-border-color-outline: var(--ct_input-general_main_stroke_default);
+
+  --uni-textarea-field-background-color-normal: var(--ct_input-general_dim_container_default);
+  --uni-textarea-field-background-color-readonly: var(--ct_input-general_dim_container_default);
+  --uni-textarea-field-background-color-disabled: var(--ct_input-general_dim_container_default);
+
+  --uni-textarea-field-placeholder-color-normal: var(--ct_text_main_subtlest);
+  --uni-textarea-field-placeholder-color-readonly: var(--ct_text_main_subtlest);
+  --uni-textarea-field-placeholder-color-disabled: var(--ct_text_main_subtlest);
+
+  --uni-textarea-field-text-color-normal: var(--ct_text_main_general);
+  --uni-textarea-field-text-color-readonly: var(--ct_text_main_general);
+  --uni-textarea-field-text-color-disabled: var(--ct_text_main_pale);
+  --uni-textarea-field-text-color-invalid: var(--ct_text_danger_general);
+
+  --uni-textarea-field-message-color-normal: var(--ct_text_main_subtle);
+  --uni-textarea-field-message-color-valid: var(--ct_text_success_general);
+  --uni-textarea-field-message-color-invalid: var(--ct_text_danger_general);
+
+  --uni-textarea-field-subject-color: var(--ct_text_main_subtle);
+  --uni-textarea-field-counter-color: var(--ct_text_main_subtle);
+  --uni-textarea-field-caret-color: var(--ct_input-caret_main_general);
+
+  --uni-textarea-field-min-block-size: 100px;
+}
+</style>
+```
+
+&lt;uni-textarea-field /> also leverages the CSS ::part() selector, enabling developers to directly customize and style the icon.
+
+```html
+<style>
+uni-textarea-field {
+  &::part(icon-subject) {
+    ...
+  }
+}
+</style>
+```
+
+Alternatively, developers can utilize the `data-hide-counter` data attribute to suppress the character counter.
+
+```html
+<uni-textarea-field data-hide-counter>
+  <textarea>
+    slot="textarea"
+    placeholder="placeholder"
+    required
+    maxlength="30"
+  ><textarea>
+</uni-textarea-field>
+```
+
+## Attributes
+
+&lt;uni-textarea-field /> component exposes a curated set of attributes, enabling developers to dynamically adjust the user interface. This provides the flexibility to tailor the component’s appearance to seamlessly adapt to any given context.
+
+- **size**
+
+  The `size` attribute configures the overall dimensions of &lt;uni-textarea-field />. The component currently supports three standard options: `large`, `medium`, and `small`, defaulting to `medium`.
+
+  ```html
+  <uni-textarea-field
+    size="large"
+  >
+    <textarea
+      slot="textarea"
+      maxlength="200"
+    ><textarea>
+  </uni-textarea-field>
+  ```
+
+  - **subject**
+
+  The `subject` attribute controls the dynamic rendering of the subject content on &lt;uni-textarea-field />. By default, it is set to an empty string, meaning no content will be displayed.
+
+  ```html
+  <uni-textarea-field
+    subject="Your subject"
+  >
+    <textarea
+      slot="textarea"
+      maxlength="200"
+    ><textarea>
+  </uni-textarea-field>
+  ```
+
+- **message**
+
+  The `message` attribute controls the dynamic rendering of the message content on &lt;uni-textarea-field />. By default, it is set to an empty string, meaning no content will be displayed.
+
+  ```html
+  <uni-textarea-field
+    message="Your message content"
+  >
+    <textarea
+      slot="textarea"
+      maxlength="200"
+      required
+    ><textarea>
+  </uni-textarea-field>
+  ```
+
+- **stat**
+
+  Through variations in the `stat` attribute, &lt;uni-textarea-field /> can dynamically transition between `valid` and `invalid` visual states, providing users with clear feedback on input correctness. By default, it is set to an empty string, which represents the standard, neutral state.
+
+  ```html
+  <uni-textarea-field
+    stat="invalid"
+  >
+    <textarea
+      slot="textarea"
+      maxlength="200"
+    ><textarea>
+  </uni-textarea-field>
+  ```
+
+- **appearance**
+
+  Currently, &lt;uni-textarea-field /> supports two distinct visual variants: `filled` and `outlined`. Developers can utilize the appearance attribute to configure the desired layout, which defaults to `filled`.
+
+  ```html
+  <uni-textarea-field
+    appearance="outlined"
+  >
+    <textarea
+      slot="textarea"
+      maxlength="200"
+      readonly
+    ><textarea>
+  </uni-textarea-field>
+  ```
+
+## Properties
+
+| Property Name | Type | Description |
+| ----------- | ----------- | ----------- |
+| size | String | Getter / Setter size. `size` configures the overall dimensions of &lt;uni-textarea-field />. The component currently supports three standard options: `large`, `medium`, and `small`, defaulting to `medium`. |
+| subject| String | Getter / Setter subject. `subject` controls the dynamic rendering of the subject content on &lt;uni-textarea-field />. By default, it is set to an empty string, meaning no content will be displayed. |
+| message| String | Getter / Setter message. `message` controls the dynamic rendering of the message content on &lt;uni-textarea-field />. By default, it is set to an empty string, meaning no content will be displayed. |
+| stat| String | Getter / Setter stat. `stat` can dynamically transition between `valid` and `invalid` visual states, providing users with clear feedback on input correctness. By default, it is set to an empty string, which represents the standard, neutral state. |
+| appearance| String | Getter / Setter appearance. `appearance` supports two distinct visual variants: `filled` and `outlined`. Developers can utilize the appearance attribute to configure the desired layout, which defaults to `filled`. |
+
+## Method
+| Mathod Signature | Description |
+| ----------- | ----------- |
+| refresh() | Force a UI refresh on &lt;uni-textarea-field />. |
+
+## Reference
+- [&lt;uni-textarea-field /> demo](https://blog.lalacube.com/mei/webComponent_uni-textarea-field.html)