feat(field-label): add field label pattern

packages/bundle/elements.ts

@@ -31,6 +31,7 @@ import '@spectrum-web-components/dialog/sp-dialog-wrapper.js';
 import '@spectrum-web-components/dropdown/sp-dropdown.js';
 import '@spectrum-web-components/dropzone/sp-dropzone.js';
 import '@spectrum-web-components/field-group/sp-field-group.js';
+import '@spectrum-web-components/field-label/sp-field-label.js';
 import '@spectrum-web-components/icon/sp-icon.js';
 import '@spectrum-web-components/icons/sp-icons-large.js';
 import '@spectrum-web-components/icons/sp-icons-medium.js';

packages/bundle/package.json

@@ -67,6 +67,7 @@
         "@spectrum-web-components/dropdown": "^0.8.5",
         "@spectrum-web-components/dropzone": "^0.4.4",
         "@spectrum-web-components/field-group": "^0.0.1",
+        "@spectrum-web-components/field-label": "^0.0.1",
         "@spectrum-web-components/icon": "^0.6.3",
         "@spectrum-web-components/icons": "^0.4.5",
         "@spectrum-web-components/icons-workflow": "^0.3.6",

packages/bundle/src/index.ts

@@ -27,6 +27,7 @@ export * from '@spectrum-web-components/dialog';
 export * from '@spectrum-web-components/dropdown';
 export * from '@spectrum-web-components/dropzone';
 export * from '@spectrum-web-components/field-group';
+export * from '@spectrum-web-components/field-label';
 export * from '@spectrum-web-components/icon';
 export * from '@spectrum-web-components/icons';
 import * as UIIcons from '@spectrum-web-components/icons-ui';

packages/bundle/tsconfig.json

@@ -25,6 +25,7 @@
         { "path": "../dropdown" },
         { "path": "../dropzone" },
         { "path": "../field-group" },
+        { "path": "../field-label" },
         { "path": "../icon" },
         { "path": "../icons" },
         { "path": "../icons-ui" },

packages/field-label/README.md

@@ -0,0 +1,129 @@
+## Description
+
+An `<sp-field-label>` provides accessible labelling for form elements. Use the `for` attribute to outline the `id` of an element in the same DOM tree to which it should associate itself.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/field-label?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/field-label)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/field-label?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/field-label)
+
+```
+yarn add @spectrum-web-components/field-label
+```
+
+Import the side effectful registration of `<sp-field-label>` via:
+
+```
+import '@spectrum-web-components/field-label/sp-field-label.js';
+```
+
+When looking to leverage the `FieldLabel` base class as a type and/or for extension purposes, do so via:
+
+```
+import { FieldLabel } from '@spectrum-web-components/field-label';
+```
+
+## Example
+
+```html
+<sp-field-label for="lifestory">
+    Life Story
+</sp-field-label>
+<sp-textfield placeholder="Enter your life story" id="lifestory">
+    <input />
+</sp-textfield>
+<sp-field-label for="birth-place">
+    Birthplace
+</sp-field-label>
+<sp-dropdown id="birth-place">
+    <span slot="label">Choose a location:</span>
+    <sp-menu>
+        <sp-menu-item>Istanbul</sp-menu-item>
+        <sp-menu-item>London</sp-menu-item>
+        <sp-menu-item>Maputo</sp-menu-item>
+        <sp-menu-item>Melbuorne</sp-menu-item>
+        <sp-menu-item>New York</sp-menu-item>
+        <sp-menu-item>San Fransisco</sp-menu-item>
+        <sp-menu-item>Santiago</sp-menu-item>
+        <sp-menu-item>Tokyo</sp-menu-item>
+    </sp-menu>
+</sp-dropdown>
+```
+
+## Side Aligned
+
+Using the `side-aligned` attribute will display the `<sp-field-label>` element inline with surrounding elements and the `start` and `end` values outline the alignment of the label text in the width specified.
+
+### Start
+
+Use `side-aligned="start"` to display the `<sp-field-label>` inline and to align the label text to the "start" of the flow of text:
+
+```html
+<sp-field-label for="lifestory-1" side-aligned="start" style="width: 120px">
+    Life Story
+</sp-field-label>
+<sp-textfield
+    placeholder="Enter your life story"
+    id="lifestory-1"
+></sp-textfield>
+<br />
+<br />
+<sp-field-label
+    for="birth-place-1"
+    side-aligned="start"
+    required
+    style="width: 120px"
+>
+    Birthplace
+</sp-field-label>
+<sp-dropdown id="birth-place-1">
+    <span slot="label">Choose a location:</span>
+    <sp-menu>
+        <sp-menu-item>Istanbul</sp-menu-item>
+        <sp-menu-item>London</sp-menu-item>
+        <sp-menu-item>Maputo</sp-menu-item>
+        <sp-menu-item>Melbuorne</sp-menu-item>
+        <sp-menu-item>New York</sp-menu-item>
+        <sp-menu-item>San Fransisco</sp-menu-item>
+        <sp-menu-item>Santiago</sp-menu-item>
+        <sp-menu-item>Tokyo</sp-menu-item>
+    </sp-menu>
+</sp-dropdown>
+```
+
+### End
+
+Use `side-aligned="end"` to display the `<sp-field-label>` inline and to align the label text to the "end" of the flow of text:
+
+```html
+<sp-field-label
+    for="lifestory-1"
+    side-aligned="end"
+    required
+    style="width: 120px"
+>
+    Life Story
+</sp-field-label>
+<sp-textfield
+    placeholder="Enter your life story"
+    id="lifestory-1"
+></sp-textfield>
+<br />
+<br />
+<sp-field-label for="birth-place-1" side-aligned="end" style="width: 120px">
+    Birthplace
+</sp-field-label>
+<sp-dropdown id="birth-place-1">
+    <span slot="label">Choose a location:</span>
+    <sp-menu>
+        <sp-menu-item>Istanbul</sp-menu-item>
+        <sp-menu-item>London</sp-menu-item>
+        <sp-menu-item>Maputo</sp-menu-item>
+        <sp-menu-item>Melbuorne</sp-menu-item>
+        <sp-menu-item>New York</sp-menu-item>
+        <sp-menu-item>San Fransisco</sp-menu-item>
+        <sp-menu-item>Santiago</sp-menu-item>
+        <sp-menu-item>Tokyo</sp-menu-item>
+    </sp-menu>
+</sp-dropdown>
+```

packages/field-label/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "@spectrum-web-components/field-label",
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/adobe/spectrum-web-components.git",
+        "directory": "packages/field-label"
+    },
+    "bugs": {
+        "url": "https://github.com/adobe/spectrum-web-components/issues"
+    },
+    "homepage": "https://adobe.github.io/spectrum-web-components/components/field-label",
+    "keywords": [
+        "spectrum css",
+        "web components",
+        "lit-element",
+        "lit-html"
+    ],
+    "version": "0.0.1",
+    "description": "",
+    "main": "src/index.js",
+    "module": "src/index.js",
+    "type": "module",
+    "exports": {
+        "./src/": "./src/",
+        "./custom-elements.json": "./custom-elements.json",
+        "./package.json": "./package.json",
+        "./sp-field-label": "./sp-field-label.js",
+        "./sp-field-label.js": "./sp-field-label.js"
+    },
+    "files": [
+        "custom-elements.json",
+        "*.d.ts",
+        "*.js",
+        "*.js.map",
+        "/src/"
+    ],
+    "sideEffects": [
+        "./sp-*.js",
+        "./sp-*.ts"
+    ],
+    "scripts": {
+        "test": "echo \"Error: run tests from mono-repo root.\" && exit 1"
+    },
+    "author": "",
+    "license": "Apache-2.0",
+    "devDependencies": {
+        "@spectrum-css/fieldlabel": "^3.0.0-beta.6",
+        "@spectrum-web-components/textfield": "^0.5.4"
+    },
+    "dependencies": {
+        "@spectrum-web-components/base": "^0.1.3",
+        "@spectrum-web-components/icons-ui": "^0.3.3",
+        "@spectrum-web-components/shared": "^0.7.4",
+        "tslib": "^2.0.0"
+    }
+}

packages/field-label/sp-field-label.ts

@@ -0,0 +1,21 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { FieldLabel } from './src/FieldLabel.js';
+
+customElements.define('sp-field-label', FieldLabel);
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'sp-field-label': FieldLabel;
+    }
+}

packages/field-label/src/FieldLabel.ts

@@ -0,0 +1,115 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import {
+    html,
+    SpectrumElement,
+    CSSResultArray,
+    TemplateResult,
+    property,
+    PropertyValues,
+} from '@spectrum-web-components/base';
+import type { Focusable } from '@spectrum-web-components/shared';
+import { AsteriskIcon } from '@spectrum-web-components/icons-ui';
+import '@spectrum-web-components/icon/sp-icon.js';
+import asterickIconStyles from '@spectrum-web-components/icon/src/spectrum-icon-asterick.css.js';
+
+import styles from './field-label.css.js';
+
+/**
+ * @element sp-field-label
+ */
+export class FieldLabel extends SpectrumElement {
+    public static get styles(): CSSResultArray {
+        return [styles, asterickIconStyles];
+    }
+
+    static instanceCount = 0;
+
+    @property({ type: Boolean, reflect: true })
+    public disabled = false;
+
+    @property({ type: String })
+    public id = '';
+
+    @property({ type: String })
+    public for = '';
+
+    @property({ type: Boolean, reflect: true })
+    public required = false;
+
+    @property({ type: String, reflect: true, attribute: 'side-aligned' })
+    public sideAligned?: 'start' | 'end';
+
+    private target?: HTMLElement;
+
+    private handleClick(): void {
+        if (!this.target || this.disabled) return;
+        this.target.focus();
+    }
+
+    private async manageFor(): Promise<void> {
+        if (!this.for) {
+            return;
+        }
+        const parent = this.getRootNode() as HTMLElement;
+        const target = parent.querySelector(`#${this.for}`) as Focusable;
+        if (typeof target.updateComplete !== 'undefined') {
+            await target.updateComplete;
+        }
+        this.target = target.focusElement || target;
+        if (this.target) {
+            const targetParent = this.target.getRootNode() as HTMLElement;
+            if (targetParent.isSameNode(parent)) {
+                this.target.setAttribute('aria-labelledby', this.id);
+            } else {
+                this.target.setAttribute(
+                    'aria-label',
+                    (this.textContent || /* c8 ignore next */ '').trim()
+                );
+            }
+        }
+    }
+
+    protected render(): TemplateResult {
+        return html`
+            <label>
+                <slot></slot>
+                ${this.required
+                    ? html`
+                          <sp-icon class="requiredIcon asterick">
+                              ${AsteriskIcon({ hidden: true })}
+                          </sp-icon>
+                      `
+                    : html``}
+            </label>
+        `;
+    }
+
+    protected firstUpdated(changes: PropertyValues): void {
+        super.firstUpdated(changes);
+        if (!this.hasAttribute('id')) {
+            this.setAttribute(
+                'id',
+                `${this.tagName.toLowerCase()}-${FieldLabel.instanceCount++}`
+            );
+        }
+        this.addEventListener('click', this.handleClick);
+    }
+
+    protected updated(changes: PropertyValues): void {
+        super.updated(changes);
+        if (changes.has('for') || changes.has('id')) {
+            this.manageFor();
+        }
+    }
+}

packages/field-label/src/field-label.css

@@ -0,0 +1,13 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+@import './spectrum-field-label.css';

packages/field-label/src/index.ts

@@ -0,0 +1,13 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+export * from './FieldLabel.js';