HTMLFormElement.addClass: Improve removal of duplicates.

CHANGES.rst

@@ -11,6 +11,10 @@ Changelog
 
 - Drop deprecated support for ``python setup.py test``.
 
+- HTMLFormElement.addClass: Improve removal of duplicates. It's now possible to
+  add multiple classes as whitespace separated string and still detect class
+  duplicates.
+
 
 4.3 (2022-03-24)
 ----------------

src/z3c/form/browser/widget.py

@@ -142,21 +142,20 @@ class HTMLFormElement(WidgetLayoutSupport):
     # layout support
     css = FieldProperty(interfaces.IHTMLFormElement['css'])
 
-    def addClass(self, klass):
-        """See interfaces.IHTMLFormElement"""
+    def addClass(self, klass: str):
+        """Add a class to the HTML element.
+
+        See interfaces.IHTMLFormElement.
+        """
         if not self.klass:
             self.klass = str(klass)
         else:
             # make sure items are not repeated
-            parts = self.klass.split() + [str(klass)]
-            seen = {}
-            unique = []
-            for item in parts:
-                if item in seen:
-                    continue
-                seen[item] = 1
-                unique.append(item)
-            self.klass = ' '.join(unique)
+            parts = self.klass.split() + klass.split()
+            # Remove duplicates and keep order.
+            # Dictionaries are ordered in Python 3.7+
+            parts = list(dict.fromkeys(parts))
+            self.klass = " ".join(parts)
 
     def update(self):
         """See z3c.form.interfaces.IWidget"""

src/z3c/form/browser/widget.rst

@@ -0,0 +1,52 @@
+Widget base classes
+===================
+
+HTMLFormElement
+---------------
+The widget base class.
+::
+
+  >>> from z3c.form.browser.widget import HTMLFormElement
+  >>> form = HTMLFormElement()
+
+
+addClass
+........
+
+Widgets based on :code:`HTMLFormElement` also have the :code:`addClass` method which can be used to add CSS classes to the widget.
+
+The :code:`klass` attribute is used because :code:`class` is a reserved keyword in Python.
+It's empty per default::
+
+  >>> form = HTMLFormElement()
+  >>> form.klass
+
+
+After adding a class it shows up in :code:`klass`::
+
+  >>> form.addClass("my-css-class")
+  >>> form.klass
+  'my-css-class'
+
+
+:code:`addClass` prevents adding the same class twice::
+
+  >>> form.addClass("my-css-class")
+  >>> form.klass
+  'my-css-class'
+
+  >>> form.addClass("another-class")
+  >>> form.klass
+  'my-css-class another-class'
+
+  >>> form.addClass("another-class third-class")
+  >>> form.klass
+  'my-css-class another-class third-class'
+
+
+The duplicate removal also keeps the original order of CSS classes::
+
+  >>> form.addClass("third-class another-class")
+  >>> form.klass
+  'my-css-class another-class third-class'
+

src/z3c/form/tests/test_doc.py

@@ -144,6 +144,11 @@ def test_suite():
             '../hint.rst',
             setUp=setUp, tearDown=testing.tearDown,
             optionflags=flags, checker=testing.outputChecker,
+        ),
+        doctest.DocFileSuite(
+            '../browser/widget.rst',
+            setUp=setUp, tearDown=testing.tearDown,
+            optionflags=flags, checker=testing.outputChecker,
         ))
         for setUp in setups)