From de81d1d3063a23343ac5ef9239e6f5eadc6bb7e6 Mon Sep 17 00:00:00 2001 From: Lea Verou Date: Mon, 15 Jul 2024 11:54:04 -0700 Subject: [PATCH 1/3] First stab at #289 --- index.bs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/index.bs b/index.bs index a55b526..c15daf6 100644 --- a/index.bs +++ b/index.bs @@ -1032,6 +1032,25 @@ The alternative user experience is a flash of unstyled content, which is undesir See also [[#worker-only]]. +

Expose content attributes for writable IDL attributes

+ +When designing a new *writable* IDL attribute to specify element state, +err on the side of exposing a corresponding content attribute. + +Providing declarative ways to manipulate state has several benefits for authors: +- It takes advantage of HTML reactivity, and alleviates the need to apply changes at a specific moment in time. +- It integrates with existing DOM methods, improving learnability, whereas an API specific to the feature needs to be learned separately. +- Behaviors can be expressed reactively in libraries supporting HTML-based syntax and be handled by any library handling HTML generically. +- UI states can be addressed in CSS via simple attribute selectors rather than new pseudo-classes. +- State can be inspected and manipulated via the browser's developer tools with no need for implementing a new UI. + +
+A counterpattern to this guidance can be found in +<{input}>'s {{HTMLInputElement/indeterminate}} IDL property +which was never exposed as a content attribute making it impossible to fully update checkbox state +by modifying HTML. +
+

Keep attributes in sync

New content attributes From c599e4b0a3afa5cd406facf75bd2eccf386efda1 Mon Sep 17 00:00:00 2001 From: Lea Verou Date: Mon, 15 Jul 2024 16:34:17 -0700 Subject: [PATCH 2/3] Update index.bs Co-authored-by: Theresa O'Connor --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index c15daf6..6b87536 100644 --- a/index.bs +++ b/index.bs @@ -1035,7 +1035,7 @@ See also [[#worker-only]].

Expose content attributes for writable IDL attributes

When designing a new *writable* IDL attribute to specify element state, -err on the side of exposing a corresponding content attribute. +expose a corresponding content attribute unless you have a compelling reason not to. Providing declarative ways to manipulate state has several benefits for authors: - It takes advantage of HTML reactivity, and alleviates the need to apply changes at a specific moment in time. From 039c7ef19652376f08e416e539545684527b50ef Mon Sep 17 00:00:00 2001 From: Lea Verou Date: Wed, 17 Jul 2024 11:10:52 -0700 Subject: [PATCH 3/3] Update index.bs --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 6b87536..e8f8cd1 100644 --- a/index.bs +++ b/index.bs @@ -1038,7 +1038,7 @@ When designing a new *writable* IDL attribute to specify element state, expose a corresponding content attribute unless you have a compelling reason not to. Providing declarative ways to manipulate state has several benefits for authors: -- It takes advantage of HTML reactivity, and alleviates the need to apply changes at a specific moment in time. +- It takes advantage of HTML’s [reactivity](https://en.wikipedia.org/wiki/Reactive_programming), and alleviates the need to apply changes at a specific moment in time. - It integrates with existing DOM methods, improving learnability, whereas an API specific to the feature needs to be learned separately. - Behaviors can be expressed reactively in libraries supporting HTML-based syntax and be handled by any library handling HTML generically. - UI states can be addressed in CSS via simple attribute selectors rather than new pseudo-classes.