@spectrum-web-components/textfield 0.0.0-20241209155954

package/README.md

@@ -0,0 +1,180 @@
+## Description
+
+`sp-textfield` components are text boxes that allow users to input custom text entries with a keyboard. Various decorations can be displayed around the field to communicate the entry requirements.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/textfield?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/textfield)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/textfield?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/textfield)
+[![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/EcE2Yrwz0MDIGkCzbyvl/src/index.ts)
+
+```
+yarn add @spectrum-web-components/textfield
+```
+
+Import the side effectful registration of `<sp-textfield>` via:
+
+```
+import '@spectrum-web-components/textfield/sp-textfield.js';
+```
+
+When looking to leverage the `Textfield` base class as a type and/or for extension purposes, do so via:
+
+```
+import { Textfield } from '@spectrum-web-components/textfield';
+```
+
+## Sizes
+
+<sp-tabs selected="m" auto label="Size Attribute Options">
+<sp-tab value="s">Small</sp-tab>
+<sp-tab-panel value="s">
+
+```html
+<sp-field-label size="s" for="name-0-s">Name</sp-field-label>
+<sp-textfield
+    size="s"
+    id="name-0-s"
+    placeholder="Enter your name"
+></sp-textfield>
+```
+
+</sp-tab-panel>
+<sp-tab value="m">Medium</sp-tab>
+<sp-tab-panel value="m">
+
+```html
+<sp-field-label for="name-0-m">Name</sp-field-label>
+<sp-textfield id="name-0-m" placeholder="Enter your name"></sp-textfield>
+```
+
+</sp-tab-panel>
+<sp-tab value="l">Large</sp-tab>
+<sp-tab-panel value="l">
+
+```html
+<sp-field-label size="l" for="name-0-l">Name</sp-field-label>
+<sp-textfield
+    size="l"
+    id="name-0-l"
+    placeholder="Enter your name"
+></sp-textfield>
+```
+
+</sp-tab-panel>
+<sp-tab value="xl">Extra Large</sp-tab>
+<sp-tab-panel value="xl">
+
+```html
+<sp-field-label size="xl" for="name-0-xl">Name</sp-field-label>
+<sp-textfield
+    size="xl"
+    id="name-0-xl"
+    placeholder="Enter your name"
+></sp-textfield>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+## Variants
+
+### Valid
+
+Dictate the validity state of the text entry with the `valid` attribute.
+
+```html
+<sp-field-label for="name-1" required>Name</sp-field-label>
+<sp-textfield
+    id="name-1"
+    placeholder="Enter your name"
+    valid
+    value="My Name"
+></sp-textfield>
+```
+
+### Invalid
+
+Dictate the invalidity state of the text entry with the `invalid` attribute.
+
+```html
+<sp-field-label for="name-2" required>Name</sp-field-label>
+<sp-textfield id="name-2" invalid placeholder="Enter your name"></sp-textfield>
+```
+
+### Quiet
+
+The quiet style works best when a clear layout (vertical stack, table, grid) assists in a user's ability to parse the element. Too many quiet components in a small space can be hard to read.
+
+```html
+<sp-field-label for="name-3">Name (quietly)</sp-field-label>
+<sp-textfield id="name-3" placeholder="Enter your name" quiet></sp-textfield>
+```
+
+### Types
+
+When inputting URLs, telephone numbers, email addresses, or passwords, specify a `type` to provide
+user affordances like mobile keyboards and obscured characters:
+
+-   `url`
+-   `tel`
+-   `email`
+-   `password`
+-   `text` (default)
+
+```html
+<sp-field-label for="tel-1">Telephone</sp-field-label>
+<sp-textfield
+    id="tel-1"
+    type="tel"
+    placeholder="Enter your phone number"
+></sp-textfield>
+<sp-field-label for="password-1">Password</sp-field-label>
+<sp-textfield id="password-1" type="password"></sp-textfield>
+```
+
+If the `type` attribute is not specified, or if it does not match any of these values, the default type adopted is "text."
+
+## Help text
+
+Help text can be accessibly associated with an `<sp-textfield>` element by using the `help-text` or `negative-help-text` slots. When using the `negative-help-text` slot, `<sp-textfield>` will self manage the presence of this content based on the value of the `invalid` property on your `<sp-textfield>` element. Content within the `help-text` slot will be show by default. When your `<sp-textfield>` should receive help text based on state outside of the complexity of `invalid` or not, manage the content addressed to the `help-text` from above to ensure that it displays the right messaging and possesses the right `variant`.
+
+<sp-tabs selected="self" auto label="Help text usage in textfields">
+<sp-tab value="self">Self managed</sp-tab>
+<sp-tab-panel value="self">
+
+```html
+<sp-field-label for="self">Stay "Positive"</sp-field-label>
+<sp-textfield id="self" pattern="[P][o][s][i][t][i][v][e]" value="Positive">
+    <sp-help-text slot="help-text">
+        Tell us how you are feeling today.
+    </sp-help-text>
+    <sp-help-text slot="negative-help-text">Please be "Positive".</sp-help-text>
+</sp-textfield>
+```
+
+</sp-tab-panel>
+<sp-tab value="above">Managed from above</sp-tab>
+<sp-tab-panel value="above">
+
+```html
+<sp-field-label for="managed">Stay "Positive"</sp-field-label>
+<sp-textfield
+    id="managed"
+    pattern="[P][o][s][i][t][i][v][e]"
+    value="Positive"
+    oninput='
+        const helpText = this.querySelector(`[slot="help-text"]`);
+        helpText.textContent = this.invalid ? `Please be "Positive".` : `Tell us how you are feeling today.`;
+        helpText.variant = this.invalid ? `negative` : `neutral`;
+    '
+>
+    <sp-help-text slot="neutral-text">
+        Tell us how you're feeling today.
+    </sp-help-text>
+    <sp-help-text slot="help-text">Please be "Positive".</sp-help-text>
+</sp-textfield>
+```
+
+</sp-tab-panel>
+</sp-tabs>

package/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@spectrum-web-components/textfield",
+    "version": "0.0.0-20241209155954",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/adobe/spectrum-web-components.git",
+        "directory": "packages/textfield"
+    },
+    "author": "",
+    "homepage": "https://opensource.adobe.com/spectrum-web-components/components/textfield",
+    "bugs": {
+        "url": "https://github.com/adobe/spectrum-web-components/issues"
+    },
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "type": "module",
+    "exports": {
+        ".": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./package.json": "./package.json",
+        "./src/Textfield.js": {
+            "development": "./src/Textfield.dev.js",
+            "default": "./src/Textfield.js"
+        },
+        "./src/index.js": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./src/textfield-overrides.css.js": "./src/textfield-overrides.css.js",
+        "./src/textfield.css.js": "./src/textfield.css.js",
+        "./sp-textfield.js": {
+            "development": "./sp-textfield.dev.js",
+            "default": "./sp-textfield.js"
+        }
+    },
+    "scripts": {
+        "test": "echo \"Error: run tests from mono-repo root.\" && exit 1"
+    },
+    "files": [
+        "**/*.d.ts",
+        "**/*.js",
+        "**/*.js.map",
+        "custom-elements.json",
+        "!stories/",
+        "!test/"
+    ],
+    "keywords": [
+        "spectrum css",
+        "web components",
+        "lit-element",
+        "lit-html"
+    ],
+    "dependencies": {
+        "@spectrum-web-components/base": "0.0.0-20241209155954",
+        "@spectrum-web-components/help-text": "0.0.0-20241209155954",
+        "@spectrum-web-components/icon": "0.0.0-20241209155954",
+        "@spectrum-web-components/icons-ui": "0.0.0-20241209155954",
+        "@spectrum-web-components/icons-workflow": "0.0.0-20241209155954",
+        "@spectrum-web-components/shared": "0.0.0-20241209155954"
+    },
+    "devDependencies": {
+        "@spectrum-css/textfield": "^8.0.0-s2-foundations.16"
+    },
+    "types": "./src/index.d.ts",
+    "customElements": "custom-elements.json",
+    "sideEffects": [
+        "./sp-*.js",
+        "./**/*.dev.js"
+    ]
+}

package/sp-textfield.d.ts

@@ -0,0 +1,6 @@
+import { Textfield } from './src/Textfield.js';
+declare global {
+    interface HTMLElementTagNameMap {
+        'sp-textfield': Textfield;
+    }
+}

package/sp-textfield.dev.js

@@ -0,0 +1,5 @@
+"use strict";
+import { Textfield } from "./src/Textfield.dev.js";
+import { defineElement } from "@spectrum-web-components/base/src/define-element.js";
+defineElement("sp-textfield", Textfield);
+//# sourceMappingURL=sp-textfield.dev.js.map

package/sp-textfield.dev.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["sp-textfield.ts"],
+  "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\n\nimport { Textfield } from './src/Textfield.dev.js'\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\n\ndefineElement('sp-textfield', Textfield);\n\ndeclare global {\n    interface HTMLElementTagNameMap {\n        'sp-textfield': Textfield;\n    }\n}\n"],
+  "mappings": ";AAYA,SAAS,iBAAiB;AAC1B,SAAS,qBAAqB;AAE9B,cAAc,gBAAgB,SAAS;",
+  "names": []
+}

package/sp-textfield.js

@@ -0,0 +1,2 @@
+"use strict";import{Textfield as e}from"./src/Textfield.js";import{defineElement as t}from"@spectrum-web-components/base/src/define-element.js";t("sp-textfield",e);
+//# sourceMappingURL=sp-textfield.js.map

package/sp-textfield.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["sp-textfield.ts"],
+  "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\n\nimport { Textfield } from './src/Textfield.js';\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\n\ndefineElement('sp-textfield', Textfield);\n\ndeclare global {\n    interface HTMLElementTagNameMap {\n        'sp-textfield': Textfield;\n    }\n}\n"],
+  "mappings": "aAYA,OAAS,aAAAA,MAAiB,qBAC1B,OAAS,iBAAAC,MAAqB,sDAE9BA,EAAc,eAAgBD,CAAS",
+  "names": ["Textfield", "defineElement"]
+}

package/src/Textfield.d.ts

@@ -0,0 +1,144 @@
+import { CSSResultArray, nothing, PropertyValues, TemplateResult } from '@spectrum-web-components/base';
+import { Focusable } from '@spectrum-web-components/shared/src/focusable.js';
+import '@spectrum-web-components/icons-ui/icons/sp-icon-checkmark100.js';
+import '@spectrum-web-components/icons-workflow/icons/sp-icon-alert.js';
+declare const textfieldTypes: readonly ["text", "url", "tel", "email", "password"];
+export type TextfieldType = (typeof textfieldTypes)[number];
+declare const TextfieldBase_base: typeof Focusable & {
+    new (...args: any[]): import("@spectrum-web-components/base").SizedElementInterface;
+    prototype: import("@spectrum-web-components/base").SizedElementInterface;
+} & {
+    new (...args: any[]): import("@spectrum-web-components/help-text/src/manage-help-text.js").HelpTextElementInterface;
+    prototype: import("@spectrum-web-components/help-text/src/manage-help-text.js").HelpTextElementInterface;
+};
+/**
+ * @fires input - The value of the element has changed.
+ * @fires change - An alteration to the value of the element has been committed by the user.
+ */
+export declare class TextfieldBase extends TextfieldBase_base {
+    static get styles(): CSSResultArray;
+    protected appliedLabel?: string;
+    /**
+     * A regular expression outlining the keys that will be allowed to update the value of the form control.
+     */
+    allowedKeys: string;
+    /**
+     * @private
+     */
+    focused: boolean;
+    protected inputElement: HTMLInputElement | HTMLTextAreaElement;
+    /**
+     * Whether the `value` held by the form control is invalid.
+     */
+    invalid: boolean;
+    /**
+     * A string applied via `aria-label` to the form control when a user visible label is not provided.
+     */
+    label: string;
+    /**
+     * Name of the form control.
+     */
+    name: string | undefined;
+    /**
+     * Text that appears in the form control when it has no value set
+     */
+    placeholder: string;
+    set type(val: TextfieldType);
+    get type(): TextfieldType;
+    /**
+     * @private
+     * This binding allows for invalid value for `type` to still be reflected to the DOM
+     */
+    private _type;
+    /**
+     * Pattern the `value` must match to be valid
+     */
+    pattern?: string;
+    /**
+     * Whether a form control delivered with the `multiline` attribute will change size
+     * vertically to accomodate longer input
+     */
+    grows: boolean;
+    /**
+     * Defines the maximum string length that the user can enter
+     */
+    maxlength: number;
+    /**
+     * Defines the minimum string length that the user can enter
+     */
+    minlength: number;
+    /**
+     * Whether the form control should accept a value longer than one line
+     */
+    multiline: boolean;
+    /**
+     * Whether a user can interact with the value of the form control
+     */
+    readonly: boolean;
+    /**
+     * The specific number of rows the form control should provide in the user interface
+     */
+    rows: number;
+    /**
+     * Whether the `value` held by the form control is valid.
+     */
+    valid: boolean;
+    /**
+     * The value held by the form control
+     */
+    set value(value: string | number);
+    get value(): string | number;
+    protected _value: string | number;
+    /**
+     * Whether to display the form control with no visible background
+     */
+    quiet: boolean;
+    /**
+     * Whether the form control will be found to be invalid when it holds no `value`
+     */
+    required: boolean;
+    /**
+     * What form of assistance should be provided when attempting to supply a value to the form control
+     */
+    autocomplete?: 'list' | 'none' | HTMLInputElement['autocomplete'] | HTMLTextAreaElement['autocomplete'];
+    get focusElement(): HTMLInputElement | HTMLTextAreaElement;
+    /**
+     * Sets the start and end positions of the current selection.
+     *
+     * @param selectionStart The 0-based index of the first selected character. An index greater than the length of the
+     *  element's value is treated as pointing to the end of the value.
+     * @param selectionEnd The 0-based index of the character after the last selected character. An index greater than
+     *  the length of the element's value is treated as pointing to the end of the value.
+     * @param [selectionDirection="none"] A string indicating the direction in which the selection is considered to
+     *  have been performed.
+     */
+    setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: 'forward' | 'backward' | 'none'): void;
+    /**
+     * Selects all the text.
+     */
+    select(): void;
+    protected handleInput(_event: Event): void;
+    protected handleChange(): void;
+    protected onFocus(): void;
+    protected onBlur(_event: FocusEvent): void;
+    protected handleInputElementPointerdown(): void;
+    protected renderStateIcons(): TemplateResult | typeof nothing;
+    protected get displayValue(): string;
+    private get renderMultiline();
+    private get renderInput();
+    protected renderField(): TemplateResult;
+    protected render(): TemplateResult;
+    protected update(changedProperties: PropertyValues): void;
+    checkValidity(): boolean;
+}
+/**
+ * @element sp-textfield
+ * @slot help-text - default or non-negative help text to associate to your form element
+ * @slot negative-help-text - negative help text to associate to your form element when `invalid`
+ */
+export declare class Textfield extends TextfieldBase {
+    set value(value: string);
+    get value(): string;
+    protected _value: string;
+}
+export {};