@reliability-design/web 1.4.1 → 1.4.3

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

@@ -1,4 +1,4 @@
-import { LitElement, html, css, nothing } from "lit";
+import { LitElement, html, css, nothing, PropertyValues } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import "@reliability-design/icons/rel-icon";
 
@@ -6,6 +6,16 @@ export type TextFieldState = "default" | "error" | "disabled";
 export type TextFieldSize = "small" | "medium" | "large";
 export type TextFieldVariant = "default" | "underline" | "legend";
 
+/**
+ * How a field presents its label. Shared by `<rel-textfield>`, `<rel-select>`
+ * and `<rel-autocomplete>` so the three stay in step.
+ *   - `"default"`  — static label above the control
+ *   - `"floating"` — label rests over the placeholder, animates onto the border
+ *   - `"none"`     — no label renders; supply `fieldAriaLabel` /
+ *                    `fieldAriaLabelledby` to keep an accessible name
+ */
+export type FieldLabelStyle = "default" | "floating" | "none";
+
 @customElement("rel-textfield")
 export class RelTextfield extends LitElement {
   @property({ type: String }) label?: string;
@@ -22,7 +32,23 @@ export class RelTextfield extends LitElement {
   @property({ type: String }) supportingText?: string;
   @property({ type: String }) state: TextFieldState = "default";
   @property({ type: String }) size: TextFieldSize = "medium";
+  /**
+   * Label presentation. Left `undefined` the deprecated `floatingLabel` boolean
+   * decides, so existing markup keeps working; set explicitly and it wins.
+   * Declares `attribute` because Lit would otherwise only listen for the
+   * all-lowercase `labelstyle`.
+   */
+  @property({ type: String, attribute: "label-style", reflect: true })
+  labelStyle?: FieldLabelStyle;
+  /** @deprecated Use `labelStyle="floating"`. Kept permanently as an alias. */
   @property({ type: Boolean, reflect: true }) floatingLabel = false;
+  /**
+   * Accessible name for the input. Required when `labelStyle="none"`, since no
+   * `<label>` renders and a placeholder is not a valid naming mechanism.
+   */
+  @property({ type: String, attribute: "field-aria-label" }) fieldAriaLabel?: string;
+  /** IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. */
+  @property({ type: String, attribute: "field-aria-labelledby" }) fieldAriaLabelledby?: string;
   @property({ type: String, reflect: true }) variant: TextFieldVariant = "default";
   @property({ type: Boolean }) disabled = false;
   @property({ type: Boolean }) required = false;
@@ -65,6 +91,17 @@ export class RelTextfield extends LitElement {
     return this.helperText ?? this.supportingText;
   }
 
+  /** labelStyle supersedes the deprecated floatingLabel boolean. */
+  private get resolvedLabelStyle(): FieldLabelStyle {
+    if (this.labelStyle) return this.labelStyle;
+    return this.floatingLabel ? "floating" : "default";
+  }
+
+  /** True when no visible label renders and the input needs an ARIA name. */
+  private get labelHidden() {
+    return this.resolvedLabelStyle === "none";
+  }
+
   static styles = css`
     :host {
       color: var(--rel-text-default);
@@ -101,6 +138,22 @@ export class RelTextfield extends LitElement {
       margin-left: 2px;
     }
 
+    /* ── labelStyle="none" ──
+       No label renders. An empty spacer holds the label row's full height so the
+       input box still bottom-aligns with labelled siblings in a form row.
+       The reserve covers label line-height + the wrapper gap, and the negative
+       margin cancels the flex gap that would otherwise sit below it — so
+       --rel-field-label-reserve: 0 collapses the row to genuinely zero
+       (toolbars, table cells), not just to the leftover gap. */
+    .label-reserve {
+      flex: none;
+      height: var(
+        --rel-field-label-reserve,
+        calc(var(--rel-body-sm-medium-line-height) + var(--rel-spacing-2xs))
+      );
+      margin-bottom: calc(-1 * var(--rel-spacing-2xs));
+    }
+
     /* Floating label variant */
     :host([floatinglabel]) .textfield-wrapper {
       gap: 0;
@@ -477,6 +530,12 @@ export class RelTextfield extends LitElement {
       box-sizing: border-box;
     }
 
+    /* labelStyle="none" + legend: nothing to seat in the notch, so drop the
+       legend entirely and let the top border run continuous. */
+    :host([label-style="none"][variant="legend"]) .field-legend {
+      display: none;
+    }
+
     /* Prefix icon (legend): vertically centered; input inset via has-left-icon */
     :host([variant="legend"]) .icon.left {
       top: 50%;
@@ -568,6 +627,34 @@ export class RelTextfield extends LitElement {
     if (rightIcon) this.rightIcon = rightIcon;
   }
 
+  willUpdate(changed: PropertyValues<this>) {
+    // Keep the deprecated boolean an accurate mirror of labelStyle. This is what
+    // lets every `:host([floatinglabel])` rule below stay untouched — the
+    // reflected attribute is still the single styling hook for the floating form.
+    if (changed.has("labelStyle") && this.labelStyle) {
+      this.floatingLabel = this.labelStyle === "floating";
+    }
+  }
+
+  private _warnedNoName = false;
+
+  updated() {
+    if (this._warnedNoName || !this.labelHidden) return;
+    if (this.fieldAriaLabel || this.fieldAriaLabelledby || this.getAttribute("aria-label")) return;
+    this._warnedNoName = true;
+    console.warn(
+      '<rel-textfield label-style="none"> has no accessible name. Set ' +
+        "`field-aria-label` or `field-aria-labelledby` — a placeholder is not a " +
+        "valid naming mechanism.",
+      this
+    );
+  }
+
+  /** Focuses the inner input/textarea (the host itself is not focusable). */
+  focus(options?: FocusOptions) {
+    (this.renderRoot.querySelector("input, textarea") as HTMLElement | null)?.focus(options);
+  }
+
   private handleFocus() {
     if (!this.isDisabled) {
       this.internalState = "focused";
@@ -644,8 +731,11 @@ export class RelTextfield extends LitElement {
       .filter(Boolean)
       .join(" ");
 
+    const labelStyle = this.resolvedLabelStyle;
+    const labelHidden = labelStyle === "none";
+
     const labelTemplate = (extraClass = "") => {
-      if (!this.label) return "";
+      if (!this.label || labelHidden) return "";
       return html`<label
         part="label"
         class="textfield-label${extraClass}"
@@ -653,7 +743,14 @@ export class RelTextfield extends LitElement {
       >${this.label}${this.required ? html`<span class="required-mark" aria-hidden="true">*</span>` : ""}</label>`;
     };
 
-    const ariaLabelledby = this.variant === "legend" && this.label ? legendId : undefined;
+    // With no visible label the <label for> / <legend> naming path is gone, so
+    // fieldAriaLabelledby → fieldAriaLabel take over. An explicit labelledby
+    // always wins; aria-label only fills in when nothing else names the input.
+    const legendLabelledby =
+      this.variant === "legend" && this.label && !labelHidden ? legendId : undefined;
+    const ariaLabelledby = this.fieldAriaLabelledby ?? legendLabelledby;
+    const hasVisibleLabel = !labelHidden && !!this.label;
+    const ariaLabel = !hasVisibleLabel && !ariaLabelledby ? this.fieldAriaLabel : undefined;
 
     const inputTemplate = this.multiline
       ? html`<textarea part="input"
@@ -669,6 +766,7 @@ export class RelTextfield extends LitElement {
           ?required="${this.required}"
           aria-invalid="${isError}"
           aria-required="${this.required}"
+          aria-label="${ariaLabel ?? nothing}"
           aria-labelledby="${ariaLabelledby ?? nothing}"
           aria-describedby="${describedById ?? nothing}"
           @focus="${this.handleFocus}"
@@ -688,6 +786,7 @@ export class RelTextfield extends LitElement {
           ?required="${this.required}"
           aria-invalid="${isError}"
           aria-required="${this.required}"
+          aria-label="${ariaLabel ?? nothing}"
           aria-labelledby="${ariaLabelledby ?? nothing}"
           aria-describedby="${describedById ?? nothing}"
           @focus="${this.handleFocus}"
@@ -720,7 +819,7 @@ export class RelTextfield extends LitElement {
       // 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>
+          <fieldset part="control" class="${fieldsetClass}"><legend class="field-legend" id="${legendId}">${labelHidden ? "" : this.label ?? ""}${this.required && !labelHidden ? html`<span class="required-mark" aria-hidden="true">*</span>` : ""}</legend>
             ${!this.multiline ? leadingIconTemplate : ""}
             ${inputTemplate}
           </fieldset>
@@ -731,10 +830,14 @@ export class RelTextfield extends LitElement {
 
     return html`
       <div class="${wrapperClasses}">
-        ${!this.floatingLabel ? labelTemplate() : ""}
+        ${labelHidden
+          ? html`<div class="label-reserve" aria-hidden="true"></div>`
+          : labelStyle !== "floating"
+            ? labelTemplate()
+            : ""}
 
         <div part="control" class="${["textfield-container", this.isDisabled ? "disabled" : "", this.multiline ? "multiline" : ""].filter(Boolean).join(" ")}">
-          ${this.floatingLabel
+          ${labelStyle === "floating"
             ? labelTemplate(leadingIcon && !this.multiline ? " has-left-icon" : "")
             : ""}
           ${!this.multiline ? leadingIconTemplate : ""}

package/dist/components/rel-time-picker/README.md

@@ -0,0 +1,199 @@
+# rel-time-picker
+
+A fully accessible time picker component built with Lit for the Reliability Design System. Features a trigger button with an hour/minute (and AM/PM) column popover. Selections are held in draft state until Apply is clicked, mirroring the rel-range-picker interaction model.
+
+## Features
+
+- Trigger button with time-column popover (Hour / Min / AM-PM)
+- 12-hour and 24-hour display formats
+- Configurable minute intervals (1, 5, 10, 15, 30, …)
+- Draft state with Now / Cancel / Apply footer
+- Min/max time constraints
+- Optional clear button
+- Label, placeholder, helper text and error states
+- Standardized input API (mirrors rel-textfield / rel-date-picker)
+- Keyboard navigation and full ARIA support
+- Token-driven styling with `::part` hooks
+
+## Value format
+
+The committed `value` is **always 24-hour `"HH:mm"`** (e.g. `"09:30"`, `"17:05"`) regardless of the display `format`, so consumers get a consistent machine-readable string.
+
+## Usage
+
+### Basic
+
+```html
+<rel-time-picker></rel-time-picker>
+```
+
+### With Value
+
+```html
+<rel-time-picker value="09:30"></rel-time-picker>
+```
+
+### With Label
+
+```html
+<rel-time-picker label="Start time" placeholder="Select time"></rel-time-picker>
+```
+
+### 24-hour format
+
+```html
+<rel-time-picker format="24h" value="17:05"></rel-time-picker>
+```
+
+### Minute intervals
+
+```html
+<rel-time-picker minute-step="15"></rel-time-picker>
+<rel-time-picker minute-step="30"></rel-time-picker>
+```
+
+### With Min/Max
+
+```html
+<rel-time-picker
+  min-time="09:00"
+  max-time="17:30"
+  placeholder="Business hours only"
+></rel-time-picker>
+```
+
+### Clearable
+
+```html
+<rel-time-picker value="09:30" clearable></rel-time-picker>
+```
+
+### States
+
+```html
+<rel-time-picker value="09:30" disabled></rel-time-picker>
+<rel-time-picker value="09:30" readonly></rel-time-picker>
+<rel-time-picker error error-message="Select a valid time"></rel-time-picker>
+<rel-time-picker helper-text="Local timezone"></rel-time-picker>
+<rel-time-picker label="Start time" required></rel-time-picker>
+```
+
+### Sizes / layout
+
+```html
+<rel-time-picker size="small"></rel-time-picker>
+<rel-time-picker size="large"></rel-time-picker>
+<rel-time-picker fullWidth></rel-time-picker>
+```
+
+### Form usage
+
+```html
+<form>
+  <rel-time-picker name="startTime" label="Start time" required></rel-time-picker>
+</form>
+```
+
+The value is mirrored onto a hidden `<input name="...">` so native form submission works.
+
+### Programmatic Control (JavaScript)
+
+```javascript
+const picker = document.querySelector('rel-time-picker');
+
+// Set value (always 24h HH:mm)
+picker.value = '14:30';
+
+// Open programmatically
+picker.open = true;
+
+// Listen to changes (fired on Apply, and on clear with value: null)
+picker.addEventListener('rel-change', (e) => {
+  console.log('Selected time:', e.detail.value); // "14:30" | null
+});
+
+picker.addEventListener('rel-open-change', (e) => {
+  console.log('Open:', e.detail.open);
+});
+```
+
+## Interaction model
+
+- Clicking a column entry updates the **draft** shown in the readout row; nothing is committed yet.
+- **Apply** commits the draft, emits `rel-change` and closes.
+- **Cancel**, `Escape` or an outside click discards the draft (same as rel-range-picker).
+- **Now** sets the draft to the current time, snapped to `minute-step` and clamped into `min-time`/`max-time`.
+- Picking an hour with no minute selected defaults the minute to `00`.
+
+## Keyboard
+
+| Key | Context | Action |
+| --- | --- | --- |
+| `Enter` / `Space` / `ArrowDown` | Trigger | Open the popover |
+| `ArrowUp` / `ArrowDown` | Column | Move and select the previous/next entry |
+| `ArrowLeft` / `ArrowRight` | Column | Jump between Hour / Min / AM-PM columns |
+| `Home` / `End` | Column | First / last entry |
+| `Enter` | Column | Select the entry and Apply |
+| `Escape` | Anywhere | Discard draft and close |
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string \| null` | `null` | Committed time, 24h `"HH:mm"` |
+| `placeholder` | `placeholder` | `string` | `"Select time"` | Trigger text when empty |
+| `label` | `label` | `string \| null` | `null` | Field label |
+| `format` | `format` | `"12h" \| "24h"` | `"12h"` | Display format (value stays `HH:mm`) |
+| `minuteStep` | `minute-step` | `number` | `1` | Minute column granularity |
+| `minTime` | `min-time` | `string \| null` | `null` | Earliest selectable time (inclusive) |
+| `maxTime` | `max-time` | `string \| null` | `null` | Latest selectable time (inclusive) |
+| `disabled` | `disabled` | `boolean` | `false` | Disables all interaction |
+| `readonly` | `readonly` | `boolean` | `false` | Value shown, popover cannot open |
+| `required` | `required` | `boolean` | `false` | Renders `*` and sets `aria-required` |
+| `clearable` | `clearable` | `boolean` | `false` | Clear button when a value is set |
+| `open` | `open` | `boolean` | `false` | Controls / reflects popover state |
+| `error` | `error` | `boolean` | `false` | Error styling |
+| `invalid` | `invalid` | `boolean` | `false` | Alias for `error` |
+| `errorMessage` | `error-message` | `string` | — | Shown below when error/invalid |
+| `helperText` | `helper-text` | `string` | — | Assistive text below the field |
+| `name` | `name` | `string` | — | Form field name (hidden input) |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Trigger size |
+| `fullWidth` | `fullWidth` | `boolean` | `false` | Fill the parent width |
+| `variant` | `variant` | `"outlined"` | `"outlined"` | Visual style |
+
+## Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `rel-change` | `{ value: string \| null }` | Fired on Apply and on clear |
+| `rel-open-change` | `{ open: boolean }` | Popover opened/closed |
+| `rel-focus` | — | Trigger received focus |
+| `rel-blur` | — | Trigger lost focus |
+
+## CSS Parts
+
+| Part | Element |
+| --- | --- |
+| `base` | Outer wrapper |
+| `label` | Field label |
+| `trigger` | Trigger button |
+| `value` | Trigger value/placeholder text |
+| `icon` | Trailing clock icon |
+| `panel` | Popover panel |
+| `option` | Hour/minute/period entries |
+| `footer` | Now / Cancel / Apply row |
+| `helper` | Helper / error text |
+
+```css
+/* Example: widen the popover and restyle options */
+rel-time-picker::part(panel) {
+  box-shadow: var(--rel-shadows-shadow-400);
+}
+rel-time-picker::part(option) {
+  border-radius: var(--rel-border-radius-xs);
+}
+```
+
+## Design tokens
+
+Styling is fully token-driven: surfaces (`--rel-bg-surface`, `--rel-bg-surface-elevated`), borders (`--rel-border-default`, `--rel-border-strong`, `--rel-border-focus`, `--rel-border-danger`, `--rel-border-subtle`), text (`--rel-text-default`, `--rel-text-label`, `--rel-text-placeholder`, `--rel-text-danger`, `--rel-text-disabled`), selection (`--rel-action-brand-fill`, `--rel-action-brand-label-icons-primary`), spacing, radius, shadows and the `--rel-body-*` typography roles.