📚 Improve switch component documentation (#7714)

frontend/src/app/main/ui/ds/controls/switch.cljs

@@ -68,11 +68,10 @@
                                 :disabled disabled?})]
 
     [:> :div props
+     [:div {:id id
+            :class (stl/css :switch-track)}
+      [:div {:class (stl/css :switch-thumb)}]]
      (when has-label?
        [:label {:for id
                 :class (stl/css :switch-label)}
-        label])
+        label])]))
-
-     [:div {:id id
-            :class (stl/css :switch-track)}
-      [:div {:class (stl/css :switch-thumb)}]]]))

frontend/src/app/main/ui/ds/controls/switch.mdx

@@ -11,7 +11,7 @@ import * as Switch from "./switch.stories";
 
 # Switch
 
-The `switch*` component is a toggle control that allows users to switch between two mutually exclusive options.
+The `switch*` component is a toggle control. It allows users to switch between two mutually exclusive states (`false` or `true`), while also accepting an initial third state (`nil`).
 
 <Canvas of={Switch.Default} />
 
@@ -19,34 +19,34 @@ The `switch*` component is a toggle control that allows users to switch between
 
 The switch component consists of three main parts:
 
-- **Label** (optional): text that describes what the switch controls
+- **Label** (optional): the text that describes what the switch controls. Clicking on this text also works for toggling.
-- **Track**: the pill-shaped background that indicates the current state
+- **Track**: the pill-shaped background.
-- **Thumb**: the circular knob that moves between positions
+- **Thumb**: the knob that moves between positions.
+
+## Basic usage
+
+```clj
+[:> switch* {:label "Toggle something"
+             :default-checked nil
+             :on-change handle-change
+             :disabled false}]
+```
 
 ## Accesibility
 
-When no visible label is provided, use `aria-label` for accessibility.
+When no visible label is provided, use `:aria-label` for accessibility.
-
-## Variants
-
-### With Label
-
-```clj
-[:> switch* {:label "Toggle dark mode"
-             :default-checked false}]
-```
-
-<Canvas of={Switch.WithLabel} />
 
 ## Usage Guidelines
 
 ### When to Use
 
-- For binary settings that take effect immediately
+- For boolean settings that take effect immediately.
-- In preference panels and configuration screens
+- In preference panels and configuration screens.
+- For ternary states where the third state is only relevant at the beginning (e.g., selection of multiple elements with opposite states).
 
 ### When Not to Use
 
-- For actions that require confirmation (use buttons instead)
+- For actions that require confirmation (use buttons instead).
-- For multiple choice selections (use radio buttons or select)
+- For multiple choice selections (use radio buttons or select).
-- For temporary states that need explicit "Apply" action
+- For temporary states that need explicit "Apply" action.
+- For ternary states that require passing through all three states.

frontend/src/app/main/ui/ds/controls/switch.stories.jsx

@@ -13,10 +13,6 @@ export default {
   title: "Controls/Switch",
   component: Switch,
   argTypes: {
-    defaultChecked: {
-      control: { type: "boolean" },
-      description: "Default checked state for uncontrolled mode",
-    },
     label: {
       control: { type: "text" },
       description: "Label text displayed next to the switch",
@@ -27,33 +23,37 @@ export default {
     }
   },
   args: {
-    defaultChecked: false,
     disabled: false
   },
   parameters: {
-    controls: { exclude: ["id", "class", "aria-label", "on-change"] },
+    controls: { exclude: ["id", "class", "aria-label", "default-checked", "on-change"] },
   },
   render: ({ ...args }) => (
     <Switch {...args} />
   ),
 };
 
-export const Default = {};
+export const Default = {
-
-export const WithLabel = {
   args: {
-    defaultChecked: false,
+    label: "Toggle something",
-    label: "Enable something",
     disabled: false,
   },
   render: ({ ...args }) => (
-    <Switch {...args} aria-label="Enable notification"/>
+    <Switch {...args} />
+  ),
+};
+
+export const WithoutLabel = {
+  args: {
+    disabled: false,
+  },
+  render: ({ ...args }) => (
+    <Switch {...args} />
   ),
 };
 
 export const WithLongLabel = {
   args: {
-    defaultChecked: false,
     label: "This is a very long label that demonstrates how the switch component handles text wrapping and layout when the label content is extensive",
     disabled: false,
   },