atomicuilibrary 0.1.0 → 0.1.3

package/dist/collection/components/label/label.js

@@ -0,0 +1,1669 @@
+import { h, Host, } from "@stencil/core";
+/**
+ * `ui-label` — Enterprise-grade, fully accessible form label component.
+ *
+ * @slot           - Primary label text / rich content.
+ * @slot start     - Content placed before the label text (e.g. leading icon).
+ * @slot end       - Content placed after the label text (e.g. trailing icon or action).
+ * @slot hint      - Helper / hint text below the label.
+ * @slot tooltip   - Rich tooltip content triggered by the info icon.
+ * @slot required-indicator - Custom required-indicator markup (overrides built-in asterisk).
+ *
+ * @cssvar --ui-label-color              Label text colour.
+ * @cssvar --ui-label-font-size          Label font size.
+ * @cssvar --ui-label-font-weight        Label font weight.
+ * @cssvar --ui-label-gap                Gap between label and associated control direction.
+ * @cssvar --ui-label-required-color     Colour of the required asterisk.
+ * @cssvar --ui-label-disabled-opacity   Opacity when disabled.
+ * @cssvar --ui-label-error-color        Colour used for error / invalid state.
+ * @cssvar --ui-label-success-color      Colour used for success state.
+ * @cssvar --ui-label-hint-color         Colour of hint / helper text.
+ */
+export class UILabel {
+    // ─── Internal refs ──────────────────────────────────────────────────────
+    el;
+    /** Tracks whether the associated control is currently focused (managed externally or via the focused prop). */
+    _isFocused = false;
+    /** Toggle state for tooltip open/close. */
+    _tooltipOpen = false;
+    // ─── Form Association ────────────────────────────────────────────────────
+    /**
+     * ID of the form control this label is associated with.
+     * Renders as a native `for` attribute on the underlying `<label>` element.
+     * Supports all standard form controls as well as custom web components.
+     */
+    htmlFor;
+    /**
+     * Alias for `htmlFor`.  `controlId` takes precedence if both are supplied.
+     */
+    controlId;
+    /**
+     * Deprecated alias kept for back-compat.  Prefer `htmlFor`.
+     */
+    target;
+    // ─── Content ────────────────────────────────────────────────────────────
+    /**
+     * Plain-text label.  Use the default slot for rich/HTML content instead.
+     */
+    label = '';
+    // ─── Typography ─────────────────────────────────────────────────────────
+    /**
+     * Semantic size token.
+     * @default 'md'
+     */
+    size = 'md';
+    /**
+     * Font-weight scale.
+     * @default 'medium'
+     */
+    weight = 'medium';
+    /**
+     * CSS text-transform value.
+     * @default 'none'
+     */
+    transform = 'none';
+    /**
+     * Single-line truncation with ellipsis.
+     */
+    truncate = false;
+    /**
+     * Allow text to wrap across multiple lines (disables truncation).
+     */
+    multiline = false;
+    /**
+     * Clamp to N visible lines (CSS `line-clamp`).  Requires `multiline` to be true.
+     */
+    lineClamp = 0;
+    // ─── Variant ────────────────────────────────────────────────────────────
+    /**
+     * Colour variant.
+     * @default 'default'
+     */
+    variant = 'default';
+    // ─── Form States ─────────────────────────────────────────────────────────
+    /**
+     * Marks the associated field as required.
+     * Shows a required indicator (asterisk by default) and sets `aria-required` on the
+     * linked control if possible.
+     */
+    required = false;
+    /**
+     * Shows "(optional)" hint text next to the label.
+     * Mutually exclusive with `required` — `required` wins if both are set.
+     */
+    optional = false;
+    /**
+     * Applies disabled styling and prevents interaction.
+     */
+    disabled = false;
+    /**
+     * Applies read-only styling (dimmed, no pointer events).
+     */
+    readonly = false;
+    /**
+     * Applies invalid / error styling to the label.
+     */
+    invalid = false;
+    /**
+     * Mirrors the focused state of the associated control so the label can react visually.
+     */
+    focused = false;
+    /**
+     * Shows a loading skeleton overlaid on the label text.
+     */
+    loading = false;
+    // ─── Validation messaging ────────────────────────────────────────────────
+    /**
+     * Error message shown below the label when `invalid` is true.
+     */
+    errorText = '';
+    /**
+     * Success message shown below the label when the field is valid and this text is set.
+     */
+    successText = '';
+    /**
+     * Helper / hint text shown below the label.
+     */
+    helperText = '';
+    // ─── Accessibility ───────────────────────────────────────────────────────
+    /**
+     * Sets `aria-label` on the root element.
+     */
+    ariaLabel = '';
+    /**
+     * IDs of elements that describe this label (space-separated).
+     */
+    ariaDescribedby = '';
+    /**
+     * Live-region politeness for dynamic content announcements.
+     * @default 'off'
+     */
+    ariaLive = 'off';
+    // ─── Layout ─────────────────────────────────────────────────────────────
+    /**
+     * Stack direction when used alongside a form control.
+     * @default 'vertical'
+     */
+    orientation = 'vertical';
+    /**
+     * Horizontal alignment of label content.
+     * @default 'start'
+     */
+    align = 'start';
+    /**
+     * Renders as an inline-level element.
+     */
+    inline = false;
+    /**
+     * Forces 100 % width block layout (useful inside flex/grid parents).
+     */
+    block = false;
+    // ─── Spacing ─────────────────────────────────────────────────────────────
+    /**
+     * Gap between the label row and the hint / error message.
+     * Accepts any valid CSS length (e.g. `'4px'`, `'0.5rem'`).
+     * Maps to `--ui-label-gap`.
+     */
+    gap = '';
+    /**
+     * External margin override (CSS shorthand string).
+     */
+    margin = '';
+    /**
+     * External padding override (CSS shorthand string).
+     */
+    padding = '';
+    // ─── Icons ───────────────────────────────────────────────────────────────
+    /**
+     * Icon name rendered before the label text.
+     * Uses the same icon library as the rest of the design system.
+     */
+    startIcon = '';
+    /**
+     * Icon name rendered after the label text.
+     */
+    endIcon = '';
+    /**
+     * When true, only icons are shown — label text is visually hidden.
+     */
+    iconOnly = false;
+    /**
+     * Icon name or URL for the tooltip trigger button.
+     * Defaults to an 'ⓘ' info glyph.
+     */
+    tooltipIcon = 'ⓘ';
+    // ─── Tooltip ─────────────────────────────────────────────────────────────
+    /**
+     * Plain-text tooltip content.  Use the `tooltip` slot for rich markup.
+     */
+    tooltip = '';
+    /**
+     * Preferred position for the tooltip callout.
+     * @default 'top'
+     */
+    tooltipPosition = 'top';
+    // ─── Interaction ─────────────────────────────────────────────────────────
+    /**
+     * Makes the label itself clickable (fires `labelClick`).
+     */
+    clickable = false;
+    /**
+     * Enables text-selection on the label (disabled by default for form labels).
+     */
+    selectable = false;
+    /**
+     * Shows a copy-to-clipboard button on hover and fires `labelCopy`.
+     */
+    copyable = false;
+    // ─── Responsive ──────────────────────────────────────────────────────────
+    /**
+     * Enable responsive font-size scaling via fluid typography.
+     */
+    responsive = false;
+    /**
+     * On narrow viewports, switches from `horizontal` to `vertical` orientation.
+     */
+    mobileStack = false;
+    // ─── Internationalisation ─────────────────────────────────────────────────
+    /**
+     * Text direction.
+     * @default 'ltr'
+     */
+    labelDir = 'ltr';
+    /**
+     * BCP-47 language tag (e.g. `'en'`, `'ar'`, `'fr'`).
+     */
+    labelLang = '';
+    // ─── Enterprise attributes ────────────────────────────────────────────────
+    /**
+     * DOM `id` for the root element.  Auto-generated if not provided.
+     */
+    labelId = '';
+    /**
+     * Logical name (maps to `name` attribute on the inner label).
+     */
+    name = '';
+    /**
+     * `data-testid` attribute for automated testing.
+     */
+    testId = '';
+    /**
+     * `data-automation-id` attribute for RPA / automation tooling.
+     */
+    automationId = '';
+    // ─── Events ───────────────────────────────────────────────────────────────
+    /**
+     * Fired when the label element is clicked (requires `clickable` or naturally via `for`).
+     */
+    labelClick;
+    /**
+     * Fired when the label receives focus (passes through from the native label).
+     */
+    labelFocus;
+    /**
+     * Fired when the label loses focus.
+     */
+    labelBlur;
+    /**
+     * Fired after text is successfully copied to the clipboard (`copyable` must be true).
+     */
+    labelCopy;
+    // ─── Watchers ─────────────────────────────────────────────────────────────
+    onFocusedChanged(val) {
+        this._isFocused = val;
+    }
+    // ─── Lifecycle ────────────────────────────────────────────────────────────
+    componentWillLoad() {
+        // Sync prop → state so imperative updates also trigger re-render.
+        this._isFocused = this.focused;
+        // Auto-generate a stable ID when none is supplied (needed for aria-describedby linkage).
+        if (!this.labelId) {
+            this.labelId = `ui-label-${Math.random().toString(36).slice(2, 9)}`;
+        }
+    }
+    // ─── Public API (Methods) ─────────────────────────────────────────────────
+    /**
+     * Programmatically focus the label element.
+     * Useful when the owning form-field component proxies focus behaviour.
+     */
+    async setFocus() {
+        this.el.shadowRoot?.querySelector('.label-root')?.focus();
+    }
+    /**
+     * Programmatically trigger the copy-to-clipboard action.
+     */
+    async copyText() {
+        await this._handleCopy();
+    }
+    // ─── Private helpers ─────────────────────────────────────────────────────
+    /** Resolve the `for`/`htmlFor` target ID with fallback chain. */
+    get _forId() {
+        return this.controlId || this.htmlFor || this.target || undefined;
+    }
+    /** Build the `aria-describedby` string used by the inner label. */
+    get _describedBy() {
+        const parts = [];
+        if (this.ariaDescribedby)
+            parts.push(this.ariaDescribedby);
+        if (this.helperText)
+            parts.push(`${this.labelId}-hint`);
+        if (this.invalid && this.errorText)
+            parts.push(`${this.labelId}-error`);
+        if (this.successText && !this.invalid)
+            parts.push(`${this.labelId}-success`);
+        return parts.join(' ');
+    }
+    /** Resolved label text — prefer the `label` prop, child text is handled via slot. */
+    get _text() {
+        return this.label || '';
+    }
+    _handleClick = (e) => {
+        if (this.disabled)
+            return;
+        this.labelClick.emit({
+            originalEvent: e,
+            text: this._text || this.el.textContent?.trim() || '',
+            targetId: this._forId,
+        });
+    };
+    _handleFocus = () => {
+        this._isFocused = true;
+        this.labelFocus.emit();
+    };
+    _handleBlur = () => {
+        this._isFocused = false;
+        this.labelBlur.emit();
+    };
+    _handleCopy = async () => {
+        const text = this._text || this.el.textContent?.trim() || '';
+        if (!text)
+            return;
+        try {
+            await navigator.clipboard.writeText(text);
+            this.labelCopy.emit({ text });
+        }
+        catch {
+            // Clipboard API unavailable — silent failure.
+        }
+    };
+    _toggleTooltip = () => {
+        this._tooltipOpen = !this._tooltipOpen;
+    };
+    _closeTooltip = () => {
+        this._tooltipOpen = false;
+    };
+    // ─── CSS class helpers ────────────────────────────────────────────────────
+    _rootClasses() {
+        return {
+            'label-root': true,
+            [`label-size-${this.size}`]: true,
+            [`label-weight-${this.weight}`]: true,
+            [`label-variant-${this.variant}`]: true,
+            [`label-align-${this.align}`]: true,
+            [`label-orientation-${this.orientation}`]: true,
+            'label-truncate': this.truncate && !this.multiline,
+            'label-multiline': this.multiline,
+            'label-inline': this.inline,
+            'label-block': this.block,
+            'label-disabled': this.disabled,
+            'label-readonly': this.readonly,
+            'label-invalid': this.invalid,
+            'label-focused': this._isFocused,
+            'label-loading': this.loading,
+            'label-clickable': this.clickable,
+            'label-selectable': this.selectable,
+            'label-copyable': this.copyable,
+            'label-icon-only': this.iconOnly,
+            'label-responsive': this.responsive,
+            'label-mobile-stack': this.mobileStack,
+            'label-rtl': this.labelDir === 'rtl',
+        };
+    }
+    // ─── Sub-renders ──────────────────────────────────────────────────────────
+    _renderRequiredIndicator() {
+        // Custom slot wins
+        const slotContent = this.el.querySelector('[slot="required-indicator"]');
+        if (slotContent) {
+            return h("slot", { name: "required-indicator" });
+        }
+        return (h("span", { class: "label-required", "aria-hidden": "true", title: "Required field" }, "*"));
+    }
+    _renderOptionalBadge() {
+        return (h("span", { class: "label-optional", "aria-hidden": "true" }, "(optional)"));
+    }
+    _renderIcon(name, position) {
+        return (h("span", { class: `label-icon label-icon-${position}`, "aria-hidden": "true", innerHTML: name }));
+    }
+    _renderTooltipTrigger() {
+        const hasTooltip = this.tooltip || this.el.querySelector('[slot="tooltip"]');
+        if (!hasTooltip)
+            return null;
+        return (h("button", { type: "button", class: `label-tooltip-trigger${this._tooltipOpen ? ' is-open' : ''}`, "aria-label": "More information", "aria-expanded": this._tooltipOpen ? 'true' : 'false', "aria-haspopup": "true", onClick: this._toggleTooltip, onBlur: this._closeTooltip }, h("span", { "aria-hidden": "true" }, this.tooltipIcon)));
+    }
+    _renderTooltipCallout() {
+        if (!this._tooltipOpen)
+            return null;
+        return (h("div", { role: "tooltip", class: `label-tooltip label-tooltip-${this.tooltipPosition}`, id: `${this.labelId}-tooltip` }, this.tooltip ? (h("span", { class: "label-tooltip-text" }, this.tooltip)) : (h("slot", { name: "tooltip" }))));
+    }
+    _renderCopyButton() {
+        return (h("button", { type: "button", class: "label-copy-btn", "aria-label": "Copy to clipboard", onClick: this._handleCopy, tabIndex: -1 }, h("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", width: "14", height: "14", "aria-hidden": "true" }, h("rect", { x: "9", y: "9", width: "13", height: "13", rx: "2", ry: "2" }), h("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" }))));
+    }
+    _renderSubText() {
+        const showError = this.invalid && this.errorText;
+        const showSuccess = !this.invalid && this.successText;
+        const showHelper = !showError && !showSuccess && this.helperText;
+        const hasHintSlot = !!this.el.querySelector('[slot="hint"]');
+        if (!showError && !showSuccess && !showHelper && !hasHintSlot)
+            return null;
+        return (h("div", { class: "label-sub" }, showError && (h("span", { id: `${this.labelId}-error`, class: "label-error-text", role: "alert", "aria-live": "assertive" }, h("span", { class: "label-sub-icon", "aria-hidden": "true" }, "\u2715"), this.errorText)), showSuccess && (h("span", { id: `${this.labelId}-success`, class: "label-success-text" }, h("span", { class: "label-sub-icon", "aria-hidden": "true" }, "\u2713"), this.successText)), showHelper && (h("span", { id: `${this.labelId}-hint`, class: "label-hint-text" }, this.helperText)), hasHintSlot && (h("span", { id: `${this.labelId}-hint`, class: "label-hint-text" }, h("slot", { name: "hint" })))));
+    }
+    _renderLoadingSkeleton() {
+        return (h("span", { class: "label-skeleton", "aria-hidden": "true" }, h("span", { class: "label-skeleton-bar" })));
+    }
+    // ─── Inline styles ────────────────────────────────────────────────────────
+    _hostStyle() {
+        const s = {};
+        if (this.gap)
+            s['--ui-label-gap'] = this.gap;
+        if (this.margin)
+            s['margin'] = this.margin;
+        if (this.padding)
+            s['padding'] = this.padding;
+        return s;
+    }
+    _lineClampStyle() {
+        if (this.multiline && this.lineClamp > 0) {
+            return {
+                '-webkit-line-clamp': String(this.lineClamp),
+                'line-clamp': String(this.lineClamp),
+                'display': '-webkit-box',
+                '-webkit-box-orient': 'vertical',
+                'overflow': 'hidden',
+            };
+        }
+        return undefined;
+    }
+    // ─── Render ───────────────────────────────────────────────────────────────
+    render() {
+        const labelFor = this._forId;
+        const describedBy = this._describedBy;
+        const labelProps = {
+            class: this._rootClasses(),
+            id: this.labelId || undefined,
+            for: labelFor,
+            'aria-label': this.ariaLabel || undefined,
+            'aria-describedby': describedBy || undefined,
+            'aria-live': this.ariaLive !== 'off' ? this.ariaLive : undefined,
+            'aria-disabled': this.disabled ? 'true' : undefined,
+            'data-testid': this.testId || undefined,
+            'data-automation-id': this.automationId || undefined,
+            onClick: this._handleClick,
+            onFocus: this._handleFocus,
+            onBlur: this._handleBlur,
+        };
+        if (this.name)
+            labelProps['name'] = this.name;
+        if (this.labelLang)
+            labelProps['lang'] = this.labelLang;
+        return (h(Host, { key: 'b67618ecbef75ae6ead3a609ff206a36b11de621', dir: this.labelDir, style: this._hostStyle(), class: {
+                'ui-label-host': true,
+                'is-inline': this.inline,
+                'is-block': this.block,
+            } }, h("label", { key: 'dc257dd21c76648e75c1e14204668a19e1baf662', ...labelProps }, h("slot", { key: 'c6932b813c6b1f83ea7e56101214cc7c55405fae', name: "start" }), this.startIcon && !this.iconOnly && this._renderIcon(this.startIcon, 'start'), h("span", { key: '30a20e30976ba791ebcf4f0644c3ebf0987970a6', class: "label-text", style: this._lineClampStyle() }, this.loading ? (this._renderLoadingSkeleton()) : (h("span", { class: this.iconOnly ? 'visually-hidden' : undefined }, this._text, h("slot", null)))), this.required && !this.disabled && this._renderRequiredIndicator(), this.optional && !this.required && this._renderOptionalBadge(), this.endIcon && this._renderIcon(this.endIcon, 'end'), h("slot", { key: '2ac12fa6019e520ad11ceead3d3f1b08dd29482d', name: "end" }), this._renderTooltipTrigger(), this.copyable && this._renderCopyButton()), this._renderTooltipCallout(), this._renderSubText()));
+    }
+    static get is() { return "ui-label"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["label.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["label.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "htmlFor": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "ID of the form control this label is associated with.\r\nRenders as a native `for` attribute on the underlying `<label>` element.\r\nSupports all standard form controls as well as custom web components."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "html-for"
+            },
+            "controlId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Alias for `htmlFor`.  `controlId` takes precedence if both are supplied."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "control-id"
+            },
+            "target": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Deprecated alias kept for back-compat.  Prefer `htmlFor`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "target"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Plain-text label.  Use the default slot for rich/HTML content instead."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label",
+                "defaultValue": "''"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelSize",
+                    "resolved": "\"jumbo\" | \"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\" | \"xxl\" | \"xxs\" | \"xxxl\"",
+                    "references": {
+                        "LabelSize": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelSize",
+                            "referenceLocation": "LabelSize"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'md'"
+                        }],
+                    "text": "Semantic size token."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "size",
+                "defaultValue": "'md'"
+            },
+            "weight": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelWeight",
+                    "resolved": "\"bold\" | \"light\" | \"medium\" | \"normal\" | \"semibold\"",
+                    "references": {
+                        "LabelWeight": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelWeight",
+                            "referenceLocation": "LabelWeight"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'medium'"
+                        }],
+                    "text": "Font-weight scale."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "weight",
+                "defaultValue": "'medium'"
+            },
+            "transform": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelTransform",
+                    "resolved": "\"capitalize\" | \"lowercase\" | \"none\" | \"uppercase\"",
+                    "references": {
+                        "LabelTransform": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelTransform",
+                            "referenceLocation": "LabelTransform"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'none'"
+                        }],
+                    "text": "CSS text-transform value."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "transform",
+                "defaultValue": "'none'"
+            },
+            "truncate": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Single-line truncation with ellipsis."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "truncate",
+                "defaultValue": "false"
+            },
+            "multiline": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Allow text to wrap across multiple lines (disables truncation)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "multiline",
+                "defaultValue": "false"
+            },
+            "lineClamp": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Clamp to N visible lines (CSS `line-clamp`).  Requires `multiline` to be true."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "line-clamp",
+                "defaultValue": "0"
+            },
+            "variant": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelVariant",
+                    "resolved": "\"danger\" | \"default\" | \"info\" | \"muted\" | \"primary\" | \"secondary\" | \"success\" | \"warning\"",
+                    "references": {
+                        "LabelVariant": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelVariant",
+                            "referenceLocation": "LabelVariant"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'default'"
+                        }],
+                    "text": "Colour variant."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "variant",
+                "defaultValue": "'default'"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Marks the associated field as required.\r\nShows a required indicator (asterisk by default) and sets `aria-required` on the\r\nlinked control if possible."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "optional": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shows \"(optional)\" hint text next to the label.\r\nMutually exclusive with `required` \u2014 `required` wins if both are set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "optional",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Applies disabled styling and prevents interaction."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "readonly": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Applies read-only styling (dimmed, no pointer events)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "readonly",
+                "defaultValue": "false"
+            },
+            "invalid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Applies invalid / error styling to the label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "invalid",
+                "defaultValue": "false"
+            },
+            "focused": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Mirrors the focused state of the associated control so the label can react visually."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "focused",
+                "defaultValue": "false"
+            },
+            "loading": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shows a loading skeleton overlaid on the label text."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "loading",
+                "defaultValue": "false"
+            },
+            "errorText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Error message shown below the label when `invalid` is true."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "error-text",
+                "defaultValue": "''"
+            },
+            "successText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Success message shown below the label when the field is valid and this text is set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "success-text",
+                "defaultValue": "''"
+            },
+            "helperText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Helper / hint text shown below the label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "helper-text",
+                "defaultValue": "''"
+            },
+            "ariaLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Sets `aria-label` on the root element."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "aria-label",
+                "defaultValue": "''"
+            },
+            "ariaDescribedby": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "IDs of elements that describe this label (space-separated)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "aria-describedby",
+                "defaultValue": "''"
+            },
+            "ariaLive": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelAriaLive",
+                    "resolved": "\"assertive\" | \"off\" | \"polite\"",
+                    "references": {
+                        "LabelAriaLive": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelAriaLive",
+                            "referenceLocation": "LabelAriaLive"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'off'"
+                        }],
+                    "text": "Live-region politeness for dynamic content announcements."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "aria-live",
+                "defaultValue": "'off'"
+            },
+            "orientation": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelOrientation",
+                    "resolved": "\"horizontal\" | \"vertical\"",
+                    "references": {
+                        "LabelOrientation": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelOrientation",
+                            "referenceLocation": "LabelOrientation"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'vertical'"
+                        }],
+                    "text": "Stack direction when used alongside a form control."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "orientation",
+                "defaultValue": "'vertical'"
+            },
+            "align": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelAlign",
+                    "resolved": "\"between\" | \"center\" | \"end\" | \"start\"",
+                    "references": {
+                        "LabelAlign": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelAlign",
+                            "referenceLocation": "LabelAlign"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'start'"
+                        }],
+                    "text": "Horizontal alignment of label content."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "align",
+                "defaultValue": "'start'"
+            },
+            "inline": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Renders as an inline-level element."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "inline",
+                "defaultValue": "false"
+            },
+            "block": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Forces 100 % width block layout (useful inside flex/grid parents)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "block",
+                "defaultValue": "false"
+            },
+            "gap": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Gap between the label row and the hint / error message.\r\nAccepts any valid CSS length (e.g. `'4px'`, `'0.5rem'`).\r\nMaps to `--ui-label-gap`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "gap",
+                "defaultValue": "''"
+            },
+            "margin": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "External margin override (CSS shorthand string)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "margin",
+                "defaultValue": "''"
+            },
+            "padding": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "External padding override (CSS shorthand string)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "padding",
+                "defaultValue": "''"
+            },
+            "startIcon": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Icon name rendered before the label text.\r\nUses the same icon library as the rest of the design system."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "start-icon",
+                "defaultValue": "''"
+            },
+            "endIcon": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Icon name rendered after the label text."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "end-icon",
+                "defaultValue": "''"
+            },
+            "iconOnly": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "When true, only icons are shown \u2014 label text is visually hidden."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "icon-only",
+                "defaultValue": "false"
+            },
+            "tooltipIcon": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Icon name or URL for the tooltip trigger button.\r\nDefaults to an '\u24D8' info glyph."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "tooltip-icon",
+                "defaultValue": "'\u24D8'"
+            },
+            "tooltip": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Plain-text tooltip content.  Use the `tooltip` slot for rich markup."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "tooltip",
+                "defaultValue": "''"
+            },
+            "tooltipPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelTooltipPosition",
+                    "resolved": "\"bottom\" | \"left\" | \"right\" | \"top\"",
+                    "references": {
+                        "LabelTooltipPosition": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelTooltipPosition",
+                            "referenceLocation": "LabelTooltipPosition"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'top'"
+                        }],
+                    "text": "Preferred position for the tooltip callout."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "tooltip-position",
+                "defaultValue": "'top'"
+            },
+            "clickable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Makes the label itself clickable (fires `labelClick`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clickable",
+                "defaultValue": "false"
+            },
+            "selectable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enables text-selection on the label (disabled by default for form labels)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selectable",
+                "defaultValue": "false"
+            },
+            "copyable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Shows a copy-to-clipboard button on hover and fires `labelCopy`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "copyable",
+                "defaultValue": "false"
+            },
+            "responsive": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enable responsive font-size scaling via fluid typography."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "responsive",
+                "defaultValue": "false"
+            },
+            "mobileStack": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "On narrow viewports, switches from `horizontal` to `vertical` orientation."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "mobile-stack",
+                "defaultValue": "false"
+            },
+            "labelDir": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "LabelDir",
+                    "resolved": "\"auto\" | \"ltr\" | \"rtl\"",
+                    "references": {
+                        "LabelDir": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelDir",
+                            "referenceLocation": "LabelDir"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "'ltr'"
+                        }],
+                    "text": "Text direction."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "dir",
+                "defaultValue": "'ltr'"
+            },
+            "labelLang": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "BCP-47 language tag (e.g. `'en'`, `'ar'`, `'fr'`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "lang",
+                "defaultValue": "''"
+            },
+            "labelId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "DOM `id` for the root element.  Auto-generated if not provided."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label-id",
+                "defaultValue": "''"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Logical name (maps to `name` attribute on the inner label)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "name",
+                "defaultValue": "''"
+            },
+            "testId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "`data-testid` attribute for automated testing."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "test-id",
+                "defaultValue": "''"
+            },
+            "automationId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "`data-automation-id` attribute for RPA / automation tooling."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "automation-id",
+                "defaultValue": "''"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "_isFocused": {},
+            "_tooltipOpen": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "labelClick",
+                "name": "labelClick",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fired when the label element is clicked (requires `clickable` or naturally via `for`)."
+                },
+                "complexType": {
+                    "original": "LabelClickEvent",
+                    "resolved": "LabelClickEvent",
+                    "references": {
+                        "LabelClickEvent": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelClickEvent",
+                            "referenceLocation": "LabelClickEvent"
+                        }
+                    }
+                }
+            }, {
+                "method": "labelFocus",
+                "name": "labelFocus",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fired when the label receives focus (passes through from the native label)."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "labelBlur",
+                "name": "labelBlur",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fired when the label loses focus."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "labelCopy",
+                "name": "labelCopy",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fired after text is successfully copied to the clipboard (`copyable` must be true)."
+                },
+                "complexType": {
+                    "original": "LabelCopyEvent",
+                    "resolved": "LabelCopyEvent",
+                    "references": {
+                        "LabelCopyEvent": {
+                            "location": "import",
+                            "path": "./types",
+                            "id": "src/components/label/types.ts::LabelCopyEvent",
+                            "referenceLocation": "LabelCopyEvent"
+                        }
+                    }
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "setFocus": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Programmatically focus the label element.\r\nUseful when the owning form-field component proxies focus behaviour.",
+                    "tags": []
+                }
+            },
+            "copyText": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Programmatically trigger the copy-to-clipboard action.",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "focused",
+                "methodName": "onFocusedChanged"
+            }];
+    }
+}