@fristil/designsystem 0.4.0 → 0.5.1

package/src/components/ramme/error-summary/fs-error-summary.ts

@@ -1,159 +1,101 @@
-import { html, LitElement } from "lit"
-
 export const FS_ERROR_SUMMARY_TAG = "fs-error-summary" as const
 
-export const ERROR_SUMMARY_CLASS = "fs-error-summary" as const
-export const ERROR_SUMMARY_TITLE_CLASS = "fs-error-summary__title" as const
-
 /**
- * Samler feilene i et skjema og sender brukeren til feltet som feilet.
+ * Sender brukeren fra en feil i oppsummeringen til feltet som feilet.
+ *
+ * Serveren skriver hele boksen med `fs.errorSummary()`: klassen, `role`,
+ * `tabindex`, overskriften og lista. Komponenten lager ingenting. Den gjorde
+ * det før, og da forsvant både klassen og overskriften ved første morfing i
+ * Datastar, uten å komme tilbake.
  *
- * Du skriver lista med feil selv, som lenker til id-en på hvert felt.
- * Komponenten gjør tre ting som er lette å glemme, og som avgjør om
- * oppsummeringen er til nytte:
+ * Det som er igjen er to ting nettleseren ikke gjør selv:
  *
- * 1. Flytter fokus til boksen når den kommer til syne, så den som hører siden
+ * 1. Fokus flyttes til boksen når den kommer til syne, så den som hører siden
  *    får vite at innsendingen stoppet.
- * 2. Gir fokus til selve kontrollen når en lenke følges. En vanlig ankerlenke
+ * 2. Fokus gis til selve kontrollen når en lenke følges. En vanlig ankerlenke
  *    ruller bare dit, og neste tastetrykk fortsetter der fokus sto før.
- * 3. Holder boksen skjult mens lista er tom, så en tom overskrift ikke blir
- *    stående i skjemaet.
  *
  * ```html
- * <fs-error-summary heading="Skjemaet har to feil">
+ * <fs-error-summary class="fs-error-summary" role="alert" tabindex="-1">
+ *   <h2 class="fs-error-summary__title">Skjemaet har to feil</h2>
  *   <ul class="fs-list">
  *     <li><a href="#epost">Skriv en gyldig e-postadresse</a></li>
  *   </ul>
  * </fs-error-summary>
  * ```
  */
-export class FsErrorSummary extends LitElement {
-  static properties = {
-    heading: { type: String },
-    autofocus: { type: Boolean, reflect: true },
-  }
-
-  /** Overskriften over lista. */
-  heading = "Skjemaet har feil"
-  /** Flytt fokus hit når boksen kommer til syne. Standard: på. */
-  autofocus = true
+export class FsErrorSummary extends HTMLElement {
+  static observedAttributes = ["autofocus", "hidden"]
 
   private hasFocused = false
-  /** Tittelen komponenten selv har laget, til forskjell fra konsumentens. */
-  private ownTitle?: HTMLElement
-
-  createRenderRoot() {
-    return this
-  }
-
-  render() {
-    return html`<slot @slotchange=${this.handleSlotChange}></slot>`
-  }
-
-  /**
-   * Ser etter at lista med feil endrer seg.
-   *
-   * Komponenten rendrer i vanlig DOM, og da melder ikke `slotchange` fra når
-   * konsumenten bytter ut innholdet. Feilene kommer og går mens brukeren
-   * fyller ut skjemaet, så endringen må observeres.
-   */
   private observer?: MutationObserver
-  private syncing = false
+  private readonly links = new Set<HTMLAnchorElement>()
 
-  connectedCallback() {
-    super.connectedCallback()
-    this.observer = new MutationObserver(() => {
-      if (!this.syncing) this.sync()
-    })
+  connectedCallback(): void {
+    // Feilene kommer og går mens brukeren retter, og `slotchange` melder ikke
+    // fra i vanlig DOM. Bare childList: komponenten setter ingen attributter
+    // på barna, så observatøren kan ikke utløse seg selv.
+    this.observer = new MutationObserver(() => this.sync())
     this.observer.observe(this, { childList: true, subtree: true })
+    this.sync()
   }
 
-  disconnectedCallback() {
+  attributeChangedCallback(): void {
+    // Serveren kan sende boksen skjult og senere bare ta bort `hidden` på
+    // den samme noden. Uten dette får en oppsummering som nettopp ble synlig
+    // aldri fokus, og det er hele grunnen til at komponenten finnes.
+    if (this.isConnected) this.sync()
+  }
+
+  disconnectedCallback(): void {
     this.observer?.disconnect()
     this.observer = undefined
-    super.disconnectedCallback()
+    for (const link of this.links) {
+      link.removeEventListener("click", this.handleLinkClick)
+    }
+    this.links.clear()
   }
 
-  firstUpdated() {
-    this.sync()
+  private get shouldFocus(): boolean {
+    const value = this.getAttribute("autofocus")
+    return value !== "false"
   }
 
-  updated() {
-    this.sync()
-  }
+  private sync(): void {
+    const links = [
+      ...this.querySelectorAll<HTMLAnchorElement>("li a[href^='#']"),
+    ]
 
-  private handleSlotChange = () => {
-    this.sync()
-  }
+    if (links.length === 0) {
+      this.hasFocused = false
+      return
+    }
 
-  private get items(): HTMLAnchorElement[] {
-    return [...this.querySelectorAll<HTMLAnchorElement>("li a[href^='#']")]
-  }
+    for (const link of links) {
+      if (this.links.has(link)) continue
+      link.addEventListener("click", this.handleLinkClick)
+      this.links.add(link)
+    }
 
-  private sync() {
-    if (this.syncing) return
-    this.syncing = true
-
-    try {
-      const links = this.items
-      const empty = links.length === 0
-
-      this.hidden = empty
-      if (empty) {
-        this.hasFocused = false
-        return
-      }
-
-      // Boksen er selve elementet. Vi flytter ikke konsumentens markup inn i
-      // et omslag: da ville Lit-delen vår og innholdet byttet plass i DOM-en.
-      this.classList.add(ERROR_SUMMARY_CLASS)
-      this.setAttribute("role", "alert")
-      this.tabIndex = -1
-
-      let title = this.querySelector<HTMLElement>(
-        `.${ERROR_SUMMARY_TITLE_CLASS}`,
-      )
-      if (!title) {
-        title = document.createElement("h2")
-        title.className = ERROR_SUMMARY_TITLE_CLASS
-        this.prepend(title)
-        this.ownTitle = title
-      }
-
-      // Overskriften følger `heading` så lenge det er vi som har laget den.
-      // Antallet feil endrer seg mens brukeren retter, og en overskrift som
-      // ble stående på det første tallet er verre enn ingen: den som hører
-      // siden får vite at det er to feil igjen når det er én.
-      // Har konsumenten skrevet tittelen selv, er den deres.
-      //
-      // Sammenligningen er ikke pynt: å skrive den samme teksten på nytt
-      // teller som en endring for MutationObserver, og da kaller den sync()
-      // igjen i det uendelige.
-      const skalSkrive = title === this.ownTitle || !title.textContent?.trim()
-      if (skalSkrive && title.textContent !== this.heading) {
-        title.textContent = this.heading
-      }
-
-      for (const link of links) {
-        link.removeEventListener("click", this.handleLinkClick)
-        link.addEventListener("click", this.handleLinkClick)
-      }
-
-      if (this.autofocus && !this.hasFocused) {
-        this.hasFocused = true
-        this.focus()
-      }
-    } finally {
-      this.syncing = false
+    // Boksen er skjult av serveren når lista er tom. Er den synlig nå, og vi
+    // ikke har flyttet fokus hit ennå, er det denne innsendingen som feilet.
+    if (this.shouldFocus && !this.hasFocused && !this.hidden) {
+      this.hasFocused = true
+      this.focus()
     }
   }
 
-  private handleLinkClick = (event: Event) => {
+  private handleLinkClick = (event: Event): void => {
     const link = event.currentTarget as HTMLAnchorElement
     const id = link.getAttribute("href")?.slice(1)
     if (!id) return
 
-    const target = document.getElementById(id)
+    // Oppslaget går mot rota komponenten selv står i, ikke mot `document`.
+    // Ligger skjemaet i en skyggerot, som i en forhåndsvisning eller inne i
+    // en annen komponent, finner `document.getElementById` ingenting, og
+    // lenken blir en vanlig ankerlenke uten fokusflytting.
+    const rot = this.getRootNode() as Document | ShadowRoot
+    const target = rot.getElementById?.(id) ?? document.getElementById(id)
     if (!target) return
 
     event.preventDefault()
@@ -161,7 +103,8 @@ export class FsErrorSummary extends LitElement {
     // Er lenken til en ledetekst, skal fokus til kontrollen den peker på.
     const control =
       target instanceof HTMLLabelElement && target.htmlFor
-        ? document.getElementById(target.htmlFor)
+        ? (rot.getElementById?.(target.htmlFor) ??
+          document.getElementById(target.htmlFor))
         : target
 
     const focusable = control ?? target

package/src/components/ramme/field/field-core.ts

@@ -130,3 +130,41 @@ export function computeFieldAttributes(
     state: invalid ? "invalid" : "default",
   }
 }
+
+/**
+ * Attributtene `<fs-field>` setter, per element den rører.
+ *
+ * Lista trengs bare når to ting gjelder samtidig.
+ *
+ * Lages markupen med JavaScript, skal den kalle `computeFieldAttributes` og
+ * skrive attributtene selv. Da trengs verken komponenten eller denne lista.
+ * Blir markupen til uten JavaScript, i en Go-mal eller håndskrevet HTML, gjør
+ * `<fs-field>` koblingen i nettleseren, og på en side serveren sender én gang
+ * er det alt som skal til.
+ *
+ * Oppdaterer serveren det samme området mens brukeren holder på, som i en
+ * Datastar- eller htmx-app, må malen i tillegg skrive lista som
+ * `data-preserve-attr` på hvert av de tre elementene. Morfingen leser den fra
+ * serverens node, per element, så komponenten kan ikke beskytte seg selv.
+ *
+ * Det holder ikke å beskytte kontrollen alene. Komponenten legger også
+ * `fs-label` og markeringene på ledeteksten, og skjuler feilmeldingen. Uten
+ * lister på de to andre forsvinner klassen og feilmeldingen ved neste
+ * morfing, som er nøyaktig den feilen kontrakten skal hindre.
+ *
+ * ```html
+ * <label class="fs-label" for="epost"
+ *        data-preserve-attr="class data-required data-optional aria-disabled">E-post</label>
+ * <input class="fs-input" id="epost"
+ *        data-preserve-attr="id aria-describedby aria-invalid data-state disabled aria-disabled">
+ * <p class="fs-error-text" hidden data-preserve-attr="hidden">Skriv en gyldig adresse.</p>
+ * ```
+ */
+export const FIELD_PRESERVED_ATTRIBUTES = {
+  /** På ledeteksten. */
+  label: "class data-required data-optional aria-disabled",
+  /** På selve kontrollen. */
+  control: "id aria-describedby aria-invalid data-state disabled aria-disabled",
+  /** På feilmeldingen. */
+  error: "hidden",
+} as const

package/src/components/ramme/field/fs-field.ts

@@ -1,5 +1,3 @@
-import { html, LitElement } from "lit"
-
 import { computeFieldAttributes } from "./field-core.js"
 
 export const FS_FIELD_TAG = "fs-field" as const
@@ -8,79 +6,175 @@ function uniqueId(prefix: string): string {
   return `${prefix}-${Math.random().toString(36).slice(2, 9)}`
 }
 
-export class FsField extends LitElement {
-  static properties = {
-    invalid: { type: Boolean, reflect: true },
-    disabled: { type: Boolean, reflect: true },
-    optional: { type: Boolean, reflect: true },
-    requiredMarker: { type: String, attribute: "required-marker" },
-    controlId: { type: String, attribute: "control-id" },
-    describedBy: { type: String, attribute: "described-by" },
+function setOrRemove(
+  element: HTMLElement,
+  name: string,
+  value: string | undefined,
+): void {
+  if (value === undefined) {
+    element.removeAttribute(name)
+  } else if (element.getAttribute(name) !== value) {
+    element.setAttribute(name, value)
   }
+}
 
-  invalid = false
-  disabled = false
-  optional = false
-  requiredMarker: "none" | "symbol" | "text" = "none"
-  controlId?: string
-  describedBy?: string
+/**
+ * Kobler ledetekst, kontroll, hjelpetekst og feilmelding i vanlig DOM.
+ *
+ * Komponenten er for markup som blir til uten JavaScript: en Go-mal, en
+ * PHP-fil, en Razor-visning eller håndskrevet HTML. Lages markupen med
+ * JavaScript, uansett hvor koden kjører, skal `fs.field()` skrive
+ * attributtene i stedet, og da trengs ikke dette elementet.
+ *
+ * Komponenten rendrer ingenting. Den satte tidligere et `<slot>`-element inn i
+ * vanlig DOM, og siden serveren ikke visste om det, fjernet Datastars morfing
+ * det ved hver patch. Se `FIELD_PRESERVED_ATTRIBUTES` for hva serveren må
+ * skrive for at koblingen skal overleve en morfing.
+ */
+export class FsField extends HTMLElement {
+  static observedAttributes = [
+    "invalid",
+    "disabled",
+    "optional",
+    "required-marker",
+    "control-id",
+    "described-by",
+  ]
+
+  private observer?: MutationObserver
+
+  /**
+   * Egenskapene speiler attributtene.
+   *
+   * Tilstanden bor i attributtet og ikke i et felt på klassen, slik at det
+   * serveren sendte og det komponenten mener alltid er det samme. En egen
+   * `invalid`-variabel ville kunne si noe annet enn markupen etter en morfing.
+   */
+  get invalid(): boolean {
+    return this.hasAttribute("invalid")
+  }
 
-  createRenderRoot() {
-    return this
+  set invalid(value: boolean) {
+    this.toggleAttribute("invalid", value)
   }
 
-  render() {
-    return html`<slot @slotchange=${this.handleSlotChange}></slot>`
+  get disabled(): boolean {
+    return this.hasAttribute("disabled")
   }
 
-  firstUpdated() {
-    this.syncA11y()
+  set disabled(value: boolean) {
+    this.toggleAttribute("disabled", value)
   }
 
-  updated() {
-    this.syncA11y()
+  get optional(): boolean {
+    return this.hasAttribute("optional")
   }
 
-  private handleSlotChange = () => {
-    this.syncA11y()
+  set optional(value: boolean) {
+    this.toggleAttribute("optional", value)
   }
 
-  private syncA11y() {
-    const label = this.querySelector("label") as HTMLLabelElement | null
-    const control = this.querySelector(
-      "input:not([type='hidden']), textarea, select",
-    ) as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null
-    const help = this.querySelector(
+  get requiredMarker(): "none" | "symbol" | "text" {
+    const value = this.getAttribute("required-marker")
+    return value === "symbol" || value === "text" ? value : "none"
+  }
+
+  set requiredMarker(value: "none" | "symbol" | "text") {
+    if (value === "none") this.removeAttribute("required-marker")
+    else this.setAttribute("required-marker", value)
+  }
+
+  get controlId(): string | undefined {
+    return this.getAttribute("control-id") ?? undefined
+  }
+
+  set controlId(value: string | undefined) {
+    if (value === undefined) this.removeAttribute("control-id")
+    else this.setAttribute("control-id", value)
+  }
+
+  get describedBy(): string | undefined {
+    return this.getAttribute("described-by") ?? undefined
+  }
+
+  set describedBy(value: string | undefined) {
+    if (value === undefined) this.removeAttribute("described-by")
+    else this.setAttribute("described-by", value)
+  }
+
+  connectedCallback(): void {
+    // `slotchange` melder ikke fra i vanlig DOM, og innholdet byttes ut mens
+    // brukeren fyller ut skjemaet. Bare childList: å sette et attributt på et
+    // barn utløser da ingen ny runde, så observatøren kan ikke gå i ring.
+    this.observer = new MutationObserver(() => this.sync())
+    this.observer.observe(this, { childList: true, subtree: true })
+    this.sync()
+  }
+
+  disconnectedCallback(): void {
+    this.observer?.disconnect()
+    this.observer = undefined
+  }
+
+  attributeChangedCallback(): void {
+    if (this.isConnected) this.sync()
+  }
+
+  private sync(): void {
+    const label = this.querySelector("label")
+    const control = this.querySelector<
+      HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+    >("input:not([type='hidden']), textarea, select")
+    const help = this.querySelector<HTMLElement>(
       ".fs-help-text, [data-role='help']",
-    ) as HTMLElement | null
-    const error = this.querySelector(
+    )
+    const error = this.querySelector<HTMLElement>(
       ".fs-error-text, [data-role='error']",
-    ) as HTMLElement | null
+    )
 
     if (!control) return
 
     if (help && !help.id) help.id = uniqueId("fs-field-help")
     if (error && !error.id) error.id = uniqueId("fs-field-error")
 
-    // Selve kontrakten regnes ut av den delte kjernen, som fs.field() også
-    // bruker. Denne komponenten gjør bare én ting utover det: å sette
-    // resultatet på elementer som allerede står i DOM-en.
+    // Markeringene leses også fra markupen. Skrev serveren dem med
+    // `fs.field()`, står de på ledeteksten, og en komponent som bare så på
+    // sine egne attributter ville fjernet dem igjen. I React ga det en
+    // hydreringsfeil: serveren sendte `data-required="symbol"`, komponenten
+    // tok det bort, og så mente React at HTML-en ikke stemte.
+    const marker =
+      this.getAttribute("required-marker") ??
+      label?.getAttribute("data-required") ??
+      null
+    const disabled =
+      this.hasAttribute("disabled") || control.hasAttribute("disabled")
+
+    // Tilstanden leses fra markupen, ikke bare fra et attributt på verten.
+    // Skrev serveren feltet med `fs.field()`, står svaret allerede på
+    // kontrollen, og en komponent som regnet ut sitt eget ville fjernet det
+    // igjen. Da kranglet de to halvdelene av API-et med hverandre.
+    const invalid =
+      this.hasAttribute("invalid") ||
+      control.getAttribute("aria-invalid") === "true"
+
     const computed = computeFieldAttributes({
-      id: this.controlId || control.id || uniqueId("fs-field-control"),
+      id:
+        this.getAttribute("control-id") ||
+        control.id ||
+        uniqueId("fs-field-control"),
       help: Boolean(help),
       error: Boolean(error),
       helpId: help?.id,
       errorId: error?.id,
-      required:
-        this.requiredMarker === "symbol" || this.requiredMarker === "text"
-          ? this.requiredMarker
-          : undefined,
-      optional: this.optional,
-      invalid: this.invalid,
-      disabled: this.disabled,
+      required: marker === "symbol" || marker === "text" ? marker : undefined,
+      optional:
+        this.hasAttribute("optional") ||
+        label?.hasAttribute("data-optional") === true,
+      invalid,
+      disabled,
       describedBy: [
         control.getAttribute("aria-describedby") ?? "",
-        this.describedBy ?? "",
+        this.getAttribute("described-by") ?? "",
       ].filter(Boolean),
     })
 
@@ -95,8 +189,10 @@ export class FsField extends LitElement {
     }
 
     if (error) {
+      // Bare `hidden`. Et skjult element er allerede ute av
+      // tilgjengelighetstreet, så `aria-hidden` var overflødig, og ga en
+      // hydreringsfeil i React fordi serveren ikke skriver det.
       error.hidden = Boolean(computed.error.hidden)
-      error.setAttribute("aria-hidden", String(Boolean(computed.error.hidden)))
     }
 
     setOrRemove(
@@ -106,7 +202,7 @@ export class FsField extends LitElement {
     )
     setOrRemove(control, "aria-invalid", computed.control["aria-invalid"])
 
-    if (this.disabled) {
+    if (disabled) {
       control.setAttribute("disabled", "")
       control.setAttribute("aria-disabled", "true")
     } else {
@@ -129,18 +225,6 @@ export class FsField extends LitElement {
   }
 }
 
-function setOrRemove(
-  element: HTMLElement,
-  name: string,
-  value: string | undefined,
-) {
-  if (value === undefined) {
-    element.removeAttribute(name)
-  } else {
-    element.setAttribute(name, value)
-  }
-}
-
 declare global {
   interface HTMLElementTagNameMap {
     "fs-field": FsField