@reliability-design/web 1.3.0 → 1.4.0

package/dist/components/rel-textfield/rel-textfield.ts

@@ -1,397 +1,718 @@
-import { LitElement, html, css } from "lit";
-import { customElement, property, state } from "lit/decorators.js";
-import "../../styles/vars-v2.css";
-import "@reliability-design/icons/rel-icon";
-
-export type TextFieldState = "default" | "error" | "disabled";
-export type TextFieldSize = "small" | "medium" | "large";
-export type TextFieldVariant = "default" | "underline";
-
-@customElement("rel-textfield")
-export class RelTextfield extends LitElement {
-  @property({ type: String }) label?: string;
-  @property({ type: String }) placeholder: string = "";
-  @property({ type: String }) type: string = "text";
-  @property({ type: String }) value: string = "";
-  @property({ type: String }) leftIcon?: string;
-  @property({ type: String }) rightIcon?: string;
-  @property({ type: String }) supportingText?: string;
-  @property({ type: String }) state: TextFieldState = "default";
-  @property({ type: String }) size: TextFieldSize = "medium";
-  @property({ type: Boolean, reflect: true }) floatingLabel = false;
-  @property({ type: String, reflect: true }) variant: TextFieldVariant = "default";
-
-  @state() private internalState: "default" | "focused" = "default";
-  private _wasError = false;
-
-  private uniqueId = `textfield-${Math.random().toString(36).slice(2)}`;
-
-  static styles = css`
-    :host {
-      display: block;
-      font-family: var(--rel-fontFamilies-primary);
-    }
-
-    /* Wrapper */
-    .textfield-wrapper {
-      display: flex;
-      flex-direction: column;
-      gap: var(--rel-spacing-space-2xs);
-      width: 100%;
-    }
-
-    /* Label */
-    .textfield-label {
-      font-size: var(--rel-fontSizes-sm);
-      font-weight: var(--rel-fontWeights-medium);
-      color: var(--rel-color-text-heading);
-    }
-
-    /* Floating label variant */
-    :host([floatinglabel]) .textfield-wrapper {
-      gap: 0;
-    }
-
-    :host([floatinglabel]) .textfield-container {
-      overflow: visible;
-      position: relative;
-      padding-top: 0;
-    }
-
-    :host([floatinglabel]) .textfield-label {
-      position: absolute;
-      left: var(--rel-spacing-space-sm);
-      top: 50%;
-      transform: translateY(-50%);
-      font-size: var(--rel-fontSizes-md);
-      font-weight: var(--rel-fontWeights-regular);
-      color: var(--rel-color-text-placeholder);
-      pointer-events: none;
-      transition: top 0.15s ease, font-size 0.15s ease, color 0.15s ease, transform 0.15s ease;
-      background: var(--rel-color-bg-primary);
-      padding: 0 2px;
-      z-index: 1;
-      line-height: 1;
-      white-space: nowrap;
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.focused .textfield-label,
-    :host([floatinglabel]) .textfield-wrapper.has-value .textfield-label {
-      top: 0;
-      transform: translateY(-50%);
-      font-size: var(--rel-fontSizes-xs);
-      color: var(--rel-color-text-primary);
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.error .textfield-label {
-      color: var(--rel-error-text);
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.focused:not(.error) .textfield-label {
-      color: var(--rel-color-text-primary);
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.focused.error .textfield-label,
-    :host([floatinglabel]) .textfield-wrapper.has-value.error .textfield-label {
-      top: 0;
-      transform: translateY(-50%);
-      font-size: var(--rel-fontSizes-xs);
-      color: var(--rel-error-text);
-    }
-
-    :host([floatinglabel]) .textfield-input {
-      padding-top: var(--rel-spacing-space-sm);
-      padding-bottom: var(--rel-spacing-space-sm);
-    }
-
-    :host([floatinglabel]) .textfield-input.has-left-icon {
-      padding-left: var(--rel-spacing-space-2xl);
-    }
-
-    :host([floatinglabel]) .textfield-label.has-left-icon {
-      left: var(--rel-spacing-space-2xl);
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.focused .textfield-label.has-left-icon,
-    :host([floatinglabel]) .textfield-wrapper.has-value .textfield-label.has-left-icon {
-      left: var(--rel-spacing-space-sm);
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.disabled .textfield-label {
-      background: var(--rel-color-bg-tertiary);
-    }
-
-    /* Container */
-    .textfield-container {
-      display: flex;
-      align-items: center;
-      position: relative;
-      border: 1px solid var(--rel-color-border-default);
-      border-radius: var(--rel-borders-radius-border-radius-100);
-      background: var(--rel-color-bg-primary);
-      overflow: hidden;
-      transition: border 0.2s;
-    }
-
-    .textfield-container.disabled {
-      background: var(--rel-color-bg-tertiary);
-      cursor: not-allowed;
-    }
-
-    /* Input */
-    .textfield-input {
-      flex: 1;
-      border: none;
-      outline: none;
-      font-size: var(--rel-fontSizes-md);
-      padding: var(--rel-spacing-space-xs) var(--rel-spacing-space-sm);
-      background: transparent;
-      font-family: var(--rel-fontFamilies-primary);
-      color: var(--rel-color-text-primary);
-    }
-
-    .textfield-input:disabled {
-      cursor: not-allowed;
-      color: var(--rel-color-text-disabled);
-    }
-
-    .icon {
-      position: absolute;
-      display: flex;
-      pointer-events: none;
-      color: var(--rel-color-text-placeholder);
-    }
-
-    .icon.left {
-      left: 8px;
-    }
-
-    .icon.right {
-      right: 8px;
-    }
-
-    .textfield-wrapper.small .textfield-input {
-      padding: var(--rel-spacing-space-xs) var(--rel-spacing-space-sm);
-      font-size: var(--rel-fontSizes-sm);
-    }
-
-    .textfield-wrapper.medium .textfield-input {
-      padding: var(--rel-spacing-space-sm) var(--rel-spacing-space-md);
-      font-size: var(--rel-fontSizes-md);
-    }
-
-    .textfield-wrapper.large .textfield-input {
-      padding: var(--rel-spacing-space-md) var(--rel-spacing-space-md);
-      font-size: var(--rel-fontSizes-lg);
-    }
-
-    /* Adjust padding when icons are present */
-    .textfield-wrapper .textfield-input.has-left-icon {
-      padding-left: var(--rel-spacing-space-2xl);
-    }
-
-    .textfield-wrapper .textfield-input.has-right-icon {
-      padding-right: var(--rel-spacing-space-2xl);
-    }
-
-    /* States */
-    .textfield-wrapper.focused .textfield-container {
-      border-color: var(--rel-color-text-primary);
-    }
-
-    .textfield-input:focus-visible {
-      outline: none;
-    }
-
-    .textfield-wrapper.focused .textfield-container,
-    .textfield-container:focus-within {
-      border-color: var(--rel-color-text-primary);
-      box-shadow: 0 0 0 1px var(--rel-color-text-primary);
-    }
-
-    .textfield-wrapper.error .textfield-container {
-      border-color: var(--rel-error-surface-default);
-      box-shadow: none;
-    }
-
-    .textfield-wrapper.disabled .textfield-container {
-      border-color: var(--rel-color-border-default);
-    }
-
-    /* Supporting text */
-    .textfield-support {
-      font-size: var(--rel-fontSizes-xs);
-      color: var(--rel-color-text-placeholder);
-    }
-
-    .textfield-support.error {
-      color: var(--rel-error-surface-default, #CC0000);
-    }
-
-    /* Placeholder */
-    .textfield-input::placeholder {
-      color: var(--rel-color-text-placeholder);
-    }
-
-    :host([floatinglabel]) .textfield-input::placeholder {
-      opacity: 0;
-    }
-
-    :host([floatinglabel]) .textfield-wrapper.focused .textfield-input::placeholder {
-      opacity: 1;
-    }
-
-    /* Suppress Chrome autofill blue background */
-    .textfield-input:-webkit-autofill,
-    .textfield-input:-webkit-autofill:hover,
-    .textfield-input:-webkit-autofill:focus {
-      -webkit-box-shadow: 0 0 0px 1000px var(--rel-color-bg-primary) inset;
-      -webkit-text-fill-color: var(--rel-color-text-primary);
-    }
-
-    /* ── Underline variant ── */
-    :host([variant="underline"]) .textfield-container {
-      border: none;
-      border-bottom: 2px solid var(--rel-color-border-default);
-      border-radius: 0;
-      background: var(--rel-color-bg-tertiary, #f5f5f5);
-      box-shadow: none;
-      overflow: visible;
-    }
-
-    :host([variant="underline"]) .textfield-wrapper.focused .textfield-container,
-    :host([variant="underline"]) .textfield-container:focus-within {
-      border-bottom: 2px solid var(--rel-color-text-primary);
-      box-shadow: none;
-    }
-
-    :host([variant="underline"]) .textfield-wrapper.error .textfield-container {
-      border-bottom: 2px solid var(--rel-error-surface-default, #CC0000);
-      box-shadow: none;
-    }
-
-    :host([variant="underline"]) .textfield-wrapper.disabled .textfield-container {
-      border-bottom: 2px solid var(--rel-color-border-default);
-      background: var(--rel-color-bg-tertiary);
-    }
-
-    /* Remove border radius on input for underline variant */
-    :host([variant="underline"]) .textfield-input {
-      background: transparent;
-    }
-
-    /* Dark mode — underline variant uses same border colors as default */
-    :host-context([data-theme="dark"]) :host([variant="underline"]) .textfield-container,
-    :host-context(.dark) :host([variant="underline"]) .textfield-container {
-      background: var(--rel-color-bg-tertiary);
-      border-bottom-color: var(--rel-color-border-default);
-    }
-  `;
-
-  connectedCallback() {
-    super.connectedCallback();
-    const leftIcon = this.getAttribute('lefticon') || this.getAttribute('leftIcon');
-    if (leftIcon) this.leftIcon = leftIcon;
-    const rightIcon = this.getAttribute('righticon') || this.getAttribute('rightIcon');
-    if (rightIcon) this.rightIcon = rightIcon;
-  }
-
-  private handleFocus() {
-    if (this.state !== "disabled") {
-      this.internalState = "focused";
-    }
-  }
-
-  private handleBlur() {
-    if (this.internalState === "focused") {
-      this.internalState = "default";
-    }
-  }
-
-  private handleInput(e: Event) {
-    const input = e.target as HTMLInputElement;
-    this.value = input.value;
-    if (this.state === "error" && this.value) {
-      this._wasError = true;
-      this.state = "default";
-    } else if (this._wasError && !this.value) {
-      this._wasError = false;
-      this.state = "error";
-    }
-    this.dispatchEvent(
-      new CustomEvent<string>("rel-change", {
-        detail: this.value,
-        bubbles: true,
-        composed: true,
-      })
-    );
-  }
-
-  render() {
-    const wrapperClasses = [
-      "textfield-wrapper",
-      this.size,
-      this.state,
-      this.internalState === "focused" ? "focused" : "",
-      this.value ? "has-value" : "",
-    ].filter(Boolean).join(" ");
-
-    const inputClasses = [
-      "textfield-input",
-      this.leftIcon ? "has-left-icon" : "",
-      this.rightIcon ? "has-right-icon" : "",
-    ]
-      .filter(Boolean)
-      .join(" ");
-
-    return html`
-      <div class="${wrapperClasses}">
-        ${!this.floatingLabel && this.label
-          ? html`<label class="textfield-label" for="${this.uniqueId}">${this.label}</label>`
-          : ""}
-
-        <div
-          class="textfield-container ${this.state === "disabled"
-            ? "disabled"
-            : ""}"
-        >
-          ${this.floatingLabel && this.label
-            ? html`<label
-                class="textfield-label${this.leftIcon ? ' has-left-icon' : ''}"
-                for="${this.uniqueId}">${this.label}</label>`
-            : ""}
-          ${this.leftIcon
-            ? html`<rel-icon name="${this.leftIcon}" size="sm" class="icon left"></rel-icon>`
-            : ""}
-
-          <input
-            type="${this.type}"
-            id="${this.uniqueId}"
-            class="${inputClasses}"
-            placeholder="${this.placeholder}"
-            .value="${this.value}"
-            ?disabled="${this.state === "disabled"}"
-            aria-invalid="${this.state === "error"}"
-            @focus="${this.handleFocus}"
-            @blur="${this.handleBlur}"
-            @input="${this.handleInput}"
-          />
-
-          ${this.rightIcon
-            ? html`<rel-icon name="${this.rightIcon}" size="sm" class="icon right"></rel-icon>`
-            : ""}
-        </div>
-
-        ${this.supportingText
-          ? html`<div
-              class="textfield-support ${this.state === "error"
-                ? "error"
-                : ""}"
-            >
-              ${this.supportingText}
-            </div>`
-          : ""}
-      </div>
-    `;
-  }
-}
+import { LitElement, html, css, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import "@reliability-design/icons/rel-icon";
+
+export type TextFieldState = "default" | "error" | "disabled";
+export type TextFieldSize = "small" | "medium" | "large";
+export type TextFieldVariant = "default" | "underline" | "legend";
+
+@customElement("rel-textfield")
+export class RelTextfield extends LitElement {
+  @property({ type: String }) label?: string;
+  @property({ type: String }) placeholder: string = "";
+  @property({ type: String }) type: string = "text";
+  @property({ type: String }) value: string = "";
+  @property({ type: String }) leftIcon?: string;
+  @property({ type: String }) rightIcon?: string;
+  @property({ type: String }) supportingText?: string;
+  @property({ type: String }) state: TextFieldState = "default";
+  @property({ type: String }) size: TextFieldSize = "medium";
+  @property({ type: Boolean, reflect: true }) floatingLabel = false;
+  @property({ type: String, reflect: true }) variant: TextFieldVariant = "default";
+  @property({ type: Boolean }) disabled = false;
+  @property({ type: Boolean }) required = false;
+  @property({ type: Boolean, reflect: true }) multiline = false;
+  @property({ type: Number }) rows = 3;
+
+  // ── Standardized input API (senior-team spec) ──────────────────────────────
+  // Prefer these over the deprecated aliases: prefixIcon (was leftIcon),
+  // helperText (was supportingText), error (was state="error").
+  @property({ type: String }) prefixIcon?: string;
+  @property({ type: String }) prefixIconAriaLabel?: string;
+  @property({ type: Boolean }) error = false;
+  @property({ type: String }) errorMessage?: string;
+  @property({ type: String }) helperText?: string;
+  @property({ type: Boolean }) readonly = false;
+  @property({ type: Number }) maxLength?: number;
+  @property({ type: String }) name?: string;
+  @property({ type: Boolean, reflect: true }) fullWidth = true;
+
+  @state() private internalState: "default" | "focused" = "default";
+  private _wasError = false;
+
+  private uniqueId = `textfield-${Math.random().toString(36).slice(2)}`;
+
+  private get isDisabled() {
+    return this.disabled || this.state === "disabled";
+  }
+
+  private get isError() {
+    return this.error || this.state === "error";
+  }
+
+  // prefixIcon supersedes the deprecated leftIcon
+  private get leadingIcon() {
+    return this.prefixIcon ?? this.leftIcon;
+  }
+
+  // helperText supersedes the deprecated supportingText
+  private get helper() {
+    return this.helperText ?? this.supportingText;
+  }
+
+  static styles = css`
+    :host {
+      color: var(--rel-text-default);
+      display: block;
+      font-family: var(--rel-fonts-font-family);
+    }
+
+    /* Wrapper */
+    .textfield-wrapper {
+      display: flex;
+      flex-direction: column;
+      gap: var(--rel-spacing-2xs);
+      width: 100%;
+    }
+
+    /* Label */
+    .textfield-label {
+      color: var(--rel-text-label);
+
+      font-family: var(--rel-body-sm-medium-font-family);
+
+      font-weight: var(--rel-body-sm-medium-font-weight);
+
+      font-size: var(--rel-body-sm-medium-font-size);
+
+      line-height: var(--rel-body-sm-medium-line-height);
+
+      letter-spacing: var(--rel-body-sm-medium-letter-spacing);
+
+    }
+
+    .required-mark {
+      color: var(--rel-text-danger);
+      margin-left: 2px;
+    }
+
+    /* Floating label variant */
+    :host([floatinglabel]) .textfield-wrapper {
+      gap: 0;
+    }
+
+    :host([floatinglabel]) .textfield-container {
+      overflow: visible;
+      position: relative;
+      padding-top: 0;
+    }
+
+    :host([floatinglabel]) .textfield-label {
+      position: absolute;
+      left: var(--rel-spacing-sm);
+      top: 50%;
+      transform: translateY(-50%);
+      color: var(--rel-text-placeholder);
+      pointer-events: none;
+      transition: top 0.15s ease, font-size 0.15s ease, color 0.15s ease, transform 0.15s ease;
+      background: var(--rel-bg-neutral);
+      padding: 0 2px;
+      z-index: 1;
+      white-space: nowrap;
+      font-family: var(--rel-body-md-regular-font-family);
+      font-weight: var(--rel-body-md-regular-font-weight);
+      font-size: var(--rel-body-md-regular-font-size);
+      line-height: var(--rel-body-md-regular-line-height);
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+    }
+
+    /* Floating label in multiline mode anchors to top instead of vertical center */
+    :host([floatinglabel][multiline]) .textfield-label {
+      top: var(--rel-spacing-sm);
+      transform: none;
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.focused .textfield-label,
+    :host([floatinglabel]) .textfield-wrapper.has-value .textfield-label {
+      top: 0;
+      transform: translateY(-50%);
+      color: var(--rel-text-default);
+      font-family: var(--rel-body-xs-regular-font-family);
+      font-weight: var(--rel-body-xs-regular-font-weight);
+      font-size: var(--rel-body-xs-regular-font-size);
+      line-height: var(--rel-body-xs-regular-line-height);
+      letter-spacing: var(--rel-body-xs-regular-letter-spacing);
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.error .textfield-label {
+      color: var(--rel-text-danger);
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.focused:not(.error) .textfield-label {
+      color: var(--rel-text-default);
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.focused.error .textfield-label,
+    :host([floatinglabel]) .textfield-wrapper.has-value.error .textfield-label {
+      top: 0;
+      transform: translateY(-50%);
+      color: var(--rel-text-danger);
+      font-family: var(--rel-body-xs-regular-font-family);
+      font-weight: var(--rel-body-xs-regular-font-weight);
+      font-size: var(--rel-body-xs-regular-font-size);
+      line-height: var(--rel-body-xs-regular-line-height);
+      letter-spacing: var(--rel-body-xs-regular-letter-spacing);
+    }
+
+    :host([floatinglabel]) .textfield-input {
+      padding-top: var(--rel-spacing-sm);
+      padding-bottom: var(--rel-spacing-sm);
+    }
+
+    :host([floatinglabel]) .textfield-input.has-left-icon {
+      padding-left: var(--rel-spacing-2xl);
+    }
+
+    :host([floatinglabel]) .textfield-label.has-left-icon {
+      left: var(--rel-spacing-2xl);
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.focused .textfield-label.has-left-icon,
+    :host([floatinglabel]) .textfield-wrapper.has-value .textfield-label.has-left-icon {
+      left: var(--rel-spacing-sm);
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.disabled .textfield-label {
+      background: var(--rel-bg-neutral-elevated-1);
+    }
+
+    /* Container */
+    .textfield-container {
+      display: flex;
+      align-items: center;
+      position: relative;
+      border: 1px solid var(--rel-border-default);
+      border-radius: var(--rel-border-radius-xs);
+      background: var(--rel-bg-neutral);
+      overflow: hidden;
+      transition: border 0.2s;
+    }
+
+    .textfield-container.disabled {
+      background: var(--rel-bg-neutral-elevated-1);
+      cursor: not-allowed;
+    }
+
+    .textfield-container.multiline {
+      overflow: visible;
+      align-items: flex-start;
+    }
+
+    /* Input */
+    .textfield-input {
+      flex: 1;
+      border: none;
+      outline: none;
+      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);
+      background: transparent;
+      color: var(--rel-text-body);
+      font-family: var(--rel-body-md-regular-font-family);
+      font-weight: var(--rel-body-md-regular-font-weight);
+      font-size: var(--rel-body-md-regular-font-size);
+      line-height: var(--rel-body-md-regular-line-height);
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+    }
+
+    .textfield-input:disabled {
+      cursor: not-allowed;
+      color: var(--rel-text-disabled);
+    }
+
+    /* Textarea */
+    textarea.textfield-input {
+      resize: vertical;
+      min-height: 80px;
+      width: 100%;
+      box-sizing: border-box;
+    }
+
+    textarea.textfield-input::-webkit-scrollbar {
+      width: 4px;
+    }
+    textarea.textfield-input::-webkit-scrollbar-track {
+      background: transparent;
+    }
+    textarea.textfield-input::-webkit-scrollbar-thumb {
+      background: var(--rel-text-placeholder);
+      border-radius: 2px;
+    }
+
+    .icon {
+      position: absolute;
+      display: flex;
+      pointer-events: none;
+      color: var(--rel-text-placeholder);
+    }
+
+    .icon.left {
+      left: 8px;
+    }
+
+    .icon.right {
+      right: 8px;
+    }
+
+    .textfield-wrapper.small .textfield-support {
+      font-weight: var(--rel-body-xs-medium-font-weight);
+    }
+
+    .textfield-wrapper.small .textfield-input {
+      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);
+      font-family: var(--rel-body-sm-regular-font-family);
+      font-weight: var(--rel-body-sm-regular-font-weight);
+      font-size: var(--rel-body-sm-regular-font-size);
+      line-height: var(--rel-body-sm-regular-line-height);
+      letter-spacing: var(--rel-body-sm-regular-letter-spacing);
+    }
+
+    .textfield-wrapper.medium .textfield-input {
+      padding: var(--rel-spacing-sm) var(--rel-spacing-md);
+      font-family: var(--rel-body-md-regular-font-family);
+      font-weight: var(--rel-body-md-regular-font-weight);
+      font-size: var(--rel-body-md-regular-font-size);
+      line-height: var(--rel-body-md-regular-line-height);
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+    }
+
+    .textfield-wrapper.large .textfield-input {
+      padding: var(--rel-spacing-md) var(--rel-spacing-md);
+      font-family: var(--rel-body-lg-regular-font-family);
+      font-weight: var(--rel-body-lg-regular-font-weight);
+      font-size: var(--rel-body-lg-regular-font-size);
+      line-height: var(--rel-body-lg-regular-line-height);
+      letter-spacing: var(--rel-body-lg-regular-letter-spacing);
+    }
+
+    /* Adjust padding when icons are present */
+    .textfield-wrapper .textfield-input.has-left-icon {
+      padding-left: var(--rel-spacing-2xl);
+    }
+
+    .textfield-wrapper .textfield-input.has-right-icon {
+      padding-right: var(--rel-spacing-2xl);
+    }
+
+    /* States */
+    /* Hover (Figma State=Hover): border-strong at 1px — no focus ring */
+    .textfield-wrapper:not(.focused):not(.error):not(.disabled) .textfield-container:hover {
+      border-color: var(--rel-border-strong);
+    }
+
+    .textfield-wrapper.focused .textfield-container {
+      border-color: var(--rel-text-default);
+    }
+
+    .textfield-input:focus-visible {
+      outline: none;
+    }
+
+    .textfield-wrapper.focused .textfield-container,
+    .textfield-container:focus-within {
+      border-color: var(--rel-border-strong);
+      box-shadow: 0 0 0 1px var(--rel-border-strong);
+    }
+
+    .textfield-wrapper.error .textfield-container,
+    .textfield-wrapper.error .textfield-container:focus-within {
+      border-color: var(--rel-border-danger);
+      box-shadow: none;
+    }
+
+    .textfield-wrapper.disabled .textfield-container {
+      border-color: var(--rel-border-default);
+    }
+
+    .textfield-wrapper.disabled .textfield-label {
+      color: var(--rel-text-disabled);
+    }
+
+    /* Supporting text */
+    .textfield-support {
+      color: var(--rel-text-caption);
+
+      font-family: var(--rel-body-xs-regular-font-family);
+
+      font-weight: var(--rel-body-xs-regular-font-weight);
+
+      font-size: var(--rel-body-xs-regular-font-size);
+
+      line-height: var(--rel-body-xs-regular-line-height);
+
+      letter-spacing: var(--rel-body-xs-regular-letter-spacing);
+
+    }
+
+    .textfield-support.error {
+      color: var(--rel-text-danger);
+    }
+
+    /* Placeholder */
+    .textfield-input::placeholder {
+      color: var(--rel-text-placeholder);
+    }
+
+    :host([floatinglabel]) .textfield-input::placeholder {
+      opacity: 0;
+    }
+
+    :host([floatinglabel]) .textfield-wrapper.focused .textfield-input::placeholder {
+      opacity: 1;
+    }
+
+    /* Suppress Chrome autofill blue background */
+    .textfield-input:-webkit-autofill,
+    .textfield-input:-webkit-autofill:hover,
+    .textfield-input:-webkit-autofill:focus {
+      -webkit-box-shadow: 0 0 0px 1000px var(--rel-bg-surface) inset;
+      -webkit-text-fill-color: var(--rel-text-default);
+    }
+
+    /* ── Underline variant ── */
+    :host([variant="underline"]) .textfield-container {
+      border: none;
+      border-bottom: 2px solid var(--rel-border-default);
+      border-radius: 0;
+      background: var(--rel-bg-neutral-elevated-1);
+      box-shadow: none;
+      overflow: visible;
+    }
+
+    :host([variant="underline"]) .textfield-wrapper:not(.focused):not(.error):not(.disabled) .textfield-container:hover {
+      border-bottom-color: var(--rel-border-strong);
+    }
+
+    :host([variant="underline"]) .textfield-wrapper.focused .textfield-container,
+    :host([variant="underline"]) .textfield-container:focus-within {
+      border-bottom: 2px solid var(--rel-text-default);
+      box-shadow: none;
+    }
+
+    :host([variant="underline"]) .textfield-wrapper.error .textfield-container {
+      border-bottom: 2px solid var(--rel-border-danger);
+      box-shadow: none;
+    }
+
+    :host([variant="underline"]) .textfield-wrapper.disabled .textfield-container {
+      border-bottom: 2px solid var(--rel-border-default);
+      background: var(--rel-bg-neutral-elevated-1);
+    }
+
+    /* Remove border radius on input for underline variant */
+    :host([variant="underline"]) .textfield-input {
+      background: transparent;
+    }
+
+    /* Dark mode — underline variant uses same border colors as default */
+    :host-context([data-theme="dark"]) :host([variant="underline"]) .textfield-container,
+    :host-context(.dark) :host([variant="underline"]) .textfield-container {
+      background: var(--rel-bg-neutral-elevated-1);
+      border-bottom-color: var(--rel-border-default);
+    }
+
+    /* ── Full-width control (fullWidth defaults true → block, fills parent) ── */
+    :host(:not([fullwidth])) {
+      display: inline-block;
+      width: auto;
+    }
+    :host(:not([fullwidth])) .textfield-wrapper {
+      width: auto;
+    }
+
+    /* ── Legend (notched-outline) variant ──
+       Native <fieldset>/<legend>: the legend notches the top border and stays
+       fixed in place across all states (no float/animation). */
+    :host([variant="legend"]) .field-fieldset {
+      position: relative;
+      margin: 0;
+      min-inline-size: 0;
+      padding: 0;
+      border: 1px solid var(--rel-border-default);
+      border-radius: var(--rel-border-radius-xs);
+      background: var(--rel-bg-neutral);
+      transition: border-color 0.2s;
+    }
+
+    :host([variant="legend"]) .field-legend {
+      margin-left: var(--rel-spacing-sm);
+      padding: 0 var(--rel-spacing-2xs);
+      color: var(--rel-text-label);
+      font-family: var(--rel-body-sm-medium-font-family);
+      font-weight: var(--rel-body-sm-medium-font-weight);
+      font-size: var(--rel-body-sm-medium-font-size);
+      line-height: var(--rel-body-sm-medium-line-height);
+      letter-spacing: var(--rel-body-sm-medium-letter-spacing);
+    }
+
+    :host([variant="legend"]) .textfield-input {
+      width: 100%;
+      box-sizing: border-box;
+    }
+
+    /* Prefix icon (legend): vertically centered; input inset via has-left-icon */
+    :host([variant="legend"]) .icon.left {
+      top: 50%;
+      left: var(--rel-spacing-sm);
+      transform: translateY(-50%);
+    }
+    :host([variant="legend"]) .field-fieldset.multiline .icon.left {
+      top: var(--rel-spacing-sm);
+      transform: none;
+    }
+
+    /* Hover */
+    :host([variant="legend"]) .field-fieldset:hover {
+      border-color: var(--rel-border-accent);
+      border-color: var(--rel-text-placeholder);
+    }
+
+    /* Focus — border-color only. A box-shadow/outline ring hugs the full
+       rectangular border-box and would draw across the notch, appearing to
+       strike through the legend. The legend also recolors on focus (below). */
+    :host([variant="legend"]) .textfield-wrapper.focused .field-fieldset,
+    :host([variant="legend"]) .field-fieldset:focus-within {
+      border-color: var(--rel-border-focus);
+      box-shadow: none;
+    }
+    :host([variant="legend"]) .textfield-wrapper.focused .field-legend,
+    :host([variant="legend"]) .field-fieldset:focus-within .field-legend {
+      color: var(--rel-border-focus);
+    }
+
+    /* Error */
+    :host([variant="legend"]) .textfield-wrapper.error .field-fieldset {
+      border-color: var(--rel-border-danger);
+      box-shadow: none;
+    }
+    :host([variant="legend"]) .textfield-wrapper.error .field-legend {
+      color: var(--rel-text-danger);
+    }
+
+    /* Disabled */
+    :host([variant="legend"]) .textfield-wrapper.disabled .field-fieldset {
+      background: var(--rel-bg-neutral-elevated-1);
+      border-color: var(--rel-border-default);
+      cursor: not-allowed;
+    }
+    :host([variant="legend"]) .textfield-wrapper.disabled .field-legend {
+      color: var(--rel-text-disabled);
+    }
+
+    /* Readonly */
+    :host([variant="legend"]) .textfield-wrapper.readonly .field-fieldset {
+      cursor: default;
+    }
+
+    /* Legend font tracks size */
+    :host([variant="legend"]) .textfield-wrapper.small .field-legend {
+
+      font-family: var(--rel-body-xs-regular-font-family);
+
+      font-weight: var(--rel-body-xs-regular-font-weight);
+
+      font-size: var(--rel-body-xs-regular-font-size);
+
+      line-height: var(--rel-body-xs-regular-line-height);
+
+      letter-spacing: var(--rel-body-xs-regular-letter-spacing);
+
+    }
+    :host([variant="legend"]) .textfield-wrapper.large .field-legend {
+
+      font-family: var(--rel-body-md-regular-font-family);
+
+      font-weight: var(--rel-body-md-regular-font-weight);
+
+      font-size: var(--rel-body-md-regular-font-size);
+
+      line-height: var(--rel-body-md-regular-line-height);
+
+      letter-spacing: var(--rel-body-md-regular-letter-spacing);
+
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    const leftIcon = this.getAttribute('lefticon') || this.getAttribute('leftIcon');
+    if (leftIcon) this.leftIcon = leftIcon;
+    const rightIcon = this.getAttribute('righticon') || this.getAttribute('rightIcon');
+    if (rightIcon) this.rightIcon = rightIcon;
+  }
+
+  private handleFocus() {
+    if (!this.isDisabled) {
+      this.internalState = "focused";
+    }
+  }
+
+  private handleBlur() {
+    if (this.internalState === "focused") {
+      this.internalState = "default";
+    }
+  }
+
+  private handleInput(e: Event) {
+    const input = e.target as HTMLInputElement;
+    this.value = input.value;
+    if (this.state === "error" && this.value) {
+      this._wasError = true;
+      this.state = "default";
+    } else if (this._wasError && !this.value) {
+      this._wasError = false;
+      this.state = "error";
+    }
+    this.dispatchEvent(
+      new CustomEvent<string>("rel-change", {
+        detail: this.value,
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  render() {
+    const isError = this.isError;
+    const stateClass = this.isDisabled ? "disabled" : isError ? "error" : "default";
+    const leadingIcon = this.leadingIcon;
+    const inputId = this.id || this.uniqueId;
+    const legendId = `${inputId}-legend`;
+
+    // errorMessage replaces the helper only when in error AND explicitly set;
+    // otherwise the (deprecated) supportingText/helperText shows as before.
+    const belowText = isError && this.errorMessage ? this.errorMessage : this.helper;
+    const describedById = belowText ? `${inputId}-desc` : undefined;
+
+    const wrapperClasses = [
+      "textfield-wrapper",
+      this.size,
+      stateClass,
+      this.readonly ? "readonly" : "",
+      this.internalState === "focused" ? "focused" : "",
+      this.value ? "has-value" : "",
+    ].filter(Boolean).join(" ");
+
+    const inputClasses = [
+      "textfield-input",
+      !this.multiline && leadingIcon ? "has-left-icon" : "",
+      !this.multiline && this.rightIcon && this.variant !== "legend" ? "has-right-icon" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    const labelTemplate = (extraClass = "") => {
+      if (!this.label) return "";
+      return html`<label
+        part="label"
+        class="textfield-label${extraClass}"
+        for="${inputId}"
+      >${this.label}${this.required ? html`<span class="required-mark" aria-hidden="true">*</span>` : ""}</label>`;
+    };
+
+    const ariaLabelledby = this.variant === "legend" && this.label ? legendId : undefined;
+
+    const inputTemplate = this.multiline
+      ? html`<textarea part="input"
+          id="${inputId}"
+          class="${inputClasses}"
+          placeholder="${this.placeholder}"
+          .value="${this.value}"
+          rows="${this.rows}"
+          name="${this.name ?? nothing}"
+          maxlength="${this.maxLength ?? nothing}"
+          ?disabled="${this.isDisabled}"
+          ?readonly="${this.readonly}"
+          ?required="${this.required}"
+          aria-invalid="${isError}"
+          aria-required="${this.required}"
+          aria-labelledby="${ariaLabelledby ?? nothing}"
+          aria-describedby="${describedById ?? nothing}"
+          @focus="${this.handleFocus}"
+          @blur="${this.handleBlur}"
+          @input="${this.handleInput}"
+        ></textarea>`
+      : html`<input part="input"
+          type="${this.type}"
+          id="${inputId}"
+          class="${inputClasses}"
+          placeholder="${this.placeholder}"
+          .value="${this.value}"
+          name="${this.name ?? nothing}"
+          maxlength="${this.maxLength ?? nothing}"
+          ?disabled="${this.isDisabled}"
+          ?readonly="${this.readonly}"
+          ?required="${this.required}"
+          aria-invalid="${isError}"
+          aria-required="${this.required}"
+          aria-labelledby="${ariaLabelledby ?? nothing}"
+          aria-describedby="${describedById ?? nothing}"
+          @focus="${this.handleFocus}"
+          @blur="${this.handleBlur}"
+          @input="${this.handleInput}"
+        />`;
+
+    const leadingIconTemplate = leadingIcon
+      ? html`<rel-icon
+          name="${leadingIcon}"
+          size="sm"
+          class="icon left"
+          role="${this.prefixIconAriaLabel ? "img" : nothing}"
+          aria-label="${this.prefixIconAriaLabel ?? nothing}"
+          aria-hidden="${this.prefixIconAriaLabel ? nothing : "true"}"
+        ></rel-icon>`
+      : "";
+
+    const belowTemplate = belowText
+      ? html`<div part="helper" class="textfield-support ${isError ? "error" : ""}" id="${describedById}">
+          ${belowText}
+        </div>`
+      : "";
+
+    if (this.variant === "legend") {
+      const fieldsetClass = ["field-fieldset", this.multiline ? "multiline" : ""].filter(Boolean).join(" ");
+      // The <legend> MUST be the fieldset's first child with no preceding
+      // whitespace/text or binding-comment, otherwise the browser won't cut the
+      // notch in the top border. So it's rendered flush against the tag open and
+      // is always present (only its content is dynamic).
+      return html`
+        <div class="${wrapperClasses}">
+          <fieldset part="control" class="${fieldsetClass}"><legend class="field-legend" id="${legendId}">${this.label ?? ""}${this.required ? html`<span class="required-mark" aria-hidden="true">*</span>` : ""}</legend>
+            ${!this.multiline ? leadingIconTemplate : ""}
+            ${inputTemplate}
+          </fieldset>
+          ${belowTemplate}
+        </div>
+      `;
+    }
+
+    return html`
+      <div class="${wrapperClasses}">
+        ${!this.floatingLabel ? labelTemplate() : ""}
+
+        <div part="control" class="${["textfield-container", this.isDisabled ? "disabled" : "", this.multiline ? "multiline" : ""].filter(Boolean).join(" ")}">
+          ${this.floatingLabel
+            ? labelTemplate(leadingIcon && !this.multiline ? " has-left-icon" : "")
+            : ""}
+          ${!this.multiline ? leadingIconTemplate : ""}
+
+          ${inputTemplate}
+
+          ${!this.multiline && this.rightIcon
+            ? html`<rel-icon name="${this.rightIcon}" size="sm" class="icon right"></rel-icon>`
+            : ""}
+        </div>
+
+        ${belowTemplate}
+      </div>
+    `;
+  }
+}