docs: improve segmented control documentation

Author: scriptcoded

packages/storybook/src/stories/segmented-control.mdx

@@ -0,0 +1,51 @@
+import {
+  Meta,
+  Controls,
+  Description,
+  Primary,
+  Source,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+
+import * as SegmentedControlStories from './segmented-control.stories';
+
+<Meta of={SegmentedControlStories} />
+
+<Title />
+<Subtitle />
+<Description />
+<Primary />
+<Controls />
+
+## Code Examples
+
+### Controlling state
+
+You must manage the state of the active segment yourself by listening to the
+`scoutChange` event and updating the `value` prop accordingly.
+
+<Source
+  language="tsx"
+  code={`
+    import { useState } from "react";
+    import { ScoutSegmentedControl } from "@scouterna/ui-react";
+
+    const [activeSegment, setActiveSegment] = useState(0);
+
+    return (
+      <ScoutSegmentedControl
+        value={activeSegment}
+        onScoutChange={(e) => setActiveSegment(e.detail.value)}
+      >
+        <button type="button">Alla</button>
+        <button type="button">Bokade</button>
+      </ScoutSegmentedControl>
+    );
+  `}
+/>
+
+## Stories
+
+<Stories title={false} />

packages/ui-webc/src/components/segmented-control/readme.md

@@ -5,9 +5,14 @@
 
 ## Overview
 
-The segmented control component is used to create a segmented interface. It
-manages the state of which segment is active and displays an indicator under
-the active segment. Use button elements to define the individual segments.
+The segmented control component presents a set of options where exactly one
+option is active at a time.
+
+The component displays an indicator under the selected option and emits a
+`scoutChange` event when the user picks a different option, so you can update
+`value`.
+
+Use button elements as the slotted segment options.
 
 ## Properties
 

packages/ui-webc/src/components/segmented-control/segmented-control.tsx

@@ -15,9 +15,14 @@ import {
 export type Size = "small" | "medium";
 
 /**
- * The segmented control component is used to create a segmented interface. It
- * manages the state of which segment is active and displays an indicator under
- * the active segment. Use button elements to define the individual segments.
+ * The segmented control component presents a set of options where exactly one
+ * option is active at a time.
+ *
+ * The component displays an indicator under the selected option and emits a
+ * `scoutChange` event when the user picks a different option, so you can update
+ * `value`.
+ *
+ * Use button elements as the slotted segment options.
  */
 @Component({
   tag: "scout-segmented-control",