HTML — カスタム要素

4.13.1.1. 自律的~custom要素の作成-法

`自律的~custom要素$の作成-法を例で~~説明するため、 ここでは，小さな国旗~icon（ `flag-icon^e ）の描画を~capsule化する~custom要素を定義してみる。 目標は、 次の様な利用を可能にすることである： ◎ For the purposes of illustrating how to create an autonomous custom element, let's define a custom element that encapsulates rendering a small icon for a country flag. Our goal is to be able to use it like so:

<flag-icon country="nl"></flag-icon>

これを行うため、 先ず，~custom要素~用に `HTMLElement$I を拡張する~classを宣言する： ◎ To do this, we first declare a class for the custom element, extending HTMLElement:

class FlagIcon extends HTMLElement {
  constructor() {
    super();
    this._countryCode = null;
  }

  static observedAttributes = ["country"];

  attributeChangedCallback(%name, %oldValue, %newValue) {
    /* 
%name は常に， `observedAttributes^c が返す結果のどれか（ここでは `country^l のみ）
◎
name will always be "country" due to observedAttributes
 */
    this._countryCode = %newValue;
    this._updateRendering();
  }
  connectedCallback() {
    this._updateRendering();
  }

  get country() {
    return this._countryCode;
  }
  set country(%v) {
    this.setAttribute("country", %v);
  }

  _updateRendering() {
/* 
読者への宿題として残しておく。
が，おそらく、
`this.ownerDocument.defaultView^m で挿入-先の文書が`属する閲覧~文脈$の有無を検査して，
無いなら何もしないことが求まれるであろう。
◎
Left as an exercise for the reader. But, you'll probably want to check this.ownerDocument.defaultView to see if we've been inserted into a document with a browsing context, and avoid doing any work if not.
 */
  }
}

次に，この~classを利用して要素を定義する必要がある： ◎ We then need to use this class to define the element:

`customElements$m.define("flag-icon", FlagIcon);

この時点で、 上の~codeは働くことになる。 構文解析器は、 `flag-icon^e ~tagに出会う度に，［ `FlagIcon^jc ~classの新たな~instanceを構築して， その新たな `country^c 属性について上の~codeに伝えてくる ］ことになる — ~codeは、 それを利用して当の要素の内部~状態を設定し， （適切なときは）要素の描画も更新する。 ◎ At this point, our above code will work! The parser, whenever it sees the flag-icon tag, will construct a new instance of our FlagIcon class, and tell our code about its new country attribute, which we then use to set the element's internal state and update its rendering (when appropriate).

`flag-icon^e 要素を ~DOM~APIを利用して作成することもできる： ◎ You can also create flag-icon elements using the DOM API:

const %flagIcon = document.createElement("flag-icon")
%flagIcon.country = "jp"
document.body.appendChild(%flagIcon)

最後に、 `~custom要素~構築子$自身を利用することもできる。 すなわち、 上の~codeは次に等価になる： ◎ Finally, we can also use the custom element constructor itself. That is, the above code is equivalent to:

const %flagIcon = new FlagIcon()
%flagIcon.country = "jp"
document.body.appendChild(%flagIcon)

4.13.1.2. ~formに所有され得る~custom要素の作成-法

`自律的~custom要素$は、［ ~T 値を返す静的な `formAssociated^c ~prop ］を追加すれば，`~formに所有され得る~custom要素$になる。 `ElementInternals$I ~interfaceは、 作者が~form~control要素に共通な各種［ 関数, ~prop ］を実装し易くする。 ◎ Adding a static formAssociated property, with a true value, makes an autonomous custom element a form-associated custom element. The ElementInternals interface helps you to implement functions and properties common to form control elements.

class MyCheckbox extends HTMLElement {
  static formAssociated = true;
  static observedAttributes = ['checked'];

  constructor() {
    super();
    this._internals = this.attachInternals();
    this.addEventListener('click', this._onClick.bind(this));
  }

  get form() { return this._internals.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }

  get checked() { return this.hasAttribute('checked'); }
  set checked(%flag) { this.toggleAttribute('checked', Boolean(%flag)); }

  attributeChangedCallback(%name, %oldValue, %newValue) {
    /* 
%name は常に， `observedAttributes^c が返す結果のどれか（ここでは `checked^l のみ）
◎
name will always be "checked" due to observedAttributes
 */
    this._internals.setFormValue(this.checked ? 'on' : null);
  }

  _onClick(%event) {
    this.checked = !this.checked;
  }
}
`customElements$m.define('my-checkbox', MyCheckbox);

作者は、 組込みの`~formに所有され得る要素$の様に， ~custom要素 `my-checkbox^e を利用できる。 例えば、 `my-checkbox^e 要素を `form$e 内に置けば それに所有され， `label$e 内に置けば その~label先~controlになり、 `form$e が提出されるときには， `my-checkbox^e の実装が供する~dataが送信されるようになる。 ◎ You can use the custom element my-checkbox like a built-in form-associated element. For example, putting it in form or label associates the my-checkbox element with them, and submitting the form will send data provided by my-checkbox implementation.

<form action="..." method="...">
  <label><my-checkbox name="agreed"></my-checkbox> I read the agreement.</label>
  <input type="submit">
</form>

4.13.1.3. 既定の~access可能な~role, 状態, ~propを伴う~custom要素の作成-法

`ElementInternals$I の適切な~propを利用すれば、 ~custom要素は，既定の~accessibility意味論を備えれる。 次の~codeは、 前~節の~formに所有され得る~checkboxを拡げて，その既定の［ ~role／~check有無 ］を — ~accessibility技術から見て適正に — 設定する： ◎ By using the appropriate properties of ElementInternals, your custom element can have default accessibility semantics. The following code expands our form-associated checkbox from the previous section to properly set its default role and checkedness, as viewed by accessibility technology:

class MyCheckbox extends HTMLElement {
  static formAssociated = true;
  static observedAttributes = ['checked'];

  constructor() {
    super();
    this._internals = this.attachInternals();
    this.addEventListener('click', this._onClick.bind(this));

    this._internals.role = 'checkbox';
    this._internals.ariaChecked = 'false';
  }

  get form() { return this._internals.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }

  get checked() { return this.hasAttribute('checked'); }
  set checked(%flag) { this.toggleAttribute('checked', Boolean(%flag)); }

  attributeChangedCallback(%name, %oldValue, %newValue) {
    /* 
%name は常に， `observedAttributes^c が返す結果のどれか（ここでは `checked^l のみ）
◎
name will always be "checked" due to observedAttributes
 */
    this._internals.setFormValue(this.checked ? 'on' : null);
    this._internals.ariaChecked = this.checked;
  }

  _onClick(%event) {
    this.checked = !this.checked;
  }
}
customElements.define('my-checkbox', MyCheckbox);

組込みの要素と同様に、 これらは既定でしかないことに注意 — ~page作者は、［ `role$a 属性, 各種 `aria-*$a 属性 ］を利用して，それを上書きできる： ◎ Note that, like for built-in elements, these are only defaults, and can be overridden by the page author using the role and aria-* attributes:

<!-- 
この~markupは不適合
◎
This markup is non-conforming
 -->
<input type="checkbox" checked role="button" aria-checked="false">

<!-- 
この~markupは、
おそらく，~custom要素の作者が意図したものではない
◎
This markup is probably not what the custom element author intended
 -->
<my-checkbox role="button" checked aria-checked="false">

~custom要素の作者は、 当の要素の~accessibility意味論のどの側面が，強い~native意味論を有するか — すなわち，~custom要素の利用者は上書きするべきでないか — を言明することが奨励される。 上の例では， `my-checkbox^e 要素の作者は、 その［ `~role$, `aria-checked$a 値 ］は強い~native意味論を有するものと言明することになろう — したがって，上のような~codeは忌避される。 ◎ Custom element authors are encouraged to state what aspects of their accessibility semantics are strong native semantics, i.e., should not be overridden by users of the custom element. In our example, the author of the my-checkbox element would state that its role and aria-checked values are strong native semantics, thus discouraging code such as the above.

4.13.1.4. ~custom化された組込みの要素の作成-法

`~custom化された組込みの要素$は、 別種の`~custom要素$であり，その定義は少しばかり異なる。 また、 その利用は，`自律的~custom要素$に比較してかなり異なる。 それが存在するのは、 新たな~custom機能性で拡張することにより，［ 既存の~HTML要素の挙動 ］の再利用を許容するためである。 この再利用は重要になる — あいにく，~HTML要素の既存の挙動の多くは、 純粋に`自律的~custom要素$だけでは~~再現できないので。 代わりに，`~custom化された組込みの要素$では、［ 構築~時に~customな挙動を~installすること, 【！＊】~lifecycle~hook, 既存の要素への~prototype~chain ］が許容され、 本質的に，これらの能力を既存の要素の上層に “mix-in” する。 ◎ Customized built-in elements are a distinct kind of custom element, which are defined slightly differently and used very differently compared to autonomous custom elements. They exist to allow reuse of behaviors from the existing elements of HTML, by extending those elements with new custom functionality. This is important since many of the existing behaviors of HTML elements can unfortunately not be duplicated by using purely autonomous custom elements. Instead, customized built-in elements allow the installation of custom construction behavior, lifecycle hooks, and prototype chain onto existing elements, essentially "mixing in" these capabilities on top of the already-existing element.

`~custom化された組込みの要素$には、 `自律的~custom要素$とは別個な構文が要求される — ~UAや他の~softwareは、 当の要素の［ 意味論, 挙動 ］を要素の局所~名で識別しているので。 すなわち、［ 既存の挙動の上層に，`~custom化された組込みの要素$の概念を築く ］ためには，［ 拡張元の要素が自身の元の局所~名を維持する ］ことが不可欠になる。 ◎ Customized built-in elements require a distinct syntax from autonomous custom elements because user agents and other software key off an element's local name in order to identify the element's semantics and behavior. That is, the concept of customized built-in elements building on top of existing behavior depends crucially on the extended elements retaining their original local name.

次の例では、［ `plastic-button^e と命名された`~custom化された組込みの要素$ ］を作成する。 それは，通常の~buttonの様に挙動するが、 ~click時には気の利いた~animation効果が追加される。 前と同様，~classを定義する所から始めるが、 今度は， `HTMLElement$I でなく `HTMLButtonElement$I を拡張する： ◎ In this example, we'll be creating a customized built-in element named plastic-button, which behaves like a normal button but gets fancy animation effects added whenever you click on it. We start by defining a class, just like before, although this time we extend HTMLButtonElement instead of HTMLElement:

class PlasticButton extends HTMLButtonElement {
  constructor() {
    super();

    this.addEventListener("click", () => {
      /* 
何か気の利いた~animation効果を描く
◎
Draw some fancy animation effects!
 */
    });
  }
}

上のような~custom要素を定義するときには、 `extends$m ~optionも指定する必要がある： ◎ When defining our custom element, we have to also specify the extends option:

`customElements$m.define("plastic-button", PlasticButton, { extends: "button" });

一般に，どの名前の要素を拡張しているかは、 どの要素~interfaceを拡張しているか見るだけでは決定できない。 多くの要素は、 同じ~interfaceを共有しているので （例： `q$e と `blockquote$e は `HTMLQuoteElement$I を共有している）。 ◎ In general, the name of the element being extended cannot be determined simply by looking at what element interface it extends, as many elements share the same interface (such as q and blockquote both sharing HTMLQuoteElement).

構文解析される~HTML~source~textから`~custom化された組込みの要素$を構築するためには、 `is$a 属性を利用する — ここでは， `button$e 要素~上で： ◎ To construct our customized built-in element from parsed HTML source text, we use the is attribute on a button element:

<button `is$a="plastic-button">Click Me!</button>

`~custom化された組込みの要素$を`自律的~custom要素$として利用しようと試行しても、 `働かない^em。 すなわち、 `<plastic-button>Click me?</plastic-button>^s は、 単純に［ 特別な挙動を何も伴わない `HTMLElement$I ］を作成することになる。 ◎ Trying to use a customized built-in element as an autonomous custom element will not work; that is, <plastic-button>Click me?</plastic-button> will simply create an HTMLElement with no special behavior.

~custom化された組込みの要素を~program的に作成する必要がある場合、 次の形による `createElement()$m を利用できる： ◎ If you need to create a customized built-in element programmatically, you can use the following form of createElement():

const %plasticButton = document.createElement("button", { is: "plastic-button" });
%plasticButton.textContent = "Click me!";

構築子は、 前と同様に働くことになる： ◎ And as before, the constructor will also work:

const %plasticButton2 = new PlasticButton();
console.log(%plasticButton2.localName);  /* 
`button^l と出力される
◎
will output "button"
 */
console.assert(%plasticButton2 instanceof PlasticButton);
console.assert(%plasticButton2 instanceof HTMLButtonElement);

~custom化された組込みの要素を~program的に作成した場合、 `is$a 属性は，明示的に設定されてないので~DOM内には無い — しかしながら、 `直列化-時には出力に追加される＠~HTMLwriting#attr-is-during-serialization$： ◎ Note that when creating a customized built-in element programmatically, the is attribute will not be present in the DOM, since it was not explicitly set. However, it will be added to the output when serializing:

console.assert(!%plasticButton.hasAttribute("is"));
console.log(%plasticButton.outerHTML); /* 
`<button is="plastic-button"></button>^l
と出力される
◎
will output '<button is="plastic-button"></button>'
 */

それがどう作成されたかに関わらず， `button$e に備わる特別なふるまい — ~focus時の挙動, `~form提出$に関与する能, `disabled$a 属性, 等々 — すべては、この種の “plastic ~button” にも適用される。 ◎ Regardless of how it is created, all of the ways in which button is special apply to such "plastic buttons" as well: their focus behavior, ability to participate in form submission, the disabled attribute, and so on.

`~custom化された組込みの要素$は、 既存の~HTML要素を［ ~UAが給する有用な挙動や~APIが備わる ］よう拡張できるように設計されている。 そのようなわけで、 拡張できるのは［ この仕様に定義される既存の~HTML要素 ］に限られ、 次に挙げる旧来の要素 — `要素~interface$として `HTMLUnknownElement$I を利用するものと定義された要素 — は拡張できない ⇒ `applet$eO†, `bgsound$eO, `blink$eO, `isindex$eO, `keygen$eO, `multicol$eO, `nextid$eO, `spacer$eO ◎ Customized built-in elements are designed to allow extension of existing HTML elements that have useful user-agent supplied behavior or APIs. As such, they can only extend existing HTML elements defined in this specification, and cannot extend legacy elements such as bgsound, blink, isindex, keygen, multicol, nextid, or spacer that have been defined to use HTMLUnknownElement as their element interface.

【† `applet^eO は、この訳による補完。 】

この要件がある理由には、 将来との互換性もある： 仮に，`~custom化された組込みの要素$が現在は未知な要素 — 例えば `combobox^e とする — を拡張するように定義された場合、 そのように派生された要素の消費者たちは，［ その基底である `combobox^e 要素は，~UAが給する挙動に関わらないこと ］に依存することになり、 この仕様が将来に `combobox^e 要素を定義できなくなる。 ◎ One reason for this requirement is future-compatibility: if a customized built-in element was defined that extended a currently-unknown element, for example combobox, this would prevent this specification from defining a combobox element in the future, as consumers of the derived customized built-in element would have come to depend on their base element having no interesting user-agent-supplied behavior.

4.13.1.5. 自律的~custom要素の欠点

下に指定されるように，および上で~~示唆したように、 単純に `taco-button^e と称される要素を定義した上で利用しても， その種の要素が~buttonを`表現-$することにはならない。 すなわち、［ ~web~browser, 探索~engine, ~accessibility技術 ］などの~toolは、 結果の要素を，単に［ 定義された名前に基づいて自動的に~buttonとして扱う ］わけではない。 ◎ As specified below, and alluded to above, simply defining and using an element called taco-button does not mean that such elements represent buttons. That is, tools such as web browsers, search engines, or accessibility technology will not automatically treat the resulting element as a button just based on its defined name.

`自律的~custom要素$を利用しつつ，［ 様々な利用者から欲される，~buttonの意味論 ］を伝達するためには、 いくつかの技法を使役する必要がある： ◎ To convey the desired button semantics to a variety of users, while still using an autonomous custom element, a number of techniques would need to be employed:

• `tabindex$a 属性を追加すれば、 `taco-button^e 要素は`~focus可能$になる。 この場合、 `taco-button^e が論理的に不能化されたときには， `tabindex$a 属性も除去する必要があることに注意。 ◎ The addition of the tabindex attribute would make the taco-button focusable. Note that if the taco-button were to become logically disabled, the tabindex attribute would need to be removed.
• ~ARIA~role, および各種~ARIA［ 状態／~prop ］を追加すれば、 意味論を~accessibility技術に伝達する一助になる。 例えば，`~role$を `button$l に設定すれば、［ “要素は~buttonである” という意味論を伝達する ］ことになり，利用者が［ ~accessibility技術の下で、 通例の~buttonの様に，当の~controlとヤリトリすること ］を可能化する。 また， `aria-label$a ~propを設定して、 当の~buttonに`~access可能な名前$を与えることも必要yである — さもなければ，~accessibility技術は、 子~text~nodeたちを辿って，それらを発声することになる。 また，~buttonが論理的に不能化されたときには、 `aria-disabled$a 状態を `true^l に設定すれば， その不能化d状態は~accessibility技術へ伝達される。 ◎ The addition of an ARIA role and various ARIA states and properties helps convey semantics to accessibility technology. For example, setting the role to "button" will convey the semantics that this is a button, enabling users to successfully interact with the control using usual button-like interactions in their accessibility technology. Setting the aria-label property is necessary to give the button an accessible name, instead of having accessibility technology traverse its child text nodes and announce them. And setting the aria-disabled state to "true" when the button is logically disabled conveys to accessibility technology the button's disabled state.
• ~buttonに共通的に期待される挙動を取扱うために~event~handlerを追加することも、 ~web~browser利用者に~buttonの意味論を伝達する一助になる。 この事例で最も関連な~event~handlerは、適切な `keydown$et ~eventを代理して， `click$et ~event化するものになるであろう — そうすれば、~keyboardでも~clickでも，~buttonを作動化できるようになるので。 ◎ The addition of event handlers to handle commonly-expected button behaviors helps convey the semantics of the button to web browser users. In this case, the most relevant event handler would be one that proxies appropriate keydown events to become click events, so that you can activate the button both with keyboard and by clicking.
• 既定で供される視覚的な~style付けの他に、 `taco-button^e 要素は，［ 不能化されるなどの，論理的な状態~変化 ］を反映するときにも更新される必要がある。 すなわち、 `taco-button^e 用の~stylesheet規則が何であれ， `taco-button[disabled]^css 用の規則も必要になる。 ◎ In addition to any default visual styling provided for taco-button elements, the visual styling will also need to be updated to reflect changes in logical state, such as becoming disabled; that is, whatever style sheet has rules for taco-button will also need to have rules for taco-button[disabled].

これらの点を念頭に、［ ~button意味論を伝達する責務を担う，全装備な `taco-button^e ］（不能化される能も含む）は，次の様な見かけの何かになろう： ◎ With these points in mind, a full-featured taco-button that took on the responsibility of conveying button semantics (including the ability to be disabled) might look something like this:

class TacoButton extends HTMLElement {
  static observedAttributes = ["disabled"];

  constructor() {
    super();
    this._internals = this.attachInternals();
    this._internals.role = "button";

    this.addEventListener("keydown", %e => {
      if (%e.code === "Enter" || %e.code === "Space") {
        this.dispatchEvent(new PointerEvent("click", {
          bubbles: true,
          cancelable: true
        }));
      }
    });

    this.addEventListener("click", %e => {
      if (this.disabled) {
        %e.preventDefault();
        %e.stopImmediatePropagation();
      }
    });

    this._observer = new MutationObserver(() => {
      this._internals.ariaLabel = this.textContent;
    });
  }

  connectedCallback() {
    this.setAttribute("tabindex", "0");

    this._observer.observe(this, {
      childList: true,
      characterData: true,
      subtree: true
    });
  }

  disconnectedCallback() {
    this._observer.disconnect();
  }

  get disabled() {
    return this.hasAttribute("disabled");
  }
  set disabled(%flag) {
    this.toggleAttribute("disabled", Boolean(%flag));
  }

  attributeChangedCallback(%name, %oldValue, %newValue) {
/* 
%name は常に， `observedAttributes^c が返す結果のどれか（ここでは `disabled^l のみ）
◎
name will always be "disabled" due to observedAttributes
 */
    if (this.disabled) {
      this.removeAttribute("tabindex");
      this._internals.ariaDisabled = "true";
    } else {
      this.setAttribute("tabindex", "0");
      this._internals.ariaDisabled = "false";
    }
  }
}

このそれなりに複雑な要素~定義をもってしても、 要素は，消費者にとって利用するのは楽でない： それは、 そいつの意志で `tabindex$a を “不断に生やし続ける” ことになり、 それが選んだ `tabindex="0"^c に対する~focus能の挙動は， 現在の~platformにおける~buttonの挙動に合致しないこともあろう。 このことは、 今の所~custom要素に対しては，既定の［ ~focus時の挙動 ］を指定する仕方がなく、 そうするためには， `tabindex$a 属性の利用を強いられるからである （それは，通例的には、消費者が既定の挙動を上書きするために予約されているが）。 ◎ Even with this rather-complicated element definition, the element is not a pleasure to use for consumers: it will be continually "sprouting" tabindex attributes of its own volition, and its choice of tabindex="0" focusability behavior may not match the button behavior on the current platform. This is because as of now there is no way to specify default focus behavior for custom elements, forcing the use of the tabindex attribute to do so (even though it is usually reserved for allowing the consumer to override default behavior).

対照的に，前~節に示した単純な`~custom化された組込みの要素$は、 `button$e 要素の［ 意味論, 挙動 ］を自動的に継承することになるので， これらの挙動を手動で実装する必要はない。 一般に、［ 自明でない［ 意味論, 挙動 ］を伴う，~HTMLの既存の要素 ］の上層に築かれる どの要素についても、 `~custom化された組込みの要素$の方が［ 開発する／保守する／消費する ］のは容易になる。 ◎ In contrast, a simple customized built-in element, as shown in the previous section, would automatically inherit the semantics and behavior of the button element, with no need to implement these behaviors manually. In general, for any elements with nontrivial behavior and semantics that build on top of existing elements of HTML, customized built-in elements will be easier to develop, maintain, and consume.

4.13.1.6. 要素の作成~後の昇格~法

`要素~定義$は，いつでも生じさせ得る — ~customでない要素が`作成-$された後，適切な`~custom要素~定義$を登録した後に、 それを`~custom要素$にすることもできる。 この処理nは、 通常の要素から~custom要素への “昇格ng” と呼ばれる。 ◎ Because element definition can occur at any time, a non-custom element could be created, and then later become a custom element after an appropriate definition is registered. We call this process "upgrading" the element, from a normal element into a custom element.

`~custom要素~定義$を登録するのは、 それに関連な要素が初期~時に — 構文解析器などにより — 作成された後の方が，好ましいこともある。 `昇格$は、 そのような~~用法を可能化して，［ ~custom要素の内容を漸進的に増強する ］ことを許容する。 例えば、 次の~HTML文書と `img-viewer^e 用の要素~定義は， 非同期的に読込まれる： ◎ Upgrades enable scenarios where it may be preferable for custom element definitions to be registered after relevant elements have been initially created, such as by the parser. They allow progressive enhancement of the content in the custom element. For example, in the following HTML document the element definition for img-viewer is loaded asynchronously:

<!DOCTYPE html>
<html lang="ja">
<title>画像~viewerの例</title>

<img-viewer filter="Kelvin">
  <img src="images/tree.jpg" alt="何もないサバンナにそびえる美しい木">
</img-viewer>

<script src="js/elements/img-viewer.js" async></script>

ここでの `img-viewer^e 要素~用の定義は、［ ~markup内の `<img-viewer>^s ~tagの後に置かれた， `async$a 属性を有する `script$e 要素 ］を利用して読込まれる。 ~scriptを読込んでいる間、 `img-viewer^e 要素は，［ `span$e に類似な，未定義な要素 ］として扱われることになる。 ~scriptが読込まれ，それが `img-viewer^e 要素を定義したとき、 ~page上の既存の `img-viewer^e 要素は，［ その~custom要素~定義が適用され，昇格される ］ことになる （それは、 文字列 `Kelvin^l で識別される画像~filterを適用して， 画像の視覚的な外観を増強することが~~想定されている）。 ◎ The definition for the img-viewer element here is loaded using a script element marked with the async attribute, placed after the <img-viewer> tag in the markup. While the script is loading, the img-viewer element will be treated as an undefined element, similar to a span. Once the script loads, it will define the img-viewer element, and the existing img-viewer element on the page will be upgraded, applying the custom element's definition (which presumably includes applying an image filter identified by the string "Kelvin", enhancing the image's visual appearance).

【 `img-viewer^e の名前には~hyphenがあるので、 将来も含めて，~scriptが読込まれる前に特別な意味を持つ要素に解釈される心配はない （`妥当な~custom要素~名$を見よ）。 】

`昇格$が適用されるのは、 文書~tree内にある（正式には，`接続されて$いる）要素に限られることに注意。 文書に挿入されていない要素は、 昇格されないままになる。 この点について，例で~~説明すると： ◎ Note that upgrades only apply to elements in the document tree. (Formally, elements that are connected.) An element that is not inserted into a document will stay un-upgraded. An example illustrates this point:

<!DOCTYPE html>
<html lang="en">
<title>昇格の際どい事例</title>

<example-element></example-element>

<script>
  "use strict";

  const %文書内 = document.querySelector("example-element");
  const %文書外 = document.createElement("example-element");

  /* 
要素~定義の前：
両者とも `HTMLElement^I ：
◎
Before the element definition, both are HTMLElement:
 */
  console.assert(%文書内 instanceof HTMLElement);
  console.assert(%文書外 instanceof HTMLElement);

  class ExampleElement extends HTMLElement {}
  `customElements$m.define("example-element", ExampleElement);

  /* 
要素~定義の後：
文書~内に在った方の要素は、
この時点で昇格-済み：
◎
After element definition, the in-document element was upgraded:
 */
  console.assert(%文書内 instanceof ExampleElement);
  console.assert(!(%文書外 instanceof ExampleElement));

  document.body.appendChild(%文書外);

  /* 
そうでない方の要素を文書の中に移動した後には、
それも昇格される：
◎
Now that we've moved the element into the document, it too was upgraded:
 */
  console.assert(%文書外 instanceof ExampleElement);
</script>

4.13.2. ~custom要素の構築子と反応に課される要件

`~custom要素~構築子$を著作する際には、 作者には，次の適合性~要件が課される： ◎ When authoring custom element constructors, authors are bound by the following conformance requirements:

• 正しい~prototype~chain および this 値を確立するため、 他のすべての~codeが走る前に — 構築子の本体~内の最初の~statementで — `super()^c が~parameterなしで~callされなければナラナイ。 ◎ A parameter-less call to super() must be the first statement in the constructor body, to establish the correct prototype chain and this value before any further code is run.
• `return^c ~statementは、 単純な早期 return （ `return^c ／ `return this^c ）でない限り， 構築子の本体に現れてはナラナイ。 ◎ A return statement must not appear anywhere inside the constructor body, unless it is a simple early-return (return or return this).
• 構築子は、［ `document.write()$m ／ `document.open()$m ］~methodを利用してはナラナイ。 ◎ The constructor must not use the document.write() or document.open() methods.
• 要素の どの［ 属性／子 ］であれ，検分されてはナラナイ — `昇格$がない場合には何も無く、 昇格に依拠することは，要素を利用し難いものにするので。 【？】 ◎ The element's attributes and children must not be inspected, as in the non-upgrade case none will be present, and relying on upgrades makes the element less usable.
• どの［ 属性／子 ］であれ，要素に持たせてはナラナイ — それは、［ `createElement()$m ／ `createElementNS()$m ］~methodを用いる消費者の期待に違反するので。 ◎ The element must not gain any attributes or children, as this violates the expectations of consumers who use the createElement or createElementNS methods.
• 一般に、 アリな限り，仕事は — とりわけ，資源の~fetchingや具現化を孕むものは — `connectedCallback()^c へ先送りされるべきである。 しかしながら， `connectedCallback()^c は複数回~callされ得ることに注意 — 初期化を行うような~~真に一度限りの仕事は、 重ねて走らないよう，防護する必要がある。 ◎ In general, work should be deferred to connectedCallback as much as possible—especially work involving fetching resources or rendering. However, note that connectedCallback can be called more than once, so any initialization work that is truly one-time will need a guard to prevent it from running twice.
• 一般に，構築子は、［ 初期~状態や既定の値，あるいは~event~listener，場合によっては`~shadow根$ ］を設定しておくために利用されるべきである。 ◎ In general, the constructor should be used to set up initial state and default values, and to set up event listeners and possibly a shadow root.

これらの要件のうちいくつかは、 `要素を作成する$間に［ 直接的／間接的 ］に検査される。 要件に従わない場合、 ~custom要素は，構文解析器や~DOM~APIにより~instance化できなくなる。 このことは、 構築子から起動される小taskの内側で行われる仕事にも該当する — `小task~checkpoint$が生じ得るのは、 構築の直後からなので。 ◎ Several of these requirements are checked during element creation, either directly or indirectly, and failing to follow them will result in a custom element that cannot be instantiated by the parser or DOM APIs. This is true even if the work is done inside a constructor-initiated microtask, as a microtask checkpoint can occur immediately after construction.

`~custom要素~反応$を著作するときには、 作者は~node~treeを操作するのを避けるベキである — それは、 予期されない結果を導き得るので。 ◎ When authoring custom element reactions, authors should avoid manipulating the node tree as this can lead to unexpected results.

class CParent extends HTMLElement {
  connectedCallback() {
    this.firstChild.remove();
  }
}
customElements.define("c-parent", CParent);

class CChild extends HTMLElement {
  connectedCallback() {
    console.log("CChild connectedCallback: isConnected =", this.isConnected);
  }
}
customElements.define("c-child", CChild);

const %parent = new CParent(),
      %child = new CChild();
parent.append(%child);
document.body.append(%parent);

// Logs:
// CChild connectedCallback: isConnected = false

4.13.7.1. `ElementInternals^I ~interface

`ElementInternals$I ~interface用の~IDLは、 以下の各節にて定義される様々な演算, 属性を伴う： ◎ The IDL for the ElementInternals interface is as follows, with the various operations and attributes defined in the following sections:

[Exposed=Window]
interface `ElementInternals@I {

  /* 
`§ ~shadow根への~access＠#shadow-root-access$
◎
Shadow root access
 */
  readonly attribute `ShadowRoot$I? `shadowRoot$eI;

  /* 
`§ ~formに所有され得る~custom要素＠#form-associated-custom-elements$
◎
Form-associated custom elements
 */

  undefined `setFormValue$eI(
      (`File$I or `USVString$ or `FormData$I)? %value,
      optional (`File$I or `USVString$ or `FormData$I)? %state
  );

  readonly attribute `HTMLFormElement$I? `form$eI;

  undefined `setValidity$eI(
      optional `ValidityStateFlags$I %flags = {},
      optional DOMString %message,
      optional `HTMLElement$I %anchor
  );
  readonly attribute boolean `willValidate$eI;
  readonly attribute `ValidityState$I `validity$eI;
  readonly attribute DOMString `validationMessage$eI;
  boolean `checkValidity$eI();
  boolean `reportValidity$eI();

  /* 
`~custom状態~疑似類＠#custom-state-pseudo-class$
◎
Custom state pseudo-class
 */
  [SameObject] readonly attribute `CustomStateSet$I `states$eI;

  readonly attribute `NodeList$I `labels$eI;
};

/* 
`§ ~accessibility意味論＠#accessibility-semantics$
◎
Accessibility semantics
 */
`ElementInternals$I includes `ARIAMixin$I;

dictionary `ValidityStateFlags@I {
  boolean valueMissing = false;
  boolean typeMismatch = false;
  boolean patternMismatch = false;
  boolean tooLong = false;
  boolean tooShort = false;
  boolean rangeUnderflow = false;
  boolean rangeOverflow = false;
  boolean stepMismatch = false;
  boolean badInput = false;
  boolean customError = false;
};

各 `ElementInternals$I は、 ある`~custom要素$を指す `~target要素@iN を有する。 ◎ Each ElementInternals has a target element, which is a custom element.

4.13.7.2. ~shadow根への~access

%internals.`shadowRoot$eI

%internals の`~target要素$iNは［ `~shadow~host$であるならば，それ用の `ShadowRoot$I ／ ~ELSE_ ~NULL ］を返す。 ◎ Returns the ShadowRoot for internals's target element, if the target element is a shadow host, or null otherwise.

4.13.7.3. ~formに所有され得る~custom要素

%internals.`setFormValue(value)$eI

%internals の`~target要素$iNの［ `状態$cF, `提出~値$cF ］とも %value に設定する。 ◎ Sets both the state and submission value of internals's target element to value.

%value ~EQ ~NULL の場合、 要素は~form提出に関与しなくなる。 ◎ If value is null, the element won't participate in form submission.

%internals.`setFormValue(value, state)$eI

%internals の`~target要素$iNの［ `提出~値$cF／`状態$cF ］を［ %value ／ %state ］に設定する。 ◎ Sets the submission value of internals's target element to value, and its state to state.

%value ~EQ ~NULL の場合、 要素は~form提出に関与しなくなる。 ◎ If value is null, the element won't participate in form submission.

%internals.`form$eI

%internals の`~target要素$iNの`~form所有者$を返す。 ◎ Returns the form owner of internals's target element.

%internals.`setValidity(flags, message [, anchor ])$eI

［ %internals の`~target要素$iNは、 %flags 引数が指示する拘束に関して難ありである ］ものと~markした上で、 要素の検証~messageを %message に設定する。 ◎ Marks internals's target element as suffering from the constraints indicated by the flags argument, and sets the element's validation message to message.＼

%anchor も指定された場合、 ~UAは，［ `~form所有者$は対話的に検証された ／ `reportValidity()$eI が~callされた ］とき［ %internals の`~target要素$iNの拘束についての問題を指示する ］ために，それを利用するかもしれない。 ◎ If anchor is specified, the user agent might use it to indicate problems with the constraints of internals's target element when the form owner is validated interactively or reportValidity() is called.

%internals.`setValidity({})$eI

［ %internals の`~target要素$iNは、 `自身の拘束を満たして$いる ］ものと~markする。 ◎ Marks internals's target element as satisfying its constraints.

%internals.`willValidate$eI

~formが提出されるとき，%internals の`~target要素$iNは［ 検証されることになるならば ~T ／ ~ELSE_ ~F ］を返す。 ◎ Returns true if internals's target element will be validated when the form is submitted; false otherwise.

%internals.`validity$eI

%internals の`~target要素$iN用の `ValidityState$I ~objを返す。 ◎ Returns the ValidityState object for internals's target element.

%internals.`validationMessage$eI

［ %internals の`~target要素$iNの妥当性が検査されたとき，利用者に示される ］ことになる，~error~messageを返す。 ◎ Returns the error message that would be shown to the user if internals's target element was to be checked for validity.

%valid = %internals.`checkValidity()$eI

%internals の`~target要素$iNに妥当性の問題は［ ないならば ~T ／ あるならば ~F ］を返す。 ~F を返す場合、 要素に向けて `invalid$et ~eventを発火する。 ◎ Returns true if internals's target element has no validity problems; false otherwise. Fires an invalid event at the element in the latter case.

%valid = %internals.`reportValidity()$eI

%internals の`~target要素$iNに妥当性の問題は［ ないならば ~T ／ あるならば ~F ］を返す。 ~F を返す場合、 要素に向けて `invalid$et ~eventを発火することに加え， （~eventが取消されなければ）利用者に問題を報告する。 ◎ Returns true if internals's target element has no validity problems; otherwise, returns false, fires an invalid event at the element, and (if the event isn't canceled) reports the problem to the user.

%internals.`labels$eI

［ %internals の`~target要素$iNを~label先とする `label$e 要素 ］すべてからなる `NodeList$I を返す。 ◎ Returns a NodeList of all the label elements that internals's target element is associated with.

各`~formに所有され得る~custom要素$は、 次に挙げるものを有する： ◎ ↓

• `提出~値@cF ⇒ ~form提出~用に 1 個~以上の`~entry$fDを供するために利用される。 次に挙げる いずれかの値をとり，初期~時は ~NULL とする ⇒＃ ~NULL ／ 文字列 ／ `File$I ~obj ／ `~entry~list$【！`~entry$fDが成す`~list$】 ◎ Each form-associated custom element has submission value. It is used to provide one or more entries on form submission. The initial value of submission value is null, and submission value can be null, a string, a File, or a list of entries.
• `状態@cF ⇒ この要素~用に，~UAが利用者の入力を復旧できる情報。 `提出~値$cFと同じ範囲の値をとり，初期~時は ~NULL とする。 ◎ Each form-associated custom element has state. It is information with which the user agent can restore a user's input for the element. The initial value of state is null, and state can be null, a string, a File, or a list of entries.

~custom要素の作者は、 `setFormValue()$eI ~methodを利用して，要素の［ `提出~値$cF, `状態$cF ］を設定できる — それらは~UAに通信される。 ◎ The setFormValue() method is used by the custom element author to set the element's submission value and state, thus communicating these to the user agent.

`~formに所有され得る~custom要素$ %要素 に対しては，~UAは： ◎ ↓

• %要素 の`状態$cFを復旧することが良案になると予見するときには — 例えば，`~naviの後＠~HTMLnav#restore-persisted-state$や再起動~後に — 次をしてもヨイ ⇒ `~custom要素~callback反応を~enqueueする$( %要素, `formStateRestoreCallback^l, « 復旧されることになる状態, `restore^l » ) ◎ When the user agent believes it is a good idea to restore a form-associated custom element's state, for example after navigation or restarting the user agent, they may enqueue a custom element callback reaction with that element, callback name "formStateRestoreCallback", an argument list containing the state to be restored, and "restore".
• ~formを埋めるための支援-特能を備えていて，当の特能が呼出されたときは、 次をしてもヨイ ⇒ `~custom要素~callback反応を~enqueueする$( %要素, `formStateRestoreCallback^l, « ［ 状態~値の履歴, 何らかの経験則 ］により決定される状態~値, `autocomplete^l » ) ◎ If the user agent has a form-filling assist feature, then when the feature is invoked, it may enqueue a custom element callback reaction with a form-associated custom element, callback name "formStateRestoreCallback", an argument list containing the state value determined by history of state value and some heuristics, and "autocomplete".

一般に、 `状態$cFは［ 利用者により指定された情報 ］であり，`提出~値$cFは［ ~serverへの提出~用に相応しくなるよう，正準-化や無毒化を施した後の値 ］である。 具体的には： ◎ In general, the state is information specified by a user, and the submission value is a value after canonicalization or sanitization, suitable for submission to the server. The following examples makes this concrete:

`~formに所有され得る~custom要素$が在って，日付を指定するよう利用者に依頼するとする。 利用者は "3/15/2019" と指定したが，~controlは `2019-03-15^l を~serverへ提出したいと望む場合、 要素の ⇒＃ `状態$cFは "3/15/2019" になる／ `提出~値$cFは `2019-03-15^l になる ◎ Suppose that we have a form-associated custom element which asks a user to specify a date. The user specifies "3/15/2019", but the control wishes to submit "2019-03-15" to the server. "3/15/2019" would be a state of the element, and "2019-03-15" would be a submission value.

各`~formに所有され得る~custom要素$は、 次に挙げるものを有する： ◎ ↓

• `妥当性~flag群@cF ⇒ `ValidityStateFlags$I と同じ構造の~map。 すなわち、 その各~memberと同じ名前の~keyたちを伴う。 各~keyに対応する値は、 どれも初期~時は ~F とする†。 ◎ Each form-associated custom element has validity flags named valueMissing, typeMismatch, patternMismatch, tooLong, tooShort, rangeUnderflow, rangeOverflow, stepMismatch, and customError. They are false initially.

  【 原文では，これら各~memberと同じ名前の~flagを列挙している （加えて `badInput^m も抜けている）が、 総称し易くするため，この訳ではこの用語に代えることにする。 】【† 値 ~T は、 （各~keyの名前が示唆するとおり，） 当の~keyに対応する`妥当性~状態$に “難あり” を意味する。 】

• `検証~message@cF ⇒ 文字列 — 初期~時は空~文字列とする。 ◎ Each form-associated custom element has a validation message string. It is the empty string initially.
• `検証~anchor@cF ⇒ 要素／ ~NULL — 初期~時は ~NULL とする。 【拘束を`対話的に検証-$するときに利用される。】 ◎ Each form-associated custom element has a validation anchor element. It is null initially.

4.13.7.4. ~accessibility意味論

%internals.`role^eI [ = %value ]

%internals の`~target要素$iN用の既定の~ARIA~roleを［ 設定する／検索取得する ］ — それは、 ~page作者が `role$a 属性を利用して上書きしない限り， 利用されることになる。 ◎ Sets or retrieves the default ARIA role for internals's target element, which will be used unless the page author overrides it using the role attribute.

%internals.`aria*^eI [ = %value ]

%internals の`~target要素$iN用の 各種~ARIA［ 状態／~prop ］の既定の値を［ 設定する／検索取得する ］（順不同） — それは、 各種 `aria-*$a 属性を利用して上書きしない限り， 利用されることになる。 ◎ Sets or retrieves various default ARIA states or property values for internals's target element, which will be used unless the page author overrides them using the aria-* attributes.

各`~custom要素$は、 `内部~内容~属性~map@ を有する — それは、 `~map$であり，初期~時は空とする。 これが ~platform~accessibility~APIにどう影響iするかの情報は、 `§ ~ARIA, および~platform~accessibility~APIに関係する要件＠~HTMLdom#wai-aria$ を見よ。 ◎ Each custom element has an internal content attribute map, which is a map, initially empty. See the Requirements related to ARIA and to platform accessibility APIs section for information on how this impacts platform accessibility APIs.

4.13.7.5. ~custom状態~疑似類

%internals.`states$eI.add(%value)

文字列 %value を当の要素の`状態~集合$に追加する — それは、 `state()$ps 疑似類を通して公開されることになる。 ◎ Adds the string value to the element's states set to be exposed as a pseudo-class.

%internals.`states$eI.has(%value)

%value は当の要素の`状態~集合$内に［ 在るならば ~T ／ 無いならば ~F ］を返す。 ◎ Returns true if value is in the element's states set, otherwise false.

%internals.`states$eI.delete(%value)

%value は当の要素の`状態~集合$内に在るならば、 それを集合から除去した上で， ~T を返す。 他の場合は ~F を返す。 ◎ If the element's states set has value, then it will be removed and true will be returned. Otherwise, false will be returned.

%internals.`states$eI.clear()

当の要素の`状態~集合$からすべての値を除去する。 ◎ Removes all values from the element's states set.

for (const %stateName of %internals.`states$eI)

for (const %stateName of %internals.`states$eI.entries())

for (const %stateName of %internals.`states$eI.keys())

for (const %stateName of %internals.`states$eI.values())

当の要素の`状態~集合$を成すすべての値を反復する。 ◎ Iterates over all values in the element's states set.

%internals.`states$eI.forEach(%callback)

当の要素の`状態~集合$を成すすべての値を［ 各~値に対し %callback を一回~callする ］ことにより反復する。 ◎ Iterates over all values in the element's states set by calling callback once for each value.

%internals.`states$eI.size

当の要素の`状態~集合$を成す値の個数を返す。 ◎ Returns the number of values in the element's states set.

各`~custom要素$は `状態~集合@ を有する — それは、 ある `CustomStateSet$I であり，初期~時は空とする。 ◎ Each custom element has a states set, which is a CustomStateSet, initially empty.

[Exposed=Window]
interface `CustomStateSet@I {
  setlike<DOMString>;
};

/* 
`readyState^c を `complete^l に変更する：
◎
Change the readyState from anything to "complete".
 */
this._readyState = "complete";
this._internals.states.delete("loading");
this._internals.states.delete("interactive");
this._internals.states.add("complete");