@xsolla/xui-switch 0.99.0 → 0.100.0

package/README.md

@@ -1,37 +1,232 @@
-# @xsolla/xui-switch
+---
+title: Switch
+subtitle: A toggle switch for on/off states.
+description: A cross-platform React switch component for toggling between on and off states.
+---
 
-Toggle switch component with label, description, and error state support.
+# Switch
+
+A cross-platform React switch component for toggling between on and off states. Provides a visual alternative to checkboxes for boolean settings.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-switch
+# or
 yarn add @xsolla/xui-switch
 ```
 
-## Usage
+## Demo
+
+### Basic Switch
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function BasicSwitch() {
+  const [enabled, setEnabled] = React.useState(false);
+
+  return (
+    <Switch
+      checked={enabled}
+      onValueChange={setEnabled}
+      label="Enable notifications"
+    />
+  );
+}
+```
+
+### Switch with Description
 
 ```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function SwitchWithDescription() {
+  const [darkMode, setDarkMode] = React.useState(false);
+
+  return (
+    <Switch
+      checked={darkMode}
+      onValueChange={setDarkMode}
+      label="Dark Mode"
+      description="Enable dark theme across the application"
+    />
+  );
+}
+```
+
+### Switch Sizes
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function SwitchSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Switch size="sm" label="Small switch" checked />
+      <Switch size="md" label="Medium switch (default)" checked />
+      <Switch size="lg" label="Large switch" checked />
+      <Switch size="xl" label="Extra large switch" checked />
+    </div>
+  );
+}
+```
+
+## Anatomy
+
+Import the component and use it directly:
+
+```jsx
 import { Switch } from '@xsolla/xui-switch';
 
 <Switch
-  label="Enable notifications"
-  checked={enabled}
-  onValueChange={setEnabled}
+  checked={isEnabled}           // Whether switch is on
+  onValueChange={handleToggle}  // Toggle handler
+  label="Setting label"         // Label text
+  description="Help text"       // Description below label
+  errorLabel="Error text"       // Error message
+  state="default"               // Visual state
+  size="md"                      // Size variant
 />
 ```
 
-## Props
+## Examples
+
+### Settings Panel
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function SettingsPanel() {
+  const [settings, setSettings] = React.useState({
+    notifications: true,
+    sounds: false,
+    autoUpdate: true,
+    analytics: false,
+  });
+
+  const toggle = (key: string) => (value: boolean) => {
+    setSettings((prev) => ({ ...prev, [key]: value }));
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 20 }}>
+      <Switch
+        checked={settings.notifications}
+        onValueChange={toggle('notifications')}
+        label="Push Notifications"
+        description="Receive push notifications for important updates"
+      />
+      <Switch
+        checked={settings.sounds}
+        onValueChange={toggle('sounds')}
+        label="Sound Effects"
+        description="Play sounds for actions and alerts"
+      />
+      <Switch
+        checked={settings.autoUpdate}
+        onValueChange={toggle('autoUpdate')}
+        label="Auto Update"
+        description="Automatically download and install updates"
+      />
+      <Switch
+        checked={settings.analytics}
+        onValueChange={toggle('analytics')}
+        label="Usage Analytics"
+        description="Help improve the app by sharing anonymous usage data"
+      />
+    </div>
+  );
+}
+```
+
+### Error State
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function ErrorSwitch() {
+  return (
+    <Switch
+      checked={false}
+      state="error"
+      label="Required Setting"
+      errorLabel="This setting must be enabled to continue"
+    />
+  );
+}
+```
+
+### Disabled Switch
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function DisabledSwitch() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Switch state="disable" label="Disabled off" />
+      <Switch state="disable" checked label="Disabled on" />
+    </div>
+  );
+}
+```
+
+## API Reference
 
 ### Switch
 
+A toggle switch component.
+
+**Switch Props:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `checked` | `boolean` | `false` | Whether the switch is on |
-| `onValueChange` | `(value: boolean) => void` | — | Callback when toggled |
-| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Switch size |
-| `disabled` | `boolean` | `false` | Disables the switch |
-| `state` | `'default' \| 'hover' \| 'disable' \| 'error'` | `'default'` | Visual state |
-| `label` | `string` | — | Label text displayed beside the switch |
-| `description` | `string` | — | Secondary text below the label |
-| `errorLabel` | `string` | — | Error text shown when `state` is `'error'` |
-| `ariaLabel` | `string` | — | Accessible label for screen readers |
+| :--- | :--- | :------ | :---------- |
+| checked | `boolean` | `false` | Whether the switch is on. |
+| size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the switch. |
+| state | `"default" \| "hover" \| "disable" \| "error"` | `"default"` | Visual state. |
+| label | `string` | - | Label text displayed next to switch. |
+| description | `string` | - | Description text below the label. |
+| errorLabel | `string` | - | Error message when state is "error". |
+| onValueChange | `(value: boolean) => void` | - | Callback when toggled. |
+| ariaLabel | `string` | - | Accessible label for screen readers. |
+| ariaLabelledBy | `string` | - | ID of element that labels this switch. |
+
+**Size Configuration:**
+
+| Size | Track Width | Track Height | Knob Size |
+| :--- | :---------- | :----------- | :-------- |
+| sm | 32px | 18px | 14px |
+| md | 40px | 22px | 18px |
+| lg | 48px | 26px | 22px |
+| xl | 56px | 30px | 26px |
+
+## Theming
+
+Switch uses the design system theme for colors:
+
+```typescript
+// Colors accessed via theme
+theme.colors.control.switch.bgOff         // Track background when off
+theme.colors.control.switch.bgOn          // Track background when on
+theme.colors.control.switch.knob          // Knob color
+theme.colors.control.switch.border        // Border color
+theme.colors.content.primary              // Label text
+theme.colors.content.secondary            // Description text
+theme.colors.content.error                // Error text
+```
+
+## Accessibility
+
+- Uses `role="switch"` semantic role
+- `aria-checked` reflects on/off state
+- Keyboard support (Space/Enter to toggle)
+- Focus indicator follows WCAG guidelines
+- Label properly associated with control
+- Disabled state announced to assistive technology

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-switch",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,8 +13,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.99.0",
-    "@xsolla/xui-primitives-core": "0.99.0"
+    "@xsolla/xui-core": "0.100.0",
+    "@xsolla/xui-primitives-core": "0.100.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",