@xsolla/xui-switch 0.148.0 → 0.148.1

package/README.md

@@ -0,0 +1,257 @@
+# 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
+```
+
+## 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"
+    />
+  );
+}
+```
+
+### Label Position
+
+```tsx
+import * as React from 'react';
+import { Switch } from '@xsolla/xui-switch';
+
+export default function SwitchLabelPosition() {
+  const [left, setLeft] = React.useState(false);
+  const [right, setRight] = React.useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Switch
+        label="Label on the right (default)"
+        labelPosition="right"
+        checked={right}
+        onValueChange={setRight}
+      />
+      <Switch
+        label="Label on the left"
+        labelPosition="left"
+        checked={left}
+        onValueChange={setLeft}
+      />
+    </div>
+  );
+}
+```
+
+### 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
+  checked={isEnabled}           // Whether switch is on
+  onValueChange={handleToggle}  // Toggle handler
+  label="Setting label"         // Label text
+  labelPosition="right"         // "left" | "right" (default: "right")
+  description="Help text"       // Description below label
+  errorLabel="Error text"       // Error message
+  state="default"               // Visual state
+  size="md"                      // Size variant
+/>
+```
+
+## 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. |
+| 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. |
+| labelPosition | `"left" \| "right"` | `"right"` | Position of the label relative to the 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.148.0",
+  "version": "0.148.1",
   "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.148.0",
-    "@xsolla/xui-primitives-core": "0.148.0"
+    "@xsolla/xui-core": "0.148.1",
+    "@xsolla/xui-primitives-core": "0.148.1"
   },
   "peerDependencies": {
     "react": ">=16.8.0",