@orange-halo/components 2.2.0 → 3.0.0

package/dist/oh-input.js

@@ -1,27 +1,33 @@
 /**
  * oh-input
  *
- * A chunky, inset input field that feels pressed into the page.
- * On focus, it rises to meet you.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. CHUNKY & CONFIDENT
- *    - Thick border (stroke.control) that feels illustrative
- *    - Solid fill, no subtle gradients
- *    - shape.control corners (matches button)
- *
- * 2. INSET SHADOW (PRESSED IN)
- *    - Shadow offset to top-left (inset)
- *    - Feels pressed into the surface
- *    - Opposite of button's outset sticker effect
+ * 1. LOOK FROM TOKENS
+ *    - Border: input.base.borderWidth (stroke.control) in color.border.emphasis
+ *    - Corners: shape.control (same as oh-button)
+ *    - Shadow: an inset shadow offset by elevation.offset.md in elevation.color.field
  *
- * 3. FOCUS THICKENS
- *    - An inset ring in focus.ringColor thickens the border inward
+ * 2. FOCUS IS A SOLID RING
+ *    - An inset ring in focus.ringColor inside the border, so focus doesn't
+ *      shift the layout
  *    - Background switches to color.surface.highlight
- *    - Clear visual hierarchy
  *
- * @element oh-input
+ * 3. A REAL FORM CONTROL
+ *    - Form-associated, like oh-textarea: its value submits with the form
+ *      under its name and shows in form.elements, `required` blocks
+ *      submission, a form reset restores the starting value, and a
+ *      disabled <fieldset> disables it
+ *
+ * 4. SUGGESTIONS ARE NATIVE
+ *    - `suggestions` renders a <datalist> inside the component (a list
+ *      outside it can't reach an input in the shadow root). The browser
+ *      draws the list and handles the keyboard and screen readers, so
+ *      people can still type anything: it suggests, it doesn't restrict
+ *
+ * 5. ERRORS BEFORE THE FIELD
+ *    - Error text sits after the label and before the field, with an icon,
+ *      so it's read before the field is reached. Helper text sits after
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -32,21 +38,91 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property, query, state } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A single-line text field that submits with a native form, with optional
+ * typing suggestions.
+ *
+ * **Use it for** short free text: names, email addresses, search terms.
+ * **Don't use it for** several lines (use `oh-textarea`) or a choice from a
+ * fixed list (use `oh-select`, or `oh-radio-group` for a few options).
+ * `suggestions` offers values while still allowing any text.
+ *
+ * **Types:** `text` (default), `email`, `password`, `search`, `tel`, `url`.
+ * One size. **States:** rest, hover, focus, error (set `error-text`),
+ * disabled, required.
+ *
+ * **Behaviour:** form-associated: the value submits under `name`, `required`
+ * blocks submission (validity comes from the inner `<input>`), a form reset
+ * restores the starting value, and a disabled `<fieldset>` disables it.
+ * Fires `oh-input` as the text changes and `oh-change` when it's committed.
+ * `suggestions` renders a native `<datalist>`, so the browser handles its
+ * keyboard and screen reader support. `autocomplete` is passed to the inner
+ * `<input>`.
+ *
+ * **Accessibility:** always set `label`: it's the field's name. The error
+ * shows after the label and before the field, with an icon, and is linked
+ * with `aria-describedby` and `aria-invalid`; it's announced (`role="alert"`)
+ * only when it appears after first render. Helper text is linked the same
+ * way (it's hidden while an error shows). Focus is a solid inset ring.
+ * Set `autocomplete` for personal data (WCAG 1.3.5).
+ *
+ * **Look:** set by tokens — `input.base.borderWidth` (`stroke.control`) in
+ * `color.border.emphasis` (border), `shape.control` (corners),
+ * `typography.control.*` (type), `input.size.md.minHeight` (height),
+ * `elevation.offset.md` and `elevation.color.field` (inset shadow),
+ * `color.border.hover` (hover), `focus.ringColor` and
+ * `color.surface.highlight` (focus), `color.feedback.error`,
+ * `color.feedback.errorSubtle` and `elevation.color.error` (error),
+ * `color.surface.disabled`, `color.border.disabled` and
+ * `color.text.disabled` (disabled).
+ *
+ * @element oh-input
+ * @fires oh-input - Whenever the text changes: typing, or picking a suggestion. detail: { value, originalEvent }
+ * @fires oh-change - When the value is committed (on blur or Enter). detail: { value, originalEvent }
+ * @csspart label - The visible label
+ * @csspart input - The text field
+ * @csspart helper - The helper text, and the error message (which also has the error part)
+ * @csspart error - The error message
+ */
 let OhInput = class OhInput extends OhElement {
     constructor() {
         super(...arguments);
+        /** The kind of text: text, email, password, search, tel or url */
         this.type = "text";
+        /** The text in the field */
         this.value = "";
+        /** Example text shown while the field is empty. Not a replacement for the label */
         this.placeholder = "";
+        /** The visible label. Always set one: it names the field */
         this.label = "";
+        /** Help shown under the field and linked to it */
         this.helperText = "";
+        /** Error shown before the field and linked to it. Setting it puts the field in its error state */
         this.errorText = "";
+        /** The name the value is submitted under */
+        this.name = "";
+        /** Must be filled in before the form submits */
         this.required = false;
+        /** Not editable, and left out of the form's data */
+        this.disabled = false;
+        /**
+         * Values offered while typing, shown by the browser as a list under the
+         * field. They suggest, they don't restrict: any text is still allowed.
+         * Set it as a property (an array of strings) or, in HTML, as a JSON array:
+         * suggestions='["Option one","Option two"]'. Browsers also offer the
+         * field's autofill history, so set autocomplete="off" to show only these.
+         */
+        this.suggestions = [];
         /**
          * Force a visual state (for documentation/Figma sync only)
          * Values: 'hover' | 'focus'
          */
         this.forceState = "default";
+        this._internals = this.attachInternals();
+        /** The starting value, restored when the form resets */
+        this._defaultValue = "";
+        /** Set when a disabled <fieldset> around it disables it */
+        this._formDisabled = false;
         /**
          * Errors that appear after first render (e.g. on submit) are announced via
          * role="alert". Errors present on page load are only linked with
@@ -54,14 +130,10 @@ let OhInput = class OhInput extends OhElement {
          */
         this._announceError = false;
     }
+    static { this.formAssociated = true; }
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO INPUT
-         Chunky • Inset • Rises on Focus
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: block;
       }
@@ -72,7 +144,7 @@ let OhInput = class OhInput extends OhElement {
         gap: var(--oh-spacing-2);
       }
 
-      /* ─── Label: friendly and readable (16px minimum) ─── */
+      /* ─── Label: typography.control.* ─── */
       .label {
         font-family: var(--oh-typography-control-font-family);
         font-size: var(--oh-typography-control-font-size-sm);
@@ -88,7 +160,7 @@ let OhInput = class OhInput extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          INPUT FIELD
-         Thick border, inset shadow, solid fill
+         Border, inset shadow and fill from tokens
          ═══════════════════════════════════════════════════════════════ */
 
       .input {
@@ -96,17 +168,18 @@ let OhInput = class OhInput extends OhElement {
         font-family: var(--oh-typography-control-font-family);
         color: var(--oh-color-text-primary);
 
-        /* Solid fill — no gradients */
+        /* Fill: color.surface.base */
         background-color: var(--oh-color-surface-base);
 
-        /* Thick illustrative border (WCAG 3:1 compliant) */
+        /* Border: input.base.borderWidth in color.border.emphasis (a UI
+           contrast pair checked by check:contrast) */
         border: var(--oh-input-base-border-width) solid
           var(--oh-color-border-emphasis);
         border-radius: var(--oh-shape-control);
 
-        /* Inset offset shadow: pressed into page */
+        /* Inset shadow: elevation.offset.md in elevation.color.field */
         box-shadow: inset var(--oh-elevation-offset-md)
-          var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-field);
+          var(--oh-elevation-offset-md) 0 0 var(--oh-elevation-color-field);
 
         transition:
           border-color var(--oh-motion-snappy) ease,
@@ -118,8 +191,8 @@ let OhInput = class OhInput extends OhElement {
         color: var(--oh-color-text-secondary); /* Readable placeholder */
       }
 
-      /* ─── Hover: border warms up ─── */
-      .input:hover:not(:focus) {
+      /* ─── Hover: border in color.border.hover ─── */
+      .input:hover:not(:focus):not(:disabled) {
         border-color: var(--oh-color-border-hover);
       }
 
@@ -145,14 +218,14 @@ let OhInput = class OhInput extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          ERROR STATE
-         Warm red, chunky — still follows the same language
+         color.feedback.error border, errorSubtle fill, elevation.color.error
          ═══════════════════════════════════════════════════════════════ */
 
       .input--error {
         border-color: var(--oh-color-feedback-error);
         background-color: var(--oh-color-feedback-error-subtle);
         box-shadow: inset var(--oh-elevation-offset-md)
-          var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-error);
+          var(--oh-elevation-offset-md) 0 0 var(--oh-elevation-color-error);
       }
 
       .input--error:focus {
@@ -164,9 +237,23 @@ let OhInput = class OhInput extends OhElement {
          HELPER TEXT
          ═══════════════════════════════════════════════════════════════ */
 
+      /* ─── Disabled: color.*.disabled tokens, no shadow ─── */
+      .input:disabled {
+        cursor: not-allowed;
+        color: var(--oh-color-text-disabled);
+        background-color: var(--oh-color-surface-disabled);
+        border-color: var(--oh-color-border-disabled);
+        box-shadow: none;
+      }
+
+      .label--disabled {
+        color: var(--oh-color-text-disabled);
+      }
+
       .helper {
         font-family: var(--oh-typography-body-font-family);
         font-size: var(--oh-typography-body-base-font-size);
+        line-height: var(--oh-typography-body-base-line-height);
         color: var(--oh-color-text-secondary);
         letter-spacing: var(--oh-typography-control-letter-spacing);
       }
@@ -222,28 +309,57 @@ let OhInput = class OhInput extends OhElement {
       }
     `,
     ]; }
-    _handleInput(event) {
-        const target = event.target;
-        this.value = target.value;
-        this.emit("oh-input", { value: this.value, originalEvent: event });
+    connectedCallback() {
+        super.connectedCallback();
+        if (!this.hasUpdated)
+            this._defaultValue = this.value;
     }
-    _handleChange(event) {
-        this.emit("oh-change", { value: this.value, originalEvent: event });
+    /** The form this field belongs to */
+    get form() {
+        return this._internals.form;
     }
-    focus() {
-        this._input?.focus();
+    focus(options) {
+        this._input?.focus(options);
     }
     blur() {
         this._input?.blur();
     }
+    formResetCallback() {
+        this.value = this._defaultValue;
+    }
+    formDisabledCallback(disabled) {
+        this._formDisabled = disabled;
+    }
+    formStateRestoreCallback(state) {
+        if (typeof state === "string")
+            this.value = state;
+    }
     willUpdate(changed) {
         if (this.hasUpdated && changed.has("errorText")) {
             this._announceError = !!this.errorText;
         }
     }
+    updated(changed) {
+        if (changed.has("value"))
+            this._internals.setFormValue(this.value);
+        if (changed.has("value") ||
+            changed.has("required") ||
+            changed.has("type")) {
+            this._internals.setValidity(this._input.validity, this._input.validationMessage, this._input);
+        }
+    }
+    _handleInput(event) {
+        this.value = event.target.value;
+        this.emit("oh-input", { value: this.value, originalEvent: event });
+    }
+    _handleChange(event) {
+        this.emit("oh-change", { value: this.value, originalEvent: event });
+    }
     render() {
         const hasError = !!this.errorText;
-        const helperContent = hasError ? this.errorText : this.helperText;
+        const disabled = this.disabled || this._formDisabled;
+        const describedBy = hasError ? "error" : this.helperText ? "helper" : "";
+        const suggestions = this.suggestions ?? [];
         const inputClasses = this.classMap({
             input: true,
             "input--error": hasError,
@@ -253,7 +369,11 @@ let OhInput = class OhInput extends OhElement {
         ${this.label
             ? html `
               <label
-                class="label ${this.required ? "label--required" : ""}"
+                class=${this.classMap({
+                label: true,
+                "label--required": this.required,
+                "label--disabled": disabled,
+            })}
                 part="label"
                 for="input"
               >
@@ -261,28 +381,12 @@ let OhInput = class OhInput extends OhElement {
               </label>
             `
             : nothing}
-
-        <input
-          id="input"
-          part="input"
-          class=${inputClasses}
-          type=${this.type}
-          .value=${this.value}
-          placeholder=${this.placeholder || nothing}
-          autocomplete=${this.autocomplete || nothing}
-          ?required=${this.required}
-          aria-invalid=${hasError ? "true" : nothing}
-          aria-describedby=${helperContent ? "helper" : nothing}
-          @input=${this._handleInput}
-          @change=${this._handleChange}
-        />
-
         ${hasError
             ? html `
               <span
-                id="helper"
+                id="error"
                 class="helper helper--error"
-                part="helper"
+                part="helper error"
                 role=${this._announceError ? "alert" : nothing}
               >
                 <svg
@@ -300,11 +404,34 @@ let OhInput = class OhInput extends OhElement {
                 ${this.errorText}
               </span>
             `
-            : this.helperText
-                ? html `<span id="helper" class="helper" part="helper"
-                >${this.helperText}</span
-              >`
-                : nothing}
+            : nothing}
+
+        <input
+          id="input"
+          part="input"
+          class=${inputClasses}
+          type=${this.type}
+          .value=${this.value}
+          placeholder=${this.placeholder || nothing}
+          autocomplete=${this.autocomplete || nothing}
+          list=${suggestions.length ? "suggestions" : nothing}
+          ?required=${this.required}
+          ?disabled=${disabled}
+          aria-invalid=${hasError ? "true" : nothing}
+          aria-describedby=${describedBy || nothing}
+          @input=${this._handleInput}
+          @change=${this._handleChange}
+        />
+        ${suggestions.length
+            ? html `<datalist id="suggestions">
+              ${suggestions.map((s) => html `<option value=${s}></option>`)}
+            </datalist>`
+            : nothing}
+        ${this.helperText && !hasError
+            ? html `<span id="helper" class="helper" part="helper"
+              >${this.helperText}</span
+            >`
+            : nothing}
       </div>
     `;
     }
@@ -322,14 +449,23 @@ __decorate([
     property({ type: String })
 ], OhInput.prototype, "label", void 0);
 __decorate([
-    property({ type: String })
+    property({ type: String, attribute: "helper-text" })
 ], OhInput.prototype, "helperText", void 0);
 __decorate([
-    property({ type: String })
+    property({ type: String, attribute: "error-text" })
 ], OhInput.prototype, "errorText", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], OhInput.prototype, "name", void 0);
 __decorate([
     property({ type: Boolean, reflect: true })
 ], OhInput.prototype, "required", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], OhInput.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Array })
+], OhInput.prototype, "suggestions", void 0);
 __decorate([
     property({ type: String })
 ], OhInput.prototype, "autocomplete", void 0);
@@ -339,6 +475,9 @@ __decorate([
 __decorate([
     query("input")
 ], OhInput.prototype, "_input", void 0);
+__decorate([
+    state()
+], OhInput.prototype, "_formDisabled", void 0);
 __decorate([
     state()
 ], OhInput.prototype, "_announceError", void 0);

package/dist/oh-input.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-input.js","sourceRoot":"","sources":["../src/oh-input.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oh-input.js","sourceRoot":"","sources":["../src/oh-input.ts"],"names":[],"mappings":"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"}

package/dist/oh-link.d.ts

@@ -1,32 +1,55 @@
 /**
  * oh-link
  *
- * A warm, playful link with retro-inspired styling.
- * Two variants: inline (for body text) and standalone (for CTAs).
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. INLINE VARIANT
- *    - Dotted underline (quirky, retro feel)
- *    - Becomes solid on hover
- *    - Warm brand orange
- *    - Subtle but distinctive
+ * 1. Two variants: `inline` for links inside body text, `standalone` for
+ *    links that stand on their own (CTAs, "View all").
+ * 2. The underline is a pseudo-element so it can transition. Its shape comes
+ *    from the `decoration.underline*` tokens; it retracts on hover.
+ * 3. Keyboard focus swaps in a solid underline (`color.brand.primary`,
+ *    `decoration.underlineFocusThickness`) as the indicator; the
+ *    `focus.glowColor` tint behind it is decoration only.
+ * 4. Links are never colour-only: the underline is visible at rest.
+ * 5. `target="_blank"` adds an icon, a visually hidden "(opens in new tab)"
+ *    and `rel="noopener noreferrer"` (unless `rel` is set).
+ */
+import { OhElement } from "./base.js";
+export type LinkVariant = "inline" | "standalone";
+/**
+ * A text link, for use inside body copy or on its own as a call to action.
  *
- * 2. STANDALONE VARIANT
- *    - Bolder presence for CTAs
- *    - Offset shadow on hover (mini sticker effect)
- *    - Lift animation like other components
- *    - Arrow icon option
+ * **Use it for** navigating to another page or place. **Don't use it for**
+ * actions that don't navigate (use `oh-button` instead).
  *
- * 3. ACCESSIBILITY
- *    - Underline always visible (not color-only)
- *    - Clear focus state
- *    - Proper contrast ratios
+ * **Variants:** `inline` (default) sits in running text; `standalone` is
+ * larger and bolder for links on their own, and can show a trailing arrow
+ * (`arrow`). `inverse` is for links on accent surfaces.
+ *
+ * **Behaviour:** renders a native `<a>`, so Enter follows it and it takes
+ * focus in tab order. On hover the underline retracts and the arrow nudges
+ * forward. Keyboard focus (`:focus-visible`) shows a solid underline and a
+ * tint; mouse focus doesn't. Transitions are cut short under
+ * `prefers-reduced-motion`. With `target="_blank"` it adds an external icon,
+ * screen-reader text "(opens in new tab)" and `rel="noopener noreferrer"`
+ * when `rel` isn't set; the arrow is not shown on external links.
+ *
+ * **Accessibility:** the underline shows at rest and on focus, so links
+ * don't rely on colour. Write link text that makes sense out of context.
+ *
+ * **Look:** set by tokens — `color.text.link` the colour (`color.text.onAccent`
+ * when `inverse`); `decoration.underlineThickness`, `decoration.underlineDash`
+ * and `decoration.underlinePeriod` the underline; `color.brand.primary`
+ * (`color.text.onAccent` when `inverse`) and
+ * `decoration.underlineFocusThickness` the focus underline; `focus.glowColor`
+ * (`link.inverse.focusBackground` when `inverse`) the focus tint;
+ * `typography.body.fontFamily`, plus `typography.body.lg.fontSize` and
+ * `typography.emphasis.fontWeight` for `standalone`; `motion.slow` and
+ * `motion.snappy` the transitions.
  *
  * @element oh-link
+ * @slot - The link text.
  */
-import { OhElement } from "./base.js";
-export type LinkVariant = "inline" | "standalone";
 export declare class OhLink extends OhElement {
     static styles: import("lit").CSSResult[];
     href: string;

package/dist/oh-link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-link.d.ts","sourceRoot":"","sources":["../src/oh-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD,qBACa,MAAO,SAAQ,SAAS;IACnC,OAAgB,MAAM,4BAuSpB;IAGF,IAAI,SAAM;IAGV,MAAM,SAAM;IAGZ,GAAG,SAAM;IAGT,OAAO,EAAE,WAAW,CAAY;IAGhC,KAAK,UAAS;IAGd,OAAO,UAAS;IAEhB,MAAM;CAyDP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB;CACF"}
+{"version":3,"file":"oh-link.d.ts","sourceRoot":"","sources":["../src/oh-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,MAAO,SAAQ,SAAS;IACnC,OAAgB,MAAM,4BAkSpB;IAGF,IAAI,SAAM;IAGV,MAAM,SAAM;IAGZ,GAAG,SAAM;IAGT,OAAO,EAAE,WAAW,CAAY;IAGhC,KAAK,UAAS;IAGd,OAAO,UAAS;IAEhB,MAAM;CAyDP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB;CACF"}

package/dist/oh-link.js

@@ -1,29 +1,18 @@
 /**
  * oh-link
  *
- * A warm, playful link with retro-inspired styling.
- * Two variants: inline (for body text) and standalone (for CTAs).
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. INLINE VARIANT
- *    - Dotted underline (quirky, retro feel)
- *    - Becomes solid on hover
- *    - Warm brand orange
- *    - Subtle but distinctive
- *
- * 2. STANDALONE VARIANT
- *    - Bolder presence for CTAs
- *    - Offset shadow on hover (mini sticker effect)
- *    - Lift animation like other components
- *    - Arrow icon option
- *
- * 3. ACCESSIBILITY
- *    - Underline always visible (not color-only)
- *    - Clear focus state
- *    - Proper contrast ratios
- *
- * @element oh-link
+ * 1. Two variants: `inline` for links inside body text, `standalone` for
+ *    links that stand on their own (CTAs, "View all").
+ * 2. The underline is a pseudo-element so it can transition. Its shape comes
+ *    from the `decoration.underline*` tokens; it retracts on hover.
+ * 3. Keyboard focus swaps in a solid underline (`color.brand.primary`,
+ *    `decoration.underlineFocusThickness`) as the indicator; the
+ *    `focus.glowColor` tint behind it is decoration only.
+ * 4. Links are never colour-only: the underline is visible at rest.
+ * 5. `target="_blank"` adds an icon, a visually hidden "(opens in new tab)"
+ *    and `rel="noopener noreferrer"` (unless `rel` is set).
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -34,6 +23,40 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A text link, for use inside body copy or on its own as a call to action.
+ *
+ * **Use it for** navigating to another page or place. **Don't use it for**
+ * actions that don't navigate (use `oh-button` instead).
+ *
+ * **Variants:** `inline` (default) sits in running text; `standalone` is
+ * larger and bolder for links on their own, and can show a trailing arrow
+ * (`arrow`). `inverse` is for links on accent surfaces.
+ *
+ * **Behaviour:** renders a native `<a>`, so Enter follows it and it takes
+ * focus in tab order. On hover the underline retracts and the arrow nudges
+ * forward. Keyboard focus (`:focus-visible`) shows a solid underline and a
+ * tint; mouse focus doesn't. Transitions are cut short under
+ * `prefers-reduced-motion`. With `target="_blank"` it adds an external icon,
+ * screen-reader text "(opens in new tab)" and `rel="noopener noreferrer"`
+ * when `rel` isn't set; the arrow is not shown on external links.
+ *
+ * **Accessibility:** the underline shows at rest and on focus, so links
+ * don't rely on colour. Write link text that makes sense out of context.
+ *
+ * **Look:** set by tokens — `color.text.link` the colour (`color.text.onAccent`
+ * when `inverse`); `decoration.underlineThickness`, `decoration.underlineDash`
+ * and `decoration.underlinePeriod` the underline; `color.brand.primary`
+ * (`color.text.onAccent` when `inverse`) and
+ * `decoration.underlineFocusThickness` the focus underline; `focus.glowColor`
+ * (`link.inverse.focusBackground` when `inverse`) the focus tint;
+ * `typography.body.fontFamily`, plus `typography.body.lg.fontSize` and
+ * `typography.emphasis.fontWeight` for `standalone`; `motion.slow` and
+ * `motion.snappy` the transitions.
+ *
+ * @element oh-link
+ * @slot - The link text.
+ */
 let OhLink = class OhLink extends OhElement {
     constructor() {
         super(...arguments);
@@ -47,11 +70,6 @@ let OhLink = class OhLink extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO LINK
-         Warm • Playful • Retro-inspired
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: inline;
       }
@@ -74,7 +92,7 @@ let OhLink = class OhLink extends OhElement {
         text-decoration: none;
       }
 
-      /* Dashed underline via pseudo-element (animatable) */
+      /* Underline via pseudo-element (animatable), shaped by decoration tokens */
       .link__text::after {
         content: "";
         position: absolute;
@@ -96,7 +114,7 @@ let OhLink = class OhLink extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          INLINE VARIANT
-         Dashed underline shrinks right-to-left on hover
+         Underline shrinks right-to-left on hover
          ═══════════════════════════════════════════════════════════════ */
 
       .link--inline {
@@ -148,7 +166,7 @@ let OhLink = class OhLink extends OhElement {
 
       /* ═══════════════════════════════════════════════════════════════
          STANDALONE VARIANT
-         CTA-style with hover lift, dashed underline shrinks on hover
+         CTA-style; underline shrinks on hover
          ═══════════════════════════════════════════════════════════════ */
 
       .link--standalone {